universal-dev-standards 6.14.0-beta.5 → 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.
- package/README.md +13 -3
- package/bin/uds.js +32 -7
- package/bundled/ai/options/code-review/pr-review.ai.yaml +20 -1
- package/bundled/ai/standards/code-review.ai.yaml +15 -2
- package/bundled/ai/standards/commit-message.ai.yaml +6 -2
- package/bundled/ai/standards/developer-memory.ai.yaml +12 -2
- package/bundled/ai/standards/full-coverage-testing.ai.yaml +44 -6
- package/bundled/ai/standards/open-work-tracking.ai.yaml +191 -11
- package/bundled/ai/standards/pipeline-security-gates.ai.yaml +48 -3
- package/bundled/ai/standards/project-context-memory.ai.yaml +12 -2
- package/bundled/core/code-review-checklist.md +20 -2
- package/bundled/core/developer-memory.md +12 -2
- package/bundled/core/full-coverage-testing.md +44 -4
- package/bundled/core/open-work-tracking.md +156 -16
- package/bundled/core/pipeline-security-gates.md +63 -0
- package/bundled/core/project-context-memory.md +10 -2
- package/bundled/locales/zh-CN/CHANGELOG.md +75 -3
- package/bundled/locales/zh-CN/README.md +1 -1
- package/bundled/locales/zh-CN/SECURITY.md +1 -1
- package/bundled/locales/zh-CN/adoption/ADOPTION-GUIDE.md +13 -4
- package/bundled/locales/zh-CN/adoption/STATIC-DYNAMIC-GUIDE.md +7 -1
- package/bundled/locales/zh-CN/adoption/checklists/enterprise.md +7 -1
- package/bundled/locales/zh-CN/adoption/checklists/minimal.md +13 -3
- package/bundled/locales/zh-CN/adoption/checklists/recommended.md +7 -1
- package/bundled/locales/zh-CN/core/code-review-checklist.md +17 -0
- package/bundled/locales/zh-CN/core/developer-memory.md +9 -0
- package/bundled/locales/zh-CN/core/full-coverage-testing.md +48 -8
- package/bundled/locales/zh-CN/core/pipeline-security-gates.md +64 -4
- package/bundled/locales/zh-CN/core/project-context-memory.md +5 -0
- package/bundled/locales/zh-CN/docs/AVAILABLE-STANDARDS.md +70 -0
- package/bundled/locales/zh-CN/docs/CHEATSHEET.md +5 -4
- package/bundled/locales/zh-CN/docs/CLI-INIT-OPTIONS.md +25 -23
- package/bundled/locales/zh-CN/docs/FEATURE-REFERENCE.md +15 -12
- package/bundled/locales/zh-CN/docs/USAGE-MODES-COMPARISON.md +6 -6
- package/bundled/locales/zh-CN/docs/WINDOWS-GUIDE.md +7 -1
- package/bundled/locales/zh-CN/docs/user/GETTING-STARTED.md +44 -0
- package/bundled/locales/zh-CN/options/code-review/pr-review.md +13 -2
- package/bundled/locales/zh-TW/CHANGELOG.md +75 -3
- package/bundled/locales/zh-TW/README.md +1 -1
- package/bundled/locales/zh-TW/SECURITY.md +1 -1
- package/bundled/locales/zh-TW/adoption/ADOPTION-GUIDE.md +13 -4
- package/bundled/locales/zh-TW/adoption/STATIC-DYNAMIC-GUIDE.md +7 -1
- package/bundled/locales/zh-TW/adoption/checklists/enterprise.md +7 -1
- package/bundled/locales/zh-TW/adoption/checklists/minimal.md +13 -3
- package/bundled/locales/zh-TW/adoption/checklists/recommended.md +7 -1
- package/bundled/locales/zh-TW/core/code-review-checklist.md +17 -0
- package/bundled/locales/zh-TW/core/developer-memory.md +9 -0
- package/bundled/locales/zh-TW/core/full-coverage-testing.md +48 -8
- package/bundled/locales/zh-TW/core/open-work-tracking.md +90 -14
- package/bundled/locales/zh-TW/core/pipeline-security-gates.md +64 -4
- package/bundled/locales/zh-TW/core/project-context-memory.md +5 -0
- package/bundled/locales/zh-TW/docs/AVAILABLE-STANDARDS.md +70 -0
- package/bundled/locales/zh-TW/docs/CHEATSHEET.md +5 -4
- package/bundled/locales/zh-TW/docs/CLI-INIT-OPTIONS.md +25 -23
- package/bundled/locales/zh-TW/docs/FEATURE-REFERENCE.md +15 -12
- package/bundled/locales/zh-TW/docs/USAGE-MODES-COMPARISON.md +6 -6
- package/bundled/locales/zh-TW/docs/WINDOWS-GUIDE.md +7 -1
- package/bundled/locales/zh-TW/docs/user/GETTING-STARTED.md +44 -0
- package/bundled/locales/zh-TW/options/code-review/pr-review.md +13 -2
- package/bundled/skills/SKILL_NAMING.md +9 -0
- package/bundled/templates/gates/check-anti-fake-tests.mjs +305 -5
- package/package.json +3 -1
- package/src/commands/audit.js +9 -2
- package/src/commands/check.js +17 -0
- package/src/commands/deps.js +31 -1
- package/src/commands/init.js +41 -21
- package/src/commands/open-work.js +65 -6
- package/src/commands/simulate.js +20 -8
- package/src/commands/skills.js +59 -33
- package/src/commands/spec.js +14 -8
- package/src/commands/update.js +106 -66
- package/src/core/manifest.js +12 -10
- package/src/core/marketplace-sentinel.js +5 -0
- package/src/core/open-work-config.js +103 -0
- package/src/core/project-config.js +58 -38
- package/src/flows/init-flow.js +10 -0
- package/src/i18n/messages.js +264 -60
- package/src/installers/skills-installer.js +3 -1
- package/src/prompts/init.js +148 -13
- package/src/reconciler/backup-locations.js +75 -0
- package/src/reconciler/backup-manager.js +29 -45
- package/src/reconciler/index.js +62 -8
- package/src/utils/available-standards-report.js +144 -0
- package/src/utils/available-standards.js +216 -0
- package/src/utils/commit-message-judge.js +137 -0
- package/src/utils/copier.js +5 -4
- package/src/utils/deps-applicability.js +25 -0
- package/src/utils/friction-detector.js +27 -0
- package/src/utils/installed-names-ownership.js +114 -0
- package/src/utils/open-work-tracking.mjs +919 -48
- package/src/utils/sdd-header.js +65 -0
- package/src/utils/skill-frontmatter.js +102 -0
- package/src/utils/skill-name-collision.js +169 -0
- package/src/utils/skills-install-paths.js +114 -0
- package/src/utils/skills-installer.js +63 -105
- package/src/utils/standard-validator.js +98 -27
- package/src/utils/transient-fs.js +113 -0
- package/src/vibe/micro-spec.js +15 -0
- package/standards-registry.json +9 -9
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
---
|
|
2
2
|
source: ../../CHANGELOG.md
|
|
3
|
-
source_version: 6.14.0-beta.
|
|
4
|
-
translation_version: 6.14.0-beta.
|
|
5
|
-
last_synced: 2026-10-
|
|
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,78 @@ 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
|
+
|
|
68
|
+
## [6.14.0-beta.6] - 2026-10-07
|
|
69
|
+
|
|
70
|
+
> **測試版**——以 `npm install -g universal-dev-standards@beta` 安裝。要測什麼、如何退回正式版:[docs/PRE-RELEASE.md](../../docs/PRE-RELEASE.md)。
|
|
71
|
+
>
|
|
72
|
+
> **行為改變:**`uds simulate` 對不可模擬的標準以 2 結束(原為 1);`uds update` 會從 manifest 移除 UDS 無法擔保的名稱;備份移到 `.uds-backups/`;`uds.project.yaml` 內雙引號的值依 YAML 解析。
|
|
73
|
+
|
|
74
|
+
> **行為改變:**`uds update` 的備份寫到 `.uds-backups/`,不再是專案根目錄的 `.uds-backup-*`;`uds simulate` 在無法得出結論時以 2(不是 1)結束,而且 `uds simulate -s commit-message` 改為在程序內判定,不再執行 `npx commitlint`;`uds update` 會把 UDS 無法擔保的技能與命令名稱從 `manifest.skills.names` / `commands.names` 移除;`uds run` 以 YAML 讀取 `uds.project.yaml`(不合法的 YAML 現在會失敗,空白後的 `#` 會結束一個值)。
|
|
75
|
+
|
|
76
|
+
### 變更
|
|
77
|
+
|
|
78
|
+
- **行為改變——`uds update` 的備份現在集中在單一資料夾 `.uds-backups/`,不再是專案根目錄下每一步一個 `.uds-backup-<時間>/`(XSPEC-456 R7)。** git 本來就看不到舊資料夾(每個都自己隱藏),但索引器、IDE 搜尋和 grep 不讀 `.gitignore`,把裡面你檔案的副本算成專案檔案。現在每份備份都是 `.uds-backups/<時間>-<NNNN>/`,`.uds-backups/` 帶一個內容為 `*` 的 `.gitignore`(不會改你自己的 `.gitignore`)。不讀 `.gitignore` 的工具請排除 `.uds-backups`,`uds update` 結束時會提醒。舊版 UDS 留在根目錄的備份不會搬動:`--rollback`、連續步驟之間的串鏈、清理與「最近五份」上限會同時看新舊兩處,依時間由新到舊。`uds uninstall` 仍然不碰備份。
|
|
79
|
+
|
|
80
|
+
### 修正
|
|
81
|
+
|
|
82
|
+
- **`uds run` 用手寫的逐行解析器讀 `uds.project.yaml`,行尾註解因此成了指令的一部分(XSPEC-456 R1)。** `test: dotnet test X.csproj # 90 tests pass` 執行時後面多了 `# 90 tests pass`;POSIX shell 會吃掉未加引號的 `#`,`cmd.exe` 不會。現在改以 YAML(js-yaml)讀取:空白後的 `#` 結束值、加引號的值保留 `#`、以引號參數結尾的指令保留最後的引號。不合法的 YAML 會回報行號;注意 YAML 的雙引號值裡反斜線是跳脫字元,Windows 路徑請不加引號或用單引號。
|
|
83
|
+
- **行為改變——`uds simulate` 不再對根本沒被判定的東西印「Simulation Failed」(XSPEC-456 R2)。** `commit-message` 原本是餵給 `npx commitlint`;專案沒有 commitlint 設定(沒有 package.json 的 .NET 專案)時工具拒絕執行,合規與不合規的訊息得到同一個答案,還先下載了工具。現在依標準本身的規則在程序內判定(標頭 `<type>(<scope>): <subject>`、已安裝選項檔的 type、`scope-lowercase` 與 `subject-max-length` 兩條規則),不呼叫 npx、不連網,輸出會列出沒檢查的項目。結束碼:**0** 通過、**1** 不合規、**2** 沒有結論(沒有定義 simulator、標準未安裝、被委派的工具不能用)——最後一種以前是 1,印「Simulation Failed」。`--json` 帶 `status`(`pass` / `fail` / `cannot-simulate`)。被委派的 simulator 指令不再把輸入貼進 shell 字串。指令說明現在寫明哪些標準有 simulator(目前只有 `commit-message`)。回報中的「失敗卻 exit 0」在 macOS 上沒有重現,不宣稱已修。
|
|
84
|
+
- **`uds skills` 在裝了 56 個技能時只列 27 個,並寫「27 / 30」(XSPEC-456 R3)。** 篩選與分母是 `standards-registry.json` 裡手工維護的 30 個名字。現在改為 UDS 出貨的技能(含 `SKILL.md` 的資料夾),與 `init`、`update`、`check` 用同一份;manifest 記錄的其他 AI 工具的技能也會列出,摘要並說明 `uds check` 為它們追蹤了多少個技能檔案。
|
|
85
|
+
- **行為改變——`uds update` 現在會把 UDS 無法擔保的名稱從 `manifest.skills.names` 與 `manifest.commands.names` 移除(XSPEC-456 R4)。** `update --apply --skills` 移除舊版 CLI 誤拷進技能資料夾的 `_shared`、`agents`、`ai`、`tools`、`workflows` 後,`skillHashes` 乾淨了,名稱清單卻仍有 61 筆(技能只有 56 個)。名稱要同時是 UDS 出貨的技能或命令,且(安裝後)在 manifest 記錄的安裝位置真的存在才保留;市集安裝,以及無法檢查磁碟的情況,不動。既有專案在下一次 `uds update` 自動修正,已是最新版的也一樣。manifest 中記錄名稱的四個欄位是 `skills.names`、`commands.names`、`skillHashes`、`commandHashes`。
|
|
86
|
+
- **`uds spec list` 把完整的 SDD 規格列成 `draft`、標題空白(XSPEC-456 R5)。** 它把每個檔案都當微規格讀並填預設值。現在會讀 SDD 標頭——表格(`| Status | Approved (...) |`)、欄位行(`- **Status**: Archived`)或 front matter——讀不出來的印「格式:SDD(狀態未解析)」,不填預設值。未改動:`spec show`、`confirm`、`archive` 仍會用微規格模板改寫檔案。
|
|
87
|
+
|
|
88
|
+
### 新增
|
|
89
|
+
|
|
90
|
+
- **`uds deps --if-present`(XSPEC-456 R6)。** 沒有 `package.json`,或套件沒有宣告執行期相依時,印出不適用、未檢查任何東西,並以 0 結束(`--json`:`notApplicable`)。不加旗標時行為不變:沒有 `package.json` 仍以 1 結束。
|
|
91
|
+
|
|
20
92
|
## [6.14.0-beta.5] - 2026-10-06
|
|
21
93
|
|
|
22
94
|
> **測試版**——以 `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.
|
|
18
|
+
**版本**: 6.14.0-beta.7 (Pre-release) | **發布日期**: 2026-10-07 | **授權**: [雙重授權](../../LICENSE) (CC BY 4.0 + MIT)
|
|
19
19
|
|
|
20
20
|
語言無關、框架無關的軟體專案文件標準。透過 AI 原生工作流,確保不同技術堆疊之間的一致性、品質和可維護性。
|
|
21
21
|
|
|
@@ -75,7 +75,7 @@ status: current
|
|
|
75
75
|
| documentation-guide | docs, README |
|
|
76
76
|
| requirement-assistant | spec, SDD, 新功能 |
|
|
77
77
|
|
|
78
|
-
|
|
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
|
-
|
|
90
|
+
**採用方式**:裝進專案(主要路徑)、透過 Claude Code 外掛市集(替代方式,有限制:只支援 Claude Code、只有英文技能文字、只跟正式版、專案內不放檔案),或手動複製安裝
|
|
91
91
|
|
|
92
92
|
```bash
|
|
93
|
-
#
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
### 選項
|
|
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
|
-
### 選項
|
|
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
|
-
|
|
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:
|
|
@@ -325,6 +339,7 @@ Is there a specific reason for this approach?
|
|
|
325
339
|
1. Read PR description and linked issues
|
|
326
340
|
2. Understand WHY the change is needed
|
|
327
341
|
3. Review design/spec documents if linked
|
|
342
|
+
4. 閱讀「合併風險」欄(門與影響範圍);若是單向門,確認決策者在合併前已知情
|
|
328
343
|
|
|
329
344
|
#### Step 2: 高層級審查
|
|
330
345
|
|
|
@@ -362,6 +377,7 @@ Is there a specific reason for this approach?
|
|
|
362
377
|
2. **本地執行測試**
|
|
363
378
|
3. **檢查 CI 狀態**
|
|
364
379
|
4. **撰寫清楚的 PR 描述**
|
|
380
|
+
5. **寫明合併風險**——門(雙向或單向)與影響範圍,一個詞
|
|
365
381
|
|
|
366
382
|
#### 審查期間
|
|
367
383
|
|
|
@@ -648,6 +664,7 @@ All PRs must pass:
|
|
|
648
664
|
│ ✓ Errors - Properly handled? │
|
|
649
665
|
│ ✓ Docs - Updated? │
|
|
650
666
|
│ ✓ Dependencies - Necessary? │
|
|
667
|
+
│ ✓ Merge danger - One-way door told? │
|
|
651
668
|
└─────────────────────────────────────────┘
|
|
652
669
|
|
|
653
670
|
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.
|
|
4
|
-
translation_version: 1.
|
|
5
|
-
last_synced: 2026-10-
|
|
6
|
-
source_hash:
|
|
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) | 繁體中文
|
|
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
|
-
//
|
|
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 自己的程式碼,意味著業務邏輯從未真正執行。
|
|
@@ -241,7 +281,7 @@ legacy 降級模式(外部服務失敗時的 fallback、重試、部分結果
|
|
|
241
281
|
|
|
242
282
|
| 腳本 | 找什麼 |
|
|
243
283
|
|------|--------|
|
|
244
|
-
| `scripts/check-anti-fake-tests.mjs` | **沒有斷言**的測試;唯一的斷言是**恆真式**的測試(`expect(true).toBe(true)`、`assert 200 == 200
|
|
284
|
+
| `scripts/check-anti-fake-tests.mjs` | **沒有斷言**的測試;唯一的斷言是**恆真式**的測試(`expect(true).toBe(true)`、`assert 200 == 200`;JavaScript/TypeScript 另含「預期值就是被測的同一個呼叫」或「以同一個輸入經 `reduce`/`map`/`filter` 重算而得」,見〈禁止:恆真斷言〉);**每一支測試都被跳過或標為 todo** 的測試檔 |
|
|
245
285
|
| `scripts/check-stubs.mjs` | `// WARNING: STUB` 標記;宣稱**尚未實作**的函式本體(`raise NotImplementedError`、`todo!()`、`TODO()` 等)而旁邊沒有標記;本體**為空**的具名函式而旁邊沒有標記 |
|
|
246
286
|
|
|
247
287
|
- 純 Node、零相依、不預設任何測試框架。它們是**你的檔案**:可以改、可以接進 CI。單獨執行時,找到東西就以非 0 結束——`node scripts/check-stubs.mjs` 就是本標準部署閘門所說的 pre-push/部署閘門。
|