art agent: enforce json schema

docs/project-memory/shared-memory/pitfalls.md

@@ -14,6 +14,14 @@
 - 关联：相关文件、文档、提交或 Issue
 ```
 
+## 工具 JSON Schema 的条件约束必须覆盖运行时默认值
+
+- 现象：LLM 按工具 schema 生成的参数可以通过结构约束，但参数补默认值后被运行时校验拒绝，白白消耗一次工具修复轮次。例如固定 `gpt-image-2` 的 UI 工具仍暴露 `0.5K`，或视频调用省略 `model` 时 schema 允许 `1080p`，运行时却默认成 `seedance2.0-fast` 后拒绝。
+- 原因：通用枚举 schema 被固定模型工具直接复用；JSON Schema 的 `if` 又用 `required: ["model"]` 排除了字段缺失场景，而 Serde 默认值只在 schema 校验之后生效。description 只能提示 LLM，不能替代 `enum` / `if` / `then` 的结构约束。
+- 处理：固定模型工具使用与该模型能力一致的专用枚举；可切换模型的图片工具在对象层复用共享 `model + image_size` 条件约束。条件字段有运行时默认值时，省略字段必须落入默认模型对应的 schema 分支：默认 nanobanana2 的图片工具只在显式选择 `gpt-image-2` 时收紧尺寸，所以条件保留 `required: ["model"]`；默认 fast 的视频工具则利用字段缺失时 `properties.model.const` 条件成立的语义，不额外要求 `model` 存在。运行时校验仍保留为最终防线。
+- 验证：锁定 `generate-ui-design.image_size = ["1K", "2K"]`，三个可切换图片模型的工具都接入共享 `gpt-image-2 -> image_size = ["1K", "2K"]` 条件，以及视频 fast 条件没有内层 `required`、其 `then.resolution = ["480p", "720p"]`；同时保留运行时拒绝 `gpt-image-2 + 0.5K` 与 `seedance2.0-fast + 1080p` 的测试。
+- 关联：`server-rs/crates/platform-editor-agent/src/agent/tools/image_generation_options.rs`、`server-rs/crates/platform-editor-agent/src/agent/tools/generate_ui_design.rs`、`server-rs/crates/platform-editor-agent/src/agent/tools/generate_video.rs`、`docs/【编辑器】画布Agent对话面板-2026-07-03.md`。
+
 ## 图片生成的 K 档不能靠回图后缩放实现
 
 - 现象：用户选择 2K 时占位框看起来是 2K，最终资源元数据也显示为 2K，但模型请求实际仍是固定 1K 或竖版回落尺寸；画面只是后端放大后的低分辨率结果。