跳到主要内容

上线前质量检测

场景​

SKILL 开发完了，在上线前需要确认它靠不靠谱。本文教你用 validate 和 eval 两个命令做质量检测，覆盖静态校验和端到端评测，确保 AI 能正确识别并调用你的 SKILL。

前置条件​

  • 已完成 手写第一个 AI 技能 或已有待检测的 SKILL
  • 项目能在开发者工具中正常打开
  • 基础库版本 ≥ 3.16.1

实现步骤​

第 1 步：静态校验​

mp-skills validate 检查 SKILL 配置的正确性，无需启动开发者工具：

npx mp-skills validate

校验内容：

检查项说明
目录结构SKILL.md、mcp.json、index.js 是否存在且位置正确
mcp.json schema接口名、inputSchema、outputSchema 格式是否合规
组件完整性componentPath 指向的组件是否包含 4 个文件（js/json/wxml/wxss）
接口一致性mcp.json 中的接口名与 index.js 注册名是否一致

预期输出：

[OK] 目录结构检查通过
[OK] mcp.json 格式校验通过
[OK] 组件完整性检查通过
[OK] 接口一致性检查通过
[OK] 项目配置检查通过

如果校验失败，根据错误提示修复。常见错误：

[ERR] 组件文件缺失: components/weather-card/index.json
[ERR] 接口名不匹配: mcp.json 中为 "getWeather"，index.js 中为 "getWeater"

第 2 步：配置评测环境​

mp-skills eval 需要 LLM 凭据来生成测试用例。配置方式：

# 方式一：云开发 token 模式（推荐）
# 自动使用云开发环境的 AI 网关，无需手动管理密钥
npx mp-skills login  # 先登录云开发
npx mp-skills eval --provider cloudbase -c 3

# 方式二：手动配置
export WXA_SKILL_EVAL_LLM_BASE_URL=https://api.deepseek.com/v1
export WXA_SKILL_EVAL_LLM_API_KEY=sk-your-key
export WXA_SKILL_EVAL_LLM_MODEL=deepseek-chat

# 方式三：交互式向导（首次运行）
# 直接运行 eval，会自动弹出 LLM 提供方选择界面
npx mp-skills eval -c 3

云开发 token 模式最简单：不需要手动获取 API Key，评测时直接通过云开发网关调用大模型。

第 3 步：运行评测​

# 生成 3 个测试用例，评测全部 SKILL
npx mp-skills eval -c 3

# 只评测指定 SKILL
npx mp-skills eval -s order-skill -c 5

# 无界面模式（适合 CI）
npx mp-skills eval --headless -c 3

评测会模拟用户对话，验证以下维度：

维度说明
意图识别用户说触发语时，AI 能否正确选中你的 SKILL
参数提取AI 能否从自然语言中提取正确的参数
接口调用原子接口能否正常返回数据
卡片渲染返回结果能否通过原子组件展示

第 4 步：解读评测结果​

评测完成后输出报告，包含：

=== 评测报告 ===
SKILL: order-skill
测试用例: 3 个
通过: 2 个
失败: 1 个

失败详情:
- 用例 "搜索川菜馆"：意图识别正确，但参数 keyword 提取为 "川菜馆"
  期望值: "川菜"
  改进建议：在 mcp.json 的 inputSchema 描述中明确参数提取规则

第 5 步：根据结果迭代修复​

常见问题及修复方向：

问题原因修复
AI 没选你的 SKILLSKILL.md 或 mcp.json 的 description 写得太模糊明确触发场景和前置条件
参数提取错误inputSchema.description 没有写清取值来源说明参数从用户原话的哪个部分提取
原子接口返回空数据实现代码有 bug 或依赖的后端不可用检查 api 代码和云函数
卡片渲染异常structuredContent 字段名与组件读取的不一致检查组件中 on(Result) 的字段名

修复后重新运行校验和评测：

npx mp-skills validate
npx mp-skills eval -c 3

验证清单​

  • npx mp-skills validate 全部通过
  • npx mp-skills eval -c 3 可正常启动评测
  • 评测报告没有严重错误
  • 修复后的 SKILL 重新校验通过

常见问题​

npx mp-skills eval 报 LLM 凭据错误

  • 使用云开发 token 模式：先 npx mp-skills login，然后 --provider cloudbase
  • 或手动配置环境变量 WXA_SKILL_EVAL_LLM_API_KEY

评测过程很慢

  • 评测需要调用大模型生成测试用例和验证结果，通常每个用例需要 1-3 分钟
  • 先用 -c 1 跑一个用例快速验证，没问题再加量

validate 报错但找不到问题

  • 检查 mcp.json 的 JSON 格式是否合法（逗号、括号）
  • 检查组件目录是否有完整的 4 个文件（js/json/wxml/wxss）

参考​