fischer
/
fischer-agentkit
1
0
Fork 0
Code Issues Pull Requests Actions 87 Packages Projects Releases Wiki Activity
fischer-agentkit/docs/brainstorms/2026-06-23-document-process...

12 KiB
Raw Permalink Blame History

date topic
2026-06-23 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 结构）