2026-08-31 08:18:28 +00:00
2 changed files with 5 additions and 5 deletions
@@ -24,7 +24,7 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安
 | --- | --- |
 | `tools/detect-clis.sh` | 列出已安裝的 AI CLI 與執行檔路徑（TSV：name / path / version；antigravity 的執行檔為 `agy`、kiro 為 `kiro-cli`） |
 | `tools/deploy.sh` | 對單一 CLI 執行安裝、更新或解除安裝（`deploy.sh [-n] {mode} {cli} {domain}...`，mode 為 install / update / uninstall）；印出每個指令與其結束碼，最後一行 `result` 標 ok 或 fail。`-n` 只印指令不執行。上表五個 CLI 的指令差異全部收在這支腳本裡。Codex 更新 `jsc-cli` 與 `jsc-hooks` 後會把舊版快取路徑補成指向新版的相容連結，避免正在跑的部署流程找不到 helper 腳本，也避免尚未重啟的工作階段在 Stop hook 階段找不到舊路徑。install 或 update 全數成功時，收尾轉呼叫 `jsc-hooks` 的 `restart-gate.sh require` 掛上重啟閘門，並印一行 `restart` 標出狀態檔位置；uninstall 不寫。尋找 `restart-gate.sh` 時優先用 `$JSC_HOME/current/jsc-hooks`、本地 clone 與 Kiro skills，最後才掃各 CLI 快取，避免部署收尾綁死單一 CLI 的版號路徑。狀態檔的路徑、格式與判讀全在 `restart-gate.sh`，這支腳本不自己拼——格式只留一個真實來源。站台取自 `GITEA_HOST`，本地 clone 目錄取自 `JSC_LOCAL_PLUGINS`，兩者的預設值見下表 |
-| `tools/check-requires.sh` | `check-requires.sh {cli} {manifest}` 檢查 manifest 的 `jsc.requires` 最低版本。沒有宣告就通過；版本不符或缺相依 plugin 就回 `status=blocked`。`deploy.sh update` 在每個 domain 更新前呼叫它，不符就跳過該 domain 並列出原因 |
+| `tools/check-requires.sh` | `check-requires.sh {cli} {manifest}` 檢查 manifest 的 `jsc.requires` 最低版本。沒有宣告就通過；版本不符或缺相依 plugin 就回 `status=blocked` 與結束碼 1。`deploy.sh update` 在每個 domain 更新前呼叫它一次：結束碼 1 只印一行 `warn`，那個 domain 照樣更新——跳過會讓落後的 domain 永遠等不到相依版本，也就永遠更新不到，真正的阻擋由 `jsc-hooks` 的 `version-guard.sh` 在技能被叫用時執行；結束碼 2 以上是檢查腳本自己出錯，讀不到結論就不當成通過，印 `skip` 並跳過該 domain |
 | `tools/write-guides.sh` | 產生這台機器專屬的更新指引 `$JSC_HOME/update-guide.md` 與移除指引 `$JSC_HOME/remove-guide.md`（`write-guides.sh [-n] {install\|update} {domain}...`），一輪部署跑一次。CLI 清單取自 `detect-clis.sh`，每支 CLI 的指令字面直接取自 `deploy.sh -n` 的輸出，所以指引寫的就是實際會跑的指令；kiro 走不走本地複製退路也依實際偵測結果標注 |
 | `tools/list-models.sh` | 讀各 CLI 設定檔列出模型（TSV：cli / model / in-use）；設定檔缺失就不輸出該 CLI 的列，一律 exit 0。設定檔位置只寫在這支腳本裡 |
 | `tools/model-config.sh` | 解析 SDLC 各階段的偏好模型鏈（`get {stage}`、`list`、`resolve {stage}` 印出目前 CLI 可用的第一個模型）；專案 `.jsc/models` 優先於 `$JSC_HOME/models.conf`，格式見 `references/model-tags.md`。鏈只影響建議與偏好順序，不影響閘門放行 |
@@ -50,7 +50,7 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安

 ### `deploy`

-技能庫批次安裝、更新、解除安裝：**偵測 CLI、版本建議、marketplace domain 清單三者併行取得** → 秀出 `jsc-hooks/hooks/version-guard.sh report` 的版本證據表，再依 `recommend` 的一行結論（`recommend<TAB>{update|none|unverifiable}`，只印這一行，不混印表格）標出推薦選項；輸出裡找不到 `recommend` 行就退回 `report` 自行推導並在回報寫明是降級路徑 → 決策樹選模式（呼叫方已確認過模式就沿用，不重問）→ 每個 CLI 一個 sub agent，**全部同時啟動**呼叫 `tools/deploy.sh` 執行原生 plugin 指令（統一 marketplace `jsc`，token `jsc-{domain}@jsc`）→ update 前逐一檢查 `jsc.requires`，版本不符就跳過該 domain 並回報缺哪一版 → Codex 更新 `jsc-cli` 與 `jsc-hooks` 時保留舊快取相容連結 → install、update 後把偵測到的 CLI 清單交給 `jsc-hooks:hooks-install`，取它的彙總結果，只自行加判一條「smoke 出現 `No such file` 一律視為更新失敗」。domain 名單動態取自 `plugins/meta` 的 marketplace.json，不硬編碼。
+技能庫批次安裝、更新、解除安裝：**偵測 CLI、版本建議、marketplace domain 清單三者併行取得** → 秀出 `jsc-hooks/hooks/version-guard.sh report` 的版本證據表，再依 `recommend` 的一行結論（`recommend<TAB>{update|none|unverifiable}`，只印這一行，不混印表格）標出推薦選項；輸出裡找不到 `recommend` 行就退回 `report` 自行推導並在回報寫明是降級路徑 → 決策樹選模式（呼叫方已確認過模式就沿用，不重問）→ 每個 CLI 一個 sub agent，**全部同時啟動**呼叫 `tools/deploy.sh` 執行原生 plugin 指令（統一 marketplace `jsc`，token `jsc-{domain}@jsc`）→ update 前逐一檢查 `jsc.requires`，版本不符只印 `warn` 並照樣更新該 domain、回報還缺哪一版，阻擋交給 `version-guard.sh` 在技能被叫用時執行；檢查腳本自己出錯才印 `skip` 跳過該 domain → Codex 更新 `jsc-cli` 與 `jsc-hooks` 時保留舊快取相容連結 → install、update 後把偵測到的 CLI 清單交給 `jsc-hooks:hooks-install`，取它的彙總結果，只自行加判一條「smoke 出現 `No such file` 一律視為更新失敗」。domain 名單動態取自 `plugins/meta` 的 marketplace.json，不硬編碼。

 ### `doctor`

@@ -61,9 +61,9 @@ Nothing passed in → run every step as written below.
   | 2 | Usage error — the mode, the CLI name or the domain list is wrong. Report it as a defect in this skill, and do not retry with a guessed argument |
   | other | Record that CLI as failed with the exit code and stderr |

-   On update, `tools/check-requires.sh {cli} {manifest}` checks each domain's `jsc.requires` before that domain is updated. A missing or too-old required jsc plugin prints a `skip` line and leaves that domain untouched. Codex update preserves old `jsc-cli` and `jsc-hooks` cache version paths as symlinks to the newest installed version, so a still-running Codex deploy can keep using its helper scripts and a still-running Codex session whose hook_run_id points at the old cache can finish without `No such file`. Antigravity cannot install from a Gitea URL, so the script clones each domain into the local plugin directory (`JSC_LOCAL_PLUGINS`, default `$JSC_HOME/plugins`) and installs from that path — keep that clone, because update pulls the same one. That default deliberately avoids a development checkout: when the directory holds uncommitted changes or unpushed commits, the script prints a `skip` line, leaves the tree untouched, and installs the on-disk content.
+   On update, `tools/check-requires.sh {cli} {manifest}` checks each domain's `jsc.requires` before that domain is updated. Exit 0 updates the domain as usual. Exit 1 — a missing or too-old required jsc plugin — prints a `warn` line and the domain **is still updated**: skipping it would leave a behind domain permanently unable to reach the version its dependency needs. The block lives one layer up, at skill invocation time, where `jsc-hooks/hooks/version-guard.sh` stops that domain's skills. Exit 4 — the manifest is unreadable, is not valid JSON, or python3 is missing — prints a `note` line and also still updates the domain: no verdict is not the same fact as behind, so it gets its own line rather than a `warn` that would send the operator hunting for a version problem that is not there. Exit 2 or any other code — a `check-requires.sh` usage error or a broken script — prints a `skip` line and leaves that domain untouched, because a checker that failed outright is not a pass. Codex update preserves old `jsc-cli` and `jsc-hooks` cache version paths as symlinks to the newest installed version, so a still-running Codex deploy can keep using its helper scripts and a still-running Codex session whose hook_run_id points at the old cache can finish without `No such file`. Antigravity cannot install from a Gitea URL, so the script clones each domain into the local plugin directory (`JSC_LOCAL_PLUGINS`, default `$JSC_HOME/plugins`) and installs from that path — keep that clone, because update pulls the same one. That default deliberately avoids a development checkout: when the directory holds uncommitted changes or unpushed commits, the script prints a `skip` line, leaves the tree untouched, and installs the on-disk content.

-   Done when every detected CLI has reported an exit code and a `result` line, and every skipped domain has a dependency reason or a local-tree reason.
+   Done when every detected CLI has reported an exit code and a `result` line, every skipped domain has a checker-failure reason or a local-tree reason, and every `warn` domain is named with the version it still has to catch up to.

 5. After install or update, call `jsc-hooks:hooks-install` and **hand it the CLI list from step 1.1**, so it does not probe the same five executables a second time. `hooks-install` still detects for itself when it receives no list — that fallback is what keeps it usable on its own.

@@ -82,7 +82,7 @@ Nothing passed in → run every step as written below.

   Done when both `wrote` lines are printed, or the failure is reported with the exit code and the paths involved.

-7. Report the run and close it, in one block. The result and any failure reason for every CLI × mode, plus every `skip` line, every Codex `compat` line, and every CLI that could not be version-checked in step 2.
+7. Report the run and close it, in one block. The result and any failure reason for every CLI × mode, plus every `skip` line, every `warn` line, every Codex `compat` line, and every CLI that could not be version-checked in step 2.

   For install or update, the same block ends with the restart instruction, in these words: 「請關閉目前的工作階段並重新啟動，新的技能內容才會載入」. `deploy.sh` recorded this round in `$JSC_HOME/restart-required.d/{cli}` — one file per CLI — and prints its path on a `restart` line; `jsc-hooks` reads only that CLI's own file and keeps reminding until that CLI restarts, with `JSC_RESTART_GATE=off` as the escape hatch. Restarting one CLI clears its own file and leaves the others' gates standing. Name the two guide paths from step 6 in that same closing block, so the operator knows where this machine's update and removal commands now live.