学习 Agent Harness，强烈推荐读这个开源项目：腾讯 WorkBuddy 的开源复刻版 OpenWorkBuddy

大道无形19982026-08-25 17:15

大家好，我是猫叔。这篇是一篇工程笔记，也是一次项目推荐：我维护的开源项目 OpenWorkBuddy------一个跑在自己电脑上的桌面端通用 AI Agent，同时是一份完整可读的 Agent Harness 参考实现。如果你最近在研究 Agent 开发、想找值得读的开源项目，或者想搞清楚 Agent Harness 到底是什么，这篇文章应该对你有用。

项目地址：github.com/CatCatUncle/openworkbuddy

先说结论：学 Agent 开发，与其从 LangChain 这类深抽象框架读起，不如先读一个手写主循环、无构建步骤、clone 下来就能顺着读下去的完整实现。 OpenWorkBuddy 就是按这个思路写的------npm install 即用，产出真实文件（PPT/Word/Excel），会话、文件、API Key 全部不出本机，不绑定任何大模型，个人和学习用途免费。

目录
一、它是个什么东西
[二、Agent 主循环：先把 Loop 读懂](#二、Agent 主循环：先把 Loop 读懂)
[三、为什么说它是学 Agent 开发的好教材](#三、为什么说它是学 Agent 开发的好教材)
[四、什么是 Agent Harness？](#四、什么是 Agent Harness？)
五、两个值得细读的设计
[六、评测系统：把 Agent 当黑盒考](#六、评测系统：把 Agent 当黑盒考)
七、五分钟上手
八、同类项目怎么选，以及什么时候不该用它
九、协议与贡献
FAQ

一、它是个什么东西

OpenWorkBuddy 是对腾讯 WorkBuddy 产品形态的独立开源复刻（与腾讯无任何关系，不含其代码和资源）。产品逻辑一句话讲完：

你给一句自然语言，它自主规划 → 拆步骤 → 调工具 → 循环执行，最后交付一份能直接打开验收的文件。

四种工作模式：

模式 行为 典型用途
Ask 只问答，不动任何东西 咨询、解释
Plan 只出计划不执行 方案评审
Goal 目标驱动，自动验收 交付文件类任务
Craft 完整执行 需要多步工具调用的复杂任务

真实使用场景：

场景 一句话指令 交付物
季度复盘 "帮我出一份 Q3 复盘 PPT，数据用这个 Excel" .pptx
行业调研 "调研一下国内 AI 陪伴产品，出一份报告" Markdown / Word
网页制作 "把这份材料做成一个能在手机上看的网页" HTML
定时晨报 "每天早上 9 点抓行业新闻，做成晨报发我飞书" 定时任务 + IM 推送
简历筛选 "批量读这份 JD 和这些简历，生成 Excel 汇总和 Word 分析报告" .xlsx + .docx

二、Agent 主循环：先把 Loop 读懂

读一个 Agent，第一个要看的永远是主循环。框架把 Loop 藏在深处，OpenWorkBuddy 直接把它写在 agent.js 里，剥掉错误处理和上下文管理后，骨架就这么长：

复制代码 
// agent.js 主循环（简化示意，完整实现见源码）
while (true) {
  const plan  = await llm.plan();            // ① 规划：下一步干什么
  if (plan.done) break;                      // ② 模型自主判定：任务是否完成
  const result = await execute(plan.tool);   // ③ 执行：调用具体工具
  verifyOutput(plan, result);                // ④ 成果核验闸门
  context.push({ plan, result });            // ⑤ 观察结果，写入上下文
}

就这么五步，循环转起来就是 Agent。但把每一步做扎实，全是工程细节：

  • 规划不是一次性的------每次循环都重新规划，模型根据上一次工具结果动态决定下一步，这就是 ReAct 思路的朴素实现
  • 执行是可插拔的 ------execute 内部按工具名路由到 run_node / run_shell / web_search / fetch_url / render_page / gen_diagram 等 16+ 内置工具，新增工具就是注册一个处理函数
  • 核验是强制的------声称写了文件但磁盘上没有、或只有 0 字节空壳，直接打回重做（最多 2 次），这是后面要展开讲的成果核验闸门
  • 上下文是有管理的------对话越来越长，模型会越来越"笨"，按对话归档成果、超出窗口做摘要截断，而不是无脑全塞

我建议的源码阅读顺序也是这条线：agent.js → store.js → skills/ → tools/ → 评测系统。读完这套代码，"Agent 到底是怎么转的"就不再是概念，而是肌肉记忆。

三、为什么说它是学 Agent 开发的好教材

多数 Agent 框架的抽象层级很深，读代码像剥洋葱------剥了三层还没见到 Loop。OpenWorkBuddy 反其道而行：

  1. Agent 主循环是手写的 CommonJS （agent.js）：没有框架，规划 → 工具调用 → 观察 → 循环，一屏能看完
  2. 没有构建步骤、没有前端框架 ：前端是手写的 public/index.html，改完刷新即生效，不用先学一套工具链
  3. 无框架黑盒：工具调度、上下文管理、成果核验全是显式代码，不是被框架藏起来的魔法
  4. 配套评测系统：15 道分层任务（L1/L2/L3），pass@1 看能力、pass^k 看稳定性，学完可以自己给 Agent 出考卷

这四点对学习者意味着：你不需要先掌握框架的抽象，再逆推它怎么落地；而是先看到"最小可工作的 Agent 长什么样"，再看任何框架都是降维。

四、什么是 Agent Harness？为什么 2026 年大家都在聊

Agent Harness（智能体运行时装具）指包裹在大模型外围、让模型真正能干活的那套工程系统：主循环、工具调度、上下文管理、记忆、安全闸门、评测。模型只是 Harness 里一个可替换的零件。

2026 年业界共识正在从"卷模型"转向"卷 Harness"------同一个模型，Harness 的好坏直接决定产出质量。OpenWorkBuddy 恰好是一份完整的、可运行、可阅读的 Harness 参考实现：

Harness 组件 OpenWorkBuddy 中的实现
主循环（Agent Loop） 手写 agent.js：规划 → 工具调用 → 观察 → 循环
工具层 run_node / run_shell / web_search / fetch_url / render_page / gen_diagram 等 16+ 内置工具
上下文与记忆 按对话归档成果、PROGRESS.md 断点续跑、只读工具并发（上限 3 路）
安全闸门 命令审批、文件黑名单、网络白名单、run_node 代码也过闸、环形审计日志
扩展机制 Markdown 技能 + MCP 连接器 + Agent Plugins 1.0.0
评测体系 15 道分层任务，pass@1 / pass^k，确定性败因码

学 Harness 为什么读源码而不是读论文？因为核心在工程取舍，举三个例子：

  • 成果核验闸门：声称写了文件却不在磁盘上、或是 0 字节空壳，直接打回重做（最多 2 次）
  • 原子写 + .bak 兜底：先写临时文件再原子重命名，断电不会产生半个 JSON
  • 长任务自动续跑：撞预算上限，从 PROGRESS.md 断点接着跑，不推倒重来

这些细节论文里没有，源码里全有。

五、两个值得细读的设计

5.1 安全闸门：Agent 手里有 shell，门必须是真门

给 Agent 一把 shell，安全就不是配置项，而是核心架构。OpenWorkBuddy 的闸门分四层：

  • 权限档位：只看不动 → 每步都问 → 自动改文件 → 全自动，用户自己选
  • 命令审批：把命令拆开逐段核验，而不是整条字符串黑名单匹配
  • 文件黑名单：排在命令放行名单前面，拦得住"顺手"而不是"刻意绕"
  • run_node 代码也过闸：只守 run_shell 那扇门是守不住的，AI 完全可以用代码做同样的事

命令审批的实现思路（简化示意）：

复制代码 
// run_shell 前的逐段核验（简化示意，完整实现见源码）
function approveCommand(cmd) {
  // 1. 先按换行 / && / || / ; 拆段，每段独立核验
  const segments = cmd.split(/\n|\|\||&&|;/);

  for (const seg of segments) {
    // 2. 包装词检测：$() / 反引号 / |bash / sh -c，都是逃逸手法
    if (/\$\s*\(|`|\|bash|sh\s+-c/.test(seg)) return BLOCK;

    // 3. 黑名单命令（rm -rf /、:(){:|&};: 等）直接拦
    if (isBlacklisted(seg)) return BLOCK;

    // 4. 不在白名单的命令 / 域名 → 弹审批，等用户点头
    if (!isWhitelisted(seg)) return ASK_USER;
  }
  return ALLOW;
}
  • 审计日志 ：环形 1000 条，落在 data/audit.json，Agent 每一步干了什么都可回溯

5.2 技能系统：一个 Markdown 文件就是一个技能

复制代码 
# 调研报告技能

## 触发条件
用户要求调研、分析、评测某个主题时触发

## 工作流程
1. 先用 web_search 搜索主题关键词
2. 从搜索结果中挑 5-8 个高质量来源
3. 用 fetch_url 逐个抓取全文
4. 提取关键信息，分类整理
5. 用 write_file 生成 Markdown 报告
6. 最后用 gen_diagram 画一个对比图

写完放进 skills/，存盘，下一条任务就生效。不改代码、不重启、不打包。内置 skill-creator，还能让 AI 自己写技能------这其实就是把"技能"也变成 Agent 能操作的产物，形成自举。

六、评测系统：把 Agent 当黑盒考

学 Agent 开发，光读代码不够，要能验证"改了一行之后 Agent 是变强还是变弱"。OpenWorkBuddy 的评测系统把 Agent 当黑盒：

复制代码 
npm run eval -- --repeat 3 --judge Y --save-baseline
  • 15 道分层任务：L1 单工具调用（如"搜一下 X 并总结"）、L2 多工具编排（如"查数据并画图"）、L3 长任务文件交付（如"读 Excel 生成 PPT"）
  • pass@1：一次执行就通过的比例，看"能力上限"
  • pass^k：重复 k 次至少一次通过的比例，看"稳定性"（LLM 有随机性，单次失败不代表不行）
  • 确定性败因码：失败不是一句"没通过"，而是可定位的失败类别（文件缺失/格式错误/工具调用失败...），改 bug 不用猜
  • 测试不需要 API Key------npm test 用模拟 LLM，CI 里就能跑

踩坑记录：开发中遇到的真问题

写 Agent 主循环时踩过的几个坑，都变成了上面的架构决策：

坑 现象 解法
幻觉交付 LLM 声称"已生成 PPT"，磁盘上根本没有 成果核验闸门：声称写了文件必须真实存在且非空
上下文爆炸 任务越长模型越笨，最后答非所问 按对话归档 + 摘要截断，控制上下文窗口
断电半成品 写一半崩了，JSON 文件损坏 原子写（临时文件 + rename）+ .bak 兜底
预算耗尽重来 长任务跑到一半撞预算，全盘推倒 PROGRESS.md 断点续跑，从断点接着做

七、五分钟上手

复制代码 
git clone https://github.com/CatCatUncle/openworkbuddy.git
cd openworkbuddy
npm install
npm run app    # 桌面版，推荐自己用

需要 Node.js 18+ 和一个大模型 API Key。不想花钱就装 Ollama 跑本地模型，连 Key 都不用。

三种跑法：

  • npm run app --- 桌面版（Electron 窗口）
  • npm start --- 纯服务端，浏览器打开 localhost:3800
  • npm run cli -- "帮我写一份本周周报" --- 命令行，适合脚本调用

macOS/Linux 一键脚本：bash install.sh

国内装 Electron 卡住的话，先设镜像：export ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/

模型支持：DeepSeek / 通义 Qwen / 智谱 GLM / Kimi / OpenRouter / Ollama，界面切换、热生效。IM 远程指挥支持飞书 / QQ / 企微 / 微信 / 钉钉------手机上下任务，干完推结果。定时任务是标准 cron 5 字段，错过的会补跑（最多回补 24 小时）。

八、同类项目怎么选，以及什么时候不该用它

项目 定位 适合谁
OpenWorkBuddy 桌面端 Agent，交付真实文件，源码可读 想用 + 想学 Agent 的人
OpenClaw 消息平台 AI 助手（Discord/TG/Slack） 重度多渠道 IM 用户
Hermes Agent 自进化记忆型 Agent 研究 Agent 记忆架构
n8n / Dify 可视化工作流编排 自动化运维场景

说句实话，它不适合所有人：

  • 要 100% 确定性输出的生产流水线------LLM 有随机性，这类场景该用传统脚本或带严格校验的编排工具
  • 公司核心业务直接使用------PolyForm Noncommercial 协议限制商业用途，公司场景需要先谈商业授权
  • 追求极致推理性能------它是"够用"的通用 Agent，不是为单一任务调优的特化方案

敢说缺点的项目才值得长期跟。这些边界也正是把它当教材的价值所在：你学的是它怎么在工程上做取舍，而不是无脑抄作业。

九、协议与贡献

采用 PolyForm Noncommercial 1.0.0：个人自用、学习、研究、学校、科研机构、公益组织、政府用途免费；公司实际业务使用、做 SaaS、打包售卖需要商业授权。源码完全公开可读可改可分发。

贡献路径：

复制代码 
Fork → 建分支（feat/xxx 或 fix/xxx）→ 改代码 + 补测试 → npm test 全绿 → 开 PR

好上手的方向：写一个技能（一个 Markdown 文件，不碰代码）、补一个模型服务商预设、加一个内置专家、接一个新的 IM 渠道。

FAQ

Q：OpenWorkBuddy 和腾讯 WorkBuddy 是什么关系？

独立开源实现，与腾讯没有任何关系，不含其任何代码或资源。

Q：为什么不基于 LangChain？

刻意不用。框架省了工程量，但把主循环、工具调度、上下文管理全部变成了黑盒------对使用者是方便，对学习者是灾难。OpenWorkBuddy 选择把 Loop 摊开写，多花一点代码，换一个"能读懂"。

Q：数据会泄露吗？

默认只监听 127.0.0.1，会话、文件、API Key 全部存在本机，config.json 已在 .gitignore 里。只有你主动配置的网络工具才会出网。

Q：会写坏我的文件吗？

权限档位默认"每步都问"，文件黑名单拦关键路径，命令和代码都过闸；真要放开，也能切"自动改文件"或"全自动"档位------风险由你自己决定放多大。

Q：学习 Agent 开发除了读代码还有什么方式？

读代码 + 跑评测。评测系统把 Agent 当黑盒考，改一行代码就能看到 pass@1 的变化，比看文章直观得多。

Q：支持 Windows 吗？

Electron 跨平台，桌面版 Windows/macOS/Linux 都能跑；一键脚本 install.sh 目前是 macOS/Linux，Windows 上直接 npm start 走服务端模式即可。

Q：支持国产大模型吗？

支持，DeepSeek、Qwen、GLM、Kimi、火山方舟都有预设渠道。想彻底不出网，接 Ollama。

写在最后：如果你在找 2026 年值得读的开源 AI Agent 项目，或者想系统了解 Agent Harness 的工程实现，欢迎来 Star、Fork、提 Issue：

项目地址 ：github.com/CatCatUncle/openworkbuddy

有问题评论区交流，写得不准确的地方欢迎老鸟们指正。

热门推荐
01国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）02GitHub 镜像站点032026 国产 AI 大模型横评：DeepSeek、通义千问、Kimi、文心一言、星火、豆包谁更能打？04微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新05历年考研数学一、数学二、数学三真题试卷及答案PDF06Agnes AI 免费 API 接入指南：文本、生图、生视频，一套接口全免费07AI 编程 IDE 全景解析 2026：Agent 全面接管开发链路082026年7月AI圈大地震：GPT-5.6被政府限制、Claude入驻Slack、Anthropic自研芯片09VSCode+CodeX扩展，无法启动10如何新建文件夹？ 电脑新建文件夹的4种方法