企业官网建设流程全解析

很久没有遇到一个值得聊的 Agent 项目了，OpenCowork 算一个。去年开始我就一直在找"能真正把活干完"的工具，而不是又一个只能陪聊的模型包装壳子。OpenCowork 的设计思路很直白：你输入一个任务，它自己决定调用哪些工具，然后一步步执行，右侧预览区实时展示中间产物——是文件就给你看文件，是表格就渲染成表格，是 PDF 就生成预览，最后输出可交付的结果文件。你不需要懂工具背后的实现细节，只需要盯住任务意图和最终成果。这篇文章我会从功能设计、function calling 原理、预览区实现、完整实操、高频故障排查几个角度，把我实测下来的经验和踩过的坑完整写出来，给正在做 Agent 开发或者想接入工具调用能力的人做参考。

1. 从"聊天"到"干活"：OpenCowork 到底变在哪

1.1 纯聊天的 Agent 和能干活的 Agent，差距不在模型

很多人对 Agent 的误解集中在"模型够不够聪明"上。但做过几个项目之后你会发现，大部分 Agent 翻车都不是模型理解错了，而是它根本没有"手"去执行。你说"帮我把这个 Excel 里离职员工筛掉、按部门汇总、转成 PDF"，普通聊天机器人只能给你一段 VBA 代码或者操作建议，真正的活计还得你拿着代码自己去跑一遍。

OpenCowork 这类工作台式的 Agent 系统，核心转变在两点：第一，它把工具调用从"模型回答问题时的可选项"变成了"任务执行流程中的必经环节"；第二，它引入了可视化中间态——右侧的预览面板让每一步的产物都能被看到和被检查。也就是说，模型不是凭想象给你答案，而是真的在本地或云端把文件读进来、处理掉、写出去，再给你看结果。

1.2 工作闭环：输入、执行、预览、交付

OpenCowork 的工作流本质上是一个闭环：

1. 任务输入。用户用自然语言描述目标，比如"把上个月离职的人从员工表里筛掉，按部门汇总人数，输出 PDF 报告"。
2. 工具执行。Agent 分析任务后，决定需要哪些工具：文件读取、CSV 处理、表格渲染、PDF 生成等，并逐步调用。
3. 中间产物预览。每完成一步，右侧面板即时的刷新结果文件、表格数据或 PDF 页面。
4. 最终交付。任务链路跑完，输出明确的产物文件，用户可以直接下载或二次利用。

这个闭环的价值在于：它把"AI 给出建议"和"AI 完成工作"之间的鸿沟填上了。对普通用户来说，最终交付的是一份 PDF 或整理好的表格，而不是一段要自己动手跑的命令；对开发者来说，预览区本身就是一个天然的调试器，Agent 每走一步你都能看到数据长什么样，出问题也能快速定位在哪一步。

1.3 这套模式适合谁用，不适合谁用

先说适合的人群。如果你日常有大量"读取资料—整理加工—输出文档"类的工作，比如运营月末要出数据报告、HR 处理花名册、财务面对一堆乱七八糟表格、开发需要自动化生成接口文档，OpenCowork 这套"自然语言任务 + 工具自动调用 + 预览确认"的模式，确实能把重复劳动压缩到很短的时间。

不太适合的场景也很明确：一是对输出格式要求极其苛刻、一点偏差都不能有的正式商务文件，Agent 出的活还是需要人工复核排版；二是涉及敏感数据大规模批量处理，权限模型没配置好之前，不建议直接把生产数据喂给 Agent。工具本身没有对错，边界得自己划清楚。

2. Agent 与工具的契约：function calling 的底层逻辑与实际卡点

2.1 工具调用本质是"选择题"而不是"自由发挥"

我见过不少人第一次接触 function calling 时，会以为模型真的去"运行"了什么程序。其实不是。大模型做工具调用的本质，是输出一段结构化的 JSON——包含工具名和一个参数对象。真正执行这段 JSON 的是应用层代码，也就是所谓 harness 或者 agent runtime。

举个例子，OpenCowork 给 Agent 注册了一个read_csv工具，对应的 schema 大概是这个样子：

{ "name": "read_csv", "description": "读取指定路径的 CSV 文件，返回前 N 行数据", "parameters": { "type": "object", "properties": { "file_path": { "type": "string", "description": "CSV 文件的路径" }, "nrows": { "type": "integer", "description": "读取行数，默认 5", "default": 5 } }, "required": ["file_path"] } }

模型看到任务后，会输出类似{"tool": "read_csv", "arguments": {"file_path": "/data/employees.csv", "nrows": 10}}的调用请求。注意，到这里模型的任务就结束了，真正打开文件、解析数据的是 harness 层的代码。这里就是热词里提到的"agent harness 可以发起工具调用，而不是自己就是工具"的核心区别：模型负责决策，harness 负责执行。

2.2 harness 与 agent：搞清楚谁在指挥谁

我把 Agent 比喻成一个项目经理，harness 比喻成执行团队。项目经理（模型）决定"下一步需要读取员工表"，把它写成工作联系单；执行团队（harness）拿着单子去把文件读出来，把结果贴回项目经理面前。项目经理只看结果，不亲手搬砖。

很多初学 Agent 开发的人会把这两层混在一起，结果是让模型既做决策又负责解析文件，最后代码里一团乱麻，一旦工具返回数据稍微复杂一点，模型就不知道该怎么办了。正确的做法是让 harness 承担固定的、重逻辑的部分，模型只做高层的任务拆解和工具选择判断。

OpenCowork 的架构里，这两层的边界就处理得比较清晰：所有工具注册表在 harness 层管理，Agent 每次只能从注册表里选工具，执行结果也由 harness 格式化后返回给模型，模型再基于结果决定下一步。

2.3 嵌套 arguments 问题：工具调用里最经典的坑

热词里有一条出现了很多次："工具调用嵌套 arguments 的问题反复"。这个坑我刚接触 function calling 时也反复踩。表现是这样的：模型在处理嵌套对象时，把 JSON 的序列化层级搞错，导致参数解析失败。比如工具需要一个columns参数，里面包含exclude和merge两个子字段，模型可能会生成：

{ "tool": "process_table", "arguments": { "columns": "{\"exclude\": [\"离职日期\"], \"merge\": \"部门\"}" } }

也就是把整个嵌套对象变成了一个转义过的字符串。Harness 层如果不做二次解析，会把"{\"exclude\": [...], \"merge\": ...}"当成一个普通字符串传给工具，工具就懵了。

解决这个问题的办法有两个方向。第一个方向是优化 schema，尽量把嵌套层级压平，能拆成多个平级参数就绝不嵌套；第二个方向是在 harness 层做自适应解析，检测到arguments里的某个字段是一个字符串化的 JSON 时，自动尝试JSON.parse。我在实测中倾向于两种都做。嵌套太深的 schema 对模型的输出稳定性是极大考验，而兼容解析又能兜住一部分漏网之鱼。

2.4 工具返回值的写法，决定了 Agent 能不能继续干下去

调用失败或者返回格式不统一，是 Agent 断链的头号原因。我在自己写工具层的时候，所有工具的返回值都会统一成下面这个结构：

{ "success": true, "summary": "已读取员工表，共 356 行 12 列", "preview": [ { "姓名": "张三", "部门": "技术部" } ], "data": "文件路径 / 详细数据的引用" }

summary是给模型看的简短摘要，preview是给右侧预览面板渲染用的，data是给下游工具用的完整数据引用。这里有个经验：不要把完整的大数据表格直接塞给模型去"看"，模型处理超长上下文的成本很高，而且容易遗漏细节。给它一个摘要、一个数据引用地址，让它决定下一步，才是可持续的方案。

3. 右侧预览区：文件、表格、PDF 到底怎么落地

3.1 预览区的双重角色：人的检查点 + Agent 的反馈信号

右侧预览面板是 OpenCowork 这类工作流比较聪明的一个设计。它表面上看起来像是"给用户看的展示窗口"，实际上还承担着一个更重要的职责：给 Agent 提供低成本的自我检查信号。

举个例子。Agent 执行完merge_tables之后，预览区会显示合并后的表格长什么样，行列是否对齐、数据是否错位，一眼就能看出来。如果让模型靠文本返回值判断合并是否正确，它只能看到零散的几行数据，很难发现"有一些行被错误地重复合并了"这种问题。但如果 harness 层把渲染后的表格截图或结构化数据反馈给模型，Agent 就具备了一个"视觉反馈闭环"的能力。这也是我在推进 Agent 自动化时比较看重的一点：中间结果必须是可机读的，才能参与后续决策。

3.2 表格类结果：渲染容易，复制粘贴和交互才是深坑

预览区渲染表格，技术上其实不难，随便一个前端表格组件都能做到。真正麻烦的是用户在预览区做了交互之后的体验。热词里"excel 表格无法复制粘贴""offer 表格无法复制其内容""markdown 表格复制""word 表格列宽无法拖动"这些搜索，全是这个领域的痛点。

我在实际使用中的体会是，预览区的表格至少要考虑四层能力：

• 复制粘贴。默认的 HTML 表格复制到 Excel 里常常格式错乱，因为缺少可复制的纯文本/Tab 分隔形式。可以在点击复制按钮时，把当前选中区域转换成 Tab 分隔的纯文本写入剪贴板，粘贴到 Excel 里才是规整的。
• 列宽调整。预览区的表格如果列宽不能拖动，遇到"部门"这种窄列和"备注"这种长文本列就别扭得要死，每一列都挤成一团。引入支持列宽拖拽渲染的表格组件能解决大半体验问题。
• 合计行。数据分析类任务经常需要合计行，热词里的"自定义表格合计行"就是这么来的。设计的时候需要注意合计行不能跟着排序，否则合计位置就乱了。
• 行列合并。像是antdesignvue表格的行合并列、LaTeX 表格的自动换行，这些是偏高级的需求，OpenCowork 里如果要做通用表格渲染，最稳妥的方式还是对上层的"不合并版本"进行预展开，把合并后的数据在底层已经拼好，前端只做展示。

另外还有个细节：CSV 文件直接打开经常发生乱码，原因基本都是编码。pycharm 里生成的 csv 文件用 Excel 打开不是表格文件，通常是因为分隔符不是默认的逗号，或者没有带 BOM。OpenCowork 的表格预览组件里我会建议内置一个"文件编码和分隔符识别"模块，直接在预览前把 UTF-8、GBK、逗号、Tab、分号这些情况都自动识别处理掉，这一步能省掉用户大量手动折腾的时间。

3.3 PDF 类结果：预览、解析、字体、转曲，四项缺一不可

PDF 是整个预览体系里最麻烦的一类。它涉及的环节太多——解析、渲染、字体嵌入、转曲。热词里面一堆跟 PDF 相关的搜索，说明这是很多人的共同痛点。

先说 PDF 预览。浏览器里预览 PDF 可以直接用浏览器自带的能力把 PDF 当内嵌对象渲染，但前提是 Agent 生成完 PDF 后，harness 要能及时把"文件已生成 + 文件地址"推送到前端。这一步在架构上比较关键：预览面板要和文件系统的变化订阅联动，文件一变，面板自动刷新。

再说 PDF 解析。如果你需要 Agent 去"读懂"一份已有的 PDF——比如提取合同关键信息、读取扫描件内容——纯文本提取只能处理数字型 PDF，扫描件必须接 OCR。这个我在实际的 Agent 工作流里踩过坑，主题是"pdf 图片中文设置"：扫描版中文 PDF 如果直接按文本提取，出来的是一堆乱码或空白。后来我调整了链路：先检测页面对象里有没有字体资源，没有字体资源的页面大概率是图片型，需要先转图片再走 OCR，最后再合并文本层。

最后说生成 PDF 时的两个高频问题。第一个是中文乱码，几乎每次都会遇到。很多 PDF 生成库默认字体不包含中文字形，解决方案是显式嵌入一款开源中文字体（比如思源黑体），并且生成前做一次字体子集化，减小文件体积。第二个是"pdf 转曲"——就是把所有文字转成矢量轮廓，这样即使对方机器上没有对应字体，打开也不会缺字。在交付给外部合作方时，通常输出转曲版；在需要后续二次编辑文字时，保留未转曲版。

3.4 文件联动、版本管理：预览区只有"最后一个版本"是不够的

Agent 干活的过程中，文件可能被修改十几遍。如果预览区只展示最终版本，用户在中间步骤产生疑问时根本没有线索去回溯。我在使用中比较习惯的工作方式是：每个工具调用产生的文件快照都带着编号和时间戳，预览区提供一个简易版本列表，点击任意版本可以回看当时的中间产物。OpenCowork 对文件快照的支持并不算完整，但它的目录结构中每个工作区天然保留了过程文件，前端只需要做一个按时间倒排的文件列表，就能实现一个还不错的版本回溯体验。

这种设计对我的实际价值在于：当 Agent 最终结果不对时，我能直接定位到"到底是哪一步处理错了"，而不是把整个流程重跑一遍或者黑盒猜原因。

4. 一次完整实操：用 OpenCowork 整理考勤表并输出 PDF 报告

4.1 任务描述与工具清单准备

为了把上面的理论串起来，我跑了一个完整的任务：给一个包含部门、员工号、姓名、出勤天数、缺勤原因的考勤 CSV，筛选出缺勤超过 3 天的人员，按部门统计人数，生成一张汇总表，再输出一份 PDF 报告。

工具清单我预先注册了四个：

这里有个技巧：给工具命名和描述的时候，我会在description里写上"什么时候该用这个工具"而不是只写"这个工具是什么"。比如filter_table的 description 是"当需要按数值条件筛掉数据行时使用，比如筛选缺勤天数 > 3"，模型看到这个描述时，把它选进调用链的准确率会明显更高。

4.2 Agent 的执行链路逐步拆解

任务输入后，我实时盯着右侧预览面板，Agent 的执行链路是这样的：

第一步，Agent 调用read_csv读取考勤文件，返回了 356 行数据的前 10 行预览。右侧面板立刻把 CSV 渲染成表格，我一眼能看到列名分别是部门, 员工号, 姓名, 应出勤天数, 实出勤天数, 缺勤原因。

第二步，Agent 判断需要计算缺勤天数，于是调用一个数学表达式工具或者直接在 harness 层做了列的计算。实际它选择的是process_table，参数是{"operation": "add_column", "column_name": "缺勤天数", "formula": "应出勤天数 - 实出勤天数"}。右侧表格刷新，多出一列"缺勤天数"。

第三步，Agent 调用filter_table，参数是{"condition": "缺勤天数", "operator": ">", "value": 3}。过滤完的结果有 47 行，右侧表格立刻变成过滤后的数据。这一步我看了一眼，发现有几行缺勤天数为 4，符合条件，没问题。

第四步，Agent 调用group_summary，按"部门"分组，对"员工号"做计数。右侧面板展示了两列的汇总表：部门、缺勤人数。合计是 47 人，和前一步一致，数据链路没有断。

第五步，Agent 调用render_pdf，把汇总表渲染成 PDF 报告。右侧预览区从表格模式切换成 PDF 模式，直接展示生成好的报告首页。我拖动滚动条检查了字体、分页、对齐，没有问题，最终交付。

整个链路跑下来，人工只需要在关键步骤扫一眼右侧的中间产物，不需要打开任何外部编辑器。这才是 Agent 该有的体验。

4.3 每一步的预览形态切换逻辑

这个实操里有个值得注意的细节：右侧预览区的形态是跟随产物类型自动切换的。CSV 数据变化时，它是一张可交互的表格；工具返回纯文本摘要时，它是一个带高亮的文本块；PDF 生成完毕时，它变成一个 PDF 阅读器容器。

自动切换的逻辑并不复杂，核心是 harness 层在每个工具执行完后，把返回结果打上 MIME 类型标签，比如text/plain、application/json、application/pdf、text/csv，前端预览面板根据 MIME 类型选择对应的渲染组件。这比让 Agent 自己决定"该怎么展示"要可靠得多。

4.4 人为介入的时机：不是每一步都需要人工，但是关键节点需要

实操里我并没有完全放手。我的介入点有两个：过滤后检查数据是否符合预期；PDF 生成后验证排版。这两个节点都是"成本低、收益高"的地方——发现问题时 Agent 还没跑偏太远，重新执行的成本很小。但像读取文件、列计算这种机械操作，我完全不碰，因为重复机械操作本来就是 Agent 的强项。

5. 高频故障与排查链路：这些报错我帮你踩过

5.1 "agent execution terminated due to error"：不只是超时的锅

热词里有一条很典型的报错：agent execution terminated due to error。我一开始以为这只是任务超时，后来排查多了发现，绝大多数情况下它是在工具调用环节出的问题，而不是任务本身太慢。

常见的真实原因是：某个工具抛了异常，harness 把错误文本返回给模型，但模型没有做出正确的恢复决策，连续重试几次后，执行器判定 Agent 失控，直接终止。比如有一次filter_table的operator参数传了>，而工具内部期望的是greater_than，解析失败抛了一个底层异常；模型看到异常以后，不是去换参数写法，而是反复调用同一套错误参数，最终触发终止。

排查这个问题的链路是：先看执行日志里最后一次工具调用是什么参数，再看异常文本是什么，最后确认模型有没有针对异常信息做出修正。如果模型没有修正，那就是工具 schema 写得太模糊，让模型猜不出正确参数格式。解决办法是在参数 description 里写清楚枚举值，或者 harness 层对参数做一次强约束校验。

5.2 表格处理三连坑：列宽、复制、合计行

表格场景里我经常遇到三个问题，几乎每个月都会在社区里看到类似提问。

第一个是 Word 表格列宽无法拖动。如果你用代码生成 docx 表格，列宽设置了但打开后还是自适应，多半是因为表格属性被设为"自动调整"或者单元格宽度单位不对。处理办法是显式设置表格布局为 fixed，并为每一列指定明确的宽度值。

第二个是预览区表格无法复制内容到 Excel。原因上面提过，HTML 表格复制到 Excel 时，默认是用 Tab 分隔还是用空格分隔取决于浏览器的实现。我自己的方案是：预览组件监听复制事件，拦截默认行为，把选中区域行拼接成\t分隔的文本写入剪贴板。这样从预览区复制到 Excel 永远不会乱。

第三个是合计行的边界问题。如果用group_summary生成了含合计行的表格，直接丢给渲染组件，合计行很容易在排序时被当成普通行参与排序，导致合计栏跑到表格中间。对策是在数据层给合计行加一个特殊标记，渲染组件识别到该标记后，将该行固定在表格底部，并且在导出 PDF 时特殊处理这一行的样式。

5.3 PDF 常见问题的排查链路

PDF 的中文乱码和字体问题，我在第 3 节提过。这里给一个排查链路，供你遇到问题时有章可循：

1. 先确定是"预览乱码"还是"下载后打开乱码"。如果只是预览乱码，大概率是浏览器 PDF 插件的字体渲染问题，下载后 PDF 其实没问题。
2. 如果下载后也乱码，检查 PDF 生成库是否嵌入了中文字体。用工具打开 PDF 的字体列表，看有没有中文字体记录；没有就是生成时没嵌入。
3. 如果你的 PDF 是扫描件,直接提取文本得到乱码，那就必须走 OCR 通道。
4. 如果对方机器上字体缺失导致缺字，最快的方案是整体转曲。

热词里的"web 页面 pdf 打印"也是一个高频场景。很多 Agent 想把网页内容直接打印成 PDF，但经常发现打印出来的页面排版错位。原因是网页打印时没有做打印样式适配。如果开发阶段就考虑打印需求，需要加一套@media print规则，把不需要的交互元素隐藏掉，并对表格设置统一的页边距和分页规则。

5.4 嵌套调用递归失控：一个容易被忽略的资源问题

工具调用嵌套不是 bug，但如果 Agent 判断失误，可能会形成递归失控。比如它调用了一个read_file工具，发现读进来的内容里提到了另一个文件，于是又去读那个文件，再读到的新内容又提到另一个文件，无限递归下去，把内存撑满，最后就是agent execution terminated due to error。

对这种问题的防御手段是在 harness 层加两个限制：最大工具调用次数，默认 15 次；单个文件最大读取大小，默认 5MB。超了就直接终止并提示用户任务过于复杂。OpenCowork 这类工作台应有类似的保护机制，但我也建议你如果自己在封装 Agent runtime，无论如何都要加上。

5.5 排查方法论：别让"重试"变成"盲试"

Agent 系统出问题时，最常见的错误做法是不看内部状态，盲目重新执行一遍。更有用的排查顺序是：

1. 打开执行轨迹，按时间线看每一步工具调用。
2. 对比任务目标和工具参数，找出哪一步的参数不合理。
3. 看工具返回的错误信息，确定是 schema 问题、数据问题还是资源问题。
4. 如果是 schema 问题，修改工具定义后重试。
5. 如果是数据问题，检查源文件格式。

6. 让 Agent 更稳定地干活：我总结的几条实战经验

6.1 工具返回统一化，是整套系统稳定的地基

我再强调一遍。无论注册多少个工具，返回结构必须统一。success、summary、preview、data四个字段我用了很久，非常稳。success让模型能快速判断这步是否成功；summary是一个不超过 50 字的中文摘要，让模型不用解析大数据也能理解发生了什么；preview是给用户界面渲染用的；data是给下游工具读取的引用。这四者职责分离，减少了模型因为"被迫理解大量数据"而犯错的概率。

6.2 工具参数越"笨"越好，别让模型猜

模型的工具调用能力再强，也架不住参数含义模糊。我在定义参数时坚持三个原则：枚举值尽量用字符串语义化（greater_than而不是>）；每个参数都给示例值；必填字段尽可能少。参数越少，模型出错的概率越低。

6.3 让 Agent 在交付前完成一次"自检"

我现在的 Agent 链路里都会加一个可选的verify_output工具。在最终交付前，Agent 会调用这个工具去检查输出文件是否存在、大小是否合理、是否包含预期关键词。比如 PDF 报告生成后，自检工具会检查文件大小大于 50KB，并且正文包含"合计"这个关键词，才认为通过。这个简单的自检，能挡掉很多"文件生成失败但 Agent 以为成功了"的情况。

6.4 别追求全自动，人为检查点是 Agent 的好朋友

最后一个经验可能和很多人想的不一样：我不追求 100% 全自动化。相反，我会在关键步骤主动设置"人工确认点"。比如过滤完数据后暂停一下，让用户确认"47 人符合条件"再继续；PDF 生成后暂停一下，让用户检查排版再交付。多花五秒钟，换来的是对最终结果的有效掌控。Agent 的浪漫之处在于它能替你扛下重复劳动，而这些关键节点上的确认，恰恰是"你在负责这件事"的体现。

这半年我用 OpenCowork 跑下来的整体感受是：工具调用的框架已经足够成熟，真正的差异在于产品层对细节的把控——预览区是否流畅、参数设计是否合理、错误恢复是否智能。把这些细节补到位，Agent 才能从"演示品"变成"生产力"。