Merge feat/agent-onboarding-followup: agent 接入补全 + amis-pitfalls skill
修 page-recipe recipe-id 400 bug、补 token/MCP/REST 分流接入说明、 新增 eip4-amis-pitfalls skill,并加 bundled skills 防漂移测试。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -4,6 +4,8 @@
|
|||||||
|
|
||||||
- 给角色授菜单、管理用户组 / 角色成员、查看菜单树。
|
- 给角色授菜单、管理用户组 / 角色成员、查看菜单树。
|
||||||
|
|
||||||
|
> 调用方式:经 REST(无对应 CLI 子命令),或经 `platform-mcp`(MCP)。非 local 环境需带 `Authorization: Bearer <token>`,取 token 见 `eip4-env-manage`。
|
||||||
|
|
||||||
## 菜单
|
## 菜单
|
||||||
|
|
||||||
- `GET {{EIP4_BASE_URL}}/api/admin/menu-all` — 管理视角全量菜单树(`roots[]` 两级,含 `templateId`)。
|
- `GET {{EIP4_BASE_URL}}/api/admin/menu-all` — 管理视角全量菜单树(`roots[]` 两级,含 `templateId`)。
|
||||||
|
|||||||
59
docs/skills/eip4-amis-pitfalls.md
Normal file
59
docs/skills/eip4-amis-pitfalls.md
Normal file
@@ -0,0 +1,59 @@
|
|||||||
|
# Skill: eip4-amis-pitfalls
|
||||||
|
|
||||||
|
EIP4 前端用 amis(JSON schema 配置 UI)。本 skill 汇集「写 / 改 amis schema 时会撞、且不真渲染就发现不了」的实战坑。**绝大多数页面由转换器 / recipe 编译器生成**,所以多数修复落在生成逻辑(Java),但症状表现为 amis 行为——下面按 amis 概念分组。
|
||||||
|
|
||||||
|
## 触发场景
|
||||||
|
|
||||||
|
- 生成或手改 amis 页面后:联动失效、选不中、显 id、空列表报错、行内编辑异常。
|
||||||
|
- 在 DesignerPage overlay 或 recipe 模板里调字段 / 事件 / 列。
|
||||||
|
- 排查「功能通了但 UI/UE 不对」。
|
||||||
|
|
||||||
|
## 铁律(先读这条)
|
||||||
|
|
||||||
|
1. **必真渲染实测**:任何 amis 改动都要 vite 反代 + Playwright / 浏览器逐屏看。功能点 e2e(落库 / status)**≠** 视觉 / UE 走查——很多坑只在渲染时暴露。
|
||||||
|
2. **线上 sdk.js 与 amis-fork 源码已漂移**:以实际加载的 sdk 行为为准,别照搬某版源码 API;直接改 sdk 有全站回归险。
|
||||||
|
3. **属性别凭记忆**:amis 属性多且迭代快,查官方文档(context7 / amis.io),别幻觉出不存在的属性或事件名。
|
||||||
|
4. **行为不确定先隔离钉死**:建隔离 `amis.embed` 手写最小 schema 跑真事件,确认机制后再写后端 / 转换器。
|
||||||
|
5. **校验工具**:`POST {{EIP4_BASE_URL}}/api/page/schema/validate`(不写库);`GET {{EIP4_BASE_URL}}/api/page/schema/components` 查注册组件 / 动作(未注册会被 typed 校验拒)。
|
||||||
|
|
||||||
|
## 引用列 / picker / select 联动
|
||||||
|
|
||||||
|
- **picker 显名**:用 form `initApi`(**不要** service 包裹,service 破坏 fetch 时序)+ 引用字段返 `{_id, _label}` 对象(自带 label 不依赖二次拉取)。**禁全局递归 schema filter**(崩过)。
|
||||||
|
- **单选 select 取联动源**:`event.data.selectedItems` 是 **Option 对象,不是数组** → 写 `selectedItems.FIELD`,**别加 `[0]`**(只有多选才是数组)。引用联动 fill 失败,十有八九是这。
|
||||||
|
- 联动 / 校验动作要锚定 `onEvent.actions[]`。
|
||||||
|
- CHAR(36) 外键值常带尾空格 → 匹配不上,要 **trim**。
|
||||||
|
|
||||||
|
## 树(tree / tree-select / treeGrid)
|
||||||
|
|
||||||
|
- **选不中**:>100 节点触发 amis 虚拟列表,`valueSet.has` 走对象身份判断 → 选中 / 高亮失效。设 `virtualThreshold` 关虚拟,或避免一次性渲染大树。
|
||||||
|
- **点一次发两请求**:别同时写 `onEvent.change` 里 reload **和** `api: node=${tree}` 自动重拉,二者叠加双触发;去掉显式 reload。
|
||||||
|
- 加节点用弹窗表单(含多必填列),顶级节点省略 parentid;「加子节点」预填父名要 `canAccessSuperData:false` + 显式传 data。
|
||||||
|
- 树形维护对应实体 type=101 → 用 tree-select + onlyLeaf。
|
||||||
|
|
||||||
|
## CRUD 列表 / 空数据
|
||||||
|
|
||||||
|
- 列表 data 必须是**数组**;后端空结果 `{result:{}}` 要兜底成 `items:[]`,否则 amis 报红横幅 `data.items 必须是数组`。
|
||||||
|
- **别直接绑外键 id 当显示列**(会显裸 id):用计算 / columnsql 显示列,或按列名映射目标表取名(如 DEPARTID→SYS_DEPART、ORGID→SYS_ORG)。
|
||||||
|
- 点整行选中:`checkOnItemClick: true`。
|
||||||
|
|
||||||
|
## 行内编辑 / 主子表
|
||||||
|
|
||||||
|
- `quickEdit.needConfirm` 必须**显式 `false`**——amis 默认会强注一个 confirm 步骤,不写就每格都要点确认。
|
||||||
|
- 派生列公式里的 `|` 会破坏表达式切分;深嵌套表达式可能 StackOverflowError,求值要兜底。
|
||||||
|
- 多行子表用 `${index}` 按行隔离,防字段串台。
|
||||||
|
|
||||||
|
## 对话框 / 表单 / 附件
|
||||||
|
|
||||||
|
- 🔑 **行级按钮打开的 dialog 表单,会按字段 name 自动回填该行同名字段**:命名冲突会意外带入行数据,起名时留意。
|
||||||
|
- 附件双态:只读 / 编辑都用 `input-file` + `staticOn: ${__readonly}`(**别**用 each / service 拼),契约字段 `{id, name, value, url, sizeKb}`;保真层大写 `DOCUMENT` 要归一为 amis 小写。
|
||||||
|
|
||||||
|
## onEvent 事件挂载
|
||||||
|
|
||||||
|
- 要挂事件的工具栏 / 按钮**必须有 id**,否则联动挂不上。
|
||||||
|
- 区分事件类型(`inited` vs `change`),别一把抓全挂。
|
||||||
|
- 联动脚本要覆盖**所有**按钮模式(不只 FULL_AUTO,NO_S3 等也要)。
|
||||||
|
|
||||||
|
## 红线
|
||||||
|
|
||||||
|
- 改 amis 行为前先想清楚改的是「生成逻辑(转换器 / recipe)」还是「单页 overlay」——前者影响全站,必跑回归。
|
||||||
|
- schema 只能用注册过的组件 / 动作;改动后 `validate` + 真渲染**双验证**再收工。
|
||||||
@@ -5,6 +5,8 @@
|
|||||||
- 用户要新建业务实体(表)、给已有表加字段。
|
- 用户要新建业务实体(表)、给已有表加字段。
|
||||||
- 需要引用列(外键)、主子表结构。
|
- 需要引用列(外键)、主子表结构。
|
||||||
|
|
||||||
|
> 调用方式:经 REST(无对应 CLI 子命令),或经 `platform-mcp`(MCP)。非 local 环境需带 `Authorization: Bearer <token>`,取 token 见 `eip4-env-manage`。
|
||||||
|
|
||||||
## 端点
|
## 端点
|
||||||
|
|
||||||
建实体:`POST {{EIP4_BASE_URL}}/api/meta/entity`
|
建实体:`POST {{EIP4_BASE_URL}}/api/meta/entity`
|
||||||
|
|||||||
@@ -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
|
/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 <token>`(`/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 种子账号;按环境替换。
|
||||||
|
|
||||||
## 禁止事项
|
## 禁止事项
|
||||||
|
|
||||||
- 不在用户原始任务目录中直接改动或启动长时间任务,除非用户明确要求。
|
- 不在用户原始任务目录中直接改动或启动长时间任务,除非用户明确要求。
|
||||||
|
|||||||
@@ -5,9 +5,13 @@
|
|||||||
- 用户要为某实体生成默认页面(维护 / 树 / 主子表)。
|
- 用户要为某实体生成默认页面(维护 / 树 / 主子表)。
|
||||||
- 需要派生列、父级汇总。
|
- 需要派生列、父级汇总。
|
||||||
|
|
||||||
|
> 调用方式:经 REST(无对应 CLI 子命令),或经 `platform-mcp`(MCP)。非 local 环境需带 `Authorization: Bearer <token>`,取 token 见 `eip4-env-manage`。
|
||||||
|
|
||||||
## recipe 类型
|
## recipe 类型
|
||||||
|
|
||||||
- `maintenance-crud` — 普通维护 CRUD(列表 + 表单)。
|
权威列表以 `GET {{EIP4_BASE_URL}}/api/ai/page-recipes` 为准;当前三种(id 带 `-v1`,须逐字传,端点精确匹配,不接受省略 `-v1` 的别名):
|
||||||
|
|
||||||
|
- `maintenance-crud-v1` — 普通维护 CRUD(列表 + 表单)。
|
||||||
- `tree-crud-v1` — 树形维护(有 parentid 的层级表)。
|
- `tree-crud-v1` — 树形维护(有 parentid 的层级表)。
|
||||||
- `master-detail-v1` — 主子表(主表 + 子表行内编辑)。
|
- `master-detail-v1` — 主子表(主表 + 子表行内编辑)。
|
||||||
|
|
||||||
@@ -19,7 +23,7 @@
|
|||||||
{
|
{
|
||||||
"tableName": "EIP4_DEMO",
|
"tableName": "EIP4_DEMO",
|
||||||
"title": "演示页面",
|
"title": "演示页面",
|
||||||
"recipe": "maintenance-crud",
|
"recipe": "maintenance-crud-v1",
|
||||||
"pageSize": 20,
|
"pageSize": 20,
|
||||||
"displayField": "NAME",
|
"displayField": "NAME",
|
||||||
"childTable": "DEMO_DETAIL",
|
"childTable": "DEMO_DETAIL",
|
||||||
|
|||||||
@@ -745,8 +745,14 @@ public final class Eip4Cli {
|
|||||||
+ "Base URL: " + baseUrl + "\n\n"
|
+ "Base URL: " + baseUrl + "\n\n"
|
||||||
+ "已安装 skills(Claude Code 见 `.claude/skills/`;以下内嵌完整正文,供 Codex / OpenCode 使用):\n"
|
+ "已安装 skills(Claude Code 见 `.claude/skills/`;以下内嵌完整正文,供 Codex / OpenCode 使用):\n"
|
||||||
+ catalog + "\n"
|
+ catalog + "\n"
|
||||||
+ "通用原则:优先用 `platform-cli`,其次 REST API;本地写默认放行、生产写阻断;"
|
+ "接入方式:① Claude Code 读 `.claude/skills/`;② Codex / OpenCode 读本文件内嵌正文;"
|
||||||
+ "AI 产物恒为 READY_FOR_HUMAN_REVIEW,需人工复核后发布。\n"
|
+ "③ 可选——把 `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 <token>`(详见 eip4-env-manage)。"
|
||||||
|
+ "本地写默认放行、生产写阻断;AI 产物恒为 READY_FOR_HUMAN_REVIEW,需人工复核后发布。\n"
|
||||||
+ bodies
|
+ bodies
|
||||||
+ SKILLS_END + "\n";
|
+ SKILLS_END + "\n";
|
||||||
Path agents = targetDir.resolve("AGENTS.md");
|
Path agents = targetDir.resolve("AGENTS.md");
|
||||||
|
|||||||
@@ -29,6 +29,11 @@
|
|||||||
"file": "eip4-acl-manage.md",
|
"file": "eip4-acl-manage.md",
|
||||||
"name": "eip4-acl-manage",
|
"name": "eip4-acl-manage",
|
||||||
"description": "菜单/角色/用户组授权(/api/admin/*)"
|
"description": "菜单/角色/用户组授权(/api/admin/*)"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"file": "eip4-amis-pitfalls.md",
|
||||||
|
"name": "eip4-amis-pitfalls",
|
||||||
|
"description": "amis 前端实战坑:引用/树/列表/行内编辑/对话框/事件 + 必实测铁律"
|
||||||
}
|
}
|
||||||
]
|
]
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -485,6 +485,70 @@ class Eip4CliTest {
|
|||||||
"embedded body must also be rendered");
|
"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
|
@Test
|
||||||
void skillsListPrintsBundledSkillNames() throws Exception {
|
void skillsListPrintsBundledSkillNames() throws Exception {
|
||||||
Path skillsDir = writeSkillsFixture();
|
Path skillsDir = writeSkillsFixture();
|
||||||
|
|||||||
Reference in New Issue
Block a user