feat(cli): eip4 skills list/check + 3 个新 agent skill (G3)

- 新增 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) <noreply@anthropic.com>
This commit is contained in:
2026-06-22 14:47:31 +08:00
parent 4a2080a4f6
commit 8a6c94ebde
8 changed files with 256 additions and 1 deletions

View File

@@ -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 <env>`。
### 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 日志),需先补「查看流定义」端点才值得做,否则只能写出无法落地的规程。
---
## 四、不做的部分(红线)

View File

@@ -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 <project> && 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 <project>
```
`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 用法:

View File

@@ -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`),不直接给单用户授菜单。

View File

@@ -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 前缀表;生产表禁碰。
- 不手传标准审计列。

View File

@@ -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 校验。

View File

@@ -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);

View File

@@ -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/*)"
}
]
}

View File

@@ -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);