Community寫作與編輯github.com

maxgfr/ultraeval

透過多智能體工作流程評估技能或程式碼庫,將每個發現錨定在真實的 file:line,並產生可供 AI 利用的 TDD 修復待辦清單。

ultraeval 是什麼?

ultraeval 是一個多智能體評估系統,用於深入審查技能(skill)或程式碼庫(codebase)。它採用結構化的步驟流程,首先初始化運行配置,然後生成包含多智能體合約和測試計劃的工作流程。在執行階段,它會進行研究、測試規劃、執行並通過門控(gate)來驗證每個發現的真實性:每個發現都必須精確指向目標中的實際 `file:line`,這是“接地門控”(grounding gate)的強制要求。任何不達標的發現都會被拒絕。之後,系統會執行驗證(verify)來確保發現的語義正確性,然後生成一個按優先級排序的待辦清單(BACKLOG.json),並為每個確認的發現產生單獨的 TDD 修復卡片(fixes/FIX-*.md)。最後,它會根據維度(dimensions)對目標進行評分(score),並渲染儀表板(render)來呈現結果。该系统支持三種模式:`audit`(僅缺陷)、`improve`(僅改進機會)和 `deep`(兩者)。它依賴於明確定義的參考文件(如 `eval-playbook.md`、`gate-contract.md`、`tdd-remediation.md`)來驅動整個流程。該工具專為致能模型(如 Claude Code、Cursor、Codex)設計,以實現自動化、可重複的評估和修復。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add maxgfr/ultraeval

Installed? Explore more 寫作與編輯 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

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-*.md TDD 卡片格式。
  • references/rubric-library.md — 每個目標類別的起始維度。
  • references/analysis-playbook.md — analyze 訊號、腦力激盪視角,以及機會如何保持接地。

安全性

  • ultraeval 只會讀取目標,並在 <RUN> 下寫入資料。它永遠不會執行目標的程式碼;執行器子代理可能會執行目標自身的命令(測試、門控)——應將不受信任的儲存庫放在沙盒中。
  • clean --run <RUN> 僅移除衍生的門控/渲染工件,並保留交付物;--all 則移除整個運行。

相關技能