Community写作与编辑github.com

maxgfr/ultraeval

使用多智能体工作流评估技能或代码库,将每个发现锚定到真实的 file:line,并生成可供AI利用的TDD修复待办列表。这是一个 skills.sh 智能体技能。

ultraeval 是什么?

ultraeval 是一个基于多智能体工作流的评估工具,专为技能(skill)或代码库(codebase)设计。它通过一个微型确定性引擎来编排运行、生成多智能体工作流,并强制执行“接地门控”(grounding gate),确保每个发现都指向目标中的真实 `file:line`,从而消除幻觉。核心流程包括初始化、规划研究、执行测试与门控、验证、生成包含TDD卡片的修复待办列表,以及最终评分与报告呈现。支持 `audit`(缺陷)、`improve`(改进机会)和 `deep`(兼顾两者)三种模式,并通过 `check` 和 `verify` 两层门控(结构性和语义性)来保证发现的可信度。输出物包括机器可读的 `BACKLOG.json` 和每个修复的 `FIX-*.md` TDD卡片,可直接由构建智能体实现。它支持在终端中通过 Node.js 脚本调用,并可与 Workflow 工具集成以实现子智能体并行。

兼容平台✓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 即程序。一个微小的确定性引擎搭建运行框架、生成多智能体工作流,并强制执行接地门控;你(以及被分发的子智能体)负责研究、判断和撰写。每个发现必须解析到目标中的一个真实 文件:行号——门控会拒绝幻觉——输出是一个优先待办列表,外加每个修复对应的TDD卡片,模型可以参照它执行 红→绿→重构。

何时使用

  • "评估 / 审计 / 评级 / 打分此技能(或仓库)"; "它是否达到生产就绪 / 符合预期?"
  • "审查此代码库并给出修复计划 / TDD 待办列表。"
  • 在更改后对自己的技能进行回归验证,或在信任第三方技能前对其进行审查。

不适合:快速审查单文件代码(直接阅读即可);运行目标自身的测试套件(直接执行)。

循环

init → plan → run(research → test-plan → execute+gates → judge → results) → verify → backlog(TDD) → score → render

所有操作都是通过 node <skill-dir>/scripts/ultraeval.mjs <cmd> 调用。分发子智能体是生成的工作流所编码的优化——并非必需。

需要确认的输入

  • 目标 — 要评估的技能/仓库的路径(或用户已在本地克隆的 git URL)。
  • 种类 — skill 或 codebase(自动检测:存在 SKILL.md 则为 skill)。可通过 --kind 覆盖。
  • 类别 — 例如 "agent skill", "CLI", "library", "web app", "security tool"。影响起始的评估维度。
  • 模式 — audit(缺陷,默认)· improve(接地改进机会)· deep(两者)。通过 --mode 设置。

模式与改进发现

ultraeval 发现两种事物,均需接地且门控:

  • 缺陷(audit, deep)— 某处存在问题;每个缺陷引用一个真实的 文件:行号。
  • 机会(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。每个子智能体都会获得 /scripts/ultraeval.mjs 的绝对路径——它有自己的工作目录,无法解析相对路径(plan 已将绝对路径烘焙到工作流中)。

4. 接地每个发现。 将结果合并到 <RUN>/findings.json(模式:references/gate-contract.md)。每个发现引用 evidence[].ref,格式为 路径:行号(在目标中)或 run:相对路径#L行号(在生成的日志中)。然后:

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 打开目标中的每个 file: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 移除整个运行。

相关技能