4.1 KiB
4.1 KiB
AI Agent Repair LLM 接入契约
本文档定义 platform-ai 调用外部 LLM 修复服务的最小契约。该服务只负责根据失败证据生成安全草稿补丁,不直接写库、不发布线上、不访问生产环境。
启用配置
默认不启用外部 LLM 修复。需要显式配置:
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:
{
"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 字段:
{
"draftPatches": [
{
"artifactType": "ENTITY",
"targetId": "CUSTOMER",
"payload": {
"publishTarget": "/api/meta/entity",
"tableName": "SYS_CUSTOMER",
"entityName": "Customer",
"fields": []
},
"metadata": {
"source": "llm-repair",
"reason": "补齐实体发布目标"
}
}
]
}
artifactType 只允许:
ENTITYPAGE_SCHEMASERVICEFLOWMENUTESTCODE
平台当前主要自动修复 ENTITY、PAGE_SCHEMA、SERVICEFLOW、MENU、TEST。CODE 补丁即使返回,也仍然必须经过后续门禁、人审和部署包流程。
安全边界
外部 LLM 服务不得执行以下操作:
- 连接或修改线上数据库。
- 触发线上发布、重启、脚本执行或远程 shell。
- 绕过平台的草稿、变更包、本地 apply、smoke、部署包和人工审批流程。
- 返回除
draftPatches之外需要平台立即执行的命令。
平台接收补丁后的流程是:
- 将补丁写成新的
AiDraft,保留metadata.source和原因。 - 基于同一
artifactType + targetId取最新草稿重新生成 change set。 - 执行本地 apply 和 smoke。
- 生成线上人工部署包。
- 线上部署仍由人工审批和发布系统执行。
示例:修复 TEST 契约
请求中的 repairPlan.actions 指出 smoke 期望状态码与实际接口不一致时,外部服务可以返回:
{
"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 时,外部服务可以返回:
{
"draftPatches": [
{
"artifactType": "PAGE_SCHEMA",
"targetId": "customer-page",
"payload": {
"type": "page",
"title": "客户管理",
"body": []
},
"metadata": {
"source": "llm-repair",
"reason": "补齐 amis 页面必填结构"
}
}
]
}