feat(skills): 新增技能盤點頁與共用部署驗證流程,並把技能驗證移到新行程
技能盤點以前只回到對話裡,換一台機器就得重跑才知道裝了什麼。 現在新增技能盤點這個 wiki 頁類型,雜湊取「主機、工具名稱、登入帳號」三段。 每支 CLI 各有自己的 plugin 集合,也各有自己的 hook 接線,那是互相獨立的事實。 少了工具名稱那一段,同一台機器上五支 CLI 會算出同一個雜湊,五份盤點互相覆蓋, 讀的人還看不出被蓋掉。技能盤點新增寫入這兩頁的步驟,整步規定必須開 sub agent。 兩份樣板刻意分開:內容頁每次盤點覆寫整頁,目錄頁只更新自己那一列, 兩者的寫入語意剛好相反,合成一份遲早有人把別台機器的紀錄刪掉。 四支異動技能原本在部署完的同一個工作階段,就叫用剛做好的技能。 部署收尾自己立起重啟閘門,那支技能必被擋下,驗證做不完。 解法不是把它加進豁免清單。豁免擋得住閘門,擋不住「行程還載著舊版」這件事, 硬過關驗到的是舊版行為,等於假通過。所以把判路線、部署、驗證、失敗分流 抽成一份共用說明,驗證一律另開 CLI 行程執行,四支技能只留一行指標指過去。 新增腳本檢查工具,一次做完語法、執行權限與結束碼宣告三項檢查, 只被 source 的函式庫豁免後兩項,而且逐支記在錯誤輸出,不靜默略過。 新增部署路線判定工具,判定改動有沒有進存取庫的預設分支, 取代四支技能各抄一段、各自漂移的散文;判不出來就回報停下,不自己挑路線走。 同時把四支技能裡的中文段落抽到共用說明、指標改回英文, 修正六處相對路徑,把技能盤點的模糊描述改成查得出來的條件, 並讓 manifest 同步的每一個呼叫端逐碼分流。 七支技能改為併行執行:例行稽核從九步併成七步,技能盤點併成六步。 技能盤點不再重跑盤點腳本內部已經跑過的三支腳本, 而那三支原本兼作獨立交叉檢查,拿掉就少一層保護, 所以把少掉的是什麼、風險由誰擋住,明白寫進 Notes,不當作沒發生。
This commit is contained in:
@@ -0,0 +1,65 @@
|
||||
# 部署與驗證
|
||||
|
||||
`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 節重跑整段。
|
||||
|
||||
完成條件:每一項不符都有對應的修正動作與重跑結果,沒有留下「已知失敗但照樣收尾」的項目。
|
||||
Reference in New Issue
Block a user