细讲项目
把拆解成一组文档，我要学它的设计。
关键机制要不要实际跑一遍：
写完要不要收纳进本 wiki：
我原来以为它是：
先读，别急着写
- 读源码，README 和设计文档只当线索；记下读的是哪个 commit，写进维护记录一次就够，正文引用不逐处标版本
- 定领域：这个项目属于什么领域，领域里的正式叫法和常见别名，中英都要
- 定 baseline：这个领域最简单、读者多半用过的做法。我写了原来的理解，它通常就是 baseline——不用纠正，拿来当起点
- 列功能、反推问题：每个功能修的是 baseline 的哪个毛病，毛病落到一个具体案例上，源码注释、设计文档、issue 里的实测记录优先。反推不出问题的功能多半是兜底或可选开关，并进别的线或不写
- 按问题把功能聚成几条功能线
- 照盘问我一轮轮问我：领域和 baseline 对不对、功能线怎么分、哪几条深挖。事实你自己查，取舍等我答，确认后再写
写成什么样
写进本 wiki：你当前的工作区就是本 wiki 的仓库，动笔前先读仓库里的 docs/skills/wiki-guide/index.md 和 docs/skills/collect/index.md（收纳的共用规矩），照写作流程写进仓库，下面没写到的都按它们来。写在 docs/projects/<名>/；这个目录里已经有一页粗讲的，就在原地写，入口那页按下面重写，地址不变。
一个项目一个目录：入口一篇，每条功能线一篇。骨架照论文，论文用来证明新颖的部分不要——文献综述、贡献声明都不写。
入口篇，正文 1500–3000 字：
- 标题：项目名加一句话，说它在 baseline 上改了什么
- 摘要：一段，300 字以内：领域、baseline、几条功能线、设计重心；重心用一个具体机制说，不用形容词撑
- 关键词：领域术语的中英叫法，只放词
- 术语：一张表，每个词标出处——项目自造、领域里通用、还是你起的——再写意思；放在引言前，引言一上来就要用到这些词
- 引言：先说领域是什么，baseline 是什么、在这个领域会出哪些毛病，有事实上的前辈项目一两句对照；再按功能线分小节，一条线一节：问题写成一个具体案例，下面列这条线引入的功能，链到细讲篇
- 局限：只写设计层面的取舍，项目自己认下的代价优先
- 结论：可以搬走的设计：几条，每条一个机制，说清换到别的项目里怎么用
实验怎么设计、脚本、用量不进正文，写进维护记录——读者要学的是项目，不是实验。
每条功能线一篇，正文 1000–2000 字，代码和输出不算：
- 开头一句：baseline 在这条线上怎么出问题
- 每节一个问题：问题（一个案例）→ 功能 → 模版（源码片段，标
文件:起止行）→ 效果 → 一两句解读 - 末尾「谁管什么」：哪些是程序做死的，哪些留给模型，哪些留给用户
- 原始记录放文末附录
- 模版按行引源码原文，不手抄；先看许可，只存档被引到的文件，用不上的不拷。项目的设计文档、README 不整篇贴：正文摘关键句，链接钉到读的那个 commit
实跑
- 不用把整个项目部署起来：拆出要演示的关键片段单独跑就够了。整个模块一导入就要拉起一串依赖的，把用到的几个函数原样抠出来跑
- 效果用项目自己的代码跑出来：import 它的函数，喂真实输入，贴原始输出。不自己重写它的逻辑——重写的那份迟早和真实行为对不上
- 模型调用照项目的配置来：同样的参数、同样的终止条件。跑出来的东西和源码对不上，先查自己的脚本是不是漏了一步
- 真实输入碰不到某条规则，就构造一份输入过同一个函数，正文写明是构造的
- 跑项目代码的进程里不放任何密钥，模型调用放在另一个进程
- 跑的脚本和原始输出一起存档。读的版本、实验设置、脚本都写进维护记录，正文只放效果
- 跑不起来的部分，只贴模版，写明没跑
不实跑：每节只贴模版，效果块省掉；实验设置写明只读了源码。
写的时候
- 只写现状：不写 commit 时间线、作者的心路历程、加了又拆的过程
- 小 bug 不写，说不定哪天就修了；只写主线
- 项目自造的词换成通用说法，引原话时保留一次并注明
- 结论落到文件路径和行号上，以代码为准
- 技术词保留原形，其余用大白话
配图
只有我明确要求配图才进行配图。画法照配图，正文写完、叫法定下来再画。画哪几张：
- 每条功能线一张开屏图，放在细讲篇的
# 标题之前；入口篇里讲这条线的一节用同一张 - 细讲篇里某一节讲的是一个有名字的结构——由哪几部分组成、分几层、走几步、绕一圈、分几条岔路——再给这一节画一张，放在这一节的标题下
- 一句话说得清的不画；界面长什么样用截图，不画