OpenWorkBuddy 实战：用 Agent Harness 把 LLM 输出变成可验收的办公产物

1. 从"能聊"到"能交差"：OpenWorkBuddy 到底在解决什么

大模型接入办公场景这件事，过去两年我见过太多团队栽在同一个坑里：Demo 演示时惊艳全场，真到了业务部门手里，三天就被打回原形。原因不复杂——模型能生成一段看起来不错的文字，但业务要的不是"看起来不错"，而是一份能直接归档、能签字、能追责的交付物。这两者之间的鸿沟，就是 OpenWorkBuddy 这类 Agent Harness 想填的东西。

先把概念掰开。Agent Harness这个词最近被讨论得很多，但很多人把它和 Agent 框架混为一谈。我的理解是：Agent 框架（比如各种 agent 开发库）解决的是"怎么让模型调用工具、怎么编排多步推理"；而 Harness 解决的是"怎么把一个不可控的 LLM 调用，约束成一条可验收的产线"。打个比方，框架是发动机和传动轴，Harness 是整车的质检工位、安全带和仪表盘。OpenWorkBuddy 的定位就在后者——它不重新发明 Agent 的推理循环，而是给这个循环套上一层"办公产物"的验收外壳。

这个区别为什么重要？因为办公场景对"产物"的要求和聊天场景完全不同。聊天可以容忍模糊、可以来回追问、可以"差不多就行"；但一份周报、一份合同摘要、一份数据核对表，它有明确的格式、明确的字段、明确的完整性要求。LLM 天然是概率性的，你让它自由发挥，它可能这次给你 8 个字段，下次给你 6 个还漏了两个关键项。Harness 的核心价值，就是把这个概率性输出，通过结构约束、校验回路和重试机制，收敛成一个确定性的、可验收的结果。

我拿关键词里的MCP来说。MCP（Model Context Protocol）在这套体系里扮演的是"工具与上下文的标准接口"角色。OpenWorkBuddy 通过 MCP 把外部能力（读文件、查数据库、调 API、写文档）标准化地暴露给模型，这样 Harness 层就不需要为每个工具写一套适配代码。这一点在实际项目里省下的工作量非常可观——我见过一个团队为了对接五个内部系统，硬编码了五套工具调用逻辑，后来换成 MCP 统一接入，维护成本直接砍掉一大半。

那 OpenWorkBuddy 适合谁来参考？三类人最该看：一是正在做AI Agent落地、被"输出不稳定"折磨的开发者；二是想把 LLM 能力嵌进现有办公流程、但苦于无法验收的产品和业务负责人；三是想理解Agent Harness 和 Agent 区别、准备自己搭一套约束层的架构师。下面我会从产物定义、约束机制、MCP 集成、容错重试、验收标准几个层面，把这套东西拆到能直接抄作业的程度。

2. 办公产物的"可验收"到底意味着什么

2.1 把"一段文字"翻译成"一份有 schema 的交付物"

大多数人做 LLM 办公应用，第一步就错了：他们让模型"写一份周报"，然后拿到一段 Markdown 就结束了。这在 Harness 视角下是没法验收的，因为你根本不知道这份周报"完整"的标准是什么。OpenWorkBuddy 的思路是，先把产物定义成一个结构化的 schema，再让模型去填充。

举个具体例子。假设产物是"项目周报"，它的 schema 可能长这样：

{ "project_name": "string, required", "week_range": "string, required, 格式 YYYY-MM-DD ~ YYYY-MM-DD", "completed_items": "array[string], required, 至少 1 项", "in_progress_items": "array[string], required", "risks": "array[{desc: string, level: enum[高,中,低]}], optional", "next_week_plan": "array[string], required, 至少 1 项" }

有了这个 schema，验收就有了依据。模型输出后，Harness 层做三件事：结构校验（字段是否齐全、类型是否正确）、语义校验（比如 week_range 是否是合法日期区间、completed_items 是否为空）、业务校验（比如 risks 里的 level 是否在枚举范围内）。任何一项不过，就触发重试或人工介入。

我特别想强调 schema 设计里的一个经验：required 字段不要贪多。我早期做类似系统时，恨不得把所有字段都设成必填，结果模型为了凑字段开始编造内容，反而降低了质量。后来改成"核心字段必填 + 次要字段可选 + 缺失时明确标注 N/A"，整体可用性反而上去了。这个取舍在 OpenWorkBuddy 的产物定义里同样适用。

2.2 验收标准要前置，而不是事后补

很多团队的做法是：先让模型跑，跑完发现不对，再回头加校验。这是典型的"事后补验收"，代价是每次出问题都要重新梳理规则。Harness 的正确姿势是验收标准前置——在定义产物的时候，就把"什么样算合格"写清楚，甚至写成可执行的校验函数。

我一般会把验收标准分成三层，这个分层在 OpenWorkBuddy 的实践里也很有参考价值：

这个分层的好处是，不同层级的失败可以用不同的成本去处理。结构层失败最便宜，重试就行；业务层失败最贵，必须人工兜底。把这三层分开，整个系统的成本和可靠性就能算得清楚。

2.3 为什么"可验收"比"高质量"更值得追求

这里有个反直觉的观点：在办公场景里，可验收性比绝对质量更重要。原因在于，办公流程本身就是一个验收流程——你的产出要交给上级、交给客户、交给审计，它必须能被检查。一份"质量很高但无法验证"的产物，在流程里是走不通的；而一份"质量中等但每个字段都可追溯、可核对"的产物，反而能顺利流转。

OpenWorkBuddy 的设计哲学我认为就落在这个点上。它不追求让模型一次生成完美内容，而是追求让每一次生成都可被检查、可被修正、可被追责。这个思路对做企业级 AI 应用的人特别有启发：别老想着提升模型能力，先把验收链路搭起来，收益往往更大。

3. Harness 的约束机制：怎么把概率输出收敛成确定结果

3.1 约束的三个抓手：格式、工具、流程

Harness 约束 LLM 的手段，我总结下来主要是三个抓手，OpenWorkBuddy 基本都覆盖了。

第一个抓手是格式约束。通过 JSON Schema、Function Calling、结构化输出（structured output）等机制，强制模型按指定格式返回。现在主流模型 API 大多支持 JSON mode 或 schema 约束，Harness 要做的就是把这个能力用足。但要注意，格式约束只能保证"形状对"，保证不了"内容对"——模型完全可能给你一个格式完美但内容胡扯的结果。所以格式约束是必要条件，不是充分条件。

第二个抓手是工具约束。通过 MCP 把可用工具限定在一个白名单里，模型只能调用被授权的工具。这既是安全考虑，也是质量考虑——工具越少，模型选错的概率越低。我见过一个案例，某团队给模型开放了二十多个工具，结果模型在简单任务上频繁调错工具，后来砍到五个核心工具，准确率立刻回升。

第三个抓手是流程约束。把复杂任务拆成固定步骤，每一步都有明确的输入输出和校验点。比如"生成合同摘要"可以拆成：读取合同 → 提取关键条款 → 分类归纳 → 生成摘要 → 校验完整性。每一步单独校验，比让模型一口气生成整份摘要要可靠得多。

3.2 重试不是万能药：什么时候该重试，什么时候该放弃

重试是 Harness 最常用的容错手段，但用不好会变成"烧钱机器"。我的经验是，重试要分情况：

• 格式错误：值得重试，而且通常一次就能修好，因为模型只是没按格式来。
• 内容缺失：值得重试，但要在 prompt 里明确指出缺了什么。
• 内容错误：谨慎重试，因为模型可能"错得很自信"，重试反而强化错误。
• 业务规则冲突：不要重试，直接转人工，因为这是模型能力边界外的问题。

OpenWorkBuddy 这类 Harness 一般会设置最大重试次数（常见是 2-3 次）和退避策略。我个人的配置习惯是：格式类错误重试 3 次，内容类错误重试 1 次，业务类错误 0 次直接转人工。这个配置不是拍脑袋来的，是根据错误类型的"可修复概率"定的——格式错误修复概率高，业务错误修复概率低，重试纯属浪费。

提示：重试时一定要把上一次的失败原因塞进新的 prompt，否则模型很可能原样再错一遍。这是很多人忽略的细节。

3.3 用 LLM as Judge 做二次校验的利与弊

关键词里出现了LLM as judge，这在 Harness 里确实是个常用手段：用一个模型去评判另一个模型的输出是否合格。它的好处是能处理一些规则难以描述的语义问题，比如"这段摘要是否准确反映了原文主旨"。

但我要泼盆冷水：LLM as Judge 不能作为唯一的验收手段。原因有三：一是它本身也是概率性的，会误判；二是它增加了成本和延迟；三是它可能和生成模型"同源偏见"，生成模型犯的错，评判模型也可能看不出来。我的做法是，把 LLM as Judge 作为辅助校验，和规则校验配合使用——规则能判的用规则，规则判不了的才交给 Judge，而且 Judge 的结论只作为"可疑标记"，最终仍由人工或业务规则定夺。

3.4 约束的边界：别把模型管死

约束是为了可靠，但约束过头会让模型失去价值。我见过一些团队，把 prompt 写得极其死板，模型只能做填空题，稍微需要一点判断的地方就卡住。这种系统虽然"稳定"，但和传统模板引擎没区别，白白浪费了 LLM 的理解能力。

好的 Harness 应该做到**"该管的管死，该放的放开"**。格式、工具、关键业务规则管死；内容的组织方式、措辞、细节补充放开。OpenWorkBuddy 在产物定义上给了 schema，但在 schema 内部留了自由度，这个平衡点找得比较准。实操中我的建议是：先放开，观察模型在哪里出问题，再针对性地加约束，而不是一开始就把所有可能性都堵死。

4. MCP 在 OpenWorkBuddy 里的角色：工具接入的标准化

4.1 MCP 解决的"重复造轮子"问题

MCP 是什么？简单说，它是一套让模型和外部工具、数据源对话的标准协议。在没有 MCP 之前，每接一个工具，你都要写一套适配代码：定义函数、描述参数、处理返回、做错误映射。工具一多，这套代码就成了维护噩梦。

MCP 把这个过程标准化了：工具方按 MCP 协议暴露能力，Harness 方按 MCP 协议调用，双方解耦。对 OpenWorkBuddy 这种要对接大量办公系统（文档、表格、邮件、数据库）的 Harness 来说，MCP 的价值尤其明显——它让"接入一个新工具"从"写代码"变成了"配置"。

我实测过一个对比：用传统方式接一个内部 API，从读文档到跑通大概要半天；用 MCP 接同样的 API，如果对方已经有 MCP server，配置加调试半小时搞定。这个效率差距在工具数量多的时候会被放大。

4.2 工具描述的质量决定调用准确率

MCP 接入本身不难，难的是工具描述写得好不好。模型是根据工具的名称、描述、参数说明来决定调不调、怎么调的。描述写得含糊，模型就会乱调。

我踩过的坑：早期给一个"查询订单"工具写的描述是"查询订单信息"，结果模型在需要"查询物流"的时候也调它，因为描述太泛。后来改成"根据订单号查询订单的支付状态、金额和创建时间，不包含物流信息"，误调率立刻下降。

写工具描述的几个经验：

• 说清楚"做什么"和"不做什么"，边界比功能更重要。
• 参数说明要带示例，尤其是格式敏感的字段（日期、ID）。
• 返回结构要明确，让模型知道能拿到什么。
• 避免功能重叠的工具，如果两个工具都能干一件事，模型会纠结。

4.3 MCP 工具流式输出与产物落盘

关键词里提到"使用 MCP 工具流式输出内容到文件"，这在办公产物场景里很实用。比如生成一份长报告，与其等模型全部生成完再落盘，不如流式写入文件，边生成边保存。好处是：一是降低内存压力，二是中途失败也能保留部分结果，三是用户可以实时看到进度。

OpenWorkBuddy 这类 Harness 在做产物落盘时，我建议注意几点：写入前先校验 schema，别把半成品写进正式目录；用临时文件 + 原子重命名，避免写入中断导致文件损坏；记录生成元数据（用的哪个模型、哪次调用、耗时多少），方便后续追溯。这些细节看着琐碎，但在真实办公流程里，出一次文件损坏就可能让整个系统失去信任。

4.4 MCP 的安全边界

工具接入带来能力，也带来风险。MCP 工具如果有写权限（改文件、发邮件、调支付），就必须做权限控制。我的做法是：读写分离，读工具可以宽松授权，写工具必须严格审批；操作留痕，每次工具调用都记录参数和结果；敏感操作二次确认，比如发送邮件前让用户确认收件人和内容。

这些不是 OpenWorkBuddy 独有的要求，而是任何把 LLM 接入真实系统的项目都必须考虑的。Agent 安全这个词最近很热，但落到实操，无非就是权限、留痕、确认这几件事做到位。

5. 容错与重试：让系统在模型犯错时还能交付

5.1 错误分类是容错的前提

容错做得好不好，前提是错误分得清。我一般把 LLM 调用中的错误分成四类：

这个分类的价值在于，它让"重试"这个动作变得有针对性。传输错误无脑重试就行；格式错误要带着错误信息重试；内容错误要谨慎；业务错误重试也没用。很多团队把所有错误一视同仁地重试，结果就是又慢又贵还解决不了问题。

5.2 降级策略：模型不行的时候，系统还能转

容错的高级形态是降级。当模型反复失败时，系统不应该直接崩溃，而应该退到一个"虽然不完美但能用"的状态。比如：

• 模型生成失败 → 用模板填充 → 人工补充
• 主模型超时 → 切备用模型 → 标记质量待复核
• 自动校验不通过 → 输出草稿 + 问题清单 → 人工修订

OpenWorkBuddy 作为 Harness，降级策略是它区别于普通 Agent 框架的关键能力之一。普通框架关注"怎么让模型完成任务"，Harness 关注"模型完不成任务时怎么办"。后者才是办公场景真正需要的。

5.3 幂等性：重试不能产生副作用

如果工具调用有副作用（写文件、发消息、改数据），重试就必须考虑幂等性。否则一次超时重试，可能发出两封邮件、写两份文件。

我的做法是给每个有副作用的操作分配一个幂等键（比如任务 ID + 操作类型），工具方根据幂等键去重。这个机制在 MCP 工具设计时就要考虑进去，不能等出了问题再补。我见过一个团队因为没做幂等，重试机制上线第一天就发了重复通知，被业务方投诉，最后不得不回滚。

5.4 可观测性：出问题时你能查到什么

容错系统必须可观测。我要求至少记录这几样：每次调用的输入输出、每次校验的结果、每次重试的原因、最终产物的来源链路。有了这些，出问题时才能快速定位是模型的问题、prompt 的问题、工具的问题还是校验规则的问题。

这块我踩过最大的坑是：早期只记录最终结果，不记录中间过程，结果一次批量失败排查了整整两天。后来加上全链路日志，同样的问题十分钟就能定位。可观测性不是锦上添花，是容错系统的地基。

6. 从 Demo 到产线：我踩过的坑和总结的配置

6.1 坑一：把 prompt 当代码写，却忘了版本管理

我早期做 Agent 项目，prompt 直接写在代码里，改一次发一次版。后来 prompt 越改越多，出了问题根本不知道是哪版 prompt 导致的。OpenWorkBuddy 这类 Harness 应该把 prompt 当配置管理，独立版本、独立发布、可回滚。

具体做法：prompt 存成独立文件或配置项，带版本号；每次调用记录用了哪个版本；A/B 测试不同版本的效果。这个习惯养成后，prompt 调优的效率会高很多。

6.2 坑二：验收规则写得太死，业务一变就全废

验收规则如果硬编码，业务规则一变就要改代码。我的经验是把验收规则配置化：用 JSON 或 DSL 描述校验逻辑，业务方自己就能改。比如"金额必须大于 0"这种规则，写成配置项，比写死在代码里灵活得多。

6.3 坑三：忽略 token 成本，跑着跑着账单爆炸

LLM 调用是有成本的，重试、Judge、多轮校验都会放大成本。我建议在 Harness 里加成本监控：记录每次任务的 token 消耗，设置预算上限，超了就降级或告警。这个在 Demo 阶段看不出来，一上量就是大问题。

6.4 一套可参考的 Harness 配置清单

最后把我自己常用的一套配置整理出来，供参考：

harness: max_retries: 3 retry_backoff: exponential validation: schema_check: true semantic_check: true llm_judge: optional fallback: on_format_fail: retry_with_hint on_content_fail: mark_and_retry_once on_business_fail: human_review observability: log_input_output: true log_validation: true log_retry_reason: true cost: budget_per_task: 0.5 alert_threshold: 0.8

这套配置不是标准答案，但覆盖了 Harness 该管的核心项。你可以根据自己的业务调整阈值和策略。

6.5 一个真实的落地体会

我在一个文档处理项目里用过类似 OpenWorkBuddy 的思路。最开始追求"模型一次生成完美结果"，准确率卡在 70% 上不去。后来改成"允许模型犯错，但保证错误可被发现和修正"，把验收链路搭起来，最终交付可用率到了 95% 以上。这个转变让我意识到，在办公场景里，工程能力比模型能力更能决定成败。模型再强，没有 Harness 兜底，也进不了真实流程；模型一般，但 Harness 做得好，反而能稳定交付。

如果你正在做类似的事，我的建议是：先把产物 schema 和验收规则定清楚，再考虑模型选型和 prompt 优化。顺序反了，后面全是返工。