merge ai agent module
This commit is contained in:
180
docs/AI_AGENT_AUTO_DEVELOPMENT.md
Normal file
180
docs/AI_AGENT_AUTO_DEVELOPMENT.md
Normal file
@@ -0,0 +1,180 @@
|
||||
# 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 \
|
||||
--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 兼容清理。
|
||||
215
docs/AI_AGENT_Nocobase_ADOPTION_PLAN.md
Normal file
215
docs/AI_AGENT_Nocobase_ADOPTION_PLAN.md
Normal file
@@ -0,0 +1,215 @@
|
||||
# AI Agent 借鉴 NocoBase 的落地路线
|
||||
|
||||
日期:2026-06-17
|
||||
|
||||
本文记录 EIP4 对 NocoBase AI + no-code 体系的可借鉴点和落地顺序。目标不是照搬 NocoBase 的 TypeScript 插件运行时,而是吸收它的工程边界:核心平台稳定、业务能力包化、AI 通过受控 CLI/API 操作、所有变更可审计、可验证、可回滚。
|
||||
|
||||
参考:
|
||||
|
||||
- NocoBase README: https://github.com/nocobase/nocobase
|
||||
- NocoBase Plugin Development: https://docs.nocobase.com/plugin-development/
|
||||
- NocoBase Project Structure: https://docs.nocobase.com/plugin-development/project-structure
|
||||
- NocoBase AI Builder: https://docs.nocobase.com/ai-builder/
|
||||
- NocoBase AI Plugin Development: https://docs.nocobase.com/ai-dev/
|
||||
- NocoBase CLI: https://docs.nocobase.com/api/cli/
|
||||
- NocoBase Skills: https://github.com/nocobase/skills
|
||||
|
||||
## 一、判断
|
||||
|
||||
NocoBase 最核心的启发是:AI 不应该默认直接写一堆业务代码,而是基于平台已有的可配置能力工作。AI 负责把自然语言需求转换为数据模型、页面配置、工作流、权限和发布包,人负责审核关键边界。
|
||||
|
||||
EIP4 当前已经有实体、页面 schema、服务流、菜单、smoke、部署包这些受控对象,因此更适合走“AI 操作元数据和发布包”的路线,而不是引入一套新的插件运行时。
|
||||
|
||||
## 二、可借鉴点
|
||||
|
||||
| NocoBase 做法 | EIP4 对应落点 | 处理方式 |
|
||||
|---|---|---|
|
||||
| AI 基于 no-code 基础设施工作 | `platform-ai` 生成实体/页面/服务流/菜单草稿 | 已落地,继续收敛到受控接口 |
|
||||
| CLI 作为 Agent 操作入口 | `platform-cli` | P1 建立,后续扩展环境/发布/回滚 |
|
||||
| Skills 让 Agent 理解平台 | `docs/skills/` | P1 建立规范骨架 |
|
||||
| 插件生命周期 | EIP4 `FeaturePackage` 生命周期 | P2 设计和持久化 |
|
||||
| 版本控制/里程碑回滚 | `SYS_AI_REVISION` / release evidence | P2-P3 |
|
||||
| FlowEngine 的可配置模型 | EIP4 typed page schema + component registry | P4 借鉴思想,不照搬实现 |
|
||||
|
||||
## 三、落地顺序
|
||||
|
||||
### P0:全自动开发主链路
|
||||
|
||||
状态:已完成。
|
||||
|
||||
完成内容:
|
||||
|
||||
- `POST /api/ai/features/auto-develop`
|
||||
- 草稿生成、变更包、release plan、本地 apply、smoke、自动修复、人工部署包
|
||||
- JDBC 审计和运行证据
|
||||
- 本地 jar 验证通过
|
||||
|
||||
验收标准:
|
||||
|
||||
- 本地可从一段功能需求生成可审核部署包
|
||||
- 线上执行仍停在人审边界
|
||||
|
||||
### P1:受控入口和 Agent 知识包
|
||||
|
||||
状态:第一版完成。
|
||||
|
||||
目标:
|
||||
|
||||
- 建立 `platform-cli`,让 Agent 通过命令调用 EIP4,而不是直接猜 HTTP 接口或直连数据库。
|
||||
- 建立 `docs/skills/`,把 EIP4 的环境管理、自动开发、发布管理写成 Agent 可复用的操作规程。
|
||||
|
||||
本阶段交付:
|
||||
|
||||
- `eip4 env status`
|
||||
- `eip4 ai auto-develop`
|
||||
- `docs/skills/eip4-env-manage.md`
|
||||
- `docs/skills/eip4-ai-feature-development.md`
|
||||
- `docs/skills/eip4-release-manage.md`
|
||||
|
||||
验收标准:
|
||||
|
||||
- CLI 单测覆盖命令解析和请求组装
|
||||
- README 和自动开发文档给出 CLI 用法
|
||||
- Agent 后续操作优先引用 Skills 和 CLI
|
||||
|
||||
### P2:FeaturePackage 和里程碑版本
|
||||
|
||||
状态:第一版完成。
|
||||
|
||||
目标:
|
||||
|
||||
- 把 AI 生成结果从松散的 draft/change-set 升级为稳定的 `FeaturePackage`。
|
||||
- 保存里程碑版本,支持本地回滚和线上部署前差异确认。
|
||||
|
||||
建议对象:
|
||||
|
||||
- `FeaturePackage`: manifest、entity、serviceflow、page schema、menu、acl、sql、rollback、smoke、evidence
|
||||
- `SYS_AI_FEATURE_PACKAGE`
|
||||
- `SYS_AI_REVISION`
|
||||
|
||||
验收标准:
|
||||
|
||||
- 一个功能包可以导出、导入、重复校验
|
||||
- 每个通过 smoke 的里程碑都能追溯输入、输出、测试证据和回滚脚本
|
||||
|
||||
第一版已落地:
|
||||
|
||||
- `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`
|
||||
- `eip4 ai feature-package`
|
||||
- `eip4 ai revision`
|
||||
- `sys_ai_feature_package`
|
||||
- `sys_ai_revision`
|
||||
|
||||
未完成项:
|
||||
|
||||
- 功能包导出/导入文件格式
|
||||
- revision 差异比较
|
||||
- 回滚执行编排
|
||||
|
||||
### P3:发布、回滚和环境治理
|
||||
|
||||
状态:进行中。
|
||||
|
||||
目标:
|
||||
|
||||
- CLI 扩展为环境管理和发布编排入口。
|
||||
- 建立本地、测试、生产环境的只读探测、部署前检查和人工批准边界。
|
||||
|
||||
建议命令:
|
||||
|
||||
- `eip4 env list/use/status`
|
||||
- `eip4 release package`
|
||||
- `eip4 release verify`
|
||||
- `eip4 release apply --require-approval`
|
||||
- `eip4 release rollback-plan --package-file FILE --output FILE`
|
||||
|
||||
验收标准:
|
||||
|
||||
- 默认不能连接线上执行写操作
|
||||
- 生产写操作必须有显式环境、审批标记和部署包
|
||||
- 发布失败能用结构化 evidence 回到本地修复链路
|
||||
|
||||
源码级修订:
|
||||
|
||||
- 参考 NocoBase `env/status.ts` 和 `env-guard.ts`,`platform-cli` 新增本地 env registry/current env。
|
||||
- 参考 NocoBase revision 创建前检查版本控制插件的思路,EIP4 后续 revision restore/diff 不能只依赖 JSON 快照,必须有发布系统能力检查。
|
||||
- 新增 `eip4 release verify --package-file FILE`,先做离线发布前门禁,阻断未替换占位符和缺失本地 evidence 的功能包。
|
||||
- 新增 `eip4 release export/import-preview`,形成 `.eip4pkg.json` 文件格式和 checksum 门禁;导入预览不写环境、不启用功能。
|
||||
- 新增 `eip4 release diff/rollback-plan`,先落地离线差异检查和计划型回滚;回滚计划不执行生产 SQL。
|
||||
- 详细源码对照见 `docs/AI_AGENT_Nocobase_SOURCE_REVIEW.md`。
|
||||
|
||||
### P4:Typed Page Schema 和组件注册表
|
||||
|
||||
状态:第一版完成。
|
||||
|
||||
目标:
|
||||
|
||||
- 借鉴 NocoBase FlowEngine 的“可配置模型”思想,把页面 block、field、action、linkage 抽象为 typed schema。
|
||||
- 让 AI 和人工设计器操作同一份 schema。
|
||||
|
||||
验收标准:
|
||||
|
||||
- 页面 schema 有版本、类型、组件能力表和校验器
|
||||
- AI 只能选择注册过的组件和动作
|
||||
- 设计器变更和 AI 变更能互相接续
|
||||
|
||||
第一版已落地:
|
||||
|
||||
- `GET /api/page/schema/components` 下发组件能力表。
|
||||
- `POST /api/page/schema/validate` 做 typed page schema 离线校验。
|
||||
- `PUT /api/page/schema/{templateId}/overlay` 保存 overlay 前强制校验组件和 actionType。
|
||||
- 当前仍是第一版 registry;后续要继续补 linkage/event/resource 和组件属性级 schema。
|
||||
|
||||
### P5:多 Agent 协作和 AI 员工
|
||||
|
||||
状态:第一版完成。
|
||||
|
||||
目标:
|
||||
|
||||
- 在平台内提供面向业务用户的 AI 助手能力,而不只是在开发侧使用 Agent。
|
||||
|
||||
建议方向:
|
||||
|
||||
- 数据分析 Agent
|
||||
- 表单配置 Agent
|
||||
- 服务流诊断 Agent
|
||||
- 权限风险审查 Agent
|
||||
- 发布审计 Agent
|
||||
|
||||
验收标准:
|
||||
|
||||
- 每个 Agent 有独立权限、审计、工具白名单
|
||||
- 业务侧操作和开发侧操作共用平台审计模型
|
||||
|
||||
第一版已落地:
|
||||
|
||||
- `GET /api/ai/tools` 下发工具注册表和 scope 要求。
|
||||
- `GET /api/ai/employees` 下发 AI employee 定义。
|
||||
- `POST /api/ai/tools/access-check` 统一检查 employee/tool/scope/targetEnv/productionWrite。
|
||||
- 生产写默认阻断;当前只开放本地开发、校验、smoke、功能包和发布准备工具。
|
||||
|
||||
## 四、不照搬的部分
|
||||
|
||||
NocoBase 是 TypeScript/Yarn workspace/插件包体系。EIP4 是 Java/Spring/Maven,并且必须兼容 EIP3 的实体、服务流和 XML 模板迁移路径。直接照搬 NocoBase 插件运行时会引入过高迁移成本。
|
||||
|
||||
EIP4 应该借鉴的是边界和流程:
|
||||
|
||||
1. 稳定核心能力。
|
||||
2. 业务功能包化。
|
||||
3. Agent 通过 CLI/API 操作。
|
||||
4. 人审控制生产变更。
|
||||
5. 每一步有 evidence、版本和回滚。
|
||||
|
||||
## 五、当前推进状态
|
||||
|
||||
| 阶段 | 状态 | 说明 |
|
||||
|---|---|---|
|
||||
| P0 | 完成 | `platform-ai` 主链路已提交 |
|
||||
| P1 | 第一版完成 | 已新增 `platform-cli` 和 Skills 规范骨架 |
|
||||
| P2 | 第一版完成 | 已新增功能包快照、里程碑 revision、CLI 命令和持久化表 |
|
||||
| P3 | 进行中 | 已完成 env registry/current env/cross-env guard/release verify/export/import-preview/diff/rollback-plan 第一版 |
|
||||
| P4 | 第一版完成 | 已新增组件 registry、typed schema validator、校验 API 和 overlay 保存前门禁 |
|
||||
| P5 | 第一版完成 | 已新增 AI tool registry、AI employee registry 和 access-check 门禁 |
|
||||
136
docs/AI_AGENT_Nocobase_SOURCE_REVIEW.md
Normal file
136
docs/AI_AGENT_Nocobase_SOURCE_REVIEW.md
Normal file
@@ -0,0 +1,136 @@
|
||||
# NocoBase 源码级对照和 EIP4 修订
|
||||
|
||||
日期:2026-06-17
|
||||
|
||||
本文件补充 `docs/AI_AGENT_Nocobase_ADOPTION_PLAN.md` 的源码级依据。结论:EIP4 不照搬 NocoBase 的 TypeScript 插件运行时,但 P3 之后必须参考它的 CLI/env/revision/skills/tool-registry 边界,否则容易只做出“HTTP wrapper”,做不到可持续的 Agent 开发体系。
|
||||
|
||||
## 一、已抽样源码
|
||||
|
||||
| 主题 | NocoBase 源码 | 对 EIP4 的影响 |
|
||||
|---|---|---|
|
||||
| CLI env status | `packages/core/cli/src/commands/env/status.ts` | CLI 要有 env registry/current env/status,不应只靠 `--base-url` |
|
||||
| 跨 env 确认 | `packages/core/cli/src/lib/env-guard.ts` | 显式选择非当前 env 时需要确认边界 |
|
||||
| API client | `packages/core/cli/src/lib/api-client.ts` | CLI 请求应带结构化 env/token/role/header,后续不能散落在命令里 |
|
||||
| runtime command registry | `packages/core/cli/src/generated/command-registry.ts` | 可根据运行时 API 生成命令,EIP4 后续可用 OpenAPI 生成安全 CLI |
|
||||
| generic resource command | `packages/core/cli/src/lib/resource-command.ts` | CRUD 类命令应统一处理 JSON body、分页、过滤、错误输出 |
|
||||
| plugin import/enable | `packages/core/cli/src/commands/plugin/import.ts`, `packages/core/cli/src/commands/plugin/enable.ts` | EIP4 的 FeaturePackage 后续也要区分导入、启用、发布和重启/刷新 |
|
||||
| revision create | `packages/core/cli/src/commands/revision/create.ts` | revision 不能只是保存 JSON,发布前要检查版本控制能力是否可用 |
|
||||
| skills install | `packages/core/cli/src/commands/skills/install.ts` | Skills 应由 CLI 安装/检查/更新,而不是只放仓库文档 |
|
||||
| AI plugin server | `packages/plugins/@nocobase/plugin-ai/src/server/plugin.ts` | AI 功能要注册 tools、skills、MCP、AI employees、ACL snippet |
|
||||
| FlowEngine | `packages/core/flow-engine/src/flowEngine.ts`, `packages/core/flow-engine/src/models/flowModel.tsx` | 页面 schema 需要演进到 typed model/action/event/resource registry |
|
||||
|
||||
## 二、对当前实现的校正
|
||||
|
||||
### P0-P2 是否做实
|
||||
|
||||
已做实:
|
||||
|
||||
- `platform-ai` 主链路有 Java 实现、JDBC/内存 store、DDL、Web API 和测试。
|
||||
- `platform-cli` 是可运行 jar,不是伪命令。
|
||||
- `FeaturePackage` 和 `Revision` 已有最小持久化模型。
|
||||
|
||||
但它还不是 NocoBase 级完整度:
|
||||
|
||||
- CLI 之前缺少 env registry/current env。
|
||||
- revision 只是功能包快照,不是完整版本控制。
|
||||
- Skills 只是仓库文档,没有 CLI 安装/检查/更新。
|
||||
- AI tools/permissions/MCP/AI employee 还没有平台级注册。
|
||||
- 页面配置还没有 typed FlowModel registry。
|
||||
|
||||
### 已按源码对照修订的 P3 第一批
|
||||
|
||||
- `platform-cli` 新增本地 env registry,默认保存到 `~/.eip4/eip4-cli.json`。
|
||||
- 新增 `eip4 env add/list/use/current/status`。
|
||||
- AI 命令支持 `--env`。
|
||||
- 显式选择非当前 env 时必须加 `--yes`,避免误操作共享环境。
|
||||
- 新增 `eip4 release verify --package-file FILE`,离线检查功能包是否具备本地门禁 evidence、人审标记、SQL/rollback,并阻断 `${...}` 占位符。
|
||||
- 新增 `eip4 release export --package-file FILE --output FILE`,将功能包封装为 `.eip4pkg.json`,包含格式版本和 SHA-256 checksum。
|
||||
- 新增 `eip4 release import-preview --package-file FILE`,离线验证 `.eip4pkg.json` checksum 和发布门禁,不写任何环境。
|
||||
- 新增 `eip4 release diff --left FILE --right FILE`,离线比较两个功能包或 `.eip4pkg.json` 的标识、SQL、rollback SQL 和 manifest 差异。
|
||||
- 新增 `eip4 release rollback-plan --package-file FILE --output FILE`,只生成结构化回滚计划,不执行生产写入。
|
||||
|
||||
## 三、后续实现顺序
|
||||
|
||||
### P3-1:CLI env 和发布前治理
|
||||
|
||||
状态:进行中。
|
||||
|
||||
目标:
|
||||
|
||||
- env registry/current env
|
||||
- `release verify`
|
||||
- package/revision 差异检查
|
||||
- 生产环境默认只读
|
||||
|
||||
### P3-2:FeaturePackage 导出/导入
|
||||
|
||||
状态:第一版完成。
|
||||
|
||||
目标:
|
||||
|
||||
- `.eip4pkg.json` 文件格式
|
||||
- checksum
|
||||
- import preview
|
||||
- import 后不自动启用
|
||||
|
||||
第一版已落地:
|
||||
|
||||
- export: 普通 feature package JSON -> `.eip4pkg.json` 信封。
|
||||
- import-preview: 校验 format/version/checksum/payload 和 release gate。
|
||||
- import-preview 只读,不落库、不启用、不发布。
|
||||
|
||||
### P3-3:Revision diff/restore
|
||||
|
||||
状态:第一版完成。
|
||||
|
||||
目标:
|
||||
|
||||
- revision diff
|
||||
- rollback plan
|
||||
- rollback 只生成计划和 SQL,不默认执行生产写入
|
||||
|
||||
第一版已落地:
|
||||
|
||||
- diff: 比较两个普通 feature package JSON 或 `.eip4pkg.json`,支持 checksum 校验和 JSON 输出。
|
||||
- rollback-plan: 生成 `EIP4_ROLLBACK_PLAN` JSON,包含 package/task/changeSet、rollback SQL、source evidence 和人审要求。
|
||||
- rollback-plan 会阻断 rollback SQL 中的 `${...}` 占位符;命令不连接环境、不落库、不执行 SQL。
|
||||
|
||||
### P4:Typed UI Registry
|
||||
|
||||
状态:第一版完成。
|
||||
|
||||
目标:
|
||||
|
||||
- typed page schema
|
||||
- component/action/event registry
|
||||
- AI 只能选择 registry 中允许的组件和动作
|
||||
|
||||
第一版已落地:
|
||||
|
||||
- `PageComponentRegistry` 提供页面组件能力表,当前覆盖 page/crud/form/operation/button、常用 layout/display 和字段组件。
|
||||
- `TypedPageSchemaValidator` 校验根节点、已注册组件和 actionType 能力。
|
||||
- `GET /api/page/schema/components` 返回组件能力表。
|
||||
- `POST /api/page/schema/validate` 离线校验页面 schema,不写库。
|
||||
- `PUT /api/page/schema/{templateId}/overlay` 保存前会先跑 typed schema 校验,未注册组件或不支持 action 会被 400 阻断。
|
||||
|
||||
### P5:AI tools/skills/employee/ACL
|
||||
|
||||
状态:第一版完成。
|
||||
|
||||
目标:
|
||||
|
||||
- AI tool registry
|
||||
- AI employee registry
|
||||
- ACL/scope check
|
||||
- 生产写默认阻断
|
||||
|
||||
第一版已落地:
|
||||
|
||||
- `AiToolRegistry` 注册工具、操作入口、所需 scope、本地限定和生产写边界。
|
||||
- `GET /api/ai/tools` 返回 AI 工具注册表。
|
||||
- `GET /api/ai/employees` 返回 AI employee 定义。
|
||||
- `POST /api/ai/tools/access-check` 只做权限判定,不执行工具;`local.apply` 等本地工具在 prod target 会被阻断。
|
||||
- 当前所有工具都不允许生产写;线上部署仍由人工拿发布包执行。
|
||||
- Skills CLI check/update
|
||||
- AI Agent 权限和审计
|
||||
- MCP 工具白名单
|
||||
127
docs/AI_AGENT_PAGE_BLUEPRINT_CONTRACT.md
Normal file
127
docs/AI_AGENT_PAGE_BLUEPRINT_CONTRACT.md
Normal file
@@ -0,0 +1,127 @@
|
||||
# AI Agent Page Blueprint Contract
|
||||
|
||||
日期:2026-06-17
|
||||
|
||||
## 目标
|
||||
|
||||
EIP4 的 AI Agent 不直接自由生成 amis JSON。Agent 应先生成 EIP4 PageBlueprint,再由平台编译器输出 amis schema,并继续通过 typed page schema、amis schema 和真实浏览器 E2E。
|
||||
|
||||
这条路径借鉴 NocoBase 的做法:AI 操作受控配置模型,平台负责规范化、校验、模板复用和版本证据。
|
||||
|
||||
## 当前已落地对象
|
||||
|
||||
代码位置:
|
||||
|
||||
- `platform-metadata/src/main/java/com/eip4/platform/metadata/schema/blueprint/PageBlueprint.java`
|
||||
- `platform-metadata/src/main/java/com/eip4/platform/metadata/schema/blueprint/PageBlueprintField.java`
|
||||
- `platform-metadata/src/main/java/com/eip4/platform/metadata/schema/blueprint/PageBlueprintCompiler.java`
|
||||
- `platform-metadata/src/main/java/com/eip4/platform/metadata/schema/blueprint/PageRecipeRegistry.java`
|
||||
- `platform-metadata/src/main/java/com/eip4/platform/metadata/schema/blueprint/PageRecipeValidator.java`
|
||||
- `platform-ai/src/main/resources/ai/page-recipes/maintenance-crud-v1.yaml`
|
||||
- `platform-ai/src/main/resources/ai/page-recipes/tree-crud-v1.yaml`
|
||||
|
||||
AI 可查询入口:
|
||||
|
||||
- `GET /api/ai/page-recipes`
|
||||
- `GET /api/ai/page-recipes/{recipe}`
|
||||
|
||||
工具注册表中对应工具为 `page-recipe.read`,所需 scope 为 `ai:page-recipe:read`。Agent 生成
|
||||
PageBlueprint 前应先读取 recipe 定义,再生成草稿。
|
||||
|
||||
AI 自动开发链路中的 `PAGE_SCHEMA` 草稿仍然保存编译后的 amis schema,保持现有落库和前端渲染契约不变;草稿 metadata 额外保存:
|
||||
|
||||
- `pageRecipe`
|
||||
- `pageBlueprintVersion`
|
||||
- `pageBlueprint`
|
||||
|
||||
声明了 `pageRecipe` 的草稿必须通过 `page-recipe` 门禁。该门禁会重新解析 metadata 中的
|
||||
`pageBlueprint`,用平台注册的 recipe/compiler 重新编译,并要求草稿 payload 与编译结果一致。
|
||||
因此 Agent 不能一边声明使用标准 recipe,一边绕过 compiler 私改 amis JSON。没有声明 recipe 的
|
||||
历史/手工 `PAGE_SCHEMA` 草稿暂按自由 schema 处理,只走 amis schema 和 typed page schema。
|
||||
|
||||
## Recipe: maintenance-crud-v1
|
||||
|
||||
适用范围:
|
||||
|
||||
- 普通实体维护页
|
||||
- 单主表列表
|
||||
- 新增、编辑、删除
|
||||
- 本地 smoke 可覆盖列表、新增、服务流搜索
|
||||
|
||||
标准输出结构:
|
||||
|
||||
- 顶层 `type=page`
|
||||
- `body` 为 `crud`
|
||||
- `crud.name` 固定为 `{lowerCamel(tableName)}Crud`
|
||||
- `crud.syncLocation=false`
|
||||
- 列表 API 固定为 `/api/entity/{table}/list?page=${page}&perPage=${perPage}`
|
||||
- 新增按钮位于 `headerToolbar[0]`
|
||||
- 新增按钮使用 `level=primary`、`icon=fa fa-plus`、`actionType=dialog`
|
||||
- 新增和编辑表单提交到 `post:/api/entity/{table}/save`
|
||||
- 编辑按钮位于操作列第一位
|
||||
- 删除按钮位于操作列第二位
|
||||
- 删除按钮使用 `className=text-danger`、`actionType=ajax`、`confirmText`
|
||||
- 删除 API 固定为 `/api/entity/{table}/delete`
|
||||
- 页大小默认 `20`
|
||||
- `footerToolbar` 固定包含 `statistics` 和 `pagination`
|
||||
|
||||
## Recipe: tree-crud-v1
|
||||
|
||||
适用范围:
|
||||
|
||||
- 自引用层级实体维护页
|
||||
- 实体必须包含 `PARENTID` 字段
|
||||
- 覆盖树形列表、新增顶级节点、加子节点、编辑、删除
|
||||
|
||||
标准输出结构:
|
||||
|
||||
- 顶层 `type=page`
|
||||
- `body` 为 `crud`
|
||||
- `crud.name` 固定为 `{lowerCamel(tableName)}TreeCrud`
|
||||
- `crud.childrenColumnName=children`
|
||||
- 列表 API 固定为 `/api/entity/{table}/tree?parentKey=PARENTID&idKey={primaryKey}&perPage=2000`
|
||||
- 新增顶级按钮位于 `headerToolbar[0]`
|
||||
- 新增顶级按钮使用 `level=primary`、`icon=fa fa-plus`、`actionType=dialog`
|
||||
- 操作列按钮顺序固定为:加子项、编辑、删除
|
||||
- 加子项表单必须隐藏写入 `PARENTID=${primaryKey}`
|
||||
- 编辑表单必须保留隐藏主键和 `PARENTID`
|
||||
- 删除按钮使用 `className=text-danger`、`actionType=ajax`、`confirmText`
|
||||
- 树数据端点返回 `data.items` 层级数组,每个节点的子节点字段为 `children`
|
||||
|
||||
字段映射:
|
||||
|
||||
- `string` -> `input-text`
|
||||
- `integer` / `number` -> `input-number`
|
||||
- `date` -> `input-date`
|
||||
- `datetime` -> `input-datetime`
|
||||
- `boolean` -> `switch`
|
||||
- 主键不出现在新增表单,编辑表单最后追加 `hidden`
|
||||
|
||||
## 当前边界
|
||||
|
||||
本阶段只解决“AI 生成维护类 CRUD 页时走受控 recipe”。还未覆盖:
|
||||
|
||||
- 主子表页面
|
||||
- 审批办理页面
|
||||
- 看板、日历、图表、报表页
|
||||
- 复杂字段分组
|
||||
- 条件联动
|
||||
- 引用选择器策略
|
||||
- 权限按钮策略
|
||||
|
||||
这些类型必须作为新的 recipe 增量加入,不能让 Agent 直接绕过 blueprint 生成最终 amis JSON。
|
||||
|
||||
## 已落地门禁
|
||||
|
||||
- `page-recipe`:校验 recipe 已注册、metadata 证据完整、payload 等于 blueprint 编译结果。
|
||||
- `typed-page-schema`:校验组件和 actionType 来自 EIP4 注册表。
|
||||
- `amis-schema`:校验最终 schema 符合 amis schema。
|
||||
- `local-smoke`:本地发布后访问页面、实体、服务流和新增接口。
|
||||
- `render-plan`:`TEST` 草稿必须提供 Playwright 可消费的 `renderTests`,包含 recipe、schemaUrl、previewUrl、预期根组件、CRUD 名、数据 API、列表列、页面动作和关键文本。
|
||||
|
||||
## 后续演进
|
||||
|
||||
1. 增加 `master-detail-v1`、`approval-task-v1` recipe。
|
||||
2. 让设计器 overlay 保存也能记录对应 blueprint 或 template 来源。
|
||||
3. 在功能包中导出 blueprint,线上部署包继续导出编译后的 amis schema。
|
||||
4. Playwright E2E 消费 `renderTests`,执行真实浏览器渲染并回写运行证据。
|
||||
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 页面必填结构"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
19
docs/skills/README.md
Normal file
19
docs/skills/README.md
Normal file
@@ -0,0 +1,19 @@
|
||||
# EIP4 Agent Skills
|
||||
|
||||
本目录是 EIP4 给 AI Agent 使用的领域操作规程。目标是让 Codex、Claude Code、Cursor、OpenCode 等 Agent 都按同一套规则操作 EIP4,而不是临时猜接口、猜表结构或直连线上库。
|
||||
|
||||
## Skills
|
||||
|
||||
| Skill | 用途 |
|
||||
|---|---|
|
||||
| `eip4-env-manage` | 环境探测、启动检查、端口和 profile 边界 |
|
||||
| `eip4-ai-feature-development` | 从自然语言需求生成实体、服务流、页面、菜单和本地 smoke |
|
||||
| `eip4-release-manage` | 部署包、人审、发布前校验和回滚边界 |
|
||||
|
||||
## 通用原则
|
||||
|
||||
1. 优先使用 `platform-cli`,其次使用公开 REST API,最后才考虑人工 SQL。
|
||||
2. 默认只允许本地开发和测试环境自动执行写操作。
|
||||
3. 线上环境只能生成部署包和校验证据,不能由 Agent 默认直接写入。
|
||||
4. 每次自动开发必须保留 request、draft、change-set、apply、smoke、repair、deployment package evidence。
|
||||
5. 任何失败先回到本地复现和修复,再重新生成部署包。
|
||||
113
docs/skills/eip4-ai-feature-development.md
Normal file
113
docs/skills/eip4-ai-feature-development.md
Normal file
@@ -0,0 +1,113 @@
|
||||
# Skill: eip4-ai-feature-development
|
||||
|
||||
## 触发场景
|
||||
|
||||
- 用户描述一个新功能,希望 AI 自动生成。
|
||||
- 用户要求从 EIP3 模板、实体、服务流或页面定义生成 EIP4 功能。
|
||||
- 用户要求本地自动开发、自动修复和 smoke。
|
||||
|
||||
## 输入要求
|
||||
|
||||
最小需求应包含:
|
||||
|
||||
- 功能目标
|
||||
- 功能名称
|
||||
- 业务表名
|
||||
- 实体名称
|
||||
- 页面 templateId
|
||||
- 菜单名称
|
||||
- 字段列表
|
||||
- 页面配方,可省略。默认 `maintenance-crud-v1`;树形维护页使用 `tree-crud-v1`
|
||||
|
||||
字段格式:
|
||||
|
||||
```text
|
||||
column:label:type[:length][:required]
|
||||
```
|
||||
|
||||
示例:
|
||||
|
||||
```text
|
||||
NAME:名称:string:100:true
|
||||
CODE:编码:string:64:true
|
||||
ENABLED:启用:boolean::false
|
||||
```
|
||||
|
||||
## 推荐命令
|
||||
|
||||
```bash
|
||||
java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar ai auto-develop \
|
||||
--base-url http://localhost:8084 \
|
||||
--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
|
||||
```
|
||||
|
||||
树形维护页示例:
|
||||
|
||||
```bash
|
||||
java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar ai auto-develop \
|
||||
--base-url http://localhost:8084 \
|
||||
--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
|
||||
```
|
||||
|
||||
## 通过标准
|
||||
|
||||
- `applyStatus` 为 `PASSED`。
|
||||
- `smokeStatus` 为 `PASSED`。
|
||||
- 最终状态为 `READY_FOR_HUMAN_REVIEW`。
|
||||
- 部署包存在且 `requiresHumanApproval=true`。
|
||||
- 页面 schema 只能使用组件能力表中注册的组件和动作。
|
||||
- `PAGE_SCHEMA` 草稿必须声明并通过 `page-recipe` 门禁;普通维护页为 `maintenance-crud-v1`,树形维护页为 `tree-crud-v1`。
|
||||
- `TEST` 草稿必须通过 `smoke-plan` 和 `render-plan`;`renderTests` 是后续 Playwright 渲染验收的输入,需包含 previewUrl、预期组件、列、动作、数据 API 和关键文本。
|
||||
|
||||
## 页面 schema 校验
|
||||
|
||||
```bash
|
||||
curl http://localhost:8084/api/page/schema/components
|
||||
|
||||
curl -X POST http://localhost:8084/api/page/schema/validate \
|
||||
-H "Content-Type: application/json" \
|
||||
--data-binary @target/ai-runs/page-schema.json
|
||||
```
|
||||
|
||||
设计器保存 overlay 时也会执行同一套 typed schema 校验;未注册组件或不支持的 `actionType` 会被拒绝。
|
||||
|
||||
## AI 工具权限检查
|
||||
|
||||
```bash
|
||||
curl http://localhost:8084/api/ai/tools
|
||||
curl http://localhost:8084/api/ai/employees
|
||||
|
||||
curl -X POST http://localhost:8084/api/ai/tools/access-check \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"employeeId":"agent-developer","toolName":"local.apply","grantedScopes":["ai:local:apply"],"targetEnv":"local","productionWrite":false}'
|
||||
```
|
||||
|
||||
本地 apply、smoke 等工具只允许本地目标;生产写默认被阻断,线上部署仍走人工发布。
|
||||
|
||||
## 失败处理
|
||||
|
||||
1. 查看输出 JSON 中的 apply/smoke/repair evidence。
|
||||
2. 如果自动修复已尝试但失败,基于 evidence 修改本地代码或元数据生成逻辑。
|
||||
3. 重新运行本地 auto-develop。
|
||||
4. 不直接连接线上库修复。
|
||||
49
docs/skills/eip4-env-manage.md
Normal file
49
docs/skills/eip4-env-manage.md
Normal file
@@ -0,0 +1,49 @@
|
||||
# Skill: eip4-env-manage
|
||||
|
||||
## 触发场景
|
||||
|
||||
- 用户要求启动、检查或切换 EIP4 环境。
|
||||
- 用户要求 Agent 在本地验证功能。
|
||||
- 用户要求确认当前服务是否可被 AI 自动开发链路使用。
|
||||
|
||||
## 操作规则
|
||||
|
||||
1. 确认当前目录是否是独立 worktree,避免污染用户正在做的任务。
|
||||
2. 使用 JDK 21,不能使用 JDK 26。
|
||||
3. 默认本地 profile:
|
||||
- `local`: `http://localhost:8084`
|
||||
- `dev`: `http://localhost:8093`
|
||||
4. 使用 CLI 探测环境:
|
||||
|
||||
```bash
|
||||
java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar env add \
|
||||
--name local \
|
||||
--base-url http://localhost:8084 \
|
||||
--kind local \
|
||||
--use
|
||||
|
||||
java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar env status
|
||||
```
|
||||
|
||||
5. 如果服务未启动,优先使用重新打包后的 jar:
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
## 禁止事项
|
||||
|
||||
- 不在用户原始任务目录中直接改动或启动长时间任务,除非用户明确要求。
|
||||
- 不把线上环境设置为默认写入目标。
|
||||
- 不跳过 JDK 版本检查。
|
||||
- 显式选择非当前 env 执行 AI 或发布类命令时,必须要求 `--yes` 或等效人工确认。
|
||||
|
||||
## 常用命令
|
||||
|
||||
```bash
|
||||
java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar env list
|
||||
java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar env current
|
||||
java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar env use --name local
|
||||
java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar env status --all
|
||||
```
|
||||
96
docs/skills/eip4-release-manage.md
Normal file
96
docs/skills/eip4-release-manage.md
Normal file
@@ -0,0 +1,96 @@
|
||||
# Skill: eip4-release-manage
|
||||
|
||||
## 触发场景
|
||||
|
||||
- 用户要求生成部署包。
|
||||
- 用户要求发布 AI 生成的功能。
|
||||
- 用户要求线上 bug 修复或回滚。
|
||||
|
||||
## 当前边界
|
||||
|
||||
当前 `platform-ai` 只生成线上人工部署包,不自动连接线上环境执行写操作。这是设计边界,不是功能缺失。
|
||||
|
||||
## 发布前检查
|
||||
|
||||
1. 确认本地 auto-develop 已通过。
|
||||
2. 使用 CLI 生成 AI 功能包快照:
|
||||
|
||||
```bash
|
||||
java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar ai feature-package \
|
||||
--base-url http://localhost:8084 \
|
||||
--task-id ait-xxx \
|
||||
--change-set-id aics-xxx \
|
||||
--output target/ai-runs/feature-package.json
|
||||
```
|
||||
|
||||
3. 保存里程碑 revision:
|
||||
|
||||
```bash
|
||||
java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar ai revision \
|
||||
--base-url http://localhost:8084 \
|
||||
--task-id ait-xxx \
|
||||
--package-id aipkg-xxx \
|
||||
--note "本地门禁通过,待人工部署" \
|
||||
--output target/ai-runs/revision.json
|
||||
```
|
||||
|
||||
4. 运行离线发布校验:
|
||||
|
||||
```bash
|
||||
java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar release verify \
|
||||
--package-file target/ai-runs/feature-package.json
|
||||
```
|
||||
|
||||
5. 导出 `.eip4pkg.json` 并做导入预览:
|
||||
|
||||
```bash
|
||||
java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar release export \
|
||||
--package-file target/ai-runs/feature-package.json \
|
||||
--output target/ai-runs/feature-package.eip4pkg.json
|
||||
|
||||
java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar release import-preview \
|
||||
--package-file target/ai-runs/feature-package.eip4pkg.json
|
||||
```
|
||||
|
||||
6. 如存在上一版功能包,先做离线差异检查:
|
||||
|
||||
```bash
|
||||
java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar release diff \
|
||||
--left target/ai-runs/feature-package-old.json \
|
||||
--right target/ai-runs/feature-package.json
|
||||
```
|
||||
|
||||
7. 需要回滚预案时,只生成回滚计划文件:
|
||||
|
||||
```bash
|
||||
java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar release rollback-plan \
|
||||
--package-file target/ai-runs/feature-package.eip4pkg.json \
|
||||
--output target/ai-runs/rollback-plan.json
|
||||
```
|
||||
|
||||
8. 确认部署包包含:
|
||||
- manifest
|
||||
- SQL 草案
|
||||
- rollback SQL
|
||||
- 本地 apply evidence
|
||||
- smoke evidence
|
||||
- repair evidence
|
||||
9. 确认部署包需要人工审批。
|
||||
10. 如果包含 `${parentMenuId}` 等占位符,必须人工替换并复核;`release verify` 默认会阻断这类包。
|
||||
|
||||
## 线上 bug 修复路径
|
||||
|
||||
1. 收集线上错误日志、请求样本或人工复现步骤。
|
||||
2. 在本地创建新的 AI 修复任务。
|
||||
3. 本地执行 apply/smoke/repair。
|
||||
4. 生成新的部署包。
|
||||
5. 人工审核后走现有上线流程。
|
||||
|
||||
## 禁止事项
|
||||
|
||||
- 不让 Agent 默认直接写线上数据库。
|
||||
- 不绕过部署包和人审。
|
||||
- 不把 smoke 失败的变更包交给发布流程。
|
||||
- 不发布 `release verify` 失败的功能包。
|
||||
- 不把 `import-preview` 当成导入或启用;它只是离线检查。
|
||||
- 不把 `rollback-plan` 当成回滚执行;它只生成计划和 SQL 清单。
|
||||
129
docs/sql/SYS_AI_AGENT.sql
Normal file
129
docs/sql/SYS_AI_AGENT.sql
Normal file
@@ -0,0 +1,129 @@
|
||||
-- ============================================================================
|
||||
-- 生产建表脚本: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_feature_package (
|
||||
package_id character varying(64) NOT NULL,
|
||||
task_id character varying(64) NOT NULL,
|
||||
change_set_id character varying(64) NOT NULL,
|
||||
status character varying(32) NOT NULL,
|
||||
manifest_json jsonb NOT NULL,
|
||||
deployment_package_json jsonb NOT NULL,
|
||||
created_at bigint NOT NULL,
|
||||
CONSTRAINT pk_sys_ai_feature_package PRIMARY KEY (package_id)
|
||||
);
|
||||
|
||||
CREATE TABLE IF NOT EXISTS sys_ai_revision (
|
||||
revision_id character varying(64) NOT NULL,
|
||||
task_id character varying(64) NOT NULL,
|
||||
package_id character varying(64) NOT NULL,
|
||||
status character varying(32) NOT NULL,
|
||||
note text NOT NULL,
|
||||
snapshot_json jsonb NOT NULL,
|
||||
created_at bigint NOT NULL,
|
||||
CONSTRAINT pk_sys_ai_revision PRIMARY KEY (revision_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_feature_package_task ON sys_ai_feature_package (task_id, created_at);
|
||||
CREATE INDEX IF NOT EXISTS idx_sys_ai_revision_task ON sys_ai_revision (task_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_feature_package IS 'AI Agent 功能包快照。封装部署包、manifest 和本地证据,用于人审/导出/版本里程碑';
|
||||
COMMENT ON TABLE sys_ai_revision IS 'AI Agent 里程碑版本。保存功能包快照,后续用于差异比较和回滚';
|
||||
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_feature_package.manifest_json IS '功能包 manifest,包含包 id、变更包 id、证据数量和发布边界';
|
||||
COMMENT ON COLUMN sys_ai_feature_package.deployment_package_json IS '部署包完整 JSON 快照';
|
||||
COMMENT ON COLUMN sys_ai_revision.snapshot_json IS '里程碑快照 JSON,当前保存 AiFeaturePackage';
|
||||
COMMENT ON COLUMN sys_ai_audit_log.details_json IS '操作详情 JSON';
|
||||
@@ -18,7 +18,8 @@ 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-cli EIP4 Agent 受控命令入口:环境探测、AI 自动开发、后续发布编排
|
||||
├── platform-parity C1 逐行对拍框架:录制/重放/逐行 diff(P1 一级交付物,可独立 CLI 跑批)
|
||||
└── platform-app Spring Boot 启动器,组装上述模块
|
||||
```
|
||||
@@ -118,4 +119,4 @@ eip4-platform(Maven 多模块单体)
|
||||
|
||||
---
|
||||
|
||||
**本文档维护**:随 P1 包结构落地校正;任何选型变更(尤其渲染层切换)回写第二、七节。
|
||||
**本文档维护**:随 P1 包结构落地校正;任何选型变更(尤其渲染层切换)回写第二、七节。
|
||||
|
||||
Reference in New Issue
Block a user