qihongkun a41f61bcf6 重命名项目为 quality-inspection-platform

将仓库目录从 ai_auto_test 迁至 quality-inspection-platform，统一质量检测平台命名；MCP 环境变量新增 QIP_* 并兼容 AI_TEST_*。

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-05-22 15:49:59 +08:00

13 KiB

Raw Blame History

MCP 工具能力说明（AI 专用）

读者：Cursor / Codex / Claude 等通过 quality-inspection-platform MCP 工作的 Agent。
目的：在调用 tools/list 之外，提供「何时用哪个工具、按什么顺序、参数怎么填」的固定上下文。
维护：工具以 app/main.py 中 MCP_TOOL_SPECS 和平台 GET /mcp/tools 为准；增删工具时请同步更新本文档。
重要：某些 MCP 客户端可能缓存、裁剪或延迟刷新工具列表；不要仅凭当前客户端可见工具反向删减本文档能力。

0. Agent 必读（30 秒）

先 catalog_snapshot 了解现有 apis / workflows / workflow_batches / mocks / folders / ssh_tree，避免重复创建。
写操作与执行必须带 sto- API Key（Authorization: Bearer 或桥接环境变量 QIP_API_KEY，兼容 AI_TEST_API_KEY）。
接口用 api_upsert；流程用 workflow_upsert 或 workflow_patch_json；跑批固定三步：workflow_batch_create → workflow_batch_update → workflow_batch_run。
排障：workflow_run_get 看 request/response → workflow_run_loki_link 查日志。
如果当前客户端没有显示某个工具，先确认平台 GET /mcp/tools 是否包含该工具，再刷新或重启 MCP 客户端。
人类可读安装与 curl 示例见 docs/mcp_quickstart.md；桥接安装见 docs/mcp_install.md。

0.1 工具来源与客户端刷新

权威工具清单来自后端 app/main.py 的 MCP_TOOL_SPECS，平台通过 GET /mcp/tools 对外暴露。
mcp_bridge.py 启动后会从 QIP_BASE_URL（或兼容 AI_TEST_BASE_URL）的 /mcp/tools 拉取工具并转换为 MCP tools/list。
Codex / Cursor / Claude 等客户端可能在会话启动时缓存工具列表；平台新增工具后，通常需要重启 MCP 客户端或重启会话。
如果客户端只显示部分工具，不代表平台没有该能力。先用 /mcp/tools 或本文档核对，再决定是否降级。
Agent 更新本文档时，应以源码和 /mcp/tools 为准，不以单个客户端当前暴露的工具子集为准。

1. 平台在做什么

层级	含义	MCP 主要工具
接口库	单个 HTTP API 定义（method、url、headers、body…）	`api_upsert`、`catalog_snapshot`
工作流	多节点编排（HTTP / 条件 / 循环 / 提取）	`workflow_upsert`、`workflow_run`
跑批	一次任务顺序执行多个工作流	`workflow_batch_*`
执行历史	每次运行的 request/response 快照	`workflow_run_list`、`workflow_run_get`
Mock	命名数据集，供节点 mock 使用	`mock_upsert`

数据约定：url 只存路径（如 /api/user/{id}），环境域名放在执行时的 base_url。

2. 鉴权

2.1 平台地址

MCP Bridge 通过环境变量访问平台：

环境变量	含义	示例
`QIP_BASE_URL`	质量检测平台后端地址（兼容 `AI_TEST_BASE_URL`）	`http://127.0.0.1:8000`
`QIP_API_KEY`	`sto-` 开头的 API Key（兼容 `AI_TEST_API_KEY`）	`sto-...`

Agent 通过 MCP 工具访问平台，不需要在业务项目中启动平台服务；平台进程由质量检测平台项目本身或共享服务负责。

2.2 调用鉴权

类型	工具示例	无 Key 时
只读	`catalog_snapshot`、`workflow_get`、`workflow_run_list`	以 superadmin 读全库（不推荐生产暴露）
写入	`api_upsert`、`workflow_upsert`、`folder_ensure`…	401
执行	`workflow_run`、`workflow_batch_run`、`ssh_script_run`、`workflow_run_replay`	401

环境变量 MCP_REQUIRE_API_KEY=true 时，所有工具（含 GET /mcp/tools）均需 Key。

写操作与执行类工具必须使用有效 Key。不要把 Key 写入文档、日志或对话输出；只允许放在 MCP 配置、环境变量或请求头中。

3. 按场景选工具（决策表）

用户意图	推荐工具链
我不知道项目里有什么	`catalog_snapshot`
客户端看不到某个工具	查 `GET /mcp/tools` → 重启 MCP 客户端 / 会话 → 再调用
从 Apifox/文档批量建接口	`folder_ensure` → 多次 `api_upsert`（或 `invoke-batch`）
新建/改流程图	`workflow_validate`（可选）→ `workflow_upsert`
只改流程里某几个字段	`workflow_patch_json`
跑一条流程	`workflow_run`（`base_url` + `workflow_id`）
只调试一个节点	`workflow_run_node`
版本/回归一次跑多条流程	`workflow_batch_create` → `workflow_batch_update` → `workflow_batch_run` → `workflow_batch_get`
看某次执行详情	`workflow_run_get`（`run_id`）
看历史列表	`workflow_run_list`（`workflow_id` / `batch_id`）
失败后续跑	`workflow_run_replay`（`run_id`）
查服务端日志	`workflow_run_loki_link`（`run_id` + `node_id`）
看节点上次结果	`workflow_node_status` 或 `workflow_get`
快速看上次成败统计	`workflow_analyze_last_run`
准备 Mock 数据	`mock_upsert`
运维脚本	`ssh_tree` → `ssh_script_upsert` → `ssh_script_run`

4. 工具清单（按分类）

4.1 发现与目录

`catalog_snapshot`

用途：一次拉取 apis、workflows、mocks、workflow_batches、folders、ssh_tree。
参数：无。
何时用：任务开始、批量导入前、避免重复 api_upsert。

`folder_ensure`

用途：登记 apis 或 workflows 目录（空目录也可）。
参数：target：apis | workflows；path：如 auth/login（不要前导 /）。
需 Key：是。

`folder_list`

用途：列出已登记目录。
参数：可选 target。

`api_move_folder` / `workflow_move_folder`

用途：移动资源到目录；workflow 目标目录须已 folder_ensure。

4.2 接口（API）

`api_upsert`

用途：创建或更新接口定义。
必填：name、method、url。
常用可选：api_id（更新）、folder_path、headers、body、query、path_params、timeout_seconds。
需 Key：是。
示例：

{
  "tool": "api_upsert",
  "arguments": {
    "name": "用户登录",
    "folder_path": "auth",
    "method": "POST",
    "url": "/api/login",
    "headers": { "Content-Type": "application/json" },
    "body": { "username": "admin", "password": "{{password}}" },
    "query": {},
    "path_params": {}
  }
}

4.3 工作流（Workflow）

`workflow_upsert`

用途：创建/更新完整 definition（Drawflow JSON）。
必填：name、definition（nodes、edges、variables）。
需 Key：是。
注意：非空 folder_path 须先 folder_ensure（workflows）。

`workflow_get`

用途：读取流程及各节点 last_run。

`workflow_patch_json`

用途：对 definition / variables 等深度合并 patch；小改动优先于全量 upsert。

`workflow_validate`

用途：检查节点 id、边是否引用合法；upsert 前建议调用。

`workflow_move_folder`

`workflow_node_status`

用途：单节点最近 last_run。

`workflow_analyze_last_run`

用途：上次执行汇总（成功/失败节点 id）；细节不足时再 workflow_get。

4.4 执行

`workflow_run`

用途：执行整条工作流。
必填：workflow_id。
可选：base_url（环境根地址）、fail_fast（默认 true）。
需 Key：是。
返回：status、variables、results[]（含每节点 request/response）、run_id。

`workflow_run_node`

用途：只跑一个节点（调试参数）。
必填：workflow_id、node_id。
需 Key：是。

`workflow_run_replay`

用途：按历史 run 内保存的 definition 快照重放。
必填：run_id。
需 Key：是。

4.5 跑批（Batch）

步骤	工具	说明
1	`workflow_batch_create`	建草稿，可带 `name`、`base_url`、`fail_fast`
2	`workflow_batch_update`	必填 `batch_id`；设置 `workflow_ids: [1,2,3]`
3	`workflow_batch_run`	执行，仅 `draft` 可跑
4	`workflow_batch_get`	查看结果及关联 `run_id`

辅助：workflow_batch_list（status 过滤：draft|running|success|failed|partial）。

需 Key：create/update/run 需 Key；get/list 只读。

4.6 执行历史与日志

`workflow_run_list`

参数：可选 workflow_id、batch_id、limit、after_id。
返回：items[] 摘要（无完整 body 时用 workflow_run_get）。

`workflow_run_get`

参数：run_id。
返回：含 payload（results、variables、workflow_snapshot）。

`workflow_run_loki_link`

参数：run_id、node_id（HTTP 节点）。
返回：explore_url、logql、时间窗；未配 GENERAL_LOKI_EXPLORE_URL 时 enabled=false。

4.7 Mock 与其它

`mock_upsert`

用途：按 name 创建/更新 Mock 数据集（data 对象）。
需 Key：是。

`mcp_tool_upsert`

用途：平台内「自定义 MCP 工具配置」表，不是本桥接工具列表本身。

SSH 系列

工具	用途
`ssh_tree`	主机与脚本树
`ssh_script_get`	读脚本内容
`ssh_script_upsert`	创建/更新内联 bash（`profile_id`+`name`+`content`）
`ssh_script_run`	远端执行（需 password，需 Key）

5. 工作流 definition 约定（简版）

{
  "nodes": [
    { "id": "n1", "position": {"x": 0, "y": 0}, "data": { "type": "http", "api_id": 1, "save_as": "resp1" } },
    { "id": "n2", "data": { "type": "extract", "source_var": "resp1", "field": "json.token", "save_as": "token" } }
  ],
  "edges": [
    { "id": "e1", "source": "n1", "target": "n2", "data": { "branch": "success" } }
  ],
  "variables": {}
}

`data.type`	说明
`start` / `end`	透传
`http`	引用 `api_id` 或内联 method/url/headers/body/query/path_params；支持 mock、expect
`extract`	从 `source_var` 取 `field` 写入 `save_as`
`condition`	出边 `branch`: `true` / `false`；支持 `left_mode=json_path`
`loop`	BODY 边进入子图；`while_*` 控制下一轮；DONE 边退出

变量替换：字符串中的 {{token}} 由 variables 注入。工作流级 default_headers 与节点 headers 合并，节点覆盖同名 key。

6. 调用协议

发现：GET /mcp/tools → { tools, require_api_key, ai_guide }
单次：POST /mcp/invoke → { ok, tool, data, error }
批量：POST /mcp/invoke-batch → { results: [...] }，stop_on_error: true 时任一步失败即停

ok=false 时读 error，修正参数后重试；不要臆造未在 tools/list 中出现的工具名。

7. 推荐 Recipe

R1：新建接口并跑通单接口流程

catalog_snapshot → folder_ensure(apis) → api_upsert
→ workflow_upsert → workflow_run → workflow_analyze_last_run

R2：Apifox 迁移一批接口

catalog_snapshot → folder_ensure(apis, 模块路径)
→ invoke-batch: N × api_upsert → 核对 catalog

R3：版本回归跑批

workflow_batch_create → workflow_batch_update(workflow_ids)
→ workflow_batch_run → workflow_batch_get
→ 对失败项 workflow_run_get + workflow_run_loki_link

R4：失败节点最小修复

workflow_analyze_last_run → workflow_patch_json(只改变量/单节点 data)
→ workflow_run → 仍失败则 workflow_run_get 看 payload

8. 常见错误

error / 现象	处理
401 MCP requires API Key	配置 `QIP_API_KEY`（或 `AI_TEST_API_KEY`）或请求头 Bearer
workflow folder not registered	先 `folder_ensure` workflows
仅 draft 批次可执行	已对 running/success 的 batch 再 run
unknown mcp tool	`GET /mcp/tools` 刷新名称
Loki enabled=false	配置 `GENERAL_LOKI_EXPLORE_URL`
重复接口	同 method+url 视为同一接口，更新时传 `api_id`

9. 文档索引

文件	受众
本文 `docs/mcp_tools_for_ai.md`	AI Agent（首选）
`docs/mcp_quickstart.md`	人类 + curl 示例
`docs/mcp_install.md`	MCP 桥接安装
项目根 `AGENTS.md`	Codex 自动加载的短指引

文档版本：与仓库 MCP_TOOL_SPECS 同步（含 workflow_run_ / workflow_validate / 执行类鉴权）。*

13 KiB Raw Blame History Unescape Escape