ultraeval:評估技能或程式碼庫 → 接地、可供 AI 利用的修復文件
Markdown 即程式。一個微小的確定性引擎用於搭建運行框架、生成多智能體工作流程,並強制執行接地門控;你(以及你分派出去的子代理)負責進行研究、判斷和撰寫。每個發現都必須解析為目標中的真實 file:line——門控會拒絕虛構的發現——而輸出是一個按優先級排序的待辦清單,以及每個修復對應的 TDD 卡片,可供模型執行紅→綠→重構。
使用時機
- "評估/審計/評分/給分這個技能(或儲存庫)";"它是否已準備好投入生產/是否符合預期?"
- "審查此程式碼庫,並給我一個修復計畫 / 一個 TDD 待辦清單。"
- 在變更後對自己的技能進行迴歸測試,或是在信任第三方技能前對其進行審查。
不適用於:快速的單檔案程式碼審查(直接閱讀即可);執行目標自身的測試套件(應直接執行)。
循環
init → plan → run(research → test-plan → execute+gates → judge → results) → verify → backlog(TDD) → score → render
一切皆為簡單的 node <skill-dir>/scripts/ultraeval.mjs <cmd> 呼叫。分派子代理是生成的工作流程所編碼的一種優化——絕非必要條件。
需要確認的輸入
- Target — 要評估的技能/儲存庫的路徑(或使用者已在本機克隆的 git URL)。
- Kind —
skill或codebase(自動偵測:有 SKILL.md 即為 skill)。可使用--kind覆蓋。 - Category — 例如 "agent skill"、"CLI"、"library"、"web app"、"security tool"。用於引導初始評分量表。
- Mode —
audit(缺陷,預設)·improve(接地改進機會)·deep(兩者)。使用--mode設定。
模式與改進發現
ultraeval 會發現兩種事物,兩者都需接地並通過門控:
- 缺陷 (
audit、deep) — 有問題的地方;每個缺陷都引用真實的file:line。 - 機會 (
improve、deep) — 一個接地的改進線索(內部健康度 以及 產品/能力),評級為 影響力 × 工作量。透過analyze(確定性熱點/依賴/變更/測試缺口)→brainstorm(發散性視角)→brainstorm --rank(將排序後的機會摺疊到findings.json中,kind:"opportunity")來發現。相同的門控適用——一個機會必須錨定在真實的程式碼/指標上,因此它永遠不會變成模糊的 "全部重寫"。請參閱references/analysis-playbook.md。
對於 improve/deep 模式,plan 會將分析和腦力激盪階段添加到生成的工作流程中。
步驟
1. 搭建運行框架。
node <skill-dir>/scripts/ultraeval.mjs init --target <PATH> --out <RUN> [--kind skill|codebase] [--category "<c>"]
使用起始維度寫入 eval.config.json(請參閱 references/rubric-library.md)。
2. 生成工作流程 + 子代理合約。
node <skill-dir>/scripts/ultraeval.mjs plan --run <RUN>
產生 <RUN>/eval.workflow.mjs(一個準備好啟動的多智能體工作流程,其中嵌入了絕對的引擎和目標路徑)、<RUN>/agents/*.md(派發合約)、TEST-PLAN.template.md、dimensions.json、findings.schema.json。
3. 執行評估。 使用你的工具套件的工作流程工具啟動生成的工作流程:
Workflow({ scriptPath: "<RUN>/eval.workflow.mjs" })。它會串接 研究 → 測試計畫 → 執行 → 發現 → 門控 → 評判 → 結果 並自行調用引擎門控。如果你沒有工作流程工具,則手動執行各個階段:閱讀每個 agents/<stage>.md 並根據合約分派子代理。請參閱 references/orchestration.md。每個子代理都會獲得 <skill-dir>/scripts/ultraeval.mjs 的絕對路徑——它有自己的當前工作目錄(cwd),無法解析相對路徑(plan 已將絕對路徑嵌入工作流程中)。
4. 接地每個發現。 將結果合併到 <RUN>/findings.json(結構:references/gate-contract.md)。每個發現引用 evidence[].ref 作為目標中的 path:line,或作為所產生日誌中的 run:relpath#Lnn。然後:
node <skill-dir>/scripts/ultraeval.mjs check --run <RUN>
修復 findings.json 直到它以狀態碼 0 退出——修復或刪除未接地的發現;切勿削弱門控。
5. 驗證(對抗性退出門控)。
node <skill-dir>/scripts/ultraeval.mjs verify --run <RUN> # 寫入 VERIFY.todo.json
# 填入每個裁決:supported | partial | refuted | unsupported(使用懷疑論子代理;使用 --shards N --shard i 進行平行化)
node <skill-dir>/scripts/ultraeval.mjs verify --run <RUN> --apply <verdicts.json>
node <skill-dir>/scripts/ultraeval.mjs check --run <RUN> --semantic --require-verify # 退出門控 — 在此之前絕不提交
refuted 的發現必須設定為 dismissed。supported/partial 的發現則保留。
6. 修正 — 交付物。
node <skill-dir>/scripts/ultraeval.mjs backlog --run <RUN> --tdd
產生 BACKLOG.json(一個機器可讀、按優先級排序的任務列表,下游代理可以執行)、REMEDIATION.md,以及每個確認發現對應的一個 fixes/FIX-*.md TDD 卡片——每個卡片包含一個 RED(失敗)的測試優先規範、GREEN 的變更,以及一個 VERIFY 命令。請參閱 references/tdd-remediation.md。
7. 評分 + 渲染 + 呈現。
node <skill-dir>/scripts/ultraeval.mjs score --run <RUN> # judges.jsonl + dimensions -> scorecard.json (0-100 + meets-expectations)
node <skill-dir>/scripts/ultraeval.mjs render --run <RUN> # index.html + index.md 儀表板(顯示裁決結果)
score 將評審小組的 judges.jsonl 和設定的維度歸納為加權裁決;一個即時的 P0 發現(或任何評審投反對票,或分數低於門檻)會將 meets-expectations 上限設為 false。呈現裁決結果、P0/P1 待辦清單標題,以及修復代理應使用的路徑(RESULTS.md、BACKLOG.json、fixes/)。
CLI 的退出碼:0 正常 / 門控通過 · 1 門控失敗(check/verify) · 2 使用方式或執行時期錯誤。
8.(選擇性)驅動修復。 將每個 fixes/FIX-*.md 交給一個建置代理來執行 TDD——卡片的撰寫方式使得它可以直接進行紅→綠→重構,而無需重新推導問題。
接地合約
一個發現只有在其證據能夠解析時才可信。check 會開啟目標中每個 path:line,並確認該行存在且位於範圍內;過時/虛構的行是嚴重失敗。然後 verify 會詢問一個懷疑論者,引用內容是否實際上支持該主張。這個雙層門控(結構 + 語義)是整個工具的重點——完整的語法和通過/失敗規則在 references/gate-contract.md 中。
方法與評分量表
references/eval-playbook.md— 研究→測試計畫→執行→評判→結果的方法,以及如何為每個維度建立評分量表。references/orchestration.md— 生成的工作流程、子代理派發合約,以及分派時不變的絕對<skill-dir>路徑。references/gate-contract.md—findings.json結構、證據參考語法,以及check/verify通過或失敗的具體條件。references/tdd-remediation.md—BACKLOG.json的形狀和fixes/FIX-*.mdTDD 卡片格式。references/rubric-library.md— 每個目標類別的起始維度。references/analysis-playbook.md—analyze訊號、腦力激盪視角,以及機會如何保持接地。
安全性
- ultraeval 只會讀取目標,並在
<RUN>下寫入資料。它永遠不會執行目標的程式碼;執行器子代理可能會執行目標自身的命令(測試、門控)——應將不受信任的儲存庫放在沙盒中。 clean --run <RUN>僅移除衍生的門控/渲染工件,並保留交付物;--all則移除整個運行。