diff --git a/docs/skills/eip4-acl-manage.md b/docs/skills/eip4-acl-manage.md index c22320c..af0eb63 100644 --- a/docs/skills/eip4-acl-manage.md +++ b/docs/skills/eip4-acl-manage.md @@ -4,6 +4,8 @@ - 给角色授菜单、管理用户组 / 角色成员、查看菜单树。 +> 调用方式:经 REST(无对应 CLI 子命令),或经 `platform-mcp`(MCP)。非 local 环境需带 `Authorization: Bearer `,取 token 见 `eip4-env-manage`。 + ## 菜单 - `GET {{EIP4_BASE_URL}}/api/admin/menu-all` — 管理视角全量菜单树(`roots[]` 两级,含 `templateId`)。 diff --git a/docs/skills/eip4-data-modeling.md b/docs/skills/eip4-data-modeling.md index b17ca40..3f2dba0 100644 --- a/docs/skills/eip4-data-modeling.md +++ b/docs/skills/eip4-data-modeling.md @@ -5,6 +5,8 @@ - 用户要新建业务实体(表)、给已有表加字段。 - 需要引用列(外键)、主子表结构。 +> 调用方式:经 REST(无对应 CLI 子命令),或经 `platform-mcp`(MCP)。非 local 环境需带 `Authorization: Bearer `,取 token 见 `eip4-env-manage`。 + ## 端点 建实体:`POST {{EIP4_BASE_URL}}/api/meta/entity` diff --git a/docs/skills/eip4-env-manage.md b/docs/skills/eip4-env-manage.md index 84ffe26..b120333 100644 --- a/docs/skills/eip4-env-manage.md +++ b/docs/skills/eip4-env-manage.md @@ -30,6 +30,23 @@ JAVA_HOME=/opt/homebrew/opt/openjdk@21 mvn -pl platform-app -am install -DskipTe /opt/homebrew/opt/openjdk@21/bin/java -jar platform-app/target/platform-app-0.1.0-SNAPSHOT.jar --spring.profiles.active=local ``` +## 鉴权 / Token + +- 非 prod profile(default / local / ci)放行 `/api/**`;本地 `eip4 init` 默认渲染 local,故本地 curl / CLI **无需 token**。 +- prod 或开启 JWT 的环境:`/api/**` 需请求头 `Authorization: Bearer `(`/api/auth/**` 例外,登录本身免令牌)。 +- 取 token(登录响应顶层字段 `token`=JWT、`expireSeconds`=过期秒数;失败 401 仅含 `success:false` + `msg`): + +```bash +TOKEN=$(curl -s -X POST {{EIP4_BASE_URL}}/api/auth/login \ + -H "Content-Type: application/json" \ + -d '{"account":"admin","password":"111111"}' \ + | python3 -c 'import sys,json;print(json.load(sys.stdin)["token"])') + +curl {{EIP4_BASE_URL}}/api/meta/entities -H "Authorization: Bearer $TOKEN" +``` + +> `admin/111111` 为本地 dev 种子账号;按环境替换。 + ## 禁止事项 - 不在用户原始任务目录中直接改动或启动长时间任务,除非用户明确要求。 diff --git a/docs/skills/eip4-page-recipe.md b/docs/skills/eip4-page-recipe.md index a9ade5d..87c91da 100644 --- a/docs/skills/eip4-page-recipe.md +++ b/docs/skills/eip4-page-recipe.md @@ -5,9 +5,13 @@ - 用户要为某实体生成默认页面(维护 / 树 / 主子表)。 - 需要派生列、父级汇总。 +> 调用方式:经 REST(无对应 CLI 子命令),或经 `platform-mcp`(MCP)。非 local 环境需带 `Authorization: Bearer `,取 token 见 `eip4-env-manage`。 + ## recipe 类型 -- `maintenance-crud` — 普通维护 CRUD(列表 + 表单)。 +权威列表以 `GET {{EIP4_BASE_URL}}/api/ai/page-recipes` 为准;当前三种(id 带 `-v1`,须逐字传,端点精确匹配,不接受省略 `-v1` 的别名): + +- `maintenance-crud-v1` — 普通维护 CRUD(列表 + 表单)。 - `tree-crud-v1` — 树形维护(有 parentid 的层级表)。 - `master-detail-v1` — 主子表(主表 + 子表行内编辑)。 @@ -19,7 +23,7 @@ { "tableName": "EIP4_DEMO", "title": "演示页面", - "recipe": "maintenance-crud", + "recipe": "maintenance-crud-v1", "pageSize": 20, "displayField": "NAME", "childTable": "DEMO_DETAIL", 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 8532af0..063cdfa 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 @@ -745,8 +745,14 @@ public final class Eip4Cli { + "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" + + "接入方式:① Claude Code 读 `.claude/skills/`;② Codex / OpenCode 读本文件内嵌正文;" + + "③ 可选——把 `platform-mcp` 注册为 stdio MCP server:" + + "`java -jar platform-mcp/target/platform-mcp-0.1.0-SNAPSHOT.jar --base-url " + baseUrl + "`" + + "(7 个工具转发同一套 REST 并保留人审)。\n\n" + + "通用原则:env / ai / release 类操作用 `platform-cli`;建模 / 页面 / 授权类用 REST 或 `platform-mcp`" + + "(无对应 CLI 子命令)。非 local 环境先 `POST " + baseUrl + "/api/auth/login` 取顶层 `token`," + + "每个请求带 `Authorization: Bearer `(详见 eip4-env-manage)。" + + "本地写默认放行、生产写阻断;AI 产物恒为 READY_FOR_HUMAN_REVIEW,需人工复核后发布。\n" + bodies + SKILLS_END + "\n"; Path agents = targetDir.resolve("AGENTS.md"); 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 c61fe8d..7faa7f7 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,70 @@ class Eip4CliTest { "embedded body must also be rendered"); } + @Test + void agentsMdDocumentsMcpAndTokenAccess() throws Exception { + // AGENTS.md (Codex/OpenCode 受众) 必须点名第三接入面 platform-mcp,并给出非 local 环境 + // 的 token 获取方式 + 头部,否则 agent 指向受保护 env 会 401 且无指引。 + Path skillsDir = writeSkillsFixture(); + Path target = tempDir.resolve("proj"); + run(new CapturingClient(new Eip4HttpResponse(200, "{}")), + "init", "--dir", target.toString(), "--skills-dir", skillsDir.toString(), + "--base-url", "http://localhost:8093"); + + String md = Files.readString(target.resolve("AGENTS.md"), StandardCharsets.UTF_8); + assertTrue(md.contains("platform-mcp"), "AGENTS.md should point to the MCP server surface"); + assertTrue(md.contains("/api/auth/login"), "AGENTS.md should document how to obtain a token"); + assertTrue(md.contains("Authorization: Bearer"), "AGENTS.md should document the auth header"); + } + + @Test + void initInstallsAllBundledSkillsWithoutDrift() throws Exception { + // No --skills-dir: exercises the REAL bundled /eip4-skills resources (manifest + + // bodies copied from docs/skills by maven copy-resources). Guards manifest↔body drift: + // a renamed/missing body makes runInit fail (缺少 skill 文件 → 非 0); an entry without a + // body never installs. The synthetic-fixture tests above can't catch either case. + Path target = tempDir.resolve("proj"); + + CliResult result = run(new CapturingClient(new Eip4HttpResponse(200, "{}")), + "init", + "--dir", target.toString(), + "--base-url", "http://localhost:8093"); + + assertEquals(0, result.code(), "bundled init must succeed: " + result.out()); + + JsonNode manifest = objectMapper.readTree( + getClass().getResourceAsStream("/eip4-skills/manifest.json")); + JsonNode skills = manifest.path("skills"); + assertTrue(skills.size() >= 1, "bundled manifest must list skills"); + for (JsonNode skill : skills) { + String name = skill.path("name").asText(); + String description = skill.path("description").asText(); + assertFalse(name.isBlank(), "manifest skill name must be set"); + assertFalse(description.isBlank(), "manifest skill description must be set: " + name); + Path installed = target.resolve(".claude/skills/" + name + "/SKILL.md"); + assertTrue(Files.exists(installed), "bundled skill not installed: " + name); + } + assertTrue(result.out().contains("Installed " + skills.size() + " EIP4 skill"), + "should install exactly every manifest entry"); + } + + @Test + void pageRecipeSkillUsesVersionedRecipeIds() throws Exception { + // Regression guard: the compile endpoint exact-matches `maintenance-crud-v1`; the skill + // must not ship the un-versioned `maintenance-crud` (would 400 an agent that copies it). + Path target = tempDir.resolve("proj"); + run(new CapturingClient(new Eip4HttpResponse(200, "{}")), + "init", "--dir", target.toString(), "--base-url", "http://localhost:8093"); + + String body = Files.readString( + target.resolve(".claude/skills/eip4-page-recipe/SKILL.md"), StandardCharsets.UTF_8); + assertTrue(body.contains("maintenance-crud-v1"), "must document the versioned recipe id"); + assertFalse(body.contains("\"recipe\": \"maintenance-crud\""), + "must not ship the un-versioned recipe example (endpoint would 400)"); + assertFalse(body.contains("`maintenance-crud`"), + "must not list the un-versioned recipe id"); + } + @Test void skillsListPrintsBundledSkillNames() throws Exception { Path skillsDir = writeSkillsFixture();