本仓库面向人机双读者，所有包 README 均维护英文与简体中文两份，规则见 docs/AGENTS.md。本文件定义配对机制、维护流程与门禁。
一份双语文档是一组三个文件，同目录平铺：
| 文件 | 内容 |
|---|---|
| README.md | 英文版 |
| README.zh.md | 中文版 |
| README.i18n.yaml | 配对一致性记录：两侧的 git blob hash |
README.i18n.yaml 记录两侧文件在「最后确认一致」时点的内容 hash（git
hash-object，内容寻址，不依赖提交）。编辑任一侧后，配对记录与另一侧即
失同步，pnpm docs:check 变红。
- 编辑任一侧（中英同等权威，先写哪侧都行）。
- 同一次改动内把另一侧同步成同一事实，保持结构镜像。
- 确认两侧表达一致后重录配对记录：
pnpm docs:write-pair <包目录名> # 如 dsh-ssh 或 xp重录产生的 yaml diff 就是「我确认了这次一致性」的可审查动作。
两侧除语言切换行与正文文本外，结构必须一一对应：
- 标题层级与顺序一致；
- 代码块（围栏与内容）一一对应；
- 表格行数与列数一致；
- 列表种类与条目数一致；
- 链接目标一致（切换行除外）。
语言切换行：英文 H1 后 English | [中文](README.zh.md)；中文 H1 后
[English](README.md) | 中文。
pnpm docs:check（scripts/verify-docs.mjs）机械校验：三件套完整、记录
hash 与当前内容一致、切换行存在、结构签名匹配。门禁只证明「记录时两侧
一致」，不判断翻译质量——忠实与通顺由评审负责。
- 覆盖：packages/ 下所有插件包与皮肤包的 README；
- 不含：docs/archive/ 冻结历史、构建产物、第三方代码；
- 新增包必须自带完整三件套（
scripts/dsh-plugin-new已生成骨架）。