deepseek-harness/.agents/notes/proposed/process/2026-08-20-audience-first-documentation-quality.zh.md

Agent Note: 以受众为先的文档质量标准

Status: proposed

English | 中文

问题

文档系统拥有健全的放置、新鲜度、链接、双语和源等价性检查，却没有把「简短、直观、友好」定义成可供用户、新人、开发者和 agent（智能体）评审的结果。全部 doc-sync（文档同步门禁）检查和全部翻译配对均通过，但仍存在以下设计问题。前三项发现是设计重点；容量问题则解释了为什么增加更多常驻规则无法解决它们。

语义正确性可以在没有现行归属者的情况下通过检查

这些门禁证明结构和生成内容的新鲜度，却不能证明维护中的正文仍指向实际机制。以前的 dsh-doc-site-sync 技能曾要求作者复用并不存在的 en-docs 侧边栏，还要求把章节加入已经移除的 sectionOrder；website/docs.ts实际拥有 en-guide、en-develop、en-reference 和 sections。已实现的产品优先 README 决策描述了内部测试说明，以及 ACP、Python 与 JSON-RPC 界面章节，但根 README并无这些内容；与此同时，已实现 Agent Note 必须跟随已交付事实。

预算策略也存在相同的分裂。docs/AGENTS.md为 architecture.md 规定 1,800 词目标和 5% 余量，但预算 manifest（元数据清单）允许 2,400 词，而该文件实际包含 1,313 词。预算门禁之所以通过，是因为它只检查 manifest 上限，不检查目标或棘轮规则。因此，高影响正文需要一个具名真源或消费真源的聚焦检查；第二份手写副本不是新鲜度机制。

读者成功与否是隐含判断，而不是可测试结果

标准把页面分成教程和参考，并要求作者私下判断教程读者的起始水平。标准没有要求留下可供评审的读者起始状态、预期结果、最短成功路径、常见失败或下一篇有用页面。因此，一份文档可以满足层级放置、链接、词数限制和 Markdown 结构，却没有证明目标读者能完成任务。

公共站点直观呈现了这种压力。每种语言发布 84 个页面：3 个指南页面、17 个开发页面和 63 个参考页面。docs/user/ 下的 13 个英文文件共有 7,540 词，而 47 个子系统页面共有 100,759 词。简短的 Web 快速开始是良好的产品入口，但全语料没有标准来验证首次使用者、插件新人和维护者是否都能沿一条明确路径从入口走到结果与故障恢复。

生成内容的准确性与检索质量混为一谈

仓库包含 19 个完全生成的英文 Markdown 文件，共 49,611 词。47 个子系统页面中有 44 个也包含生成的 Cordis 区域；这些区域占子系统层级 100,759 词中的 34,622 词。config-catalog.md 有 14,807 词，tool-catalog.md 有 10,599 词，最大的混合子系统页面则有 5,600–7,781 词。

这些内容是正当的穷尽式参考，因此统一词数限制反而会删除价值。生成器证明完整性和新鲜度，但标准没有为上下文窗口有限的 agent，或只寻找一个答案的人类读者另设检索标准。生成参考需要紧凑的入口层、稳定分组、直接锚点，以及根据查询成本触发的拆分规则；穷尽式细节可以在该入口层之后继续保持穷尽。

标准没有容纳下一条规则的空间

常驻文档标准有 1,320 词，等于 1,320 词上限，并超过声明的 1,250 词目标。根 AGENTS.md 有 1,936 词，目标为 1,600；packages/AGENTS.md 有 672 词，目标为 650；packages/README.md 有 969 词，目标为 600。冻结的上限能阻止进一步增长，却没有为受众和结果标准创造位置。继续增加常驻正文会加深该标准本应防止的问题。

基线

本次审计排除 vendor/、冻结的 .agents/notes/archived/、录制快照和 fixture（测试前置数据）。受维护语料包含 1,042 个英文 Markdown 文件和 986 个中文对侧文件，共 1,106,138 个英文词。活跃 Agent Note 占 580 个文件和 637,850 词；packages/ 下的 Markdown 占 276 个文件和 225,630 词；docs/ 占 112 个文件和 193,456 词。这些数量描述维护和检索压力，本身并不构成缺陷。

系统最强的性质应予保留：按层级为每项事实指定一个归属者；把规范 Markdown 投影到站点而不创建副本；完整双语配对；源变更时快速失败的生成目录；源等价声明；可编译的 TypeScript 示例；受检查的链接与锚点；以及包局部的模型体验与限制约定。提案改变的是质量标准和入口结构，而不是这些保证。

提案

采用一套以受众为先的质量约定，并给出五项定义：

• 简短表示常用路径只包含达成结果所需的事实。穷尽式约定仍可通过直接链接或生成细节访问；简短绝不意味着删除必要行为、失败、所有权或限制。
• 直观表示页面会确定读者的起始状态，在依赖概念之前介绍前置知识，提供一个明确的下一步操作，并使用读者会搜索的产品或领域术语。
• 友好表示读者能识别成功，在操作前理解实质风险，从常见失败中恢复，并在无需先学习无关架构的情况下进入下一层相关细节。
• 准确表示每项持久事实都有一个归属者和与风险相称的验证路径。生成事实来自源；手写工作流值链接或消费其归属者，而不是复制枚举和路径。
• 便于 agent 阅读表示标题、锚点、术语、所有权以及当前与提议状态足够明确，无需加载整个语料或重建评审历史即可检索所需章节。

原型规则

dsh-doc skill 负责这些规则的首个可执行版本。SQLite README 对以已交付的分片行实现为证据，而不把其旧版正文当作权威。

• 每个撰写型包 README 都以可搜索 YAML 开头。Skill 风格的 description 与按机制推导的 kind 为必填字段。四种 kind 与四个技能模板一一对应：package-group（组地图）、package-reference（插件或服务包）、package-library（纯模块入口）与 package-bundle（dsh.bundle.patch）。对照文件路径、哈希与物理行对齐由支持自动合并的 sidecar 及其门禁负责，因此 README frontmatter 不包含 i18n 块。名称已由标题或包 manifest 归属，受众已由文档职责表达；在受治理的标签分类与搜索消费方证明其价值超过全文检索之前，不加入标签。
• 撰写型页面先写三至五句的 Summary，再写带链接的 Table of Contents。由格式约束的 Agent Note、事故复盘、生成片段和机器文件保留其必需骨架。
• 每个实质章节在子章节、表格或代码之前先给出简短引导，页面则从基础用户用法逐步进入高级开发者与维护者细节。
• 英文技术正文采用受 ASD-STE100 启发但不宣称认证的清晰度评审：明确行动者与动作，稳定使用术语，使用直接动词，拆分指令与条件，并完整保留情态、例外、时序与数值。指令 20 词和描述 25 词的限制仅作评审提示。准确性高于句长。
• 包约定留在代码旁。跨包材料有计划地向 docs/learn/overview/、docs/learn/cordis/、docs/learn/practices/、docs/user/、docs/developer/、docs/developer/discussion/、docs/scratch/ 和平行的 docs/subsystems/ 层级迁移。
• 英文和中文页面保持同等权威，并在结构、链接、代码、frontmatter 布局和精确物理行数上一一对应。
• 内联配对元数据是伴随文件的目标替代方案。在验证器、合并驱动、恢复流程、生成区域记录器和归档检查消费非自引用配对摘要之前，原型可以同时保留两者。
• 仓库根级内部链接是目标撰写模型。原型保留渲染器可用的相对链接，因为前导 / 当前会在 GitHub 上离开仓库、绕过 verify-md-links，并且不会由站点投影。
• Further Exploration 是可选的新人路径，链接三至七个相邻页面。
• 每个撰写型页面都以 Dev Note 结尾，作为活跃粗略上下文的唯一位置。它保持非权威状态，只链接而不复制任务状态，并在工作结束时完成提升或清理。
• 可独立搜索的规则、实践、示例和决策在拥有不同归属者或变更节奏时，使用描述性目录下的小文件；紧密耦合的义务保留在一起。

按文档职责划分的标准

职责	主要结果	必需入口信息	验证
产品快速开始	完成一项有代表性的任务	前置条件、一个启动路径、首次成功、安全边界、下一步	文档路径的构建或打包冒烟测试，加链接和站点检查
用户任务指南	完成一项用户任务或从中恢复	起始 UI／API 状态、有序操作、可观察结果、常见失败及恢复	行为测试；涉及视觉状态时评审截图；或指定人工归属者
贡献者教程	进入通过检查的开发状态	支持的运行时、设置命令、预期结果、聚焦的后续命令	在受支持环境中对干净检出运行命令冒烟测试
架构概览	从一个页面重建系统	产品组合、归属者、依赖方向、扩展点、细节链接	由源支持的包或图检查，加聚焦人工评审
包或子系统参考	无需阅读实现即可查到一项约定	范围、归属的类型或行为、失败、生命周期、限制、相关归属者	既有 JSDoc、类型等价、生成区域、README 和链接检查
生成参考	找到一个精确条目并信任其完整性	范围、生成归属者、分组或索引、稳定锚点、相关概念指南	确定性 --check、完整性 fixture、站点构建和检索规模报告
Agent 指令或 skill（技能）	在没有陈旧复制值的情况下执行一项工作流	范围、权威链接、必需决策、仅在此处归属时写入精确命令	元数据或链接检查，以及针对复制机器值的聚焦测试
提议或已实现 Agent Note	理解决策、取舍与状态	问题、提案或决策、备选方案、验收或后果	既有生命周期、格式、配对和取代检查；语义时效性由评审负责

该表应归属一份规范质量参考。docs/AGENTS.md 只保留每次编辑文档都需要的简短常驻规则，并链接到该参考。这样可以创造预算余量，而不是把另一份完整标准放进 agent 上下文。

生成参考的入口层与细节层

每份生成参考都应在穷尽式输出之前提供紧凑入口层：范围、预期查询、分组或索引、概念指南的直接链接，以及生成器或检查命令。生成器应报告页面词数、条目数、标题数和最大章节。当一次查询需要扫描无关分组，或单页主导 agent 上下文时，该页面便跨过评审阈值；随后，归属者按照源元数据中已有的稳定领域拆分页面，而不是按任意词数切片。

首个原型应选择一个大型目录和一个混合子系统页面。在进行全语料拆分前，它应比较查询步骤、生成 diff 大小、构建时间、路由稳定性，以及代表性问题所需的 agent 上下文。路由移动时，既有锚点需要保留别名。

执行切片

1. 创建并验证 dsh-doc，再把 session-persistence-sqlite README 对改写为行对齐、带元数据的原型，同时不改变运行时事实。
2. 用新人、用户、开发者和 agent 任务评审渲染后的原型；先修订 skill，再在其他位置强制执行该格式。
3. 添加聚焦的元数据、章节顺序、行对齐、链接解析和配对 fixture。在每个合并与恢复消费方都有替代支持前，保留伴随文件。
4. 把已接受的常驻规则提取到一份规范质量参考，将 docs/AGENTS.md 精简到目标以下，并且一次只组织一个内聚的 docs/ 主题，同时原子地修复链接与导航。
5. 在 config-catalog.md 和 docs/subsystems/core.md 上制作生成参考入口层与细节层分离的原型；只有实测查询成本下降且没有丢失事实或造成路由扰动，才把确认后的模式应用到其他位置。

该顺序使每项变更都能独立评审。前三个切片在不重写语料的情况下改进标准与正确性；生成文档原型则在更广的信息架构变更前提供证据。

切片 1–3 已按此形式交付：dsh-doc 成为合并后的标准（dsh-doc-standards 与 dsh-doc-site-sync 已并入其中，站点工作流携带修正后的侧边栏值），session-persistence-sqlite README 对是参考示例，pnpm run test:docs 强制执行元数据、配对与快速文档检查。切片 4–5 仍待完成。

非目标

本提案不缩减穷尽式事实，不合并受众层级，不发布内部决策记录，不恢复 Agent Note 索引，不为了文件数对称而拆分紧密耦合的规则，也不把此次审计当作用户研究。在替代方案通过等价的恢复与渲染检查前，本提案不删除现有配对或链接基础设施。

考虑过的备选方案

**为每份文档设置统一词数上限。**不予采纳，因为穷尽式参考条目、公开约定和决策理由可以既长又正确。对这些文档职责而言，入口路径长度与查询成本才是相关约束。

**强制使用统一页面模板或受众前置元数据。**不予采纳，因为这会给生成页面、包参考和简短指令增加形式，却不能证明读者成功。标准按文档职责定义结果，仅在 kind 能选择具体包文档标准时使用它，并且只添加聚焦检查或评审会消费的字段。

**把可读性分数作为质量门禁。**不予采纳，因为公式会惩罚精确技术术语，却无法发现错误所有权、遗漏失败行为、陈旧命令或破损的读者路径。

**立即重写或拆分全部语料。**不予采纳，因为现有系统在机制上健康，许多长参考也确实应保持穷尽。原型应先证明检索有所改善，再扩散路由和翻译扰动。

**保留现有门禁，让评审负责友好程度。**不予采纳，因为陈旧工作流值和预算策略不一致说明，仅凭评审无法保留复制的语义事实，而现有门禁也不询问读者是否能完成任务。

验收标准

• 一份规范质量参考按文档职责定义简短、直观、友好、准确和便于 agent 阅读的文档。
• .agents/skills/dsh-doc 通过验证，并直接链接其元数据、结构或层级及评审或原型参考，而不在 SKILL.md 中复制这些参考的详细规则。
• SQLite README 对展示可搜索 YAML、Summary、Table of Contents、从用户到开发者的渐进结构、Further Exploration、结尾 Dev Note、结构一致性和精确行数相等，同时保留已验证的包约定。
• docs/AGENTS.md 链接该参考，仍足以充当常驻指令，并低于其目标且至少保留 5% 余量。
• 根级用户路径、Web 快速开始、第一个插件教程、贡献者设置和架构概览各自给出一个可观察结果与验证归属者，同时不复制实现细节。
• 预算 manifest 同时记录目标与临时上限，其检查会报告或拒绝违反余量或棘轮规则的状态。
• 文档站工作流不再包含复制的无效侧边栏名称或章节归属声明，并有聚焦测试防止复发。
• sidecar 继续作为唯一一致性记录，因为它能保留同等权威、上次确认文本恢复、自动合并安全、生成区域记录和归档封存，同时不会在正文文件中制造冲突。
• 一个已接受的仓库根级链接格式在迁移相对链接前能在 GitHub 与文档站正确渲染，并继续接受本地目标或锚点检查。
• 一个大型独立生成目录页和一个混合子系统页面展示紧凑入口层与更低的实测查询成本，同时保留穷尽式生成事实、稳定链接、双语配对和确定性新鲜度。
• pnpm run doc-sync、pnpm run lint、聚焦的新检查和 git diff --check 均通过。

风险

• 元数据可能沦为样板；因此包 README 检查只允许具有现行检索、模板选择或双语一致性消费方的字段。
• 硬性句长限制可能割裂说明，或把条件与后果分开。受控英语的词数限制仅作评审提示，精确约定优先于句长。
• 精确行对齐可能迫使译者写出不自然的正文；评审必须保护含义，并可同时修订两侧，而不是削弱其中一侧。
• 拆分生成参考可能增加路由与链接维护；原型必须保留别名并衡量取舍。
• 语义检查可能膨胀成阻塞正当变更的仓库拓扑扫描器；检查应覆盖高风险复制值和代表性路径，而正文含义仍由评审负责。
• 包 README 的快速参考表会手工重复部分配置默认值；在源驱动检查接管之前，评审者必须对照源码和生成配置目录验证变更值，并让这些表保持精选而非穷尽。
• 为缩短 agent 上下文而优化可能使人类参考变得碎片化；每次拆分都需要一个稳定概念归属者和一条明确导航路径。
• 永久的 Dev Note 可能变成第二份队列或陈旧历史堆积；完成工作时必须提升持久事实并删除已解决的过程内容。
• 本次审计使用仓库结构、门禁和代表性页面，而不是用户研究。在广泛推广之前，维护者应通过真实的新人、用户、开发者和 agent 任务验证提议的读者结果。