---
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）链路；若需要解析，后续按“显式触发”另开能力。
- 本次不引入运行时兼容分支（如旧字段回填、双状态同步）。
- 历史数据迁移若需要，采用一次性离线迁移，不在在线请求链路增加复杂度。