---
date: 2026-06-23
topic: document-processing-capability
---

## Summary

为 AgentKit 增加文档处理能力，v1 聚焦 Word/Excel/PDF 三种格式的创建和读取。通过 DocumentService 统一封装所有文档操作（内部调用 MCP Document Tools 或自研模块），Agent 工具和前端 REST API 共用同一套业务逻辑。生成的文档保存在服务器并持久化元数据，对话中返回文件卡片，同时在右侧面板展示当前对话的文档/附件列表供快速查看和下载。

## Problem Frame

当前 Agent 的工具集（memory、shell、search、web_crawl 等）没有任何格式化文档处理能力。用户需要生成报告、合同、数据表等格式化文档时，Agent 只能通过 shell 工具用命令行创建纯文本文件，无法满足实际办公需求。

项目已有完整的 MCP 集成基础设施（`MCPClient` + `MCPTool` + `MCPManager`），可以连接外部 MCP Server。社区有 Python 文档处理 MCP Server（MCP Document Tools），可能支持 Word/Excel/PPT 的创建和读写——但功能覆盖度尚未验证，是本方案的关键风险。

剩余的缺口是：MCP Document Tools 的 PDF 只读（不能创建 PDF），模板填充需要专门的 Office XML 感知库（Jinja2 不能直接用于 Office 文档），以及前端需要新的 UI 组件来展示和交付生成的文档。

## Key Decisions

- **DocumentService 统一封装所有能力（方向 A）** — DocumentService 作为唯一业务逻辑层，内部调用 MCP Document Tools（Word/Excel）或自研模块（PDF/模板填充）。Agent 工具和前端 REST API 都是 DocumentService 的薄封装，不直接暴露 MCP 工具给 Agent——这确保两个入口行为一致，且 Agent 工具的 input_schema 可定制。
- **Agent 生成结构化内容，Service 负责格式映射** — Agent 生成 Markdown 格式的结构化内容（标题、段落、列表、表格），DocumentService 负责将 Markdown 映射到目标格式（Word 段落样式、Excel 单元格、PDF 排版）。Agent 不直接操作 Office XML。
- **模板填充是自研部分，v1 只支持 Word** — Jinja2 不能直接用于 Office 文档（XML 结构会被破坏），需要 `python-docx-template` 库处理 Word 模板。Excel/PPT 模板填充 defer 到 v2。
- **v1 聚焦三种格式** — Word/Excel/PDF 创建 + 读取。PPT 创建、Office→PDF 转换、PDF 合并/拆分 defer 到 v2（依赖未验证或独立性强）。
- **对话内文件卡片 + 右侧面板双交付** — 生成的文档不仅在对话消息中返回文件卡片，同时在右侧面板维护当前对话的文档/附件列表，用户随时可查看或下载。
- **Jinja2 占位符语法 + 沙箱化** — 模板填充使用 Jinja2 语法（`{{variable}}`），但必须使用 `SandboxedEnvironment` 防止 SSTI 攻击。

## Requirements

### 文档处理能力

- R1. 支持创建 Word 文档（.docx），Agent 生成 Markdown 内容，DocumentService 映射为 Word 格式（标题、段落、列表、表格）。
- R2. 支持创建 Excel 表格（.xlsx），Agent 生成结构化数据（JSON 或 Markdown 表格），DocumentService 映射为 Excel 单元格。
- R3. 支持创建 PDF 文档，从零生成（自研，reportlab），Agent 生成 Markdown 内容，DocumentService 映射为 PDF 排版。
- R4. 支持读取/解析已上传的 Word/Excel/PDF 文档内容，用于 Agent 理解和分析（复用现有 `DocumentLoader`）。

### Agent 工具集成

- R5. Agent 通过工具调用触发文档创建，工具参数包括格式（word/excel/pdf）、内容（Markdown）、模板（可选）。
- R6. Agent 工具调用后，生成的文档自动保存到服务器并返回文件元信息（文件名、路径、下载 URL、大小）。
- R7. Agent 工具的 input_schema 清晰描述参数，LLM 能正确选择格式和操作。
- R8. Agent 工具不直接调用 MCP Document Tools，而是通过 DocumentService 间接调用——确保前端和 Agent 行为一致。

### 前端界面

- R9. 前端有独立的文档处理入口（页面或面板），用户可直接选择格式、填写内容、上传模板，不依赖对话。
- R10. 前端文档处理页面调用与 Agent 工具相同的 DocumentService，逻辑一致。

### 文件存储与生命周期

- R11. 生成的文档保存在服务器本地文件系统（复用现有 `data/uploads/` 基础设施）。
- R12. 每个生成的文档有唯一的下载 URL，通过下载 API 获取。
- R13. 文件名使用 UUID + 原扩展名存储，防止路径遍历和命名冲突。
- R14. 文档元数据（文件名、格式、大小、生成时间、关联对话 ID）持久化到数据库，支持跨会话查询。
- R15. 文档与对话的关联关系持久化——刷新页面或切换对话后，右侧面板仍能显示该对话的文档列表。
- R16. 文档过期清理策略（如 7 天自动清理），避免磁盘空间无限增长。

### 对话中文档展示

- R17. Agent 生成文档后，对话消息中返回文件卡片，显示文件名、格式图标、大小、下载按钮。
- R18. 文件卡片是新的消息渲染类型，当前 chat 消息只支持文本/tool_calls，需新增文件渲染层。

### 右侧文档/附件面板

- R19. 右侧面板展示当前对话中所有生成的文档和用户上传的附件，按时间排序。
- R20. 面板中每项显示文件名、格式图标、生成时间，支持点击下载。
- R21. 面板内容随对话实时更新——Agent 生成新文档时自动出现在列表中。
- R22. 面板可折叠/展开，不占用对话区域空间。

### 模板填充

- R23. 用户可上传 Word 文档模板，Agent 识别模板中的 Jinja2 占位符变量（`{{variable}}`）并填充数据。
- R24. 模板填充支持基本 Jinja2 控制结构（条件 `{% if %}`、循环 `{% for %}`），覆盖常见的文档动态内容需求。
- R25. 模板填充使用 `python-docx-template` 库处理 Office XML 结构，确保填充后文档格式不被破坏。

### 安全

- R26. Jinja2 模板填充使用 `SandboxedEnvironment`，防止 SSTI（服务端模板注入）攻击。
- R27. 文档下载 API 需要认证，未认证请求返回 401。
- R28. 文件大小限制（生成文档不超过 50MB，上传模板不超过 50MB）。

## Key Flows

- F1. 对话中触发文档生成
  - **Trigger:** 用户在对话中要求生成文档（如"帮我生成一份周报"）。
  - **Actors:** 用户, Agent, DocumentService, MCP Document Tools / reportlab
  - **Steps:** Agent 理解需求 → 生成 Markdown 格式的结构化内容 → 调用 Agent 工具（格式 + Markdown 内容 + 可选模板）→ DocumentService 接收请求 → 根据格式调用 MCP Document Tools（Word/Excel）或 reportlab（PDF）或 python-docx-template（模板填充）→ 生成文档保存到服务器 → 元数据写入数据库 → 返回文件元信息 → 对话中渲染文件卡片 → 右侧面板更新文档列表。
  - **Covered by:** R5, R6, R8, R11, R14, R17, R19, R21

- F2. 前端独立页面操作
  - **Trigger:** 用户在前端文档处理页面直接操作。
  - **Actors:** 用户, 前端, DocumentService
  - **Steps:** 用户选择格式 → 填写 Markdown 内容或上传模板 → 前端调用 REST API → DocumentService 处理 → 元数据写入数据库 → 返回文件下载链接。
  - **Covered by:** R9, R10, R11, R14

- F3. 右侧面板查看/下载
  - **Trigger:** 用户点击右侧面板中的文档项。
  - **Actors:** 用户, 前端
  - **Steps:** 用户展开面板 → 查看当前对话文档列表（从数据库加载关联元数据）→ 点击下载 → 认证后浏览器下载文件。
  - **Covered by:** R15, R19, R20, R22, R27

## Scope Boundaries

### Deferred for later (v2)

- PPT 创建（.pptx）— MCP Document Tools 的 PPT 支持待验证，且 PPT 模板填充最复杂。
- 格式转换（Word→PDF、Excel→PDF、PPT→PDF）— python-docx/openpyxl 不能直接转 PDF，可能需要 LibreOffice headless，影响部署架构。
- PDF 合并和拆分 — 独立功能域，与文档创建无关。
- Excel/PPT 模板填充 — `python-docx-template` 只支持 Word，Excel/PPT 需要自研或寻找其他库。
- 文档编辑（修改已有文档的特定内容）— 与创建是完全不同的能力，复杂度更高。

### Outside this product's identity

- OCR / 扫描文档识别 — 需要额外的 OCR 引擎，属于不同的能力域。
- 文档协作编辑（多人实时编辑）— 这是另一个产品方向。
- 文档版本控制（历史版本管理）— 超出当前文档处理的范畴。
- 云存储集成（OneDrive / Google Drive / S3）— 当前使用本地文件系统存储。
- 文档水印 / 加密 / 数字签名 — 安全相关功能，后续按需评估。

## Dependencies / Assumptions

- **MCP Document Tools**（`mcp-document-tools` PyPI 包）— 可能提供 Word/Excel 的创建/读写能力。项目已有 MCPManager 集成机制。**关键风险：功能覆盖度尚未验证，需在规划前做 spike 验证。**
- **reportlab**（Python 库）— 用于自研 PDF 创建功能。
- **python-docx-template**（Python 库）— 用于 Word 模板填充，处理 Office XML 结构中的 Jinja2 占位符。
- **现有文件上传/下载基础设施** — `src/agentkit/server/routes/chat.py` 中的上传/下载 API 和 `data/uploads/` 目录可复用，但需补充认证。
- **现有 MCP 集成基础设施** — `src/agentkit/mcp/` 下的 MCPClient、MCPTool、MCPManager 提供了完整的 MCP Server 连接和工具注册能力。DocumentService 内部通过 MCPClient 调用 MCP Document Tools。
- **现有 DocumentLoader** — `src/agentkit/memory/document_loader.py` 可复用于 R4（读取/解析文档）。
- **假设** MCP Document Tools 的稳定性满足生产需求 — 需要在规划阶段评估其功能覆盖度和可靠性。
- **假设** MCP Document Tools 支持 STDIO 传输 — 作为 AgentKit 子进程运行，部署最简单。如果只支持 HTTP/SSE，需要独立部署服务。

## Outstanding Questions

### Deferred to Planning

- **MCP Document Tools 功能 spike（规划首要任务）** — 需要验证以下能力是否可用：Word 创建（从结构化内容）、Excel 创建、Word 读取、Excel 读取。如果验证失败，Word/Excel 创建改为自研（python-docx/openpyxl），DocumentService 架构不变，只替换内部实现。spike 结果决定混合方案的具体实现路径。
- MCP Document Tools 的具体工具 API 形状（工具名、参数 schema）需要在规划阶段调研，以确定 DocumentService 如何调用。
- MCP Document Tools 的部署架构（STDIO vs HTTP/SSE）需在规划阶段确定。
- 右侧面板的 UI 设计细节（折叠方向、宽度、排序方式）。
- 前端独立文档处理页面的具体布局和交互流程。
- 文档元数据的数据库表结构设计。
- Markdown → Word/Excel/PDF 的格式映射规则（标题层级、表格样式、列表缩进等）。
- 文档过期清理的实现方式（定时任务 vs 懒清理）。

## Sources / Research

- 项目 MCP 集成基础设施：`src/agentkit/mcp/client.py`、`src/agentkit/mcp/manager.py`、`src/agentkit/mcp/transport.py`
- MCP 工具包装：`src/agentkit/tools/mcp_tool.py`
- MCP Server 配置模型：`src/agentkit/server/config.py`（`MCPServerConfig`）
- 现有文件上传/下载路由：`src/agentkit/server/routes/chat.py`（第 1170-1234 行，无认证，需补充）
- 现有文档解析能力：`src/agentkit/memory/document_loader.py`（仅解析，不生成，可复用于 R4）
- 前端文件附件组件：`src/agentkit/server/frontend/src/components/chat/messages/FileAttachment.vue`
- 社区 MCP Document Tools：`pip install mcp-document-tools`（Python，支持 STDIO/SSE/HTTP 传输）
- python-docx-template：`pip install docxtpl`（处理 Word 文档中的 Jinja2 占位符，感知 Office XML 结构）