合并资源规范与画布 JSON 功能

合并 canonical 资源 kind 校验与按类型提示词上限。\n保留 UI JSON 预览识别、严格 UI 文档持久化和画布编辑入口。\n修复合并后 Rust 资源 kind 测试夹具并补齐定向回归用例。
2026-09-17 18:28:19 +08:00
parent 6853ec5388 c958e1955b
commit 64879cfcdd
48 changed files with 3107 additions and 150 deletions
@@ -0,0 +1,26 @@
+# AGC 对话历史分页恢复实施计划
+
+- Date: 2026-09-16
+- Status: awaiting-runtime-acceptance
+- Milestone: [AGC 对话历史分页恢复](./【里程碑】AGC对话历史分页恢复-2026-09-16.md)
+
+## 实施
+
+1. 原生历史读取复用逐行解析，增加消息模式，过滤后分页并返回已有原始消息 ID 游标；保持原始接口默认行为和路径权限。
+2. 工作台首屏与更早消息读取显式请求消息模式，消费游标；加载代次隔离、单飞与 ID 去重。
+3. 合成记录测试复现原始工具页卡住的形状，覆盖旧无 ID、坏行、时间、失败/重复/切项目；临时目录只读重放用户日志。
+4. 前端/原生定向测试、类型、Lint、编码、文档和差异检查通过后，更新问题表及 PR 草稿并本地提交。
+5. 在临时消息投影中标记历史来源，保留 Runtime 所有权语义；刷新合并时只保留非历史来源的待回读消息。补齐「先加载旧页，再 /history，再翻页」的顺序与去重回归，保持尚未落盘用户输入的保留逻辑。
+
+## 边界与停止条件
+
+不调整 Direct 消息呈现归属、不修未证明的写入丢失、不上传日志、不触碰用户项目。必要 API 变化仅为本地 IPC 可选参数和游标字段；无 OpenAPI、SpacetimeDB 或持久化迁移。远程推送/PR/WIP 操作仍待额外确认。
+
+## 验收证据
+
+- 历史消息模型、回合呈现及分页集成共 24 个前端测试通过；包含真实 App 的首屏/更早页、单飞、失败重试、重叠消息、同项目重新加载及离开再进入的迟到响应。
+- 16 个历史原生测试通过；人工日志重放用例在 CI 默认忽略，已在本地单独执行通过。
+- 使用用户提供的原始日志运行修复后的原生读取：44 条现存聊天消息（含 2 条用户消息）分 3 页取回，逐项内容与顺序一致，原文件字节未变；未在仓库保存原始日志。
+- 工作台/Direct 恢复与画布导航的 8 个定向回归通过。真实客户端重新进入与向上翻页尚待用户验收；本次涉及 Rust IPC，需重新构建并启动原生端。
+- 与前面画布/JSON 修复联合复验：119 个前端定向测试、30 个原生测试通过；AGC TypeScript、修改文件 ESLint、编码、文档索引和差异检查通过。
+- 状态只覆盖日志中已经证明的分页卡页，不据此宣称其它可能的未落盘消息也已恢复。
@@ -0,0 +1,44 @@
+# AGC 画布交互稳定性修复实施计划
+
+- Date: 2026-09-16
+- Status: awaiting-runtime-acceptance
+- Milestone: [画布交互稳定性修复](./【里程碑】AGC画布交互稳定性修复-2026-09-16.md)
+
+## 修改顺序与边界
+
+1. 将临时诊断收敛成正式回归测试，覆盖窗口 Context 反馈、提示条件和鼠标/触摸板事件。
+2. 稳定工作台打开项目的转发回调，保持最新处理器语义，不改项目加载逻辑。
+3. 解耦运行提示与选择；在原有画布事件链加入右键平移、菜单边界和中断清理，不另建控制器。
+4. 执行定向验证并检查首次加载、平移和原有框选/卡片拖动回归。
+
+## 验证
+
+- 定向 Vitest：窗口工作台、画布交互、布局与原有导航用例。
+- 运行提示的源码契约与交互回归同时覆盖：提示仅取决于运行能力和 UI 编辑器路由，不依赖资源选择；选中资源后提示及 `aria-describedby` 保留，点击运行仍不能进入不可用视图。
+- AGC `tsc --noEmit`；`npm run check:encoding`、`npm run check:doc-index`、`git diff --check`。
+- 真实客户端首次进入和触摸板操作无法以 jsdom 代替；未实测时保持待验收。
+
+## 风险与停止条件
+
+窗口反馈测试必须有更新次数上限，避免未修复代码让测试失控。右键仅接管画布背景/卡片，不抢输入控件与浮层。新增问题只有影响本次验收才扩大范围；不根据猜测修改 B01/B02 的布局与动画。
+
+回滚仅限本批局部补丁；不重置工作树，不覆盖其它修改。完成自动化验证后停在真实客户端验收，不推进额外功能。
+
+## 问题状态
+
+| 编号 | 问题 | 状态与证据 |
+| --- | --- | --- |
+| B01 | 刷新后首次进入画布元素抖动 | 已优化；用户在本轮反馈未再复现，按用户要求更新状态。不宣称所有布局/动画原因均已排除。 |
+| B02 | 初次进入双指平移无效，整理后恢复 | 已优化；用户在本轮反馈未再复现，按用户要求更新状态。隔离组件连续平移通过。 |
+| B03 | 快速平移触发更新深度错误 | 已修复已确认的窗口 Context 反馈循环，回归验证收敛；真实操作继续观察。 |
+| B04 | 资源选中后运行不可用提示消失 | 已修复，提示与选择解耦，自动化验证通过。 |
+| B05 | 对话记录偶发丢失 | 已修复日志复现的历史分页卡点：消息模式过滤后分页、原生游标与读取代次隔离。原生只读重放分 3 页取回全部 44 条现存消息，原文件未变；真实客户端待验收，不扩大为其它未落盘记录已恢复。 |
+| B06 | JSON 文档未正确识别展示 | 已按用户确认完成本地修复：合法 UI State 由原生完整校验，卡片显示 UI 设计并进入现有编辑器；普通 JSON 显示 JSON 并可代码预览。自动化验证通过，待重建原生客户端验收；详见 JSON 语义识别实施计划。 |
+| C01 | 右键平移，保留左键框选 | 已实现，卡片左键拖动、框选、指针取消/失焦/捕获丢失及控件边界测试通过。 |
+
+## 已取得证据与剩余门禁
+
+- 修复前新增回归测试能检出外壳重复发布、运行提示消失和右键无效；修复后窗口/画布定向测试通过，现有导航、框选、指针点击/取消、UI 编辑器返回平移和素材定位用例通过。
+- AGC TypeScript、修改文件 ESLint、编码、文档索引及差异空白检查通过。
+- 测试仍有既有 React 列表 key、旧用例 act/IPC 桩告警，未作为本批功能修复扩大范围。
+- 用户反馈 B01/B02 本轮未再复现，记为已优化；右键手感与其它真实客户端细节继续观察。对话历史分页与 JSON 双路径均已本地修复并通过定向验证，待重建原生端后真实客户端验收。本计划保持开放。
@@ -0,0 +1,27 @@
+# AGC 资源 JSON 语义识别实施计划
+
+- Date: 2026-09-16
+- Status: awaiting-runtime-acceptance
+- Milestone: [AGC 资源 JSON 语义识别](./【里程碑】AGC资源JSON语义识别-2026-09-16.md)
+
+## 实施边界
+
+1. 原生 UI 持久化模块抽取可复用的内容解析与只读识别；文本预览返回可选的已验证 UI 资产身份。
+2. 保留新设计初始化的严格 UI 资产门禁；已有 State 的加载/保存/生成按登记资源和真实文档校验，不依赖标签精确大小写。
+3. 前端预览缓存透传识别结果；工作台卡片与编辑器入口消费同一结果，普通 JSON 详情使用代码块。
+4. 单元、组件与原生测试覆盖合法/普通/损坏/跨身份/未登记和保存边界；保持先前画布修复。
+
+## 验证与停止条件
+
+- 定向 Vitest、Tauri persistence/resource preview 定向 Rust 测试、AGC TypeScript、修改文件 ESLint、编码、文档索引及 `git diff --check`。
+- 不读取或修改用户项目原文件，不将日志或真实对话作为仓库测试夹具。
+- 原生构建/真实客户端受环境限制时记录实际证据，不能以 TS 测试代替原生验证。
+- 完成上述范围后停止；B05 已有分页卡点证据，本轮不顺带修改历史合同。
+
+## 验证结果
+
+- 92 个前端定向测试通过，覆盖原生结果驱动的卡片/编辑器路由、普通 JSON 代码预览、伪 UI 文本拒绝、读取失败、缓存切项目，以及原有画布导航与指针回归。
+- 14 个 UI 持久化原生测试通过，包含有效 State 对多种登记标签的识别/加载/保存、未知 schema/字段与坏结构拒绝、项目/资产身份、普通 JSON 防覆盖及原有恢复/CAS 边界。
+- 原生测试在 macOS 默认 `/var` 临时路径触发既有拒绝符号链接门禁；改用真实 `/private/tmp` 后通过，未放宽产品路径安全校验。
+- AGC TypeScript、修改文件 ESLint 已通过。测试仍有既有 React key/act 告警及 Rust 未使用代码警告，不影响本批断言。
+- 真实客户端的图片/UI State 体验仍待验收。本次包含 Rust 预览字段，必须重新构建并启动原生端，不能仅刷新前端就认为识别结果已更新。
@@ -0,0 +1,20 @@
+# AGC 对话历史分页恢复
+
+- Version: 1
+- Status: reviewed
+- Date: 2026-09-16
+- Parent Spec: [AGC 实施计划：DirectProject 回合展示唯一归属](../../technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md)
+
+## 范围与评审
+
+用户已要求修复 B05。已用用户提供的原始日志只读复验：原始切片被工具/推理填满时，聊天投影为空，消息游标不推进。修复聊天读取与分页，不改历史写入、不删除记录、不修改模型上下文，不扩大到其它尚无证据的对话丢失原因。
+
+采用已有切片接口的显式消息模式与原生游标。原始模式缺省行为保持不变，旧无 ID 消息保留；前端以项目和加载代次隔离结果。本轮不包含远程写入。
+
+## 验收
+
+1. 工具/推理密集、末尾无消息、纯工具历史均不产生空页死循环。
+2. 消息正文、原始 ID、时间和顺序保持不变，翻页能到达早期用户提问及最终回答，不重复。
+3. 连点、请求失败重试、项目切换和同项目重新加载不会污染消息或游标。
+4. 原始切片默认模式回归通过，用户日志只读重放可以取回全部现存消息；不把真实日志或对话正文提交到仓库。
+5. 加载更早消息后重新读取历史，旧页不出现在最新回复之后；再次翻页保持顺序且不重复。未落盘的实时用户输入不因历史刷新被丢弃。
@@ -0,0 +1,26 @@
+# AGC 画布交互稳定性修复
+
+- Version: 1
+- Status: reviewed
+- Date: 2026-09-16
+- Parent Spec: [AGC 实施计划：资源画布交互与工作台状态同步](../../technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md)
+
+## 目标与范围
+
+完成工作台标题栏状态更新循环、运行提示随选择消失、右键平移三项本地修复，保持左键框选与卡片拖动。不修改布局算法、持久化和后端；不开远程 Issue/PR、不推送。
+
+## 评审
+
+依据已完成的源码追踪、客户端错误日志及有界复现自检：状态归属仍在窗口与工作台原有边界内；交互修改只影响画布手势；没有数据迁移、权限或 API 变化。用户已确认右键平移及保留左键框选，并授权先尝试本地修复。真实客户端首次进入抖动与触摸板平移仍需另行验收。
+
+## 验收
+
+1. 工作台发布窗口状态后收敛；重复渲染不持续更新或清理，打开项目回调使用最新处理器，卸载清理有效。
+2. 选中资源后运行不可用提示仍在，运行能力不变。
+3. 子画布空白处及卡片右键平移不改变选择或坐标；左键框选与卡片拖动保留；总览支持右键平移。
+4. 指针取消、失去捕获、窗口失焦终止平移；控件与浮层保留原有交互。
+5. 连续平移测试、定向测试、类型检查、编码与文档门禁完成并记录限制；B01/B02 仅在真实复测后决定关闭。
+
+## 依赖
+
+当前源码与已安装测试依赖；真实 AGC 客户端验收环境。没有外部写操作依赖。
@@ -0,0 +1,26 @@
+# AGC 资源 JSON 语义识别
+
+- Version: 1
+- Status: reviewed
+- Date: 2026-09-16
+- Parent Spec: [AGC 实施计划：文档与代码素材预览](../../technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md)
+
+## 目标与边界
+
+按用户确认同时支持普通 JSON 与 UI 设计 JSON：前者显示 JSON 并可代码预览，后者显示 UI 设计并进入原有编辑器。原生侧复用现有文档校验，前端不推断正式状态。不修改 manifest 分类，不迁移用户文件，不改历史分页，不做远程写入。
+
+## 评审
+
+已核对原生受控文本预览、UI State 持久化合同和工作台卡片/编辑器路由。复用完整读取结果识别，未知 schema/坏结构/身份不符均不授予编辑入口；已有 UI 资产的大小写标签不应阻断真实合法 State。新增可选预览字段只承载原生识别结果；不引入新的状态文件或平行编辑器。
+
+## 验收标准
+
+1. 普通 JSON 显示 JSON，不渲染卡面原文，不出现 UI 编辑器入口，显式预览为 JSON 代码块。
+2. 完整合法且身份匹配的 UI State 显示 UI 设计并进入现有编辑器；大小写标签或文档标签不影响内容识别。
+3. 损坏 JSON、伪 schema、未知字段、坏 State、跨项目/资产、未登记文件不能获得 UI 编辑入口；原文查看或读取错误仍可见。
+4. 识别不产生写入；普通 JSON 不能通过编辑器保存或初始化被覆盖。有效已有设计仍支持原有 CAS 保存。
+5. 预览缓存能传递原生结果并随资源身份失效；原有卡片、框选/平移和图片预览回归通过。
+
+## 依赖
+
+本地前端与 Tauri 源码、现有测试依赖；真实客户端体验单独验收。
@@ -22,6 +22,17 @@
 - 决策（无写副作用）：只在生成本轮 prompt 时展开该上下文；历史 item 回读走 `direct_codex_user_item_to_response_item` 的纯投影，不得触发 UI 代码导出或任何项目写入。
 - 验证：`agent::direct_codex_user_item` 定向 16 条通过，覆盖成功注入、生成失败保留引用摘要、非 UI 文档不触发与历史回读不产生 `ui/generated-*.js`。

+
+## 2026-09-17 `agc_tools` 媒体资源提示词上限收敛为单一口径，并按 kind 暴露给模型
+
+- 背景：有人反馈「客户端没法由 agent 调用图片快速编辑功能以及背景音乐生成功能」。核查后工具本身都在（`agc_edit_image` / `agc_create_or_derive_resource`），图片快速编辑在 2026-09-14 的真实项目日志里也有成功记录；但存在三类真实缺陷：① `agc_create_or_derive_resource` 的 `prompt` 在 schema 里只声明 4000，真实上限却是按 kind 分的（背景音乐 140、音效 1900、视频/角色动画 4000、图片 32000），MCP 层还额外写死了一条 140 判断，模型从 schema 与 skill 都看不出 140/1900，写一句正常长度的背景音乐描述就当场被拒；② 客户端 UI 用同一口径但会截断并提示，agent 侧却只有硬拒，形成「UI 能做、agent 调不动」的观感；③ `sourceLocalAssetId` 不是已登记资源时只报「不属于当前项目已登记资源」，模型会原地重试而不会先登记。
+- 决策一（单一口径）：提示词上限只由 `resource_edit_prompt_max_chars` 给出，MCP 工具层、客户端受控工具桥与提交校验全部从它取数；超限文案复用 `resource_edit_prompt_limit_error`，保证模型看到的数字就是真实生效的数字。传输层边界只在信封级生效，不再用一个更小的通用常量先于按 kind 上限误报。
+- 决策二（按 kind 暴露）：`agc_create_or_derive_resource` 的 schema 用 `allOf[oneOf]` 逐 kind 声明 `prompt.maxLength`（background-music / sound-effect / video+character-animation），顶层 `maxLength` 等于各 kind 上限的最大值，`prompt` 描述里写明每个数字；`agc_edit_image` 继续用图片口径 32000。skill 包 `agc-client-projection`（SKILL.md 与 `references/projection-contract.md`）同步写明四个数字，并说明超限要在本地收敛而不是原样重发。
+- 决策三（可执行的前置提示）：源资源未登记时统一返回「先用 `agc_list_registered_assets` 选已有 localAssetId；文件只在项目里时先用 `agc_list_project_files` 确认 `assetImportable=true`，再用 `agc_import_account_assets.localPaths` 登记后重试」。本轮不放开「已完成任务产物」在 agent 侧的隐式正规化：登记是带副作用与 revision 推进的事务，必须由模型显式发起。
+- 影响范围：`apps/ai-game-creator-shell/src-tauri/src/project/resource_editor.rs`（上限与文案的唯一口径）、`agent/direct_tool_bridge.rs`（按 kind 判定与未登记源资源提示）、`agent/direct_tools_mcp.rs`（schema 与校验）、`resources/agc-skills/agc-client-projection/**` 与清单指纹（version `2026-08-26.18`）。**未改** `/api/external/v1` 契约与 OpenAPI、SpacetimeDB schema、前端 TS 侧 `resourceEditPromptMaxLength` 数字、客户端 UI 行为。
+- 验证方式：新增 `tool_prompt_limits_agree_with_the_client_authority`（四个 kind 的 schema 上限、MCP 校验与客户端权威口径同数字，超限文案带真实上限）、`bridge_resource_prompt_limits_follow_the_client_authority`（工具桥侧同类门禁，含图片编辑的 32000 边界）、`edit_image_tool_reaches_the_platform_image_edit_route` 与 `background_music_tool_reaches_the_platform_audio_route`（MCP 工具层 → 真实工具桥 → 假平台，断言 `/api/editor/images/edits` 与 `/api/editor/audios/background-music/generations` 的路径、Bearer、Idempotency-Key、正文与派生资源落盘，图片编辑正文不得回填 assetKind）、`background_music_prompt_over_the_limit_is_rejected_before_any_bridge_call`（超限在桥请求之前失败）、`unregistered_source_reports_the_registration_follow_up_tools`；`agent::direct_tools_mcp` 22 passed、`agent::skill_pack` 4 passed、`agent::direct_tool_bridge` 17 passed（7 条本机既有失败见下）、`npm run agc:skill-pack:check` 与 `skill-pack:test` 通过。本机 `tempfile::tempdir()` 归属校验失败导致的既有用例（`project::resource_editor` 45 条、`agent::direct_tool_bridge` 7 条）在本轮改动前后**同为失败**（stash 基线复跑确认），与本次无关。
+- 关联文档：[AI游戏创作智能体App实施计划](../../technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md)、[踩坑记录](pitfalls.md)。
+
 ## 2026-09-16 抠图模式与背景色契约

 - External v1 抠图和 AGC `agc_remove_background` 支持 `complex`（语义分割识别前景）与 `flat`（纯色背景抠图）；明确纯色背景优先 flat，模式缺省仍为 complex，主站前端保持现有行为。
@@ -6,6 +6,35 @@
 - **处理（现行口径）**：生成目录一律成对登记 `.prettierignore` + eslint `ignorePatterns`；改 `export_to` 时同步改这两处，并用 `cargo test --locked -p shared-contracts --features ts-bindings export_bindings --manifest-path server-rs/Cargo.toml` 后 `git diff` 为空来验证幂等。
 - **易错点**：旧的 `apps/ai-game-creator-shell/src/contracts/generated/` 目录下的同名文件不会自动删除，换目录后必须显式删除旧文件，否则会出现「两个同名 union，改动只落在一个目录」的假绿。

+## 2026-09-17 AGC 输入盒的「推理档」弹层被祖先裁切：要放开裁切而不是挪弹层
+
+- **现象**：窄窗口下（视口 ≤1000px 时右侧对话面板只有 280px 宽）点开输入盒右下角的「推理档」，弹层是个**空盒子**：档位文字（默认 / 低 / 中 / 高 / 最高）整片看不见，只剩一个方框。
+- **成因**：推理档是控制排里最靠左的弹层锚点，`.conversation-model-menu` 默认 `right: 0` 贴触发钮右缘**向左**展开；触发钮右边还压着模型选择、语音、发送三颗钮，所以 150px 宽的弹层在 280px 面板里会伸到面板左侧 42px 之外。`.game-workbench-chat`、`.project-supervisor-surface.is-direct-codex`、`.project-supervisor-conversation` 三层各自的 `overflow: hidden` 沿自己的溢出边界裁掉它，而档位文字起点才 14px（面板左内边距 5px + 按钮左内边距 9px），正好落在被裁掉的那半边。
+- **处理（用户指定口径）**：不挪弹层位置——只让 direct-codex 那三层不再裁切：`.game-workbench-chat:has(.project-supervisor-composer.is-direct-codex)`、`.game-workbench-chat .project-supervisor-surface.is-direct-codex`、`.game-workbench-chat .project-supervisor-surface.is-direct-codex .project-supervisor-conversation` 三条 `overflow: visible`。弹层的 `right: 0`、尺寸和触发钮锚点全不变，只是允许它盖到左侧资源面板上完整显示。消息列表自带 `overflow-y: auto`（另一轴按规范计算为 auto），消息内容仍由列表自身裁剪。
+- **易错点**：① 把弹层改成 `left: 0` 或往右挪也能让它可见，但那是改变展开方向，弹层会跑到触发钮右边（用户明确否决）；② 只放开最外层聊天列不够——surface 与 conversation 各自都会裁，三层必须同时放开；③ 只按宽度比大小会误判：280px 面板里控制排本身也超出（发送钮右侧溢出 22px，被窗口右缘吃掉），那不是本条的原因，别顺手去改控制排布局。
+- **验证**：`apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts` 的 `keeps the landscape workbench edge-to-edge with internal chat scrolling` 钉住三条 override 声明在场（删掉任一条即红）。真机几何用 playwright-cli 打开一份只含真实 `styles.css` 与真实 composer DOM 的最小复现页实测（视口 1000×700、面板 280px）：弹层 rect 修复前后都是 `[-42, 108]`（位置未动），`elementFromPoint` 的命中区间从修复前的 `[2, 108]` 变成整块；档位文字在截图中完整可见。
+- **关联**：`apps/ai-game-creator-shell/src/styles.css`（`面板纵向布局（2026-07 Codex 风格改造）` 区块之后）、`apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts`。
+
+## DirectProject 历史不能按工具条目切页再按消息推进游标
+
+原始 `response_item` 历史同时含用户/助手消息、推理与工具输出。若原生每次取 20 个原始条目、前端过滤聊天消息后再找最旧 ID，纯工具页会让消息集合为空且游标不动，看起来历史丢失。聊天读取固定显式请求 `messagesOnly: true`，原生逐行过滤后按消息分页并返回 `oldestItemId`；默认原始模式留给原始条目消费者。无 ID 旧消息保留并扩展到可寻址边界，不能造 ID。前端保留项目与读取代次、单飞及 ID 去重，旧请求的成功、失败与 finally 都不能覆盖新读取；真实日志只在临时目录只读重放，不能提交正文夹具。
+
+## JSON 卡片显示与 UI 编辑能力必须同源
+
+JSON 的文本读取分支不等于卡面应该展示原始 State 摘要。卡片、缩略图及编辑器入口共同消费受控文本预览的 `uiDesignAssetId`；只有原生复用 UI 持久化合同校验 schema、完整 State 和项目/资产身份后才设置它。普通 JSON 保留 JSON 代码预览，不按 `kind: UI/ui` 或 schema 字符串片段猜测编辑能力。已有合法 UI State 的加载/保存不依赖 kind 精确大小写，但新建初始化仍保留正式 UI 资产门禁；缓存与项目切换须保留现有身份隔离。
+
+## 窗口 Context 发布不得依赖每次渲染新建的业务回调
+
+工作台向窗口标题栏发布运行项目时，若 effect 依赖普通函数派生的回调，发布 Context 会重新渲染工作台，进而再次发布并清理，形成更新深度循环。转发入口须稳定，并在提交阶段更新实际处理器引用；发布数据变化与卸载清理分开。回归测试必须组合真实窗口 Provider 和工作台消费者，只有独立画布测试无法覆盖这条反馈链；回归时用有界发布次数阻止测试失控。画布快速操作时暴露的更新深度错误，也须检查外层状态同步，不能直接归因于滚轮频率。
+
+## 2026-09-17 工具 schema 声明的上限与真实校验不一致，会表现成「agent 调不动这个功能」
+
+- **现象**：用户反馈「客户端没法由 agent 调用图片快速编辑功能以及背景音乐生成功能」。查工具目录时两个工具都在（`agc_edit_image`、`agc_create_or_derive_resource`），图片快速编辑在真实项目日志里还有成功记录；但 agent 侧写一句正常长度的背景音乐描述就失败，而客户端 UI 用同一个提示词却只是被截断加提示。
+- **原因**：`agc_create_or_derive_resource.prompt` 在 MCP schema 里只声明 `maxLength: 4000`，真实上限按 kind 分（背景音乐 140 / 音效 1900 / 视频、角色动画 4000 / 图片 32000），MCP 层还额外写死一条 `kind == background-music && > 140` 的判断；skill 包没有任何一处写这两个数字。模型从 schema 与 skill 都无法得知 140，于是必然踩一次硬拒。同类隐患还有两处：客户端工具桥用通用 4000 校验 prompt，会把 4000 以上的图片编辑提示词误报成「超出安全边界」；按 kind 校验散落在 MCP 与桥两处，新增类型容易只改一处。
+- **处理**：上限收敛到 `resource_edit_prompt_max_chars` 单一权威（工具层、桥、提交校验共用），超限文案复用 `resource_edit_prompt_limit_error`；工具 schema 用 `allOf[oneOf]` 逐 kind 声明 `prompt.maxLength` 并在描述里写明数字；prompt 的传输层边界退到信封级，避免通用常量先于按 kind 上限报错；两端 skill 文档同步写明四个数字。新增 `tool_prompt_limits_agree_with_the_client_authority` 作为门禁：四类 kind 的 schema 上限、桥上限与权威口径必须同数字，且超限文案必须带真实上限。
+- **验证**：`cargo test --bin genarrative-ai-game-creator-shell -- --test-threads=1 agent::direct_tools_mcp::tests`（22 passed，含两条走 MCP 工具层 → 真实工具桥 → 假平台的媒体工具契约用例与一条超限零请求用例）、`agent::direct_tool_bridge::tests`（17 passed，含新增的按 kind 上限门禁；另有 7 条本机既有失败）、`agent::skill_pack`（4 passed）、`npm run agc:skill-pack:check`。本机 `tempfile::tempdir()` 归属校验失败会让 `project::resource_editor` 45 条与 `agent::direct_tool_bridge` 7 条既有用例失败，改动前后同为失败，不要据此误判回归。
+- **关联**：`apps/ai-game-creator-shell/src-tauri/src/project/resource_editor.rs`、`src-tauri/src/agent/direct_tool_bridge.rs`、`src-tauri/src/agent/direct_tools_mcp.rs`、`src-tauri/resources/agc-skills/agc-client-projection/`。
+
 ## 2026-09-16 从 Codex 里启动 AGC 客户端会看到被重定向的 `%APPDATA%`

 - **现象**：在 Codex 会话里用 `Start-Process` 启动 `genarrative-ai-game-creator-shell.exe` 做排障时，子进程写 `C:\Users\<user>\AppData\Roaming\world.genarrative.ai-game-creator\...` 的内容会落到 `C:\Users\<user>\AppData\Local\Packages\OpenAI.Codex_2p2nqsd0c76g0\LocalCache\Roaming\...`；同一个 `Test-Path` / `Get-ChildItem` 命中的是重定向视图，只有 `\\?\C:\Users\...` 形式能区分真实路径。