企业官网建设流程全解析

Agent-Skills-for-Context-Engineering 路由基准测试解析：用 LLM-as-Router 验证 15 个 Agent Skill 的描述质量

【免费下载链接】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

导读

本篇技术指南深入解读 Agent-Skills-for-Context-Engineering 仓库中首份已发布的技能路由基准报告（researcher/benchmarks/router/results-published/2026-05-15.md）。这份报告回答了一个对任何 Agent 系统都至关重要的问题：当 15 个技能（Skill）只有"激活描述（activation description）"这一个信号时，前沿大模型能否把用户任务准确路由到正确的技能？读完本文，你将掌握该基准的完整方法论（LLM-as-Router、确定性乱序、bootstrap 置信区间）、四模型排行榜的解读方法、混淆矩阵定位"边界技能"的分析套路，以及如何用仓库内的 runner 源码与脚本复现这份报告。

图：v2.3.0 发布资产中的 router 排行榜图（对应 2026-05-19 那次全量扫描的模型 Top-1 结果可视化），用于快速对比各模型的路由精度。

一、这份报告回答什么问题：路由阶段是技能体系的"咽喉"

在 researcher/benchmarks/PLAN.md 的四阶段基准架构中，这份报告属于Stage 2：Skill Router Benchmark（v2.3.0 发布）。它的核心假设是：

v2.2.0 起，技能采用 frontmatter 中的"激活场景描述（activation-scenario description）"取代 v2.1.x 的关键字触发器后，前沿模型应该能以高 Top-1 精度、极高 Top-3 精度把提示词路由到正确技能。

为什么路由这么重要？PLAN.md 里有一句关键判断："技能描述是部署后的 Agent 决定是否加载某个技能的唯一信号。如果路由不正确，其余所有基础设施都是空谈。"也就是说，无论技能本体写得多好，只要描述写得模棱两可，Agent 就不会在正确的时机加载它——路由精度是技能体系有效性链条上的第一道闸门。

报告在方法论上做了一个严格的控制：settingSources: []（不加载任何技能文件），让"提示词中的描述"成为唯一路由信号。这保证了测的是描述质量，而不是技能正文对模型的引导。

二、运行元数据：一次可完全复现的受控实验

报告头部完整记录了本次扫描的运行环境（这也是整个仓库所有基准报告的统一"溯源头"）：

需要特别说明的是，本次基线扫描并未跑满计划中的 600 次调用：进程在第 566 次运行后退出（报告注明原因未知，推测为 SDK 超时或本地限流）。尽管没有跑满，每个模型的覆盖量依然均衡地保持在约 141 次，远超统计显著性所需的最低样本量，因此报告结论不受影响。这也是后续版本（2026-05-15-v2、2026-05-19）专门加固 runner（增加断点续跑 resume 与并发控制）的直接动因。

测试夹具（fixture）是 researcher/benchmarks/router/prompts.jsonl，当前版本包含 56 条人工标注的真值提示词，每条记录包含prompt_id、prompt、expected_primary_skill、可选的acceptable_secondary_skills与rejected_skills、以及reason。夹具设计覆盖了五类场景（见 researcher/benchmarks/router/README.md）：

• 单技能正向控制（每个技能 1 条，共 15 条）；
• 来自 v2.2.0 边界混淆清单的对抗性边界对（5 组边界 × 3 个变体）；
• 多个技能都可接受的组合提示词；
• 任何技能都不该匹配的负向控制（如 p045"计算三角形面积"）；
• 应能正确解析的隐蔽激活案例。

三、执行摘要：四个关键结论

报告的执行摘要给出了四条真正有意义的发现，这也是整个 Stage 2 最值得吸收的分析方法：

1. 四个前沿模型在 Top-1 精度上差距不超过 0.3 个百分点。Composer-2 0.888、GPT-5.5 0.886、Claude Opus 4.7 0.886、Gemini 3.1 Pro 0.886；Top-3 精度从 0.921（Gemini）到 0.943（GPT-5.5）。四者的 95% bootstrap 置信区间完全重叠。结论：在路由阶段，模型选择不是决定因素。换句话说，路由瓶颈不在"谁在路由"，而在"被路由的描述"本身。

2. 路由失败几乎全部集中在一个技能：context-fundamentals。它 47 次中只被正确预测 12 次，其余被分到context-degradation（12）、project-development（12）、context-optimization（8）、evaluation（2）、tool-design（1）。这个激活描述过于宽泛、与相邻技能重叠，是改写优先级最高的描述。

3.tool-design与project-development是真实的边界问题。48 个tool-design案例中有 12 个被路由到project-development，反向也有 12/48。对称、温和但持续存在。

4.evaluation与advanced-evaluation的边界问题基本解决。36 个evaluation案例中只有 3 个泄漏到advanced-evaluation，49 个advanced-evaluation案例中只有 1 个反向泄漏——v2.2.0 对该边界做的加固（refactor）是有效的。

5. 负向控制行为符合设计。像 p045"计算三角形面积"这类提示词只以 25% 的概率路由到预期兜底技能，并在多个技能间分散；没有模型错误地锁定某个不相关的"领域技能"。这是正确行为：当没有技能强匹配时，就不该有技能占主导。

6. 格式合规率几乎完美。566 次调用中仅 1 次格式失败（0.18%），严格 JSON 路由提示词在四个模型上都稳定可用。

7. 延迟差异约 3 倍。每次调用中位数毫秒数：Claude 3392、GPT-5.5 3764、Composer-2 3957、Gemini 3.1 Pro 9077。Gemini 是最慢路径，其余三者做路由吞吐可互换。

报告给出的最明确下一步行动是：重写context-fundamentals的激活描述，让它对"基础性提示词"成为无争议的赢家、不再向相邻领域渗透，预期对全模型的 Top-1 提升约 5-7 个百分点。

四、方法论：确定性乱序 + 严格 JSON + bootstrap 置信区间

报告的方法论设计是保证结论可信的基石，逐条拆解如下：

1. 提示构造：每条提示词会与 15 个技能的激活描述一起呈现给每个模型，技能顺序采用确定性乱序（同一提示-模型对的每次复现使用不同 shuffle，但给定 seed 后结果可复现）。乱序是为了消除位置偏差——PLAN.md 的 Bias Mitigation 一节明确要求"在 router 基准中打乱技能顺序、跨复现报告一致性"。

2. 输出契约：模型必须返回一个 JSON 对象，包含ranking（按相关性降序的技能名数组，至少一个）、confidence（0.0-1.0）、rationale（一句话说明）。完整模板见 researcher/benchmarks/router/routing-prompt.md，其中使用{{SKILL_BLOCK}}、{{USER_PROMPT}}、{{SKILL_COUNT}}三个占位符由 runner 填充。

3. 打分口径：Top-1 精度 = 排名第一的技能是否等于人工标注的expected_primary_skill；Top-3 精度 = 期望技能是否出现在前三位。

4. 控制变量：settingSources: []，不加载任何技能进 Agent，唯一信号就是提示词中的描述。

5. 统计口径：置信区间为 95% bootstrap，2000 次重采样。

这五个要素共同保证了这份报告"可复现、可对拍、可横向比较"，是后续每份路由报告（包括 2026-05-15-v2 与 2026-05-19）都沿用的标准方法论。

五、分模型排行榜：模型之间没有统计显著差异

阅读这张表的关键点是看置信区间而非点估计：四个模型的 Top-1 置信区间完全重叠，因此任何"某模型比另一模型更会路由"的断言都不被数据支持。唯一显著的跨模型差异来自格式合规（Gemini 是唯一出现格式失败的模型）和延迟（Gemini 中位 9077ms，约为其他三者的 2.5-3 倍，该规律在 v2 报告中同样出现）。

六、分技能混淆矩阵：定位"谁在抢谁的活儿"

混淆矩阵的行是人工标注的真值expected_primary_skill，列是模型实际预测的技能，只统计finished状态运行。它回答"当期望是 X 时，模型到底预测成了谁"。

从这张矩阵能提炼出清晰的"技能健康度"分层：

• 零混淆的完美技能：bdi-mental-states、context-compression、context-degradation、context-optimization、filesystem-context、harness-engineering、hosted-agents、latent-briefing、memory-systems、multi-agent-patterns全部 100% 正确——它们的描述与使用场景边界足够清晰。
• 轻微泄漏：evaluation3/36 泄漏到advanced-evaluation；advanced-evaluation1/49 反向泄漏。这个 v2.2.0 加固过的边界基本被验证成功。
• 对称边界问题：tool-design↔project-development双向各 12 次混淆，说明两者描述在使用场景上确有重叠区。
• 核心病灶：context-fundamentals47 次仅 12 次正确（25.5%），同时向context-degradation、project-development、context-optimization三个方向大规模流失。它作为"兜底技能"的描述过于宽泛，是最优先重写对象。

七、最难提示词：从单条失败反推描述缺陷

结合 prompts.jsonl 中的原文，能还原每一条失败的具体成因：

• p001（"解释上下文窗口为何随填充而退化、注意力机制为何让中段信息更难恢复"）：期望context-fundamentals，全部模型都给了context-degradation。p001 的acceptable_secondary_skills明确包含context-degradation，说明这是一条真值标注本身就有争议的提示词——它既像"基础解释"又像"退化诊断"，暴露的是context-fundamentals与context-degradation描述重叠。
• p037（"结构化输出设计为何改善下游解析"）：期望project-development，全部给了tool-design。p037 的acceptable_secondary_skills含tool-design，同样是边界重叠案例。
• p046（"用一致缩进和去尾随空白重排 Python 文件"）：负向控制，期望tool-design，被路由到project-development。这是一个"没有技能真正匹配"的泛化格式化任务，其失败是预期内的负向行为而非描述缺陷。
• p048（"规划如何评估 latent-briefing 式 KV 压缩是否保持任务精度，含消融与基线"）：期望advanced-evaluation，全部给了evaluation。p048 的acceptable_secondary_skills同时包含latent-briefing、evaluation、harness-engineering，是一个刻意设计的多义提示词。
• p045（"给定底 12 高 7 计算三角形面积"）：负向控制，期望兜底技能context-fundamentals，实际在 4 个技能间分散——这正是负向控制想要的行为。

值得强调的是，报告中Top-1 为 0.00 的四条提示词，除 p037 外全部是真值标注含"可接受次选"的边界/负向案例。这说明失败并不总意味着描述质量差，也可能是"期望答案"本身在多个合理选项之间。这也解释了为何 v2 报告（2026-05-15-v2.md）中 p046、p048 依然保持 0.00 而被建议"重新标注"。

八、源码级解读：runner 如何完成一次扫描

报告呈现的是结果，而结果的产生逻辑完整落在 runner 源码中，理解它才能真正读懂报告。

8.1 运行计划：提示词 × 模型 × 复现 × 确定性乱序

src/runRouter.ts 的main()首先加载夹具与技能描述，然后调用buildRunPlan()（定义于 src/common.ts）生成完整运行计划：对每个 prompt × model × rep 组合生成一个计划项，并计算shuffleSeed = hash32(promptId|modelId|rep|baseSeed)。技能顺序的乱序使用mulberry32 种子化 PRNG 的 Fisher-Yates shuffle（shuffleSeeded），保证"不同复现不同乱序、同一复现可重现"。

8.2 提示渲染与严格解析

renderPrompt()把模板中的三个占位符替换为实际内容：技能块按乱序后的顺序编号列出（1. 技能名\n 描述），用户提示词填入{{USER_PROMPT}}，技能数量填入{{SKILL_COUNT}}。随后调用Agent.prompt()时显式传入settingSources: []——这正是报告"唯一信号是描述"承诺的实现位置。模型返回后由parseRouterJson()用正则/\{[\s\S]*\}/提取 JSON 并解析ranking数组；解析失败记为format_failure，最多重试一次（MAX_FORMAT_ATTEMPTS = 2）。

8.3 成本闸门与断点续跑

common.ts 中resolveConfig()有一个硬性安全设计：不提供成本上限就拒绝运行（Refusing to run without a cost cap）。支持的 CLI 参数包括--dry-run、--models、--reps、--max-runs、--max-budget-usd、--seed、--fixture、--concurrency、--no-resume。每条运行记录以{promptId}-{modelId}-{rep}.json命名写入results/<date>-<seed>/目录，下次扫描通过loadExistingResults()扫描已有文件实现断点续跑——这正是 v1 进程死在 566/600 后能补齐到 600/600 的机制。

8.4 报告渲染器

researcher/scripts/render_router_report.py 读取上述 JSON 记录，产出报告中的全部表格：bootstrap_ci()实现 2000 次重采样的 95% 置信区间；build_confusion()按"期望 × 预测"构建混淆矩阵；hardest_prompts()按 Top-1 率升序取前 10；delta_section()在传入--baseline时追加"相对基线变化"章节（v2 报告中的 Delta 表就由它生成）。报告不是手写的，而是从原始运行记录确定性生成的——这保证了每一份发布报告的每个数字都可追溯到逐条 JSON 记录。

九、复现这份报告

报告自带完整的复现命令（这也是仓库所有基准报告的统一约定，见 researcher/benchmarks/router/results-published/README.md）：

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 researcher/scripts/render_router_report.py \ --results researcher/benchmarks/router/results/<date>-<seed> \ --fixture researcher/benchmarks/router/prompts.jsonl \ --output researcher/benchmarks/router/results-published/<date>.md

需要注意的复现前提：

• API Key：runner 只在设置了CURSOR_API_KEY时才真正执行；未设置时可用--dry-run查看计划与成本预估而不产生任何调用。
• 成本闸门：必须提供--max-runs或--max-budget-usd（或显式--unsafe-no-cost-cap），这是 common.ts 的强制约束；runRouter.ts 中单次调用成本按约 4000 in / 400 out tokens、0.012 USD 估算。
• 模型清单：--models以逗号分隔传入；若运行时不指定则默认只有composer-2。
• 原始产物：每次运行的逐条 JSON（prompt、model、replication、raw model output、parsed ranking）保存在 gitignored 的results/目录中，summary.json与报告同步生成，同时向researcher/reports/router-history.jsonl（gitignored）追加一条历史记录用于纵向对比。

十、这份报告的后续：描述重写的度量闭环

将这份基线报告放在整个仓库的迭代时间线里，才能看到它的真正价值——它是**"度量-改写-再度量"闭环的起点**：

1. 基线（本文报告的 2026-05-15.md）：暴露context-fundamentals25.5% 与project-development75%、tool-design72.9% 的 Top-1 短板。
2. 修复（2026-05-15-v2.md）：针对性地重写描述并加固 runner（并发=4、断点续跑）后，context-fundamentals提升到 48.9%（+23.4pp）、project-development达到 100%（+25pp，完美路由）、tool-design到 80.7%（+7.8pp）；四模型中有三者在 Top-1 上提升，四者 Top-3 全部提升。报告中还包含完整的"Delta vs baseline"章节，逐模型、逐技能、逐提示词给出变化量。
3. 语料级加固验证（2026-05-19.md）：全 15 个技能正文、机制映射、声明溯源、语料索引与激活夹具全面更新后，600/600 全部可用、0 格式失败，三模型 Top-1 ≥ 0.913；剩余失败集中在已知的少数歧义边界（p046 负向控制、p048 多义提示词、context-fundamentals兜底边界）。

由此形成的工程方法论是：当某个技能在路由基准上失败，就改写该技能的激活描述，重跑扫描，并与上一份报告对拍看 delta——这正是 results-published/README.md 明确建议的跟进动作。

结语

2026-05-15.md这份路由基准报告的价值远超"一张排行榜"：它以可复现的严格方法论证明，在 Agent-Skills-for-Context-Engineering 的 15 技能体系中，路由阶段的精度瓶颈几乎全部集中在技能描述本身而非模型选择。报告给出的"混淆矩阵定位边界问题 → 单条提示词反推描述缺陷 → 重写描述 → 重跑对拍"的完整分析链路，对任何维护技能库、工具库或多 Agent 路由系统的团队都有直接借鉴意义。如果你正在构建自己的 Agent 技能体系，这份报告及其配套源码（runRouter.ts、common.ts、routing-prompt.md、prompts.jsonl、render_router_report.py）就是一套开箱即用的"路由质量验证工作台"。

【免费下载链接】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