31—AI Skill 测评前的环境准备：从 MCP 到账号、数据、隔离和证据链上一篇讲的是 Skill 怎么写成可测、

上一篇讲的是 Skill 怎么写成可测、可执行、可维护的工程契约。

但写法正确只是第一步。真正跑测评时，很多失败并不是 Skill 本身写错，而是环境没有准备好：

MCP 工具连不上。
测试账号没有权限。
测试数据不存在。
明明想跑测试环境，结果连到了生产环境。
用例依赖的 fixture 缺失。
Grader 没有 rubric，报告里只有一堆无法解释的 FAIL。
CI 能跑脚本，但拿不到 token 或产物没有上传。

所以本文不是只讲 MCP，而是给出一份 AI Skill 测评前的环境准备总清单。

如果你的 Skill 是 mcp_based，MCP 真实调用是最关键的前置条件。
如果你的 Skill 是文本生成、代码生成、文档处理、工作流 Agent，也同样需要准备运行依赖、测试数据、fixture、评分器、报告产物和隔离策略。

核心结论：环境准备的目标不是“能跑起来”，而是让测评结论可复现、可解释、可追责。没有真实执行证据的通过率，不能直接用于发布决策。

一、测评前环境全景图

一次可信的 SkillSentry 测评，至少依赖 9 类环境准备：

1. 测评对象准备      Skill 路径、版本、hash、静态检查
2. 执行运行时准备    本地编码助手、OpenCode/Claude Code、Python/Node、SkillSentry
3. MCP 与工具环境    MCP Server、工具列表、真实调用 smoke test
4. 账号与权限        测试账号、审批人、权限矩阵、token
5. 测试数据与 Fixture 正常/边界/异常/权限数据，fixture hash
6. 环境隔离          test/staging/production、写操作隔离、清理机制
7. 测评集与基线      cases/evals/golden/baseline/suite mode
8. 评分器与报告      assertions、rubric、transcript、grading、report.html
9. 同步与 CI         飞书/Bitable、secrets、artifact、复现命令

这 9 类准备对应一个判断：

如果测评失败，我能不能判断是 Skill 问题、环境问题、数据问题、权限问题、评分器问题，还是 CI 问题？

如果不能，环境还没准备好。

二、测评对象准备：先锁定你到底在测什么

测评前第一件事不是启动 MCP，而是确认“被测对象”。

1. 必须确认的信息

项	要求	目的
Skill 路径	明确到 `SKILL.md` 文件	避免测错 Skill
Skill 名称	与 report/session 中一致	方便追溯
Skill 版本	git commit / 文件 hash / 发布版本	支持复现
Skill 类型	`mcp_based` / `text_generation` / `code_execution` / `workflow_agent`	决定环境准备重点
写操作风险	是否会 create/update/delete/send/submit	决定是否强制 HiL 和隔离
依赖工具	MCP 工具、脚本、外部 API、文件系统	决定预检内容

2. 静态检查先于真实执行

建议先跑轻量静态检查：

python scripts/sentry_run.py --skill C:\path\to\skill\SKILL.md --profile lint

静态检查至少要确认：

description 是否清楚。
是否存在明显误触发风险。
主文件是否过长。
写操作是否有 HiL 确认。
工具名是否在文档中明确。
核心规则是否能转成断言。

如果静态检查已经发现严重问题，不建议直接进入真实执行。

三、执行运行时准备：确认 SkillSentry 自己能跑

很多测评失败不是业务系统问题，而是本地运行环境问题。

1. 本地工具链

检查：

python --version
node --version
git --version

如果使用 OpenCode / Claude Code / 本地编码助手，需要确认：

客户端能正常启动。
能读取当前 Skill。
能创建 session 输出目录。
能写入 transcript.md、response.md、grading.json、report.html。
配置修改后已重启客户端。

2. SkillSentry 脚本路径

确认 SkillSentry 根目录和脚本可用：

python scripts/sentry_run.py --help
python scripts/sentry_ci.py --help

至少能跑通：

python scripts/sentry_run.py --skill C:\path\to\skill\SKILL.md --profile lint

3. Profile 选择

Profile / Mode	用途	是否需要真实 MCP
`lint`	静态检查	不需要
`plan`	规划流程	不一定
`local`	本地轻量执行	看 Skill 类型
`smoke`	核心路径冒烟	mcp_based 通常需要
`standard`	发布前常规测评	mcp_based 必须需要
`full`	深度测评	mcp_based 必须需要

不要用 lint 或规则推断结果替代发布前真实执行结果。

四、MCP 与工具环境：真实调用是 mcp_based 的生命线

对依赖外部工具或业务系统的 mcp_based Skill，没有可用的真实工具调用，就不要把通过率用于发布决策。

SkillSentry 支持两种执行模式：

模式	行为	结论可信度
真实执行模式	executor 实际调用 MCP 工具，生成真实 transcript	可用于发布判断
规则推断模式	无 MCP 时由 LLM 根据规则推断“如果执行会怎样”	只能用于早期排查，不应用于发布判断

1. 什么是 MCP Server

MCP（Model Context Protocol）Server 是一个独立进程，接受本地编码助手 / OpenCode 的工具调用请求，再将请求转发给实际业务系统。

本地编码助手 / OpenCode
    ↓ 工具调用
MCP Server
    ↓ HTTP / RPC / SDK
业务系统 API
    ↓ 响应
MCP Server
    ↓ 返回工具调用结果
本地编码助手 / OpenCode

2. 安装前确认

向系统管理员或开发团队确认：

MCP Server 程序获取路径。
启动命令。
依赖的运行时：Node、Python、Java、Go 等。
环境参数：test / staging / production。
认证方式：token、AK/SK、OAuth、cookie、证书。
支持的工具列表。
每个工具的参数 schema。
是否有写操作。
是否有调用频率限制。

3. 独立启动 MCP Server

示例：

./expense-mcp-server --env test --token YOUR_TOKEN

期望看到：

MCP Server started
Available tools: saveExpenseDoc, getExpenseTypes, checkExpenseItem
Environment: test

如果 MCP Server 不能独立启动，不要继续配置客户端。

4. 配置文件

常见位置：

client_config.json
desktop_config.json

示例：

{
  "mcpServers": {
    "expense-mcp-test": {
      "command": "C:\\tools\\expense-mcp-server.exe",
      "args": ["--env", "test"],
      "env": {
        "EXPENSE_TOKEN": "YOUR_TEST_TOKEN"
      }
    }
  }
}

注意：

路径尽量使用绝对路径。
token 不要提交到 Git。
配置修改后必须重启本地编码助手 / OpenCode。
测试环境和生产环境配置要明确区分。

5. 连接验证

最低验证不是 list_tools，而是一次真实 smoke 调用。

1. list_tools 能看到工具。
2. 读取类工具能返回真实数据。
3. 写入类工具能在测试环境创建草稿或测试记录。
4. 错误参数能返回可解释错误。
5. 权限不足时能返回明确权限错误。

建议记录：

{
  "mcp_server": "expense-mcp-test",
  "env": "test",
  "tools_checked": ["getExpenseTypes", "validateExpense"],
  "smoke_result": "PASS",
  "checked_at": "2026-07-04T10:00:00+08:00"
}

五、账号与权限：不要用生产账号跑测评

SkillSentry 的真实执行会产生真实工具调用。只要涉及写操作，就可能产生真实业务数据。

1. 测试账号配置清单

项	要求	验证方式
测试账号	与生产账号隔离	能登录，能被审计
普通用户	覆盖普通权限路径	能创建/查询自己的数据
无权限用户	覆盖权限拦截	查询敏感数据被拒绝
测试审批人	覆盖审批流	审批节点能流转到测试人员
管理员/特殊角色	覆盖高权限场景	仅在测试环境使用
清理账号	可清理测评数据	能删除草稿或触发清理任务

2. Token 与凭证

必须确认：

token 对应的是测试账号。
token 未过期。
token 权限足够但不过度。
token 不写入文章、用例、报告和 Git。
CI 中通过 secret 注入。

3. 权限矩阵

建议维护一张最小权限矩阵：

场景	账号	预期
查询自己的单据	普通测试账号	PASS
查询他人敏感单据	普通测试账号	FAIL / 拒绝
创建测试草稿	普通测试账号	PASS
删除正式数据	任何测试账号	不允许

没有权限矩阵，权限类 case 很容易变成不可解释的 INCONCLUSIVE。

六、测试数据与 Fixture：让每条用例有前提条件

测试数据不足时，Skill 可能没有错，但用例会失败或变成 INCONCLUSIVE。

1. 数据类型

数据类型	用途	示例
正常数据	happy path	一张合法报销单
边界数据	boundary	金额刚好等于 5000
异常数据	robustness	缺附件、错格式、过期单据
权限数据	security	他人单据、跨部门单据
历史缺陷数据	regression	曾经失败过的线上样本
清理数据	teardown	测评产生的草稿记录

2. Fixture 管理

建议把测试数据写成 fixture，而不是散落在 prompt 里：

fixtures/
  expense-normal.json
  expense-over-limit.json
  invoice-invalid.pdf
  user-no-permission.json

每个 fixture 至少记录：

数据 ID。
所属环境。
创建时间。
数据 owner。
是否可重复使用。
是否需要清理。
hash 或版本号。

3. 数据清理

写操作测评必须有清理策略：

测评前：准备固定测试数据
测评中：所有创建数据打上 eval_run_id
测评后：按 eval_run_id 清理草稿或测试记录
报告中：记录清理结果

如果无法清理，必须在报告里说明风险。

七、环境隔离：测试环境优先，生产环境慎用

1. 推荐环境顺序

test → staging → production with test account

优先使用独立测试环境：

数据完全隔离。
可以制造边界数据。
可以反复创建和删除。
不影响真实业务流。

2. 不得已使用生产环境时

必须满足：

使用专用测试账号。
测试审批流只流向测试人员。
所有创建数据带 eval_run_id 或测试标识。
测评后立即清理。
不跑破坏性 delete/update 用例。
报告中标注“生产环境受控测试”。

3. 环境证据

每次测评应输出：

{
  "env": "test",
  "mcp_server": "expense-mcp-test",
  "skill_hash": "abc123",
  "cases_hash": "def456",
  "started_at": "2026-07-04T10:00:00+08:00"
}

如果 env 是 production，报告必须高亮提示。

八、测评集与基线：确认跑的是哪一套用例

环境准备还包括测评集准备。否则工具都通了，也可能测错用例。

1. 必须确认

项	说明
`cases.yaml` / `evals.json`	本次执行的用例来源
`golden.yaml`	是否包含回归核心集
suite mode	`smoke` / `quick` / `regression` / `standard` / `full`
baseline	对比哪次历史结果
release lock	是否锁定 case/assertion/fixture hash
case count	本次执行多少条
P0 count	P0 用例多少条

2. 用例可执行性检查

在 executor 前做：

python scripts/sentry_case_lint.py --cases C:\path\to\evals.json

至少检查：

本地路径是否存在。
fixture 是否存在。
case ID 是否稳定。
prompt 是否包含不可用私有路径。
P0 用例是否都有 expected/assertion。

3. 新增用例不要污染 baseline

如果本次新增了大量 case：

共有用例用于 regression delta。
新增用例单独统计。
删除用例写入 release note。
修改用例重新计算 hash。

九、评分器与报告产物：没有证据链就没有可信结论

测评不是 executor 跑完就结束。还要确认评分器和报告产物可用。

1. Grader 准备

确认：

deterministic assertions 可执行。
LLM-as-Judge 有 rubric。
高风险 case 是否需要人工复核。
grader version 已记录。
rubric version 已记录。
judge model 已记录。

2. 必须落盘的产物

每次测评至少应有：

session.json
evals.json
transcript.md
response.md
grading.json
grading-summary.json
report.html
diagnostics.json
eval_environment.json

如果 transcript 缺失，很多评分只能变成“根据最终回答推断”，可信度会下降。

3. INCONCLUSIVE 的处理

INCONCLUSIVE 不等于 FAIL，也不等于 PASS。

常见原因：

数据前提不存在。
权限不足导致无法验证。
MCP 返回不完整。
fixture 缺失。
grader 没有足够证据。

处理方式：

先补环境 / 数据 / fixture / 证据，再重跑。
不要一看到 INCONCLUSIVE 就改 Skill。

十、同步与 CI：让测评能被团队复现

如果只在本地能跑，团队无法复现，测评价值会大打折扣。

1. 飞书 / Bitable 同步

如果使用同步能力，确认：

config.json 不提交 Git。
app token / table id 配置正确。
sync-pull 能拉到用例。
sync-push-results 能回写结果。
失败时能降级为本地报告，不阻塞执行。

2. CI 环境

CI 需要额外确认：

runner 能访问 MCP Server 或测试环境。
secrets 已注入。
Python / Node 版本一致。
artifact 能上传。
report.html 能被保存。
失败时保留 transcript 和 diagnostics。

示例：

python scripts/sentry_ci.py \
  --skill finance-doc-query-prod \
  --mode smoke \
  --cases cases/finance-doc-query-prod/evals.json

3. 复现命令

每份报告都应包含复现命令：

python scripts/sentry_run.py \
  --skill C:\path\to\skill\SKILL.md \
  --profile local \
  --cases C:\path\to\evals.json

没有复现命令，团队协同排查会很痛苦。

十一、常见问题排查

Q1：出现 `Tool 'xxx' not found`

原因：

MCP Server 没启动。
配置路径错误。
客户端没重启。
工具名和 SKILL.md 写法不一致。

处理：

查看 MCP Server 日志。
检查配置文件绝对路径。
重启本地编码助手 / OpenCode。
对比 list_tools 和 SKILL.md 工具名。

Q2：工具调用 `401 Unauthorized`

原因：

token 过期。
token 对应生产账号或错误账号。
权限不足。

处理：

重新生成测试 token。
确认 token 绑定测试账号。
用最小 smoke case 验证权限。

Q3：预检通过，但执行中途失败

原因：

预检只做 list_tools，没有真实执行。
测试数据不满足前提。
特定金额、部门、审批流没有配置。

处理：

读取 transcript。
判断是权限、数据还是工具异常。
补数据或权限后重跑。

Q4：大量 `INCONCLUSIVE`

原因：

测试环境缺少前提数据。
Grader 没有足够证据。
MCP 返回不完整。

处理：

先补 fixture 和数据。
确认 transcript 是否包含工具返回。
必要时增强 assertion 或 grader hint。

Q5：不确定当前连的是测试还是生产

处理：

查看 eval_environment.json。
查看 MCP Server 启动参数。
查看工具返回中的环境标识。
如果是 production，立即停止写操作测评。

十二、测评前总检查清单

A. 测评对象

□ Skill 路径明确
□ Skill hash / git commit 已记录
□ Skill 类型已确认
□ 是否写操作已确认
□ 静态检查已完成

B. 运行时

□ Python / Node / Git 可用
□ SkillSentry 脚本可运行
□ 本地编码助手 / OpenCode 已重启
□ session 输出目录可写

C. MCP / 工具

□ MCP Server 可独立启动
□ 配置文件使用绝对路径
□ list_tools 能看到目标工具
□ 至少完成一次真实 smoke 调用
□ 工具 schema 与 SKILL.md 一致

D. 账号权限

□ 使用测试账号
□ token 未过期
□ 权限矩阵已确认
□ 无权限场景可验证
□ 不使用生产个人账号

E. 测试数据

□ 正常数据已准备
□ 边界数据已准备
□ 异常数据已准备
□ 权限数据已准备
□ fixture 路径可用
□ 数据清理机制已确认

F. 环境隔离

□ 当前环境是 test 或 staging
□ 如使用 production，已标记受控测试
□ 写操作有 HiL
□ 创建数据带 eval_run_id
□ 测后清理策略明确

G. 测评集

□ cases/evals 文件存在
□ suite mode 已确认
□ golden/baseline 已确认
□ case lint 已通过
□ P0 用例有 expected/assertion

H. 评分和报告

□ deterministic assertions 可执行
□ LLM judge 有 rubric
□ 高风险 case 有人工复核策略
□ transcript / response / grading / report 能落盘
□ report.html 输出路径明确

I. 同步与 CI

□ 飞书/Bitable config 可用或明确跳过
□ CI secrets 已注入
□ artifact 上传路径明确
□ 报告包含复现命令

全部通过后，再运行正式测评。

总结

AI Skill 测评前的环境准备，不是“把 MCP 配上”这么简单。

MCP 是 mcp_based Skill 的关键前提，但可信测评还需要：

明确测评对象。
稳定运行时。
测试账号和权限矩阵。
可复用测试数据和 fixture。
严格环境隔离。
明确测评集和 baseline。
可校准评分器。
可落盘证据链。
可团队复现的同步和 CI。

真正的标准是：

任何一条测评结论，都能追溯到 Skill 版本、用例版本、环境、账号、数据、工具调用 transcript、评分器和报告产物。

做到这一点，测评通过率才有资格进入发布决策。

31—AI Skill 测评前的环境准备：从 MCP 到账号、数据、隔离和证据链