Files
eip4-platform/docs/AI_AGENT_REPAIR_CONTRACT.md

156 lines
4.1 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# AI Agent Repair LLM 接入契约
本文档定义 `platform-ai` 调用外部 LLM 修复服务的最小契约。该服务只负责根据失败证据生成安全草稿补丁,不直接写库、不发布线上、不访问生产环境。
## 启用配置
默认不启用外部 LLM 修复。需要显式配置:
```properties
eip4.ai.llm.repair.enabled=true
eip4.ai.llm.repair.endpoint=http://127.0.0.1:18081/ai-agent/repair
eip4.ai.llm.repair.api-key=${AI_REPAIR_API_KEY}
eip4.ai.llm.repair.model=${AI_REPAIR_MODEL}
```
`api-key` 为空时不发送 `Authorization` 头;非空时使用 `Authorization: Bearer <api-key>`。接口超时为 60 秒。服务返回非 2xx、响应格式非法或调用异常时,平台会忽略外部结果并回退到内置确定性修复规则。
## 请求格式
`HttpAiLlmRepairClient` 向配置的 endpoint 发送 `POST application/json`:
```json
{
"model": "repair-model-name",
"taskId": "ait-1",
"changeSetId": "aics-1",
"repairPlan": {
"taskId": "ait-1",
"changeSetId": "aics-1",
"sourceRunId": "run-1",
"status": "READY",
"generatedAt": 1710000000000,
"actions": [],
"messages": []
},
"drafts": [],
"contract": {
"responseField": "draftPatches",
"patchShape": "artifactType,targetId,payload,metadata",
"rule": "Return only safe draft patches; do not execute production changes"
}
}
```
字段说明:
- `repairPlan`: 平台根据最近失败的 `AUTO_DEVELOP` / `LOCAL_APPLY` / `SMOKE` 证据生成的修复计划。
- `drafts`: 当前任务的草稿快照,LLM 只能基于这些草稿生成替代草稿。
- `contract`: 平台要求的响应约束,外部服务必须遵守。
## 响应格式
外部服务必须返回 JSON 对象,且补丁数组放在 `draftPatches` 字段:
```json
{
"draftPatches": [
{
"artifactType": "ENTITY",
"targetId": "CUSTOMER",
"payload": {
"publishTarget": "/api/meta/entity",
"tableName": "SYS_CUSTOMER",
"entityName": "Customer",
"fields": []
},
"metadata": {
"source": "llm-repair",
"reason": "补齐实体发布目标"
}
}
]
}
```
`artifactType` 只允许:
- `ENTITY`
- `PAGE_SCHEMA`
- `SERVICEFLOW`
- `MENU`
- `TEST`
- `CODE`
平台当前主要自动修复 `ENTITY`、`PAGE_SCHEMA`、`SERVICEFLOW`、`MENU`、`TEST`。`CODE` 补丁即使返回,也仍然必须经过后续门禁、人审和部署包流程。
## 安全边界
外部 LLM 服务不得执行以下操作:
- 连接或修改线上数据库。
- 触发线上发布、重启、脚本执行或远程 shell。
- 绕过平台的草稿、变更包、本地 apply、smoke、部署包和人工审批流程。
- 返回除 `draftPatches` 之外需要平台立即执行的命令。
平台接收补丁后的流程是:
1. 将补丁写成新的 `AiDraft`,保留 `metadata.source` 和原因。
2. 基于同一 `artifactType + targetId` 取最新草稿重新生成 change set。
3. 执行本地 apply 和 smoke。
4. 生成线上人工部署包。
5. 线上部署仍由人工审批和发布系统执行。
## 示例:修复 TEST 契约
请求中的 `repairPlan.actions` 指出 smoke 期望状态码与实际接口不一致时,外部服务可以返回:
```json
{
"draftPatches": [
{
"artifactType": "TEST",
"targetId": "customer-smoke",
"payload": {
"smokes": [
{
"name": "打开客户列表",
"method": "GET",
"path": "/api/customer/list",
"expectedStatus": 200
}
]
},
"metadata": {
"source": "llm-repair",
"reason": "同步 smoke 期望状态码"
}
}
]
}
```
## 示例:修复 PAGE_SCHEMA
页面 schema 缺少 `type`、`title` 或 `body` 时,外部服务可以返回:
```json
{
"draftPatches": [
{
"artifactType": "PAGE_SCHEMA",
"targetId": "customer-page",
"payload": {
"type": "page",
"title": "客户管理",
"body": []
},
"metadata": {
"source": "llm-repair",
"reason": "补齐 amis 页面必填结构"
}
}
]
}
```