Skills
skills/skills.netease.im/easydata-tool-validator

easydata-tool-validator

SKILL.md

easydata-tool-validator

MCP Tool Schema 规范检测工具，用于拉取 EasyData 平台远程类目（Category）和工具（Tool）的 Schema 信息，并对照规范文档检测其是否合规。

规范文件

规范文件位于 reference/ 目录下，检测时应以此为依据：

文件 说明
category_tool_schema_spec.md EasyData Schema 完整规范，包含 Tool 命名、描述、参数、类目、敏感操作、输入输出等全部规范定义

配置管理

配置文件位置：~/.easydata/cli.json

检查配置

python3 scripts/easydata config check

返回 ✅ 配置完整 时可直接使用；返回 ❌ 缺少必填配置: [...] 时需引导用户配置。

首次配置

配置提醒规则： 引导配置时必须对每个可选配置项说明决策原则。

向用户获取以下配置项信息：

  • endpoint: 【必需】EasyOpenAPI 服务地址（请根据访问位置配置办公网/机房网地址）
  • apiKey: 【必需】EasyOpenAPI API Key
  • secretKey: 【必需】EasyOpenAPI Secret Key
  • groupId: 【可选】项目组ID（单项目组建议配置，多项目组建议执行时指定）
  • product: 【可选】项目名称（单项目建议配置，多项目建议执行时指定）
  • clusterId: 【可选】集群ID（单集群建议配置，多集群建议执行时指定）
  • user: 【可选】用户邮箱（单用户建议配置，多用户建议执行时指定）
python3 scripts/easydata config init

修改单项配置

python3 scripts/easydata config set [--endpoint ENDPOINT] [--apiKey API_KEY] [--secretKey SECRET_KEY] [--groupId GROUP_ID] [--product PRODUCT] [--clusterId CLUSTER_ID] [--user USER]

命令说明

python3 scripts/easydata <command> [options]
命令 说明
list 列出所有服务类目（始终返回全量，无筛选参数）
check <category> [index] [since] 查看指定类目下工具的完整 Schema。<category>：必填，服务类目标识（通过 list 获取）；[index]：可选，工具序号（从 1 开始），不传则返回该类目下全量工具，传入则返回单个工具（超出范围不展示）；[since]：可选，格式 YYYY-MM-DD，仅检测该日期后更新的工具
refresh 强制刷新服务类目信息与工具 Schema 信息缓存
config init 交互式初始化配置
config set --<key> <value> 修改单项或多项配置，如 --endpoint URL --product NAME
config check 检查配置完整性
config show 显示当前配置（敏感字段脱敏显示）

list — 列出服务类目

# 返回全量服务类目（list 命令始终返回全量，不支持筛选）
python3 scripts/easydata list

输出示例（JSON 格式）：

{
  "total": 10,
  "categories": [
    {"category": "easyolap", "description": "自助分析平台 ..."},
    {"category": "easydqc", "description": "数据质量管控中心 ..."}
  ]
}

check — 审查工具 Schema

check 命令支持两种模式，均可使用：

模式一：全量模式（不传 index） — 一次性返回该类目下所有工具的完整 Schema

# 返回 easyolap 类目下全量工具
python3 scripts/easydata check easyolap

# 返回 easyolap 类目中 2026-04-01 以来更新的全量工具
python3 scripts/easydata check easyolap 2026-04-01

全量模式输出示例：

{
  "category": "easyolap",
  "total": 5,
  "tools": [
    {"name": "get_task_detail", "description": "...", "annotations": {...}, "inputSchema": {...}, "outputSchema": {...}, "inputExample": [...]},
    {"name": "list_tasks", "description": "...", ...}
  ]
}

模式二：单个模式（传入 index） — 返回指定序号的单个工具 Schema

# 查看 easyolap 类目下第 1 个工具的完整 Schema
python3 scripts/easydata check easyolap 1

# 查看 easyolap 类目中 2026-04-01 以来第 1 个更新工具的完整 Schema
python3 scripts/easydata check easyolap 1 2026-04-01

单个工具输出包含：

  • name：工具名称
  • description：工具描述
  • annotations：元信息（含 sensitive 敏感等级等）
  • inputSchema：完整入参 JSON Schema
  • outputSchema：完整出参 JSON Schema
  • inputExample：输入参数示例

refresh — 刷新缓存

python3 scripts/easydata refresh

工作流程

严格按照以下步骤顺序执行，不可省略、不可调换、不可合并步骤。

第一步：检查配置

执行 config check，若配置不完整则引导用户执行 config init 完成初始化。

第二步：强制刷新缓存

执行 refresh 命令，强制刷新缓存，确保后续所有操作使用最新数据。此步骤必须执行，不可省略。

第三步：确认检测范围

询问用户是否指定更新时间（格式 YYYY-MM-DD），用于增量检测工具。若不指定则检测全量工具。注意：更新时间仅影响 check 命令的工具筛选，list 命令始终返回全量类目。

第四步：获取全量类目

执行 list 获取全量类目列表。

第五步：类目合规检测

对照规范文档逐一检测每个类目的命名、描述是否合规，输出类目检测结果。

第六步：按类目分发 subagent 并行检测工具

核心机制：为避免上下文超限，必须将工具检测任务按类目拆分为多个独立 subagent 并行执行。

将第四步获取的全量类目列表拆分，每个类目单独分发一个 subagent 任务，多个 subagent 可并行执行（每批最多 5 个）。

每个 subagent 任务的指令模板如下：

请检测类目「{category}」下所有工具的 Schema 合规性。

获取工具数据（以下两种方式均可使用，自行选择）：
- 全量模式：执行 python3 scripts/easydata check {category} [{since}]，一次性获取该类目下所有工具
- 逐个模式：从 index=1 开始，逐一执行 python3 scripts/easydata check {category} {index} [{since}]，index 递增直到提示「序号超出范围」

执行步骤：
1. 先阅读规范文档 reference/category_tool_schema_spec.md
2. 使用上述任一方式获取该类目下的工具 Schema
3. 对每个工具 Schema，对照规范检查以下内容：
   - Tool 命名：是否蛇形命名、动词开头、长度合规（§1）
   - Tool 描述：是否清晰描述功能、场景、参数要求（§2）
   - 参数数量：是否不超过 8 个（§3.1）
   - 参数类型：类型是否合规（§3.3）
   - 参数描述：每个参数是否有描述和示例（§3.4）
   - 敏感操作：annotations.sensitive 是否正确标识 high/medium/low（§6）
   - inputSchema：是否必填、结构是否合规（§7.1）
   - outputSchema：是否必填、结构是否合规（§7.2）
   - inputExample：是否提供调用示例，每个示例是否包含 description 和 example；description 场景描述是否清晰易懂，example 参数值是否贴近真实场景、便于大模型理解和参考（§7.3）
4. 输出该类目的检测结果汇总：合规项、不合规项及具体改进建议

分发规则：

  • 将类目列表按每批最多 5 个分组
  • 每批内的 subagent 任务互相独立，可并行分发
  • 等当前批次全部完成后，再分发下一批
  • 如果用户指定了更新时间 {since}，在 check 命令中带上该参数；否则不带

第七步：汇总结果

收集所有 subagent 返回的检测结果，汇总输出完整报告：

  1. 类目检测结果（来自第五步）
  2. 工具检测结果（来自各 subagent）：按类目分组，列出每个工具的合规/不合规项
  3. 整体统计：总工具数、合规数、不合规数
  4. 改进建议：汇总所有不合规项的改进建议

检测要点

对照 reference/category_tool_schema_spec.md 规范，主要检测以下内容：

检测项 规范章节 说明
Tool 命名 §1 是否蛇形命名、动词开头、长度合规
Tool 描述 §2 是否清晰描述功能、场景、参数要求
参数数量 §3.1 是否不超过 8 个
参数类型 §3.3 类型是否合规（string/number/boolean/integer/array/object/enum）
参数描述 §3.4 每个参数是否有描述和示例
类目命名 §4.1 是否烤串命名、长度合规
类目描述 §4.2 是否符合「一句话定位 + 能力概述」结构
敏感操作 §6 annotations.sensitive 是否正确标识（high/medium/low）
inputSchema §7.1 是否为必填、结构是否合规
outputSchema §7.2 是否为必填、结构是否合规
inputExample §7.3 是否提供调用示例，每个示例是否包含 description（场景描述）和 example（参数示例对象）；description 是否清晰易懂，example 参数值是否贴近真实场景、便于大模型理解和参考

重要规则

  1. 规范为准：所有检测结论必须基于 reference/category_tool_schema_spec.md 规范文档，不可自行编造规则。
  2. 配置隔离：不直接操作配置文件，只通过脚本命令管理配置。
  3. 必须刷新：每次执行检测前必须先执行 refresh 刷新缓存。
  4. 全量类目：list 命令始终返回全量类目，类目检测和工具检测都基于同一份全量类目列表。
  5. 按类目拆分 subagent：工具检测必须按类目拆分为独立 subagent 执行，每个 subagent 只处理一个类目，避免上下文超限。
  6. 两种 check 模式均可：subagent 可选择全量模式（check {category}）一次性获取所有工具，也可选择逐个模式（check {category} {index}）逐一获取。两种方式都允许使用。
  7. 不遗漏工具：无论使用哪种模式，必须确保该类目下所有工具均被检测，不可跳过。

资源文件

scripts/

  • easydata：Schema 数据拉取与查询工具，提供类目和工具 Schema 的缓存管理能力。

reference/

  • category_tool_schema_spec.md：EasyData Schema 规范文档，是检测的唯一依据。
Installs
2
Source
skills.netease.…0acee98c
First Seen
Apr 21, 2026