universal-dev-standards 6.14.0-beta.6 → 6.14.0-beta.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (99) hide show
  1. package/README.md +13 -3
  2. package/bin/uds.js +30 -6
  3. package/bundled/ai/options/code-review/pr-review.ai.yaml +20 -1
  4. package/bundled/ai/standards/code-review.ai.yaml +15 -2
  5. package/bundled/ai/standards/developer-memory.ai.yaml +12 -2
  6. package/bundled/ai/standards/full-coverage-testing.ai.yaml +44 -6
  7. package/bundled/ai/standards/open-work-tracking.ai.yaml +191 -11
  8. package/bundled/ai/standards/pipeline-security-gates.ai.yaml +48 -3
  9. package/bundled/ai/standards/project-context-memory.ai.yaml +12 -2
  10. package/bundled/core/code-review-checklist.md +20 -2
  11. package/bundled/core/developer-memory.md +12 -2
  12. package/bundled/core/full-coverage-testing.md +44 -4
  13. package/bundled/core/open-work-tracking.md +156 -16
  14. package/bundled/core/pipeline-security-gates.md +63 -0
  15. package/bundled/core/project-context-memory.md +10 -2
  16. package/bundled/locales/zh-CN/CHANGELOG.md +78 -3
  17. package/bundled/locales/zh-CN/README.md +1 -1
  18. package/bundled/locales/zh-CN/SECURITY.md +1 -1
  19. package/bundled/locales/zh-CN/adoption/ADOPTION-GUIDE.md +13 -4
  20. package/bundled/locales/zh-CN/adoption/STATIC-DYNAMIC-GUIDE.md +7 -1
  21. package/bundled/locales/zh-CN/adoption/checklists/enterprise.md +7 -1
  22. package/bundled/locales/zh-CN/adoption/checklists/minimal.md +13 -3
  23. package/bundled/locales/zh-CN/adoption/checklists/recommended.md +7 -1
  24. package/bundled/locales/zh-CN/core/code-review-checklist.md +17 -0
  25. package/bundled/locales/zh-CN/core/developer-memory.md +9 -0
  26. package/bundled/locales/zh-CN/core/full-coverage-testing.md +48 -8
  27. package/bundled/locales/zh-CN/core/pipeline-security-gates.md +64 -4
  28. package/bundled/locales/zh-CN/core/project-context-memory.md +5 -0
  29. package/bundled/locales/zh-CN/docs/AVAILABLE-STANDARDS.md +70 -0
  30. package/bundled/locales/zh-CN/docs/CHEATSHEET.md +4 -3
  31. package/bundled/locales/zh-CN/docs/CLI-INIT-OPTIONS.md +25 -23
  32. package/bundled/locales/zh-CN/docs/FEATURE-REFERENCE.md +13 -11
  33. package/bundled/locales/zh-CN/docs/USAGE-MODES-COMPARISON.md +6 -6
  34. package/bundled/locales/zh-CN/docs/WINDOWS-GUIDE.md +7 -1
  35. package/bundled/locales/zh-CN/docs/user/GETTING-STARTED.md +44 -0
  36. package/bundled/locales/zh-CN/options/code-review/pr-review.md +13 -2
  37. package/bundled/locales/zh-TW/CHANGELOG.md +78 -3
  38. package/bundled/locales/zh-TW/README.md +1 -1
  39. package/bundled/locales/zh-TW/SECURITY.md +1 -1
  40. package/bundled/locales/zh-TW/adoption/ADOPTION-GUIDE.md +13 -4
  41. package/bundled/locales/zh-TW/adoption/STATIC-DYNAMIC-GUIDE.md +7 -1
  42. package/bundled/locales/zh-TW/adoption/checklists/enterprise.md +7 -1
  43. package/bundled/locales/zh-TW/adoption/checklists/minimal.md +13 -3
  44. package/bundled/locales/zh-TW/adoption/checklists/recommended.md +7 -1
  45. package/bundled/locales/zh-TW/core/code-review-checklist.md +17 -0
  46. package/bundled/locales/zh-TW/core/developer-memory.md +9 -0
  47. package/bundled/locales/zh-TW/core/full-coverage-testing.md +48 -8
  48. package/bundled/locales/zh-TW/core/open-work-tracking.md +90 -14
  49. package/bundled/locales/zh-TW/core/pipeline-security-gates.md +64 -4
  50. package/bundled/locales/zh-TW/core/project-context-memory.md +5 -0
  51. package/bundled/locales/zh-TW/docs/AVAILABLE-STANDARDS.md +70 -0
  52. package/bundled/locales/zh-TW/docs/CHEATSHEET.md +4 -3
  53. package/bundled/locales/zh-TW/docs/CLI-INIT-OPTIONS.md +25 -23
  54. package/bundled/locales/zh-TW/docs/FEATURE-REFERENCE.md +13 -11
  55. package/bundled/locales/zh-TW/docs/USAGE-MODES-COMPARISON.md +6 -6
  56. package/bundled/locales/zh-TW/docs/WINDOWS-GUIDE.md +7 -1
  57. package/bundled/locales/zh-TW/docs/user/GETTING-STARTED.md +44 -0
  58. package/bundled/locales/zh-TW/options/code-review/pr-review.md +13 -2
  59. package/bundled/skills/SKILL_NAMING.md +9 -0
  60. package/bundled/templates/gates/check-anti-fake-tests.mjs +305 -5
  61. package/package.json +3 -1
  62. package/src/commands/audit.js +9 -2
  63. package/src/commands/check.js +17 -0
  64. package/src/commands/hitl.js +3 -0
  65. package/src/commands/init.js +41 -21
  66. package/src/commands/list.js +12 -3
  67. package/src/commands/mcp.js +2 -3
  68. package/src/commands/open-work.js +65 -6
  69. package/src/commands/quickstart.js +29 -13
  70. package/src/commands/release.js +41 -17
  71. package/src/commands/skills.js +19 -33
  72. package/src/commands/spec-split.js +28 -16
  73. package/src/commands/spec.js +34 -13
  74. package/src/commands/uninstall.js +2 -2
  75. package/src/commands/update.js +61 -61
  76. package/src/core/open-work-config.js +103 -0
  77. package/src/flows/init-flow.js +10 -0
  78. package/src/hitl/manager.js +4 -2
  79. package/src/i18n/messages.js +240 -63
  80. package/src/installers/skills-installer.js +3 -1
  81. package/src/mcp/__tests__/server.test.js +0 -1
  82. package/src/mcp/server.js +16 -4
  83. package/src/prompts/init.js +148 -13
  84. package/src/reconciler/index.js +42 -5
  85. package/src/uninstallers/skills-uninstaller.js +83 -16
  86. package/src/uninstallers/standards-uninstaller.js +56 -7
  87. package/src/utils/agents-installer.js +10 -17
  88. package/src/utils/available-standards-report.js +144 -0
  89. package/src/utils/available-standards.js +216 -0
  90. package/src/utils/copier.js +5 -4
  91. package/src/utils/friction-detector.js +27 -0
  92. package/src/utils/open-work-tracking.mjs +919 -48
  93. package/src/utils/prompt-closed.js +18 -0
  94. package/src/utils/skill-frontmatter.js +102 -0
  95. package/src/utils/skill-name-collision.js +169 -0
  96. package/src/utils/skills-install-paths.js +114 -0
  97. package/src/utils/skills-installer.js +63 -105
  98. package/src/utils/transient-fs.js +113 -0
  99. package/standards-registry.json +34 -9
@@ -1,8 +1,8 @@
1
1
  ---
2
2
  source: ../../CHANGELOG.md
3
- source_version: 6.14.0-beta.6
4
- translation_version: 6.14.0-beta.6
5
- last_synced: 2026-10-07
3
+ source_version: 6.14.0-beta.8
4
+ translation_version: 6.14.0-beta.8
5
+ last_synced: 2026-10-09
6
6
  status: current
7
7
  ---
8
8
 
@@ -17,6 +17,81 @@ status: current
17
17
 
18
18
  ## [Unreleased]
19
19
 
20
+ ## [6.14.0-beta.8] - 2026-10-10
21
+
22
+ > **测试版**——以 `npm install -g universal-dev-standards@beta` 安装。要测什么、如何退回正式版:[docs/PRE-RELEASE.md](../../docs/PRE-RELEASE.md)。
23
+ >
24
+ > **行为改变:**`uds hitl check` 无人可答时拒绝(结束码 1);`uds release verify` 失败以 1、无法验证以 2 结束;`uds release promote` 不再为没做的事印「✓」;移除 `uds mcp serve --root`;没有终端机时 `uds spec delete/split` 以 2、`uds spec create` 以 0 结束;`uds uninstall` 只移除 UDS 写的、你没改过的文件。
25
+
26
+ ### Added
27
+
28
+ - **CI:uds CLI 的每个命令、子命令与选项都要有验收步骤,而且步骤必须读回效果,不能只看退出码(XSPEC-471 R2、R3)。** `node scripts/beta-acceptance/check-cli-coverage.mjs`(CI 工作「Beta Acceptance Coverage」)加载真正的 `cli/bin/uds.js`,记录它建出的 commander 程序(含隐藏命令、隐藏选项与别名;不读帮助文本),当 `scripts/beta-acceptance/steps.json` 的任何步骤都没用到某个命令、子命令或选项时,逐一列名并使 CI 变红,并打印已用、豁免与缺少各几个。要豁免只能在 `exemptions` 加 `{"command": ...}` 或 `{"option": ...}`,并附至少 20 字符的理由;空白或单字理由等于没有豁免。加入这项检查时已存在的缺口(31 个命令与子命令、115 个选项)列在 `scripts/beta-acceptance/coverage-baseline.json`,这份文件只能减少:不在其中的缺口会红,已被步骤用到的条目若没移除也会红(`--shrink-baseline`),所以文件不会腐烂;`--baseline-not-larger-than <ref>` 会让新增条目的变更变红。`check-steps.mjs` 现在也会指名 `expect` 只有退出码的步骤(含人工步骤;`{"step": ..., "reason": ...}` 可豁免一个步骤)。**未验证**:CI 接线只由 YAML 解析器与测试读过,尚未由 GitHub 实际执行。
29
+ - **CI:`scripts/bump-version.mjs` 遇到不带预览标记的版本号,除非它最近一个预览版已在三个平台验收通过,否则拒绝(XSPEC-471 R5)。** 在改动任何文件之前,它先确认:`scripts/beta-acceptance/reports/<预览版>/` 有 Windows、macOS、Linux 三个平台、来自已发布包的报告(用 `--local-bin`、`--source` 或注入的安装器做出的报告不算;同一平台从多种 shell 跑过时,每一种都要看,取最差的),其中没有任何自动步骤失败,`check-cli-coverage.mjs` 与 `check-steps.mjs` 为绿、`coverage-baseline.json` 为空,当前 `steps.json` 的每一步都在这些报告里(预览版发布之后新增的步骤需要更新的预览版),而且 `steps.json` 没有任何豁免写明功能“已知坏掉”(R4 的写法 "known broken",`已知壞掉` 也会读)。缺的东西会在一次拒绝中全部列出,退出码为 1。没人确认的人工步骤会列出,但不挡。预览版本号不检查。这道关卡没有跳过的开关,连 `SKIP_BUNDLE_PARITY` 也管不到:补丁版先以预览版发出,发版后的验收会自动跑。规则在 `scripts/beta-acceptance/lib/stable-gate.mjs`。
30
+
31
+ ### 变更
32
+
33
+ - **行为变更——`uds release verify` 验证失败时改以退出码 1 结束,无法验证时以 2 结束(XSPEC-471 R4)。** 它打印“Manifest 驗證失敗”后仍以 0 结束,把验证当作发布关卡的脚本或 CI 步骤会把每一次失败都读成通过。退出码 0 表示 manifest 验证通过;1 表示 commit 或 artifact 的 checksum 与 manifest 的记录不符;2 表示根本无法验证:没有 `build-manifest.json`、文件不是合法 JSON、`--artifact` 指的文件不存在,或发布模式(`ci-cd`)没有 `verify`。分法与 `uds hitl check` 相同(1=答案是否,2=没有答案)。缺少 staging 结果仍只是警告,不改变退出码。若有脚本一直假设 `uds release verify` 必回 0,请处理 1 与 2。
34
+ - **`uds release promote <版本>` 不再为它没做的事打印“✓ 晉升紀錄建立”与“✓ Git tag”(XSPEC-471 R4)。** 这个命令不写晋升记录、也不建 tag,只打印文字;相信那些勾号的人可能把一个从未打过 tag 的版本拿去部署。现在它明说“這個指令不會建立晉升紀錄,也不會建立 Git tag”,并列出要你自己执行的下一步,包含 `git tag v<版本>`。没有新增任何行为:它仍然什么都不写、什么 tag 都不建。
35
+ - **行为变更——移除 `uds mcp serve` 的 `--root <path>` 选项(XSPEC-471 R4)。** 它被接受并存起来,但没有任何程序读它,所以 `--root /elsewhere` 不改变任何回答,却看起来像在指定标准从哪里来。服务器照旧从已安装的包读 UDS 随附的文件。`uds mcp serve --root <path>` 现在会以 `error: unknown option '--root'` 与退出码 1 停下;请从任何传入它的 MCP 客户端配置中移除这个选项。
36
+
37
+ ### 修复
38
+
39
+ - **`uds mcp serve`:`get_design_standards` 与 `get_design_token` 的 DESIGN.md 模板后备,在每一种安装方式下都返回 ENOENT(XSPEC-471 R4)。** 服务器去“`cli/src/mcp/` 往上四层”找 UDS 随附的文件,那个位置在仓库之外,已安装的包也一样在包之外。现在改找包的 `bundled/` 文件夹,在源码检出时则找 `cli/` 的上一层。服务器的单元测试把文件系统换掉了,所以从没发现;新增的端到端测试会启动真正的 `uds mcp serve` 并读回响应。
40
+ - **`uds release deploy <env>` 在“`release-config.yaml` 是 UDS 自己生成”的项目里,拒绝每一个环境(XSPEC-471 R4)。** `uds init` 与 `uds config` 把 `release.environments` 写成对象(`- name: staging`),检查却拿用户输入的名称去比这些对象,于是说“未知的环境”并列出 `[object Object]`。现在对象形式与纯名称都能读懂。
41
+ - **`uds agent list` 与 `uds agent info` 显示空白的说明,也没有专长、工具、技能(XSPEC-471 R4)。** 代理文件是 YAML(`description: |`、列表),读取程序一次只看一行 `key: value`,把说明看成 `|`。现在 front matter 以 YAML 解析。
42
+ - **行为变更——`uds hitl check` 在无法询问时不再以退出码 0 结束(XSPEC-471 R4)。** 没有终端可回答、也没有 `CI` 变量时,高风险的 `--op` 会打开一个永远等不到回答的提示,打印堆栈跟踪后以 0 结束,脚本会把它当成“已批准”。现在打印“Blocked (Safety First)”与“Denied”并以 1 结束,与 CI 下相同。`uds hitl check` 没给 `--op` 时以 2 结束(原本是 0)。
43
+ - **`uds list` 只显示它所计算的 163 个标准中的 81 个,而且拒绝 `--category core`(编写 XSPEC-471 R4 验收步骤时发现)。** “Total”行计入注册表中的每一个标准,但列表只走固定的五个分类,所以 `core`、`testing`、`security`、`deployment`、`operations` 这五个分类里的 82 个标准被计入却从未显示,`uds list --category core` 还回答“Unknown category”。现在列表会显示注册表里有标准的每一个分类,每个分类各有标题与数量,标题上的数字加起来等于 Total;这五个分类已声明在 `cli/standards-registry.json`(并注明它们不由 `uds init` 安装,要用 `uds update --apply --add-standard` 按编号加入),日后注册表新增的分类会以它自己的名称列出,不会再被丢掉。“有效分类”提示现在列出全部十个。标题与 Total 不一致时 `npm test` 会失败。
44
+ - **`uds quickstart`、`uds spec create`、`uds spec delete`、`uds spec split` 在没有任何东西能回答它们的问题时,以 Node 堆栈跟踪结束,且退出码为 0(编写 XSPEC-471 R4 验收步骤时发现)。** 在没有终端的环境(AI 助手、CI、管道)运行时,它们画出问题后就死在 `ExitPromptError`,整次运行看起来像成功。`uds update` 与 `uds uninstall` 早先已用同样方式修复。现在:`uds quickstart` 打印四个流程与各自的命令(这份指南本来的工作就是列出命令);没给 `--yes` 的 `uds spec create` 把已写好的规格留作草稿并说明如何确认(退出码 0);没给 `--yes` 的 `uds spec delete` 什么都不删、说明要加 `--yes` 重跑,并以 2 结束(原为 0);`uds spec split` 什么都不改、说明要在终端运行,并以 2 结束(原为 0)。有终端时行为不变。
45
+ - **验收步骤 `init-locale-pack-missing-is-said` 在任何跑过 `prepack` 的 checkout 上,用 `run.mjs --local-bin cli/bin/uds.js` 会失败(XSPEC-471 R5)。** 它以 `cli/bundled/` 是否存在来区分已发布包与源码 checkout,但源码 checkout 在 `prepack` 之后也有那个文件夹,于是“缺少 zh-TW 技能文本”的副本被建在仓库根目录,`skills-installer.js` 照样在那里找到 `locales/zh-TW`,装了中文技能。现在步骤改问 `locales/zh-TW` 是否在 `cli/` 旁边。已发布的包从未受影响,`uds init` 也没有。
46
+
47
+ ## [6.14.0-beta.7] - 2026-10-08
48
+
49
+ > **测试版**——以 `npm install -g universal-dev-standards@beta` 安装。要测什么、如何退回正式版:[docs/PRE-RELEASE.md](../../docs/PRE-RELEASE.md)。
50
+ >
51
+ > **行为改变:**`uds init` 与 `uds init --yes` 会把 UDS 技能装进项目;`uds init` 的命令约定步骤保留 `uds.project.yaml` 其余内容;`uds skills` 输出文字改变;`uds open-work next-action` 在唯一的违规是 OWT-022 判定完整的「已询问、等回复」行时以 0 结束(原为 1)。
52
+
53
+ ### 新增
54
+
55
+ - **`uds update` 现在会说出 UDS 有发布、项目没有的标准,`--add-standard <id>` 可以挑着装(XSPEC-458)。** 用旧版 UDS 设置的项目只保有 manifest 列出的标准,所以 `uds update --apply` 会报告“已是最新”,之后新增的标准(例如 `open-work-tracking`)却从没装上,也没有任何东西告诉你。现在:`uds update --plan` 结尾会打印“上游有、项目没装(N 个)”并按类别分组,没有时打印“没有”;`--apply` 结尾打印数量与命令;`uds check` 打印一行“上游有 N 个标准未安装”;`uds audit --friction` 列出一项低严重度发现。这些都不会改变计划的动作、判定、退出码或 `uds audit --score`。`uds update --plan|--apply --add-standard <id>`(可重复)会安装标准并记入 `manifest.standards`,所以下一次 `--apply` 不会把它当多余而删;一次 `--rollback` 就能移除。未知的 id 以 1 退出并列出最相近的 id;已安装的 id 说明后以 0 退出;`extension`、`integration`、`template`(由语言、工具、模板的选项安装)会被拒绝并说明原因。“可用”的定义是:类别为 `reference` 或 `skill`、在项目格式下有来源文件、manifest 里没有同名文件——旧的 `uds update` 路径、`--plan`/`--apply`、`check`、`audit` 共用这一个定义。其他类别(`core`、`testing`、`security`、`deployment`、`operations` 等)`uds init` 从没装过,只以一行计数、不逐项列出;它们仍可用 id 指名安装。规则与死字段(`level`、`profile`)见 [docs/AVAILABLE-STANDARDS.md](../../docs/AVAILABLE-STANDARDS.md)。
56
+ - **CI:标准孤儿矩阵(XSPEC-458 R4)。** `npm run check:orphan-matrix` 为登记表 163 个标准各记五栏是或否(`uds init` 是否安装、生成的索引是否提到、是否有技能包装、是否有检查、是否被 workflow/hook/技能调用),五栏全空的标准,以及没有任何调用者的 `check-*` 脚本,都会让它失败。第一次运行找到 78 个孤儿标准与 2 个没人调用的检查脚本,已逐项附上理由与处理者列在 `cli/scripts/orphan-matrix-allowlist.json`,该清单于 2026-12-31 到期,条目不再是发现时也会失败。另新增升级测试:用当前的 CLI 对照真正的 6.11.0 写出的 manifest。
57
+ - **`open-work-tracking` 1.2.0——“还没问”与“已问、等回复”成为两个有名字的状态,且对没有任何东西能推导的事实容许手写行(OWT-020~OWT-026,XSPEC-459)。** 草拟了从没送出的消息,与已送出、没人回的消息看起来一模一样;助理无法观察的事实(有没有寄出、对方有没有回、有没有核准)没有被认可的地方可以写。OWT-020~OWT-022 为 `not-yet-asked`(必须点名草稿或动作)与 `asked-awaiting`(必须带 `asked-at`、在等什么、解除事件)命名;两者皆非的等待项目被逐项点名、绝不算成已完成。OWT-023~OWT-026 只对这类事实容许手写行,必须有 `observed-by`、`observed-at` 与 `yes`/`no`/`unknown` 的值——`unknown` 单独计数、单独显示、永远不算完成,每笔观察的年龄都印出来,超过门槛的回报为“观察已旧”且绝不算已确认。这个例外不及于版本控制、规格标记或 CI 结果已能决定的东西。七条要求全是 `warning`;词汇(中英文)与“观察已旧”默认的 7 天都未校准;检查只判定字段存在且格式正确,绝不判定观察为真。“刻意不采纳”表中“手写状态档”那一行已改写成如实描述这件事;OWT-003 不变。
58
+ - **`uds open-work waiting` 与 `uds open-work observations`**——对应的参考检查。`--now` 注入今天的日期(规则绝不读时钟)、`--stale-after` 声明门槛,退出码与其他 `open-work` 指令相同:0 无违反、1 违反(`warning` 等级的违反也是 1,与 OWT-019 相同)、2 判定不了。`uds open-work self-test` 现在对 OWT-020~OWT-026 每一条各跑一个违反与一个符合的样本。`next-action`、`revision`、`separation` 印出的内容与 1.1.0 逐字节相同(21 次执行、16 份载体逐字节比对,含中文表头的表格)。
59
+ - **`uds check` 在 UDS 技能装了两次时警告(XSPEC-462 R2)。** 项目里有 UDS 技能(`.claude/skills/`),同时又从 Claude Code 市场装了 UDS 插件时,Claude Code 会把每个技能列出两次(`/commit` 与 `/universal-dev-standards:commit`),而且每个技能的名称与描述每回合都会放进上下文。`uds check` 现在会说出这件事,并说明怎么二选一。纯信息:不改变判定与退出码;任何一边不存在、或读不到 `~/.claude/plugins/installed_plugins.json` 时不出声。
60
+ - **CI:插件设置不得写错技能数(XSPEC-462 R3)。** `npm run check:plugin-manifest` 在 `.claude-plugin/plugin.json`、`marketplace.json` 或 `README.md` 的描述写出的技能数,与 `skills/` 下含 `SKILL.md` 的文件夹数不同时失败。描述里没有数字则通过。
61
+ - **文档:`docs/user/GETTING-STARTED.md` 新增「技能怎么装」(XSPEC-462 R3)。** 并列两种装法与各自的限制、为什么 `uds check` 与 `uds update` 建议 `uds update --apply --skills`、两者都装时怎么办(英文、繁体中文、简体中文)。
62
+ - **`pipeline-security-gates` 1.1.0——pre-commit 密钥扫描现在写明扫描器自身的三个行为(PSG-1~PSG-3,XSPEC-463)。** 标准原本写了闸门扫描什么、阻断什么,没写扫描器本身必须怎么表现。第 1.1 节新增:PSG-1(必须)扫描输出——终端、CI 日志、报告文件——不得含被匹配到的密钥值,只能指出文件、行号与规则名称;PSG-2(必须)扫描器跑不起来(可执行文件不存在、配置文件无法读取或无效、超时、非预期的退出)视同闸门失败并阻断,不得以 `|| true` 或 `2>/dev/null` 吞掉;PSG-3(建议)团队自己编写的检测规则,每条都有一个红样本与一个绿样本,且在测试中执行。三条各附采用者在自己的闸门上跑的三行判定程序;PSG-1 的程序第一步要求先证明闸门真的阻断,所以没有任何规则匹配的样本无法让它通过。工具注记只写在厂商自己文档读到的内容:gitleaks 的 README(2026-10-07 读取)示例输出在未加 `--redact` 时打印 `Secret:` 一行,且退出码 1 同时代表「发现泄漏」与「发生错误」;detect-secrets 与 trufflehog 标示「采用者须自行确认」。UDS 不发布扫描器,自己的 CI 与 hook 也没有,标准正文已写明。机器可读:`.ai.yaml` 的 `gate_positions.pre_commit.output_redaction`、`.scanner_failure`、`.custom_rule_samples`;注册表描述与两个译本已同步,`meta.updated` 标为 2026-10-07。
63
+ - **`open-work-tracking` 1.3.0——等待可以点名另一个项目里的对象,这台机器看不到的项目被单独计数(OWT-027~OWT-029,XSPEC-460)。** 彼此依赖的项目,过去没有办法说“这个条目在等那个项目的产出”。OWT-027 让解除条件可以写成 `<项目>:<对象>`:项目是**逻辑名称**(`uds`、`vibeops`),绝不是目录;对象是文件路径、测试名称、指令、需求编号或版本控制标签;载体里出现机器专属的绝对路径(家目录或卷目录、盘符、`~/`),或离开对方项目的路径,即违反。名称在某台机器上对应哪里,声明在载体之外。OWT-028:对每个这样的条件,`uds open-work waiting` 说四种话之一并单独计数:**已解除**(该路径或标签现在在那边存在)、**尚未解除**、**从这里看不到**(项目不在这台机器上、目录不存在、或读不到它的 git 标签:不是已解除,也不是零)、**需要人判断**(另一个项目里的测试名称、指令、需求编号,没有任何检查读得到的东西)。它只读这台机器上的文件与 git,不联网。在等另一个项目之对象的条目,免于 OWT-020 的“有没有问过”,并在自己那一行计数(`waiting-cross-project`)。OWT-029 说这类工作的记录放在每个相关项目的 session 都读得到、受版本控制的仓库,不只放在某个人的 AI 工具记忆;检查不判定载体放在哪。涵盖的是一个人在一台机器上的各个 session,人与人之间的共享不在这版决定。三条都是 `warning`,且未校准。
64
+ - **`uds open-work waiting --root NAME=DIR`(可重复)与 `uds.project.yaml` 的 `open_work`。** 它一直接受的单一 `--root DIR` 行为与之前完全相同(用 1.2.0 检查的冻结输出逐字节比对 14 次运行;第二个没有名称的 `--root` 现在会被拒绝,而不是被误读)。`--root NAME=DIR` 说明另一个项目在哪里;`uds.project.yaml` 的 `open_work.projects` 不必打字就说同一件事,相对目录以该文件所在目录为基准,同一个名称两边都有时以命令行为准。读得到的文件、但 `open_work` 区段格式不对,命令以 2 停下;完全读不了的文件只提示一句、命令继续。同一个 `open_work` 区段也放 `next_action_words`(见下),所以两件事共用一个设置命名空间。
65
+ - **`uds open-work next-action` 认得更多人们说“下一步”的词、让项目声明自己的词,并说清楚为什么回 2(XSPEC-461)。** 一位用户的载体一个状态一张表,得到退出码 2 却没被告知原因。现在 `下一个动作`、`下一个步骤`、`接下来要做什么` 也会被读到,与标题、表头、行内标签共用同一份清单。`待办`、`后续`、`Next`、`TODO`、`Action` 与单独的 `接下来` 刻意**不**加入(它们也标在不是下一步的列上),并有回归测试钉住。`--next-action-word <词>`(可重复;`separation` 也接受)与 `uds.project.yaml` 的 `open_work.next_action_words` 把词加进同一份清单;词是纯文本、不分大小写、绝不是正则表达式,空白的词会被拒绝并以 2 退出。找不到任何字段时退出码仍是 2,文字现在会逐载体列出它看到的表头与标题(约 20 个,其余写“还有 N 个”)、认得的词(声明的另列)、怎么加,以及该载体是有表格但表头都不符、还是根本没有可读的东西。`glab` 与 `dotnet` 现在是内置命令(有用户写的 `glab mr merge 486` 被读成什么都没点名);`go`、`make`、`sh` 刻意不内置。`--command-word <程序名>`(可重复)与 `open_work.command_words` 可加入程序,`next-action` 与 `waiting` 都读得到——`waiting` 以前问“这份草稿有没有点名动作”时读不到它们。`next-action` 现在也会说路径是在哪个目录下查找的、那个目录来自 `--root` 还是当前目录,载体在所有 git 仓库之外又没给 `--root` 时会明说,并把 `named-unresolved` 分成 `path-missing`(查过、不在)与 `not-resolvable`(指令、测试名称、需求编号,从不查找);旧的计数行不变,新的两个数字相加等于它。其余既有载体上的 `next-action`、`revision`、`separation` 输出不变:1.1.0 的冻结输出仍逐字节比对(拿掉新增的行之后),只有其中两个“找不到字段”的退出码 2 案例变长,原文仍是它们的开头。
66
+ - **`developer-memory` 与 `project-context-memory` 的边界说明(两者都是 1.2.1,XSPEC-460 R5)。** 个人、跨项目、可识别的信息(谁负责什么、怎么连到某个环境)不是这里的记忆条目:它们属于用户自己的 AI 工具记忆。项目之间的协调(谁在等谁)是开放工作,不是记忆,并指向 `open-work-tracking`。这两份标准的 zh-TW 与 zh-CN 译本本来就落后(1.0.0 与 1.1.0),现在仍然落后;只在它们里面加了这一段。
67
+ - **`uds check` 在个人技能与项目里装的 UDS 技能同名时警告(XSPEC-465 R1)。** Claude Code 对同一个名称只执行一个技能,而且个人层(`~/.claude/skills/`)优先级高于项目层(`.claude/skills/`,`uds init --skills-location project` 与 `uds update --apply --skills` 把 UDS 技能装在这里),所以采用者自己的 `plan`、`push` 或 `commit` 会静默盖掉 UDS 那个:没有错误、没有消息。`uds check` 现在会比对两个文件夹、点名每一组、说明执行的是个人那个,并说明怎么解(把你的技能改名,或删掉 UDS 那个);`uds init` 与 `uds update --apply --skills` 在安装结尾打印同一条警告。名称是 `SKILL.md` frontmatter 的 `name:`,没有就用文件夹名称,两者都会比对(文件夹名称同样能调用技能)。只是信息:有无 `--ci` 都不改变判定与退出码;个人文件夹不存在、不是文件夹、读不到或 `SKILL.md` 损坏时,不打印任何东西也不失败;UDS 自己装在用户层的副本(`~/.claude/skills/.manifest.json` 的 source 是 `universal-dev-standards`)与「项目就是主目录」的情况不列入。**它看不到企业层,也看不到它运行之后才新增的个人技能,文字里也这样说:没有警告不等于没有撞名。** 插件技能(`/<插件名>:<技能名>`)与 `.claude/commands/` 文件不列入。(英文、繁体中文、简体中文。)
68
+ - **文档:`docs/user/GETTING-STARTED.md` 新增「个人技能与 UDS 技能同名时」,`skills/SKILL_NAMING.md` 新增命名规则 6(XSPEC-465 R3)。** 同一个名称出现在多处时哪个技能执行(Claude Code 技能文档,2026-10-07 读取)、这对名称通用的 UDS 技能(`plan`、`push`、`sweep`、`orchestrate`)意味着什么、怎么用 `uds check` 看见、怎么解。UDS 不为此替已发布的技能改名(改名会破坏所有既有调用);新技能应避免单一通用单词。(英文、繁体中文、简体中文;命名规则与该文件一样是中文。)
69
+ - **`open-work-tracking` 1.4.0——已问、等回复的条目由 OWT-022 判定,不由 OWT-019 判定(XSPEC-464)。** 一位用户的 17 个下一步中有 14 个是“等对方回信、等排时间、等撤销”;`uds open-work waiting` 接受这些行,`uds open-work next-action` 却拒绝同一批行,因为“等回信”没有点名任何文件、命令、测试或编号。现在,处于 `asked-awaiting` 且 OWT-022 认为齐全的行(真的 `asked-at`、不在未来、写了在等什么、写了什么解除它)是 OWT-019 的第四种结果 `waiting-on-reply`:不是违反、不算已点名、不算完成,在自己的一节里列出并显示年龄,超过 `--stale-after`(默认 7 天,未校准)标为 STALE。它不是藏身处:缺三者之一的行、`not-yet-asked` 的行、其他状态的行、写成小节标题的下一步、没有状态列的载体,判定与过去完全相同。`next-action` 以 `waiting` 所用的同一个函数读这一行的状态,所以两者不可能对同一行给出相反的结论;一个自测臂与一个涵盖中英文行的属性测试守着这件事。`uds open-work next-action` 新增选项 `--now` 与 `--stale-after`;`waiting-on-reply=N` 只在 N 不为 0 时才附在计数行尾。没有新的要求编号。冻结的 1.1.0 与 1.2.0 输出仍逐字节吻合。检查只判定这三个字段存在且格式正确,判定不了请求是否真的发出。
70
+ - **`open-work-tracking` 说明 OWT-007 的摘要可以由程序打印、完整版按需获取(XSPEC-465 R2)。** OWT-007 从未说摘要由谁产生、多长。新小节说明便宜的做法(回合结束时由程序打印简短摘要,完整版在被要求时才产生,模型不花 token)与昂贵的做法(模型在每条回复里附一张完整的表,可行但不是要求),第一种仍适用 OWT-008 与 OWT-009,并以“建议”的身份提出摘要的分类词汇(等决策、等外部回复、等 CI、固定日期到期、无人看管),直说 UDS 没有出货任何产生这种摘要的程序、本标准也没有东西检查它存在。没有新的要求编号,也没有新的检查。
71
+ - **测试版验收:一个程序在每一台机器上对已发布的包运行验收步骤(XSPEC-469 R2、R3)。** `node scripts/beta-acceptance/run.mjs --version <版本>` 把该版本从 npm 装进一次性文件夹(不是 repository 源码),执行 `scripts/beta-acceptance/steps.json` 中适用于本机操作系统的步骤——每一步有自己的文件夹与自己的一次性 home,不碰真正的 home——并写出可整份贴回的 Markdown 报告与可比对的 JSON 报告:操作系统与版本、shell、Node 与 npm 版本、Windows 控制台代码页(读不到就写「取不到」及原因,不留空)、UDS 版本,以及每一步的通过、失败、跳过(平台不符)或未确认,附输出摘要。只用 Node 标准库、不经 shell 启动程序,所以同一行命令在 PowerShell、cmd、Git Bash、zsh、bash 都能用。它是维护者工具,不进 npm 包。退出码 0=有步骤通过且没有失败;1=有步骤失败;2=无法执行(安装失败、装到别的版本、步骤文件格式错误);3=零个步骤通过——什么都没测到的执行绝不算通过。需要人眼的步骤(例如 cp950 控制台的中文显示)会在终端询问,或读取 `--answers` 文件;没有回答就记为「未确认」,不计入通过。`steps.json` 为下面每一条至少安排一步,另含 beta.6 的修复(那些修复从未在 Windows 上运行过)。这些步骤已对 beta.6 的源码与 `main` 的源码比对过(功能步骤在前者红、后者绿),并对真正已发布的 beta.6 在 macOS 上运行过一次。**未验证**:还没有任何一步在真的 Windows 机器上运行过;beta.7 的运行是第一次。
72
+ - **CI:`[Unreleased]` 的每一条都要有验收步骤,`docs/PRE-RELEASE.md` 改为生成(XSPEC-469 R1、R5)。** `node scripts/beta-acceptance/check-steps.mjs`(CI 作业「Beta Acceptance Coverage」)在 `[Unreleased]` 下的 Added、Changed 或 Fixed 条目既没有 `steps.json` 中的步骤、也没有写明「无用户可见行为」理由的 `exemptions` 项目时失败,并指名那一条。步骤用条目的开头(至少 20 个字符)指名它:改条目后半段的措辞不受影响,改开头则条目与步骤一起变红、各自被点名。`generate-pre-release.mjs` 由 `steps.json` 生成 `docs/PRE-RELEASE.md` 的「请帮忙测什么」清单(不再手写),并且只由 `scripts/beta-acceptance/reports/<版本>/` 的 JSON 报告填写「已在哪些机器验过」:没有报告的平台写「尚未验证」;来自 `--local-bin`、`--source` 或注入安装器、来自别的版本、或什么都没测到的报告,都不会填入任何一格。`--check`(同一个 CI 作业)在文档与生成结果不同时失败。
73
+ - **CI:推送到 `main` 时,端到端测试在 ubuntu、windows、macos 各跑一次(XSPEC-469 R4)。** 原本只在 pull request 且只在 Ubuntu 跑,Windows 作业只跑单元测试。pull request 维持只跑 Ubuntu,且只在 `cli/**` 有变动时。推送到 `main` 的那次运行不再被下一次推送取消(pull request 的运行仍会),因为被取消的运行和被跳过的一样不算通过。用 bash 执行 `scripts/check-*.sh` 的四个测试在 Windows 上调用 `ctx.skip()`;作业的最后一步(`scripts/ci-vitest-summary.mjs`)把跑了多少、通过、失败、跳过多少写进作业摘要,并在一个都没跑时失败(跳过不等于通过)。**未验证**:workflow 只被 YAML 解析器与测试读过,GitHub 没有运行过它,也没有 `actionlint` 可用;第一次推送到 `main` 才是第一次实跑,只在 Windows 或 macOS 会红的测试届时会让它变红。
74
+ - **`check-anti-fake-tests` 现在也会点名「预期值不独立于被测代码」的测试(XSPEC-470 R1)。** `full-coverage-testing` 过去只在断言「永远不可能失败」(`expect(true).toBe(true)`)时才叫恒真式。预期值来自被测代码本身的测试同样必然通过:`expect(total(items)).toBe(total(items))`,或 `expect(total(items)).toBe(items.reduce((s, i) => s + i.price, 0))`——同一套算式再打一遍,实作算错时它跟着一起错而照样通过。`uds init` 写到 `scripts/check-anti-fake-tests.mjs` 的扫描脚本现在把这两种形状都回报为 `tautology`(JavaScript/TypeScript:`toBe`/`toEqual`/`toStrictEqual`、chai 的 `to.equal`/`to.eql`、node 的 `assert.equal`/`strictEqual`/`deepEqual`/`deepStrictEqual`):两侧是同一个函数、同样的参数;以及预期值把被测调用自己的输入送进 `reduce`、`map`、`flatMap` 或 `filter`,且回调只用到自己的参数、不含任何字面值;只读断言本身的文本,前面几行设置过的名称一律不展开。`--json` 输出附上 `forms` 与每个断言所在的行。**判不了就沉默**:动作前后的状态比较、与第二份实作比对、名称说明是决定性/幂等/缓存/同一性的测试里比较两次调用、查写死表格的预期值(`ids.map(id => PRICES[id])`)、用字面值挑数据(`users.filter(u => u.id === 2)`)、调用里又有调用(`render(now())`、`parse(serialize(rows))`)、只把参数原样返回或浅拷贝的回调(`rows.map(r => r)`、`users.map(u => ({ ...u }))`、`pairs.map(([k, v]) => [k, v])`)、先存值、动作之后再比对(`const before = items.map(...); freezeCart(items); expect(pricesOf(items)).toEqual(before)`)、被测的值是结果的属性(`sortUsers(users).length`)、没有参数的调用、`new` 表达式、否定的比对,以及同一支测试里还有别种断言的情形(与 `expect(true).toBe(true)` 相同的「只有」规则)。在本保存库自己的 297 个测试档(4,200 支测试)上没有添加任何回报;第一版曾把「先前设置的名称」当成「同一个调用」,回报了 6 支测试,全是正当的前后比对或决定性检查,所以现在只读写在同一个叙述里的内容。`full-coverage-testing` 1.3.0 把第二种恒真式定义为「断言的预言(oracle)就是被测实作本身」,并指向 `verification-oracle`,不再另立一套独立真值的定义;附一组好坏对照例,以及脚本判不了的情形该由审查者提出的问题。扫描脚本的自我检查加入了新形状与它们的相似物,所以被削弱过的脚本会以 `2` 结束,不会照跑。**谁会看到差异:** `uds init` 在本版之后写入 `scripts/check-anti-fake-tests.mjs` 的项目;已存在的文件绝不覆写,想要这条规则请把 `templates/gates/check-anti-fake-tests.mjs` 拷贝过去。预设只警告;在 `.standards/test-policy.json` 设 `"mode": "block"` 时,新的回报可能挡下提交。**我们接受的两个代价:** 拿参考实现当预期值的差分测试和教科书例一模一样,会被点名(在同一个测试加一个对手算字面值的断言,或把文件列进 `ignore`);这条规则也很容易被绕过(把被测值包进 `Number(...)`、接 `.valueOf()` 或 `[0]`、或实参改成 `items.slice()`;对预期值做同样的事仍会被点名),它是提醒审查者的线索,不是挡得住刻意规避的闸门。**该怎么做:** 把重复的调用或重打的算式换成字面值或手算例;刻意为之的比较请放进名称就在讲这件事的测试。(XSPEC-470 R1)
75
+ - **`code-review-checklist` 1.6.0 与各 PR 范本要求每项变更写明合并风险:双向门或单向门,以及一个词的影响范围(XSPEC-470 R2)。** 双向门合并后能轻松退回;单向门不可逆或很难退回(数据迁移、删除、预设行为改变、结束码改变、对外界面改名)。添加的检查项 11 与审查者、作者的步骤都写明:单向门必须在合并**之前**让决定合并的人知情;`pr-review` 选项范本(1.1.0)与本保存库自己的 PR 范本都带有这个字段。检查清单也请审查者确认测试的预期值独立于被测代码。**谁会看到差异:** 拷贝 `pr-review` 范本或阅读检查清单的人;没有任何程序强制运行。**该怎么做:** 想要的话,把这个字段加进你的 PR 范本。(XSPEC-470 R2)
76
+
77
+ ### 变更
78
+
79
+ - 旧的 `uds update` 消息“N new standard(s) available for your level”不再提到等级:没有等级规则(manifest 的 `level` 是没有任何程序读取的残值)。
80
+ - `uds audit --report` 不会把“可用标准未安装”这项发现当成给维护者的反馈发送。
81
+ - **行为改变:`uds skills` 的输出文字改了(XSPEC-462 R1)。** 项目层与用户层安装不再标 `(deprecated)`,插件不再标 `(recommended)`,「手动安装已弃用」与「建议:迁移到 Plugin Marketplace」两段也拿掉了。取而代之的是,每次运行都以并列的两种装法收尾:装进项目(`uds init --skills-location project`、`uds update --apply --skills`;支持多种 AI 工具、有繁体与简体中文文本、跟随你装的 UDS 版本,含测试版),以及 Claude Code 插件市场(只支持 Claude Code、只有英文文本、只跟正式版、项目内不放文件)。「已弃用」这个字写于 2026-01,与 `uds check`、`uds update` 一向建议的 `uds update --apply --skills` 互相矛盾。匹配旧文字的脚本需要更新。(英文、繁体中文、简体中文)
82
+ - **`uds update` 的「Skills 有可用更新」提示**,对项目层、用户层与无法判定的安装,现在说 `更新方式:uds update --apply --skills`。它原本称这些安装已弃用、指向一个泛用的插件网址,并建议在技能文件夹里 `git pull`。技能来自插件时,现在写出的市场名是 `asia-ostrich`(`/plugin marketplace update asia-ostrich`),不再是 `anthropic-agent-skills`。
83
+ - **行为变更——对“OWT-019 违反全都是 `asked-awaiting` 且 OWT-022 认为齐全的行”的载体,`uds open-work next-action` 回 0,不再回 1(XSPEC-464)。** 那些行现在是 `waiting-on-reply`。有其他违反的载体仍回 1;没有状态列的载体与 1.3.0 的行为相同。
84
+ - **行为改变:`uds init` 与 `uds init --yes` 现在会把 UDS 技能装进项目(XSPEC-462 之后的 XSPEC-468 R1)。** XSPEC-462 把「装进项目」定为主要路径,但 `uds init --yes` 检测到 Claude Code 时仍选插件、不写任何技能文件;在没有 AI 工具标记的文件夹则一个都不装。既有脚本运行 `uds init --yes`,现在会多出 `.claude/skills/`(Claude Code;其他检测到的工具各有自己的文件夹),`git status` 也会变长。交互提示预先勾选项目层,直接按 Enter 就会安装。要保持旧结果,请明说:`uds init --yes --skills-location marketplace`(插件:项目内不写入任何技能文件,安装结尾会说明技能从哪里来、插件做不到什么、怎么改装进项目)或 `--skills-location none`。交互提示中,取消所有勾选即为跳过。若已安装 UDS 插件,安装结尾会打印与 `uds check` 相同的「技能装了两次」警告。`uds init --help` 中 `--skills-location` 的默认值现在是 `project`。
85
+ - **行为改变:`uds init` 的命令契约步骤不再整份重写 `uds.project.yaml`(XSPEC-468 R5)。** 文件已存在、你同意覆盖时,向导原本以它询问的四个命令整份重写,其余全部消失:`open_work:`(`uds open-work` 读取的设置)、`custom:`、注释。现在问题会列出会保留的区段,默认答案仍是否;答是时只改 `commands:` 底下的 `test`、`lint`、`build`、`security` 几行(各题的默认值是文件内现有的值,留空就不动那一行),文件其余字节原样保留。不是合法 YAML 的文件无法只留一部分,所以问题会明说,并询问是否整份替换。
86
+ - **文档与提示不再推荐插件市场(XSPEC-468 R2)。** `docs/CLI-INIT-OPTIONS.md`、`docs/WINDOWS-GUIDE.md`、`docs/USAGE-MODES-COMPARISON.md`、采用指南与检查清单、`uds init` 的提示文字与较旧的设计笔记,现在写的是 XSPEC-462 的决定:装进项目是主要路径,插件是替代方式,限制写在旁边(只支持 Claude Code、只有英文技能文本、只跟正式版、项目内不放文件)。三语一致。3.2.x 的发行说明与本变更日志仍照原样引用当时的说法。`npm test` 现在会在 Markdown 文件或 CLI 自己的文字又推荐插件时失败,并指出文件名与行号。
87
+
88
+ ### 修复
89
+
90
+ - **插件设置里的技能数是错的(XSPEC-462 R3)。** `.claude-plugin/plugin.json` 写「25 comprehensive skills」、`marketplace.json` 写「23 skills」、`.claude-plugin/README.md` 列了 15 个,而插件实际加载 56 个。描述不再带数字,上面那个检查会让它保持这样。
91
+ - **`uds open-work waiting` 把列表条目里留空的字段读成被下面的 `Next action:` 那一行填满了(做 XSPEC-464 时发现)。** 在列表条目里,最后一个被认得的标签的值会一路延伸到条目结尾,所以 `- release:` 留空、接着 `- Next action: wait for the vendor reply`,会被读成有解除条件,OWT-022 于是放行一个没写解除条件的 `asked-awaiting` 条目。现在 `Next action:` 标签(内置词)会结束它前面那个值,本身也不再是字段。缺解除条件、缺在等什么或缺 `asked-at`、且下面有下一步那一行的列表条目,现在由 `waiting`(OWT-022)报告,`next-action` 也不再免除它;表格不受影响。
92
+ - **缺少中文技能文本的 UDS 会默默装英文版(XSPEC-468 R3)。** `--locale zh-tw` 或 `zh-cn` 从包内的 `locales/` 文件夹取技能文本;那个文件夹不在时,原本一声不响地复制英文技能并以 0 结束,与 XSPEC-451 的 `zh-CN` 变英文同一形态。现在 `uds init` 与 `uds update` 会说「这份 UDS 里没有 zh-TW 的技能文本,所以技能装的是英文版」,说明原因是这份 UDS 不完整或已损坏而不是网络,并给出补救命令。安装仍以英文继续,不算错误。这些文本在 npm 包内(zh-TW 约 4.6 MB、zh-CN 约 4.1 MB,由打包后的 tarball 量得),所以安装它们不需要网络:安装说明三语都写了这一点。
93
+ - **`uds init` 与 `uds update` 在文件只是被暂时锁住时会重试复制,锁不开时用白话说明(2026-10-08 的 Windows CI 发现)。** Windows 上杀毒实时扫描、搜索索引或云同步程序可能短暂占用一个文件;此时复制标准文件会以 `EBUSY: resource busy or locked, copyfile ...` 失败,`uds init` 整个安装因而回滚,但其实什么都没坏(`--locale zh-cn` 的端到端测试就在某次 CI 这样失败、下一次又通过)。现在复制标准文件与扩展文件(语系文件、语言或框架文件)时,最多重试 10 次,等待时间递增(50 毫秒、100 毫秒……最多 500 毫秒;每个文件约最多等 2.3 秒,硬上限 5 秒)。`EBUSY` 在所有平台都重试;`EPERM` 与 `EACCES` 只在 Windows 重试(杀毒会造成它们),其他系统上它们是真正的权限错误,重试无用,仍立即失败。锁一直不放开时,安装照旧回滚,消息现在会点名是哪个文件、说明被其他程序锁住、列出常见原因(杀毒扫描、搜索索引、云同步、编辑器),并建议关闭该程序或把文件夹加入杀毒排除列表后重跑命令,原始错误码也保留在文本中。本次重试**不涵盖**其他写入或复制文件的地方(技能、hooks、`github.js` 的本机复制、旧式集成文件复制、更新计划里针对非标准文件与非扩展文件的直接复制、更新备份与还原、manifest 写入),它们行为不变。`uds update` 因为用同一个函数复制标准文件而涵盖在内,但测试驱动的是 `uds init`。
94
+
20
95
  ## [6.14.0-beta.6] - 2026-10-07
21
96
 
22
97
  > **测试版**——以 `npm install -g universal-dev-standards@beta` 安装。要测什么、如何退回正式版:[docs/PRE-RELEASE.md](../../docs/PRE-RELEASE.md)。
@@ -15,7 +15,7 @@ status: current
15
15
 
16
16
  > **语言**: [English](../../README.md) | [繁體中文](../zh-TW/README.md) | 简体中文
17
17
 
18
- **版本**: 6.14.0-beta.6 (Pre-release) | **发布日期**: 2026-10-07 | **授权**: [双重授权](../../LICENSE) (CC BY 4.0 + MIT)
18
+ **版本**: 6.14.0-beta.8 (Pre-release) | **发布日期**: 2026-10-07 | **授权**: [双重授权](../../LICENSE) (CC BY 4.0 + MIT)
19
19
 
20
20
  语言无关、框架无关的软件项目文档标准。通过 AI 原生工作流,确保不同技术栈之间的一致性、质量和可维护性。
21
21
 
@@ -13,7 +13,7 @@ status: current
13
13
  <!-- UDS_SUPPORTED_VERSIONS_START -->
14
14
  | 版本 | 支持状态 |
15
15
  |------|--------|
16
- | 6.14.0-beta.6 | ✅ 预发布版本 |
16
+ | 6.14.0-beta.8 | ✅ 预发布版本 |
17
17
  | 6.13.1 | ✅ 最新正式版 |
18
18
  | < 6.0.0 | ❌ 已终止支持 |
19
19
  <!-- UDS_SUPPORTED_VERSIONS_END -->
@@ -74,7 +74,7 @@ status: current
74
74
  | documentation-guide | docs, README |
75
75
  | requirement-assistant | spec, SDD, 新功能 |
76
76
 
77
- **部署方式**:通过 Plugin Marketplace 或手动复制安装为 Skills。
77
+ **部署方式**:装进项目(主要路径)、通过 Claude Code 插件市场(替代方式,有限制)或手动复制,安装为 Skills。
78
78
 
79
79
  > 详细分类请参阅 [STATIC-DYNAMIC-GUIDE.md](../../../adoption/STATIC-DYNAMIC-GUIDE.md)。
80
80
 
@@ -86,10 +86,13 @@ status: current
86
86
 
87
87
  已制作为 Claude Code Skills 的规范,提供互动式 AI 辅助。
88
88
 
89
- **采用方式**:通过 Plugin Marketplace(推荐)或手动复制安装
89
+ **采用方式**:装进项目(主要路径)、通过 Claude Code 插件市场(替代方式,有限制:只支持 Claude Code、只有英文技能文本、只跟正式版、项目内不放文件),或手动复制安装
90
90
 
91
91
  ```bash
92
- # Plugin Marketplace(推荐)
92
+ # 装进项目(主要路径)
93
+ npx universal-dev-standards init
94
+
95
+ # 插件市场(替代方式,有限制)
93
96
  /plugin marketplace add AsiaOstrich/universal-dev-standards
94
97
  /plugin install universal-dev-standards@asia-ostrich
95
98
 
@@ -237,7 +240,13 @@ Copy-Item <source-file> .standards\
237
240
 
238
241
  ### 步骤二:安装 Skills
239
242
 
240
- **推荐:Plugin Marketplace**
243
+ **主要路径:装进项目**(支持多种 AI 工具、有繁体与简体中文文本、跟随你装的 UDS 版本)
244
+ ```bash
245
+ npx universal-dev-standards init # 新项目
246
+ npx universal-dev-standards update --apply --skills # 已设置好的项目
247
+ ```
248
+
249
+ **替代方式(有限制):Claude Code 插件市场**(只支持 Claude Code、只有英文技能文本、只跟正式版、项目内不放文件)
241
250
  ```bash
242
251
  /plugin marketplace add AsiaOstrich/universal-dev-standards
243
252
  /plugin install universal-dev-standards@asia-ostrich
@@ -168,7 +168,13 @@ status: current
168
168
 
169
169
  安装为 Claude Code Skills:
170
170
 
171
- **推荐:Plugin Marketplace**
171
+ **主要路径:装进项目**(支持多种 AI 工具、有繁体与简体中文文本、跟随你装的 UDS 版本)
172
+ ```bash
173
+ npx universal-dev-standards init # 新项目
174
+ npx universal-dev-standards update --apply --skills # 已设置好的项目
175
+ ```
176
+
177
+ **替代方式(有限制):Claude Code 插件市场**(只支持 Claude Code、只有英文技能文本、只跟正式版、项目内不放文件)
172
178
  ```bash
173
179
  /plugin marketplace add AsiaOstrich/universal-dev-standards
174
180
  /plugin install universal-dev-standards@asia-ostrich
@@ -28,7 +28,13 @@ status: current
28
28
 
29
29
  确保安装所有 skills:
30
30
 
31
- **推荐:Plugin Marketplace**
31
+ **主要路径:装进项目**(支持多种 AI 工具、有繁体与简体中文文本、跟随你装的 UDS 版本)
32
+ ```bash
33
+ npx universal-dev-standards init # 新项目
34
+ npx universal-dev-standards update --apply --skills # 已设置好的项目
35
+ ```
36
+
37
+ **替代方式(有限制):Claude Code 插件市场**(只支持 Claude Code、只有英文技能文本、只跟正式版、项目内不放文件)
32
38
  ```bash
33
39
  /plugin marketplace add AsiaOstrich/universal-dev-standards
34
40
  /plugin install universal-dev-standards@asia-ostrich
@@ -25,14 +25,24 @@ status: current
25
25
 
26
26
  ## Skills 安装
27
27
 
28
- ### 选项 A:Plugin Marketplace(推荐)
28
+ ### 选项 A:装进项目(主要路径)
29
+
30
+ 支持多种 AI 工具、有繁体与简体中文文本、跟随你装的 UDS 版本。
31
+
32
+ ```bash
33
+ npx universal-dev-standards init
34
+ ```
35
+
36
+ ### 选项 B:Plugin Marketplace(替代方式,有限制)
37
+
38
+ 只支持 Claude Code、只有英文技能文本、只跟正式版、项目内不放文件。
29
39
 
30
40
  ```bash
31
41
  /plugin marketplace add AsiaOstrich/universal-dev-standards
32
42
  /plugin install universal-dev-standards@asia-ostrich
33
43
  ```
34
44
 
35
- ### 选项 B:手动复制(macOS / Linux)
45
+ ### 选项 C:手动复制(macOS / Linux)
36
46
 
37
47
  ```bash
38
48
  # Copy only Level 1 skills
@@ -40,7 +50,7 @@ cp -r universal-dev-skills/skills/ai-collaboration-standards ~/.claude/skills/
40
50
  cp -r universal-dev-skills/skills/commit-standards ~/.claude/skills/
41
51
  ```
42
52
 
43
- ### 选项 C:手动复制(Windows PowerShell)
53
+ ### 选项 D:手动复制(Windows PowerShell)
44
54
 
45
55
  ```powershell
46
56
  # Copy only Level 1 skills
@@ -27,7 +27,13 @@ status: current
27
27
 
28
28
  安装额外的等级二 skills:
29
29
 
30
- **推荐:Plugin Marketplace**
30
+ **主要路径:装进项目**(支持多种 AI 工具、有繁体与简体中文文本、跟随你装的 UDS 版本)
31
+ ```bash
32
+ npx universal-dev-standards init # 新项目
33
+ npx universal-dev-standards update --apply --skills # 已设置好的项目
34
+ ```
35
+
36
+ **替代方式(有限制):Claude Code 插件市场**(只支持 Claude Code、只有英文技能文本、只跟正式版、项目内不放文件)
31
37
  ```bash
32
38
  /plugin marketplace add AsiaOstrich/universal-dev-standards
33
39
  /plugin install universal-dev-standards@asia-ostrich
@@ -146,6 +146,7 @@ status: stale
146
146
  - Test names describe scenarios
147
147
  - Assertions are clear
148
148
  - No flaky tests
149
+ - 预期值独立于被测代码:字面值、手算例或规格——不是同一个调用再写一次,也不是同一套算式再敲一遍(见[禁止:恒真断言](full-coverage-testing.md))
149
150
 
150
151
  - [ ] **测试覆盖率维持**
151
152
  - Coverage not decreased
@@ -252,6 +253,19 @@ status: stale
252
253
 
253
254
  ---
254
255
 
256
+ ### 11. 合并风险(可逆性)
257
+
258
+ - [ ] **变更写明了它的门与影响范围**
259
+ - **双向门**:合并后能轻松退回
260
+ - **单向门**:无法退回或很难退回——数据迁移、删除、默认行为改变、退出码改变、对外接口改名
261
+ - **影响范围**:用一个词说明波及多远(例如 `docs`、`cli`、`adopters`)
262
+
263
+ - [ ] **单向门在合并前已让决策者知情**
264
+ - 决定要不要合并的人,已在 PR 描述或交付报告中被告知这个变更无法轻易退回
265
+ - 字段缺漏时,请对方补上;不要只凭差异内容推测是哪一种门
266
+
267
+ ---
268
+
255
269
  ## 审查评论类型
256
270
 
257
271
  Use these prefixes to clarify comment intent:
@@ -323,6 +337,7 @@ Is there a specific reason for this approach?
323
337
  1. Read PR description and linked issues
324
338
  2. Understand WHY the change is needed
325
339
  3. Review design/spec documents if linked
340
+ 4. 阅读“合并风险”字段(门与影响范围);若是单向门,确认决策者在合并前已知情
326
341
 
327
342
  #### Step 2: 高层级审查
328
343
 
@@ -360,6 +375,7 @@ Is there a specific reason for this approach?
360
375
  2. **本地执行测试**
361
376
  3. **检查 CI 状态**
362
377
  4. **撰写清楚的 PR 描述**
378
+ 5. **写明合并风险**——门(双向或单向)与影响范围,一个词
363
379
 
364
380
  #### 审查期间
365
381
 
@@ -646,6 +662,7 @@ All PRs must pass:
646
662
  │ ✓ Errors - Properly handled? │
647
663
  │ ✓ Docs - Updated? │
648
664
  │ ✓ Dependencies - Necessary? │
665
+ │ ✓ Merge danger - One-way door told? │
649
666
  └─────────────────────────────────────────┘
650
667
 
651
668
  Comment Prefixes:
@@ -563,6 +563,15 @@ AI 加载 developer-memory.ai.yaml
563
563
 
564
564
  ---
565
565
 
566
+ ## 边界:本标准不放什么
567
+
568
+ 下面两种信息不在本标准的范围内,写进这里是错的:
569
+
570
+ - **个人、跨项目、可识别的信息**(谁负责什么、怎么连到某个环境)。去标识化(见上方的 schema)会把这些剥掉,所以它们不能是一条记忆条目。它们属于用户自己的 AI 工具的记忆——那种记忆绑定该用户与该机器,不被分享。
571
+ - **项目之间的协调**(哪件工作在等哪件工作)。那是开放工作,不是记忆:见 [Open Work Tracking](open-work-tracking.md)(OWT-027–OWT-029)。
572
+
573
+ ---
574
+
566
575
  ## 版本历史
567
576
 
568
577
  | 版本 | 日期 | 变更 |
@@ -1,9 +1,9 @@
1
1
  ---
2
2
  source: ../../../core/full-coverage-testing.md
3
- source_version: 1.2.0
4
- translation_version: 1.2.0
5
- last_synced: 2026-10-06
6
- source_hash: 1fe2966d8684
3
+ source_version: 1.3.0
4
+ translation_version: 1.3.0
5
+ last_synced: 2026-10-08
6
+ source_hash: 6962df9f7135
7
7
  status: current
8
8
  ---
9
9
 
@@ -12,7 +12,7 @@ status: current
12
12
  > **Language**: [English](../../../core/full-coverage-testing.md) | [繁體中文](../../zh-TW/core/full-coverage-testing.md) | 简体中文
13
13
 
14
14
  > **AI 最优化版本**: `ai/standards/full-coverage-testing.ai.yaml`
15
- > **XSPEC**: XSPEC-178、XSPEC-444(R2、R5——提交前警告与随附闸门脚本)
15
+ > **XSPEC**: XSPEC-178、XSPEC-444(R2、R5——提交前警告与随附闸门脚本)、XSPEC-470(R1——恒真式=预期值不独立)
16
16
  > **取代**: 金字塔门槛模型(UT≥80%、IT≥70%、E2E 仅 happy-path)
17
17
 
18
18
  ## 概述
@@ -61,18 +61,58 @@ Coverage improved: 91.3% → 92.0%. New baseline set.
61
61
 
62
62
  ### 禁止:恒真断言(Tautology Assertions)
63
63
 
64
- 无论行为如何都会通过的断言,提供的是虚假覆盖率。
64
+ 断言若不可能与实现产生分歧,提供的就是虚假覆盖率。恒真断言有两种:
65
+
66
+ 1. **恒为真**——不管程序做什么都会通过:`expect(true).toBe(true)`、`assert 200 == 200`。
67
+ 2. **预期值不独立**——预期值由被测的代码产生,或由测试里再写一遍的同一套逻辑产生。实现正确时它会通过;实现与那份副本以同样方式出错时,它照样通过。
68
+
69
+ 第二种用 [`verification-oracle`](verification-oracle.md) 的词汇定义:断言的**预言(oracle)**是“说明正确答案是什么”的来源,恒真式就是**预言本身就是被测实现**的断言。本标准不另立第二套“独立真值”定义,直接采用该标准的:登记的真值案例、已知的字面值、手算例,或规格(见其 *Oracle-ability Spectrum*)。
65
70
 
66
71
  ```typescript
67
72
  // ❌ FORBIDDEN — always passes, tests nothing
68
73
  expect(true).toBe(true)
69
74
  expect(result).toBeDefined() // without specific value
70
75
 
71
- // ✅ REQUIRED — verifies actual behavior
76
+ // ❌ FORBIDDEN — the oracle is the implementation
77
+ expect(countInstalled(manifest)).toBe(countInstalled(manifest)) // the same call on both sides
78
+ expect(countInstalled(manifest)).toBe(manifest.standards.filter(s => s.installed).length) // the same logic, typed again
79
+ // ^ 这一例要靠审查者判断:自动检查只抓下方《随附扫描脚本判定什么、哪些留给审查者》列出的子集,这一例不在其中
80
+
81
+ // ✅ REQUIRED — a value that was decided before the code ran
72
82
  expect(result).toBe(90)
73
83
  expect(result).toEqual({ discount: 10, total: 90 })
84
+ expect(countInstalled({ standards: [{ id: 'a', installed: true }, { id: 'b', installed: false }] })).toBe(1)
74
85
  ```
75
86
 
87
+ 并非每个“两个算出来的值互相比较”都是恒真式。下列是正常测试,**不会**被报告:
88
+
89
+ | 看起来相似 | 为什么它是真测试 |
90
+ |------------|------------------|
91
+ | 动作之后 `expect(snapshot(dir)).toEqual(before)` | 问的是“有没有任何东西变动?”——两个值取自不同时间点 |
92
+ | `expect(parse(a)).toEqual(parseWithOldEngine(a))` | 预言是另一份独立写成的实现 |
93
+ | 名称就是在讲确定性的测试里 `expect(hash(x)).toBe(hash(x))` | 比较两次调用正是这个测试的目的 |
94
+ | `report` 与 `rows` 来自不同数据路径时的 `expect(report.total).toBe(rows.reduce(...))` | 两个来源之间的对账 |
95
+
96
+ #### 随附扫描脚本判定什么、哪些留给审查者
97
+
98
+ `scripts/check-anti-fake-tests.mjs`(见下方《两个扫描脚本》)只点名光看文本就能判定的两种形状。它读 **JavaScript/TypeScript**(`toBe`、`toEqual`、`toStrictEqual`、chai 的 `to.equal`/`to.eql`、node 的 `assert.equal`/`strictEqual`/`deepEqual`/`deepStrictEqual`):
99
+
100
+ | 形状 | 示例 | 报告条件 |
101
+ |------|------|----------|
102
+ | **同一个调用(same call)** | `expect(total(items)).toBe(total(items))` | 两侧是同一个函数、同样的参数(调用里没有另一个调用或 `new`),写在同一条语句里,且测试名称不是在讲“比较两次调用”(确定性、幂等、缓存、同一性) |
103
+ | **重算(recomputed)** | `expect(total(items)).toBe(items.reduce((s, i) => s + i.price, 0))` | 被测调用吃一个输入,预期值把同一个输入(就是实参本身,如 `items.reduce`,不是它的某个字段)送进 `reduce`、`map`、`flatMap` 或 `filter`,且回调只用到自己的参数(外加 `Math`、`Number`、`String` 这类纯内建)、不含任何字面值、不是单纯的复制(`(x) => x`、`(x) => ({ ...x })`);被测调用是单一调用,里面没有别的调用或 `new`,后面也没有接 `.length` 之类的属性访问。只读断言本身的文本:前面几行设置过的名称一律不展开 |
104
+
105
+ 下列看起来相似的写法**刻意放过**,因为光看文本分不出它们和正当测试的差别:`expect(priceOf(ids)).toEqual(ids.map(id => KNOWN_PRICES[id]))`(预期值查写死的价目表,是独立来源);`expect(activeOf(users)).toEqual(users.filter(u => u.id === 2))`(字面值是测试作者提供的知识);`expect(render(now())).toBe(render(now()))`(两次 `now()` 是两个值,两侧不一定相等);`expect(parse(serialize(rows))).toEqual(rows.map(r => r))`(往返测试:被测调用里还有调用);`expect(clone(input)).toEqual(input.map(x => x))`(只把参数原样返回、或把参数浅拷贝的回调(如 `u => ({ ...u })`)、或把解构参数原样组回同一形状的回调(如 `([k, v]) => [k, v]`),是复制而不是逻辑;`filter(x => x)` 按真假值筛选,是有逻辑的,但光看文本分不出它和复制的差别,所以一并放过);`expect(sortUsers(users).length).toBe(users.filter(u => u.name).length)`(被测的值是结果的属性,哪一侧才对光看文本判不出)。`const before = items.map(i => i.price); freezeCart(items); expect(pricesOf(items)).toEqual(before)`(前面几行设置的名称存的是较早时刻的值,中间发生的事正是这个测试要问的;“同一调用”也是这样读的)。原则是:拿不准宁可漏抓,不可误报。
106
+
107
+ **两个已接受、不隐瞒的代价。**
108
+
109
+ 1. **差分测试会被点名。** 拿参考实现当预期值的测试,`expect(fastTotal(items)).toBe(items.reduce((s, i) => s + i.price, 0))`,文本上和教科书例一模一样,所以扫描脚本会点名它。这种测试是正当的(见上表“预言是另一份独立写成的实现”);处理方式有二:在同一个测试里另外加一个对手算字面值的断言(只有在测试的所有断言都不是真断言时才报告),或把该文件列进 `.standards/test-policy.json` 的 `ignore`(这会让整个文件不再被这个脚本的任何检查看到,且 `ignore` 不收理由,请在注释写明)。测试名称写“与参考实现一致”**不能**豁免,`exempt` 清单也不适用于这个脚本(它属于“改了代码却没有测试”的检查)。
110
+ 2. **这条规则很容易被绕过。** 把**被测值**包进 `Number(...)`、在它后面接 `.valueOf()` 或 `[0]`、把实参改成 `items.slice()`,扫描脚本就看不到了。(对**预期值**做同样的事没有用:照样会被点名。)它是提醒审查者的线索,不是挡得住刻意规避的闸门,写测试的是 AI 代理时尤其如此:扫描干净不能当成预期值独立的证据。下面审查者的问题才是控制手段,脚本只指出最容易判的情形。
111
+
112
+ 与 `expect(true).toBe(true)` 相同,只有在测试的**所有**断言都不是真断言时才报告;自我比较旁边还有一个对字面值的断言,就留给审查者。文本判不了的,扫描脚本保持沉默——会乱叫的扫描脚本迟早被关掉。
113
+
114
+ 其余一律是**审查者的判断题**,在代码审查时问(见[代码审查检查清单](code-review-checklist.md)):这个预期值从哪里来?能不能靠运行被测代码得到?如果实现错得跟测试自己的算式一样,这个测试还会过吗?扫描脚本不判的典型情形:手写循环重新推导答案、包着实现的辅助函数、拿实现第一次的输出当快照,以及 JavaScript/TypeScript 以外的所有语言。
115
+
76
116
  ### 禁止:Mock 核心业务逻辑
77
117
 
78
118
  Mock 自己的代码,意味着业务逻辑从未真正执行。
@@ -247,7 +287,7 @@ legacy 降级模式(外部服务失败时的 fallback、重试、部分结果
247
287
 
248
288
  | 脚本 | 找什么 |
249
289
  |------|--------|
250
- | `scripts/check-anti-fake-tests.mjs` | **没有断言**的测试;唯一的断言是**恒真式**的测试(`expect(true).toBe(true)`、`assert 200 == 200`);**每个测试都被跳过或标为 todo** 的测试文件 |
290
+ | `scripts/check-anti-fake-tests.mjs` | **没有断言**的测试;唯一的断言是**恒真式**的测试(`expect(true).toBe(true)`、`assert 200 == 200`;JavaScript/TypeScript 另含“预期值就是被测的同一个调用”或“以同一个输入经 `reduce`/`map`/`filter` 重算而得”,见《禁止:恒真断言》);**每个测试都被跳过或标为 todo** 的测试文件 |
251
291
  | `scripts/check-stubs.mjs` | `// WARNING: STUB` 标记;声称**尚未实现**的函数体(`raise NotImplementedError`、`todo!()`、`TODO()` 等)而旁边没有标记;函数体**为空**的具名函数而旁边没有标记 |
252
292
 
253
293
  - 纯 Node、零依赖、不预设任何测试框架。它们是**你的文件**:可以改、可以接入 CI。单独运行时,找到东西就以非 0 退出——`node scripts/check-stubs.mjs` 就是本标准部署闸门所说的 pre-push/部署闸门。
@@ -1,9 +1,9 @@
1
1
  ---
2
2
  source: ../../../core/pipeline-security-gates.md
3
- source_version: 1.0.0
4
- translation_version: 1.0.0
5
- last_synced: 2026-07-08
6
- source_hash: b234d1eb2344
3
+ source_version: 1.1.0
4
+ translation_version: 1.1.0
5
+ last_synced: 2026-10-07
6
+ source_hash: a1e0a4792a90
7
7
  status: current
8
8
  ---
9
9
 
@@ -22,6 +22,7 @@ status: current
22
22
  ## 核心原则
23
23
 
24
24
  - **密钥扫描在 pre-commit**:所有包含密钥的提交都必须被阻断,不得例外
25
+ - **密钥扫描器自身的行为也要写明**:输出不得打印被匹配到的密钥值;扫描器跑不起来视同闸门失败(见 1.1 节)
25
26
  - **SAST 在构建后**:Critical 和 High 等级发现阻断 pipeline
26
27
  - **SCA + SBOM 在打包阶段**:追踪依赖组件风险并生成物料清单
27
28
  - **Attestation 验证在发布前**:打包后、部署前 MUST 验证 artifact 的 checksum、签名与 SLSA provenance(消费 supply-chain-attestation 标准的产出,不得「生成 SBOM 却不验证」)
@@ -44,6 +45,65 @@ status: current
44
45
 
45
46
  **重要**:此闸门必须在代码进入版本控制前执行,一旦密钥进入 git 历史便需要完整的密钥轮换流程。
46
47
 
48
+ ### 1.1 扫描器自身的三个行为(1.1.0 新增)
49
+
50
+ 上表讲「扫描什么、何时阻断」;本节讲**扫描器本身**必须怎么表现。以下三条都以本标准既有的两条原则为前提:
51
+ 「安全闸门失败 = pipeline 失败」与「禁止静默跳过安全闸门」。
52
+
53
+ | 编号 | 强度 | 要求 |
54
+ |------|------|------|
55
+ | **PSG-1** | 必须(MUST) | 扫描的输出——终端、CI 日志、报告文件——**不得包含被匹配到的密钥值本身**,只能指出文件、行号与规则名称 |
56
+ | **PSG-2** | 必须(MUST) | 扫描器**无法执行**视同闸门失败,**必须阻断**提交/pipeline,不得放行 |
57
+ | **PSG-3** | 建议(SHOULD) | 团队**自己编写**的检测规则,每一条都有一个应被抓到(红)与一个不应被误报(绿)的测试样本,样本在测试中执行 |
58
+
59
+ #### PSG-1 输出不得打印被匹配到的密钥值
60
+
61
+ 理由:扫描日志会被贴进聊天室与工单。闸门把密钥值打印在输出里,等于把已被拦下的密钥再泄漏一次。
62
+
63
+ 工具注记(只写已查证的):
64
+
65
+ | 工具 | 注记 | 依据 |
66
+ |------|------|------|
67
+ | gitleaks | 官方 README 的示例输出(`gitleaks git -v`,未加 `--redact`)含 `Secret:` 一行,打印被匹配到的值全文;`--redact` 参数的说明为「redact secrets from logs and stdout」。README 未说明 `--redact` 是否也涵盖 `--report-path` 生成的报告文件,**采用者须自行确认** | gitleaks 官方 README,2026-10-07 读取 |
68
+ | detect-secrets | 默认输出行为**本标准未查证,采用者须自行确认** | — |
69
+ | trufflehog | 默认输出行为**本标准未查证,采用者须自行确认** | — |
70
+
71
+ 判定程序(示意,三行):
72
+
73
+ 1. 建一个含**假**密钥的文件(示意记法:`FAKE-SECRET-DO-NOT-USE-0000`;实际样本须是**你自己的闸门会匹配的格式**——例如自写一条 canary 规则,或工具文档列出的测试样式——且必须是假值,不得是任何真实服务的有效凭证),加入 staging 后执行闸门,**先确认闸门确实阻断**。
74
+ 2. 没阻断代表样本没被匹配,第 3 步不算数——此时输出里当然找不到它,结果是「绿得虚假」。
75
+ 3. 在终端、CI 日志、报告文件的**全部输出**搜索该假密钥字符串;找到任何一处即不合规。
76
+
77
+ #### PSG-2 扫描器跑不起来视为闸门失败
78
+
79
+ 「跑不起来」包含:可执行文件不存在、配置文件无法读取或无效、超时、非预期的退出。这些情况必须阻断,**不得**以 `|| true`、`2>/dev/null` 等方式吞掉,也不得让闸门输出「扫描通过」。
80
+
81
+ UDS 自己的先例:`uds init` 为非 Node 项目写的原生 `.git/hooks/pre-commit`,曾把每个检查接上 `2>/dev/null || true` 后打印「Pre-commit checks passed」——检查坏掉也照样放行,且藏起自己的错误。6.14.0-beta.4 修正(见 CHANGELOG 该版〈Fixed〉)。
82
+
83
+ 工具注记:gitleaks 官方 README 的〈Exit Codes〉一节写 `1 - leaks or error encountered`——发现泄漏与发生错误是**同一个退出码**,所以**区分原因要靠输出,不靠退出码**;对阻断与否,两者的结论相同。README 另说明 `--exit-code` 参数可改写「发现泄漏时」的退出码(2026-10-07 读取):把它设成 0 会让闸门在发现泄漏时放行,不得这样配置。detect-secrets、trufflehog 的退出码行为**本标准未查证,采用者须自行确认**。
84
+
85
+ 判定程序(示意,三行):
86
+
87
+ 1. 把扫描器可执行文件改名或移走,或把它的配置文件改成无效内容。
88
+ 2. 对一个**不含任何密钥**的提交执行闸门(此时若被阻断,原因只可能是扫描器跑不起来)。
89
+ 3. 提交被阻断(退出码非 0),且输出说明是扫描器无法执行;若提交被放行,或输出看起来像「扫描通过」,即不合规。
90
+
91
+ #### PSG-3 自己写的检测规则,每条要有红绿样本
92
+
93
+ 适用于团队**自己编写**的规则,包含 `secret-management-standards` 的 REQ-003 所列的最低四种:AWS access key、PEM 私钥头、通用 API token、含密码的连接字符串。只用工具内置规则、不自己写规则的团队不适用。
94
+
95
+ 道理与 `open-work-tracking` 的 OWT-015 相同:没见过失败的检查不算证据。一条从没被红样本匹配过的规则,无法证明它抓得到东西;一条没有绿样本的规则,无法证明它不会把正常代码全部拦下。
96
+
97
+ 判定程序(示意,三行):
98
+
99
+ 1. 列出团队自写的全部检测规则。
100
+ 2. 逐条找对应的一个红样本(必被匹配)与一个绿样本(不得匹配);样本须是假值。
101
+ 3. 确认样本在测试中真的执行;缺任一个即列为缺口(本条为建议,缺口不阻断)。
102
+
103
+ #### 范围的诚实注明
104
+
105
+ UDS **不发布扫描器**。上面三段是采用者在**自己的闸门**上自行验证的程序。UDS 自己的 repo 目前也没有密钥扫描(CI 与 hook 都没有用到上述三种工具)。
106
+
47
107
  ---
48
108
 
49
109
  ### 2. Post-Build — SAST(静态应用安全测试)
@@ -112,6 +112,11 @@ grep -l "API" .project-context/*.md
112
112
 
113
113
  ---
114
114
 
115
+ ## 边界:本标准不放什么
116
+
117
+ - **个人、跨项目、可识别的信息**(谁负责什么、怎么连到某个环境)不是项目上下文:这里的条目放在仓库里,会被每个 clone 它的人看到。把它们放在用户自己的 AI 工具记忆,不要放进 `.project-context/`。
118
+ - **项目之间的协调**(哪件工作在等哪件工作)是开放工作,不是上下文:见 [Open Work Tracking](open-work-tracking.md)(OWT-027–OWT-029)。
119
+
115
120
  ## 相关标准
116
121
 
117
122
  - [情境感知加载](context-aware-loading.md)