Skip to content

2026-07-04-doc-tiers-and-budgets.zh.md

Latest commit

 

History

History
33 lines (23 loc) · 5.51 KB

2026-07-04-doc-tiers-and-budgets.zh.md

File metadata and controls

33 lines (23 loc) · 5.51 KB
Raw

Agent Note: 文档结构、层级与预算

Status: implemented

English | 中文

问题

尽管已有写作指导，常设文档仍不断累积重复规则、反复讲述的事故、重复的包映射，以及陈旧的 Agent Note 摘要。该指导也未明确文档在层级中的位置如何限定其内容范围，以及按顺序引导读者学习的内容与面向查阅的材料有何不同。仅靠评审无法阻止这种增长，因此仓库需要在文档分类体系之外再配一套可自动执行的预算。

决策

  • 结构遵循文档树。docs/AGENTS.md 是文档标准：文档负责承载其主题的详细内容，仅概述直接子项的目的、职责和高层行为，并链接到更深层内容的归属文档。Agent Note 仍不受这一结构约定约束。每份面向人的文档要么是按顺序引导读者达成结果的教程（tutorial），要么是查阅范围明确的参考文档（reference）；事故复盘（postmortem） 是范围限定于单起事故的参考文档，其时间线记录证据。教程结合读者的起始知识，按前置依赖顺序介绍概念。
  • **每项事实只归属一处的层级分类。**文档标准为每种 Markdown 层级分配单一职责，禁止在事实归属层级之外重复陈述，并包含编写或评审任何文档时使用的赘余检查清单。
  • **单一产品入门路径。**根 README 负责推荐的包运行路径、从源码运行的备选路径和简要的 dsh plugin --profile 用法。已发布的用户指南从运行中的 Web UI 内部任务开始，再链接到其他界面的独立教程或插件开发与进阶配置的参考文档归属处，而不会重复介绍 Web 启动步骤。
  • 范围窄且严格的预算门禁。scripts/verify-doc-budgets.ts 接入 doc-sync：scripts/doc-budgets.manifest.json 列出的每份文档都必须低于其词数上限（采用 wc -w 语义，统计整个文件）；预算内文件缺失也会使门禁失败，使重命名无法悄然遗落其预算。范围刻意只涵盖容易膨胀的常设文档——根目录和子树中的 AGENTS.md 文件、architecture.md、packages/README.md，以及它们将内容移入的常设策略文档（docs/testing.md、docs/defensive-patterns.md）。参考文档、Agent Note 和包 README 不设预算：只要每一行都是事实，长度在这些位置就是合理的；评审和赘余检查清单负责约束它们。
  • 上限是只进不退的执行红线。 达到或低于目标的文档在上限逐步下调时保留至少 5% 的余量；高于目标的文档则维持冻结的上限，在达到目标之前不得增长（根 AGENTS.md ≤ 1,600 词；architecture.md ≤ 1,800；子树 AGENTS.md ≤ 600，但 packages/AGENTS.md ≤ 650、docs/AGENTS.md ≤ 1,250；packages/README.md ≤ 600）。门禁变红时，迁移或压缩内容；只有在 PR（Pull Request）描述中给出明确理由时才提高上限。
  • 精简的工作流 skill（技能），约定归文档。.agents/skills/dsh-doc-standards 承载文档放置、审计和门禁失败处理工作流，并以文档标准为真源，与 dsh-translate-docs 和 i18n 约定之间的分工相同。

曾考虑的替代方案

  • 仅靠 skill 和评审纪律，不设门禁：否决。上述膨胀正是在现行规则和评审注意力已经存在的情况下发生的；一条没有自动化保障的行文规则在此处已被证明无法维持，而本仓库自身的质量门禁立场认为值得保持的不变式就值得编码。
  • 对所有文档层级全面设限：否决。一刀切的上限恰好惩罚了那些正当的长文档（如功能矩阵或类型目录，每一行都是事实），并产生逐文件的例外变更，训练贡献者机械地批准提限。
  • 为每个文档入口维护独立入门教程：否决。重复的设置步骤会在命令顺序、首个结果和产品定位上产生分歧。简短的 README 路径接上面向任务的指南，可明确衔接两者，且不需要维护相互竞争的教程。
  • 将标准放在 skill 内部：否决。约定归文档，工作流归 skill；如果标准被塞进 SKILL.md，那些不调用该 skill 而直接编辑文档的 agent（智能体）就看不到它，而 docs/AGENTS.md 已经作为子树指令被任何在 docs/ 下工作的人加载。

后果

  • 向受预算约束的文档添加内容需要腾挪空间：将新增内容迁移到其分类体系归属地并留下链接，或压缩现有行文来腾出空间。只增不减会导致 CI 失败。
  • 结构评审先检查归属关系和文档形式，再进行句子层面的编辑，使较低层级的细节迁移到其归属文档，而不是在错误的位置加以润色。
  • 读者会先进入可运行的 Web UI，再遇到 headless 执行、SDK 嵌入、自定义 profile 或直接 settings 文件；这些入口仍可从各自的参考文档归属处访问。
  • 仍高于目标的受预算约束文档不得增长；达到目标后，将恢复 5% 的工作余量。
  • 词数是一个粗糙的代理指标，这是有意接受的：它无法判断质量，但它在内容被添加的那一刻强制触发迁移决策，而那正是作者拥有足够上下文来正确放置内容的时刻。