fix(cli): 部署收尾的重啟狀態檔路徑改為一支 CLI 一份 #30

2026-08-27T10:50:21Z

jiantw83 commented

2026-08-27 10:50:21 +00:00

摘要

需求描述：jsc-hooks 這一輪把部署後重啟閘門的狀態檔從全機器單一檔案 $JSC_HOME/restart-required 改為一支 CLI 一份的 $JSC_HOME/restart-required.d/{CLI 代號}（修的是並行部署互相覆寫、以及任一支 CLI 重啟就解除全部五支閘門這兩個實測缺陷）。jsc-cli 這一側跟著把部署收尾印出的路徑、更新指引的說明與設定落點清單全部對齊，不留舊路徑。
計畫名稱：無
計畫頁：無
分析頁：無

變更內容

檔案	為什麼改
`tools/deploy.sh`	`restart` 那一行印的是操作者接下來要看的檔案，改印帶 CLI 代號的路徑，印舊路徑會指向一個不存在的檔案；檔頭註解改寫成「轉呼叫 `restart-gate.sh require` 掛上這支 CLI 的閘門」
`tools/write-guides.sh`	更新指引是下一輪部署的依據，狀態檔說明改成一支 CLI 一份、重啟只清自己那份、別支的閘門不受影響
`tools/config-spec.tsv`	`/jsc-cli:doctor` 比對設定落點的依據，`$JSC_HOME/restart-required` 那一列改成 `restart-required.d` 目錄，說明改為「該 CLI 那份不存在代表這支沒有待重啟的部署」
`README.md`	「部署留在機器上的檔案」那張表同步，並訂正原本寫成「一行一次成功部署」的描述——實際是四行 key=value
`skills/deploy/SKILL.md`	第 9 步的路徑說明同步，補上只讀自己那一份、重啟一支只清自己那份，全篇維持英文
`plugin.json`、`.claude-plugin/plugin.json`、`.codex-plugin/plugin.json`	版本 0.1.9 → 0.2.0，三份同步；部署留在機器上的檔案落點改變是對外契約變更，所以走次版號

設計重點

唯一來源不搬家。 狀態檔的路徑與格式只留在 jsc-hooks/hooks/restart-gate.sh，deploy.sh 仍只轉呼叫它的 require，這一側不自己組狀態檔內容、也不重寫一份判定。這次改的全是要印給人看的路徑與說明。
失敗要講出來這件事照舊。 require 失敗時仍走 note 那一行講明「這次沒有掛上重啟閘門」；jsc-hooks 側新增的「取不到 CLI 代號回 exit 2」會直接落在同一條路徑上，不必在這裡加判斷。
指引寫的是整台機器、狀態檔寫的是單一 CLI。 更新指引照舊一輪部署寫一次，但狀態檔說明要講清楚一支一份，看指引的人才不會以為刪掉一個檔案就解除全部閘門。
config-spec.tsv 那一列的性質不變：global 的執行期暫態，備份與還原都是 none，只有路徑與說明改寫，欄位數維持 8。
版號跨存取庫成對。 這一版要搭 jsc-hooks 0.2.6 才有一支 CLI 一份的狀態檔，兩者一起發佈。

測試結果

ste100-lint.sh：本存取庫全綠。三份 manifest 版本一致為 0.2.0。sh -n 對這次改動過的 tools/deploy.sh 與 tools/write-guides.sh 通過。
grep 掃過本存取庫，舊路徑 restart-required（不帶 .d）零殘留。
tools/config-spec.tsv 每列欄位數一致為 8。
狀態檔本身的行為（一支一份、只擋自己那一支、清除只清自己那份、舊檔相容、髒值防護）在 jsc-hooks 那份 PR 實測，這一側不重複驗一次判定邏輯。
無法測試的部分：codex、copilot、antigravity、kiro 四支沒有 pre-tool hook，這道閘門在那四支上一次技能呼叫都擋不下來。那是覆蓋範圍的先天限制，不是還沒測。
這批修正尚未部署到任何 CLI。

前置 Push Request

plugins/hooks#37 plugins/hooks#37（狀態檔路徑與格式的唯一來源在 restart-gate.sh）

## 摘要 - 需求描述：`jsc-hooks` 這一輪把部署後重啟閘門的狀態檔從全機器單一檔案 `$JSC_HOME/restart-required` 改為一支 CLI 一份的 `$JSC_HOME/restart-required.d/{CLI 代號}`（修的是並行部署互相覆寫、以及任一支 CLI 重啟就解除全部五支閘門這兩個實測缺陷）。`jsc-cli` 這一側跟著把部署收尾印出的路徑、更新指引的說明與設定落點清單全部對齊，不留舊路徑。 - 計畫名稱：無 - 計畫頁：無 - 分析頁：無 ## 變更內容 | 檔案 | 為什麼改 | | --- | --- | | `tools/deploy.sh` | `restart` 那一行印的是操作者接下來要看的檔案，改印帶 CLI 代號的路徑，印舊路徑會指向一個不存在的檔案；檔頭註解改寫成「轉呼叫 `restart-gate.sh require` 掛上這支 CLI 的閘門」 | | `tools/write-guides.sh` | 更新指引是下一輪部署的依據，狀態檔說明改成一支 CLI 一份、重啟只清自己那份、別支的閘門不受影響 | | `tools/config-spec.tsv` | `/jsc-cli:doctor` 比對設定落點的依據，`$JSC_HOME/restart-required` 那一列改成 `restart-required.d` 目錄，說明改為「該 CLI 那份不存在代表這支沒有待重啟的部署」 | | `README.md` | 「部署留在機器上的檔案」那張表同步，並訂正原本寫成「一行一次成功部署」的描述——實際是四行 key=value | | `skills/deploy/SKILL.md` | 第 9 步的路徑說明同步，補上只讀自己那一份、重啟一支只清自己那份，全篇維持英文 | | `plugin.json`、`.claude-plugin/plugin.json`、`.codex-plugin/plugin.json` | 版本 0.1.9 → 0.2.0，三份同步；部署留在機器上的檔案落點改變是對外契約變更，所以走次版號 | ## 設計重點 - **唯一來源不搬家。** 狀態檔的路徑與格式只留在 `jsc-hooks/hooks/restart-gate.sh`，`deploy.sh` 仍只轉呼叫它的 `require`，這一側不自己組狀態檔內容、也不重寫一份判定。這次改的全是要印給人看的路徑與說明。 - **失敗要講出來這件事照舊。** `require` 失敗時仍走 `note` 那一行講明「這次沒有掛上重啟閘門」；`jsc-hooks` 側新增的「取不到 CLI 代號回 exit 2」會直接落在同一條路徑上，不必在這裡加判斷。 - **指引寫的是整台機器、狀態檔寫的是單一 CLI。** 更新指引照舊一輪部署寫一次，但狀態檔說明要講清楚一支一份，看指引的人才不會以為刪掉一個檔案就解除全部閘門。 - **`config-spec.tsv` 那一列的性質不變**：`global` 的執行期暫態，備份與還原都是 `none`，只有路徑與說明改寫，欄位數維持 8。 - **版號跨存取庫成對。** 這一版要搭 `jsc-hooks` 0.2.6 才有一支 CLI 一份的狀態檔，兩者一起發佈。 ## 測試結果 - `ste100-lint.sh`：本存取庫全綠。三份 manifest 版本一致為 0.2.0。`sh -n` 對這次改動過的 `tools/deploy.sh` 與 `tools/write-guides.sh` 通過。 - `grep` 掃過本存取庫，舊路徑 `restart-required`（不帶 `.d`）零殘留。 - `tools/config-spec.tsv` 每列欄位數一致為 8。 - 狀態檔本身的行為（一支一份、只擋自己那一支、清除只清自己那份、舊檔相容、髒值防護）在 `jsc-hooks` 那份 PR 實測，這一側不重複驗一次判定邏輯。 - **無法測試的部分**：codex、copilot、antigravity、kiro 四支沒有 pre-tool hook，這道閘門在那四支上一次技能呼叫都擋不下來。那是覆蓋範圍的先天限制，不是還沒測。 - 這批修正尚未部署到任何 CLI。 ## 前置 Push Request - plugins/hooks#37 https://gitea.jsc.idv.tw/plugins/hooks/pulls/37（狀態檔路徑與格式的唯一來源在 restart-gate.sh）

jiantw83 added 3 commits 2026-08-27 10:50:21 +00:00

fix(deploy): 部署工具的重啟狀態檔路徑改為一支 CLI 一份 98781a331f

What：`tools/deploy.sh` 的 `restart` 那一行改印 `$JSC_HOME/restart-required.d/{CLI 代號}`，檔頭註解一併改寫成「轉呼叫 `restart-gate.sh require` 掛上這支 CLI 的閘門」。`tools/write-guides.sh` 產生的更新指引，狀態檔說明改成一支 CLI 一份、重啟只清自己那份、別支的閘門不受影響。`tools/config-spec.tsv` 的 `$JSC_HOME/restart-required` 那一列改成 `$JSC_HOME/restart-required.d` 目錄，說明改為「該 CLI 那份不存在代表這支沒有待重啟的部署」。

Why：`jsc-hooks` 這一輪把狀態檔改成一支 CLI 一份，路徑從單一檔案變成狀態目錄底下的一份。`deploy.sh` 印的是操作者接下來要看的檔案路徑，印錯就指向一個不存在的檔案；`write-guides.sh` 寫出的更新指引是下一輪部署的依據，留著舊路徑會讓人以為刪掉那個檔案就能解除閘門；`config-spec.tsv` 是 `/jsc-cli:doctor` 比對設定落點的依據，路徑對不上就查不到這份執行期暫態。

How：三處都只跟著改路徑與說明，掛閘門的動作本來就是轉呼叫 `jsc-hooks` 的 `restart-gate.sh require`，這裡不重寫一份判定，也不自己組狀態檔內容——路徑與格式的唯一來源留在 `restart-gate.sh`。`config-spec.tsv` 那一列的型別仍是 `global` 的執行期暫態、備份與還原都維持 `none`，欄位數不變。

Who：`jsc-cli:deploy` 的部署收尾與更新指引，對齊 `jsc-hooks` 一支 CLI 一份的重啟狀態檔。

docs(deploy): 部署說明同步一支 CLI 一份的重啟狀態檔 284292ffcb

What：`README.md`「部署留在機器上的檔案」那張表，`$JSC_HOME/restart-required` 那一列改成 `$JSC_HOME/restart-required.d/{cli}`，寫明一支 CLI 一份、內容是四行 key=value，以及路徑與格式的唯一來源在 `jsc-hooks/hooks/restart-gate.sh`。`skills/deploy/SKILL.md` 第 9 步的路徑說明同步改寫，補上「每支 CLI 只讀自己那一份」與「重啟一支只清自己那份、別支的閘門還立著」，全篇維持英文。

Why：這兩份說的是同一件事在不同讀者面前的樣貌——README 給看存取庫的人，技能文件給執行部署的模型。收尾提示裡的路徑是操作者唯一會拿到的線索，寫成舊的單一檔案就對不上機器上的實況，也會讓人以為重啟一支就把全部閘門解除了，那正是這一輪要修掉的錯誤認知。

How：只改說明，第 9 步的完成判準與那句固定的重啟指示都不動。舊表格那一列原本寫「一行一次成功部署」，其實是四行 key=value 的狀態檔，這次一併訂正。路徑與格式指回 `restart-gate.sh`，兩個存取庫不各自維護一份格式說明。

Who：`jsc-cli` 的存取庫說明與 `jsc-cli:deploy` 技能文件，對齊 `jsc-hooks` 的重啟狀態檔設計。

chore(cli): 三份 manifest 版本升到 0.2.0 2e85dc4978

What：`plugin.json`、`.claude-plugin/plugin.json`、`.codex-plugin/plugin.json` 的 `version` 從 0.1.9 升到 0.2.0，三份同步，description 不動。

Why：這一輪改的是部署收尾留在機器上的檔案落點——狀態檔從單一檔案變成一支 CLI 一份的狀態目錄，`config-spec.tsv` 這份對外的設定落點清單也跟著改。那是對外可見的契約變更，不只是內部修正，所以走次版號而不是修訂號。版本不升，`version-guard.sh` 與 `jsc-cli:deploy` 都判不出本機還是舊版，機器上就不會被提示更新。

How：只改版號一個欄位。三份必須一致：`plugin.json` 給 marketplace、`.claude-plugin` 給 claude、`.codex-plugin` 給 codex，任一份落後都會讓那一路的版本比對抓錯。這一版的部署工具要搭 `jsc-hooks` 0.2.6 才有一支 CLI 一份的狀態檔，兩者一起發佈。

Who：`jsc-cli` 的三份 plugin manifest，配合這一輪重啟狀態檔路徑的修正發佈。

jiantw83 added a new dependency 2026-08-27 10:50:22 +00:00

plugins/hooks#37 - fix(hooks): 重啟閘門狀態檔改為一支 CLI 一份，修並行覆寫與全域解除

admin merged commit a94a942712 into develop

2026-08-27 10:51:25 +00:00

admin deleted branch fix/restart-gate-per-cli-state

2026-08-27 10:51:25 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Depends on

#37 fix(hooks): 重啟閘門狀態檔改為一支 CLI 一份，修並行覆寫與全域解除

plugins/hooks

Reference: plugins/cli#30