[Tracking] GameAgent 客户端画布与资源工作台 V3.0 #309

New Issue

2026-09-09T13:12:40+08:00

suzmii commented

2026-09-09 13:12:40 +08:00

[Tracking] GameAgent 客户端画布与资源工作台 V3.0

需求来源：飞书《GameAgent客户端画布与资源工作台 V3.0》
https://kcnz41bksl1c.feishu.cn/wiki/N4KiwMFkGiwemFkbKU7cAXwxn9U
关联 PR：#316
本文档为唯一权威：范围、方案与进度都维护在这里，子项按 C1…C11 编号。

一、目标

把网页端美术编辑器能力迁到 AGC 客户端，形成「资源画布 + Agent 对话 + 运行模块」闭环。资源的产生与变更方式：

新增资源：生成 / 派生 / 上传 → 新文件落本地 assets/ 并登记进 manifest；
更换某个版本使用的资源：改 manifest 里该版本的资源绑定，指向另一个已登记资源；
删除资源：用户确认后删除。

二、贯穿性决策

素材不可变：创建后内容不变，所有编辑产出新素材。
asset-canvas 彻底删除：不再有"单个图片的精修草稿"（已完成）。
快速编辑改为创建新素材，交互与美术画布保持一致。
版本绑定即资源记录：游戏版本的 resourceBindings 就是"这个版本使用了哪些资源"的权威记录；slotId 保持恒等映射 asset:{assetId}，契约字段不改。
不做运行时资源观察：不写代码注入、不做 Phaser wrapper、不引入 .agent 侧车、不做脚手架哈希校验。资源文件与登记路径都不变。
更换资源 = 改 manifest 绑定：不创建新版本、不改动资源文件、不引入 UI 流程。
删除由用户确认：被版本引用过时二次提示，并提供"是否连带删除相关游戏版本"的勾选；不勾选则只删素材，版本保留悬空绑定，后果由用户自负。

三、交付范围

必须：美术画布功能迁移（第一刀）｜资源分类与自定义标签｜素材模型与生命周期（含删除）｜游戏项目资源使用记录（版本绑定）｜运行模块版本切换｜AI 润色与发送前提醒

应该：参考图弹窗｜@ 面板两个页签｜素材重命名｜首轮进度投影

不做：图层高级操作（剪切/层序/导出）｜图集拆分/像素规整｜任务列表全量｜Godot/Unity 运行期替换｜账号素材库/公开投稿｜新的 Agent 编排或审批门｜替换功能（候选素材 / 替换关系 / 替换队列 / Agent 审核 / 单点替换）｜运行画面点选｜运行时资源观察与代码注入

四、子项总览

编号	子项	状态
C1	游戏项目资源使用记录	已完成（恒等绑定口径，运行期观察侧车已撤）
C2	资源分类与自定义标签	已完成
C3	美术画布功能迁移（第一刀）	已完成（转场动画 + 交互 1:1 复刻 + 画布基础能力；生成入口未做，见下）
C4	聊天通用引用	已完成（两个页签 + 独立筛选 + 改名刷新 + 跨会话光标）
C5	素材模型与生命周期	已完成（删除确认 + 可选连带删版本 + 卡片边框）
C6	替换关系与替换队列	已取消，不实现
C7	运行模块版本切换	已完成
C8	AI 润色与发送前提醒	已完成
C9	参考图弹窗	已完成
C10	asset-canvas 彻底删除	已完成
C11	PR #283 收口	已完成

C1 · 游戏项目资源使用记录

要解决的问题：客户端要能说清"某个游戏版本使用了哪些资源"。

方案

游戏版本的 resourceBindings 承担这个记录；slotId 为恒等映射 asset:{assetId}，resourceId 指向 manifest 资产 ID；
版本追加、不可变；清单随版本冻结；
需要更换某个资源时，改 manifest 里该版本的绑定指向另一个已登记资源——不动文件、不创建新版本。

不做：运行时观察、Phaser wrapper、Vite 注入、虚拟模块、脚手架哈希校验、.agent 资源侧车、未登记素材诊断。

C2 · 资源分类与自定义标签（已完成）

manifest 资产条目新增 category（6 类，默认"待归类"）与 tags（自定义标签）；
默认分类由 kind 穷举映射，历史 manifest 缺字段时按 kind 派生，显式值原样保留；
筛选口径统一为 category：资源画布与 @ 面板共用同一组筛选，旧的按 mediaType 分 7 桶已删除；
分类与标签可在资源详情里编辑（独立弹窗 + 写入命令，非法分类直接拒绝）。

C3 · 美术画布功能迁移（第一刀）

目标：画布结构保持组织板（默认"全部资源" + 功能画布 + 资源卡 + 筛选，不做图层编辑），交互 1:1 复刻美术画布。

交互合同（与美术画布一致）

操作	行为
点击资源卡	选中 + 在卡片旁浮出选中工具条。工具条动作与美术画布一致：快速编辑 / 重绘 / 裁剪扩图 / 去背景 / 像素完美 / 切图集 / 提取 UI 素材 / 角色动画 / 下载
点击"快速编辑"	打开浮层面板（复用美术画布的快速编辑面板）；语义按已定决策——产出新素材，不原地改
其余动作	与美术画布同名动作同语义、同面板形态
一律复用现成组件	`src/components/image-editor/` 下的工具条、面板、生成 composer 等直接复用，不自己重写一套

明确取消：点击资源卡弹出"资源详情"面板；"编辑资源"全屏路由（resourceEditorRoute）。分类与标签等编辑入口改由工具条承担。

已完成

转场与布局动画改为真实元素 FLIP：同一批 DOM 节点，不存在"克隆→真实节点"的交接，结束时不再跳变；
预览图尺寸晚到引起的布局变化走同一套可中断重基；
修复返回总览时非活动栏目标题栏从屏幕外飞入。

待改造（前期实现与交互合同不符）

点击卡片目前弹出"资源详情"面板、并存在"编辑资源"全屏路由，需按上表改为"选中 + 浮出工具条 + 浮层面板"。

待做：画布基础（平移 / 缩放 / 适应 / 恢复、选择 / 多选 / 框选、撤销重做）、资源面板（预览 / 上传 / 下载 / 重命名 / 多选）、生成入口、快速编辑浮层、参考图选择。

后置：图层高级操作、图集拆分、像素规整、任务列表全量、UI 编辑器联动。

C4 · 聊天通用引用

已完成：结构化引用（资源与运行区域）、@ 面板主体实现（自 agc-chat-resource-mentions 迁入）。

待做：@ 面板两个页签（当前版本素材 / 全部画布素材）、独立筛选状态、素材改名后显示名刷新、跨会话引用光标位置。

不做：运行画面点选（原设计的 Phaser hitTestPointer 方案随 C6 一起取消）。

C5 · 素材模型与生命周期

素材不可变：创建后内容不变；所有编辑产出新素材；
删除：
- 未被任何版本绑定 → 直接删除；
- 被版本绑定过 → 提示被哪些版本使用，并给出"把相关游戏版本一并删除"勾选；
  - 勾选 → 素材与相关版本一起删除；
  - 不勾选 → 只删素材，版本记录保留悬空绑定，界面不为它合成资源卡；
- 用户自负后果，不做二次拦截；
卡片边框：当前使用 / 其他（无边框）；
编辑面中间状态：前端内存临时缓存，刷新即失效，不持久化。

C6 · 替换关系与替换队列（已取消）

原设计包含：候选素材、替换关系（资源级默认 + 单 slot 覆盖）、持久串行队列、Agent 审核三态、替换后生成新版本。

结论：整条不实现。 更换资源的需求由 C1 的"改 manifest 绑定"覆盖，不再引入队列、审核与单点替换。

C7 · 运行模块版本切换

版本入口移到运行模块右上角；
当前版本的素材列表移入 @ 面板；
切换版本时，游戏画面与 @ 面板的"当前版本素材"同步更新；
按版本绑定取对应资源，未被改动过的部分完全还原。

C8 · AI 润色与发送前提醒

主动润色回填 + 恢复原文快照 + 失败保留原文 + 可重复润色；
发送前提醒面板：AI 润色 / 使用原文提交 / 关闭 + 不再提醒偏好；
计费：1 泥点。

C9 · 参考图弹窗

独立参考图选择弹窗：网格卡片、多选、筛选、搜索、清空、确认 / 取消；
复用画布筛选组件，但使用独立筛选状态；
任务提交时记录参考图素材 ID 快照，源素材后续变化不影响已提交任务。

C10 · asset-canvas 彻底删除（已完成）

删除 Rust project/asset_canvas.rs、asset_canvas/generation.rs、asset_canvas_tests.rs、相关命令与注册；删除前端 features/asset-canvas/ 与草稿路由、提交事件链路及相关测试；
图片编辑改走 derive + editKind='image-reference'：结果创建新素材，源素材不变；
保留：canvas.asset_generate 契约、packages/image-canvas-core|react、resource_editor.rs、manifest 画板来源 kind='canvas'、服务端直传票据白名单；
文档按"四不写"收口，退役合同整篇删除，仍有效内容迁入对应技术方案。

C11 · PR #283 收口（已完成）

#283 已关闭；canonical 资源类型契约、资源依赖本地身份解析、资源画本视觉层样式与画布实现已迁入本分支。

五、验收总纲

资源记录：任一正式版本都能列出它使用的资源；改绑定后该版本按新绑定取资源，未改动的部分不变；
更换资源：改 manifest 绑定后，该版本使用新资源，且不产生新版本、资源文件未被修改；
删除：被引用时必须出现二次提示与勾选；不勾选时只删素材，版本仍可读、不合成资源卡；
画布：平移 / 缩放 / 适应 / 恢复、多选 / 框选、撤销重做、资源面板、生成入口、快速编辑浮层、筛选；
资源卡交互：点击卡片选中并在卡片旁浮出工具条，动作与美术画布一致；不存在"资源详情"面板与全屏"编辑资源"路由；
版本切换：画面与 @ 面板同步，未被改动过的资源完全还原；
现有 typecheck、编码检查、git diff --check、Rust 与前端定向测试全部通过。

六、当前进度

已完成

C1 口径收敛：撤掉运行期资源使用侧车与槽位优先绑定，回到恒等映射口径；
C2 资源分类与自定义标签（含筛选口径统一）；
C3 交互 1:1 复刻美术画布（点卡选中 + 卡片旁浮出工具条 + 快速编辑浮层，取消资源详情面板与全屏「编辑资源」路由）+ 画布基础能力（平移/缩放/适应/恢复、单选/多选/框选、撤销重做、独立资源面板含预览/上传/下载/多选）+ 转场与布局动画；
C4 两个页签 + 独立筛选状态 + 改名后显示名刷新 + 跨会话引用光标位置；
C5 删除新口径（确认 + 可选连带删除相关版本）与卡片边框；
C7 运行模块版本切换；C8 AI 润色与发送前提醒；C9 参考图弹窗；
C10 asset-canvas 彻底删除；C11 #283 收口；
素材重命名（文件改名 + localPath 更新，id 不变，写失败回滚）。

明确未做（不在本轮交付）

画布「生成入口」（从画布发起新建素材）未接；角色动画/重绘/裁剪扩图/去背景/像素完美/切图集/提取 UI 素材等工具条动作为未接通状态，按 opt-in 机制不渲染按钮，不留半成品入口；
C7 的版本切换只做记录层 + UI 层（切换即重载预览）。要做到「历史版本独有的资源集合被运行时按版本加载」需新增版本化资源解析机制，未实现；
「首轮进度投影」只在交付范围的"应该"清单出现，无编码级判据；现有底部 Agent 状态栏已覆盖该可见性。

# [Tracking] GameAgent 客户端画布与资源工作台 V3.0 > 需求来源：飞书《GameAgent客户端画布与资源工作台 V3.0》 > https://kcnz41bksl1c.feishu.cn/wiki/N4KiwMFkGiwemFkbKU7cAXwxn9U > 关联 PR：#316 > 本文档为唯一权威：范围、方案与进度都维护在这里，子项按 C1…C11 编号。 --- ## 一、目标把网页端美术编辑器能力迁到 AGC 客户端，形成「资源画布 + Agent 对话 + 运行模块」闭环。资源的产生与变更方式： - **新增资源**：生成 / 派生 / 上传 → 新文件落本地 `assets/` 并登记进 manifest； - **更换某个版本使用的资源**：改 manifest 里该版本的资源绑定，指向另一个已登记资源； - **删除资源**：用户确认后删除。 ## 二、贯穿性决策 1. **素材不可变**：创建后内容不变，所有编辑产出新素材。 2. **asset-canvas 彻底删除**：不再有"单个图片的精修草稿"（已完成）。 3. **快速编辑改为创建新素材**，交互与美术画布保持一致。 4. **版本绑定即资源记录**：游戏版本的 `resourceBindings` 就是"这个版本使用了哪些资源"的权威记录；`slotId` 保持恒等映射 `asset:{assetId}`，契约字段不改。 5. **不做运行时资源观察**：不写代码注入、不做 Phaser wrapper、不引入 `.agent` 侧车、不做脚手架哈希校验。资源文件与登记路径都不变。 6. **更换资源 = 改 manifest 绑定**：不创建新版本、不改动资源文件、不引入 UI 流程。 7. **删除由用户确认**：被版本引用过时二次提示，并提供"是否连带删除相关游戏版本"的勾选；不勾选则只删素材，版本保留悬空绑定，后果由用户自负。 ## 三、交付范围 **必须**：美术画布功能迁移（第一刀）｜资源分类与自定义标签｜素材模型与生命周期（含删除）｜游戏项目资源使用记录（版本绑定）｜运行模块版本切换｜AI 润色与发送前提醒 **应该**：参考图弹窗｜@ 面板两个页签｜素材重命名｜首轮进度投影 **不做**：图层高级操作（剪切/层序/导出）｜图集拆分/像素规整｜任务列表全量｜Godot/Unity 运行期替换｜账号素材库/公开投稿｜新的 Agent 编排或审批门｜**替换功能（候选素材 / 替换关系 / 替换队列 / Agent 审核 / 单点替换）**｜**运行画面点选**｜**运行时资源观察与代码注入** ## 四、子项总览 | 编号 | 子项 | 状态 | |-|-|-| | **C1** | 游戏项目资源使用记录 | **已完成**（恒等绑定口径，运行期观察侧车已撤） | | **C2** | 资源分类与自定义标签 | **已完成** | | **C3** | 美术画布功能迁移（第一刀） | **已完成**（转场动画 + 交互 1:1 复刻 + 画布基础能力；生成入口未做，见下） | | **C4** | 聊天通用引用 | **已完成**（两个页签 + 独立筛选 + 改名刷新 + 跨会话光标） | | **C5** | 素材模型与生命周期 | **已完成**（删除确认 + 可选连带删版本 + 卡片边框） | | **C6** | 替换关系与替换队列 | **已取消，不实现** | | **C7** | 运行模块版本切换 | **已完成** | | **C8** | AI 润色与发送前提醒 | **已完成** | | **C9** | 参考图弹窗 | **已完成** | | **C10** | asset-canvas 彻底删除 | **已完成** | | **C11** | PR #283 收口 | **已完成** | --- ## C1 · 游戏项目资源使用记录 **要解决的问题**：客户端要能说清"某个游戏版本使用了哪些资源"。 **方案** - 游戏版本的 `resourceBindings` 承担这个记录；`slotId` 为恒等映射 `asset:{assetId}`，`resourceId` 指向 manifest 资产 ID； - 版本追加、不可变；清单随版本冻结； - 需要更换某个资源时，改 manifest 里该版本的绑定指向另一个已登记资源——不动文件、不创建新版本。 **不做**：运行时观察、Phaser wrapper、Vite 注入、虚拟模块、脚手架哈希校验、`.agent` 资源侧车、未登记素材诊断。 ## C2 · 资源分类与自定义标签（已完成） - manifest 资产条目新增 `category`（6 类，默认"待归类"）与 `tags`（自定义标签）； - 默认分类由 kind 穷举映射，历史 manifest 缺字段时按 kind 派生，显式值原样保留； - 筛选口径统一为 `category`：资源画布与 `@` 面板共用同一组筛选，旧的按 mediaType 分 7 桶已删除； - 分类与标签可在资源详情里编辑（独立弹窗 + 写入命令，非法分类直接拒绝）。 ## C3 · 美术画布功能迁移（第一刀） **目标**：画布结构保持组织板（默认"全部资源" + 功能画布 + 资源卡 + 筛选，不做图层编辑），**交互 1:1 复刻美术画布**。 **交互合同（与美术画布一致）** | 操作 | 行为 | |---|---| | 点击资源卡 | **选中 + 在卡片旁浮出选中工具条**。工具条动作与美术画布一致：快速编辑 / 重绘 / 裁剪扩图 / 去背景 / 像素完美 / 切图集 / 提取 UI 素材 / 角色动画 / 下载 | | 点击"快速编辑" | 打开**浮层面板**（复用美术画布的快速编辑面板）；语义按已定决策——**产出新素材，不原地改** | | 其余动作 | 与美术画布同名动作同语义、同面板形态 | | 一律复用现成组件 | `src/components/image-editor/` 下的工具条、面板、生成 composer 等直接复用，不自己重写一套 | **明确取消**：点击资源卡弹出"资源详情"面板；"编辑资源"全屏路由（`resourceEditorRoute`）。分类与标签等编辑入口改由工具条承担。 **已完成** - 转场与布局动画改为真实元素 FLIP：同一批 DOM 节点，不存在"克隆→真实节点"的交接，结束时不再跳变； - 预览图尺寸晚到引起的布局变化走同一套可中断重基； - 修复返回总览时非活动栏目标题栏从屏幕外飞入。 **待改造（前期实现与交互合同不符）** - 点击卡片目前弹出"资源详情"面板、并存在"编辑资源"全屏路由，需按上表改为"选中 + 浮出工具条 + 浮层面板"。 **待做**：画布基础（平移 / 缩放 / 适应 / 恢复、选择 / 多选 / 框选、撤销重做）、资源面板（预览 / 上传 / 下载 / 重命名 / 多选）、生成入口、快速编辑浮层、参考图选择。 **后置**：图层高级操作、图集拆分、像素规整、任务列表全量、UI 编辑器联动。 ## C4 · 聊天通用引用 **已完成**：结构化引用（资源与运行区域）、`@` 面板主体实现（自 `agc-chat-resource-mentions` 迁入）。 **待做**：`@` 面板两个页签（当前版本素材 / 全部画布素材）、独立筛选状态、素材改名后显示名刷新、跨会话引用光标位置。 **不做**：运行画面点选（原设计的 Phaser `hitTestPointer` 方案随 C6 一起取消）。 ## C5 · 素材模型与生命周期 - **素材不可变**：创建后内容不变；所有编辑产出新素材； - **删除**： - 未被任何版本绑定 → 直接删除； - 被版本绑定过 → 提示被哪些版本使用，并给出"把相关游戏版本一并删除"勾选； - 勾选 → 素材与相关版本一起删除； - 不勾选 → 只删素材，版本记录保留悬空绑定，界面不为它合成资源卡； - 用户自负后果，不做二次拦截； - **卡片边框**：当前使用 / 其他（无边框）； - **编辑面中间状态**：前端内存临时缓存，刷新即失效，不持久化。 ## C6 · 替换关系与替换队列（已取消）原设计包含：候选素材、替换关系（资源级默认 + 单 slot 覆盖）、持久串行队列、Agent 审核三态、替换后生成新版本。 **结论：整条不实现。** 更换资源的需求由 C1 的"改 manifest 绑定"覆盖，不再引入队列、审核与单点替换。 ## C7 · 运行模块版本切换 - 版本入口移到运行模块右上角； - 当前版本的素材列表移入 `@` 面板； - 切换版本时，游戏画面与 `@` 面板的"当前版本素材"同步更新； - 按版本绑定取对应资源，未被改动过的部分完全还原。 ## C8 · AI 润色与发送前提醒 - 主动润色回填 + 恢复原文快照 + 失败保留原文 + 可重复润色； - 发送前提醒面板：AI 润色 / 使用原文提交 / 关闭 + 不再提醒偏好； - 计费：1 泥点。 ## C9 · 参考图弹窗 - 独立参考图选择弹窗：网格卡片、多选、筛选、搜索、清空、确认 / 取消； - 复用画布筛选组件，但使用独立筛选状态； - 任务提交时记录参考图素材 ID 快照，源素材后续变化不影响已提交任务。 ## C10 · asset-canvas 彻底删除（已完成） - 删除 Rust `project/asset_canvas.rs`、`asset_canvas/generation.rs`、`asset_canvas_tests.rs`、相关命令与注册；删除前端 `features/asset-canvas/` 与草稿路由、提交事件链路及相关测试； - 图片编辑改走 `derive + editKind='image-reference'`：结果创建新素材，源素材不变； - 保留：`canvas.asset_generate` 契约、`packages/image-canvas-core|react`、`resource_editor.rs`、manifest 画板来源 `kind='canvas'`、服务端直传票据白名单； - 文档按"四不写"收口，退役合同整篇删除，仍有效内容迁入对应技术方案。 ## C11 · PR #283 收口（已完成） - #283 已关闭；canonical 资源类型契约、资源依赖本地身份解析、资源画本视觉层样式与画布实现已迁入本分支。 --- ## 五、验收总纲 - **资源记录**：任一正式版本都能列出它使用的资源；改绑定后该版本按新绑定取资源，未改动的部分不变； - **更换资源**：改 manifest 绑定后，该版本使用新资源，且不产生新版本、资源文件未被修改； - **删除**：被引用时必须出现二次提示与勾选；不勾选时只删素材，版本仍可读、不合成资源卡； - **画布**：平移 / 缩放 / 适应 / 恢复、多选 / 框选、撤销重做、资源面板、生成入口、快速编辑浮层、筛选； - **资源卡交互**：点击卡片选中并在卡片旁浮出工具条，动作与美术画布一致；不存在"资源详情"面板与全屏"编辑资源"路由； - **版本切换**：画面与 `@` 面板同步，未被改动过的资源完全还原； - 现有 typecheck、编码检查、`git diff --check`、Rust 与前端定向测试全部通过。 ## 六、当前进度 **已完成** - C1 口径收敛：撤掉运行期资源使用侧车与槽位优先绑定，回到恒等映射口径； - C2 资源分类与自定义标签（含筛选口径统一）； - C3 交互 1:1 复刻美术画布（点卡选中 + 卡片旁浮出工具条 + 快速编辑浮层，取消资源详情面板与全屏「编辑资源」路由）+ 画布基础能力（平移/缩放/适应/恢复、单选/多选/框选、撤销重做、独立资源面板含预览/上传/下载/多选）+ 转场与布局动画； - C4 两个页签 + 独立筛选状态 + 改名后显示名刷新 + 跨会话引用光标位置； - C5 删除新口径（确认 + 可选连带删除相关版本）与卡片边框； - C7 运行模块版本切换；C8 AI 润色与发送前提醒；C9 参考图弹窗； - C10 asset-canvas 彻底删除；C11 #283 收口； - 素材重命名（文件改名 + `localPath` 更新，`id` 不变，写失败回滚）。 **明确未做（不在本轮交付）** - 画布「生成入口」（从画布发起新建素材）未接；角色动画/重绘/裁剪扩图/去背景/像素完美/切图集/提取 UI 素材等工具条动作为未接通状态，**按 opt-in 机制不渲染按钮**，不留半成品入口； - C7 的版本切换只做记录层 + UI 层（切换即重载预览）。要做到「历史版本独有的资源集合被运行时按版本加载」需新增版本化资源解析机制，未实现； - 「首轮进度投影」只在交付范围的"应该"清单出现，无编码级判据；现有底部 Agent 状态栏已覆盖该可见性。

suzmii added the Kind/Feature label 2026-09-09 13:12:40 +08:00

suzmii referenced this issue

2026-09-09 13:13:08 +08:00

AGC 聊天通用引用：素材 @ 面板、资源卡入口与运行画面区域点选 #293

suzmii referenced this issue

2026-09-09 14:57:34 +08:00

WIP:Feat/GameAgent客户端画布与资源工作台 #283

~~suzmii referenced this issue 2026-09-09 21:47:43 +08:00~~

WIP: AGC 资源画布与替换改造 V3.0 #316

Sign in to join this conversation.