API Shakedown

API Shakedown

提供 OpenAPI 规范，即可获得一套开箱即用的测试工具包：WireMock 桩、契约测试、健壮性探测和混沌场景，均由一组相互审查工作的 LLM Agent 编写。

默认在 Ollama 上本地运行：无需 API 密钥，数据不会离开你的计算机。云端模型（OpenAI、Anthropic）需自行提供密钥。提供 CLI、Docker 镜像和 MCP 服务，方便 AI 助手驱动运行。

状态：alpha（0.1.3）。使用本地 8B 模型，可在示例规范上端到端运行。

在笔记本电脑上使用随附示例和 qwen3:8b 进行的一次真实运行，已加速：生成耗时约 9 分钟。录制文件：docs/demo.cast。

---

目录

• 原因
• 适用场景
• 快速开始
• 你将获得什么
• 工作原理
• 安装
• 用法
• 配置
• MCP 服务
• Docker
• 架构
• 限制
• 路线图
• 开发
• 贡献
• 许可证

原因

使用 API 的团队需要以下三样东西，但手动编写既繁琐又很快会过时：

1. 逼真的 API 模拟，用于开发和测试。
2. 契约测试，帮助你发现真实 API 何时不再符合其规范。
3. 故障演练：当 API 速度变慢、时好时坏、触发速率限制、返回无效数据或宕机时，你的客户端会如何应对？

API Shakedown 会根据你已有的规范生成这三样东西，并确保它们始终可靠：LLM 不会编写可运行的代码。它们只提出数据（响应正文、测试用例、故障场景、测试记录），由代码根据规范验证每一项，将问题反馈给模型；如果模型无法正确完成，则回退到确定性输出。即使完全不使用模型（--offline），所有功能仍可运行。

适用场景

场景	典型团队	API Shakedown 能为你做什么
后端尚不存在时开始构建	前端、移动端、合作伙伴集成团队	根据已达成一致的规范生成虚拟服务，让工作从第一天就开始，而不必等到后端上线或手写模拟。
依赖你无法控制的 API（支付、配送、身份验证、信用机构）	金融科技、电商、物流、保险	供应商的沙盒通常有速率限制、不稳定，或按调用计费。你可以在本地测试应用在服务提供商超时、限制你的速率，或在恢复前连续两次返回 503 时的表现。
验证客户端能够经受故障	微服务团队、SRE 故障演练	在客户端运行期间，随时启用或关闭超时、速率限制、不稳定调用和部分中断，并确认重试、退避和回退机制确实有效。
在发布前发现规范偏差	API 负责人、平台和公共 API 团队	在 CI 中针对真实部署运行契约测试；当实现与规范不再一致时，测试就会失败。
强化输入验证	任何 API 团队	鲁棒性探测会检查格式错误的请求是否返回 4xx，而不是 500。这是安全审查的补充，而非替代。
受监管或离线环境	银行、医疗、政府	所有内容都由本地模型处理：规范不会离开设备，而许多 AI 工具在这类环境中完全无法使用。
迁移或重写服务	旧系统现代化团队	根据现有规范生成契约测试，并针对新实现运行，以确认其行为一致。
通过 AI 助手开展工作	使用 Claude 和其他 MCP 客户端的开发者	助手会按需生成测试框架并运行故障演练。

它不是负载测试工具或安全扫描器，而且虚拟服务不会在调用之间保留状态；请参阅限制。

快速开始

前提条件：Python 3.11+、Docker（用于 WireMock）以及安装了模型的 Ollama（运行 ollama pull qwen3:8b），除非你使用 --offline 或云模型。

pip install api-shakedown
shakedown doctor                                   # is the model ready?
shakedown run openapi.yaml --out my-harness        # minutes on a local model
cd my-harness
docker compose up -d                               # WireMock with your stubs on :8080
pip install -r requirements.txt
SHAKEDOWN_SELECT_STATUS=1 pytest tests/test_contract.py
python chaos/chaos.py on flaky-start               # now point your client at :8080
python chaos/chaos.py off

使用附带的示例试用：shakedown run examples/petstore.yaml --out petstore。

使用示例规范和 qwen3:8b 进行的一次实际运行：

Petstore 1.0.0: 5 operations (ollama / qwen3:8b)
Generating test data...
Test data ready (3 Pet).
Generating stubs, contract tests, and chaos scenarios...
  stubs: done
  contracts: done
  chaos: done
  review contracts: approved
  review stubs: approved
  review chaos: approved

Wrote 14 files to harness in 436s: 15 stubs, 11 contract cases, 11 chaos scenarios, 30 probes.
Next: cd harness && docker compose up -d   (then see README.md)

你将获得什么

my-harness/
├── README.md                  # generated: how to run it, every scenario, review notes
├── docker-compose.yml         # WireMock 3 serving the stubs (port: SHAKEDOWN_WIREMOCK_PORT)
├── wiremock/mappings/         # stub mappings
├── tests/
│   ├── test_contract.py       # contract tests (cases in contract_cases.json)
│   └── test_robustness.py     # malformed-request probes (cases in robustness_cases.json)
├── chaos/
│   ├── chaos.py               # switch failure scenarios on/off (standard library only)
│   └── chaos_scenarios.json
├── data/dataset.json          # test records and edge-case values per field
├── requirements.txt           # pytest, httpx, openapi-schema-validator
└── shakedown.json             # manifest: counts, review outcome, generation notes

部分	功能
桩	每个操作所有有文档记录的响应。已知 ID 会返回自身记录，未知 ID 会返回有文档记录的 404；也可以通过 X-Shakedown-Status: <status> 请求其他响应。
契约测试	正常路径、有文档记录的错误状态和边界值。每项都会根据响应架构检查状态码、Content-Type 和响应正文。可针对桩或真实部署运行。
稳健性探测	根据架构生成无效正文和参数（缺少必填字段、类型错误、超出范围的值、格式错误的 JSON）。稳健的服务应返回 4xx，而绝不返回 5xx。
混沌场景	每个客户端都应能应对的 7 种基线故障，以及由大模型针对你的 API 生成的场景。
测试数据	每种实体都有真实、一致的记录，供桩和测试共用；此外，每个字段都包含边界情况值。

基线混沌场景：

场景	发生情况	有弹性的客户端应
total-outage	每个端点都返回 503	快速失败、退避，避免不断请求 API
slow-responses	每个响应都耗时 3 s	保持响应灵敏
timeouts	每个响应都耗时 30 s	自行放弃并释放资源
connection-resets	连接被重置	以退避方式重试幂等调用
flaky-start	前 2 次调用失败并返回 503，随后恢复	重试并在第 3 次尝试时成功
rate-limited	前 3 次调用返回 429	遵守 Retry-After
truncated-json	成功响应正文在 JSON 中途被截断	报告解析错误，绝不崩溃

真实运行中由大模型针对 API 生成的场景包括：createPet 连续 3 次返回 503 后恢复、listPets 遭遇速率限制，以及 getPet 丢失必填字段。

工作原理

flowchart LR
    spec[/"OpenAPI spec"/] --> load["Load, validate,<br/>normalize, chunk"]
    load --> data["Test data agent"]
    data --> stubs["Stub agent"]
    data --> contracts["Contract agent"]
    data --> chaos["Chaos agent"]
    stubs --> review{"Reviewer agent"}
    contracts --> review
    chaos --> review
    review -- "blocker: revise with feedback" --> stubs
    review -- "blocker" --> contracts
    review -- "blocker" --> chaos
    review -- "approved, or budget spent" --> coord["Coordinator"]
    coord --> harness[/"Harness directory"/]

1. 规范层：从路径或 URL 加载 YAML/JSON，对其进行验证（问题会转为警告），安全地内联 $ref，并将操作拆分成适合提示词的块，以便小型模型也能处理大型规范。
2. 测试数据 Agent 首先运行：桩和测试共用其生成的记录。
3. 桩 Agent、契约 Agent 和混沌 Agent 并行运行。
4. 审查器评估每项产物。遇到阻断项时，会将产物连同反馈退回给作者，在有限轮次内进行修订；建议会作为备注保留。
5. 协调器整合测试框架及其 README，其中包括修订次数用尽时审查器仍不接受的内容。

每个 Agent 都遵循相同的模式，这正是小型本地模型也能稳定运行的关键：

sequenceDiagram
    participant A as Agent
    participant M as LLM
    participant C as Code checks
    A->>M: task + JSON schema (constrained decoding on Ollama)
    M-->>A: proposal (bodies, cases, scenarios, records)
    A->>C: validate against the spec
    alt problems found
        C-->>A: exact errors, e.g. "listPets 200: 'id' is a required property"
        A->>M: fix these problems
        M-->>A: corrected proposal
    end
    A->>A: keep valid items, fall back to deterministic ones for the rest

以下事项由代码保证，因此模型无需处理：

• 桩中的请求匹配、URL 模式、优先级和路径参数类型。
• 响应正文符合其架构。
• 测试输入能够正确路由（有效的路径参数、必填查询参数）；成功用例使用存在的 ID，404 用例使用不存在的 ID。
• 根据规范中的安全方案进行身份验证。
• 混沌场景在逻辑上保持一致（“不稳定”故障必须恢复，速率限制必须返回 429，部分服务中断必须保留部分可用端点）。
• 审查器的审查结果引用真实项目，且阻断项只针对作者可控制的内容。

安装

pip install api-shakedown              # local models via Ollama; includes the MCP server
pip install "api-shakedown[cloud]"     # plus OpenAI and Anthropic

也可以使用包含所有内容的 Docker 镜像：参见 Docker。

生成的测试框架需要 Docker（用于 WireMock）和 Python 来运行测试。

使用方法

shakedown doctor                     Check the LLM provider is reachable and ready
shakedown inspect SPEC [--json]      Show the operations the agents will see
shakedown run SPEC [options]         Generate a harness
shakedown version

shakedown run 选项：

选项	默认值
--out PATH	shakedown-output	输出测试框架的位置（若目录非空则拒绝写入）
--offline	关闭	不使用大模型：数秒内生成确定性输出
--no-review	开启评审	跳过评审者（在示例中速度约快 3 倍）
--max-revisions N	1	评审／修订轮数
--force	关闭	写入非空目录（仅覆盖测试框架文件）
--provider、--model	来自设置	覆盖本次运行所用的大模型

使用测试框架：

docker compose up -d                                     # stubs on http://localhost:8080
SHAKEDOWN_SELECT_STATUS=1 pytest tests/test_contract.py  # against the stubs
python chaos/chaos.py list | on <scenario> | off         # failure drills
SHAKEDOWN_TARGET_URL=https://api.example.com/v1 pytest tests   # against a real server
SHAKEDOWN_SEED=1 SHAKEDOWN_TARGET_URL=... pytest tests   # create the test records first

设置 SHAKEDOWN_SEED=1 后，契约测试会先使用规范自身的创建操作，在服务器上创建测试数据集的记录，并在测试结束时将其删除。 这会向服务器写入数据，因此请将其指向测试实例。

PowerShell：$env:SHAKEDOWN_SELECT_STATUS = "1"; pytest tests/test_contract.py。

配置

设置来自环境变量或 .env 文件 （参见 .env.example）。所有设置均为可选。

变量	默认值
SHAKEDOWN_PROVIDER	ollama	ollama、openai 或 anthropic
SHAKEDOWN_MODEL	按提供商而定	qwen3:8b、gpt-5-mini、claude-sonnet-5-5
SHAKEDOWN_OLLAMA_URL	http://localhost:11434	Ollama 的运行位置
SHAKEDOWN_BASE_URL		端点覆盖值，例如 OpenAI 兼容服务
SHAKEDOWN_TIMEOUT	600（Ollama）／120	每次请求的秒数
SHAKEDOWN_CONTEXT_WINDOW	16384	Ollama 上下文大小
SHAKEDOWN_REASONING	模型默认值	Ollama：开启／关闭推理模型的思考功能
SHAKEDOWN_AGENT_MODELS		按 Agent 指定模型，例如 {"reviewer": "anthropic:claude-sonnet-5-5"}
SHAKEDOWN_AGENT_REASONING	生成器默认关闭思考	按 Agent 指定思考功能，例如 {"reviewer": true}
OPENAI_API_KEY、ANTHROPIC_API_KEY		使用你自己的密钥

混用模型效果很好：在本地生成，再用更强大的云端模型进行评审：

SHAKEDOWN_AGENT_MODELS='{"reviewer": "anthropic:claude-sonnet-5-5"}' shakedown run openapi.yaml

生成的测试框架会读取 SHAKEDOWN_TARGET_URL、SHAKEDOWN_SELECT_STATUS、 SHAKEDOWN_SEED、SHAKEDOWN_API_KEY、SHAKEDOWN_BASIC_AUTH、SHAKEDOWN_TIMEOUT 和 SHAKEDOWN_WIREMOCK_PORT／SHAKEDOWN_WIREMOCK_URL。

MCP 服务

shakedown-mcp（stdio）允许 MCP 客户端（例如 Claude Code 或 Claude Desktop） 生成测试框架并运行故障演练：

工具
doctor	大模型提供商是否已就绪？
inspect_spec	列出规范中的操作和警告
generate_harness	生成测试框架，并发送进度通知
list_chaos_scenarios	列出测试框架中的场景
activate_chaos／deactivate_chaos	在运行中的 WireMock 中启用／停用场景

claude mcp add api-shakedown -- uvx api-shakedown mcp     # Claude Code, nothing to install
claude mcp add api-shakedown -- shakedown-mcp             # Claude Code, after pip install

官方 MCP Registry 中的名称： io.github.anzar-ahsan-commits/api-shakedown。

其他客户端（在其配置中使用 mcpServers）：

{
  "mcpServers": {
    "api-shakedown": {
      "command": "uvx",
      "args": ["api-shakedown", "mcp"],
      "env": { "SHAKEDOWN_PROVIDER": "ollama" }
    }
  }
}

请传入绝对路径。使用本地模型生成需要几分钟；如果客户端因工具调用时间过长而放弃，请使用 offline 或 review: false，或者调高其工具超时时间。

Docker

docker build -t api-shakedown .
docker run --rm -v "$PWD:/work" api-shakedown run /work/openapi.yaml --out /work/harness
docker run -i --rm -v "$PWD:/work" --entrypoint shakedown-mcp api-shakedown   # MCP server

镜像通过 host.docker.internal 访问主机上的 Ollama。Linux、PowerShell 和云端密钥的详情请参见：DOCKER.md。

架构

flowchart TB
    subgraph app["api-shakedown"]
        cli["CLI: shakedown"] --> pipeline["pipeline"]
        mcp["MCP server: shakedown-mcp"] --> pipeline
        pipeline --> agents["agents: testdata, stubs, contracts,<br/>chaos, reviewer, coordinator"]
        agents --> domain["spec, wiremock, contracts,<br/>chaos, testdata (code checks)"]
        pipeline --> harness["harness writer + templates"]
    end
    subgraph core["agentpanel (reusable core)"]
        workflow["Workflow: parallel specialists,<br/>cross-review, bounded revision"]
        structured["structured output:<br/>validate, feed back, retry"]
        llm["providers: Ollama, OpenAI, Anthropic"]
    end
    agents --> workflow
    agents --> structured
    structured --> llm

编排核心以独立项目 agentpanel 的形式发布：这是一个小型、与领域无关的库，用于在 LangGraph 上实现“专家起草、评审者批评、作者修订、协调者决策”工作流。 它不会导入应用程序；有一项测试会对此进行验证。

packages/agentpanel/     # the reusable core (its own PyPI package)
src/api_shakedown/       # the application
  spec/                  # loading, validation, $ref resolution, edge cases, samples
  agents/                # the six agents
  templates/             # runners copied into every harness
examples/petstore.yaml   # example spec
tests/                   # offline tests; `-m live` for Ollama + Docker tests

局限性

• 本地模型运行速度：使用 qwen3:8b 运行包含 5 个操作的示例大约需要 7 分钟，其中大部分时间用于审查；--no-review 大约需要 2.5 分钟。
• 小型审查模型并不完美：8B 审查模型有时会误报阻塞问题，导致需要多一轮修订。如果可以，请使用更强的模型进行审查。
• 规范：支持 OpenAPI 3.0-3.2。必须先转换 Swagger 2.0；不会跟进对其他文件的引用；不会验证自引用架构。
• 桩是静态的：创建调用会返回一条新记录，但桩不会在调用之间保留状态。
• 针对桩的探测仅涵盖文档中注明 4xx 响应的操作；这些探测面向真实服务。
• 数据填充有限制：SHAKEDOWN_SEED=1 只能创建规范允许使用测试数据中的 ID 创建的记录，而真实服务通常会强制执行规范未说明的规则。无法创建的记录会列在警告中；读取这些记录的测试会失败并返回 404，直到你自行创建它们。
• 适用范围：不是负载测试工具，也不是安全扫描器。
• 大型规范在笔记本电脑上运行较慢：使用 qwen3:8b 和笔记本电脑 GPU 端到端处理 Typesense API（79 个操作）需要数小时，而小型规范只需几分钟。更强大的 GPU 或云端模型会快得多；--offline 只需几秒。非常欢迎分享更多来自真实场景规范的报告。

路线图

• 加快大型规范的运行速度（每批使用更短的提示词，显示每批进度）
• 改进数据填充：从创建响应中获取服务分配的 ID，以便也能填充 API 密钥等资源
• 支持有状态桩（WireMock 响应模板化，创建的记录可供后续调用使用）
• 添加认证失败场景（401/403）和“有效但恶意的输入不得导致 5xx”探测
• 审查测试数据集
• 支持更多测试框架（k6 负载配置、Postman 集合）

开发

git clone https://github.com/anzar-ahsan-commits/api-shakedown.git
cd api-shakedown
python -m venv .venv && source .venv/bin/activate     # Windows: .venv\Scripts\activate
pip install -e packages/agentpanel -e ".[dev]"
ruff check . && ruff format --check . && mypy
pytest                 # offline: LLMs are faked, about 20 s
pytest -m live         # also uses your local Ollama and Docker

贡献

欢迎贡献：请参阅 CONTRIBUTING.md。安全问题： 请参阅 SECURITY.md。

许可证

MIT © 2026 Anzar Ahsan