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

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 (84) 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 +51 -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 +51 -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/init.js +41 -21
  65. package/src/commands/open-work.js +65 -6
  66. package/src/commands/skills.js +19 -33
  67. package/src/commands/update.js +61 -61
  68. package/src/core/open-work-config.js +103 -0
  69. package/src/flows/init-flow.js +10 -0
  70. package/src/i18n/messages.js +237 -60
  71. package/src/installers/skills-installer.js +3 -1
  72. package/src/prompts/init.js +148 -13
  73. package/src/reconciler/index.js +42 -5
  74. package/src/utils/available-standards-report.js +144 -0
  75. package/src/utils/available-standards.js +216 -0
  76. package/src/utils/copier.js +5 -4
  77. package/src/utils/friction-detector.js +27 -0
  78. package/src/utils/open-work-tracking.mjs +919 -48
  79. package/src/utils/skill-frontmatter.js +102 -0
  80. package/src/utils/skill-name-collision.js +169 -0
  81. package/src/utils/skills-install-paths.js +114 -0
  82. package/src/utils/skills-installer.js +63 -105
  83. package/src/utils/transient-fs.js +113 -0
  84. package/standards-registry.json +9 -9
@@ -1,6 +1,6 @@
1
1
  # UDS 速查表
2
2
 
3
- > Quick reference for all UDS features | Last updated: 2026-10-07
3
+ > Quick reference for all UDS features | Last updated: 2026-10-08
4
4
 
5
5
  **Language**: [English](../../../docs/user/CHEATSHEET.md) | [繁體中文](../../zh-TW/docs/CHEATSHEET.md) | 简体中文
6
6
 
@@ -32,7 +32,7 @@
32
32
  | `uds agent` | Manage UDS agents for AI tools |
33
33
  | `uds ai-context` | Manage .ai-context.yaml configuration for AI-friendly architecture |
34
34
  | `uds mcp` | MCP server commands for AI tool integration |
35
- | `uds open-work` | Reference checks for open-work-tracking (OWT-017/018/019). Exit 0 no violation, 1 violation, 2 cannot decide (not a pass) |
35
+ | `uds open-work` | Reference checks for open-work-tracking (OWT-017 to OWT-028). Exit 0 no violation, 1 violation, 2 cannot decide (not a pass) |
36
36
  | `uds run` | Run a project command by intent (test/lint/build/security) via uds.project.yaml |
37
37
 
38
38
  ## 💬 斜线命令
@@ -355,7 +355,7 @@
355
355
  | `check-error-exit.mjs` | 🔴 沒填就是沒設定,而沒設定會 exit 2, |
356
356
  | `check-external-references.mjs` | External Reference Checker (SPEC-SELFDIAG-001 REQ- |
357
357
  | `check-home-untouched.mjs` | check-home-untouched — did this run write anywhere |
358
- | `check-open-work-tracking.mjs` | Open-work-tracking reference checks for OWT-017 / |
358
+ | `check-open-work-tracking.mjs` | Open-work-tracking reference checks for OWT-017 to |
359
359
  | `check-orphan-specs.ps1` | Check Orphan Specs |
360
360
  | `check-orphan-specs.sh` | Orphan Spec Detection Script |
361
361
  | `check-prompt-footprint.mjs` | Prompt Footprint Ratchet — DEC-117 D2/L2 |
@@ -378,6 +378,7 @@
378
378
  | `check-version-sync.ps1` | Check Version Sync |
379
379
  | `check-version-sync.sh` | Version Sync Checker |
380
380
  | `check-workflow-compliance.sh` | Thin wrapper — scripts/check-workflow-compliance.t |
381
+ | `ci-vitest-summary.mjs` | ci-vitest-summary — say how many tests ran, passed |
381
382
  | `commitlint-bilingual-rule.mjs` | commitlint-bilingual-rule.mjs — custom commitlint |
382
383
  | `convert-md-to-yaml.mjs` | Markdown to AI-YAML Conversion Script |
383
384
  | `fix-manifest-paths.ps1` | Fix Manifest Paths |
@@ -112,9 +112,8 @@ status: current
112
112
  ```
113
113
  ? Select AI agents to install Skills for:
114
114
  ── Claude Code ──
115
- ❯ ◉ Claude Code (Plugin Marketplace) - Auto-managed (Recommended)
116
115
  ◯ Claude Code (User Level) - ~/.claude/skills/
117
- ◯ Claude Code (Project Level) - .claude/skills/
116
+ ❯ ◉ Claude Code (Project Level) - .claude/skills/ (预先勾选:主要路径)
118
117
  ── OpenCode ──
119
118
  ◯ OpenCode (User Level) - ~/.config/opencode/skill/
120
119
  ◯ OpenCode (Project Level) - .opencode/skill/
@@ -148,22 +147,26 @@ status: current
148
147
 
149
148
  ### 详细说明
150
149
 
151
- #### Plugin Marketplace (推荐)
150
+ #### Plugin Marketplace(替代方式,有限制)
151
+
152
+ 它不是提示里的选项,而是 Claude Code 自己的插件系统。要用它,请取消提示中的所有勾选(或加 `--skills-location marketplace`),再在 Claude Code 内执行:
152
153
 
153
154
  ```bash
154
- # 如果尚未安装,执行:
155
155
  /plugin marketplace add AsiaOstrich/universal-dev-standards
156
156
  /plugin install universal-dev-standards@asia-ostrich
157
157
  ```
158
158
 
159
159
  **优点**:
160
- - 自动更新到最新版本
161
- - 无需手动管理
162
- - 所有 15 个 Skills 一次安装
160
+ - 由 Claude Code 更新,不用自己下命令
161
+ - 项目内不放文件
163
162
 
164
- **缺点**:
165
- - 无法锁定特定版本
163
+ **限制**:
164
+ - 只支持 Claude Code
165
+ - 只有英文技能文本(插件设置没有语言选择)
166
+ - 只跟正式版:UDS 的测试版不会有测试版技能,也无法锁定特定版本
166
167
  - 需要网络连接
168
+ - `uds check` 无法逐文件比对它的技能文件
169
+ - 项目内也装了技能时,Claude Code 会把每个技能列两次;`uds check` 会警告
167
170
 
168
171
  #### User Level
169
172
 
@@ -184,7 +187,10 @@ status: current
184
187
  - 需要手动更新
185
188
  - 不会随项目版本控制
186
189
 
187
- #### Project Level
190
+ #### Project Level(主要路径,也是 `uds init --yes` 的默认)
191
+
192
+ 繁体与简体中文技能文本都放在 npm 包内(`--locale zh-tw` 或 `zh-cn`),所以安装它们不需要网络。如果某份 UDS 缺少这些文本,UDS 会明说,并改装英文版。
193
+
188
194
 
189
195
  ```
190
196
  your-project/
@@ -208,19 +214,15 @@ your-project/
208
214
  ### 决策流程
209
215
 
210
216
  ```
211
- 是否使用 Claude Code?
217
+ 你用哪些 AI 工具?
212
218
  │
213
- ├─ 否 → 选择 None
219
+ ├─ 任何读 SKILL.md 的工具(Claude Code、OpenCode、Codex、Copilot……)
220
+ │ → Project Level(主要路径,预先勾选)
221
+ │ └─ 也想让这台机器上每个项目都有技能? → 再加 User Level
214
222
  │
215
- └─ 是 → 是否需要自动更新?
216
- │
217
- ├─ 是 → Plugin Marketplace
218
- │
219
- └─ 否 → 是否需要团队共享?
220
- │
221
- ├─ 是 → Project Level
222
- │
223
- └─ 否 → User Level
223
+ └─ 只用 Claude Code,且英文文本、只跟正式版、
224
+ 项目内不放文件都可以?
225
+ → Plugin Marketplace(--skills-location marketplace)
224
226
  ```
225
227
 
226
228
  ---
@@ -812,7 +814,7 @@ uds init --experimental
812
814
  | 选项 | 交互式提示 | CLI 参数 | 默认值 |
813
815
  |------|------------|----------|--------|
814
816
  | AI Tools | `promptAITools()` | - (检测) | 自动检测 |
815
- | Skills Location | `promptSkillsInstallLocation()` | `--skills-location` | `marketplace` |
817
+ | Skills Location | `promptSkillsInstallLocation()` | `--skills-location` | `project` |
816
818
  | Standards Scope | `promptStandardsScope()` | - | 依 Skills 决定 |
817
819
  | Format | `promptFormat()` | `-f, --format` | `ai` |
818
820
  | Git Workflow | `promptGitWorkflow()` | `--workflow` | `github-flow` |
@@ -962,7 +964,7 @@ uds init -y
962
964
  # 指定所有选项
963
965
  uds init -y \
964
966
  --format ai \
965
- --skills-location marketplace \
967
+ --skills-location project \
966
968
  --workflow github-flow \
967
969
  --merge-strategy squash \
968
970
  --output-lang english \
@@ -1,7 +1,7 @@
1
1
  # UDS 功能参考手册
2
2
 
3
3
  > Universal Development Standards - 完整功能文档
4
- > Auto-generated | Last updated: 2026-10-07
4
+ > Auto-generated | Last updated: 2026-10-08
5
5
 
6
6
  **Language**: [English](../../../docs/reference/FEATURE-REFERENCE.md) | [繁體中文](../../zh-TW/docs/FEATURE-REFERENCE.md) | 简体中文
7
7
 
@@ -15,9 +15,9 @@
15
15
  4. [代理](#agents) (5)
16
16
  5. [工作流程](#workflows) (5)
17
17
  6. [核心规范](#core-standards) (153)
18
- 7. [脚本](#scripts) (64)
18
+ 7. [脚本](#scripts) (65)
19
19
 
20
- **Total Features: 358**
20
+ **Total Features: 359**
21
21
 
22
22
  ---
23
23
 
@@ -48,7 +48,7 @@
48
48
  | `--lang` | Language extension (csharp, php) |
49
49
  | `--framework` | Framework extension (fat-free) |
50
50
  | `--locale` | Locale extension (zh-tw) |
51
- | `--skills-location` | Skills location (marketplace, user, project, none) [default: marketplace] |
51
+ | `--skills-location` | Skills location (project, user, marketplace, none) [default: project] |
52
52
  | `--content-mode` | Content mode for integration files (minimal, index) [default: index]; full is retired and resolves to index |
53
53
  | `--agents-md` | Generate AGENTS.md universal summary |
54
54
  | `--no-agents-md` | Skip AGENTS.md generation |
@@ -156,6 +156,7 @@
156
156
  | `--force` | Force update all files, ignoring hash comparison |
157
157
  | `--prune` | Delete .standards/ files UDS wrote but no longer ships (listed without this flag; never touches files UDS did not write) |
158
158
  | `--rollback` | Rollback to the most recent backup |
159
+ | `--add-standard` | With --plan or --apply: also install this standard UDS ships and the project lacks, and record it in the manifest (repeatable; `uds update --plan` lists what is available) |
159
160
  | `--claude-target` | Switch an existing install to a different Claude Code integration target: project (CLAUDE.md) or local (CLAUDE.local.md) — moves the UDS block, keeps your content, no reinstall |
160
161
  | `--locale` | Override locale for skills install (zh-tw, zh-cn, en); also reads .uds/install.yaml + UDS_LOCALE env |
161
162
  | `--with-hooks` | Install the enforcement hooks that are missing from this already-initialized project (re-detects tools; hooks already there and your own hooks are not touched; with --plan, writes nothing; --force also overwrites edited hook scripts) |
@@ -282,7 +283,7 @@
282
283
 
283
284
  ### `uds open-work`
284
285
 
285
- **说明**: Reference checks for open-work-tracking (OWT-017/018/019). Exit 0 no violation, 1 violation, 2 cannot decide (not a pass)
286
+ **说明**: Reference checks for open-work-tracking (OWT-017 to OWT-028). Exit 0 no violation, 1 violation, 2 cannot decide (not a pass)
286
287
 
287
288
  ### `uds run`
288
289
 
@@ -470,7 +471,7 @@
470
471
  | `checkin-standards` | 1.8.0 | This standard defines quality gates that MUST be passed before committing code t |
471
472
  | `circuit-breaker` | - | |
472
473
  | `class-level-fix` | 1.1.0 | A defect is almost never alone. It is one member of a set — one flag in a dispat |
473
- | `code-review-checklist` | 1.5.0 | This standard provides a comprehensive checklist for reviewing code changes, ens |
474
+ | `code-review-checklist` | 1.6.0 | This standard provides a comprehensive checklist for reviewing code changes, ens |
474
475
  | `commit-message-guide` | 1.3.0 | Standardized commit messages improve code review efficiency, facilitate automate |
475
476
  | `container-image-standards` | 1.0.0 | **Status**: Active | **Updated**: 2026-06-17 | |
476
477
  | `container-security` | - | |
@@ -487,7 +488,7 @@
487
488
  | `deployment-standards` | 1.1.0 | This standard defines guidelines for safely deploying software to production, co |
488
489
  | `deprecation-standards` | 1.1.0 | |
489
490
  | `design-document-standards` | 1.0.0 | |
490
- | `developer-memory` | 1.2.0 | This standard defines a structured system for capturing, retrieving, and surfaci |
491
+ | `developer-memory` | 1.2.1 | This standard defines a structured system for capturing, retrieving, and surfaci |
491
492
  | `disaster-recovery-drill` | - | |
492
493
  | `documentation-lifecycle` | 1.0.0 | This standard defines **when** to update documentation, **when** to check it, an |
493
494
  | `documentation-structure` | 1.5.0 | This standard defines a consistent documentation structure for software projects |
@@ -525,18 +526,18 @@
525
526
  | `mutation-testing` | 1.1.0 | Mutation testing evaluates test suite effectiveness by injecting artificial bugs |
526
527
  | `no-cicd-deployment` | - | |
527
528
  | `observability-standards` | 1.0.0 | |
528
- | `open-work-tracking` | 1.1.0 | The deferred-item-exit standard requires that a deferred item leave its document |
529
+ | `open-work-tracking` | 1.4.0 | The deferred-item-exit standard requires that a deferred item leave its document |
529
530
  | `packaging-standards` | 1.1.0 | This standard defines a Recipe-based packaging framework that enables user proje |
530
531
  | `performance-standards` | 1.2.0 | This standard defines comprehensive guidelines for software performance engineer |
531
532
  | `pii-classification` | 1.1.0 | **Status**: Active | **Updated**: 2026-06-19 | |
532
533
  | `pipeline-integration-standards` | - | |
533
- | `pipeline-security-gates` | - | |
534
+ | `pipeline-security-gates` | 1.1.0 | |
534
535
  | `policy-as-code-testing` | - | |
535
536
  | `postmortem-standards` | 1.0.0 | |
536
537
  | `prd-standards` | 1.0.0 | **Status**: Active | **Updated**: 2026-06-17 | |
537
538
  | `privacy-standards` | 1.1.0 | |
538
539
  | `product-metrics-standards` | 1.0.0 | **Status**: Active | **Updated**: 2026-06-17 | |
539
- | `project-context-memory` | 1.2.0 | This standard defines a structured system for capturing, retrieving, and enforci |
540
+ | `project-context-memory` | 1.2.1 | This standard defines a structured system for capturing, retrieving, and enforci |
540
541
  | `project-structure` | 1.2.0 | This standard defines conventions for project directory structure beyond documen |
541
542
  | `prompt-regression` | - | |
542
543
  | `property-based-testing` | - | |
@@ -620,7 +621,7 @@
620
621
  | `check-error-exit.mjs` | 🔴 沒填就是沒設定,而沒設定會 exit 2, |
621
622
  | `check-external-references.mjs` | External Reference Checker (SPEC-SELFDIAG-001 REQ-5, AC-7) |
622
623
  | `check-home-untouched.mjs` | check-home-untouched — did this run write anywhere UDS writes under HOME? |
623
- | `check-open-work-tracking.mjs` | Open-work-tracking reference checks for OWT-017 / OWT-018 / OWT-019 — repo entry point. |
624
+ | `check-open-work-tracking.mjs` | Open-work-tracking reference checks for OWT-017 to OWT-028 — repo entry point. |
624
625
  | `check-orphan-specs.ps1` | Check Orphan Specs |
625
626
  | `check-orphan-specs.sh` | Orphan Spec Detection Script |
626
627
  | `check-prompt-footprint.mjs` | Prompt Footprint Ratchet — DEC-117 D2/L2 |
@@ -643,6 +644,7 @@
643
644
  | `check-version-sync.ps1` | Check Version Sync |
644
645
  | `check-version-sync.sh` | Version Sync Checker |
645
646
  | `check-workflow-compliance.sh` | Thin wrapper — scripts/check-workflow-compliance.ts is the only copy of the |
647
+ | `ci-vitest-summary.mjs` | ci-vitest-summary — say how many tests ran, passed, failed and were skipped (dev-platform XSPEC-469 R4). |
646
648
  | `commitlint-bilingual-rule.mjs` | commitlint-bilingual-rule.mjs — custom commitlint rules enforcing the |
647
649
  | `convert-md-to-yaml.mjs` | Markdown to AI-YAML Conversion Script |
648
650
  | `fix-manifest-paths.ps1` | Fix Manifest Paths |
@@ -35,7 +35,7 @@ status: current
35
35
 
36
36
  **配置方式**:
37
37
  - 安裝时选择 `standardsScope: minimal`
38
- - Skills 位置:Plugin Marketplace(推荐)
38
+ - Skills 位置:装进项目(`--skills-location project`,默认);插件市场是有限制的替代方式(只支持 Claude Code、只有英文技能文本、只跟正式版)
39
39
  - 最小化规范文件複制到项目
40
40
 
41
41
  **包含内容**:
@@ -147,7 +147,7 @@ status: current
147
147
  | 团队同步 | 需各自安裝 | Git 同步 | 混合 |
148
148
 
149
149
  **说明**:
150
- - Skills 在 Plugin Marketplace 集中管理,但無法版本控制
150
+ - 装进项目的 Skills(默认)可以提交到 Git;来自插件市场的 Skills 由 Claude Code 管理,不在项目内
151
151
  - 规范文件可放入 Git,团队自动同步
152
152
  - 自订規則需要修改规范文件
153
153
 
@@ -180,7 +180,7 @@ status: current
180
180
 
181
181
  **配置方式**:
182
182
  ```bash
183
- uds init -y --skills-location marketplace
183
+ uds init -y --skills-location project
184
184
  # standardsScope 將自动设为 minimal
185
185
  ```
186
186
 
@@ -195,7 +195,7 @@ uds init -y --skills-location marketplace
195
195
 
196
196
  **配置方式**:
197
197
  ```bash
198
- uds init -y --skills-location marketplace --content-mode index
198
+ uds init -y --skills-location project --content-mode index
199
199
  # 在互动提示中选择多个 AI 工具
200
200
  ```
201
201
 
@@ -296,11 +296,11 @@ uds init -y --skills-location none --content-mode index
296
296
  ```
297
297
  个人开发者 + Claude Code
298
298
  └─ 推荐:僅 Skills(模式 A)
299
- └─ 配置:standardsScope: minimal + Plugin Marketplace
299
+ └─ 配置:standardsScope: minimal + 技能装进项目
300
300
 
301
301
  团队开发 + 混合工具
302
302
  └─ 推荐:Skills + 规范文件(模式 C)
303
- └─ 配置:standardsScope: full + Plugin Marketplace
303
+ └─ 配置:standardsScope: full + 技能装进项目
304
304
  └─ 规范文件納入 Git 管理
305
305
 
306
306
  企业環境 + 合規要求
@@ -59,7 +59,13 @@ npm link
59
59
 
60
60
  ## 安装 Claude Code Skills
61
61
 
62
- **推荐:Plugin Marketplace**
62
+ **主要路径:装进项目**(支持多种 AI 工具、有繁体与简体中文文本、跟随你装的 UDS 版本)
63
+ ```bash
64
+ npx universal-dev-standards init # 新项目
65
+ npx universal-dev-standards update --apply --skills # 已设置好的项目
66
+ ```
67
+
68
+ **替代方式(有限制):Claude Code 插件市场**(只支持 Claude Code、只有英文技能文本、只跟正式版、项目内不放文件)
63
69
  ```bash
64
70
  /plugin marketplace add AsiaOstrich/universal-dev-standards
65
71
  /plugin install universal-dev-standards@asia-ostrich
@@ -57,6 +57,50 @@ CLAUDE.md ← 已更新 UDS 指引(Claude Code)
57
57
 
58
58
  ---
59
59
 
60
+ ## 技能怎么装
61
+
62
+ 获取 UDS 技能有两种方式,两种都受支持。主要路径是装进项目;Claude Code 插件市场是有限制的替代方式。
63
+
64
+ > **默认是装进项目。** `uds init` 与不带 `--skills-location` 的 `uds init --yes` 会把技能装进项目(Claude Code 是 `.claude/skills/`)。6.14 之前它们一个技能文件都不装,把 Claude Code 的技能留给插件。要改用插件,请加 `--skills-location marketplace`:项目内不会写入任何技能文件,安装结尾会说明技能从哪里来。
65
+
66
+ | | 装进项目(主要路径) | Claude Code 插件市场(替代方式) |
67
+ |---|---|---|
68
+ | 指令 | 新项目:`uds init`(这是默认)<br>已设置过的项目:`uds update --apply --skills` | `/plugin marketplace add AsiaOstrich/universal-dev-standards`,再 `/plugin install universal-dev-standards@asia-ostrich` |
69
+ | AI 工具 | Claude Code、OpenCode、Cursor、Codex、Copilot、Windsurf 等 | 只支持 Claude Code |
70
+ | 技能文本的语言 | 英文、繁体中文、简体中文。中文文本放在 npm 包内,所以安装它们不需要网络;缺少这些文本的 UDS 会改装英文并明说 | 只有英文:插件设置没有语言选项 |
71
+ | UDS 版本 | 你装的那个版本,包含测试版 | 只跟正式版 |
72
+ | 项目内的文件 | 有,例如 `.claude/skills/`;`uds check` 会逐文件验证 | 没有 |
73
+ | 更新 | 升级 UDS 后,自己再运行一次 `uds update --apply --skills` | 由 Claude Code 管理插件(`/plugin`) |
74
+
75
+ **请二选一。** Claude Code 执行插件技能是 `/<插件名>:<技能名>`,执行项目技能是 `/<技能名>`,所以两种都装时每个技能会出现两次(例如 `/commit` 与 `/universal-dev-standards:commit`),而且每个技能的名称与描述每回合都会放进上下文,重复装等于重复占用。`uds check` 发现项目内有 UDS 技能、同时又装了 UDS 插件时,会打印警告;警告只是信息,不改变判定与退出码。要留项目这份,在 Claude Code 执行 `/plugin uninstall universal-dev-standards@asia-ostrich`。要留插件,删掉 `.claude/skills/` 下的 UDS 技能文件夹。
76
+
77
+ **为什么 `uds check` 与 `uds update` 叫你运行 `uds update --apply --skills`。** `uds check` 在项目里的技能文件缺失或被改过时说这句,`uds update` 在已装的技能版本落后时说这句。只有装进项目的技能有文件,UDS 才能拿它和当初装的内容比对、放回去,所以修法就是那个指令。插件不在你的项目里放文件,`uds check` 没有东西可比对,也就没有这类消息。
78
+
79
+ `uds skills` 会列出装了什么、装在哪里,并打印同样的两种方式与各自的限制。
80
+
81
+ ### 个人技能与 UDS 技能同名时
82
+
83
+ Claude Code 对同一个名称只执行一个技能,而且漏掉另一个时不会告诉你。哪一个执行,取决于各自从哪里来(Claude Code 技能文档,2026-10-07 读取):
84
+
85
+ | 同名出现在 | 执行哪一个 |
86
+ |---|---|
87
+ | 企业层(组织下发的 managed settings 目录)、个人层(`~/.claude/skills/<名称>/`)、项目层(`.claude/skills/<名称>/`) | 企业层高于个人层,个人层高于项目层 |
88
+ | 项目技能与子目录里的嵌套技能 | 两个都加载:`/<名称>` 执行项目根目录那个,嵌套那个是 `/<目录>:<名称>` |
89
+ | 插件技能与上面任一处的技能 | 两个都加载:插件技能是 `/<插件名>:<名称>` |
90
+ | 技能与 `.claude/commands/<名称>.md` 文件 | 技能 |
91
+
92
+ 技能的名称是 `SKILL.md` frontmatter 里的 `name:`,没有就用文件夹名称;文件夹名称同样能调用该技能,所以两者任一撞名都算。
93
+
94
+ **对 UDS 的意思。** `uds init --skills-location project` 与 `uds update --apply --skills` 写进去的是项目技能。你若已有同名的个人技能,执行的是你的,UDS 那个永远不会执行,而且没有任何消息说明。UDS 有几个技能名称短而通用(`plan`、`push`、`sweep`、`orchestrate`,以及文件夹叫 `commit-standards` 的 `/commit`),所以有个人技能库的人都可能遇到。UDS 不为此改名:改名会破坏所有既有的调用。
95
+
96
+ **怎么看见。** `uds check` 会拿项目里的 UDS 技能与 `~/.claude/skills/` 的技能比对,打印一条警告并点名每一组;`uds init` 与 `uds update --apply --skills` 在安装结尾打印同一条警告。它只是信息,不改变判定也不改变退出码。它有限制,而且**没有警告不等于没有撞名**:它看不到组织以企业层下发的技能(优先级高于个人层),也看不到它运行之后你才新增的个人技能,所以新增之后请再运行一次 `uds check`。
97
+
98
+ **怎么解。** 二选一。两个都留:把你的个人技能改名(文件夹名称,以及 `SKILL.md` 里的 `name:`)。只留你的:删掉 `.claude/skills/` 下那个 UDS 技能文件夹。
99
+
100
+ 给新的 UDS 技能取名以避免撞名,属于贡献者的事:见 `skills/SKILL_NAMING.md`。
101
+
102
+ ---
103
+
60
104
  ## 步骤 3 — 你的第一份 Spec(`/sdd`)
61
105
 
62
106
  在写代码之前,先创建一份 spec:
@@ -1,7 +1,8 @@
1
1
  ---
2
2
  source: options/code-review/pr-review.md
3
- source_version: 1.0.0
4
- translation_version: 1.0.0
3
+ source_version: 1.1.0
4
+ translation_version: 1.1.0
5
+ source_hash: 3fafa7b1a9c3
5
6
  status: current
6
7
  ---
7
8
 
@@ -35,6 +36,7 @@ Pull Request(PR)审查是传统的异步代码审查流程,在合并前先
35
36
  - 链接相关 issue
36
37
  - 指派适当的 reviewer
37
38
  - 确保 CI 检查通过
39
+ - 写明合并风险:门(双向或单向)与影响范围,一个词;单向门要在合并前让决策者知情
38
40
 
39
41
  ### 2. 审查
40
42
 
@@ -127,6 +129,15 @@ Brief description of changes
127
129
  - [ ] Unit tests added/updated
128
130
  - [ ] Manual testing performed
129
131
 
132
+ ## Merge Danger
133
+ Door (tick one):
134
+ - [ ] Two-way door: after merging, it can be taken back easily
135
+ - [ ] One-way door: irreversible or hard to take back (data migration, deletion, changed default behavior, changed exit code, renamed public interface)
136
+
137
+ Blast radius (one word, e.g. docs, cli, adopters):
138
+
139
+ A one-way door must be made known to whoever decides to merge before the merge.
140
+
130
141
  ## Checklist
131
142
  - [ ] Code follows project style guidelines
132
143
  - [ ] Self-review completed
@@ -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.7
4
+ translation_version: 6.14.0-beta.7
5
+ last_synced: 2026-10-08
6
6
  status: current
7
7
  ---
8
8
 
@@ -17,6 +17,54 @@ status: current
17
17
 
18
18
  ## [Unreleased]
19
19
 
20
+ ## [6.14.0-beta.7] - 2026-10-08
21
+
22
+ > **測試版**——以 `npm install -g universal-dev-standards@beta` 安裝。要測什麼、如何退回正式版:[docs/PRE-RELEASE.md](../../docs/PRE-RELEASE.md)。
23
+ >
24
+ > **行為改變:**`uds init` 與 `uds init --yes` 會把 UDS 技能裝進專案;`uds init` 的命令約定步驟保留 `uds.project.yaml` 其餘內容;`uds skills` 輸出文字改變;`uds open-work next-action` 在唯一的違規是 OWT-022 判定完整的「已詢問、等回覆」列時以 0 結束(原為 1)。
25
+
26
+ ### 新增
27
+
28
+ - **`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)。
29
+ - **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。
30
+ - **`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 不變。
31
+ - **`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 份載體逐位元組比對,含中文表頭的表格)。
32
+ - **`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` 時不出聲。
33
+ - **CI:外掛設定不得寫錯技能數(XSPEC-462 R3)。** `npm run check:plugin-manifest` 在 `.claude-plugin/plugin.json`、`marketplace.json` 或 `README.md` 的描述寫出的技能數,與 `skills/` 底下含 `SKILL.md` 的資料夾數不同時失敗。描述裡沒有數字則通過。
34
+ - **文件:`docs/user/GETTING-STARTED.md` 新增「技能怎麼裝」(XSPEC-462 R3)。** 並列兩種裝法與各自的限制、為什麼 `uds check` 與 `uds update` 建議 `uds update --apply --skills`、兩者都裝時怎麼辦(英文、繁體中文、簡體中文)。
35
+ - **`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。
36
+ - **`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 都讀得到、受版本控制的 repo,不只放在某個人的 AI 工具記憶;檢查不判定載體放在哪。涵蓋的是一個人在一台機器上的各個 session,人與人之間的共享不在這版決定。三條都是 `warning`,且未校準。
37
+ - **`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`(見下),所以兩件事共用一個設定命名空間。
38
+ - **`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 repo 之外又沒給 `--root` 時會明說,並把 `named-unresolved` 分成 `path-missing`(查過、不在)與 `not-resolvable`(指令、測試名稱、需求編號,從不查找);舊的計數行不變,新的兩個數字相加等於它。其餘既有載體上的 `next-action`、`revision`、`separation` 輸出不變:1.1.0 的凍結輸出仍逐位元組比對(拿掉新增的行之後),只有其中兩個「找不到欄位」的結束碼 2 案例變長,原文仍是它們的開頭。
39
+ - **`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),現在仍然落後;只在它們裡面加了這一段。
40
+ - **`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/` 檔不列入。(英文、繁體中文、簡體中文。)
41
+ - **文件:`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 不為此替已出貨的技能改名(改名會破壞所有既有呼叫);新技能應避免單一通用單字。(英文、繁體中文、簡體中文;命名規則與該檔一樣是中文。)
42
+ - **`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 輸出仍逐位元組吻合。檢查只判定這三個欄位存在且格式正確,判定不了請求是否真的送出。
43
+ - **`open-work-tracking` 說明 OWT-007 的摘要可以由程式印出、完整版按需取得(XSPEC-465 R2)。** OWT-007 從未說摘要由誰產生、多長。新小節說明便宜的做法(回合結束時由程式印出簡短摘要,完整版在被要求時才產生,模型不花 token)與昂貴的做法(模型在每則回覆裡附一張完整的表,可行但不是要求),第一種仍適用 OWT-008 與 OWT-009,並以「建議」的身分提出摘要的分類詞彙(等決策、等外部回覆、等 CI、固定日期到期、無人看管),直說 UDS 沒有出貨任何產生這種摘要的程式、本標準也沒有東西檢查它存在。沒有新的要求編號,也沒有新的檢查。
44
+ - **測試版驗收:一支程式在每一台機器上對已發布的套件跑驗收步驟(XSPEC-469 R2、R3)。** `node scripts/beta-acceptance/run.mjs --version <版本>` 把該版本從 npm 裝進拋棄式資料夾(不是 repository 原始碼),執行 `scripts/beta-acceptance/steps.json` 裡適用於本機作業系統的步驟——每一步有自己的資料夾與自己的拋棄式 home,不碰真正的 home——並寫出可整份貼回的 Markdown 報告與可比對的 JSON 報告:作業系統與版本、殼層、Node 與 npm 版本、Windows 主控台字碼頁(讀不到就寫「取不到」與原因,不留空)、UDS 版本,以及每一步的通過、失敗、略過(平台不符)或未確認,附輸出摘要。只用 Node 標準庫、不經殼層啟動程式,所以同一行指令在 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 的執行是第一次。
45
+ - **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 工作)在文件與產生結果不同時失敗。
46
+ - **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 會紅的測試屆時會讓它變紅。
47
+ - **`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)
48
+ - **`code-review-checklist` 1.6.0 與各 PR 範本要求每項變更寫明合併風險:雙向門或單向門,以及一個詞的影響範圍(XSPEC-470 R2)。** 雙向門合併後能輕鬆退回;單向門不可逆或很難退回(資料遷移、刪除、預設行為改變、結束碼改變、對外介面改名)。新增的檢查項 11 與審查者、作者的步驟都寫明:單向門必須在合併**之前**讓決定合併的人知情;`pr-review` 選項範本(1.1.0)與本儲存庫自己的 PR 範本都帶有這個欄位。檢查清單也請審查者確認測試的預期值獨立於被測程式碼。**誰會看到差異:** 複製 `pr-review` 範本或閱讀檢查清單的人;沒有任何程式強制執行。**該怎麼做:** 想要的話,把這個欄位加進你的 PR 範本。(XSPEC-470 R2)
49
+
50
+ ### 變更
51
+
52
+ - 舊的 `uds update` 訊息「N new standard(s) available for your level」不再提到等級:沒有等級規則(manifest 的 `level` 是沒有任何程式讀取的殘值)。
53
+ - `uds audit --report` 不會把「可用標準未安裝」這項發現當成給維護者的回饋送出。
54
+ - **行為改變:`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` 互相矛盾。比對舊文字的腳本需要更新。(英文、繁體中文、簡體中文)
55
+ - **`uds update` 的「Skills 有可用更新」提示**,對專案層、使用者層與無法判定的安裝,現在說 `更新方式:uds update --apply --skills`。它原本稱這些安裝已棄用、指向一個泛用的外掛網址,並建議在技能資料夾裡 `git pull`。技能來自外掛時,現在寫出的市集名是 `asia-ostrich`(`/plugin marketplace update asia-ostrich`),不再是 `anthropic-agent-skills`。
56
+ - **行為變更——對「OWT-019 違反全都是 `asked-awaiting` 且 OWT-022 認為齊全的列」的載體,`uds open-work next-action` 回 0,不再回 1(XSPEC-464)。** 那些列現在是 `waiting-on-reply`。有其他違反的載體仍回 1;沒有狀態欄的載體與 1.3.0 的行為相同。
57
+ - **行為改變:`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`。
58
+ - **行為改變:`uds init` 的指令契約步驟不再整份重寫 `uds.project.yaml`(XSPEC-468 R5)。** 檔案已存在、你同意覆寫時,精靈原本以它詢問的四個指令整份重寫,其餘全部消失:`open_work:`(`uds open-work` 讀的設定)、`custom:`、註解。現在問題會列出會保留的區段,預設答案仍是否;答是時只改 `commands:` 底下的 `test`、`lint`、`build`、`security` 幾行(各題的預設值是檔內現有的值,留空就不動那一行),檔案其他位元組原樣保留。不是合法 YAML 的檔案無法只留一部分,所以問題會明說,並詢問是否整份取代。
59
+ - **文件與提示不再推薦外掛市集(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 自己的文字又推薦外掛時失敗,並指出檔名與行號。
60
+
61
+ ### 修正
62
+
63
+ - **外掛設定裡的技能數是錯的(XSPEC-462 R3)。** `.claude-plugin/plugin.json` 寫「25 comprehensive skills」、`marketplace.json` 寫「23 skills」、`.claude-plugin/README.md` 列了 15 個,而外掛實際載入 56 個。描述不再帶數字,上面那個檢查會讓它維持這樣。
64
+ - **`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` 也不再免除它;表格不受影響。
65
+ - **缺少中文技能文字的 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 量得),所以安裝它們不需要網路:安裝說明三語都寫了這一點。
66
+ - **`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`。
67
+
20
68
  ## [6.14.0-beta.6] - 2026-10-07
21
69
 
22
70
  > **測試版**——以 `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-CN/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.7 (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.7 | ✅ 預發布版本 |
17
17
  | 6.13.1 | ✅ 最新正式版 |
18
18
  | < 6.0.0 | ❌ 已終止支援 |
19
19
  <!-- UDS_SUPPORTED_VERSIONS_END -->
@@ -75,7 +75,7 @@ status: current
75
75
  | documentation-guide | docs, README |
76
76
  | requirement-assistant | spec, SDD, 新功能 |
77
77
 
78
- **部署方式**:透過 Plugin Marketplace 或手動複製安裝為 Skills。
78
+ **部署方式**:裝進專案(主要路徑)、透過 Claude Code 外掛市集(替代方式,有限制)或手動複製,安裝為 Skills。
79
79
 
80
80
  > 詳細分類請參閱 [STATIC-DYNAMIC-GUIDE.md](../../../adoption/STATIC-DYNAMIC-GUIDE.md)。
81
81
 
@@ -87,10 +87,13 @@ status: current
87
87
 
88
88
  已製作為 Claude Code Skills 的規範,提供互動式 AI 輔助。
89
89
 
90
- **採用方式**:透過 Plugin Marketplace(推薦)或手動複製安裝
90
+ **採用方式**:裝進專案(主要路徑)、透過 Claude Code 外掛市集(替代方式,有限制:只支援 Claude Code、只有英文技能文字、只跟正式版、專案內不放檔案),或手動複製安裝
91
91
 
92
92
  ```bash
93
- # Plugin Marketplace(推薦)
93
+ # 裝進專案(主要路徑)
94
+ npx universal-dev-standards init
95
+
96
+ # 外掛市集(替代方式,有限制)
94
97
  /plugin marketplace add AsiaOstrich/universal-dev-standards
95
98
  /plugin install universal-dev-standards@asia-ostrich
96
99
 
@@ -238,7 +241,13 @@ Copy-Item <source-file> .standards\
238
241
 
239
242
  ### 步驟二:安裝 Skills
240
243
 
241
- **推薦:Plugin Marketplace**
244
+ **主要路徑:裝進專案**(支援多種 AI 工具、有繁體與簡體中文文字、跟著你裝的 UDS 版本)
245
+ ```bash
246
+ npx universal-dev-standards init # 新專案
247
+ npx universal-dev-standards update --apply --skills # 已設定好的專案
248
+ ```
249
+
250
+ **替代方式(有限制):Claude Code 外掛市集**(只支援 Claude Code、只有英文技能文字、只跟正式版、專案內不放檔案)
242
251
  ```bash
243
252
  /plugin marketplace add AsiaOstrich/universal-dev-standards
244
253
  /plugin install universal-dev-standards@asia-ostrich
@@ -166,7 +166,13 @@ status: current
166
166
 
167
167
  ### 部署方式
168
168
 
169
- **推薦:Plugin Marketplace**
169
+ **主要路徑:裝進專案**(支援多種 AI 工具、有繁體與簡體中文文字、跟著你裝的 UDS 版本)
170
+ ```bash
171
+ npx universal-dev-standards init # 新專案
172
+ npx universal-dev-standards update --apply --skills # 已設定好的專案
173
+ ```
174
+
175
+ **替代方式(有限制):Claude Code 外掛市集**(只支援 Claude Code、只有英文技能文字、只跟正式版、專案內不放檔案)
170
176
  ```bash
171
177
  /plugin marketplace add AsiaOstrich/universal-dev-standards
172
178
  /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