Files
eip4-platform/docs/AI_AGENT_AUTO_DEVELOPMENT.md
2026-06-17 13:03:38 +08:00

8.0 KiB
Raw Blame History

AI Agent 全自动开发运行说明

platform-ai 的自动开发入口是 POST /api/ai/features/auto-develop。它只在本地环境执行草稿生成、本地落库、smoke 和自动修复;线上变更只输出人工部署包,不连接线上环境执行。

本地运行配置

local 和 dev profile 已开启:

spring:
  sql:
    init:
      mode: always
      schema-locations: classpath:bootstrap/bootstrap-ai-agent.sql

eip4:
  ai:
    store: jdbc

因此本地启动时会幂等创建 sys_ai_task、sys_ai_draft、sys_ai_change_set、sys_ai_run、sys_ai_audit_log,并用 JDBC 持久化开发证据。默认 profile 不强制写远端验证库,避免误把开发证据写到共享环境。

建议使用独立 worktree 做 Agent 功能开发,避免占用当前任务目录:

git worktree add ../eip4-platform-ai-agent -b ai/agent-dev
cd ../eip4-platform-ai-agent

运行态验证要先构建依赖模块并启动重新打包后的 jar,避免 spring-boot:run -pl platform-app 读取本地 Maven 仓库里的旧 platform-ai:

JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-app -am install -DskipTests
/opt/homebrew/opt/openjdk@21/bin/java -jar platform-app/target/platform-app-0.1.0-SNAPSHOT.jar --spring.profiles.active=local

请求示例

推荐优先使用 platform-cli,让 Agent 通过稳定命令入口操作自动开发链路:

mvn -pl platform-cli package
java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar ai auto-develop \
  --base-url http://localhost:8093 \
  --objective "新增客户等级维护功能" \
  --feature-name "客户等级维护" \
  --table-name EIP4AI_CUSTOMER_LEVEL \
  --entity-name "客户等级" \
  --template-id eip4ai-customer-level \
  --menu-name "客户等级维护" \
  --field NAME:名称:string:100:true \
  --field CODE:编码:string:64:true \
  --field ENABLED:启用:boolean::false \
  --page-recipe maintenance-crud-v1 \
  --max-repair-attempts 2 \
  --output target/ai-runs/customer-level.json

树形维护页使用 tree-crud-v1。如果字段列表没有显式提供 PARENTID,生成器会自动补一个父级字段, 页面使用 /api/entity/{table}/tree?parentKey=PARENTID&idKey={table}_ID&perPage=2000 作为树数据接口,并把 PARENTID 从树列表列中隐藏:

java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar ai auto-develop \
  --base-url http://localhost:8093 \
  --objective "新增组织分类树形维护功能" \
  --feature-name "组织分类维护" \
  --table-name EIP4AI_ORG_CATEGORY \
  --entity-name "组织分类" \
  --template-id eip4ai-org-category \
  --menu-name "组织分类维护" \
  --field NAME:名称:string:100:true \
  --field CODE:编码:string:64:true \
  --page-recipe tree-crud-v1 \
  --max-repair-attempts 2 \
  --output target/ai-runs/org-category-tree.json

本地门禁通过后,可以把最终变更包封装成功能包快照,并保存一个里程碑 revision:

java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar ai feature-package \
  --base-url http://localhost:8093 \
  --task-id ait-xxx \
  --change-set-id aics-xxx \
  --output target/ai-runs/customer-level-package.json

java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar ai revision \
  --base-url http://localhost:8093 \
  --task-id ait-xxx \
  --package-id aipkg-xxx \
  --note "本地门禁通过,待人工部署" \
  --output target/ai-runs/customer-level-revision.json

底层 REST API 仍可直接调用:

curl -X POST http://localhost:8093/api/ai/features/auto-develop \
  -H 'Content-Type: application/json' \
  -d '{
    "baseUrl": "http://localhost:8093",
    "generateDeploymentPackage": true,
    "maxRepairAttempts": 2,
    "feature": {
      "objective": "新增客户等级维护功能",
      "featureName": "客户等级维护",
      "tableName": "EIP4AI_CUSTOMER_LEVEL",
      "entityName": "客户等级",
      "templateId": "eip4ai-customer-level",
      "menuName": "客户等级维护",
      "pageRecipe": "maintenance-crud-v1",
      "fields": [
        {"column": "NAME", "label": "名称", "type": "string", "length": 100, "required": true},
        {"column": "CODE", "label": "编码", "type": "string", "length": 64, "required": true},
        {"column": "ENABLED", "label": "启用", "type": "boolean", "required": false}
      ]
    }
  }'

maxRepairAttempts 可省略,默认 2;设为 0 时只跑首轮开发和本地门禁,失败后由调用方手动调用 repair 接口。

自动链路

  1. 创建 AiTask。
  2. 读取 /api/ai/page-recipes 中的 EIP4 页面 recipe,确认当前页面类型的 UI/UE 约束。
  3. 生成 ENTITY、PAGE_SCHEMA、SERVICEFLOW、MENU、TEST 草稿。PAGE_SCHEMA 先生成 EIP4 PageBlueprint,再由平台编译器输出 amis schema;草稿 metadata 保留 blueprint 证据。 未指定 feature.pageRecipe 时默认使用 maintenance-crud-v1;树形维护页应指定 tree-crud-v1。
  4. 对草稿执行基础门禁,包括 page-recipe、amis schema、typed page schema、服务流 XML、实体字段和 smoke 计划。
  5. 生成待人审 AiChangeSet。
  6. 生成 release plan。
  7. 本地 apply:实体走本机 /api/meta/entity,页面/服务流写本地库;如果本地最小库缺少 sys_menu,菜单发布标记为 SKIPPED,不阻断本地 gate,部署包仍保留菜单 SQL 供线上人审。
  8. 本地 smoke:只允许 localhost、127.0.0.1、::1 baseUrl;HTTP 状态必须匹配,且 JSON 响应体存在 status 时必须为 0。
  9. 若失败,自动生成 repair plan 并执行修复重试。
  10. 生成线上人工部署包,包含 manifest、SQL 草案、回滚 SQL 和本地执行证据。
  11. 可选:生成功能包快照并保存 revision,用于后续导出、差异比较和回滚扩展。

返回体中的关键字段:

  • originalChangeSetId: 首轮自动生成的变更包。
  • changeSetId: 最终用于部署包的变更包;如果修复生成了替代草稿,可能不同于 originalChangeSetId。
  • repairExecutions: 每轮自动修复证据。
  • deploymentPackage.requiresHumanApproval: 固定为 true,线上发布必须人工审批。

功能包和 revision

P2 第一版新增功能包快照和里程碑版本:

  • POST /api/ai/tasks/{taskId}/change-sets/{changeSetId}/feature-package
  • GET /api/ai/tasks/{taskId}/feature-packages
  • POST /api/ai/tasks/{taskId}/feature-packages/{packageId}/revisions
  • GET /api/ai/tasks/{taskId}/revisions

功能包封装部署包、manifest、本地 evidence、SQL 草案和回滚 SQL。revision 当前保存功能包 JSON 快照,作为后续差异比较和回滚执行的基础。生产执行仍不自动化,必须人审。

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=...
EIP4_AI_LLM_REPAIR_MODEL=...

外部服务契约见 docs/AI_AGENT_REPAIR_CONTRACT.md。LLM 只能返回草稿补丁,不能要求平台执行生产命令。

线上边界

可靠路径是:本地 auto-develop 通过后,人工检查部署包,再由现有发布流程上线。功能上线后如果发现 bug,Agent 可以基于线上错误日志、导出的 run evidence 或人工复现结果生成新的本地任务并修复,但仍应先在本地验证,再输出人工部署包。

当前验证结论与遗留项

已在 local profile 验证完整自动开发链路:实体创建、默认服务流发布、页面 schema 发布、实体列表、默认搜索流和新增数据 smoke 均通过,最终状态为 READY_FOR_HUMAN_REVIEW。local 最小库没有菜单表,因此菜单 apply 为 SKIPPED,这是预期的本地边界。

遗留项是全局 metadata 辅助读路径仍有部分 SQL 写死 eip3. schema;在 local/eip4m0 下会出现非阻断 warning。AI 主链路已规避/修正必要路径,后续如果要让所有后台辅助解析在 local 最小库完全无噪声,需要单独做一次 schema 兼容清理。