tako 文档 GitHub

术语先大白话后学名:第一次出现就要能落脚

模块:文档纪律 · 架构篇可读性(tmp/doc-clarify-plain,落点 doc/19-v6/19v6-05)|状态:已落地(2026-10-10)|证据:tmp/doc-clarify-plain/{planning,todos}.md、doc/19-v6/19v6-05-tool-loop.md、doc/19-v6/19v6-90-演进记录.md

1. 场景与病灶

一篇架构文档要讲「模型怎么按规格解析」。作者写下这句:

Registry.Get(ctx, ref)(进程内注册表 =「多实例 + 晚解析」的机械件)

在这句话里,读者至少撞上四个没落脚的词:Registry 是什么形状、ref 从哪来、**「机械件」指什么、「晚解析」**又是什么。后文还有「继承档 / ref 档」这种自造缩写。

2026-10-10,用户连续追问三轮——「Registry 是什么」「ref 是什么」「其他实例怎么办」——三轮之后仍然没看懂。这不是读者的问题,是文档没有给出可落脚的定义。 三个月后重读同一段,问题一模一样:文档没变,只是当时那个人不在了。

具体的失败有两条:

2. 候选与代价

候选 做法 好处 代价
A 保持行话 行业词 + 自造缩写照写 作者省事;熟手读得快 新人/三个月后的自己读不懂;追问三轮仍在原地;错误心智模型会传染进设计讨论
B 全部换成大白话,不用学名 把 Registry 叫「缓存表」、ref 叫「模型名」 第一遍最好懂 代码里叫 ModelRegistry / ref,文档与代码对不上,grep 不到;后续讨论失去精确指称,同一概念会出现多个说法
C 第一次出现「大白话 + 括号学名」,后文用学名(选定) 「进程内的懒加载缓存表(学名 ModelRegistry)」 第一遍能落脚;后文仍精确、可 grep 首次出现处要多写半句;作者要判断「哪个词对读者是新的」
D 只在文末加术语表 正文照旧,附录统一解释 改动最小 读者在正文中途不会翻附录;定义与使用相隔几十行,等于没有

选 C。关键区分不是「术语好还是不好」,而是第一次出现时读者心里有没有东西:

学名不能删,因为它是代码与讨论的指称:删了就没法 grep、没法在评审里精确说「这里查的是 ModelRegistry 不是缓存」;但学名必须跟在真身后面,不能反过来让读者先背名字再猜意思。

3. 改法:五处具体动作

动作 做法 没它会怎样
① 术语表钉在 §0 新增 ref、ChatModel 实例、ModelRegistry 三条,每条五列:形状(正向定义)/ 住处 / 消费者 / 例子 读者到 §4 才发现自己不知道 ref 是什么,只能往回翻或放弃
② 三档表改名 「继承档 / ref 档」→「写法一:根本不写 / 写法二:写 inherit / 写法三:指定 ref」;表头「档」→「写法」 自造缩写让读者先学一套私有词汇,再学机制;两层负担
③ 链路图换成具体值 主 worker 用 deepseek/x、子代理 A 写 inherit、子代理 B 写 anthropic/claude-sonnet-4;至少走一条继承分支、一条指定分支 抽象变量名(A/B/C)的箭头图看起来完整,实际无法验证读者是否理解分流
④ 补「为什么在进程内」 用表格列出判断依据:实例无状态、按 ref 懒建、多副本各自建一份不冲突、缓存丢了只是重建 读者按「跨副本注册中心」的模型理解,会设计出不必要的共享层
⑤ 补最小伪代码 ModelRegistry.Get 约 30 行:先查 map → 未命中走 ResolveModelWithRef → 双检后写入 「懒加载」四个字仍然要读者自己翻译成代码;伪代码把「懒」落到操作上

原则一句:每个术语第一次出现,必须三选一——贴真身(真实格式、示例值、map[ref]ChatModel)、给操作定义(谁、从哪、拿什么、做什么、得到什么)、或指回前文已给出的同等定义。三样都给不出,就换成人话或删掉。

4. 同族小裁定

小问题 裁定 代价 / 备注
术语删不删 不删,保留学名供 grep 与讨论 但必须跟在真身后面,不能裸用
定义放哪 第一次出现处 / §0,不放文末附录 读者不会中途翻附录
自造缩写(「档」「机械件」「晚解析」) 改成人话 它们不是代码里的名字,没有精确性收益
链路图怎么写 用具体值走完整分流,不用抽象变量 抽象图无法暴露「读者是否真懂」
「为什么这样设计」要不要写 要,且列判断依据 只写「因为它是缓存」等于把问题推回去
改哪些文档 只改 19v6-05 §0/§4 与 19v6-90 十修段 契约真源 19v6-01、存储真源 19v6-03 不动
历史记录能不能改措辞 可以换掉黑话,不改结论 「只追加不改结论」的规则不禁止把句子写得更可读
代码要不要改 零改动 这是纯文档拍;术语指的是已存在的代码符号
文档拍的验收 三个自问:术语首次出现前 3 段内有定义?图是否用具体值走两条分支?「为什么」是否有依据表? 没有 curl 可打;判据是可读性,不是字节
同类规则放哪 升格进 AGENTS.md「解释与汇报的及格线」 名词准入、故事先行、黑话翻译令——与本拍同一条纪律

5. 证据

台账:tmp/doc-clarify-plain/planning.md(为什么要改、改哪些、措辞原则、验收三问、无脚手架)、todos.md。本地台账,验收后清理。

落点:

位置 是什么
doc/19-v6/19v6-05-tool-loop.md §0 术语表补 ref / ChatModel 实例 / ModelRegistry 三条,含形状、住处、消费者、例子
doc/19-v6/19v6-05-tool-loop.md §4 三档穷举表改为「写法一/二/三」;链路图用具体 ref 走继承与指定两条分支;补 ModelRegistry.Get 最小伪代码
doc/19-v6/19v6-05-tool-loop.md:28 ref 的正向定义与示例值
doc/19-v6/19v6-05-tool-loop.md:30 ModelRegistry = 进程内懒加载缓存表 map[ref]ChatModel实例
doc/19-v6/19v6-90-演进记录.md 十修段 同一批黑话替换为直白说法,结论不变
AGENTS.md「解释与汇报的及格线」 名词准入 / 故事先行 / 黑话翻译令(同一条纪律的升格)

复核命令:

grep -n "懒加载\|ref\b\|ModelRegistry" doc/19-v6/19v6-05-tool-loop.md | head -20
grep -n "继承档\|ref 档\|机械件\|晚解析" doc/19-v6/19v6-05-tool-loop.md   # 期望:无命中
sed -n '/## 0\./,/## 1\./p' doc/19-v6/19v6-05-tool-loop.md               # 术语表五列齐全

验收(文档拍):逐个 section 读改后内容,三个自问——① 第一次出现的术语是否在之前 3 段内有正向定义;② 链路图是否用具体值走了至少一条「继承」和一条「指定 ref」分支;③ 「为什么 Registry 放进程内」是否有判断依据列表而非一句「因为是缓存」。

6. 现状