From 8a6c94ebde78fe833fc94a720b8e111d82e1f71c Mon Sep 17 00:00:00 2001 From: zhengwr Date: Mon, 22 Jun 2026 14:47:31 +0800 Subject: [PATCH] =?UTF-8?q?feat(cli):=20eip4=20skills=20list/check=20+=203?= =?UTF-8?q?=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);