xerrors--yuxi/docs/develop-guides/documentation-guidelines.md

文档编写与维护规范

本文是 Yuxi 正式文档的信息架构与写作标准，面向新增、修改、审阅或迁移 docs/ 内容的贡献者与 Agent。进入文档子树时还必须遵循 docs/AGENTS.md；系统事实以仓库根 ARCHITECTURE.md 为准，开发流程和测试命令分别由 Yuxi Spec Loop 和测试规范拥有。

适用范围与目标

本规范适用于用户指南、配置参考、机制详解、开发指南、决策记录、事故复盘及代码变更所需的配套文档。目标包括：帮助读者从可运行结果逐步建立系统模型；让维护者能够追溯源码、配置、数据或协议 Owner；要求 Agent 在动笔前确定页面职责，避免向最近的文件直接追加内容。

合格页面需要回答预定读者当前要解决的问题，完整保留行为、条件、时序、失败、权限和安全用法，并删除实现过程叙事、重复解释及装饰性内容。篇幅、图表和术语只按表达需要使用，不构成独立质量指标。Yuxi 维护单语文档；英文标识仅在源码、配置或行业术语需要时保留。

信息架构与事实 Owner

一个事实只有一个负责完整解释的页面；其他页面保留完成当前任务必需的最小上下文并链接 Owner。页面在目录中的位置决定其职责和允许的细节：

层级	读者任务与内容 Owner	不应放入
intro/	第一次使用、完成可观察结果、理解产品概念	内部类调用链、部署变量全集、设计取舍
advanced/	配置、部署、运维、外部集成与故障定位参考	大段源码解读、重复的产品入门
agents/	Agent 配置与扩展开发的接口、约束和操作方法	跨系统机制全景、仅供历史解释的实现过程
mechanisms/	当前运行机制、状态、Owner、权限、失败与源码定位	面向初学者的完整安装步骤、环境变量清单
develop-guides/	贡献流程、测试、设计、文档治理和工程信任	产品使用教程、运行时事实的重复副本
develop-guides/decisions/	非显然决定、真实替代、代价与验证	当前 API 手册、迁移日志、推理流水账
develop-guides/postmortems/	达到门槛的事故影响、时间线、因果链和防复发	普通修复记录、版本发布列表
根 ARCHITECTURE.md	稳定代码地图、主链路和系统不变量	模块 API 细节、操作教程、决策历史
changelog.md / roadmap.md	已发布事实 / 尚未完成的方向	同一事项同时声明完成与未完成

子页面可以完整描述自己的主题，只用目的、责任和高层行为概括直接下级；更深细节下沉到真正 Owner。源码、schema、Compose 和测试拥有可执行事实，文档拥有面向读者的稳定解释，决策记录拥有“为什么接受这个取舍”。

教程与参考

每份人类可读文档在写作前必须归类为教程或参考。教程带领明确起点的读者按顺序得到一个可观察结果；参考围绕明确主题提供可查找的当前事实，不要求从头顺序阅读。少量辅助内容可以放在标明名称的次级章节，实质性混合内容必须拆页并互相链接。

教程先写前置条件和最终结果，再按依赖顺序介绍概念与步骤。作者在内部将读者起点和概念划为入门、中级、深入三个层级：当前步骤只解释完成它所需的概念，可选原理与完整参数转到机制页或参考页。每个关键步骤给出可观察验证，不用“配置成功”“应该可以”代替实际页面、状态、文件或协议结果。

参考先声明查找范围，再按读者问题组织字段、语义、限制、失败和示例。表格适合精确映射，流程图适合三步以上的状态或调用关系；一个事实用短段落已能说明时不添加图。参考不按实现文件逐个复述函数，也不手写可以从源码或生成器直接得到且容易漂移的完整目录清单。

从浅入深的写作流程

1. 读取根与当前子树 AGENTS.md、ARCHITECTURE.md 和 owning 文档；非平凡改动先按 Spec Loop 建立 proposed decision。
2. 写出预定读者、要解决的问题、前置知识、目标、非目标和页面类型，定位它在目录树与侧边栏中的父级。
3. 通过符号搜索重建事实链：入口 → 服务或执行器 → 持久化/发布点 → 用户或模型可观察结果；同时找到权限、失败路径和相关测试。
4. 先列页面 Section 及每节唯一问题，从概念和全景进入组件关系，再进入状态、边界、失败和源码定位；教程则按完成任务的前置依赖排序。
5. 一次只撰写或审阅一个 Section。完成该节后核对事实、链接和与相邻 Section 的重复，再进入下一节；不要一次生成整页后把内部矛盾留给最终校对。
6. 更新事实 Owner 后再更新索引、导航、派生示例和交叉链接。移动页面时在同一变更中修复所有入站链接，不能留下两个可独立维护的副本。
7. 从最小相关检查开始，运行文档构建、工程契约检查和补丁检查；由独立 Reviewer 对照需求、源码与完整 diff 做语义审查。

不同解释会改变权限、安全、数据或公开行为时必须停下确认；只影响措辞且可由当前 Owner 判断时，记录假设后继续。外部 Wiki、搜索结果、旧 changelog 和历史 PR 只能帮助发现入口，不能覆盖当前源码与测试。

证据与源码定位

机制、API、配置和安全说明必须能追溯到当前仓库证据。优先顺序是：当前公开契约与真实装配入口；执行行为的 service/executor/repository 与数据约束；Compose、schema 和配置默认值；与风险匹配的 unit、integration、E2E；最后才是 decision、changelog 和外部说明。发现冲突时先修正 owning 事实或明确未验证范围，不能挑选更方便的材料。

机制页在末尾提供“源码定位与验证”Section，按职责列少量稳定入口，例如装配、状态 Owner、适配器和关键测试。docs/ 内页面使用站点相对 Markdown 链接；站点根之外的公开源码使用项目 GitHub blob/main 文件链接，让发布后的页面可以直接进入 Owner。不要写本地绝对路径、行号快照、分支临时提交 URL 或易变化的函数清单。正文需要说明某个字段、状态或环境变量时，名称必须与源码一致，并写清谁读取、何时生效、默认值来自哪里、错误时如何表现。

验证结论只使用项目定义的 Passed、Inspected、Not run、Inferred 语义。HTTP 200、任务“完成”提示、日志关键词和 Agent 自述不能证明最终事实；根据主题回读数据库状态、对象、文件、页面、DOM 或协议输出。文档变更没有运行产品链路时应写 Inspected 或 Not run，不要包装成测试通过。

机制详解页面契约

“机制详解”回答系统为什么呈现当前行为以及各部分如何协作，不替代配置手册。每页至少覆盖以下内容，标题可按主题调整：

• 适用范围：读者、前置知识、页面负责与不负责的内容。
• 全景与阅读顺序：高层组件关系或状态流，并标明可选分支。
• 真实装配链：producer、registration/dispatch、consumer、持久化或发布点、可观察结果。
• 状态与 Owner：关键状态、允许转换、事务或文件归属、缓存与派生视图。
• 权限和隔离：身份来源、可见性过滤、执行处的最终拒绝边界、LITE 或可选能力行为。
• 失败与恢复：失败如何被记录、何处可观测、是否可重试、哪些结果不能推断。
• 配置边界：只解释影响机制的参数语义，完整变量和操作步骤链接到配置页。
• 源码定位与验证：少量 owning 路径、关键 oracle、未覆盖或外部依赖。

图中的节点使用稳定职责名，必要时在同一节点标注 owning 模块；不要把类名堆成目录图。图只辅助理解，正文必须单独说明条件、异常、权限和持久化语义。尚未实现的方向不画进当前机制图，放入 roadmap 或 proposed decision。

写作标准与冗余检查

使用直接、具体、可验证的现在时。句子写明执行者和动作：写“KnowledgeFileRepository 保存文件状态”，避免“状态被处理”；写“API 在事务提交后投递 ARQ”，避免“确保一致性”。Owner、边界、契约、gate 只用于表达所有权、信任或事务分界、调用义务、阻断检查。具体字段、校验、接口和时序优先于抽象术语。

普通段落每段使用一个物理行，由编辑器软换行；代码块、表格和列表保留自身结构。一个段落承载多个独立规则时拆成多个段落或列表，不用硬换行掩盖段落墙。

优先使用肯定句陈述职责、边界和结论。对举式否定通常先构造一个弱命题，再依靠转折制造强调，信息密度低且容易出现机器化语气；此类句子改写为目标事实及其适用条件。必要的禁止、例外和失败语义可以直接使用否定句。

每次修改都检查以下文档噪声，同时保留完整命题：

• 同一规则在两个页面完整出现；保留一个 Owner，其他页面改成一句上下文与链接。
• “以前、现在、不再、这次修改、某 PR”混入当前说明；当前事实留在正文，变化原因进入 decision，事故过程进入 postmortem。
• 按代码逐行叙述控制流、解释显然分支、记录测试过程或 Review 对话；只保留调用者需要的行为、条件、失败和后果。
• 手写完整 API、文件、测试或配置清单，而源码、schema、Compose 或生成器才是权威；正文保留稳定分类与查找入口。
• 大段“架构很重要、功能很强大”等宣传性前言，没有帮助读者完成任务或建立系统模型。
• 过度使用粗体、提示框、括号和英文缩写；强调只用于会改变操作、安全或兼容结果的内容。
• 先否定一个宽泛说法，再用转折重复目标结论；直接保留后半句并补齐条件或后果。
• 用“可能、应该、一般”掩盖未核实事实；核实后写确定语义，无法核实时明确条件和 Not run 范围。

代码注释与 JSDoc/docstring 只描述源码局部无法表达的调用义务、时序、失败、所有权和安全用法，不把机制页复制进代码。模型可见 prompt、工具描述和 UI 文案属于行为，修改时需要相应测试或明确说明为何没有可适用的行为验证。

图、示例与敏感信息

三项以上组件关系、状态转换或跨边界时序优先使用最小可用 Mermaid 图；精确字段映射使用表格，单步操作用正文。图要能在 VitePress 构建中渲染，节点文本包含标点或括号时使用引号。不要用 ASCII 大图重复同一关系，也不要用颜色承担唯一语义。

示例必须能复制到对应上下文，使用与仓库一致的服务名、路径和命令。占位值用 <your-value>、example.com、文档保留 IP 或明确的假 ID；不从 .env、日志、数据库和个人目录复制真实账号、Token、内部地址或用户数据。安全参数示例说明最小长度、是否可轮换和泄露后果，但不提供弱默认值。

代码块只保留解释当前任务需要的最小片段，并标注正确语言。示例输出与运行时事实同样需要 Owner：稳定协议字段可写入并由测试保护，容易漂移的长输出只展示关键字段。外部截图和生成 Wiki 不能证明当前实现；需要引用外部资料时链接官方或一手来源，并注明它只支持哪项背景判断。

维护、预算与验证

代码、配置、API、权限、状态或命令变化时，修改同一变更中的 owning page；仅受影响的导航或上级概览同步更新链接和一句摘要。新增页面必须加入 docs/.vitepress/config.mts 的正确层级，检查前后页阅读顺序；内部 decision、postmortem 和 AGENTS.md 不因存在于 docs/ 就自动成为面向用户的首要入口。

根与子树 AGENTS.md 使用 scripts/verify_engineering_contracts.py 中的字符预算。该 guardrail 控制 standing orders 的增长，不要求删除正确事实。超限时先把示例、背景和专题解释下沉到 owning 文档，再压缩重复句；只有内容确实属于该指令文件时才提高预算，并在 decision/PR 中说明原因。参考页和机制页由职责边界与 Review 控制，不设统一篇幅上限。

文档改动至少运行：

python3 scripts/verify_engineering_contracts.py
python3 -m unittest scripts.test_verify_engineering_contracts
cd docs && pnpm run build
git diff --check

纯文档改动不需要用后端 unit 结果装饰可信度；如果页面描述了运行时行为，应检查相关现有测试，必要时运行最小集合。构建失败先修正文档或导航，不扩大 ignoreDeadLinks 掩盖断链。提交前报告实际命令、结果、未执行项和风险。

提交前检查

• 页面有明确读者、目的、边界和教程/参考类型，概念顺序符合前置知识。
• 每个重要事实只有一个完整 Owner；上级页面没有复制下级实现细节。
• 行为、状态、默认值、权限、失败和恢复已对照当前源码、配置、数据约束或测试。
• 机制页包含真实装配、状态 Owner、观察结果、安全边界、失败语义和源码定位。
• 教程关键步骤有可观察结果，参考字段有条件、默认值、限制和生效时机。
• 没有 PR 叙事、旧实现故事、推理流水账、手写易漂移清单或无证据宣传语。
• 相对链接、标题层级、代码块、表格和 Mermaid 图在 VitePress 中有效。
• 新页面已加入导航；移动或拆分页面的全部入站链接已更新，没有双重 Owner。
• 示例不含 secret、真实账号、用户数据、本地绝对路径或无法公开的内部地址。
• 实际验证与未验证范围已记录，独立 Reviewer 已覆盖完整需求、diff 和证据。