DocMason 如何将 DOCX、PPTX 等办公文件转成本地 LLM 知识库？

作者：袖梨 2026-09-13

DocMason 可以把 DOCX、PPTX、XLSX、PDF、邮件和文本资料整理成本地知识库，但它不是自带聊天窗口或模型服务的传统 RAG 应用。它采用“仓库就是应用、宿主代理负责推理”的方式：文件、结构化证据、检索结果和溯源记录留在本地工作区，Codex、ChatGPT Work、Claude Code 等宿主根据这些证据回答问题。

先理解 DocMason 的产品边界

DocMason 当前是 alpha 版本，参考运行环境是 macOS 上的 Codex，Claude Code 获得较完整支持，GitHub Copilot 属于兼容路径。项目没有 Web UI，也没有把 Windows 作为主要支持平台。

“用于本地 LLM 知识库”更准确的理解是：它构建本地文件型证据库，宿主代理可以在此基础上推理。DocMason 本身不发起模型 API 请求，因此推理是否本地、数据是否进入云端，取决于宿主代理及其隐私和遥测设置。

它为什么不只提取纯文本

办公文件中的意义经常依赖结构和版面。例如，幻灯片的文本框位置可能表达层级，讲者备注可能补充关键条件，电子表格的工作表和单元格关系不能随意打平，红色文字也可能表示风险。

DocMason 为每个来源生成文本、结构、渲染、备注和媒体等证据产物，并保留来源身份和定位信息。知识库发布前还要经过验证，阻断性错误不会被静默写入当前可读版本。

准备工作区与依赖

项目推荐下载 clean 发布包，把它解压为独立目录，再用支持的宿主打开整个 DocMason 文件夹。源码包面向维护和开发，普通使用不必从源码安装。

当前 Python 包要求 Python 3.11 或更高版本；README 的参考环境使用仓库内托管的 Python 3.13。Office 高保真处理依赖本机 LibreOffice，PDF 处理则使用 PyMuPDF、pypdfium2、pypdf 和 Pillow 等本地库。

在宿主中可直接要求“准备 DocMason 环境”，或由操作者执行：

./scripts/bootstrap-workspace.sh --yes --json
docmason doctor --json
docmason status --json

准备过程可能安装依赖并请求更高的本机文件访问权限。应逐项检查命令与目标目录，不要把一次命令确认误认为宿主已获得持续的完整访问权限。

把办公文件放进来源边界

私有原始文件统一放在工作区的 original_doc/ 目录。项目将该目录视为真实来源边界；knowledge_base/staging/ 是构建区，knowledge_base/current/ 才是发布后供检索读取的当前知识库。

第一批建议只放少量有代表性的样本：

带标题、表格和页眉页脚的 DOCX。
包含图表、备注和多种布局的 PPTX。
包含多个工作表与公式的 XLSX。
包含扫描页和可复制文本页的 PDF。

不要把私有来源、生成后的知识库或运行日志提交到公共 Git 仓库。项目的安全说明明确要求排除 original_doc/、knowledge_base/ 和 runtime/。

支持哪些文件类型

层级	格式	处理特点
Office 与 PDF	PDF、PPTX、PPT、DOCX、DOC、XLSX、XLS	生成结构化和视觉证据，Office 依赖 LibreOffice
深度文本	Markdown、TXT、EML	保留标题、正文及邮件关系
轻量文本	MDX、YAML、YML、TEX、CSV、TSV	使用保守的文本结构解析

格式在支持清单中不代表任意复杂内容都能无损还原。宏、嵌入对象、外部链接、特殊字体和加密文件都应单独验证。

构建并发布知识库

准备完成后，可让宿主执行“构建知识库”，也可以使用公共命令：

docmason sync
docmason sync --yes
docmason validate-kb --json
docmason status --json

首次或具有实质变化的同步可能要求显式确认。同步会在 staging 中准备证据、执行验证，再把合格快照发布到 current。若结果显示 pending synthesis 或 blocking errors，应完成待办或修复验证问题，不要把未发布的 staging 当成当前事实。

后续新增或修改文件时可以增量刷新，不需要每次彻底重建。当前版本明确不包含持续 watch 模式，因此文件变化后仍需触发同步。

从 DOCX、PPTX 到证据包

扫描 original_doc/ 并为每个来源建立稳定身份。
调用本地解析与 LibreOffice 转换链路。
提取正文、页面或幻灯片结构、备注、表格与媒体线索。
生成可检索文本和必要的视觉渲染产物。
写入来源清单、证据清单、引用定位和已知缺口。
执行一致性验证，通过后发布为 current 快照。

这种流程的重点不是生成更长的文本，而是让代理能区分“某份文件明确陈述的内容”和“跨文档推断出的结论”。

通过自然语言提问

普通业务问题应从宿主中的自然语言入口开始。项目把 canonical ask 定义为唯一的常规问答入口；retrieve、trace 和 workflow 命令主要用于检索检查、溯源和运维，不应替代正常 ask 流程。

一个有效问题应同时要求结论和证据，例如：

比较这些方案中的上线风险，列出每项风险的来源文件、页码或幻灯片，并标记证据不足的判断。

若工作区尚未准备、知识库缺失或来源已经变化，ask 流程应先路由到准备或同步，而不是依据旧快照继续回答。

检查检索与溯源

公共 CLI 提供 retrieve 和 trace，用于检查检索命中与来源链。普通用户不必记住所有参数，但在答案有争议时应核对三层信息：

答案中的具体主张是否有对应证据段。
证据段是否指向唯一的来源文件与页面、幻灯片或工作表。
定位后的原始内容是否真的支持该主张，而非只有相似关键词。

视觉或结构敏感的问题还应检查渲染、结构、备注或媒体产物。只看抽取文本，可能遗漏图表关系和版面语义。

隐私边界不能只看 DocMason

项目声明 DocMason 不上传文档内容、文件名、路径、问题、答案或证据包，也不直接调用模型。生成的 clean 和 demo 包只有在显式运行更新命令时，才可能执行受限的版本检查。

但宿主代理仍可能通过自己的服务完成推理。使用私有文件前，应确认宿主的数据保留、训练、遥测、网络和企业管理策略。只有本地证据处理与宿主推理两部分都满足组织要求，完整链路才符合预期。

常见问题定位

现象	优先检查
Office 文件无法构建	LibreOffice 可执行文件、权限和 doctor 结果
知识库一直陈旧	来源签名、同步状态与是否完成确认
答案缺少图表信息	视觉渲染、媒体产物和结构证据
引用无法回到原文	来源身份、定位字段和 current 快照
同步被阻断	staging 验证报告和 pending work