二途序

纯净原则：让文档和提示词只说当前事实的 16 条规则

文档为什么会越来越脏

在调优一个多 agent PPT 生成流水线时，我反复遇到同一种问题：文档和提示词越写越长，但能用的信息越来越少。

读者打开一份文档，想知道的是 "现在该怎么用"。但正文里夹着 "自 v2.8 起新增"" 之前是 X，现改为 Y""本次改动……"—— 这些是给作者看的，不是给读者看的。读者不需要知道历史，只需要当前事实。

本质问题是：写文档的人把变更日志当成了文档本身。版本演进、变更指针、特例补丁，全堆进正文。结果是正文越来越臃肿，真正的事实被噪声淹没。

我把这种 "文档不纯净" 的现象拆成五大类、16 条可审计的规则，叫它 "纯净原则"。

纯净原则的 16 条审计规则

核心心智一句话：读者只需当前事实，版本演进归 git log / CHANGELOG。

mindmap
  root((纯净原则))
    A[溯源残留]
    B[装饰与冗余]
    C[死内容]
    D[doc/impl裂隙]
    E[语言与平台残留]

五大类逐一看。每条都配一个 "怎么查"，能直接 grep 或人工抽检。

A. 溯源残留

文件里带着 "这是何时 / 为何加的" 叙事。

  1. 标签式溯源 —— 小节标题 / 括号带版本或事件，如 （v2.8 新增）、（已观测）、（保留）。查：grep （.*新 / （.*保留。
  2. 正文嵌版本号 / 变更指针 ——"自 vX 起"" 详见 CHANGELOG""原来用 A，现已迁移到 B"。查：正文里 v[0-9]\.[0-9]（非依赖声明），以及 "之前/原来/改为/迁移到" 句式。
  3. 按批次而非维度分组 —— 信息架构本身带时间线，按 "加入顺序" 组织而非按主题维度。查：把所有小节标题的溯源词删掉后，分组是否还合理？不合理 → 分组本身是残留。

B. 装饰与冗余

为达标而存在、不承载信息的结构。

  1. 装饰性 diagram / 注释 —— 为凑 "≥N 张图" 而画，不服务信息。查：删掉它，读者会少理解什么？答案是 "nothing" → 删。
  2. benchmark 角标当卖点 —— 文档里 #N 排名、stars 数当推荐理由。查：角标是否驱动当前决策？若只是 "看它多流行"，降为背景或删。
  3. 重复 / 冗余 —— 同一内容多处陈述。查：同一断言 grep 命中 ≥2 处，确认是否一处链另一处而非复制。
  4. 特例 guard —— 用加粗的 "除非/注意/例外" 补丁架构字段，而非把特例纳入字段定义。查：找 **除非** / **注意** / // HACK，判断能否重构为字段。

C. 死内容

文件声称存在、但实际没有或已过时的东西。

  1. 死指令 ——"统一/一律/必须" 类规则，正文实际没全做到。查：每条 "统一/必须" 指令，抽验正文是否真做到。
  2. 死链接 / 过时引用 —— [x](x.md) 指向不存在文件；引用的函数 / flag 已改名。查：lint 查死链；人工查引用符号是否仍存在。
  3. 死字段 / 死参数 ——frontmatter、配置表、函数签名里无人读的字段。查：grep 字段名全仓无读取 → 删。

D. doc / impl 裂隙

文档声称与实际结构 / 行为不符。

  1. 校验项与动作不对应 —— 文档写了 "检查 X"，但实现没产生 X 的动作；或代码做了 Y 但校验没查。查：逐条校验项反查动作源，逐条动作反查校验。
  2. 产物路径与清单不同步 —— 文档声明的产物路径与实际产物清单不一致。查：改声明时同步改清单。
  3. 跨实例共享结构 drift —— 多处共享同一结构，但某实例偷偷改了命名或顺序。查：grep 共享结构的标题 / 字段名，确认所有实例用词一致。
  4. 章节 / 编号跳号 ——1,2,3,5,6（漏 4）。查：编号是否连续无跳。

E. 语言与平台残留

夹带不属于当前语境的内容。

  1. 语言混用 —— 一种语言文档夹另一种语言叙述（代码标识符 / 枚举值除外）。查：正文语言是否一致。
  2. 平台 / 工具实现痕迹 —— 特定平台 / 工具的私有 API、CI step id 混进通用规则。查：规则是否平台无关。

怎么落地：心智先于清单

16 条规则不是检查清单，是写作心智。落地有三点：

flowchart LR
    A[写之前<br/>心智：读者只看当前事实] --> B[写之时<br/>每条规则对应一个 grep]
    B --> C[改之后<br/>每次diff局部纯净]
    C --> D[全局纯净]

** 第一，心智先于清单。** 记住 "读者只需当前事实" 这一句，能拦掉一半的问题。规则是用来兜底和审计的，不是用来边写边对的。

** 第二，每条规则都配 "怎么查"。** 能 grep 的就 grep，能 lint 的就 lint，让审计可自动化。比如 "标签式溯源" 直接 grep （.*新，"死字段" 直接 grep 字段名看有没有消费者。

** 第三，纯净审计落实到每次 diff。** 不是等全部写完再审计，而是每改一处就保持局部纯净，最后全局自然纯净。这条经验在合并多个 PR 时尤其重要 —— 大重构全程遵循纯净原则，commit 按子 agent、公式、校验等分类，主线才清晰。

本周其他工程产出

除了纯净原则，本周还做了这些，各点到为止：

  • designer 调优：designer 不再忠实复用文稿文字，而是做 PPT 风格化；以 HTML 源文件作为中间产物，方便单页调优。
  • 公式处理：OMML 在 WPS 支持不完整，改用 MathJax → SVG / 图片方案；LaTeX 智能识别归 researcher，渲染归 designer。
  • 降级设计：脚本启动参数 "首选 → 失败降级"，而非多选一；提示词对应 "渐进性披露"，不一次给太多选择。
  • HITL 显式化：需求对齐 → 大纲设计 → finalize.py 校验 → 用户确认才推进，不默认回答。
  • AI 阅读器 v0.1：新项目，PRD 与 tech 方向确认。

参考资料