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

157 lines
7.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# AI Agent 全自动开发运行说明
`platform-ai` 的自动开发入口是 `POST /api/ai/features/auto-develop`。它只在本地环境执行草稿生成、本地落库、smoke 和自动修复;线上变更只输出人工部署包,不连接线上环境执行。
## 本地运行配置
`local` 和 `dev` profile 已开启:
```yaml
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 功能开发,避免占用当前任务目录:
```bash
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`:
```bash
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 通过稳定命令入口操作自动开发链路:
```bash
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 \
--max-repair-attempts 2 \
--output target/ai-runs/customer-level.json
```
本地门禁通过后,可以把最终变更包封装成功能包快照,并保存一个里程碑 revision:
```bash
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 仍可直接调用:
```bash
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": "客户等级维护",
"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 证据。
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 参与时设置:
```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=...
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 兼容清理。