# 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 `。接口超时为 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 页面必填结构" } } ] } ```