docs: 统一使用中文结构化子列表

docs/reference/agent-instruction-hygiene.md

@@ -1,16 +1,37 @@
 # Agent 指令治理
 
-本文是长期参考，用于保持自动加载的 Agent 指令文件精简、可导航且稳定。适用于本地和远端 `AGENTS.md`、`CLAUDE.md` 类别名，以及所有自动注入 Agent 上下文的仓库级指令文件。
+- 本文范围：
+
+  - 目标：保持自动加载的 Agent 指令文件精简、可导航且稳定；
+  - 适用对象：本地和远端 `AGENTS.md`、`CLAUDE.md` 类别名；
+  - 扩展范围：所有自动注入 Agent 上下文的仓库级指令文件。
 
 ## 体积预算
 
-`AGENTS.md` 是索引，不是知识库。任何本地或远端 `AGENTS.md` 的硬上限均为 10 KiB，使用 `wc -c AGENTS.md` 按字节计量。
+- 体积定义：
 
-`AGENTS.md` 已超过 10 KiB 时，不得继续追加详细规则。必须先拆分，再只向 `AGENTS.md` 回填一行索引。
+  - `AGENTS.md` 是索引，不是知识库；
+  - 本地或远端 `AGENTS.md` 的硬上限均为 10 KiB；
+  - 使用 `wc -c AGENTS.md` 按字节计量。
 
-修改 `AGENTS.md` 会导致其超过 10 KiB 时，把新内容分流到 skill 或 `docs/reference/*.md`，并保持 `AGENTS.md` 为短索引。
+`AGENTS.md` 已超过 10 KiB 时：
 
-加载或输出 `AGENTS.md` 触发 CLI 输出转储或上下文膨胀时，将其视为可见性缺陷和指令治理缺陷。正确修复是拆分文件，不是提高输出上限或要求 Agent 绕过转储读取。
+- 不得继续追加详细规则；
+- 必须先拆分；
+- 只向 `AGENTS.md` 回填一行索引。
+
+- 修改会导致 `AGENTS.md` 超过 10 KiB 时：
+
+  - 把新内容分流到 skill 或 `docs/reference/*.md`；
+  - 保持 `AGENTS.md` 为短索引。
+
+- 加载或输出 `AGENTS.md` 触发 CLI 输出转储或上下文膨胀时：
+
+  - 将其视为可见性缺陷；
+  - 将其视为指令治理缺陷；
+  - 通过拆分文件修复；
+  - 不得提高输出上限；
+  - 不得要求 Agent 绕过转储读取。
 
 ## AGENTS.md 应包含的内容
 
@@ -22,47 +43,89 @@
 - 常用工作流必须加载的 skill 名称；
 - Secret、破坏性命令、目标工作区和构建禁令的短警告。
 
-不得放入长示例、命令记录、JSON 输出、issue 时间线、架构长文、provider 特定调试日志或一次性事故分析。
+- 禁止内容：
+
+  - 长示例、命令记录或 JSON 输出；
+  - issue 时间线或架构长文；
+  - provider 特定调试日志；
+  - 一次性事故分析。
 
 ## 超出内容的分流位置
 
-拆分 `AGENTS.md` 时按以下顺序分流：
+- 分流顺序：
 
-- 可复用工作流进入 skill `SKILL.md`，例如 `$dad-dev`、`$unidesk-cicd`、`$unidesk-gh`、`$unidesk-trans`、`$unidesk-otel`、`$unidesk-webdev` 或 `$unidesk-ymalops`。
-- 稳定项目约束、工作区规则、架构边界和验收标准进入 `docs/reference/*.md`。
-- CLI 形态、输出样式、路由语法和操作体验进入 `docs/reference/cli.md`，已有更具体参考文档时进入具体文档。
-- 部署治理、固定仓库边界和真相源规则进入 `docs/reference/devops-hygiene.md`。
-- HWLAB 节点/通道规则进入 `docs/reference/hwlab.md` 和目标仓库自身参考文档。
-- AgentRun 真相源和部署通道规则进入 `docs/reference/agentrun.md`。
-- 平台基础设施和 YAML-first 运维进入 `docs/reference/platform-infra.md` 与 `docs/reference/yaml-first-ops.md`。
-- 过程记录、临时发现和带日期调查日志进入 GitHub issue、PR 评论或过程记录；进入长期参考前必须蒸馏。
+  - 可复用工作流进入 skill `SKILL.md`，例如：
+    - `$dad-dev`、`$unidesk-cicd`、`$unidesk-gh`；
+    - `$unidesk-trans`、`$unidesk-otel`、`$unidesk-webdev`；
+    - `$unidesk-ymalops`。
+  - 稳定项目约束、工作区规则、架构边界和验收标准进入 `docs/reference/*.md`。
+  - CLI 相关内容：
+    - 形态、输出样式、路由语法和操作体验进入 `docs/reference/cli.md`；
+    - 已有更具体参考文档时进入具体文档。
+  - 部署治理、固定仓库边界和真相源规则进入 `docs/reference/devops-hygiene.md`。
+  - HWLAB 节点/通道规则进入 `docs/reference/hwlab.md` 和目标仓库自身参考文档。
+  - AgentRun 真相源和部署通道规则进入 `docs/reference/agentrun.md`。
+  - 平台基础设施和 YAML-first 运维：
+    - 进入 `docs/reference/platform-infra.md`；
+    - 同时由 `docs/reference/yaml-first-ops.md` 约束。
+  - 过程材料：
+    - 过程记录、临时发现和带日期调查日志进入 GitHub issue、PR 评论或过程记录；
+    - 进入长期参考前必须蒸馏。
 
-规则既能跨项目复用、又依赖 UniDesk 当前目录或服务时，把可复用流程放入 skill，把 UniDesk 特定路径、通道名和验收边界放入 `docs/reference/*.md`，并双向交叉引用。
+- 规则既能跨项目复用、又依赖 UniDesk 当前目录或服务时：
+
+  - 把可复用流程放入 skill；
+  - 把 UniDesk 特定路径、通道名和验收边界放入 `docs/reference/*.md`；
+  - 双向交叉引用。
 
 ## 拆分步骤
 
-Agent 发现本地或远端 `AGENTS.md` 超过 10 KiB 时：
-
 1. 识别正在修改或扩展的详细领域。
 2. 把详细内容移到权威 skill 或 `docs/reference/*.md`。
 3. 用一条简短索引和权威链接替换原详细章节。
 4. 在 `AGENTS.md` 保留 P0 损害预防警告，但压缩为一行路由规则。
-5. 不得把所有内容移入单个巨大溢出文档。临时迁移记录仅在立即指向各领域承接文档时可用。
-6. 用户未明确要求时，不为体积预算新增测试、保护代码或预检。默认控制方式是文档治理和简洁评审。
+5. 禁止创建巨大溢出文档：
+   - 不得把所有内容移入单个文件；
+   - 临时迁移记录仅在立即指向各领域承接文档时可用。
+6. 用户未明确要求时：
+   - 不为体积预算新增测试、保护代码或预检；
+   - 默认控制方式是文档治理和简洁评审。
 
-大型旧文件按领域逐步拆分。每次编辑都应让涉及领域更精简、引用更清晰。
+- 大型旧文件治理：
+  - 按领域逐步拆分；
+  - 每次编辑都应让涉及领域更精简；
+  - 每次编辑都应让引用更清晰。
 
 ## 交叉引用要求
 
-`AGENTS.md` 中指向外部的每条索引必须注明权威目标。优先使用 `docs/reference/hwlab.md` 等直接路径或 `$unidesk-cicd` 等 skill 名称。
+- 外部索引规则：
 
-不得在 `AGENTS.md`、skill 和长期参考之间重复完整规则。`AGENTS.md` 可以摘要，参考文档拥有细节。两个参考文档冲突时，更新职责更具体的文档，并只保留一个权威版本。
+  - 每条索引必须注明权威目标；
+  - 优先使用 `docs/reference/hwlab.md` 等直接路径；
+  - 也可使用 `$unidesk-cicd` 等 skill 名称。
+
+- 规则归属：
+
+  - 不得在 `AGENTS.md`、skill 和长期参考之间重复完整规则；
+  - `AGENTS.md` 可以保留摘要；
+  - 参考文档拥有细节；
+  - 两个参考文档冲突时，更新职责更具体的文档；
+  - 冲突处理后只保留一个权威版本。
 
 ## Secret 与输出治理
 
-指令文件不得包含 Secret、完整 API key、完整 DSN、base64 载荷、bearer token、SSH 私钥或可直接复用的凭据。
+- 指令文件不得包含：
 
-不得把大段 CLI 输出、OTel trace 转储、JSON 数组或浏览器记录粘贴进 `AGENTS.md`。大输出证明可复用规则时，只保留规则摘要，并链接到拥有完整结论的 issue 或参考文档。
+  - Secret、完整 API key 或完整 DSN；
+  - base64 载荷或 bearer token；
+  - SSH 私钥或可直接复用的凭据。
+
+- 大输出治理：
+
+  - 不得把大段 CLI 输出粘贴进 `AGENTS.md`；
+  - 不得粘贴 OTel trace 转储、JSON 数组或浏览器记录；
+  - 大输出证明可复用规则时，只保留规则摘要；
+  - 摘要必须链接到拥有完整结论的 issue 或参考文档。
 
 ## 当前 UniDesk 路由图
 

docs/reference/docs-governance.md

@@ -1,53 +1,175 @@
 # 文档治理与过程蒸馏
 
-本文是 UniDesk 本机文档治理的长期参考，适用于 `AGENTS.md`、`CLAUDE.md` 类入口文档、`docs/reference/*.md`、skill 文档和过程文档蒸馏。具体任务仍先加载 `$docs-spec`；本文沉淀长期稳定规则和本仓判定标准。
+- 本文适用于：
+
+  - `AGENTS.md`、`CLAUDE.md` 类入口文档；
+  - `docs/reference/*.md`；
+  - skill 文档；
+  - 过程文档蒸馏。
+
+- 使用要求：
+
+  - 具体任务先加载 `$docs-spec`；
+  - 本文只沉淀长期稳定规则和本仓判定标准。
+
+## 中文与单行治理
+
+- 自然语言标题和正文统一使用中文；发现非中文内容时先翻译再继续。
+- 新写内容必须使用中文。
+- 一个自然语言单行不得堆叠多个独立约束、步骤、条件或并列事实。
+- 发现过长单行时立即处理，不等待集中清理。
+- 过长内容一律按语义拆成主项与下级列表；禁止只做自然换行或物理折行来伪装拆分。
+- 命令、路径、URL、代码、协议名、字段名和机器可读单值可以保留原文或长行。
 
 ## 顶级入口
 
-`AGENTS.md` 只作为项目级顶级索引，用于快速定位命令、入口、技能和长期参考文档。它不能承载实现细节、参数说明、长流程、历史排障、日志、JSON、trace dump 或一次性过程记录。
+- `AGENTS.md` 职责：
 
-与 `AGENTS.md` 具有同等作用的入口文档只保留一行 `@AGENTS.md`，避免 `CLAUDE.md`、`AGENTS.md` 或其他入口出现多套口径。
+  - 只作为项目级顶级索引；
+  - 用于快速定位命令、入口、技能和长期参考文档；
+  - 不承载实现细节、参数说明或长流程；
+  - 不承载历史排障、日志、JSON、trace dump 或一次性过程记录。
 
-每个命令或工作流在 `AGENTS.md` 中最多保留一条主索引；需要多个功能点时，用短子列表分别指向对应的 `docs/reference/*.md` 或 skill。子列表只写一句话摘要，不展开背景和用法。
+- 同级入口文档规则：
+  - 与 `AGENTS.md` 具有同等作用的入口文档只保留一行 `@AGENTS.md`；
+  - 避免 `CLAUDE.md`、`AGENTS.md` 或其他入口出现多套口径。
+
+- 命令与工作流索引：
+
+  - 每个命令或工作流最多保留一条主索引；
+  - 多个功能点使用短子列表；
+  - 子列表分别指向对应的 `docs/reference/*.md` 或 skill；
+  - 子列表只写一句话摘要；
+  - 不展开背景和用法。
 
 `AGENTS.md` 的体积、拆分和输出 dump 治理细则见 `docs/reference/agent-instruction-hygiene.md`。
 
 ## 长期参考
 
-`docs/reference/` 只记录长期稳定、可重复复用的入口、前置条件、约束、职责边界和判定标准。不要写日期、一次性执行记录、实测流水账、changelog 式内容或容易过时的临时结论。
+- `docs/reference/` 内容边界：
 
-详细说明优先进入职责明确的独立参考文档，再回到 `AGENTS.md` 维护一句话索引。跨文档重复时，选择或新建唯一权威出处，其他位置只交叉引用。
+  - 只记录长期稳定、可重复复用的入口、前置条件和约束；
+  - 记录职责边界和判定标准；
+  - 不写日期、一次性执行记录或实测流水账；
+  - 不写 changelog 式内容或容易过时的临时结论。
 
-知识更新按四类处理：增加新知识、删除过时知识、修正错误知识、合并重复知识。新旧材料冲突时，以新的稳定结论替换旧结论，并删除或压缩旧说法。
+- 详细说明归属：
 
-`docs/reference/` 不维护 YAML/config 已能表达的业务策略数值、阈值、冷却时间、退避窗口、容量或价格作为第二真相。长期参考只写“数值以 YAML/config 为准”以及同步、渲染、验证入口。
+  - 优先进入职责明确的独立参考文档；
+  - 再回到 `AGENTS.md` 维护一句话索引；
+  - 跨文档重复时，选择或新建唯一权威出处；
+  - 其他位置只交叉引用。
 
-长期参考不得要求为业务策略数值新增合同测试、代码硬范围或 schema 内容校验；配置校验只检查格式、类型、必填项和可渲染性。
+- 知识更新分为：
 
-涉及 skill 的长期参考必须写清该 skill 与当前项目代码、硬件、目录、运行面和判定标准的具体关系。通用安装、CLI 参数、子命令和完整用法直接引用对应 `SKILL.md`，不要在 reference 中复制一份。
+  - 增加新知识；
+  - 删除过时知识；
+  - 修正错误知识；
+  - 合并重复知识。
+
+- 新旧材料冲突时：
+
+  - 以新的稳定结论替换旧结论；
+  - 删除或压缩旧说法。
+
+`docs/reference/` 不维护 YAML/config 已能表达的以下内容作为第二真相：
+
+- 业务策略数值和阈值；
+- 冷却时间和退避窗口；
+- 容量或价格。
+
+- 长期参考只保留：
+
+  - “数值以 YAML/config 为准”；
+  - 同步入口；
+  - 渲染入口；
+  - 验证入口。
+
+- 业务策略数值规则：
+
+  - 不得要求新增合同测试；
+  - 不得增加代码硬范围；
+  - 不得增加 schema 内容校验；
+  - 配置校验只检查格式、类型、必填项和可渲染性。
+
+- 涉及 skill 的长期参考必须写清该 skill 与以下内容的具体关系：
+
+  - 当前项目代码和硬件；
+  - 当前目录和运行面；
+  - 当前判定标准。
+
+- 通用用法归属：
+
+  - 通用安装直接引用对应 `SKILL.md`；
+  - CLI 参数和子命令直接引用对应 `SKILL.md`；
+  - 完整用法直接引用对应 `SKILL.md`；
+  - 不得在 reference 中复制一份。
 
 ## Skill 文档
 
-`SKILL.md` 是短入口和路由表，不承载完整 runbook、历史排障、长命令矩阵或大段背景。内容变长时，拆到同 skill 的 `references/`。
+- `SKILL.md` 是短入口和路由表，不能承载：
 
-拆分后的 reference 必须按职责、生命周期和读取场景组织，例如部署、账号管理、公开暴露、验收、排障、禁止事项分别成文件。禁止把内容重新堆成 `references/full.md`、`all.md`、`guide.md` 或其他变相超级 Markdown。
+  - 完整 runbook；
+  - 历史排障；
+  - 长命令矩阵；
+  - 大段背景；
+  - 内容变长时，拆到同 skill 的 `references/`。
 
-`SKILL.md` 必须明确何时读取哪个 reference，让 agent 按任务加载最小必要文件。单个 reference 继续变长时，继续按职责拆分，并在旧文件保留短索引或迁移说明。
+- reference 拆分规则：
+
+  - 按职责、生命周期和读取场景组织；
+  - 部署、账号管理、公开暴露、验收、排障和禁止事项分别成文件；
+  - 禁止重新堆成 `references/full.md`、`all.md` 或 `guide.md`；
+  - 禁止创建其他变相超级 Markdown。
+
+- reference 路由规则：
+
+  - `SKILL.md` 必须明确何时读取哪个 reference；
+  - Agent 按任务加载最小必要文件；
+  - 单个 reference 继续变长时，继续按职责拆分；
+  - 在旧文件保留短索引或迁移说明。
 
 ## 过程文档蒸馏
 
-过程文档是开发过程中的一手历史资料，通常带有时间戳、阶段性判断和临时结论。蒸馏时不得篡改过程文档本身。
+- 过程文档定义：
+  - 属于开发过程中的一手历史资料；
+  - 通常带有时间戳、阶段性判断和临时结论；
+  - 蒸馏时不得篡改过程文档本身。
+- 蒸馏顺序：
+  - 从旧到新；
+  - 大文件采用滑动窗口；
+  - 读一段就更新一次长期参考；
+  - 不等全部读完再统一整理。
 
-蒸馏顺序从旧到新。大文件采用滑动窗口处理，读一段就更新一次长期参考，不等全部读完再统一整理。
+- 过程结论规则：
 
-新的稳定结论覆盖旧结论。长期参考只简述总体发展过程和关键节点，避免把发展过程写成流水账；越早期的过程越应压缩。
+  - 新的稳定结论覆盖旧结论；
+  - 长期参考只简述总体发展过程和关键节点；
+  - 避免把发展过程写成流水账；
+  - 越早期的过程越应压缩。
 
-重要过程节点可以交叉引用原始过程文档、issue 或 PR，但长期参考必须保留可直接复用的当前规则、边界和验证入口。
+- 重要过程节点：
+  - 可以交叉引用原始过程文档、issue 或 PR；
+  - 长期参考必须保留可直接复用的当前规则、边界和验证入口。
 
 ## 本机工作流
 
-单纯文档、`AGENTS.md`、`docs/reference/*.md`、skill 规则、runbook 和过程文档蒸馏可在当前主 worktree 处理，不需要新建 `.worktree` 或 PR。开始前必须按本仓 P0 规则快进到最新 `origin/master`，并保留并行脏改。
+- 以下工作可在当前主 worktree 处理，不需要新建 `.worktree` 或 PR：
 
-该例外只覆盖文档和规则本身。不得夹带源码、配置、部署、Secret、运行面变更或 issue lifecycle 写操作。
+  - 单纯文档；
+  - `AGENTS.md` 和 `docs/reference/*.md`；
+  - skill 规则和 runbook；
+  - 过程文档蒸馏。
 
-收尾检查以最小语法、链接、grep 和 diff 审核为主。完成后只提交本次文档治理相关文件；若工作区存在并行修改，不得把无关文件加入提交。
+开始前必须按本仓 P0 规则快进到最新 `origin/master`，并保留并行脏改。
+
+- 本机工作流例外边界：
+  - 只覆盖文档和规则本身；
+  - 不得夹带源码、配置、部署或 Secret；
+  - 不得夹带运行面变更或 issue lifecycle 写操作。
+
+- 收尾要求：
+
+  - 以最小语法、链接、grep 和 diff 审核为主；
+  - 只提交本次文档治理相关文件；
+  - 工作区存在并行修改时，不得把无关文件加入提交。