Yuxi

Appearance

文档编写与维护规范 ​

这份规范回答两个问题：读者怎样更快得到结果，维护者怎样避免把错误信息写进文档。它适用于 docs/ 下的教程、操作指南、参考、机制说明、开发指南和版本材料。

文档不是代码的逐行注释，也不是把所有接口堆在一起的目录。每一页都应围绕一个读者任务组织内容，并把容易变化的事实交给源码、配置、Schema、Compose 或测试维护。

先确定读者和结果 ​

动笔前先写清三件事：

  • 读者是谁：第一次部署的人、平台管理员、Agent 开发者、集成开发者，还是项目贡献者。
  • 读者要完成什么：例如启动服务、接入模型、让 Agent 使用知识库、排查一次失败任务。
  • 怎样算完成：给出页面状态、文件、接口响应、运行结果或其他可以重新检查的证据。

标题优先描述任务或对象，不用“全面介绍”“详细说明”之类的空泛措辞。开头直接说明适用范围、前置条件和读完后能得到的结果；读者不需要的信息放到链接指向的专题页。

信息架构与事实 Owner ​

Yuxi 采用 Diátaxis 的四类文档思路。现有目录保持不变，但写作时要先判断页面属于哪一类：

四种页面，各自解决一种需要 ​

类型读者正在做什么Yuxi 的主要位置
教程从明确起点按顺序完成一次任务intro/
操作指南已经了解基本概念，解决一个具体问题advanced/、agents/
参考查一个参数、接口、状态或限制advanced/、develop-guides/
解释理解系统为什么这样工作，以及边界在哪里mechanisms/、ARCHITECTURE.md

一页可以有少量辅助内容，但不能把安装教程、变量字典和内部实现长期混在一起。页面职责不清时，先拆分或把细节移到真正的 Owner，再用一句话和相对链接承接上下文。

目录层级的职责如下：

  • intro/：第一次使用和产品任务的顺序教程。
  • advanced/：部署、配置、外部集成和故障处理参考。
  • agents/：Agent、工具、MCP、Skills、子智能体的配置和扩展方法。
  • mechanisms/：运行链路、状态、权限、文件与失败恢复的解释。
  • develop-guides/：贡献、测试、设计和文档治理。
  • decisions/：代码和当前文档无法表达的非显然取舍；它不是运行时说明的副本。
  • postmortems/：达到项目门槛的逃逸事故及其防复发机制。
  • changelog.md：已发布变更；roadmap.md：尚未完成的方向。

内容怎么组织 ​

教程和操作指南 ​

按依赖顺序写：前置条件 → 操作步骤 → 可观察结果 → 常见失败和下一步。关键步骤不要只写“配置成功”或“启动完成”，要告诉读者去哪里确认，例如某个 URL 返回什么、文件状态变成什么、页面出现什么。

一个步骤只做一件事。命令前说明它会改变什么，命令后说明成功和失败分别意味着什么。危险操作先写影响和备份要求，再给命令。

参考页 ​

开头先说明查找范围。字段、变量、状态和接口按读者问题分组，写清名称、默认值、条件、限制、生效时机和失败表现。完整清单如果会随代码变化，保留稳定分类并链接源码或生成 Owner，不手写第二份容易过期的清单。

机制页 ​

机制页至少回答：

  1. 这条链路什么时候生效，处理什么对象？
  2. 组件如何连接，谁创建、谁消费、谁保存事实？
  3. 关键状态怎样变化，哪个事务、文件系统或服务拥有它？
  4. 权限和隔离在哪里最终执行？LITE 或可选依赖怎样表现？
  5. 失败如何记录、如何恢复，哪些结果不能从现象推断？
  6. 读者应查看哪些源码、配置和测试？

流程图只表达三个或更多组件之间的关系、状态转换或跨边界时序。图不能替代正文中的条件、权限和异常语义。

语言和术语 ​

使用直接、具体的现在时和主动句，写出执行者、动作、条件和结果。例如：“API 在 PostgreSQL 事务提交后投递 ARQ”；不要写“请求会被处理”或“系统会确保一致性”。无法核实的内容明确写出条件和未验证范围，不用“应该、一般、可能”掩盖不确定性。

中文是正文语言；代码、配置和行业名称保留原文。第一次出现时给出中文和英文名称，之后保持一种写法：

  • 智能体（Agent）：面向用户的正文优先写“智能体”，代码标识保留 Agent。
  • Skill、MCP、Sandbox、Workdir、Run、Request、SSE：首次解释用途，后续保留项目约定的英文名称。
  • Embedding、Rerank：分别写“嵌入模型”和“重排模型”，需要对应源码字段时保留 embedding、rerank。
  • 知识库与数据库分开使用；只有 PostgreSQL 等持久化组件才称为数据库。

段落短一些，一个段落只讲一个结论。列表用于并列规则，表格用于精确映射；不要用大量加粗、括号、提示框或英文缩写制造层次。删除宣传性开场、重复结论和“本节将……”式过渡。

示例和安全 ​

示例必须能在对应上下文中使用。命令使用仓库真实的服务名、路径和参数；URL、账号、Token、ID 和域名使用 <your-value>、example.com 或文档保留值。不要复制 .env、日志、数据库、个人目录、内部地址或用户数据。

涉及密钥、权限、文件路径、外部网络或数据迁移时，说明最小权限、存放位置、泄露后果和回滚边界。不要建议把 provisioner、数据库、对象存储或云平台管理凭据注入 Agent 沙盒。代码块只保留当前任务需要的片段，并标注正确语言。

事实、链接和 Owner ​

当前事实的核对顺序是：

  1. 真实装配入口、公开契约和用户入口；
  2. service/executor、repository、Schema、数据约束和持久化边界；
  3. Compose、配置默认值和部署脚本；
  4. 与风险匹配的 unit、integration、E2E、replay 或真实探针；
  5. decision、changelog 和外部资料。

源码、Schema、Compose、测试和数据约束拥有可执行事实；文档负责把事实讲给读者听。发现冲突时先修正事实 Owner 或明确条件，不能挑选更顺手的说法。

每个重要事实只在一个页面完整说明。其他页面保留完成当前任务所需的一句话，并链接 Owner。站内页面使用相对 Markdown 链接；仓库外的公开源码使用项目 GitHub blob/main 链接。不要写本地绝对路径、易漂移的行号、临时分支 URL 或只列文件名的源码清单。

当前说明使用现在时。历史原因、取舍和代价写入 decision；事故影响、时间线和因果链写入 postmortem；已完成变更写入 changelog，未完成方向写入 roadmap。不要在当前页面混入“这次修改”“以前版本”或 Review 过程。

验证结果怎么写 ​

重要事实要能从页面追到语义 Owner、独立 oracle 和实际执行后果。改变权限、数据、运行生命周期、文件隔离或公开行为时，至少说明：谁拥有事实、怎样直接观察、什么负向案例能让目标缺陷失败，以及哪个 workflow 或 Reviewer 会阻断错误结果。不要用中央 claim ID 或手工清单替代这些关系。

验证状态使用固定含义：

  • Passed：命令实际成功，并且回读了数据库、文件、对象、DOM 或协议结果；
  • Inspected：只读核对了源码、配置、Schema 或已有材料；
  • Not run：没有执行，必须写明原因和剩余风险；
  • Inferred：由间接证据推断，不能当作直接测试通过。

构建成功、HTTP 200、日志关键词、mock 调用次数和 Agent 自述都不是最终事实。文档改动没有运行产品链路时，写 Inspected 或 Not run；不要把它包装成产品行为已通过。

修改流程 ​

  1. 读取根与子树 AGENTS.md、ARCHITECTURE.md、当前 Owner 和相关源码。
  2. 写出读者、任务、前置条件、完成标准、非目标和页面类型；非平凡的信息架构或长期约束变化先建立 proposed decision。
  3. 沿入口 → service/executor → repository/发布点 → 用户或模型可见结果核对事实，同时检查权限、失败、LITE 和可选依赖。
  4. 先列出每节唯一要回答的问题，再按“概念 → 关系 → 状态/Owner → 权限/失败 → 源码定位”展开；教程按完成任务的顺序展开。
  5. 一次只写或审阅一个 Section。每节完成后检查事实、链接、术语和重复，再继续下一节。
  6. 先更新事实 Owner，再同步导航、索引和引用页。移动或拆分页面时在同一变更中修复所有入站链接。
  7. 先跑最小相关检查，再运行文档构建、工程契约检查和 git diff --check。交付前由不继承开发上下文的 Reviewer 对照源码、完整 diff、测试和未验证范围审阅。

提交前检查 ​

  • 页面有明确读者、任务、前置条件、完成标准和类型。
  • 一个事实只有一个完整 Owner，上级页面没有复制下级实现细节。
  • 行为、状态、默认值、权限、失败和恢复已对照源码、配置、Schema 或测试。
  • 教程步骤有可观察结果；参考字段有条件、默认值、限制和生效时机；机制页有 Owner 和验证入口。
  • 文字直接、自然，没有空泛宣传、硬译术语、段落墙、PR 叙事或推理流水账。
  • 示例没有 secret、真实账号、用户数据、本地绝对路径或不可公开的内部地址。
  • 相对链接、标题、代码块、表格和 Mermaid 图可以由 VitePress 构建。
  • 新页面已加入正确导航；页面移动或拆分后没有遗留入站链接。
  • 交付说明如实记录实际运行的命令、结果、未执行项和剩余风险。

至少运行：

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

外部资料只用于学习文档组织和表达方式。可参考 Diátaxis 的文档分类，以及 Write the Docs 入门指南 对读者、安装、使用和贡献路径的建议；Yuxi 的当前行为仍以仓库内事实 Owner 为准。

本项目基于 MIT License 开源，欢迎使用和贡献。

Copyright © 2025-present Yuxi