接口联调总扯皮？用 JiuwenSwarm 搭一套 API 契约测试 Agent 团队-开发者社区

后端说"接口已经开发完了"，前端联调一测——返回格式不对、字段缺失、状态码乱飞。测试同学拿着一份过时的接口文档逐条核对，Mock 数据全靠手写，每次需求迭代都要重新来一遍。

这不是某个团队的特例，而是几乎所有前后端协作项目都会遇到的日常。与其靠人肉核对接口契约，不如让一组 Agent 来干这事。

JiuwenSwarm 是基于 openJiuwen 框架构建的智能 AI Agent，支持 Team 多智能体协作、可安装的 Skill 技能系统、Heartbeat 心跳巡检和定时任务，能让接口验证这件事变得自动化、可持续。

官方网站：https://www.openjiuwen.com

代码仓库：https://atomgit.com/openJiuwen

我们要搭什么东西

三个 Agent，各管一件事：

接口契约（OpenAPI / Swagger 文档） │ ┌──────┴──────┐ │ Team Leader│ 统一调度 └──────┬──────┘ ┌───────────┼───────────┐ │ │ │ 契约验证Agent 数据生成Agent 回归巡检Agent 逐接口发请求 读契约生成Mock 定时跑全量用例 断言状态码/ 覆盖边界场景 对比前后版本差异 字段/格式 输出到Mock服务 输出变更报告

听起来复杂，但用 JiuwenSwarm 的 Team 模式 + Skill，半天就能跑起来。

五分钟装好环境

pip install jiuwenswarm jiuwenswarm-init jiuwenswarm-start

浏览器打开 http://localhost:5173，进"设置 → 配置信息 → 模型配置"填上 API KEY（支持华为云 MaaS 等），就算就绪了。

第一步：建一个测试团队

Team 模式是 JiuwenSwarm 的多智能体协作方式，直接点击集群模式切换。团队结构在config.yaml里配：

modes: team: api_test_team: team_name: api_test_team lifecycle: persistent teammate_mode: build_mode spawn_mode: inprocess leader: member_name: api_test_leader display_name: API测试负责人 persona: "你是一个资深的API测试工程师，负责协调接口契约验证。 收到接口文档或测试需求后，你需要： 1) 逐个接口发送请求，验证状态码、响应字段、数据格式是否符合契约； 2) 基于契约自动生成各字段的Mock数据，覆盖正常值、边界值、异常值； 3) 对比前后版本的接口变更，输出兼容性报告。 所有结果以结构化格式输出。" agents: leader: workspace: stable_base: true max_iterations: 200 completion_timeout: 600.0 workspace: enabled: true transport: type: inprocess storage: type: sqlite

配好后重启服务，直接使用集群模式，你的对话对象变成了"API测试负责人"。

第二步：装一个契约分析技能

Skill 是 JiuwenSwarm 的可安装能力模块，每个 Skill 就是一个带SKILL.md的文件夹。我们来创建一个 API 契约测试专用技能。

cd ~/.jiuwenswarm/agent/jiuwenswarm_workspace/skills mkdir api-contract-test

创建SKILL.md：

name: api-contract-test version: 1.0.0 description: API契约测试技能，支持接口验证、Mock数据生成和变更对比 tags: [api, testing, contract, mock] allowed_tools: [webSearch, readFile] API 契约测试 当收到接口契约文档需要验证时，按以下流程处理： 步骤 接口验证：逐个接口发送请求，断言以下内容： HTTP 状态码是否符合预期（2xx / 4xx / 5xx） 响应体的字段名称、类型是否与契约一致 必填字段是否存在，可选字段为空时是否合规 分页、排序、过滤等查询参数是否生效 Mock 数据生成：基于契约中的 Schema 定义，为每个接口生成三组数据： 正常数据：符合字段类型、长度、格式要求的标准用例 边界数据：空字符串、最大长度、最小值/最大值、特殊字符 异常数据：缺少必填字段、类型错误、越界值 变更对比：对比新旧两版接口契约，输出： 新增/删除的接口 字段变更（新增、删除、类型变化） 是否存在破坏性变更（Breaking Changes）

然后通过 Web 界面左侧栏 → Skills → Local import 导入即可。

值得提一句：JiuwenSwarm 的技能支持自演进。当 Agent 执行出错或你给出纠错反馈时，SKILL.md会自动优化。在config.yaml里确保这一段开着：

evolution: enabled: true auto_scan: false skill_base_dir: "workspace/agent/skills"

第三步：配个心跳，让它自己跑

接口不是测一次就完了。JiuwenSwarm 的 Heartbeat 可以按固定间隔自动巡检。编辑HEARTBEAT.md：

心跳任务： 对测试环境执行全量接口健康检查 逐接口发送 GET /health 或标准请求，验证状态码是否为 2xx 如有异常接口，按 api-contract-test 技能流程进行详细诊断 输出健康检查摘要

config.yaml里配上频率：

heartbeat: every: 1800 # 每 30 分钟巡检一次 target: web active_hours: start: 08:00 end: 22:00 # 工作时间跑就行

这样你不需要主动去测，Agent 每半小时自己过一遍，有问题直接在 Web 界面弹出通知。

第四步：定时出报告

每天下班前自动跑一遍全量回归，第二天早上看报告。用 Cron 功能：

在 Web UI 中 Cron → New job：

name：daily_api_report
cron_expr：0 18 * * *（每天下午 6 点）
timezone：Asia/Shanghai
targets：web
description：跑全量接口回归测试，输出今日新增失败用例、未通过接口列表、与前日的对比变化

也可以直接在对话框里说："帮我创建一个每天下午6点的定时任务，跑全量接口回归，结果推到 web。"

跑一把试试

在 Web 对话框中（集群模式下），贴一份接口契约进去：

请验证以下接口契约： POST /api/v1/users 请求体： name: string, 必填, 2-50字符 email: string, 必填, 合法邮箱格式 age: integer, 可选, 0-150 role: enum [admin, editor, viewer], 必填 成功响应 201: id: string (UUID) name: string email: string role: string created_at: ISO8601 datetime 错误响应 400: error: string detail: object

接口验证结果：