为什么你的Agent评测总是超时:skill-up MCP服务器Mock完整指南

原创2026-10-13 19:49:421,420 阅读

为什么你的Agent评测总是超时:skill-up MCP服务器Mock完整指南

在评测 Agent 时遇到「MCP 工具调用卡住 → 整条评测超时」是新手最常踩的坑。开源工具 skill-up 内置了 MCP 服务器 Mock 能力(mode: mocked):它会自动生成一个本地 stdio 模拟 MCP 服务器并安装进 Agent,让工具调用瞬间返回固定结果,从而彻底消除外部依赖带来的等待、鉴权失败和网络抖动。本文用一份完整指南,带你 5 分钟搞定 MCP Mock 配置、按用例注入不同 fixture,并顺手排查评测超时问题。

skill-up 评测与进化工作流总览:EVALUATE 与 EVOLVE 双环,包含 evals、agents、judge、report 与 skill-upper 自动修复流程

评测为什么会超时:3个真实原因

跑过 skill-up 评测的人都知道,cases.defaults.timeout_seconds 一旦设置得不够,用例就会失败。但超时往往不是「Agent 太慢」,而是环境在拖后腿:

  1. 外部 MCP 服务器响应慢或不稳定 —— 真实 MCP 服务(如项目管理、搜索类 API)一次调用可能耗时数秒到数十秒,Agent 多轮调用后轻松击穿超时。
  2. 鉴权失败或 Token 缺失 —— 真实服务器需要 headers 里的凭证,CI 环境中漏配 ${VAR} 环境变量时,连接重试会白白消耗大量时间。
  3. 结果不可复现 —— 外部数据每次不同,即使这次没超时,下次 CI 也可能因数据变化直接判错。

解决思路只有一个:把不可控的外部依赖替换成可控的本地 mock。

skill-up 的 MCP Mock 是什么?

skill-up 支持两种 MCP 模式(详见 docs/guide/writing-evals.md):

模式 行为 适用场景
mode: real 安装真实 MCP 服务器(stdio 或 http)到 Agent 需要验证真实链路
mode: mocked 由 internal/mcp/ 生成一个本地 stdio mock 服务器,像普通 MCP 服务器一样装进 Agent 日常回归、CI、稳定性评测

mocked 模式的实现见 internal/mcp/mock_server.go:它会注入一段 Node 脚本,完整实现 MCP 的 initialize / tools/list / tools/call 协议,并按你在 config_ref 里声明的 tool_responses 原样返回结果。也就是说:零网络、零鉴权、毫秒级响应,超时问题从根上消失。

一键使用内置 filesystem mock

最简单的用法——内置的 filesystem mock 服务器开箱即用,支持 list_directory / read_file / write_file 三个工具,且做了路径越界保护:

mcp:
  servers:
    - name: filesystem
      mode: mocked

自定义工具响应:用 config_ref 声明 fixture

想让 mock 服务器假装是「项目管理服务」?在 config_ref 指向的 YAML 里写死每个工具的返回值即可:

# evals/eval.yaml
mcp:
  servers:
    - name: project-mgmt
      mode: mocked
      config_ref: evals/fixtures/mcp/project-mgmt.yaml
# evals/fixtures/mcp/project-mgmt.yaml
tool_responses:
  create_publish_plan_simple:
    default:
      id: 999
      name: "{{params.name}}"   # 支持模板,把入参渲染进返回值
      status: ONGOING

注意两个细节:

  • mock 模式只支持 stdio,不要写 transport: http 或 endpoint,配置里写了自己的 command/args 也会被拒绝(mock 会自己生成命令)。
  • {{params.xxx}} 模板支持 | default: 'xxx' 兜底写法,Agent 传什么参数就能渲染出对应内容,测试「参数是否被正确透传」非常方便。

官方 e2e 示例可以直接参考:e2e/testdata/mcp-mocked-marker/evals/eval.yaml 演示了自定义 fixture 注入,e2e/testdata/mcp-stdio-marker/evals/eval.yaml 则展示了 mode: real 的 stdio 服务器写法,两者对照着看能帮你判断该用哪种模式。

进阶:按用例注入不同 Mock 数据

同一个 MCP 服务器,不同用例需要不同的「项目状态」?skill-up 支持 case 级 MCP 覆盖(提案见 proposals/0003-per-case-mocked-mcp-responses.md):eval 级配置作为默认值,case 里再声明同名 mcp.servers 就会整体替换。

官方示例 e2e/testdata/mcp-case-overrides/ 就是标准玩法:

使用规则(务必注意):

  • case 级覆盖目前只支持 mode: mocked,真实 MCP 暂不支持按用例覆盖;
  • 替换是整条替换,不是字段合并——需要把 name、mode、config_ref 写全;
  • config_ref 相对 Skill 目录(SKILL.md 所在目录)解析,不是 case 文件目录;
  • 每个 case 各自生成并安装自己的 mock 服务器,cases.parallelism > 1 并行跑时 fixture 天然隔离,不会串数据。

超时排查清单:5步定位问题

如果配了 mock 还是超时,按下面顺序排查:

  1. 先看模式:确认 mcp.servers[].mode: mocked,真实服务器会走网络,超时大概率来自它。
  2. 再看环境类型:Skill 不碰文件系统时用 environment.type: none,能跳过沙箱准备,速度差异显著(见 docs/guide/writing-evals.md 的环境选择表)。
  3. 检查超时预算:cases.defaults.timeout_seconds 要覆盖「Agent 启动 + 多轮工具调用」全过程;CI 上模型响应慢,本地 180s 够用的配置在 CI 可能要放宽。
  4. 核对引擎与模型:不同引擎(claude_code / codex / qodercli)启动 MCP 安装流程耗时不同,报告里的时长对比能帮你定位瓶颈。
  5. 看报告证据:skill-up 输出 result.json、JUnit XML 和 HTML 报告,保留 transcript 工件后,能精确回放每一步工具调用花了多久。

下面这张真实回归对比图,展示了 skill-up 报告中 Duration 指标前后变化(39.1s → 21.5s,快 45%)——优化环境和 mock 依赖后,时长收益一目了然:

skill-up 回归对比报告:baseline 与 postchange 两次运行的状态、通过率、Duration 与轮数对比,展示评测耗时优化 45%

常见问题 FAQ

Q:mocked 和 real 可以同时声明多个服务器吗? A:可以。mcp.servers 是列表,每个服务器独立声明模式;mock 的负责稳定性,real 的负责关键链路验证,混搭是 CI 的常见做法。

Q:mock 服务器不支持 HTTP transport,那 http 类 MCP 怎么办? A:目前 mock 模式只覆盖 stdio 场景。若必须评测 http 链路,建议保留少量 mode: real 用例并放宽该用例超时,或用 case 级覆盖把大部分用例切到 mocked。

Q:fixture 数据想改怎么办? A:直接改 config_ref 指向的 YAML 里的 tool_responses 即可,无需改代码;模板变量 {{params.xxx}} 让同一份 fixture 适配多种入参。

小结

Agent 评测超时的根因,绝大多数是「把不可控的外部 MCP 依赖带进了评测」。skill-up 的 MCP Mock(mode: mocked + config_ref fixture + case 级覆盖)让你用声明式 YAML 就能:

  • ✅ 毫秒级、零网络的稳定工具响应;
  • ✅ 按用例注入不同项目状态,覆盖更多分支;
  • ✅ 并行执行时 fixture 自动隔离,结果可复现;
  • ✅ 配合 none 环境和合理超时设置,彻底告别超时红灯。

相关路径速查:MCP 核心实现 internal/mcp/(mock_server.go、provisioner.go)、配置文档 docs/guide/writing-evals.md、可运行示例 e2e/testdata/mcp-case-overrides/ 与 e2e/testdata/mcp-mocked-marker/。把外部依赖 Mock 掉,让评测回归到测「你的 Skill」本身——这才是评测该有的样子 🚀

登录后查看全文
skill-up