Files
eip4-platform/docs/AI_AGENT_PAGE_BLUEPRINT_CONTRACT.md
zhengwr 9aea6c1cd0 docs(ai): converge external wording to AI-assisted + human review, not full-auto
Per the architecture-review redline (EIP3 决策会纪要: AI claims limited to 'AI-assisted, human-reviewed'; never promise 'AI full-auto development'), soften endpoint @Operation summaries, the default task objective, and AI docs that read as committed full-automation. Endpoint paths/method names unchanged (API contract). Added a capability-boundary disclaimer at the top of AI_AGENT_AUTO_DEVELOPMENT.md. 33 platform-ai tests green.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-19 16:39:45 +08:00

5.3 KiB
Raw Blame History

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,执行真实浏览器渲染并回写运行证据。