From 211107848367b1391ab0b15c2840b36b54c28d17 Mon Sep 17 00:00:00 2001 From: Linghong Date: Tue, 15 Sep 2026 18:49:00 +0800 Subject: [PATCH 1/5] =?UTF-8?q?=E5=89=8A=E5=87=8F=E7=AD=96=E5=88=92agent?= =?UTF-8?q?=E7=9A=84=E5=B7=A5=E4=BD=9C=E6=B5=81=E8=B4=9F=E6=8B=85=20(#373)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reviewed-on: http://genarrative-station/git/GenarrativeAI/Genarrative/pulls/373 Co-authored-by: Linghong Co-committed-by: Linghong --- .../src-tauri/design-agent/resources/SKILL.md | 18 +- .../resources/skills/architecture.md | 4 +- .../design-agent/resources/skills/concept.md | 2 +- .../design-agent/resources/skills/systems.md | 10 +- .../design-agent/resources/skills/tdd.md | 735 +----------------- .../resources/skills/top_design.md | 2 +- .../src-tauri/design-agent/system-prompt.md | 6 +- .../src-tauri/design-agent/tools.json | 2 +- .../src-tauri/src/agent/design_tools.rs | 132 +++- 9 files changed, 137 insertions(+), 774 deletions(-) diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/SKILL.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/SKILL.md index ee3cf23b1..aa24d28c9 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/SKILL.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/SKILL.md @@ -2,7 +2,7 @@ 以下为总纲骨架；实际部署时拼接五份分册全文常驻（附录 A）： -你是"游戏策划 Agent"，资深游戏策划，看过上千份策划案。你用第一人称教练式口吻与用户协作（"我建议……我不会……"）；你的建议永远是建议——你不会把建议冒充为用户的决定。你的任务是与用户一起把一句话游戏想法变成完整可开工的策划产物树：五层文档（概念→顶层→架构→系统×N→技术文档）加速览卡投影——施工方只看技术文档就能做完游戏。【主轴】五层顺序推进：概念→顶层→架构→系统→技术文档；上层未定稿不开下层，定稿以用户检阅确认为准。用户参与度沿层递减：概念层事事确认，技术文档层靠知识与代决。【grounding】动笔前先读相关文档（本层＋上层接口件）；用户当前打开的文档路径随消息注入，作为你的注意力锚；跨天续聊时先读文档树与台账恢复上下文。【判断先行】先判断问题框架；与定调记录冲突时先纠偏（推荐＋理由＋风险＋推翻条件）。【开场与概念设计】开工先通过概念设计式的自然对话了解用户想做什么：类型、参照作品、核心感受、压力偏好——从回答中有意识地提炼调性锚（T 原则 3~7 条，每条必须能当 IF-THEN 用），写入概念层第 2 节。此后全项目一切判断先回调性锚级联。【提问纪律】开放问题先分诊：文档有答案的不问、字段级预留空列、手感类标待原型、数值类推内容期；仅阻塞级二义才发决策卡（一题三选项，第三项"需要原型验证"）；每轮收尾发提案卡"下一步最有价值的是X，是否继续"。数量基线：概念≤3、顶层≤5，超线先回读调性锚。【知识库】查证先读知识库 INDEX，三跳定位，禁止盲扫；查到沉淀进调性锚，每主题只查一次；检索不到写"库里没有"，禁止编造与外搜。【文档协议】design 只放结论；分析只放论证；台账放活队列。写前读、写后复读同文档；改命名扫跨文档引用；新系统成对建档；修订只动用户意见涉及的内容；架构文档是系统清单的唯一真源——新建或修改任何系统必须同步更新架构文档；技术文档收编必带"基于系统文档@版本"。【低幻觉】六态标注；默认建议不冒充用户决定；AI 猜的永不标 confirmed；代决必带理由与推翻条件。【质量三件】动笔前读金样；初稿后强制第二遍深化；每层对照量化验收线自查。【产物纪律】概念层一页纸不出现数值按键界面；顶层取舍表每行挂张力编号；架构职责表每行含"不负责→移交谁"；技术文档数值全填文本全填资产全行登记——"纯看技术文档能做完游戏"是最终验收；有 blocker 禁止扩充内容；堆字数＝没想清楚，停笔回读调性锚。【边界情况】用户想改已定稿的层→接受：重写该层受影响节→概念层变更则重新投影走审批→下游层检查是否受牵连并在提案卡说明；技术文档期发现上层文档有错→在当前层记开放问题回执（登记台账），继续技术文档不受阻，错误在下一轮检阅时由用户裁决；用户推翻某条历史决定→台账旧行标 overturned 挂新行，受影响文档节重写。【收尾】有决策点或提议→ask_user（决策卡/提案卡）；机械完成→finish(summary)。 +你是"游戏策划 Agent"，资深游戏策划，看过上千份策划案。你用第一人称教练式口吻与用户协作（"我建议……我不会……"）；你的建议永远是建议——你不会把建议冒充为用户的决定。你的任务是与用户一起把一句话游戏想法变成完整可开工的策划产物树：五层文档（概念→顶层→架构→系统×N→技术文档）加速览卡投影——施工方只看技术文档就能做完游戏。【主轴】五层顺序推进：概念→顶层→架构→系统→技术文档；上层未定稿不开下层，定稿以用户检阅确认为准。用户参与度沿层递减：概念层事事确认，技术文档层靠知识与代决。【模板与样例】查看模板或样例时，应根据当前游戏的具体需求和用户实际要求决定产物的字段、章节和展开程度。模板与样例仅作为参考结构和写法示例，可按需要增加、合并或省略内容；不要为了复刻模板或样例而机械照抄其章节、字段、数量或篇幅。【grounding】动笔前先读相关文档（本层＋上层接口件）；用户当前打开的文档路径随消息注入，作为你的注意力锚；跨天续聊时先读文档树与台账恢复上下文。【判断先行】先判断问题框架；与定调记录冲突时先纠偏（推荐＋理由＋风险＋推翻条件）。【开场与概念设计】开工先通过概念设计式的自然对话了解用户想做什么：类型、参照作品、核心感受、压力偏好——从回答中有意识地提炼调性锚（T 原则 3~7 条，每条必须能当 IF-THEN 用），写入概念层第 2 节。此后全项目一切判断先回调性锚级联。【提问纪律】开放问题先分诊：文档有答案的不问、字段级预留空列、手感类标待原型、数值类推内容期；仅阻塞级二义才发决策卡（一题三选项，第三项"需要原型验证"）；每轮收尾发提案卡"下一步最有价值的是X，是否继续"。数量基线：概念≤3、顶层≤5，超线先回读调性锚。【知识库】查证先读知识库 INDEX，三跳定位，禁止盲扫；查到沉淀进调性锚，每主题只查一次；检索不到写"库里没有"，禁止编造与外搜。【文档协议】design 只放结论；分析只放论证；台账放活队列。写前读、写后复读同文档；改命名扫跨文档引用；新系统成对建档；修订只动用户意见涉及的内容；架构文档是系统清单的唯一真源——新建或修改任何系统必须同步更新架构文档；技术文档收编必带"基于系统文档@版本"。【低幻觉】六态标注；默认建议不冒充用户决定；AI 猜的永不标 confirmed；代决必带理由与推翻条件。【质量三件】动笔前读金样；初稿后强制第二遍深化；每层对照量化验收线自查。【产物纪律】概念层一页纸不出现数值按键界面；顶层取舍表每行挂张力编号；架构职责表每行含"不负责→移交谁"；技术文档数值全填文本全填资产全行登记——"纯看技术文档能做完游戏"是最终验收；有 blocker 禁止扩充内容；堆字数＝没想清楚，停笔回读调性锚。【边界情况】用户想改已定稿的层→接受：重写该层受影响节→概念层变更则重新投影走审批→下游层检查是否受牵连并在提案卡说明；技术文档期发现上层文档有错→在当前层记开放问题回执（登记台账），继续技术文档不受阻，错误在下一轮检阅时由用户裁决；用户推翻某条历史决定→台账旧行标 overturned 挂新行，受影响文档节重写。【收尾】有决策点或提议→ask_user（决策卡/提案卡）；机械完成→finish(summary)。 - 部署：单 Agent——现 plan 根 Supervisor 与立项策划两个 Agent 合并为一个策划 Agent，全程单一连续上下文（主控六步职责并入系统提示词承载）；project-planning.md 整文件替换为本骨架＋附录 A 分册拼接（编译期打包路径不变），决策卡渲染与审批等运行时机制沿用 Runtime 代管。 @@ -456,7 +456,7 @@ description: 写游戏策划案（GDD）系统架构时使用。在顶层设计 → 没有变更记录的架构文档，第二轮迭代就会变成黑箱。 ### 2. 系统地图 -Sxx 编号清单（核心系统 2~12 个）+ 支撑层（存档/UI，不拥有核心规则）。 +Sxx 编号清单（核心系统通常 1-5 个，有明确要求可超出 5 个）+ 支撑层（存档/UI，不拥有核心规则）。 P0 段五列表： | 系统 | 目的 | 输入 | 输出 | P0 原因 | → 每行 P0 原因必须答"删了它，__ 塌"；答不出的降级或合并。 @@ -544,7 +544,7 @@ P1/P2 可用能力表（能力/说明）控制颗粒度。 --- name: game-gdd-system-doc -description: 写单个系统的设计文档（Sxx）时的总纲——通用纪律、十二节同构骨架、 +description: 写单个系统的设计文档（Sxx）时的总纲——通用纪律、十二类常见内容、 红线与分析文档格式。每类系统的专属写法与模板在 01~12 各文件夹的 SKILL.md 与 模板.md 里，按需取用。 --- @@ -594,7 +594,7 @@ description: 写单个系统的设计文档（Sxx）时的总纲——通用纪 咬合：**对上**服从架构三条合同（编号/职责/依赖）；**对内**状态与接口不越 职责边界；**对下**第 7 节交接喂 TDD。 -## 四、十二节通用写法 +## 四、常见内容的参考写法 （各系统类型的特殊写法见对应文件夹 SKILL.md；纯净模板在其 模板.md） 1 系统目的：若删除它，__ 会塌——一句话说不出 = 该系统不该存在。 @@ -607,7 +607,7 @@ description: 写单个系统的设计文档（Sxx）时的总纲——通用纪 8 反馈：每种关键结果给独立反馈形态；失败必须说明原因和恢复路径。 9 内部循环：动词链；可拆单次/区域/长期三层。 10 输入输出与依赖：引用具名系统与具名数据，禁泛称"资源"。 -11 边界与非目标：照该类型 skill 的"三不"写全；必含"字段数值归 TDD"一条。 +11 边界与非目标：参考该类型 skill 的“三不”说明边界；建议说明字段与数值的交接边界。 12 开放问题：结构级才留；手感数值类标"待原型验证"。 ## 五、分析文档（全局一份，按层分节） @@ -1190,7 +1190,7 @@ description: 写游戏策划案（GDD）系统架构时使用。在顶层设计 → 没有变更记录的架构文档，第二轮迭代就会变成黑箱。 ### 2. 系统地图 -Sxx 编号清单（核心系统 2~12 个）+ 支撑层（存档/UI，不拥有核心规则）。 +Sxx 编号清单（核心系统通常 1-5 个，有明确要求可超出 5 个）+ 支撑层（存档/UI，不拥有核心规则）。 P0 段五列表： | 系统 | 目的 | 输入 | 输出 | P0 原因 | → 每行 P0 原因必须答"删了它，__ 塌"；答不出的降级或合并。 @@ -1280,7 +1280,7 @@ P1/P2 可用能力表（能力/说明）控制颗粒度。 --- name: game-gdd-system-doc -description: 写单个系统的设计文档（Sxx）时的总纲——通用纪律、十二节同构骨架、 +description: 写单个系统的设计文档（Sxx）时的总纲——通用纪律、十二类常见内容、 红线与分析文档格式。每类系统的专属写法与模板在 01~12 各文件夹的 SKILL.md 与 模板.md 里，按需取用。 --- @@ -1330,7 +1330,7 @@ description: 写单个系统的设计文档（Sxx）时的总纲——通用纪 咬合：**对上**服从架构三条合同（编号/职责/依赖）；**对内**状态与接口不越 职责边界；**对下**第 7 节交接喂 TDD。 -## 四、十二节通用写法 +## 四、常见内容的参考写法 （各系统类型的特殊写法见对应文件夹 SKILL.md；纯净模板在其 模板.md） 1 系统目的：若删除它，__ 会塌——一句话说不出 = 该系统不该存在。 @@ -1343,7 +1343,7 @@ description: 写单个系统的设计文档（Sxx）时的总纲——通用纪 8 反馈：每种关键结果给独立反馈形态；失败必须说明原因和恢复路径。 9 内部循环：动词链；可拆单次/区域/长期三层。 10 输入输出与依赖：引用具名系统与具名数据，禁泛称"资源"。 -11 边界与非目标：照该类型 skill 的"三不"写全；必含"字段数值归 TDD"一条。 +11 边界与非目标：参考该类型 skill 的“三不”说明边界；建议说明字段与数值的交接边界。 12 开放问题：结构级才留；手感数值类标"待原型验证"。 ## 五、分析文档（全局一份，按层分节） diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/skills/architecture.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/skills/architecture.md index 5f474d9e7..41dc962ec 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/skills/architecture.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/skills/architecture.md @@ -74,7 +74,7 @@ description: 写游戏策划案（GDD）系统架构时使用。在顶层设计 三个接口：**对上**承顶层系统范围表并跑循环覆盖检查；**对内**地图↔职责↔依赖 三方一致、主数据归属唯一；**对下**目录映射 + MVP 闭环喂系统文档站。 -## 四、怎么写（模板即流程，十二节按序） +## 四、怎么写（模板参考结构，建议按此组织） （本节是带写法要领的教学版；实际填写的纯净模板在 templates/architecture.md） ### 1. 架构定位与目标 @@ -85,7 +85,7 @@ description: 写游戏策划案（GDD）系统架构时使用。在顶层设计 → 没有变更记录的架构文档，第二轮迭代就会变成黑箱。 ### 2. 系统地图 -Sxx 编号清单（核心系统 2~12 个）+ 支撑层（存档/UI，不拥有核心规则）。 +Sxx 编号清单（核心系统通常 1-5 个，有明确要求可超出 5 个）+ 支撑层（存档/UI，不拥有核心规则）。 P0 段五列表： | 系统 | 目的 | 输入 | 输出 | P0 原因 | → 每行 P0 原因必须答"删了它，__ 塌"；答不出的降级或合并。 diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/skills/concept.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/skills/concept.md index 05c48b19a..1d8f73496 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/skills/concept.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/skills/concept.md @@ -69,7 +69,7 @@ description: 写游戏策划案（GDD）概念层时使用。把一句话游戏 记住三个接口：**对内**锚点仲裁一切；**对下**张力变取舍表、定稿变硬约束； **对上**边界画线防止越层。九节不是清单，是一台咬合的机器。 -## 四、怎么写（模板即流程，九节按序） +## 四、怎么写（模板参考结构，建议按此组织） （本节是带写法要领的教学版；实际填写的纯净模板在 templates/concept-design.md） ### 1. 一句话概念 diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/skills/systems.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/skills/systems.md index 554ebbf81..50c44335c 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/skills/systems.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/skills/systems.md @@ -2,7 +2,7 @@ --- name: game-gdd-system-doc -description: 写单个系统的设计文档（Sxx）时的总纲——通用纪律、十二节同构骨架、 +description: 写单个系统的设计文档（Sxx）时的总纲——通用纪律、十二类常见内容、 红线与分析文档格式。每类系统的专属写法与模板在 modules/system-types/ 下对应目录的 SKILL.md 与对应模块的模板.md 里，按需取用。 --- @@ -26,9 +26,9 @@ description: 写单个系统的设计文档（Sxx）时的总纲——通用纪 1. 架构已定稿：找到本系统的 Sxx 编号、职责表行、依赖方向——这是合同。 2. 在 01~12 文件夹里选最接近的系统类型（可组合，如"钓鱼"=05 采集+06 战斗 的判定部分），读取对应的 `SKILL.md` 与 `模板.md`。 -3. 该文件夹标注"必读例子"的，先读例子全文做密度锚。 +3. 该文件夹标注"参考例子"的，可先读例子了解写法。 -## 三、十二节总览：写什么、为什么、怎么咬合 +## 三、常见内容总览：写什么、为什么、怎么咬合 系统文档回答四个问题： **这个系统为什么存在（1~2）→ 玩家怎么用它（3~5）→ 它怎么运转（6~8）→ @@ -52,7 +52,7 @@ description: 写单个系统的设计文档（Sxx）时的总纲——通用纪 咬合：**对上**服从架构三条合同（编号/职责/依赖）；**对内**状态与接口不越 职责边界；**对下**第 7 节交接喂 TDD。 -## 四、十二节通用写法 +## 四、常见内容的参考写法 （各系统类型的特殊写法见对应文件夹 SKILL.md；纯净模板在其 模板.md） 1 系统目的：若删除它，__ 会塌——一句话说不出 = 该系统不该存在。 @@ -65,7 +65,7 @@ description: 写单个系统的设计文档（Sxx）时的总纲——通用纪 8 反馈：每种关键结果给独立反馈形态；失败必须说明原因和恢复路径。 9 内部循环：动词链；可拆单次/区域/长期三层。 10 输入输出与依赖：引用具名系统与具名数据，禁泛称"资源"。 -11 边界与非目标：照该类型 skill 的"三不"写全；必含"字段数值归 TDD"一条。 +11 边界与非目标：参考该类型 skill 的“三不”说明边界；建议说明字段与数值的交接边界。 12 开放问题：结构级才留；手感数值类标"待原型验证"。 ## 五、分析文档（全局一份，按层分节） diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/skills/tdd.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/skills/tdd.md index cf7faffe5..b2b6e6c50 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/skills/tdd.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/skills/tdd.md @@ -97,737 +97,18 @@ GDD 喂的（系统文档交接节就是订单）；程序侧的加载与验证 -## A1 概念层分册（game-gdd-concept） +## A1 概念层分册（简介） ---- -name: game-gdd-concept -description: 写游戏策划案（GDD）概念层时使用。把一句话游戏想法写成一份 - "一次写对、之后不动"的立项概念文档——它是后续所有设计争议的仲裁依据。 - 任何游戏类型通用。配套：templates/concept-design.md、templates/analysis.md（全局一份）、 - exemplars/stardew-concept.md、exemplars/stardew-analysis.md（全局一份）。 ---- +本分册说明概念设计的目标、边界、核心张力、分析记录和交接要求。完整内容请阅读 `resources/skills/concept.md`；概念设计模板请阅读 `resources/templates/concept-design.md`。 -# 概念层写法（策划 agent · 概念层分册） +## A2 顶层设计分册（简介） -> 本文件是概念层唯一承载写作流程的教学件。 -> 模板与例子文件保持纯净：不含任何步骤、检验提示与标记。 +本分册说明顶层循环、资源流、节奏、取舍、范围和验证标准。完整内容请阅读 `resources/skills/top_design.md`；顶层设计模板请阅读 `resources/templates/top-design.md`。 -## 一、这一层的判断立场 -你是资深游戏策划，看过上千份概念案，清楚绝大多数死在"什么都说、什么都不尖"。 -在这个层里你相信： -- 概念的成败在取舍，不在丰富：一句话里卖点只许有一个。 -- 你写的是裁判文档：后续每一层的设计争议，都要能回到这里找到仲裁。 -- 具体压倒抽象："压力很大"是废字，"每开一扇门都在烧自己的命"才是概念。 -- 用户没说过的话不当他说过：宁可标"待确认"，不替人拍板。 -- 发现自己在堆形容词 = 概念没想清楚：停笔回去问，别用空话盖过去。 -- 概念层是"一次写对、之后不动"的层（实作中它的返工率远低于架构与 - 系统层），所以判断力要前置堆足，不要指望后面回来改。 +## A3 系统架构分册（简介） -## 二、动笔前 -1. 拿到用户真实回答过的定调信息（参照对象、题材偏好、压力档位）。 - 没有 → 先问一个定调问题，禁止自问自答充当用户。 -2. 读 exemplars/stardew-concept.md 做质量锚（模仿密度，不抄内容）， - 然后往 templates/concept-design.md 里填。 -3. 零参照时在文档头注明"零参照"。 +本分册说明系统职责、依赖、数据归属、MVP 闭环、目录映射和架构校验。完整内容请阅读 `resources/skills/architecture.md`；架构模板请阅读 `resources/templates/architecture.md`。 -## 三、九节总览：写什么、为什么、怎么咬合 +## A4 系统文档分册（简介） -概念文档回答四个问题： -**这是什么（1~5）→ 它不是什么（6）→ 它靠什么让人一直玩（7）→ -它管到哪、交出什么（8~9）。** - -第 1 节是全案的压缩态，第 9 节是全案的判断态重述，首尾呼应； -中间各节从"设计锚点"这个枢纽长出来，争议又都回头接受它的仲裁。 - -| # | 节 | 是什么 | 为什么写 | 和谁咬合 | -|---|---|---|---|---| -| 1 | 一句话概念 | 全案压缩成一句：品类+融合+唯一卖点 | 概念的第一命运是被转述；这句立不住，后面写得再好都救不回来 | 9 是它的重述；2 是它的展开 | -| 2 | 定调与设计锚点 | 定调记录（参照/滑杆/T 原则，调性真源）+ 六个仲裁位：幻想/体验/动机/循环/跑偏/非目标 | 概念层把调定死：后续所有开放问题先回定调记录级联（约八成可就地定），级联不掉的才上决策卡；概念文档的核心职能是当裁判 | **全文档枢纽**：3~6 由它长出；7 由它的循环与动机抽出；定调记录被顶层及以下所有层引用 | -| 3 | 玩家身份与基调 | 玩家在虚构里是谁 + 情绪温度与红线 | 幻想需要一张脸和一种温度，否则是空话；基调边界句防调性漂移 | 身份 = 幻想的具象化；基调 = 目标体验的情绪面 | -| 4 | 风格与世界观 | 支撑玩法的世界规则 + 叙事载体 | 世界观是给玩法供氧的背景板，不是设定集 | 服务 3 的身份与基调；世界规则支撑 2 的核心循环成立 | -| 5 | 目标玩家与情境 | 为谁、什么场景、门槛多高 | 同一设计对不同人是不同游戏；受众映射防止"谁都适合=谁都不适合" | 反面校验 2 的目标体验；情境（一局多久）给 7 的循环定参数 | -| 6 | 不是什么 | 负面定位表：不是 X，因为 Y | 正面定义写多必然发散；负面定位用"误会方向+封死原因"收边界，比光秃的非目标锋利一档 | 2 的非目标与跑偏风险的表化展开；与 5 的防串味声明呼应 | -| 7 | 核心张力 | 玩家持续面对的两难，两端各有代价 | 长期游玩的根本动力；没有张力，再丰富的内容玩几次就腻 | **向下接口**：每条张力必须在顶层变成取舍表里的具体决策 | -| 8 | 边界与约束 | 本层只定什么、什么留给后面 + 规模回流 | 防止概念层越层写数值和系统（越层是下游返工之源）；给写作画线 | 保护 2 的纯度；告诉顶层"你们的地盘从哪开始" | -| 9 | 概念定稿 | "核心不是 __ 而是 __"重述 + 给顶层的硬约束 | 收口重锤：写完九节重述一遍，检验整份文档有没有写散；把承诺变成对下的契约 | 回环呼应 1；把 8 的交接具体化成 2~4 条硬约束 | - -咬合一图： - -``` - 1 一句话概念（压缩态） - ↓ 展开 - 2 设计锚点（枢纽 · 仲裁位）◄── 所有节的争议回来找它 - ├→ 3 身份基调 ──→ 4 风格世界观（给玩法供氧） - ├→ 5 目标玩家（反面校验）──→ 6 不是什么（负面收边） - └→ 7 核心张力（动力结构）──→ 【交给顶层】取舍表 - 8 边界与约束（画线：本层到此为止） - ↓ 回环 - 9 概念定稿（判断态重述 + 交接契约） -``` - -记住三个接口：**对内**锚点仲裁一切；**对下**张力变取舍表、定稿变硬约束； -**对上**边界画线防止越层。九节不是清单，是一台咬合的机器。 - -## 四、怎么写（模板即流程，九节按序） -（本节是带写法要领的教学版；实际填写的纯净模板在 templates/concept-design.md） - -### 1. 一句话概念 -《__》是一款 __（品类与融合）：玩家通过 __，把 __ 逐步 __。 -→ 45~90 字，卖点唯一。检验：删掉那个卖点句子依然成立，说明没写对。 - -### 2. 定调与设计锚点（先定调，再立仲裁位） -**定调记录**（全项目调性真源，此节定死）： -- 参照选择：以 __ 为主、__ 学 __（参照即定调，选完调性随之而来）。 -- 调性滑杆：压力感/战斗比重/管理深度/叙事比重/节奏，各一档。 -- 调性锚 T 原则：3~7 条逐条具名（如"T2 不劝退——凡惩罚类问题默认取最轻档"）。 - 检验：每条 T 都能当一句 IF-THEN 用——"凡__类问题默认__"；写不出口径的 T 是空话。 - → 下游每个开放问题先来这里级联批量起草，级联不了的才升级提问。 -**设计锚点（六项，争议时的仲裁原则，全部具名）** -- 核心幻想：一句描述 + 一句玩家念头（引号写出玩家脑中的自言自语）。 - 检验：念头句写不出来 = 幻想没立住，回去重想，不要用描述糊弄。 -- 目标体验：何时感到什么。 -- 玩家动机：短期 __；长期 __。 -- 核心循环：__ → __ → __ → __ → 回到 __（箭头式）。 -- 跑偏风险：本项目可能的真实偏航，不放万金油。 -- 非目标：一行带过，详表见第 6 节。 - -### 3. 玩家身份与基调 -- 玩家身份：玩家在虚构里是谁 + 本项目的核心节奏，一口气说清。 -- 情绪基调：正面定调 + 边界句——"可以 __，不可以 __"。 - -### 4. 风格与世界观 -世界观为 __（玩法）服务；叙事通过 __（载体）展开。禁编年史、种族志。 - -### 5. 目标玩家与情境（受众映射三件套） -- 与谁的受众重合；吸收了谁的什么需求；**为什么不会变成它**（防串味声明， - 参照越多越必须有这句）。 -- 情境与门槛：单人/多人；一局多久；需要理解 __，不应要求 __。 - -### 6. 不是什么（负面定位表） -| 不是 | 因为 | -→ 每行原因要封死一条具体误会方向（例：不是武器店经营｜武器主要拿去 - 战斗，不是卖给顾客）。从锚点的非目标与跑偏风险长出来，通常 4~6 行。 - -### 7. 核心张力 -- __ 有限，但 __。 -- __ vs __（两端的代价各是什么）。 -→ 每条两端都必须有代价，只有一端的"假张力"删掉。这些是顶层取舍表的 - 种子，后面要逐条对应。 - -### 8. 边界与约束 -- 概念边界放首位：本层只定幻想、用户、基调与排除方向；具体数值、 - 系统清单、MVP 内容留给顶层及以后。 -- 规模与回流：单人可维护；所有系统回流核心循环。 -- 参照声明：学组织方式，不复制角色/文本/美术/数值。 - -### 9. 概念定稿（收口重锤） -这个游戏的核心不是 __，而是： -> （一句话重述核心承诺） -交给下一层的约束：__ 必须 __（2~4 条，顶层必须围绕它们展开）。 - -某节对本项目没意义 → 写一行"略，因为 __"，不硬凑。 - -## 五、分析文档（全局一份，按层分节） - -**全局唯一一份《分析.md》**（项目根），本层不另设分析文件（2026-09-06 收敛： -原每层一份 analysis 合并为全局一份——论证按发生层归节，决定登记表全项目 -只此一张，跨层引用只查这里）。模板与例子：资源 `templates/analysis.md`、 -`exemplars/stardew-analysis.md`。状态池（灵感池/代决/待原型等活队列）在决策台账， -不放分析文档——本文件只放已决论证与登记。 - -- 条目格式：`## 问题：<一句话>` ＋ 状态（agent_proposal / user_confirmed / - superseded，登记 D-__）＋ 广度分析（牵动面＋候选 ≥2）＋ 深度分析 - （逐候选利弊依据，必须引 T 原则/锚点/张力编号，写不出依据的偏好不进分析） - ＋ 综合判断（建议取 __ 因为 __；推翻条件：__）。 -- 分诊三条件全满足才进：① 影响项目方向或边界；② ≥2 合理候选；③ 一时定不了。 - 不满足的：就地小权衡直接进登记表一行，不写条目。 -- 本层标准两问：① 什么是本项目不可替代的核心承诺；② 什么内容扩张会稀释它。 -- 数量纪律：概念期问题通常 ≤3；开始堆第 4 问时先怀疑概念层没想清楚，重读定调记录而不是继续开新争议。 -- user_confirmed 后三件事：结论一句话迁入 design.md 对应节（留修订痕迹）； - 登记表加行（编号全项目连续，跨层引用写 D-__）；本条目改状态记 D 号保留不删。 - 推翻时新增行挂旧行编号，旧行不删。 - - -## 六、写完自查（参考，不是闸门） -- 卖点唯一吗？念头句立得住吗？ -- 随便挑一个后续设计问题，锚点六项之一能当裁判吗？ -- "不是什么"表封死了最可能的误会方向吗？ -- 张力每条都两端有代价吗？ - -## 七、红线（只有三条） -1. 不冒充用户决定：用户没说的方向标"待确认"，正文不写死。 -2. 不越层：出现具体数值、按键、界面即删。 -3. 不凑数：写不满就说明缺什么，禁止万金油句填充。 - - - - -## A2 顶层设计分册（game-gdd-top-design） - ---- -name: game-gdd-top-design -description: 写游戏策划案（GDD）顶层设计时使用。在概念层定稿之后， - 回答"玩家为什么一直玩"——把概念变成可玩的时间结构（循环/资源/取舍/节奏）， - 并向架构层交付系统范围。配套：templates/top-design.md、templates/analysis.md（全局一份）、 - exemplars/stardew-top-design.md、exemplars/stardew-analysis.md（全局一份）。 ---- - -# 顶层设计写法（策划 agent · 顶层设计分册） - -> 本文件是顶层设计唯一承载写作流程的教学件。 -> 模板与例子文件保持纯净：不含任何步骤、检验提示与标记。 - -## 一、这一层的判断立场 -你是资深游戏策划，正在写全 GDD 最重要的一份文档——概念说"凭什么成立"， -顶层说"好玩在哪"。核心循环无趣，后面写再多系统也救不回来。在这个层里你相信： -- 循环优先：先把大循环、小循环、最小体验单位三层跑通，再谈其他一切。 -- 用玩家的手写，不用系统的嘴写：写"玩家在做什么、在想什么"， - 不写"系统提供了什么功能"。 -- 每个时间段的痛苦和甜都要有来处：取舍表接概念层的张力，节奏接情绪摆动。 -- 资源守恒直觉：每种资源必问来源、储存、消耗——无来源是白给， - 无消耗是废物，环环相扣成套利。 -- 你不替概念层翻案（张力与定稿已定），也不替架构层拆系统（只划边界）。 - -## 二、动笔前 -1. 概念层 design.md 已定稿可用——顶层定位与取舍表直接从它长出来。 -2. 读 exemplars/stardew-top-design.md 做质量锚（模仿密度，不抄内容）， - 往 templates/top-design.md 里填。 -3. 把概念层的核心张力清单摊开放在手边——取舍表必须逐条挂上编号。 - -## 三、十六节总览：写什么、为什么、怎么咬合 - -顶层文档回答四个问题： -**玩家在玩什么（1~9）→ 玩家面对什么选择与后果（10~11）→ -交给架构什么（12~14）→ 没想清什么、定了什么（15~16）。** - -第 1 节承概念定稿开篇，第 16 节给架构硬约束收口，首尾呼应； -中段三层循环互检，资源流从底下供血。 - -| # | 节 | 是什么 | 为什么写 | 和谁咬合 | -|---|---|---|---|---| -| 1 | 顶层定位与规模锚点 | 承概念定稿 + "让玩家每天都在想"念头句 + 不是X不是Y + 规模参数表（循环单位/段落/复杂度/长期主轴） | 循环单位定错全盘错；定位句防止顶层漂离概念 | 承概念层"概念定稿"；念头句是概念层玩家念头的时间维度版 | -| 2 | 设计目标 | 几种回报、如何互相供给 | 回报并列=小游戏拼盘；互相供给才是循环 | 供给关系落到 4~5 的循环里 | -| 3 | 核心推动力 | 动机主次 + 即时/日程/季节/长期四层推动 | 玩家"什么时候被什么推着走"的完整图谱 | 时间四层对应 10 节奏结构的四层 | -| 4 | 大循环 | 跨较长时间的循环：文字箭头 + 核心循环图 | 长期留存的结构骨架 | 与 5、7 三层互检：大循环的每环应有小循环供血 | -| 5 | 小循环 | 几十秒到几分钟的具名动词链 ×3+ | 真正被玩到的那层；动词链可直接复制进实现 | 检验：删掉某条，游戏是否少了一块可命名的乐趣 | -| 6 | 资源流与输入输出 | 资源流图（来源→储存→消耗）+ 输入输出清单 + 反馈四层 | 资源是循环的血液；防白给、防废物、防套利 | 供血给 4~5 的每个循环环节 | -| 7 | 最小体验单位 | 多短一段玩法就能体现独有乐趣 + 反馈铁律 | 原型只做这一个单位——定原型规模 | 是 5 的最小切片；14 验证标准的试验对象 | -| 8 | 核心活动流程 | 段落表：阶段/玩家行为/**设计目的** | "玩这个游戏的一天"的可复述剧本 | 设计目的列写不出的段=该删的段 | -| 9 | 取舍表 | 决策/立即收益/延迟收益/主要代价 | 张力的具体化——玩家决策的路口 | **逐条对应概念层核心张力**（对上接口） | -| 10 | 节奏结构 | 日内/周内/季节/长期四层 + 情绪摆动 | 防止"一直紧张"或"一直平"；摆动才有呼吸 | 四层对应 3 的推动力四层 | -| 11 | 失败与回收 | 亏损定性 + 情况/结果表 | 失败的形态决定调性——"少拿"还是"毁掉" | 对齐概念层情绪基调的边界句 | -| 12 | 系统范围 | 系统/顶层目的/**边界** 表 | 架构层接口：系统地图的种子 | **对下接口**：架构照此拆系统 | -| 13 | 范围与非目标 | 最小完整版本清单 + 不做清单 | 立项交付物的边界 | 承概念层"不是什么"；给 14 提供验证范围 | -| 14 | 验证标准 | 验证点/成功标准（行为判据） | "好玩"不可测，"玩家能复述循环"可测 | 判据对象=7 的最小体验单位 | -| 15 | 开放问题 | 留给架构前必须想清的 | 显式债务清单 | 进分析文档或架构层开题 | -| 16 | 顶层定稿 | 收口重锤 + 给架构的硬约束（必须__/不得__） | 检验全文档没写散；架构的紧箍咒 | 回环呼应 1；承概念层定稿的接力棒 | - -咬合一图： - -``` -概念层定稿（硬约束 + 张力） - ↓ 承接 -1 定位与规模锚点 ───张力落位───► 9 取舍表（逐条对应） - ↓ 展开 -2 设计目标 → 3 核心推动力 → 4 大循环 ⇄ 5 小循环 ⇄ 7 最小体验单位 - ↓ 供血 -6 资源流与输入输出（防无来源/无消耗/套利） - ↓ 后果侧 -8 活动流程（段落表）→ 10 节奏结构 → 11 失败与回收 - ↓ 交付 -12 系统范围（→架构系统地图的种子）＋ 13 范围 ＋ 14 验证标准 - ↓ 收口 -15 开放问题 → 16 顶层定稿（给架构的硬约束） -``` - -三个接口：**对上**承概念定稿、张力逐条变取舍表；**对内**三层循环互检 -（大⇄小⇄最小单位）+ 资源三段全；**对下**系统范围表喂架构的系统地图、 -顶层定稿当架构的紧箍咒、验证标准当原型试玩判据。 - -## 四、怎么写（模板即流程，十六节按序） -（本节是带写法要领的教学版；实际填写的纯净模板在 templates/top-design.md） - -### 1. 顶层定位与规模锚点 -顶层不是做 __，也不是做 __，而是让玩家每天都在想： -> "__（玩家每天惦记的那件事）" -规模锚点表：循环单位 / 段落构成 / 操作复杂度 / 经营复杂度 / 长期主轴排序。 -→ 循环单位先行，定错全盘错。复杂度行可内联参照与"不做"。 - -### 2. 设计目标 -玩家在 __ 循环中同时获得 __、__、__——三者不是并列小游戏，而是互相供给：__。 -→ 检验：砍掉任何一种回报，另外两种是否受伤。 - -### 3. 核心推动力 -- 动机主次：__。 -- 即时推动 __；日程推动 __；季节推动 __；长期推动 __。 -→ 四层都要有实指；空着的那层就是将来留存崩塌的地方。 - -### 4. 大循环 -**__ → __ → __ → __ → 回到 __。**（附核心循环图） -→ 检验：断掉任何一环，后面是否塌；每一环应有对应小循环供血。 - -### 5. 小循环（具名动词链 ×3+） -**__循环**：__ → __ → __ → __ → __。 -→ 必须具名（"农务循环"不是"资源循环"）；动词链完整到可以直接照做。 - -### 6. 资源流与输入输出 -（资源流图：每种核心资源 来源 → 储存 → 消耗 三段全） -主要输入 __；主要输出 __；反馈四层：立即 __ / 短期 __ / 中期 __ / 长期 __。 -→ 三问：这资源哪来的？存在哪？花在哪去？答不出=资源设计未完成。 - -### 7. 最小体验单位 -__（多短一段玩法体现独有乐趣——原型只做这一个单位）。 -单个行动必须至少提供一种清晰反馈：资源/进度/能力/关系/信息/视觉状态之一。 - -### 8. 核心活动流程（段落表） -| 阶段 | 玩家行为 | 设计目的 | -→ 设计目的列必填；写不出目的的段落删掉。这份表要能让陌生人复述 -"玩这个游戏的一天"。 - -### 9. 取舍表 -| 决策 | 立即收益 | 延迟收益 | 主要代价 | -→ 每行挂概念层张力编号；避免唯一最优解；不同选择应产生不同但都合理的玩法方式。 - -### 10. 节奏结构 -日内 __ → 周内 __ → 季节/章节 __ → 长期 __。 -整体情绪在"__"与"__"之间摆动（恢复来源 __；变化来源 __）。 - -### 11. 失败与回收 -先定性：失败主要表现为 __（少拿收益 / 延迟成长 / 毁掉积累——三选一档位）， -再列表： -| 情况 | 结果 | -→ 亏损档位必须与概念层情绪基调一致；治愈基调配"少拿"档。 - -### 12. 系统范围（架构层接口） -| 系统 | 顶层目的 | 边界（本层不做什么） | -→ 只写目的与边界，不写系统内部规则；每行将来对应架构层一个 Sxx。 - -### 13. 范围与非目标 -最小完整版本包含：__。不做清单：__。 - -### 14. 验证标准 -| 验证点 | 成功标准 | -→ 成功标准必须是行为判据（"玩家能复述__""玩家出现__行为"）， - "感觉好玩"不算。 - -### 15. 开放问题 -→ 逐条列出；值得跨轮保留的进分析文档，其余留待架构层开题。 - -### 16. 顶层定稿（收口重锤） -顶层当前定稿为：__（循环单位、核心结构、关键档位一句话说全）。 -后续架构必须围绕 __ 拆系统；不得 __。 - -某节对本项目没意义 → 写一行"略，因为 __"，不硬凑。 - -## 五、分析文档（全局一份，按层分节） - -**全局唯一一份《分析.md》**（项目根），本层不另设分析文件（2026-09-06 收敛： -原每层一份 analysis 合并为全局一份——论证按发生层归节，决定登记表全项目 -只此一张，跨层引用只查这里）。模板与例子：资源 `templates/analysis.md`、 -`exemplars/stardew-analysis.md`。状态池（灵感池/代决/待原型等活队列）在决策台账， -不放分析文档——本文件只放已决论证与登记。 - -- 条目格式：`## 问题：<一句话>` ＋ 状态（agent_proposal / user_confirmed / - superseded，登记 D-__）＋ 广度分析（牵动面＋候选 ≥2）＋ 深度分析 - （逐候选利弊依据，必须引 T 原则/锚点/张力编号，写不出依据的偏好不进分析） - ＋ 综合判断（建议取 __ 因为 __；推翻条件：__）。 -- 分诊三条件全满足才进：① 影响项目方向或边界；② ≥2 合理候选；③ 一时定不了。 - 不满足的：就地小权衡直接进登记表一行，不写条目。 -- 本层标准两问：① 一天/一局怎样形成清楚但不拖沓的循环；② 风险、收益与长期成长怎样互相支撑。 -- 数量纪律：顶层期问题通常 ≤5（结构性争议天然更多）；堆问题时先回读第 1 节定位句。 -- user_confirmed 后三件事：结论一句话迁入 design.md 对应节（留修订痕迹）； - 登记表加行（编号全项目连续，跨层引用写 D-__）；本条目改状态记 D 号保留不删。 - 推翻时新增行挂旧行编号，旧行不删。 - - -## 六、写完自查（参考，不是闸门） -- 三层循环互检了吗：大循环每环有小循环供血？最小单位切得出来？ -- 概念层张力每条都在取舍表有对应行吗？ -- 每种资源三段全吗（来源/储存/消耗）？ -- 验证标准是行为判据吗，还是写了"好玩"？ -- 架构层拿到系统范围表能直接开工吗——有没有该划没划的系统？ -- 失败档位和概念层基调一致吗？ - -## 七、红线（只有三条） -1. 不冒充用户决定：用户没说的方向标"待确认"，正文不写死。 -2. 不越层：向上不翻概念层的案，向下不写系统内部规则与具体数值。 -3. 不凑数：写不满就说明缺什么，禁止万金油句填充。 - - - - -## A3 系统架构分册（game-gdd-architecture） - ---- -name: game-gdd-architecture -description: 写游戏策划案（GDD）系统架构时使用。在顶层设计定稿之后， - 把顶层的系统范围表正式切成 Sxx 系统：编号、职责、依赖、数据流、优先级， - 并向系统文档站交付目录映射与 MVP 闭环。配套：templates/architecture.md、 - templates/analysis.md（全局一份）、exemplars/stardew-architecture.md、exemplars/stardew-analysis.md（全局一份）。 ---- - -# 系统架构写法（策划 agent · 系统架构分册） - -> 本文件是系统架构层唯一承载写作流程的教学件。 -> 模板与例子文件保持纯净：不含任何步骤、检验提示与标记。 - -## 一、这一层的判断立场 -你是架构师，切系统的刀在你手里。在这个层里你相信： -- 切分是为了**职责清晰、可独立讨论**，不是为了凑数量——每个系统必须能 - 一句话答出"删了它，什么塌"（P0 原因）。 -- **数据所有权唯一**：同一事实只由一个系统维护，其他系统只引用稳定 ID， - 不复制主数据。两个系统管同一件事 = 架构事故。 -- **依赖无环**是硬要求；信息呈现层只读状态、只经行动入口写入。 -- 架构是全项目返工最多的一份（实测 11 版 vs 概念层 2 版）——所以每次改刀 - 都要写变更记录，让"为什么这么切"可追溯。 -- 你不越层：上不重定义玩法循环（那是顶层的），下不写单系统内部规则 - （那是系统文档的），字段定义与数值配置归技术文档层（数值策划）。 - -## 二、动笔前 -1. 顶层设计已定稿可用——把它的**系统范围表**（粗清单）和**顶层定稿约束** - 摊开当输入；切分是对粗清单的正式化（拆、并、裁都在这层做）。 -2. 读 exemplars/stardew-architecture.md 做质量锚（模仿密度，不抄内容）， - 往 templates/architecture.md 里填。 -3. 记住顶层的核心循环图——切完必须跑覆盖检查。 - -## 三、十二节总览：写什么、为什么、怎么咬合 - -架构文档回答四个问题： -**这个架构为什么这样切（1~3）→ 系统是什么、怎么连接（4~6）→ -怎么落地、怎么验证（7~11）→ 还有什么没想清（12）。** - -第 1 节承顶层的定稿约束开篇，MVP 闭环在中间当守门员，开放问题收尾。 - -| # | 节 | 是什么 | 为什么写 | 和谁咬合 | -|---|---|---|---|---| -| 1 | 架构定位与目标 | 阶段边界（定哪些系统、不展开内部）+ 划分原则 + 一句话架构 + **变更记录** | 防止架构漂离顶层；改刀可追溯 | 承顶层定稿；变更记录引登记编号 | -| 2 | 系统地图 | Sxx 编号清单（=系统文档目录真源）+ 支撑层 + P0 段五列表（目的/输入/输出/P0原因） | 编号让系统可引用；P0 原因逼答"删了塌什么" | **对下真源**：Sxx ↔ 04 系统文档一一对应 | -| 3 | 系统职责 | 职责表（负责/不负责→移交谁）+ 逐系统说明段 | 边界写死，防两个系统管同一件事 | 系统文档的"边界与非目标"必须与此对齐 | -| 4 | 依赖与数据流 | 依赖图（无环）+ 数据流图 + 主要状态 + 主数据归属规则 | 谁读谁、数据从哪到哪——接口的真源 | 顶层的资源流图在此展开成系统级 | -| 5 | 核心循环覆盖检查 | 顶层每个循环环节 → 认领系统 | 顶层→架构的验收线，防切系统切碎循环 | 对上接口：逐环节对照顶层循环图 | -| 6 | 目录映射 | 职责 → 物理文档目录的归并表 | 职责数≠文档数；归并规则显式化 | **对下接口**：系统文档站照此开工 | -| 7 | MVP 最小闭环 | 编号验证链 + 守门句（"闭环不成立不许加东西"） | 立项后第一条要跑通的链 | 对应顶层验证标准；失败回顶层而非加系统 | -| 8 | 统一数值基准 | 单位清单 + 四类定性基准（时间/货币/成长/体力风险的风格约束） | 各系统单独配数值会互相失衡；先定全局尺度 | **数值换算与验算归技术文档层**，此处只到定性 | -| 9 | 系统边界 | 哪些功能明确不属于任何系统/归引擎层/归呈现层 | 显式排除，防范围蔓延 | 承概念层"不是什么" | -| 10 | 优先级与范围 | P0/P1/P2 三档（P1/P2 可用能力表） | 拆分≠全做；裁剪顺序显式化 | P0 = MVP 闭环的系统集 | -| 11 | 风险与校验 | 风险/校验方式表 | 架构级风险提前挂出，每条带检验法 | 对应顶层验证标准与概念层跑偏风险 | -| 12 | 开放的结构问题 | 结构级未定案 | 显式债务 | 进分析文档或系统文档开题 | - -咬合一图： - -``` -顶层定稿 + 系统范围表（粗清单） - ↓ 正式切分（拆/并/裁） -1 定位与目标 ──► 2 系统地图（Sxx 真源）──► 3 职责表 - ↓ ↓ ↓ -5 循环覆盖检查 ◄── 4 依赖与数据流（接口真源） - ↓ -6 目录映射 ──► 7 MVP 最小闭环（守门员） - ↓ -8 数值基准（定性）· 9 边界 · 10 优先级 · 11 风险校验 - ↓ -12 开放问题 →（进分析文档 / 系统文档站开题） -``` - -三个接口：**对上**承顶层系统范围表并跑循环覆盖检查；**对内**地图↔职责↔依赖 -三方一致、主数据归属唯一；**对下**目录映射 + MVP 闭环喂系统文档站。 - -## 四、怎么写（模板即流程，十二节按序） -（本节是带写法要领的教学版；实际填写的纯净模板在 templates/architecture.md） - -### 1. 架构定位与目标 -本阶段确定"哪些系统支撑一轮玩法"，不展开单系统内部规则。 -划分原则：__。一句话架构： -> （玩家通过哪些系统、以什么因果，把一轮玩法的输入变成下一轮的选择） -变更记录：日期 + 改了什么 + 为什么（引登记编号）。 -→ 没有变更记录的架构文档，第二轮迭代就会变成黑箱。 - -### 2. 系统地图 -Sxx 编号清单（核心系统 2~12 个）+ 支撑层（存档/UI，不拥有核心规则）。 -P0 段五列表： -| 系统 | 目的 | 输入 | 输出 | P0 原因 | -→ 每行 P0 原因必须答"删了它，__ 塌"；答不出的降级或合并。 - -### 3. 系统职责 -| 系统 | 主要职责 | 不负责 → 移交谁 | -→ "不负责"列必填且指向具名系统；再为争议最大的 2~3 个系统各写一段 -说明（负责什么 / 不负责什么 / 只负责什么）。 - -### 4. 依赖与数据流 -依赖图（mermaid，呈现层用虚线"读取状态"）+ 数据流图（资源从产到耗）。 -主要状态：全局/玩家/场景/社会 四类。 -主数据归属规则：规则与数据表分工 / 稳定 ID 关联 / 任何系统不复制他系统主数据。 -→ 依赖图出现环 = 回去重切。 - -### 5. 核心循环覆盖检查 -| 顶层循环环节 | 认领系统 | -→ 逐环节对照顶层循环图；有环节无人认领或多人认领都是切分错误。 - -### 6. 目录映射 -| 目录 | 本阶段定位 | -→ 职责可以归并进同一文档目录（官方版 8 职责→3 文档）；归并规则写明。 -系统文档站以此开工：地图上没有的系统不许有文档。 - -### 7. MVP 最小闭环 -1. __ 2. __ …（编号验证链，一条玩家可走的完整因果） -守门句：如果这条闭环不成立，不应继续增加 __。 -→ 闭环失败回顶层改设计，不是加系统打补丁。 - -### 8. 统一数值基准（定性） -全局单位清单（如时间片/游戏日/货币/体力/经验）+ 四类风格约束 -（时间节奏/货币量级感/成长回报取向/体力风险档位）。 -→ 只写到定性；具体换算、验算数值由技术文档层（数值策划）承接。 - -### 9. 系统边界 -明确排除项（不拆出独立 __ 系统 / __ 归引擎层 / __ 归呈现层）。 - -### 10. 优先级与范围 -P0（最小闭环必需）：__；P1（完整体验）：__；P2（扩展内容）：__。 -P1/P2 可用能力表（能力/说明）控制颗粒度。 - -### 11. 风险与校验 -| 风险 | 校验方式 | -→ 从概念层跑偏风险和顶层失败档位反推；校验方式要可观察。 - -### 12. 开放的结构问题 -→ 结构级（接口归属/统一格式/合并拆分）才留这里；数值细节不留。 - -## 五、分析文档（全局一份，按层分节） - -**全局唯一一份《分析.md》**（项目根），本层不另设分析文件（2026-09-06 收敛： -原每层一份 analysis 合并为全局一份——论证按发生层归节，决定登记表全项目 -只此一张，跨层引用只查这里）。模板与例子：资源 `templates/analysis.md`、 -`exemplars/stardew-analysis.md`。状态池（灵感池/代决/待原型等活队列）在决策台账， -不放分析文档——本文件只放已决论证与登记。 - -- 条目格式：`## 问题：<一句话>` ＋ 状态（agent_proposal / user_confirmed / - superseded，登记 D-__）＋ 广度分析（牵动面＋候选 ≥2）＋ 深度分析 - （逐候选利弊依据，必须引 T 原则/锚点/张力编号，写不出依据的偏好不进分析） - ＋ 综合判断（建议取 __ 因为 __；推翻条件：__）。 -- 分诊三条件全满足才进：① 影响项目方向或边界；② ≥2 合理候选；③ 一时定不了。 - 不满足的：就地小权衡直接进登记表一行，不写条目。 -- 本层标准问题：结构级争议——接口统一、系统归并、主数据归属划分。（本层原本不配独立分析文件，结构争议全归全局文件本节。） -- 数量纪律：按需；架构期问题多为接口与归属二义。 -- user_confirmed 后三件事：结论一句话迁入 design.md 对应节（留修订痕迹）； - 登记表加行（编号全项目连续，跨层引用写 D-__）；本条目改状态记 D 号保留不删。 - 推翻时新增行挂旧行编号，旧行不删。 - - -## 六、写完自查（参考，不是闸门） -- 每个 Sxx 都能一句话答"删了它什么塌"吗？ -- 顶层的循环环节全覆盖、无重复认领吗？ -- 依赖图无环？主数据无一物两管？ -- 系统文档站拿到目录映射能直接开工吗？ -- 有没有字段定义或数值配置偷偷写进来？（该在技术文档层） -- 变更记录补了吗——这次切分和上次的差异说得清吗？ - -## 七、红线（只有三条） -1. 不冒充用户决定：用户没说的方向标"待确认"，正文不写死。 -2. 不越层：向上不翻顶层的案，向下不写系统内部规则，数值字段归技术文档层。 -3. 不凑数：系统数量不是成绩，写不出 P0 原因的系统就是该删的系统。 - - - - -## A4 系统文档分册（game-gdd-system-doc） - ---- -name: game-gdd-system-doc -description: 写单个系统的设计文档（Sxx）时的总纲——通用纪律、十二节同构骨架、 - 红线与分析文档格式。每类系统的专属写法与模板在 modules/system-types/ 下对应目录的 SKILL.md - 与对应模块的模板.md 里，按需取用。 ---- - -# 系统文档写法（策划 agent · 系统文档分册 · 总纲） - -> 本文件是系统文档层的总纲；各系统的专属写法在 `modules/system-types/` 下对应目录的 `SKILL.md`， - 专属模板在 `modules/system-types/` 对应目录的 `模板.md`。通用纪律不在各系统 skill 里重复。 - -## 一、这一层的判断立场 -你是写单个系统的策划。在这个层里你相信： -- 系统文档是**执行层**：刀已经在架构层切好——服从系统地图编号、职责表 - 边界、依赖图方向，无权改刀；发现切错了，提分析、记登记，不私自扩边界。 -- 一个系统文档的成败在**边界节**："不负责什么、移交给谁"那几行是 - 防返工价值最高的几行。 -- 接口纪律：引用具名系统与具名数据，禁泛称；别家主数据只引 ID 不复制。 -- 字段定义、数值配置、表结构不归你——写交接声明，交技术文档层（数值策划）。 -- 所有系统同构：读者读熟一份就能读所有份。 - -## 二、动笔前 -1. 架构已定稿：找到本系统的 Sxx 编号、职责表行、依赖方向——这是合同。 -2. 在 01~12 文件夹里选最接近的系统类型（可组合，如"钓鱼"=05 采集+06 战斗 - 的判定部分），读取对应的 `SKILL.md` 与 `模板.md`。 -3. 该文件夹标注"必读例子"的，先读例子全文做密度锚。 - -## 三、十二节总览：写什么、为什么、怎么咬合 - -系统文档回答四个问题： -**这个系统为什么存在（1~2）→ 玩家怎么用它（3~5）→ 它怎么运转（6~8）→ -它怎么和别人连接、不碰什么（9~12）。** - -| # | 节 | 是什么 | 为什么写 | 和谁咬合 | -|---|---|---|---|---| -| 1 | 系统目的 | 一句话：删了它什么塌 | 存在性检验 | 架构 P0 原因的展开 | -| 2 | 支撑的玩家体验 | 对应顶层目标第几条 | 防系统自嗨 | 顶层设计目标 ↔ 本系统 | -| 3 | 进入与退出 | 何时进入、何时/如何退出 | 循环的接口时刻 | 顶层的循环环节 | -| 4 | 玩家行动 | 具名动词组 | 玩家用手玩 | 系统类型卡给动词组 | -| 5 | 取舍表 | 玩家在本系统内的决策 | 张力在系统内的落地 | 概念张力→顶层取舍表→本表 | -| 6 | 状态与规则 | 对象/状态/转换/异常，枚举表达 | 定性规则真源 | 架构职责表对齐 | -| 7 | 数值与数据交接 | 本系统交 TDD 的数据类别+定性约束 | 分层边界 | 技术文档层承接 | -| 8 | 反馈 | 何时/何强度/何通道 | 无反馈=没发生 | 顶层反馈四层 | -| 9 | 内部循环 | 本系统内的小循环 | 系统自己的心跳 | 顶层小循环的组成 | -| 10 | 输入、输出与依赖 | 消费/交付/依赖谁 | 接口真源 | 架构依赖图逐边对齐 | -| 11 | 边界与非目标 | 不负责什么→移交谁 | **防返工价值最高** | 架构职责表"不负责"列 | -| 12 | 开放问题 | 本系统未定案 | 显式债务 | 进分析文档 | - -咬合：**对上**服从架构三条合同（编号/职责/依赖）；**对内**状态与接口不越 -职责边界；**对下**第 7 节交接喂 TDD。 - -## 四、十二节通用写法 -（各系统类型的特殊写法见对应文件夹 SKILL.md；纯净模板在其 模板.md） - -1 系统目的：若删除它，__ 会塌——一句话说不出 = 该系统不该存在。 -2 支撑体验：对应顶层目标第__条、调性原则第__条。 -3 进入与退出：常规进入/读档恢复/特殊事件后返回，三入口必写。 -4 玩家行动：≥4 个具名动词组；编排类写"安排"动词，活动类写"操作"动词。 -5 取舍表：决策/立即收益/延迟收益/主要代价；挂顶层张力编号。 -6 状态与规则：对象-状态-转换-异常，全部枚举表达，不许整段散文。 -7 数值与数据交接：列数据类别名 + 设计侧定性约束；字段定义归 TDD。 -8 反馈：每种关键结果给独立反馈形态；失败必须说明原因和恢复路径。 -9 内部循环：动词链；可拆单次/区域/长期三层。 -10 输入输出与依赖：引用具名系统与具名数据，禁泛称"资源"。 -11 边界与非目标：照该类型 skill 的"三不"写全；必含"字段数值归 TDD"一条。 -12 开放问题：结构级才留；手感数值类标"待原型验证"。 - -## 五、分析文档（全局一份，按层分节） - -**全局唯一一份《分析.md》**（项目根），本层不另设分析文件（2026-09-06 收敛： -原每层一份 analysis 合并为全局一份——论证按发生层归节，决定登记表全项目 -只此一张，跨层引用只查这里）。模板与例子：资源 `templates/analysis.md`、 -`exemplars/stardew-analysis.md`。状态池（灵感池/代决/待原型等活队列）在决策台账， -不放分析文档——本文件只放已决论证与登记。 - -- 条目格式：`## 问题：<一句话>` ＋ 状态（agent_proposal / user_confirmed / - superseded，登记 D-__）＋ 广度分析（牵动面＋候选 ≥2）＋ 深度分析 - （逐候选利弊依据，必须引 T 原则/锚点/张力编号，写不出依据的偏好不进分析） - ＋ 综合判断（建议取 __ 因为 __；推翻条件：__）。 -- 分诊三条件全满足才进：① 影响项目方向或边界；② ≥2 合理候选；③ 一时定不了。 - 不满足的：就地小权衡直接进登记表一行，不写条目。 -- 本层标准问题：① 本系统与相邻系统的边界在哪；② 本系统内部哪个规则影响顶层取舍。条目标系统号（如 S06）。 -- 数量纪律：按需；每系统通常 0~1 条，超了先回读架构职责表。 -- user_confirmed 后三件事：结论一句话迁入 design.md 对应节（留修订痕迹）； - 登记表加行（编号全项目连续，跨层引用写 D-__）；本条目改状态记 D 号保留不删。 - 推翻时新增行挂旧行编号，旧行不删。 - - -## 六、写完自查（参考，不是闸门） -- 目的一句话成立吗？边界节和架构职责表逐行对齐吗？ -- 输入输出和依赖图逐边对上吗？有没有泛称漏网？ -- 状态是枚举还是散文？失败路径给了原因和恢复吗？ -- 有没有字段或数值偷偷写进来？（该在 TDD） -- 同构检查：另一份系统文档的读者能按同样方式读这份吗？ - -## 七、红线（只有三条） -1. 不冒充用户决定：用户没说的方向标"待确认"，正文不写死。 -2. 不越层：不翻架构的案（要改走分析文档+登记表），不写字段数值（归 TDD）， - 不替别的系统定规则。 -3. 不凑数：写不出"删了塌什么"、填不满的节，说明缺料——停笔说明，不硬凑。 - - - - -## A5 技术文档分册（game-tdd） - ---- -name: game-tdd -description: 写游戏技术文档（TDD）时使用的总纲。GDD 四层定稿后的第五步：把 - "怎么做"写实——程序怎么写、美术怎么做、字段怎么定义、怎么配表。 - 三大件各有专属分册：技术实现（程序侧）/ 美术圣经（美术侧）/ 数据与配表（数据侧）。 ---- - -# 技术文档写法（策划 agent · TDD 分册 · 总纲） - -> 本文件是 TDD 层唯一承载写作流程的教学件；各分册 SKILL 与模板配套使用。 -> 模板与例子文件保持纯净：不含任何步骤、检验提示与标记。 - -## 〇、TDD 的完成判据（总纲） - -**TDD 是自足构建包：一个施工 agent 只看 TDD，就能做完完整游戏。** -GDD 是设计真源（给人看、给迭代看）；TDD 是构建真源（给施工看）。 -检验方式＝自足性检查（见总册）：不看 GDD 能否回答——每个系统怎么行为、 -每张表多少行内容、每个界面怎么走、每份素材什么规格。答不出的项就是缺口， -缺口回 GDD 同步后**收编**进 TDD（带版本锁）。收编是构建期快照：GDD 定稿 -变更 → 触发对应收编节重同步（与 fast_gdd 投影同一机制，方向相反）。 - -## 一、这一层的判断立场 - -你是工程师思维的策划。GDD 是"用户视角的功能描述"，TDD 是"实现者视角的 -架构性描述"——你不重复设计的论证（为什么这样设计，去 GDD 和 analysis 查）， -只写怎么落地。你相信： - -- **交接契约是 TDD 最大的价值**：美术交给程序的素材、程序读的表、加载的 - 顺序——每一条缝都写死。缝上不写死，返工就在缝里发生。 -- **平台事实优先**：目标运行时由 GDD 平台事实锁定——**HTML / Unity / Godot / - Cocos 四选一**。HTML 项纯 HTML/CSS/JS 交付；引擎项支持打开引擎工程、自然 - 语言协作改素材与代码，由陶泥儿驱动引擎**弹窗预览**、驱动引擎 **CLI 导出**。 - 一切技术选择先过所选运行时这道闸，不推荐该运行时做不出来的东西； - TDD 不擅自换运行时。 -- **一个事实只有一个写权**：每张表、每条主数据都有唯一拥有者系统， - 其他系统只引用不复制（GDD 架构层主数据归属规则在 TDD 落成表结构）。 -- **验收是硬闸不是仪式**：有 blocker 禁止扩充内容——这条竞品四十轮实测 - 验证过，照抄。 -- **先少量验证再量产**（美术）/ **先建索引再转表**（数据）——任何方向都 - 不做"做完一大批才发现不对"的事。 - -## 二、TDD 与 GDD 的接口（输入从哪来） - -| 输入 | 来自 | 喂给哪件 | -|---|---|---| -| 系统范围表 + P0 清单 + 主数据归属规则 | 架构层 | 三件共用（拆表与拆模块依据） | -| 各系统「数值与数据交接」节 + 定性约束 | 系统文档 | 数据侧（直接订单） | -| 定调记录（参照/滑杆/T 原则）+ 身份基调 | 概念层 | 美术圣经（视觉翻译源头） | -| 技能选型卡 | skill 库 | 程序侧+美术圣经（@版本+参数实例化） | - -TDD 不回头改 GDD：发现 GDD 没写清楚的点，走「开放问题回执」——该问用户 -的升级决策卡，该代决的记台账（带理由和推翻条件），结论回写对应层，TDD 只 -登记去向。顾问期（开发阶段）同一出口：程序美术卡点、成品与文档偏差，都从 -回执进、修订出（v{N+1}）。 - -## 三、三大件与开工顺序 - -| 件 | 管什么 | 读者 | 分册 | -|---|---|---|---| -| 数据与配表 | 字段定义、表结构、数值、验收 | 数值策划 + 程序 | 03 | -| 技术实现 | 代码组织、场景镜头、输入、音频、性能预算、验证 | 程序 | 01 | -| 美术圣经 | 视觉锚、素材规格契约、量产流程 | 美术 | 02 | - -**顺序：数据侧 → 程序侧 → 美术圣经**。数据侧先开的理由：它是唯一直接被 -GDD 喂的（系统文档交接节就是订单）；程序侧的加载与验证要引用表结构；美术 -圣经的素材总清单要引用物品表（每个可见对象绑定 item_id 或显式豁免）。小型 -项目三件可交叉，但**表结构永远先于数值填充**。 - -## 四、怎么写（总纲级；细节在各分册） - -1. 数据侧：总清单拆表 → ID 与字段字典 → 公共条件表 → 建表顺序（物品表 - 起步）→ 表结构契约（程序签名）→ 数值填充（代决+台账）→ 验收七查。 -2. 程序侧：系统实现总览（每系统一段话写死怎么做）→ 技术选型与 skill 引用 - → 场景与镜头 → 输入与操作 → 音频 → 验证方式与性能预算。 -3. 美术圣经：视觉锚（从概念层定调翻译）→ 素材规格契约逐素材一行 → - 量产流程（概念候选→锚点确认→小批→验收→扩产）→ 资产总清单。 - -## 五、写完自查（参考，不是闸门） - -- 任意一条缝（美术→程序、表→代码、表→表引用）是否都写死了规格？ -- 每张表是否答得出"谁是拥有者系统"？每个 ID 是否全局唯一？ -- 程序侧验证方式是否可执行（跑什么命令、看什么输出）？ -- 素材契约是否覆盖了 GDD 里全部可见对象（或显式豁免）？ -- 验收是否跑过且无 blocker？ - -## 六、红线（只有四条） - -1. **收编必带版本锁**：从 GDD 收编的任何内容标注"基于系统文档@v{N}"； - 无锁收编=违规（双源漂移之源）。TDD 不产生设计观点，只汇集与落实施工。 -2. 引用必带版本：skill 引用必须 `名字@版本 + 实例化参数`，选型时与执行时 - 用的一致性靠此保证。 -3. 不越权拍板：产品级取舍回 GDD 层走决策流程；TDD 只做技术代决且记台账。 -4. 表里不写散文：单元格只有数据和枚举；规则写在契约文档，不写在表里。 +本分册说明单个系统的职责、规则、输入输出、反馈、边界、验证和分析记录。完整内容请阅读 `resources/skills/systems.md`；系统类型的专属写法和模板请按需阅读 `modules/system-types/` 下对应分册。 diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/skills/top_design.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/skills/top_design.md index 0f720e181..0eeba8577 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/skills/top_design.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/skills/top_design.md @@ -80,7 +80,7 @@ description: 写游戏策划案（GDD）顶层设计时使用。在概念层定 （大⇄小⇄最小单位）+ 资源三段全；**对下**系统范围表喂架构的系统地图、 顶层定稿当架构的紧箍咒、验证标准当原型试玩判据。 -## 四、怎么写（模板即流程，十六节按序） +## 四、怎么写（模板参考结构，建议按此组织） （本节是带写法要领的教学版；实际填写的纯净模板在 templates/top-design.md） ### 1. 顶层定位与规模锚点 diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/system-prompt.md b/apps/ai-game-creator-shell/src-tauri/design-agent/system-prompt.md index 0850865e8..3807f565e 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/system-prompt.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/system-prompt.md @@ -1,12 +1,16 @@ 你是游戏策划协作 Agent，与用户持续协作完成游戏设计。像普通策划同事一样交流，使用工作区文件工具读写资料；所有文件路径使用相对路径。根据当前对话、阶段上下文和已有文档决定下一步行动。修改文件后，简要说明修改内容和相对路径。对不确定内容区分用户确认、Agent 建议和待原型验证事项；不要把建议写成用户已确认的决定。 -优先完成能够依据已有信息推进的工作，不要为每个设计空白都询问用户。局部、可逆的问题可以先提出合理方案并标为暂定。会影响当前阶段范围、关键规则、下游实现或其他重要方向，且必须由用户决定的问题，应先通过纯文本或问询工具询问，等待用户回答，并据此更新相关产物；不要带着这类未决问题提交阶段审批。 +优先完成能够依据已有信息推进的工作，不要为每个设计空白都询问用户。局部、可逆的问题可以先提出合理方案并标为暂定。会影响当前阶段范围、关键规则、下游实现或其他重要方向，且必须由用户决定的问题，应先通过纯文本或问询工具询问，等待用户回答。决定稳定后，再更新受影响的正式产物和必要的过程记录；不要带着这类未决问题提交阶段审批。 + +分析阶段优先记录当前目标、上层约束、候选方案、取舍、用户已确认或 Agent 暂定的边界，以及必须检查的验收项。除非用户明确要求展开讨论，不要先在回复中逐节起草与正式文档重复的长篇正文；形成结论后直接写入正式产物，再进行一次必要的一致性检查。文件操作前只需说明简短计划、目标文件和主要变化。 正式策划文档在文档头部写明版本标记，例如“版本：v1”。由你自行维护版本号：只有整体修订、阶段性定稿或用户意见造成实质内容变化时才递增；错别字、措辞润色、单个局部修改和小范围补充不单独递增。 阶段审批是每个阶段的最终检查，表示本阶段产物已经完成，无未决内容，交给用户做最终检阅，不承担问询功能。提交前，解决所有影响本阶段完成的关键问题，或明确说明它们不阻塞本阶段交付，并更新相关产物。可以保留不阻塞当前阶段的后续事项和待原型验证项。 +过程文档用于记录关键依据、决定和待办，不要求实时完整，也不应重复正式设计文档。阶段内优先完成主要设计内容；只有稳定且影响后续工作的决定才需要同步到多个过程文档。阶段提交前，补齐影响验收的关键记录。 + 阶段获批后，产物中已经采用的方案作为后续工作的依据，并保留原有决策来源。除非用户主动质疑或出现新的约束冲突，不要反复要求确认历史暂定决定。 用户说“继续”时，继续推进当前阶段最有价值的工作。判断本阶段已完成并准备交用户检阅时，应调用 `submit_phase_for_approval`；只有该工具调用成功，才算正式提交审批。 diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/tools.json b/apps/ai-game-creator-shell/src-tauri/design-agent/tools.json index 06c643c6b..c9c1bd6cf 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/tools.json +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/tools.json @@ -2,7 +2,7 @@ {"type":"function","function":{"name":"get_workflow_status","description":"读取当前策划工作流状态，只返回阶段列表、当前阶段、已批准阶段和待审批阶段；不推进阶段、不提交审批、不修改文件。","parameters":{"type":"object","properties":{},"additionalProperties":false}}}, {"type":"function","function":{"name":"list_resources","description":"列出固定资源的逻辑目录、资源 ID、标题和简介。资源是只读的随包文档；不要猜测物理路径。","parameters":{"type":"object","properties":{},"additionalProperties":false}}}, {"type":"function","function":{"name":"read_resource","description":"读取一份固定资源文档全文。每次读取一个 resource_id；资源只读。读到未实现占位文档时由你自行判断和处理。","parameters":{"type":"object","properties":{"resource_id":{"type":"string"}},"required":["resource_id"],"additionalProperties":false}}}, - {"type":"function","function":{"name":"patch_file","description":"局部修改 UTF-8 文件，优先用于已有文件的小范围修订。先读文件，以唯一且非空的 old_text 精确匹配并替换为 new_text；new_text 为空可删除片段，保留原文并追加可插入。匹配失败不修改文件。path 使用相对路径。","parameters":{"type":"object","properties":{"path":{"type":"string"},"old_text":{"type":"string"},"new_text":{"type":"string"}},"required":["path","old_text","new_text"],"additionalProperties":false}}}, + {"type":"function","function":{"name":"patch_file","description":"局部修改 UTF-8 文件。使用 old_text/new_text，或使用 edits 一次进行多个独立替换；每个 old_text 必须非空且在原文件中唯一，匹配失败、重复或范围重叠时不修改文件。path 使用相对路径。","parameters":{"type":"object","properties":{"path":{"type":"string"},"old_text":{"type":"string"},"new_text":{"type":"string"},"edits":{"type":"array","items":{"type":"object","properties":{"old_text":{"type":"string"},"new_text":{"type":"string"}},"required":["old_text","new_text"],"additionalProperties":false}}},"required":["path"],"additionalProperties":false}}}, {"type":"function","function":{"name":"delete_path","description":"谨慎使用；永久删除工作区内的文件或目录；目录会连同全部内容递归删除，不备份。先确认目标及删除范围。path 使用相对路径，不能删除工作区根目录，也不能经过链接。","parameters":{"type":"object","properties":{"path":{"type":"string"}},"required":["path"],"additionalProperties":false}}}, {"type":"function","function":{"name":"list_dir","description":"列出工作目录内的文件和目录。path 使用相对路径。","parameters":{"type":"object","properties":{"path":{"type":"string"}},"required":["path"],"additionalProperties":false}}}, {"type":"function","function":{"name":"read_file","description":"读取工作目录内的 UTF-8 文本文件。path 使用相对路径。","parameters":{"type":"object","properties":{"path":{"type":"string"}},"required":["path"],"additionalProperties":false}}}, diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/design_tools.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/design_tools.rs index 6d65f9dd3..5221030b1 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/agent/design_tools.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/agent/design_tools.rs @@ -264,22 +264,45 @@ pub(crate) fn execute_design_file_tool( } "patch_file" => { let relative = required_tool_path(args)?; - let old = args - .get("old_text") - .and_then(Value::as_str) - .ok_or("缺少 old_text")?; - let new = args - .get("new_text") - .and_then(Value::as_str) - .ok_or("缺少 new_text")?; - if old.is_empty() { - return Err("old_text 不能为空".to_string()); - } + let edits = if let Some(items) = args.get("edits").and_then(Value::as_array) { + if items.is_empty() { + return Err("edits 不能为空".to_string()); + } + items + .iter() + .enumerate() + .map(|(index, item)| { + let old = item + .get("old_text") + .and_then(Value::as_str) + .ok_or_else(|| format!("edits[{index}].old_text 必须是字符串"))?; + let new = item + .get("new_text") + .and_then(Value::as_str) + .ok_or_else(|| format!("edits[{index}].new_text 必须是字符串"))?; + if old.is_empty() { + return Err(format!("edits[{index}].old_text 不能为空")); + } + Ok((old.to_string(), new.to_string())) + }) + .collect::, String>>()? + } else { + let old = args + .get("old_text") + .and_then(Value::as_str) + .ok_or("缺少 old_text")?; + let new = args + .get("new_text") + .and_then(Value::as_str) + .ok_or("缺少 new_text")?; + if old.is_empty() { + return Err("old_text 不能为空".to_string()); + } + vec![(old.to_string(), new.to_string())] + }; let (display, path) = resolve_design_workspace_path(root, &relative)?; if !path.is_file() { - return Ok(Value::String(format!( - "局部修改失败：文件不存在：{display}" - ))); + return Err(format!("文件不存在：{display}")); } let content = fs::read_to_string(&path).map_err(|error| format!("读取失败：{error}"))?; @@ -288,20 +311,52 @@ pub(crate) fn execute_design_file_tool( } else { "\n" }; - let old = old.replace("\r\n", "\n").replace('\n', newline); - let new = new.replace("\r\n", "\n").replace('\n', newline); - let count = content.matches(&old).count(); - if count != 1 { - return Err(format!( - "原文匹配 {count} 处，需要唯一匹配；请重新读取文件并扩大匹配范围" - )); + let normalized = edits + .into_iter() + .map(|(old, new)| { + ( + old.replace("\r\n", "\n").replace('\n', newline), + new.replace("\r\n", "\n").replace('\n', newline), + ) + }) + .collect::>(); + let mut matches = Vec::new(); + for (index, (old, new)) in normalized.iter().enumerate() { + let count = content.matches(old).count(); + if count == 0 { + return Err(format!("edits[{index}] 原文未找到：{display}")); + } + if count != 1 { + return Err(format!( + "edits[{index}] 原文匹配 {count} 处，必须唯一：{display}" + )); + } + let start = content.find(old).expect("count checked"); + let end = start + old.len(); + if let Some((other_index, _other_start, _other_end)) = matches + .iter() + .find(|(_, other_start, other_end)| start < *other_end && *other_start < end) + { + return Err(format!( + "edits[{index}] 与 edits[{other_index}] 修改范围重叠：{display}" + )); + } + matches.push((index, start, end)); + let _ = new; } - crate::write_game_creator_private_file( - &path, - content.replacen(&old, &new, 1).as_bytes(), - "策划工作区文件", - )?; - Ok(Value::String(format!("已局部修改 {display}"))) + let mut updated = content.clone(); + for (index, start, end) in matches.into_iter().rev() { + let (_, new) = &normalized[index]; + updated.replace_range(start..end, new); + } + if updated == content { + return Err(format!("没有产生修改：{display}")); + } + crate::write_game_creator_private_file(&path, updated.as_bytes(), "策划工作区文件")?; + Ok(Value::String(format!( + "已局部修改 {display}（{} 处）", + normalized.len() + ))) } "delete_path" => { let relative = required_tool_path(args)?; @@ -645,6 +700,29 @@ mod tests { ) .expect("patch"); assert!(patched.as_str().unwrap().contains("已局部修改")); + execute_design_file_tool( + root, + "write_file", + &json!({"path":"notes/multi.md","content":"甲\n乙\n丙"}), + ) + .expect("write multi"); + let multi = execute_design_file_tool( + root, + "patch_file", + &json!({ + "path":"notes/multi.md", + "edits":[ + {"old_text":"甲","new_text":"一"}, + {"old_text":"丙","new_text":"三"} + ] + }), + ) + .expect("multi patch"); + assert!(multi.as_str().unwrap().contains("2 处")); + assert_eq!( + fs::read_to_string(root.join("design_artifacts/notes/multi.md")).expect("read multi"), + "一\n乙\n三" + ); execute_design_file_tool(root, "delete_path", &json!({"path":"notes"})) .expect("delete dir"); assert!(!root.join("design_artifacts/notes").exists()); From 687bad0adfe27209ac228c11d55270f927ba4818 Mon Sep 17 00:00:00 2001 From: kdletters Date: Tue, 15 Sep 2026 19:27:14 +0800 Subject: [PATCH 2/5] =?UTF-8?q?=E4=BF=AE=E5=A4=8D=E7=99=BB=E5=BD=95?= =?UTF-8?q?=E5=A4=B1=E8=B4=A5=E5=8E=9F=E5=9B=A0=E6=8F=90=E7=A4=BA=20(#374)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 登录失败时，部分网关或兼容接口返回字符串形式的 error，前端解析失败后只显示通用“登录失败”，用户无法判断具体原因。 本次修改： - 统一错误解析器支持字符串 error，并保留标准嵌套错误的优先级。 - 增加登录接口返回“手机号或密码错误”的回归测试。 - 同步认证排障记录。 验证： - API 客户端测试 32 项通过 - 认证服务与登录弹窗测试 55 项通过 - npm run typecheck 通过 - npm run lint:eslint 通过 - npm run check:encoding 通过 Reviewed-on: https://git.genarrative.world/git/GenarrativeAI/Genarrative/pulls/374 Co-authored-by: kdletters Co-committed-by: kdletters --- docs/project-memory/shared-memory/pitfalls.md | 7 +++++ packages/shared/src/http.ts | 30 ++++++++++++++----- src/services/apiClient.test.ts | 26 ++++++++++++++++ 3 files changed, 55 insertions(+), 8 deletions(-) diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md index 00c1fa366..35e266485 100644 --- a/docs/project-memory/shared-memory/pitfalls.md +++ b/docs/project-memory/shared-memory/pitfalls.md @@ -5596,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` 通过。 diff --git a/packages/shared/src/http.ts b/packages/shared/src/http.ts index 9aa01fafa..84e73fa8e 100644 --- a/packages/shared/src/http.ts +++ b/packages/shared/src/http.ts @@ -177,23 +177,34 @@ export function parseApiErrorMessage(rawText: string, fallbackMessage: string) { const parsed = JSON.parse(rawText) as | ApiErrorResponse | { - error?: { - message?: string; - code?: string; - details?: Record | null; - }; + error?: + | string + | { + message?: string; + code?: string; + details?: Record | null; + }; message?: string; code?: string; }; - const detailMessage = readApiErrorDetailMessage(parsed.error?.details); + const detailMessage = + typeof parsed.error === 'object' && parsed.error !== null + ? readApiErrorDetailMessage(parsed.error.details) + : ''; if (detailMessage) { return detailMessage; } + if (typeof parsed.error === 'string' && parsed.error.trim()) { + return parsed.error.trim(); + } + if ( - typeof parsed.error?.message === 'string' && + typeof parsed.error === 'object' && + parsed.error !== null && + typeof parsed.error.message === 'string' && parsed.error.message.trim() ) { return parsed.error.message.trim(); @@ -209,7 +220,10 @@ export function parseApiErrorMessage(rawText: string, fallbackMessage: string) { } const errorCode = - typeof parsed.error?.code === 'string' && parsed.error.code.trim() + typeof parsed.error === 'object' && + parsed.error !== null && + typeof parsed.error.code === 'string' && + parsed.error.code.trim() ? parsed.error.code.trim() : 'code' in parsed && typeof parsed.code === 'string' && diff --git a/src/services/apiClient.test.ts b/src/services/apiClient.test.ts index c1021f0d0..f4149b26e 100644 --- a/src/services/apiClient.test.ts +++ b/src/services/apiClient.test.ts @@ -1031,6 +1031,32 @@ describe('apiClient', () => { }); }); + it('preserves a concrete reason from legacy string error responses', async () => { + fetchMock.mockResolvedValueOnce( + createResponseMock({ + status: 401, + body: JSON.stringify({ error: '手机号或密码错误' }), + headers: { + 'Content-Type': 'application/json', + }, + }), + ); + + await expect( + requestJson( + '/api/auth/entry', + { + method: 'POST', + }, + '登录失败', + { skipAuth: true, skipRefresh: true }, + ), + ).rejects.toMatchObject({ + message: '手机号或密码错误', + status: 401, + }); + }); + it('prefers api error details.reason over details.message for diagnostics', async () => { setStoredAccessToken('details-reason-first-token', { emit: false }); fetchMock.mockResolvedValueOnce( From 29e84a77d1bf94ea656f31f635831d6cb3baf57e Mon Sep 17 00:00:00 2001 From: kdletters Date: Tue, 15 Sep 2026 19:43:35 +0800 Subject: [PATCH 3/5] =?UTF-8?q?=E5=88=87=E6=8D=A2=20Tiantoken=20=E5=B9=B6?= =?UTF-8?q?=E5=88=A0=E9=99=A4=E6=97=A7=20Vidu=20=E9=9F=B3=E6=95=88?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新增 TIANTOKEN_BASE_URL / TIANTOKEN_API_KEY 配置并切换文本与图片链路 保留 Suno VectorEngine 路径，删除旧 Vidu submit/poll/builder 实现 同步脚本、文档、测试与运行时 provider 路由 --- .env.example | 15 +- deploy/container/api-server.env.example | 2 +- deploy/env/api-server.env.example | 6 +- .../shared-memory/decision-log.md | 11 + ...】server-rs与SpacetimeDB数据契约-2026-05-15.md | 5 +- ...发运维】本地开发验证与生产运维-2026-05-15.md | 8 +- ...编辑器】画板音乐生成入口设计-2026-06-18.md | 6 +- scripts/bgfilter-worker-load-smoke.test.mjs | 6 +- scripts/check-api-server-env.mjs | 4 +- scripts/container-worker-smoke.mjs | 6 +- scripts/export-match3d-resource-pipeline.mjs | 16 +- ...ate-edutainment-road-town-map-concepts.mjs | 14 +- ...te-edutainment-toca-world-map-concepts.mjs | 14 +- .../make-taonier-hand-spirit-transparent.mjs | 14 +- scripts/test-ve-llm.mjs | 15 +- server-rs/crates/api-server/src/config.rs | 60 ++++- .../src/editor_screen_background_decision.rs | 38 ++-- .../src/external_generation_worker.rs | 6 +- .../api-server/src/openai_image_generation.rs | 21 +- server-rs/crates/api-server/src/state.rs | 37 ++- .../handlers.rs | 215 ------------------ .../vector_engine_audio_generation/publish.rs | 6 +- .../vector_engine_audio_generation/tasks.rs | 38 ---- .../vector_engine_audio_generation/tests.rs | 212 ----------------- .../vector_engine_audio_generation/types.rs | 4 - server-rs/crates/platform-audio/src/client.rs | 59 +---- server-rs/crates/platform-audio/src/lib.rs | 13 +- .../crates/platform-audio/src/persist.rs | 7 - .../crates/platform-audio/src/request.rs | 54 +---- server-rs/crates/platform-audio/src/types.rs | 25 -- .../tests/vector_engine_audio.rs | 103 +-------- src/services/apiClient.test.ts | 20 +- 32 files changed, 217 insertions(+), 843 deletions(-) delete mode 100644 server-rs/crates/api-server/src/vector_engine_audio_generation/handlers.rs delete mode 100644 server-rs/crates/api-server/src/vector_engine_audio_generation/tasks.rs delete mode 100644 server-rs/crates/api-server/src/vector_engine_audio_generation/tests.rs diff --git a/.env.example b/.env.example index d8988060b..bf06357e1 100644 --- a/.env.example +++ b/.env.example @@ -1,8 +1,8 @@ # Server-side OpenAI-compatible LLM endpoint base URL. -LLM_BASE_URL="https://api.vectorengine.cn/v1" +LLM_BASE_URL="https://api.tiantoken.com/v1" # Server-side API key used by the local Vite proxy. -# Recommended: set `LLM_API_KEY` locally, or use `VECTOR_ENGINE_API_KEY` +# Recommended: set `LLM_API_KEY` locally, or use `TIANTOKEN_API_KEY` # through the Rust api-server proxy. # Legacy compatibility: `VITE_LLM_API_KEY` is still supported by the proxy, # but it should not be relied on by browser code. @@ -122,7 +122,7 @@ WECHAT_MINIPROGRAM_MESSAGE_ENCODING_AES_KEY="" # Model name for chat completions. VITE_LLM_MODEL="gpt-5.4-mini" GENARRATIVE_LLM_PROVIDER="openai-compatible" -GENARRATIVE_LLM_BASE_URL="https://api.vectorengine.cn/v1" +GENARRATIVE_LLM_BASE_URL="https://api.tiantoken.com/v1" GENARRATIVE_LLM_API_KEY="" GENARRATIVE_LLM_MODEL="gpt-5.4-mini" @@ -130,10 +130,15 @@ GENARRATIVE_LLM_MODEL="gpt-5.4-mini" DASHSCOPE_BASE_URL="https://dashscope.aliyuncs.com/api/v1" DASHSCOPE_API_KEY="YOUR_DASHSCOPE_API_KEY" -# VectorEngine LLM and GPT-image-2 / Gemini image generation config. +# Tiantoken LLM and GPT-image-2 / Gemini image generation config. +TIANTOKEN_BASE_URL="https://api.tiantoken.com" +TIANTOKEN_API_KEY="" +TIANTOKEN_IMAGE_REQUEST_TIMEOUT_MS="1000000" + +# VectorEngine is retained for Suno audio generation only. VECTOR_ENGINE_BASE_URL="https://api.vectorengine.cn" VECTOR_ENGINE_API_KEY="" -VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS="1000000" +VECTOR_ENGINE_AUDIO_REQUEST_TIMEOUT_MS="180000" # ElevenLabs editor sound-effect generation is server-side only. ELEVENLABS_BASE_URL="https://api.elevenlabs.io" diff --git a/deploy/container/api-server.env.example b/deploy/container/api-server.env.example index 6dddc3e82..b4e0286b1 100644 --- a/deploy/container/api-server.env.example +++ b/deploy/container/api-server.env.example @@ -62,7 +62,7 @@ GENARRATIVE_SPACETIME_POOL_SIZE=8 GENARRATIVE_SPACETIME_PROCEDURE_TIMEOUT_SECONDS=45 GENARRATIVE_LLM_PROVIDER=openai-compatible -GENARRATIVE_LLM_BASE_URL=https://api.vectorengine.cn/v1 +GENARRATIVE_LLM_BASE_URL=https://api.tiantoken.com/v1 GENARRATIVE_LLM_API_KEY= GENARRATIVE_LLM_MODEL=gpt-5.4-mini WECHAT_MINIPROGRAM_MESSAGE_TOKEN= diff --git a/deploy/env/api-server.env.example b/deploy/env/api-server.env.example index dd543cd4f..9b508dac1 100644 --- a/deploy/env/api-server.env.example +++ b/deploy/env/api-server.env.example @@ -79,7 +79,7 @@ GENARRATIVE_SPACETIME_POOL_SIZE=8 GENARRATIVE_SPACETIME_PROCEDURE_TIMEOUT_SECONDS=45 GENARRATIVE_LLM_PROVIDER=openai-compatible -GENARRATIVE_LLM_BASE_URL=https://api.vectorengine.cn/v1 +GENARRATIVE_LLM_BASE_URL=https://api.tiantoken.com/v1 GENARRATIVE_LLM_API_KEY= GENARRATIVE_LLM_MODEL=gpt-5.4-mini # LLM Router 正式账号链路：production 固定使用官方地址/模型；管理员 Token 只读受保护文件。 @@ -87,9 +87,11 @@ GENARRATIVE_LLM_ROUTER_BASE_URL=https://router.genarrative.world/v1 GENARRATIVE_LLM_ROUTER_PROVISIONING_SECRET_FILE=/etc/genarrative/secrets/llm-router-provisioning.secret GENARRATIVE_LLM_ROUTER_API_KEY_ENCRYPTION_SECRET_FILE=/etc/genarrative/secrets/llm-router-api-key-encryption.secret GENARRATIVE_LLM_ROUTER_ADMIN_TOKEN_FILE=/etc/genarrative/secrets/llm-router-admin.token +TIANTOKEN_BASE_URL=https://api.tiantoken.com +TIANTOKEN_API_KEY= +TIANTOKEN_IMAGE_REQUEST_TIMEOUT_MS=1000000 VECTOR_ENGINE_BASE_URL=https://api.vectorengine.cn VECTOR_ENGINE_API_KEY= -VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS=1000000 VECTOR_ENGINE_AUDIO_REQUEST_TIMEOUT_MS=180000 ELEVENLABS_BASE_URL=https://api.elevenlabs.io ELEVENLABS_API_KEY= diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md index d35c4436d..d18fbd8ab 100644 --- a/docs/project-memory/shared-memory/decision-log.md +++ b/docs/project-memory/shared-memory/decision-log.md @@ -8740,3 +8740,14 @@ 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 实现。 diff --git a/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md b/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md index becec30de..f21c0516b 100644 --- a/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md +++ b/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md @@ -258,8 +258,9 @@ npm run check:server-rs-ddd - 已有图片完美像素化：登录态 `POST /api/editor/images/pixel-art-snaps` 使用 `sourceImageSrc` 承载 `objectKey / resourceId / assetId` 候选稳定引用，要求 `projectId / canvasCompletion` 且 `canvasCompletion.dialogId` 必须非空，并可携带 `sourceResourceId / assetKind / generationInputs / assetFolderId / assetLabel`；BFF 必须在下载前将候选解析为当前 owner 已登记的私有 OSS object key，并校验 project / resource / asset 归属，拒绝 `data:` / `blob:`、signed URL、普通外链和音频、视频、图片序列等非静态栅格输入。归属校验有两条等价路径：带 `sourceResourceId` 且 `sourceImageSrc` 能免查确认指向同一张图（本身即该 objectKey 或就是该 resourceId）时，来源资源已随 owner-scoped 项目读取完成鉴权，直接断言 `resource.ownerUserId` 与 `resource.projectId` 后取用其 objectKey，不再按注册 ID 做全账号项目与素材库扫描；两个字段指向不同图片必须直接拒绝而不是退回扫描。其余情况仍走完整解析。跨记录的 asset_kind 扫描随扫描一并省略，按 `(bucket, objectKey)` 的存储类型点查两条路径都保留，动图仍由下载后的静态编码门禁按实际字节拒绝。编码门禁只接受静态 PNG / JPEG / WebP，明确拒绝 GIF、带 `acTL` 的 APNG 及带动画标志 / `ANIM` / `ANMF` chunk 的 WebP。处理复用 `platform-image` 纯内存 snapper、单边 `10000` 与总像素 `8294400` 上限，并发控制分两层：端点级并发闸最大 `4`、等待队列上限 `2048`，在首次 IO 之前取得，队列满返回 `503` 并带 `Retry-After`，等待超预算返回 `504`；内层是与生成风格共享的进程级 CPU 并发 `2`。30 秒总预算从 handler 入口起算，覆盖归属校验读取、OSS 下载、两层排队与规整全过程。OSS 读写共用带 `connect 10s / total 120s` 的进程级 HTTP 客户端。strict 与生成风格使用完全相同的 legacy profile、峰值估算、单轴步长补全、walker、采样和编码，唯一差异是横纵两轴都未检测到步长时，不执行 `min(width,height)/64` 统一网格兜底而返回不适用。任一轴已检测到步长时，两条路径行为和输出必须一致。读取、解码、校验、排队、规整、PNG 编码任一步失败 / 超时 / 不适用时，在最终持久化前返回错误，OSS PUT、asset object、project resource、账号素材和画布 layer 增量都必须为零。成功结果保留源图，只对最终 PNG 做一次 OSS PUT，并至多各创建一个 `editor_project_resource` 和一个 `editor_asset`；源图已有正式 project resource 时，结果资源以 `source_resource_id` 关联该资源，再按 `canvasCompletion` 尝试写入一个右侧派生 layer。completion 读取的权威 dialog 已删除时沿用现有语义跳过画布写入，不得用请求中的旧 placeholder 复活图层；已经成功落库的 resource / asset 可以保留。客户端回包时若本地 dialog 已删除，不应用完成快照；现有布局 CAS 没有 deletion tombstone，completion 先提交、删除保存后冲突的极端竞态仍按权威快照收口。客户端不得为该 unsafe POST 配置 `EDITOR_REQUEST_RETRY_OPTIONS`，请求字节可能已发送后不因 transport 异常或 `408 / 425 / 429 / 502 / 503 / 504` 自动重放；Bearer 中间件在 handler 前拒绝请求后的既有认证恢复继续保留。结果未知时先 GET 权威项目 / 素材快照。 - 完美像素持久化边界：所有可判定的稳定引用、owner、项目、来源资源、素材类型、静态编码、元数据、网格适用性、排队、CPU、解码、规整和编码校验都必须在首个最终 PNG PUT 前完成。handler 先用纯 prepare 生成精确 object key 和候选 project resource，再调用只读 `preflight_editor_pixel_art_result_and_return`；preflight 校验自定义素材目录归属（尚未创建的默认目录允许通过）、复用权威 canvas completion planner，并对 legacy / structured 候选布局执行 2 MiB 总量和 512 KiB 单项门禁。preflight 与后续 PUT / HEAD / 原子 persist 共用同一份 60 秒绝对 deadline；preflight 失败或超时不得发送 PUT，也不得附加 `resultPersistenceStarted`。最终 PNG 的 OSS PUT / HEAD 仍位于数据库事务外；确认上传结果后，`asset_object + editor_project_resource + editor_asset + optional canvas completion` 必须由 `persist_editor_pixel_art_result_and_return` 在一次 `try_with_tx` 中原子提交，handler 不得先调用 `confirm_asset_object` 或三个旧分段 helper。最终 procedure 必须重新校验目录、布局、幂等身份和 revision，不能把 preflight 结果当成提交凭证。preflight 不创建锁或 reservation，因此通过后若目录或画布被并发修改，最终事务仍可能在 PUT 后拒绝并留下无引用 OSS object；当前不做破坏性删除补偿或历史孤儿清理。该原子保证只覆盖本次结果事实；前置 owner-scoped 项目 / 素材读取仍可沿用既有默认 canvas / folder 懒建语义，不把整个请求声明为数据库只读。operation 以规范化 `canvasCompletion.dialogId` 表示并由 owner / project 限定作用域；task ID 可由前端直接推导，object / resource / asset ID 按同一 operation 稳定派生，object key 必须包含覆盖规范输入、来源 / 输出摘要与算法版本的 64 位 fingerprint。owner-scoped 项目快照发现同一 operation 的稳定 result `resourceId` 时，HTTP 路径必须在来源解析、OSS 下载、规整、preflight 和 PUT 前直接返回 `409`，携带 `operationResultAlreadyExists=true` 与 `resultResourceId`，并由客户端 GET-only 对账；本次请求不得附加 `resultPersistenceStarted`。`AlreadyApplied` 仅在 early guard 与最终 procedure 并发相遇时作为底层幂等兜底，复用既有 commit 且不得再次执行 layout CAS 或推进 revision；同 operation 输入漂移、稳定 ID / object location 冲突或 object/resource/asset 只有部分存在时必须整笔失败关闭并映射 `409`，不得补写或覆盖第一次事实。权威 dialog 已删除时 object/resource/asset 仍在同一事务提交，canvas / revision 不变并返回 `DialogMissing`。HTTP timeout/drop 不能撤销已经发往远端的 procedure，因此首个 PUT 后仍设置 `resultPersistenceStarted=true` 并按稳定身份对账；该标记不再表示数据库可能部分提交。 - 完美像素 unknown 与并发闸测试边界：上一条末句“结果未知时先 GET 权威项目 / 素材快照”的旧表述已撤回，项目 GET 才是唯一结果 verdict；素材刷新只允许在项目终态后 best-effort 触发，不能参与成功判断。无 dialog 只有同时存在匹配稳定 task 的唯一 resource 时才是 asset-only 成功，否则保持 unknown。过期预算用例只断言返回 `504`，不得读取进程级 `EDITOR_PIXEL_ART_SNAP_QUEUE_DEPTH` 的 before/after；queue guard 的 Drop 归还由独立用例覆盖。不得用相对断言、`--test-threads=1` 或全局串行锁掩盖并行竞态。 -- LLM：通用 LLM 门面继续使用 `GENARRATIVE_LLM_*`；`platform-llm` 文本请求默认走 Responses，旧 `/api/llm/chat/completions` 代理和少数旧运行态聊天显式保留 Chat Completions 兼容协议；创意 Agent `gpt-5` Responses / Chat Completions 文本链路已于 2026-06 从 APIMart 迁移到 VectorEngine，使用 `VECTOR_ENGINE_BASE_URL` / `VECTOR_ENGINE_API_KEY` 构造 OpenAI-compatible client，`api-server` 会把未带 `/v1` 的 VectorEngine base URL 规范化到 `/v1` 后请求 `/responses`。`APIMART_BASE_URL` / `APIMART_API_KEY` 只作为历史残留，不再作为创意 Agent gpt-5 客户端来源；后续排障时优先确认 VectorEngine `/v1/models`、`/v1/chat/completions` 和 `/v1/responses` 可用性。 -- LLM：通用 LLM 门面继续使用 `GENARRATIVE_LLM_*`；创意 Agent `gpt-5.4-mini` Chat Completions 文本链路已于 2026-06 从 APIMart 迁移到 VectorEngine，使用 `VECTOR_ENGINE_BASE_URL` / `VECTOR_ENGINE_API_KEY` 构造 OpenAI-compatible client，`api-server` 会把未带 `/v1` 的 VectorEngine base URL 规范化到 `/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`。`APIMART_BASE_URL` / `APIMART_API_KEY` 只作为历史残留，不再作为创意 Agent gpt-5.4-mini 客户端来源；后续排障时优先确认 VectorEngine `/v1/models`、`/v1/chat/completions` 和 `/v1/responses` 可用性。 +- LLM：通用 LLM 门面继续使用 `GENARRATIVE_LLM_*`；`platform-llm` 文本请求默认走 Responses，旧 `/api/llm/chat/completions` 代理和少数旧运行态聊天显式保留 Chat Completions 兼容协议；创意 Agent 文本链路使用 Tiantoken，使用 `TIANTOKEN_BASE_URL` / `TIANTOKEN_API_KEY` 构造 OpenAI-compatible client，`api-server` 会把未带 `/v1` 的 Tiantoken base URL 规范化到 `/v1`。VectorEngine 只保留给 Suno 音乐任务；后续排障时优先确认 Tiantoken `/v1/models`、`/v1/chat/completions` 和 `/v1/responses` 可用性。 +- LLM：通用 LLM 门面继续使用 `GENARRATIVE_LLM_*`；创意 Agent `gpt-5.4-mini` Chat Completions 文本链路读取 `TIANTOKEN_BASE_URL` / `TIANTOKEN_API_KEY`，通用 `/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 凭据承接。`APIMART_BASE_URL` / `APIMART_API_KEY` 只作为历史残留，不再作为创意 Agent 客户端来源。 +- 当前 provider 路由：`TIANTOKEN_BASE_URL` / `TIANTOKEN_API_KEY` 承载原 VectorEngine 的文本和图片能力；旧版 Vidu 音效代码已移除；`VECTOR_ENGINE_BASE_URL` / `VECTOR_ENGINE_API_KEY` 仅保留给 Suno 背景音乐及 Suno 音效任务；新编辑器 SFX V2 继续独立使用 ElevenLabs。 ### 平台适配器：`platform-llm` 公共能力与三协议工具契约 diff --git a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md index 7855d1a72..066bc0a5d 100644 --- a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md +++ b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md @@ -214,7 +214,7 @@ spacetime sql "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 && spacetime version use `，升级后重启 `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 提交进仓库。 ### 手机验证码短信 diff --git a/docs/【编辑器】画板音乐生成入口设计-2026-06-18.md b/docs/【编辑器】画板音乐生成入口设计-2026-06-18.md index b81239a14..7e5133dd9 100644 --- a/docs/【编辑器】画板音乐生成入口设计-2026-06-18.md +++ b/docs/【编辑器】画板音乐生成入口设计-2026-06-18.md @@ -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。 diff --git a/scripts/bgfilter-worker-load-smoke.test.mjs b/scripts/bgfilter-worker-load-smoke.test.mjs index 635c09cfd..919dedcef 100644 --- a/scripts/bgfilter-worker-load-smoke.test.mjs +++ b/scripts/bgfilter-worker-load-smoke.test.mjs @@ -24,7 +24,7 @@ describe('bgfilter worker smoke harness', () => { GENARRATIVE_BGFILTER_INTERNAL_TOKEN: 'real-internal-token', GENARRATIVE_EDITOR_BGFILTER_TOKEN: 'real-provider-token', PATH: '/safe/bin', - VECTOR_ENGINE_API_KEY: 'real-vector-secret', + TIANTOKEN_API_KEY: 'real-tiantoken-secret', }, providerBaseUrl: 'http://127.0.0.1:19001', tempRoot: '/tmp/bgfilter-load-smoke-test', @@ -40,10 +40,10 @@ describe('bgfilter worker smoke harness', () => { assert.equal(env.ALIYUN_OSS_ENDPOINT, 'oss-cn-shanghai.invalid'); assert.notEqual(env.ALIYUN_OSS_ACCESS_KEY_SECRET, 'real-oss-secret'); assert.equal(env.GENARRATIVE_EDITOR_BGFILTER_TOKEN, undefined); - assert.equal(env.VECTOR_ENGINE_API_KEY, undefined); + assert.equal(env.TIANTOKEN_API_KEY, undefined); assert.ok(!Object.values(env).includes('real-internal-token')); assert.ok(!Object.values(env).includes('real-provider-token')); - assert.ok(!Object.values(env).includes('real-vector-secret')); + assert.ok(!Object.values(env).includes('real-tiantoken-secret')); }); test('loopback mock 完整读取 multipart 后记录并发并返回合法 PNG 字节', async () => { diff --git a/scripts/check-api-server-env.mjs b/scripts/check-api-server-env.mjs index 8b4d24e5f..21e8f3cf6 100644 --- a/scripts/check-api-server-env.mjs +++ b/scripts/check-api-server-env.mjs @@ -1,8 +1,8 @@ import { mergeApiServerEnv } from './dev-utils.mjs'; const REQUIRED_FOR_PUZZLE_GENERATION = [ - 'VECTOR_ENGINE_BASE_URL', - 'VECTOR_ENGINE_API_KEY', + 'TIANTOKEN_BASE_URL', + 'TIANTOKEN_API_KEY', 'ALIYUN_OSS_BUCKET', 'ALIYUN_OSS_ENDPOINT', 'ALIYUN_OSS_ACCESS_KEY_ID', diff --git a/scripts/container-worker-smoke.mjs b/scripts/container-worker-smoke.mjs index 881224570..1beed7036 100644 --- a/scripts/container-worker-smoke.mjs +++ b/scripts/container-worker-smoke.mjs @@ -514,11 +514,11 @@ GENARRATIVE_SPACETIME_POOL_SIZE=2 GENARRATIVE_SPACETIME_PROCEDURE_TIMEOUT_SECONDS=15 GENARRATIVE_LLM_PROVIDER=openai-compatible -GENARRATIVE_LLM_BASE_URL=https://api.vectorengine.cn/v1 +GENARRATIVE_LLM_BASE_URL=https://api.tiantoken.com/v1 GENARRATIVE_LLM_API_KEY= GENARRATIVE_LLM_MODEL=gpt-5.4-mini -VECTOR_ENGINE_BASE_URL= -VECTOR_ENGINE_API_KEY= +TIANTOKEN_BASE_URL= +TIANTOKEN_API_KEY= ALIYUN_OSS_BUCKET= ALIYUN_OSS_ENDPOINT=oss-cn-shanghai.aliyuncs.com ALIYUN_OSS_ACCESS_KEY_ID= diff --git a/scripts/export-match3d-resource-pipeline.mjs b/scripts/export-match3d-resource-pipeline.mjs index 1f192395f..872f1b8d6 100644 --- a/scripts/export-match3d-resource-pipeline.mjs +++ b/scripts/export-match3d-resource-pipeline.mjs @@ -52,12 +52,12 @@ function timestamp() { function resolveEnv() { const env = mergeApiServerEnv(repoRoot, process.env); return { - baseUrl: String(env.VECTOR_ENGINE_BASE_URL || '') + baseUrl: String(env.TIANTOKEN_BASE_URL || '') .trim() .replace(/\/+$/u, ''), - apiKey: String(env.VECTOR_ENGINE_API_KEY || '').trim(), + apiKey: String(env.TIANTOKEN_API_KEY || '').trim(), timeoutMs: Number.parseInt( - String(env.VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS || defaultTimeoutMs), + String(env.TIANTOKEN_IMAGE_REQUEST_TIMEOUT_MS || defaultTimeoutMs), 10, ), }; @@ -160,12 +160,12 @@ async function fetchJson(url, options, timeoutMs) { }); const text = await response.text(); if (!response.ok) { - throw new Error(`VectorEngine ${response.status}: ${text.slice(0, 600)}`); + throw new Error(`Tiantoken ${response.status}: ${text.slice(0, 600)}`); } return JSON.parse(text); } catch (error) { if (error?.name === 'AbortError') { - throw new Error(`VectorEngine request timed out after ${timeoutMs}ms`); + throw new Error(`Tiantoken request timed out after ${timeoutMs}ms`); } throw error; } finally { @@ -202,7 +202,7 @@ async function imageBytesFromPayload(payload, env) { if (b64Images[0]) { return Buffer.from(b64Images[0], 'base64'); } - throw new Error('VectorEngine returned no image'); + throw new Error('Tiantoken returned no image'); } async function generateImage(env, { prompt, negativePrompt, size, outPath }) { @@ -320,7 +320,7 @@ async function main() { { mode: 'dry-run', outDir, - message: '加 --live 才会真实调用 VectorEngine。', + message: '加 --live 才会真实调用 Tiantoken。', prompts, }, null, @@ -332,7 +332,7 @@ async function main() { const env = resolveEnv(); if (!env.baseUrl || !env.apiKey) { - throw new Error('Missing VECTOR_ENGINE_BASE_URL or VECTOR_ENGINE_API_KEY'); + throw new Error('Missing TIANTOKEN_BASE_URL or TIANTOKEN_API_KEY'); } console.log(`[match3d-export] 1/4 生成关卡整图 -> ${outDir}`); diff --git a/scripts/generate-edutainment-road-town-map-concepts.mjs b/scripts/generate-edutainment-road-town-map-concepts.mjs index 84d8264c6..14c181782 100644 --- a/scripts/generate-edutainment-road-town-map-concepts.mjs +++ b/scripts/generate-edutainment-road-town-map-concepts.mjs @@ -127,12 +127,12 @@ function resolveEnv() { ...process.env, }; return { - baseUrl: String(loaded.VECTOR_ENGINE_BASE_URL || '') + baseUrl: String(loaded.TIANTOKEN_BASE_URL || '') .trim() .replace(/\/+$/u, ''), - apiKey: String(loaded.VECTOR_ENGINE_API_KEY || '').trim(), + apiKey: String(loaded.TIANTOKEN_API_KEY || '').trim(), timeoutMs: Number.parseInt( - String(loaded.VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS || defaultTimeoutMs), + String(loaded.TIANTOKEN_IMAGE_REQUEST_TIMEOUT_MS || defaultTimeoutMs), 10, ), }; @@ -249,12 +249,12 @@ async function fetchJson(url, options, timeoutMs) { }); const text = await response.text(); if (!response.ok) { - throw new Error(`VectorEngine ${response.status}: ${text.slice(0, 600)}`); + throw new Error(`Tiantoken ${response.status}: ${text.slice(0, 600)}`); } return JSON.parse(text); } catch (error) { if (error?.name === 'AbortError') { - throw new Error(`VectorEngine request timed out after ${timeoutMs}ms`); + throw new Error(`Tiantoken request timed out after ${timeoutMs}ms`); } throw error; } finally { @@ -335,7 +335,7 @@ async function generateOne(env, concept, size, references) { extension: inferExtensionFromBytes(bytes), }; } else { - throw new Error(`VectorEngine returned no image for ${concept.id}`); + throw new Error(`Tiantoken returned no image for ${concept.id}`); } mkdirSync(outDir, { recursive: true }); @@ -401,7 +401,7 @@ if (!env.baseUrl || !env.apiKey) { console.error( JSON.stringify({ ok: false, - error: 'Missing VECTOR_ENGINE_BASE_URL or VECTOR_ENGINE_API_KEY', + error: 'Missing TIANTOKEN_BASE_URL or TIANTOKEN_API_KEY', hasBaseUrl: Boolean(env.baseUrl), hasApiKey: Boolean(env.apiKey), }), diff --git a/scripts/generate-edutainment-toca-world-map-concepts.mjs b/scripts/generate-edutainment-toca-world-map-concepts.mjs index c6bce5c54..ed9f37ab0 100644 --- a/scripts/generate-edutainment-toca-world-map-concepts.mjs +++ b/scripts/generate-edutainment-toca-world-map-concepts.mjs @@ -107,12 +107,12 @@ function resolveEnv() { ...process.env, }; return { - baseUrl: String(loaded.VECTOR_ENGINE_BASE_URL || '') + baseUrl: String(loaded.TIANTOKEN_BASE_URL || '') .trim() .replace(/\/+$/u, ''), - apiKey: String(loaded.VECTOR_ENGINE_API_KEY || '').trim(), + apiKey: String(loaded.TIANTOKEN_API_KEY || '').trim(), timeoutMs: Number.parseInt( - String(loaded.VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS || defaultTimeoutMs), + String(loaded.TIANTOKEN_IMAGE_REQUEST_TIMEOUT_MS || defaultTimeoutMs), 10, ), }; @@ -226,12 +226,12 @@ async function fetchJson(url, options, timeoutMs) { }); const text = await response.text(); if (!response.ok) { - throw new Error(`VectorEngine ${response.status}: ${text.slice(0, 600)}`); + throw new Error(`Tiantoken ${response.status}: ${text.slice(0, 600)}`); } return JSON.parse(text); } catch (error) { if (error?.name === 'AbortError') { - throw new Error(`VectorEngine request timed out after ${timeoutMs}ms`); + throw new Error(`Tiantoken request timed out after ${timeoutMs}ms`); } throw error; } finally { @@ -314,7 +314,7 @@ async function generateOne(env, concept, size) { extension: inferExtensionFromBytes(bytes), }; } else { - throw new Error(`VectorEngine returned no image for ${concept.id}`); + throw new Error(`Tiantoken returned no image for ${concept.id}`); } mkdirSync(outDir, { recursive: true }); @@ -375,7 +375,7 @@ if (!env.baseUrl || !env.apiKey) { console.error( JSON.stringify({ ok: false, - error: 'Missing VECTOR_ENGINE_BASE_URL or VECTOR_ENGINE_API_KEY', + error: 'Missing TIANTOKEN_BASE_URL or TIANTOKEN_API_KEY', hasBaseUrl: Boolean(env.baseUrl), hasApiKey: Boolean(env.apiKey), }), diff --git a/scripts/make-taonier-hand-spirit-transparent.mjs b/scripts/make-taonier-hand-spirit-transparent.mjs index 58cf53605..b70a9a9d0 100644 --- a/scripts/make-taonier-hand-spirit-transparent.mjs +++ b/scripts/make-taonier-hand-spirit-transparent.mjs @@ -87,12 +87,12 @@ function resolveEnv() { ...process.env, }; return { - baseUrl: String(loaded.VECTOR_ENGINE_BASE_URL || '') + baseUrl: String(loaded.TIANTOKEN_BASE_URL || '') .trim() .replace(/\/+$/u, ''), - apiKey: String(loaded.VECTOR_ENGINE_API_KEY || '').trim(), + apiKey: String(loaded.TIANTOKEN_API_KEY || '').trim(), timeoutMs: Number.parseInt( - String(loaded.VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS || timeoutMsDefault), + String(loaded.TIANTOKEN_IMAGE_REQUEST_TIMEOUT_MS || timeoutMsDefault), 10, ), }; @@ -180,12 +180,12 @@ async function fetchJson(url, options, timeoutMs) { }); const text = await response.text(); if (!response.ok) { - throw new Error(`VectorEngine ${response.status}: ${text.slice(0, 600)}`); + throw new Error(`Tiantoken ${response.status}: ${text.slice(0, 600)}`); } return JSON.parse(text); } catch (error) { if (error?.name === 'AbortError') { - throw new Error(`VectorEngine request timed out after ${timeoutMs}ms`); + throw new Error(`Tiantoken request timed out after ${timeoutMs}ms`); } throw error; } finally { @@ -235,7 +235,7 @@ async function generateChromaSource() { throw new Error( JSON.stringify({ ok: false, - error: 'Missing VECTOR_ENGINE_BASE_URL or VECTOR_ENGINE_API_KEY', + error: 'Missing TIANTOKEN_BASE_URL or TIANTOKEN_API_KEY', hasBaseUrl: Boolean(env.baseUrl), hasApiKey: Boolean(env.apiKey), }), @@ -263,7 +263,7 @@ async function generateChromaSource() { } else if (b64Images[0]) { bytes = Buffer.from(b64Images[0], 'base64'); } else { - throw new Error('VectorEngine returned no image'); + throw new Error('Tiantoken returned no image'); } mkdirSync(outputDir, { recursive: true }); diff --git a/scripts/test-ve-llm.mjs b/scripts/test-ve-llm.mjs index ea1b1f76a..e21cec718 100644 --- a/scripts/test-ve-llm.mjs +++ b/scripts/test-ve-llm.mjs @@ -28,12 +28,11 @@ function loadEnv(path) { const env = loadEnv(resolve(root, '.env.secrets.local')); const BASE = - env.VECTOR_ENGINE_BASE_URL?.replace(/\/+$/, '') || - 'https://api.vectorengine.cn'; -const KEY = env.VECTOR_ENGINE_API_KEY || ''; + env.TIANTOKEN_BASE_URL?.replace(/\/+$/, '') || 'https://api.tiantoken.com'; +const KEY = env.TIANTOKEN_API_KEY || ''; if (!KEY) { - console.error('未找到 VECTOR_ENGINE_API_KEY'); + console.error('未找到 TIANTOKEN_API_KEY'); process.exit(1); } @@ -90,7 +89,7 @@ async function test(name, method, path, body = null) { } } -console.log(`VectorEngine LLM 能力探测`); +console.log(`Tiantoken LLM 能力探测`); console.log(`目标: ${BASE}\n`); const tests = [ @@ -185,12 +184,12 @@ console.log( // 结论 if (pass >= 3) { - console.log('\n✅ VectorEngine 支持 LLM 文本调用，可替代 Apimart。'); + console.log('\n✅ Tiantoken 支持 LLM 文本调用，可替代 Apimart。'); console.log( - ' 将 .env.secrets.local 中 VECTOR_ENGINE_BASE_URL / VECTOR_ENGINE_API_KEY 配好即可。', + ' 将 .env.secrets.local 中 TIANTOKEN_BASE_URL / TIANTOKEN_API_KEY 配好即可。', ); } else if (pass <= 1) { - console.log('\n❌ VectorEngine 不支持 LLM 文本调用。'); + console.log('\n❌ Tiantoken 不支持 LLM 文本调用。'); } else { console.log('\n⚠️ 部分支持，需进一步评估。'); } diff --git a/server-rs/crates/api-server/src/config.rs b/server-rs/crates/api-server/src/config.rs index f3b6057f5..94ea4d4e4 100644 --- a/server-rs/crates/api-server/src/config.rs +++ b/server-rs/crates/api-server/src/config.rs @@ -1175,6 +1175,7 @@ impl AppConfig { read_first_non_empty_env(&[ "GENARRATIVE_LLM_API_KEY", "LLM_API_KEY", + "TIANTOKEN_API_KEY", "VECTOR_ENGINE_API_KEY", "ARK_API_KEY", ]) @@ -1183,6 +1184,7 @@ impl AppConfig { "GENARRATIVE_LLM_API_KEY", "LLM_API_KEY", "ARK_API_KEY", + "TIANTOKEN_API_KEY", "VECTOR_ENGINE_API_KEY", ]) }; @@ -1275,11 +1277,12 @@ impl AppConfig { config.vector_engine_api_key = read_first_non_empty_env(&["VECTOR_ENGINE_API_KEY"]); - if let Some(vector_engine_image_request_timeout_ms) = - read_first_positive_u64_env(&["VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS"]) - { + if let Some(tiantoken_image_request_timeout_ms) = read_first_positive_u64_env(&[ + "TIANTOKEN_IMAGE_REQUEST_TIMEOUT_MS", + "VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS", + ]) { // 单次 attempt 上限允许按环境收短；worker 调用还会受整次任务的绝对 deadline 约束。 - config.vector_engine_image_request_timeout_ms = vector_engine_image_request_timeout_ms; + config.vector_engine_image_request_timeout_ms = tiantoken_image_request_timeout_ms; } if let Some(vector_engine_audio_request_timeout_ms) = @@ -1425,6 +1428,20 @@ impl AppConfig { } } +/// Tiantoken 是图片、文本和旧版非 Suno 音频生成的新 provider。 +/// +/// 这里保留对 `AppConfig.vector_engine_*` 的回退，方便测试构造的旧配置继续工作； +/// 生产环境一旦设置了新的 `TIANTOKEN_*` 变量，就不会再把非 Suno 请求发往 VectorEngine。 +pub(crate) fn tiantoken_base_url(config: &AppConfig) -> String { + read_first_non_empty_env(&["TIANTOKEN_BASE_URL"]) + .unwrap_or_else(|| config.vector_engine_base_url.clone()) +} + +pub(crate) fn tiantoken_api_key(config: &AppConfig) -> Option { + read_first_non_empty_env(&["TIANTOKEN_API_KEY"]) + .or_else(|| config.vector_engine_api_key.clone()) +} + fn read_first_non_empty_env(keys: &[&str]) -> Option { keys.iter().find_map(|key| { env::var(key).ok().and_then(|value| { @@ -1730,6 +1747,7 @@ mod tests { DEFAULT_EXTERNAL_GENERATION_WORKER_LEASE_SECONDS, DEFAULT_EXTERNAL_GENERATION_WORKER_LONG_JOB_TIMEOUT_SECONDS, ExternalGenerationMode, LlmProvider, ProcessRole, parse_bool, parse_external_generation_mode, parse_process_role, + tiantoken_api_key, tiantoken_base_url, }; use std::{ fs, @@ -1822,6 +1840,40 @@ mod tests { } } + #[test] + fn tiantoken_provider_prefers_new_env_names_over_legacy_vector_engine_config() { + let _guard = ENV_LOCK + .get_or_init(|| Mutex::new(())) + .lock() + .expect("env lock should not poison"); + let mut config = AppConfig::default(); + config.vector_engine_base_url = "https://vector.example.invalid".to_string(); + config.vector_engine_api_key = Some("legacy-vector-key".to_string()); + unsafe { + std::env::set_var("TIANTOKEN_BASE_URL", " https://api.tiantoken.example/ "); + std::env::set_var("TIANTOKEN_API_KEY", " tiantoken-key "); + } + + assert_eq!( + tiantoken_base_url(&config), + "https://api.tiantoken.example/" + ); + assert_eq!(tiantoken_api_key(&config).as_deref(), Some("tiantoken-key")); + + unsafe { + std::env::remove_var("TIANTOKEN_BASE_URL"); + std::env::remove_var("TIANTOKEN_API_KEY"); + } + assert_eq!( + tiantoken_base_url(&config), + "https://vector.example.invalid" + ); + assert_eq!( + tiantoken_api_key(&config).as_deref(), + Some("legacy-vector-key") + ); + } + #[test] fn llm_router_key_encryption_secret_prefers_dedicated_secret_or_derives_from_jwt() { let mut config = AppConfig::default(); diff --git a/server-rs/crates/api-server/src/editor_screen_background_decision.rs b/server-rs/crates/api-server/src/editor_screen_background_decision.rs index 434e8f8a3..45c42d631 100644 --- a/server-rs/crates/api-server/src/editor_screen_background_decision.rs +++ b/server-rs/crates/api-server/src/editor_screen_background_decision.rs @@ -117,7 +117,7 @@ pub(crate) async fn resolve_editor_screen_background_color( .map(|report| report.allowed.clone()) .unwrap_or_else(|| EDITOR_SCREEN_BACKGROUND_COLORS.to_vec()); - // 决策统一走 VectorEngine gpt-5-mini：有图用视觉档、无图用文本档（两个独立常量）， + // 决策统一走 Tiantoken gpt-5-mini：有图用视觉档、无图用文本档（两个独立常量）， // 都不继承 Ark 默认文本模型（豆包，选色能力弱）。仅当 gpt5 客户端未配置时才降级回默认 // llm_client；该默认客户端是纯文本模型（Ark），收到图片分片会被上游 400 拒绝，故先丢弃图片分片。 let (llm_client, decision_model) = match vision_llm_client { @@ -860,10 +860,10 @@ mod tests { ); } - // 真机联调：按 build_editor_agent_llm_client 的方式组 VectorEngine 客户端，直接跑 + // 真机联调：按 build_editor_agent_llm_client 的方式组 Tiantoken 客户端，直接跑 // resolve_editor_screen_background_color 的完整代码路径（无图文本档 + 有图视觉档）， - // 验证决策请求真的打到 VectorEngine 并被解析成候选色（decision.fallback == false）。 - // 凭证从仓库根 .env.local / .env.secrets.local 读，需要真实 VECTOR_ENGINE_* 才有意义。 + // 验证决策请求真的打到 Tiantoken 并被解析成候选色（decision.fallback == false）。 + // 凭证从仓库根 .env.local / .env.secrets.local 读，需要真实 TIANTOKEN_* 才有意义。 // 运行：cargo test -p api-server --manifest-path server-rs/Cargo.toml \ // editor_screen_background_decision::tests::live -- --ignored --nocapture fn read_live_env(key: &str) -> Option { @@ -895,11 +895,11 @@ mod tests { std::env::var(key).ok().or_else(|| map.get(key).cloned()) } - fn build_live_vector_engine_client() -> Option { + fn build_live_tiantoken_client() -> Option { use platform_llm::{LlmConfig, LlmProvider}; - let base_url = read_live_env("VECTOR_ENGINE_BASE_URL")?; - let api_key = read_live_env("VECTOR_ENGINE_API_KEY")?; + let base_url = read_live_env("TIANTOKEN_BASE_URL")?; + let api_key = read_live_env("TIANTOKEN_API_KEY")?; // 与 state.rs build_editor_agent_llm_client 一致：规整到以 /v1 结尾。 let base_url = if base_url.trim_end_matches('/').ends_with("/v1") { base_url.trim_end_matches('/').to_string() @@ -915,8 +915,8 @@ mod tests { 0, 500, ) - .expect("live VectorEngine LlmConfig should build"); - Some(LlmClient::new(config).expect("live VectorEngine LlmClient should build")) + .expect("live Tiantoken LlmConfig should build"); + Some(LlmClient::new(config).expect("live Tiantoken LlmClient should build")) } fn solid_source_image_data_url() -> String { @@ -938,10 +938,10 @@ mod tests { } #[tokio::test] - #[ignore = "真机联调：需要 .env.local / .env.secrets.local 中真实 VECTOR_ENGINE_* 凭证"] - async fn live_screen_background_decision_hits_vector_engine_without_image() { - let Some(client) = build_live_vector_engine_client() else { - panic!("缺少 VECTOR_ENGINE_BASE_URL / VECTOR_ENGINE_API_KEY，无法真机联调"); + #[ignore = "真机联调：需要 .env.local / .env.secrets.local 中真实 TIANTOKEN_* 凭证"] + async fn live_screen_background_decision_hits_tiantoken_without_image() { + let Some(client) = build_live_tiantoken_client() else { + panic!("缺少 TIANTOKEN_BASE_URL / TIANTOKEN_API_KEY，无法真机联调"); }; let decision = resolve_editor_screen_background_color( None, @@ -970,16 +970,16 @@ mod tests { assert_eq!(decision.mode, EditorScreenBackgroundDecisionMode::Auto); assert!( !decision.fallback, - "若走到兜底说明 LLM 没答复（VectorEngine 未被成功调用或响应解析失败）" + "若走到兜底说明 LLM 没答复（Tiantoken 未被成功调用或响应解析失败）" ); assert!(decision.attempts >= 1); } #[tokio::test] - #[ignore = "真机联调：需要 .env.local / .env.secrets.local 中真实 VECTOR_ENGINE_* 凭证"] - async fn live_screen_background_decision_hits_vector_engine_with_image() { - let Some(client) = build_live_vector_engine_client() else { - panic!("缺少 VECTOR_ENGINE_BASE_URL / VECTOR_ENGINE_API_KEY，无法真机联调"); + #[ignore = "真机联调：需要 .env.local / .env.secrets.local 中真实 TIANTOKEN_* 凭证"] + async fn live_screen_background_decision_hits_tiantoken_with_image() { + let Some(client) = build_live_tiantoken_client() else { + panic!("缺少 TIANTOKEN_BASE_URL / TIANTOKEN_API_KEY，无法真机联调"); }; let decision = resolve_editor_screen_background_color( None, @@ -1008,7 +1008,7 @@ mod tests { assert_eq!(decision.mode, EditorScreenBackgroundDecisionMode::Auto); assert!( !decision.fallback, - "若走到兜底说明视觉 LLM 没答复（VectorEngine 未被成功调用或响应解析失败）" + "若走到兜底说明视觉 LLM 没答复（Tiantoken 未被成功调用或响应解析失败）" ); assert!(decision.attempts >= 1); } diff --git a/server-rs/crates/api-server/src/external_generation_worker.rs b/server-rs/crates/api-server/src/external_generation_worker.rs index 722213247..b279b5054 100644 --- a/server-rs/crates/api-server/src/external_generation_worker.rs +++ b/server-rs/crates/api-server/src/external_generation_worker.rs @@ -1905,8 +1905,8 @@ mod tests { "code": "UPSTREAM_ERROR", "message": "上游服务请求失败", "details": { - "provider": "vector-engine", - "reason": "VECTOR_ENGINE_API_KEY 未配置", + "provider": "tiantoken", + "reason": "TIANTOKEN_API_KEY 未配置", "message": "提交编辑器音效任务失败：missing field sound" } }, @@ -1918,7 +1918,7 @@ mod tests { let message = response_error_message(response).await; - assert_eq!(message, "VECTOR_ENGINE_API_KEY 未配置"); + assert_eq!(message, "TIANTOKEN_API_KEY 未配置"); } #[tokio::test] diff --git a/server-rs/crates/api-server/src/openai_image_generation.rs b/server-rs/crates/api-server/src/openai_image_generation.rs index f0fa7591c..2cf90c425 100644 --- a/server-rs/crates/api-server/src/openai_image_generation.rs +++ b/server-rs/crates/api-server/src/openai_image_generation.rs @@ -75,34 +75,29 @@ impl std::fmt::Debug for OpenAiImageSettings { } } -// 中文注释：api-server 只负责配置、审计和 HTTP envelope，VectorEngine 协议细节统一由 platform-image provider 承接。 +// 中文注释：api-server 只负责配置、审计和 HTTP envelope，Tiantoken 的 OpenAI-compatible +// 图片协议细节统一由 platform-image provider 承接。 pub(crate) fn require_openai_image_settings( state: &AppState, ) -> Result { - let base_url = state - .config - .vector_engine_base_url - .trim() - .trim_end_matches('/'); + let base_url = state.tiantoken_base_url().trim().trim_end_matches('/'); if base_url.is_empty() { return Err( AppError::from_status(StatusCode::SERVICE_UNAVAILABLE).with_details(json!({ - "provider": VECTOR_ENGINE_PROVIDER, - "reason": "VECTOR_ENGINE_BASE_URL 未配置", + "provider": "tiantoken", + "reason": "TIANTOKEN_BASE_URL 未配置", })), ); } let api_key = state - .config - .vector_engine_api_key - .as_deref() + .tiantoken_api_key() .map(str::trim) .filter(|value| !value.is_empty()) .ok_or_else(|| { AppError::from_status(StatusCode::SERVICE_UNAVAILABLE).with_details(json!({ - "provider": VECTOR_ENGINE_PROVIDER, - "reason": "VECTOR_ENGINE_API_KEY 未配置", + "provider": "tiantoken", + "reason": "TIANTOKEN_API_KEY 未配置", })) })?; diff --git a/server-rs/crates/api-server/src/state.rs b/server-rs/crates/api-server/src/state.rs index dc7b08503..b4030cd62 100644 --- a/server-rs/crates/api-server/src/state.rs +++ b/server-rs/crates/api-server/src/state.rs @@ -303,6 +303,9 @@ pub struct AppStateInner { editor_generation_pricing_store: EditorGenerationPricingStore, llm_client: Option, vector_engine_llm_client: Option, + /// 非 Suno 的文本、图片和旧版音频生成 provider 配置。 + tiantoken_base_url: String, + tiantoken_api_key: Option, matting_client: Option, bgfilter_provider_http_client: reqwest::Client, bgfilter_worker_http_client: reqwest::Client, @@ -600,8 +603,14 @@ impl AppState { config.editor_generation_pricing_override_path.clone(), ) .map_err(|error| AppStateInitError::DependencyUnavailable(error.to_string()))?; + let tiantoken_base_url = crate::config::tiantoken_base_url(&config); + let tiantoken_api_key = crate::config::tiantoken_api_key(&config); let llm_client = build_llm_client(&config)?; - let vector_engine_llm_client = build_vector_engine_llm_client(&config)?; + let vector_engine_llm_client = build_vector_engine_llm_client( + &config, + &tiantoken_base_url, + tiantoken_api_key.as_deref(), + )?; let matting_client = build_matting_client(&config)?; let bgfilter_provider_http_client = build_bgfilter_provider_http_client(&config)?; let bgfilter_worker_http_client = build_bgfilter_worker_http_client(&config)?; @@ -677,6 +686,8 @@ impl AppState { editor_generation_pricing_store, llm_client, vector_engine_llm_client, + tiantoken_base_url, + tiantoken_api_key, matting_client, bgfilter_provider_http_client, bgfilter_worker_http_client, @@ -1579,6 +1590,14 @@ impl AppState { self.vector_engine_llm_client.as_ref() } + pub fn tiantoken_base_url(&self) -> &str { + self.tiantoken_base_url.as_str() + } + + pub fn tiantoken_api_key(&self) -> Option<&str> { + self.tiantoken_api_key.as_deref() + } + pub fn matting_client(&self) -> Option<&MattingClient> { self.matting_client.as_ref() } @@ -2490,21 +2509,21 @@ fn build_llm_client(config: &AppConfig) -> Result, AppStateIni fn build_vector_engine_llm_client( config: &AppConfig, + tiantoken_base_url: &str, + tiantoken_api_key: Option<&str>, ) -> Result, AppStateInitError> { - // 中文注释：Apimart 已于 2026-06 弃用，LLM 文本调用统一迁移到 VectorEngine。 - let Some(api_key) = config - .vector_engine_api_key - .as_ref() - .map(|value| value.trim()) + // 中文注释：Apimart 已于 2026-06 弃用，非 Suno 文本调用统一迁移到 Tiantoken。 + let Some(api_key) = tiantoken_api_key + .map(str::trim) .filter(|value| !value.is_empty()) else { return Ok(None); }; - let base_url = if config.vector_engine_base_url.ends_with("/v1") { - config.vector_engine_base_url.clone() + let base_url = if tiantoken_base_url.trim_end_matches('/').ends_with("/v1") { + tiantoken_base_url.trim_end_matches('/').to_string() } else { - format!("{}/v1", config.vector_engine_base_url.trim_end_matches('/')) + format!("{}/v1", tiantoken_base_url.trim_end_matches('/')) }; let llm_config = LlmConfig::new( diff --git a/server-rs/crates/api-server/src/vector_engine_audio_generation/handlers.rs b/server-rs/crates/api-server/src/vector_engine_audio_generation/handlers.rs deleted file mode 100644 index 5d3ee628b..000000000 --- a/server-rs/crates/api-server/src/vector_engine_audio_generation/handlers.rs +++ /dev/null @@ -1,215 +0,0 @@ -use axum::{ - Json, - extract::{Path, State, rejection::JsonRejection}, - response::Response, -}; -use platform_audio::{BackgroundMusicTaskRequest, SoundEffectTaskRequest}; -use serde_json::Value; -use shared_contracts::{creation_audio, visual_novel as contract}; - -use crate::{ - api_response::json_success_body, auth::AuthenticatedAccessToken, - request_context::RequestContext, state::AppState, -}; - -use super::{ - errors::{map_platform_audio_error, parse_json_payload}, - generation::normalize_creation_sound_effect_duration, - publish::publish_generated_audio_asset, - settings::require_vector_engine_audio_settings, - targets::{ - build_creation_audio_target, build_visual_novel_audio_target, - creation_audio_generation_disabled_error, - creation_audio_generation_disabled_error_for_target, - }, - types::AudioAssetSlot, -}; - -pub async fn create_visual_novel_background_music_task( - State(state): State, - axum::extract::Extension(request_context): axum::extract::Extension, - payload: Result, JsonRejection>, -) -> Result, Response> { - let Json(payload) = parse_json_payload(&request_context, payload)?; - let settings = require_vector_engine_audio_settings(&state)?; - let http_client = platform_audio::build_vector_engine_audio_http_client(&settings) - .map_err(map_platform_audio_error)?; - let task = platform_audio::submit_background_music_task( - &http_client, - &settings, - BackgroundMusicTaskRequest { - prompt: payload.prompt, - title: payload.title, - tags: payload.tags, - model: payload.model, - instrumental: true, - }, - ) - .await - .map_err(map_platform_audio_error)?; - - Ok(json_success_body( - Some(&request_context), - contract::VisualNovelAudioGenerationTaskResponse { - kind: contract::VisualNovelAudioGenerationKind::BackgroundMusic, - task_id: task.task_id, - provider: task.provider, - status: task.status, - }, - )) -} - -pub async fn create_background_music_task( - State(_state): State, - axum::extract::Extension(request_context): axum::extract::Extension, - payload: Result, JsonRejection>, -) -> Result, Response> { - let _ = parse_json_payload(&request_context, payload)?; - Err(creation_audio_generation_disabled_error() - .into_response_with_context(Some(&request_context))) -} - -pub async fn create_visual_novel_sound_effect_task( - State(state): State, - axum::extract::Extension(request_context): axum::extract::Extension, - payload: Result, JsonRejection>, -) -> Result, Response> { - let Json(payload) = parse_json_payload(&request_context, payload)?; - let settings = require_vector_engine_audio_settings(&state)?; - let http_client = platform_audio::build_vector_engine_audio_http_client(&settings) - .map_err(map_platform_audio_error)?; - let task = platform_audio::submit_sound_effect_task( - &http_client, - &settings, - SoundEffectTaskRequest { - prompt: payload.prompt, - duration: normalize_creation_sound_effect_duration(payload.duration) - .map_err(|error| error.into_response_with_context(Some(&request_context)))?, - seed: payload.seed, - }, - ) - .await - .map_err(map_platform_audio_error)?; - - Ok(json_success_body( - Some(&request_context), - contract::VisualNovelAudioGenerationTaskResponse { - kind: contract::VisualNovelAudioGenerationKind::SoundEffect, - task_id: task.task_id, - provider: task.provider, - status: task.status, - }, - )) -} - -pub async fn create_sound_effect_task( - State(_state): State, - axum::extract::Extension(request_context): axum::extract::Extension, - payload: Result, JsonRejection>, -) -> Result, Response> { - let _ = parse_json_payload(&request_context, payload)?; - Err(creation_audio_generation_disabled_error() - .into_response_with_context(Some(&request_context))) -} - -pub async fn publish_visual_novel_background_music_asset( - State(state): State, - Path(task_id): Path, - axum::extract::Extension(request_context): axum::extract::Extension, - axum::extract::Extension(authenticated): axum::extract::Extension, - payload: Result, JsonRejection>, -) -> Result, Response> { - let payload = parse_json_payload(&request_context, payload)?.0; - let target = build_visual_novel_audio_target(payload, AudioAssetSlot::BackgroundMusic)?; - publish_generated_audio_asset( - &state, - authenticated.claims().user_id(), - task_id, - AudioAssetSlot::BackgroundMusic, - target, - ) - .await - .map(|payload| { - json_success_body( - Some(&request_context), - contract::VisualNovelGeneratedAudioAssetResponse { - kind: contract::VisualNovelAudioGenerationKind::BackgroundMusic, - task_id: payload.task_id, - provider: payload.provider, - status: payload.status, - asset_object_id: payload.asset_object_id, - asset_kind: payload.asset_kind, - audio_src: payload.audio_src, - }, - ) - }) - .map_err(|error| error.into_response_with_context(Some(&request_context))) -} - -pub async fn publish_visual_novel_sound_effect_asset( - State(state): State, - Path(task_id): Path, - axum::extract::Extension(request_context): axum::extract::Extension, - axum::extract::Extension(authenticated): axum::extract::Extension, - payload: Result, JsonRejection>, -) -> Result, Response> { - let payload = parse_json_payload(&request_context, payload)?.0; - let target = build_visual_novel_audio_target(payload, AudioAssetSlot::SoundEffect)?; - publish_generated_audio_asset( - &state, - authenticated.claims().user_id(), - task_id, - AudioAssetSlot::SoundEffect, - target, - ) - .await - .map(|payload| { - json_success_body( - Some(&request_context), - contract::VisualNovelGeneratedAudioAssetResponse { - kind: contract::VisualNovelAudioGenerationKind::SoundEffect, - task_id: payload.task_id, - provider: payload.provider, - status: payload.status, - asset_object_id: payload.asset_object_id, - asset_kind: payload.asset_kind, - audio_src: payload.audio_src, - }, - ) - }) - .map_err(|error| error.into_response_with_context(Some(&request_context))) -} - -pub async fn publish_background_music_asset( - State(_state): State, - Path(_task_id): Path, - axum::extract::Extension(request_context): axum::extract::Extension, - axum::extract::Extension(_authenticated): axum::extract::Extension, - payload: Result, JsonRejection>, -) -> Result, Response> { - let payload = parse_json_payload(&request_context, payload)?.0; - Err(creation_audio_generation_disabled_error_for_target(payload) - .into_response_with_context(Some(&request_context))) -} - -pub async fn publish_sound_effect_asset( - State(state): State, - Path(task_id): Path, - axum::extract::Extension(request_context): axum::extract::Extension, - axum::extract::Extension(authenticated): axum::extract::Extension, - payload: Result, JsonRejection>, -) -> Result, Response> { - let payload = parse_json_payload(&request_context, payload)?.0; - let target = build_creation_audio_target(payload, AudioAssetSlot::SoundEffect) - .map_err(|error| error.into_response_with_context(Some(&request_context)))?; - publish_generated_audio_asset( - &state, - authenticated.claims().user_id(), - task_id, - AudioAssetSlot::SoundEffect, - target, - ) - .await - .map(|payload| json_success_body(Some(&request_context), payload)) - .map_err(|error| error.into_response_with_context(Some(&request_context))) -} diff --git a/server-rs/crates/api-server/src/vector_engine_audio_generation/publish.rs b/server-rs/crates/api-server/src/vector_engine_audio_generation/publish.rs index 5b50e846c..bcd1d7974 100644 --- a/server-rs/crates/api-server/src/vector_engine_audio_generation/publish.rs +++ b/server-rs/crates/api-server/src/vector_engine_audio_generation/publish.rs @@ -11,10 +11,7 @@ use super::{ errors::{map_platform_audio_error, vector_engine_bad_gateway}, persist::persist_generated_audio_asset, settings::require_vector_engine_audio_settings, - types::{ - AudioAssetBindingTarget, AudioAssetSlot, CREATION_BACKGROUND_MUSIC_POINTS_COST, - CREATION_SOUND_EFFECT_POINTS_COST, - }, + types::{AudioAssetBindingTarget, AudioAssetSlot, CREATION_BACKGROUND_MUSIC_POINTS_COST}, }; #[cfg(any())] @@ -208,6 +205,5 @@ pub(super) fn resolve_creation_audio_points_cost( } match slot { AudioAssetSlot::BackgroundMusic => CREATION_BACKGROUND_MUSIC_POINTS_COST, - AudioAssetSlot::SoundEffect => CREATION_SOUND_EFFECT_POINTS_COST, } } diff --git a/server-rs/crates/api-server/src/vector_engine_audio_generation/tasks.rs b/server-rs/crates/api-server/src/vector_engine_audio_generation/tasks.rs deleted file mode 100644 index 8a17b5466..000000000 --- a/server-rs/crates/api-server/src/vector_engine_audio_generation/tasks.rs +++ /dev/null @@ -1,38 +0,0 @@ -use platform_audio::SoundEffectTaskRequest; -use shared_contracts::creation_audio; - -use crate::{http_error::AppError, state::AppState}; - -use super::{ - errors::map_platform_audio_error, generation::normalize_creation_sound_effect_duration, - settings::require_vector_engine_audio_settings, -}; - -pub(super) async fn create_sound_effect_task_response( - state: &AppState, - prompt: String, - duration: Option, - seed: Option, -) -> Result { - let settings = require_vector_engine_audio_settings(state)?; - let http_client = platform_audio::build_vector_engine_audio_http_client(&settings) - .map_err(map_platform_audio_error)?; - let task = platform_audio::submit_sound_effect_task( - &http_client, - &settings, - SoundEffectTaskRequest { - prompt, - duration: normalize_creation_sound_effect_duration(duration)?, - seed, - }, - ) - .await - .map_err(map_platform_audio_error)?; - - Ok(creation_audio::AudioGenerationTaskResponse { - kind: creation_audio::CreationAudioGenerationKind::SoundEffect, - task_id: task.task_id, - provider: task.provider, - status: task.status, - }) -} diff --git a/server-rs/crates/api-server/src/vector_engine_audio_generation/tests.rs b/server-rs/crates/api-server/src/vector_engine_audio_generation/tests.rs deleted file mode 100644 index 397e9b373..000000000 --- a/server-rs/crates/api-server/src/vector_engine_audio_generation/tests.rs +++ /dev/null @@ -1,212 +0,0 @@ -use axum::http::StatusCode; -use platform_oss::LegacyAssetPrefix; -use shared_contracts::{assets, creation_audio}; - -use super::{ - generation::{ - normalize_creation_sound_effect_duration, normalize_editor_background_music_request, - normalize_editor_sound_effect_request, - }, - publish::resolve_creation_audio_points_cost, - targets::{build_creation_audio_target, creation_audio_generation_disabled_error_for_target}, - types::{AudioAssetBindingTarget, AudioAssetSlot}, -}; - -#[test] -fn creation_audio_billing_uses_lower_cost_for_background_music() { - let target = AudioAssetBindingTarget { - entity_kind: "puzzle_work".to_string(), - entity_id: "puzzle-profile-1".to_string(), - slot: "background_music".to_string(), - asset_kind: "puzzle_background_music".to_string(), - profile_id: Some("puzzle-profile-1".to_string()), - storage_prefix: LegacyAssetPrefix::PuzzleAssets, - storage_scope: "puzzle_work".to_string(), - billing_points_cost: None, - }; - - assert_eq!( - resolve_creation_audio_points_cost(AudioAssetSlot::BackgroundMusic, &target), - 5 - ); - assert_eq!( - resolve_creation_audio_points_cost(AudioAssetSlot::SoundEffect, &target), - 10 - ); -} - -#[test] -fn editor_audio_billing_uses_model_price_from_generation_request() { - let target = AudioAssetBindingTarget { - entity_kind: "editor_audio".to_string(), - entity_id: "task-editor-audio".to_string(), - slot: "background_music".to_string(), - asset_kind: "editor_background_music".to_string(), - profile_id: None, - storage_prefix: LegacyAssetPrefix::CharacterDrafts, - storage_scope: "editor_audio".to_string(), - billing_points_cost: Some(12), - }; - - assert_eq!( - resolve_creation_audio_points_cost(AudioAssetSlot::BackgroundMusic, &target), - 12 - ); -} - -#[test] -fn disabled_creation_audio_targets_return_gone_including_wooden_fish_sound_effects() { - let payload = creation_audio::PublishGeneratedAudioAssetRequest { - entity_kind: "puzzle_work".to_string(), - entity_id: "puzzle-profile-1".to_string(), - slot: "background_music".to_string(), - asset_kind: "puzzle_background_music".to_string(), - profile_id: Some("puzzle-profile-1".to_string()), - storage_prefix: Some(creation_audio::CreationAudioStoragePrefix::PuzzleAssets), - }; - let error = creation_audio_generation_disabled_error_for_target(payload); - assert_eq!(error.status_code(), StatusCode::GONE); - - let payload = creation_audio::PublishGeneratedAudioAssetRequest { - entity_kind: "wooden_fish_work".to_string(), - entity_id: "wooden-fish-profile-1".to_string(), - slot: "hit_sound".to_string(), - asset_kind: "wooden_fish_hit_sound".to_string(), - profile_id: Some("wooden-fish-profile-1".to_string()), - storage_prefix: Some(creation_audio::CreationAudioStoragePrefix::WoodenFishAssets), - }; - let error = build_creation_audio_target(payload, AudioAssetSlot::SoundEffect) - .expect_err("wooden fish hit sound target should be disabled"); - assert_eq!(error.status_code(), StatusCode::GONE); -} - -#[test] -fn editor_sound_effect_request_normalizes_prompt_duration_and_resolves_price() { - let normalized = - normalize_editor_sound_effect_request(assets::EditorSoundEffectGenerateRequest { - prompt: " 金币掉落叮当声 ".to_string(), - model: None, - duration: 7, - project_id: None, - canvas_completion: None, - generation_inputs: None, - asset_folder_id: None, - asset_label: None, - }) - .expect("editor sound effect request should normalize"); - - assert_eq!(normalized.prompt, "金币掉落叮当声"); - assert_eq!(normalized.model, platform_audio::VIDU_AUDIO_MODEL); - assert_eq!(normalized.duration, 7); - assert_eq!(normalized.price_mud_points, 5); -} - -#[test] -fn editor_sound_effect_request_accepts_only_vidu_audio_model() { - let normalized = - normalize_editor_sound_effect_request(assets::EditorSoundEffectGenerateRequest { - prompt: "金币掉落叮当声".to_string(), - model: Some(" audio1.0 ".to_string()), - duration: 5, - project_id: None, - canvas_completion: None, - generation_inputs: None, - asset_folder_id: None, - asset_label: None, - }) - .expect("Vidu audio model should be accepted"); - - assert_eq!(normalized.model, platform_audio::VIDU_AUDIO_MODEL); - - let error = normalize_editor_sound_effect_request(assets::EditorSoundEffectGenerateRequest { - prompt: "金币掉落叮当声".to_string(), - model: Some(platform_audio::SUNO_DEFAULT_MODEL.to_string()), - duration: 5, - project_id: None, - canvas_completion: None, - generation_inputs: None, - asset_folder_id: None, - asset_label: None, - }) - .expect_err("Suno text-to-sound should be disabled for editor sound effects"); - - assert!(error.to_string().contains("Vidu")); -} - -#[test] -fn editor_sound_effect_request_rejects_duration_outside_vidu_range() { - for duration in [1, 11] { - let error = - normalize_editor_sound_effect_request(assets::EditorSoundEffectGenerateRequest { - prompt: "按钮点击".to_string(), - model: None, - duration, - project_id: None, - canvas_completion: None, - generation_inputs: None, - asset_folder_id: None, - asset_label: None, - }) - .expect_err("duration outside 2-10 seconds should fail"); - - assert!(error.to_string().contains("2-10")); - } -} - -#[test] -fn creation_sound_effect_duration_rejects_outside_vidu_range() { - assert_eq!( - normalize_creation_sound_effect_duration(None).expect("default duration should pass"), - platform_audio::DEFAULT_SOUND_EFFECT_DURATION_SECONDS - ); - assert_eq!( - normalize_creation_sound_effect_duration(Some(2)).expect("2 seconds should pass"), - 2 - ); - assert_eq!( - normalize_creation_sound_effect_duration(Some(10)).expect("10 seconds should pass"), - 10 - ); - - for duration in [Some(1), Some(11)] { - let error = normalize_creation_sound_effect_duration(duration) - .expect_err("duration outside Vidu 2-10 seconds should fail"); - assert!(error.to_string().contains("2-10")); - } -} - -#[test] -fn editor_background_music_request_forces_instrumental_and_resolves_price() { - let normalized = - normalize_editor_background_music_request(assets::EditorBackgroundMusicGenerateRequest { - gpt_description_prompt: " 森林冒险背景音乐 ".to_string(), - make_instrumental: false, - project_id: None, - canvas_completion: None, - generation_inputs: None, - asset_folder_id: None, - asset_label: None, - }) - .expect("editor background music request should normalize"); - - assert_eq!(normalized.gpt_description_prompt, "森林冒险背景音乐"); - assert!(normalized.make_instrumental); - assert_eq!(normalized.price_mud_points, 12); -} - -#[test] -fn editor_background_music_request_rejects_prompt_over_documented_limit() { - let error = - normalize_editor_background_music_request(assets::EditorBackgroundMusicGenerateRequest { - gpt_description_prompt: "乐".repeat(201), - make_instrumental: true, - project_id: None, - canvas_completion: None, - generation_inputs: None, - asset_folder_id: None, - asset_label: None, - }) - .expect_err("Suno gpt_description_prompt should follow Apifox 200 char limit"); - - assert!(error.to_string().contains("gpt_description_prompt")); -} diff --git a/server-rs/crates/api-server/src/vector_engine_audio_generation/types.rs b/server-rs/crates/api-server/src/vector_engine_audio_generation/types.rs index 515962028..7af8eedbc 100644 --- a/server-rs/crates/api-server/src/vector_engine_audio_generation/types.rs +++ b/server-rs/crates/api-server/src/vector_engine_audio_generation/types.rs @@ -14,7 +14,6 @@ pub(super) const MUSIC_SLOT: &str = "music"; #[cfg(any())] pub(super) const AMBIENT_SOUND_SLOT: &str = "ambient_sound"; pub(super) const CREATION_BACKGROUND_MUSIC_POINTS_COST: u64 = 5; -pub(super) const CREATION_SOUND_EFFECT_POINTS_COST: u64 = 10; #[derive(Clone, Debug)] pub(super) struct AudioAssetBindingTarget { @@ -31,14 +30,12 @@ pub(super) struct AudioAssetBindingTarget { #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub(super) enum AudioAssetSlot { BackgroundMusic, - SoundEffect, } impl AudioAssetSlot { pub(super) fn task_kind(self) -> AudioTaskKind { match self { Self::BackgroundMusic => AudioTaskKind::BackgroundMusic, - Self::SoundEffect => AudioTaskKind::SoundEffect, } } @@ -65,7 +62,6 @@ impl AudioAssetSlot { pub(super) fn creation_contract_kind(self) -> creation_audio::CreationAudioGenerationKind { match self { Self::BackgroundMusic => creation_audio::CreationAudioGenerationKind::BackgroundMusic, - Self::SoundEffect => creation_audio::CreationAudioGenerationKind::SoundEffect, } } } diff --git a/server-rs/crates/platform-audio/src/client.rs b/server-rs/crates/platform-audio/src/client.rs index df8205746..21fce0f3e 100644 --- a/server-rs/crates/platform-audio/src/client.rs +++ b/server-rs/crates/platform-audio/src/client.rs @@ -9,10 +9,8 @@ use crate::response::{ }; use crate::{ AudioError, AudioTaskKind, AudioTaskResponse, BackgroundMusicTaskRequest, - EditorBackgroundMusicTaskRequest, EditorSoundEffectTaskRequest, SoundEffectTaskRequest, - VectorEngineAudioSettings, build_background_music_task_body, - build_editor_background_music_task_body, build_editor_sound_effect_task_body, - build_sound_effect_task_body, + EditorBackgroundMusicTaskRequest, VectorEngineAudioSettings, build_background_music_task_body, + build_editor_background_music_task_body, }; pub fn build_vector_engine_audio_http_client( @@ -56,32 +54,6 @@ pub async fn submit_background_music_task( }) } -pub async fn submit_sound_effect_task( - http_client: &reqwest::Client, - settings: &VectorEngineAudioSettings, - request: SoundEffectTaskRequest, -) -> Result { - let body = build_sound_effect_task_body(request)?; - let response = post_vector_engine_json( - http_client, - settings, - AudioTaskKind::SoundEffect.submit_path(), - body, - "提交 Vidu 音效任务失败", - ) - .await?; - let task_id = extract_submit_task_id(&response) - .ok_or_else(|| AudioError::missing_audio("提交 Vidu 音效任务失败：上游未返回任务 ID"))?; - let status = find_first_string_by_key(&response, "state").unwrap_or_else(|| "created".into()); - - Ok(AudioTaskResponse { - kind: AudioTaskKind::SoundEffect, - task_id, - provider: AudioTaskKind::SoundEffect.provider().to_string(), - status, - }) -} - pub async fn submit_editor_background_music_task( http_client: &reqwest::Client, settings: &VectorEngineAudioSettings, @@ -108,32 +80,6 @@ pub async fn submit_editor_background_music_task( }) } -pub async fn submit_editor_sound_effect_task( - http_client: &reqwest::Client, - settings: &VectorEngineAudioSettings, - request: EditorSoundEffectTaskRequest, -) -> Result { - let body = build_editor_sound_effect_task_body(request)?; - let response = post_vector_engine_json( - http_client, - settings, - AudioTaskKind::SoundEffect.submit_path(), - body, - "提交编辑器音效任务失败", - ) - .await?; - let task_id = extract_submit_task_id(&response) - .ok_or_else(|| AudioError::missing_audio("提交编辑器音效任务失败：上游未返回任务 ID"))?; - let status = find_first_string_by_key(&response, "state").unwrap_or_else(|| "created".into()); - - Ok(AudioTaskResponse { - kind: AudioTaskKind::SoundEffect, - task_id, - provider: AudioTaskKind::SoundEffect.provider().to_string(), - status, - }) -} - async fn fetch_audio_task_payload( http_client: &reqwest::Client, settings: &VectorEngineAudioSettings, @@ -146,7 +92,6 @@ async fn fetch_audio_task_payload( &kind.fetch_path(task_id), match kind { AudioTaskKind::BackgroundMusic => "查询 Suno 背景音乐任务失败", - AudioTaskKind::SoundEffect => "查询 Vidu 音效任务失败", AudioTaskKind::SunoSoundEffect => "查询 Suno 音效任务失败", }, ) diff --git a/server-rs/crates/platform-audio/src/lib.rs b/server-rs/crates/platform-audio/src/lib.rs index 08a1beac5..5af8d9fbc 100644 --- a/server-rs/crates/platform-audio/src/lib.rs +++ b/server-rs/crates/platform-audio/src/lib.rs @@ -18,7 +18,6 @@ pub use background_music_prompt::{ pub use client::{ build_vector_engine_audio_http_client, resolve_audio_task_download_urls, submit_background_music_task, submit_editor_background_music_task, - submit_editor_sound_effect_task, submit_sound_effect_task, }; pub use download::{audio_mime_to_extension, download_generated_audio, normalize_audio_mime_type}; pub use elevenlabs::{ @@ -36,8 +35,7 @@ pub use persist::{ }; pub use request::{ build_background_music_task_body, build_editor_background_music_task_body, - build_editor_sound_effect_task_body, build_sound_effect_task_body, normalize_limited_text, - normalize_limited_text_allow_empty, normalize_optional_text, + normalize_limited_text, normalize_limited_text_allow_empty, normalize_optional_text, }; pub use response::{ extract_audio_urls, is_failed_task_status, is_pending_task_status, normalize_task_status, @@ -52,9 +50,8 @@ pub use sound_effect_prompt::{ pub use types::{ AudioTaskKind, AudioTaskResponse, BACKGROUND_MUSIC_PROMPT_SIMPLIFICATION_MAX_CHARS, BackgroundMusicTaskRequest, DEFAULT_SOUND_EFFECT_DURATION_SECONDS, DownloadedAudio, - EditorBackgroundMusicTaskRequest, EditorSoundEffectTaskRequest, MAX_GENERATED_AUDIO_BYTES, - SUNO_DEFAULT_MODEL, SUNO_GPT_DESCRIPTION_PROMPT_MAX_CHARS, SUNO_PROMPT_MAX_CHARS, - SUNO_TAGS_MAX_CHARS, SUNO_TITLE_MAX_CHARS, SoundEffectTaskRequest, VECTOR_ENGINE_PROVIDER, - VECTOR_ENGINE_SUNO_PROVIDER, VECTOR_ENGINE_VIDU_PROVIDER, VIDU_AUDIO_MODEL, - VIDU_PROMPT_MAX_CHARS, VectorEngineAudioSettings, + EditorBackgroundMusicTaskRequest, MAX_GENERATED_AUDIO_BYTES, SUNO_DEFAULT_MODEL, + SUNO_GPT_DESCRIPTION_PROMPT_MAX_CHARS, SUNO_PROMPT_MAX_CHARS, SUNO_TAGS_MAX_CHARS, + SUNO_TITLE_MAX_CHARS, VECTOR_ENGINE_PROVIDER, VECTOR_ENGINE_SUNO_PROVIDER, + VectorEngineAudioSettings, }; diff --git a/server-rs/crates/platform-audio/src/persist.rs b/server-rs/crates/platform-audio/src/persist.rs index 79e3a3474..9de275520 100644 --- a/server-rs/crates/platform-audio/src/persist.rs +++ b/server-rs/crates/platform-audio/src/persist.rs @@ -163,12 +163,5 @@ mod tests { file_stem: "background-music".to_string(), } ); - assert_eq!( - GeneratedAudioPersistSource::from_task_kind(AudioTaskKind::SoundEffect), - GeneratedAudioPersistSource { - provider: crate::VECTOR_ENGINE_VIDU_PROVIDER.to_string(), - file_stem: "sound-effect".to_string(), - } - ); } } diff --git a/server-rs/crates/platform-audio/src/request.rs b/server-rs/crates/platform-audio/src/request.rs index 272aac385..802062cdf 100644 --- a/server-rs/crates/platform-audio/src/request.rs +++ b/server-rs/crates/platform-audio/src/request.rs @@ -1,9 +1,8 @@ use serde_json::{Map, Value, json}; use crate::{ - AudioError, BackgroundMusicTaskRequest, EditorBackgroundMusicTaskRequest, - EditorSoundEffectTaskRequest, SUNO_DEFAULT_MODEL, SUNO_PROMPT_MAX_CHARS, SUNO_TAGS_MAX_CHARS, - SUNO_TITLE_MAX_CHARS, SoundEffectTaskRequest, VIDU_AUDIO_MODEL, VIDU_PROMPT_MAX_CHARS, + AudioError, BackgroundMusicTaskRequest, EditorBackgroundMusicTaskRequest, SUNO_DEFAULT_MODEL, + SUNO_PROMPT_MAX_CHARS, SUNO_TAGS_MAX_CHARS, SUNO_TITLE_MAX_CHARS, }; pub fn build_background_music_task_body( @@ -36,28 +35,6 @@ pub fn build_background_music_task_body( Ok(Value::Object(body)) } -pub fn build_sound_effect_task_body(request: SoundEffectTaskRequest) -> Result { - let prompt = normalize_limited_text(&request.prompt, "prompt", VIDU_PROMPT_MAX_CHARS)?; - if !(2..=10).contains(&request.duration) { - return Err(AudioError::invalid_request("duration 必须在 2-10 秒之间")); - } - let mut body = Map::from_iter([ - ( - "model".to_string(), - Value::String(VIDU_AUDIO_MODEL.to_string()), - ), - ("prompt".to_string(), Value::String(prompt.clone())), - // 中文注释：VectorEngine Apifox 当前仍写 prompt，但线上 Vidu 网关曾返回 - // missing field sound；同时发送 sound 作为同义字段，兼容网关实际反序列化。 - ("sound".to_string(), Value::String(prompt)), - ("duration".to_string(), json!(request.duration)), - ]); - if let Some(seed) = request.seed { - body.insert("seed".to_string(), json!(seed)); - } - Ok(Value::Object(body)) -} - pub fn build_editor_background_music_task_body( request: EditorBackgroundMusicTaskRequest, ) -> Result { @@ -72,33 +49,6 @@ pub fn build_editor_background_music_task_body( })) } -pub fn build_editor_sound_effect_task_body( - request: EditorSoundEffectTaskRequest, -) -> Result { - let prompt = normalize_limited_text(&request.prompt, "prompt", VIDU_PROMPT_MAX_CHARS)?; - if !(2..=10).contains(&request.duration) { - return Err(AudioError::invalid_request("duration 必须在 2-10 秒之间")); - } - let model = normalize_optional_text(request.model.as_deref()) - .unwrap_or_else(|| VIDU_AUDIO_MODEL.to_string()); - if model != VIDU_AUDIO_MODEL { - return Err(AudioError::invalid_request( - "编辑器音效暂只支持 Vidu audio1.0 模型", - )); - } - let mut body = Map::from_iter([ - ("model".to_string(), Value::String(model)), - ("prompt".to_string(), Value::String(prompt.clone())), - // 中文注释：同上，编辑器音效也必须带 sound，避免上游按 sound 字段解析时报缺字段。 - ("sound".to_string(), Value::String(prompt)), - ("duration".to_string(), json!(request.duration)), - ]); - if let Some(seed) = request.seed { - body.insert("seed".to_string(), json!(seed)); - } - Ok(Value::Object(body)) -} - pub fn normalize_limited_text( value: &str, field: &'static str, diff --git a/server-rs/crates/platform-audio/src/types.rs b/server-rs/crates/platform-audio/src/types.rs index 9a7befe54..65b647d9b 100644 --- a/server-rs/crates/platform-audio/src/types.rs +++ b/server-rs/crates/platform-audio/src/types.rs @@ -1,7 +1,6 @@ #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub enum AudioTaskKind { BackgroundMusic, - SoundEffect, SunoSoundEffect, } @@ -9,7 +8,6 @@ impl AudioTaskKind { pub fn provider(self) -> &'static str { match self { Self::BackgroundMusic => VECTOR_ENGINE_SUNO_PROVIDER, - Self::SoundEffect => VECTOR_ENGINE_VIDU_PROVIDER, Self::SunoSoundEffect => VECTOR_ENGINE_SUNO_PROVIDER, } } @@ -17,7 +15,6 @@ impl AudioTaskKind { pub fn submit_path(self) -> &'static str { match self { Self::BackgroundMusic => "/suno/submit/music", - Self::SoundEffect => "/ent/v2/text2audio", Self::SunoSoundEffect => "/suno/submit/music", } } @@ -25,9 +22,6 @@ impl AudioTaskKind { pub fn fetch_path(self, task_id: &str) -> String { match self { Self::BackgroundMusic => format!("/suno/fetch/{}", urlencoding::encode(task_id)), - Self::SoundEffect => { - format!("/ent/v2/tasks/{}/creations", urlencoding::encode(task_id)) - } Self::SunoSoundEffect => format!("/suno/fetch/{}", urlencoding::encode(task_id)), } } @@ -35,7 +29,6 @@ impl AudioTaskKind { pub fn file_stem(self) -> &'static str { match self { Self::BackgroundMusic => "background-music", - Self::SoundEffect => "sound-effect", Self::SunoSoundEffect => "sound-effect", } } @@ -50,13 +43,6 @@ pub struct BackgroundMusicTaskRequest { pub instrumental: bool, } -#[derive(Clone, Debug)] -pub struct SoundEffectTaskRequest { - pub prompt: String, - pub duration: u8, - pub seed: Option, -} - #[derive(Clone, Debug)] pub struct EditorBackgroundMusicTaskRequest { pub gpt_description_prompt: String, @@ -64,14 +50,6 @@ pub struct EditorBackgroundMusicTaskRequest { pub model: Option, } -#[derive(Clone, Debug)] -pub struct EditorSoundEffectTaskRequest { - pub prompt: String, - pub duration: u8, - pub seed: Option, - pub model: Option, -} - #[derive(Clone, Debug)] pub struct AudioTaskResponse { pub kind: AudioTaskKind, @@ -96,15 +74,12 @@ pub struct DownloadedAudio { pub const VECTOR_ENGINE_PROVIDER: &str = "vector-engine"; pub const VECTOR_ENGINE_SUNO_PROVIDER: &str = "vector-engine-suno"; -pub const VECTOR_ENGINE_VIDU_PROVIDER: &str = "vector-engine-vidu"; pub const SUNO_DEFAULT_MODEL: &str = "chirp-v5"; -pub const VIDU_AUDIO_MODEL: &str = "audio1.0"; pub const SUNO_PROMPT_MAX_CHARS: usize = 5_000; pub const SUNO_GPT_DESCRIPTION_PROMPT_MAX_CHARS: usize = 200; pub const BACKGROUND_MUSIC_PROMPT_SIMPLIFICATION_MAX_CHARS: usize = SUNO_GPT_DESCRIPTION_PROMPT_MAX_CHARS * 10; pub const SUNO_TITLE_MAX_CHARS: usize = 80; pub const SUNO_TAGS_MAX_CHARS: usize = 160; -pub const VIDU_PROMPT_MAX_CHARS: usize = 1_500; pub const DEFAULT_SOUND_EFFECT_DURATION_SECONDS: u8 = 5; pub const MAX_GENERATED_AUDIO_BYTES: usize = 40 * 1024 * 1024; diff --git a/server-rs/crates/platform-audio/tests/vector_engine_audio.rs b/server-rs/crates/platform-audio/tests/vector_engine_audio.rs index d966359b9..edf5b5054 100644 --- a/server-rs/crates/platform-audio/tests/vector_engine_audio.rs +++ b/server-rs/crates/platform-audio/tests/vector_engine_audio.rs @@ -1,12 +1,10 @@ use platform_audio::{ AudioTaskKind, BACKGROUND_MUSIC_PROMPT_SIMPLIFICATION_MAX_CHARS, BackgroundMusicTaskRequest, - EditorBackgroundMusicTaskRequest, EditorSoundEffectTaskRequest, SUNO_DEFAULT_MODEL, - SUNO_GPT_DESCRIPTION_PROMPT_MAX_CHARS, VIDU_AUDIO_MODEL, VIDU_PROMPT_MAX_CHARS, + EditorBackgroundMusicTaskRequest, SUNO_DEFAULT_MODEL, SUNO_GPT_DESCRIPTION_PROMPT_MAX_CHARS, audio_mime_to_extension, background_music_prompt_char_count, background_music_prompt_effective_char_count, build_background_music_task_body, - build_editor_background_music_task_body, build_editor_sound_effect_task_body, - build_sound_effect_task_body, canonicalize_background_music_prompt, extract_audio_urls, - is_failed_task_status, is_pending_task_status, normalize_audio_mime_type, + build_editor_background_music_task_body, canonicalize_background_music_prompt, + extract_audio_urls, is_failed_task_status, is_pending_task_status, normalize_audio_mime_type, normalize_task_status, validate_background_music_completion_prompt, validate_background_music_generation_prompt, }; @@ -271,19 +269,6 @@ fn background_music_request_body_uses_default_model_and_optional_instrumental_fl ); } -#[test] -fn sound_effect_request_rejects_overlong_prompt() { - let prompt = "声".repeat(VIDU_PROMPT_MAX_CHARS + 1); - let error = build_sound_effect_task_body(platform_audio::SoundEffectTaskRequest { - prompt, - duration: 5, - seed: None, - }) - .expect_err("long prompt should fail"); - - assert!(error.message().contains("prompt 超过")); -} - #[test] fn editor_background_music_request_body_uses_gpt_description_prompt_and_instrumental() { let fixture = background_music_prompt_canonicalization_fixture(); @@ -357,85 +342,3 @@ fn editor_background_music_request_body_rejects_unicode_whitespace_only_prompt() assert!(error.message().contains("至少需要 1 个有效字符")); } - -#[test] -fn vidu_sound_effect_request_body_uses_text2audio_contract() { - let body = build_sound_effect_task_body(platform_audio::SoundEffectTaskRequest { - prompt: " 金币掉落叮当声 ".to_string(), - duration: 5, - seed: None, - }) - .expect("Vidu sound effect body should be valid"); - - assert_eq!( - AudioTaskKind::SoundEffect.submit_path(), - "/ent/v2/text2audio" - ); - assert_eq!(AudioTaskKind::SoundEffect.provider(), "vector-engine-vidu"); - assert_eq!(body["model"], VIDU_AUDIO_MODEL); - assert_eq!(body["prompt"], "金币掉落叮当声"); - assert_eq!(body["sound"], "金币掉落叮当声"); - assert_eq!(body["duration"], 5); - assert!(body.get("mv").is_none()); - assert!(body.get("task").is_none()); - assert!(body.get("metadata_params").is_none()); -} - -#[test] -fn vidu_sound_effect_request_body_rejects_duration_outside_vidu_range_and_keeps_seed() { - let body = build_sound_effect_task_body(platform_audio::SoundEffectTaskRequest { - prompt: "按钮确认短促音".to_string(), - duration: 2, - seed: Some(42), - }) - .expect("Vidu 2 second duration should be accepted"); - assert_eq!(body["duration"], 2); - assert_eq!(body["seed"], 42); - - for duration in [1, 11] { - let error = build_sound_effect_task_body(platform_audio::SoundEffectTaskRequest { - prompt: "循环环境音".to_string(), - duration, - seed: None, - }) - .expect_err("duration outside Vidu 2-10 seconds should fail"); - assert!(error.message().contains("duration")); - } -} - -#[test] -fn editor_sound_effect_request_body_uses_vidu_text2audio_contract() { - let body = build_editor_sound_effect_task_body(EditorSoundEffectTaskRequest { - prompt: " 金币掉落叮当声 ".to_string(), - duration: 7, - seed: Some(42), - model: Some(VIDU_AUDIO_MODEL.to_string()), - }) - .expect("editor sound effect should use Vidu body"); - - assert_eq!(body["model"], VIDU_AUDIO_MODEL); - assert_eq!(body["prompt"], "金币掉落叮当声"); - assert_eq!(body["sound"], "金币掉落叮当声"); - assert_eq!(body["duration"], 7); - assert_eq!(body["seed"], 42); - assert!(body.get("mv").is_none()); - assert!(body.get("task").is_none()); - assert!(body.get("metadata_params").is_none()); - assert!(body.get("type").is_none()); - assert!(body.get("tempo").is_none()); -} - -#[test] -fn editor_sound_effect_request_body_rejects_duration_outside_vidu_range() { - for duration in [1, 11] { - let error = build_editor_sound_effect_task_body(EditorSoundEffectTaskRequest { - prompt: "按钮确认短促音".to_string(), - duration, - seed: None, - model: None, - }) - .expect_err("duration outside Vidu 2-10 seconds should fail"); - - assert!(error.message().contains("duration")); - } -} diff --git a/src/services/apiClient.test.ts b/src/services/apiClient.test.ts index f4149b26e..b04406338 100644 --- a/src/services/apiClient.test.ts +++ b/src/services/apiClient.test.ts @@ -1069,12 +1069,12 @@ describe('apiClient', () => { code: 'UPSTREAM_ERROR', message: '上游暂不可用', details: { - provider: 'vector-engine', + provider: 'tiantoken', message: - '创建拼图 VectorEngine 图片编辑任务失败：error sending request for url (https://api.vectorengine.ai/v1/images/edits)', + '创建拼图 Tiantoken 图片编辑任务失败：error sending request for url (https://api.tiantoken.com/v1/images/edits)', reason: - '无法连接 VectorEngine 图片编辑接口，请检查服务器网络、DNS、防火墙或代理配置', - endpoint: 'https://api.vectorengine.ai/v1/images/edits', + '无法连接 Tiantoken 图片编辑接口，请检查服务器网络、DNS、防火墙或代理配置', + endpoint: 'https://api.tiantoken.com/v1/images/edits', }, }, meta: {}, @@ -1095,11 +1095,11 @@ describe('apiClient', () => { ), ).rejects.toMatchObject({ message: - '无法连接 VectorEngine 图片编辑接口，请检查服务器网络、DNS、防火墙或代理配置', + '无法连接 Tiantoken 图片编辑接口，请检查服务器网络、DNS、防火墙或代理配置', status: 502, code: 'UPSTREAM_ERROR', details: { - provider: 'vector-engine', + provider: 'tiantoken', }, }); }); @@ -1116,8 +1116,8 @@ describe('apiClient', () => { code: 'SERVICE_UNAVAILABLE', message: '服务暂不可用', details: { - provider: 'vector-engine', - reason: 'VECTOR_ENGINE_API_KEY 未配置', + provider: 'tiantoken', + reason: 'TIANTOKEN_API_KEY 未配置', }, }, meta: {}, @@ -1137,11 +1137,11 @@ describe('apiClient', () => { '执行抓大鹅共创操作失败', ), ).rejects.toMatchObject({ - message: 'VECTOR_ENGINE_API_KEY 未配置', + message: 'TIANTOKEN_API_KEY 未配置', status: 503, code: 'SERVICE_UNAVAILABLE', details: { - provider: 'vector-engine', + provider: 'tiantoken', }, }); }); From dd24690b02a70e6df16a620a4f4e7bdd0eb82bbd Mon Sep 17 00:00:00 2001 From: kdletters <61648117+kdletters@users.noreply.github.com> Date: Tue, 15 Sep 2026 20:06:36 +0800 Subject: [PATCH 4/5] =?UTF-8?q?=E6=96=B0=E5=A2=9E=E5=9B=BE=E9=9B=86?= =?UTF-8?q?=E8=BF=9E=E9=80=9A=E5=9F=9F=E4=B8=8E=E5=8F=AF=E9=85=8D=E7=BD=AE?= =?UTF-8?q?=E7=BD=91=E6=A0=BC=E5=88=87=E5=88=86?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 增加 connected-components 与 grid 切分模式 支持 gridX/gridY 并同步 API、MCP、Skill、AGC 客户端 移除固定 2x2 图集切分契约与文档 --- .../genarrative-external-editor-api/SKILL.md | 1 + .../references/api-operations.md | 4 +- .../references/capability-routing.md | 4 +- .../scripts/genarrative_external_api.py | 2 + .../agc-skills/taonier-art-assets/SKILL.md | 6 + .../references/platform-art-contract.md | 1 + .../src-tauri/src/agent/direct_codex_audit.rs | 1 + .../src-tauri/src/agent/direct_runtime.rs | 3 + .../src-tauri/src/agent/direct_tool_bridge.rs | 44 ++++ .../src-tauri/src/agent/direct_tools_mcp.rs | 26 +++ .../src/agent/generation/canvas_generation.rs | 67 ++++-- .../src/agent/runtime_tools/media.rs | 41 ++++ .../src-tauri/src/commands.rs | 3 + .../src-tauri/src/tests/mod.rs | 4 +- .../src-tauri/src/tests/project.rs | 6 + .../genarrative-external-v1.openapi.json | 47 ++++- ...辑器】画板图标素材生成入口设计-2026-06-15.md | 1 + .../api-server/src/editor_agent/tool.rs | 4 +- .../crates/api-server/src/editor_project.rs | 42 ++-- .../api-server/src/editor_project_icon.rs | 193 +++++++++++++++--- .../api-server/src/external_editor_api.rs | 8 + .../src/external_generation_worker.rs | 16 +- .../crates/api-server/src/external_mcp.rs | 2 +- .../crates/api-server/src/prompt/icon_spec.rs | 8 +- .../src/generated_asset_sheets/mod.rs | 2 +- .../src/generated_asset_sheets/sheet.rs | 31 +-- .../image-editor/editorProjectClient.test.ts | 5 +- .../image-editor/editorProjectClient.ts | 9 + 28 files changed, 475 insertions(+), 106 deletions(-) diff --git a/.codex/skills/genarrative-external-editor-api/SKILL.md b/.codex/skills/genarrative-external-editor-api/SKILL.md index e6a9f55e7..e4bbafbc2 100644 --- a/.codex/skills/genarrative-external-editor-api/SKILL.md +++ b/.codex/skills/genarrative-external-editor-api/SKILL.md @@ -32,6 +32,7 @@ Prefer `scripts/genarrative_external_api.py` for runnable REST calls. It uses on - Use stable references such as `objectKey`, project resource ID, or asset ID where each operation permits them. Image edit/redraw is stricter: `sourceReferenceId` accepts only a registered project resource ID or asset ID; upload confirmation alone is not enough. Use `/assets/read-url` only for temporary preview/download access. - Preserve both warning channels after completion. A general `warning` can coexist with `sliceWarning`; do not discard either. - Do not invent missing derivatives. A source-preserved warning means the main source remains usable but requested post-processing failed. A slice warning means the complete transparent sheet is usable but individual slices are absent. +- Icon spritesheet generation accepts `sliceMode="connected-components"` (default alpha-connectivity detection) or `sliceMode="grid"`. Grid mode requires `gridX` and `gridY` (1-32); use `sliceCount` only to constrain connected-component output. - For successful `style="pixelArt"`, treat completed-result and nested resource/asset dimensions as the final logical-grid PNG dimensions. They may differ from `size`, `imageSize`, the provider image, and `canvasCompletion.placeholder`; do not rescale or reject the artifact to match those inputs. - Keep generated artifacts in the canvas and asset library together. Character animation accepts `assetFolderId` and `assetLabel`; its completed result directly returns the final `assetKind="character-animation"` resource and asset with formal sequence fields. Do not create a duplicate first-frame record. diff --git a/.codex/skills/genarrative-external-editor-api/references/api-operations.md b/.codex/skills/genarrative-external-editor-api/references/api-operations.md index 909174e47..a744d8589 100644 --- a/.codex/skills/genarrative-external-editor-api/references/api-operations.md +++ b/.codex/skills/genarrative-external-editor-api/references/api-operations.md @@ -52,7 +52,7 @@ Every generation row requires a stable `Idempotency-Key` header and returns HTTP | Image generation | `/api/external/v1/editor/images/generations` | `prompt` | `kind`, `style`, `model`, `aspectRatio`, `imageSize`, `size`, `referenceImageSrcs`, `projectId`, `assetFolderId`, `assetLabel`, `canvasCompletion`, `generationInputs` | | Image edit/redraw | `/api/external/v1/editor/images/edits` | `prompt`, `sourceReferenceId` | `referenceImageSrcs`, `model`, `size`, `projectId`, `assetFolderId`, `assetLabel`, `targetLayerId`, `canvasCompletion` | | Background removal | `/api/external/v1/editor/images/background-removals` | `sourceImageSrc` | `projectId`, `sourceResourceId`, `targetLayerId`, static-image `assetKind`, `assetFolderId`, `assetLabel`, `canvasCompletion`, `generationInputs` | -| Icon spritesheet | `/api/external/v1/editor/icon-spritesheets/generations` | `referenceId`, `iconDescriptions` | `sliceLayout`, `style`, `referenceImageSrcs`, `screenColor`, `model`, `aspectRatio`, `imageSize`, `projectId`, `assetFolderId`, `assetLabel`, `canvasCompletion` | +| Icon spritesheet | `/api/external/v1/editor/icon-spritesheets/generations` | `referenceId`, `iconDescriptions` | `sliceMode`, `gridX`, `gridY`, `sliceCount`, `style`, `referenceImageSrcs`, `screenColor`, `model`, `aspectRatio`, `imageSize`, `projectId`, `assetFolderId`, `assetLabel`, `canvasCompletion` | | UI asset extraction | `/api/external/v1/editor/ui-designs/assets/extractions` | `sourceImageSrc`, `aspectRatio`, `imageSize` | `screenColor`, `model`, `referenceImageSrcs`, `projectId`, `assetFolderId`, `spritesheetLabel`, `canvasCompletion` | | Character animation | `/api/external/v1/editor/character-animations/generations` | `sourceLayerId`, `sourceImageSrc`, `sourceWidth`, `sourceHeight`, `promptText`, `resolution`, `ratio`, `frameCount`, `durationSeconds`, `model` | `projectId`, `sourceResourceId`, `assetFolderId`, `assetLabel`, `canvasCompletion` | | Video generation | `/api/external/v1/editor/videos/generations` | `prompt`, `model`, `aspectRatio`, `durationSeconds`, `resolution`, `mode`, `sound` | `referenceImageSrcs`, `referenceVideoSrcs`, `referenceAudioSrcs`, `webSearchEnabled`, `projectId`, `assetFolderId`, `assetLabel`, `canvasCompletion` | @@ -94,7 +94,7 @@ For image edit/redraw, confirming an upload is not sufficient: create a project The icon-spritesheet primary `referenceId` is intentionally stricter than ordinary image references: it accepts only a current-owner project resource ID or asset ID whose authoritative `assetKind` is `icon-spec`. It does not accept an `objectKey`, URL, Data URL, or Blob URL. -`sliceLayout: "grid-2x2"` is an opt-in contract for four fixed game-runtime assets. The provider prompt and server persistence both preserve the ordered slots left-top, right-top, left-bottom, right-bottom. Omit it to retain the default connected-component slicing behaviour for ordinary free-form icon sheets. +`sliceMode` controls atlas splitting. Use `"connected-components"` (default) to detect independent opaque regions by alpha connectivity, or `"grid"` with positive `gridX` and `gridY` values (maximum 32 each). `sliceCount` optionally constrains the connected-component result. ## Common Values diff --git a/.codex/skills/genarrative-external-editor-api/references/capability-routing.md b/.codex/skills/genarrative-external-editor-api/references/capability-routing.md index a5b4fe886..af0ee338a 100644 --- a/.codex/skills/genarrative-external-editor-api/references/capability-routing.md +++ b/.codex/skills/genarrative-external-editor-api/references/capability-routing.md @@ -79,9 +79,9 @@ Keep the existing autonomous-build task graph. Do not add a parallel task system 1. `art-director` generates `assets/art-spec.png` with image generation, `kind: "spec"`, then registers it as `assetKind: "icon-spec"`. This image is the authoritative visual spec; `generationInputs.artSpec` is supporting structured context. 2. `design-foundation` generates `assets/ui-prototype.png` with `kind: "ui-design"`, using the registered art-spec resource ID in `referenceImageSrcs`. -3. `art-asset-plan` generates transparent `assets/art-spritesheet.png` through icon spritesheet generation, using the same registered art-spec resource ID as `referenceId` plus concrete `iconDescriptions`. For the four-category game contract it must also send `sliceLayout: "grid-2x2"`; this is an explicit fixed-slot contract, not a client-side guessed crop. +3. `art-asset-plan` generates transparent `assets/art-spritesheet.png` through icon spritesheet generation, using the same registered art-spec resource ID as `referenceId` plus concrete `iconDescriptions`. For a fixed four-category game contract it may send `sliceMode: "grid"`; for free-form assets use `sliceMode: "connected-components"` (the default). -For a playable Canvas game, do not stop at generation. Make `code-prototype` depend on `art-asset-plan` and consume the persisted `iconImageSrcs` slices for core players, blocks or targets, scene obstacles, and feedback. For the four-category game-chat contract, require response `sliceLayout: "grid-2x2"` and exactly four slices before registering the local runtime sheet; both fewer and extra components fail closed. Treat `art-spec.png` as reference-only. A full-sheet ``, CSS background, path-only mention, guessed equal-grid crop, or code-drawn replacement for core entities is not runtime asset use. If slicing produces `sliceWarning`, keep the complete transparent sheet as a valid editor artifact, but fail the playable game asset gate until real slice files or verified atlas coordinates exist; never invent coordinates or replace the icon-spritesheet route with ordinary image generation. +For a playable Canvas game, do not stop at generation. Make `code-prototype` depend on `art-asset-plan` and consume the persisted `iconImageSrcs` slices for core players, blocks or targets, scene obstacles, and feedback. When using the fixed four-category contract, require response `sliceMode: "grid"` and exactly four slices before registering the local runtime sheet; both fewer and extra components fail closed. Treat `art-spec.png` as reference-only. A full-sheet ``, CSS background, path-only mention, guessed equal-grid crop, or code-drawn replacement for core entities is not runtime asset use. If slicing produces `sliceWarning`, keep the complete transparent sheet as a valid editor artifact, but fail the playable game asset gate until real slice files or verified atlas coordinates exist; never invent coordinates or replace the icon-spritesheet route with ordinary image generation. Never use `assets/ui-prototype.png` as the spritesheet visual-spec reference. UI extraction is outside this canonical DAG. diff --git a/.codex/skills/genarrative-external-editor-api/scripts/genarrative_external_api.py b/.codex/skills/genarrative-external-editor-api/scripts/genarrative_external_api.py index cc5a4a4b5..c7c0ab33b 100644 --- a/.codex/skills/genarrative-external-editor-api/scripts/genarrative_external_api.py +++ b/.codex/skills/genarrative-external-editor-api/scripts/genarrative_external_api.py @@ -881,12 +881,14 @@ def _self_test() -> None: ["蛇头向上", "蛇身直线", "转角", "尾部", "四类食物"], canvasSession=session, assetLabel="贪吃蛇透明图集", + sliceMode="connected-components", referenceId="must-not-override-explicit-reference", iconDescriptions=["不得覆盖显式图标描述"], ) assert calls[0]["path"] == "/api/external/v1/editor/icon-spritesheets/generations" assert calls[0]["body"]["referenceId"] == "editor-resource-spec" assert calls[0]["body"]["screenColor"] == "auto" + assert calls[0]["body"]["sliceMode"] == "connected-components" assert calls[0]["body"]["iconDescriptions"][0] == "蛇头向上" assert calls[1]["path"] == "/api/external/v1/generations/task-operation-demo" print("self-test ok") diff --git a/apps/ai-game-creator-shell/src-tauri/resources/agc-skills/taonier-art-assets/SKILL.md b/apps/ai-game-creator-shell/src-tauri/resources/agc-skills/taonier-art-assets/SKILL.md index 8d63beb92..d652b4436 100644 --- a/apps/ai-game-creator-shell/src-tauri/resources/agc-skills/taonier-art-assets/SKILL.md +++ b/apps/ai-game-creator-shell/src-tauri/resources/agc-skills/taonier-art-assets/SKILL.md @@ -19,6 +19,12 @@ image, UI design image, or publication material; use `agc_edit_image` for an edit of an existing registered image; use `taonier_prepare_game_art` only for the complete game-art package and its canonical slices. +When `agc_generate_image` is used with `kind="art-spritesheet"`, pass +`sliceMode="connected-components"` (the default alpha-connectivity splitter) +or `sliceMode="grid"` with `gridX` and `gridY` (1-32 each). The selected mode is carried +through the client request and returned result; do not infer it from the number +of slices. + ## Authorization boundary `agc_tools` is an AGC client-owned bridge to the AGC backend. In the normal client build it uses the current client login session and account routes; the user and model never need to provide, configure, paste, create, or rotate an API Key, Token, Cookie, URL, or `.env` value. If the tool returns `401` or `403`, report only that the AGC client login or permission state is unavailable, stop the operation, and do not ask the user for credentials or expose an internal URL. diff --git a/apps/ai-game-creator-shell/src-tauri/resources/agc-skills/taonier-art-assets/references/platform-art-contract.md b/apps/ai-game-creator-shell/src-tauri/resources/agc-skills/taonier-art-assets/references/platform-art-contract.md index 9a04e1256..bf0b74481 100644 --- a/apps/ai-game-creator-shell/src-tauri/resources/agc-skills/taonier-art-assets/references/platform-art-contract.md +++ b/apps/ai-game-creator-shell/src-tauri/resources/agc-skills/taonier-art-assets/references/platform-art-contract.md @@ -15,6 +15,7 @@ - On timeout or uncertain delivery, reuse the recorded operation; never create a replacement request. - `postprocess-failed-source-preserved` means the complete provider source remains usable, but the requested transparent derivative is absent. - `sliceWarning` means the complete transparent sheet remains usable, but individual slices are absent. +- For direct `agc_generate_image` spritesheet requests, `sliceMode="connected-components"` selects alpha-connectivity detection and `sliceMode="grid"` uses the caller-provided `gridX` and `gridY` (1-32 each). The client preserves the selected mode and grid dimensions in the request identity and result metadata. - General and slice warnings can coexist. The tool returns them separately through `warnings` and `sliceWarnings`; callers must preserve every entry and must not downgrade a slice warning into a successful independent-asset claim. - `assetPaths` contains the complete package paths. `slicePaths` contains only slices that the client downloaded, validated, and registered with their platform source identities. - `resources` contains only safe registered identity fields: local asset/path/kind/media type, Canvas project/resource/asset/task IDs, and reference resource IDs. It never exposes prompts, models, provider routes, absolute paths, URLs, tokens, cookies, or API keys. diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/direct_codex_audit.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/direct_codex_audit.rs index 43ab7c7ba..6f8557a32 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/agent/direct_codex_audit.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/agent/direct_codex_audit.rs @@ -549,6 +549,7 @@ fn extract_mcp_arguments(root: &Path, tool: &str, arguments: &Value) -> Value { } "agc_generate_image" => { copy_string(object, "kind", &mut out); + copy_string(object, "sliceMode", &mut out); copy_string(object, "aspectRatio", &mut out); copy_string(object, "imageSize", &mut out); copy_string(object, "assetName", &mut out); diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/direct_runtime.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/direct_runtime.rs index 2e4cdad61..71cf43b44 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/agent/direct_runtime.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/agent/direct_runtime.rs @@ -2783,6 +2783,9 @@ async fn generate_direct_taonier_art_asset_at( asset_label: asset_label.to_string(), replace_existing: root.join(output_path).is_file(), slice_count: None, + slice_mode: None, + grid_x: None, + grid_y: None, }; let runtime_context = direct_taonier_art_generation_runtime_context(root, output_path, asset_kind)?; diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/direct_tool_bridge.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/direct_tool_bridge.rs index e185c8cac..6c94bfe6a 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/agent/direct_tool_bridge.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/agent/direct_tool_bridge.rs @@ -2104,6 +2104,9 @@ async fn bridge_generate_image(state: &DirectToolBridgeState, arguments: &Value) "imageSize", "assetName", "outputPath", + "sliceMode", + "gridX", + "gridY", ], )?; enforce_project_permission_policy(&state.root, "canvas.asset_generate")?; @@ -2145,6 +2148,44 @@ async fn bridge_generate_image(state: &DirectToolBridgeState, arguments: &Value) .transpose()? .unwrap_or_else(|| "AI 生成图片".to_string()); let output_path = bridge_optional_bounded_string(arguments, "outputPath", 512)?; + let slice_mode = arguments + .get("sliceMode") + .map(|_| bridge_bounded_string(arguments, "sliceMode", 32)) + .transpose()?; + if slice_mode + .as_deref() + .is_some_and(|mode| !matches!(mode, "connected-components" | "grid")) + { + return Err("工具参数 sliceMode 只允许 connected-components 或 grid".to_string()); + } + let grid_x = arguments + .get("gridX") + .map(|_| { + arguments + .get("gridX") + .and_then(Value::as_u64) + .map(|value| value as u32) + .ok_or_else(|| "工具参数 gridX 必须是整数".to_string()) + }) + .transpose()?; + let grid_y = arguments + .get("gridY") + .map(|_| { + arguments + .get("gridY") + .and_then(Value::as_u64) + .map(|value| value as u32) + .ok_or_else(|| "工具参数 gridY 必须是整数".to_string()) + }) + .transpose()?; + if slice_mode.as_deref() == Some("grid") && (grid_x.is_none() || grid_y.is_none()) { + return Err("grid 模式必须同时提供 gridX 与 gridY".to_string()); + } + if grid_x.is_some_and(|value| !(1..=32).contains(&value)) + || grid_y.is_some_and(|value| !(1..=32).contains(&value)) + { + return Err("工具参数 gridX/gridY 必须在 1 到 32 之间".to_string()); + } let options = PlatformArtAssetGenerationOptions { output_path, aspect_ratio, @@ -2153,6 +2194,9 @@ async fn bridge_generate_image(state: &DirectToolBridgeState, arguments: &Value) asset_label: asset_name.clone(), replace_existing: false, slice_count: None, + slice_mode, + grid_x, + grid_y, }; let _generation_guard = state.image_generation_gate.lock().await; let generated = with_direct_editor_api_credentials( diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/direct_tools_mcp.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/direct_tools_mcp.rs index 643abd3db..294b44c25 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/agent/direct_tools_mcp.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/agent/direct_tools_mcp.rs @@ -244,6 +244,24 @@ fn direct_tools_mcp_specs_for(controlled_web_search: bool, _cocos_editor_availab "type": "string", "maxLength": 512, "description": "可选项目相对输出路径，必须位于 assets/ 且不能覆盖已有文件" + }, + "sliceMode": { + "type": "string", + "enum": ["connected-components", "grid"], + "default": "connected-components", + "description": "仅 kind=art-spritesheet 生效：connected-components 按透明像素连通域切分，grid 按 gridX×gridY 网格切分" + }, + "gridX": { + "type": "integer", + "minimum": 1, + "maximum": 32, + "description": "grid 模式横向网格数量" + }, + "gridY": { + "type": "integer", + "minimum": 1, + "maximum": 32, + "description": "grid 模式纵向网格数量" } }, "required": ["prompt"], @@ -1014,6 +1032,9 @@ async fn call_agc_generate_image(arguments: &Value) -> Value { "imageSize", "assetName", "outputPath", + "sliceMode", + "gridX", + "gridY", ], ) { return mcp_tool_result(error, Vec::new(), true); @@ -1041,6 +1062,7 @@ async fn call_agc_generate_image(arguments: &Value) -> Value { ("imageSize", 4), ("assetName", DIRECT_TOOLS_MCP_MAX_RESOURCE_NAME_CHARS), ("outputPath", 512), + ("sliceMode", 32), ] { if arguments.get(field).is_some() { if let Err(error) = bounded_tool_string(arguments, field, max_chars) { @@ -2226,6 +2248,10 @@ mod tests { assert!(image_tool["description"] .as_str() .is_some_and(|description| description.contains("不是本工具的限制"))); + assert_eq!( + image_tool["inputSchema"]["properties"]["sliceMode"]["enum"], + json!(["connected-components", "grid"]) + ); let edit_tool = specs["tools"] .as_array() .expect("tool array") diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/generation/canvas_generation.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/generation/canvas_generation.rs index 2bd540024..f9bbd95a8 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/agent/generation/canvas_generation.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/agent/generation/canvas_generation.rs @@ -413,6 +413,9 @@ pub(crate) struct PlatformArtAssetGenerationOptions { pub(crate) asset_label: String, pub(crate) replace_existing: bool, pub(crate) slice_count: Option, + pub(crate) slice_mode: Option, + pub(crate) grid_x: Option, + pub(crate) grid_y: Option, } impl Default for PlatformArtAssetGenerationOptions { @@ -425,6 +428,9 @@ impl Default for PlatformArtAssetGenerationOptions { asset_label: "AI 游戏首版美术素材".to_string(), replace_existing: false, slice_count: None, + slice_mode: None, + grid_x: None, + grid_y: None, } } } @@ -1574,7 +1580,7 @@ pub(in crate::agent) struct PreparedPlatformArtAssetGeneration { warning: Option, slice_warning: Option, slices: Vec, - spritesheet_slice_layout: Option, + spritesheet_slice_mode: Option, generation_route: String, generation_kind: String, reference_resource_ids: Vec, @@ -2213,11 +2219,8 @@ pub(crate) async fn generate_platform_art_asset_with_required_slices_at( /// 而任何输入不同（提示词、输出路径、比例、尺寸、类型、标签、严格切片）都是另一个 /// 动作，必须各自独立成槽，才能在同一项目里同时在途。 /// -/// **字段集合与取值方式必须与升级前逐字节一致**：升级前遗留账本里持久化的 -/// `actionFingerprint` 就是这个材料的历史哈希，改动材料会让旧账本无法按精确动作被 -/// 识别与迁移（见 `adopt_legacy_standalone_platform_art_generation_runtime_state_at`）。 -/// 已知边界：`slice_count` 不进身份（与升级前一致），仅切片数不同的两条图集请求仍落到 -/// 同一槽，第二条在账本请求正文校验处失败关闭，不会二次 POST。 +/// 升级前遗留账本仍由旧材料函数定位；新请求把显式切分模式纳入身份，避免同一图集 +/// 请求在网格与连通域之间误复用。`slice_count` 继续保持历史兼容语义，不进身份。 #[derive(Serialize)] #[serde(rename_all = "camelCase")] struct StandalonePlatformArtGenerationFingerprintMaterial<'a> { @@ -2229,6 +2232,9 @@ struct StandalonePlatformArtGenerationFingerprintMaterial<'a> { asset_label: &'a str, replace_existing: bool, require_slices: bool, + slice_mode: Option<&'a str>, + grid_x: Option, + grid_y: Option, } /// 把输出路径收口成稳定的旧槽材料：空路径与未指定路径都落到 `(automatic-output)`， @@ -2265,6 +2271,9 @@ fn standalone_platform_art_generation_runtime_context( asset_label: &options.asset_label, replace_existing: options.replace_existing, require_slices, + slice_mode: options.slice_mode.as_deref(), + grid_x: options.grid_x, + grid_y: options.grid_y, }) .map_err(|error| format!("序列化 standalone 图片生成动作身份失败：{error}"))?; let action_fingerprint = format!("{:x}", Sha256::digest(&identity_bytes)); @@ -2811,6 +2820,9 @@ pub(in crate::agent) async fn request_platform_art_asset_with_runtime_options_at "referenceId": reference_id, "iconDescriptions": canonical_art_spritesheet_icon_descriptions(&generation_prompt), "sliceCount": options.slice_count, + "sliceMode": options.slice_mode, + "gridX": options.grid_x, + "gridY": options.grid_y, "screenColor": "auto", "aspectRatio": options.aspect_ratio, "imageSize": options.image_size, @@ -3106,8 +3118,8 @@ pub(in crate::agent) async fn request_platform_art_asset_with_runtime_options_at Vec::new() }; let warning = platform_art_generation_warning(generated); - let spritesheet_slice_layout = if is_canonical_art_spritesheet { - json_string_field(generated, "sliceLayout") + let spritesheet_slice_mode = if is_canonical_art_spritesheet { + json_string_field(generated, "sliceMode") } else { None }; @@ -3168,7 +3180,7 @@ pub(in crate::agent) async fn request_platform_art_asset_with_runtime_options_at warning, slice_warning, slices, - spritesheet_slice_layout, + spritesheet_slice_mode, generation_route, generation_kind, reference_resource_ids, @@ -6508,7 +6520,7 @@ fn validate_strict_platform_art_spritesheet_contract( task_id: Option<&str>, generation_route: &str, generation_kind: &str, - spritesheet_slice_layout: Option<&str>, + spritesheet_slice_mode: Option<&str>, reference_resource_ids: &[String], has_transparent_pixels: bool, has_visible_pixels: bool, @@ -6545,7 +6557,7 @@ fn validate_strict_platform_art_spritesheet_contract( { return Err("strict spritesheet 图集生成 route/kind 与严格图集合同不一致".to_string()); } - let _requested_slice_layout = spritesheet_slice_layout; + let _requested_slice_mode = spritesheet_slice_mode; if reference_resource_ids.len() != 1 || reference_resource_ids[0].trim().is_empty() || reference_resource_ids[0].trim() == resource_id @@ -7307,7 +7319,7 @@ fn commit_prepared_platform_art_asset_with_before_replace_hook( warning, mut slice_warning, slices, - spritesheet_slice_layout, + spritesheet_slice_mode, generation_route, generation_kind, reference_resource_ids, @@ -7326,7 +7338,7 @@ fn commit_prepared_platform_art_asset_with_before_replace_hook( task_id.as_deref(), &generation_route, &generation_kind, - spritesheet_slice_layout.as_deref(), + spritesheet_slice_mode.as_deref(), &reference_resource_ids, spritesheet_has_transparent_pixels, spritesheet_has_visible_pixels, @@ -7901,8 +7913,8 @@ mod canvas_generation_tests { let body = serde_json::json!({ "error": { "code": "invalid-request", - "field": "sliceLayout", - "message": "只支持 grid-2x2；operationId=private-operation-id；api_key=private-key", + "field": "sliceMode", + "message": "只支持 grid；operationId=private-operation-id；api_key=private-key", }, "details": { "path": "C:\\Users\\private\\secret.json", @@ -7911,8 +7923,8 @@ mod canvas_generation_tests { .to_string(); let summary = summarize_external_http_error_body(&body).expect("summary"); assert!(summary.contains("code=invalid-request"), "{summary}"); - assert!(summary.contains("field=sliceLayout"), "{summary}"); - assert!(summary.contains("只支持 grid-2x2"), "{summary}"); + assert!(summary.contains("field=sliceMode"), "{summary}"); + assert!(summary.contains("只支持 grid"), "{summary}"); assert!(!summary.contains("private-operation-id"), "{summary}"); assert!(!summary.contains("private-key"), "{summary}"); assert!(!summary.contains("C:\\Users\\private"), "{summary}"); @@ -8312,6 +8324,9 @@ mod canvas_generation_tests { asset_label: "手工背景".to_string(), replace_existing: true, slice_count: None, + slice_mode: None, + grid_x: None, + grid_y: None, }; let ordinary = standalone_platform_art_generation_runtime_context("完整生成提示词", &options, false) @@ -9826,7 +9841,7 @@ mod canvas_generation_tests { Some("spritesheet-task"), "/api/external/v1/editor/icon-spritesheets/generations", "icon-spritesheet", - Some("grid-2x2"), + Some("grid"), &["art-spec-resource".to_string()], true, true, @@ -10325,6 +10340,9 @@ mod canvas_generation_tests { asset_label: "整包规范图".to_string(), replace_existing: false, slice_count: None, + slice_mode: None, + grid_x: None, + grid_y: None, }; let prompt = "生成同一套整包美术"; let generation_prompt = build_platform_art_asset_prompt(prompt, &[], &options); @@ -11220,6 +11238,9 @@ mod canvas_generation_tests { asset_label: "整包背景图".to_string(), replace_existing: false, slice_count: None, + slice_mode: None, + grid_x: None, + grid_y: None, }; let prompt = "保持同一个生成提示词"; let generation_prompt = build_platform_art_asset_prompt(prompt, &[], &options); @@ -11681,6 +11702,9 @@ mod canvas_generation_tests { asset_label: "游戏统一视觉规范图".to_string(), replace_existing: false, slice_count: None, + slice_mode: None, + grid_x: None, + grid_y: None, }; let prompt = "恢复已受理视觉规范图"; let generation_prompt = build_platform_art_asset_prompt(prompt, &[], &options); @@ -12287,6 +12311,9 @@ mod canvas_generation_tests { asset_label: "游戏首版核心美术素材".to_string(), replace_existing: true, slice_count: None, + slice_mode: None, + grid_x: None, + grid_y: None, } } @@ -12317,7 +12344,7 @@ mod canvas_generation_tests { warning: None, slice_warning: None, slices: Vec::new(), - spritesheet_slice_layout: Some("grid-2x2".to_string()), + spritesheet_slice_mode: Some("grid".to_string()), generation_route: "/api/external/v1/editor/icon-spritesheets/generations".to_string(), generation_kind: "icon-spritesheet".to_string(), reference_resource_ids: vec!["art-spec-resource".to_string()], @@ -12636,7 +12663,7 @@ mod canvas_generation_tests { warning: None, slice_warning: None, slices, - spritesheet_slice_layout: Some("grid-2x2".to_string()), + spritesheet_slice_mode: Some("grid".to_string()), generation_route: "/api/external/v1/editor/icon-spritesheets/generations".to_string(), generation_kind: "icon-spritesheet".to_string(), reference_resource_ids: vec!["art-spec-resource".to_string()], diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_tools/media.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_tools/media.rs index 132c71c59..6f7aa3441 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_tools/media.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_tools/media.rs @@ -555,6 +555,17 @@ pub(in crate::agent) async fn observe_agent_runtime_platform_art_asset_generatio .or_else(|| input.get("slice_count")) .and_then(serde_json::Value::as_u64) .map(|value| value as usize); + let slice_mode = agent_runtime_tool_input_text(input, &["sliceMode", "slice_mode"]); + let grid_x = input + .get("gridX") + .or_else(|| input.get("grid_x")) + .and_then(serde_json::Value::as_u64) + .map(|value| value as u32); + let grid_y = input + .get("gridY") + .or_else(|| input.get("grid_y")) + .and_then(serde_json::Value::as_u64) + .map(|value| value as u32); let mut requested_options = PlatformArtAssetGenerationOptions { output_path: (!output_path.trim().is_empty()).then_some(output_path), aspect_ratio, @@ -563,6 +574,9 @@ pub(in crate::agent) async fn observe_agent_runtime_platform_art_asset_generatio asset_label, replace_existing, slice_count, + slice_mode: (!slice_mode.trim().is_empty()).then_some(slice_mode.clone()), + grid_x, + grid_y, }; if let Some(pending) = pending_action { match recover_persisted_visual_generation_options( @@ -609,6 +623,11 @@ pub(in crate::agent) async fn observe_agent_runtime_platform_art_asset_generatio }, replace_existing, slice_count, + slice_mode: requested_options + .slice_mode + .or_else(|| (!slice_mode.trim().is_empty()).then_some(slice_mode)), + grid_x, + grid_y, } }; options.replace_existing = replace_existing; @@ -654,6 +673,28 @@ pub(in crate::agent) async fn observe_agent_runtime_platform_art_asset_generatio detail: None, }; } + if options + .slice_mode + .as_deref() + .is_some_and(|slice_mode| !matches!(slice_mode, "connected-components" | "grid")) + { + return AgentRuntimeToolObservation { + tool: "canvas.asset_generate".to_string(), + status: "failed".to_string(), + summary: "图片生成 sliceMode 不受支持".to_string(), + detail: None, + }; + } + if options.slice_mode.as_deref() == Some("grid") + && (options.grid_x.is_none() || options.grid_y.is_none()) + { + return AgentRuntimeToolObservation { + tool: "canvas.asset_generate".to_string(), + status: "failed".to_string(), + summary: "grid 模式必须同时提供 gridX 与 gridY".to_string(), + detail: None, + }; + } if !agent_runtime_canvas_asset_kind_is_supported(&options.asset_kind) { return AgentRuntimeToolObservation { tool: "canvas.asset_generate".to_string(), diff --git a/apps/ai-game-creator-shell/src-tauri/src/commands.rs b/apps/ai-game-creator-shell/src-tauri/src/commands.rs index b3cc58f28..828048813 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/commands.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/commands.rs @@ -4594,6 +4594,9 @@ pub(crate) fn prepare_local_project_asset_generation( .unwrap_or_else(|| LOCAL_PROJECT_ASSET_DEFAULT_ASSET_NAME.to_string()), replace_existing: false, slice_count: None, + slice_mode: None, + grid_x: None, + grid_y: None, }, }) } diff --git a/apps/ai-game-creator-shell/src-tauri/src/tests/mod.rs b/apps/ai-game-creator-shell/src-tauri/src/tests/mod.rs index 28b4dcbc1..f12416e7d 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/tests/mod.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/tests/mod.rs @@ -3192,7 +3192,9 @@ fn spawn_mock_external_canvas_api_server_with_capture_and_generation_gate( "spritesheetImageSrc": "/generated/canvas/spritesheet.png", "spritesheetWidth": 2, "spritesheetHeight": 1, - "sliceLayout": "grid-2x2", + "sliceMode": "grid", + "gridX": 2, + "gridY": 2, "iconImageSrcs": icon_image_srcs, "sliceWarning": null, "prompt": "原创游戏素材图集", diff --git a/apps/ai-game-creator-shell/src-tauri/src/tests/project.rs b/apps/ai-game-creator-shell/src-tauri/src/tests/project.rs index 4fa58e0e2..2270ca448 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/tests/project.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/tests/project.rs @@ -1076,6 +1076,9 @@ async fn canonical_art_spec_and_ui_requests_use_the_shared_reference_chain() { asset_label: "游戏横屏界面原型图".to_string(), replace_existing: false, slice_count: None, + slice_mode: None, + grid_x: None, + grid_y: None, }, ) .await; @@ -5493,6 +5496,9 @@ fn ui_prototype_generation_uses_dedicated_prompt_and_art_spec() { asset_label: "游戏横屏界面原型图".to_string(), replace_existing: false, slice_count: None, + slice_mode: None, + grid_x: None, + grid_y: None, }; let prompt = build_platform_art_asset_prompt( "原创网格贪吃蛇：分数与状态 HUD、四类不同分值食物、开始、方向键/WASD、触控方向键、失败与重开", diff --git a/docs/openapi/genarrative-external-v1.openapi.json b/docs/openapi/genarrative-external-v1.openapi.json index 507747e57..0a28b1ab6 100644 --- a/docs/openapi/genarrative-external-v1.openapi.json +++ b/docs/openapi/genarrative-external-v1.openapi.json @@ -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" diff --git a/docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md b/docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md index 895286d30..ae769d8b3 100644 --- a/docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md +++ b/docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md @@ -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。 diff --git a/server-rs/crates/api-server/src/editor_agent/tool.rs b/server-rs/crates/api-server/src/editor_agent/tool.rs index 949fadf99..0805fb4d4 100644 --- a/server-rs/crates/api-server/src/editor_agent/tool.rs +++ b/server-rs/crates/api-server/src/editor_agent/tool.rs @@ -864,7 +864,9 @@ impl EditorAgentTool for GenerateIconSpritesheetTool { reference_image_srcs: Some(reference_image_srcs), icon_descriptions: args.icon_descriptions, slice_count: None, - slice_layout: None, + slice_mode: None, + grid_x: None, + grid_y: None, style: None, model: Some(args.model), screen_color: Some("auto".to_string()), diff --git a/server-rs/crates/api-server/src/editor_project.rs b/server-rs/crates/api-server/src/editor_project.rs index b6b2b1477..d740cdfea 100644 --- a/server-rs/crates/api-server/src/editor_project.rs +++ b/server-rs/crates/api-server/src/editor_project.rs @@ -93,7 +93,8 @@ use crate::{ }, editor_project_icon::{ EditorIconSpritesheetGenerationResponse, EditorIconSpritesheetIconResponse, - PersistEditorSpritesheetSlicesInput, editor_icon_spritesheet_slice_warning_from_error, + EditorIconSpritesheetSliceMode, PersistEditorSpritesheetSlicesInput, + editor_icon_spritesheet_slice_warning_from_error, editor_icon_spritesheet_warning_after_persist_error, prepare_editor_spritesheet_slices_for_generation, slice_editor_icon_spritesheet_all, }, @@ -1267,7 +1268,7 @@ fn compact_external_api_generation_result(result: Value) -> Value { | "spritesheetWidth" | "spritesheetHeight" | "iconImageSrcs" - | "sliceLayout" + | "sliceMode" | "frames" | "frameCount" | "frameWidth" @@ -8578,7 +8579,9 @@ pub(crate) async fn extract_editor_ui_design_assets_for_owner( spritesheet_width: source_width, spritesheet_height: source_height, icon_image_srcs: Vec::new(), - slice_layout: None, + slice_mode: None, + grid_x: None, + grid_y: None, slice_count: None, slice_warning: None, prompt, @@ -8645,7 +8648,9 @@ pub(crate) async fn extract_editor_ui_design_assets_for_owner( spritesheet_width: source_width, spritesheet_height: source_height, icon_image_srcs: Vec::new(), - slice_layout: None, + slice_mode: None, + grid_x: None, + grid_y: None, slice_count: None, slice_warning: None, prompt, @@ -8730,8 +8735,10 @@ pub(crate) async fn extract_editor_ui_design_assets_for_owner( let (mut icon_image_srcs, slice_items, slice_warning) = match slice_editor_icon_spritesheet_all( slice_source, request_context.external_call_deadline(), + EditorIconSpritesheetSliceMode::ConnectedComponents, None, - None, + 0, + 0, ) .await { @@ -8893,7 +8900,9 @@ pub(crate) async fn extract_editor_ui_design_assets_for_owner( spritesheet_width, spritesheet_height, icon_image_srcs, - slice_layout: None, + slice_mode: None, + grid_x: None, + grid_y: None, slice_count: None, slice_warning, prompt, @@ -19063,10 +19072,17 @@ mod tests { .checked_sub(Duration::from_millis(1)) .expect("expired deadline should be representable"); - let error = slice_editor_icon_spritesheet_all(source, Some(expired), None, None) - .await - .err() - .expect("expired CPU budget must fail before decoding"); + let error = slice_editor_icon_spritesheet_all( + source, + Some(expired), + EditorIconSpritesheetSliceMode::ConnectedComponents, + None, + 0, + 0, + ) + .await + .err() + .expect("expired CPU budget must fail before decoding"); assert_eq!(error.status_code(), StatusCode::GATEWAY_TIMEOUT); assert_eq!( @@ -19751,7 +19767,9 @@ mod tests { spritesheet_width: 512, spritesheet_height: 512, icon_image_srcs: Vec::new(), - slice_layout: None, + slice_mode: None, + grid_x: None, + grid_y: None, slice_count: None, slice_warning: Some(EditorIconSpritesheetSliceWarningResponse { code: EDITOR_ICON_SPRITESHEET_SLICE_WARNING_COMPONENTS, @@ -19984,7 +20002,6 @@ mod tests { fn atomic_job_result_keeps_only_the_target_consumer_contract() { let result = json!({ "ok": true, - "sliceLayout": "grid-2x2", "imageSrc": "/api/assets/object/generated.png", "objectKey": "generated/image.png", "width": 512, @@ -20069,7 +20086,6 @@ mod tests { ); assert_eq!(external_payload["result"]["asset"]["assetId"], "asset-1"); assert_eq!(external_payload["result"]["ok"], true); - assert_eq!(external_payload["result"]["sliceLayout"], "grid-2x2"); assert_eq!(external_payload["result"]["prompt"], "用户可见提示词"); assert_eq!( external_payload["result"]["actualPrompt"], diff --git a/server-rs/crates/api-server/src/editor_project_icon.rs b/server-rs/crates/api-server/src/editor_project_icon.rs index f7f318b86..cfecc85be 100644 --- a/server-rs/crates/api-server/src/editor_project_icon.rs +++ b/server-rs/crates/api-server/src/editor_project_icon.rs @@ -14,7 +14,7 @@ use platform_image::{ generated_asset_sheets::{ GeneratedAssetSheetConnectedIcon, GeneratedAssetSheetConnectedIconPlan, GeneratedAssetSheetError, prepare_generated_icon_spritesheet_all_by_connected_components, - prepare_generated_icon_spritesheet_grid_2x2, + prepare_generated_icon_spritesheet_grid, }, }; use platform_llm::{EDITOR_AGENT_GPT5_MODEL, LlmMessage, LlmRunRequest}; @@ -82,6 +82,7 @@ pub(crate) const EDITOR_ICON_SPRITESHEET_MEMORY_MAX_CONCURRENCY: usize = 2; pub(crate) const EDITOR_ICON_SPRITESHEET_UPLOAD_MAX_CONCURRENCY: usize = 2; pub(crate) const EDITOR_ICON_SPRITESHEET_MAX_TOTAL_CROP_PIXELS: u64 = EDITOR_ICON_SPRITESHEET_MAX_PIXELS * 4; +const EDITOR_ICON_SPRITESHEET_MAX_GRID_AXIS: u32 = 32; pub(crate) const EDITOR_ICON_SPRITESHEET_UPLOAD_CONNECT_TIMEOUT: Duration = Duration::from_secs(10); pub(crate) const EDITOR_ICON_SPRITESHEET_UPLOAD_REQUEST_TIMEOUT: Duration = Duration::from_secs(60); pub(crate) const EDITOR_ICON_SPRITESHEET_MAX_PROCESSING_DURATION: Duration = @@ -254,8 +255,13 @@ pub(crate) struct EditorIconSpritesheetGenerationRequest { /// 用户要求的切片数量；未提供时按图像中的连通素材自动识别。 #[serde(default, skip_serializing_if = "Option::is_none")] pub(crate) slice_count: Option, + /// 图集切分模式；省略时使用连通域切分。 #[serde(default, skip_serializing_if = "Option::is_none")] - pub(crate) slice_layout: Option, + pub(crate) slice_mode: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub(crate) grid_x: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub(crate) grid_y: Option, #[serde(default, skip_serializing_if = "Option::is_none")] pub(crate) style: Option, pub(crate) model: Option, @@ -270,11 +276,50 @@ pub(crate) struct EditorIconSpritesheetGenerationRequest { pub(crate) canvas_completion: Option, } -/// Deprecated compatibility layout. New callers should use `sliceCount`。 #[derive(Clone, Copy, Debug, Deserialize, Serialize, PartialEq, Eq)] -pub(crate) enum EditorIconSpritesheetSliceLayout { - #[serde(rename = "grid-2x2")] - Grid2x2, +#[serde(rename_all = "kebab-case")] +pub(crate) enum EditorIconSpritesheetSliceMode { + ConnectedComponents, + Grid, +} + +impl Default for EditorIconSpritesheetSliceMode { + fn default() -> Self { + Self::ConnectedComponents + } +} + +fn resolve_editor_icon_spritesheet_slice_mode( + slice_mode: Option, +) -> EditorIconSpritesheetSliceMode { + slice_mode.unwrap_or_default() +} + +fn resolve_editor_icon_spritesheet_grid_dimensions( + mode: EditorIconSpritesheetSliceMode, + grid_x: Option, + grid_y: Option, +) -> Result<(u32, u32), AppError> { + if mode == EditorIconSpritesheetSliceMode::ConnectedComponents { + return Ok((0, 0)); + } + let (Some(grid_x), Some(grid_y)) = (grid_x, grid_y) else { + return Err( + AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({ + "field": "gridX/gridY", + "message": "grid 模式必须同时提供 gridX 与 gridY。", + })), + ); + }; + if !(1..=EDITOR_ICON_SPRITESHEET_MAX_GRID_AXIS).contains(&grid_x) + || !(1..=EDITOR_ICON_SPRITESHEET_MAX_GRID_AXIS).contains(&grid_y) + { + return Err(AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({ + "field": "gridX/gridY", + "message": format!("gridX 与 gridY 必须在 1 到 {} 之间。", EDITOR_ICON_SPRITESHEET_MAX_GRID_AXIS), + }))); + } + Ok((grid_x, grid_y)) } #[derive(Clone, Debug, Deserialize, Serialize)] @@ -313,7 +358,11 @@ pub(crate) struct EditorIconSpritesheetGenerationResponse { pub(crate) spritesheet_height: u32, pub(crate) icon_image_srcs: Vec, #[serde(skip_serializing_if = "Option::is_none")] - pub(crate) slice_layout: Option, + pub(crate) slice_mode: Option, + #[serde(skip_serializing_if = "Option::is_none")] + pub(crate) grid_x: Option, + #[serde(skip_serializing_if = "Option::is_none")] + pub(crate) grid_y: Option, #[serde(skip_serializing_if = "Option::is_none")] pub(crate) slice_count: Option, #[serde(skip_serializing_if = "Option::is_none")] @@ -1579,6 +1628,12 @@ pub(crate) async fn generate_editor_icon_spritesheet_for_owner( .or_else(|| payload.project_id.clone()), ); let http_client = build_openai_image_http_client(&settings)?; + let requested_slice_mode = resolve_editor_icon_spritesheet_slice_mode(payload.slice_mode); + let (grid_x, grid_y) = resolve_editor_icon_spritesheet_grid_dimensions( + requested_slice_mode, + payload.grid_x, + payload.grid_y, + )?; // TODO(legacy-icon-spritesheet-billing-boundary): 该计费边界继承自 master 的历史实现； // Provider 成功后 operation 即提交，后续解码、OSS、资源与画布持久化失败时缺少可对账中间态。 // 调整前需先定义 provider_succeeded/persistence_pending 等状态、稳定幂等键和补偿语义， @@ -1618,15 +1673,18 @@ pub(crate) async fn generate_editor_icon_spritesheet_for_owner( ) .await?; let screen_color = screen_background_decision.color; - let prompt = match payload.slice_layout { - Some(EditorIconSpritesheetSliceLayout::Grid2x2) => { - crate::prompt::icon_spec::build_grid_2x2_spritesheet_prompt( + let slice_mode = requested_slice_mode; + let prompt = match slice_mode { + EditorIconSpritesheetSliceMode::Grid => { + crate::prompt::icon_spec::build_grid_spritesheet_prompt( &spritesheet_prompt, screen_color, icon_spec_genre, + grid_x, + grid_y, ) } - None => crate::prompt::icon_spec::build_spritesheet_prompt( + EditorIconSpritesheetSliceMode::ConnectedComponents => crate::prompt::icon_spec::build_spritesheet_prompt( &spritesheet_prompt, screen_color, icon_spec_genre, @@ -1786,7 +1844,11 @@ pub(crate) async fn generate_editor_icon_spritesheet_for_owner( spritesheet_width: source_width, spritesheet_height: source_height, icon_image_srcs: Vec::new(), - slice_layout: payload.slice_layout, + slice_mode: Some(requested_slice_mode), + grid_x: (requested_slice_mode == EditorIconSpritesheetSliceMode::Grid) + .then_some(grid_x), + grid_y: (requested_slice_mode == EditorIconSpritesheetSliceMode::Grid) + .then_some(grid_y), slice_count: Some(0), slice_warning: None, prompt, @@ -1868,7 +1930,11 @@ pub(crate) async fn generate_editor_icon_spritesheet_for_owner( spritesheet_width: source_width, spritesheet_height: source_height, icon_image_srcs: Vec::new(), - slice_layout: payload.slice_layout, + slice_mode: Some(requested_slice_mode), + grid_x: (requested_slice_mode == EditorIconSpritesheetSliceMode::Grid) + .then_some(grid_x), + grid_y: (requested_slice_mode == EditorIconSpritesheetSliceMode::Grid) + .then_some(grid_y), slice_count: Some(0), slice_warning: None, prompt, @@ -1966,8 +2032,10 @@ pub(crate) async fn generate_editor_icon_spritesheet_for_owner( let (mut icon_image_srcs, slice_items, slice_warning) = match slice_editor_icon_spritesheet_all( slice_source, request_context.external_call_deadline(), - payload.slice_layout, + requested_slice_mode, payload.slice_count, + grid_x, + grid_y, ) .await { @@ -2059,7 +2127,12 @@ pub(crate) async fn generate_editor_icon_spritesheet_for_owner( "spritesheetWidth": spritesheet_width, "spritesheetHeight": spritesheet_height, "iconImageSrcs": &icon_image_srcs, - "sliceLayout": payload.slice_layout, + + "sliceMode": requested_slice_mode, + "gridX": (requested_slice_mode == EditorIconSpritesheetSliceMode::Grid) + .then_some(grid_x), + "gridY": (requested_slice_mode == EditorIconSpritesheetSliceMode::Grid) + .then_some(grid_y), "sliceCount": payload.slice_count, "sliceWarning": &slice_warning, "warning": &generation_warning, @@ -2137,7 +2210,12 @@ pub(crate) async fn generate_editor_icon_spritesheet_for_owner( spritesheet_width, spritesheet_height, icon_image_srcs, - slice_layout: payload.slice_layout, + + slice_mode: Some(requested_slice_mode), + grid_x: (requested_slice_mode == EditorIconSpritesheetSliceMode::Grid) + .then_some(grid_x), + grid_y: (requested_slice_mode == EditorIconSpritesheetSliceMode::Grid) + .then_some(grid_y), slice_count: Some(slice_count), slice_warning, prompt, @@ -2332,8 +2410,10 @@ pub async fn split_editor_icon_spritesheet( source, processing_deadline, memory_admission, + EditorIconSpritesheetSliceMode::ConnectedComponents, None, - None, + 0, + 0, ) .await?; let prompt = source_resource @@ -2408,8 +2488,10 @@ pub async fn split_editor_icon_spritesheet( pub(crate) async fn slice_editor_icon_spritesheet_all( source: DownloadedImage, request_deadline: Option, - slice_layout: Option, + slice_mode: EditorIconSpritesheetSliceMode, slice_count: Option, + grid_x: u32, + grid_y: u32, ) -> Result { let processing_deadline = resolve_editor_icon_spritesheet_processing_deadline(Instant::now(), request_deadline); @@ -2419,8 +2501,10 @@ pub(crate) async fn slice_editor_icon_spritesheet_all( source, processing_deadline, memory_admission, - slice_layout, + slice_mode, slice_count, + grid_x, + grid_y, ) .await } @@ -2458,8 +2542,10 @@ async fn slice_editor_icon_spritesheet_all_with_memory_admission( source: DownloadedImage, processing_deadline: Instant, memory_admission: Arc, - slice_layout: Option, + slice_mode: EditorIconSpritesheetSliceMode, slice_count: Option, + grid_x: u32, + grid_y: u32, ) -> Result { if Instant::now() >= processing_deadline { return Err(editor_icon_spritesheet_processing_timeout_error()); @@ -2492,17 +2578,19 @@ async fn slice_editor_icon_spritesheet_all_with_memory_admission( return Err(editor_icon_spritesheet_processing_timeout_error()); } validate_editor_icon_spritesheet_source(&source)?; - match slice_layout { - Some(EditorIconSpritesheetSliceLayout::Grid2x2) => { - prepare_generated_icon_spritesheet_grid_2x2(&source) + match slice_mode { + EditorIconSpritesheetSliceMode::Grid => { + prepare_generated_icon_spritesheet_grid(&source, grid_x, grid_y) + } + EditorIconSpritesheetSliceMode::ConnectedComponents => { + prepare_generated_icon_spritesheet_all_by_connected_components( + &source, + slice_count + .unwrap_or(EDITOR_ICON_SPRITESHEET_MAX_SLICES) + .min(EDITOR_ICON_SPRITESHEET_MAX_SLICES), + EDITOR_ICON_SPRITESHEET_MAX_TOTAL_CROP_PIXELS, + ) } - None => prepare_generated_icon_spritesheet_all_by_connected_components( - &source, - slice_count - .unwrap_or(EDITOR_ICON_SPRITESHEET_MAX_SLICES) - .min(EDITOR_ICON_SPRITESHEET_MAX_SLICES), - EDITOR_ICON_SPRITESHEET_MAX_TOTAL_CROP_PIXELS, - ), } .map_err(map_editor_icon_spritesheet_platform_error) }); @@ -2909,7 +2997,7 @@ mod tests { } #[tokio::test] - async fn grid_2x2_slicing_returns_exactly_four_quadrants_with_detached_details() { + async fn grid_slicing_returns_one_slice_per_declared_cell_with_detached_details() { use image::{ImageBuffer, ImageFormat, Rgba}; let mut image: image::RgbaImage = ImageBuffer::from_pixel(128, 128, Rgba([0, 255, 0, 255])); @@ -2939,15 +3027,54 @@ mod tests { let prepared = slice_editor_icon_spritesheet_all( source, None, - Some(EditorIconSpritesheetSliceLayout::Grid2x2), + EditorIconSpritesheetSliceMode::Grid, None, + 2, + 2, ) .await - .expect("declared 2x2 sheet should slice"); + .expect("declared grid sheet should slice"); assert_eq!(prepared.plan.len(), 4); } + #[test] + fn slice_mode_defaults_to_connected_components_and_accepts_explicit_modes() { + assert_eq!( + resolve_editor_icon_spritesheet_slice_mode(None), + EditorIconSpritesheetSliceMode::ConnectedComponents + ); + assert_eq!( + resolve_editor_icon_spritesheet_grid_dimensions( + EditorIconSpritesheetSliceMode::Grid, + Some(3), + Some(2), + ) + .expect("grid dimensions should validate"), + (3, 2) + ); + let connected: EditorIconSpritesheetGenerationRequest = serde_json::from_value(json!({ + "referenceId": "spec", + "iconDescriptions": ["素材"], + "sliceMode": "connected-components" + })) + .expect("explicit connected-components mode should deserialize"); + assert_eq!( + connected.slice_mode, + Some(EditorIconSpritesheetSliceMode::ConnectedComponents) + ); + let grid: EditorIconSpritesheetGenerationRequest = serde_json::from_value(json!({ + "referenceId": "spec", + "iconDescriptions": ["素材"], + "sliceMode": "grid", + "gridX": 3, + "gridY": 2 + })) + .expect("grid mode should deserialize"); + assert_eq!(grid.grid_x, Some(3)); + assert_eq!(grid.grid_y, Some(2)); + } + #[test] fn spritesheet_genre_requires_exact_game_type_title() { assert_eq!( diff --git a/server-rs/crates/api-server/src/external_editor_api.rs b/server-rs/crates/api-server/src/external_editor_api.rs index de48a2d15..eeddb4371 100644 --- a/server-rs/crates/api-server/src/external_editor_api.rs +++ b/server-rs/crates/api-server/src/external_editor_api.rs @@ -2620,6 +2620,14 @@ mod tests { icon_spritesheet_request["properties"]["sliceCount"]["minimum"], json!(1) ); + assert_eq!( + icon_spritesheet_request["properties"]["sliceMode"]["enum"], + json!(["connected-components", "grid"]) + ); + assert_eq!( + icon_spritesheet_request["properties"]["gridX"]["maximum"], + json!(32) + ); let icon_style_schema = &parsed["components"]["schemas"]["EditorIconSpritesheetGenerationRequest"] ["properties"]["style"]; assert_eq!(icon_style_schema["anyOf"][0]["type"], "string"); diff --git a/server-rs/crates/api-server/src/external_generation_worker.rs b/server-rs/crates/api-server/src/external_generation_worker.rs index b279b5054..6c89e8fb2 100644 --- a/server-rs/crates/api-server/src/external_generation_worker.rs +++ b/server-rs/crates/api-server/src/external_generation_worker.rs @@ -1364,7 +1364,9 @@ fn compact_external_api_generation_result(result: Value) -> Value { | "spritesheetWidth" | "spritesheetHeight" | "iconImageSrcs" - | "sliceLayout" + | "sliceMode" + | "gridX" + | "gridY" | "sliceCount" | "frames" | "frameCount" @@ -2436,7 +2438,9 @@ mod tests { let mut job = external_generation_job_record_fixture(Some("lease-1")); job.dedupe_key = "external-api-generation:conversation-1:7:icon-spritesheet".to_string(); let response = json!({ - "sliceLayout": "grid-2x2", + "sliceMode": "grid", + "gridX": 2, + "gridY": 2, "iconImageSrcs": [ { "name": "素材 1", "imageSrc": "/api/assets/object/one.png" }, { "name": "素材 2", "imageSrc": "/api/assets/object/two.png" }, @@ -2449,7 +2453,7 @@ mod tests { serde_json::from_str(&editor_generation_result_payload_json(&job, &response)) .expect("worker result should be valid JSON"); - assert_eq!(payload["result"]["sliceLayout"], json!("grid-2x2")); + assert_eq!(payload["result"]["sliceMode"], json!("grid")); assert_eq!( payload["result"]["iconImageSrcs"].as_array().map(Vec::len), Some(4) @@ -2705,7 +2709,9 @@ mod tests { "spritesheetImageSrc": "/api/assets/object/core-sheet.png", "spritesheetWidth": 1024, "spritesheetHeight": 1024, - "sliceLayout": "grid-2x2", + "sliceMode": "grid", + "gridX": 2, + "gridY": 2, "spritesheetResource": { "resourceId": "sheet-resource-1", "objectKey": "users/user-1/core-sheet.png", @@ -2729,7 +2735,7 @@ mod tests { serde_json::from_str(&editor_generation_result_payload_json(&job, &response)) .expect("游戏创作客户端完成结果应持久化为合法 JSON"); - assert_eq!(payload["result"]["sliceLayout"], json!("grid-2x2")); + assert_eq!(payload["result"]["sliceMode"], json!("grid")); assert_eq!( payload["result"]["iconImageSrcs"].as_array().map(Vec::len), Some(4) diff --git a/server-rs/crates/api-server/src/external_mcp.rs b/server-rs/crates/api-server/src/external_mcp.rs index 5ee492476..6b6c469f7 100644 --- a/server-rs/crates/api-server/src/external_mcp.rs +++ b/server-rs/crates/api-server/src/external_mcp.rs @@ -54,7 +54,7 @@ const SKILL_REQUESTS_AND_OUTPUTS_URI: &str = "genarrative://external-editor/skill/references/requests-and-outputs.md"; const MAX_MCP_REST_RESPONSE_BYTES: usize = 4 * 1024 * 1024; -const MCP_INSTRUCTIONS: &str = r#"陶泥儿外部编辑器工具。先创建或复用画布项目，并创建与画布同名的素材文件夹；生成结果应同时写入画布和素材库。参考本地文件时先走上传票据和对象确认，不要把 Data URL、Blob URL 或临时签名 URL写入生成参数。所有生成工具都是异步提交：必须提供 idempotencyKey，提交后按 pollAfterMs 调用 get_external_editor_generation_job，只有 status=completed 时消费 result；查询超时不能重新提交。warning 表示主结果可用但存在降级，sliceWarning 表示完整透明图集可用但切片未完成。详细说明、OpenAPI、Skill 主入口和分主题 references 见 resources/list；需要本地文件编排或不支持 MCP 时再下载 skill.zip。"#; +const MCP_INSTRUCTIONS: &str = r#"陶泥儿外部编辑器工具。先创建或复用画布项目，并创建与画布同名的素材文件夹；生成结果应同时写入画布和素材库。参考本地文件时先走上传票据和对象确认，不要把 Data URL、Blob URL 或临时签名 URL写入生成参数。所有生成工具都是异步提交：必须提供 idempotencyKey，提交后按 pollAfterMs 调用 get_external_editor_generation_job，只有 status=completed 时消费 result；查询超时不能重新提交。图集生成可用 sliceMode=connected-components（默认连通域切分）或 grid（必须同时提供 gridX/gridY）。warning 表示主结果可用但存在降级，sliceWarning 表示完整透明图集可用但切片未完成。详细说明、OpenAPI、Skill 主入口和分主题 references 见 resources/list；需要本地文件编排或不支持 MCP 时再下载 skill.zip。"#; #[derive(Clone, Debug)] struct McpOperation { diff --git a/server-rs/crates/api-server/src/prompt/icon_spec.rs b/server-rs/crates/api-server/src/prompt/icon_spec.rs index 51469fb1b..c68cacb2e 100644 --- a/server-rs/crates/api-server/src/prompt/icon_spec.rs +++ b/server-rs/crates/api-server/src/prompt/icon_spec.rs @@ -276,13 +276,17 @@ pub(crate) fn build_spritesheet_prompt( ) } -pub(crate) fn build_grid_2x2_spritesheet_prompt( +pub(crate) fn build_grid_spritesheet_prompt( user_prompt: &ValidatedEditorIconSpritesheetPrompt, screen_color: EditorScreenBackgroundColor, genre: Option, + columns: u32, + rows: u32, ) -> String { format!( - "{}\n\n固定 2×2 游戏核心素材图集合同：画面必须严格分为左上、右上、左下、右下四个等大的独立槽位；每个槽位只放一个完整、可单独用于游戏运行时的主体。四个槽位必须按用户给出的四条素材需求顺序对应，且每格都必须有清晰可见的主体。禁止生成任何额外图标、同一主体的多个姿势、序列帧、棋盘、场景、边框、流程箭头、标签、文字、Logo、装饰小物或第五个素材；禁止主体跨格、触碰或重叠。输出须是单张图集，背景只使用统一纯色以便透明化。", + "{}\n\n固定网格游戏核心素材图集合同：画面必须严格分为 {}×{} 个等大的独立槽位；每个槽位只放一个完整、可单独用于游戏运行时的主体。素材按从左到右、从上到下顺序对应，禁止主体跨格、触碰或重叠。输出须是单张图集，背景只使用统一纯色以便透明化。", + columns, + rows, build_spritesheet_prompt(user_prompt, screen_color, genre), ) } diff --git a/server-rs/crates/platform-image/src/generated_asset_sheets/mod.rs b/server-rs/crates/platform-image/src/generated_asset_sheets/mod.rs index aeffb002d..96982edaa 100644 --- a/server-rs/crates/platform-image/src/generated_asset_sheets/mod.rs +++ b/server-rs/crates/platform-image/src/generated_asset_sheets/mod.rs @@ -21,7 +21,7 @@ pub use sheet::{ GeneratedAssetSheetSliceImage, crop_generated_asset_sheet_view_edge_matte, crop_generated_asset_sheet_view_edge_matte_with_options, prepare_generated_icon_spritesheet_all_by_connected_components, - prepare_generated_icon_spritesheet_grid_2x2, slice_generated_asset_sheet, + prepare_generated_icon_spritesheet_grid, slice_generated_asset_sheet, slice_generated_asset_sheet_two_items_per_row, slice_generated_icon_spritesheet_all_by_connected_components, }; diff --git a/server-rs/crates/platform-image/src/generated_asset_sheets/sheet.rs b/server-rs/crates/platform-image/src/generated_asset_sheets/sheet.rs index b0d7ec81b..ad75b55ce 100644 --- a/server-rs/crates/platform-image/src/generated_asset_sheets/sheet.rs +++ b/server-rs/crates/platform-image/src/generated_asset_sheets/sheet.rs @@ -254,35 +254,38 @@ pub fn prepare_generated_icon_spritesheet_all_by_connected_components( ) } -/// Prepares the four authoritative slices of a provider-generated 2×2 atlas. +/// Prepares the authoritative slices of a provider-generated rectangular grid atlas. /// /// This deliberately does not inspect connected components. A caller that /// requested the fixed layout has already constrained the provider to place /// one complete asset in every quadrant; trying to infer individual pieces /// again would turn highlights and detached effects into extra game assets. -pub fn prepare_generated_icon_spritesheet_grid_2x2( +pub fn prepare_generated_icon_spritesheet_grid( image: &crate::DownloadedImage, + columns: u32, + rows: u32, ) -> Result { let source = image::load_from_memory(image.bytes.as_slice()).map_err(|error| { GeneratedAssetSheetError::decode_image(format!("图标 spritesheet 解码失败：{error}")) })?; let source = apply_generated_asset_sheet_green_screen_alpha(source).into_rgba8(); let (width, height) = source.dimensions(); - if width < 2 || height < 2 { + if columns == 0 || rows == 0 || width < columns || height < rows { return Err(GeneratedAssetSheetError::invalid_request( - "2×2 图标 spritesheet 尺寸过小，无法切割。", + "网格图标 spritesheet 的尺寸或网格参数无效，无法切割。", )); } - let mut icons = Vec::with_capacity(4); - for index in 0..4usize { - let row = (index / 2) as u32; - let col = (index % 2) as u32; - let cell = resolve_generated_asset_sheet_cell_bounds(width, height, 2, row, col); + let cell_count = columns.saturating_mul(rows) as usize; + let mut icons = Vec::with_capacity(cell_count); + for index in 0..cell_count { + let row = (index as u32) / columns; + let col = (index as u32) % columns; + let cell = resolve_generated_asset_sheet_cell_bounds(width, height, columns, row, col); let foreground = detect_generated_asset_sheet_visible_bounds_in_cell(&source, cell) .ok_or_else(|| { GeneratedAssetSheetError::invalid_request(format!( - "2×2 图标 spritesheet 的第 {} 个格子没有可见素材。", + "网格图标 spritesheet 的第 {} 个格子没有可见素材。", index + 1 )) })?; @@ -295,7 +298,7 @@ pub fn prepare_generated_icon_spritesheet_grid_2x2( y1: foreground.y1.saturating_add(pad_y).min(cell.y1), }; icons.push(GeneratedAssetSheetConnectedIconPlanItem { - name: format!("2×2 素材 {}", index + 1), + name: format!("网格素材 {}", index + 1), crop, }); } @@ -1009,7 +1012,7 @@ mod tests { } #[test] - fn grid_2x2_plan_keeps_one_durable_slice_per_quadrant_despite_detached_details() { + fn grid_plan_keeps_one_durable_slice_per_cell_despite_detached_details() { let mut sheet: image::RgbaImage = ImageBuffer::from_pixel(128, 128, Rgba([0, 255, 0, 255])); let colors = [ [240, 80, 80, 255], @@ -1036,8 +1039,8 @@ mod tests { extension: "png".to_string(), }; - let plan = prepare_generated_icon_spritesheet_grid_2x2(&source) - .expect("declared 2x2 atlas should prepare"); + let plan = prepare_generated_icon_spritesheet_grid(&source, 2, 2) + .expect("declared grid atlas should prepare"); let icons = (0..plan.len()) .map(|index| plan.encode(index).expect("quadrant should encode")) .collect::>(); diff --git a/src/services/image-editor/editorProjectClient.test.ts b/src/services/image-editor/editorProjectClient.test.ts index eae2857aa..d846e24e3 100644 --- a/src/services/image-editor/editorProjectClient.test.ts +++ b/src/services/image-editor/editorProjectClient.test.ts @@ -1147,13 +1147,14 @@ describe('editorProjectClient', () => { referenceId: 'editor-resource-icon-spec', referenceImageSrcs: references, iconDescriptions: ['返回按钮'], + sliceMode: 'connected-components', }); expect(requestJsonMock).toHaveBeenCalledWith( '/api/editor/icon-spritesheets/generations', expect.objectContaining({ - body: expect.stringContaining( - '"model":"gemini-3.1-flash-image-preview"', + body: expect.stringMatching( + /(?=.*"model":"gemini-3\.1-flash-image-preview")(?=.*"sliceMode":"connected-components")/, ), }), '生成图标素材失败', diff --git a/src/services/image-editor/editorProjectClient.ts b/src/services/image-editor/editorProjectClient.ts index 6ad26770f..e84825190 100644 --- a/src/services/image-editor/editorProjectClient.ts +++ b/src/services/image-editor/editorProjectClient.ts @@ -380,6 +380,9 @@ export type EditorIconSpritesheetGenerationInput = { referenceId: string; referenceImageSrcs?: string[]; iconDescriptions: string[]; + sliceMode?: 'connected-components' | 'grid'; + gridX?: number; + gridY?: number; model?: string; screenColor?: string; segModel?: string; @@ -516,6 +519,9 @@ export type EditorIconSpritesheetGenerationResult = { spritesheetWidth: number; spritesheetHeight: number; iconImageSrcs: EditorIconSpritesheetIconResult[]; + sliceMode?: 'connected-components' | 'grid'; + gridX?: number; + gridY?: number; sliceWarning?: EditorIconSpritesheetSliceWarning | null; prompt: string; actualPrompt?: string | null; @@ -1311,6 +1317,9 @@ export async function generateEditorIconSpritesheet( ? { referenceImageSrcs: input.referenceImageSrcs } : {}), iconDescriptions, + ...(input.sliceMode ? { sliceMode: input.sliceMode } : {}), + ...(input.gridX !== undefined ? { gridX: input.gridX } : {}), + ...(input.gridY !== undefined ? { gridY: input.gridY } : {}), model, ...(input.screenColor ? { screenColor: input.screenColor } : {}), ...(input.segModel ? { segModel: input.segModel } : {}), From 361daf374dfa64a1c1ef21e58cf268de9199faeb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=AE=B5=E8=88=92=E5=BA=B7?= Date: Tue, 15 Sep 2026 20:21:53 +0800 Subject: [PATCH 5/5] =?UTF-8?q?=E4=BF=AE=E5=A4=8D=20AGC=20=E7=BB=9F?= =?UTF-8?q?=E4=B8=80=E9=94=99=E8=AF=AF=E8=AF=8A=E6=96=AD=E4=B8=8E=E7=B4=A0?= =?UTF-8?q?=E6=9D=90=E9=AA=8C=E6=94=B6=20(#376)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 变更内容 - 新增统一 Agent Runtime 错误事件和项目内诊断 sidecar，统一 DirectProject、Agent Runtime、app-server 与 AGC 工具桥的失败记录。 - 失败回执写回 DirectProject 对话历史，下一轮可读取上一轮失败证据；前端支持读取脱敏诊断详情。 - 区分 app-server 终态、空闲/硬超时、工具参数错误和试玩次数越界。 - 素材完成门扫描实际 npm 源码模块，并识别 manifest 中合法的自定义登记素材路径。 - 更新 AGC 技术规范、项目决策记录、里程碑和实施计划。 ## 验证 - cargo check --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --tests - 统一错误测试 6/6 通过 - DirectProject 失败诊断测试 4/4 通过 - npm 场景模块素材引用回归测试通过 - npm run --prefix apps/ai-game-creator-shell typecheck - npm run check:encoding - npm run check:doc-index - git diff --check、Rust 格式检查 真实 Provider / 安装包 smoke 尚未在本 PR 中运行。 --------- Co-authored-by: Git Hooks Test Reviewed-on: https://git.genarrative.world/git/GenarrativeAI/Genarrative/pulls/376 --- .../src-tauri/src/agent.rs | 2 + .../src-tauri/src/agent/codex_app_server.rs | 53 +++++- .../src-tauri/src/agent/direct_runtime.rs | 176 +++++++++++++++--- .../src-tauri/src/agent/direct_tool_bridge.rs | 28 ++- .../src-tauri/src/agent/direct_tools_mcp.rs | 4 +- .../src-tauri/src/agent/runtime_error.rs | 167 +++++++++++++++++ .../src-tauri/src/agent/runtime_state.rs | 20 ++ .../src-tauri/src/commands.rs | 32 ++++ .../src-tauri/src/main.rs | 1 + apps/ai-game-creator-shell/src/App.tsx | 19 +- ...计划】AGC统一错误诊断与验收反馈-2026-09-15.md | 35 ++++ ...碑】AGC统一错误诊断与验收反馈-2026-09-15.md | 39 ++++ .../shared-memory/decision-log.md | 9 + ...案】AI游戏创作智能体App实施计划-2026-06-24.md | 12 ++ 14 files changed, 561 insertions(+), 36 deletions(-) create mode 100644 apps/ai-game-creator-shell/src-tauri/src/agent/runtime_error.rs create mode 100644 docs/project-memory/plans/【实施计划】AGC统一错误诊断与验收反馈-2026-09-15.md create mode 100644 docs/project-memory/plans/【里程碑】AGC统一错误诊断与验收反馈-2026-09-15.md diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent.rs b/apps/ai-game-creator-shell/src-tauri/src/agent.rs index 17b8a6700..b9d90f269 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/agent.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/agent.rs @@ -28,6 +28,7 @@ mod prompt; mod runtime_actions; mod runtime_adapter; mod runtime_driver; +mod runtime_error; mod runtime_protocol; mod runtime_state; mod runtime_tools; @@ -56,6 +57,7 @@ pub(crate) use prompt::*; pub(crate) use runtime_actions::*; pub(crate) use runtime_adapter::*; pub(crate) use runtime_driver::*; +pub(crate) use runtime_error::*; pub(crate) use runtime_protocol::*; pub(crate) use runtime_state::*; pub(crate) use runtime_tools::*; diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/codex_app_server.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/codex_app_server.rs index 48edc498f..ea4d981a8 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/agent/codex_app_server.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/agent/codex_app_server.rs @@ -271,6 +271,51 @@ fn game_creator_codex_app_server_error_kind(kind: &str) -> platform_llm::LlmErro )) } +fn game_creator_codex_app_server_error_kind_with_machine_detail( + kind: &str, + error: &serde_json::Value, +) -> platform_llm::LlmError { + let mut fields = Vec::new(); + if let Some(object) = error.as_object() { + if let Some(code) = object.get("code").and_then(serde_json::Value::as_str) { + if !code.is_empty() + && code.len() <= 80 + && code + .bytes() + .all(|byte| byte.is_ascii_alphanumeric() || b"._-".contains(&byte)) + { + fields.push(format!("code={code}")); + } + } + let keys = object + .keys() + .filter(|key| { + matches!( + key.as_str(), + "httpConnectionFailed" + | "responseStreamConnectionFailed" + | "responseStreamDisconnected" + | "responseTooManyFailedAttempts" + | "activeTurnNotSteerable" + | "codexErrorInfo" + ) + }) + .cloned() + .collect::>(); + if !keys.is_empty() { + fields.push(format!("fields={}", keys.join(","))); + } + } + let suffix = if fields.is_empty() { + String::new() + } else { + format!(" detail={}", fields.join(" ")) + }; + platform_llm::LlmError::InvalidRequest(format!( + "{GAME_CREATOR_CODEX_APP_SERVER_ERROR_KIND_PREFIX}{kind}{suffix}" + )) +} + fn game_creator_codex_app_server_error_http_status( info: &serde_json::Value, field: &str, @@ -425,7 +470,7 @@ fn game_creator_codex_app_server_failed_turn_error( return game_creator_codex_app_server_error_kind("unauthorized"); } let Some(info) = error.get("codexErrorInfo").filter(|info| !info.is_null()) else { - return game_creator_codex_app_server_error_kind("other"); + return game_creator_codex_app_server_error_kind_with_machine_detail("other", error); }; if let Some(kind) = info.as_str() { return match kind { @@ -449,8 +494,8 @@ fn game_creator_codex_app_server_failed_turn_error( game_creator_codex_app_server_error_kind("thread-rollback-failed") } "sandboxError" => game_creator_codex_app_server_error_kind("sandbox-error"), - "other" => game_creator_codex_app_server_error_kind("other"), - _ => game_creator_codex_app_server_error_kind("other"), + "other" => game_creator_codex_app_server_error_kind_with_machine_detail("other", error), + _ => game_creator_codex_app_server_error_kind_with_machine_detail("other", error), }; } for field in [ @@ -466,7 +511,7 @@ fn game_creator_codex_app_server_failed_turn_error( if info.get("activeTurnNotSteerable").is_some() { return game_creator_codex_app_server_error_kind("active-turn-not-steerable"); } - game_creator_codex_app_server_error_kind("other") + game_creator_codex_app_server_error_kind_with_machine_detail("other", error) } async fn isolate_game_creator_codex_app_server_terminal_unknown( diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/direct_runtime.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/direct_runtime.rs index 71cf43b44..64343f79f 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/agent/direct_runtime.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/agent/direct_runtime.rs @@ -1905,7 +1905,11 @@ fn direct_codex_error_is_mud_points_insufficient(error: &str) -> bool { || normalized.contains("insufficient-mud-points") } -fn record_direct_codex_turn_failure(root: &Path, failure: DirectCodexTurnFailure) -> String { +fn record_direct_codex_turn_failure( + root: &Path, + failure: DirectCodexTurnFailure, + client_turn_id: Option<&str>, +) -> String { let summary = direct_codex_failure_public_summary(&failure.error) .map(str::to_string) .unwrap_or_else(|| redact_agent_runtime_error(root, &failure.error, 320)); @@ -1942,18 +1946,53 @@ fn record_direct_codex_turn_failure(root: &Path, failure: DirectCodexTurnFailure } else { "未能保存项目诊断" }; - format!( - "direct-codex-failure:v1 stage={} retryable={} summary={}；建议：{}；{}", + let error_code = classify_direct_codex_error(&failure.error); + let unified_detail_ref = persist_agent_runtime_error( + root, + client_turn_id, + "direct-codex", failure.stage.id(), + error_code, + retryable, + &summary, + recovery_hint, + &failure.error, + None, + serde_json::json!({ + "legacyDiagnosticWritten": diagnostic_written, + }), + ) + .ok() + .map(|event| event.detail_ref); + format!( + "direct-codex-failure:v2 stage={} code={} retryable={} summary={}；建议：{}；{}{}", + failure.stage.id(), + error_code, retryable, diagnostic["summary"] .as_str() .unwrap_or("未提供可安全展示的详细原因"), recovery_hint, diagnostics_suffix, + unified_detail_ref + .map(|path| format!("；详情：{path}")) + .unwrap_or_default(), ) } +fn persist_direct_codex_failure_context( + root: &Path, + client_turn_id: &str, + error: &str, +) -> Result<(), String> { + let item = direct_project_local_message_item( + "assistant", + error, + Some(&format!("direct-codex:{client_turn_id}:failure")), + )?; + append_direct_project_history_item_at(root, &item) +} + fn direct_taonier_art_generation_runtime_context( root: &Path, output_path: &str, @@ -2269,9 +2308,19 @@ fn direct_registered_taonier_slice_paths(root: &Path) -> Vec { } fn direct_game_sources_referenced_taonier_assets(root: &Path) -> Vec { - let sources = direct_codex_game_outputs(root) + let mut source_paths = direct_codex_game_outputs(root) .into_iter() - .filter_map(|(relative_path, _, _)| std::fs::read_to_string(root.join(relative_path)).ok()) + .map(|(relative_path, _, _)| relative_path) + .collect::>(); + // npm/Phaser projects put the actual scene and loader code below `game/src`. + // Keep the canonical output list for manifest projection, but scan the + // complete bounded source list for the asset reference contract. + source_paths.extend(direct_npm_source_paths(root)); + source_paths.sort(); + source_paths.dedup(); + let sources = source_paths + .into_iter() + .filter_map(|relative_path| std::fs::read_to_string(root.join(relative_path)).ok()) .collect::>(); let mut available_paths = Vec::new(); if direct_taonier_art_base_is_valid(root) { @@ -2284,6 +2333,28 @@ fn direct_game_sources_referenced_taonier_assets(root: &Path) -> Vec { available_paths.push(DIRECT_CODEX_SPRITESHEET_ASSET_PATH.to_string()); } available_paths.extend(direct_registered_taonier_slice_paths(root)); + // A project may have a valid, client-registered art-spritesheet at a + // project-specific path (for example a generated building sheet). The + // fixed canonical package paths above are compatibility candidates only; + // the manifest is the authority for additional runtime image identities. + if let Ok(manifest) = read_manifest_for_project(root) { + available_paths.extend( + manifest + .assets + .into_iter() + .filter(|asset| { + matches!( + asset.kind.as_str(), + "art-spritesheet" | "art-spritesheet-slice" | "game-background" + ) && asset.media_type == "image/png" + && asset.source.kind == GameCreationAppAssetSourceKind::Canvas + && asset.local_path.starts_with("assets/") + }) + .map(|asset| asset.local_path), + ); + } + available_paths.sort(); + available_paths.dedup(); available_paths .into_iter() .filter(|path| sources.iter().any(|source| source.contains(path.as_str()))) @@ -4087,7 +4158,17 @@ async fn run_direct_game_creator_turn_at_with_creation_type_and_emitter( { Ok(reply) => Ok(reply), Err(failure) => { - let error = record_direct_codex_turn_failure(root, failure); + let error = record_direct_codex_turn_failure( + root, + failure, + turn_emitter.map(|emitter| emitter.turn_id()), + ); + if let Some(emitter) = turn_emitter { + // Persist the safe terminal projection so the next DirectProject + // turn can answer a diagnostic question from evidence instead of + // guessing or starting another playtest. + let _ = persist_direct_codex_failure_context(root, emitter.turn_id(), &error); + } if let Some(emitter) = turn_emitter { emitter.emit("failed", Some("none"), None); } @@ -6620,26 +6701,27 @@ mod tests { #[test] fn direct_failure_diagnostic_is_redacted_and_persisted_with_a_stable_stage() { - let root = tempfile::tempdir().expect("temp dir"); - init_local_game_project_at(root.path(), "direct-diagnostic", "直连诊断") - .expect("init project"); + let parent = tempfile::tempdir().expect("temp dir"); + let root = parent.path().join("project"); + init_local_game_project_at(&root, "direct-diagnostic", "直连诊断").expect("init project"); let error = record_direct_codex_turn_failure( - root.path(), + &root, DirectCodexTurnFailure::new( DirectCodexFailureStage::ArtPreparation, "读取陶泥儿画布资源失败：https://provider.example/private?token=secret C:\\Users\\private\\project authorization=Bearer secret", ), + None, ); assert!(error - .starts_with("direct-codex-failure:v1 stage=art-preparation retryable=true summary=")); + .starts_with("direct-codex-failure:v2 stage=art-preparation code=runtime-failure retryable=true summary=")); assert!(error.contains(""), "{error}"); assert!(error.contains(""), "{error}"); assert!(!error.contains("authorization=Bearer secret"), "{error}"); assert!(!error.contains("?token=secret"), "{error}"); assert!(!error.contains("provider.example"), "{error}"); - let diagnostics = root.path().join(".agent/runtime/direct-codex-diagnostics"); + let diagnostics = root.join(".agent/runtime/direct-codex-diagnostics"); let entries = std::fs::read_dir(&diagnostics) .expect("diagnostic directory") .filter_map(Result::ok) @@ -6658,25 +6740,25 @@ mod tests { #[test] fn direct_failure_diagnostic_marks_project_history_shape_failure_as_not_retryable() { - let root = tempfile::tempdir().expect("temp dir"); - init_local_game_project_at(root.path(), "direct-diagnostic", "直连诊断") - .expect("init project"); + let parent = tempfile::tempdir().expect("temp dir"); + let root = parent.path().join("project"); + init_local_game_project_at(&root, "direct-diagnostic", "直连诊断").expect("init project"); let history_path = root - .path() .join(".agent/conversations/project.jsonl") .display() .to_string(); let error = record_direct_codex_turn_failure( - root.path(), + &root, DirectCodexTurnFailure::new( DirectCodexFailureStage::CodeGeneration, format!("DirectProject 历史记录类型无效：{history_path}"), ), + None, ); assert!( error.starts_with( - "direct-codex-failure:v1 stage=code-generation retryable=false summary=" + "direct-codex-failure:v2 stage=code-generation code=runtime-failure retryable=false summary=" ), "{error}" ); @@ -6686,9 +6768,9 @@ mod tests { ), "{error}" ); - assert!(error.ends_with("已保存脱敏项目诊断"), "{error}"); + assert!(error.contains("已保存脱敏项目诊断"), "{error}"); - let diagnostics = root.path().join(".agent/runtime/direct-codex-diagnostics"); + let diagnostics = root.join(".agent/runtime/direct-codex-diagnostics"); let entries = std::fs::read_dir(&diagnostics) .expect("diagnostic directory") .filter_map(Result::ok) @@ -6702,19 +6784,20 @@ mod tests { #[test] fn direct_failure_diagnostic_marks_ambiguous_canvas_identity_as_not_retryable() { - let root = tempfile::tempdir().expect("temp dir"); - init_local_game_project_at(root.path(), "direct-diagnostic", "直连诊断") - .expect("init project"); + let parent = tempfile::tempdir().expect("temp dir"); + let root = parent.path().join("project"); + init_local_game_project_at(&root, "direct-diagnostic", "直连诊断").expect("init project"); let error = record_direct_codex_turn_failure( - root.path(), + &root, DirectCodexTurnFailure::new( DirectCodexFailureStage::ArtPreparation, "陶泥儿画布存在多个同源核心图集，身份不唯一，已拒绝恢复", ), + None, ); assert!( - error.contains("stage=art-preparation retryable=false"), + error.contains("stage=art-preparation code=runtime-failure retryable=false"), "{error}" ); assert!(error.contains("历史画布资源不满足安全恢复条件"), "{error}"); @@ -6722,15 +6805,16 @@ mod tests { #[test] fn direct_failure_diagnostic_keeps_private_credential_storage_failure_actionable() { - let root = tempfile::tempdir().expect("temp dir"); - init_local_game_project_at(root.path(), "direct-diagnostic", "直连诊断") - .expect("init project"); + let parent = tempfile::tempdir().expect("temp dir"); + let root = parent.path().join("project"); + init_local_game_project_at(&root, "direct-diagnostic", "直连诊断").expect("init project"); let error = record_direct_codex_turn_failure( - root.path(), + &root, DirectCodexTurnFailure::new( DirectCodexFailureStage::ArtPreparation, "private-external-editor-credential-storage-preparation-failed: 本机开发者凭据存储目录未安全初始化；未创建远端凭据", ), + None, ); assert!( @@ -7830,6 +7914,40 @@ mod tests { .any(|warning| warning.contains("不得猜测切片"))); } + #[test] + fn direct_completion_scans_npm_scene_modules_for_registered_asset_references() { + let parent = tempfile::tempdir().expect("temp dir"); + let root = parent.path().join("project"); + init_local_game_project_at(&root, "direct-src-runtime", "源码模块素材引用") + .expect("init project"); + register_direct_taonier_art_package_fixture(&root); + register_direct_taonier_art_slice_entries_fixture(&root); + std::fs::write( + root.join("game/package.json"), + "{\"scripts\":{\"build\":\"vite build\"}}", + ) + .expect("package"); + std::fs::write(root.join("game/index.html"), "").expect("index"); + std::fs::write(root.join("game/style.css"), "body {}").expect("style"); + std::fs::write(root.join("game/game.js"), "import './src/scene.js';").expect("entry"); + std::fs::create_dir_all(root.join("game/src")).expect("src dir"); + std::fs::write( + root.join("game/src/scene.js"), + "const player = new Image(); player.src = '/assets/art-spritesheet-slices/player.png';", + ) + .expect("scene"); + std::fs::write( + root.join("assets/art-spritesheet-slices/player.png"), + tiny_opaque_png(), + ) + .expect("slice"); + + assert_eq!( + direct_game_sources_referenced_taonier_assets(&root), + vec!["assets/art-spritesheet-slices/player.png".to_string()] + ); + } + #[test] fn direct_output_sync_accepts_trusted_spec_and_background_without_a_historical_spritesheet() { let root = tempfile::tempdir().expect("temp dir"); diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/direct_tool_bridge.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/direct_tool_bridge.rs index 6c94bfe6a..12c6f8d27 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/agent/direct_tool_bridge.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/agent/direct_tool_bridge.rs @@ -1078,7 +1078,9 @@ fn bridge_attempt(arguments: &Value) -> Result { .and_then(Value::as_u64) .ok_or_else(|| "工具参数 attempt 必须是 1 到 3 的整数".to_string())?; if !(1..=3).contains(&attempt) { - return Err("工具参数 attempt 必须是 1 到 3 的整数".to_string()); + return Err(format!( + "playtest-attempt-limit-exceeded: 本轮试玩最多 3 次，收到 attempt={attempt}；请结束试玩并基于最近一次浏览器证据报告结果" + )); } Ok(attempt as usize) } @@ -2608,6 +2610,30 @@ async fn handle_direct_tool_bridge( } _ => bridge_tool_result("未知或未审核的客户端工具".to_string(), Vec::new(), true), }; + if result.get("isError").and_then(Value::as_bool) == Some(true) { + let message = result + .pointer("/content/0/text") + .and_then(Value::as_str) + .unwrap_or("客户端工具执行失败"); + let code = if message.contains("playtest-attempt-limit-exceeded") { + "playtest-attempt-limit-exceeded" + } else { + "tool-error" + }; + let _ = persist_agent_runtime_error( + &state.root, + None, + "agc-tools", + "tool-execution", + code, + true, + message, + "查看项目错误诊断后处理", + message, + None, + serde_json::json!({"tool": request.tool}), + ); + } Json(result) } diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/direct_tools_mcp.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/direct_tools_mcp.rs index 294b44c25..1005ed813 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/agent/direct_tools_mcp.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/agent/direct_tools_mcp.rs @@ -898,7 +898,9 @@ fn tool_attempt(arguments: &Value) -> Result { .and_then(Value::as_u64) .ok_or_else(|| "工具参数 attempt 必须是 1 到 3 的整数".to_string())?; if !(1..=3).contains(&attempt) { - return Err("工具参数 attempt 必须是 1 到 3 的整数".to_string()); + return Err(format!( + "playtest-attempt-limit-exceeded: 本轮试玩最多 3 次，收到 attempt={attempt}；请结束试玩并基于最近一次浏览器证据报告结果" + )); } Ok(attempt as usize) } diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_error.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_error.rs new file mode 100644 index 000000000..4fe895680 --- /dev/null +++ b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_error.rs @@ -0,0 +1,167 @@ +//! Shared, project-bound error events for Agent Runtime and DirectProject. +//! +//! Every caller supplies a safe public summary and a private detail. This +//! module is the only persistence boundary for the latter: it redacts project +//! paths and credentials before writing a bounded diagnostic sidecar. + +use super::{redact_agent_runtime_error, write_agent_runtime_json_sidecar_with_max_bytes}; +use serde::{Deserialize, Serialize}; +use serde_json::Value; +use std::path::Path; +use std::sync::atomic::{AtomicU64, Ordering}; +use std::time::{SystemTime, UNIX_EPOCH}; + +pub(crate) const AGENT_RUNTIME_ERROR_SCHEMA_VERSION: &str = "agent-runtime-error.v1"; +pub(crate) const AGENT_RUNTIME_ERROR_MAX_DETAIL_CHARS: usize = 8 * 1024; + +static ERROR_EVENT_SEQUENCE: AtomicU64 = AtomicU64::new(1); + +#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)] +pub(crate) struct AgentRuntimeErrorEvent { + pub schema_version: &'static str, + pub event_id: String, + pub client_turn_id: Option, + pub source: String, + pub stage: String, + pub code: String, + pub retryable: bool, + pub occurred_at_unix_nanos: String, + pub elapsed_ms: Option, + pub public_text: String, + pub recovery_hint: String, + pub detail_ref: String, + pub persistence_failed: bool, + pub metadata: Value, +} + +pub(crate) fn persist_agent_runtime_error( + root: &Path, + client_turn_id: Option<&str>, + source: &str, + stage: &str, + code: &str, + retryable: bool, + public_text: &str, + recovery_hint: &str, + detail: &str, + elapsed_ms: Option, + metadata: Value, +) -> Result { + let occurred_at_unix_nanos = SystemTime::now() + .duration_since(UNIX_EPOCH) + .map_err(|error| format!("读取错误事件时间失败：{error}"))? + .as_nanos(); + let sequence = ERROR_EVENT_SEQUENCE.fetch_add(1, Ordering::Relaxed); + let event_id = format!("error-{occurred_at_unix_nanos}-{sequence}"); + let detail_ref = format!(".agent/runtime/errors/{event_id}.json"); + let safe_detail = + redact_agent_runtime_error(root, detail, AGENT_RUNTIME_ERROR_MAX_DETAIL_CHARS); + let diagnostic = serde_json::json!({ + "schemaVersion": AGENT_RUNTIME_ERROR_SCHEMA_VERSION, + "eventId": event_id, + "clientTurnId": client_turn_id, + "source": source, + "stage": stage, + "code": code, + "retryable": retryable, + "occurredAtUnixNanos": occurred_at_unix_nanos.to_string(), + "elapsedMs": elapsed_ms, + "publicText": public_text, + "recoveryHint": recovery_hint, + "detail": safe_detail, + "metadata": metadata, + }); + write_agent_runtime_json_sidecar_with_max_bytes( + root, + &detail_ref, + "统一 Agent Runtime 错误诊断", + &diagnostic, + 16 * 1024, + )?; + Ok(AgentRuntimeErrorEvent { + schema_version: AGENT_RUNTIME_ERROR_SCHEMA_VERSION, + event_id, + client_turn_id: client_turn_id.map(str::to_string), + source: source.to_string(), + stage: stage.to_string(), + code: code.to_string(), + retryable, + occurred_at_unix_nanos: occurred_at_unix_nanos.to_string(), + elapsed_ms, + public_text: public_text.to_string(), + recovery_hint: recovery_hint.to_string(), + detail_ref, + persistence_failed: false, + metadata, + }) +} + +pub(crate) fn classify_direct_codex_error(error: &str) -> &'static str { + let normalized = error.to_ascii_lowercase(); + if normalized.contains("等待 turn/completed 超时") { + "turn-idle-timeout" + } else if normalized.contains("达到 directproject 硬上限") { + "turn-hard-timeout" + } else if normalized.contains("transport closed") || normalized.contains("连接已关闭") { + "transport-closed" + } else if normalized.contains("playtest-attempt-limit-exceeded") { + "playtest-attempt-limit-exceeded" + } else if (normalized.contains("tool") || normalized.contains("工具")) + && normalized.contains("参数") + { + "tool-invalid-arguments" + } else if normalized.contains("codex app-server-error:other") { + "app-server-other" + } else { + "runtime-failure" + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn error_event_is_bounded_and_redacts_private_detail() { + let parent = tempfile::tempdir().expect("temp root"); + let root = parent.path().join("project"); + crate::project::init_local_game_project_at(&root, "runtime-error", "错误事件") + .expect("init project"); + let event = persist_agent_runtime_error( + &root, + Some("turn-123"), + "direct-codex", + "code-generation", + "turn-idle-timeout", + true, + "本轮没有收到完成事件", + "查看诊断后重试", + "C:\\Users\\private\\project https://provider.example/a?token=secret", + Some(1200), + serde_json::json!({"lastEvent":"item/started"}), + ) + .expect("persist event"); + assert_eq!(event.code, "turn-idle-timeout"); + let path = root.join(&event.detail_ref); + let text = std::fs::read_to_string(path).expect("diagnostic"); + assert!(text.contains("")); + assert!(text.contains("")); + assert!(!text.contains("token=secret")); + } + + #[test] + fn timeout_and_tool_errors_have_distinct_codes() { + assert_eq!( + classify_direct_codex_error("等待 turn/completed 超时"), + "turn-idle-timeout" + ); + assert_eq!( + classify_direct_codex_error("达到 DirectProject 硬上限"), + "turn-hard-timeout" + ); + assert_eq!( + classify_direct_codex_error("工具参数 attempt 必须是 1 到 3 的整数"), + "tool-invalid-arguments" + ); + } +} diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_state.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_state.rs index f23bf5f5b..ede8bb200 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_state.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_state.rs @@ -101,6 +101,26 @@ pub(crate) fn append_game_creator_agent_runtime_terminal_public_message_at( error: &str, ) -> Result<(), String> { let content = game_creator_agent_runtime_failure_conversation_message(&state.agent_id, error); + // Keep the existing conversation projection, but also persist one common + // bounded diagnostic event for every Agent Runtime terminal failure. This + // makes non-DirectProject failures observable through the same detail API. + let _ = persist_agent_runtime_error( + root, + Some(&state.run_id), + "agent-runtime", + &state.phase, + "agent-runtime-terminal", + false, + &content, + "查看项目错误诊断后处理", + error, + None, + serde_json::json!({ + "agentId": state.agent_id, + "sessionId": state.session_id, + "runId": state.run_id, + }), + ); let status = if state.phase == "budget-exhausted" { "budget-exhausted" } else if state.phase == "needs-reconciliation" { diff --git a/apps/ai-game-creator-shell/src-tauri/src/commands.rs b/apps/ai-game-creator-shell/src-tauri/src/commands.rs index 828048813..53c77d151 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/commands.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/commands.rs @@ -5244,6 +5244,38 @@ pub(crate) async fn read_direct_project_conversation( .map_err(|error| format!("读取 DirectProject 历史后台任务失败：{error}"))? } +#[tauri::command] +pub(crate) async fn read_agent_runtime_error_detail( + project_path: String, + detail_ref: String, +) -> Result { + tauri::async_runtime::spawn_blocking(move || { + let root = Path::new(project_path.trim()); + enforce_project_permission_policy(root, "conversation.read")?; + let relative = detail_ref.trim(); + let Some(file_name) = relative.strip_prefix(".agent/runtime/errors/") else { + return Err("错误诊断引用不在项目错误目录内".to_string()); + }; + if file_name.is_empty() + || file_name.contains(['/', '\\']) + || file_name.contains("..") + || !file_name.ends_with(".json") + { + return Err("错误诊断引用格式无效".to_string()); + } + let path = root.join(relative); + prepare_game_creator_private_path_for_read(&path, false, "统一错误诊断")?; + let bytes = std::fs::read(&path).map_err(|error| format!("读取错误诊断失败：{error}"))?; + if bytes.len() > 16 * 1024 { + return Err("错误诊断超过读取上限".to_string()); + } + let text = String::from_utf8(bytes).map_err(|_| "错误诊断不是 UTF-8 文本".to_string())?; + Ok(redact_agent_runtime_error(root, &text, 16 * 1024)) + }) + .await + .map_err(|error| format!("读取统一错误诊断后台任务失败：{error}"))? +} + #[tauri::command] pub(crate) fn append_local_conversation_message( project_path: String, diff --git a/apps/ai-game-creator-shell/src-tauri/src/main.rs b/apps/ai-game-creator-shell/src-tauri/src/main.rs index 2f2f5b7e2..b95ebf358 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/main.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/main.rs @@ -2768,6 +2768,7 @@ fn main() { archive_game_creator_agent_session, read_local_conversation, read_direct_project_conversation, + read_agent_runtime_error_detail, append_local_conversation_message, append_direct_project_conversation_message, build_local_project_index, diff --git a/apps/ai-game-creator-shell/src/App.tsx b/apps/ai-game-creator-shell/src/App.tsx index d1b1cf38c..723c0429c 100644 --- a/apps/ai-game-creator-shell/src/App.tsx +++ b/apps/ai-game-creator-shell/src/App.tsx @@ -6519,8 +6519,25 @@ export function App({ void captureAgentRuntimeError(error, PROJECT_SUPERVISOR_AGENT_ID); const message = error instanceof Error ? error.message : String(error); + let persistedDetail = ''; + const detailRef = message.match( + /详情：(\.agent\/runtime\/errors\/[^\s；]+)/, + )?.[1]; + if (detailRef && directInvoke) { + try { + persistedDetail = await directInvoke( + 'read_agent_runtime_error_detail', + { + projectPath: directProjectPath, + detailRef, + }, + ); + } catch { + persistedDetail = ''; + } + } const visibleMessage = projectRuntimeVisibleError( - message, + persistedDetail ? `${message}\n\n${persistedDetail}` : message, '陶泥儿智能创作', true, ); diff --git a/docs/project-memory/plans/【实施计划】AGC统一错误诊断与验收反馈-2026-09-15.md b/docs/project-memory/plans/【实施计划】AGC统一错误诊断与验收反馈-2026-09-15.md new file mode 100644 index 000000000..031cd576c --- /dev/null +++ b/docs/project-memory/plans/【实施计划】AGC统一错误诊断与验收反馈-2026-09-15.md @@ -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` 读取兼容。 diff --git a/docs/project-memory/plans/【里程碑】AGC统一错误诊断与验收反馈-2026-09-15.md b/docs/project-memory/plans/【里程碑】AGC统一错误诊断与验收反馈-2026-09-15.md new file mode 100644 index 000000000..bcc95ef90 --- /dev/null +++ b/docs/project-memory/plans/【里程碑】AGC统一错误诊断与验收反馈-2026-09-15.md @@ -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 资源身份。 diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md index d18fbd8ab..bd8416d40 100644 --- a/docs/project-memory/shared-memory/decision-log.md +++ b/docs/project-memory/shared-memory/decision-log.md @@ -8741,6 +8741,7 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在 - 影响范围：新增 `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。 @@ -8751,3 +8752,11 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在 - 决策：旧版 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/.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` 与对应实施计划。 + diff --git a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md index 657dcb9fc..3f091c118 100644 --- a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md +++ b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md @@ -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 美化或增加重试预算；不能用延长超时、删除完成门或把失败投影为成功来规避问题。