Files
eip4-platform/docs/AI_AGENT_REPAIR_CONTRACT.md

4.1 KiB
Raw Blame History

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 只允许:

  • 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 期望状态码与实际接口不一致时,外部服务可以返回:

{
  "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 页面必填结构"
      }
    }
  ]
}