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-*.mdTDD 卡片格式。references/rubric-library.md— 针对每个目标类别的起始维度。references/analysis-playbook.md—analyze信号、头脑风暴视角,以及机会如何保持接地。
安全
- ultraeval 只读取目标,并写入
<RUN>目录下。它从不执行目标的代码;执行子智能体可能会运行目标自身的命令(测试、门控)——请对不受信任的仓库进行沙箱隔离。 clean --run <RUN>仅移除派生的门控/渲染工件并保留交付物;--all移除整个运行。