取消抠图工具的每回合四项媒体请求限制

resource_request_ids 增加 enforce_turn_limit 参数，上限检查只在付费路径生效 agc_remove_background 传 false 豁免上限，id 派生与幂等复用不变 create_or_derive（含 agc_edit_image 委托）维持四项上限与原有报错文案决策记录补充 2026-09-18 抠图豁免条目实施计划文档同步注明抠图不占四项额度
2026-09-18 23:55:19 +08:00
parent 9a21690fe9
commit c413ca44df
3 changed files with 19 additions and 5 deletions
@@ -637,7 +637,11 @@ impl DirectToolBridgeState {
        Ok(())
    }

-    fn resource_request_ids(&self, request_fingerprint: &str) -> Result<(String, String), String> {
+    fn resource_request_ids(
+        &self,
+        request_fingerprint: &str,
+        enforce_turn_limit: bool,
+    ) -> Result<(String, String), String> {
        let mut authorization = self
            .turn_authorization
            .lock()
@@ -649,7 +653,9 @@ impl DirectToolBridgeState {
        if let Some(ids) = active.resource_request_ids.get(request_fingerprint) {
            return Ok(ids.clone());
        }
-        if active.resource_request_ids.len() >= DIRECT_TOOL_BRIDGE_MAX_RESOURCE_CALLS_PER_TURN {
+        if enforce_turn_limit
+            && active.resource_request_ids.len() >= DIRECT_TOOL_BRIDGE_MAX_RESOURCE_CALLS_PER_TURN
+        {
            return Err("单个用户回合最多只能创建四项媒体资源请求".to_string());
        }
        let operation_id =
@@ -1891,7 +1897,7 @@ async fn bridge_create_or_derive_resource(
            .await?
        } else {
            let (operation_id, idempotency_key) =
-                state.resource_request_ids(&request_fingerprint)?;
+                state.resource_request_ids(&request_fingerprint, true)?;
            let revision = read_game_creator_agent_runtime_project_revision(&state.root)?.revision;
            let source_resource_id = source_asset
                .as_ref()
@@ -2001,7 +2007,9 @@ async fn bridge_remove_background(state: &DirectToolBridgeState, arguments: &Val
            })
            .await?
        } else {
-            let (operation_id, idempotency_key) = state.resource_request_ids(&fingerprint)?;
+            // 抠图不计费且服务端秒级完成，不占每回合付费媒体请求的四项额度。
+            let (operation_id, idempotency_key) =
+                state.resource_request_ids(&fingerprint, false)?;
            let revision = read_game_creator_agent_runtime_project_revision(&state.root)?.revision;
            let request = DeriveLocalProjectResourceInput {
                project_path: state.root.to_string_lossy().into_owned(),
@@ -3,6 +3,12 @@
 > 用途：记录已经确认、会影响后续开发的长期技术/产品/协作决策。短期讨论不要写在这里。
 > 当前口径：历史条目的旧路径、旧版本和已退役对象只用于追溯，不构成现行实现依据；如与当前代码或 `docs/README.md` 冲突，以当前代码和最新专题文档为准。

+## 2026-09-18 AGC Direct 抠图不占每回合四项付费媒体额度
+
+- 背景：2026-08-24 起 `agc_create_or_derive_resource` 与 `agc_remove_background` 共用每回合四项媒体资源请求上限。抠图服务端持久化 `generation_cost_mud_points: 0`（不计费），bgfilter 实测单张约 1 秒，上限导致一回合抠超过四张时后续请求被直接拒绝、agent 反复无效重试。
+- 决策：`resource_request_ids` 增加 `enforce_turn_limit` 参数；`agc_remove_background` 传 `false` 豁免上限，确定性 id 派生、同指纹幂等复用与 pending 对账语义不变。付费的 create/derive（含 `agc_edit_image` 委托）维持四项上限与原有报错文案。
+- 验证方式：`cargo check`（ai-game-creator-shell src-tauri）与 `git diff --check` 通过；未新增测试。
+
 ## 2026-09-18 Provider 瞬态重试次数严格按设置执行（游戏开发 Agent 与策划 Agent 不再被档位收进区间）

 - 背景：AGC 客户端此前把 `agentLlm.<agent>.maxRetries` 按运行档位重新收进固定区间——`autonomous-game-build` 档位（自主构建的游戏开发 Agent 及其继承档位的专业子 Agent）被抬到 12~16，`standard` 档位（含立项策划入口的策划 Agent 与普通 Agent 对话）被压到最多 3；瞬态分类里的上游 400 还在同一预算上再收窄到 2 次。现场把 `maxRetries` 设成 5 时，游戏开发与策划两条链路都不按设置执行。
@@ -203,7 +203,7 @@ npm 游戏的可预览产物固定为对应 package 目录下的 `dist/index.htm

 - `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，不能换键重发。
+- 项目路径、projectId、当前 revision、源文件路径与媒体类型、operationId、Idempotency-Key、登录态、项目锁、付费提交、轮询恢复、下载校验与 manifest 事务全部由客户端持有。模型不能提交或覆盖这些字段。同一 Direct `clientTurnId + 规范语义参数` 生成稳定 UUID v4 身份；单回合同参重试复用原 operation，不同请求串行且最多四项（不计费的抠图派生请求不占该额度，见决策记录 2026-09-18）。跨回合存在完全匹配的 pending 账本时优先恢复原 operation，不能换键重发。
 - 资源查询同时投影未完成 operation 的安全状态。媒体工具成功只返回 operation、本地相对路径、资源类型、Canvas/resource/asset/task 身份、正式序列帧以及脱敏后的 `warnings / sliceWarnings`；错误继续使用统一脱敏边界。客户端资源账本持久化 completed 结果的两类告警，committed replay 不能把历史告警伪装成空集合。
 - 角色动画、视频、音效和背景音乐在构造新的远端请求前统一准备当前项目同名画布与素材目录上下文，并在端点支持时携带 `projectId / assetFolderId / canvasCompletion`。角色动画 placeholder 使用源图片真实宽高，避免非方形角色进入画布时失真；正式 resource/asset 与序列帧继续直接复用 External 返回身份，不从首帧伪造重复资源。已有冻结 request body 或已受理 operation 保持不变，不因本次升级重建请求或重复扣费。
 - 抠图通过新增 `agc_remove_background` 语义工具开放：模型只提交当前 manifest 的图片 `sourceLocalAssetId` 与结果名称；客户端解析稳定 `resourceId`，准备同名画布/素材目录并生成稳定 operation/idempotency 身份。普通登录态使用账号鉴权的 `/api/editor/images/background-removals`，ExternalDeveloper 模式使用 External v1 `/api/external/v1/editor/images/background-removals`；客户端接收异步受理后轮询任务状态，下载完成媒体并登记到本地 manifest，未知结果保留同一 operation 供恢复。抠图服务仍由客户端和服务端负责源校验、BgFilter、素材登记与画布事务，Codex 不获得内部 worker、凭据或任意 API 调用权。