W1 引入 db/migration/V1-V3 后,平台表 DDL 在迁移与各模块 bootstrap-*.sql 重复
(评审揪出的"易漂移")。本次收敛,db/migration 成唯一真相:
- 删 3 份重复 bootstrap:bootstrap-page-schema(=V1)/bootstrap-datastatus(=V2)/
bootstrap-ai-agent(=V3)。三者无运行态 classpath 消费者(已全仓核实)。
- AiAgentDdlTest(platform-ai,原读 bootstrap-ai-agent.sql)删除,等价覆盖迁入
platform-app 新增 PlatformMigrationDdlGuardTest:① 守 V3 声明全部 AI 平台表/索引;
② 守 SchemaImportCli.CREATE_DDL ≡ V1(独立 CLI 兜底 DDL 防漂移)。
- SchemaImportCli.CREATE_DDL 由包私有改 public 供上述 guard 比对;两处过时注释改指 V1。
- ci.sh 平台表预灌改指 db/migration/V1(注:app 启动 Flyway 已幂等建表,此预灌仅冗余兜底)。
- docs 对齐:AI_AGENT_AUTO_DEVELOPMENT(spring.sql.init→Flyway)、docs/sql/SYS_PAGE_SCHEMA
/SYS_AI_AGENT 头注释(待办→已落地)、A10 design 残留收敛标完成、deploy/README 残留项标完成。
边界:platform-parity 的 bootstrap-{sys,privilege,auth,xservice,multidim,flow}.sql 是
eip3 schema 对拍测试 fixture,非平台表副本,原样保留。
验证:全 reactor mvn clean install 绿;PlatformMigrationDdlGuardTest 2/2;独立 code-reviewer
评审 GO(零 CRITICAL/HIGH/MEDIUM,含 guard substring 逻辑对真实 V1 仿真核实)。
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
179 lines
9.2 KiB
Markdown
179 lines
9.2 KiB
Markdown
> 📌 **现状以总览为准(2026-06-21)**:正文若称「只覆盖最简单 CRUD recipe」已过时——现已有 maintenance-crud / tree-crud / master-detail-v1 多类 recipe。**对外口径红线仍有效**(AI 辅助 + 人审、非全自动开发)。进度见 [总览-2026-06-21](项目进度与路线-总览-2026-06-21.md) B2。
|
||
|
||
# AI Agent 辅助开发运行说明(生成草稿 + 本地验证 + 人工复核发布)
|
||
|
||
> **能力边界(对外口径,红线)**:本能力是「**AI 辅助生成草稿 + 人工复核发布**」,**不是** AI 全自动开发。当前只覆盖最简单的 CRUD recipe,存量复杂场景未取得数据;按《EIP3架构决策会纪要》红线,**严禁在报价/合同中承诺「AI 全自动开发 / 人力大幅下降」**。线上变更一律输出人工部署包、由人工复核后发布。
|
||
|
||
`platform-ai` 的辅助开发入口是 `POST /api/ai/features/auto-develop`。它只在本地环境执行草稿生成、本地落库、smoke 和自动修复;线上变更只输出人工部署包,不连接线上环境执行,须人工复核后发布。
|
||
|
||
## 本地运行配置
|
||
|
||
`local` 和 `dev` profile 已开启 JDBC 持久化:
|
||
|
||
```yaml
|
||
eip4:
|
||
ai:
|
||
store: jdbc
|
||
```
|
||
|
||
平台表(`sys_ai_task`、`sys_ai_draft`、`sys_ai_change_set`、`sys_ai_run`、`sys_ai_feature_package`、`sys_ai_revision`、`sys_ai_audit_log`)由 **W1 Flyway 在启动时幂等建表**——单一真相 `platform-app/src/main/resources/db/migration/V3__sys_ai_agent.sql`(A10 W1 收敛后取代原 `spring.sql.init` + 已删的 `bootstrap-ai-agent.sql`)。因此本地启动即用 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 \
|
||
--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` 从树列表列中隐藏:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```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": "客户等级维护",
|
||
"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 计划和 render plan。
|
||
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。
|
||
`TEST` 草稿同时包含 `renderTests`,给 Playwright 渲染验收提供 recipe、schemaUrl、previewUrl、预期组件、CRUD 名、数据 API、列、动作和关键文本。
|
||
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 兼容清理。
|