企业官网建设流程全解析

Agent 技能路由基准测试：Agent-Skills-for-Context-Engineering 的 Router Benchmark 实战与源码解析

【免费下载链接】Agent-Skills-for-Context-EngineeringA comprehensive collection of Agent Skills for context engineering, multi-agent architectures, and production agent systems. Use when building, optimizing, or debugging agent systems that require effective context management.项目地址: https://gitcode.com/GitHub_Trending/ag/Agent-Skills-for-Context-Engineering

本文档以仓库中 researcher/benchmarks/router/results-published/2026-05-19.md 这份 2026-05-19 路由器基准测试报告为主体，系统讲解该仓库如何用 LLM-as-Router 的方法检验 15 个 Agent Skill 的激活描述（activation description）能否把用户任务准确路由到正确技能。读完本文，你将掌握 Stage 2 Router Benchmark 的完整方法论、600 次运行的结果解读方法（排行榜、混淆矩阵、最难 prompt）、以及如何在本地用 SDK Runner 精确复现这套测试。

一、这份报告在测什么：从"描述能不能被读懂"验证技能门面

这份 2026-05-19 报告是仓库四级基准计划（见 researcher/benchmarks/PLAN.md）中Stage 2（v2.3.0）的一次正式结果发布。Stage 2 的核心假设（Hypothesis）是：

v2.2.0 frontmatter 中的激活场景描述（activation-scenario descriptions，取代了 v2.1.x 的关键字触发）应当能让前沿模型把用户 prompt 路由到正确的技能，达到高 top-1 准确率和很高的 top-3 准确率。

为什么这很重要？正如 PLAN.md 所写："Skill descriptions are the only signal a deployed agent uses to decide whether to load a skill. If they don't route correctly, the rest of the harness is academic."（技能描述是已部署 Agent 决定是否加载某技能的唯一信号。如果路由不正确，其余的一切都只是纸上谈兵。）

本轮 sweep 的特殊任务在于：它验证的是**语料库级加固（corpus-wide hardening）**之后的效果——15 个技能的正文、机制映射、声明溯源记录（claim provenance）、语料库索引条目和激活 fixtures 全部更新后，路由没有出现大面积崩塌。

关键运行元数据（报告中逐项给出，便于精确复现与对比）：

二、方法论：只有描述是信号的纯路由实验

报告的方法论部分非常严谨，也是理解后续所有数据的前提：

1. fixture 是人工标注的 ground-truth prompt 集合。每条记录形如{prompt_id, prompt, expected_primary_skill, acceptable_secondary_skills, rejected_skills, reason}，存放在 researcher/benchmarks/router/prompts.jsonl。初始 50 条 prompt 覆盖五类场景（详见 researcher/benchmarks/router/README.md）：

   • 单技能正向控制（每个技能 1 条，共 15 条）；
   • 来自 v2.2.0 边界混淆清单的对抗性边界对（5 对 × 3 变体 = 15 条）；
   • 多技能均合理的组合型 prompt（10 条）；
   • 任何技能都不应匹配的负向控制（5 条）；
   • 应当仍能解析的微妙激活案例（5 条）。

2. 每条 prompt 与 15 个技能的激活描述一同呈现给模型，技能顺序按 seed 确定性洗牌（每个复制品 shuffle 不同）。洗牌由 common.ts 中的shuffleSeeded实现——基于 mulberry32 种子 PRNG 的确定性 Fisher-Yates 洗牌，保证同一 seed 下可复现，同时用于缓解位置偏差（position bias）（详见 PLAN.md 的 Bias Mitigation 一节）。

3. 模型必须返回严格 JSON 的排名列表，模板见 researcher/benchmarks/router/routing-prompt.md，占位符为{{SKILL_BLOCK}}、{{USER_PROMPT}}、{{SKILL_COUNT}}，JSON 结构要求ranking、confidence、rationale三个字段。

4. 关键设计：settingSources: []。运行时代码在 runRouter.ts 中调用Agent.prompt(filled, { apiKey, model: { id }, local: { cwd: REPO_ROOT, settingSources: [] } })——任何技能都没有被加载进 Agent，唯一的路由信号就是 prompt 里的描述文本。这是验证"描述质量"而非"技能正文质量"的关键隔离。

5. 评分：top-1 准确率 = 排第一的技能是否等于人工标注的expected_primary_skill；top-3 准确率 = 期望技能是否出现在前三位。置信区间为95% bootstrap，2000 次重采样（渲染脚本 render_router_report.py 的bootstrap_ci实现）。

三、执行结果：600/600 可用，零格式失败

3.1 执行摘要的四个结论

报告的执行摘要给出了四个可验证的结论：

• 600/600 可用记录，0 格式失败：第一遍跑出了零星的空输出/格式失败 SDK 结果；这些记录通过 runner 的resume 路径（loadExistingResults，按promptId-modelId-rep.json文件名去重续跑）重跑后全部成功。runner 现在对瞬时格式失败自动重试一次（MAX_FORMAT_ATTEMPTS = 2，见 runRouter.ts）。
• 语料库级改动没有带来大范围路由崩塌：三个模型 top-1 保持在 0.913 及以上；Claude Opus 4.7 较低（0.840），但其剩余 miss 集中在与上一份报告相同的已知模糊边界上。
• 新加固的技能路由干净：bdi-mental-states、hosted-agents、latent-briefing、memory-systems、multi-agent-patterns在本轮全部满分。
• 剩余失败高度集中且已被理解：p046是一个没有任何真正匹配技能的负向控制 Python 格式化任务；p048是一个真正模糊的 advanced-evaluation/evaluation/latent-briefing 混合 prompt；context-fundamentals仍是最弱的兜底边界。

3.2 与上一轮对比的总体结论

与 2026-05-15-v2.md 相比，实质结论未变：描述-基准测试的迭代闭环（description-benchmark loop）是有效的，语料库级正文/元数据加固没有引入广泛的路由回归。报告明确指出下一笔基准投入应是 Stage 3 有效性测试（加载完整技能正文）。

四、逐模型排行榜：0.84–0.92 的 top-1 区间

从源码可以验证这套表格是自动渲染而非手写的：render_router_report.py 的render()按 top-1 降序排序输出 leaderboard，置信区间来自bootstrap_ci（2000 次重采样、2.5%/97.5% 分位），median ms 来自summarize_per_model。这也意味着只要你有原始 per-run JSON，就可以随时复现这张表。

几点读表要点：

• top-3 显著高于 top-1（多数模型 0.93+），说明即使首选技能选错，期望技能几乎总在前三——路由失败多为"边界相邻技能"而非"完全跑偏"。
• Claude Opus 4.7 的 0.840 是四者中最低，但其 CI [0.780, 0.893] 与其余模型有部分重叠，且其 miss 全部落在已知模糊边界。
• 延迟差异明显：gemini-3.1-pro 中位数 8631ms，约为其余模型的 2–3 倍；上一轮（2026-05-15-v2）也观察到同样模式（9130ms vs 3269–4201ms）。

五、逐技能混淆矩阵：谁和谁打架

混淆矩阵的行是 ground-truth 的expected_primary_skill，列是模型实际预测的结果，只统计finished运行：

解读要点：

1. 7 个技能满分（对角线 = n）：bdi-mental-states、context-degradation、context-optimization、filesystem-context、harness-engineering、hosted-agents、latent-briefing、memory-systems、multi-agent-patterns、project-development——其中报告特别点名bdi-mental-states、hosted-agents、latent-briefing、memory-systems、multi-agent-patterns为"新加固后路由干净"。
2. context-fundamentals是最弱边界：42 次期望中只有 19 次被正确预测，12 次跑到project-development、6 次到context-optimization、5 次到context-degradation。这与上一轮（2026-05-15-v2）中"14 次混淆到 project-development"的模式一致，说明它是团队已认知的兜底 catch-all 技能。
3. advanced-evaluation与evaluation是经典边界对：60 次中 10 次被预测为evaluation；反过来evaluation也有 4 次被预测为advanced-evaluation。这正是 v2.2.0 边界混淆清单里被重点设计的对抗对之一（对应 prompt p012/p017 vs p016/p033）。
4. tool-design有 7 次跑到project-development、4 次到filesystem-context：描述里"工具契约/整合"与"管线开发/文件化上下文"的边界仍有提升空间。

矩阵的生成逻辑同样在 render_router_report.py 的build_confusion中：只统计status == "finished"的记录，按expected → predicted计数，对角线加粗。

六、最难 Prompt：失败是设计出来的"可控失败"

报告给出按 top-1 率升序排列的 10 个最难 prompt：

结合 prompts.jsonl 原文逐条理解：

• p046："Reformat this Python file with consistent indentation and remove trailing whitespace." 这是一个负向控制（rejected_skills明确排除了 latent-briefing/bdi-mental-states/memory-systems），本身没有真正的匹配技能，fixture 把tool-design标为"最接近的通用工具任务"。0.00 的 top-1 是预期中的、可接受的失败。
• p048："Plan how to evaluate whether my latent-briefing-style KV compaction actually preserves task accuracy." 设计上就是 triple-ambiguous：acceptable_secondary_skills同时给了 latent-briefing、evaluation、harness-engineering。模型在evaluation和latent-briefing之间摇摆是合理的。上一轮（2026-05-15-v2）同样 0.00，报告建议"考虑重新标注"。
• p045/p047：都是负向控制（"Compute the area of a triangle"、"Translate this English paragraph to French"），没有技能真正适合，fixture 把兜底的context-fundamentals标为 expected。模型倾向于选project-development——从路由角度这不算错误行为，只是 fixture 标注有讨论空间（上一轮 p047 甚至因此 -33pp "回归"）。
• p001："Explain why context windows degrade as they fill, and how attention mechanics make middle-of-context information less recoverable." 期望是context-fundamentals（reason 明确说"基础性解释归 context-fundamentals"），但也允许context-degradation作为次选。0.58 的 top-1 与"foundation vs 诊断"的边界直接相关。

要点：这些"最难 prompt"多数是刻意设计的负向控制或模糊边界，失败模式集中且可解释，并非描述质量的整体性崩塌——这本身就是基准测试有效性的证明。

七、从源码看 runner 的执行细节与成本闸门

runRouter.ts 完整实现了报告描述的全部流程，几个值得展开的实现细节：

1. 确定性运行计划：buildRunPlan对每个 (prompt, model, rep) 生成一个条目，shuffleSeed = hash32("promptId|modelId|rep|baseSeed")——同一 seed 下任何人重跑都得到完全相同的洗牌序列，这是"可复现"的根基。
2. 严格 JSON 解析与格式失败惩罚：parseRouterJson用/\{[\s\S]*\}/提取最外层 JSON 对象，解析失败则记录为format_failure（不给坏输出奖励），并且MAX_FORMAT_ATTEMPTS = 2时只自动重试一次。本轮 0 格式失败正是"重试 + resume"两条机制共同作用的结果。
3. 成本闸门：resolveConfig强制要求--max-runs或--max-budget-usd或--unsafe-no-cost-cap或--dry-run四者之一，否则直接拒绝运行；assertBudget在调用任何 Agent 前用估算（ESTIMATED_TOKENS_INPUT=4000、ESTIMATED_TOKENS_OUTPUT=400、ESTIMATED_USD_PER_RUN=0.012）做 fail-fast 预算校验。完整 CLI 参数表（来自parseCliFlags）：
   • --dry-run：只打印计划与成本预测，不发 SDK 调用；
   • --models <a,b,c>：限定模型子集（默认composer-2）；
   • --reps N：每 (prompt, model) 的复制次数（默认 3）；
   • --seed N：随机种子（默认 1）；
   • --max-runs N：Agent 调用硬上限；
   • --max-budget-usd N：估算成本上限；
   • --concurrency N：并发度（2026-05-15-v2 报告显示 concurrency=4 把墙钟时间从 ~60 分钟压到 ~15 分钟）；
   • --fixture <path>：自定义 fixture；
   • --no-resume：忽略已有结果强制重跑。
4. 产物持久化：每个 per-run 结果写入researcher/benchmarks/router/results/<date>-<seed>/下的promptId-modelId-rep.json（含 raw_text、parsed ranking、duration_ms 等），summary.json汇总各模型 top-1/top-3/格式失败率，并 append 一行到 researcher/reports/router-history.jsonl（gitignored）用于纵向回归追踪。
5. 模型不可用时的容错：CursorAgentError被捕获后记录为model_unavailable而非中断整个 sweep，运行继续。

另外值得注意：runner 从 researcher/corpus/index.json 读取技能清单，再通过extractDescription解析每个skills/<name>/SKILL.md的 frontmatterdescription字段作为路由信号——这也解释了为什么该基准直接服务于"激活描述质量"这一目标。

八、如何精确复现本轮 600 次运行

报告给出可直接执行的复现命令（完整命令链）：

cd researcher/benchmarks/sdk-runner npm install export CURSOR_API_KEY=<your-key> node --experimental-strip-types src/runRouter.ts --models claude-opus-4-7,composer-2,gemini-3.1-pro,gpt-5.5 --reps 3 --seed 1 --max-budget-usd 15 python3 ../../scripts/render_router_report.py \ --results ../router/results/<date>-<seed> \ --fixture ../router/prompts.jsonl \ --output ../router/results-published/<date>.md

执行要点与前置条件：

• 前置条件：Node.js 环境、在researcher/benchmarks/sdk-runner下npm install（依赖@cursor/sdk）、CURSOR_API_KEY环境变量。runner 在 key 未设置或 SDK 未安装时会明确报错拒绝运行（见 runRouter.ts）。
• 先干跑再看预算：正式花钱前建议先执行npm run router:dry-run（对应 README 中的快捷命令，见 researcher/benchmarks/router/README.md），它会打印计划条目数、估算 token、最坏情况 SDK 调用数（plan.length × MAX_FORMAT_ATTEMPTS）与估算总成本，不产生任何 SDK 调用。
• fixture 校验：报告头部的fixture sha256-16: 8f974d930836bc9c由fixtureSha对 prompts.jsonl 计算 sha256 前 16 位得到；重跑时若 fixture 未变，这个值应一致，可作为输入一致性检查。
• 关于 seed=1 与 reps=3：seed 决定洗牌序列与计划顺序，reps=3 是 PLAN.md 要求的最低复制次数（用于方差估计）。改变任一参数都会得到不同（但同样有效）的结果。
• 报告渲染：render_router_report.py支持--baseline <dir> --baseline-label <text>生成 "Delta vs baseline" 对比章节——这正是 2026-05-15-v2 报告 delta 部分的生成方式，也是 README 建议的"改描述 → 重跑 → 对比 delta"闭环的落地工具。

适用前提与限制（依据 PLAN.md "What This Plan Does Not Solve"）：token 级成本核算依赖 SDKconversation()暴露的数据，缺失时以墙钟时间与请求数为代理；Cursor 模型目录随时间变化，跨版本比较需谨慎；真实部署效果不等于基准上限，本文所有数字仅代表该 seed/fixture/commit 条件下的路由能力。

九、从 2026-05-19 往回看：描述迭代闭环确实有效

虽然 2026-05-19 报告本身未包含 delta 章节，但对比上一份 2026-05-15-v2.md 可以看清这套基准的演进价值：

• 基线（2026-05-15）566/600 完成，runner 中途死亡；v2 硬化 runner 后 600/600，concurrency=4 把墙钟从 ~60 分钟降到 ~15 分钟。
• 定向描述重写带来最大单技能提升：context-fundamentalstop-1 从 0.255 → 0.489（+23.4pp），project-development从 0.750 → 1.000（+25pp，满分）。
• 本轮（05-19）在此基础上验证了语料库级加固没有引入广泛回归：三模型 ≥0.913，新加固的五技能全满分，剩余失败集中在两个已知负向控制/模糊 prompt 与context-fundamentals兜底边界上。

结论与仓库 README（researcher/benchmarks/router/README.md）的建议一致：当基准暴露路由失败时，正确动作是修改失败技能的激活描述、重跑、再用 delta 对比证明改善——2026-05-19 证明这个闭环在语料库大规模改动后依然稳健。

十、读这份报告的正确姿势：四个问题按顺序回答

PLAN.md 的 "How To Read Results" 给出了一套四问框架，任何一轮基准结果都应按顺序回答：

1. harness 是否通过确定性闸门？（Stage 0 + 1，必须恒通过）
2. 描述能否路由到正确技能？（Stage 2，本报告回答的问题，逐模型看 top-1/top-3）
3. 技能是否真的有效？（Stage 3，下一投资方向——加载完整技能正文的有效性测试，仓库已有一个样例任务 001-filesystem-context-offload）
4. 技能能否组合？（Stage 4，未来）

"在任何更早阶段失败的技能，不需要等到更晚阶段才被证明应该移除或返工"——这正是把基准按阶段分层、把"路由准确性"放在"有效性"之前验证的设计意图。

【免费下载链接】Agent-Skills-for-Context-EngineeringA comprehensive collection of Agent Skills for context engineering, multi-agent architectures, and production agent systems. Use when building, optimizing, or debugging agent systems that require effective context management.项目地址: https://gitcode.com/GitHub_Trending/ag/Agent-Skills-for-Context-Engineering