104 lines
8.5 KiB
Markdown
104 lines
8.5 KiB
Markdown
---
|
||
name: spec-model
|
||
description: JSC plugins 共用「取得可用模型並加上標籤」規範：固定標籤體系（能力等級／成本／延遲／上下文／用途／可用性）、任務→必要標籤對映表、取得模型清單的權威來源優先序（`claude-api` skill／CLI 自陳／使用痕跡／smoke test）、`~/.claude/jsc/models.json` 快取設計（30 天過期）、強制切換規則，以及讀到帶 `model:` frontmatter 清單檔時的模型檢查義務。當其他 skill 內文引用 spec-model 或 /jsc-shared:spec-model、或需要挑選模型／驗證模型可用性／開啟帶 `model:` frontmatter 的清單檔時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。
|
||
---
|
||
|
||
# spec-model — 共用「取得可用模型並加上標籤」規範
|
||
|
||
所有 JSC skills 需要查詢目前可用哪些模型、為模型加上可供選型決策的標籤、依任務挑選推薦模型，或檢查執行者目前使用的模型是否符合某份清單／某個 skill 的要求時，一律遵守以下規範。
|
||
|
||
## 一、標籤體系（固定字彙表，不可自由發揮）
|
||
|
||
下表為**唯一**標籤字彙表；新增或改名標籤前一律先改本表，不得在其他 skill 內文自創同義詞。
|
||
|
||
| 面向 | 標籤 | 判準 |
|
||
| --- | --- | --- |
|
||
| 能力等級 | `#深度推理` | 多步推理、架構設計、跨檔案分析、需求拆解 |
|
||
| | `#均衡實作` | 一般編碼、文件重整、規格落地 |
|
||
| | `#輕量快速` | 摘要、分類、格式轉換、固定欄位抽取 |
|
||
| 成本 | `#高成本` `#中成本` `#低成本` | 依當下官方定價分三段，**不憑記憶**，每次都要查 |
|
||
| 延遲 | `#延遲敏感可用` | 在使用者等待路徑上仍可接受 |
|
||
| | `#可長時間跑` | 背景／批次工作 |
|
||
| 上下文 | `#長上下文` | ≥ 1M（如 `[1m]` 變體） |
|
||
| | `#標準上下文` | 200k 級 |
|
||
| 用途 | `#分析` `#實作` `#審查` `#摘要` `#對話人格` | 一個模型可帶多個標籤 |
|
||
| 可用性 | `#本機可用` | 已通過 smoke test |
|
||
| | `#不可用` | smoke test 失敗（無權限或不存在） |
|
||
| | `#未驗證` | 無法在此 CLI 驗證，只有文件記載 |
|
||
|
||
## 二、任務 → 必要標籤對映表
|
||
|
||
挑選模型時，先依任務類型找出下表的「必要標籤」——候選模型必須**同時具備**必要標籤才可推薦；「加分標籤」不具備也可推薦，只是排序上較後。
|
||
|
||
| 任務類型 | 必要標籤 | 加分標籤 |
|
||
| --- | --- | --- |
|
||
| 需求分析／拆 TODO／架構決策 | `#深度推理` `#分析` `#本機可用` | `#長上下文` |
|
||
| 依清單實作／規格落地 | `#均衡實作` `#實作` `#本機可用` | `#中成本` |
|
||
| code review／findings 判讀 | `#深度推理` `#審查` `#本機可用` | — |
|
||
| 逐輪摘要（worklog）／分類 | `#輕量快速` `#摘要` `#延遲敏感可用` `#低成本` | — |
|
||
| 人格對話 | `#對話人格` `#本機可用` | `#延遲敏感可用` |
|
||
|
||
同一任務有多個候選都滿足必要標籤時，優先挑加分標籤命中較多者；仍並列則挑 `verified_at`（見〔四、快取設計〕）較新者。
|
||
|
||
## 三、取得清單的權威來源優先序
|
||
|
||
依序取得可用模型清單與其中繼資料（id／定價／上下文長度），**前一項可取得就不往下**：
|
||
|
||
1. **Claude Code 內建 `claude-api` skill**——模型 id／定價／上下文長度的權威來源，**不憑記憶**，每次查都要實際載入這個 skill 取得當下資料，不可用過去對話中記得的數字代替。
|
||
2. **CLI 自陳**：
|
||
- Claude Code：`claude --help` 的 `--model` 說明列出的 alias（例如 `fable`／`opus`／`sonnet` 這類最新模型別名，實際列出內容以當次 `--help` 輸出為準，不可硬編碼）。
|
||
- 其他 CLI（`codex`／`opencode`／`agy`／`copilot`）用各自的列出指令取得；取不到就把該模型標為 `#未驗證`，不得省略、也不得用其他 CLI 的結果替代。
|
||
3. **使用痕跡**：`~/.claude/stats-cache.json` 內 `dailyModelTokens`／`modelUsage` 等欄位出現過的模型 id（例如曾實際用過的 `claude-opus-5`、`claude-sonnet-5`、`claude-haiku-4-5-20251001`）。這一層**只當補充候選**，用來發現前兩層沒列出但實際上帳號可用的模型，**不當權威**——出現在這裡不代表現在仍可用，仍須走第 4 步驗證。
|
||
4. **Smoke test 驗證可用性**（標準做法，所有候選模型都要跑）：
|
||
|
||
```bash
|
||
CLAUDE_CODE_CHILD_SESSION=1 timeout 45 claude -p 'OK' --model <id>
|
||
```
|
||
|
||
不可用時 stderr／stdout 會出現「is not a model this version of Claude Code recognizes」或「There's an issue with the selected model」；出現任一即標 `#不可用`；正常回應則標 `#本機可用`。
|
||
|
||
⚠️ **必須帶 `CLAUDE_CODE_CHILD_SESSION=1`**，否則會觸發巢狀 session 與 SessionStart hook，汙染 smoke test 結果也可能造成非預期副作用。
|
||
|
||
## 四、快取設計
|
||
|
||
- 路徑：`~/.claude/jsc/models.json`。
|
||
- 每筆模型記錄的欄位：`{ id, aliases[], tags[], context, pricing, verified_at, verdict, reason }`。
|
||
- `id`：模型完整 id（如 `claude-sonnet-5`）。
|
||
- `aliases[]`：CLI 自陳取得的別名（如 `sonnet`）。
|
||
- `tags[]`：依〔一、標籤體系〕貼上的標籤陣列。
|
||
- `context`：上下文長度（依〔一〕分類為 `#長上下文`／`#標準上下文` 的依據數值）。
|
||
- `pricing`：查證當下的定價摘要（來源為 `claude-api` skill 或對應 CLI 文件）。
|
||
- `verified_at`：本筆最後驗證（含 smoke test）的時間，格式依 `/jsc-shared:spec-time-log`。
|
||
- `verdict`：`本機可用`／`不可用`／`未驗證` 三者之一，對應〔一〕的可用性標籤。
|
||
- `reason`：判定 `verdict` 的簡短依據（例如 smoke test 的錯誤訊息摘要、或「僅文件記載未能於此 CLI 驗證」）。
|
||
- **過期規則**：`verified_at` 距今**超過 30 天視為過期**（沿用 worklog 快取的年限慣例），過期記錄需重新走〔三、取得清單的權威來源優先序〕更新，不得直接沿用。
|
||
- **內容邊界（重要）**：快取檔**只准存模型中繼資料**（上述欄位），**不得寫入任何工作內容或使用者資料**（例如對話內容、專案路徑、議題內容、任何個資）。任何要寫進這份快取的內容，寫入前都要檢查是否落在這個邊界內。
|
||
|
||
## 五、強制切換規則（供 `/jsc-shared:todo-wiki` 與其他 skill 使用）
|
||
|
||
任何 skill 宣告了必要標籤（依〔二〕的對映表）或直接指定模型時，執行者當前模型不符就**停止並要求使用者切換**：
|
||
|
||
- **不得自行降級或升級**到別的模型頂替。
|
||
- **不得先做一部分**再提醒使用者切換——必須在動手前就完成檢查並停下。
|
||
- 錯誤訊息格式依 `/jsc-shared:spec-time-log` 的 `[時間][階段][等級]: 訊息`：
|
||
|
||
```
|
||
[yyyy/MM/dd HH:mm:ss][模型檢查][ERR]: 本清單/本 skill 指定 <model>（<alias>），當前模型為 <current-model-id>。
|
||
請執行 /model <alias> 切換後重新載入，本次不進行任何修改。
|
||
```
|
||
|
||
- **限制**：Claude Code **沒有環境變數可讀取當前模型 id**，只能以 agent 對自己當下模型的自我回報為準；自我回報不確定時，請使用者執行 `/status` 確認目前模型後再繼續判斷，不得用猜測代替確認。
|
||
|
||
## 六、讀到帶 `model:` frontmatter 的清單檔時的檢查義務
|
||
|
||
任何 agent 開啟像 `todo.md` 這種帶 `model:` frontmatter 的清單檔時，**開始執行清單內容之前**都要先依〔五、強制切換規則〕做一次模型檢查：
|
||
|
||
1. 讀出清單檔 frontmatter 的 `model`（與可能並列的 `model_alias`）。
|
||
2. 依〔五〕的方式確認當前模型（agent 自我回報，不確定就請使用者 `/status` 確認）。
|
||
3. 兩者不符 → 依〔五〕的錯誤訊息格式停止，不得先執行清單中的任何一項再提醒。
|
||
4. 相符才繼續往下執行清單內容。
|
||
|
||
**具體操作步驟（可直接照做，不需另外解讀）**：開啟一份 `.md` 檔案、發現其 YAML frontmatter 含 `model` 欄位時，**在做任何修改前**先自我回報目前模型 id，並與 frontmatter 的 `model` 欄位比對；不符就依〔五、強制切換規則〕的錯誤訊息格式中斷，本次不進行任何修改；相符才繼續往下執行檔案內容。
|
||
|
||
本節會被 `/jsc-shared:todo-wiki`（產生指定模型 wiki TODO 頁的 skill）與其他消費這類清單檔的 skill（例如處理 `TARGET.md`、處理議題 TODO 的 skill）引用，各消費端不必重抄本節內容，直接引用本節即可。
|