jiantw83
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` 的重啟狀態檔設計。
93 lines
10 KiB
Markdown
93 lines
10 KiB
Markdown
# jsc-cli — CLI 偵測與技能庫部署
|
||
|
||
jsc 技能組的 CLI domain：找出已安裝的 AI CLI、列出各 CLI 可用模型並加上能力標籤，以及對每個 CLI 批次安裝、更新、解除安裝整組 jsc plugins。
|
||
|
||
## 安裝、更新、移除
|
||
|
||
Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安裝 token 為 `jsc-cli@jsc`。每個指令一行：
|
||
|
||
| CLI | 安裝 | 更新 | 移除 |
|
||
| --- | --- | --- | --- |
|
||
| claude | `claude plugin marketplace add https://gitea.jsc.idv.tw/plugins/meta.git && claude plugin install jsc-cli@jsc` | `claude plugin marketplace update jsc && claude plugin update jsc-cli@jsc` | `claude plugin uninstall jsc-cli@jsc` |
|
||
| codex | `codex plugin marketplace add https://gitea.jsc.idv.tw/plugins/meta.git && codex plugin add jsc-cli@jsc` | `codex plugin marketplace upgrade jsc` | `codex plugin remove jsc-cli@jsc` |
|
||
| copilot | `copilot plugin marketplace add https://gitea.jsc.idv.tw/plugins/meta.git && copilot plugin install jsc-cli@jsc` | `copilot plugin marketplace update jsc && copilot plugin update jsc-cli@jsc` | `copilot plugin uninstall jsc-cli@jsc` |
|
||
| antigravity | `git clone https://gitea.jsc.idv.tw/plugins/cli.git ~/plugins/cli && agy plugin install ~/plugins/cli` | `git -C ~/plugins/cli pull && agy plugin uninstall jsc-cli && agy plugin install ~/plugins/cli` | `agy plugin uninstall jsc-cli` |
|
||
| kiro | `kiro-cli plugin marketplace add https://gitea.jsc.idv.tw/plugins/meta.git && kiro-cli plugin install jsc-cli@jsc` | `kiro-cli plugin marketplace update jsc && kiro-cli plugin update jsc-cli@jsc` | `kiro-cli plugin uninstall jsc-cli@jsc` |
|
||
|
||
> antigravity 不支援 gitea URL 安裝，改用本地 clone 路徑。批次操作五個 CLI：使用 `/jsc-cli:deploy`。
|
||
|
||
> 舊入口 `plugins/jsc` 已移除，marketplace 正本移到 `plugins/meta`。marketplace 名稱仍是 `jsc`（取自 marketplace.json 的 `name` 欄位，與存取庫名無關），安裝 token 不變；已從舊入口安裝過的人先執行 `claude plugin marketplace remove jsc`，再依上表重新 add。
|
||
|
||
## 工具
|
||
|
||
| 工具 | 用途 |
|
||
| --- | --- |
|
||
| `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 的指令差異全部收在這支腳本裡。install 或 update 全數成功時，收尾轉呼叫 `jsc-hooks` 的 `restart-gate.sh require` 掛上重啟閘門，並印一行 `restart` 標出狀態檔位置；uninstall 不寫。狀態檔的路徑、格式與判讀全在 `restart-gate.sh`，這支腳本不自己拼——格式只留一個真實來源。站台取自 `GITEA_HOST`，本地 clone 目錄取自 `JSC_LOCAL_PLUGINS`，兩者的預設值見下表 |
|
||
| `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`。鏈只影響建議與偏好順序，不影響閘門放行 |
|
||
| `tools/config-spec.tsv` | 設定規格表：每個環境變數與設定檔一列，標明必要或選擇、預設值、驗證方式、修法。體檢與設定共用這一份，新增設定時要同步補一列 |
|
||
| `tools/scan-config.sh` | 依規格表盤點設定現況（`scan {global\|project\|all}` 印 TSV 與 summary、`spec` 印規格表、`orphans` 找出漏登錄的變數）；`-o` 為離線模式，需要連 Gitea 的檢查一律標 skipped。唯讀，不寫任何設定；帶 TOKEN 的項目只印 set 或 unset |
|
||
| `tools/apply-config.sh` | 把設定寫進 shell rc 檔（`set {KEY} {VALUE}`、`unset {KEY}`）或建立目錄（`mkdir {PATH}`）；`show` 印出目前設定，`rcfiles` 印出會寫入的檔案。內容一律收在 `# jsc-config` 標記段落之間，整段重寫不疊加，段落外不動。動檔案前先備份到 `$JSC_HOME/backup/config/{yyyyMMdd_HHmmss}/`，備份失敗就不寫；寫完重讀驗證。fish 自動改用 `set -gx` 語法 |
|
||
| `tools/model-tags.sh` | 解析 `references/model-tags.md` 的能力標籤與 SDLC 階段必要標籤（`dump`、`sync`、`stage {階段}`、`model {模型 id}`、`gate {階段} {模型 id}`）；`sync` 寫出 `$JSC_HOME/model-tags.tsv` 供 `jsc-hooks` 的 sdlc-gate 讀取 |
|
||
|
||
## Skills 目錄
|
||
|
||
呼叫方式：Claude / Antigravity `/jsc-cli:{name}`；Codex `${name}`；Copilot / Kiro 描述需求自動觸發。
|
||
|
||
<!-- JSC-SKILLS:START -->
|
||
|
||
### `models`
|
||
|
||
用 `tools/list-models.sh` 讀出各已安裝 CLI 可使用的模型並加上能力標籤（`references/model-tags.md`），用 `tools/model-tags.sh sync` 把標籤表寫進 `$JSC_HOME/model-tags.tsv` 供 sdlc-gate 讀取，列出 SDLC 各階段的必要標籤（plan、analyze 需 `reasoning-max`；implement 需 `coding`；maintain 任意），並用 `tools/model-config.sh` 列出各階段的偏好模型鏈。`jsc-sdlc` 閘門一律以能力標籤判定，偏好鏈只用來建議切換目標。
|
||
|
||
### `delegate`
|
||
|
||
把單一明確任務交給另一個已安裝的 AI agent CLI 當作 subagent 執行。可指定目標 CLI，也可依任務需求用能力標籤篩選模型，或強制指定模型。每個目標分開派工，預設只讀，並回傳結構化結果供主 agent 驗證與彙整。此技能不負責模型盤點或 plugin 部署。
|
||
|
||
### `deploy`
|
||
|
||
技能庫批次安裝、更新、解除安裝：偵測 CLI → **先比對各 plugin 的本機與已發佈版本並列表，只要有任一個落後就把「更新」設為推薦選項** → 決策樹選模式 → 每個 CLI 一個 sub agent 呼叫 `tools/deploy.sh` 執行原生 plugin 指令（統一 marketplace `jsc`，token `jsc-{domain}@jsc`）。domain 名單動態取自 `plugins/meta` 的 marketplace.json，不硬編碼。
|
||
|
||
### `doctor`
|
||
|
||
一次體檢執行環境，只讀不改。四項檢查：技能版本（`jsc-hooks/hooks/version-guard.sh report`）、Hook 接線（`jsc-hooks/tools/wire-cli.sh status`，唯讀子命令）、全域設定與自我設定（`tools/scan-config.sh` 比對 `tools/config-spec.tsv`）。每項各出一張表，整份結果寫進 wiki `CHECK_{HASH}`，`HASH` 取 `{主機名}/{登入帳號}`，只保留最新一次。修復交給 `/jsc-cli:setup`，體檢本身不動任何設定。
|
||
|
||
### `setup`
|
||
|
||
修復 `/jsc-cli:doctor` 找出的問題，一次一項，逐項確認才動手。待修清單優先讀 wiki `CHECK_{HASH}`，沒有頁面就當場重掃一份。依修法分流：`auto` 用 `tools/apply-config.sh` 直接寫、`ask` 先用決策樹問到值再寫、`manual` 印出步驟交給操作者。複合修復交回原主：版本落後找 `/jsc-cli:deploy`、hook 未接線找 `/jsc-hooks:hooks-install`、缺 `model-tags.tsv` 找 `/jsc-cli:models`。每一項寫完都重驗一次，最後覆寫 CHECK 頁。
|
||
|
||
<!-- JSC-SKILLS:END -->
|
||
|
||
## 環境變數
|
||
|
||
| 變數 | 用途 | 未設定時 |
|
||
| --- | --- | --- |
|
||
| `GITEA_HOST` | Gitea 站台（可省略 scheme，預設 https） | 用正本站台 `https://gitea.jsc.idv.tw` |
|
||
| `JSC_GITEA_OWNER` | 技能組存取庫的 owner | 用 `plugins` |
|
||
| `JSC_LOCAL_PLUGINS` | antigravity 與 kiro 退路用的本地 clone 目錄 | 用 `$JSC_HOME/plugins`（即 `~/.jsc/plugins`） |
|
||
| `JSC_KIRO_SKILLS` | kiro 退路複製 skills 的目標目錄 | 用 `~/.kiro/skills` |
|
||
| `JSC_DEPLOY_DRYRUN` | 設為 `1` 等同 `deploy.sh -n`，只印指令不執行 | 照常執行 |
|
||
| `JSC_WIKI_REPO_CHECK` | 體檢頁 `CHECK_CONTENTS`、`CHECK_{HASH}` 所在的 `{owner}/{repo}` | 退回 `JSC_WIKI_REPO`；兩個都沒有就略過寫入，並把這一項列進待修 |
|
||
| `JSC_CONFIG_SPEC` | 改讀別份設定規格表（測試 `scan-config.sh` 時用） | 用 `tools/config-spec.tsv` |
|
||
| `JSC_HOME` | hook 資料目錄，兩份指引與重啟狀態檔都寫在這裡 | 用 `~/.jsc` |
|
||
| `JSC_RESTART_GATE` | 設成 `off` 可略過部署後的重啟提示閘門（判讀在 `jsc-hooks`，`jsc-cli` 只負責寫狀態檔） | 照常提示重啟 |
|
||
|
||
`JSC_LOCAL_PLUGINS` 的預設值刻意避開 `~/plugins`：那是維護者放技能組開發 checkout 的地方，`git pull` 下去會蓋掉未提交的工作。這個變數指到的目錄若是開發中的樹（有未提交變更，或有未推送的 commit），`deploy.sh` 只印一行 `skip` 並直接用現地內容安裝，不執行 `git pull`。
|
||
|
||
## 部署留在機器上的檔案
|
||
|
||
| 檔案 | 何時產生 | 用途 |
|
||
| --- | --- | --- |
|
||
| `$JSC_HOME/update-guide.md` | install、update 收尾 | 下次更新的依據：偵測到的 CLI、每支的安裝方式與實際指令、marketplace token、domain 清單 |
|
||
| `$JSC_HOME/remove-guide.md` | install、update 收尾 | 整組移除的依據：各 CLI 的移除指令，加上 `$JSC_HOME`、本地 clone、kiro 技能目錄、rc 檔 `# jsc-config` 段落這些殘留物 |
|
||
| `$JSC_HOME/restart-required.d/{cli}` | install、update 全數成功時 | 一支 CLI 一份，內容是四行 key=value（`at`、`mode`、`domains`、`cli`）。`jsc-hooks` 只讀當前 CLI 那一份來提示重啟，別支的不影響這一支；逃生門 `JSC_RESTART_GATE=off` 也在那邊判讀。路徑與格式的唯一來源是 `jsc-hooks/hooks/restart-gate.sh`，`deploy.sh` 只轉呼叫它的 `require` |
|
||
|
||
兩份指引一律整份覆寫，內容依產生當下的偵測結果生成，不寫死。`uninstall` 不產生指引、也不寫重啟狀態檔。
|
||
|
||
## 相關 domain
|
||
|
||
- [`jsc-gitea`](https://gitea.jsc.idv.tw/plugins/gitea)：取得 domain 名單（`tools/gitea.sh repos plugins`）
|
||
- [`jsc-hooks`](https://gitea.jsc.idv.tw/plugins/hooks)：deploy 完成後重新接線 hooks（`jsc-hooks:hooks-install`）
|