AI Agent文档生成：DeepSeek+LibreOffice解决最后一公里

做文档Agent的朋友应该都遇到过这个尴尬模型聊得头头是道真要它把一份带格式的合同导成PDF它转头就给你一段Markdown。生成文本不等于生成文档这个“最后一公里”卡住了不少人。这一篇就聊聊我最近把本地部署的DeepSeek接进Agent框架也就是Harness再把LibreOffice当工具挂进去的完整实践——让Agent能真正动手改文件、转格式、填模板而不是只会“说”。这套组合适合谁看正在做AI Agent工具链集成、办公自动化、以及被“模型输出很漂亮但落不了地”折磨的开发者。后面所有环节我都按实际能跑通的方式写包含选型逻辑、关键代码思路和踩过的坑拿走就能照着搭。1. 为什么一上来就卡“最后一公里”1.1 文本生成和文档交付之间隔着一条河先把这个问题的本质说清楚。大模型本质上是一个“文本生成器”它输出的是token序列。你把一份需求丢进去它回给你的是一段结构清晰的文字甚至可能给你一段伪代码或者一个XML模板。但真实办公场景里要的东西是一份“文档产物”——带页眉页脚的Word、套好公司模板的PPT、带公式能自动算的Excel。模型内部没有文件系统也没有排版引擎它不知道什么叫“分页符”更不可能直接操作一个.docx里的表格样式。这就是“最后一公里”的含义从模型输出到最终可交付文件之间的这段距离必须靠外部工具来补。我之前在某个跨平台系统上做过一个文档生成模块第一版纯粹靠模型直出文本结果下游同事拿到内容是空的样式、乱的表格还得人工重新排版。第二版开始引入LibreOffice的headless转换能力才勉强把“生成内容”变成“可交付文件”。那次之后我就明白文档Agent的核心不在模型本身有多聪明而在于它有没有一支“手”能把内容落到真实文件里。1.2 办公场景真正难处理的不是“写”是“改”单纯的“写一份新文档”其实还好办因为格式可以从零定义。真正麻烦的是“改”——客户丢给你一份满是格式的模板要求批量替换里面的占位符、保留原有样式、按指定页码导出PDF。这种场景下模型需要理解模板结构还需要调用底层文档引擎去执行精确的修改操作。我自己总结下来办公文档Agent的高频需求大概有四类格式转换docx转PDF、xlsx转CSV、模板填充把结构化数据填进既有模板、内容提取从PDF里抽表格、以及数据汇总把数据库记录生成一张统计报表。这四类需求里面前三类都离不开真正的文档引擎纯靠模型“嘴炮”是完不成的。还有一个常被忽略的点是文件持久化。模型生成的临时文本如果不落盘、不命名、不指定保存路径后续所有下游流程都接不上。Agent一旦接上LibreOffice就天然获得了文件系统的操作能力这是“最后一公里”里最关键的一步。2. Agent框架Harness在中间扮演什么角色2.1 别再叫它“框架”它其实是模型的手脚架所谓Harness直译是“背带、缰绳”在AI Agent领域指的就是套在模型外面那一层控制逻辑。模型本身没有记忆、不会自我纠错、也不会主动去调用外部工具这些全部需要Harness来做。Harness负责工具调度、上下文管理、错误恢复还有执行轨迹的维护。打个比方模型像是一个聪明但健忘的实习生它知道很多知识但不知道什么时候该去翻资料、什么时候该写文件、出错之后该重试还是该换方案。Harness就是那个坐在旁边提醒它的老员工你现在的任务是导出PDF第一步找到源文件第二步调用转换工具第三步检查输出是否生成失败就换一种方式再来。在我这个项目里Harness承担了几个具体职责把用户的自然语言需求解析成“计划”按计划依次调用工具每次工具返回结果后重新喂回模型做下一步判断出现异常时执行回退或重试。还有一个容易被忽略的工作是“上下文预算”——工具返回的大段日志不能全塞回给模型否则很快就把token窗口撑爆这也就是很多人问的“AI Agent token是什么意思”的由来后面我会专门说。2.2 为什么要把工具调用循环拆成“计划-执行-观察”三段这是我实践下来觉得最值得分享的一个架构经验。看似多了一步但每个环节都能独立排查问题至少在实际运维时能少熬几个夜。计划阶段模型面对用户请求先做拆解输出一个工具调用清单比如“第一步提取模板、第二步填充数据、第三步转换PDF”。执行阶段Harness严格按清单调用LibreOffice命令行工具并把每一步的真实返回状态记录下来。观察阶段再把结果反馈给模型让它决定是继续、重试还是调整方案。这个三段式最大的好处是“代码回退”特别自然。热搜里提到的“deepseek harness 代码回退”说的就是当某一步工具执行结果不理想时Harness可以把状态回滚到上一个稳定节点而不是让模型从头再来。我在实操中就是给每一步的执行结果打一个快照标记发现转换失败就退回到填充前的那一步重新走一遍整个流程的稳定性提升了非常多。2.3 工具服务与模型之间的职责边界还有一点要搞清楚模型不该直接操作文件路径也不该自己去拼命令行参数。这些脏活应该全部下沉到工具服务层也就是我的架构里专门隔离出来的“文档操作服务”。这套服务对外暴露的是语义化接口比如fillTemplate(templatePath, data)、convertTo(format, path)而不是大段的shell命令。模型只需要表达“我要做什么”具体的“怎么做到”由工具服务内部完成。这样的好处第一是安全模型接触不到系统级命令出问题的面就小了第二是稳定命令行参数、编码问题、临时目录这些细节不需要模型理解只要工具服务保证接口兼容就行。当时还纠结过到底走LibreOffice的命令行接口还是走它底层那套UNO API。最后大部分场景还是选了命令行原因是UNO虽然控制力更强但启动慢、环境依赖重实时的稳定性不太好。命令行模式用soffice --headless启动占用低、好部署、也容易做异常隔离对做Agent工具来说性价比最高。3. 实操把LibreOffice塞进Harness的关键路径3.1 环境准备装一个能“无人值守”的LibreOffice既然是给Agent用的办公能力LibreOffice装的不是日常办公版而是headless无界面模式。在Linux环境下装起来很快以Debian系发行版为例几条命令就能搞定sudo apt update sudo apt install libreoffice-writer libreoffice-calc -y只装Writer和Calc就够覆盖大多数文档场景Impala和Draw可以先不装减少体积也减少被攻击面。安装完跑一个最基础的验证命令确认能正常转换soffice --headless --convert-to pdf --outdir /tmp/test /tmp/test.docx如果这个命令能成功生成PDF文件说明LibreOffice的基础能力已经可用了。这里有个小坑也要提一句如果想要更好的字体兼容性建议同时安装中文字体包否则转换出来的PDF里中文很可能显示成方块这个在Agent自动化场景里特别常见。另外文档模板操作往往依赖宏能力涉及宏的地方需要Java运行时环境。提前检查一下java -version没有就装一个OpenJDK免得后续用到模板宏的时候卡壳。3.2 在Harness里注册工具给模型一个“写文件的能力”工具注册是Agent能不能用好LibreOffice的分水岭。以我用的这套开源Agent框架社区里习惯管它叫AgentRunner我这里也沿用这个化名为例工具定义按标准的方式注册就行。tools [ { name: libreoffice_convert, description: 把文档转换到指定格式比如docx转pdf、xlsx转csv, parameters: { input_path: {type: string, description: 源文件路径}, target_format: {type: string, enum: [pdf, csv, txt, docx]}, output_dir: {type: string, description: 输出目录默认/tmp/agent_output} } }, { name: libreoffice_fill_template, description: 用结构数据填充文档模板中的占位符保留模板样式, parameters: { template_path: {type: string}, data_json: {type: object, description: 填充字段的键值对} } } ]工具描述写得越明确模型就越不容易瞎填参数。AI Agent里的工具本质上是函数但模型对函数签名没有直观概念全靠description去“猜”用途。描述里写清楚“什么时候用、参数是什么、输出在哪里”比让模型自己理解要稳得多。实测下来把参数的枚举值、默认路径、输入输出格式都写进描述之后工具的调用成功率明显上了一个台阶。3.3 工具调用循环与代码回退的实现接下来是Harness里最核心的执行循环。我把它做成一个有限状态机状态包括“解析中、执行中、观察中、回退中、完成”。def run_agent_task(user_request): plan model.plan(user_request) # 计划阶段 state executing for step in plan.steps: if state executing: result execute_tool(step) # 执行阶段 if result.success: observation summarize(result.output) # 观察阶段 plan model.adjust_plan(plan, observation) else: state rollback rollback_to_last_good(step) # 代码回退 plan model.new_plan_for_step(step) # 换方案重试 return collect_outputs(plan)这里有一个重要的经验角度就是“回退不等于全部重新开始”。每一步执行前我都会把当前干预记录快照存下来比如规划好的字段映射、已经生成的临时文件路径失败时一键回到最后一个良好节点让模型在那个节点上重新规划后续步骤而不是整个任务从零再来一遍。这个设计在文档处理中非常重要因为LibreOffice转换本身耗时不少全部重来的话一次任务可能就要多跑几十秒甚至几分钟。3.4 提示词优化与知识库插件给模型喂“文档格式规矩”这是我从热搜词里看到不少人提“提示词优化插件”“LLM wiki”时想重点展开的。模型其实不知道你的模板长什么样也不知道你们公司对导出文件有什么命名规范这些知识必须通过提示词插件或外部知识库喂给它。我在Harness里挂了两个实用插件。第一个是提示词优化插件它的作用是当用户请求描述得太模糊时先自动补一轮追问或格式化生成“结构化任务描述”再交给主模型。比如用户只说“帮我把这个转一下”插件会主动把格式补全成“把/tmp/data/docx转成PDF并输出到/tmp/out”。实测下来这个插件能大幅减少模型因为参数残缺而产生的无效调用。第二个是知识库插件我把它跟文档格式规范绑在一起其实就是给模型挂了一本“操作手册”。模型遇到不确定的模板格式时会先去检索知识库里预设的条目比如“合同模板必须保留第二页的声明内容”“导出PDF前必须重算所有Excel公式”。这相当于把团队的文档规范沉淀成Agent的执行准则不用每次都在提示词里重复教它一遍。4. 文档Agent落地中的细节与坑4.1 从docx到PDF转换没那么简单我最初以为转换是小菜一碟真的跑起来才发现坑比想象得多。第一个问题是转换速度LibreOffice启动大概要两三秒如果每个文件都新建一个进程频繁调用时会积压大量等待。正确的做法是把LibreOffice跑成长期驻留的服务进程复用同一个实例来处理多次转换任务整体吞吐能提升非常多。soffice --headless --acceptsocket,hostlocalhost,port2002;urp; --norestore --nologo 第二个问题是转换成功率。有些带复杂样式的docx文件直接转PDF出来会丢图表或者页边距错乱根本原因往往是模板本身不规范。对这种文件我建议先在模型生成阶段就约束好尽量从规范模板出发而不是事后靠工具硬转。人工排版都费劲的文件指望Agent一次成功不现实。4.2 模板填充里的占位符陷阱模板填充看起来简单就是查找替换实际用起来有几个反复踩坑的地儿。比如Word里的占位符常见的有${name}、{{name}}、#name#好几种风格替换的时候一定要确定统一格式并且让模型在刚开始就识别出实际模板用的是哪一套否则会出现“替换完模板却发现内容没变”的诡异现象。另外中文字体名和段落样式在模板里经常被嵌套在节section级别直接对局部做文本替换会破坏样式。我现在的处理方式是尽量用底层的“字符级替换”而不是“段落重写”这样可以保留模板原有的字体、间距和段落结构不会替换完就变成一堆裸文本。这套处理方式最开始也是某次交付踩了雷之后才总结出来的替换完的文档客户打开一看说“格式跟原来不一样”之后我就老老实实按这个思路写了替换模块。4.3 Token治理为什么工具输出不能全量回喂这是个很多人会忽略的性能细节。LibreOffice转换完一个大型Excel时返回的日志可能非常长如果原封不动交给模型判断一次对话的token消耗会飞快。搜索热词里的“ai agent token是什么意思”问的就是这个问题我这里也用一句话解释——token是模型消耗的计算计量单位工具返回的内容越长这一次推理所花的时间与成本越高。我的做法是“结果摘要化”工具执行完之后Harness只把关键信息整理成一小段结构化结果回传给模型比如文件名、输出路径、文件大小、转换是否成功那些冗长的中间日志直接丢进本地日志文件里备查。这样既保住了模型对执行结果的判断能力又把对话的token开销控制在稳定范围内。4.4 Agent安全与越权边界谈到工具集成就不能不提安全边界。让Agent能调用文件系统工具之后必须对操作范围做硬性限制否则表达能力越强风险越大。我在Harness里做了三层防护每一层都是必须守住的底线。第一层是路径白名单所有工具调用代码都经过一个统一的路径检查只允许访问预设的工作目录禁止访问系统目录和任何绝对路径的“越权”操作第二层是工具白名单模型在计划阶段只能从注册列表里选择工具不能通过“附带其他指令”来额外执行任何命令第三层是权限降级Agent跑在专用的低权限用户下这样即使文件操作出现异常也不会波及宿主系统的关键文件。4.5 RPC偶发错误与稳定性兜底运行Agent过程中最让人头疼的不是模型答错而是基础设施层的偶发故障。比如你可能会在调用分布式工具时撞上类似“agent rpc error (-1): empty sid and service name”这样的报错这个报错本质上是RPC会话状态丢失导致的——服务端没有正确拿到会话标识连接被重置看起来就像“工具调不通”了。从我的排查经验来看这个问题大概率发生在长时间空闲后的首次调用或者服务重启后连接没重新建立。解法也不复杂给工具调用加一层“自动重试”策略发生连接级错误时先重新建立会话再重试一次同时定时发心跳请求保持连接活跃避免空闲超时。加了这两层之后这类报错基本就不太容易遇到了。5. 高频问题速查与避坑清单5.1 开发阶段遇到的高频问题直接看这张表下面这张表是我把实操中反复遇到的问题整理出来的速查表遇到相似表现时可以照方抓药。现象根本原因解决办法转换PDF中文变方块系统缺少中文字体安装fonts-noto-cjk务必在测试机和生产机都装上docx转PDF后表格间距错乱模板本身样式不规范从模板源头治理模型生成阶段就统一风格高频转换时积压超时每次新建LibreOffice进程开销太大改成socket驻留复用同一个LibreOffice实例模板占位符替换后无效果占位符格式不统一或藏在文本框里统一占位符规范替换前先扫描模板实际结构工具返回日志膨胀token消耗剧增日志直接回喂模型做结果摘要化只回传关键字段调用“agent rpc error(-1)”类报错会话建立状态丢失加连接重试和心跳保活机制模型乱填工具参数工具描述过短、缺少参数约束在description里写明字段枚举、路径默认值和调用边界5.2 几条我拿时间换来的避坑经验有些坑不是看文档就能避开的需要在真实任务里摔过跤才能真正理解。这里我把踩过的一些高频坑整理出来至少能帮你少熬几天夜。第一宁造专用环境也不能共用一个LibreOffice实例做多用户并发。最开始我觉得复用实例性能好结果并发多个任务时文件互相覆盖排查了半天才发现是工作目录冲突。于是我在每个任务目录里建立独立临时子目录加个随机后缀才能保证互不干扰。第二在做模板填充前先让模型“读”一遍模板的结构再动手。很多人直接让模型去填充模板占位符找不准、位置理解错结果生成出来的文档结构错乱。我的做法是增加一个“模板结构化读取”的前置步骤先把模板里的段落、表格、页眉页脚等信息提取出来交给模型再让它基于结构去执行填充。这个前置步骤虽小却让填充任务的完成度和稳定性有了质的变化。第三设计好“重试上限”。Agent文档工具并不是无限重试成功率就越高某些转换场景下重试100次也一样失败根源通常是模板文件本身的损坏或不规范。我在Harness里把单个工具设置成最多重试三次三次都没过就升级给用户“人工介入”提醒。这比在自动化链路里死磕效率高很多。6. 最后再分享一点个人体会这套“DeepSeekLibreOfficeHarness”的组合跑通之后我的体会是文档Agent能不能用关键真的不在模型的文本能力而在于工具链的完整度和执行框架的稳定度。模型负责“想”Harness负责“控”LibreOffice负责“做”三者各司其职整个链路才转得起来。实际使用中另一个很深的感受是“Agent anywhere”的价值——把同样的Harness接上不同的工具就能解决不同领域的最后一公里问题。今天接的是LibreOffice做文档明天接一个数据库接口做数据分析后天再接一个画图工具做图表输出原理和架构都能复用。后面我打算重点往“数据处理Agent”的方向再扩展一轮把数据库查询和报表生成也一并接进来到时候再写一篇详细的拆解。