diff --git a/docs/AI_AGENT_AUTO_DEVELOPMENT.md b/docs/AI_AGENT_AUTO_DEVELOPMENT.md index 0aaab16..22f8aaf 100644 --- a/docs/AI_AGENT_AUTO_DEVELOPMENT.md +++ b/docs/AI_AGENT_AUTO_DEVELOPMENT.md @@ -102,16 +102,17 @@ curl -X POST http://localhost:8093/api/ai/features/auto-develop \ ## 自动链路 1. 创建 `AiTask`。 -2. 生成 `ENTITY`、`PAGE_SCHEMA`、`SERVICEFLOW`、`MENU`、`TEST` 草稿。`PAGE_SCHEMA` +2. 读取 `/api/ai/page-recipes` 中的 EIP4 页面 recipe,确认当前页面类型的 UI/UE 约束。 +3. 生成 `ENTITY`、`PAGE_SCHEMA`、`SERVICEFLOW`、`MENU`、`TEST` 草稿。`PAGE_SCHEMA` 先生成 EIP4 PageBlueprint,再由平台编译器输出 amis schema;草稿 metadata 保留 blueprint 证据。 -3. 对草稿执行基础门禁,包括 page-recipe、amis schema、typed page schema、服务流 XML、实体字段和 smoke 计划。 -4. 生成待人审 `AiChangeSet`。 -5. 生成 release plan。 -6. 本地 apply:实体走本机 `/api/meta/entity`,页面/服务流写本地库;如果本地最小库缺少 `sys_menu`,菜单发布标记为 `SKIPPED`,不阻断本地 gate,部署包仍保留菜单 SQL 供线上人审。 -7. 本地 smoke:只允许 `localhost`、`127.0.0.1`、`::1` baseUrl;HTTP 状态必须匹配,且 JSON 响应体存在 `status` 时必须为 0。 -8. 若失败,自动生成 repair plan 并执行修复重试。 -9. 生成线上人工部署包,包含 manifest、SQL 草案、回滚 SQL 和本地执行证据。 -10. 可选:生成功能包快照并保存 revision,用于后续导出、差异比较和回滚扩展。 +4. 对草稿执行基础门禁,包括 page-recipe、amis schema、typed page schema、服务流 XML、实体字段和 smoke 计划。 +5. 生成待人审 `AiChangeSet`。 +6. 生成 release plan。 +7. 本地 apply:实体走本机 `/api/meta/entity`,页面/服务流写本地库;如果本地最小库缺少 `sys_menu`,菜单发布标记为 `SKIPPED`,不阻断本地 gate,部署包仍保留菜单 SQL 供线上人审。 +8. 本地 smoke:只允许 `localhost`、`127.0.0.1`、`::1` baseUrl;HTTP 状态必须匹配,且 JSON 响应体存在 `status` 时必须为 0。 +9. 若失败,自动生成 repair plan 并执行修复重试。 +10. 生成线上人工部署包,包含 manifest、SQL 草案、回滚 SQL 和本地执行证据。 +11. 可选:生成功能包快照并保存 revision,用于后续导出、差异比较和回滚扩展。 返回体中的关键字段: diff --git a/docs/AI_AGENT_PAGE_BLUEPRINT_CONTRACT.md b/docs/AI_AGENT_PAGE_BLUEPRINT_CONTRACT.md index 52b4717..df2397f 100644 --- a/docs/AI_AGENT_PAGE_BLUEPRINT_CONTRACT.md +++ b/docs/AI_AGENT_PAGE_BLUEPRINT_CONTRACT.md @@ -15,8 +15,18 @@ EIP4 的 AI Agent 不直接自由生成 amis JSON。Agent 应先生成 EIP4 Page - `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` +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` diff --git a/platform-ai/src/main/java/com/eip4/platform/ai/service/AiAgentService.java b/platform-ai/src/main/java/com/eip4/platform/ai/service/AiAgentService.java index ebc2933..4b5311f 100644 --- a/platform-ai/src/main/java/com/eip4/platform/ai/service/AiAgentService.java +++ b/platform-ai/src/main/java/com/eip4/platform/ai/service/AiAgentService.java @@ -62,6 +62,7 @@ import com.eip4.platform.metadata.schema.TypedPageSchemaIssue; import com.eip4.platform.metadata.schema.TypedPageSchemaReport; import com.eip4.platform.metadata.schema.TypedPageSchemaValidator; import com.eip4.platform.metadata.schema.blueprint.PageBlueprint; +import com.eip4.platform.metadata.schema.blueprint.PageRecipeDefinition; import com.eip4.platform.metadata.schema.blueprint.PageRecipeRegistry; import com.eip4.platform.metadata.schema.blueprint.PageRecipeValidationReport; import com.eip4.platform.metadata.schema.blueprint.PageRecipeValidator; @@ -90,6 +91,7 @@ public class AiAgentService { private final ObjectMapper objectMapper; private final AiToolRegistry toolRegistry; private final TypedPageSchemaValidator typedSchemaValidator; + private final PageRecipeRegistry pageRecipeRegistry; private final PageRecipeValidator pageRecipeValidator; private static volatile SchemaGate sharedSchemaGate; @@ -127,7 +129,8 @@ public class AiAgentService { this.typedSchemaValidator = typedSchemaValidator == null ? new TypedPageSchemaValidator(objectMapper, PageComponentRegistry.defaults()) : typedSchemaValidator; - this.pageRecipeValidator = new PageRecipeValidator(objectMapper, PageRecipeRegistry.defaults()); + this.pageRecipeRegistry = PageRecipeRegistry.defaults(); + this.pageRecipeValidator = new PageRecipeValidator(objectMapper, pageRecipeRegistry); } public AiTask createTask(String objective) { @@ -760,6 +763,16 @@ public class AiAgentService { return toolRegistry.employees(); } + public List listPageRecipes() { + return pageRecipeRegistry.definitions(); + } + + public PageRecipeDefinition getPageRecipe(String recipe) { + return pageRecipeRegistry.find(recipe) + .orElseThrow(() -> new ResponseStatusException(HttpStatus.NOT_FOUND, + "页面 recipe 不存在: " + (recipe == null ? "" : recipe))); + } + public AiToolAccessDecision checkToolAccess(AiToolAccessRequest request) { return toolRegistry.check(request); } diff --git a/platform-ai/src/main/java/com/eip4/platform/ai/service/AiToolRegistry.java b/platform-ai/src/main/java/com/eip4/platform/ai/service/AiToolRegistry.java index eb83e01..1cd9bee 100644 --- a/platform-ai/src/main/java/com/eip4/platform/ai/service/AiToolRegistry.java +++ b/platform-ai/src/main/java/com/eip4/platform/ai/service/AiToolRegistry.java @@ -34,6 +34,10 @@ public final class AiToolRegistry { "Validate AMIS and typed page schema before saving or packaging.", List.of("POST /api/ai/tools/validate-schema", "POST /api/page/schema/validate"), List.of("ai:schema:validate"), false, false); + registerTool(tools, "page-recipe.read", "design-contract", + "Read EIP4 page recipes and UI/UE constraints before generating page blueprints.", + List.of("GET /api/ai/page-recipes", "GET /api/ai/page-recipes/{recipe}"), + List.of("ai:page-recipe:read"), false, false); registerTool(tools, "local.apply", "local-gate", "Apply a change set to a local EIP4 environment only.", List.of("POST /api/ai/tasks/{taskId}/change-sets/{changeSetId}/local-apply"), @@ -56,9 +60,9 @@ public final class AiToolRegistry { Map employees = new LinkedHashMap<>(); registerEmployee(employees, "agent-developer", "Agent Developer", "Develops EIP4 feature packages in local environments.", - List.of("feature.draft.generate", "schema.validate", "local.apply", "smoke.run", + List.of("feature.draft.generate", "schema.validate", "page-recipe.read", "local.apply", "smoke.run", "feature.package", "release.prepare"), - List.of("ai:feature:draft", "ai:schema:validate", "ai:local:apply", "ai:smoke:run", + List.of("ai:feature:draft", "ai:schema:validate", "ai:page-recipe:read", "ai:local:apply", "ai:smoke:run", "ai:package:create", "ai:release:prepare"), List.of("Local apply only", "Production deployment requires human operator")); registerEmployee(employees, "release-auditor", "Release Auditor", diff --git a/platform-ai/src/main/java/com/eip4/platform/ai/web/AiAgentController.java b/platform-ai/src/main/java/com/eip4/platform/ai/web/AiAgentController.java index 4697e69..02a42e5 100644 --- a/platform-ai/src/main/java/com/eip4/platform/ai/web/AiAgentController.java +++ b/platform-ai/src/main/java/com/eip4/platform/ai/web/AiAgentController.java @@ -33,6 +33,7 @@ import com.eip4.platform.ai.model.AiToolAccessRequest; import com.eip4.platform.ai.model.AiToolDefinition; import com.eip4.platform.ai.model.AiEmployeeDefinition; import com.eip4.platform.ai.service.AiAgentService; +import com.eip4.platform.metadata.schema.blueprint.PageRecipeDefinition; import com.fasterxml.jackson.databind.JsonNode; import io.swagger.v3.oas.annotations.Operation; @@ -207,6 +208,18 @@ public class AiAgentController { return service.listEmployees(); } + @Operation(summary = "列出 AI 页面 recipe", description = "返回 Agent 生成页面前必须读取的 EIP4 UI/UE recipe 定义") + @GetMapping("/page-recipes") + public List pageRecipes() { + return service.listPageRecipes(); + } + + @Operation(summary = "查看 AI 页面 recipe", description = "按 recipe id 返回字段映射、门禁和版本信息") + @GetMapping("/page-recipes/{recipe}") + public PageRecipeDefinition pageRecipe(@PathVariable String recipe) { + return service.getPageRecipe(recipe); + } + @Operation(summary = "检查 AI 工具访问权限", description = "只做权限判定,不执行工具;生产写默认阻断") @PostMapping("/tools/access-check") public AiToolAccessDecision checkToolAccess(@RequestBody(required = false) AiToolAccessRequest request) { diff --git a/platform-ai/src/test/java/com/eip4/platform/ai/service/AiToolRegistryTest.java b/platform-ai/src/test/java/com/eip4/platform/ai/service/AiToolRegistryTest.java index 5f7d3b6..850b595 100644 --- a/platform-ai/src/test/java/com/eip4/platform/ai/service/AiToolRegistryTest.java +++ b/platform-ai/src/test/java/com/eip4/platform/ai/service/AiToolRegistryTest.java @@ -26,6 +26,19 @@ class AiToolRegistryTest { assertTrue(decision.blockers().isEmpty()); } + @Test + void agentDeveloperCanReadPageRecipes() { + var decision = registry.check(new AiToolAccessRequest( + "agent-developer", + "page-recipe.read", + List.of("ai:page-recipe:read"), + "local", + false)); + + assertTrue(decision.allowed()); + assertTrue(decision.blockers().isEmpty()); + } + @Test void localOnlyToolIsBlockedForProductionTarget() { var decision = registry.check(new AiToolAccessRequest( diff --git a/platform-ai/src/test/java/com/eip4/platform/ai/web/AiAgentControllerTest.java b/platform-ai/src/test/java/com/eip4/platform/ai/web/AiAgentControllerTest.java index d83fe6a..2b1e53a 100644 --- a/platform-ai/src/test/java/com/eip4/platform/ai/web/AiAgentControllerTest.java +++ b/platform-ai/src/test/java/com/eip4/platform/ai/web/AiAgentControllerTest.java @@ -50,6 +50,7 @@ import com.eip4.platform.ai.model.AiToolAccessRequest; import com.eip4.platform.ai.model.AiToolDefinition; import com.eip4.platform.ai.model.AiEmployeeDefinition; import com.eip4.platform.ai.service.AiAgentService; +import com.eip4.platform.metadata.schema.blueprint.PageRecipeDefinition; import com.fasterxml.jackson.databind.JsonNode; import com.fasterxml.jackson.databind.ObjectMapper; @@ -183,6 +184,37 @@ class AiAgentControllerTest { verify(service).listEmployees(); } + @Test + void 页面Recipe列表接口返回规范定义() throws Exception { + when(service.listPageRecipes()).thenReturn(List.of(new PageRecipeDefinition( + "maintenance-crud-v1", 1, "EIP4 maintenance CRUD page", + Map.of("string", "input-text"), + List.of("page-recipe", "typed-page-schema")))); + + mvc.perform(get("/api/ai/page-recipes")) + .andExpect(status().isOk()) + .andExpect(jsonPath("$[0].recipe").value("maintenance-crud-v1")) + .andExpect(jsonPath("$[0].fieldMappings.string").value("input-text")) + .andExpect(jsonPath("$[0].gates[0]").value("page-recipe")); + + verify(service).listPageRecipes(); + } + + @Test + void 页面Recipe详情接口按名称查询() throws Exception { + when(service.getPageRecipe(eq("maintenance-crud-v1"))).thenReturn(new PageRecipeDefinition( + "maintenance-crud-v1", 1, "EIP4 maintenance CRUD page", + Map.of("boolean", "switch"), + List.of("page-recipe"))); + + mvc.perform(get("/api/ai/page-recipes/maintenance-crud-v1")) + .andExpect(status().isOk()) + .andExpect(jsonPath("$.recipe").value("maintenance-crud-v1")) + .andExpect(jsonPath("$.fieldMappings.boolean").value("switch")); + + verify(service).getPageRecipe("maintenance-crud-v1"); + } + @Test void 工具访问检查接口不执行工具只返回判定() throws Exception { var request = new AiToolAccessRequest("agent-developer", "local.apply", diff --git a/platform-metadata/src/main/java/com/eip4/platform/metadata/schema/blueprint/PageRecipeRegistry.java b/platform-metadata/src/main/java/com/eip4/platform/metadata/schema/blueprint/PageRecipeRegistry.java index 0582ad7..17b2d61 100644 --- a/platform-metadata/src/main/java/com/eip4/platform/metadata/schema/blueprint/PageRecipeRegistry.java +++ b/platform-metadata/src/main/java/com/eip4/platform/metadata/schema/blueprint/PageRecipeRegistry.java @@ -38,6 +38,10 @@ public final class PageRecipeRegistry { return find(recipe).isPresent(); } + public List definitions() { + return List.copyOf(recipes.values()); + } + public ObjectNode compile(PageBlueprint blueprint, ObjectMapper objectMapper) { if (!supports(blueprint == null ? null : blueprint.recipe())) { String recipe = blueprint == null ? "" : blueprint.recipe();