maxgfr/ultraeval

# ultraeval [](https://github.com/maxgfr/ultraeval/actions/workflows/ci.yml) ultraeval 是一个 [Agent Skill](https://www.skills.sh/)（开放的 agent-skills 生态系统）。一个微型的零依赖引擎为运行搭建脚手架，**生成 workflow + subagent 合约**，并强制执行 grounding gate；由 AI 完成研究、判断和撰写。它是已被产品化的方法：与用于审计整个技能家族的方法相同，将其打包，以便您可以在任何目标上重放它。 ## 安装 ``` npx skills add maxgfr/ultraeval # into the current project (committed, team-shared) npx skills add -g maxgfr/ultraeval # globally ``` 无需 `npm install`，无需 API keys —— 该引擎是一个单一的已提交 `.mjs` bundle。 ## 它的功能 ``` init → plan → run(research → test-plan → execute → findings) → gate(check → verify(+honeypots) → check --semantic --require-verify) → judge → score(+history) → backlog(TDD) → render → fix → verify-fix ``` - **`plan`** 生成 `eval.workflow.mjs` —— 一个准备好启动的、根据您的目标参数化的多 agent Workflow —— 外加 `agents/*.md` 分发合约。这就是“生成 workflow 和 subagents”的部分。 - 每个发现都必须解析为目标（或生成的运行日志行）中真实的 `file:line`。**`check` 拒绝虚构或过时的引用**；**`verify`** 以对抗的方式确认被引用的内容确实支持该声明。 - **`backlog --tdd`** 将已确认的发现转化为 `BACKLOG.json`（机器可读、按优先级排序）以及针对每个发现的一个 `fixes/FIX-*.md` **TDD 卡片**（RED 测试先行失败 → GREEN 变更 → VERIFY）。 - **流程是规范化的。** 每个评分维度都锚定到一个外部参考（代码使用 ISO/IEC 25010:2023，技能使用 ISO 25010/25059 复合标准，各类别使用 29148/WCAG/OWASP），P0/P1/P2 严重性已被编纂成典（CVSS 对齐的区间），并且每次运行都在版本化协议下记录 **来源**（引擎/协议/评分标准版本，目标 git SHA）—— `compare` 拒绝读取不兼容运行之间的 delta。规范文本：[`references/protocol.md`](./skills/ultraeval/references/protocol.md)。 ## 它生成的内容 ``` / eval.config.json # target, kind, category, scored dimensions eval.workflow.mjs # the generated multi-agent Workflow agents/*.md # subagent dispatch contracts research/.md # cited methodology per dimension TEST-PLAN.md # every functionality + gate to test runs/core.md, live.md # deterministic + live evidence (cited by findings) findings.json # grounded findings (the gate enforces file:line resolution) VERIFY.todo.json/.json # adversarial claim↔evidence verdicts RESULTS.md / SUMMARY.md # scored report (claims cite [F#]) BACKLOG.json # priority-ordered fix tasks fixes/FIX-*.md # per-fix TDD cards REMEDIATION.md # the human-readable plan index.html / index.md # dashboard ``` ## 独立 CLI（引擎） ``` ENGINE=node scripts/ultraeval.mjs $ENGINE init --target ../my-skill --out /tmp/eval --category "agent skill" --mode deep # add --since origin/main for a diff-scoped PR-gating run $ENGINE init --target ../my-app --out ../my-app/.ultraeval/metier --category métier --scope "src/domain/**" # business-only eval: métier rubric + file scope (check fails out-of-scope findings) $ENGINE oneshot --target ../my-app --out /tmp/quick [--category ...] [--scope ...] # single-pass quick eval: ONESHOT.md contract, structural gate kept, indicative verdict; plan --run upgrades it $ENGINE status --run /tmp/eval # pipeline checklist + the exact next command $ENGINE plan --run /tmp/eval # generate the workflow + agents (Analyze+Brainstorm stages in improve/deep) $ENGINE analyze --run /tmp/eval [--since ] [--json] # deterministic hotspots/deps/churn/test-gaps -> analysis.json $ENGINE brainstorm --run /tmp/eval # divergent lenses -> BRAINSTORM.todo.md $ENGINE brainstorm --run /tmp/eval --rank [--check] # fold ranked, grounded opportunities into findings.json (and gate them) $ENGINE compare --run /tmp/eval-new --base /tmp/eval-old # diff two runs -> COMPARE.md (score Δ, resolved, introduced) $ENGINE check --run /tmp/eval # grounding gate (exit 1 on a hallucinated citation); add --json for the CheckResult in CI $ENGINE verify --run /tmp/eval --honeypots 3 # adversarial worklist + planted traps that catch a rubber-stamping skeptic $ENGINE verify --run /tmp/eval --apply verdicts.json $ENGINE check --run /tmp/eval --semantic --require-verify # exit gate (also fails while a honeypot failure is unresolved) $ENGINE backlog --run /tmp/eval --tdd # BACKLOG.json + fixes/FIX-*.md (dependsOn derived from shared files) $ENGINE fix --run /tmp/eval --workflow # one autonomous fix-agent contract per task + fix.workflow.mjs $ENGINE verify-fix --run /tmp/eval --task FIX-001 # replay the task's verify command; stamp status done + verifiedAt $ENGINE score --run /tmp/eval --history # scorecard.json (verdict + weight-sensitivity + judgesCalibrated) + ledger line $ENGINE history --run /tmp/eval # read the score trend back (overall vs bar, Δ, counts); --json for CI $ENGINE rejudge --run /tmp/eval --out /tmp/eval-rj # fresh judge panel over the same artifacts (test-retest stability) $ENGINE render --run /tmp/eval # index.html + index.md (shows the verdict) $ENGINE clean --run /tmp/eval # remove derived artifacts (keeps deliverables) ``` **模式。** `--mode audit`（缺陷，默认） · `improve`（有根据的改进**机会** —— 包括内部健康状况*以及*产品/能力，按影响力 × 工作量评估） · `deep`（两者兼有）。机会是通过 `analyze` → `brainstorm` 发现的，并受*相同*的 grounding gate 约束，因此一个结论总是锚定到真实代码或真实指标上 —— 绝不是含糊的“重写一切”。`render` 显示影响力 × 工作量矩阵，并标记快速获益点。 `init --category` 自动选择合适的评分标准（security → 精确率/召回率/误报率；métier/business/domain → 仅业务逻辑维度；web → +无障碍设计/身份验证；research → 忠实度/检索；requirements → 29148）。`init --scope ""` 对 eval 进行文件范围限定：agent 绑定到 glob 模式，如果发现的引用仅存在于范围之外，`check` 将判定失败（标记 `scope-exempt` 以保留合理的横切发现）。`check` 还会验证发现记录的 schema（id/severity/status/evidence/kind），而不仅仅是 grounding。`init --bar ` 校准每次运行达到预期的阈值（默认为 80）；它会被标记在记分卡和账本中，当两次运行以不同的标准评分时，`compare` 会发出警告。退出代码：**0** 正常/通过 gate · **1** gate 失败 · **2** 使用/运行时错误。运行 `node scripts/ultraeval.mjs --help` 获取完整的参数列表。 ## 参考包 该技能是 markdown 优先的 —— [`skills/ultraeval/references/`](./skills/ultraeval/references/) 是其实质内容，并且 `tests/docs-drift.test.ts` 通过将每个评分标准集、实时场景块、严重性行和 CLI 参数与引擎自身的值进行比较，来保持其准确性。 | reference | 用途 | |---|---| | [`protocol.md`](./skills/ultraeval/references/protocol.md) | 规范流程 (RFC-2119)：阶段进入/退出、gate 阈值、严重性、来源 | | [`worked-example.md`](./skills/ultraeval/references/worked-example.md) | 一个真实的、可重现的端到端运行 —— 包括被 gate 拒绝的发现 | | [`methodology-library.md`](./skills/ultraeval/references/methodology-library.md) | 如何评估每个维度：指标、测量、0–5 锚点、什么会欺骗它 —— 这样 Research 是在精炼而不是重复搜索 | | [`finding-quality.md`](./skills/ultraeval/references/finding-quality.md) | 可辩护发现的门槛、严重性判定程序、误报目录 | | [`gate-contract.md`](./skills/ultraeval/references/gate-contract.md) | `findings.json` schema，证据语法，确切说明 `check`/`verify` 在什么情况下失败和警告 | | [`tdd-remediation.md`](./skills/ultraeval/references/tdd-remediation.md) | `BACKLOG.json`、TDD 卡片以及 `red.expectedNew` 测试优先 gate | | [`rubric-library.md`](./skills/ultraeval/references/rubric-library.md) · [`live-scenarios.md`](./skills/ultraeval/references/live-scenarios.md) | 起始维度和按类别划分的规范化实时场景 | | [`orchestration.md`](./skills/ultraeval/references/orchestration.md) · [`eval-playbook.md`](./skills/ultraeval/references/eval-playbook.md) · [`analysis-playbook.md`](./skills/ultraeval/references/analysis-playbook.md) | workflow、方法论以及机会如何保持有根据 | | [`troubleshooting.md`](./skills/ultraeval/references/troubleshooting.md) | 当运行停滞或 gate 变红时的症状 → 原因 → 命令 | **自动 gitignore。** 当运行目录（`--out`）位于 git 仓库中时，`init`/`oneshot` 会以幂等方式将其添加到该仓库的 `.gitignore` 中（常规的 `.ultraeval/` 容器只需一行即可覆盖所有运行）。`--no-gitignore` 可选择退出；`evals/history.jsonl` —— 提交的得分账本 —— 永远不会被忽略。 **单次 evals。** `oneshot` 为单次运行搭建脚手架（`ONESHOT.md`：一个 agent，一次通过所有维度，发现结果采用相同的受 gate 限制的 schema）。结构性的 `check` gate 依然适用；verify/judges 不在合约范围内，因此结论仅具有指示性 —— 完整的 pipeline 依然是默认选项，而 `plan --run ` 会就地升级单次运行。 ## 作为 MCP server 使用 该 skill 通过 shell 调用 CLI 并解析其输出。而 MCP server 跳过了这两步： 您的 agent 以带类型的 tools 形式调用 ultraeval，输入为 JSON schema，输出为结构化结果。相同的引擎，相同的运行目录，无需 wrapper。 ``` # stdio — 默认选项，也是 Claude Code / Claude Desktop / Cursor 所期望的 claude mcp add ultraeval -- node /abs/path/to/scripts/ultraeval.mjs mcp # 或通过 HTTP，在 loopback 上 node scripts/ultraeval.mjs mcp --transport http --port 7344 claude mcp add --transport http ultraeval http://127.0.0.1:7344/mcp ``` ``` // Claude Desktop takes stdio servers only — a remote URL here will not work. { "mcpServers": { "ultraeval": { "command": "node", "args": ["/abs/path/to/scripts/ultraeval.mjs", "mcp"] } } } // Cursor, HTTP: { "mcpServers": { "ultraeval": { "url": "http://127.0.0.1:7344/mcp" } } } ``` 它提供所有三种 MCP 原语，因为一个 skill 包含三样东西：引擎（**tools**）、方法（**prompts**），以及方法所引用的文档（**resources**）。在这里这一点至关重要：`score` 是对*记录在运行中*的判断的纯粹归纳，因此如果客户端仅被赋予 tools，它会产生一个空白的记分卡并将其报告为成绩。 ### Tools | Tool | 功能 | |------|--------------| | `ultraeval_status` | 运行进度，以及确切的下一个命令 | | `ultraeval_analyze` | 热点、变动、测试和文档缺口 —— 关注去哪看，而不是得出什么结论 | | `ultraeval_check` | 反幻觉 gate：每个发现都必须能解析到真实的 file:line | | `ultraeval_verify` | 对抗性工作清单，可分片，带有**蜜罐**以捕捉草率的盲目批准 | | `ultraeval_backlog` | 已验证的发现 → TDD 修复卡片 | | `ultraeval_score` | 将记录的判断归纳为记分卡 | | `ultraeval_compare` | 对比两次运行；分数下降或出现新的 P0 即为退化 | | `ultraeval_history` | 得分随时间变化的趋势 | | `ultraeval_read` | 读取运行记录或目标中的一个文件，或某个行范围 | `--allow-write` 额外暴露了 `ultraeval_init`、`ultraeval_render`、`ultraeval_clean`（具有破坏性）和 `ultraeval_verify_fix`。最后一个是该系列中唯一**执行目标自身命令**的 tool —— 出于这个原因，它被标注为 open-world 且非幂等，因此请仅将其指向您信任的目标。 在启动时传入 `--run ` 可将 server 专用于某一项评估 —— 这样一来，除了 `ultraeval_clean` 之外，每个 tool 上的 `run` 都会变为可选，因为 `ultraeval_clean` 绝不会继承一个未明确给予它的目标。 ### Prompts —— 是 workflow，而不仅仅是 tools | Prompt | 参数 | 驱动过程 | |--------|-----------|----------------| | `evaluate_skill` | `run` | 分析 → 按维度研究 → check → 用蜜罐进行 verify → 打分 → backlog | | `write_findings` | `run`, `dimension?` | 测试行为，而不是测试文档；报告您无法确定的内容 | | `judge_dimension` | `run`, `dimension?` | 根据证据打分 —— 并将同意一切视为其本身发出的信号 | ### Resources —— skill 自身的文档 `SKILL.md` 和 `references/*.md` 在 `skill://` 下提供服务，在请求时从磁盘读取 —— 这样一来，文档的修复无需重新构建即可到达每个客户端。有两件事值得了解： - **对同一次运行的调用是串行化的。** `verify --apply`、`backlog`、`score` 和 `verify-fix` 都是针对相同发现进行的读取-合并-写入操作，而将持怀疑态度的验证者分散到工作清单中，正是该 server 所倡导的并行模式。 - **HTTP 传输会绑定 `127.0.0.1` 并拒绝任何其他地址**，除非您传入 `--allow-remote`。此 server 会读取本地文件并可以运行目标的测试命令；暴露的端口对于任何发现它的人来说，都是一个“可以执行任何操作”的原语。 ## 为什么 gate 很重要 每个“AI 评估 X”工具的失败模式都是自信且毫无根据的发现。ultraeval 在结构上使这种情况变得困难：`check` 会打开目标中被引用的每个 `file:line`，如果它不存在或超出范围，则会失败；随后 `verify` 会询问质疑者内容是否确实支持该声明，而 `check --semantic --require-verify` 就是退出 gate。一个您无法追溯到真实代码的修复积压列表比没有还要糟糕。 ## 开发 ``` pnpm install pnpm run build # tsup -> scripts/ultraeval.mjs, mirrored into skills/ultraeval/scripts/ pnpm test # vitest pnpm run eval # RED/GREEN gate probe against the shipped bundle pnpm run check:build # bundle is reproducible + install-bundle shape is valid ``` 引擎源码是 `src/*.ts`；已发布的 bundle 已被提交，因此该 skill 安装时具有零依赖。保持两份引擎副本在字节上完全一致（`check:build` 强制执行此操作）。 ## 安全 ultraeval 只会**读取**被评估的目标，并在运行目录下进行写入；它从不执行目标的代码。`executor` subagent 可能会运行目标*自身*的命令（其 tests/gates）—— 因此请对不受信任的仓库进行沙盒隔离。 ## 许可证 MIT © maxgfr

标签：AI智能体, Homebrew安装, MITM代理, TDD, 代码质量评估, 多智能体工作流, 自定义脚本, 防御加固