diff --git a/docs/plans/2026-03-05-refactor-thread-upload-state-source-files-plan.md b/docs/plans/2026-03-05-refactor-thread-upload-state-source-files-plan.md deleted file mode 100644 index fcc6566b..00000000 --- a/docs/plans/2026-03-05-refactor-thread-upload-state-source-files-plan.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -title: refactor: remove auto attachment conversion and persist uploads in state -type: refactor -date: 2026-03-05 ---- - -# refactor: remove auto attachment conversion and persist uploads in state - -## Overview - -将聊天附件链路从“上传即转换为 markdown 并写入 state.files”重构为“上传即保存原文件并写入 state.uploads 元数据”。目标是把附件处理从预处理模式改为按需读取模式,避免在 agent 未使用文件前做不必要转换,并统一线程目录下的原始文件作为唯一事实来源。 - -## Problem Statement / Motivation - -当前实现在上传阶段存在较强耦合: -- 上传流程在 `src/services/conversation_service.py` 同时做文件保存、可选 markdown 转换、状态同步。 -- state 写入依赖 `attachment.markdown -> files[path].content`(`conversation_service.py`、`chat_stream_service.py` 的 `_build_state_files`)。 -- 中间件提示词依赖 `attachments` 列表,但 UI 和状态还混用了 `virtual_path/original_virtual_path/file_path/markdown/truncated` 等字段。 - -这导致: -- 上传阶段成本高(转换前置)。 -- 状态语义混乱(`attachments` 既是展示元数据又承载转换结果)。 -- 后续扩展“按需解析/按类型处理”时改动面过大。 - -## Proposed Solution - -采用“上传原文件优先”的单一路径: - -1. 上传阶段不再触发自动 markdown 转换(移除 `doc_converter` 依赖链路)。 -2. 原文件统一保存到线程目录 `.../user-data/uploads`,并同步到 sandbox 同路径。 -3. LangGraph state 新增并使用 `uploads` 作为附件事实来源(每个条目包含文件标识、路径、大小、类型、时间等必要元数据)。 -4. `attachments` 退出状态主链路,`uploads` 成为唯一状态来源。 -5. agent 读取文件内容统一通过现有文件工具(如 `read_file`)在需要时访问 `uploads` 中声明的路径。 - -## Key Decisions (Locked) - -- 不采用双写:不同时维护 `attachments` 与 `uploads` 两套状态事实来源。 -- 单次切换:本次重构同时更新后端与前端读取路径,直接切到 `uploads`。 -- 不维护 `state.files` 镜像:停止由附件内容派生 `files`,避免冗余状态与同步复杂度。 - -## Technical Considerations - -- 需要统一以下使用点的数据语义: - - `src/services/conversation_service.py`:上传、删除、state 同步。 - - `src/services/chat_stream_service.py`:`get_agent_state_view` 的回填逻辑。 - - `src/agents/common/middlewares/attachment_middleware.py`:提示词来源从 `attachments` 迁移/对齐到 `uploads`。 - - `web/src/components/AgentChatComponent.vue` 与附件组件:字段从 `original_virtual_path/file_path` 对齐到单一上传路径。 -- 兼容策略:不做运行时兼容层,不做双写;接口与前端在同一版本内完成同步切换。 - -## Acceptance Criteria - -- [ ] 上传任意受支持大小文件后,不再触发自动 markdown 转换。 -- [ ] 原文件可在线程 `uploads` 目录中稳定落盘并可下载。 -- [ ] state 中存在 `uploads`,且能完整表达当前线程附件集合。 -- [ ] agent 在无预转换 markdown 的前提下,仍可基于上传文件路径正常执行读取流程。 -- [ ] 删除附件后,state.uploads 与线程目录保持一致。 -- [ ] 前端附件列表与提及能力在新数据结构下行为一致(无回归)。 - -## Success Metrics - -- 上传接口平均耗时下降(相对当前版本)。 -- 上传失败率不高于当前基线。 -- 相关会话流程无新增 P1 回归(上传、查看、下载、删除、提及)。 - -## Dependencies & Risks - -- 风险:前端仍依赖旧字段(`markdown/truncated/original_virtual_path`)导致展示回归。 -- 风险:`get_agent_state_view` 仍按旧逻辑回填 `files`,可能与 `uploads` 语义冲突。 -- 风险:历史会话中仅存在旧 `attachments` 结构的数据,在切换后可能不再自动注入到模型上下文。 - -## SpecFlow Gaps / Edge Cases - -- 同名文件覆盖策略(覆盖、重命名、拒绝)需明确。 -- 无扩展名文件与非常规 MIME 文件在 UI 展示规则需明确。 -- 历史会话首次读取时是否做一次性状态归一化需明确。 - -## References & Research - -- `src/services/conversation_service.py` -- `src/services/chat_stream_service.py` -- `src/agents/common/middlewares/attachment_middleware.py` -- `src/repositories/conversation_repository.py` -- `server/routers/chat_router.py` -- `web/src/components/AgentChatComponent.vue` - -## Scope Boundaries - -- 本次不包含上传后自动解析(markdown/OCR)链路;若需要解析,后续按“显式触发”另开能力。 -- 本次不引入运行时兼容分支(如旧字段回填、双状态同步)。 -- 历史数据迁移若需要,采用一次性离线迁移,不在在线请求链路增加复杂度。