CyrilLeMat/temper-skills

Temper-Skills（庫模式）

將代理技能或提示的決策邏輯轉換為確定性 Python — 推理時零 LLM 呼叫 — 透過驅動已安裝的 temper-skills CLI。您協調 CLI 並轉發其輸出；庫負責進行調節。您無需親自編寫決策樹。

當您沒有原生子代理/任務原語來自行運行循環時，請使用此技能。在 Claude Code 內部，請優先使用子代理模式技能（它無需金鑰即可運行，並帶有即時面板）。此模式改為對 CLI 進行外殼呼叫。

何時使用

• 一個 .md 技能、系統提示或劇本包含路由/決策邏輯（對結構化輸入的 if-this-then-that），該邏輯應可測試、可在 PR 中差異化，或對模型更新具有韌性。
• 適用：工單路由、分類規則、資格檢查 — 基於可預先計算特徵的分類決策。
• 不適用：連續評分、文字生成，或模型無法觸及的無文檔邏輯。

不可協商的規則

1. 始終透過其 CLI 呼叫庫。絕不要用自然語言重新實作決策邏輯來替代運行它。
2. 絕不跳過 schema 批准。 您批准的 schema 是循環隨後共同進化的初始種子（schema_critic 會生長它，earn-a-branch 守衛會修剪它），因此種子中的靜默提取錯誤仍會毒害一切。即使未連接終端機，也請使用下面的基於檔案的閘門（--propose-schema）。審查共同進化的 schema 以及 CLI 在末尾列印的任何 schema gaps / schema grew 註記。
3. 絕不靜默安裝。 如果閘門（步驟 0）報告缺少庫或後端，請在使用者執行 pip install 或更改其環境之前詢問使用者。
4. 絕不聲稱樹是「正確的」 — 僅聲明它是確定性且可審計的。正確性由使用者透過批准的範例（validate，步驟 4）確定。
5. 逐字轉發 CLI 的閘門和裁決 — 審計裁決、人格面板、灰色區域、待批准的案例。不要對其進行摘要。

步驟 0 — 檢查安裝 + 後端

運行 python scripts/check_install.py 並根據退出碼分支：

• 0 — 就緒，繼續。
• 10 — 已安裝但沒有模型後端。告訴使用者：temper-skills 需要後端 — 已登入的 claude 或 opencode CLI，或環境中的 ANTHROPIC_API_KEY。詢問他們希望如何提供。在後端存在之前，不要繼續。
• 11 — 未安裝。 詢問：「temper-skills 未安裝。現在安裝嗎？（pip install temper-skills）」僅在明確確認後才安裝。

步驟 1 — 使用 guide 進行分流（此處為引導）

找到包含決策邏輯的 .md 檔案或提示（如果不明確，請與使用者確認路徑），然後運行一次性導覽：

temper-skills guide <path/to/skill.md> --json

如果使用者指向一個目錄（一個技能庫），則掃描該目錄而不是引導單個檔案 — 審計本身就是一個值得轉發的報告：

temper-skills audit <dir> --json --report audit.md

轉發排序後的發現（JSON 是按技能報告的列表，最具可行性的排在最前），並提供引導頂部選項。audit.md 是可分享的 Markdown 版本，適用於 PR。

始終傳遞 --json。 guide 和 ingest 隨後將機器可讀的清單輸出到 stdout，並將人性化的 Rich 面板傳送到 stderr — 讀取清單，不要抓取面板。guide 的清單是：

{ "audit": { "verdict": "...", "recommended_action": "...", ... },
  "action_taken": "temper|decompose|...",
  "status": "compiled|stopped_for_ratification|action_not_auto_run",
  "final_skill_path": "...", "artifacts": ["..."] }

guide 審計技能，然後遵循 recommended_action。將審計裁決和操作轉發給使用者：

• temper — 單個樹狀決策。guide 調節它（快速）；status: compiled。
• decompose — 一個流程（≥2 個決策）。guide 為每個決策生成 schema 並停止；status: stopped_for_ratification。
• externalize_data / build_normalizer / delegate_prose — 非調節任務。status: action_not_auto_run；轉發操作提示並停止。

guide 是導覽：它運行 quick 設定檔並自動接受推斷的 schema。這適用於「展示這是做什麼的」，但對於使用者將依賴的樹，請前往步驟 2，以便 schema 得到批准。

步驟 2 — 生成一個持久樹（經批准的流程）

2a. 草擬 schema 並停止等待批准

temper-skills ingest <path/to/skill.md> --propose-schema --json

這會寫入 schema.proposed.py 並停止 — 循環絕不會在未經批准的 schema 上運行。stdout 上的 JSON 會提供 {proposed_schema_path, fn_name, features:[{name,type,description}], constraints}。向使用者顯示提議的特徵，並只問一件事：接受這些特徵，還是編輯列表？ 將他們的編輯應用於 schema.proposed.py。

在此處不要詢問使用者任何其他內容 — 不要問特徵廣度，不要問保留哪些分支。修剪是循環的工作（過度工程審查員），而不是使用者的。

2b. 根據批准的 schema 進行編譯

temper-skills ingest <path/to/skill.md> \
  --schema schema.proposed.py \
  --profile standard \
  --json

與使用者一起選擇設定檔 — quick | standard | audit-grade，預設 standard；在推薦之前請參閱 references/profiles.md。--json 意味著非互動式：循環運行至收斂（當以此方式驅動時，它無法暫停以進行每輪閘門 — 該閘門是一個人類終端機功能）並在 stdout 上輸出結果清單。讀取它，不要抓取面板。（如果審計裁決為 skip，--require-fit 會以退出碼 3 提前中止；添加它以避免在不合適的情況上浪費循環。）

2c. 如果操作是 decompose

必須先拆分流程；分別調節每個決策：

temper-skills decompose <path/to/skill.md> --temper-each --out-dir out/

這會為每個決策生成一個 schema 並停止等待批准。展示 schema，讓使用者編輯它們，然後重新運行相同的命令以將每個 schema 編譯成一個樹加上編排器技能（--yes-unratified 跳過停止 — 除非使用者要求，否則避免使用）。

步驟 3 — 報告產出物（來自清單）

ingest --json 清單是真相來源 — 讀取這些欄位，不要抓取：

{ "tree_path": "...", "tempered_skill_path": "...",
  "validation_dataset_path": "..." , "validation_case_count": 0,
  "gray_zones": [{"node": 1, "condition": "...", "note": "..."}],
  "features": ["..."], "node_count": 0, "profile": "...", "cost_usd": 0.0 }

向使用者展示所有三個產出物：

• tree_path — 決策樹：不導入任何東西，推理時零 LLM 呼叫，帶有 generated_at + 模型標頭和每個節點的來源註釋；
• tempered_skill_path — 已調節的 skill.md：原始技能被重寫為呼叫凍結的樹，而不是重新決策。一半的交付成果；不要丟棄；
• validation_dataset_path — 循環為其灰色區域建立的已提交 .validation.jsonl，等待批准（validation_case_count）。"agrees": false 的行是最高價值的分歧，供使用者裁決。它旁邊的行為鎖定測試（test_<stem>.py）保持綠色；只有批准的標籤可以將測試變為紅色。

告訴使用者路徑、設定檔、cost_usd 和 gray_zones。重申規則 4：確定性且可審計，而非「正確」。

步驟 4（可選）— 在 CI 中固定

一旦使用者批准了一個標記集，針對它驗證樹：

temper-skills validate decision_tree.generated.py ratified.json --min-agreement 1.0

不同意時非零退出 — 這就是將樹固定在 CI 中的原因。每個分歧要么是樹的錯誤，要么是錯誤標記的範例；轉發它們以供簽署。

參考

在推薦之前，請參閱 references/profiles.md 了解輪次 / 收斂 / 人格面板 / 每個設定檔的成本。

絕不

• 絕不要用自然語言編寫樹的邏輯，而不是運行庫。
• 絕不要跳過 schema 批准，即使在 quick 演示中也是如此（quick 會刪除來源註釋，而不是閘門）。
• 未經明確確認，絕不安裝或修改環境。
• 絕不聲稱生成的樹是「正確的」。