merge ai agent module

This commit is contained in:
2026-06-19 14:01:09 +08:00
112 changed files with 11723 additions and 14 deletions

19
docs/skills/README.md Normal file
View 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. 任何失败先回到本地复现和修复,再重新生成部署包。

View 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. 不直接连接线上库修复。

View 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
```

View 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 清单。