Merge branch 'master' into fix/chat-state

2026-09-15 20:25:16 +08:00
parent 17716347e2 361daf374d
commit 09dcc0c263
106 changed files with 2023 additions and 1835 deletions
@@ -3370,16 +3370,32 @@
              "maxLength": 200
            }
          },
-          "sliceLayout": {
+          "sliceMode": {
            "type": "string",
-            "deprecated": true,
-            "description": "历史兼容字段，新的调用请使用 sliceCount。"
+            "enum": [
+              "connected-components",
+              "grid"
+            ],
+            "default": "connected-components",
+            "description": "图集切分模式。connected-components 按透明像素 alpha 连通域识别独立素材；grid 按用户提供的 gridX/gridY 划分网格槽。省略时使用 connected-components。"
+          },
+          "gridX": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 32,
+            "description": "grid 模式的横向网格数量。"
+          },
+          "gridY": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 32,
+            "description": "grid 模式的纵向网格数量。"
          },
          "sliceCount": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
-            "description": "可选的目标切片数量；省略时按图像内容自动识别。"
+            "description": "connected-components 模式下可选的目标切片数量；省略时按图像内容自动识别。grid 模式的切片数量由 gridX×gridY 决定。"
          },
          "screenColor": {
            "type": ["string", "null"],
@@ -3603,15 +3619,28 @@
          },
          "iconImageSrcs": {
            "type": "array",
-            "description": "识别图集中有效 alpha 连通域并持久化的独立素材，按视觉阅读顺序命名为“素材 N”；可通过 sliceCount 指定目标数量。",
+            "description": "按 sliceMode 识别或裁切并持久化的独立素材，按视觉阅读顺序命名为“素材 N”；connected-components 模式可通过 sliceCount 指定目标数量。",
            "items": {
              "$ref": "#/components/schemas/EditorIconSpritesheetIconResult"
            }
          },
-          "sliceLayout": {
+          "sliceMode": {
            "type": "string",
-            "deprecated": true,
-            "description": "历史兼容字段。"
+            "enum": [
+              "connected-components",
+              "grid"
+            ],
+            "description": "实际采用的图集切分模式。"
+          },
+          "gridX": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 32
+          },
+          "gridY": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 32
          },
          "sliceCount": {
            "type": "integer",
@@ -3628,7 +3657,7 @@
                "type": "null"
              }
            ],
-            "description": "可信透明图集已成功持久化，但全连通域自动拆分未完成时返回；此时 iconImageSrcs 为空，调用方仍应使用整张图集。原始连通域、输出数量或 CPU 预算超限不会产生切片 PUT、资源或画布切片。透明处理、Alpha/尺寸恢复、provider 原图修复性回读或透明图完整解码失败时走 provider 原图 source-only，sliceWarning 为 null。"
+            "description": "可信透明图集已成功持久化，但所选 sliceMode 的自动拆分未完成时返回；此时 iconImageSrcs 为空，调用方仍应使用整张图集。原始连通域、输出数量、网格裁切或 CPU 预算超限不会产生切片 PUT、资源或画布切片。透明处理、Alpha/尺寸恢复、provider 原图修复性回读或透明图完整解码失败时走 provider 原图 source-only，sliceWarning 为 null。"
          },
          "prompt": {
            "type": "string"
@@ -0,0 +1,35 @@
+# AGC 统一错误诊断与验收反馈实施计划
+
+Version: 1.0
+Status: active
+Date: 2026-09-15
+Parent Milestone: `【里程碑】AGC统一错误诊断与验收反馈-2026-09-15.md`
+
+## 修改边界
+
+1. 新增 `agent/runtime_error.rs`，承载统一事件字段、code/stage 白名单、脱敏后的 public projection、项目错误 JSONL/sidecar 落库和 detail 读取边界。
+2. `direct_runtime.rs` 使用统一事件替代仅写 `failure.json` 的路径；失败 assistant 投影带稳定 ID，下一轮 prompt 注入最近失败事件摘要。
+3. `codex_app_server.rs` 将 failed turn、idle/hard timeout、transport close、invalid terminal 和 stderr tail 转成稳定事件字段；不公开原始 detail。
+4. `direct_tool_bridge.rs` 与 `direct_tools_mcp.rs` 让 attempt 由客户端回合状态约束，越界请求返回终态工具错误；不扩展重试预算。
+5. `direct_runtime.rs` 的素材扫描递归覆盖可执行源码模块，基于 manifest 身份和浏览器 URL 映射判定；补充模块引用回归测试。
+6. 前端读取后端 `publicText/detailRef`，在现有 Runtime 错误面板中加入详情入口；不在 React 侧重新分类错误。
+
+## 实现顺序
+
+先写统一事件模型和 Rust 单测，再接 direct failure/app-server/tool bridge，随后接 prompt/history 与前端详情，最后修素材验收和 attempt 生命周期。每一步保留原有脱敏和失败关闭行为。
+
+## 验证命令
+
+- `cargo fmt --check`
+- `cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml runtime_error direct_runtime codex_app_server direct_tool_bridge`
+- `npm run --prefix apps/ai-game-creator-shell typecheck`
+- `npm run check:encoding`
+- `git diff --check`
+- 必要时运行 AGC deterministic playable E2E；真实 Provider smoke 与浏览器双视口 smoke 单独报告。
+
+## 风险与回滚
+
+- 统一事件 schema 只新增项目内文件和对话投影，不修改已有 manifest、公开 API 或 SpacetimeDB schema。
+- 若前端详情读取失败，仍展示安全 `publicText`，不阻塞错误终态。
+- 若素材身份无法映射，继续失败关闭并记录明确 code，不回退为路径字符串通过。
+- 回滚可删除新事件写入和详情入口，保留旧 `failure.json` 读取兼容。
@@ -0,0 +1,20 @@
+Version: 1
+Status: active
+Date: 2026-09-15
+Parent Spec: 【里程碑】AGC首页策划补全入口-2026-09-15.md
+
+## 修改顺序
+
+1. 在 `view/home/index.tsx` 增加本地复选框状态与入口切换清理。
+2. 将游戏勾选状态映射到既有 `ProjectStartMode`。
+3. 增加启动模式纯函数测试，覆盖模式分流；首页显示边界和切换清理作为后续组件测试补充项。
+
+## 验证
+
+- AGC 首页相关定向测试。
+- AGC 前端 typecheck。
+- `npm run check:encoding` 与 `git diff --check`。
+
+## 当前验证边界
+
+本次已交付测试覆盖 `planning` / `direct-build` 模式分流；“策划补全”复选框的显示边界及切换创作类型后的状态清理尚未有组件级自动化测试，需后续补充 `HomeView` 测试时完成。
@@ -0,0 +1,39 @@
+# AGC 统一错误诊断与验收反馈
+
+Version: 1.0
+Status: active
+Date: 2026-09-15
+Parent Spec: `docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md` 的“2026-09-15 AGC 统一错误事件、诊断落库与验收反馈”
+
+## 目标
+
+让 DirectProject 和共享 Agent Runtime 对失败使用同一份安全、可追踪、可恢复的错误事件合同；用户追问失败原因时能够读取上一轮证据；构建与浏览器验收只依据真实源码、manifest 身份和运行时证据判断。
+
+## 范围
+
+- 统一错误事件模型与项目内诊断落库。
+- DirectProject 失败 assistant 投影、下一轮诊断上下文和前端详情入口。
+- app-server 终态/超时、内置 MCP 工具错误和试玩 attempt 上限的分类。
+- 游戏源码模块素材扫描、manifest 身份映射与浏览器观察映射。
+- 定向 Rust/前端回归和现有 AGC 运行时门禁。
+
+## 不做
+
+- 不改变 Provider、External Editor 或 app-server 的 wire 协议。
+- 不放宽项目写锁、凭据隔离、工具白名单或完成门安全边界。
+- 不迁移历史项目文件；旧诊断只读兼容，新增事件使用新 schema。
+- 不把原始 stderr、请求正文或绝对路径展示给用户。
+
+## 验收标准
+
+1. 任一 DirectProject 失败均生成统一事件、稳定 `eventId` 和有界诊断引用；落库失败不覆盖原始错误。
+2. 失败安全投影写入对话历史，下一轮能读取 `publicText / code / stage / detailRef`，不会因追问而自动试玩。
+3. 结构化 failed turn、idle/hard timeout、transport close、MCP 参数错误和 `other` 各有稳定 code 与 recoveryHint。
+4. `attempt` 由客户端按回合分配并有上限；越界调用不会让回合继续等待。
+5. `game/src` 下模块引用已登记素材、Vite dist 稳定映射和浏览器实际观察均能通过；未登记素材仍失败。
+6. 脱敏测试证明 Token、Cookie、URL/query、私钥、宿主绝对路径和 stderr 私密内容不会进入用户文本。
+
+## 依赖
+
+- 现有 `direct_project_history`、`runtime_state`、`codex_app_server`、`direct_tool_bridge` 与浏览器 validation 证据。
+- 现有 DirectProject 诊断 sidecar 和 manifest 资源身份。
@@ -0,0 +1,20 @@
+Version: 1
+Status: active
+Date: 2026-09-15
+Parent Spec: AGC 首页与 Agent Runtime 入口
+
+## 范围
+
+在首页“做游戏”输入框下增加“策划补全”复选框；勾选后复用现有 `planning` 启动模式进入策划 Agent Runtime。
+
+## 验收标准
+
+- 仅“做游戏”显示复选框。
+- 勾选时提交 `planning`，未勾选时提交 `direct-build`。
+- “做方案”原有 `planning` 行为保持不变。
+- 切换到其它创作类型时清除游戏专属勾选状态。
+
+## 不做项
+
+- 不新增 runtime 类型、后端接口或持久化字段。
+- 不改变现有策划 runtime 内部流程。
@@ -8740,3 +8740,23 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 决策（面板可关 + 非模态任务面板）：两块生成浮层在提交期间放开 × / 遮罩 / Esc，提交按钮旁给「后台运行并关闭」；**关闭 ≠ 取消**（表单的 `await` 挂在该任务的终局上，不是面板生命周期）。新增「生成任务」非模态浮层（不铺遮罩、不做焦点陷阱、**不进** `isResourceCanvasFloatingPanelOpen` / `resourceCanvasHostGenerationPanelOpen` 遮挡判据），入口按钮 `aria-label="生成任务"`；已完成的条目按 `assetId` 复用既有 `pendingResourceFocusRef` 聚焦链定位素材卡。
 - 影响范围：新增 `apps/ai-game-creator-shell/src-tauri/src/asset_generation_tasks.rs`（+ `main.rs` 注册）、`src/features/resource-canvas/{resourceCanvasAssetGenerationTaskModel.ts,resourceCanvasAssetGenerationQueue.ts,ResourceCanvasAssetGenerationTasksPanelView.tsx}`；改动 `ResourceCanvasAssetGenerationPanelView.tsx` / `ResourceCanvasGenerationPanelView.tsx` / `src/view/project-development/index.tsx`；测试改动 `tests/{resourceCanvasAssetGenerationBackgroundClose.test.tsx,resourceCanvasAssetGenerationQueue.test.ts,resourceCanvasAssetGenerationTasksPanel.test.tsx}`（新增）与 `tests/appSurface/project-development.suite.ts`（把「每个入口一次 `generate_local_project_asset`」改成 `start_local_project_asset_generation` + `list_...` 轮询桩，载荷断言逐字不变）。**未动**：external v1 / OpenAPI、`packages/`、SpacetimeDB、音频入口的 pending-edit 账本语义、生成参数与 IPC 载荷字段名。
 - 关联文档：`docs/technical/【AGC】栏目画布底部工具栏入口矩阵-2026-09-13.md`（§4 / §4a / §8）、`docs/technical/【测试用例】AGC资源工作台V3端到端验收-2026-09-11.md`（S11a / §7.3）。
+
+
+## 2026-09-15 非 Suno 的 VectorEngine 能力切换到 Tiantoken
+
+- 决策：新增本地私密环境变量 `TIANTOKEN_BASE_URL` / `TIANTOKEN_API_KEY`（图片 timeout 可独立配置），承载原 VectorEngine 的文本和图片；`VECTOR_ENGINE_BASE_URL` / `VECTOR_ENGINE_API_KEY` 仅保留给 Suno 背景音乐与 Suno 音效。编辑器 SFX V2 继续走 ElevenLabs。
+- 实现边界：api-server 在创建状态时冻结 Tiantoken 配置，LLM、图片和旧版非 Suno 音频按该配置路由；Suno 的提交 / 轮询仍使用旧 VectorEngine 配置。旧 `vector_engine_*` 测试构造保留为 Tiantoken fallback，生产新环境变量优先。
+- 验证：Tiantoken `/v1/models` 返回 HTTP 200（126 个模型，含 `gpt-image-2`、`gpt-5.4-mini`）；api-server Tiantoken 配置单测、platform-audio 全量测试、图片定向测试、前端 `apiClient` 定向测试、`npm run typecheck`、`npm run check:api-server-env`、编码 / fmt / diff 检查通过。未对音频上游提交生成任务，模型列表未列出 audio / Vidu 条目。
+
+## 2026-09-15 删除旧版 Vidu 音效实现
+
+- 决策：旧版 Vidu `audio1.0` 的 submit / poll / download builder、旧视觉小说与创建音效死代码、对应 platform-audio 请求类型和测试全部删除。历史素材的 `audio1.0` 展示与定价兼容数据保留；新编辑器音效仍只走 ElevenLabs，Suno 音乐链路不变。
+- 验证：platform-audio 全量测试 55 条通过，api-server `cargo check` 通过，fmt / 编码 / diff 检查通过；仓库现役源码不再包含 `VIDU_AUDIO_MODEL`、`AudioTaskKind::SoundEffect` 或 Vidu submit/poll 实现。
+
+## 2026-09-15 AGC 统一错误事件与项目诊断落库
+
+- 背景：DirectProject 的 app-server 超时、MCP 参数错误、浏览器完成门误判和普通 Agent Runtime 失败分别投影为短文案；失败正文没有稳定落库，下一轮模型看不到上一轮失败证据，用户追问原因时可能继续试玩或重复修改。
+- 决策：新增 `agent/runtime_error.rs` 作为统一错误事件与有界诊断 sidecar 边界。DirectProject 失败、Agent Runtime terminal failure 均持久化 `.agent/runtime/errors/<eventId>.json`，并将脱敏 assistant 终态写回 `project.jsonl`；前端只通过 `read_agent_runtime_error_detail` 读取脱敏详情。旧 `failure.json` 保留兼容，不把原始 stderr、凭据、URL/query、宿主绝对路径写入用户文本。
+- 决策：错误使用稳定 `source / stage / code / retryable / publicText / recoveryHint / detailRef` 字段；试玩 attempt 越界返回终态错误并停止继续等待。素材完成门扫描实际 npm 源码模块，并把 manifest 中合法的自定义 art-spritesheet 路径纳入候选，构建和浏览器观察仍需通过既有完成门。
+- 关联规范：`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md` 的“2026-09-15 AGC 统一错误事件、诊断落库与验收反馈”；开发期计划见 `docs/project-memory/plans/【里程碑】AGC统一错误诊断与验收反馈-2026-09-15.md` 与对应实施计划。
+
@@ -1,5 +1,9 @@
 # 踩坑与排障记录

+## Windows 已登记生图资产未刷新
+
+Direct 工具桥会 canonicalize 项目根，事件中的路径可能带 `\\?\` / `\\?\UNC\`，而前端项目路径仍是普通盘符或 UNC。失效监听不能直接比较原始字符串；识别为同一项目后，用当前项目路径重读 manifest，保留项目切换与 revision 门禁。普通 `agc_generate_image` 成功提交也必须发出失效通知，不能依赖整轮 Agent 结束。回归需覆盖两种 Windows 前缀、其它项目事件拒收，以及 Agent 尚未结束和后续失败时已登记图片卡片仍可见。
+
 ## 2026-09-14 严格 IPC 桩缺登记新命令时，症状可能是「unhandled rejection + 不相干的提示断言」，而不是同一处报错

 - **现象**：`ProjectDevelopmentView` 新增「项目打开时读生成任务账本」（`list_local_project_asset_generations`）后，两个**别的关注点**的用例同时红：`resourceCanvasManualLayout.test.tsx` 报 `AssertionError: expected [ Array(1) ] to deeply equal []`（严格桩把新命令记进 `unexpectedCommands`），并伴随 7 条 `Unhandled Rejection: TypeError: Cannot read properties of undefined (reading 'map')`；`appSurface/project-development.suite.ts` 的「布局读时提示」用例则因为新命令被当成 unexpected invoke 抛错、触发了新的提示条，导致 `queryBySelector('.game-resource-live-notice')` 断言失败。
@@ -22,6 +26,11 @@
 - **验证**：`apps/ai-game-creator-shell/tests/start-dev-stack.test.ts` 新增两条——「探测脚本使用 netstat 且不再出现 Get-NetTCPConnection」「命令行按 PID 缓存后随请求下发、TTL 过期即失效」；定向 vitest 55 passed。本机实测：不含 SpacetimeDB 端口的探测 368 ms（原约 22 秒）、含 SpacetimeDB 端口 3.8 秒、命中缓存 368 ms；`npm run agc:serve` 的 `starting backend stack` → `backend ready` 由约 80 秒降到 16.7 秒（其中归属校验只占 4.4 秒，其余是 SpacetimeDB + api-server 的真实启动时间）。
 - **残留**：这台机器上首次 WMI 调用本身仍是秒级（曾见 18 秒），所以「新 SpacetimeDB PID 的第一次探测」仍可能多花几秒；命令行在进程存活期内不变，TTL 只用来限制 PID 复用造成的误判窗口。
 - **关联**：`apps/ai-game-creator-shell/scripts/start-dev-stack.mjs`（`readWindowsPortOwnerIdentities`）、`apps/ai-game-creator-shell/tests/start-dev-stack.test.ts`、`apps/ai-game-creator-shell/scripts/dev-windows-process.mjs`（退出清理仍走整份 `Win32_Process` 快照，自带 1 秒缓存，不在本次范围）。
+## 2026-09-15 AGC JSON API 的响应体也必须有等待上限
+
+- `fetchClientHttp` 的超时只覆盖请求到响应头返回；随后直接等待 `response.text()` 仍可能无限挂起。模型目录共用一个在途 Promise，响应体卡住会使后续刷新复用同一挂起请求、选择器持续忙碌。
+- 成功 JSON 与错误响应体均复用 `readClientHttpResponseText` 的 15 秒上限；超时后保留最后一次有效目录并释放在途请求，手动重试重新发起请求。迟到的响应不得覆盖重试获得的新目录。
+- 排查时区分接口未挂载（404）、未授权（401）、网络或响应体超时以及刷新无变化但缺少反馈；不能仅凭客户端启动 IPC 回退警告判断刷新失败原因。

 ## 2026-09-14 AGC 壳 Rust 套件按「一片一 job」拆分，且分片必须自校验覆盖

@@ -5587,3 +5596,10 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 - 原因：健康检查只能证明“有服务响应”，不能证明服务属于当前工作树；旧 `.app/dev-stack.json` 可能没有当前 `repoRoot`、`instanceId` 和服务级 dataDir 身份。
 - 处理：先读取 `.app/dev-stack.json`，核对顶层 `repoRoot + instanceId`，再核对服务 `repoRoot + instanceId + dataDir + pid + port`；AGC Vite marker 还必须带 `repoRoot + processId + port`。任何字段缺失或不匹配都拒绝静默复用，改为启动当前工作树自己的服务或明确提示清理。
 - 验证：`scripts/dev.test.ts`、`apps/ai-game-creator-shell/tests/start-dev-stack.test.ts` 覆盖 snapshot identity 和旧状态拒绝复用；运行时记录实际端口、进程命令行和 dataDir，不要只记录 HTTP 200。
+
+## 2026-09-15 登录失败提示必须保留接口返回原因
+
+- **现象**：账号登录失败时页面只显示“登录失败”，用户无法判断是手机号、验证码、密码还是服务状态问题。
+- **原因**：统一错误解析器只处理标准 `error.message/details` 结构；部分网关或旧兼容响应使用字符串 `error`，解析失败后回落到登录接口传入的通用文案。
+- **处理**：`parseApiErrorMessage` 同时支持字符串 `error`，标准嵌套结构保持原有优先级；未知或空响应继续使用通用兜底。
+- **验证**：`src/services/apiClient.test.ts` 新增字符串错误响应回归用例，定向测试 32 项通过，`npm run typecheck` 通过。
@@ -51,6 +51,8 @@ SpacetimeDB crate、SDK、CLI / standalone 与生成 bindings 按 `2.8.3` 对齐

 ## AGC DirectProject 与 UI workflow

+- AGC 安装产品名统一为“陶泥儿”，由 Tauri `productName` 控制安装项、快捷方式与 EXE 产品描述；Windows 内置 Codex 安装到顶层 `coding-agent/win-x64/`，打包资源映射与运行时查找路径必须一致。内部可执行文件名与应用 identifier 保持稳定。
+
 - 新 Web 游戏为 `game/` 下的 npm + Vite + Phaser 4.2.1 工程，使用包导入且允许其它依赖；npm 预览与导出只读取 dist，运行素材需纳入构建。单 HTML → Phaser 迁移固定走 DirectProject：文件落盘后先用受控 `project.bootstrap` 在 `game` 执行无参数 `npm install`，再用支持相对 cwd 的 `project.verify` 构建并确认 `game/dist/index.html`，已有单 HTML/Godot 不通过 JSON Generator 伪装成 npm 工程。

 - 通用 Agent Rust 分层为 `agent-runtime-core`（catalog、执行生命周期、ToolHost/spawn/all-join/Provider 契约）、`agent-runtime-orchestration`（动态无环任务图、ready、依赖波次、返工下游闭包和受限自主扩图提案）与 `platform-agent` 游戏适配器；循环返工通过新 pass / epoch 表达，不在单张依赖图中建立回边。LLM 可经宿主结构化 function call 提出新增节点/边，编排层只生成经校验的新候选图，epoch 与持久化仍由宿主掌控。
@@ -7,6 +7,8 @@
 - `GET/PUT /admin/api/agc-models` 仅 owner 可用，返回完整配置；PUT 携带上次读取的 revision，冲突拒绝覆盖。
 - `GET /api/llm/models` 返回启用项的 `id/displayName`、`defaultModelId` 和目录 `revision`，不返回实际模型名、Router 目录、凭据或能力原始数据。
 - 客户端缓存最近 `revision`，在项目切换 / 对话表面挂载 / 下拉展开 / 窗口聚焦时条件刷新：`revision` 未变化不更新界面，同一时刻只保留一个在途请求，刷新失败保留上一次有效目录与本地选择。发起对话前用同一份快照校验所选模型仍启用，已停用或删除则回退默认模型并提示。
+- 手动刷新立即显示进行中状态；真实刷新成功后显示完成反馈，即使 `revision` 未变化也有反馈。失败沿用有效缓存时仍显示失败，不能报告刷新成功；HTTP 状态和超时使用可辨认的提示。
+- 模型目录与其它客户端 JSON API 的成功、失败响应体读取均复用 `readClientHttpResponseText` 的 15 秒上限；响应头已返回但响应体卡住时必须结束本次等待、释放目录在途请求并允许重试，迟到的响应不得覆盖新目录。
 - AGC Responses 请求的 `model` 是稳定目录标识。服务端按当前目录映射实际模型名；未知、停用项拒绝，不回退其它模型。旧客户端无 AGC 标记时使用后台默认项。
 - 输入框右下角选择模型，只显示别名；选择保存到客户端配置 `selectedModelId` 与 `selectedModelIsDefault`（当前选择是否来自平台默认项），从下一次请求生效。加载失败或选项停用时禁用提交并允许刷新，不显示实际 ID 作为兜底文案。
 - `selectedModelIsDefault` 为真表示选择由平台默认项驱动（首次进入、默认项变化、所选模型失效回退），后台默认项变化时客户端跟随切换并提示；用户手动选择后置为假，不再被默认项变化覆盖。
@@ -19,4 +21,5 @@
 - 目录领域校验、未知/停用模型拒绝、客户端响应不包含实际模型名。
 - 后台鉴权、持久化 revision 冲突处理；客户端选择保存后重新读取，设置保存不覆盖选择。
 - 目录 `revision` 条件刷新与并发触发去重、发送前回退默认模型、刷新失败可恢复。
+- 响应体超时保留有效缓存、再次刷新重新请求、迟到响应不覆盖新目录；手动刷新进行中、同版本成功与缓存兜底失败反馈。
 - AGC/admin-web 类型检查与定向测试、编码检查、Rust 定向检查、schema 一致性与 diff 检查。
@@ -265,7 +265,7 @@ Supervisor 认领该回执后，由父 run 自己为每个原 delivery 逐一创
 - 模式合同：客户端 AppData 配置新增全局 `agentMode`，只接受 `codex_cli / provider`。缺省和新安装默认使用 `codex_cli`，原有 HTTP LLM Provider 路径完整保留并可显式切回 `provider`；切换只影响下一次节点请求，不新增 Runner、任务图、会话库、配置库或业务事实源。
 - 调度边界：正式 DAG、manifest、Agent task/session/run 身份、队列、锁、委派、all-join、完成门、Provider lifecycle、持久 retry/handoff 与 `needs-reconciliation` 继续由现有 AGC Runtime 掌控。每个被调度节点在 `codex_cli` 模式下直接启动一次非交互 `codex exec` 充当该节点的推理 Agent；Codex 返回当前 Runtime 广告函数的结构化调用，Runtime 仍是唯一 ToolHost，不允许 CLI 自己写项目、执行命令、调用 MCP 或形成第二套 revision / verification 真相。
 - 安装包侧车：Windows x64 release 固定随 Tauri resource 打包 `@openai/codex@0.147.0` 的原生 `codex.exe`；Rust build script 从 AGC 子包锁定依赖 stage 到 resource，并写入版本与 SHA-256 清单。Windows 侧车映射只写入 `tauri.windows.conf.json`，通用 `tauri.conf.json` 不得让 Linux / macOS 构建依赖未生成的 Windows 二进制。运行时只在文件摘要和 `codex-cli` 版本同时匹配清单时优先选内置侧车；缺失、损坏或版本漂移时跳过它，按既有 npm 安装、PATH 顺序回退。安装包同时携带 Apache-2.0 第三方声明；API Key、`auth.json`、Cookie、Token、用户 `CODEX_HOME`、用户配置和项目数据绝不打包。
- Windows x64 release 安装包只生成 NSIS，不生成 MSI：`tauri.windows.conf.json` 的 `bundle.targets` 固定为 `["nsis"]`，通用配置继续保留其它平台的默认打包目标。
+- Windows x64 release 安装包只生成 NSIS，不生成 MSI：`tauri.windows.conf.json` 的 `bundle.targets` 固定为 `["nsis"]`，通用配置继续保留其它平台的默认打包目标。安装后的产品名、开始菜单 / 桌面快捷方式和 EXE 产品描述统一由 `tauri.conf.json` 的 `productName: "陶泥儿"` 生成；应用 identifier 与内部可执行文件名保持稳定。内置 Codex 资源安装到顶层 `coding-agent/win-x64/`，运行时从同一路径查找 `bin/codex.exe` 与 `manifest.json`；仓库 staging 仍使用 `resources/codex/win-x64/`，包内子目录、组件名、版本和完整性校验保持原合同。
 - CLI 安全边界：CLI 固定使用 argv 启动，禁止 shell 拼接；工作目录使用本次请求专用的空临时目录，不把游戏项目绝对路径写入 prompt、stdout、stderr 或持久记录。调用固定使用 ephemeral、忽略用户配置和 exec rules、read-only sandbox、never approval，并关闭 Codex shell tool；只继承 CLI 运行和认证所需的最小环境，显式移除宿主 `CODEX_API_KEY`。用户级 Codex 登录态继续由本机 Codex 自己读取，API Key、auth 文件、Cookie、Token、`CODEX_HOME` 私有内容不得复制到项目配置、Runtime sidecar、Agent DB、conversation 或日志；stdout / stderr 无换行时也受硬上限约束，stderr 诊断只记录固定分类、字节数和 SHA-256。
 - 协议边界：Runtime 把既有 `LlmRunRequest` 的消息和当前函数目录编码为有界 prompt，并从同一函数 JSON Schema 生成 Codex structured-output schema。CLI 输出转换为现有 `LlmRunResponse / LlmToolCall` 后，继续经过 native tool / MCP 参数校验、动作上限、权限、pending、receipt、验证与格式修复链；最终回复仍走唯一提交路径，不新增平行响应协议。
 - 取消与恢复：Codex 子进程绑定当前 Provider request lifecycle，取消、暂停、Runner draining 或 GUI owner 丢失时终止并回收当前进程；started 后没有可信终态仍沿现有 Provider reconciliation 处理。`agentMode`、CLI 可执行身份和影响输出的 Codex 参数进入 `providerConfigFingerprint`，模式切换不得消费另一模式遗留的 retry/handoff。
@@ -1167,7 +1167,7 @@ game-project/

 - `.agent/manifest.json` 的存储写边界使用同目录持久文件锁跨线程、跨进程串行化；锁必须覆盖旧 manifest 读取、不可变版本前缀校验、临时文件安装和安装后回读一致性校验。锁文件拒绝符号链接、非普通文件和异常所有权 / 硬链接；Windows 使用不共享写句柄，Unix 使用 `O_NOFOLLOW + flock`。旧快照在新版本安装后只能被拒绝，不能覆盖已追加版本。
 - 后台 Agent 的 manifest 变化以共用 Runtime 状态投影 / 终态 emitter 作为失效因果点：`game-creator-agent-runtime-update` 的 Rust / TypeScript DTO 固定携带 `manifestInvalidated`，且 App 必须在 Supervisor、selected agent、session 和 run 身份的任何 early return 之前处理失效。GUI 进程内 Runtime 直接发该事件；External Runner 是独立进程、没有 GUI `AppHandle`，因此 Runner 协议 v5 的 `runner.attach_gui_owner` 必须登记 GUI 创建的随机 loopback 端口和 64 位随机令牌，Runner 的同一 emitter 通过受令牌保护的短连接转发 `game-creator-manifest-invalidated`。两条路径都只传项目路径与 Agent 身份，不复制 manifest，也不靠轮询补偿。
- Direct Codex 不伪造普通 Agent Runtime state。每张平台美术在本地文件与 manifest 提交成功后，统一通过 standalone `game-creator-manifest-invalidated` 发送 `projectPath + direct-codex-art`；只读恢复的已付费源图同样在 `register_local_asset_at` 成功后发送，下载、解码、文件写入或登记失败时不得发送成功失效。前端仍把 `game-creator-agent-progress` 仅用于进度文案；Direct Codex 整体命令成功、失败或超时 reject 后都追加一次 manifest 最终对账，只有完整成功才启动本地预览。
+- Direct Codex 不伪造普通 Agent Runtime state。每张平台美术在本地文件与 manifest 提交成功后，统一通过 standalone `game-creator-manifest-invalidated` 发送 `projectPath + direct-codex-art`；普通 `agc_generate_image` 同样在生成通道成功返回后、工具结果组装前发出通知，不能只覆盖标准美术包。只读恢复的已付费源图同样在 `register_local_asset_at` 成功后发送，下载、解码、文件写入或登记失败时不得发送成功失效。失效事件匹配当前项目时统一 Windows 盘符、UNC 与对应 verbatim 前缀的写法，实际重读始终使用当前项目保存的路径；该比较仅用于刷新提示，不替代后端路径与权限校验。前端仍把 `game-creator-agent-progress` 仅用于进度文案；Direct Codex 整体命令成功、失败或超时 reject 后都追加一次 manifest 最终对账，只有完整成功才启动本地预览。
 - App 收到当前项目的 Runtime / relay 失效后重新调用 `get_local_game_manifest`。重读按项目 single-flight 合并事件风暴；读取中再到达失效只追加一轮串行重读，不并发提交同项目响应。应用结果同时校验组件仍挂载、当前项目路径和项目 scope version；项目切换、组件卸载或旧 scope 的迟到响应不得覆盖新项目。Project Supervisor 对外发布前以“revision 前读 -> manifest -> revision 后读”取得一致快照，再通过 `onManifestChange(projectPath, manifest, metadata)` 携带 `projectId + revision + source`；启动器按 `projectPath + projectId` 只接受更高 revision，同 revision 只接受内容一致的重复，旧轮询和同 revision 分叉都不得覆盖。资源列表、依赖图输入、任务状态、运行入口和正式版本卡必须在当前页面实时重投影，不要求关闭或重开项目。集成测试记录“事件未重新打开项目”的调用基线前，必须先等待项目写入最近列表后触发的只读目录状态刷新完成，不能把这项合法后台检查误算成失效事件副作用。
 - `.agent/agent.db` 有界尾部读取报告截断时，审计 producer 映射失败关闭，不生成基于不完整审计的 producer、task flow 或对应任务环。前端收到截断 DTO 时只剔除 `producerAssignments`、`taskFlows` 与对应 `cyclicTaskIds`；Rust 根据当前 manifest、精确资源引用和仍可信任务深度下限返回的 `dependencyDepths` 继续保留，前端只校验资源仍存在且深度为非负安全整数，不得自行重算或压平权威深度。精确引用边、reference connection index、`cyclicResourceIds` 与 unresolved references 同样继续保留。
  -- 资源依赖 SVG 继续作为不可交互装饰层隐藏，但 dependency 画布通过 `aria-describedby` 提供当前可见精确引用和任务流的文本等价列表。中央资源聚焦按稳定 `resourceId` 驱动焦点状态：仅 `null -> id` 或 `idA -> idB` 聚焦详情 region，同一 ID 的 manifest 重投影不得抢走音频、视频、链接或关闭按钮焦点；显式收起和 Escape 恢复画布滚动并优先聚焦原触发卡片。聚焦资源被删除时清理 stale focused / selected ID，关闭详情并把焦点落到资源搜索框；项目切换或运行视图切换清除旧恢复意图，不得恢复旧项目卡片。橙色引用线及箭头使用对 `#fffdfa` 画布达到至少 `3:1` 的颜色。
@@ -1379,3 +1379,15 @@ DirectProject 使用 `approvalPolicy=never`，避免每次原生调用再经过
 ## 2026-09-14 新游戏策划到真实美术接入的连续交付

 DirectProject 在收到完整游戏策划或游戏制作请求后，必须把视觉素材作为同一交付链路处理：先读取当前项目已登记资源；策划案包含角色、对象、背景、特效、界面或其它视觉实体且现有资源不满足时，Codex 必须在同一游戏实现任务中调用审核的 `agc_tools` 生图或编辑工具，读取返回的资源身份与相对路径，把真实产物接入游戏源码，再构建并验证实际渲染。生成了素材但源码仍使用 emoji、CSS 形状或临时占位图替代策划要求的视觉元素，不能报告游戏完成。只有策划明确不需要视觉素材，或现有已登记素材完全满足需求时，才允许跳过生图；图片生成、处理、登记和接入不因用户没有重复输入“生图”而降级为可选建议。
+
+## 2026-09-15 AGC 统一错误事件、诊断落库与验收反馈
+
+DirectProject、Agent Runtime、Provider、app-server、内置 MCP、命令执行、构建和浏览器试玩的失败必须先转换为统一的 `AgentRuntimeErrorEvent`，再分别投影到用户消息、运行面板和项目诊断文件；业务模块不得自行拼接只有一句“执行失败”的终态文案。统一事件至少包含 `schemaVersion / eventId / clientTurnId / source / stage / code / retryable / occurredAt / elapsedMs / publicText / recoveryHint / detailRef`，其中 `publicText` 是脱敏后的可行动摘要，`detailRef` 指向项目内有界诊断记录；Token、Cookie、URL/query、私钥、宿主绝对路径、原始请求正文和未脱敏 stderr 不得进入对话或用户可见文本。
+
+项目内统一落库目录为 `.agent/runtime/errors/`，事件记录采用幂等 JSONL 或 JSON sidecar；写入失败不能覆盖原始业务错误，但必须在事件中标记 `persistenceFailed`。DirectProject 对话历史必须持久化本轮用户消息、终态错误的安全 assistant 投影和诊断引用，使下一轮能够读取上一轮失败证据。前端只展示 `publicText`，点击详情后按 `detailRef` 读取有界、脱敏的诊断，不直接展示私有 `detail`。
+
+`turn/completed` 等待超时必须区分 `idle-timeout`、`hard-timeout`、`transport-closed`、`failed-turn`、`invalid-terminal` 和 `tool-error`；收到内置工具参数错误后必须结束当前工具调用并进入可行动终态，不能继续使用越界的试玩 `attempt` 或无限等待。试玩次数由客户端按当前 `clientTurnId` 持久化分配，模型不能自由递增；超过上限必须返回一次终态并停止回合。
+
+游戏素材完成门必须扫描实际参与构建的 `game/` 源码模块，读取 manifest 的登记身份与相对路径，并把构建后的 URL 映射回登记身份。固定素材路径只能作为兼容候选，不能作为唯一准入。已登记且被真实源码引用、被构建纳入并在浏览器证据中观察到的资源通过；未登记、来源不匹配或只存在于设计规范中的资源继续失败关闭。
+
+验收至少覆盖：普通错误、结构化 app-server failed turn、idle/hard timeout、MCP 参数错误、历史落库失败、脱敏边界、下一轮诊断上下文、源码子模块素材引用、Vite 构建 URL 映射以及试玩次数上限。统一错误事件和诊断落库先于 UI 美化或增加重试预算；不能用延长超时、删除完成门或把失败投影为成功来规避问题。
@@ -344,7 +344,7 @@ UI 使用“批准”和“继续修改”两个文字按钮，分别配 Lucide

 项目运行模式通过 `.agent/runtime-mode.json` 持久化。新建策划项目在进入工作台前写入 `design`；“做成游戏”先登记 `design_artifacts` 中尚未登记或登记信息已变化的策划产物，若 manifest 实际发生变化则在同一项目写锁范围内推进一次项目 revision，再写入 `game`。重复切换不重复登记或推进 revision。重新打开项目时通过 `get_design_agent_runtime_mode` 读取模式，完成后一次性挂载对应工作台，不能先挂载 GameAgent 再切回策划。旧项目缺少模式文件但存在策划会话时按 `design` 恢复；明确的 `game` 标记优先于残留策划会话。无模式也无策划会话的项目仍使用游戏工作台。

-开发构建的策划工作区页头在“刷新”旁提供“快速准备做成游戏测试”按钮。该入口与策划 Debug 日志共用 `GENARRATIVE_AGC_DESIGN_DEBUG=1` 开关：开关未启用时按钮不显示，命令也不可执行。入口仅进行本地 fixture 和会话状态写入，不调用 Provider；完成后自动刷新文件树与阶段，通过 `design-agent-update` 状态事件同步右侧审批/阶段操作区。随后仍需点击正常的“做成游戏”按钮执行资产登记与运行时切换。
+开发构建的策划工作区页头在“刷新”旁提供“快速准备做成游戏测试”按钮。策划 Debug 日志和该入口共用运行时环境变量 `GENARRATIVE_AGC_DESIGN_DEBUG=1`；前端通过 Tauri 查询当前构建是否具备 Debug 入口，只有 Debug 构建且变量启用时显示按钮，命令也不可执行。入口仅进行本地 fixture 和会话状态写入，不调用 Provider；完成后自动刷新文件树与阶段，通过 `design-agent-update` 状态事件同步右侧审批/阶段操作区。随后仍需点击正常的“做成游戏”按钮执行资产登记与运行时切换。

 ## 15. 策划 Agent reasoning 展示

@@ -214,7 +214,7 @@ spacetime sql <database> "SELECT * FROM runtime_setting LIMIT 1" --server http:/

 本地 `spacetime` CLI / standalone 版本必须和 `server-rs/Cargo.toml` 里锁定的 `spacetimedb` 版本一致；当前统一版本为 `2.8.3`，CLI / standalone commit 固定核对为 `8e410d2842147bd8e5a32a9589cc00c19f7478e2`。若版本或 commit 错配，procedure 返回值可能在宿主侧触发 `Failed to BSATN deserialize procedure return value`，api-server 最终表现为现役 settings、editor project 或 profile procedure 超时。排障时先运行 `spacetime --version`，再对照 `server-rs/Cargo.toml` 的 `spacetimedb = "..."`；其它版本可执行 `spacetime version install <version> && spacetime version use <version>`，升级后重启 `npm run dev:spacetime` 再重试。当前 `scripts/dev.mjs` 会把 tool version 和 commit 一起写入 `dev-spacetime-tool-version`，启动新 standalone 与复用已有本地进程时都要求 `2.8.3 + 8e410d28...` 同时匹配；旧版本或旧单行版本记录会拒绝复用并要求重启。2.6.1 修复了 procedure context 中调用者 `Identity` / `ConnectionId` 始终为空的回归，依赖 `ctx.sender` 鉴权时必须同时确认宿主已升级。

-本地 `.env`、`.env.local` 或 `.env.secrets.local` 修改后必须重启 `api-server` 才会生效；若已经通过 `npm run dev` 启动完整联调，可在该终端输入 `rs api-server`。排查图片编辑器 VectorEngine 生成链路时，确认 `VECTOR_ENGINE_BASE_URL`、`VECTOR_ENGINE_API_KEY` 和 `VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS` 只在本地或服务器密钥文件中配置，不能写入 Git。`VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS` 是单次 attempt 的配置上限，默认 `1000000`；配置加载层允许显式值低于该默认值，不再在读取环境变量时强制抬高。业务模型和 VectorEngine provider 首选请求都使用 `gpt-image-2`，符合条件时才回退到兜底模型 `gpt-image-2-c`；图片协议、URL / base64 响应解析、远端图片下载和 provider 侧结构化日志在 `server-rs/crates/platform-image`，`api-server` 只做编辑器请求编排、OSS / asset 持久化、计费和失败审计落库。`platform-image` 会在 JSON 生成和 multipart 编辑请求发送前按同一 GPT-image-2 family 规则归一显式像素尺寸；若请求发送失败，先按同一 `request_id` 查看 provider 日志与 `external_api_call_failure.metadata_json.errorSource`，当前 multipart `/v1/images/edits` 单独强制 HTTP/1.1。
+本地 `.env`、`.env.local` 或 `.env.secrets.local` 修改后必须重启 `api-server` 才会生效；若已经通过 `npm run dev` 启动完整联调，可在该终端输入 `rs api-server`。排查图片编辑器 Tiantoken 生成链路时，确认 `TIANTOKEN_BASE_URL`、`TIANTOKEN_API_KEY` 和 `TIANTOKEN_IMAGE_REQUEST_TIMEOUT_MS` 只在本地或服务器密钥文件中配置，不能写入 Git。VectorEngine 配置仅保留给 Suno 音乐任务。`TIANTOKEN_IMAGE_REQUEST_TIMEOUT_MS` 是单次 attempt 的配置上限，默认 `1000000`；配置加载层允许显式值低于该默认值，不再在读取环境变量时强制抬高。业务模型和 Tiantoken provider 首选请求都使用 `gpt-image-2`，符合条件时才回退到兜底模型 `gpt-image-2-c`；图片协议、URL / base64 响应解析、远端图片下载和 provider 侧结构化日志在 `server-rs/crates/platform-image`，`api-server` 只做编辑器请求编排、OSS / asset 持久化、计费和失败审计落库。`platform-image` 会在 JSON 生成和 multipart 编辑请求发送前按同一 GPT-image-2 family 规则归一显式像素尺寸；若请求发送失败，先按同一 `request_id` 查看 provider 日志与 `external_api_call_failure.metadata_json.errorSource`，当前 multipart `/v1/images/edits` 单独强制 HTTP/1.1。

 编辑器 ElevenLabs 音效生成只从服务端读取 `ELEVENLABS_BASE_URL`、`ELEVENLABS_API_KEY` 和 `ELEVENLABS_REQUEST_TIMEOUT_MS`，timeout 默认 `180000ms`；base URL 或 Key 缺失时失败关闭，不回退 Vidu。生产 API 与 external-generation worker 通过共享 API env 取得同一配置，模板见 `deploy/env/api-server.env.example`；Key 不得进入 Web/Vite 环境、命令参数、日志、fixture 或仓库。普通测试只使用 loopback mock，禁止把真实付费请求作为 T3 自动验收。

@@ -790,14 +790,14 @@ PowerShell 下按测试文件头部示例依次设置三个必填变量，并按

 该用例只从进程环境变量读取凭据，不读 `.env.secrets.local`，也不会写入任何文件。真实 API Key 一律不得提交进仓库，也不要写进 `docs/`、脚本默认值或测试 fixture；临时密钥用完应在上游及时吊销。

-创意 Agent `gpt-5` 文本链路已从 APIMart 切到 VectorEngine：`api-server` 读取 `VECTOR_ENGINE_BASE_URL` / `VECTOR_ENGINE_API_KEY` 构造 OpenAI-compatible LLM client，并自动补齐 `/v1` 前缀用于 Responses 协议。排查或切换密钥后，可在本地运行：
-创意 Agent `gpt-5.4-mini` 文本链路已从 APIMart 切到 VectorEngine：`api-server` 读取 `VECTOR_ENGINE_BASE_URL` / `VECTOR_ENGINE_API_KEY` 构造 OpenAI-compatible LLM client，并自动补齐 `/v1` 前缀后请求 `/chat/completions`。通用 `/api/llm/chat/completions` 代理使用 `GENARRATIVE_LLM_PROVIDER=openai-compatible`、`GENARRATIVE_LLM_BASE_URL=https://api.vectorengine.cn/v1`、`GENARRATIVE_LLM_MODEL=gpt-5.4-mini`，未单独配置 `GENARRATIVE_LLM_API_KEY` 时可复用 `VECTOR_ENGINE_API_KEY`。排查或切换密钥后，可在本地运行：
+创意 Agent 文本链路使用 Tiantoken：`api-server` 读取 `TIANTOKEN_BASE_URL` / `TIANTOKEN_API_KEY` 构造 OpenAI-compatible LLM client，并自动补齐 `/v1` 前缀用于文本协议。排查或切换密钥后，可在本地运行：
+创意 Agent `gpt-5.4-mini` 文本链路使用 Tiantoken：`api-server` 读取 `TIANTOKEN_BASE_URL` / `TIANTOKEN_API_KEY` 构造 OpenAI-compatible LLM client，并自动补齐 `/v1` 前缀后请求 `/chat/completions`。通用 `/api/llm/chat/completions` 代理使用 `GENARRATIVE_LLM_PROVIDER=openai-compatible`、`GENARRATIVE_LLM_BASE_URL=https://api.tiantoken.com/v1`、`GENARRATIVE_LLM_MODEL=gpt-5.4-mini`，未单独配置 `GENARRATIVE_LLM_API_KEY` 时可复用 Tiantoken 凭据。排查或切换密钥后，可在本地运行：

 ```bash
 node scripts/test-ve-llm.mjs
 ```

-该脚本读取仓库根目录 `.env.secrets.local` 中的 `VECTOR_ENGINE_BASE_URL` 和 `VECTOR_ENGINE_API_KEY`，依次探测 `/v1/models`、`/v1/chat/completions`、`/v1/responses`、`gpt-5.4-mini` Chat Completions 和基础 JSON 输出能力；脚本只输出 HTTP 状态、耗时、模型和截断摘要，不应打印密钥。若 `.env.secrets.local` 不存在，先补本地 secrets 文件再运行，不要把 secrets 提交进仓库。
+该脚本读取仓库根目录 `.env.secrets.local` 中的 `TIANTOKEN_BASE_URL` 和 `TIANTOKEN_API_KEY`，依次探测 `/v1/models`、`/v1/chat/completions`、`/v1/responses`、`gpt-5.4-mini` Chat Completions 和基础 JSON 输出能力；脚本只输出 HTTP 状态、耗时、模型和截断摘要，不应打印密钥。若 `.env.secrets.local` 不存在，先补本地 secrets 文件再运行，不要把 secrets 提交进仓库。

 ### 手机验证码短信

@@ -40,6 +40,7 @@
 ## 生成契约

 - 前端提交到 `POST /api/editor/icon-spritesheets/generations`。
+- 图集拆分通过 `sliceMode` 显式选择：`connected-components` 按透明像素连通域切分（默认），`grid` 按用户提供的 `gridX × gridY` 网格切分。
 - 图标规范生成在 inline 模式下也必须先建立带稳定请求指纹的 generation operation，并由编辑器生成 durable billing 边界包住共享执行器；不得在 `operation=None` 时调用 provider 后再进入原子结果持久化。
 - 图标 spritesheet 的入队与实际执行路径都必须在引用解析、generation input 重建、定价和 provider / OSS 副作用之前预检 owner、项目和最终素材目录，并将返回的 canonical `projectId + assetFolderId` 回写到后续流程；请求省略目录时按实际写入的 owner 默认目录预检，worker 不得只信任入队时的旧校验结果。
 - queued 图标规范生成由共享原子结果持久化使用 worker caller 中的 lease 一并完成任务并清理 lease；共享执行器返回成功后 worker 只能返回 `Ok(())`，不得再次调用 job completion。
@@ -30,7 +30,7 @@ SFX V2 已完成产品与技术口径冻结及 T0–T6 工程实施；这不表

 - `prompt`：用户在输入框确认的原始语言音效描述，语义为 `userPrompt`，继续复用对外请求和持久化字段 `prompt`。消费动作前按 ECMAScript `String.trim()` 语义只删除首尾空白和行终止符，包含 `U+FEFF`；不改写内部空白、换行、标点、零宽字符或 Unicode 形式。首尾 `U+0085` 不属于该删除集合。按 Unicode code point 计数，合法范围为 `1-2048`。空值和全空白不得回退“游戏音效”。
 - `actualPrompt`：Worker 在正式生成时对冻结的 `userPrompt` 进行统一英文化并严格验收后得到的英文 Prompt，继续复用持久化字段 `actual_prompt`。前端不提交 `actualPrompt`，ElevenLabs 只接收验收通过的 `actualPrompt`。
- `model`：新任务固定 `eleven_text_to_sound_v2`，UI 以禁用态模型胶囊显示 `ElevenLabs`，客户端不决定模型。历史 `audio1.0` 只作旧素材展示和其它未迁移调用方的兼容标识，不是新编辑器 SFX 任务的 alias 或 fallback。
+- `model`：新任务固定 `eleven_text_to_sound_v2`，UI 以禁用态模型胶囊显示 `ElevenLabs`，客户端不决定模型。历史 `audio1.0` 只作旧素材展示标识，不是新编辑器 SFX 任务的 alias 或 fallback。
 - `duration`：`null` 表示自动时长，有限数值表示手动时长。首次打开面板默认处于自动模式，并预置最近手动值为 `5s`；手动范围 `0.5-30s`，UI 步进 `0.1s`。自动模式禁用 slider 但保留最近手动值，关闭自动后恢复该值。服务端只校验有限值与范围，不把 UI 步进扩大成 provider 精度限制。
 - `loop`：独立布尔参数，默认 `false`，由页面开关原样冻结并传入 ElevenLabs。Prompt 是自由文本，系统不从 Prompt 推断、同步或校验 Loop；Prompt 文本与 Loop 开关不建立业务一致性门禁。
 - `prompt_influence`：服务端固定 `0.3`，不向前端开放滑杆或请求字段。输出格式固定为 query `output_format=mp3_44100_128`。
@@ -468,7 +468,7 @@ POST / api / editor / audios / background - music / prompts / simplifications;
  - 背景音乐在 body builder 边界防御性执行幂等 canonicalization，再按 canonical Prompt 检查至少一个有效字符和最多 200 个 Unicode code point；校验通过后用 canonical Prompt 构造 Suno body。不得复用语义不同的 `normalize_limited_text`，不得提供默认 Prompt。
  - Suno 音乐接口路径固定为 `/suno/submit/music`；`VECTOR_ENGINE_BASE_URL` 即使配置为带 `/v1` 的图片接口根，也要在 `platform-audio` 中归一为根路径后再拼接，避免误请求 `/v1/suno/submit/music`。
  - 新编辑器音效使用独立 ElevenLabs 直接二进制 adapter，不伪装成 Vidu / Suno 的 submit + poll 任务。adapter 负责 endpoint 归一、`xi-api-key` header、固定 query / body、单次 POST、有界二进制读取、MP3 验证和时长探测。
-  - Vidu `audio1.0` 的 body builder、轮询和下载能力仅保留给历史展示和其它未迁移调用方；新 `audio-sound-effect` 任务不进入 `/ent/v2/text2audio` 或 `/ent/v2/tasks/{taskId}/creations`，也不使用 Suno `task: "sound"`。
+  - 旧版 Vidu `audio1.0` 的 body builder、轮询和下载代码已移除；历史 `audio1.0` 只读展示，新 `audio-sound-effect` 任务不进入 `/ent/v2/text2audio` 或 `/ent/v2/tasks/{taskId}/creations`，也不使用 Suno `task: "sound"`。
  - Suno 提交成功后的任务 ID 兼容与 wav clip 轮询逻辑只保留给背景音乐链路；`/suno/fetch/{taskId}` 返回 `audiopipe.suno.ai/?item_id=...` 时，该地址只作为 clip id 来源，不作为最终下载文件，后端继续调用 `/suno/act/wav/{clipId}` 获取稳定 wav URL，避免 worker 在不完整 chunked body 上卡满超时。
  - VectorEngine 音频响应的 `code` 需要兼容 `"success"`、`"ok"`、`"0"`、`"200"` 以及数字 `0` / `200`；HTTP 非 2xx 时后端错误信息应透出安全的上游状态和短响应摘要，避免前端只显示笼统提交失败。
 - 在 `api-server/src/vector_engine_audio_generation/generation.rs` 原地演进现有编辑器音频 generation handler；以下正式路由保持原路径和现有注册，不新增平行 BFF：
@@ -526,7 +526,7 @@ POST / api / editor / audios / background - music / prompts / simplifications;
 - BGM 边界测试覆盖 200 / 201 个纯 Unicode `White_Space` 均归一为空并禁止三动作、大量边界空白包围 `A` 后只允许生成、`A` 加 199 个内部空格再加 `B` 后只允许简化、201 个 U+200B 或 U+FEFF 只允许简化、边界空白包围 200 个 `A` 后允许补全和生成，以及 TypeScript 与 Rust 对 U+0085、U+200B 和 U+FEFF 的一致行为。
 - BGM 助手入口测试覆盖 canonical 2000 字允许简化、2001 字返回 `400` 且不调用 LLM；两个助手路由 body 超过 `32 KiB` 时返回 `413`；连续合法请求不因本功能新增限流器返回 `429`。
 - 两个助手成功路由分别产生 `editor_background_music_prompt_completion` / `editor_background_music_prompt_simplification` tracking event，均为 `module_key = editor`、User scope；失败响应沿用普通 route tracking 只记录成功的现状。
- BGM Suno body 仍只包含 `mv`、`gpt_description_prompt`、`make_instrumental`，固定 `Suno` 胶囊和动态泥点价格不变；历史和其它未迁移 Vidu 调用方的 builder / 轮询能力保持可用，但新编辑器 SFX 任务只调用 ElevenLabs。
+- BGM Suno body 仍只包含 `mv`、`gpt_description_prompt`、`make_instrumental`，固定 `Suno` 胶囊和动态泥点价格不变；旧版 Vidu builder / 轮询能力已移除，历史素材只读展示，新编辑器 SFX 任务只调用 ElevenLabs。
 - `audio-sound-effect` 与 `audio-background-music` 必须由同一个音频 composer 渲染，并在组件内通过 `isSoundEffect` 分支。SFX 不得渲染 BGM 的补全 / 简化、Suno 模型和 BGM 字符规则；BGM 不得渲染 SFX 的一键优化、Loop、ElevenLabs 模型和 SFX 时长控件。两个 mode 相互切换时，菜单、预设滚动、锁、快照和助手状态不得跨分支泄漏。
 - SFX V2 翻译失败时 ElevenLabs 请求数为 0；成功时每个平台 job 最多一次 ElevenLabs POST，`prompt / actual_prompt`、实际时长、Loop、model、provider 和 Task ID 在队列、素材、画布、响应、刷新和重绘后保持权威一致。
 - SFX 两类 LLM 请求契约测试分别断言：一键优化每次请求为 Luna + Medium + `max_completion_tokens = 8192`，翻译每次业务尝试为 Luna + Low + `max_completion_tokens = 8192`，两者都不含 `max_tokens`、`max_output_tokens` 或 temperature；测试命名和说明必须把 `8192` 解释为包含 reasoning 的 completion tokens 总预算。优化遇到 `finish_reason = length` 直接失败且不写回；翻译首轮 `length` 只重试一次，第二轮 `length` 最终失败且 ElevenLabs 请求数为 0。