Skill Auditor — 代理能力折舊與契合度評測
概述
技能是一種折舊資產。 模型版本每隔幾個月就推出一次。上一季通過的技能可能在此期間悄悄退化——輸出格式錯誤、工具呼叫中斷、觸發條件錯失——而沒有人告訴使用者他們的代理變笨了。
這項技能就是評估方法論。它回答三個問題：
- 技能是否正在退化？ ——跨模型版本的能力迴歸。
- 新技能真的有用嗎？ ——效果與成本的權衡。
- 這個技能適合「這個」使用者嗎？ ——觸發準確度、環境與風格。
它內建五個可執行入口點：
scripts/console.py—— 常駐主控台（資料層）：為每種主機維護registry.<host>.json，偵測模型版本變更（bump/check），並產出推薦/淘汰面板。完整指令集請參閱USAGE.md。scripts/regress.py—— 根據黃金測試集重放結果，計算通過率矩陣，標記衰退（門檻值 + 方向），並在資產被編輯時標記FINGERPRINT-DRIFT。scripts/baseline.py—— 建立重放檢查清單，然後將記錄的判定合併到baseline-results.json（按資產分類；使用--replace進行完整覆蓋）。除非加上--allow-draft，否則跳過草稿案例。scripts/fingerprint.py—— 獨立的報告 CLI；是scan使用的相同雜湊碼的簡化包裝。僅寫入fingerprint-report.*；不會寫入註冊表。scripts/install.py—— 將此技能安裝到機器上的每個代理主機（~/.workbuddy-ai/skills、~/.claude/skills、~/.agents/skills、~/.dsh/skills、~/.codex/skills）。安裝後進行驗證；絕不留空目錄；絕不複製個人資料。
核心原則：沒有基準線就沒有測量。退化 = 在指紋不變的情況下通過率顯著下降——絕非「感覺變笨」。
多主機架構（技能 vs 插件）
一個核心引擎，每主機配備介面卡。相同的指紋 / 基準線 / 迴歸 / 推薦 / 需求建議邏輯在所有地方執行；介面卡只需知道資產存放在哪裡以及如何讀取其清單。
| 主機 | 種類 | 預設根目錄 | 清單檔 |
|---|---|---|---|
| workbuddy | skill | 包含此技能的 skills 根目錄 | SKILL.md |
| claude-code | skill | ~/.claude/skills | SKILL.md |
| deepseek | 插件 | ~/.dsh/profiles/desktop（讀取 package.json 依賴） | package.json / plugin.json |
| generic | asset | 傳遞 --root 參數 | plugin.json / manifest.json / SKILL.md / package.json |
- 每種主機維護自己的註冊表：
registry.<host>.json—— 不會跨主機覆蓋。 - 基準線結果 + 黃金測試集是共享的，以資產名稱作為鍵值。
- 使用
--host <name> --root <path>執行；可在hosts.json中新增自訂主機。 console.py hosts顯示所有設定檔、解析後的根目錄以及偵測到的資產數量。
因此，在 WorkBuddy 中你評估的是 skills；在 DeepSeek 框架中你評估的是 plugins —— 同樣的指令，不同的介面卡。新增主機只需在 hosts.json 中增加一個條目（種類 + 根目錄 + 清單檔名），無需修改程式碼。
使用時機
- 部署新技能或插件之前（「做個 skill，按評測流程走」）。
- 模型版本升級之後，檢查現有技能是否退化。
- 當技能「感覺不太對勁」時——用數據確認，而非靠感覺。
- 決定保留、重寫或淘汰某個技能時。
- 向使用者推薦技能或插件時（契合度 + 證據）。
**不適用的時機：**一次性任務且無需重複使用的技能；純敘述性文件。
核心概念：版本指紋
指紋是折舊矩陣的行。
fingerprint = hash(能力面文件內容 + 相對路徑) # 口徑 v2-ability-surface
能力面包含的內容（其變更會實際影響行為的文件）：
- 包含：
SKILL.md、scripts/*、lib/*、dist/*、package.json、plugin.json、cordis.patch.yml、範本 - 排除：
README*、CHANGELOG*、LICENSE*、圖片/音訊/字型、*.map、鎖定檔、node_modules/、test*/、docs/
為什麼排除：編輯 README 並不會改變能力，但將其納入雜湊會導致指紋變動，從而產生虛假的 FINGERPRINT-DRIFT（「該資產已被編輯」）。插件會使這個問題更嚴重——一個安裝的插件可能包含 16 MB 的打包輸出以及一個 57 KB 的 README。
規則：
- 指紋不變 ⇒ 該行記錄保留；通過率下降表示模型退化。
- 指紋變更 ⇒ 變更是技能自身的責任，而非模型造成。 新舊行會共存，因此技能的編輯絕不會被錯誤歸因於模型漂移。
執行 python scripts/console.py scan 來計算指紋並將其儲存在註冊表中。fingerprint.py 是獨立的報告包裝；它不會觸碰註冊表。
能力表面（為何插件需要第二個維度）
指紋回答的是「文件是否變更」。它無法回答「是否仍然提供相同的功能」。
因此，scan 還會記錄每個資產的能力表面，並與前一次掃描進行差異比較：
| 資產種類 | 能力表面記錄內容 |
|---|---|
| plugin | patch (dsh.bundle.patch)、main/module、bin、exports、deps、skills、mcp、hooks、insert (cordis rows)、scripts |
| skill | tools (允許工具數量)、scripts |
當它變更時，scan 會明確印出：
[caps] 1 個資產的能力面有變化（這是「它對外提供的東西變了」，與通過率無關）：
plug-a +bin
這對插件為何重要： 插件退化的方式是「未註冊其工具 / 路由回傳 404 / 未執行其鉤子」——而非「回答得更差」。一組提示的黃金測試集對插件來說衡量的方向是錯的。能力表面差異可以捕捉到「v1.1.0 刪除了一個入口點」而無需啟動主機。
已知邊界（不要試圖掩蓋）： 能力表面是聲明的能力，而非觀察到的能力。對於清單說謊的插件（聲明了一個載入失敗的修補程式），這個方法無法捕捉。
執行時期證據（第三個軸，以及它做不到的事）
有兩種截然不同的東西都叫做「執行時期探針」。不要混淆：
| 主動探針 (active probe) | 被動證據 (passive evidence) — 已實作 | |
|---|---|---|
| 作用 | 啟動主機，詢問「你實際註冊了哪些工具」 | 讀取主機已寫入的日誌 |
| 成本 | DSH desktop 設定檔僅限 Electron——dsh --profile desktop --dump-config 會被拒絕；無無頭模式入口 → 需要逆向工程 IPC 或驅動 UI | 一次檔案讀取，約 10 毫秒 |
| 能捕捉到 | 所有情況，包括清單說謊的插件 | 插件記錄的任何內容 |
| 狀態 | 尚未建置 | console.py probe / skill_audit_probe |
probe 讀取 ~/.dsh/logs/*.log（可透過 hosts.json 中的 "logs" 設定），解析 <iso> [level] [source] message，將 source 等於已安裝資產名稱的行歸類，並標記符合失敗詞彙（fail|error|ENOENT|unavailable|timeout|…）的行。
在此機器上實際捕捉到的案例：
@wxg-prc-cpg/browser-skill-dsh-plugin 2 條故障跡象
bsk probe failed (spawn bsk ENOENT); browser tools will report install guidance…
檔案存在，清單有效，caps=4——所有靜態檢查都通過。插件已載入且工具已註冊，但它們無法運作：它所 shell 出去執行的 bsk CLI 不在 PATH 上。再多的檔案雜湊也找不到這個問題。
盲點（陳述它們，絕不隱藏）： 不記錄任何日誌的插件是隱形的；日誌輪替會清除舊的故障；沒人使用過的插件沒有證據；info 等級的故障是透過關鍵字匹配來捕獲，因此可能遺漏或誤報。沒有證據不等於健康證據——probe 會印出這句話本身，而不是一個綠色勾號。
已實作 vs 僅方法論（不要模糊這條界線）
下面的方法論範圍比程式碼更廣。使用者應該知道他們拿到的是一半還是全部：
| 領域 | 狀態 |
|---|---|
能力表面上的指紋、scan/status、能力差異 | 已實作 |
| 黃金測試架構 + 基準線合併（按資產合併，草稿保護） | 已實作 (baseline.py) |
通過率矩陣、≥20pp 門檻 + 方向、FINGERPRINT-DRIFT | 已實作 (regress.py) |
模型變更偵測 (bump/check)、每主機時間戳 | 已實作——但事件來源是手動的；排程的 check 會保持綠色直到有人執行 bump |
| 推薦/淘汰面板、需求建議、根據歷史挖掘的草稿 | 已實作（啟發式；建議並非證據） |
| 來自主機日誌的執行時期證據 | 已實作（被動式；僅限插件記錄的內容） |
| 消融測試、影子模式採用率、淨值 / Token 遙測 | 僅方法論——無程式碼 |
| 觸發精確度/召回率、環境調和、風格基準線 | 僅方法論——無程式碼 |
| K≥3 次重放、LLM 評審交叉驗證 | 未實作；目前的判定是 K=1 的自我評估 |
risk 欄位 | 維護表面代理——非價值 |
如果此檔案中的某項主張無法追溯到標記為「已實作」的行，請將其視為對執行審計人員的建議，而非工具會為他們做的事。
判斷 1 — 能力退化
四個步驟：
- 從歷史記錄中建立黃金測試集，而非手動建立。 挖掘過往對話：使用者接受而無異議 → 正面重放；使用者反對或要求重寫 → 負面重放。重放就是迴歸。使用者自己的使用歷史就是語料庫——不需要發明測試集。
- 在同一黃金測試集中執行兩個模型，K≥3（LLM 評審評分案例：K≥5，因為評審本身有雜訊）。記錄每個 (指紋, 模型版本) 組合的通過率。
- 決策規則： 下降 ≥20pp 且方向一致 → 回報退化；低於門檻 → 列入「波動觀察」。這將「這個輸出很奇怪」轉化為可重現的標準。
- 歸因，而不僅僅標記。 檢查中間產出：
- 工具呼叫錯誤 / 格式變更 → 修正工具描述。
- 輸出結構正確，內容錯誤 → 重寫指示。
- 應該觸發但沒有 → 修正觸發描述。
- 所有中間產出都正確，只有最終結果錯誤 → 模型內部退化；標記技能為「單一模型依賴」，等待模型修正。
「7 個退化，2 個建議重寫」這一行是步驟 4 輸出的可歸因子集——這正是讓報告可行動化的關鍵。
判斷 2 — 新技能是否好？
分為兩個可衡量的軸向：效果（更好的結果）和經濟性（更低的成本）。
- 部署前消融測試。 相同任務批次，兩組：A 組無技能，B 組有技能。記錄成功率、人工修正次數、Token 成本。
淨效益 = 成功率提升 × 任務頻率 − 邊際成本一個能將成功率提升 30%，但每年只觸發 3 次且每次消耗 50k Token 的技能，是負債，而非資產。 - 部署後影子模式。 新技能以安靜模式執行：產生建議但不自動執行；記錄「本來會發生什麼事」。觀察採用率（被接受 vs 覆寫）。採用率是判斷「好」的最終標準，比任何離線指標都誠實。邊界：寫入型操作技能（刪除檔案、發送郵件）在影子模式中只能模擬或註解，絕不能真正執行。
- 淨值卡片。 每個技能一個儀表板：呼叫次數、成功率、採用率、平均 Token 數、累積淨效益。連續 90 天淨值為負 → 建議重寫或淘汰。這是折舊表的使用者端。
判斷 3 — 它適合「這個」使用者嗎？
「適合你」= 觸發準確 + 假設成立 + 風格匹配。全部可以自動化：
- 觸發精確度（最影響感受，也最常被跳過）。取樣歷史中的正例（應觸發）和負例（看似相關但不應觸發——「修復這個 bug」vs「解釋什麼是 bug」）。重放 → 精確度/召回率。低精確度 = 惱人（過度觸發）；低召回率 = 安裝了但沒用。先手動標記 10–20 個，然後半自動化，LLM 成本為零。
- 環境調和（已安裝 ≠ 可執行）。技能元資料聲明依賴：哪些工具 / MCP / 權限 / 路徑習慣 / 語言，加上隱含的模型能力假設（長上下文、程式碼執行、多模態）。與使用者的實際環境進行比對；缺少 → 紅旗標記。「假設使用 macOS」、「輸出日文」、「需要 200k 上下文」——看不見的假設是技能未被使用的第一大原因。這會回饋到判斷 1：能力假設失敗 = 無聲退化。
- 風格基準線（權重最低）。以使用者的歷史輸出和
USER.md作為參考；LLM 評審比較格式、語言、冗長程度。僅用於打破得分相同技能之間的平手。
內嵌工作流程（用於「建立新技能」）
當使用者要求建立技能時，在交付之前內嵌執行此流程：
- 環境調和——使用者的環境是否滿足技能聲明的依賴和功能假設？
- 觸發重放——重放 10–20 個取樣案例；報告精確度/召回率。
- 消融測試——在一個小型任務批次上，測量提升 vs 成本。
- 進入監控——通過後，註冊指紋和黃金測試集；常駐主控台會在每次模型更新時重新執行。
基於需求的建議（當沒有技能匹配時）
這是「空貨架」的行為：使用者（尤其是零技能/插件的使用者）詢問某個已安裝技能未涵蓋的需求。不要只說「我做不到」——要揭露這個缺口並提供填補的選項。
- 從對話中偵測需求：任務類型 + 領域（例如「季度財務報告」→ 財務/分析；「去除 AI 語氣」→ 人性化工具；「建立一個儀表板」→ 前端/圖表）。
- 先檢查註冊表——執行
python scripts/console.py suggest --need "<need>"。它會回傳：✓ 你已有可用的 skill/插件：<name>→ 直接使用，無需安裝任何東西；或💡 建議新增：[install:<slug>] <title>→ 沒有涵蓋，推薦該類別。
- 如果未涵蓋，搜尋市場以尋找真實的候選方案（skills/plugins/experts），並提供一張附有證據的卡片：功能說明、為何適合此需求、來源。絕不自動安裝——由使用者選擇。
- 在執行程式碼之前，先搜尋已安裝的註冊表。 安裝是對使用者環境的寫入操作——只有在使用者實際說「安裝它」之後才執行。