156 lines
4.1 KiB
Markdown
156 lines
4.1 KiB
Markdown
# 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 页面必填结构"
|
||
}
|
||
}
|
||
]
|
||
}
|
||
```
|