# AI Agent Page Blueprint Contract 日期:2026-06-17 ## 目标 EIP4 的 AI Agent 不直接自由生成 amis JSON。Agent 应先生成 EIP4 PageBlueprint,再由平台编译器输出 amis schema,并继续通过 typed page schema、amis schema 和真实浏览器 E2E。 这条路径借鉴 NocoBase 的做法:AI 操作受控配置模型,平台负责规范化、校验、模板复用和版本证据。 ## 当前已落地对象 代码位置: - `platform-metadata/src/main/java/com/eip4/platform/metadata/schema/blueprint/PageBlueprint.java` - `platform-metadata/src/main/java/com/eip4/platform/metadata/schema/blueprint/PageBlueprintField.java` - `platform-metadata/src/main/java/com/eip4/platform/metadata/schema/blueprint/PageBlueprintCompiler.java` - `platform-metadata/src/main/java/com/eip4/platform/metadata/schema/blueprint/PageRecipeRegistry.java` - `platform-metadata/src/main/java/com/eip4/platform/metadata/schema/blueprint/PageRecipeValidator.java` - `platform-ai/src/main/resources/ai/page-recipes/maintenance-crud-v1.yaml` - `platform-ai/src/main/resources/ai/page-recipes/tree-crud-v1.yaml` AI 可查询入口: - `GET /api/ai/page-recipes` - `GET /api/ai/page-recipes/{recipe}` 工具注册表中对应工具为 `page-recipe.read`,所需 scope 为 `ai:page-recipe:read`。Agent 生成 PageBlueprint 前应先读取 recipe 定义,再生成草稿。 AI 辅助开发链路中的 `PAGE_SCHEMA` 草稿仍然保存编译后的 amis schema,保持现有落库和前端渲染契约不变;草稿 metadata 额外保存: - `pageRecipe` - `pageBlueprintVersion` - `pageBlueprint` 声明了 `pageRecipe` 的草稿必须通过 `page-recipe` 门禁。该门禁会重新解析 metadata 中的 `pageBlueprint`,用平台注册的 recipe/compiler 重新编译,并要求草稿 payload 与编译结果一致。 因此 Agent 不能一边声明使用标准 recipe,一边绕过 compiler 私改 amis JSON。没有声明 recipe 的 历史/手工 `PAGE_SCHEMA` 草稿暂按自由 schema 处理,只走 amis schema 和 typed page schema。 ## Recipe: maintenance-crud-v1 适用范围: - 普通实体维护页 - 单主表列表 - 新增、编辑、删除 - 本地 smoke 可覆盖列表、新增、服务流搜索 标准输出结构: - 顶层 `type=page` - `body` 为 `crud` - `crud.name` 固定为 `{lowerCamel(tableName)}Crud` - `crud.syncLocation=false` - 列表 API 固定为 `/api/entity/{table}/list?page=${page}&perPage=${perPage}` - 新增按钮位于 `headerToolbar[0]` - 新增按钮使用 `level=primary`、`icon=fa fa-plus`、`actionType=dialog` - 新增和编辑表单提交到 `post:/api/entity/{table}/save` - 编辑按钮位于操作列第一位 - 删除按钮位于操作列第二位 - 删除按钮使用 `className=text-danger`、`actionType=ajax`、`confirmText` - 删除 API 固定为 `/api/entity/{table}/delete` - 页大小默认 `20` - `footerToolbar` 固定包含 `statistics` 和 `pagination` ## Recipe: tree-crud-v1 适用范围: - 自引用层级实体维护页 - 实体必须包含 `PARENTID` 字段 - 覆盖树形列表、新增顶级节点、加子节点、编辑、删除 标准输出结构: - 顶层 `type=page` - `body` 为 `crud` - `crud.name` 固定为 `{lowerCamel(tableName)}TreeCrud` - `crud.childrenColumnName=children` - 列表 API 固定为 `/api/entity/{table}/tree?parentKey=PARENTID&idKey={primaryKey}&perPage=2000` - 新增顶级按钮位于 `headerToolbar[0]` - 新增顶级按钮使用 `level=primary`、`icon=fa fa-plus`、`actionType=dialog` - 操作列按钮顺序固定为:加子项、编辑、删除 - 加子项表单必须隐藏写入 `PARENTID=${primaryKey}` - 编辑表单必须保留隐藏主键和 `PARENTID` - 删除按钮使用 `className=text-danger`、`actionType=ajax`、`confirmText` - 树数据端点返回 `data.items` 层级数组,每个节点的子节点字段为 `children` 字段映射: - `string` -> `input-text` - `integer` / `number` -> `input-number` - `date` -> `input-date` - `datetime` -> `input-datetime` - `boolean` -> `switch` - 主键不出现在新增表单,编辑表单最后追加 `hidden` ## 当前边界 本阶段只解决“AI 生成维护类 CRUD 页时走受控 recipe”。还未覆盖: - 主子表页面 - 审批办理页面 - 看板、日历、图表、报表页 - 复杂字段分组 - 条件联动 - 引用选择器策略 - 权限按钮策略 这些类型必须作为新的 recipe 增量加入,不能让 Agent 直接绕过 blueprint 生成最终 amis JSON。 ## 已落地门禁 - `page-recipe`:校验 recipe 已注册、metadata 证据完整、payload 等于 blueprint 编译结果。 - `typed-page-schema`:校验组件和 actionType 来自 EIP4 注册表。 - `amis-schema`:校验最终 schema 符合 amis schema。 - `local-smoke`:本地发布后访问页面、实体、服务流和新增接口。 - `render-plan`:`TEST` 草稿必须提供 Playwright 可消费的 `renderTests`,包含 recipe、schemaUrl、previewUrl、预期根组件、CRUD 名、数据 API、列表列、页面动作和关键文本。 ## 后续演进 1. 增加 `master-detail-v1`、`approval-task-v1` recipe。 2. 让设计器 overlay 保存也能记录对应 blueprint 或 template 来源。 3. 在功能包中导出 blueprint,线上部署包继续导出编译后的 amis schema。 4. Playwright E2E 消费 `renderTests`,执行真实浏览器渲染并回写运行证据。