企业官网建设流程全解析

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

评测为什么会超时：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）：

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

一键使用内置 filesystem mock

最简单的用法——内置的filesystemmock 服务器开箱即用，支持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/ 就是标准玩法：

• 默认 fixture：evals/fixtures/mcp/project-default.yaml
• 用例project-closed覆盖为 project-closed.yaml，mock 返回status: CLOSED，用例断言输出必须包含CLOSED；
• 用例project-open则覆盖为 project-open.yaml，返回status: OPEN。

使用规则（务必注意）：

• 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 依赖后，时长收益一目了然：

常见问题 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_reffixture + 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」本身——这才是评测该有的样子 🚀