修复 agc_tools 媒体资源提示词上限并按 kind 暴露 (#398)

## 改动 - 提示词上限收敛为 `resource_edit_prompt_max_chars` 单一权威：`agc_tools` MCP 工具层、客户端受控工具桥与提交校验共用同一数字与拒绝文案，不再出现「schema 写 4000、真实上限按 kind 分」的分叉。 - `agc_create_or_derive_resource` 的 schema 逐 kind 声明 `prompt.maxLength`（background-music / sound-effect / video 与 character-animation），`prompt` 描述写明每个数字；`agc_edit_image` 继续用图片口径 32000。 - 工具桥不再用通用 4000 校验 prompt：图片编辑 4000~32000 的提示词不再被误报成「超出安全边界」。 - 源资源未登记时的错误文案补上可执行两步：先用 `agc_list_registered_assets` 选已有 localAssetId；只在项目里的文件先 `agc_list_project_files` 确认 `assetImportable=true`，再用 `agc_import_account_assets.localPaths` 登记后重试。`agc_remove_background` 复用同一条文案。 - skill 包 `agc-client-projection` 的 SKILL.md 与 projection-contract.md 写明四个上限，并说明超限要在本地收敛而不是原样重发；清单指纹同步到 `2026-08-26.18`（已合并 master 的抠图文案）。 - 前端 `resourceEditModel.ts` 补注释指向 Rust 权威函数，数字未动。 - decision-log、pitfalls 与《AI游戏创作智能体App实施计划》记录本轮口径；未改 External v1 契约 / OpenAPI、SpacetimeDB schema 与客户端 UI 行为。 ## 问题 | 编号 | 问题 | 本 PR 状态 | | --- | --- | --- | | P1 | 背景音乐提示词真实上限 140，但 schema 只写 4000、skill 未写明，agent 写一句正常长度描述必被硬拒 | 已修复：口径单源 + 逐 kind 暴露 + skill 写明 | | P2 | 音效 1900 与图片编辑 32000 的上限只在 Rust 内部生效，MCP 与工具桥各自硬编码或误报 | 已修复：三处共用同一函数，图片编辑不再误报安全边界 | | P3 | 源资源未登记时只报「不属于当前项目已登记资源」，模型会原地重试 | 已修复：文案给出 `agc_list_registered_assets` 与登记工具两步动作 | | P4 | 这两个工具此前没有端到端用例，同类漂移无法被门禁拦住 | 已补：MCP 工具层 → 真实工具桥 → 假平台的契约用例 + 两条按 kind 上限门禁 | ## 验证 - `agent::direct_tools_mcp::tests` 23 passed / 0 failed：含新增的按 kind 上限门禁、图片快速编辑契约（断言 `POST /api/editor/images/edits` 的路径、Bearer、Idempotency-Key、正文且不得回填 assetKind）、背景音乐契约（断言 `POST /api/editor/audios/background-music/generations` 的 `gptDescriptionPrompt` 与 `makeInstrumental`）、超限零桥请求、未登记源资源提示。 - `agent::direct_tool_bridge::tests` 18 passed / 7 failed；`agent::skill_pack` 4 passed；`npm run agc:skill-pack:check` 与 `skill-pack:test` 通过（version `2026-08-26.18`）。 - AGC `typecheck`（tsc + skill-pack check + check-config）、`resourceEditModel` 6 项前端测试、`npm run check:encoding`、`npm run check:doc-index`、`cargo fmt --check`、`git diff --check` 通过。 - 那 7 条（以及 `project::resource_editor` 45 条）失败与本 PR 无关：全部是 `tempfile::tempdir()` 的 `Windows 安全对象不属于当前用户`，已 stash 改动并用基线复跑确认失败集合一致。 - 未跑整包 AGC Rust 全量分片、`npm run lint` 聚合门禁与 CI；未做任何付费生成。工具 schema 与 skill 文案都在应用内，终端用户需重新构建客户端才能看到修复效果。 --------- Co-authored-by: kdletters <61648117+kdletters@users.noreply.github.com> Reviewed-on: #398
2026-09-17 14:56:56 +08:00
parent d85622069d
commit cd9faae9b2
10 changed files with 904 additions and 54 deletions
@@ -150,6 +150,7 @@ npm 游戏的可预览产物固定为对应 package 目录下的 `dist/index.htm
 ## 2026-08-24 Direct Codex 已登记资源查询与媒体生成语义工具

 - `agc_tools` 新增 `agc_list_registered_assets` 与 `agc_create_or_derive_resource`。前者按 `kind / assetId / offset / limit` 有界查询客户端权威 manifest，并可显式返回角色动画正式序列帧的稳定 objectKey、assetObjectId 和尺寸；结果不包含完整 manifest、prompt、model、provider route、签名 URL、宿主路径或凭据。后者只接受 `kind / mode / sourceLocalAssetId / prompt / assetName`，`create` 仅允许无源视频、音效和背景音乐，`derive` 必须引用当前项目已登记的 localAssetId，角色动画固定为 derive。
+- `prompt` 上限按 `kind` 分别生效，且工具 schema、MCP 校验、客户端工具桥与提交校验共用同一权威口径（`resource_edit_prompt_max_chars`）：背景音乐 140、音效 1900、视频与角色动画 4000、图片编辑 32000。schema 逐 kind 声明 `maxLength` 并在 `prompt` 描述里写明数字，超限必须在发起任何桥请求与付费提交之前失败并回报真实上限；`sourceLocalAssetId` 不是当前项目已登记资源时，错误文案必须直接给出 `agc_list_registered_assets` 与 `agc_list_project_files` → `agc_import_account_assets.localPaths` 两步后续动作。
 - 项目路径、projectId、当前 revision、源文件路径与媒体类型、operationId、Idempotency-Key、登录态、项目锁、付费提交、轮询恢复、下载校验与 manifest 事务全部由客户端持有。模型不能提交或覆盖这些字段。同一 Direct `clientTurnId + 规范语义参数` 生成稳定 UUID v4 身份；单回合同参重试复用原 operation，不同请求串行且最多四项。跨回合存在完全匹配的 pending 账本时优先恢复原 operation，不能换键重发。
 - 资源查询同时投影未完成 operation 的安全状态。媒体工具成功只返回 operation、本地相对路径、资源类型、Canvas/resource/asset/task 身份、正式序列帧以及脱敏后的 `warnings / sliceWarnings`；错误继续使用统一脱敏边界。客户端资源账本持久化 completed 结果的两类告警，committed replay 不能把历史告警伪装成空集合。
 - 角色动画、视频、音效和背景音乐在构造新的远端请求前统一准备当前项目同名画布与素材目录上下文，并在端点支持时携带 `projectId / assetFolderId / canvasCompletion`。角色动画 placeholder 使用源图片真实宽高，避免非方形角色进入画布时失真；正式 resource/asset 与序列帧继续直接复用 External 返回身份，不从首帧伪造重复资源。已有冻结 request body 或已受理 operation 保持不变，不因本次升级重建请求或重复扣费。