feat: add CLI env registry and release verification

This commit is contained in:
2026-06-17 08:21:40 +08:00
parent c5bfbd3ca3
commit 5f7e226fa0
8 changed files with 684 additions and 21 deletions

View File

@@ -111,6 +111,8 @@ EIP4 当前已经有实体、页面 schema、服务流、菜单、smoke、部署
### P3:发布、回滚和环境治理
状态:进行中。
目标:
- CLI 扩展为环境管理和发布编排入口。
@@ -130,6 +132,13 @@ EIP4 当前已经有实体、页面 schema、服务流、菜单、smoke、部署
- 生产写操作必须有显式环境、审批标记和部署包
- 发布失败能用结构化 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 的功能包。
- 详细源码对照见 `docs/AI_AGENT_Nocobase_SOURCE_REVIEW.md`。
### P4:Typed Page Schema 和组件注册表
目标:
@@ -181,6 +190,6 @@ EIP4 应该借鉴的是边界和流程:
| P0 | 完成 | `platform-ai` 主链路已提交 |
| P1 | 第一版完成 | 已新增 `platform-cli` 和 Skills 规范骨架 |
| P2 | 第一版完成 | 已新增功能包快照、里程碑 revision、CLI 命令和持久化表 |
| P3 | 待开始 | 依赖 P2 的功能包和版本模型 |
| P3 | 进行中 | 已开始 env registry/current env/cross-env guard/release verify |
| P4 | 待开始 | 依赖页面 schema 现状清理 |
| P5 | 待开始 | 依赖权限、审计、工具白名单成熟 |

View File

@@ -0,0 +1,93 @@
# 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,并阻断 `${...}` 占位符。
## 三、后续实现顺序
### P3-1:CLI env 和发布前治理
状态:进行中。
目标:
- env registry/current env
- `release verify`
- package/revision 差异检查
- 生产环境默认只读
### P3-2:FeaturePackage 导出/导入
目标:
- `.eip4pkg.json` 文件格式
- checksum
- import preview
- import 后不自动启用
### P3-3:Revision diff/restore
目标:
- revision diff
- rollback plan
- rollback 只生成计划和 SQL,不默认执行生产写入
### P4:Typed UI Registry
目标:
- typed page schema
- component/action/event registry
- AI 只能选择 registry 中允许的组件和动作
### P5:AI tools/skills/employee/ACL
目标:
- AI tool registry
- Skills CLI check/update
- AI Agent 权限和审计
- MCP 工具白名单

View File

@@ -16,7 +16,13 @@
4. 使用 CLI 探测环境:
```bash
java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar env status --base-url http://localhost:8084
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:
@@ -31,4 +37,13 @@ JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-app -am install -DskipTe
- 不在用户原始任务目录中直接改动或启动长时间任务,除非用户明确要求。
- 不把线上环境设置为默认写入目标。
- 不跳过 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

@@ -34,15 +34,22 @@ java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar ai revision \
--output target/ai-runs/revision.json
```
4. 确认部署包包含:
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. 确认部署包包含:
- manifest
- SQL 草案
- rollback SQL
- 本地 apply evidence
- smoke evidence
- repair evidence
5. 确认部署包需要人工审批。
6. 如果包含 `${parentMenuId}` 等占位符,必须人工替换并复核。
6. 确认部署包需要人工审批。
7. 如果包含 `${parentMenuId}` 等占位符,必须人工替换并复核;`release verify` 默认会阻断这类包。
## 线上 bug 修复路径
@@ -57,3 +64,4 @@ java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar ai revision \
- 不让 Agent 默认直接写线上数据库。
- 不绕过部署包和人审。
- 不把 smoke 失败的变更包交给发布流程。
- 不发布 `release verify` 失败的功能包。