[Feature] 跨格式产物协作：选区引用、批注、可视化编辑与 Agent 修改审阅

[AlphaCatMeow]

Affected area

Desktop UI (agent-gui / React)

同时涉及共享 agent-ui、Gateway WebUI、文件读写和会话上下文。桌面端与 WebUI 都应支持核心流程；本机应用打开、下载和远端文件访问按各端实际能力提供。

Problem statement (what should this solve)

希望在 LiveAgent 中直接完成产物的审阅与修改：打开文件，选中需要处理的内容，自己做简单调整，或让 Agent 根据选区和批注意见修改，再对照结果继续审阅。

目前项目已有多格式文件预览、源码编辑和代码行引用，也有图片缩放、旋转、保存等操作。仍需要补齐的是跨格式的内容定位、批注、修改和结果核对。比如：

• 看 HTML 报告时，只想改一个标题或卡片颜色，却需要切到源码或重新描述位置。
• 看 PDF、图片或演示稿时，“右下角这块”“第 5 页第二张图”缺少可以直接交给 Agent 的准确引用。
• 审阅长文档时，需要连续标出多处意见，集中交给 Agent 处理，并知道哪些已经改完。
• 希望用表格里的数据更新演示稿，同时参考另一张图片的配色，需要明确哪份是修改目标、哪份提供数据、哪份只是参考。
• 用户正在编辑文件时，Agent 也可能写入同一文件；如果缺少版本核对，容易覆盖修改，旧批注也可能落到错误位置。

本 Issue 提出一个完整的“产物选取、批注与修改”需求，作为总需求跟踪。下面保留全部目标能力，并给出可拆分的实施阶段。阶段一完成不代表整个需求完成；实现顺序和子 Issue 划分由维护者确认。

Proposed behavior

1. 统一操作流程

从文件树、对话中的产物链接等现有入口打开文件。进入同一文件时，选区、版本和批注应能正确对应，不因入口不同生成互不相关的状态。

1. 用户在预览中选择文字、对象、区域、单元格或时间范围。
2. 选区附近出现当前格式可用的操作，例如“批注”“引用到对话”“让 Agent 修改”，以及简单编辑操作。
3. 选择“让 Agent 修改”后，将选区引用放入输入框，用户补充要求并主动发送；选取和批注本身不自动触发模型调用。
4. Agent 根据文件版本、选区和要求执行解释、核查或修改。
5. 修改结果关联回原请求和批注，用户可以查看前后差异、接受结果或继续提出意见。

预览、选取和编辑的操作含义应清楚区分。阅读时保留正常的文本复制、链接访问和媒体播放；进入选取或编辑模式后，再接管对应手势。桌面鼠标、触屏和键盘均应有可用入口，不能只靠 hover。

示意：

产物预览 → 选中内容 → 直接编辑 / 添加批注 / 引用到对话
                                      ↓
                             用户补充要求并发送
                                      ↓
                             Agent 处理选定内容
                                      ↓
                          前后对照 → 确认 / 继续修改

2. 各类产物的完整目标范围

以下是目标能力。现有预览支持不等于已经具备原格式编辑能力；每个格式应分别声明可选取、可批注、可直接编辑和可由 Agent 处理的范围。

产物	可选取内容	直接操作	Agent 处理示例与边界
HTML	文字、元素、父级容器、页面区域	静态 HTML 的文字、字体颜色、背景色、边框色、字号、加粗等；后续支持复制、删除、同级移动及 SVG 文字	“重排这张卡片”“修改手机布局”；动态页面的运行时 DOM 不等于源码，不能直接序列化后当作源文件保存
Markdown	标题、段落、列表、表格、代码块	修改文字、标题级别、强调样式和任务项；保留源码编辑入口	“缩短这一段”“把列表整理成表格”；可视化改动应写回 Markdown，保留未涉及的结构与语法
图片	整图、矩形区域、标记位置	裁剪、旋转、标注、批注；区分仅改变查看方向与实际修改文件	“修改这块日期”“去掉选区中的对象”“解释图中内容”；局部生成或修图依赖实际可用的模型或工具
PDF	页码、文字选区、页面区域	高亮、批注、页面旋转；明确批注保存在应用内还是写入文件	“核查这一段”“按批注修改源文档”；扫描件没有文本层时支持区域引用，OCR 结果需标明，不能假定可直接回写原文字
表格	工作表、单元格、区域、行列、图表	受支持范围内的值、显示格式和公式编辑	“检查 D12:D28 的公式”“用这组数据生成图表”；同时保留公式与显示值的区别，不能把格式化显示值当作源公式
Word / DOCX	标题、段落、表格、图片、页面区域	批注及受支持范围内的文字修改	“统一术语”“重写章节”“生成修订版”；预览中的 HTML 不可直接作为 DOCX 回写，未修改部分的样式、图片和文档结构需要保留
演示稿 / PPTX	页、文本框、图片、图表、页面区域	批注、受支持对象的文字和位置调整	“重做第 5 页”“统一多页样式”“替换配图”；需要补齐演示稿预览与对象定位，无可靠对象信息时明确降级到页或区域
音频	时间范围、对应转写文本	播放选段、时间批注、设置裁剪范围	转写、总结、翻译、降噪或导出片段；保留原始时间定位，区分转写文本和实际音频编辑
视频	时间范围、单帧、某时刻的画面区域	时间批注、片段播放、设置裁剪范围	修改字幕、提取片段、分析镜头、生成或执行剪辑方案；单帧区域不自动表示跨帧对象跟踪
代码与纯文本	行号、函数、配置项、日志片段	沿用现有源码编辑、查找替换和代码引用	修复、重构、解释或更新配置；与其他格式共享引用、批注和版本语义

复杂的排版、图像处理和媒体编辑允许通过已有工具、Skills 或外部应用完成。界面只展示确实可用的能力；无法直接编辑时，仍可提供引用、批注或打开源文件。

3. 可以返回原位置的选区引用

引用在输入框和历史消息中显示为可点击的卡片，至少包含文件名、可读的位置说明和内容摘要。例如：

• 季度报告.md · 风险章节 · 第 2 段
• 活动海报.png · 右下角选区
• 预算.xlsx · 预算表!D12:D28
• 方案.pdf · 第 8 页 · 选中文字
• 产品介绍.pptx · 第 5 页
• 访谈.mp4 · 02:15–02:48

用户能检查、删除、复制引用，并在切换会话或重新打开文件后返回对应位置。无法返回时，说明文件已移动、版本不一致或缺少访问权限，保留原引用摘要。

引用需要记录文件所属工作区或远端来源、选取时的版本，以及格式对应的定位信息：文本范围与上下文、页面与区域坐标、工作表与单元格、幻灯片与对象、媒体时间范围等。图片和页面区域采用文件自身的坐标，不能仅记录当前屏幕坐标；缩放、滚动或旋转预览后仍应指向同一内容。

文件变化后先核对版本。能够可靠重新定位时更新锚点，否则显示“引用已过期”并要求重新选取，不得静默套用到附近内容。HTML 元素也不能只依赖一个易变的 CSS selector。

4. 批注列表与集中处理

用户可以连续添加多处批注，编辑、删除和选择其中一组加入对话。批注与文件版本、选区和对应的 Agent 请求关联，并保留到重新打开时。

建议至少区分“待处理”“处理中”“待用户确认”“已确认”“需要说明”。Agent 报告完成后进入待确认状态，由用户核对结果；无法完成或只完成部分要求时说明原因。重新修改后允许再次打开已处理的批注。

例如审阅演示稿时，先标注第 1 页缩短标题、第 3 页核查数字、第 5 页调整排版，再一次发送：“处理这些意见，保持现有配色和字体。”用户应能逐项查看修改结果，无须从整段回复中猜测每条意见是否落实。

5. 多产物引用与源文件关联

同一条消息允许引用多个文件或选区，并明确其用途：修改目标、事实或数据来源、风格参考。只有参考用途的文件不应被顺手修改。

示例：选择 预算.xlsx 的数据区域、汇报.pptx 的第 5 页和一张图片的配色区域，发送：“用这组数据更新这一页图表，配色参考这张图，保留演示稿字体。”

允许用户建立预览产物与源文件的关联，例如 PDF 对应 DOCX、Markdown 或 PPTX。用户在 PDF 上批注后，Agent 修改关联的源文件，再重新生成 PDF，并报告生成结果。关联应可查看、修改和解除；不能只凭同名文件自动决定写入目标。源文件或生成工具缺失时，保留批注并说明限制。

6. 草稿、保存、冲突与恢复

简单编辑应即时反馈，支持撤销、重做、保存、另存为以及放弃草稿。明确区分未保存、保存中、已保存、保存失败和版本冲突；“还原”要说明恢复到哪个版本。

• 预览运行状态、原始文件、编辑草稿和导出副本应分开管理，不把辅助脚本、选框和批注 UI 写入产物。
• Agent 或外部程序修改文件后，不能用旧草稿直接覆盖。复用现有内容哈希和修改时间检查，提供查看差异、重新载入、另存草稿等处理入口。
• 切换文件、关闭预览或应用重启后，应能按已定义的草稿恢复策略找回未提交编辑；大文件可单独限制，但必须给出明确提示。
• 批量修改、取消、超时或连接中断时，保留已完成项与未完成项。失败不能被显示为全部成功；重试和重复点击不得产生重复提交或重复覆盖。
• 文件回退前同样检查当前版本，只恢复此次目标文件的指定版本，不回退用户后续无关改动。

7. 按格式核对修改结果

修改结果应能回到对应文件和批注，并提供适合该格式的对照：

格式	结果核对方式
文本、代码、Markdown、HTML	源码或文本差异，并可查看渲染结果
图片	原图与修改图并排或切换对照，保留选区位置
表格	明确哪些单元格的值、公式或格式改变
PDF、DOCX、PPTX	页或对象级前后对照；无法精确归因时说明限制
音视频	前后片段播放、字幕或转写差异、时长变化

用户确认的是具体文件版本。之后文件再次变化时，不能继续把新版本标成已确认。已有检查点或文件历史可复用，但普通文件和非 Git 工作区也需要可用的恢复方式。

8. 导出与交付

保留原格式保存和另存副本的区别，明确输出位置。HTML 可提供将本地图片、样式等资源打包为便携副本的能力；不能只转换成功加载的 <img> 就声称完全离线可用。资源缺失、跨域不可访问或仍依赖网络时，列出未打包项。

文档、表格和演示稿导出后应能重新打开，并检查内容、公式或版式是否保留。批注是否随文件导出应由用户选择，并说明格式支持范围；应用内部的审阅记录不应未经说明写入交付文件。

9. 隔离、模型能力与双端一致性

HTML 保持现有沙箱隔离，编辑通信不应通过给不可信页面开放宿主同源或文件系统权限实现。文件、引用内容和批注都属于用户提供的上下文，不自动成为可覆盖用户指令的系统指令。

引用准备在本地或对应 Gateway 完成，按需要提取文本、截图、数据或片段；发送前能看清将提供给模型的范围。仅选取或添加批注不上传整个文件。模型不支持图片、音视频或目标文件格式时，明确提示可用的文本提取、转写或其他工具方案，不能悄悄丢弃选区。

桌面与 WebUI 共享核心交互和数据语义。远端文件由所属 Gateway 读写，不能与浏览器本机同名文件混淆；断线后恢复到正确工作区、会话和文件版本。下载、系统应用打开和剪贴板操作允许按平台能力有所不同。

10. 建议分阶段交付

阶段	交付范围	阶段完成条件
A：跨格式选取与引用	建立引用和版本基础，接入 Markdown/文本、HTML、图片、PDF；支持引用卡片、返回选区和基础批注	桌面与 WebUI 均可选取、发送、恢复引用；过期选区和不支持格式有明确反馈
B：编辑与审阅	静态 HTML/Markdown 轻量编辑，图片标注与裁剪等受支持操作；批注集中处理、草稿、冲突检查、结果对照与恢复	用户能完成一轮手动或 Agent 修改，并逐项检查、确认或恢复
C：结构化文档与媒体	表格、DOCX、PPTX、音视频的格式适配；多产物引用、源文件关联与重新生成、完整导出	各类选区能可靠定位，处理能力与限制明确，输出文件和恢复流程通过验证

这些是完整需求的拆分建议，不要求放进一个 PR。每种格式可以进一步拆成“选择与引用”“直接编辑”“Agent 工具接入”“结果对照”子任务，避免把一个只能预览的格式标成已支持全部编辑。

11. 验收场景

以下为目标验收要求，尚未实施或运行。实施时应补充具体样例文件及各端执行结果；自动化专用检查单独记录，不计作人工验收通过。

场景	触发与操作	预期结果
各格式正常选取	按格式矩阵分别选文字、元素、图像区域、页、单元格、对象和时间段，加入对话后再次点击引用	正确显示来源与位置，返回原选区；按阶段明确已支持项
预览手势	阅读、播放后进入选取模式，再退出；用鼠标、键盘和触屏操作	选取不破坏正常复制、滚动、链接和播放；无 hover 依赖
选区边界	缩放、旋转、滚动、跨页，选择空区域或最小片段	合法选区保持准确，非法或超界选区被明确处理
静态 HTML 编辑	改文字和颜色，撤销、重做、保存，再重新打开	内容与渲染一致，保存文件中无预览辅助代码
动态 HTML	运行依赖脚本的页面并尝试编辑或引用	保留隔离；对无法回写源码的操作说明限制
Markdown 与结构化文档	改段落、表格值或受支持对象后重新打开	未涉及内容保留；公式、样式或结构损失能被发现并报告
多处批注	在同一文件标三处意见，选择其中两处交给 Agent	仅处理所选意见，逐项关联结果，完成后待用户确认
多文件引用	将表格设为数据来源、PPT 设为目标、图片设为风格参考	修改目标明确，参考文件保持原样，引用可追溯
源文件关联	在 PDF 批注后修改关联源文件并重新生成	输出关联到对应源版本；缺源文件或生成失败时保留意见
版本冲突	保留手动草稿，同时让 Agent 或外部程序改同一文件，再保存	阻止旧版本覆盖，提供差异与草稿处理入口
引用失效	添加引用后改动、移动或删除文件	可靠定位或明确提示失效，不误改其他内容
取消、超时与重复操作	处理中取消或超时，再重试、重复点击提交	区分完成与未完成部分，无重复修改，草稿与批注保留
远端断线与重启	WebUI 处理中断线后重连，或关闭应用后恢复	返回正确工作区和版本，恢复状态，不将旧确认套用到新文件
缺少处理能力	使用不支持图片的模型、无文本层 PDF、缺少媒体工具或只读文件	说明限制并提供实际可用的降级路径，不伪报成功
大文件与异常文件	打开大文档、超长媒体、损坏文件或缺资源 HTML	有明确加载、限制和错误反馈，不阻塞整个会话
结果对照与回退	核对差异、确认，再尝试恢复此前版本	对照与确认关联正确版本；回退前检查后续改动
导出	导出修改文件或便携 HTML，重新打开；检查公式、样式和资源	文件可用，未打包资源及格式限制明确，无内部编辑 UI

Estimated change scope

以下为基于当前结构的候选范围，不预设最终实现或承诺工期：

• crates/agent-ui/src/components/workspace-editor/：预览、格式适配、编辑草稿、批注和对照界面。
• crates/agent-ui/src/lib/chat/mentionReferences.ts 及输入框、消息渲染：扩展产物选区引用，保留现有文件与代码引用行为。
• crates/agent-gui/src/agent-ui-adapters/、crates/agent-gateway/web/src/agent-ui-adapters/：桌面和浏览器的保存、剪贴板、外部打开等差异。
• crates/agent-gui/src-tauri/、crates/agent-gateway/：按需补充版本化读写、上下文提取、批注持久化和格式处理接口，复用现有冲突检测。
• 根据格式评估预览和编辑库；PDF 文字层、PPTX 对象定位、DOCX 保真回写及媒体处理需单独验证。公共 UI 放在共享层，镜像范围内的文件保持同步。

实现后的验证应包含相关 GUI/WebUI build、lint、前端测试、受影响的 Rust/Go 测试、Mirror Check 和真实客户端验收。对于文档和媒体，另外检查导出文件，而不只检查界面操作成功。

Alternatives considered

• 继续用截图和文字描述位置：无需开发，但缺少版本、结构和可返回的位置，批量审阅与数据引用仍需要大量手工整理。
• 只增加 HTML 可视化编辑：能解决静态页面的小改动，覆盖不到报告、图片、表格和媒体的审阅需求。
• 直接嵌入一个完整 HTML 编辑器：可参考点击编辑、选区工具条和撤销等交互，但其 DOM 操作、脚本权限和整页序列化方式不适合直接套到所有格式。
• 全部交给外部编辑器：复杂格式仍应支持此路径，但选区、意见和修改结果需要回到 LiveAgent 对话中，不能丢失上下文。
• 只做 Agent 修改，不提供直接编辑：能减少格式编辑器的投入，但改字、调色等小操作仍需模型调用，因此建议保留有限、可靠的本地编辑。

Related work

检索了已有 Issue 和 PR，暂未发现覆盖上述完整流程的同类提案。以下工作可作为基础，已有能力不应重复实现：

• Add workspace file previews #65：多格式工作区文件预览。
• feat(ui): upgrade workspace image preview with anchored pan/zoom, rotation, file actions, metadata, and fullscreen #461：工作区图片缩放、平移、旋转、文件操作、信息面板与全屏。
• [Bug] 工作区文件预览中 Markdown 文档无法选中/复制文本 #430 / fix(ui): 工作区 Markdown 预览支持选中复制文本 #431：Markdown 预览支持文本选中与复制。

建议先确认总需求和阶段 A 的范围，再按格式与依赖拆分子 Issue，后续 PR 分别关联已确认的子需求。

Pre-submit checklist

• I searched existing issues and pull requests and found no duplicates.
• This proposal is focused on a single feature or improvement.
• I understand a PR should come after this issue is confirmed by maintainers, otherwise it will be converted to draft.