最近我在折腾一个把 DeepSeek 接进 Harness 的项目做着做着发现一个特别现实的瓶颈模型能写出很漂亮的内容但生成不了“文件”。你说一个 Agent 分析完数据最后回给你一坨 Markdown 文本这在命令行里看看还行真要交付给业务同事人家要的是带页码、带目录、排版正常的 docx 或 PDF。所以我把 LibreOffice 整个塞进了 Harness 的工具箱让文档 Agent 终于能补齐这最后一公里——直接吐出可交付的文档。这篇文章就聊聊我这个组合的架构思路、接入细节以及实测中踩过的各种坑。1. 这波折腾的背景文档 Agent 的输出经常卡在“最后一公里”1.1 真实工作流不认 Markdown我最早做的几个 Agent 原型输出全靠文本流。跑 RAG 问答还行用户问一句模型引着知识库答一段终端里贴出来也像那么回事。但真正用到办公场景里就完了你让 Agent 生成一份季度总结、整理一份合同初稿、把一堆数据变成报表它输出给谁看总不能让人手动复制进 Word 再调一天格式吧。这个“最后一公里”我理解有两层意思。第一层是格式落地内容要能落到真正的文档格式里比如 docx、odt、PDF第二层是流程落地文档要能被后续环节直接使用比如归档、打印、合并、盖章。之前很多 Agent 项目就死在第一层因为大家默认“能生成文本就等于能生成文档”忽略了下游消费方其实只认文件。1.2 为什么偏偏是 LibreOffice你要是只想要一份“像样”的文档其实有很多方案比如直接调在线文档服务或者用 python-docx 拼 docx。但我的场景有几个硬约束要离线局域网可用要覆盖文字、表格、演示三类文档要能被 Agent 当成一个工具频繁调用还不能按次收费。市面上能同时满足这几点的LibreOffice 几乎是唯一选择。它本身就是开源办公套件支持 docx、xlsx、pptx 这些常见格式的读写带完整的无头模式headless可以在没有桌面环境的情况下作为一个排版服务来跑。更关键的是它自带 UNO API可以程序化控制文档对象。这意味着我不光能“把文本灌进模板”还能设置样式、插入表格、导出 PDF整套操作都能封装成 Harness 里的工具函数。2. 三层架构怎么搭DeepSeek 出内容Harness 做编排LibreOffice 管排版2.1 三个角色各干各的这个项目里三个组件各司其职缺一个都会变味。DeepSeek 是大脑负责理解用户的自然语言指令拆解成可执行的步骤并生成文档需要的核心内容。Harness 是手和骨架负责管理 Agent 的执行流程、工具调用、上下文传递以及失败回退。LibreOffice 是车间负责把内容变成真正的文档处理排版、样式、分页、导出等工作。你可能会问让 DeepSeek 直接生成 docx 的 XML 结构不行吗理论可行但实操非常痛苦。docx 本质是 zip 包里的 XML 文件模型生成这种结构很容易漏 namespace、图片关系、样式定义一旦缺了就整个文件打不开。LibreOffice 的价值就在于它把“内容和排版之间”的脏活累活全包了模型只需要告诉它“我要什么内容”剩下的交给模板和样式。2.2 一次调用链路的“慢动作”我习惯把整个流程拆成一条链来看这样出了问题好定位。用户发来指令比如“把这份销售数据整理成季度报告带趋势分析和表格”。Harness 先把这条指令和可用工具列表一起交给 DeepSeek模型返回一个执行计划比如“读取数据文件分析趋势调用文档模板工具生成 docx再转换 PDF”。Harness 按计划逐个调度工具其中文档生成工具会启动 LibreOffice 服务往模板里填内容导出文件最后把输出路径回传给模型。模型拿到路径之后可以判定任务是否完成如果需要还能继续追加修改。这条链路里有一个容易忽略的设计点工具返回给模型的信息一定要精简。不要把整个文档内容回传模型记不住那么长的上下文传一个文件路径加文件大小的摘要就足够了。如果后续要修改模型只需要基于用户最新指令再次调用工具不需要重新知道全文。3. LibreOffice 无头模式的接入细节UNO 连接、模板填充、PDF 导出3.1 无头模式安装与启动我用的系统是 Ubuntu 类的 Linux 服务器安装的时候不要整个套件都装用 --no-install-recommends 可以省掉很多没用的东西。sudo apt-get update sudo apt-get install -y libreoffice-writer libreoffice-calc --no-install-recommends注意 LibreOffice 有不少命令最关键的是 soffice。启动无头服务时我用的参数是soffice --headless --invisible --nodefault --norestore \ --acceptsocket,host127.0.0.1,port2002;urp; 这里的核心是--accept参数它打开了一个 UNO 监听端口。也就是说LibreOffice 不再只是一个“每次转换完就退出”的一次性进程而是常驻的服务其他程序可以通过 socket 连上来控制它。--norestore很重要如果不加异常退出后它可能试图恢复上次会话导致进程卡住。装完之后建议先手动测试一下服务是否正常别急着上代码。用命令转一个小文件是最快的探活方式soffice --headless --convert-to pdf --outdir /tmp test.docx如果这一步能正常输出说明库依赖没问题如果把 document 转换成 pdf 时报字体错误那多半是系统缺字体后面容器化那节我会专门讲。3.2 用 UNO 做模板填充我的方案不是让模型直接生成完整文档而是先准备一套模板再通过占位符填充。这么做的好处是格式稳定且用户可控性更强。模板里有{{title}}、{{summary}}、{{table_content}}这样的占位符Python 脚本连上 UNO 后打开模板替换占位符另存为新文件。import uno from com.sun.star.beans import PropertyValue def connect(): ctx uno.getComponentContext() resolver ctx.ServiceManager.createInstanceWithContext( com.sun.star.bridge.UnoUrlResolver, ctx) url uno:socket,host127.0.0.1,port2002;urp;StarOffice.ComponentContext component_ctx resolver.resolve(url) smgr component_ctx.ServiceManager desktop smgr.createInstanceWithContext(com.sun.star.frame.Desktop, component_ctx) return desktop def fill_template(template_path, output_path, replacements): desktop connect() props [] prop PropertyValue() prop.Name Hidden prop.Value True props.append(prop) doc desktop.loadComponentFromURL( ffile://{template_path}, _blank, 0, tuple(props)) # 遍历全文并替换占位符 for key, value in replacements.items(): search doc.createSearchDescriptor() search.SearchString key found doc.findFirst(search) while found: found.setString(value) found doc.findNext(found.End, search) doc.storeToURL(ffile://{output_path}, ()) doc.close(True)这里有个细节我一开始差点忽略loadComponentFromURL的 URL 必须是file://开头的绝对路径如果传成相对路径或普通路径UNO 会直接报错。另外替换文本后如果占位符本身带着表格的换行结构需要额外处理否则插入的内容会丢失格式。我实测下来最简单的稳妥做法是每个替换值里只放纯文本需要表格的地方单独用 API 创建不要让模型把表格的可见文本硬塞进去。3.3 命令行转换这条“安全通道”UNO 适合精细控制但它也是坑最多的路径。比如进程连接超时、端口被占用、连接无法释放都会导致整个 Agent 卡住。所以我实际上准备了两套工具一套是 UNO 模板填充精细操作另一套是纯命令行转换快速稳妥。soffice --headless --convert-to pdf --outdir /output report.docx命令行转换的好处是简单、隔离性强、不容易污染常驻服务。缺点是控制粒度粗只能做格式转换不能改内容。我在 Harness 里把这两个工具分开了需要精细排版走 fill_template只需要产出 PDF 版本走 convert_pdf。实践中你会发现绝大多数“最后一公里”问题用命令行转换就够了UNO 是锦上添花。4. 完整复现一次从一句自然语言到一份可交付的 docx4.1 先在 Harness 里注册两个文档工具接下来是集成环节。我用的 Harness 支持注册自定义工具说白了就是给每个函数写清楚名字、描述、参数告诉模型“你有一个工具叫这个名字输入这些参数调用后返回这些信息”。我的工具注册表长这样{ tools: [ { name: libreoffice_fill_template, description: 使用LibreOffice打开模板文件替换占位符生成docx文档, parameters: { template_path: string, output_path: string, replacements: object } }, { name: libreoffice_convert_pdf, description: 将docx或odt文件转换为PDF用于最终交付, parameters: { input_path: string, output_dir: string } } ] }这段注册信息会拼进系统提示词里DeepSeek 看到之后才知道“哦我可以用这两个工具”。我必须强调工具的 description 要写清楚适用场景。最开始我写得太简单模型经常在不需要转换 PDF 的时候也调用转换工具白白浪费几次调用。后来把 description 改成“仅在用户要求PDF格式或最终交付需要时使用”误调用率立刻降了下来。4.2 DeepSeek 的规划与工具调用我实际跑通的场景是让 Agent 基于一份销售数据生成季度报告要求“包含三个章节最后附一个对比表格导出为 docx 和 PDF 两个版本”。Harness 把指令交给 DeepSeek 后模型给出的规划大致是分析数据文件提取各季度销售数字。撰写报告文字包括概述、趋势分析、下季度建议。调用libreoffice_fill_template把内容填入模板。调用libreoffice_convert_pdf生成 PDF 版本。这里值得注意的是 DeepSeek 能根据模板结构自动决定替换哪些字段。模板里的{{chapter1_title}}、{{chapter1_body}}、{{sales_table}}这些字段模型会照着章节内容去填。不过sales_table这个字段不能直接填 Markdown 表格因为 LibreOffice 的文本替换不会自动把竖线文本变成表格。我的做法是让工具函数内部识别“表格占位符”然后单独用 UNO API 插入真正的表格对象。4.3 我踩过的几个小坑第一个坑是 LibreOffice 进程的并发安全。当我同时跑多个文档任务时多个 UNO 客户端连同一个服务会互相干扰。最典型的报错是 “connect failed” 和 “no such element in collection”。二次看日志发现是并发调用同一个 soffice 进程导致的。我的解决办法是把 UNO 连接封装进一个带锁的队列保证同一时刻只有一个填充任务在执行。第二个坑是中文字体缺失。默认容器里没有中文字体生成 PDF 的时候所有汉字变成方块整体排版直接崩了。这个问题排查起来最烦因为 docx 在 LibreOffice 里打开看着是对的转 PDF 才出错。后来我在系统里装好了 Noto CJK 字体并且在模板里把字体显式设置为“Noto Sans CJK SC”问题才彻底解决。字体问题对中文文档 Agent 来说几乎绕不开后面容器化章节我会再展开。第三个坑是 Harness 的上下文窗口被工具返回信息撑爆。最初我把整个模板填充后的校验结果都回传给模型文本很长。后来学乖了工具只返回“生成成功文件路径xxx大小xxKB”模型只需要这个结论就够了。你真需要让模型知道文档内容时它可以再开一个读取工具去读文件而不是在工具返回里塞全文。5. 从“能用”到“抗造”容器化、并发控制、失败回退里的实战心得5.1 批量生成时别让 LibreOffice 进程打架我把这套东西跑出单次流程之后第一个想做的就是批量生成几十份周报一次性跑完。结果并发一开问题立刻暴露。LibreOffice 的无头模式其实有两个用法。一种是我前面说的常驻服务模式快但单个进程扛不住并发。另一种是每次调用临时启动一个soffice --convert-to命令用完就退出慢但隔离性强。批量任务里我建议混合用转换 PDF 这种“无状态”操作走临时进程多个并行没关系前提是你控制了机器资源模板填充这种“有状态”操作走常驻服务但必须排队。我实测下来的经验是四核机器上同时跑六个--convert-to进程是没问题的再往上内存就开始吃紧。模板填充服务我最多给它留一个并发名额宁等勿乱。排队的实现直接用了 Python 的线程锁简单粗暴但后面跑了几千次文档任务一次没因为资源冲突崩溃过。5.2 容器镜像里的字体与 locale 问题容器化是“抗造”的关键一步。我的 Docker 镜像基于 Debian就安装文字处理相关组件和字体加上中文字体包同时把 locale 也设置好避免生成日期或数字格式时不按中文习惯显示。这一套下来镜像看起来有点大但换来的是环境完全可控再也不用担心换一台机器生成出来的文档样式不一致。这里还有一个容易忽略的点时区。默认容器的时区是 UTC文档里如果带日期时间戳很可能比你的本地时间早八个小时。我一开始没设时区连续两次看到文档里时间不对还以为是数据源的问题最后才查出来是容器的锅。5.3 代码回退与失败重试的设计最后一个让我真正觉得“可以交付”的功能是回退机制。文档生成过程里最让人头大的是“生成到一半失败”。比如模板里有模型没见过的占位符或者 LibreOffice 进程突然挂了如果 Harness 不处理用户只能拿到一个半成品文件路径体验会很差。我的处理方案分两层。第一层是 Harness 级别的重试失败之后Harness 从报错信息里提取关键词自动决定是重新调用工具还是调整一次参数再试。比如转换 PDF 失败大概率是输入文件的问题那就原样重试一次如果还失败就果断放弃不要再让模型空转。第二层是模板级别的回退每个模板文件都保留一个备份填充前先备份填充失败就用备份恢复确保原始模板不会被污染。这些设计做完之后我最大的感觉是整个 Agent 从“偶尔能出文档”变成了“稳定产出文档”。至少在离线局域网的环境下DeepSeek 负责理解指令Harness 负责任务编排LibreOffice 负责排版输出一套既不需要联网又不需要付费的文档 Agent 工作流就闭环了。如果你也想搭类似的东西我的建议是不要一上来就追求复杂功能。先把“自然语言到纯文本”跑通再单独接一个 LibreOffice 转换工具最后再加模板填充和批量并发。每一步都验证完再往前走踩坑的频率会小很多。