feat: add AI agent auto-development pipeline
This commit is contained in:
155
docs/AI_AGENT_REPAIR_CONTRACT.md
Normal file
155
docs/AI_AGENT_REPAIR_CONTRACT.md
Normal file
@@ -0,0 +1,155 @@
|
||||
# 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 页面必填结构"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user