Files
eip4-platform/docs/AI_AGENT_PAGE_BLUEPRINT_CONTRACT.md

83 lines
2.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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-ai/src/main/resources/ai/page-recipes/maintenance-crud-v1.yaml`
AI 自动开发链路中的 `PAGE_SCHEMA` 草稿仍然保存编译后的 amis schema,保持现有落库和前端渲染契约不变;草稿 metadata 额外保存:
- `pageRecipe`
- `pageBlueprintVersion`
- `pageBlueprint`
## Recipe: maintenance-crud-v1
适用范围:
- 普通实体维护页
- 单主表列表
- 新增、编辑、删除
- 本地 smoke 可覆盖列表、新增、服务流搜索
标准输出结构:
- 顶层 `type=page`
- `body[0]` 为 `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`
字段映射:
- `string` -> `input-text`
- `integer` / `number` -> `input-number`
- `date` -> `input-date`
- `datetime` -> `input-datetime`
- `boolean` -> `switch`
- 主键不出现在新增表单,编辑表单最后追加 `hidden`
## 当前边界
本阶段只解决“AI 生成维护类 CRUD 页时走受控 recipe”。还未覆盖:
- 主子表页面
- 树表页面
- 审批办理页面
- 看板、日历、图表、报表页
- 复杂字段分组
- 条件联动
- 引用选择器策略
- 权限按钮策略
这些类型必须作为新的 recipe 增量加入,不能让 Agent 直接绕过 blueprint 生成最终 amis JSON。
## 后续演进
1. 将 `maintenance-crud-v1.yaml` 中的规则接入 UI lint。
2. 增加 `master-detail-v1`、`tree-crud-v1`、`approval-task-v1` recipe。
3. 让设计器 overlay 保存也能记录对应 blueprint 或 template 来源。
4. 在功能包中导出 blueprint,线上部署包继续导出编译后的 amis schema。
5. Playwright E2E 从 recipe 反推出应验证的 UI 行为。