universal-dev-standards 6.14.0-beta.2 → 6.14.0-beta.4

package/bundled/locales/COVERAGE.md

@@ -3,9 +3,9 @@
 > Auto-generated by `scripts/generate-locale-coverage.mjs` on 2026-07-16.
 > Do not edit manually — re-run the script.
 
-> **Canonical**: `skills/` (55) + `core/` (149). **Locales tracked**: `zh-CN`, `zh-TW`.
+> **Canonical**: `skills/` (56) + `core/` (149). **Locales tracked**: `zh-CN`, `zh-TW`.
 
-## Skills (55 canonical)
+## Skills (56 canonical)
 
 | Skill | zh-CN | zh-TW |
 | :-- | :-: | :-: |
@@ -24,6 +24,7 @@
 | ci-cd-assistant | :white_check_mark: 1.0.0 | :white_check_mark: 1.0.0 |
 | code-review-assistant | :white_check_mark: 1.0.0 | :white_check_mark: 1.0.0 |
 | commit-standards | :white_check_mark: 1.0.0 | :white_check_mark: 1.0.0 |
+| comprehension-ladder | :white_check_mark: 1.0.0 | :white_check_mark: 1.0.0 |
 | contract-test-assistant | :white_check_mark: 1.0.0 | :white_check_mark: 1.0.0 |
 | database-assistant | :white_check_mark: 1.0.0 | :white_check_mark: 1.0.0 |
 | deploy-assistant | :white_check_mark: 1.0.0 | :white_check_mark: 1.0.0 |
@@ -65,8 +66,8 @@
 | test-coverage-assistant | :white_check_mark: 1.1.0 | :white_check_mark: 1.1.0 |
 | testing-guide | :white_check_mark: 1.2.0 | :white_check_mark: 1.2.0 |
 
-**zh-CN skills coverage**: 55/55 (100%)
-**zh-TW skills coverage**: 55/55 (100%)
+**zh-CN skills coverage**: 56/56 (100%)
+**zh-TW skills coverage**: 56/56 (100%)
 
 ## Standards (`core/` — 149 canonical)
 

package/bundled/locales/zh-CN/CHANGELOG.md

@@ -1,8 +1,8 @@
 ---
 source: ../../CHANGELOG.md
-source_version: 6.14.0-beta.2
-translation_version: 6.14.0-beta.2
-last_synced: 2026-09-30
+source_version: 6.14.0-beta.4
+translation_version: 6.14.0-beta.4
+last_synced: 2026-10-06
 status: current
 ---
 
@@ -17,6 +17,47 @@ status: current
 
 ## [Unreleased]
 
+## [6.14.0-beta.4] - 2026-10-06
+
+> **测试版**——以 `npm install -g universal-dev-standards@beta` 安装。要测什么、如何退回正式版：[docs/PRE-RELEASE.md](../../docs/PRE-RELEASE.md)。
+>
+> **行为改变：**`uds check --standard checkin-standards` 在 lint 或测试失败时会失败；非 Node 项目的原生 pre-commit hook 现在能拦住提交。见下方 Fixed 的相关条目。
+
+### 修复
+- **`extensions/` 现在放进 npm 包，`uds init`、`uds update` 与 reconciler 只从包内安装扩展文件——三者都不再从 GitHub 下载。** 6.13.1 版包里 `extensions/` 下的 7 个文件（语言风格规范、框架模式、繁中与简中语系包）一个都没有，所以 `uds init --lang csharp`、`--lang php`、`--framework fat-free`、`--locale zh-tw`／`zh-cn` 安装时是去 GitHub `main` 下载。后果有两个：离线或公司内网装不了这些扩展；而且拿到的是 `main` 当天的内容，不是你所装版本对应的那个文件。同一个后备也把缺少的 `zh-cn.md` 藏了好几个月。现在 `cli/scripts/prepack.mjs` 会把整个目录打包；包内容一致性检查会逐文件、逐字节比对 `extensions/` 与包（以前只比对 `.ai.yaml` 标准，所以一个扩展文件都没有的包也会显示“bundle parity holds”）；声明的扩展文件若不在包内，安装会**失败并指出该文件**——不下载、也不静默跳过。**谁会看到差别：**从 npm 安装的人多拿到 7 个文件（约 152 KB），且这些文件不再发出任何网络请求；`uds update` 也从包内更新 `manifest.extensions` 的条目。**没有改的：**其他在本地缺文件时仍会尝试 GitHub 的地方（标准、选项、集成文件、技能），以及 `uds check --diff`——它仍会从 GitHub `main` 抓任何追踪文件（含扩展文件）的原稿来比对。这份清单列在规格里，本次不动。新增的测试会运行 `npm pack`、把压缩包装进一次性目录、封锁并记录网络，对已安装包声明的每一个扩展选项运行 `uds init`，再逐字节读回每个已安装的文件；第二个测试从包中移除一个声明的文件，要求安装以该文件的名称失败，且没有任何下载尝试。落实 dev-platform XSPEC-452 的 R1、R2、R3。
+- **`uds init --locale` 不区分大小写，且不支持的语言会明确提示**：`--locale zh-CN` 以前会安装英文并报告成功，现在会安装简体中文。不支持的值（例如 `fr`）仍改用英文安装，但会打印警告，不再静默。（dev-platform XSPEC-451 后续）
+
+- **行为改变——`uds check --standard checkin-standards` 在你的 lint 或测试失败时现在会失败；它以前会说“通过”。** 该验证器原本是 `(npm test --if-present || echo "No test script")`。`--if-present` 本来就处理“没有测试脚本”的情况；`|| echo` 因此只做了一件事：把失败的 `npm test` 或 `npm run lint` 变成 exit 0。UDS 自己的 `test-governance` 标准要求闸门 fail-closed，它自己发布的检查却没做到。现在：lint 或测试脚本失败会返回非 0，并指出是哪一个（`FAILED: npm run test exited with 1`，后面接该脚本自己的输出）；真的没有该脚本不算失败，并且**只有这时**才打印 `No lint script`／`No test script`；`npm init` 为 `test` 写的默认占位（`echo "Error: no test specified" && exit 1`）视为没有；没有 `package.json` 的项目通过，并打印 lint 与测试**没有**被执行；`package.json` 存在却无法解析会失败，不会被当成“没有脚本”。缺 `CHANGELOG.md` 仍只是提示。**谁会看到差别：**pre-commit hook 执行 `check --standard checkin-standards` 的项目（UDS 在 2026-02-04 至 2026-03-04 写的 hook，`uds update` 会把它保留成区块的参数），以及在 CI 或脚本里执行该命令的人。过去带着失败的测试也能提交成功的 commit，现在会被拦下——这正是目的。**怎么处理：**执行 `npm test`／`npm run lint`，修掉它们报告的问题。没有测试的项目不受影响。全新的 `uds init` 所写的 hook 执行的是不带参数的 `uds check`，它不评估这个验证器；它该不该评估是另一个决定，本次不变。验证器现在会执行 `node`，凡是在运行 `uds` CLI 的项目本来就有。
+- **`pipeline-security-gates` 验证器不再在没有任何 pipeline 提到安全闸门时通过。**它把 `grep` 接到 `head -1`，再以 `|| echo 'no-ci-pipeline'` 兜底；`head` 永远返回 0，所以兜底从不执行，这个检查不可能失败。现在改用 `grep -q`，除非 `.github/workflows/`、`.gitlab-ci.yml` 或 `Jenkinsfile` 提到 `secrets`、`sast`、`sca` 或 `dast`，否则返回非 0。只有 `uds check --standard pipeline-security-gates` 会执行它。
+- **`uds init` 为非 Node 项目写的原生 `.git/hooks/pre-commit` 现在真的能拦下 commit。**它原本把每个 linter 都写成 `... 2>/dev/null || true`，把 `uds check 2>/dev/null || true` 也是，最后打印“Pre-commit checks passed”——什么都拦不了，还把自己的错误藏起来。现在：已安装的 linter（`ruff`、`go vet`、`cargo clippy`）失败会拦下 commit，没安装的 linter 则跳过；UDS 检查改用与 husky hook 相同的标记区块，所以它的退出码会拦下 commit，而找不到 `universal-dev-standards` CLI 时会说明如何安装并拦下，不再静默跳过。`uds uninstall` 会整段移除该区块，连你改过的脚本也一样。**磁盘上既有的 hook 维持原样**——UDS 无法证明一个被改过的文件是自己写的，这一项也没有随本次变更附上迁移。
+- **`uds init --locale zh-cn` 现在可用。它以前会失败并把整个安装回滚。** 安装程序声明了 `zh-cn`，并会复制 `extensions/locales/zh-cn.md`，但这个文件不存在（只有 `zh-tw.md`），所以安装以 `extensions/locales/zh-cn.md: File not available` 收场，并移除它装过的所有东西——没有人能用简体中文安装 UDS，而且没有任何测试用简体中文跑过安装，所以一直坏着。现在这个文件存在了：它是以大陆通行术语写成的简体中文语系包（不是把繁体版逐字转换——它的术语表写“Performance → 性能”，繁体版写的正好相反）。它以 `zh-cn-locale` 登记在 `zh-tw-locale` 旁边。新增的测试对安装程序声明的每一个语系实际运行真正的 `uds init`（列表从安装程序读出，不写在测试里），并读回语系包、manifest 与已安装的技能；有语系声明了却没有对应文件，测试就会变红并指出是哪个语系。理解阶梯的安装测试现在也让 zh-CN 走 `uds init`。**npm 安装的注意事项：**写下这一条时 `extensions/` 不在 npm 包里，语系包是安装时从 GitHub（`main`）下载的；现在它已放进包内（见上方 `extensions/` 那一条）。落实 dev-platform XSPEC-451 的 R1、R2。
+
+### 新增
+
+- **`ai-response-navigation` 1.3.0 → 1.4.0——R12 受控语言，其中一条为必须。** 把文字简化会让它更好读，而最好读的句子是肯定的句子，所以「简化」会朝肯定的方向漂移：「可能」变成「是」。R12 把答案分成两半。**12.1 属必须**：为非原作者的读者缩短、简化、改写或翻译文字时，要保留写作者的不确定语气（might、could、probably、可能、推断、尚未确认），不可把不确定的论断改成确定的，也不可加入原文没说的事实。只有这一部分的失败会让读者相信不真实的事，而且不需要校准：检查就是拿改写前后比对，任何语言都做得到。**12.2 属可选**，理由已写进标准：以该语言自己的单位计句长（起始范围，按语言校准）、同物同名、主动语态、一步一动作、少用分号、数字带单位。R10 现在指向 R12。
+  - **不附英文词典，并在标准里明说。** 这些原则取自 ASD-STE100，但它的核可词表与时态限制依赖英文，不适用于中文或其他非英文文字。标准只取原则、不附任何词表，并警告：以空白分词的计数器会把一整段中文看成一个词，永远通过。
+  - **一组中文示例**：同一段文字的原文、约 80%、严格三个版本，全部保留不确定语气，外加第四个更短却错误的改写（把「可能」改成直接陈述的原因、把「尚未复现」改成「已确认」）。同步 zh-TW 与 zh-CN、两份 `.ai.yaml`，以及一个读取实际出货文件的测试——必须条款被削弱或删除时它会变红。
+- **新增技能 `comprehension-ladder`（`/comprehend`）1.0.0 — 把一段难懂的 AI 输出换成较好懂的形式，而且不改变事实。** 技能先从原文建立一份大纲，再从大纲做出最多三阶：受控文字、Mermaid 图、单文件 HTML 解说页（可离线打开，不从网络加载任何东西）。没有视频阶。**三条防护为必须**，各附正例与反例：不加原文没有的事实、保留每一个不确定语气（「可能」仍是「可能」）、每一项都附对应原文的位置与「没涵盖」注记。技能本身依 [ai-response-navigation](../../core/ai-response-navigation.md) 第 12 条（受控语言）写成，防护 G2 就是 12.1 条。
+  - **尚未证明有帮助。** `skills/comprehension-ladder/eval-cases.md` 有 5 段为此撰写的原文，各附理解题与标准答案，并附一套跑法，会产出两个数字：前后的答对率，以及防护违反次数。实跑需要模型调用，目前还没做。做完之前，技能不宣称有效。
+  - 提供 `zh-TW` 与 `zh-CN` 版本，并登记于 registry、manifest、`llms.txt` 与技能索引。有一支测试会在抛弃式项目里运行真正的 `uds init`，读回安装后的技能：三条防护都在、且标为必须，HTML 阶禁止外部资源，也没有视频阶。
+
+## [6.14.0-beta.3] - 2026-09-30
+
+> **测试版**——以 `npm install -g universal-dev-standards@beta` 安装。要测什么、如何退回正式版：[docs/PRE-RELEASE.md](../../docs/PRE-RELEASE.md)。
+>
+> **既有采用者：请执行一次 `uds update`。**旧版 `uds init` 写进 pre-commit hook 的是单行 `npx uds check`，它可能请 npm 去拿一个叫 `uds`、但不是本项目的软件包。新安装不再写这一行，而 `uds update` 会替换既有 `.husky/pre-commit` 里 UDS 自己写的那一行。另外：`uds uninstall` 只移除能证明是 UDS 写的东西（早期 UDS 安装的项目会保留一部分文件并说明原因），`uds open-work next-action` 读得懂写成表格列的下一步。
+
+### 变更
+
+- **`uds open-work next-action` 现在读得懂写成 Markdown 表格列的“下一步”，不再只认小节标题与行内标签。** 表头在“下一步”词汇内的列（`Next action`、`Next step`、`下一步`、`下一動`，以及新增的 `回來要做什麼`）每一行都会被读取，报告附带行号与该行第一格内容，便于定位。词汇仍然只有一份：标题、行内标签与表头都读同一份。放在引用块（`> | … |`）里的表格现在看得见；代码片段内或反斜杠之后的 `|` 不再切开单元格。列数与表头不一致的行会列为 `UNDECIDABLE`（无法判定），不会被当成空白；别处没有违反时退出码为 2，因为干净的结果只涵盖了字段的一部分。空白、`—`、`-` 的单元格只计数、不评估，也不算 OWT-019 违反。此事是在真实工作记录上量测 DEC-122 H2 基准时发现的：80 行中有 32 行的列数与表头不同。`回來要做什麼` 是该工作记录实际使用的表头（其文字说明把该列叫作 下一動），属未校准判断（OWT-016）。检查器自身的突变测试新增八个表格突变，原有十七个仍然转红。
+
+### 修复
+
+- **`uds uninstall` 不再留下 UDS 自己写的文件，也不再移除它无法证明是 UDS 写的东西。** 走过 `init` → `update --with-hooks` → `uninstall -y` 之后，它报告“已移除 5、已跳过 1、错误 0”，却留下 `scripts/hooks/` 下的 15 个 hook 脚本、一个空的 `.codex/`、一份生成标头仍指向已删除 `.standards/` 的 AGENTS.md，以及 `uds init` 写入的 `.git/hooks/pre-commit` 脚本主体。现在的规则是：整个文件只有在 manifest 记录了“UDS 写的”（`installedArtifacts`，由 `init` 与 `update --with-hooks` 写入）**并且**内容仍与记录的哈希相符时才会删除。其他一律保留，并在输出中说明原因（`kept: modified since UDS wrote it`、`kept: no install record — ...`）。文件夹只有在 UDS 创建且现已为空时才移除；采用者自己的 `scripts/hooks/*.mjs`、`.agents/rules/*` 与 hook 条目都会保留。由旧版 UDS 安装的项目没有记录，其脚本、AGENTS.md 生成文字与原生 pre-commit 主体会被保留并说明，而不是猜测。每一行“已移除”现在都对应一次真实的删除或修改，带着错误结束的运行也会以非 0 结束。
+- **`uds uninstall` 在没有人能回答时不再画出提示或抛出错误堆栈，做不了事时也不再以 0 结束。** `--dry-run` 从不提示（它不写任何东西），并预览所有类别。没有 `--yes` 又没有终端时，实际运行会以退出码 2 拒绝，而不是假定“是”；提示被关闭时退出码为 130；项目未初始化时退出码为 1。
+- **`uds init --with-hooks` 在 Windows 上不再打印 `'chmod' is not recognized`。** pre-commit hook 原本用 try/catch 包住的 `execSync("chmod +x ...")` 赋予执行权限；catch 对代码隐藏了失败，但 `execSync` 已先把 cmd.exe 的错误送到终端。现在改用 `fs.chmodSync`，并在没有执行位的 Windows 上跳过此步骤。
+- **安全性：`uds init` 写入的 pre-commit hook 不再向 npm 要一个叫 `uds`、但不是本项目的包。** 该 hook 原本是单行 `npx uds check`。`npx` 先找 `node_modules/.bin` 与 `PATH`，两处都没有才去 npm registry，而 registry 上的 `uds` 是不相干的项目（维护者 wizawu、`github.com/wizawu/uds`、v0.3.6、2022 年后未更新、目前没有 `bin`）。装了 UDS 的机器不受影响；没装的 clone 则会用名称去抓陌生人的包——目前无害只是因为该包*尚*无可执行文件，对方一旦发布带 `uds` bin 的版本，每位采用者的每次 commit 都会执行它。`--no-install` 不是解法：用会记录每个请求的本机 registry 实测（npm 10.9.9、11.20.0、12.1.0，三者一致），`npx --no-install uds` 仍会发出 `GET /uds`，而 `npx --no-install --package=universal-dev-standards uds` 完全找不到全局安装。hook 现在两者都不用：它在项目的 `node_modules/.bin`、再到 `PATH` 找 `universal-dev-standards`（包本名，只有本项目能发布）并执行 `check`；两处都找不到时打印该装什么并以非 0 退出——不跳过检查、不下载任何东西，而且即使采用者自己的命令排在后面，检查失败也会拦下 commit。`uds uninstall` 依标记整块移除新写法。给人看的文字同样修正：生成的 `CLAUDE.md`/`AGENTS.md` 区块内的警告行与 hook 提示改写为 `npx universal-dev-standards init` / `update`（警告行多了几个 token，所以 `scripts/prompt-footprint-baseline.json` 依实测值各调高 3–6）。**既有采用者：**`uds update`（除了 `--skills`、`--commands`、`--integrations-only`、`--standards-only` 与 `--rollback` 之外的所有模式，以及 `--with-hooks`；`--plan` 只报告不写入）会替换 `.husky/pre-commit` 中 UDS 自己写的那一行——只认 UDS 曾生成过的两种确切写法（`npx uds check`，以及较早的 `npx uds check --standard checkin-standards`），且必须紧接在 `# UDS Standard Check` 标记下方；你自己写或改过的行不会被动，并会连同行号报告。此步骤在“已是最新版本”的提前返回**之前**执行，所以标准已是最新的采用者也会被处理。`uds check` 现在会警告仍使用裸名称的 hook。新增一个测试遍历 `npm pack` 出货的全部内容，只要有字符串以包运行器（npx、bunx、pnpm dlx、yarn dlx、npm exec）执行裸名称 `uds` 就会失败；非 Node 项目的原生 hook（`uds check`，只从 `PATH` 解析、不经 registry）不受影响，保持原样。
+
 ## [6.14.0-beta.2] - 2026-09-30
 
 > **测试版**——以 `npm install -g universal-dev-standards@beta` 安装。要测什么、如何退回正式版：[docs/PRE-RELEASE.md](../../docs/PRE-RELEASE.md)。

package/bundled/locales/zh-CN/README.md

@@ -15,7 +15,7 @@ status: current
 
 > **语言**: [English](../../README.md) | [繁體中文](../zh-TW/README.md) | 简体中文
 
-**版本**: 6.14.0-beta.2 (Pre-release) | **发布日期**: 2026-09-30 | **授权**: [双重授权](../../LICENSE) (CC BY 4.0 + MIT)
+**版本**: 6.14.0-beta.4 (Pre-release) | **发布日期**: 2026-10-06 | **授权**: [双重授权](../../LICENSE) (CC BY 4.0 + MIT)
 
 语言无关、框架无关的软件项目文档标准。通过 AI 原生工作流，确保不同技术栈之间的一致性、质量和可维护性。
 
@@ -77,7 +77,7 @@ npx universal-dev-standards init
 | 类别 | 数量 | 说明 |
 |----------|-------|-------------|
 | **核心标准** | 153 | 通用开发准则 |
-| **AI Skills** | 55 | 互动式技能 |
+| **AI Skills** | 56 | 互动式技能 |
 | **斜线命令** | 51 | 快速操作 |
 | **CLI 命令** | 24 | 项目设置与维护 |
 <!-- UDS_STATS_TABLE_END -->

package/bundled/locales/zh-CN/SECURITY.md

@@ -13,7 +13,7 @@ status: current
 <!-- UDS_SUPPORTED_VERSIONS_START -->
 | 版本 | 支持状态 |
 |------|--------|
-| 6.14.0-beta.2 | ✅ 预发布版本 |
+| 6.14.0-beta.4 | ✅ 预发布版本 |
 | 6.13.1 | ✅ 最新正式版 |
 | < 6.0.0 | ❌ 已终止支持 |
 <!-- UDS_SUPPORTED_VERSIONS_END -->

package/bundled/locales/zh-CN/core/ai-response-navigation.md

@@ -1,8 +1,8 @@
 ---
 source: ../../../core/ai-response-navigation.md
-source_version: 1.3.0
-translation_version: 1.3.0
-last_synced: 2026-08-17
+source_version: 1.4.0
+translation_version: 1.4.0
+last_synced: 2026-10-05
 status: current
 ---
 
@@ -10,8 +10,8 @@ status: current
 
 > **语言**: [English](../../../core/ai-response-navigation.md) | [繁體中文](../../zh-TW/core/ai-response-navigation.md) | 简体中文
 
-**版本**: 1.3.0
-**最后更新**: 2026-08-17
+**版本**: 1.4.0
+**最后更新**: 2026-10-05
 **适用范围**: 所有使用 AI 辅助开发的项目
 **范围**: universal
 **行业标准**: 无（新兴 AI 工具实践）
@@ -27,10 +27,13 @@ status: current
 
 **解决方案**：在每个实质性 AI 响应结尾附加标准化的「导航区块」，包含情境模板、推荐标记和弹性选项数量。
 
-**范围注记（v1.2.0，v1.3.0 扩充）**：规则 1–6 管的是答案**之后**要附什么。
-规则 7–11 **全部属可选**，管的是答案本身：先讲发现（R7）、每轮重述进度（R8）、不要开场白（R9）、
-白话是主语（R10）、每个选项都要带自己的利弊而非只有推荐项有（R11）。新增的理由是——
-一个响应可以满足规则 1–6 的每一条，同时把结论埋起来；
+**范围注记（v1.2.0，v1.3.0、v1.4.0 扩充）**：规则 1–6 管的是答案**之后**要附什么。
+规则 7–12 管的是答案本身：先讲发现（R7）、每轮重述进度（R8）、不要开场白（R9）、
+白话是主语（R10）、每个选项都要带自己的利弊而非只有推荐项有（R11）、受控语言（R12）。
+规则 7–11 **属可选**。**规则 12 是唯一的例外，而且只有一部分**：其中「简化后的文字要保留写作者的不确定语气」
+这一条**属必须**，其余部分属可选。新增的理由是——
+一个响应可以满足规则 1–6 的每一条，同时把结论埋起来、用只有作者持有的词汇讲它、列出读者还得自己比较的选项，
+或是靠「比证据更肯定」来变得好读；
 **而找不到答案的读者，不会因为结尾有一个正确的导航区块被告知下一步而得到帮助。**
 
 ---
@@ -109,11 +112,13 @@ status: current
 
 ---
 
-## 导航之前的那个答案（规则 7–11，可选）
+## 导航之前的那个答案（规则 7–12）
 
 > **规则 7–9 借鉴自**：[`ayghri/i-have-adhd`](https://github.com/ayghri/i-have-adhd)（MIT），十条中取三条。
 > **规则 10–11 于 1.3.0 新增**，来源不同——用户在同一次工作会话中两度指出，
 > 一个正确且完整的回答读不懂。当时规则 7–9 已经出货且正在被遵守。
+> **规则 12 于 1.4.0 新增**，来源又不同：一则公开的建议——请 LLM 写到「大约达到 ASD-STE100 的 80%」
+> （ASD-STE100 是技术文档用的受控英文标准）。只取它的原则；它的英文词典与时态规则不取（见规则 12）。
 > 其余七条删去：两条已被上方规则 1–2 涵盖，五条与本标准冲突
 > （它的「不要 recap／不要结语」与规则 1 的导航区块直接矛盾；它的「列表上限 5 项」
 > 会截断证据表格与遍历分母）或与 [estimation-standards](estimation-standards.md) 重复。
@@ -122,8 +127,9 @@ status: current
 一个响应可以把结论埋在一整面证据底下，只要结尾附上正确的导航区块，
 它仍然满足本标准的每一条。**找不到答案的读者，不会因为被告知下一步而得到帮助。**
 
-**这五条是可选的**，语义同规则 6：采用项目不必启用，既有 skill 也不需回头补。
-项目**可以**在自己的配置中把任一条提升为必须。**不可选的是它们必须有精确的触发条件**——
+**规则 7–11 是可选的**，语义同规则 6：采用项目不必启用，既有 skill 也不需回头补。
+项目**可以**在自己的配置中把任一条提升为必须。**规则 12 有一条必须（12.1）**，其余（12.2）可选；
+为什么这样分，规则内部有论证。**任何一条都不可选的是它们必须有精确的触发条件**——
 一条松到永远不会启动的规则，与没有这条规则无从分辨。
 
 ### 规则 7：先讲发现，不要先讲过程（可选）
@@ -181,6 +187,9 @@ status: current
 **为什么它与 R7 是两条**：R7 规范的是**先讲发现再给证据**的顺序。R10 规范的是**语域**——
 一个响应可以先讲发现，却仍然用只有作者持有的词汇讲那个发现。两者都让读者无法行动，但它们是不同的失效。
 
+**白话不可以拿肯定语气来换。** 把说明改成读者的话就是一次改写，而改写正是「可能」悄悄变成「是」的地方。
+当 R10 用在写作者原本就有保留的论断上，由[规则 12](#规则-12受控语言部分必须) 的 12.1（必须）管：不确定语气要留着。
+
 ### 规则 11：每个选项都要带自己的利弊（可选）
 
 **触发条件**：要求读者在两个以上做法之间选择的响应。
@@ -204,6 +213,93 @@ status: current
 
 **与规则 4 相辅**：选项数维持在 1–5。利弊让每个选项读起来更花力气，所以这条规则让规则 4 的上限**更**要紧，不是更不要紧。
 
+### 规则 12：受控语言（部分必须）
+
+**触发条件**：为「不是原作者」的读者撰写、改写、缩短、简化或翻译文字——典型是一位非专业的读者，要靠这段文字做判断或审批。
+
+受控语言（用变化换可预测性的写作规则）让文字更好读。它有一个已知的失败方式：最好读的句子是肯定的句子，
+所以「简化」会朝肯定的方向漂移。本规则取受控写作的原则，并对这个漂移设一道硬性的止损。
+
+#### 12.1 简化后的文字要保留不确定语气（必须）
+
+不确定语气是一个告诉读者「这个论断可以信到什么程度」的词：*可能、推断、大概、尚未确认*——
+*might、could、probably、appears to、not yet confirmed*。它是信息，不是赘词。
+
+缩短、简化、改写或翻译时：
+
+- **不可把不确定的论断改成确定的。** 原文说「可能」，结果就说「可能」（或结果语言里对等的说法）。
+- **不可为了省字而删掉不确定语气。** 目标是更短的句子；更肯定的句子不被允许。
+- **不可加入原文没说的事实**——编出来的原因、编出来的「已确认」，是同一种失败的另一个样子。
+- 只有在论断之后**已经被验证**时，不确定语气才可以拿掉；而且要由验证（查了什么、结果是什么）取代它的位置。
+  只删掉不确定语气，不算验证。
+
+**为什么只有这一条是必须的**：只有它的失败会让读者**相信不真实的事**，而不只是让文字更难读。
+它也不需要校准——检查就是拿改写前后两份文字比对，人或模型在任何语言都做得到；
+而下面每一个阈值都取决于语言与读者。
+
+#### 12.2 白话写作原则（可选）
+
+读者是非专业人士时使用。它们与语言无关：每一条都用该语言自己的单位来表达，不附任何词表。
+
+| 原则 | 要求什么 |
+|------|----------|
+| **句子短，以该语言自己的单位计** | 一句一个意思。**起始范围**，不是上限：英文大约 15–25 个词，中文大约 25–40 个字。远超过范围是「该拆句」的信号，不是要计数的缺陷。按语言与读者校准 |
+| **同一个东西只用一个名称** | 每个东西选定一个名称，全文都用它。不要为了文采换说法：读者看到第二个名称，会以为是第二个东西 |
+| **主语明确、主动语态** | 说清楚谁做了什么。施事者不明或不重要时，才用被动 |
+| **一步一动作** | 流程是编号列表，每项一个动作，不是一段文字 |
+| **少用分号** | 分号把读者必须同时记住的两个意思接在一起。拆成两句或一份列表 |
+| **数字带单位** | 「30 秒」「3 个文件」「NT$1,200」——不要只写「30」 |
+
+**为什么是可选**：上面的范围只是起始点，**没有**对照读者实际理解度校准过，也没有检查器在执行。
+一条**必须**的规则若附带没人能验证的阈值，会产生机械式的遵守——句子被拆到不再像句子——
+而专家读者可能反而更适合比较密的文字。这些原则是写作者凭判断使用的指引；12.1 才是不会弯的那一部分。
+
+#### 本规则不取 ASD-STE100 的什么
+
+ASD-STE100 的**核可词典**（每个核可的英文单词只有一个意思，并有一份封闭的允许词表）与它的**时态限制**，
+都依赖英文这个语言。它们**不适用于中文**或其他非英文文字，本标准**不附任何形式的词表**。
+只取 12.2 的原则，并改写成每一条都能在任何语言使用。
+
+同理，不要用「以空白或 ASCII 字符分词」的计数器去衡量非英文文字：它把一整段中文看成一个「词」，
+不论多长都通过。一把在某个语言上永远是绿灯的量尺，在那个语言上什么也没量到。
+
+#### 示例：同一段文字、三种改写，以及一个不被允许的改写
+
+示例刻意用中文：本规则与语言无关，而中文正是只靠英文做法行不通的地方。三个有效版本都保留不确定语气
+「可能」、「推断」、「尚未」，且没有加入原文没有的事实。
+
+**原文**
+
+```text
+经过检查，登录页面在高流量时段响应变慢，这个问题可能是数据库连接池被耗尽所造成的，我们推断是因为上周的改版新增了一个会长时间占用连接的查询；目前尚未在测试环境复现，所以修复后的效果还需要被确认，建议在确认之前先不要对外宣布已经解决。
+```
+
+**约 80%**——句子较短，读起来仍像一段文字
+
+```text
+登录页面在高流量时段响应变慢。原因可能是数据库连接池被耗尽。我们推断，上周改版新增了一个查询，它会长时间占用连接。这一点尚未在测试环境复现，修复后有没有效，也还没确认。确认之前，建议先不要对外宣布已经解决。
+```
+
+**严格**——一行一个意思、加标签、保留不确定语气
+
+```text
+登录页面在高流量时段响应变慢。
+1. 原因：可能是数据库连接池被耗尽。
+2. 推断：上周改版新增了一个查询，这个查询可能长时间占用连接。
+3. 状态：尚未在测试环境复现。
+4. 修复效果：尚未确认。
+5. 建议：确认之前，不要对外宣布已解决。
+```
+
+**不是有效的改写**——最短，而且是错的
+
+```text
+登录页面变慢，原因是数据库连接池被耗尽，已确认由上周改版造成。
+```
+
+最后这一版最短、也最好读，却两度违反 12.1：「可能」变成直接陈述的原因，「尚未复现」变成「已确认」，
+而原文从没说过这件事。读者若凭它批准一个修复，就是被给了一件不真实的事。
+
 ---
 
 ## 情境模板
@@ -398,6 +494,7 @@ AI 需要用户做出选择或提供信息时使用。
 | R9 | *（可选）* 不要开场白。结语仍为必须——见 R1 |
 | R10 | *（可选）* 白话是主语；标识符放在论断之后当佐证 |
 | R11 | *（可选）* 每个选项都要说明换到什么、代价是什么——不只推荐那一个 |
+| R12 | **12.1 *（必须）***：简化、缩短或翻译时，保留不确定语气——不可把「可能」改成「是」。12.2 *（可选）*：句子短（以该语言自己的单位计）、同物同名、主动语态、一步一动作、少用分号、数字带单位。不附英文词典——它无法移到其他语言 |
 
 | 豁免 | 不豁免 |
 |------|--------|
@@ -421,6 +518,7 @@ AI 需要用户做出选择或提供信息时使用。
 
 | 版本 | 日期 | 变更 |
 |------|------|------|
+| 1.4.0 | 2026-10-05 | 新增 R12 受控语言（语言中立）。一条必须（12.1：简化后的文字要保留写作者的不确定语气——「可能」不会变成「是」、也不新增原文没有的事实）；其余（12.2：以该语言自己的单位计句长、同物同名、主动语态、一步一动作、少用分号、数字带单位）属可选，理由已写进标准。取 ASD-STE100 的原则、不取它的英文词典与时态规则，并在标准里明说。附一组中文改写对照（三种严格度），外加一个更短却错误的改写。R10 现在指向 R12，因为把论断改成白话就是一次改写，而改写正是不确定语气流失的地方 |
 | 1.3.0 | 2026-08-17 | 新增可选规则 R10–R11。R10 管语域:白话是句子的主语、标识符当佐证——与 R7 不同,R7 管的是「先发现后证据」的顺序,而一个响应可以先讲发现却仍用只有作者持有的词汇讲它。R11 把规则 2 从推荐选项扩及全部:只论证推荐项的清单等于把比较丢回给读者,而没标代价的选项读起来像没有代价 |
 | 1.2.0 | 2026-08-17 | 新增可选规则 R7–R9，管答案本身（先讲发现、重述进度、不要开场白）。借鉴自 `ayghri/i-have-adhd`（MIT），十条取三；其余七条因已被 R1–R2 涵盖、与 R1 冲突、或与 estimation-standards 重复而删去。规则 1–6 全部可以被一个把结论埋起来的响应满足——R7–R9 补上这个缺口 |
 | 1.1.0 | 2026-06-10 | 新增规则 R6 可选模型级别标注（`〔模型：Fast｜Standard｜Capable〕`）；与厂商无关；不强制既有技能回改 |

package/bundled/locales/zh-CN/skills/README.md

@@ -59,6 +59,7 @@ skills/
 | `refactoring-assistant` | `/refactor` | [UDS] 重构指引 |
 | `project-discovery` | `/discover` | [UDS] 评估项目健康度与风险 |
 | `brainstorm-assistant` | `/brainstorm` | [UDS] 结构化 AI 辅助构思 |
+| `comprehension-ladder` | `/comprehend` | [UDS] 把难懂的 AI 输出换成受控文字、Mermaid 图或离线 HTML 解说页，不改变事实 |
 | `changelog-guide` | `/changelog` | [UDS] 生成 changelog 条目 |
 | `dev-workflow-guide` | `/dev-workflow` | [UDS] 将开发阶段对应到 UDS 命令 |
 | `docs-generator` | `/docgen` | [UDS] 生成使用文档 |

package/bundled/locales/zh-CN/skills/comprehension-ladder/SKILL.md

@@ -0,0 +1,289 @@
+---
+name: comprehend
+source: ../../../../skills/comprehension-ladder/SKILL.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-10-05
+source_hash: 7c69dc2bfc9f
+status: current
+scope: universal
+description: |
+  [UDS] 把一段难懂的 AI 输出换成较好懂的形式：受控文字、Mermaid 图、单文件 HTML 解说页。所有形式都来自同一份大纲，所以形式会变，事实不会变。
+  Use when: AI 的说明、规格或代码解说太密、读的人看不出该不该核准；非专业的人必须靠它做核准；想要它的图或离线解说页。
+  Not for: 写新内容或加新分析——本技能只把既有的文字换形式；从源代码产生文档——请用 /docgen；为专家读者缩短文字——直接改写即可。
+  Keywords: comprehension ladder, explainer, controlled language, Mermaid, HTML explainer, outline, plain language, understand AI output, 理解阶梯, 受控语言, 流程图, 解说页, 换形式不换事实.
+allowed-tools: Read, Glob, Grep, Write
+argument-hint: "[text or file | 原文或文件] [rungs: 1 | 2 | 3]"
+---
+
+# 理解阶梯
+
+> **语言**: [English](../../../../skills/comprehension-ladder/SKILL.md) | [繁體中文](../../../zh-TW/skills/comprehension-ladder/SKILL.md) | 简体中文
+
+**版本**: 1.0.0 | **最后更新**: 2026-10-05 | **适用**: Claude Code Skills
+
+把一段难懂的 AI 输出换成较好懂的形式。形式会变，事实不会变。
+
+## 目的
+
+现在慢的不是拿到答案，而是看懂答案并判断它。本技能帮忙这一步。它拿一份原文，最多做出三种形式，每一种叫一「阶」。
+
+本技能的文字依 [ai-response-navigation](../../core/ai-response-navigation.md) 第 12 条（受控语言）写成。它自己也遵守自己的防护。
+
+## 阶梯
+
+阶梯正好有三阶。每一阶都从同一份大纲产生（见[大纲](#大纲)）。任何一阶都不得在大纲之外加东西。
+
+| 阶 | 形式 | 适合 | 产出 |
+|----|------|------|------|
+| 1 | 受控文字 | 任何原文。永远是第一阶 | 短句或编号列，放在对话或文件里 |
+| 2 | Mermaid 图 | 有流程、先后顺序、多个角色，或 3 个以上选项的原文 | 一个 Mermaid 代码区块，外加一份画不出来的项目文字清单 |
+| 3 | 单文件 HTML 解说页 | 需要探索或核准的读者 | 一个可离线打开的 `.html` 文件 |
+
+先问用户要哪几阶。用户没说，就先做第 1 阶，再提议另外两阶。
+
+没有视频阶。视频需要语音服务，而且会把原文送给第三方。
+
+## 三条防护
+
+这三条防护**必须**遵守。破坏任何一条的那一阶，就还没做完。不得交出去。
+
+| 编号 | 防护 | 等级 |
+|------|------|------|
+| G1 | `no-new-facts`：不加原文没有的事实 | **必须（Required）** |
+| G2 | `keep-hedges`：保留每一个不确定语气。不得把不确定的说法改成确定 | **必须（Required）** |
+| G3 | `trace-and-gaps`：每一项都附「对应原文哪一段」与「没涵盖什么」 | **必须（Required）** |
+
+G2 与 [ai-response-navigation](../../core/ai-response-navigation.md) 的 12.1 条是同一条规则。这里把它用在本技能的三阶。
+
+### G1 `no-new-facts`（必须）
+
+每一阶的每一个说法都必须来自原文。不要加原因、数字、名字、日期或「已确认」。不要加你知道、但原文没写的背景。
+
+**正例**——原文写：「订单有时会在付款步骤失败。」
+
+```text
+O1  订单有时会在付款步骤失败。
+```
+
+**反例**——同一份原文：
+
+```text
+O1  订单会在付款步骤失败。这也会让退款坏掉。
+```
+
+「退款」是添加的事实。「有时」也不见了，所以 G2 同时被破坏。
+
+### G2 `keep-hedges`（必须）
+
+不确定语气告诉读者，一个说法可以信到什么程度。例如：可能、推断、大概、尚未确认、might、could、probably。它是信息，不是赘字。
+
+- 原文写「可能」，这一阶就写「可能」。
+- 图里也要保留。不确定的项目用虚线画，标签里留下那个词。
+- HTML 里也要保留。不确定的项目要显示看得见的「尚未确认」标记。
+- 只有在原文自己说这个说法已经验证时，才可以拿掉不确定语气。这时要写出检查了什么。
+
+**正例**——原文写：「原因可能是缓存留着旧的价目表。」
+
+```text
+O2  原因可能是缓存留着旧的价目表。   [hedge: 可能]
+```
+
+**反例**——同一份原文：
+
+```text
+O2  原因是缓存留着旧的价目表。
+```
+
+反例比较短，也比较好读。但它与原文不符。读的人若凭这一行核准修复，就被误导了。
+
+### G3 `trace-and-gaps`（必须）
+
+每一项都带两个注记：
+
+- **对应原文**：这一项出自原文的哪个位置。用段落与句子编号，或文件名与行号，再加一段 12 个词以内的引文（中文约 20 字以内）。
+- **没涵盖**：这一项没说到什么，或它证明不了什么。原文没有更多内容时，写「原文没有更多内容」。
+
+最后一项之后，加一份清单，叫做**这份大纲没有收的部分**。它列出原文中所有没变成项目的部分。
+
+**正例**
+
+```text
+O3  我们尚未在测试环境重现这个问题。
+    对应原文：第 1 段第 3 句——「尚未在测试环境重现」
+    没涵盖：为什么没有重现。原文没有给理由。
+```
+
+**反例**
+
+```text
+O3  这个问题已在测试环境重现。
+    对应原文：那份报告。
+```
+
+「那份报告」没有指向某个位置。这个说法也与原文相反。而且没有「没涵盖」注记。
+
+## 大纲
+
+大纲是唯一共享的事实来源。先做大纲，再做任何一阶。不要直接从原文写某一阶。
+
+每个大纲项目有一个编号和一个种类。
+
+| 种类 | 意思 |
+|------|------|
+| `claim` | 原文提出的说法 |
+| `mechanism` | 一个步骤、一个原因，或两件事之间的关联 |
+| `uncertainty` | 原文说不知道或尚未确认的事 |
+| `example` | 原文拿来说明某个说法的案例 |
+
+每个项目写成这个样子：
+
+```text
+O<编号> | 种类 | 文字 | hedge: <原文的不确定用词，或 none>
+  对应原文：<位置> — 「<引文，12 个词以内>」
+  没涵盖：<这一项没说到的事>
+```
+
+依原文的顺序编号。编号不得重复使用。三阶都用同一组编号。
+
+## 工作流程
+
+### 步骤 1——读原文
+
+读完整份原文。原文是文件，就读那个文件。读完之前，不要开始做大纲。
+
+### 步骤 2——创建大纲
+
+抽出项目。一项一个事实。每个不确定用词都要原样抄下。
+
+### 步骤 3——为每一项标出处
+
+为每一项写「对应原文」与「没涵盖」。再写「这份大纲没有收的部分」清单。
+
+### 步骤 4——把大纲给用户看
+
+项目超过 5 个，或用户要求时，就把大纲给用户看。让用户删除或修正项目。用户否决的大纲，不要拿去做任何一阶。
+
+### 步骤 5——做出各阶
+
+用户要哪几阶，就做哪几阶。照下面各阶的规则做。
+
+#### 第 1 阶：受控文字
+
+照 [ai-response-navigation](../../core/ai-response-navigation.md) 的 12.2 条：
+
+- 一句一件事。英文约 15 到 25 个词，中文约 25 到 40 个字。
+- 一物一名。不要为了文采换名称。
+- 写清楚谁做什么。
+- 一步一动作。流程写成编号列表。
+- 少用分号。
+- 数字要带单位。
+
+每一行开头保留项目编号，读的人才找得到它在大纲里的位置。
+
+#### 第 2 阶：Mermaid 图
+
+1. 步骤与因果用 `flowchart TD`。角色与交接用 `flowchart LR`。
+2. 每个 `mechanism` 项目画一个节点。用项目编号当节点编号。
+3. 节点标签取自项目文字。标签里要留下不确定用词。
+4. 不确定的项目画成虚线节点或虚线边（`-.->`）。
+5. 不要画没有大纲编号的节点。
+6. 在图的下面，用文字列出你没有画的每一项，并各附一个理由。
+
+```mermaid
+flowchart TD
+  O1["O1 订单有时在付款步骤失败"]
+  O2["O2 可能：缓存留着旧的价目表"]
+  O1 -.-> O2
+```
+
+#### 第 3 阶：单文件 HTML 解说页
+
+页面必须是一个文件。必须能离线打开。不得从网络加载任何东西。
+
+页面**必须**符合：
+
+- 所有 CSS 都放在一个 `<style>` 元素里。
+- 所有脚本（若有）都放在一个内嵌的 `<script>` 元素里。关掉脚本，页面仍要能用。
+- `src`、`href`、`action`、`@import`、`url()` 里不得有 `http://`、`https://` 或 `//` 开头的网址。只允许页内的 `#` 锚点链接。
+- 不得有 `<link>` 元素。不得有网络字体、CDN 或外部图片。
+- 不得调用 `fetch`、`XMLHttpRequest`、`WebSocket` 或 `import()`。
+- 不要加载 Mermaid 函数库。把图画成内嵌 SVG，或画成有样式的清单。
+- 原文中 HTML 会当成标记的字符，都要跳脱。
+
+页面依序包含：
+
+1. 标题，加一句话说明原文是什么。
+2. 图（若用户要了第 2 阶）。
+3. 每个大纲项目一张卡片。卡片显示编号、文字、有不确定语气时的「尚未确认」标记、对应原文，以及没涵盖注记。
+4. 「这份大纲没有收的部分」清单。
+
+最小骨架：
+
+```html
+<!doctype html>
+<html lang="zh-Hant">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>解说页：原文的简短名称</title>
+<style>
+  body { font: 16px/1.6 system-ui, sans-serif; max-width: 46rem; margin: 2rem auto; padding: 0 1rem; }
+  .card { border: 1px solid #8884; border-radius: 8px; padding: .75rem 1rem; margin: .75rem 0; }
+  .badge { background: #fd0; color: #000; border-radius: 4px; padding: 0 .4rem; font-size: .85em; }
+</style>
+</head>
+<body>
+<h1>解说页</h1>
+<p>一句话：原文是什么。</p>
+<section class="card" id="O2">
+  <strong>O2</strong> 原因可能是缓存留着旧的价目表。
+  <span class="badge">尚未确认：可能</span>
+  <p><em>对应原文：</em>第 1 段第 2 句</p>
+  <p><em>没涵盖：</em>是哪一个缓存。原文没有说。</p>
+</section>
+</body>
+</html>
+```
+
+### 步骤 6——交出之前先检查
+
+五项检查都要跑。有一项没过，就修好那一阶，再跑一次。
+
+1. **数量**：每一阶的项目数，等于大纲的项目数，减去你列为「没有画」的项目。原文有 5 个步骤，每一阶就是 5 个步骤。不是 4，也不是 6。
+2. **没有新项目**：每一阶的每个项目都有大纲编号。找找看有没有项目没有编号。
+3. **不确定语气比对**：`hedge:` 不是 `none` 的每一项，每一阶都要有同一个不确定用词。比对的是该阶与原文。任何语言都做得到。
+4. **出处**：每一项都有指向某个位置的「对应原文」，也有「没涵盖」注记。
+5. **离线**（只用于第 3 阶）：在文件里搜索 `http`、`//`、`<link`、`fetch(` 与 `XMLHttpRequest`。每一项搜索，除了你从原文引用的文字，都必须是零命中。
+
+### 步骤 7——回报
+
+结尾放这张表。没有这张表，不要交出任何一阶。
+
+| 项目 | 第 1 阶 | 第 2 阶 | 第 3 阶 | 保留不确定语气 | 对应原文 | 没涵盖 |
+|------|---------|---------|---------|----------------|----------|--------|
+| O1 | 有 | 有 | 有 | 不适用 | 第 1 段第 1 句 | 「有时」的频率 |
+
+有任何一项防护检查没过、又修不好，就说是哪一项、为什么。不要回报成功。
+
+## 什么时候不要用
+
+- 原文不到约 150 字。用 [ai-response-navigation](../../core/ai-response-navigation.md) 的 12.2 条改写，并保留不确定语气。不要做各阶。
+- 读者是专家，需要密度高的原形。
+- 任务是找出新的事实。本技能不做这件事。
+
+## 衡量它有没有帮助
+
+本技能还没有被证明有帮助。[eval-cases.md](eval-cases.md) 有 5 段原文，各附理解题与标准答案，并附一套跑法，会产出两个数字：前后的答对率，以及防护违反次数。实跑需要模型调用，目前还没做。实跑完成之前，不要宣称本技能有效。
+
+## 相关
+
+- [ai-response-navigation](../../core/ai-response-navigation.md)：第 12 条，受控语言。12.1 条是防护 G2 的基础。
+- [documentation-guide](../documentation-guide/SKILL.md)：Mermaid 图在项目文档中该放哪里。
+- [brainstorm-assistant](../brainstorm-assistant/SKILL.md)：相反方向，还没有原文时用。
+
+## 版本历史
+
+| 版本 | 日期 | 变更 |
+|------|------|------|
+| 1.0.0 | 2026-10-05 | 首次发布。从同一份大纲做出三阶。三条必须遵守的防护。评估案例。落实 dev-platform XSPEC-450 / DEC-125 D4。 |