` → 脚本。 - 脚本顺序（**敏感**）： `theme.js` → `viz-core.js` → `echarts-theme.js` → `playground.js` → `katex-config.js` → `nav.js` → `assets/viz.js`（本单元）。 - 内容区用 `.lesson-layout`（左 TOC `[data-toc]` + 主 `[data-toc-root]`），章节用 `

`。 - 全局相对路径：从 `models/NN-slug/index.html` 引全局资源用 `../../assets/...`。 > 脚手架 `new_model.py` 生成的 `index.html` 已是合规骨架，**勿破坏引用顺序**。 --- ## 5. assets/viz.js 约定 ```js let chart, pg; function redraw(state) { /* 依据 state 重绘 chart / canvas */ } function init() { chart = PA_ECHARTS.init(document.getElementById('chart')); pg = PAPlayground.create({ controls: { /* 控件→state 映射 */ }, onChange: redraw }); PAKatex.render(); } if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', init); else init(); ``` - 全局可用：`PAViz`（CanvasAnim/linspace/clamp/palette…）、`PA_ECHARTS`（init/PALETTE）、`PAPlayground`、`PAKatex`、`PATheme`、`PANav`。 - 颜色**必须**取自 `PAViz.PALETTE` / `PAViz.palette(i)` 或 CSS 变量，不得硬编码他色。 - Canvas 动画继承 `PAViz.CanvasAnim`，重写 `draw(t, dt)`，用 `this.W/this.H/this.ctx`。 - 主题切换时：ECharts 由 `echarts-theme.js` 自动重绘；自写 Canvas 需订阅 `PATheme.onChange(theme=>redraw())`。 - **⚠ 初始化时序（常见坑，务必遵守）**： - `PAPlayground.create({onChange})` 在返回前会**首次触发** onChange，此时 `pg` 尚未赋值。**onChange 回调及其调用的函数里不要直接用 `pg.state`**——改用回调传入的 `state` 参数（或 `s = s || (pg && pg.state)` 兜底）。 - `requestAnimationFrame` 动画循环访问数据前，先判断数据已初始化（如 `if (!myData) return;`），避免首帧在 init 完成前读到 null 而抛错、中断整个 init。 --- ## 6. Python 双实现规范 ### `code/from_scratch.py`（从零，教学白盒） - **仅依赖 numpy**（不得 import torch/sklearn），确保任何环境可跑。 - 固定结构：构造示例数据 → 初始化参数 → 训练循环（前向/损失/梯度/更新）→ 打印对照真值。 - 关键行**逐行中文注释**（为什么这样算、对应哪个公式）。 - 训练循环打印进度（每 N 轮一次），结束时打印「真值 vs 拟合值」对照。 - 末尾 `if __name__ == "__main__": main()`，可 `python code/from_scratch.py` 独立运行。 ### `code/framework.py`（框架对照） - 监督/无监督模型用 **scikit-learn**；深度模型用 **PyTorch**。 - 简洁（10–40 行），凸显「工业实现 vs 从零」的差异。 - 输出结果应与 `from_scratch.py` **数值可比**（同数据、同真值），便于读者对照。 - 末尾 `if __name__ == "__main__": main()`。 - 顶部注释说明依赖与运行命令。 > Python 3.14 下若 torch 无 wheel，`framework.py` 顶部加保护：try import 失败则打印安装提示并退出，**不得让 import 报错中断**。 --- ## 7. 可视化技术选择（meta.viz） | 现象 | 首选技术 | |---|---| | 损失曲线、数据分布、决策边界（静态/低频更新） | **ECharts** | | 算法过程（梯度流、卷积滑动、聚类迭代、扩散去噪） | **手写 Canvas**（`PAViz.CanvasAnim`） | | 结构图（神经元、网络层、残差连接、树结构） | **手写 SVG**（静态或简单动效） | | 参数空间、卷积体素、GNN 图结构 | **Three.js**（`hasThree:true`） | | 数学公式 | **KaTeX**（`data-tex`） | 每单元 `viz` 数组如实声明用到的技术；门户据此决定卡片缩略与预加载策略。 --- ## 8. 写作风格：去「AI 味」（强制） AI 生成的技术文常被一眼识破：机翻腔、形容词堆砌、面面俱到却无重点、公式与正文脱节。规避要点： - **第一人称「我们」**，像在带读者走一遍，而非说明书。 - **给具体数字**，不写「效果很好」——写「100 轮后 MSE 从 12.3 降到 0.8」。 - **每个公式配一句白话**：它衡量什么、为什么长这样。 - **讲取舍**：这个模型相对上一个，多了什么、付出了什么。 - **承认局限**：什么时候它会崩、为什么。 - **忌**：空洞排比、过度小标题、罗列一切变体、不必要的「首先/其次/最后」。 - 中文标点、半角与全角混用正确（代码/变量半角，中文全角）。 --- ## 9. 质量检查清单（提交前） - [ ] `meta.json` 字段齐全，`slug` 与目录名一致，`status` 已设 - [ ] README 11 节齐全，公式渲染正常，无 TODO 残留 - [ ] `index.html` 引用顺序正确，暗/亮主题都正常 - [ ] `viz.js` 颜色取自调色板，控件可交互且实时重绘 - [ ] `from_scratch.py` 仅依赖 numpy，能独立运行并打印真值对照 - [ ] `framework.py` 能运行（或优雅降级），结果与从零可比 - [ ] `python scripts/verify_unit.py ` 零错误 - [ ] 浏览器打开页面，动画/公式/图表/滑块均正常 - [ ] 文档读起来像人写的（过 §8 自检）