# 贡献指南（Contributing）

欢迎为 PixelAlgo 贡献模型单元、改进可视化或修订文档！

## 快速贡献一个新模型

```bash
# 1. 生成骨架（NN 自动递增）
python scripts/new_model.py <英文-slug> <category> --title "中文标题"
# 例：python scripts/new_model.py knn supervised-classic --title "K近邻"

# 2. 填充内容（务必先读规范）
#    docs/conventions.md  ——  单元结构 / meta schema / 写作风格
#    models/01-linear-regression/  ——  黄金范例，照此质量

# 3. 本地校验
python scripts/verify_unit.py <slug>        # 单元完整性 + Python 语法
python scripts/verify_all.py                # 全量 + 重新生成 manifest

# 4. 本地预览
python scripts/serve.py                     # 打开 http://127.0.0.1:8000/
```

## 质量底线（PR 必须满足）

- `verify_unit.py` 零错误
- `from_scratch.py` **仅依赖 numpy**，能独立运行并打印真值对照
- `index.html` 在暗/亮主题下均正常，控件可实时交互
- 颜色取自全局调色板（`PAViz.PALETTE` / CSS 变量），不得硬编码他色
- 文档读起来像人写的（过 [`docs/conventions.md` §8](docs/conventions.md) 自检）

## 可视化技术约定

- 损失/分布/边界 → ECharts（`PA_ECHARTS.init`）
- 算法过程 → 手写 Canvas（继承 `PAViz.CanvasAnim`）
- 结构图 → 手写 SVG
- 3D 参数空间 → Three.js（`meta.hasThree = true`）
- 公式 → KaTeX（`data-tex` / `data-display`）

## 提交规范

- 一个模型单元 = 一个 PR，便于审阅。
- commit message：`add(model): 线性回归` / `fix(viz): 修正 loss 碗轨迹` / `docs: 补充 conventions`。
- PR 描述附：本地 `verify_unit` 输出截图、页面动图（可选）。

## 行为准则

保持友善、教学优先、证据驱动。数学断言给推导或代码验证，性能断言给数字。

## 许可

贡献内容按 [MIT](LICENSE) 发布。