From 5b06aecefff2da424982c7e4ff588140c09e6a0c Mon Sep 17 00:00:00 2001 From: zhengwr Date: Mon, 22 Jun 2026 14:14:26 +0800 Subject: [PATCH 1/3] =?UTF-8?q?feat(cli):=20eip4=20init=20=E4=B8=80?= =?UTF-8?q?=E9=94=AE=E6=8E=A5=E5=85=A5=20Claude=20Code/Codex/OpenCode=20(G?= =?UTF-8?q?1)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增 eip4 init:把 agent skills 装到目标项目 - Claude Code → .claude/skills//SKILL.md(代码生成 frontmatter) - Codex/OpenCode → 根 AGENTS.md(EIP4-SKILLS 标记块,内嵌 skill 全文,块外保留,幂等) - base URL 按 --base-url/--env/current env 渲染 - docs/skills/*.md 的 base URL 改为 {{EIP4_BASE_URL}} 占位符 - 新增 eip4-skills/manifest.json + pom 用 maven-resources-plugin 把 docs/skills 打进 jar(init 默认从 classpath 读,无需仓库在场) - 文档:AI_AGENT_Nocobase_INTEGRATION_GAP_AND_PLAN(NocoBase 对照 + G1-G3 计划)、skills/README、平台 README - TDD 5 个新测试,platform-cli 共 20 单测全绿;真实 jar 端到端验证通过 Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 9 +- ...AGENT_Nocobase_INTEGRATION_GAP_AND_PLAN.md | 148 ++++++++++++++++++ docs/skills/README.md | 23 +++ docs/skills/eip4-ai-feature-development.md | 14 +- docs/skills/eip4-env-manage.md | 6 +- docs/skills/eip4-release-manage.md | 4 +- platform-cli/pom.xml | 27 ++++ .../java/com/eip4/platform/cli/Eip4Cli.java | 115 ++++++++++++++ .../main/resources/eip4-skills/manifest.json | 19 +++ .../com/eip4/platform/cli/Eip4CliTest.java | 127 +++++++++++++++ 10 files changed, 478 insertions(+), 14 deletions(-) create mode 100644 docs/AI_AGENT_Nocobase_INTEGRATION_GAP_AND_PLAN.md create mode 100644 platform-cli/src/main/resources/eip4-skills/manifest.json diff --git a/README.md b/README.md index 32d5139..a297d50 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ EIP4 平台正式工程(路线 A'):双层制模块化单体——**保真层供 | platform-converter | 模板转换器(P4) | 可独立 CLI 跑批 | | platform-flow-gateway | P3 占位:Flowable 网关 | | | platform-ai | P5 AI Agent 开发底座:草稿/变更包/本地门禁/自动修复/人工部署包 | Agent 不直连线上执行生产变更 | -| platform-cli | EIP4 Agent 受控命令入口:环境探测、AI 自动开发、后续发布编排 | Agent 优先通过 CLI/API 操作 | +| platform-cli | EIP4 Agent 受控命令入口:`init` 一键接入(Claude Code/Codex/OpenCode)、环境探测、AI 自动开发、发布编排 | Agent 优先通过 CLI/API 操作 | | platform-parity | C1 对拍框架:录制/重放/RowDiff/自对拍 CLI | P1 一级交付物 | | platform-app | Boot 启动器,组装全部模块 | ArchUnit 规则在此模块测试里 | @@ -81,6 +81,13 @@ mvn -pl platform-parity exec:java -Dexec.mainClass="com.eip4.platform.parity.sel 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//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 <你的项目> + 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 diff --git a/docs/AI_AGENT_Nocobase_INTEGRATION_GAP_AND_PLAN.md b/docs/AI_AGENT_Nocobase_INTEGRATION_GAP_AND_PLAN.md new file mode 100644 index 0000000..913bb40 --- /dev/null +++ b/docs/AI_AGENT_Nocobase_INTEGRATION_GAP_AND_PLAN.md @@ -0,0 +1,148 @@ +# EIP4 对照 NocoBase 的 AI Agent 接入差距与补齐计划 + +日期:2026-06-22 + +本文回答一个具体问题:**外部 coding agent(Claude Code / Codex / Cursor / OpenCode)接入平台做开发这件事,EIP4 和 NocoBase 现在差在哪、要补什么。** + +口径限定:只谈「外部 agent 驱动确定性开发」这条线(EIP4 称 ①面)。平台内置生成式 LLM(②面)受对外承诺红线约束,单列在「四、不做的部分」,本文不展开。 + +前序文档: +- `AI_AGENT_Nocobase_ADOPTION_PLAN.md`(2026-06-17 借鉴路线,P0–P5) +- `AI_AGENT_Nocobase_SOURCE_REVIEW.md`(2026-06-17 源码级对照) +- 本文是上述两份在「接入体验」维度的增量,已对齐 NocoBase 2026 现状(AI employees 加 Skills、新增 MCP server plugin)。 + +NocoBase 参考: +- AI Builder:https://docs.nocobase.com/ai-builder/ +- Skills 仓库:https://github.com/nocobase/skills +- AI Employees / MCP:https://docs.nocobase.com/ai-employees/ ,https://docs.nocobase.com/ai-employees/features/mcp +- LLM Service:https://v2.docs.nocobase.com/ai-employees/features/llm-service + +--- + +## 一、一句话结论 + +EIP4 和 NocoBase 的**核心判断一致**:AI 不从零生成代码,而是在已过生产验证的 no-code 底座上操作元数据/页面/流程,人审控制生产变更。EIP4 ①面 v1 已交付、骨架完整;**差距全在「接入体验」而非「架构方向」**:NocoBase 把接入做成了一键安装 + 标准 MCP 协议,EIP4 还停在「手动喂 md + agent 死记 CLI」。补齐这层,EIP4 的外部 agent 接入即可达到 NocoBase 同等顺滑度。 + +--- + +## 二、现状对照(带证据) + +### EIP4 已有的接入资产(基线) + +| 资产 | 证据 | 状态 | +|---|---|---| +| 确定性生成主链路 | `platform-ai/.../service/AiFeatureDraftGenerator.java`、`AiAgentService.java`、`AiLocalReleaseExecutor.java` | ✅ 已合 main | +| CLI(可运行 jar) | `platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar`;命令族 `env` / `ai` / `release` | ✅ | +| Skills 规程 | `docs/skills/`:`README.md` + `eip4-env-manage` + `eip4-ai-feature-development` + `eip4-release-manage` | ⚠️ 仅 4 个,且只是仓库文档 | +| REST API | `/api/ai/*`、`/api/design/*`、`/api/meta/*`、`/api/page/schema/{components,validate,overlay}` | ✅ | +| Typed schema 门禁 | `POST /api/page/schema/validate`、overlay 保存前强制校验 | ✅ | +| AI 工具/权限注册表 | `GET /api/ai/tools`、`/api/ai/employees`、`POST /api/ai/tools/access-check` | ✅(注册表层,非运行时调度)| +| 人审红线 | `AiDeploymentPackage.requiresHumanApproval=true`、状态恒 `READY_FOR_HUMAN_REVIEW` | ✅ | +| 版本/回滚 | `eip4 ai revision`、`eip4 release rollback-plan`(只生成计划不执行)| ✅ | + +### EIP4 CLI 命令清单(核实自 `Eip4Cli.java`) + +``` +eip4 env add | list | use | current | status +eip4 ai auto-develop | feature-package | revision +eip4 release diff | export | import-preview | rollback-plan | verify +``` +**注意:没有 `init`,也没有 `skills install/check/update`。** 这是和 NocoBase 的关键体验差。 + +### 逐项对照 + +| 维度 | NocoBase(2026 现状) | EIP4(现状) | 差距 | +|---|---|---|---| +| 核心理念:AI 在 no-code 底座工作、不从零生成 | ✅ | ✅ | 无(同源)| +| 外部 agent 接入门槛 | `nb init --ui` **自动安装 ~13 个 Skills**,`cd && claude` 直连 | 需人工把 `docs/skills/*.md` 复制/引用给 agent | **大** → G1 | +| Skills 覆盖面 | ~13:env / data-modeling / ui-builder / workflow / acl / plugin-manage / publish / revision / plugin-dev / data-analysis … | 4:env / ai-feature / release | **中** → G3 | +| Skills 安装与校验 | CLI 安装/检查/更新(`skills install`)| 无,纯仓库文档 | 中 → G3 | +| MCP server(外部 AI 用标准协议操作平台)| ✅ 已有 MCP server plugin(2026 新增)| ❌ 仅 `AiArtifactType.java:6` 一行注释 | **大** → G2 | +| CLI 命令族 | `nb` env/pm/revision/publish | `eip4` env/ai/release | 小(基本对齐)| +| 人审确认 | Skill Permission(Ask / Allow)| `READY_FOR_HUMAN_REVIEW` + `requiresHumanApproval` | 无(机制等价)| +| 版本/回滚 | `nb revision` | `eip4 ai revision` / `release rollback-plan` | 无 | +| 端口/连接配置一致性 | `nb init` 引导写入 | skills 文档写 `8084`,实际环境跑 `8093/8094` | **小但扎手** → G1 | +| 内置 LLM / AI employees(②面)| ✅ 接 OpenAI/Claude/Gemini/DeepSeek/Qwen/Ollama | ❌ 刻意不做(repair 钩子默认关)| 受红线约束 → 见「四」| + +--- + +## 三、补齐计划(按对外接入体验优先级) + +### G1 — 一键接入体验(P0,最快见效)✅ 已完成(2026-06-22) + +**问题**:接入要人工搬运 md + agent 不知道端口,第一步就劝退。 + +**做什么**: +1. 新增 `eip4 init`(或独立脚本 `scripts/install-skills.sh`),把 `docs/skills/*.md` 安装到各 agent 能自动读取的位置: + - Claude Code:`.claude/skills/`(或写入项目 `CLAUDE.md` 引用块) + - Codex:项目根 `AGENTS.md` + - OpenCode:其 agent 规则/上下文目录 +2. 安装时把 skills 里的 `--base-url` 占位符**用当前 env registry 的 current env 渲染**(解决 `8084` vs `8093/8094` 不一致)。 +3. 安装完打印「下一步:`cd && claude`」引导,对齐 NocoBase 体验。 + +**验收**: +- 一条命令后,新开 Claude Code 会话能识别 `eip4-ai-feature-development` skill,并据此跑通 `eip4 ai auto-develop` 产出 `READY_FOR_HUMAN_REVIEW` 包。 +- skills 文档内端口与实际启动端口一致,agent 不再连错。 + +**成本**:小(1 个 CLI 子命令 + 文本渲染 + 端口统一)。 + +**落地(2026-06-22)**:`eip4 init` 已实现于 `platform-cli`(`Eip4Cli.runInit`),TDD 4 个新测试 + 原有共 19 单测全绿。配套:`docs/skills/*.md` 的 base URL 改为 `{{EIP4_BASE_URL}}` 占位符;新增 `platform-cli/src/main/resources/eip4-skills/manifest.json`(skill 清单 + name/description);`pom.xml` 用 maven-resources-plugin 把 `docs/skills` 打进 jar。真实 jar 端到端验证通过:`init` 产出 `.claude/skills//SKILL.md`(带 frontmatter)+ 根 `AGENTS.md`(`EIP4-SKILLS` 标记块,块外内容保留、可重复执行,且**内嵌每个 skill 渲染后全文**——Claude Code 用 `.claude/skills/` 原生 skill,Codex/OpenCode 读 `AGENTS.md` 即得完整规程,三工具全覆盖),base URL 按 `--base-url`/`--env`/current env 渲染,零占位符残留。skills 随 jar 打包,`init` 默认从 classpath 读取,无需仓库在场。 + +### G2 — MCP server(P1,接入面标准化) + +**问题**:现在 agent 要靠 skill 文档「死记」CLI/REST 用法;NocoBase 已用 MCP 把能力做成可发现、可调用的标准工具。 + +**做什么**:起一个 **EIP4 MCP server** 最小骨架,把已有端点包成 MCP tools(stdio + streamable HTTP 两种 transport,对齐 NocoBase): +- `eip4.auto_develop` → `POST /api/ai/features/auto-develop` +- `eip4.list_page_recipes` → `GET /api/ai/page-recipes` +- `eip4.validate_page_schema` → `POST /api/page/schema/validate` +- `eip4.list_components` → `GET /api/page/schema/components` +- `eip4.access_check` → `POST /api/ai/tools/access-check` +- (只读)`eip4.list_entities` / `eip4.entity_attributes` → `/api/meta/*` + +红线沿用:所有写工具走本地 env;生产写默认阻断;产物恒 `READY_FOR_HUMAN_REVIEW`。MCP 工具粒度 1:1 复用现有 `AiToolRegistry` 的 scope 与 `access-check`,不新开权限面。 + +**验收**: +- Claude Code / Codex 通过 MCP 连上后 `list tools` 能看到上述 eip4 工具。 +- 通过 MCP 调 `eip4.auto_develop` 能产出待人审部署包,证据与 CLI 路径一致。 + +**成本**:中(一个独立 server 进程;建议先 stdio + 复用 REST,不重写业务)。 + +### G3 — Skills 覆盖面 + 安装/检查(P1) + +**问题**:4 个 skill 覆盖不到「建模/选 recipe/权限/服务流诊断」等高频动作,agent 仍要猜。 + +**做什么**: +1. 补 skills(对标 NocoBase 但只覆盖 EIP4 真实能力,不照搬不存在的功能): + - `eip4-data-modeling`(建实体/字段/引用列,映射 `/api/meta/entity`) + - `eip4-page-recipe`(三种 recipe:maintenance-crud-v1 / tree-crud-v1 / master-detail-v1 的选用与字段约束) + - `eip4-acl-manage`(菜单授权/角色,映射 `/api/admin/*`) + - `eip4-serviceflow-diagnose`(默认流生成与排错) +2. 给 CLI 加 `eip4 skills list/check`,校验本地已安装 skill 版本与仓库是否一致。 + +**验收**:agent 不再询问「表怎么建 / recipe 怎么选 / 权限怎么配」即可独立完成一个新功能。 + +**成本**:中(主要是文档 + 一个 CLI 校验命令)。 + +--- + +## 四、不做的部分(红线) + +- **平台不内置生成式 LLM(②面)**:NocoBase 做了内置 AI employees + LLM Service(OpenAI/Claude/Gemini/DeepSeek/Qwen/Ollama)。EIP4 进程内唯一 LLM 是 `HttpAiLlmRepairClient`,`@ConditionalOnProperty(...repair.enabled,"true")` **默认关,且只修不生成**。是否立②面 = v1 之后的产品决策,本文不推进。 +- **终点恒人审**:任何接入路径产物都停在 `READY_FOR_HUMAN_REVIEW`,生产写默认阻断。G1–G3 不得绕过该门禁。 +- **对外口径**:限「AI 辅助、人工复核」;严禁承诺「AI 全自动开发 / 人力大幅下降」(决策会纪要商务条款③)。 + +--- + +## 五、建议执行顺序 + +1. **G1 一键接入**(P0,半天级):投入最小、最快让 claude code/codex 真正能用上 EIP4。 +2. **G2 MCP server 最小骨架**(P1):把接入面标准化,去掉「agent 死记用法」。 +3. **G3 Skills 补全**(P1,可与 G2 并行):提升 agent 自主完成度。 +4. ②面(内置 LLM)维持观望,待产品对红线拍板。 + +--- + +## 六、与既有路线图的关系 + +本文 G1–G3 落在 `AI_AGENT_Nocobase_ADOPTION_PLAN.md` 的 P1(受控入口/Skills)与 P5(MCP 白名单)之间,是把当时「第一版完成」的接入层提升到 NocoBase 2026 的体验基线。`SOURCE_REVIEW.md` P5 未完成项明确列了「MCP 工具白名单」「Skills CLI check/update」——本文 G2/G3 即其落地化。进度以 `项目进度与路线-总览-2026-06-21.md` 为准,落地后回写该总览。 diff --git a/docs/skills/README.md b/docs/skills/README.md index 3aaf5ac..d0423fa 100644 --- a/docs/skills/README.md +++ b/docs/skills/README.md @@ -10,6 +10,29 @@ | `eip4-ai-feature-development` | 从自然语言需求生成实体、服务流、页面、菜单和本地 smoke | | `eip4-release-manage` | 部署包、人审、发布前校验和回滚边界 | +## 快速接入(一键安装) + +用 `eip4 init` 把这些 skills 安装到目标项目,供 Claude Code / Codex / OpenCode 直接读取。skill 示例里的 base URL 会按当前环境自动渲染(不再硬编码 8084/8093): + +```bash +# 可选:先登记环境地址(init 会用 current env 渲染示例端口) +java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar env add \ + --name local --base-url http://localhost:8094 --use + +# 一键安装 skills + 生成 AGENTS.md +java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar init --base-url http://localhost:8094 + +# 然后在该目录启动你的 agent +cd && claude +``` + +产出: + +- `.claude/skills//SKILL.md`:Claude Code 原生 skill(自带 frontmatter)。 +- `AGENTS.md`:Codex / OpenCode 共用入口,内容受 `EIP4-SKILLS` 标记块管理(块外内容不动,可重复执行)。块内**内嵌每个 skill 的完整正文**,因此 Codex / OpenCode 只读 `AGENTS.md` 即可拿到全部规程,不依赖 `.claude/skills/`。 + +参数:`--dir` 目标项目根(默认当前目录)、`--base-url` 或 `--env` 指定渲染地址、`--skills-dir` 用本地目录覆盖内置 skills。skills 已随 `platform-cli` jar 一起打包,`init` 默认从 jar 内读取,无需仓库在场。 + ## 通用原则 1. 优先使用 `platform-cli`,其次使用公开 REST API,最后才考虑人工 SQL。 diff --git a/docs/skills/eip4-ai-feature-development.md b/docs/skills/eip4-ai-feature-development.md index c22d071..e30e151 100644 --- a/docs/skills/eip4-ai-feature-development.md +++ b/docs/skills/eip4-ai-feature-development.md @@ -37,7 +37,7 @@ ENABLED:启用:boolean::false ```bash java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar ai auto-develop \ - --base-url http://localhost:8084 \ + --base-url {{EIP4_BASE_URL}} \ --objective "新增客户等级维护功能" \ --feature-name "客户等级维护" \ --table-name EIP4AI_CUSTOMER_LEVEL \ @@ -56,7 +56,7 @@ java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar ai auto-develop \ ```bash java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar ai auto-develop \ - --base-url http://localhost:8084 \ + --base-url {{EIP4_BASE_URL}} \ --objective "新增组织分类树形维护功能" \ --feature-name "组织分类维护" \ --table-name EIP4AI_ORG_CATEGORY \ @@ -83,9 +83,9 @@ java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar ai auto-develop \ ## 页面 schema 校验 ```bash -curl http://localhost:8084/api/page/schema/components +curl {{EIP4_BASE_URL}}/api/page/schema/components -curl -X POST http://localhost:8084/api/page/schema/validate \ +curl -X POST {{EIP4_BASE_URL}}/api/page/schema/validate \ -H "Content-Type: application/json" \ --data-binary @target/ai-runs/page-schema.json ``` @@ -95,10 +95,10 @@ curl -X POST http://localhost:8084/api/page/schema/validate \ ## AI 工具权限检查 ```bash -curl http://localhost:8084/api/ai/tools -curl http://localhost:8084/api/ai/employees +curl {{EIP4_BASE_URL}}/api/ai/tools +curl {{EIP4_BASE_URL}}/api/ai/employees -curl -X POST http://localhost:8084/api/ai/tools/access-check \ +curl -X POST {{EIP4_BASE_URL}}/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}' ``` diff --git a/docs/skills/eip4-env-manage.md b/docs/skills/eip4-env-manage.md index c8e07d0..84ffe26 100644 --- a/docs/skills/eip4-env-manage.md +++ b/docs/skills/eip4-env-manage.md @@ -10,15 +10,13 @@ 1. 确认当前目录是否是独立 worktree,避免污染用户正在做的任务。 2. 使用 JDK 21,不能使用 JDK 26。 -3. 默认本地 profile: - - `local`: `http://localhost:8084` - - `dev`: `http://localhost:8093` +3. 默认本地 base URL 由 `eip4 init` 渲染,当前环境为 `{{EIP4_BASE_URL}}`;多套环境用 `eip4 env add/use` 管理。 4. 使用 CLI 探测环境: ```bash java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar env add \ --name local \ - --base-url http://localhost:8084 \ + --base-url {{EIP4_BASE_URL}} \ --kind local \ --use diff --git a/docs/skills/eip4-release-manage.md b/docs/skills/eip4-release-manage.md index 94621a8..9094290 100644 --- a/docs/skills/eip4-release-manage.md +++ b/docs/skills/eip4-release-manage.md @@ -17,7 +17,7 @@ ```bash java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar ai feature-package \ - --base-url http://localhost:8084 \ + --base-url {{EIP4_BASE_URL}} \ --task-id ait-xxx \ --change-set-id aics-xxx \ --output target/ai-runs/feature-package.json @@ -27,7 +27,7 @@ java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar ai feature-package ```bash java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar ai revision \ - --base-url http://localhost:8084 \ + --base-url {{EIP4_BASE_URL}} \ --task-id ait-xxx \ --package-id aipkg-xxx \ --note "本地门禁通过,待人工部署" \ diff --git a/platform-cli/pom.xml b/platform-cli/pom.xml index 653ebd3..393354a 100644 --- a/platform-cli/pom.xml +++ b/platform-cli/pom.xml @@ -51,6 +51,33 @@ + + org.apache.maven.plugins + maven-resources-plugin + + + copy-agent-skills + process-resources + + copy-resources + + + ${project.build.outputDirectory}/eip4-skills + + + ${project.basedir}/../docs/skills + + *.md + + + README.md + + + + + + + diff --git a/platform-cli/src/main/java/com/eip4/platform/cli/Eip4Cli.java b/platform-cli/src/main/java/com/eip4/platform/cli/Eip4Cli.java index 2005082..6f17b8d 100644 --- a/platform-cli/src/main/java/com/eip4/platform/cli/Eip4Cli.java +++ b/platform-cli/src/main/java/com/eip4/platform/cli/Eip4Cli.java @@ -1,6 +1,7 @@ package com.eip4.platform.cli; import java.io.IOException; +import java.io.InputStream; import java.io.PrintStream; import java.net.URI; import java.nio.charset.StandardCharsets; @@ -60,6 +61,7 @@ public final class Eip4Cli { return 0; } return switch (args[0]) { + case "init" -> runInit(args, out, err); case "env" -> runEnv(args, out, err); case "ai" -> runAi(args, out, err); case "release" -> runRelease(args, out, err); @@ -689,6 +691,119 @@ public final class Eip4Cli { return new CliTarget("", Eip4EnvStore.normalizeBaseUrl(value)); } + private int runInit(String[] args, PrintStream out, PrintStream err) throws IOException { + if (args.length >= 2 && isHelp(args[1])) { + printInitHelp(out); + return 0; + } + Options options = Options.parse(args, 1); + String baseUrl = baseUrl(options); + Path targetDir = Path.of(options.single("dir") == null ? "." : options.single("dir")); + SkillSource source = skillSource(options.single("skills-dir")); + + String manifestJson = source.read("manifest.json"); + if (manifestJson == null) { + return fail(err, "找不到 skills manifest.json(--skills-dir 指向的目录或内置资源缺失)"); + } + JsonNode manifest = objectMapper.readTree(manifestJson); + Path claudeSkills = targetDir.resolve(".claude").resolve("skills"); + StringBuilder catalog = new StringBuilder(); + StringBuilder bodies = new StringBuilder(); + int installed = 0; + for (JsonNode skill : manifest.path("skills")) { + String file = skill.path("file").asText(); + String name = skill.path("name").asText(); + String description = skill.path("description").asText(); + String body = source.read(file); + if (body == null) { + return fail(err, "缺少 skill 文件: " + file); + } + String rendered = body.replace("{{EIP4_BASE_URL}}", baseUrl); + Path skillDir = claudeSkills.resolve(name); + Files.createDirectories(skillDir); + String doc = "---\nname: " + name + "\ndescription: " + description + "\n---\n\n" + rendered; + Files.writeString(skillDir.resolve("SKILL.md"), doc, StandardCharsets.UTF_8); + catalog.append("- **").append(name).append("** — ").append(description).append('\n'); + bodies.append("\n---\n\n### Skill: ").append(name).append("\n\n").append(rendered).append('\n'); + installed++; + } + Path agents = writeAgentsMd(targetDir, baseUrl, catalog.toString(), bodies.toString()); + out.println("Installed " + installed + " EIP4 skill(s) for Claude Code at " + claudeSkills); + out.println("Updated " + agents + " for Codex / OpenCode"); + out.println("baseUrl: " + baseUrl); + out.println("Next: cd " + targetDir + " && claude"); + return 0; + } + + private static final String SKILLS_BEGIN = ""; + private static final String SKILLS_END = ""; + + private Path writeAgentsMd(Path targetDir, String baseUrl, String catalog, String bodies) throws IOException { + String block = SKILLS_BEGIN + "\n" + + "## EIP4 平台接入(AI Agent)\n\n" + + "Base URL: " + baseUrl + "\n\n" + + "已安装 skills(Claude Code 见 `.claude/skills/`;以下内嵌完整正文,供 Codex / OpenCode 使用):\n" + + catalog + "\n" + + "通用原则:优先用 `platform-cli`,其次 REST API;本地写默认放行、生产写阻断;" + + "AI 产物恒为 READY_FOR_HUMAN_REVIEW,需人工复核后发布。\n" + + bodies + + SKILLS_END + "\n"; + Path agents = targetDir.resolve("AGENTS.md"); + String updated; + if (Files.exists(agents)) { + String existing = Files.readString(agents, StandardCharsets.UTF_8); + int begin = existing.indexOf(SKILLS_BEGIN); + int end = existing.indexOf(SKILLS_END); + if (begin >= 0 && end > begin) { + updated = existing.substring(0, begin) + block + + existing.substring(end + SKILLS_END.length()).replaceFirst("^\\R", ""); + } else { + String sep = existing.isEmpty() || existing.endsWith("\n\n") + ? "" : (existing.endsWith("\n") ? "\n" : "\n\n"); + updated = existing + sep + block; + } + } else { + Files.createDirectories(targetDir); + updated = "# AGENTS\n\nEIP4 项目的 AI Agent 接入说明。\n\n" + block; + } + Files.writeString(agents, updated, StandardCharsets.UTF_8); + return agents; + } + + private SkillSource skillSource(String skillsDir) { + if (skillsDir != null && !skillsDir.isBlank()) { + Path dir = Path.of(skillsDir); + return name -> { + Path file = dir.resolve(name); + return Files.exists(file) ? Files.readString(file, StandardCharsets.UTF_8) : null; + }; + } + return name -> { + try (InputStream in = Eip4Cli.class.getResourceAsStream("/eip4-skills/" + name)) { + return in == null ? null : new String(in.readAllBytes(), StandardCharsets.UTF_8); + } + }; + } + + @FunctionalInterface + private interface SkillSource { + String read(String name) throws IOException; + } + + private void printInitHelp(PrintStream out) { + out.println(""" + Usage: + eip4 init [--dir DIR] [--base-url URL|--env NAME] [--skills-dir DIR] + + Installs EIP4 agent skills so Claude Code / Codex / OpenCode can drive + the platform. Renders the configured base URL into the skill examples. + --dir target project root (default: current directory) + --base-url base URL to render (default: current env, then http://localhost:8084) + --env use a configured env's base URL + --skills-dir read skills from a directory instead of the bundled set + """); + } + private void ensureCrossEnvConfirmed(Options options) throws IOException { String envName = options.single("env"); if (envName == null || envName.isBlank() || options.has("yes")) { diff --git a/platform-cli/src/main/resources/eip4-skills/manifest.json b/platform-cli/src/main/resources/eip4-skills/manifest.json new file mode 100644 index 0000000..3cb7312 --- /dev/null +++ b/platform-cli/src/main/resources/eip4-skills/manifest.json @@ -0,0 +1,19 @@ +{ + "skills": [ + { + "file": "eip4-env-manage.md", + "name": "eip4-env-manage", + "description": "EIP4 环境探测、启动检查、端口与 profile 边界" + }, + { + "file": "eip4-ai-feature-development.md", + "name": "eip4-ai-feature-development", + "description": "从自然语言需求生成实体、服务流、页面、菜单并跑本地 smoke" + }, + { + "file": "eip4-release-manage.md", + "name": "eip4-release-manage", + "description": "EIP4 部署包、人审、发布前校验与回滚边界" + } + ] +} diff --git a/platform-cli/src/test/java/com/eip4/platform/cli/Eip4CliTest.java b/platform-cli/src/test/java/com/eip4/platform/cli/Eip4CliTest.java index 2eed1ad..2c6cb67 100644 --- a/platform-cli/src/test/java/com/eip4/platform/cli/Eip4CliTest.java +++ b/platform-cli/src/test/java/com/eip4/platform/cli/Eip4CliTest.java @@ -381,6 +381,133 @@ class Eip4CliTest { assertTrue(result.err().contains("rollbackSqlStatements 仍包含")); } + @Test + void initRendersClaudeSkillWithRenderedBaseUrl() throws Exception { + Path skillsDir = writeSkillsFixture(); + Path target = tempDir.resolve("proj"); + + CliResult result = run(new CapturingClient(new Eip4HttpResponse(200, "{}")), + "init", + "--dir", target.toString(), + "--skills-dir", skillsDir.toString(), + "--base-url", "http://localhost:8093"); + + assertEquals(0, result.code()); + Path skill = target.resolve(".claude/skills/eip4-demo/SKILL.md"); + assertTrue(Files.exists(skill)); + String content = Files.readString(skill, StandardCharsets.UTF_8); + assertTrue(content.startsWith("---"), "should carry YAML frontmatter"); + assertTrue(content.contains("name: eip4-demo")); + assertTrue(content.contains("description: 演示用 skill")); + assertTrue(content.contains("http://localhost:8093/api/ai/features/auto-develop")); + assertFalse(content.contains("{{EIP4_BASE_URL}}"), "placeholder must be rendered"); + } + + @Test + void initGeneratesAgentsMdWithSkillCatalog() throws Exception { + Path skillsDir = writeSkillsFixture(); + Path target = tempDir.resolve("proj"); + + CliResult result = run(new CapturingClient(new Eip4HttpResponse(200, "{}")), + "init", + "--dir", target.toString(), + "--skills-dir", skillsDir.toString(), + "--base-url", "http://localhost:8093"); + + assertEquals(0, result.code()); + Path agents = target.resolve("AGENTS.md"); + assertTrue(Files.exists(agents)); + String md = Files.readString(agents, StandardCharsets.UTF_8); + assertTrue(md.contains("EIP4-SKILLS:BEGIN"), "should carry a managed marker block"); + assertTrue(md.contains("EIP4-SKILLS:END")); + assertTrue(md.contains("eip4-demo")); + assertTrue(md.contains("演示用 skill")); + assertTrue(md.contains("http://localhost:8093")); + } + + @Test + void initUsesCurrentEnvBaseUrlWhenNoFlag() throws Exception { + Path skillsDir = writeSkillsFixture(); + Path target = tempDir.resolve("proj"); + Eip4EnvStore store = tempStore(); + run(store, new CapturingClient(new Eip4HttpResponse(200, "{}")), + "env", "add", "--name", "dev", "--base-url", "http://localhost:8093", "--use"); + + CliResult result = run(store, new CapturingClient(new Eip4HttpResponse(200, "{}")), + "init", + "--dir", target.toString(), + "--skills-dir", skillsDir.toString()); + + assertEquals(0, result.code()); + String content = Files.readString( + target.resolve(".claude/skills/eip4-demo/SKILL.md"), StandardCharsets.UTF_8); + assertTrue(content.contains("http://localhost:8093"), "should fall back to current env base URL"); + } + + @Test + void initPreservesUserContentOutsideMarkerBlock() throws Exception { + Path skillsDir = writeSkillsFixture(); + Path target = tempDir.resolve("proj"); + Files.createDirectories(target); + Files.writeString(target.resolve("AGENTS.md"), + "# My project\n\n用户自定义说明,必须保留。\n", StandardCharsets.UTF_8); + + CliResult result = run(new CapturingClient(new Eip4HttpResponse(200, "{}")), + "init", + "--dir", target.toString(), + "--skills-dir", skillsDir.toString(), + "--base-url", "http://localhost:8093"); + + assertEquals(0, result.code()); + String md = Files.readString(target.resolve("AGENTS.md"), StandardCharsets.UTF_8); + assertTrue(md.contains("# My project"), "user heading must survive"); + assertTrue(md.contains("用户自定义说明,必须保留。"), "user content must survive"); + assertTrue(md.contains("EIP4-SKILLS:BEGIN"), "managed block must be injected"); + assertEquals(1, md.split("EIP4-SKILLS:BEGIN", -1).length - 1, "exactly one managed block"); + } + + @Test + void initEmbedsFullSkillBodyIntoAgentsMd() throws Exception { + Path skillsDir = writeSkillsFixture(); + Path target = tempDir.resolve("proj"); + + CliResult result = run(new CapturingClient(new Eip4HttpResponse(200, "{}")), + "init", + "--dir", target.toString(), + "--skills-dir", skillsDir.toString(), + "--base-url", "http://localhost:8093"); + + assertEquals(0, result.code()); + String md = Files.readString(target.resolve("AGENTS.md"), StandardCharsets.UTF_8); + // Codex / OpenCode read AGENTS.md, not .claude/skills — the full body must be inline. + assertTrue(md.contains("eip4 ai auto-develop"), "AGENTS.md should embed the full skill body"); + assertTrue(md.contains("http://localhost:8093/api/ai/features/auto-develop"), + "embedded body must also be rendered"); + } + + private Path writeSkillsFixture() throws Exception { + Path dir = tempDir.resolve("skills-src"); + Files.createDirectories(dir); + Files.writeString(dir.resolve("manifest.json"), """ + { + "skills": [ + {"file": "eip4-demo.md", "name": "eip4-demo", "description": "演示用 skill"} + ] + } + """, StandardCharsets.UTF_8); + Files.writeString(dir.resolve("eip4-demo.md"), """ + # Skill: eip4-demo + + 调用示例: + + ```bash + eip4 ai auto-develop --base-url {{EIP4_BASE_URL}} + curl {{EIP4_BASE_URL}}/api/ai/features/auto-develop + ``` + """, StandardCharsets.UTF_8); + return dir; + } + private Path validPackageFile(String name) throws Exception { return packageFile(name, "aipkg-1", "insert into sys_page_schema values ('x')", From 4a2080a4f64f471ffd161cc953e93296db9b78b8 Mon Sep 17 00:00:00 2001 From: zhengwr Date: Mon, 22 Jun 2026 14:37:02 +0800 Subject: [PATCH 2/3] =?UTF-8?q?feat(mcp):=20platform-mcp=20=E2=80=94?= =?UTF-8?q?=E2=80=94=20EIP4=20MCP=20server=20=E6=A0=87=E5=87=86=E6=8E=A5?= =?UTF-8?q?=E5=85=A5=20Claude=20Code/Codex/OpenCode=20(G2)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增 platform-mcp 模块(stdio MCP server,MCP Java SDK 1.1.0 / jackson2 路线) - 注册 7 个 MCP 工具:eip4_auto_develop / list_page_recipes / validate_page_schema / list_components / access_check / list_entities / entity_attributes 忠实转发 EIP4 REST,复用人审红线(产物恒 READY_FOR_HUMAN_REVIEW),不另开权限面 - 工具逻辑 TDD(Eip4McpTools 9 单测,注入 mock REST client) - 真实 stdio JSON-RPC e2e:initialize 协商 + tools/list 返回 7 工具(schema 正确) + tools/call 链路(死端口优雅 isError) - 坑:父 pom 为 amis 校验钉死 networknt 1.5.2,与 MCP 需要的 2.0.0(含 dialect.Dialects) 冲突 → platform-mcp 显式覆盖 2.0.0(仅本模块) - 文档:GAP 标记 G2 完成、平台 README + skills/README 加 MCP 接入说明 接入:claude mcp add eip4 -- java -jar platform-mcp/target/platform-mcp-0.1.0-SNAPSHOT.jar --base-url Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 6 + ...AGENT_Nocobase_INTEGRATION_GAP_AND_PLAN.md | 4 +- docs/skills/README.md | 12 ++ platform-mcp/pom.xml | 71 +++++++ .../com/eip4/platform/mcp/Eip4McpServer.java | 90 +++++++++ .../com/eip4/platform/mcp/Eip4McpTools.java | 178 ++++++++++++++++++ .../com/eip4/platform/mcp/Eip4RestClient.java | 15 ++ .../eip4/platform/mcp/JdkEip4RestClient.java | 48 +++++ .../eip4/platform/mcp/Eip4McpToolsTest.java | 143 ++++++++++++++ pom.xml | 14 ++ 10 files changed, 580 insertions(+), 1 deletion(-) create mode 100644 platform-mcp/pom.xml create mode 100644 platform-mcp/src/main/java/com/eip4/platform/mcp/Eip4McpServer.java create mode 100644 platform-mcp/src/main/java/com/eip4/platform/mcp/Eip4McpTools.java create mode 100644 platform-mcp/src/main/java/com/eip4/platform/mcp/Eip4RestClient.java create mode 100644 platform-mcp/src/main/java/com/eip4/platform/mcp/JdkEip4RestClient.java create mode 100644 platform-mcp/src/test/java/com/eip4/platform/mcp/Eip4McpToolsTest.java diff --git a/README.md b/README.md index a297d50..e1e0ac7 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,7 @@ EIP4 平台正式工程(路线 A'):双层制模块化单体——**保真层供 | 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 规则在此模块测试里 | @@ -95,6 +96,11 @@ java -jar platform-cli/target/platform-cli-0.1.0-SNAPSHOT.jar release import-pre 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 \ diff --git a/docs/AI_AGENT_Nocobase_INTEGRATION_GAP_AND_PLAN.md b/docs/AI_AGENT_Nocobase_INTEGRATION_GAP_AND_PLAN.md index 913bb40..80fc5c1 100644 --- a/docs/AI_AGENT_Nocobase_INTEGRATION_GAP_AND_PLAN.md +++ b/docs/AI_AGENT_Nocobase_INTEGRATION_GAP_AND_PLAN.md @@ -88,7 +88,7 @@ eip4 release diff | export | import-preview | rollback-plan | verify **落地(2026-06-22)**:`eip4 init` 已实现于 `platform-cli`(`Eip4Cli.runInit`),TDD 4 个新测试 + 原有共 19 单测全绿。配套:`docs/skills/*.md` 的 base URL 改为 `{{EIP4_BASE_URL}}` 占位符;新增 `platform-cli/src/main/resources/eip4-skills/manifest.json`(skill 清单 + name/description);`pom.xml` 用 maven-resources-plugin 把 `docs/skills` 打进 jar。真实 jar 端到端验证通过:`init` 产出 `.claude/skills//SKILL.md`(带 frontmatter)+ 根 `AGENTS.md`(`EIP4-SKILLS` 标记块,块外内容保留、可重复执行,且**内嵌每个 skill 渲染后全文**——Claude Code 用 `.claude/skills/` 原生 skill,Codex/OpenCode 读 `AGENTS.md` 即得完整规程,三工具全覆盖),base URL 按 `--base-url`/`--env`/current env 渲染,零占位符残留。skills 随 jar 打包,`init` 默认从 classpath 读取,无需仓库在场。 -### G2 — MCP server(P1,接入面标准化) +### G2 — MCP server(P1,接入面标准化)✅ 已完成(2026-06-22) **问题**:现在 agent 要靠 skill 文档「死记」CLI/REST 用法;NocoBase 已用 MCP 把能力做成可发现、可调用的标准工具。 @@ -108,6 +108,8 @@ eip4 release diff | export | import-preview | rollback-plan | verify **成本**:中(一个独立 server 进程;建议先 stdio + 复用 REST,不重写业务)。 +**落地(2026-06-22)**:新增 `platform-mcp` 模块(stdio MCP server,MCP Java SDK 1.1.0 / jackson2 路线)。`McpServer.sync(StdioServerTransportProvider).tools(...).build()`,注册 7 个工具:`eip4_auto_develop / list_page_recipes / validate_page_schema / list_components / access_check / list_entities / entity_attributes`,忠实转发 EIP4 REST,复用人审红线、不另开权限面。工具逻辑 TDD(`Eip4McpTools` 9 单测,注入 mock REST client);真实 stdio JSON-RPC e2e 通过:`initialize` 协商 + `tools/list` 返回 7 工具(inputSchema 正确解析)+ `tools/call` 链路(死端口优雅 isError)。坑:父 pom 为 amis 校验钉死 `networknt:json-schema-validator:1.5.2`,与 MCP 需要的 `2.0.0`(含 `dialect.Dialects`)冲突 → 在 platform-mcp 显式覆盖 2.0.0(仅本模块)。接入:`claude mcp add eip4 -- java -jar platform-mcp/target/platform-mcp-0.1.0-SNAPSHOT.jar --base-url `。 + ### G3 — Skills 覆盖面 + 安装/检查(P1) **问题**:4 个 skill 覆盖不到「建模/选 recipe/权限/服务流诊断」等高频动作,agent 仍要猜。 diff --git a/docs/skills/README.md b/docs/skills/README.md index d0423fa..f2f73e8 100644 --- a/docs/skills/README.md +++ b/docs/skills/README.md @@ -33,6 +33,18 @@ cd && claude 参数:`--dir` 目标项目根(默认当前目录)、`--base-url` 或 `--env` 指定渲染地址、`--skills-dir` 用本地目录覆盖内置 skills。skills 已随 `platform-cli` jar 一起打包,`init` 默认从 jar 内读取,无需仓库在场。 +## MCP 接入(标准协议) + +除 skills + CLI 外,EIP4 还提供 MCP server(`platform-mcp`,stdio),把 `eip4_auto_develop / eip4_list_page_recipes / eip4_validate_page_schema / eip4_list_components / eip4_access_check / eip4_list_entities / eip4_entity_attributes` 暴露为 MCP 工具,让 Agent 用标准协议调用,而不必死记 CLI/REST 用法: + +```bash +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:8094 +# 或设环境变量 EIP4_BASE_URL;默认 http://localhost:8084 +``` + +工具忠实转发到平台 REST,复用人审红线(产物恒 `READY_FOR_HUMAN_REVIEW`)与 `access-check`;MCP server 应只配本地/开发 baseUrl,不另开权限面。 + ## 通用原则 1. 优先使用 `platform-cli`,其次使用公开 REST API,最后才考虑人工 SQL。 diff --git a/platform-mcp/pom.xml b/platform-mcp/pom.xml new file mode 100644 index 0000000..add4da1 --- /dev/null +++ b/platform-mcp/pom.xml @@ -0,0 +1,71 @@ + + + 4.0.0 + + com.eip4 + eip4-platform + 0.1.0-SNAPSHOT + + platform-mcp + platform-mcp + EIP4 MCP server:把 AI/元数据 REST 端点包成 MCP 工具,供 Claude Code/Codex/OpenCode 经 stdio 接入;复用 env/baseUrl 与人审红线 + + + + io.modelcontextprotocol.sdk + mcp-core + + + io.modelcontextprotocol.sdk + mcp-json-jackson2 + + + com.fasterxml.jackson.core + jackson-databind + + + + com.networknt + json-schema-validator + 2.0.0 + + + org.junit.jupiter + junit-jupiter + test + + + + + + + org.apache.maven.plugins + maven-assembly-plugin + 3.7.1 + + + + com.eip4.platform.mcp.Eip4McpServer + + + + jar-with-dependencies + + false + + + + make-assembly + package + + single + + + + + + + diff --git a/platform-mcp/src/main/java/com/eip4/platform/mcp/Eip4McpServer.java b/platform-mcp/src/main/java/com/eip4/platform/mcp/Eip4McpServer.java new file mode 100644 index 0000000..2e2c8f4 --- /dev/null +++ b/platform-mcp/src/main/java/com/eip4/platform/mcp/Eip4McpServer.java @@ -0,0 +1,90 @@ +package com.eip4.platform.mcp; + +import java.util.ArrayList; +import java.util.List; +import java.util.Map; +import java.util.concurrent.CountDownLatch; + +import com.fasterxml.jackson.databind.ObjectMapper; + +import io.modelcontextprotocol.json.McpJsonMapper; +import io.modelcontextprotocol.json.jackson2.JacksonMcpJsonMapper; +import io.modelcontextprotocol.server.McpServer; +import io.modelcontextprotocol.server.McpServerFeatures.SyncToolSpecification; +import io.modelcontextprotocol.server.McpSyncServer; +import io.modelcontextprotocol.server.transport.StdioServerTransportProvider; +import io.modelcontextprotocol.spec.McpSchema; + +/** + * EIP4 MCP server(stdio):把 EIP4 的 AI / 元数据 REST 端点暴露为 MCP 工具, + * 供 Claude Code / Codex / OpenCode 通过标准协议驱动平台开发。 + * + *

用法:{@code java -jar platform-mcp.jar [--base-url URL]}, + * 或设环境变量 {@code EIP4_BASE_URL};默认 http://localhost:8084。 + * stdout 被 MCP JSON-RPC 占用,日志只走 stderr。 + */ +public final class Eip4McpServer { + + private static final String DEFAULT_BASE_URL = "http://localhost:8084"; + + private Eip4McpServer() { + } + + public static void main(String[] args) throws InterruptedException { + String baseUrl = resolveBaseUrl(args); + ObjectMapper objectMapper = new ObjectMapper(); + McpJsonMapper jsonMapper = new JacksonMcpJsonMapper(objectMapper); + Eip4McpTools tools = new Eip4McpTools(new JdkEip4RestClient(baseUrl, objectMapper), objectMapper); + + List toolSpecs = new ArrayList<>(); + for (Eip4McpTools.McpToolDef def : tools.toolDefs()) { + McpSchema.Tool tool = McpSchema.Tool.builder() + .name(def.name()) + .description(def.description()) + .inputSchema(jsonMapper, def.inputSchemaJson()) + .build(); + toolSpecs.add(SyncToolSpecification.builder() + .tool(tool) + .callHandler((exchange, request) -> { + Map arguments = request.arguments() == null ? Map.of() : request.arguments(); + Eip4McpTools.ToolResult result = def.handler().apply(arguments); + return McpSchema.CallToolResult.builder() + .addTextContent(result.text()) + .isError(result.isError()) + .build(); + }) + .build()); + } + + McpSyncServer server = McpServer.sync(new StdioServerTransportProvider(jsonMapper)) + .serverInfo("eip4", "0.1.0") + .capabilities(McpSchema.ServerCapabilities.builder().tools(true).build()) + .tools(toolSpecs) + .build(); + + System.err.println("EIP4 MCP server started (baseUrl=" + baseUrl + ", tools=" + toolSpecs.size() + ")"); + Runtime.getRuntime().addShutdownHook(new Thread(server::close)); + new CountDownLatch(1).await(); + } + + static String resolveBaseUrl(String[] args) { + for (int i = 0; i < args.length - 1; i++) { + if ("--base-url".equals(args[i])) { + return stripTrailingSlash(args[i + 1]); + } + } + String env = System.getenv("EIP4_BASE_URL"); + if (env != null && !env.isBlank()) { + return stripTrailingSlash(env); + } + return DEFAULT_BASE_URL; + } + + private static String stripTrailingSlash(String value) { + String out = value.trim(); + while (out.endsWith("/")) { + out = out.substring(0, out.length() - 1); + } + return out; + } +} diff --git a/platform-mcp/src/main/java/com/eip4/platform/mcp/Eip4McpTools.java b/platform-mcp/src/main/java/com/eip4/platform/mcp/Eip4McpTools.java new file mode 100644 index 0000000..d6a5240 --- /dev/null +++ b/platform-mcp/src/main/java/com/eip4/platform/mcp/Eip4McpTools.java @@ -0,0 +1,178 @@ +package com.eip4.platform.mcp; + +import java.util.List; +import java.util.Map; +import java.util.function.Function; + +import com.fasterxml.jackson.databind.JsonNode; +import com.fasterxml.jackson.databind.ObjectMapper; +import com.fasterxml.jackson.databind.node.ObjectNode; + +/** + * 把 EIP4 的 AI / 元数据 REST 端点封装成 MCP 工具的纯逻辑层(不依赖 MCP SDK,便于单测)。 + * + *

红线复用:所有工具忠实转发到平台 REST,平台已有的人审门禁(产物恒 READY_FOR_HUMAN_REVIEW)、 + * access-check 与安全门负责权限/生产写控制;本层不另开权限面。MCP server 应只配本地/开发 baseUrl。 + */ +final class Eip4McpTools { + + private static final String EMPTY_SCHEMA = "{\"type\":\"object\",\"properties\":{}}"; + + private final Eip4RestClient client; + private final ObjectMapper mapper; + + Eip4McpTools(Eip4RestClient client, ObjectMapper mapper) { + this.client = client; + this.mapper = mapper; + } + + record ToolResult(String text, boolean isError) { + } + + record McpToolDef(String name, String description, String inputSchemaJson, + Function, ToolResult> handler) { + } + + List toolDefs() { + return List.of( + new McpToolDef("eip4_auto_develop", + "AI 辅助生成一个新功能(实体+页面+服务流+菜单)并在本地跑门禁,产出待人工复核的部署包(恒 READY_FOR_HUMAN_REVIEW,生产写由平台阻断)。", + """ + {"type":"object", + "required":["objective","featureName","tableName","entityName","templateId","menuName","fields"], + "properties":{ + "objective":{"type":"string","description":"功能目标"}, + "featureName":{"type":"string"}, + "tableName":{"type":"string","description":"业务表名"}, + "entityName":{"type":"string"}, + "templateId":{"type":"string"}, + "menuName":{"type":"string"}, + "fields":{"type":"array","items":{"type":"object", + "required":["column","label","type"], + "properties":{"column":{"type":"string"},"label":{"type":"string"}, + "type":{"type":"string"},"length":{"type":"integer"},"required":{"type":"boolean"}}}}, + "pageRecipe":{"type":"string","enum":["maintenance-crud-v1","tree-crud-v1","master-detail-v1"],"default":"maintenance-crud-v1"}, + "maxRepairAttempts":{"type":"integer","default":2}, + "generateDeploymentPackage":{"type":"boolean","default":true}}} + """, + this::autoDevelop), + new McpToolDef("eip4_list_page_recipes", + "列出可用的页面 recipe(maintenance-crud-v1 / tree-crud-v1 / master-detail-v1)。", + EMPTY_SCHEMA, this::listPageRecipes), + new McpToolDef("eip4_list_components", + "列出 typed page schema 注册的组件能力表(AI 只能使用其中的组件/动作)。", + EMPTY_SCHEMA, this::listComponents), + new McpToolDef("eip4_validate_page_schema", + "对一个 amis 页面 schema 做 typed schema 离线校验(不写库)。", + """ + {"type":"object","required":["schema"], + "properties":{"schema":{"type":"object","description":"待校验的 amis 页面 schema"}}} + """, + this::validatePageSchema), + new McpToolDef("eip4_access_check", + "检查某 AI employee 对某工具/目标环境的权限(生产写默认阻断)。", + """ + {"type":"object","required":["employeeId","toolName","targetEnv"], + "properties":{"employeeId":{"type":"string"},"toolName":{"type":"string"}, + "grantedScopes":{"type":"array","items":{"type":"string"}}, + "targetEnv":{"type":"string"},"productionWrite":{"type":"boolean"}}} + """, + this::accessCheck), + new McpToolDef("eip4_list_entities", + "列出已登记的元数据实体。", + EMPTY_SCHEMA, this::listEntities), + new McpToolDef("eip4_entity_attributes", + "查询某业务表的字段(实体属性)。", + """ + {"type":"object","required":["table"], + "properties":{"table":{"type":"string","description":"业务表名"}}} + """, + this::entityAttributes)); + } + + ToolResult autoDevelop(Map args) { + ObjectNode feature = mapper.createObjectNode(); + feature.put("objective", str(args, "objective")); + feature.put("featureName", str(args, "featureName")); + feature.put("tableName", str(args, "tableName")); + feature.put("entityName", str(args, "entityName")); + feature.put("templateId", str(args, "templateId")); + feature.put("menuName", str(args, "menuName")); + feature.put("pageRecipe", strOr(args, "pageRecipe", "maintenance-crud-v1")); + feature.set("fields", mapper.valueToTree(args.getOrDefault("fields", List.of()))); + ObjectNode body = mapper.createObjectNode(); + body.set("feature", feature); + body.put("generateDeploymentPackage", boolOr(args, "generateDeploymentPackage", true)); + body.put("maxRepairAttempts", intOr(args, "maxRepairAttempts", 2)); + return forward("POST", "/api/ai/features/auto-develop", body); + } + + ToolResult listPageRecipes(Map args) { + return forward("GET", "/api/ai/page-recipes", null); + } + + ToolResult listComponents(Map args) { + return forward("GET", "/api/page/schema/components", null); + } + + ToolResult listEntities(Map args) { + return forward("GET", "/api/meta/entities", null); + } + + ToolResult validatePageSchema(Map args) { + return forward("POST", "/api/page/schema/validate", mapper.valueToTree(args.get("schema"))); + } + + ToolResult accessCheck(Map args) { + return forward("POST", "/api/ai/tools/access-check", mapper.valueToTree(args)); + } + + ToolResult entityAttributes(Map args) { + return forward("GET", "/api/meta/entity/" + str(args, "table") + "/attributes", null); + } + + private ToolResult forward(String method, String path, JsonNode body) { + Eip4RestClient.Response response = client.send(method, path, body); + boolean error = response.status() < 200 || response.status() >= 300; + String text = error + ? "EIP4 " + method + " " + path + " 返回 HTTP " + response.status() + ":\n" + response.body() + : response.body(); + return new ToolResult(text, error); + } + + private static String str(Map args, String key) { + Object value = args.get(key); + if (value == null) { + throw new IllegalArgumentException("缺少参数: " + key); + } + return String.valueOf(value); + } + + private static String strOr(Map args, String key, String fallback) { + Object value = args.get(key); + return value == null || String.valueOf(value).isBlank() ? fallback : String.valueOf(value); + } + + private static boolean boolOr(Map args, String key, boolean fallback) { + Object value = args.get(key); + if (value instanceof Boolean b) { + return b; + } + return value == null ? fallback : Boolean.parseBoolean(String.valueOf(value)); + } + + private static int intOr(Map args, String key, int fallback) { + Object value = args.get(key); + if (value instanceof Number n) { + return n.intValue(); + } + if (value == null) { + return fallback; + } + try { + return Integer.parseInt(String.valueOf(value)); + } catch (NumberFormatException ex) { + return fallback; + } + } +} diff --git a/platform-mcp/src/main/java/com/eip4/platform/mcp/Eip4RestClient.java b/platform-mcp/src/main/java/com/eip4/platform/mcp/Eip4RestClient.java new file mode 100644 index 0000000..61bf513 --- /dev/null +++ b/platform-mcp/src/main/java/com/eip4/platform/mcp/Eip4RestClient.java @@ -0,0 +1,15 @@ +package com.eip4.platform.mcp; + +import com.fasterxml.jackson.databind.JsonNode; + +/** + * EIP4 REST 调用抽象,便于单测注入。path 是相对 baseUrl 的路径(以 / 开头)。 + * body 为 null 表示无请求体(GET)。 + */ +interface Eip4RestClient { + + Response send(String method, String path, JsonNode body); + + record Response(int status, String body) { + } +} diff --git a/platform-mcp/src/main/java/com/eip4/platform/mcp/JdkEip4RestClient.java b/platform-mcp/src/main/java/com/eip4/platform/mcp/JdkEip4RestClient.java new file mode 100644 index 0000000..4e92882 --- /dev/null +++ b/platform-mcp/src/main/java/com/eip4/platform/mcp/JdkEip4RestClient.java @@ -0,0 +1,48 @@ +package com.eip4.platform.mcp; + +import java.net.URI; +import java.net.http.HttpClient; +import java.net.http.HttpRequest; +import java.net.http.HttpResponse; +import java.time.Duration; + +import com.fasterxml.jackson.databind.JsonNode; +import com.fasterxml.jackson.databind.ObjectMapper; + +/** 基于 JDK HttpClient 的 EIP4 REST 调用实现。 */ +final class JdkEip4RestClient implements Eip4RestClient { + + private final HttpClient http = HttpClient.newBuilder() + .connectTimeout(Duration.ofSeconds(10)) + .build(); + private final ObjectMapper mapper; + private final String baseUrl; + + JdkEip4RestClient(String baseUrl, ObjectMapper mapper) { + this.baseUrl = baseUrl; + this.mapper = mapper; + } + + @Override + public Response send(String method, String path, JsonNode body) { + try { + HttpRequest.Builder builder = HttpRequest.newBuilder() + .uri(URI.create(baseUrl + path)) + .timeout(Duration.ofSeconds(60)) + .header("Accept", "application/json"); + if (body == null) { + builder.method(method, HttpRequest.BodyPublishers.noBody()); + } else { + builder.header("Content-Type", "application/json") + .method(method, HttpRequest.BodyPublishers.ofString(mapper.writeValueAsString(body))); + } + HttpResponse response = http.send(builder.build(), HttpResponse.BodyHandlers.ofString()); + return new Response(response.statusCode(), response.body()); + } catch (InterruptedException ex) { + Thread.currentThread().interrupt(); + return new Response(599, "请求被中断: " + ex.getMessage()); + } catch (Exception ex) { + return new Response(599, "请求失败(baseUrl=" + baseUrl + "): " + ex); + } + } +} diff --git a/platform-mcp/src/test/java/com/eip4/platform/mcp/Eip4McpToolsTest.java b/platform-mcp/src/test/java/com/eip4/platform/mcp/Eip4McpToolsTest.java new file mode 100644 index 0000000..4424d27 --- /dev/null +++ b/platform-mcp/src/test/java/com/eip4/platform/mcp/Eip4McpToolsTest.java @@ -0,0 +1,143 @@ +package com.eip4.platform.mcp; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.util.List; +import java.util.Map; + +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; + +import com.fasterxml.jackson.databind.JsonNode; +import com.fasterxml.jackson.databind.ObjectMapper; + +class Eip4McpToolsTest { + + private final ObjectMapper mapper = new ObjectMapper(); + private CapturingClient client; + private Eip4McpTools tools; + + @BeforeEach + void setUp() { + client = new CapturingClient(); + tools = new Eip4McpTools(client, mapper); + } + + @Test + void autoDevelopPostsAssembledFeatureToEndpoint() { + client.response = new Eip4RestClient.Response(200, "{\"status\":\"READY_FOR_HUMAN_REVIEW\"}"); + + Eip4McpTools.ToolResult result = tools.autoDevelop(Map.of( + "objective", "新增客户等级维护", + "featureName", "客户等级维护", + "tableName", "EIP4AI_CUSTOMER_LEVEL", + "entityName", "客户等级", + "templateId", "eip4ai-customer-level", + "menuName", "客户等级维护", + "fields", List.of(Map.of("column", "NAME", "label", "名称", "type", "string")))); + + assertEquals("POST", client.method); + assertEquals("/api/ai/features/auto-develop", client.path); + assertEquals("EIP4AI_CUSTOMER_LEVEL", client.body.path("feature").path("tableName").asText()); + assertEquals(1, client.body.path("feature").path("fields").size()); + assertEquals("NAME", client.body.path("feature").path("fields").get(0).path("column").asText()); + assertTrue(client.body.path("generateDeploymentPackage").asBoolean(), "default: generate deployment package"); + assertFalse(result.isError()); + assertTrue(result.text().contains("READY_FOR_HUMAN_REVIEW")); + } + + @Test + void autoDevelopDefaultsPageRecipeWhenMissing() { + tools.autoDevelop(Map.of( + "objective", "x", "featureName", "f", "tableName", "T", + "entityName", "E", "templateId", "t", "menuName", "M", + "fields", List.of(Map.of("column", "C", "label", "标签", "type", "string")))); + assertEquals("maintenance-crud-v1", client.body.path("feature").path("pageRecipe").asText()); + } + + @Test + void listPageRecipesGetsEndpoint() { + client.response = new Eip4RestClient.Response(200, "[\"maintenance-crud-v1\",\"tree-crud-v1\"]"); + Eip4McpTools.ToolResult result = tools.listPageRecipes(Map.of()); + assertEquals("GET", client.method); + assertEquals("/api/ai/page-recipes", client.path); + assertFalse(result.isError()); + assertTrue(result.text().contains("tree-crud-v1")); + } + + @Test + void listComponentsAndEntitiesUseReadEndpoints() { + tools.listComponents(Map.of()); + assertEquals("GET", client.method); + assertEquals("/api/page/schema/components", client.path); + + tools.listEntities(Map.of()); + assertEquals("GET", client.method); + assertEquals("/api/meta/entities", client.path); + } + + @Test + void entityAttributesBuildsPathFromTableArg() { + tools.entityAttributes(Map.of("table", "OA_NOTICE")); + assertEquals("GET", client.method); + assertEquals("/api/meta/entity/OA_NOTICE/attributes", client.path); + } + + @Test + void validatePageSchemaPostsRawSchema() { + tools.validatePageSchema(Map.of("schema", Map.of("type", "page", "body", List.of()))); + assertEquals("POST", client.method); + assertEquals("/api/page/schema/validate", client.path); + assertEquals("page", client.body.path("type").asText()); + } + + @Test + void accessCheckPostsToToolsAccessCheck() { + tools.accessCheck(Map.of( + "employeeId", "agent-developer", + "toolName", "local.apply", + "targetEnv", "local", + "productionWrite", false)); + assertEquals("POST", client.method); + assertEquals("/api/ai/tools/access-check", client.path); + assertEquals("agent-developer", client.body.path("employeeId").asText()); + } + + @Test + void nonSuccessStatusMarksError() { + client.response = new Eip4RestClient.Response(500, "boom"); + Eip4McpTools.ToolResult result = tools.listPageRecipes(Map.of()); + assertTrue(result.isError()); + assertTrue(result.text().contains("boom")); + } + + @Test + void toolDefsCoverAllSevenToolsWithSchema() { + List names = tools.toolDefs().stream().map(Eip4McpTools.McpToolDef::name).toList(); + assertTrue(names.contains("eip4_auto_develop")); + assertTrue(names.contains("eip4_list_page_recipes")); + assertTrue(names.contains("eip4_list_components")); + assertTrue(names.contains("eip4_validate_page_schema")); + assertTrue(names.contains("eip4_access_check")); + assertTrue(names.contains("eip4_list_entities")); + assertTrue(names.contains("eip4_entity_attributes")); + tools.toolDefs().forEach(d -> assertFalse(d.inputSchemaJson().isBlank(), "schema required: " + d.name())); + } + + private static final class CapturingClient implements Eip4RestClient { + private Response response = new Response(200, "{}"); + private String method; + private String path; + private JsonNode body; + + @Override + public Response send(String method, String path, JsonNode body) { + this.method = method; + this.path = path; + this.body = body; + return response; + } + } +} diff --git a/pom.xml b/pom.xml index b8f7daa..c90d921 100644 --- a/pom.xml +++ b/pom.xml @@ -26,6 +26,7 @@ platform-converter platform-ai platform-cli + platform-mcp platform-parity platform-app @@ -81,6 +82,19 @@ platform-parity ${project.version} + + com.eip4 + platform-mcp + ${project.version} + + + + io.modelcontextprotocol.sdk + mcp-bom + 1.1.0 + pom + import + org.dom4j From 8a6c94ebde78fe833fc94a720b8e111d82e1f71c Mon Sep 17 00:00:00 2001 From: zhengwr Date: Mon, 22 Jun 2026 14:47:31 +0800 Subject: [PATCH 3/3] =?UTF-8?q?feat(cli):=20eip4=20skills=20list/check=20+?= =?UTF-8?q?=203=20=E4=B8=AA=E6=96=B0=20agent=20skill=20(G3)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增 skill(均基于源码核实过的端点): - eip4-data-modeling — /api/meta/entity 建实体/加字段/引用列/主子表 - eip4-page-recipe — /api/design/recipe/compile 生成默认页(维护/树/主子表) - eip4-acl-manage — /api/admin/* 菜单/角色/用户组授权 manifest.json + jar 打包同步,docs/skills 现共 6 个 - CLI 新增 eip4 skills list(列内置 skills)+ skills check --dir(缺失退出非 0) - TDD 2 个新测试,platform-cli 共 22 单测全绿 - 真实验证:skills list 列 6 个 / init 装 6 个 / skills check 全 installed(exit 0)/ 端口渲染零占位符残留 - serviceflow-diagnose 暂缓:平台无「查看/诊断服务流定义」的 agent 可操作端点(需先补端点) Co-Authored-By: Claude Opus 4.8 (1M context) --- ...AGENT_Nocobase_INTEGRATION_GAP_AND_PLAN.md | 4 +- docs/skills/README.md | 12 ++++ docs/skills/eip4-acl-manage.md | 30 ++++++++ docs/skills/eip4-data-modeling.md | 53 ++++++++++++++ docs/skills/eip4-page-recipe.md | 44 ++++++++++++ .../java/com/eip4/platform/cli/Eip4Cli.java | 69 +++++++++++++++++++ .../main/resources/eip4-skills/manifest.json | 15 ++++ .../com/eip4/platform/cli/Eip4CliTest.java | 30 ++++++++ 8 files changed, 256 insertions(+), 1 deletion(-) create mode 100644 docs/skills/eip4-acl-manage.md create mode 100644 docs/skills/eip4-data-modeling.md create mode 100644 docs/skills/eip4-page-recipe.md diff --git a/docs/AI_AGENT_Nocobase_INTEGRATION_GAP_AND_PLAN.md b/docs/AI_AGENT_Nocobase_INTEGRATION_GAP_AND_PLAN.md index 80fc5c1..25b5578 100644 --- a/docs/AI_AGENT_Nocobase_INTEGRATION_GAP_AND_PLAN.md +++ b/docs/AI_AGENT_Nocobase_INTEGRATION_GAP_AND_PLAN.md @@ -110,7 +110,7 @@ eip4 release diff | export | import-preview | rollback-plan | verify **落地(2026-06-22)**:新增 `platform-mcp` 模块(stdio MCP server,MCP Java SDK 1.1.0 / jackson2 路线)。`McpServer.sync(StdioServerTransportProvider).tools(...).build()`,注册 7 个工具:`eip4_auto_develop / list_page_recipes / validate_page_schema / list_components / access_check / list_entities / entity_attributes`,忠实转发 EIP4 REST,复用人审红线、不另开权限面。工具逻辑 TDD(`Eip4McpTools` 9 单测,注入 mock REST client);真实 stdio JSON-RPC e2e 通过:`initialize` 协商 + `tools/list` 返回 7 工具(inputSchema 正确解析)+ `tools/call` 链路(死端口优雅 isError)。坑:父 pom 为 amis 校验钉死 `networknt:json-schema-validator:1.5.2`,与 MCP 需要的 `2.0.0`(含 `dialect.Dialects`)冲突 → 在 platform-mcp 显式覆盖 2.0.0(仅本模块)。接入:`claude mcp add eip4 -- java -jar platform-mcp/target/platform-mcp-0.1.0-SNAPSHOT.jar --base-url `。 -### G3 — Skills 覆盖面 + 安装/检查(P1) +### G3 — Skills 覆盖面 + 安装/检查(P1)✅ 基本完成(2026-06-22,serviceflow 诊断暂缓) **问题**:4 个 skill 覆盖不到「建模/选 recipe/权限/服务流诊断」等高频动作,agent 仍要猜。 @@ -126,6 +126,8 @@ eip4 release diff | export | import-preview | rollback-plan | verify **成本**:中(主要是文档 + 一个 CLI 校验命令)。 +**落地(2026-06-22)**:新增 3 个 skill(`eip4-data-modeling` / `eip4-page-recipe` / `eip4-acl-manage`,全部基于核实过的 `/api/meta/entity`、`/api/design/recipe/compile`、`/api/admin/*` 端点写就),manifest + jar 打包同步,`docs/skills` 现共 6 个。CLI 新增 `eip4 skills list`(列内置 skills)+ `eip4 skills check --dir`(检测目标项目已装/缺失,缺失退出非 0),TDD 2 新测试、platform-cli 共 22 单测全绿。真实验证:`skills list` 列 6 个、`init` 装 6 个、`skills check` 全 installed(exit 0)、新 skill 端口正确渲染零占位符残留。**`serviceflow-diagnose` 暂缓**:经源码核实平台没有「查看/诊断服务流定义」的 agent 可操作端点(仅能 `POST/GET /api/flow/{id}` 执行 + 看 FlowController 日志),需先补「查看流定义」端点才值得做,否则只能写出无法落地的规程。 + --- ## 四、不做的部分(红线) diff --git a/docs/skills/README.md b/docs/skills/README.md index f2f73e8..2f30c92 100644 --- a/docs/skills/README.md +++ b/docs/skills/README.md @@ -9,6 +9,9 @@ | `eip4-env-manage` | 环境探测、启动检查、端口和 profile 边界 | | `eip4-ai-feature-development` | 从自然语言需求生成实体、服务流、页面、菜单和本地 smoke | | `eip4-release-manage` | 部署包、人审、发布前校验和回滚边界 | +| `eip4-data-modeling` | 建实体/加字段/引用列/主子表(/api/meta/entity) | +| `eip4-page-recipe` | 用 recipe 生成默认页:维护/树/主子表(/api/design/recipe/compile) | +| `eip4-acl-manage` | 菜单/角色/用户组授权(/api/admin/*) | ## 快速接入(一键安装) @@ -33,6 +36,15 @@ cd && claude 参数:`--dir` 目标项目根(默认当前目录)、`--base-url` 或 `--env` 指定渲染地址、`--skills-dir` 用本地目录覆盖内置 skills。skills 已随 `platform-cli` jar 一起打包,`init` 默认从 jar 内读取,无需仓库在场。 +查看与校验已安装的 skills: + +```bash +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 +``` + +`skills check` 在目标项目缺少任一内置 skill 时退出码非 0,便于在 CI/接入脚本里把关。 + ## MCP 接入(标准协议) 除 skills + CLI 外,EIP4 还提供 MCP server(`platform-mcp`,stdio),把 `eip4_auto_develop / eip4_list_page_recipes / eip4_validate_page_schema / eip4_list_components / eip4_access_check / eip4_list_entities / eip4_entity_attributes` 暴露为 MCP 工具,让 Agent 用标准协议调用,而不必死记 CLI/REST 用法: diff --git a/docs/skills/eip4-acl-manage.md b/docs/skills/eip4-acl-manage.md new file mode 100644 index 0000000..c22320c --- /dev/null +++ b/docs/skills/eip4-acl-manage.md @@ -0,0 +1,30 @@ +# Skill: eip4-acl-manage + +## 触发场景 + +- 给角色授菜单、管理用户组 / 角色成员、查看菜单树。 + +## 菜单 + +- `GET {{EIP4_BASE_URL}}/api/admin/menu-all` — 管理视角全量菜单树(`roots[]` 两级,含 `templateId`)。 +- `GET {{EIP4_BASE_URL}}/api/menu` — 当前用户可见菜单树。 +- `GET {{EIP4_BASE_URL}}/api/admin/user/{userId}/menu` — 指定用户可见菜单。 +- 菜单写:`POST {{EIP4_BASE_URL}}/api/admin/menus/create`、`/api/admin/menus/{id}/update`、`/api/admin/menus/{id}/delete`。 + +## 角色授权 + +- `POST {{EIP4_BASE_URL}}/api/admin/roles/{id}/set-menus`,body `{"menuIds": ["..."]}`(整存差量,空数组=清空)。 +- `GET {{EIP4_BASE_URL}}/api/admin/roles/{roleId}/users` — 角色成员。 + +## 用户 / 用户组 + +- `GET {{EIP4_BASE_URL}}/api/admin/users?page=1&perPage=20&keyword=` — 用户分页(密码列不下发)。 +- `POST {{EIP4_BASE_URL}}/api/admin/usergroups/create`,body `{"name","description"}`。 +- `POST {{EIP4_BASE_URL}}/api/admin/usergroups/{id}/update | /delete`。 +- `POST {{EIP4_BASE_URL}}/api/admin/usergroups/{id}/add-user | /remove-user`(幂等)。 +- `POST {{EIP4_BASE_URL}}/api/admin/usergroups/{id}/add-role | /remove-role`。 + +## 红线 + +- 写操作仅管理员,事务性。 +- 授权走「用户组 → 角色 → 菜单」链(`sys_usergrouprole` / `sys_usergroupuser`),不直接给单用户授菜单。 diff --git a/docs/skills/eip4-data-modeling.md b/docs/skills/eip4-data-modeling.md new file mode 100644 index 0000000..b17ca40 --- /dev/null +++ b/docs/skills/eip4-data-modeling.md @@ -0,0 +1,53 @@ +# Skill: eip4-data-modeling + +## 触发场景 + +- 用户要新建业务实体(表)、给已有表加字段。 +- 需要引用列(外键)、主子表结构。 + +## 端点 + +建实体:`POST {{EIP4_BASE_URL}}/api/meta/entity` + +```json +{ + "tablename": "EIP4AI_DEMO", + "name": "演示实体", + "attributes": [ + {"column": "TITLE", "display": "标题", "type": "string", "length": 200, "mandatory": true}, + {"column": "OWNER", "display": "负责人", "type": "reference", "referenceTable": "SYS_USER"} + ], + "tabletype": 0, + "masterTable": "PARENT_TABLE" +} +``` + +- `tablename` 必须 EIP4 前缀,大写,匹配 `[A-Z][A-Z0-9_]{2,40}`。 +- `type`:`string | integer | number | date | datetime | boolean | reference`。 + - `reference` 必带 `referenceTable`,自动生成 CHAR(36) 外键列指向目标表。 +- `tabletype`:`0`=主表 `1`=子表 `2`=中间表;子表用 `masterTable` 指定主表,自动加 `MASTERID` 回链列。 +- 标准列(主键/版本/审计时间/操作人)由引擎自动补齐,**不要手传**。 + +加字段:`POST {{EIP4_BASE_URL}}/api/meta/entity/{table}/attributes`,body 为 `{"attributes":[...]}`。 +- ALTER ADD COLUMN 恒可空(有数据的表加 NOT NULL 会失败)。 + +查询: +- `GET {{EIP4_BASE_URL}}/api/meta/entities` — 实体目录(引用列目标表选择)。 +- `GET {{EIP4_BASE_URL}}/api/meta/entity/{table}` — 单实体属性(columns + displayColumn)。 +- `GET {{EIP4_BASE_URL}}/api/meta/entity-types` — 实体分类。 + +删除:`DELETE {{EIP4_BASE_URL}}/api/meta/entity/{table}`(仅 EIP4 前缀表)。 + +## 命令示例 + +```bash +curl -X POST {{EIP4_BASE_URL}}/api/meta/entity \ + -H "Content-Type: application/json" \ + --data-binary @entity.json +``` + +## 红线 + +- 表名必须 EIP4 前缀,DDL 经 CreateTableSqlGuard / AlterTableSqlGuard / DropTableSqlGuard 强制校验。 +- 建表/加列/删表只对 EIP4 前缀表;生产表禁碰。 +- 不手传标准审计列。 diff --git a/docs/skills/eip4-page-recipe.md b/docs/skills/eip4-page-recipe.md new file mode 100644 index 0000000..a9ade5d --- /dev/null +++ b/docs/skills/eip4-page-recipe.md @@ -0,0 +1,44 @@ +# Skill: eip4-page-recipe + +## 触发场景 + +- 用户要为某实体生成默认页面(维护 / 树 / 主子表)。 +- 需要派生列、父级汇总。 + +## recipe 类型 + +- `maintenance-crud` — 普通维护 CRUD(列表 + 表单)。 +- `tree-crud-v1` — 树形维护(有 parentid 的层级表)。 +- `master-detail-v1` — 主子表(主表 + 子表行内编辑)。 + +## 端点 + +编译生成默认页:`POST {{EIP4_BASE_URL}}/api/design/recipe/compile` + +```json +{ + "tableName": "EIP4_DEMO", + "title": "演示页面", + "recipe": "maintenance-crud", + "pageSize": 20, + "displayField": "NAME", + "childTable": "DEMO_DETAIL", + "linkColumn": "MASTERID", + "childDerived": [{"column": "AMOUNT", "formula": "QTY*PRICE"}], + "childRollup": [{"masterColumn": "TOTAL", "childColumn": "AMOUNT", "agg": "SUM"}] +} +``` + +- `childTable` / `linkColumn` 仅 `master-detail-v1` 需要;`childDerived` / `childRollup` 可选。 +- 生成流程:读实体属性 → 装配编译 → typed schema 严格校验(不过则 400)→ 落标准层(页面唯一真相)。 +- 返回 `data.templateId`。 + +查可用 recipe(经 AI 链路):`GET {{EIP4_BASE_URL}}/api/ai/page-recipes`。 + +校验页面 schema(不写库):`POST {{EIP4_BASE_URL}}/api/page/schema/validate`。 +组件能力表:`GET {{EIP4_BASE_URL}}/api/page/schema/components`。 + +## 红线 + +- schema 只能使用注册过的组件 / 动作;typed 校验会拒未注册组件或不支持的 actionType。 +- 生成 = 落标准层;设计器 overlay 在其上叠加,二者共用同一份 typed schema 校验。 diff --git a/platform-cli/src/main/java/com/eip4/platform/cli/Eip4Cli.java b/platform-cli/src/main/java/com/eip4/platform/cli/Eip4Cli.java index 6f17b8d..8532af0 100644 --- a/platform-cli/src/main/java/com/eip4/platform/cli/Eip4Cli.java +++ b/platform-cli/src/main/java/com/eip4/platform/cli/Eip4Cli.java @@ -62,6 +62,7 @@ public final class Eip4Cli { } return switch (args[0]) { case "init" -> runInit(args, out, err); + case "skills" -> runSkills(args, out, err); case "env" -> runEnv(args, out, err); case "ai" -> runAi(args, out, err); case "release" -> runRelease(args, out, err); @@ -770,6 +771,74 @@ public final class Eip4Cli { return agents; } + private int runSkills(String[] args, PrintStream out, PrintStream err) throws IOException { + if (args.length < 2 || isHelp(args[1])) { + printSkillsHelp(out); + return 0; + } + return switch (args[1]) { + case "list" -> runSkillsList(args, out, err); + case "check" -> runSkillsCheck(args, out, err); + default -> fail(err, "Unknown skills command: " + args[1]); + }; + } + + private int runSkillsList(String[] args, PrintStream out, PrintStream err) throws IOException { + Options options = Options.parse(args, 2); + JsonNode manifest = readSkillsManifest(options, err); + if (manifest == null) { + return 1; + } + for (JsonNode skill : manifest.path("skills")) { + out.println(skill.path("name").asText() + " — " + skill.path("description").asText()); + } + return 0; + } + + private int runSkillsCheck(String[] args, PrintStream out, PrintStream err) throws IOException { + Options options = Options.parse(args, 2); + Path targetDir = Path.of(options.single("dir") == null ? "." : options.single("dir")); + JsonNode manifest = readSkillsManifest(options, err); + if (manifest == null) { + return 1; + } + int missing = 0; + for (JsonNode skill : manifest.path("skills")) { + String name = skill.path("name").asText(); + Path skillFile = targetDir.resolve(".claude").resolve("skills").resolve(name).resolve("SKILL.md"); + boolean installed = Files.exists(skillFile); + out.println((installed ? "[installed] " : "[missing] ") + name); + if (!installed) { + missing++; + } + } + if (missing > 0) { + err.println(missing + " 个 skill 未安装;运行 `eip4 init` 安装。"); + return 1; + } + return 0; + } + + private JsonNode readSkillsManifest(Options options, PrintStream err) throws IOException { + String manifestJson = skillSource(options.single("skills-dir")).read("manifest.json"); + if (manifestJson == null) { + fail(err, "找不到 skills manifest.json(--skills-dir 指向的目录或内置资源缺失)"); + return null; + } + return objectMapper.readTree(manifestJson); + } + + private void printSkillsHelp(PrintStream out) { + out.println(""" + Usage: + eip4 skills list [--skills-dir DIR] + eip4 skills check --dir DIR [--skills-dir DIR] + + list 列出内置(或 --skills-dir 指定)的 agent skills。 + check 检查目标项目 .claude/skills 下已安装/缺失的 skill;有缺失时退出码非 0。 + """); + } + private SkillSource skillSource(String skillsDir) { if (skillsDir != null && !skillsDir.isBlank()) { Path dir = Path.of(skillsDir); diff --git a/platform-cli/src/main/resources/eip4-skills/manifest.json b/platform-cli/src/main/resources/eip4-skills/manifest.json index 3cb7312..718490f 100644 --- a/platform-cli/src/main/resources/eip4-skills/manifest.json +++ b/platform-cli/src/main/resources/eip4-skills/manifest.json @@ -14,6 +14,21 @@ "file": "eip4-release-manage.md", "name": "eip4-release-manage", "description": "EIP4 部署包、人审、发布前校验与回滚边界" + }, + { + "file": "eip4-data-modeling.md", + "name": "eip4-data-modeling", + "description": "建实体/加字段/引用列/主子表(/api/meta/entity)" + }, + { + "file": "eip4-page-recipe.md", + "name": "eip4-page-recipe", + "description": "用 recipe 生成默认页:维护/树/主子表(/api/design/recipe/compile)" + }, + { + "file": "eip4-acl-manage.md", + "name": "eip4-acl-manage", + "description": "菜单/角色/用户组授权(/api/admin/*)" } ] } diff --git a/platform-cli/src/test/java/com/eip4/platform/cli/Eip4CliTest.java b/platform-cli/src/test/java/com/eip4/platform/cli/Eip4CliTest.java index 2c6cb67..c61fe8d 100644 --- a/platform-cli/src/test/java/com/eip4/platform/cli/Eip4CliTest.java +++ b/platform-cli/src/test/java/com/eip4/platform/cli/Eip4CliTest.java @@ -485,6 +485,36 @@ class Eip4CliTest { "embedded body must also be rendered"); } + @Test + void skillsListPrintsBundledSkillNames() throws Exception { + Path skillsDir = writeSkillsFixture(); + CliResult result = run(new CapturingClient(new Eip4HttpResponse(200, "{}")), + "skills", "list", "--skills-dir", skillsDir.toString()); + assertEquals(0, result.code()); + assertTrue(result.out().contains("eip4-demo")); + assertTrue(result.out().contains("演示用 skill")); + } + + @Test + void skillsCheckFlagsMissingThenPassesAfterInit() throws Exception { + Path skillsDir = writeSkillsFixture(); + Path target = tempDir.resolve("proj"); + + CliResult missing = run(new CapturingClient(new Eip4HttpResponse(200, "{}")), + "skills", "check", "--dir", target.toString(), "--skills-dir", skillsDir.toString()); + assertEquals(1, missing.code()); + assertTrue(missing.out().contains("eip4-demo")); + + run(new CapturingClient(new Eip4HttpResponse(200, "{}")), + "init", "--dir", target.toString(), "--skills-dir", skillsDir.toString(), + "--base-url", "http://localhost:8093"); + + CliResult ok = run(new CapturingClient(new Eip4HttpResponse(200, "{}")), + "skills", "check", "--dir", target.toString(), "--skills-dir", skillsDir.toString()); + assertEquals(0, ok.code()); + assertTrue(ok.out().contains("eip4-demo")); + } + private Path writeSkillsFixture() throws Exception { Path dir = tempDir.resolve("skills-src"); Files.createDirectories(dir);