内容
<p align="center">
<img src="apilabs_ai_supercontracts.png"
alt="apilabs.ai SuperContracts"
width="400">
</p>
<h1 align="center">超级合约</h1>
<p align="center">
API、MCP 和 AI 代理的执行合约和安全防护。
</p>
开放合约规范定义了软件系统如何被调用、测试、安全、批准和执行 — 以人类、工具和 AI 代理可以理解的格式。
传统 API 规范描述端点。**开放合约规范描述执行、策略和安全性。**
---
## 为什么
API 操作是分散的。
* **OpenAPI** 文档描述端点。
* **Postman** 测试请求。
* **CI** 验证更改。
* **工作流工具** 自动执行操作。
* **安全工具** 强制执行策略。
* **Jira、Slack 和电子邮件** 处理审批。
* **日志** 捕获审计。
结果是漂移、重复工作、治理薄弱和所有权不明确。
对于开发者来说，这是不高效的。
随着 AI 代理和 MCP 工具执行实际操作，它变成了安全风险。
代理可以触及资金、数据、代码、基础设施和客户操作。没有防护措施，它们可以触发未经授权的访问、破坏性更改、权限滥用、提示注入攻击或未经批准的生产操作。
**开放合约规范** 将文档、测试、工作流、审批、安全防护和审计轨迹带入一个可执行的合约中。
---
## 内容
* API 和 MCP 工具
* 身份验证和环境
* 工作流和测试
* 审批和安全防护
* AI 代理权限
* 运行证据
---
# 超级合约核心功能与代码示例
## Cursor™ MCP 集成与运行时证据
通过 MCP 将超级合约直接集成到 Cursor™ 中，使开发者和 AI 代理能够从 IDE 发现、执行、测试和治理 API 和工作流。
每个操作都会捕获请求、响应、策略决策、审批、执行者、时间戳和执行轨迹，以便审计、合规、监控和调试。
## Cursor
通过 MCP 将超级合约连接到 Cursor，这样您的 AI 代理可以发现合约、执行工作流、检查测试历史并接收自动生成的 AI 环境 — 无需离开 IDE。
每个工具调用都通过合约中定义的相同安全防护、审批和证据捕获。
### 配置超级合约 MCP in Cursor
1. 打开 **Cursor 设置 → 功能 → MCP** 并点击 **添加 MCP 服务器**，或添加项目级 `.cursor/mcp.json` 文件。
2. 从 [apilabs-mcp-server](https://github.com/apilabs-ai/apilabs-mcp-server) 下载超级合约 MCP 服务器，或在启动本地 MCP 服务器后粘贴以下配置：
```json
{
"mcpServers": {
"supercontracts": {
"url": "http://127.0.0.1:8080/mcp"
}
}
}
```
3. 启动超级合约 MCP 服务器并使用您的 apilabs.ai 工作区进行身份验证。Cursor 中的绿色指示器确认工具已发现。
### 已发布的 MCP 工具
| 工具 | 目的 |
| --- | --- |
| `list_contracts` | 列出 API 合同模型中保存的合约 YAML 文件，包括嵌套的文件夹 |
| `get_contract` | 通过 `connection_id` 加载保存的合约 YAML 内容 |
| `save_contract` | 在 API 合同模型中创建或更新合约 YAML 文件 |
| `run_contract` | 执行合约内联 — 返回 `run_id`、响应和可选的 AI 环境 |
| `list_test_runs` | 浏览最近的合约测试运行历史，带有存档和状态过滤器 |
| `get_test_run` | 获取完整的运行详细信息，包括断言、响应正文和 AI 环境 |
| `resolve_resource` | 将 apilabs ARN（文件、机密或方法）解析为元数据，而不暴露机密 |
**典型流程：** `list_contracts` → `get_contract` → `run_contract` → `get_test_run`
示例：
待补充
当 `generate_ai_context` 在 `run_contract` 上启用时，超级合约会生成一个 `ai_context.md` 工件，总结执行结果、策略决策、失败的断言和补救提示 — 为 Cursor 代理准备好在下一轮推理。
### 工作演示
观看端到端 Cursor MCP 演示：从 IDE 测试工作流 API，执行合约，并将自动生成的 AI 环境反馈给代理。
**[使用 AI 代理合约和自动生成的 AI 环境测试工作流 API](https://youtu.be/GAt-V7jL4e0?si=lcWUECktH2ZkjOOw)**
在演示中，Cursor：
1. 调用 `run_contract` 并带有超级合约 YAML 工作流。
2. 捕获运行工件 — `run.json`、`response.json` 和 `ai_context.md`。
3. 使用生成的 AI 环境来解释失败、建议修复并继续调试 — 所有操作都在同一个聊天中。
### 示例 1
要求 Cursor™：
```text
退款 Stripe 支付订单 #10482。
```
超级合约执行工作流，请求必要时审批，执行退款，并记录完整的审计轨迹。
### 示例 2
要求 Cursor™：
```text
为功能标志创建新的 Supabase 表。
```
超级合约验证 SQL，执行迁移，并记录已执行的 SQL、用户、时间戳和结果。
---
## AI 代理防护措施
定义 AI 代理允许访问的系统、工具、数据和操作。
这些防护措施将自主代理限制在批准的范围内，防止对企业系统进行未经授权的更改。
### 示例 1
允许 AI 支持代理读取 Stripe 客户和订阅信息，但禁止其发出退款。
### 示例 2
允许 AI 编码代理创建 GitHub 分支和拉取请求，但禁止其将更改部署到生产环境。
---
## MCP 防护措施
控制 AI 模型如何与模型上下文协议工具交互。
超级合约作为一个策略强制执行层，阻止未经授权、不安全或未经验证的工具调用到达连接的系统。
### 示例 1
允许 GitHub MCP 服务器创建分支和拉取请求，但阻止直接推送到 `main` 分支。
### 示例 2
允许 Supabase MCP 服务器运行 `SELECT` 查询，同时阻止 `DROP TABLE` 和无限制的 `DELETE` 操作。
---
## 生产操作审批
为破坏性、敏感或高影响力的生产操作添加人为审批。
数据库迁移、大批量删除、退款或基础设施更改等操作在没有明确授权的情况下无法继续。
### 示例 1
要求财务审批后再执行超过 `$500` 的 Stripe 退款。
### 示例 2
要求数据库管理员审批后再对生产 Supabase 数据库应用迁移。
---
## Slack™ 机器人防护措施
控制 Slack™ 机器人和 AI 代理可以读取、发布、审批和执行的操作。
超级合约可以限制敏感频道、阻止未经授权的命令、要求高风险操作审批、验证请求用户，并保留每个机器人触发的操作证据。
### 示例 1
授权财务用户提交：
```text
/refund ORD-10482
```
超级合约验证用户并启动 Stripe 退款工作流。
### 示例 2
用户提交：
```text
/deploy production
```
超级合约要求发布经理审批后再触发 GitHub Actions 部署。
---
## API 工作流测试与执行
在单个可执行合约中集中 API 行为、依赖关系、条件、测试和工作流步骤。
这消除了分散的脚本，并帮助多步骤工作流可预测、一致地运行。
### 示例 1
测试客户 onboarding 工作流：
1. 在 Supabase 中创建用户。
2. 在 Stripe 中创建订阅。
3. 通过 SendGrid 发送欢迎电子邮件。
4. 验证每个 API 的响应。
### 示例 2
执行订单履行工作流：
1. 检索订单。
2. 验证库存。
3. 通过 Stripe 向客户收费。
4. 通过 Shippo 创建发货。
5. 更新订单状态。
代码示例（待补充）
---
## 状态
开放合约规范处于早期公开开发阶段。
目标是为安全的 API、MCP 和 AI 代理执行创建中立、开放的格式。
---
## 许可证
Apache-2.0
