AGENTS.md

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

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

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

层	职责	不属于这里
根 AGENTS.md	每个会话都需要的全局规则（布局/命令/约定），每条 1-3 行并链接归属	故事、示例、任何从归属层重述的内容
packages/AGENTS.md	包级通用规则	根文件已有的全局规则
各包 AGENTS.md	该包特有规则	包级通用规则、全局规则
各包 README	包的用户契约：功能、安装、配置、安全模型、已知限制	JSDoc 重述、构建内部细节
docs/ 长期文档	跨包流程与约定：plugins.md（新插件入桶）、i18n.md（双语契约）、development.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 首段描述同一能力，不残留脚手架占位（如「」）。

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、机翻痕迹或占位符？