jiantw83
5aa4a3da57
技能盤點以前只回到對話裡，換一台機器就得重跑才知道裝了什麼。 現在新增技能盤點這個 wiki 頁類型，雜湊取「主機、工具名稱、登入帳號」三段。 每支 CLI 各有自己的 plugin 集合，也各有自己的 hook 接線，那是互相獨立的事實。 少了工具名稱那一段，同一台機器上五支 CLI 會算出同一個雜湊，五份盤點互相覆蓋， 讀的人還看不出被蓋掉。技能盤點新增寫入這兩頁的步驟，整步規定必須開 sub agent。 兩份樣板刻意分開：內容頁每次盤點覆寫整頁，目錄頁只更新自己那一列， 兩者的寫入語意剛好相反，合成一份遲早有人把別台機器的紀錄刪掉。 四支異動技能原本在部署完的同一個工作階段，就叫用剛做好的技能。 部署收尾自己立起重啟閘門，那支技能必被擋下，驗證做不完。 解法不是把它加進豁免清單。豁免擋得住閘門，擋不住「行程還載著舊版」這件事， 硬過關驗到的是舊版行為，等於假通過。所以把判路線、部署、驗證、失敗分流 抽成一份共用說明，驗證一律另開 CLI 行程執行，四支技能只留一行指標指過去。 新增腳本檢查工具，一次做完語法、執行權限與結束碼宣告三項檢查， 只被 source 的函式庫豁免後兩項，而且逐支記在錯誤輸出，不靜默略過。 新增部署路線判定工具，判定改動有沒有進存取庫的預設分支， 取代四支技能各抄一段、各自漂移的散文；判不出來就回報停下，不自己挑路線走。 同時把四支技能裡的中文段落抽到共用說明、指標改回英文， 修正六處相對路徑，把技能盤點的模糊描述改成查得出來的條件， 並讓 manifest 同步的每一個呼叫端逐碼分流。 七支技能改為併行執行：例行稽核從九步併成七步，技能盤點併成六步。 技能盤點不再重跑盤點腳本內部已經跑過的三支腳本， 而那三支原本兼作獨立交叉檢查，拿掉就少一層保護， 所以把少掉的是什麼、風險由誰擋住，明白寫進 Notes，不當作沒發生。
66 lines
5.1 KiB
Markdown
66 lines
5.1 KiB
Markdown
# 部署與驗證
|
||
|
||
`skill-new`、`skill-update`、`skill-delete`、`skillset-update` 四支異動技能的收尾共用這份流程。四支只在 SKILL.md 留一行指標指過來，不各自抄一份——抄四份會各自漂移，改一次要記得改四個地方。
|
||
|
||
## 1. 判路線
|
||
|
||
改動有沒有進存取庫的**預設分支**，決定走哪條路線。marketplace 與 `version-guard.sh` 都讀預設分支，停在 `develop` 的改動 `jsc-cli:deploy` 看不到。
|
||
|
||
判定交給 `jsc-meta/tools/deploy-route.sh {domain-path}`，不要自己用 `git log` 目測。多個 domain 就每個各跑一次，可以並行。
|
||
|
||
| 結束碼 | 意思 | 怎麼辦 |
|
||
| --- | --- | --- |
|
||
| 0 | 改動已在預設分支上 | 走第 2 節的部署路線 |
|
||
| 3 | 改動還沒併進預設分支 | 走第 3 節的工作樹路線 |
|
||
| 2 | 用法錯誤 | 修參數重跑 |
|
||
| 1 | 判不出來：不是 git 存取庫、沒有 origin、fetch 失敗，或取不到預設分支 | 停下回報 stderr 的原因。**1 不等於工作樹路線**，判不出來就問使用者，不要自己挑一條走 |
|
||
|
||
完成條件：每個受影響的 domain 存取庫都有一個路線判定，且判定來自腳本輸出的 `route` 欄位。
|
||
|
||
## 2. 部署路線（結束碼 0）
|
||
|
||
1. 叫用 `jsc-cli:deploy` 的更新模式，讓每支已安裝的 CLI 都載入新版。deploy 收尾會寫 `$JSC_HOME/restart-required.d/{cli}`，一支 CLI 一份；重啟該支 CLI 之後由 `jsc-hooks` 清掉自己那一份。閘門規則見 [`guidelines.md`](guidelines.md) 的「部署後重啟閘門」。
|
||
2. deploy 更新不了某些 CLI 時，記下哪幾支確實載入了新版，改用其中一支繼續。一支都沒載入就停下，把這次異動回報為未驗證。
|
||
|
||
完成條件：`claude plugin list`（或別支已安裝 CLI 的等效指令）印出的 `jsc-{domain}` 版本，等於三份 manifest 現在的版本。
|
||
|
||
## 3. 工作樹路線（結束碼 3）
|
||
|
||
改動還沒進預設分支，部署路線的完成條件永遠達不到，所以改對**工作樹**驗證：
|
||
|
||
1. 第 4 節的驗證對象改成 `{root}/{domain}` 工作樹，不是已安裝的副本。
|
||
2. 回報標注「工作樹驗證、尚未部署」。
|
||
3. 點名還沒合併的釋出 PR——改動要等它合進預設分支才會到任何 CLI。跨多個存取庫的異動要等最後一支合併，所以全部列出來。刪除技能還要補一句：PR 合併前技能仍然裝著，指令仍然叫得動。
|
||
|
||
完成條件：第 4 節的驗證在每個工作樹上都通過，且回報裡列出每一支待合的釋出 PR。
|
||
|
||
## 4. 功能驗證：一定要換一個工作階段
|
||
|
||
**部署會把閘門立在自己腳下。** `jsc-cli:deploy` 收尾寫下重啟閘門的狀態檔，緊接著在**同一個工作階段**叫用剛做好的技能，那支技能不在豁免清單上就必被擋；連修復路徑 `jsc-cli:doctor` 與 `jsc-cli:setup` 也一起被擋。
|
||
|
||
解法不是把它們加進豁免清單。豁免只擋得住閘門，擋不住「目前行程還載著舊版」這個事實——豁免過關的驗證，驗到的是舊版行為，等於假通過。
|
||
|
||
**正解：驗證一律在新的 CLI 行程裡跑。** 用 `jsc-cli/tools/detect-clis.sh` 取得已安裝 CLI 的執行檔路徑，對每支支援非互動 Prompt 的 CLI，另外開一個行程送出最小 Prompt。新行程是新的工作階段，`jsc-hooks` 開場就清掉那支 CLI 自己的狀態檔，載入的也是磁碟上的新版。
|
||
|
||
四支技能都不得在部署的那個工作階段內叫用剛異動的技能。
|
||
|
||
驗證項目：
|
||
|
||
1. 跑 `jsc-meta/tools/list-skills.sh`，確認該技能的列符合這次異動：新增看得到 `{domain}<TAB>{name}` 那一列；更新看得到新的 `description`；刪除看不到那一列。
|
||
2. 這次異動碰過的每一支工具，都用真實參數跑一次，把實際結束碼對照工具檔頭宣告的意思。
|
||
3. 每支可測的 CLI 各開一個新行程，送出一個最小 Prompt 叫用 `/jsc-{domain}:{name}`，記錄 CLI 結束碼與 stderr。新增與更新要確認載入的是異動後的 SKILL.md 內文，不是「未知指令」；刪除要確認指令已消失，或替代路徑仍可用。各支 CLI 可以並行送。
|
||
|
||
完成條件：上列三項各有結果；每支可測 CLI 的 Prompt 都沒有非預期 stderr；不可測的 CLI 逐支寫明原因。
|
||
|
||
## 5. 驗證失敗怎麼辦
|
||
|
||
Prompt 因為 CLI 工具、plugin 安裝、hook 接線、模型標籤表或設定而失敗時：
|
||
|
||
1. 先跑 `jsc-cli:doctor`，再用 `jsc-cli:setup` 修待修項目，然後在新行程重跑同一個 Prompt。
|
||
2. hook 冒煙測試失敗，交給 `jsc-hooks:hooks-install`，由它把 hook 接線或執行期錯誤轉給 `jsc-hooks:repair`。
|
||
3. 根因若在技能組本身的規格、工具或 hook 實作，就修對應 domain，跑 `jsc-meta/tools/sync-skill-manifest.sh {domain-path}` 同步與驗證，再用 `jsc-git:pr` 對 `develop` 開 PR；PR 送出後回到第 1 節重判路線。
|
||
|
||
任一項對不上——列不見、結束碼不在工具文件裡、指令載不到、Prompt 失敗、非預期 stderr——就修掉成因，回到第 1 節重跑整段。
|
||
|
||
完成條件：每一項不符都有對應的修正動作與重跑結果，沒有留下「已知失敗但照樣收尾」的項目。
|