From 7eb179f3a120d3b392553dd3a5a76414402ceb91 Mon Sep 17 00:00:00 2001 From: Jeffery Date: Tue, 25 Aug 2026 11:52:38 +0800 Subject: [PATCH] =?UTF-8?q?docs(guidelines):=20=E6=96=B0=E5=A2=9E=E7=89=88?= =?UTF-8?q?=E6=9C=AC=E5=89=8D=E7=BD=AE=E6=AA=A2=E6=9F=A5=E8=A6=8F=E7=AF=84?= =?UTF-8?q?=E8=88=87=E8=B1=81=E5=85=8D=E6=B8=85=E5=96=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 5 (1M context) --- references/guidelines.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/references/guidelines.md b/references/guidelines.md index 752c7d3..1214af1 100644 --- a/references/guidelines.md +++ b/references/guidelines.md @@ -73,6 +73,30 @@ 頁面類型只讀自己的 `JSC_WIKI_REPO_{TYPE}`。只有該變數未設定時，才退回 `JSC_WIKI_REPO`。不得跨類型代用。 +## 版本前置檢查 + +技能組的每一支技能在被呼叫前都要確認本機版本沒有落後遠端發佈版本。判定在程式層，由 `jsc-hooks` 的 `version-guard.sh`（PreToolUse，matcher `Skill`）執行，**不靠技能內文自我約束**——寫在內文的規則，模型可以無視。 + +| 項目 | 規則 | +| --- | --- | +| 比對對象 | 遠端發佈版本（`master` 的 `plugin.json`）對本機**實際載入**版本 | +| 實際載入版本 | 讀 `installed_plugins.json` 的 `installPath` 底下那份 `plugin.json`，**不可只看註冊欄位**——兩者可能不同，只看註冊值會放過真正被載入的舊版 | +| 落後 | 擋下該次技能呼叫（exit 2），並印出更新指令 | +| 相等或超前 | 放行。開發技能組時本機本來就會超前 `master`，擋下去維護者自己動不了 | +| 查不到遠端版本 | **擋**（fail-closed）。查詢失敗會重試一次，仍失敗才擋 | +| 逃生門 | `JSC_VERSION_GUARD=off`（離線工作用），快取秒數 `JSC_VERSION_TTL`（預設 600） | + +**豁免清單**（永遠放行，改動前想清楚後果）： + +| 技能 | 為什麼不能擋 | +| --- | --- | +| `jsc-cli:deploy` | 更新整組技能的入口。擋了就沒有任何方法更新，形成死鎖 | +| `jsc-hooks:hooks-install` | 更新後要重新接線，擋了會讓更新做一半卡住 | +| `jsc-cli:models` | SDLC 階段閘門依賴它產生 `model-tags.tsv` | +| `jsc-meta:*` | 開發技能組本身的工具，擋了就修不了技能組 | + +沒有 pre-tool hook 的 CLI 接不上這道檢查，`hooks-install` 要據實回報，不得暗示每個 CLI 都有保護。 + ## Wiki 頁命名總表 所有 wiki 頁面一律採雙層命名：