SEG：技能評估圖譜：代理技能審計與優化的程序化驅動工具
將代理技能轉化為可靠、Token 高效、符合生產標準的工程資產。評估觸發精確度、漸進式揭露架構、行為引導、執行確定性、操作安全性與 Token 經濟性。
快速參考矩陣
| 關注事項 | 目的 | 權威資源 |
|---|---|---|
| 標準術語 | 權威詞彙與領域定義 | references/terminology.md |
| 六大支柱審計評分量表 | 客觀 1–5 分評分定義 | references/audit-rubric.md |
| 反模式目錄 | 14 種常見技能缺陷的診斷指南 | references/anti-patterns.md |
| 上下文工程 | 多層次漸進式揭露模式 | references/progressive-disclosure-patterns.md |
| 評估圖譜與循環 | 自主評估者循環引擎操作手冊 | references/workflow-graph-and-evaluator-loop.md |
| 工具鏈相容性 | 跨平台工具對應 (Antigravity/Claude/Codex) | references/harness-tool-matrix.md |
| 行為試驗執行器 | 對照組與實驗組評估及現場試驗 | scripts/eval_skill.py |
| 能力聲明審計 | 技術現實與證據分類 | references/claim-audit.md |
| 計分卡範本 | 標準化評估報告範本 | assets/skill-audit-scorecard-template.md |
| 範例計分卡 | 示範性完整評估報告 | assets/example-scorecard.md |
| 自我審計計分卡 | SEG 自身基線審計計分卡 | assets/self-audit-scorecard.md |
| 標準對齊 | 應用型 AI Wiki 14 步驟框架 | references/wiki-standard-alignment.md |
| 代理保護 | 反幻覺貢獻者合約 | assets/agent-contributor-contract-template.md |
[!重要] 標準術語：使用 references/terminology.md 作為 SEG 的標準詞彙。未更新詞彙表前，請勿為已定義的概念引入同義詞。
工作流程圖譜架構
[節點 1：接收與範圍界定]
│
▼
[節點 2：並行評估者 DAG 執行]
(綱要, 鏈接, Token, 安全/隱私, 可攜性, 觸發路由, 行為策略)
│
▼
[節點 3：合併多節點證據]
│
▼
[節點 4：多閘門評估者預言機]
│
┌───────┼───────────────────────────────┐
▼ ▼ ▼
[節點 5A：接受] [節點 5B/5C：修訂] [節點 5D：升級]
(計分卡與收據) (沙箱驗證 -> 預覽/變異) (需人工介入)
程序化執行驅動器
審計或優化代理技能時，請依序執行以下步驟：
步驟 1：識別目標技能並驗證範圍
- 找到包含
SKILL.md的目標目錄。 - 檢查
SKILL.md、references/、scripts/與assets/中的套件清單。 - 驗證主機工具鏈相容性清單 (
.codex-plugin/plugin.json、CLAUDE.md、AGENTS.md、.agents/plugins/marketplace.json)。
步驟 2：閱讀標準術語
記錄發現之前，請查閱 references/terminology.md。確保所有反饋與報告均使用精確的標準名稱（例如 靜態品質分數 (Static Quality Score)、預言機裁決 (Oracle Verdict)、評估完整性閘門 (Evaluation Integrity Gate)、預變異快照 (Pre-mutation Snapshot)）。
步驟 3：執行評估圖譜
透過 scripts/run_loop.py 執行模塊化並行評估 DAG：
# 唯讀評估與差異預覽 (預設)
python "<skill-dir>/scripts/run_loop.py" "<target-skill-path>" --target-score 95 --max-iterations 3
# 接受時交付計分卡
python "<skill-dir>/scripts/run_loop.py" "<target-skill-path>" --scorecard "<target-skill-path>/scorecard.md"
評估者節點按並行依賴波次執行：
schema：驗證 YAML 前置元素、命名與必填欄位。links_syntax：解析相對鏈接、單跳躍規則與程式碼圍欄。tokens：剖析五層漸進式揭露的 Token 預算。safety_privacy：偵測破壞性指令與工作站路徑暴露。portability：驗證 OpenAI Codex 插件與市集清單。trigger_routing：檢查前置元素描述的觸發器與負面邊界。behaviour_policy：強制執行反合理化指南。
步驟 4：合併證據並評估閘門
來自所有節點的證據被合成為 聯合證據 (JoinedEvidence)。評估者預言機 (EvaluatorOracle) 強制執行五道強制閘門：
- 評估完整性閘門 (閘門 0)：若任何評估者遭遇未處理的錯誤、超時或意外跳過，則關閉。
- 規範符合性閘門：若任何節點報告
規格錯誤 (SPECIFICATION_ERROR)（例如無效的市集綱要或損壞的前置元素），則失敗。 - 安全與隱私閘門：若偵測到破壞性指令或工作站路徑洩露，則失敗。
- 鏈接完整性閘門：若發現損壞的相對 Markdown 鏈接，則失敗。
- 靜態品質分數策略閘門：驗證總分是否達到
--target-score（預設值：95）。
步驟 5：處理預言機裁決
接受 (ACCEPT)(節點 5A)：所有強制閘門通過，且靜態品質分數 ≥ 95。生成計分卡與評估收據。狀態：已完成 (COMPLETED)（若已套用修復則為已變異 (MUTATED)）。修訂 (REVISE)(節點 5B/5C)：偵測到可修復缺陷。前進至步驟 6。升級 (ESCALATE)(節點 5D)：遇到不可解決的阻礙或迭代上限已達。停止並附上詳細阻礙清單，等待人工介入。狀態：已升級 (ESCALATED)。
步驟 6：推導修復、在沙箱中驗證，並以權威進行變異
當裁決為 修訂 (REVISE) 時：
plan_repairs()從發現結果推導出確定性修補提案。修復隔離器 (RepairIsolator)將提案暫存於隔離的暫存沙箱 (tempfile.TemporaryDirectory)。- 在沙箱內使用 DAG 與預言機重新評估候選方案，以驗證：
- 評估完整性閘門通過。
- 強制閘門未退步。
- 未引入新的
錯誤 (ERROR)發現。 - 靜態品質分數或發現計數嚴格改善。
- 若候選方案通過驗證：
- 預設 (唯讀)：顯示統一差異供人工審閱。磁碟上的目標技能保持不變。狀態：
已預覽 (PREVIEWED)。 - 搭配
--apply：將驗證過的修補寫入磁碟，並附加預變異快照保護（一個唯一命名的同級復原目錄）。狀態：已變異 (MUTATED)。
- 預設 (唯讀)：顯示統一差異供人工審閱。磁碟上的目標技能保持不變。狀態：
- 循環恢復進行下一次迭代，直到達到
接受 (ACCEPT)或最大迭代次數耗盡。
步驟 7：可選執行行為試驗
捆綁的版本化目錄位於 evaluations/scenarios/。執行 SEG 前，請先從 requirements.txt 安裝 Python 依賴。
如需動態驗證技能執行，請執行 scripts/eval_skill.py：
# 反合理化場景的離線模擬
python "<skill-dir>/scripts/eval_skill.py" "<target-skill-path>"
# 使用隔離主目錄的即時認證 Codex CLI 試驗
python "<skill-dir>/scripts/eval_skill.py" "<target-skill-path>" --live --harness codex --trials 1 --timeout 90
步驟 8：產出有證據支援的計分卡
透過 scripts/audit_skill.py 生成最終審計計分卡：
python "<skill-dir>/scripts/audit_skill.py" "<target-skill-path>" --scorecard "<output-scorecard.md>"
計分卡嚴格反映來自 DAG 與預言機的測量證據：
- 建議與預言機裁決 (
接受 (ACCEPT)、修訂 (REVISE)、升級 (ESCALATE)) 一致。 - 測量到的評分量表支柱反映評估者指標。
- 未測量的支柱明確報告
未評估 (NOT EVALUATED)。 - 儲存一份防篡改的評估收據，內含最終執行狀態的 SHA256 摘要。
品質不變量
- 零損壞鏈接： 每個相對 Markdown 鏈接都必須在技能目錄內可解析。
- 嚴格單跳躍： 無參考檔案可連結至另一個參考檔案。
- 預算合規：
SKILL.md不得超過 300 行或 2500 個 Token。 - 自包含可攜性： 零硬編碼機器路徑或使用者主目錄。
- 證據完整性： 計分卡與收據必須反映可驗證的證據，不得包含捏造的分數。