API Contract Agent

从真实代码和调用行为中自动生成、验证和完善 API 规范的工具。
面向“没有文档 / 文档过期 / 错误信息含糊”的内部服务，帮助团队快速恢复 OpenAPI + llms.txt，让人和 LLM 都能安全、正确地调用接口。

背景

在大型公司内部，很多服务缺乏可靠的 API 文档，或者文档早已与代码和网关规则脱节。

典型现象包括：

• 报错提示 “missing token” 却不说明需要哪个 header；
• 项目多次易主，历史负责人已经记不清接口约束；
• 新接手的同学只能翻源码或抓包来“考古”。

API Contract Agent 试图自动化这件事：

1. 从现有服务的 源码（当前支持 FastAPI）中抽取路由、方法和基本参数；
2. 基于代码与少量调用日志，让 LLM 生成更完整的 OpenAPI 规范；
3. 通过内置的 API test harness 对接口进行自测，利用真实响应修正规范；
4. 从最终规范生成适配 LLM 的 llms.txt，方便 Copilot / Cursor / Claude Code 等工具使用。

核心能力

• 针对单个 FastAPI 服务：
  • 自动导出或推断初始 OpenAPI 规范；
  • 生成小规模 harness 测试计划，自动自测常见错误（例如缺少鉴权 header）；
  • 根据自测结果更新 OpenAPI 中的 required 字段、错误码和示例；
  • 一键生成 llms.txt，对外暴露“推荐调用方式”和“常见坑”。

当前仓库已经实现了一个可运行的 MVP：

• demo_service/ 提供一个带“隐式鉴权 header”的示例服务；
• analyzer/ 支持优先从 FastAPI.app.openapi() 导出规范，失败时退回 AST 扫描；
• harness/ 会从 OpenAPI 生成少量测试，并根据 401/403 响应推断缺失的 header 约束；
• app/ 暴露 /scan、/self_test、/llms_txt 三个 orchestrator 接口；
• llms/client.py 已预留统一 LLM 适配层，当前 refinement 先采用启发式规则，方便比赛演示先跑通。

目标是让开发者从“翻旧代码 / 追问历史负责人”，升级为对 AI 生成的 contract 做 review。

Demo

自动扫描仓库并生成初始 OpenAPI 规范	自测流程实时展示轮次进度和状态
Swagger UI 预览修正后的接口文档	生成面向 LLM 使用的 llms.txt

项目结构

app/                # FastAPI 后端 & orchestrator
analyzer/           # 从源码抽取路由和初稿 OpenAPI
harness/            # API test harness，自测并收集实际行为
llms/               # LLM 客户端与各类 prompt
demo_service/       # 示例 FastAPI 服务（用于比赛演示）
tests/              # 单元测试与集成测试
scripts/            # 命令行工具（生成规范、运行 harness 等）

• app/main.py
  暴露 HTTP 接口，例如 /scan, /self_test, /llms_txt，供前端调用。
• analyzer/fastapi_extractor.py
  优先使用 app.openapi() 导出规范；失败时退回 AST 扫描。
• harness/
  根据当前 OpenAPI 生成测试计划，发起 HTTP 请求，收集响应，调用 LLM 进行规范修正。
• llms/prompts/
  存放针对本项目调优过的 prompt 模板。

快速开始

1. 克隆仓库并同步依赖：

git clone https://github.com/<yourname>/api-contract-agent.git
cd api-contract-agent
uv sync --dev

2. 准备配置文件：

• 项目统一从仓库根目录的 config.json 读取配置。
• 仓库提供了 config.example.json 作为模板，当前本地开发默认使用 config.json。
• 关键字段：
  • service.repo_path：目标代码仓库路径（扫描入口）
  • service.service_url：目标服务地址
  • service.auth_token：harness 使用的鉴权 token
  • service.startup.approved_command：可选，手工覆盖启动命令
  • service.startup.auto_start：是否自动在沙盒中拉起服务
  • service.startup.approval_required：若为 true，需要手动审批命令后才会执行
  • llm.base_url / llm.api_key / llm.model：真实 LLM 配置
  • llm.mode：auto（自动检测）、responses（使用 /v1/responses 接口）、chat-completions（使用 /v1/chat/completions 接口）

3. 启动示例服务（可选）：

默认流程会在自测时自动拉起服务。仅在你想手工调试时才需要单独启动。

4. 启动 orchestrator 后端：

uv run uvicorn app.main:app --reload --port 8000

此时便可访问 localhost:8000 查看 demo 页面。

5. 生成初始规范：

uv run python scripts/gen_spec.py

6. 运行自测并完善规范：

uv run python scripts/run_harness.py

生成的 OpenAPI 和 llms.txt 会输出到 output/ 目录，并可通过 Web 界面查看。

如果你想临时覆盖配置文件中的值，也可以传 CLI 参数：

uv run python scripts/gen_spec.py --repo-path ./demo_service
uv run python scripts/run_harness.py --repo-path ./demo_service --service-url http://localhost:8001 --auth-token your-token

当前已实现接口

• POST /scan
  • 输入：可直接传 {"repo_path":"./demo_service"}，也可以传空对象并使用 config.json
  • 输出：聚合后的初始 OpenAPI 规范 + 启动命令建议
• POST /self_test
  • 输入：可传 {"repo_path":"./demo_service","service_url":"http://localhost:8001"}，也可以只覆盖需要覆盖的字段，其余走 config.json
  • 行为：若目标服务不可达且 auto_start=true，自动在沙盒中使用检测命令拉起服务
  • 约束：当 approval_required=true 时，必须通过 start_command 或 service.startup.approved_command 完成审批
  • 输出：测试结果、推断出的约束、修正后的规范、运行时启动信息
• POST /self_test/stream
  • 输入：与 /self_test 相同
  • 输出：application/x-ndjson 流式事件，包含阶段进度、每轮状态码、LLM analysis 与最终结果
• POST /llms_txt
  • 输入：{"repo_path":"./demo_service"}、空对象加 config.json，或直接传入 spec
  • 输出：生成的 llms.txt 内容

技术栈

• 语言：Python 3.11+
• Web 框架：FastAPI / Uvicorn
• HTTP 客户端：httpx / requests
• OpenAPI 校验：openapi-spec-validator
• LLM 接入：通过 llms/client.py 统一封装（OpenAI / 火山引擎 / DeepSeek 等）

配置文件格式

{
  "service": {
    "repo_path": "./demo_service",
    "service_url": "http://127.0.0.1:8001",
    "auth_token": "demo-secret",
    "startup": {
      "approved_command": "uvicorn main:app --host 127.0.0.1 --port 8001",
      "approval_required": false,
      "auto_start": true,
      "readiness_path": "/openapi.json",
      "readiness_timeout_seconds": 20
    }
  },
  "llm": {
    "provider": "openai-compatible",
    "base_url": "https://api.openai.com/v1",
    "api_key": "replace-with-real-key",
    "model": "gpt-5.4",
    "mode": "auto"
  }
}

CI 失败自动分析（Failure Assistant）

仓库同时提供失败后分析工作流：

• 触发条件：CI 工作流结束且结论为 failure
• 工作内容：
  • 拉取失败 run 的 jobs/logs
  • 生成 failure signals 和 root-cause queries
  • 复用仓库扫描能力生成修复建议（patch draft + PR template）
  • 上传分析结果到 output/ci/ artifact
  • 若失败 run 关联 PR，则自动在 PR 下评论修复草稿

工作流文件：.github/workflows/ci-failure-assistant.yml 脚本入口：scripts/ci_failure_assistant.py

路线图 / ToDo

• 支持更多框架和语言，甚至不限语言
• 自动把规范反向生成 server stub / PR 模板
• 接入真实开发文档并补充文档，使用 RAG 搜索文档
• 一键重构过时接口（高危），或者为过时接口加入兼容层，强制符合 REST 规范
• 集成 CI，从 CI 中自动发现报错并处理