dsh-web

# AGENTS.md — 文档标准

本文件定义 dsh-web 的文档结构、写作规则与 i18n 配对契约。
pnpm docs:check（scripts/verify-docs.mjs）强制执行本文件的可机械检查部分。

## 文档分层：一个事实只有一个家

每个事实只在其归属层写一次，其他层用链接引用，不重复展开。

| 层 | 职责 | 不属于这里 |
| --- | --- | --- |
| 根 AGENTS.md | 每个会话都需要的全局规则（布局/命令/约定），每条 1-3 行并链接归属 | 故事、示例、任何从归属层重述的内容 |
| packages/AGENTS.md | 包级通用规则 | 根文件已有的全局规则 |
| 各包 AGENTS.md | 该包特有规则 | 包级通用规则、全局规则 |
| 各包 README | 包的用户契约：功能、安装、配置、安全模型、已知限制 | JSDoc 重述、构建内部细节 |
| docs/ 长期文档 | 跨包流程与约定：architecture.md（架构总览）、plugins.md（新插件入桶）、i18n.md（双语契约）、development.md（开发流程）、telemetry.md（匿名遥测）、publish-prep.md（发布准备）、multi-agent-resources.md（多代理资源纪律） | 一次性任务记录（→ docs/archive/） |
| docs/release-notes/ | 每版冻结的发布说明（vX.Y.Z.md，中文默认 + English 折叠双语，发布管线直接采用，v0.2.6 起） | 未发布的草稿、其他时间戳快照 |
| docs/archive/ | 任务交接、验证快照、一次性记录（冻结历史） | 当前行为描述 |

- **README 必含结构**：功能（What it does / 能力）、安装（Install / 安装）、配置（Config / 配置）、已知限制（Known limitations / 已知限制）。涉及安全的包必须有「安全模型 / Security model」一节。
- **docs/ 只放长期文档**：任务交接、一次性验证记录一律进 docs/archive/，长期文档目录不出现时间戳快照。
- **README 标题层级**：H1 是包名，## 为顶级章节，### 为子节；安装方式的并列选项用 ###，不得用 # 破坏层级。

## 写作规则

- **写当前状态，不写变更历史**：避免「之前/现在/不再/改名为」；变更故事进 commit / PR / docs/archive/。
- **一个物理段落一行**：编辑器软换行，便于 diff 与自动检查。
- **链接必须真实**：相对链接的目标文件必须存在，锚点（#）必须指向真实标题；pnpm docs:check 强制执行。
- **不做装饰性表达**：不用 emoji（全仓禁止），强调用加粗而非通篇大写。
- **包描述与 README 一致**：package.json 的 description 与 README 首段描述同一能力，不残留脚手架占位（如「<edit me>」）。

## i18n 配对契约

- **一份文档一对三文件**：README.md（英文）+ README.zh.md（中文）+ README.i18n.yaml（配对一致性记录），同目录平铺，无 locale 子目录。
- **两种语言同等权威**：中英必须表达同一事实；编辑任一侧必须同 PR 更新另一侧，然后重新记录 README.i18n.yaml 中的 blob hash。
- **语言切换行**：中文文件 H1 后立即 `[English](README.md) | 中文`；英文文件 H1 后 `English | [中文](README.zh.md)`。
- **结构镜像**：标题层级与顺序、列表种类与条数、表格行列数、链接目标、代码块在两侧一一对应（见 docs/i18n.md）。
- **门禁**：pnpm docs:check 校验三件套完整、hash 与当前内容一致、切换行存在、结构签名匹配。编辑任一侧不同步即变红。

## 写作检查清单

- 同一规则是否在多个地方出现？（保留一个家，其余链接）
- 是否叙述了历史/变更？（改为当前状态；历史进 archive）
- 是否有手抄的清单/目录，而源码或生成器才是权威？
- 是否有一个自然段承载多条规则？（拆开或降级到归属层）
- 是否用了 emoji、机翻痕迹或占位符？

More agent context in zhu1090093659/dsh-web

12 other files this repository gives its agents.