---
name: 细讲项目
description: "想拆解学习一个仓库或项目的设计时用：照论文的骨架写成一组文档，先定领域和 baseline，再从 baseline 的具体毛病出发按功能线写「问题 → 功能」，每步贴源码模版和用项目自己代码跑出的效果，结论写能搬走的设计"
---

# 细讲项目

把<input placeholder="仓库地址或本地路径，比如 https://github.com/xxx">拆解成一组文档，我要学它的设计。

关键机制要不要实际跑一遍：<select name="实跑"><option>是</option><option>否</option></select>

<div class="zx-no-copy" markdown>

写完要不要收纳进本 wiki：<select name="收纳"><option>是</option><option>否</option></select>

</div>

<div data-when="理解" markdown>

我原来以为它是：<input name="理解" placeholder="可选，比如：一个带上了一段 system prompt 的 AI 对话网页而已">

</div>

## 先读，别急着写

1. 读源码，README 和设计文档只当线索；记下读的是哪个 commit，写进维护记录一次就够，正文引用不逐处标版本
2. 定领域：这个项目属于什么领域，领域里的正式叫法和常见别名，中英都要
3. 定 baseline：这个领域最简单、读者多半用过的做法。我写了原来的理解，它通常就是 baseline——不用纠正，拿来当起点
4. 列功能、反推问题：每个功能修的是 baseline 的哪个毛病，毛病落到一个具体案例上，源码注释、设计文档、issue 里的实测记录优先。反推不出问题的功能多半是兜底或可选开关，并进别的线或不写
5. 按问题把功能聚成几条功能线
6. 照[盘问我](../grilling.md)一轮轮问我：领域和 baseline 对不对、功能线怎么分、哪几条深挖。事实你自己查，取舍等我答，确认后再写

## 写成什么样

<div data-when="收纳=是" markdown>

写进本 wiki：你当前的工作区就是本 wiki 的仓库，动笔前先读仓库里的 `docs/skills/wiki-guide/index.md` 和 `docs/skills/collect/index.md`（收纳的共用规矩），照写作流程写进仓库，下面没写到的都按它们来。写在 `docs/projects/<名>/`；这个目录里已经有一页粗讲的，就在原地写，入口那页按下面重写，地址不变。

</div>

一个项目一个目录：入口一篇，每条功能线一篇。骨架照论文，论文用来证明新颖的部分不要——文献综述、贡献声明都不写。

入口篇，正文 1500–3000 字：

- **标题**：项目名加一句话，说它在 baseline 上改了什么
- **摘要**：一段，300 字以内：领域、baseline、几条功能线、设计重心；重心用一个具体机制说，不用形容词撑
- **关键词**：领域术语的中英叫法，只放词
- **术语**：一张表，每个词标出处——项目自造、领域里通用、还是你起的——再写意思；放在引言前，引言一上来就要用到这些词
- **引言**：先说领域是什么，baseline 是什么、在这个领域会出哪些毛病，有事实上的前辈项目一两句对照；再按功能线分小节，一条线一节：问题写成一个具体案例，下面列这条线引入的功能，链到细讲篇
- **局限**：只写设计层面的取舍，项目自己认下的代价优先
- **结论：可以搬走的设计**：几条，每条一个机制，说清换到别的项目里怎么用

实验怎么设计、脚本、用量不进正文，写进维护记录——读者要学的是项目，不是实验。

每条功能线一篇，正文 1000–2000 字，代码和输出不算：

- 开头一句：baseline 在这条线上怎么出问题
- 每节一个问题：**问题**（一个案例）→ **功能** → **模版**（源码片段，标 `文件:起止行`）→ **效果** → 一两句解读
- 末尾「谁管什么」：哪些是程序做死的，哪些留给模型，哪些留给用户
- 原始记录放文末附录
- 模版按行引源码原文，不手抄；先看许可，只存档被引到的文件，用不上的不拷。项目的设计文档、README 不整篇贴：正文摘关键句，链接钉到读的那个 commit

<div data-when="实跑=是" markdown>

## 实跑

- 不用把整个项目部署起来：拆出要演示的关键片段单独跑就够了。整个模块一导入就要拉起一串依赖的，把用到的几个函数原样抠出来跑
- 效果用项目自己的代码跑出来：import 它的函数，喂真实输入，贴原始输出。不自己重写它的逻辑——重写的那份迟早和真实行为对不上
- 模型调用照项目的配置来：同样的参数、同样的终止条件。跑出来的东西和源码对不上，先查自己的脚本是不是漏了一步
- 真实输入碰不到某条规则，就构造一份输入过同一个函数，正文写明是构造的
- 跑项目代码的进程里不放任何密钥，模型调用放在另一个进程
- 跑的脚本和原始输出一起存档。读的版本、实验设置、脚本都写进维护记录，正文只放效果
- 跑不起来的部分，只贴模版，写明没跑

</div>

<div data-when="实跑=否" markdown>

不实跑：每节只贴模版，效果块省掉；实验设置写明只读了源码。

</div>

## 写的时候

- 只写现状：不写 commit 时间线、作者的心路历程、加了又拆的过程
- 小 bug 不写，说不定哪天就修了；只写主线
- 项目自造的词换成通用说法，引原话时保留一次并注明
- 结论落到文件路径和行号上，以代码为准
- 技术词保留原形，其余用大白话

## 配图

只有我明确要求配图才进行配图。画法照[配图](../wiki-guide/reference/infographic.md)，正文写完、叫法定下来再画。画哪几张：

- 每条功能线一张开屏图，放在细讲篇的 `# 标题` 之前；入口篇里讲这条线的一节用同一张
- 细讲篇里某一节讲的是一个有名字的结构——由哪几部分组成、分几层、走几步、绕一圈、分几条岔路——再给这一节画一张，放在这一节的标题下
- 一句话说得清的不画；界面长什么样用截图，不画