goodbuddy/docs/features/document-processing/chat-attachments-technical-design.md

聊天附件技术说明

产品规则见 PRD 的聊天附件入口，输入区布局与反馈遵循 UI 设计系统。本文说明本地文件选择、文件粘贴和截图粘贴的实现。

文件导入链路

App.tsx 在 textarea 的 paste 事件中同步读取 clipboardData.files。没有文件时 保留浏览器默认文本粘贴。有文件时阻止默认插入，并通过 preload 的 context.getFilePath(file) 调用 Electron webUtils.getPathForFile。

有本地路径的文件调用 context.importFiles(paths)，经 context:import-files IPC 到 Main。IPC 先验证可信 sender，再使用共享 contextImportFilesSchema 校验输入。 没有本地路径的截图沿用 context.addPastedImage；无路径的非图片文件和混有无路径项目 的本地文件批次显示可处理的错误，不静默丢弃项目。

ContextManager.selectFiles 只负责文件对话框，再调用与粘贴共用的 importFiles。 这个方法完成路径规范化、格式及大小检查、文本读取、图片转换、文档解析与上下文暂存。 任一文件失败时删除本批次已经暂存的项目，保留之前的附件。文件系统错误不向 Renderer 暴露绝对路径。

两种文件入口均发送 context:file-selection-progress。Renderer 共用正在导入状态、 附件上限处理和附件清理逻辑，解析期间禁用附件按钮并阻止发送。成功结果加入发起操作的 会话草稿；发送时通过已有 contextIds 和 ContextManager.enrichRequest 生成请求上下文。 本次变更不修改 Agent、远端协议或 Runtime 的附件消费实现。

PPTX 图片识别与 OCR 生命周期

产品策略与限制分别见 PPTX 图片流程、 OCR 空闲资源回收。

DocumentParsingService 在非快速工作流中使用 knowledge/pptx-parser.ts 读取 演示文稿顺序、幻灯片文字、图片关系和内嵌图片。Office ZIP 读取复用 document-parser.ts 的条目数量、单条目及总展开大小检查；不读取工作区中的关联文件。 每张引用图片通过现有 DocumentOcrBroker 的图片请求契约，进入生产 document-ocr-bridge.ts 和 WASM Worker。结果合并时保留原生文字，附上幻灯片页码、 图片定位及 OCR 置信度，诊断中的 OCR 页数按页码去重。

Bridge 用待完成请求计数判断队列是否空闲，正常完成后安排一次空闲计时； 新请求和 terminateWorker 均清除计时。到期通过 Worker.terminate() 释放整个推理环境， 而不是只清空 JavaScript 引用或反复触发垃圾回收。此机制由 PDF 与 PPTX 共用， 不增加 IPC、持久化设置或模型安装状态。

解析与回收发生在 Desktop 的 Main/Renderer，gbagent 不运行此 OCR Worker。 远程 Runtime 消费的仍是 Desktop 已提取的附件文本，没有单独的 Agent 解析器或 需要同步修改的远程 OCR 生命周期。

Electron 验证

2026-09-15 在 Windows 的 Electron 43.2.0 上，从当前源码构建隔离输出并启动完整应用， 使用独立用户数据目录，保持 sandbox: true、contextIsolation: true。

已实际验证：

• Windows Shell.Application 的文件 copy verb 生成系统剪贴板后，原生粘贴事件提供 File 和有效路径，TXT 出现在聊天附件区。
• CF_HDROP 同时携带 TXT、DOCX 时，两个文件经生产 preload、IPC 和解析器成为附件； DOCX 发出 reading、parsing 进度，包含正确文件名及 2 / 2 批次序号。
• 普通文本原生粘贴进入草稿，后续文件粘贴保持文字不变。
• ZIP 经生产导入路径报出不支持类型，已添加附件仍在。
• 系统图片剪贴板产生的 image.png 没有本地路径，仍通过截图入口生成图片附件。

以上使用原生 webContents.paste()，未伪造 DOM 粘贴事件或替换附件实现。Windows Shell 复制测试没有操纵资源管理器窗口中的键盘。产品未增加 Win32 剪贴板读取或兼容代码。 探测程序的原生调用仅用于构造文件剪贴板和保存、恢复测试前的剪贴板对象；最终探测的 OleSetClipboard、OleFlushClipboard 均返回成功。早期一次探测的恢复调用返回错误， 无法追溯确认该次剪贴板是否完整恢复。

macOS、Linux 文件管理器的实际剪贴板行为尚未在本次环境验证。没有发起模型调用；附件 进入发送请求的 contextIds 由 Renderer 回归测试验证，完整文档内容进入请求由生产 ContextManager 的真实文件解析测试验证。

自动检查

聚焦用例位于 src/main/context-manager.test.ts、src/main/ipc.test.ts、 src/preload/context-files.test.ts、src/shared/context-contracts.test.ts 和 src/renderer/src/App.test.tsx，覆盖多文件、进度、重复粘贴、发送上下文、错误与草稿保留、 大小及数量限制、批次回滚、可信 sender、输入契约和截图/文本回归。

npx vitest run src/main/context-manager.test.ts src/main/ipc.test.ts src/preload/context-files.test.ts src/shared/context-contracts.test.ts src/renderer/src/App.test.tsx
npm test
npm run typecheck
npm run lint

本次最终拆分检查通过 6 项附件相关 Renderer 用例和 160 项 Main、IPC、preload、契约及 沙箱用例，类型检查与 lint 通过。完整 npm test 运行结果为 4214 项通过、67 项跳过、 6 项窗口恢复用例失败；这些用例属于并行修改的 window.test.ts，随后该文件单独复跑 10 项全部通过。本次没有再次完整重跑全仓测试。

2026-09-15 PPTX OCR 与空闲回收验证

在 Windows x64、Electron 43.2.0 上，从本次源码构建独立输出，使用独立用户数据目录和 本机已安装的 PP-OCRv6 Tiny 模型完成真实验证。测试仅替换系统文件选择对话框的返回路径， 保留生产 UI、preload、IPC、ContextManager、解析服务、OCR Broker 与 WASM Worker， 未替换解析或推理实现。

• 从“添加附件”一次导入 4 份图片型 PPTX，共 40 页；4 个附件均成功显示，连续处理期间 仅创建 1 个 OCR Worker。
• 队列空闲后观察到 Worker 被终止。每 5 秒读取 Electron app.getAppMetrics()： Renderer 工作集采样高点为 733,492 KiB（约 716 MiB），回收后为 162,716 KiB （约 159 MiB），启动基线约 163 MiB。该结果是本次设备与文件上的测量，不是固定内存承诺。
• 回收后，通过生产 context.importFiles 再导入一份 9 页 PPTX；新建第 2 个 Worker， 9 页均返回非空文字，共 2,462 字符，附件成功生成。
• 本次合计 49 次本地图片 OCR 请求，文本模型调用 0 次；没有发送聊天消息，也没有将文件 交给云端模型。未修改源文件。未在 macOS、Linux 或其他 OCR 模型档位上做本次实测。

新增聚焦回归覆盖 PPTX 关系与顺序、各场景路由、原生文字合并、快速模式、页数上限、 OCR 错误和取消；Worker 回归覆盖空闲到期、连续请求复用、队列保护、关闭清理与立即取消。 空闲回收后重新加载也在真实模型路径上验证，不能只用模型配置检查代替。

最终检查：npm test 4,293 项通过、67 项跳过；npm run typecheck、 npm run lint 通过。当前源码的隔离 Electron 生产构建通过；文档的 10 个相对文件链接 均有效。测试应用已关闭，包含附件草稿的独立用户数据目录已删除，原文件和原模型安装未改动。