feat: add AI agent auto-development pipeline
This commit is contained in:
104
docs/AI_AGENT_AUTO_DEVELOPMENT.md
Normal file
104
docs/AI_AGENT_AUTO_DEVELOPMENT.md
Normal file
@@ -0,0 +1,104 @@
|
||||
# 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
|
||||
```
|
||||
|
||||
## 请求示例
|
||||
|
||||
```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. 生成 `ENTITY`、`PAGE_SCHEMA`、`SERVICEFLOW`、`MENU`、`TEST` 草稿。
|
||||
3. 对草稿执行基础门禁,包括 amis schema、服务流 XML、实体字段和 smoke 计划。
|
||||
4. 生成待人审 `AiChangeSet`。
|
||||
5. 生成 release plan。
|
||||
6. 本地 apply:实体走本机 `/api/meta/entity`,页面/服务流写本地库;如果本地最小库缺少 `sys_menu`,菜单发布标记为 `SKIPPED`,不阻断本地 gate,部署包仍保留菜单 SQL 供线上人审。
|
||||
7. 本地 smoke:只允许 `localhost`、`127.0.0.1`、`::1` baseUrl;HTTP 状态必须匹配,且 JSON 响应体存在 `status` 时必须为 0。
|
||||
8. 若失败,自动生成 repair plan 并执行修复重试。
|
||||
9. 生成线上人工部署包,包含 manifest、SQL 草案、回滚 SQL 和本地执行证据。
|
||||
|
||||
返回体中的关键字段:
|
||||
|
||||
- `originalChangeSetId`: 首轮自动生成的变更包。
|
||||
- `changeSetId`: 最终用于部署包的变更包;如果修复生成了替代草稿,可能不同于 `originalChangeSetId`。
|
||||
- `repairExecutions`: 每轮自动修复证据。
|
||||
- `deploymentPackage.requiresHumanApproval`: 固定为 `true`,线上发布必须人工审批。
|
||||
|
||||
## 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 兼容清理。
|
||||
155
docs/AI_AGENT_REPAIR_CONTRACT.md
Normal file
155
docs/AI_AGENT_REPAIR_CONTRACT.md
Normal file
@@ -0,0 +1,155 @@
|
||||
# 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 <api-key>`。接口超时为 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 页面必填结构"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
100
docs/sql/SYS_AI_AGENT.sql
Normal file
100
docs/sql/SYS_AI_AGENT.sql
Normal file
@@ -0,0 +1,100 @@
|
||||
-- ============================================================================
|
||||
-- 生产建表脚本:SYS_AI_AGENT(AI Agent 运行态平台表)
|
||||
-- ----------------------------------------------------------------------------
|
||||
-- 归属:platform-ai(P5 Agent 开发底座)。
|
||||
-- 契约:/api/ai/tasks、/api/ai/tasks/{taskId}/drafts、change-sets、runs、audit。
|
||||
--
|
||||
-- 【Flyway 待办(P5)】
|
||||
-- 架构条款(docs/架构设计.md §「平台表管理」):SYS_* 平台表由 Flyway 管理。
|
||||
-- 本工程当前未引入 Flyway。本脚本即「生产建表脚本」,P5 引入 Flyway 时
|
||||
-- 原样改名为 V{n}__create_sys_ai_agent.sql 纳入 src/main/resources/db/migration 即可。
|
||||
-- 本地 / CI 自举副本见 platform-ai/src/main/resources/bootstrap/bootstrap-ai-agent.sql。
|
||||
--
|
||||
-- 边界:这些表只保存 AI 开发运行态和草稿。发布到 SYS_PAGE_SCHEMA / SYS_ENTITY /
|
||||
-- 服务流等生产元数据必须经过独立人审门禁,不能由 Agent 接口直接落生产。
|
||||
-- ============================================================================
|
||||
|
||||
CREATE TABLE IF NOT EXISTS sys_ai_task (
|
||||
task_id character varying(64) NOT NULL,
|
||||
objective text NOT NULL,
|
||||
status character varying(32) NOT NULL,
|
||||
plan_json jsonb NOT NULL,
|
||||
created_at bigint NOT NULL,
|
||||
updated_at bigint NOT NULL,
|
||||
CONSTRAINT pk_sys_ai_task PRIMARY KEY (task_id)
|
||||
);
|
||||
|
||||
CREATE TABLE IF NOT EXISTS sys_ai_draft (
|
||||
draft_id character varying(64) NOT NULL,
|
||||
task_id character varying(64) NOT NULL,
|
||||
artifact_type character varying(32) NOT NULL,
|
||||
target_id character varying(128) NOT NULL,
|
||||
payload_json jsonb NOT NULL,
|
||||
gates_json jsonb NOT NULL,
|
||||
metadata_json jsonb NOT NULL,
|
||||
created_at bigint NOT NULL,
|
||||
CONSTRAINT pk_sys_ai_draft PRIMARY KEY (draft_id)
|
||||
);
|
||||
|
||||
CREATE TABLE IF NOT EXISTS sys_ai_change_set (
|
||||
change_set_id character varying(64) NOT NULL,
|
||||
task_id character varying(64) NOT NULL,
|
||||
status character varying(32) NOT NULL,
|
||||
draft_ids_json jsonb NOT NULL,
|
||||
summary_json jsonb NOT NULL,
|
||||
created_at bigint NOT NULL,
|
||||
CONSTRAINT pk_sys_ai_change_set PRIMARY KEY (change_set_id)
|
||||
);
|
||||
|
||||
CREATE TABLE IF NOT EXISTS sys_ai_run (
|
||||
run_id character varying(64) NOT NULL,
|
||||
task_id character varying(64) NOT NULL,
|
||||
change_set_id character varying(64) NOT NULL,
|
||||
run_type character varying(32) NOT NULL,
|
||||
status character varying(32) NOT NULL,
|
||||
payload_json jsonb NOT NULL,
|
||||
created_at bigint NOT NULL,
|
||||
CONSTRAINT pk_sys_ai_run PRIMARY KEY (run_id)
|
||||
);
|
||||
|
||||
CREATE TABLE IF NOT EXISTS sys_ai_audit_log (
|
||||
audit_id character varying(64) NOT NULL,
|
||||
task_id character varying(64) NOT NULL,
|
||||
action character varying(96) NOT NULL,
|
||||
actor character varying(64) NOT NULL,
|
||||
details_json jsonb NOT NULL,
|
||||
created_at bigint NOT NULL,
|
||||
CONSTRAINT pk_sys_ai_audit_log PRIMARY KEY (audit_id)
|
||||
);
|
||||
|
||||
CREATE INDEX IF NOT EXISTS idx_sys_ai_draft_task ON sys_ai_draft (task_id, created_at);
|
||||
CREATE INDEX IF NOT EXISTS idx_sys_ai_change_set_task ON sys_ai_change_set (task_id, created_at);
|
||||
CREATE INDEX IF NOT EXISTS idx_sys_ai_run_task ON sys_ai_run (task_id, created_at);
|
||||
CREATE INDEX IF NOT EXISTS idx_sys_ai_run_change_set ON sys_ai_run (change_set_id, created_at);
|
||||
CREATE INDEX IF NOT EXISTS idx_sys_ai_audit_log_task ON sys_ai_audit_log (task_id, created_at);
|
||||
|
||||
COMMENT ON TABLE sys_ai_task IS 'AI Agent 开发任务。只描述需求、状态和计划,不代表已发布功能';
|
||||
COMMENT ON TABLE sys_ai_draft IS 'AI Agent 草稿产物。payload_json 保存实体/页面/服务流/代码等草稿';
|
||||
COMMENT ON TABLE sys_ai_change_set IS 'AI Agent 待人审变更包。通过门禁后供人工确认和发布';
|
||||
COMMENT ON TABLE sys_ai_run IS 'AI Agent 本地执行证据。保存 smoke/local-apply 的结构化结果';
|
||||
COMMENT ON TABLE sys_ai_audit_log IS 'AI Agent 操作审计日志';
|
||||
|
||||
COMMENT ON COLUMN sys_ai_task.task_id IS 'Agent 任务 id';
|
||||
COMMENT ON COLUMN sys_ai_task.objective IS '用户目标或需求描述';
|
||||
COMMENT ON COLUMN sys_ai_task.status IS '任务状态,例如 DRAFTING / READY_FOR_REVIEW';
|
||||
COMMENT ON COLUMN sys_ai_task.plan_json IS 'Agent 计划步骤 JSON';
|
||||
COMMENT ON COLUMN sys_ai_task.created_at IS '创建时间 epoch 毫秒';
|
||||
COMMENT ON COLUMN sys_ai_task.updated_at IS '更新时间 epoch 毫秒';
|
||||
|
||||
COMMENT ON COLUMN sys_ai_draft.artifact_type IS '草稿类型:ENTITY / PAGE_SCHEMA / SERVICEFLOW / MENU / CODE / TEST';
|
||||
COMMENT ON COLUMN sys_ai_draft.target_id IS '目标标识,例如实体编码、templateId、服务流 id 或文件路径';
|
||||
COMMENT ON COLUMN sys_ai_draft.payload_json IS '草稿内容 JSON';
|
||||
COMMENT ON COLUMN sys_ai_draft.gates_json IS '草稿门禁结果 JSON';
|
||||
COMMENT ON COLUMN sys_ai_draft.metadata_json IS '来源、上下文、生成参数等附加信息';
|
||||
|
||||
COMMENT ON COLUMN sys_ai_change_set.draft_ids_json IS '纳入变更包的 draft_id 列表';
|
||||
COMMENT ON COLUMN sys_ai_change_set.summary_json IS '变更摘要、风险、人审要求和回滚提示';
|
||||
COMMENT ON COLUMN sys_ai_run.run_type IS '执行类型:SMOKE / LOCAL_APPLY / AUTO_DEVELOP / REPAIR_PLAN / REPAIR_EXECUTION';
|
||||
COMMENT ON COLUMN sys_ai_run.status IS '执行状态:PASSED / FAILED / APPLY_FAILED / SMOKE_FAILED 等';
|
||||
COMMENT ON COLUMN sys_ai_run.payload_json IS '执行结果 JSON,包含逐条 smoke 或 apply step 详情';
|
||||
COMMENT ON COLUMN sys_ai_audit_log.details_json IS '操作详情 JSON';
|
||||
@@ -18,7 +18,7 @@ eip4-platform(Maven 多模块单体)
|
||||
├── platform-auth P2:组织/权限/数据权限真实现(替换 PoC 桩)
|
||||
├── platform-flow-gateway Flowable REST 客户端、待办聚合、3 个 handler bean
|
||||
├── platform-converter 模板转换器 + S3 脚本改写器(可独立 CLI 跑批)
|
||||
├── platform-ai MCP Server、schema 双闸校验
|
||||
├── platform-ai AI Agent 开发底座、schema 双闸校验、自动修复、本地门禁和人工部署包
|
||||
├── platform-parity C1 逐行对拍框架:录制/重放/逐行 diff(P1 一级交付物,可独立 CLI 跑批)
|
||||
└── platform-app Spring Boot 启动器,组装上述模块
|
||||
```
|
||||
@@ -118,4 +118,4 @@ eip4-platform(Maven 多模块单体)
|
||||
|
||||
---
|
||||
|
||||
**本文档维护**:随 P1 包结构落地校正;任何选型变更(尤其渲染层切换)回写第二、七节。
|
||||
**本文档维护**:随 P1 包结构落地校正;任何选型变更(尤其渲染层切换)回写第二、七节。
|
||||
|
||||
Reference in New Issue
Block a user