项目地址：github.com/CatCatUncle/openworkbuddy
作者：开发者猫叔（多年互联网大厂一线开发经验），个人/非商用免费，商用需单独授权。

WorkBuddy 源码OpenWorkBuddyAgent HarnessAI Agent 私有化部署Agent 框架源码MCP 连接器开源

0. 这篇写给谁

如果你在 CSDN 刷到这篇，大概率是下面三种情况之一：

  1. 最近腾讯 WorkBuddy 很火，你想研究它的实现，但官方给的多数是使用教程，找不到能读的源码；
  2. 你在追 Agent Harness（Agent 运行时/控制器） 这个新概念，想要一个能拆开看、能动手改的真实工程，而非层层封装的框架黑箱；
  3. 你想在自己的服务器/电脑上私有化部署一个能真交付文件的 AI 办公 Agent，数据不出本机、还能换任意模型。

这篇把一条路走通：Clone 一个叫 OpenWorkBuddy 的开源项目，它就是腾讯 WorkBuddy 的开源复刻版，而且源码本身就是一份极好的 Agent Harness 学习材料。

1. 先泼一盆冷水：市面上的 Agent 框架，大多"能跑不能读"

先说个让人头疼的现状。

现在是 2026 年，能跑的 Agent 框架其实多到数不过来。但你随便挑一个 opensource 的 agentic 框架去读源码，大概率撞上同一个问题：它是多层抽象叠出来的黑箱。

你想搞明白"模型说它要调用 write_file 工具，代码到底是怎么把它翻译成一次真实的磁盘写入的"——得穿过基类、抽象层、接口实现三层继承，追完一通脾气都没了。更别提各家模型（DeepSeek 的工具调用是特殊 token、OpenAI 是 function calling、Anthropic 是 tool_use 结构）怎么归一成一件事，多数框架扔给一个 adapter 就完了，你也读不到里面的取舍。

而 Agent 这行的价值，恰恰藏在这些"实现细节"里。 调度、约束、恢复、审计——这些才是 harness 的全部意义。一个把你挡在外面的框架，你学不到东西，改起来更是噩梦。

OpenWorkBuddy 是反着来的：它把这一切摊开写给你看，而且写得很干净。

2. 它到底是个什么项目

一句话：腾讯 WorkBuddy 的开源复刻版。

WorkBuddy 是腾讯的 AI 办公 Agent——你给它一句话，它自己规划、拆解、动手，最后交给你一份能打开验收的成果文件（PPT / Word / Excel / 网页 / 调研报告 / 公众号推文），而不是一段聊天记录。它一度是国内日活最高的生产力 Agent 产品。

OpenWorkBuddy 把这件事复刻到了你的本机，并且加了三条很硬的原则：

原则 说明
完全自托管 数据、会话、API Key 全在本机，默认只监听 127.0.0.1，不主动外传
模型不锁定 DeepSeek / 通义 Qwen / 智谱 GLM / Kimi / OpenRouter / Ollama 本地模型，界面点一下就切，不出网也能跑
交付真文件 PPT / Word / Excel / 网页都是真生成，声称写了文件但磁盘上没有，会被内置闸门打回去重做

它不绑任何一家大模型——这是它和直接拿 Claude / GPT 套壳的最大区别。

3. 源码层面最值钱的三块：它把 Agent Harness 拆给你看

3.1 Agent 主循环是手写的，没有框架

项目里 agent.js 是 Agent 运行时：协调者/专家循环、工具路由、系统提示，全部手写，没有引入任何 agentic 框架。你顺着读能看完整条链路：

  1. 模型输出一个 tool call
  2. 拆解、校验（包括把 DeepSeek 那类特殊 token 的"假调用"救回来还原成真调用）
  3. 路由到真实工具（tools.js）
  4. 工具执行结果喂回上下文
  5. 循环继续或走收尾逻辑

而且工程上零负担：CommonJS、Node 18+ 直接跑、没有构建步骤、没有前端框架（前端就是一个手写的 public/index.html）、中文注释写"为什么"不写"是什么"。改完刷新即生效，不用打包。

对想弄懂 Agent 到底怎么转的人，这是最干净的教材。

3.2 生产级问题它当正经事做了

这是它和其他 demo 拉开差距的地方。很多开源 demo 跑通一次 hello world 就没了，OpenWorkBuddy 处理了一堆上传生产才撞得上的坑：

  • 断点续传：刷新页面 / 断网 / 电脑睡醒，任务自动接回直播，不从头再来
  • 上下文字节截断：超预算时截短较早的工具原文，界面上明写截了多少字，不假装模型一直看得到全文
  • 原子写 + .bak 兜底：会话/账本/定时任务表先写临时文件再改名，断电最多丢最后几秒，不会剩半个 JSON
  • 任务中途也落盘（最多每 5 秒一次）：跑了半小时的任务不因一次崩溃从头再来
  • 命令闸：恶意的 rm -rf、$(...)、反引号、子 shell 这些写法，拆成一段一段真拦（下面有单独的测试覆盖）

3.3 它连"自己稳不稳"都能测

  • 智能体评测：15 道分层任务（L1 基础 / L2 陷阱 / L3 多约束）把整个 agent 当黑盒考，用 pass@1 看能不能、k 次全过看稳不稳
  • 模型健康账本：每次任务按模型记成败，连挂 ≥2 次的渠道标红
  • 稳定性基线：可固定一条基线，之后每轮自动对比、退步点名

npm test 用模拟 LLM，不需要 API Key 就能全绿——前端部分还在真 Chromium 里跑。

4. 它不只是学习材料，也是一个能上手的办公 Agent

读代码之外，它开箱就能干活：

  • 一句话下任务，它自己跑完交付文件
  • 四种模式：Ask（只问答）/ Plan（只出计划）/ Goal（目标模式，自动拆验收清单）/ Craft（完整执行）
  • 加技能 = 写一个 Markdown 文件放进 skills/，改完下一条任务就生效，不用改代码不用重启
  • 12 位内置专家 + 4 个专家团，也可自定义（头像/职称/说明/绑技能）
  • 支持标准 MCP 连接器 + Agent Plugins 1.0.0 开放插件标准（粘 GitHub 地址就装）
  • IM 远程指挥：飞书 / QQ / 企微 / 微信 / 钉钉，手机下任务、干完推回来
  • 定时任务：cron 跑，错过了会补跑（最多补 24h、只补最近一次）

5. 部署运维：从 0 到跑起来（含踩坑）

5.1 环境准备

前置条件极少：

依赖 说明
Node.js 18+ node -v 确认
git 拉代码
一个大模型 API Key DeepSeek / Qwen / GLM / Kimi / OpenRouter 任选其一；不想花钱装 Ollama 跑本地，不需要 Key

5.2 安装启动

# 拉代码 + 装依赖
git clone https://github.com/CatCatUncle/openworkbuddy.git
cd openworkbuddy
npm install

# macOS/Linux 也有一键脚本
bash install.sh

# 启动，三种跑法挑一个
npm run app                          # 桌面版（Electron），自己用推荐
npm start                            # 纯服务端，浏览器打开 http://localhost:3800
npm run cli -- "帮我写一份本周周报"    # 命令行/脚本调用

5.3 两个高频踩坑点

坑 1：npm install 卡在 electron

国内需要先设 Electron 镜像再装：

export ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/
npm install

坑 2：端口被占

换端口启动即可：PORT=3801 npm start。

5.4 服务器部署（Docker）

git clone https://github.com/CatCatUncle/openworkbuddy.git && cd openworkbuddy
cp config.example.json config.json      # compose 按文件挂，必须先有
mkdir -p data workspace
docker compose up -d
docker compose logs -f openworkbuddy

默认只把端口绑在 127.0.0.1:3800，外面自己套 nginx/Caddy 反代 + HTTPS。

6. 安全：这个 Agent 手里有 shell，务必这样做

这是最重要的提醒，放前面。

因为 Agent 能干文件操作、能跑命令，把它挂公网 = 把这台机器的 shell 挂公网。 部署/公开前确认三件事：

  1. 起来后第一件事注册管理员账号——空库对外挂着，谁先访问谁就是管理员
  2. 用完后关掉"允许别人自己注册"
  3. 打开安全中心的命令审批，用低权限账号跑

安全中心是真闸门：命令审批、文件黑名单、网络白名单、审计日志（data/audit.json，环形 1000 条）。而且run_node 的代码也过闸——只守 run_shell 那扇门没用，一句 require("child_process").execSync(...) 就从旁边过去了。

另外，权限档位可以一键切：只看不动 → 每步都问 → 自动改文件（默认）→ 全自动。

7. 一些客观的边界（负责任的选型参考）

不是所有场景都适合它，说清楚免得误判：

适合：

  • 想从源码学 Agent Harness / 想研究 WorkBuddy 实现
  • 私有化部署、数据不出本机的个人 / 小团队
  • 想低成本跑 AI 办公自动化（用 DeepSeek / Ollama）
  • 讨厌黑箱框架、想改自己想改的东西的开发者

不适合：

  • 纯小白要"开箱即用啥都不配"——需自备 Node、Key 或 Ollama
  • 严格多租户硬隔离的企业场景——它偏"一台机器几个自己人"，agent 有 shell 挡不住成员互读，真要隔离得一人一个实例
  • 商业闭源使用——非商用免费，商用需单独授权（见 LICENSE）

8. 想参与贡献？从"写一个技能"入门

方向 难度
写一个技能（一个 Markdown 文件，不碰代码） ⭐
补模型服务商预设 / 改文档 ⭐
加一个内置专家 ⭐⭐
接一个新的 IM 渠道 ⭐⭐⭐
加一个内置工具（记得过安全闸） ⭐⭐⭐

代码约定也好懂：CommonJS、不加构建工具、注释写"为什么"、动落盘走 store.js（原子写 + .bak）、提交信息用中文。

提 issue 时请提供：用的模型服务商和模型名、复现步骤、报错原文。 贴日志前一定先清掉自己的 API Key 和令牌。

9. 总结

如果你在研究 Agent Harness、想找 WorkBuddy 源码级实现、或想私有化部署一个能真交付文件的 AI 办公 Agent——OpenWorkBuddy 都值得你 Clone 下来读一遍。

它给的三样东西，别处比较少同时具备：

  1. 一整套能读懂的手写 Agent Harness 源码（不是黑箱框架）；
  2. 一个能真交付文件的完整产品（不是 demo）；
  3. 一份开放标准、能平移到任何 Agent 项目的学习材料（MCP / Agent Plugins / 通用 Model 抽象）。

作者是多年大厂一线开发经验的开发者猫叔，这项目把生产级工程质量（断点续传、原子落盘、命令闸、稳定性评测）都做进了实现里——不是练手项目。

仓库：GitHub - CatCatUncle/openworkbuddy: OpenWorkBuddy：腾讯 WorkBuddy 开源复刻版 —— 零框架手写 Agent 循环 + 技能库 + 专家团 + Agent Plugins 1.0.0 + 多 IM 通道（飞书/QQ/微信）的本地 AI 办公工作台 · GitHub
个人与非商业用途免费；商业使用请先看 LICENSE 与 COMMERCIAL-LICENSE.md。

本文关键词：WorkBuddy 源码、OpenWorkBuddy、Agent Harness、AI Agent 私有化部署、Agent 框架源码解析、DeepSeek 本地 Agent、MCP 连接器开源、Ollama 本地模型 Agent。

# 开源
Logo
2048 AI社区

有“AI”的1024 = 2048，欢迎大家加入2048 AI社区

更多推荐

MoneyPrinterTurbo：让中小企业把短视频生产成本压到接近零 ｜SSP Github Daily

MoneyPrinterTurbo 是务实的“API 编排”项目——不自研模型、不赌未来技术，只用今天成熟的 API，把短视频生产成本压到接近零，让中小企业从“单条手工剪辑”转向“批量内容实验”。

avatar 2048 AI社区

LangChain+Gradio+千问大模型实现AI聊天助手

1. 非流式输出模式。

avatar 2048 AI社区
cover

Stripe花75亿美元买了个“中间商“，OpenRouter被支付巨头收编了

avatar 2048 AI社区