---
name: 写书
description: "想把一个项目或一个领域写成一本书时用：先选角度——从零复刻一个迷你版、对比同领域几个项目、或做实验量出功能管多少用——再定侧重；拿粗讲、细讲的产出当底稿，章节按读者读完能干什么排，写完通读挑错"
---

# 写书

把<input placeholder="仓库地址或本地路径；领域对比填同一领域的几个项目">写成一本书。

角度：<select name="角度"><option>从零复刻</option><option>领域对比</option><option>做实验</option></select>

<div data-when="侧重" markdown>

侧重：<input name="侧重" placeholder="可选，比如：前端交互 / 拼 prompt 和调模型 / 数据存储">

</div>

<div data-when="底稿" markdown>

底稿：<input name="底稿" placeholder="可选：粗讲或细讲的成品地址，比如 docs/projects/sillytavern/">

</div>

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

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

</div>

## 先备料，别急着写

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

写进本 wiki：你当前的工作区就是本 wiki 的仓库，动笔前先读仓库里的 `docs/skills/wiki-guide/index.md` 和 `docs/skills/collect/index.md`（收纳的共用规矩），照写作流程写进仓库，和本页冲突的按本页。`docs/projects/` 里已经拆过这个项目的，那就是底稿。板块按角度定：从零复刻、做实验讲的是一个具体的东西，进项目；领域对比讲一个领域问题的几种解法，进文章；具体目录盘问时一并问我。

</div>

1. 书只写官方文档没有的部分：先读官方文档，记下它已经讲清的用法，书里用到就链过去，不重写
2. 有底稿就从底稿起步：baseline、功能线、术语表、源码存档直接用，断言沿用它引的 `文件:行号`，底稿没覆盖的再读源码。没有底稿，先照[细讲项目](dissect.md)的「先读，别急着写」读源码、定领域和 baseline、聚功能线，只拿来备料，不写成文档
3. 定侧重：我写了就用我的；没写，从底稿深挖的那几条线里挑两三个候选
4. 拟目录：每章一行，写读者读完这章能做到的一件事
5. 照[盘问我](../grilling.md)一轮轮问我：侧重、目录、每章的边界、哪几章深写。事实你自己查，取舍等我答，确认后再写

## 章节怎么排

<div data-when="角度=从零复刻" markdown>

读者读完能自己造出一个迷你版。

- 第 0 章是 baseline：这个领域最简单的做法，几十行能跑
- 之后每章加一个功能：先用一个案例让上一章的版本出问题，再加功能修好；贴本章改了哪些代码、跑出来的效果，再对照原项目的同一处，引源码 `文件:起止行`，说清迷你版省了什么
- 章节顺序照底稿里侧重那几条线的「问题 → 功能」排；上一章的代码是下一章的起点，每章结束都能跑
- 迷你版的代码自己写，每章真跑通；讲原项目怎么做时引它的源码，不拿迷你版代替
- 最后一章：迷你版和原项目还差什么，省掉的功能列一张表，每个写一句这本书为什么不需要它

</div>

<div data-when="角度=领域对比" markdown>

读者读完能看清这个领域的设计空间：同一个问题有几种解法，各取舍了什么。

- 至少两个项目，最好都细讲过；只给了一个，先问我还拿哪几个比
- 每章一个领域问题，章名就是这个问题：先写成一个具体案例，再写每个项目怎么解、各引源码 `文件:起止行`，末尾一张对比表——机制、代价、适合什么场景
- 同一个东西各项目叫法不同，全书统一用一个通用说法，第一次出现时列出各项目的原叫法
- 只有一个项目做了的功能不单独成章，并进最相关的那章顺带一句
- 最后一章：这个领域还没人解好的问题

</div>

<div data-when="角度=做实验" markdown>

读者读完能知道哪些功能真管用、管用多少。

- 每章一个功能或一个设计决策：关掉它（消融），或换成另一种常见做法（反事实），量效果变了多少
- 先定指标再跑：指标能自动算，或者有写死的评分标准；每章写清样本、对照、重复几次，报均值和波动，不只报跑一次的结果
- 用项目自己的代码跑：开关和替换做在它的配置或最小改动上，不重写它的逻辑；跑项目代码的进程里不放任何密钥
- 大批量调模型的，先估花费报给我
- 实验设计就是正文，写进每章；脚本和原始输出放附录
- 最后一章：一张总表，所有功能按效果大小排

</div>

## 写的时候

- 每章开头一句：读完这章能做到什么
- 术语表放全书最前；后一章只用前面讲过的词和代码
- 结论落到文件路径和行号上，以代码为准
- 只写现状：不写 commit 时间线、作者的心路历程；小 bug 不写
- 技术词保留原形，其余用大白话

## 写完通读挑错

全书写完，派一个子代理只读全书挑错，没有子代理就开一个新对话；挑出的改完，改过的章再审一遍：

- 术语前后不一致，后面的章用了前面没讲过的词或代码
- 章与章重复、互相打架
- 断言和引的源码对不上
- 代码跑不通，跑出来的和贴出来的对不上