Files
eip4-platform/README.md
zhengwr a573d8fa2c docs(readme): 平台 README 命令段补 eip4 skills list/check(G3 收尾)
G3 当时只更新了 docs/skills/README,平台主 README 的 EIP4 Agent CLI 段漏了 skills 命令。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-22 14:57:07 +08:00

131 lines
7.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# eip4-platform
EIP4 平台正式工程(路线 A'):双层制模块化单体——**保真层供奉,现代层生长**。
架构依据:`docs/架构设计.md`(必读);坑位台账:`docs/迁移手册.md`。
## 模块
| 模块 | 职责 | 纪律 |
|------|------|------|
| platform-legacy-core | 保真层:移植引擎原样,包名 `com.dsasp.*` 不动 | **不重写、不改包名,与 framework 源码 diff 最小;对拍=完成定义** |
| platform-metadata | 现代层 REST API/DTO/OpenAPI(`com.eip4.*`) | 新代码须评审+单测 |
| platform-auth | 数据权限真实现(C2 已替换桩)+ P2 组织/权限 | |
| platform-converter | 模板转换器(P4) | 可独立 CLI 跑批 |
| platform-flow-gateway | P3 占位:Flowable 网关 | |
| platform-ai | P5 AI Agent 开发底座:草稿/变更包/本地门禁/自动修复/人工部署包 | Agent 不直连线上执行生产变更 |
| platform-cli | EIP4 Agent 受控命令入口:`init` 一键接入(Claude Code/Codex/OpenCode)、环境探测、AI 自动开发、发布编排 | Agent 优先通过 CLI/API 操作 |
| platform-mcp | EIP4 MCP server(stdio):把 AI/元数据 REST 端点包成 MCP 工具,供 Claude Code/Codex/OpenCode 经标准协议接入 | 忠实转发 REST,复用人审红线,不另开权限面 |
| platform-parity | C1 对拍框架:录制/重放/RowDiff/自对拍 CLI | P1 一级交付物 |
| platform-app | Boot 启动器,组装全部模块 | ArchUnit 规则在此模块测试里 |
**边界纪律(ArchUnit 强制)**:`com.eip4.*` 可调 `com.dsasp.*`,反向禁止。
## 三套 profile
| profile | 数据源 | 端口 | 用途 |
|---------|--------|------|------|
| **dev**(日常开发) | localhost:5433/eip4dev(真实数据副本) | 8093 | **日常功能开发/联调,完全本地,无需网络** |
| **local**(自举) | localhost:5433/eip4m0(极简自举集) | 8084 | CI/对拍/单元测试 |
| 默认(验证) | 192.168.20.68:5435/eip3(客户库副本) | 8084 | 验收验证/性能基线,5435 收敛为只读基线 |
> eip4dev 刷新:`bash tools/local-devdb/build_devdb.sh --drop-target`(约 6 分钟)
> 详见:`tools/local-devdb/本地开发库构建报告.md`
## ⚠️ 运行环境(必读):必须 JDK 21,不可用 JDK 26
**保真层老引擎的服务流脚本运行时走 JSR-223 调 Groovy 4.0.27(`pom.xml` 钉定)。**
**Groovy 4.0.27 不认 JDK 26 的字节码(class major version 70),会在编译脚本时抛
`GroovyBugError: Unsupported class file major version 70`,导致大批服务流查询
(`*_SEARCH_LISTINFO`/`*_SZWJ` 等)直接 500。** 项目 `maven.compiler.release=21`、
生产环境=JDK 21(LTS),故本地开发也**必须用 JDK 21**。
⚠️ homebrew 默认的 `openjdk` 现在是 **26**——不显式指定 `JAVA_HOME` 会误用 26。
请先 `brew install openjdk@21`,并始终用 JDK 21 启动。**推荐用守卫脚本(自动定位并强制 21):**
```bash
# 一键启动(强制 JDK 21,自动关停旧实例;默认 platform+flowable 都起)
bash scripts/run-dev.sh both # 或 platform / flowable
EIP4_PROFILE=local bash scripts/run-dev.sh platform # 换 profile
# 将来升 JDK:目标是下个 LTS=25(非 LTS 的 26 不用),且须同步升 Groovy + 跑对拍回归。
```
## 常用命令
```bash
# 所有 mvn/java 命令都须用 JDK 21(见上「运行环境」)
export JAVA_HOME=/opt/homebrew/opt/openjdk@21 # 必须 21;openjdk@21/bin/java 应报 21.x
mvn test # 全模块测试(含 ArchUnit)
# 启动:推荐 scripts/run-dev.sh(带 JDK 21 守卫);以下 mvn 方式同样要求 JAVA_HOME=21
# dev profile — 日常开发(真实数据副本 eip4dev,端口 8093)
mvn spring-boot:run -pl platform-app -Dspring-boot.run.profiles=dev
# local profile — 自举最小集(CI/对拍,端口 8084)
mvn spring-boot:run -pl platform-app -Dspring-boot.run.profiles=local
# 默认 profile — 客户库副本 5435(验证用)
mvn spring-boot:run -pl platform-app
# 构建/刷新本地开发库 eip4dev(幂等,约 6 分钟)
bash tools/local-devdb/build_devdb.sh --drop-target
# 对拍(详见 platform-parity/C1实测报告.md)
CP="platform-parity/target/classes:$(mvn -q org.apache.maven.plugins:maven-dependency-plugin:build-classpath -pl platform-parity -Dmdep.outputFile=/dev/stdout -o | tail -1)"
java -cp "$CP" com.eip4.platform.parity.selfcheck.ParityCli --all # 本地全量
java -cp "$CP" com.eip4.platform.parity.selfcheck.ParityCli --privilege # C2 数据权限样本
# 指向 eip4dev 自对拍:
mvn -pl platform-parity exec:java -Dexec.mainClass="com.eip4.platform.parity.selfcheck.ParityCli" \
"-Dexec.args=--discover --jdbc=jdbc:postgresql://localhost:5433/eip4dev?currentSchema=eip3 --engine=http://localhost:8093 --out=parity-reports/eip4dev"
# EIP4 Agent CLI
mvn -pl platform-cli package
java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar env add --name local --base-url http://localhost:8084 --use
java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar env status --base-url http://localhost:8084
# 一键把 agent skills 装到目标项目,让 Claude Code / Codex / OpenCode 都能驱动平台开发
# Claude Code → .claude/skills/<name>/SKILL.md(原生 skill);Codex/OpenCode → 根 AGENTS.md(内嵌全文)
# base URL 按 current env(或 --base-url/--env)渲染;skills 已随 jar 打包,无需仓库在场
# 详见 docs/skills/README.md
java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar init --dir <你的项目>
# 查看内置 agent skills / 校验目标项目是否已安装(缺失退出码非 0,便于 CI 把关)
java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar skills list
java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar skills check --dir <你的项目>
java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar ai feature-package --task-id ait-xxx --change-set-id aics-xxx --output target/ai-runs/package.json
java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar release verify --package-file target/ai-runs/package.json
java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar release export --package-file target/ai-runs/package.json --output target/ai-runs/package.eip4pkg.json
java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar release import-preview --package-file target/ai-runs/package.eip4pkg.json
java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar release diff --left target/ai-runs/package-old.json --right target/ai-runs/package.json
java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar release rollback-plan --package-file target/ai-runs/package.eip4pkg.json --output target/ai-runs/rollback-plan.json
# EIP4 MCP server(stdio):把下面这些 AI/元数据端点包成 MCP 工具,供 Claude Code/Codex/OpenCode 用标准协议调用
mvn -pl platform-mcp package
claude mcp add eip4 -- java -jar platform-mcp/target/platform-mcp-0.1.0-SNAPSHOT.jar --base-url http://localhost:8093
# 或设 EIP4_BASE_URL;默认 http://localhost:8084。手动启动:java -jar platform-mcp/target/platform-mcp-0.1.0-SNAPSHOT.jar
# Typed page schema
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
# AI tools / employees / ACL
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}'
```
## tools/
- `tools/s3_rewriter/` — C4 S3 脚本正则改写器(真实库自动化率 81.2%,P4 facade 扩容种子);`run_eval.py --from-db` 连客户库复测
- `tools/loadtest/load_p95.py` — C3 压测 harness(零依赖)
## 本地自举
空库重建:`platform-parity/src/main/resources/bootstrap/bootstrap-sys.sql` + `bootstrap-privilege.sql`,
再 `ParityCli --seed --all` 建 21 个测试实体并灌数。