这个标题放在计算机科学与技术专业的项目清单里乍一看像是个调个API生成Word文档的普通毕设。但实际上把AI智能体、Office套件、工程实现三件事串起来做的是一个非常典型的Agent工程课题让大模型从会聊天变成会干活而且是干Word排版、Excel分析、PPT生成这种具体到文件格式的活。这篇文章我把整个设计思路、模块拆解、代码实现和踩坑记录完整写出来给正在做类似项目的同学提供一个可以直接参考的工程样板。我自己做这版套件的时候目标很明确不做一个只能吐文字的聊天框而是做一个能自己规划任务、调用文档处理工具、最后交付真实Office文件的智能体系统。当你真正把一个Agent项目落地到这个粒度就会发现核心难点根本不在调用大模型而在工具设计、上下文管理、格式保真和错误恢复这一层。这恰恰是计算机科学与技术专业做这类项目最有价值的部分。1. 项目到底在做什么从标题里读出的真实需求1.1 标题拆解三个关键词分别落地成什么AI智能体Office套件拆开看每一个词都有明确的工程含义。AI智能体意味着你不能只写一个prompt(用户输入) - 模型输出的简单接口。智能体的核心特征是自主性它能理解一个模糊任务拆解成多个步骤调用外部工具检查执行结果然后决定下一步做什么。在这个项目里我把它实现为一个规划-行动-反思循环后文会详细讲。Office套件则对应三个具体能力域文档助手处理Word、表格助手处理Excel、演示助手处理PPT。这三个域的技术栈完全不同Word要处理样式和章节结构Excel要面对公式、数据类型和图表PPT要处理版式、占位符和分页逻辑。把它们抽象成三个工具集挂在同一个Agent调度核心下面才叫套件而不是三个独立的demo。计算机科学与技术这个前缀决定了项目的重心不在算法创新而在系统设计模块怎么划分、接口怎么定义、异常怎么处理、运行日志怎么记录、模型怎么替换。这些工程能力恰恰是这类项目最容易被评审老师或面试官追问的地方。1.2 市面上的AI办公产品那么多为什么还要自己造现在WPS、Microsoft 365都内置了AI能力用起来确实方便。但作为计科专业项目直接买现成产品是行不通的因为你要展示的是设计实现能力不是产品使用能力。更现实的问题是现有办公AI大多是黑盒。你问它是用什么架构做的、工具调用怎么设计的、prompt怎么组织它不会告诉你。自己实现一遍你才能真正理解为什么大厂AI写文档偶尔会格式错乱为什么Excel长表格分析容易丢上下文这些问题的根源往往不是模型不够聪明而是工程细节没做好。另外自研套件有一个商业产品做不到的优势可控性。我可以接入任意兼容OpenAI接口的大模型本地部署也行还能自由添加自定义工具。比如做毕设的学生可能会接入学校内部的文档模板要求套用特定排版格式这种定制化在商业产品里很难实现。1.3 这个项目适合谁、能复用哪些能力如果你正在做以下事情这篇文章应该对你有直接帮助计算机科学与技术、软件工程专业的毕业设计选题类似基于大模型的智能文档处理系统。想做Agent方向的项目积累但不想停留在套壳聊天机器人层面想做一个有工具调用、有真实产出的系统。想进AI应用开发岗位需要在简历里展示一个完整的LLM工程化项目。做完这版套件你手里会留下几笔核心资产一套可扩展的Agent内核代码、一套完整的Office文档处理工具链、一整套调参和排错的经验。这些比用ChatGPT写过文档要有说服力得多。2. 整体架构设计与方案选型2.1 Agent核心模式为什么选规划-行动-反思循环我的Agent内核没有用什么复杂的多智能体框架而是采用了一个非常经典的模式Plan - Action - Reflection循环执行直到任务完成。这个结构对应到代码层面就是一个while循环加三个核心阶段。规划阶段由大模型根据用户意图生成任务序列比如分析上传的销售数据表然后生成一份季度总结Word文档。模型会把任务拆成读取Excel - 进行统计 - 生成报告大纲 - 写入Word文件。行动阶段调用具体工具。每类Office能力封装成独立的工具函数Agent通过函数调用机制触发它们。工具执行完会返回一个结构化的结果摘要比如统计完成Q3总销售额118万环比增长12%而不是把整个大文件塞回上下文。反思阶段模型阅读执行结果判断任务是否完成、是否需要修正。如果统计口径不对它会回到规划阶段重新设计步骤。如果输出不完整它会补齐缺失内容。这个循环看起来简单但设计上有两个关键点。第一每个阶段的消息都必须精简。规划阶段的输出只保留任务编号和工具参数行动阶段的输出只保留结果摘要和错误信息不能让大段全文混入上下文。第二必须设置最大循环轮次。我在实现里默认是8轮超过就触发人工介入提示避免模型进入死循环烧token。2.2 模块划分一个调度中枢加三个能力域系统在逻辑上分成四块模块职责关键技术点Agent调度中枢任务规划、工具注册、上下文管理、循环控制函数调用、消息历史管理文档能力域Word文件生成与格式化python-docx、文档结构树表格能力域Excel读写、数据分析、图表生成openpyxl、pandas、matplotlib演示能力域PPT生成与版式处理python-pptx、模板机制这种划分的核心收益是替换成本极低。每个能力域只通过一组标准工具函数暴露给Agent工具函数内部怎么实现完全隔离。我在开发过程中把表格模块的数据读取从openpyxl换成pandas时Agent调度中枢一行代码没改。更重要的收益是上下文控制。不同能力域产生的中间数据格式完全不同Word模块产出JSON文档结构Excel模块产出统计摘要和图表路径PPT模块产出页面对象列表。如果让调度中枢统一处理这些异构数据消息历史里很快就会堆满垃圾信息。模块化之后调度中枢只需要处理统一格式的工具调用参数和执行结果摘要复杂度大幅下降。2.3 技术栈选型为什么是Python三件套加FastAPI语言毫不犹豫选了Python因为Office文档处理生态它最成熟。三个核心库分别是python-docx、openpyxl、python-pptx分别对应Word、Excel、PPT全部可以pip直接安装不依赖Office软件本身这意味着项目可以跑在Linux服务器上方便部署展示。LLM接入层我做成一个统一的客户端封装兼容OpenAI API格式。这样底层模型可以自由切换跑性能测试时用DeepSeek跑私有化演示时用本地部署的开源模型切换只需要改环境变量里的base_url和api_key。特别注意如果你所在项目环境不允许调用外部API可以改成基于本地模型的推理方案但前期的接口逻辑不需要任何改动。前端暂时不需要重投入。我用FastAPI提供REST接口配合一个简单的HTML页面完成文件上传、任务提交和结果下载。很多同学在这个环节会纠结要不要上React/Vue我的建议是不要。在毕设或课程设计阶段评委看的是核心系统怎么实现不是前端框架多新。把精力留给Agent和文档处理性价比高得多。2.4 为什么不做一个超级大Prompt硬扛所有任务我也试过最初的粗暴方案把你是Office助手这是用户需求这是文件内容写成一个长prompt让模型直接生成最终的docx二进制内容或markdown再由工具转换。结果在简单的写一段通知场景下能跑通一旦涉及读取Excel - 按条件筛选 - 生成带表格的报告就彻底失控。问题在于大模型无法在一次推理中可靠地完成多步且每步都有严格格式要求的任务。生成一般性文本没问题但生成一个结构正确的Office文件需要精确处理几百个排版参数和格式规则这超出了单次推理的稳定范围。而且当任务跨多个文件时上下文根本无法承载完整数据。所以我把职责重新划分模型负责思考和决策程序负责生成和执行。模型输出一份结构化的中间描述比如文档大纲JSON、数据统计结论、PPT页面列表程序再把它渲染成真实文件。这样模型的成功率高程序的渲染逻辑也容易测试。简单说模型是大脑程序是手脚而不是让大脑直接去控制每根手指。这一步是整个项目最重要的设计决策。3. 核心模块的实现细节3.1 文档模块让AI产出符合排版的Word文件文档模块的输入是用户意图输出是.docx文件。实现上分为两段模型生成文档结构python-docx渲染成Word。模型生成的文档结构是一个JSON对象我把它定义成三级结构文档级元信息、章节列表、段落内容。一个例子是这样的{ title: 2025年三季度部门工作总结, sections: [ { heading: 一、整体业绩回顾, level: 2, paragraphs: [ {text: 三季度部门累计完成项目交付12个整体达成率102%。, style: normal}, {text: 重点KPI完成情况见下表, style: normal} ] } ] }关键约束是模型只负责生成文本和章节关系不负责字体、字号、缩进这些精准样式。样式由渲染器按照预置模板统一套用。这样做的原因很简单大模型对三号黑体居中行距28磅这类描述的理解不稳定偶尔会把格式参数写错直接导致渲染出来的文件乱七八糟。而预置模板可以保证每个章节标题、正文、表格都用统一的样式规则文档质量稳定。python-docx渲染时有一个容易踩的坑生成的样式必须显式附加到文本所属的段落不能只设置默认样式。我封装了一个apply_paragraph_style函数统一处理中文字体、大小、对齐和行距。中文字体这块特别提醒docx文档的默认字体经常不支持中文需要在渲染时同时设置w:eastAsia字体属性否则生成的文件里中文显示成系统默认字体到别的电脑上打开会变样。3.2 表格模块把Excel变成可对话的数据源表格模块是这个套件里工程复杂度和踩坑密度最高的一块因为Excel文档天生异构有单元格数据、公式、格式、图表、多工作表还有数值精度问题。模块的读取层我做了两层封装。第一层用pandas读取数据用于分析场景。pandas擅长处理规整的表格数据转换成向量后可以直接喂给统计函数。第二层用openpyxl读取原生的单元格元数据包括公式、格式、合并单元格信息用于生成格式保持型的修改操作。直接用openpyxl读公式时要特别注意默认库不会对公式求值需要设置data_onlyTrue才能读取计算结果但如果你用这个模式打开一个还没被计算过的文件会得到None。分析层我采用Agent写代码沙箱执行的方式。模型生成Python代码片段来完成数据统计比如按月份聚合、计算同比环比、生成条形图然后由模块内的执行器运行。这个方案让模型的分析能力得到最大发挥因为统计逻辑种类太多你不可能为每一种预写一个工具函数。# 模型生成的代码示例按区域汇总销售额并生成柱状图 def analyze(df): result df.groupby(区域)[销售额].sum().sort_values(ascendingFalse) result.to_excel(肆output/summary.xlsx) result.plot(kindbar).get_figure().savefig(output/sales_chart.png)沙箱执行是这套方案的安全底线。如果项目是本地自用可以不启动Docker但至少要用exec限制可用内置函数禁止访问系统关键路径并设置超时。如果在生产环境部署强烈建议放进容器隔离环境。这个点如果项目要过查重或安全评审是必问项建议提前准备。图表生成我用了matplotlib生成后保存为PNG文件再把图片用openpyxl插入到Excel指定工作表。这里有一个顺序问题需要注意matplotlib输出的是无边框的绘图对象必须调用get_figure().savefig()完整落盘然后再通过openpyxl的add_image()方法引用图片路径顺序不能颠倒否则图片可能只有一部分被写入。3.3 演示模块从大纲到PPT页面的流水线PPT模块的输入可以是一段文字描述比如做个关于智能体技术分享的演示文稿大约10页输出是一个.pptx文件。流水线分为三步。第一步模型生成演示大纲JSON包含页面标题和每页的要点列表。第二步程序根据大纲选择一个版式模板。第三步python-pptx批量创建幻灯片填写标题文本框和内容占位符最后保存。这里有个经验预置版式比全自动排版靠谱得多。我做了三套版式模板标题页、章节页、内容页。内容页固定为主标题多要点列表结构这样既能保证演示效果又能避免模型无节制地生成过长文本导致页面溢出。如果你的项目允许UI投入还可以允许用户上传自己的PPT模板作为底版实现效果会更贴近真实办公场景。字号控制是演示模块的核心规则。我发现只要不限制每页字数模型生成的文本经常超长放不进一页PPT。所以我在渲染器里加了一层硬校验每个要点不超过40个中文字符每页最多5个要点。超长的文本在渲染阶段被截断并在末尾加省略号同时把这个信息反馈给Agent进行重新组织。初版实现时我没有做这层校验结果生成的PPT页面字都挤成一团后来加了一个简单的字符长度检查就解决了。3.4 工具调用与工作流编排的工程细节Agent调度中枢要为能力域的每个功能注册一个工具描述包括函数名、参数说明、JSON Schema。这部分直接决定了模型能不能正确调用工具。工具描述的一个核心原则是参数越明确越好。以生成Word文档为例工具参数包括doc_title字符串、sections数组每个元素是包含heading、level、paragraphs的对象。如果参数描述写得太模糊比如sections是用来描述文章结构的字段模型就可能在paragraphs里放进嵌套结构导致解析失败。我把参数描述写成We must be have 1-5 paragraphs...这种明确语义模型在大多数情况下会遵循。工具数量控制在5个以内一个调度周期内不要超过5个可用工具多了模型选择困难出错率直线上升。解决办法是分流收到用户指令后先经过一次意图分类判断任务属于文档、表格还是演示域然后只把对应域的工具集挂载到本次循环中。比如用户让整理一个会议纪要系统只会看到文档域的工具不会看到Excel图表工具干扰决策。上下文管理方面我做了两层优化。一是历史消息裁剪每轮循环结束后把工具执行结果压缩成一句话摘要原始输出写入磁盘缓存摘要保留在消息历史里。当历史消息总长超过阈值我设置为约4000token自动丢弃最早的辅助轮次消息只保留用户原始目标和最近的执行摘要。二是关键信息粘合把当前任务目标已完成步骤待办事项三块内容固定放在系统消息末尾保证模型即使在长任务后期仍能锚定最初的目标不容易跑偏。4. 实操过程从零搭一个最小可用版本4.1 环境与依赖准备我用的Python版本是3.10建议你也用3.10及以上避免一些新特性兼容性问题。项目依赖集中在requirements.txt里核心是这几项fastapi0.111.0 uvicorn0.30.1 openai1.30.0 python-docx1.1.2 openpyxl3.1.5 pandas2.2.2 python-pptx0.6.23 matplotlib3.9.0 python-dotenv1.0.1安装完成后在项目根目录创建.env文件配置LLM接入参数LLM_BASE_URLhttps://你的模型服务地址 LLM_API_KEY你的密钥 LLM_MODELdeepseek-chat我这里用的是OpenAI兼容接口所以只要模型服务兼容这个协议配置就能通。如果你用的是本地模型把base_url改成http://localhost:xxxx/v1即可。4.2 实现Agent内核消息循环和工具注册表Agent内核是整个系统的骨架我把核心代码精简后发现只有三个类AgentCore、ToolRegistry、MessageHistory。ToolRegistry用字典维护所有工具MessageHistory管理消息列表的增删和裁剪AgentCore负责循环控制。核心循环的逻辑用伪代码描述非常清楚class AgentCore: def run(self, user_task: str): history MessageHistory() history.add_system_prompt(self._build_system_prompt()) history.add_user_message(user_task) for _ in range(self.max_rounds): response self.llm.chat(history.messages, toolsself.tool_registry.schemas()) history.add_assistant_message(response) if response.finish_reason stop: return response.content # 任务完成输出最终结果 if response.finish_reason tool_calls: for tool_call in response.tool_calls: result self.tool_registry.execute(tool_call.name, **tool_call.arguments) history.add_tool_result(tool_call.id, result.summary()) return 任务超过最大轮次未能自动完成请人工介入注意这里每个工具执行完毕历史里记录的是result.summary()也就是工具返回的结果摘要不是原始数据。如果摘要本身超过长度限制怎么办我在摘要生成时再次调用模型做压缩确保摘要不超过300字。_build_system_prompt用来注入全局规则我会在末尾写入三块粘合信息当前任务目标{original_task} 已完成步骤{completed_tasks} 待办步骤{pending_tasks}这三块信息由Agent内核在每个循环结束时更新效果是模型到后期仍然记得自己最初要干什么避免写着写着跑题的问题。4.3 接入文档模块从写内容到落盘.docx工具函数的实现要非常务实。以create_word_doc为例输入是JSON结构输出是文件路径函数内部调用python-docx渲染并且把文件保存到统一输出目录返回路径和摘要。实际开发中我写了一个docx_renderer.py包含三个核心函数def create_document(meta: dict) - Document: doc Document() return doc def add_heading(doc: Document, text: str, level: int): doc.add_heading(text, levellevel) def add_paragraph(doc: Document, text: str): paragraph doc.add_paragraph(text) # 统一设置中文字体与字号 for run in paragraph.runs: run.font.size Pt(12) run.font.name 微软雅黑 run._element.rPr.rFonts.set(qn(w:eastAsia), 微软雅黑)这里的qn导入路径是from docx.oxml.ns import qn是我调试中文字体时查文档查到的重要细节。不设置w:eastAsia时生成的docx打开后中文显示为默认宋体文件在不同设备间传递时字体可能不一致。渲染完成后工具返回的文件路径和摘要信息会传回Agent内核作为下一轮规划的输入。比如Agent发现报告内容过于简短它会主动调用update_doc工具追加章节。4.4 用FastAPI封装HTTP接口并在浏览器里操作为了让项目更像一个完整产品而不是一堆脚本我加了三层API接口接口方法功能/api/uploadPOST接收用户上传的Excel/数据文件保存到服务器临时目录/api/taskPOST提交Agent任务返回任务ID/api/task/{id}GET查询任务状态完成后返回输出文件下载链接任务采用异步方式执行。FastAPI的BackgroundTasks可以直接完成不需要引入Celery这么重的依赖。但注意Agent任务涉及多次大模型调用可能耗时几十秒前端页面需要轮询/api/task/{id}而不是同步等待这是个体验细节。前端页面我做得很轻一个HTML文件搞定顶部是文件上传区中间是任务输入框下方是状态展示和下载按钮。页面上不做花哨的交互重点把上传文件 - 提交任务 - 查看运行日志 - 下载结果这条链路跑通。运行日志要直接展示Agent每一步的决策过程包括正在读取Excel文件正在分析Q3销售数据正在生成报告大纲正在写入Word文件这个设计在答辩时非常加分评委一眼就能看出你的系统具备自主决策能力而不是简单的API转发。4.5 一次完整的现场演示CSV数据生成带图表的月报我拿一份模拟的月度销售数据做全链路测试。数据是CSV文件包含日期、城市、产品线、销售额、毛利五列共约3000行。用户输入帮我分析这份销售数据生成一份8月份销售月报包含整体业绩、城市排名、产品线对比三部分并配一张柱状图。整个流程的Agent决策记录是这样的第一轮模型识别任务汽车判定调用表格读取工具load_excel_data打开CSV返回摘要文件有3000行5列数据包含完整的销售额和毛利字段。第二轮模型执行数据分析工具我封装的工具实际是生成并运行pandas代码。执行结果摘要8月总销售额约82万环比上月增长12.4%华东区占比最高达35%产品线中企业服务增长最快。第三轮模型发现用户要求图表调用generate_chart工具生成城市销售额对比柱状图保存为PNG路径。第四轮模型生成报告大纲JSON调用create_word_doc输出包含文本段落的Word文件。第五轮模型发现还需要在Word中插入柱状图调用add_image_to_doc工具把图表嵌入月报的对应章节并调整了图片宽度到14厘米。第六轮模型检查所有需求都已满足以finish_reasonstop输出最终交付信息任务结束。全程用了6轮循环token消耗约12000耗时约45秒。这个演示过程实际上是整个项目最有说服力的部分因为它完整展示了一个Agent从理解任务、分解步骤、调用工具、生成文件到自查交付的全过程。写文档时把这个流程记录下来配几张截图就是很好的项目亮点材料。5. 常见问题与排错经验实录5.1 模型返回的JSON结构不合法解析直接崩溃这是初期遇到最多的一个问题。生成文档大纲时模型偶尔会在JSON末尾多加一个逗号或者把字符串中的引号转义错误导致json.loads直接抛异常。解决办法分两层。第一层是在工具执行结果里捕获JSON解析异常把错误信息反馈给模型让它重新生成合法JSON。我在工具回调里加了重试逻辑最多重试两次。第二层是切换到支持JSON模式的大模型接口很多OpenAI兼容服务都支持response_format{type: json_object}开启后几乎不会出现格式错误。如果服务不支持还有一个土办法解析前用正则把多余的逗号和换行清理掉虽然不完美但有概率救回来。5.2 长任务跑到后面模型像失忆一样重复已完成的步骤这个现象在分析大Excel文件时特别明显。模型的上下文窗口里塞入了太多历史工具结果虽然做了摘要压缩但当历史超过一定量级模型容易忽略前面的内容重复调用同一个工具。解决办法是两条路并行。使用稀疏注意力或长上下文模型把窗口拉大降低遗忘概率。同时在系统提示里做显式的任务进度记录。我在每个循环结束时更新已完成步骤和待办步骤并在系统提示中固定展示。这个设计实测能显著减少重复动作因为模型每次规划前都会刷新一遍进度信息不再依赖它在长文本里自己找定位。5.3 python-docx生成的文件中文变乱码或字体漂移最典型的表现是在开发机打开没问题换一台电脑打开中文全部变成宋体甚至出现部分方块字符。根因往往是没有同时设置ascii字体和中文字体。Office的字体机制区分ascii和eastAsia如果你只设置了font.nameWord只会把ascii字体改掉中文仍然走主题默认字体。我修复的方法是统一用封装函数设置三类属性run.font.name 微软雅黑 r run._element r.rPr.rFonts.set(qn(w:eastAsia), 微软雅黑) r.rPr.rFonts.set(qn(w:ascii), 微软雅黑) r.rPr.rFonts.set(qn(w:hAnsi), 微软雅黑)这个方法在我的所有渲染器里统一使用之后再没出现字体漂移问题。另一个坑是生成文件时必须调用doc.save()保存完整路径如果路径目录不存在python-docx不会自动创建要先os.makedirs否则会得到FileNotFoundError。5.4 openpyxl读取Excel中的公式结果是None而不是计算值如果你试图读取一个由Excel软件生成、单元格包含公式的文件用openpyxl默认模式打开并读取该单元格的值得到的可能是公式字符串或者None。很多人一开始都会踩这个坑以为读取失败。原因是openpyxl本身不执行公式计算它只是把公式字符串原样读出来。要拿到计算结果必须用data_onlyTrue模式打开文件。但注意这个模式下只能拿到上次由Excel软件计算后缓存的结果如果文件是由openpyxl刚刚写入、还没有被Excel打开计算过那么计算结果同样为None。我给出的方案是如果任务是读取外部Excel并给出分析优先转成CSV或者用pandas读取避免公式干扰。如果必须保留公式就在Agent工具里注明公式单元格将被保留计算以原始数据为准对数据进行预处理把公式列替换为其缓存值。5.5 功能调用不稳定模型不按规定的参数传为了让LLM正确调用工具除了在JSON Schema中把类型字段写明确外还有三个实操层面的技巧。参数示例很重要。我习惯在Schema的description字段里放一个example元数据比如写文档工具传入的doc_title示例是2025年二季度项目复盘报告。模型会参考这个示例生成更符合预期的参数。把工具数量控制在5个以内工具越多模型选择错误率越高尽量做到一个能力域只有3-4个工具。关键参数尽量用枚举而不是自由字符串这样尽可能约束模型的选择空间。还有一个容易被忽略的细节工具执行结果摘要要带干净的结构化反馈。比如输出不是统计完成产生了图表而是统计完成总销售额82万环比12.4%生成图表路径: output/chart.png下一步建议将图表插入Word报告第三段下方。后者能让模型规划下一步时有一个清晰的决策锚点。6. 复盘与后续扩展方向把这套件从想法到完整跑通我最深刻的体会是Agent系统设计本质上是一种接口工程而不是模型工程。大模型只是决策内核真正决定系统上限的是工具粒度的设计、上下文管理策略、错误恢复机制以及模型与程序之间细颗粒度的职责划分。你可以在不更换模型的前提下通过调整工具定义和反馈结构让系统表现发生质的飞跃。如果后续还要继续扩展我建议按这几个方向来一是插件机制把每个能力域做成可独立加载的插件包让不同团队可以合作开发不同能力模块互相不影响。二是多智能体协作文档智能体、表格智能体、演示智能体各自独立运行通过一个协调者共享上下文这是很多商业产品主推的方向。三是基于模板的精细化渲染允许用户上传自己的Word/PPT模板系统只负责把模型内容填入模板这会更加贴近真实办公需求。最后分享一个调试技巧一定要给Agent循环加一份决策日志。每一步记录了模型调用信息、采用工具、输入参数、输出摘要、耗时和token消耗输出到JSON日志文件。我在调试阶段有过很多次模型行为怪异的情况最终都是靠日志定位问题的——不是模型真怪是我某轮工具返回的结果摘要格式不对污染了模型后续的规划。有了决策日志这类问题基本几分钟就能查出来。