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

New Issue

2026-09-07T10:52:28+08:00

suzmii commented

2026-09-07 10:52:28 +08:00

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

需求背景

《客户端画布与资源工作台需求》第 9 节“素材点选和 @ 引用”要求 AGC 支持素材引用和运行画面点选。

当前远端 master 尚没有 @ 素材引用能力：聊天输入框没有 @ 候选和按钮，也没有素材选择面板、资源卡 @引用、运行画面点选模式或结构化引用提交协议。

仓库中已有可复用基础：

项目 manifest 已包含稳定资源 ID、类型、媒体类型和项目相对路径；
资源画布已有资源卡、选择、预览和依赖展示；
首页已有 Lexical 富文本输入和内联附件芯片模型；
运行模块已有受限本地预览 iframe，可在此基础上扩展受控检查协议。

本 Issue 需要在这些现有能力上补齐通用引用系统，不做按 @名称 反向解析的文本方案。

目标

用户可以在 AGC 聊天输入中插入一个或多个结构化素材引用，并在引用标签前后自由编辑自然语言；提交时客户端同时保留用户文本和引用数据，Agent 只接收安全投影。

引用入口共三类：

Agent 输入区 @ 按钮和键盘 @ 触发；
资源画布资源卡和当前版本素材；
运行画面区域点选。

结构化引用协议

先锁定统一输入 DTO，再实现各入口。聊天提交至少包含：

text: 用户可见自然语言
references: 结构化引用数组

素材引用至少包含：

稳定资源 ID；
资源类型；
展示名称快照；
可选来源：asset-picker / resource-card / version-asset / runtime-picker。

来源仅用于展示和追踪，不参与资源解析。

运行画面引用使用独立类型，例如 runtime-region，至少包含：

运行预览或版本身份；
区域摘要标识；
元素类型、可见文本摘要、尺寸等白名单字段；
可解析到的关联资源 ID 列表；
展示名称快照。

运行画面点选不得假设选区一定对应单个素材。它可能是单个素材元素，也可能是包含多个素材的容器、一块 UI 区域或整个游戏窗口。

实现范围

1. 通用引用编辑器

抽取可复用的富文本输入组件，三个聊天入口共用：

输入 @ 后在当前光标处触发候选；
@ 按钮打开素材选择面板；
引用以芯片形式插入，芯片内部保存稳定 ID；
支持在文本中间插入多个引用；
支持在引用前后编辑中文自然语言；
支持删除单个引用后重新编辑；
输入法组合期间不误触发候选或提交；
Enter / Tab 确认，ArrowUp / ArrowDown 选择，Esc 关闭候选；
引用数据与用户文本分开导出，不通过 @名称 反向解析。

2. 素材选择面板

Agent 输入区提供 @ 按钮，打开独立素材选择面板：

素材缩略图；
按名称和资源 ID 搜索；
按类型筛选；
多选；
已选状态；
无资源、无匹配和加载失败状态提示；
键盘可操作；
候选范围来自当前项目 manifest，不限制为固定前几项；
界面做有界渲染，避免一次性渲染超大资源集合。

缩略图复用现有资源预览读取和 object URL 生命周期管理，不新增平行素材存储。

3. 资源画布与当前版本素材入口

资源卡工具栏增加 @引用 操作；
点击后将该资源作为结构化引用插入当前 Agent 输入区；
不改变资源卡现有选择、预览、拖拽和打开详情行为；
运行画面下方当前版本素材也使用同一插入链路；
以上入口与 @ 面板共用同一引用协议。

4. 运行画面区域点选

运行模块顶部提供“点选素材”入口；
进入点选模式后，运行画面支持元素 hover 高亮和点击选择；
选区可为元素、容器或整个窗口；
能解析到 manifest 资源时记录关联资源 ID；
无法一一映射时保留 runtime-region 引用，不伪装成素材引用；
点选结果插入 Agent 输入区；
再次点击入口、点击“退出点选”或按 Esc 均可退出；
点选期间不修改游戏文件，退出后清理高亮和监听状态。

实现应基于现有本地预览 iframe 的 origin 校验消息通道，新增受控检查协议；禁止把完整 DOM、任意属性或内部路径传给宿主。

5. 提交前校验与安全投影

提交前客户端必须重新校验引用：

资源已删除或不可用：阻止发送，并提示用户移除或重新选择；
资源改名：继续使用稳定 ID，刷新显示名快照；
同名资源：按稳定 ID 区分；
运行预览或版本失效：阻止发送旧区域引用，提示重新点选；
普通无引用消息继续走现有聊天兼容分支。

Agent 只接收白名单安全投影，例如稳定 ID、类型、展示名快照和必要的选区摘要。

禁止进入 Agent 输入的字段包括：

宿主绝对路径；
签名 URL、objectKey、Token、Cookie；
Provider 路由或内部请求信息；
完整 DOM 结构和任意元素属性。

验收标准

当前 master 无 @ 候选，本 Issue 完成后三个聊天入口均具备引用能力；
三个聊天入口使用同一引用编辑器和输入 DTO；
Agent 输入区提供 @ 按钮；
素材面板支持缩略图、搜索、类型筛选和多选；
输入 @ 可触发候选，并支持键盘选择和 Esc 关闭；
可以在文本中间插入多个引用；
引用标签前后可继续编辑中文自然语言；
删除引用后可重新编辑和再次插入；
输入法组合期间不误触发候选或提交；
同名资源通过稳定 ID 区分；
资源改名后引用身份不丢失，显示名可刷新；
资源删除或失效时发送前有明确错误提示；
普通无引用消息保持兼容；
资源卡提供 @引用，且不影响现有交互；
当前版本素材可插入 Agent 输入区；
运行画面可进入和退出点选模式；
Esc、再次点击入口和“退出点选”均可退出；
运行画面可选择元素、容器或整个窗口区域；
包含多个素材的区域不会被错误降级为单一素材；
实际提交请求包含稳定 ID 或结构化选区数据，而不是仅包含 @名称 文本；
Agent 输入不包含绝对路径、签名 URL、Token、Cookie 或完整 DOM；
相关组件测试、类型检查、编码检查和 git diff --check 通过；
完成桌面端和窄视口交互验证。

不在本 Issue 范围内

不新增素材存储系统；
不修改现有素材文件格式；
不新增平行资源画布；
不改变 Agent 权限边界；
不开放任意本地文件扫描或任意路径引用；
不实现完整浏览器开发者工具；
不改动与素材引用无关的生成、发布和运行时流程。

# AGC 聊天通用引用：素材 @ 面板、资源卡入口与运行画面区域点选 ## 需求背景 [《客户端画布与资源工作台需求》](https://kcnz41bksl1c.feishu.cn/wiki/N4KiwMFkGiwemFkbKU7cAXwxn9U) 第 9 节“素材点选和 @ 引用”要求 AGC 支持素材引用和运行画面点选。当前远端 `master` 尚没有 `@` 素材引用能力：聊天输入框没有 `@` 候选和按钮，也没有素材选择面板、资源卡 `@引用`、运行画面点选模式或结构化引用提交协议。仓库中已有可复用基础： - 项目 manifest 已包含稳定资源 ID、类型、媒体类型和项目相对路径； - 资源画布已有资源卡、选择、预览和依赖展示； - 首页已有 Lexical 富文本输入和内联附件芯片模型； - 运行模块已有受限本地预览 iframe，可在此基础上扩展受控检查协议。本 Issue 需要在这些现有能力上补齐通用引用系统，不做按 `@名称` 反向解析的文本方案。 ## 目标用户可以在 AGC 聊天输入中插入一个或多个结构化素材引用，并在引用标签前后自由编辑自然语言；提交时客户端同时保留用户文本和引用数据，Agent 只接收安全投影。引用入口共三类： 1. Agent 输入区 `@` 按钮和键盘 `@` 触发； 2. 资源画布资源卡和当前版本素材； 3. 运行画面区域点选。 ## 结构化引用协议先锁定统一输入 DTO，再实现各入口。聊天提交至少包含： ```text text: 用户可见自然语言 references: 结构化引用数组 ``` 素材引用至少包含： - 稳定资源 ID； - 资源类型； - 展示名称快照； - 可选来源：`asset-picker` / `resource-card` / `version-asset` / `runtime-picker`。来源仅用于展示和追踪，不参与资源解析。运行画面引用使用独立类型，例如 `runtime-region`，至少包含： - 运行预览或版本身份； - 区域摘要标识； - 元素类型、可见文本摘要、尺寸等白名单字段； - 可解析到的关联资源 ID 列表； - 展示名称快照。运行画面点选不得假设选区一定对应单个素材。它可能是单个素材元素，也可能是包含多个素材的容器、一块 UI 区域或整个游戏窗口。 ## 实现范围 ### 1. 通用引用编辑器抽取可复用的富文本输入组件，三个聊天入口共用： - 输入 `@` 后在当前光标处触发候选； - `@` 按钮打开素材选择面板； - 引用以芯片形式插入，芯片内部保存稳定 ID； - 支持在文本中间插入多个引用； - 支持在引用前后编辑中文自然语言； - 支持删除单个引用后重新编辑； - 输入法组合期间不误触发候选或提交； - Enter / Tab 确认，ArrowUp / ArrowDown 选择，Esc 关闭候选； - 引用数据与用户文本分开导出，不通过 `@名称` 反向解析。 ### 2. 素材选择面板 Agent 输入区提供 `@` 按钮，打开独立素材选择面板： - 素材缩略图； - 按名称和资源 ID 搜索； - 按类型筛选； - 多选； - 已选状态； - 无资源、无匹配和加载失败状态提示； - 键盘可操作； - 候选范围来自当前项目 manifest，不限制为固定前几项； - 界面做有界渲染，避免一次性渲染超大资源集合。缩略图复用现有资源预览读取和 object URL 生命周期管理，不新增平行素材存储。 ### 3. 资源画布与当前版本素材入口 - 资源卡工具栏增加 `@引用` 操作； - 点击后将该资源作为结构化引用插入当前 Agent 输入区； - 不改变资源卡现有选择、预览、拖拽和打开详情行为； - 运行画面下方当前版本素材也使用同一插入链路； - 以上入口与 `@` 面板共用同一引用协议。 ### 4. 运行画面区域点选 - 运行模块顶部提供“点选素材”入口； - 进入点选模式后，运行画面支持元素 hover 高亮和点击选择； - 选区可为元素、容器或整个窗口； - 能解析到 manifest 资源时记录关联资源 ID； - 无法一一映射时保留 `runtime-region` 引用，不伪装成素材引用； - 点选结果插入 Agent 输入区； - 再次点击入口、点击“退出点选”或按 Esc 均可退出； - 点选期间不修改游戏文件，退出后清理高亮和监听状态。实现应基于现有本地预览 iframe 的 origin 校验消息通道，新增受控检查协议；禁止把完整 DOM、任意属性或内部路径传给宿主。 ### 5. 提交前校验与安全投影提交前客户端必须重新校验引用： - 资源已删除或不可用：阻止发送，并提示用户移除或重新选择； - 资源改名：继续使用稳定 ID，刷新显示名快照； - 同名资源：按稳定 ID 区分； - 运行预览或版本失效：阻止发送旧区域引用，提示重新点选； - 普通无引用消息继续走现有聊天兼容分支。 Agent 只接收白名单安全投影，例如稳定 ID、类型、展示名快照和必要的选区摘要。禁止进入 Agent 输入的字段包括： - 宿主绝对路径； - 签名 URL、objectKey、Token、Cookie； - Provider 路由或内部请求信息； - 完整 DOM 结构和任意元素属性。 ## 验收标准 - [ ] 当前 `master` 无 `@` 候选，本 Issue 完成后三个聊天入口均具备引用能力； - [ ] 三个聊天入口使用同一引用编辑器和输入 DTO； - [ ] Agent 输入区提供 `@` 按钮； - [ ] 素材面板支持缩略图、搜索、类型筛选和多选； - [ ] 输入 `@` 可触发候选，并支持键盘选择和 Esc 关闭； - [ ] 可以在文本中间插入多个引用； - [ ] 引用标签前后可继续编辑中文自然语言； - [ ] 删除引用后可重新编辑和再次插入； - [ ] 输入法组合期间不误触发候选或提交； - [ ] 同名资源通过稳定 ID 区分； - [ ] 资源改名后引用身份不丢失，显示名可刷新； - [ ] 资源删除或失效时发送前有明确错误提示； - [ ] 普通无引用消息保持兼容； - [ ] 资源卡提供 `@引用`，且不影响现有交互； - [ ] 当前版本素材可插入 Agent 输入区； - [ ] 运行画面可进入和退出点选模式； - [ ] Esc、再次点击入口和“退出点选”均可退出； - [ ] 运行画面可选择元素、容器或整个窗口区域； - [ ] 包含多个素材的区域不会被错误降级为单一素材； - [ ] 实际提交请求包含稳定 ID 或结构化选区数据，而不是仅包含 `@名称` 文本； - [ ] Agent 输入不包含绝对路径、签名 URL、Token、Cookie 或完整 DOM； - [ ] 相关组件测试、类型检查、编码检查和 `git diff --check` 通过； - [ ] 完成桌面端和窄视口交互验证。 ## 不在本 Issue 范围内 - 不新增素材存储系统； - 不修改现有素材文件格式； - 不新增平行资源画布； - 不改变 Agent 权限边界； - 不开放任意本地文件扫描或任意路径引用； - 不实现完整浏览器开发者工具； - 不改动与素材引用无关的生成、发布和运行时流程。

suzmii self-assigned this 2026-09-07 10:52:28 +08:00

kdletters added the Kind/Feature label 2026-09-07 15:24:26 +08:00

kdletters commented

2026-09-07 17:43:46 +08:00

This was generated by AI during triage.

建议先把结构化引用协议锁定，再分别实现三个入口。输入模型至少应同时保留自然语言文本和 references 数组，每个引用使用稳定资源 ID、资源类型和展示名称快照；来源（聊天选择、运行画面点选、资源卡）可以作为可选字段，不能让来源决定解析方式。

还需要在发送前定义资源已删除、停用或版本变化时的行为，以及同名资源和改名后的显示规则。运行画面点选只能把资源的安全投影传给 Agent，建议明确投影白名单和服务端二次校验，禁止绝对路径、签名 URL、Token 等字段进入回合输入。三个聊天入口应共用同一输入 DTO，普通无引用消息继续走兼容分支。

验收建议补上：输入中间位置插入多个引用、删除后重新编辑、中文和同名资源、资源失效后的发送失败提示，以及桌面端和窄视口下的面板/键盘操作；同时用请求断言验证实际提交的是稳定 ID 而不是仅有 @名称。

> *This was generated by AI during triage.* 建议先把结构化引用协议锁定，再分别实现三个入口。输入模型至少应同时保留自然语言文本和 references 数组，每个引用使用稳定资源 ID、资源类型和展示名称快照；来源（聊天选择、运行画面点选、资源卡）可以作为可选字段，不能让来源决定解析方式。还需要在发送前定义资源已删除、停用或版本变化时的行为，以及同名资源和改名后的显示规则。运行画面点选只能把资源的安全投影传给 Agent，建议明确投影白名单和服务端二次校验，禁止绝对路径、签名 URL、Token 等字段进入回合输入。三个聊天入口应共用同一输入 DTO，普通无引用消息继续走兼容分支。验收建议补上：输入中间位置插入多个引用、删除后重新编辑、中文和同名资源、资源失效后的发送失败提示，以及桌面端和窄视口下的面板/键盘操作；同时用请求断言验证实际提交的是稳定 ID 而不是仅有 @名称。

suzmii changed title from ~~AGC 聊天支持素材点选与 @ 引用~~ to AGC 聊天通用引用：素材 @ 面板、资源卡入口与运行画面区域点选

2026-09-08 15:35:44 +08:00

suzmii commented

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

需求文档（飞书《GameAgent客户端画布与资源工作台 V3.0》）已完整落地，原先因文档未定型而拆分出来的这部分需求，现在合并到 Tracking Issue #309 统一处理。

本 Issue 覆盖的内容对应 #309 的 C4（聊天通用引用与点选）；
已有实现（三个引用入口、结构化 references、Rust 侧按 manifest 二次校验、runtime-region 兜底）保留在 feat/agc-chat-resource-mentions 分支，后续在 #309 下继续补齐：@ 面板两个页签、独立筛选状态、改名后显示名刷新、跨会话引用光标位置、点选改走 Phaser hitTestPointer。

本 Issue 关闭，后续讨论与进度统一见 #309。

需求文档（飞书《GameAgent客户端画布与资源工作台 V3.0》）已完整落地，原先因文档未定型而拆分出来的这部分需求，现在合并到 Tracking Issue #309 统一处理。 - 本 Issue 覆盖的内容对应 #309 的 **C4（聊天通用引用与点选）**； - 已有实现（三个引用入口、结构化 `references`、Rust 侧按 manifest 二次校验、`runtime-region` 兜底）保留在 `feat/agc-chat-resource-mentions` 分支，后续在 #309 下继续补齐：@ 面板两个页签、独立筛选状态、改名后显示名刷新、跨会话引用光标位置、点选改走 Phaser `hitTestPointer`。本 Issue 关闭，后续讨论与进度统一见 #309。

suzmii closed this issue

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

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: GenarrativeAI/Genarrative#293