说实话，我刚把 WorkBuddy 装好的头两周，差点就把它卸载了。不是功能不行，而是它“独”得很——本地文件读不到，钉钉多维表只能看不能用，说好的定时通知一条都没发出来。后来我才反应过来，问题根本不在 WorkBuddy 本身，而是我从来没认真对待过“连接”这件事。作为《WorkBuddy 实战蓝皮书》系列的第三篇“连接篇”，这篇就把如何把 WorkBuddy 的连通性做扎实这件事讲透。前面两篇写的是工具认知和本地部署，这一篇专门解决让你“接得上、连得通、传得动”的问题。无论你是刚装完想知道怎么连第一个数据源，还是已经在生产环境里被 3002 错误搞到头大，这篇文章都能给出一条能落地的路径。
1. 先拆清楚：WorkBuddy 的“连接”到底在连接什么
1.1 我把 WorkBuddy 的连接对象分成四类
在开始配连接之前，建议先建立一张地图：什么算连接？
第一类叫数据底座。包括本地目录、共享文件夹、数据库、数据仓库。WorkBuddy 最常见的用法，是让 Agent 去读你磁盘上的 Markdown、PDF、Excel 或 CSV 文件，然后基于这些数据生成报告、写周报、做信息整理。没有这一层，Agent 就是个没有上下文的大脑，你问它什么它都只能给“通用答案”。
第二类叫办公系统。包括钉钉、企业微信、飞书这类协同办公平台的开放 API。它们的典型价值，是把组织内部流程里的数据接进来，比如钉钉多维表、审批流、考勤记录。很多人对 WorkBuddy 的核心诉求是“让它每天自动同步我业务表里的新记录”，这就得靠办公系统连接器，而且通常要单独处理授权和鉴权。
第三类叫知识库。包括 Obsidian、Notion、Confluence、语雀、各类 wiki 等。和直接拉本地文件不一样，知识库连接往往要求做更多处理——保留目录结构、维护双链、处理冲突。这一层连接好之后，Agent 回答问题时才有“记忆感”和“出处感”。
第四类叫消息与事件通道。包括群机器人、Webhook、邮件、IM 通知。数据能进能出还不够，你还得让系统在“该出现的时候”出现。定时推送、异常告警、跨系统事件触发，都要靠这类连接来完成。
我在项目里给这四类各建了一个配置目录，互不交叉。好处是排查问题时能精准定位——比如钉钉同步挂掉，我只需要检查办公系统连接器这一块，不需要把本地文件路径也翻一遍。
1.2 连接器（Connector）与普通插件的边界
社区里经常有人把连接器和插件混为一谈。我的理解是：连接器负责“搬东西”，插件负责“加工东西”。
连接器通常定义一组协议和配置——API 地址、认证方式、同步频率、字段映射——它把外部系统和 WorkBuddy 之间的数据管道打通。比如钉钉连接器知道怎么拿 AppKey 换 token、知道多维表分页参数怎么传、知道错误码 40010 代表什么。而插件是跑在工作台内部的逻辑单元，比如一个“发送 HTTP 请求”节点、一个“解析 JSON”节点，它完成的是具体的数据变换动作。
搞清楚这个边界有什么用？因为绝大多数连接失败，都是因为你拿插件干了连接器的活儿——比如在 HTTP 请求节点里手写了复杂的鉴权逻辑，token 过期之后又没做自动刷新，就很容易出问题。或者反过来，在连接器里塞了一堆本应该由工作流处理的业务逻辑，导致每次同步都特别慢。连接器只管管道，业务处理交给工作流，职责清晰，排查也快。
1.3 一次连接请求的完整生命周期
把这个流程拆开看，有助于你以后排查问题。
用户在工作台里点击“连接数据源”之后，WorkBuddy 会先读取对应连接器的配置，然后走认证流程——OAuth 2.0 或 API Key 二选一，成功后创建数据会话；接下来根据同步策略拉取数据，这里会做字段映射和类型转换；再下一步，数据进入工作台上下文之前，会经过一层范围过滤，也就是你设置的访问白名单；最后才把结果交给 Agent 使用。
这六个环节里，任何一个出错，最终表现都是“连接失败”或“数据读不到”。所以当界面弹出一句笼统的报错时，不要只盯着网络，先判断卡在了哪一环：
- 配置阶段出错，通常是连接器参数填错或认证失败；
- 拉取阶段出错，通常是接口权限不足、字段类型不兼容或者分页逻辑写错；
- 过滤阶段出错，通常是你授权的工作目录/数据范围没覆盖到目标位置。
2. 数据源接入实战：目录授权、数据库同步与知识库协作
2.1 访问文件夹范围设置：第一次配置最容易踩的坑
说一个我培训同事时的真实场景。他建了一个工作区，给 WorkBuddy 指定目录是D:/工作文档/项目A，但执行任务时 Agent 一直说找不到文件。我们打开日志，发现路径被保存成了D:/工作文档/项目A/，末尾多了一个斜杠。
这看起来是字符级差异，但 WorkBuddy 的路径校验非常严格。Windows 下驱动器的根路径不能带尾部斜杠，而子目录路径必须统一用反斜杠或正斜杠。路径规范化失败时，目录会直接被标记为不可访问，而不是“修一下继续用”。
我的建议是，填路径之前先做规范化：
- Windows 上优先用
D:\projects\demo这种纯英文绝对路径； - macOS/Linux 上用
/Users/name/projects/demo，不要写~/projects/demo，除非你确认 WorkBuddy 服务进程会自动展开波浪号； - 多个项目建议在工作区里分别配置子路径，而不是一个父目录管全部；
- 不要让 WorkBuddy 扫描整个
C:\Users\<用户名>或/home/<用户名>主目录。
关于授权的第二个坑，是权限范围给得太大。把整个用户主目录授权给 WorkBuddy 虽然省事，但会让本地知识库索引变得臃肿——它每 5 分钟扫描一次文件变更，目录树一大，索引构建和任务响应都会变慢。更重要的是，Agent 一旦被某个 Prompt 误导，就可能去读取不该读的隐私文件，后果很难收拾。
我自己目前的实践是，专门建一个agent-workdir文件夹，下面按项目分子目录，WorkBuddy 只有这一层的访问权。所有需要 Agent 处理的数据，都由定时任务或手动方式挪到这个目录里。这样权限边界非常清晰，日后审查日志也方便。
2.2 钉钉多维表定期同步的完整落地记录
问得最多的连接需求之一，就是钉钉多维表同步。场景通常是：团队每天把客户跟进记录写进钉钉多维表，我希望 WorkBuddy 每天自动拉取新增和变更的数据，然后基于它生成销售日报。
实现路径不复杂，但关键细节特别容易出问题。
第一步，在钉钉开放平台创建企业内部应用，拿到 AppKey 和 AppSecret。这里要留意：多维表读权限和通讯录读权限是分开申请的应用权限，别只勾了一个。我见过不少同事只申请了“文档读”却漏了“多维表读”，最后接口返回“无权限”。
第二步，在 WorkBuddy 连接器里选择“钉钉文档/多维表”类型，填入应用凭证，然后选择要同步的多维表。这里可能还会要求填namespace或baseId，直接从 URL 里复制即可，不需要手动输入。
第三步，设置同步策略。我建议第一次拉全量，之后按updated_at字段增量拉取。为什么要增量？因为多维表的 API 有访问频次限制，逐行转存很容易把配额打满。我在项目里用一个游标分页脚本，每次批量拉 50 条，记录游标位置；下一次同步从游标开始，配合时间戳过滤，效率立刻上来了。
字段映射是第二个坑。多维表里的“日期”字段在 API 返回的是一个毫秒级时间戳，如果不转成datetime，WorkBuddy 内部就无法按时间排序或做统计。“人员”字段返回的是用户 ID 数组，最好先映射成姓名，否则 Agent 对话时只能看到一串user_xxx。“附件”字段则需要保留下载链接，因为同步时 WorkBuddy 不会主动帮你把二进制文件下载到本地，除非你在连接器配置里开启“附件缓存”。
第三个坑是重复数据。把同步间隔设成 5 分钟一次，很快就发现本地库里全是重复记录。这不是 WorkBuddy 的 Bug，而是多维表对“变更”的定义和业务预期不一致。建议用双时间戳策略——gmt_create判断新增，gmt_modified判断更新，再配合去重键。多数情况下，这个组合就足够稳定了。
同步跑稳定之后，可以再往前一步：让 WorkBuddy 把拉取到的数据做清洗和打标签。比如把“状态=待回访”的记录单独抽出来生成 Task 清单，同步完成后再触发一次通知。数据进来了只是开始，数据能用起来才是目的。
2.3 Obsidian 连接：两种可行路线与选择逻辑
很多人把 WorkBuddy 当第二大脑的助手，那和 Obsidian 打通就是刚需。Obsidian 官方没有向第三方开放云同步 API，所以常见的打通方式有两种。
路线 A：直接读取本地 Markdown 文件。如果你的 Obsidian 库就在本机，而且你只在一台设备上使用 WorkBuddy，那么最稳妥的方式是授权 vault 路径，让 WorkBuddy 直接读取.md文件。好处是零中间层、无数据冗余，Agent 回答问题时读到的就是最新内容。缺点是如果你用了 Obsidian 的加密插件或大量二进制附件，WorkBuddy 只能处理明文文本部分，图片、音频这些需要额外处理。
路线 B：通过 Local REST API 插件暴露本地库。Obsidian 社区有一个 Local REST API 插件，可以启动一个本地 HTTP 服务，WorkBuddy 连接器通过调用它的接口来读写笔记。这个方案适合“多进程访问同一库”的场景，比如 WorkBuddy 运行时不想直接读写文件，避免和其他 Obsidian 插件产生锁冲突。缺点是需要在插件侧配置 API Key，并设置允许跨域访问。如果你要把它部署到局域网内其他设备上访问，还要把监听地址从127.0.0.1改成0.0.0.0，并处理好防火墙。
实际使用中我更推荐路线 A，但有一个前提：把笔记库拆开，只把真正需要给 WorkBuddy 使用的笔记目录授权出去。比如我单独建了一个05-agent目录，专门给 Agent 读取，其他私人日记目录完全不授权。这样既打通了知识库，又保住了隐私边界。
另外，无论用哪条路线，都建议给 WorkBuddy 建一个独立的“知识索引文件”，里面写清楚哪个目录下有什么主题的资料、适合用来回答什么问题。这个文件本质上是在给 Agent 指路，能让跨目录检索准确率高很多。
3. 消息与事件的取舍：从定时任务到 Webhook 触发
3.1 定时发送微信消息的三种实现路径
在社区里热度一直很高的需求，是把 WorkBuddy 生成的日报定时推送到微信。这里要先澄清一个事实：WorkBuddy 官方没有内置个人微信连接器，个人微信的接口限制很多，也没有稳定的官方开放 API。我试过几条路线，把结论分享出来。
路径一：企业微信群机器人。这是最稳妥也最简单的方案。在企业微信里建一个群，添加群机器人，拿到 Webhook 地址。WorkBuddy 这边在自定义指令里添加一个“HTTP 请求”节点，方法选 POST，把 JSON 内容作为消息体发过去，然后设置 cron 触达时间。
路径二：Server 酱或类似的推送服务。如果你没有企业微信，可以用这类聚合推送服务，把 WorkBuddy 的 URL 回调接到它的接口上。原理是 WorkBuddy 通过 HTTP 调用推送服务接口，服务端帮你把消息推到微信。好处是简单、不依赖企业号，缺点是消息会经过第三方中转，敏感数据不要走这条路。
路径三：钉钉或飞书机器人。原理跟企业微信一样。如果你的团队已经在钉钉上，就优先用钉钉群机器人，因为它可以复用你在钉钉开放平台创建的应用凭证，不需要再维护第二套密钥体系。
给一个实际的 cron 例子：团队每天早上 9 点要看到当日待办和风险项。我在 WorkBuddy 指令里写了类似这样的逻辑：
cron: "0 9 * * *" task: | 读取本地任务清单，统计今日待办数量、超期任务、风险等级， 按团队分组生成简短日报； 调用 webhook 工具推送到企业微信群机器人。跑了一周之后，最大的收获是准时率。之前人工整理日报至少半小时，现在每天 9 点零几分消息就弹出来了。不过要注意，群机器人 Webhook 对消息频率是有限制的，单条消息体也不要超过 2048 字节，长报告要拆分或者转成 Markdown 文件链接，否则消息会发送失败。
3.2 Webhook 事件驱动：把轮询改成被通知
和定时任务不同，Webhook 是外部系统主动通知 WorkBuddy。典型场景：订单系统写入一条新订单，随后通过 Webhook 调用 WorkBuddy 的本地服务，触发一个“客户画像生成”工作流。这种模式下，WorkBuddy 不需要一直轮询数据库，只在事件发生时醒来，效率和实时性都更好。
配置 Webhook 时要做好三件事：
- 设置允许来源 IP 白名单。如果不是公网调用，可以只允许内网网段；
- 校验签名。把外部系统生成的签名和 WorkBuddy 服务端计算的摘要做比对，防止伪造事件；
- 配置失败重试机制。外部系统发送失败时，WorkBuddy 至少要保留最近 N 次事件记录，避免事件丢失。
签名校验的具体做法，一般是在 HTTP Header 里带一个X-Signature字段，内容是用密钥对请求体做 HMAC-SHA256 后得到的哈希值。WorkBuddy 收到请求后，用同一把密钥重新计算，比对一致才处理。这个步骤看起来有些繁琐，但能挡住绝大多数的伪造请求。
我见过不少人把 Webhook 和定时任务混着用，两者不冲突，但要明确边界：定时任务是“我按计划做事”，Webhook 是“我响应事件做事”。频繁任务用定时，高实时任务用 Webhook。比如“每天早上整理报表”是定时任务，“有新客户注册后立刻生成跟进话术”就是 Webhook 任务。
3.3 同步频率与触发粒度的实用基线
连接配完之后，最需要盯的就是频率。频率太高，API 限额很容易被打满；频率太低，数据滞后，Agent 输出的结果就可能过时。这里给一张我自己跑了一段时间之后调出来的对照表：
| 场景 | 推荐频率 | 原因 |
|---|---|---|
| 钉钉多维表增量同步 | 15 分钟 ~ 1 小时 | 在 API 配额和数据新鲜度之间取平衡 |
| 本地文件扫描 | 5 分钟一次，或监听文件变化 | 本地读取开销小，可高频 |
| 群机器人推送 | 按业务触发，非周期性 | 高频推送会打扰团队 |
| 数据库变更捕获 | 用 Binlog/WAL 监听 | 实时性最高，但运维成本高 |
| Webhook 接收 | 事件触发 | 外部系统实时推送，WorkBuddy 被动响应 |
这不是严格的规范，只是我的基线值。如果你的业务对实时性要求高，可以调得更激进；如果你经常被限流，先看是不是单次拉取量太大，而不是一味降低频率。另外，每次调整频率之后，记得观察至少 24 小时的同步日志，确认没有因为 API 返回429 Too Many Requests而导致任务失败。
4. 网络与部署故障排查：3002 背后的完整链路
4.1 3002 报错的完整复盘
“网络连接失败(3002)”是 WorkBuddy 用户群里出现频率最高的问题之一。我一开始以为它就是服务端故障，后来自己在一台 Ubuntu 服务器上部署之后，连续遇到两次 3002，才算把这个问题彻底研究明白。
第一次的根因是 DNS 解析异常。服务器在启动后没有及时获取正确的 DNS 配置，导致 WorkBuddy 去请求 API 域名时长时间解析不到 IP，最终超时报 3002。第二次是防火墙策略：服务器只放行了 22 和 443 端口，WorkBuddy 的工作端口没开放，服务能启动，但外部回调根本进不来。
这件事给我的教训是：3002 只是一个“客户端视角”的错误码，真正的原因可能横跨 DNS、TLS、端口、防火墙、服务端限流等多个层面。不把链路拆开，你只能靠猜。
4.2 从现象到根因的四步排查法
我整理了一个可执行的排查顺序，你在本地环境或服务器上可以直接照着走。
第一步，检查本地网络基础连通性。在 WorkBuddy 所在机器上执行：
curl -Iv --connect-timeout 10 https://api.workbuddy.example.com注意把域名换成你自己的实际 API 地址。命令能成功输出SSL connection using TLS就说明网络链路基本通。如果超时，问题大概率出在出口网络或 DNS 解析。
第二步，检查防火墙和端口监听。用nc测试端口是否开放：
nc -zv 127.0.0.1 8080如果端口没有监听，去确认 WorkBuddy 服务进程是否真的启动成功，再看看监听地址是127.0.0.1还是0.0.0.0。有些部署模式下，服务只监听回环地址，外部回调自然连不上。
第三步，看日志。WorkBuddy 日志目录下一般会记录每次请求的目标地址、状态码和耗时。实时跟踪日志：
tail -f ~/.workbuddy/logs/workbuddy.log如果看到大量ETIMEDOUT，就是出口到目标服务器的网络不通；如果看到HTTP 429，就是请求频率超过服务端限制；如果看到证书校验失败，那就要更新证书链或检查系统时间是否准确。
第四步，做最小化测试。临时关闭安全软件、把防火墙策略先放行，再启动 WorkBuddy。如果问题消失，说明是安全软件拦截；如果问题依旧，再逐项排查配置。
每次排查我都建议先记录时间线和报错代码，再动手改配置。否则你改了十处，也不知道是哪一处生效的。这个习惯能帮你省下大量重复试错的时间。
4.3 启动非常慢与目录名出现点号
搜索热词里有一个非常具体的现象，正好和连接篇相关：启动非常慢，以及目录前面出现一个.。我第一次遇到时也很困惑，后来才发现问题出在安装路径和工作目录命名上。
情况是这样的：我把 WorkBuddy 装在了包含空格和中文的路径下，比如C:\Users\张三\My WorkBuddy\。某些版本在加载 Node 模块时，路径中的空格会导致模块编译缓存失效，每次启动都要重新解析，启动时间从 3 秒变成 3 分钟。更诡异的是，工作区目录列表前面会出现一个.，很多脚本把它当成隐藏目录跳过，导致目录扫描结果缺失。
解决方法也很直接：安装路径和工作目录都用纯英文、无空格的绝对路径，比如D:\workbuddy\。目录名不要以.开头；如果已经用错了名字，重新初始化工作区，再把旧目录里的配置迁移过来。这个方法对我和身边同事遇到的两次启动问题都有效。
另外，如果你看到 WorkBuddy 在工作区目录前生成了一个.workbuddy之类的隐藏目录，这是正常现象，里面存的是索引和缓存，不要手动删。真正需要警惕的是你自己创建的目录名以.开头，那才会导致路径解析异常。
4.4 连接状态自检清单
| 症状 | 可能原因 | 处理动作 |
|---|---|---|
| 3002 网络连接失败 | DNS 解析异常、防火墙拦截、TLS 握手失败 | 按四步排查法逐项测试 |
| 连接器显示成功但无数据 | 权限范围未覆盖目标目录 | 检查工作区路径与授权范围 |
| 同步任务堆积 | API 限流或单次拉取量过大 | 调大同步间隔，改用分页拉取 |
| 启动明显变慢 | 安装路径含空格或中文 | 换纯英文路径，重建工作区 |
| 目录列表出现前导点号 | 工作区目录命名以点开头 | 重命名为普通目录并迁移配置 |
| Webhook 收不到事件 | IP 白名单或签名校验失败 | 检查来源 IP、密钥和签名逻辑 |
这张表不一定覆盖所有场景，但可以作为你排查时的第一级参考。
5. 连接的安全边界与季度巡检习惯
5.1 为什么授权范围要尽量小
连接的本质是权限交换。你把一个系统接到 WorkBuddy 上，就等于给 WorkBuddy 发了一张“可访问该系统的通行证”。通行证的范围越大，泄漏时的爆炸半径也越大。所以我的原则始终是：最小权限，最小范围。
落地到具体操作上：
- 目录授权只给需要处理的数据目录，绝不授权整个磁盘；
- 数据库账号用只读用户，不要给 DBA 权限；
- 办公系统应用只申请必要的 API 权限，比如多维表只申请“读取”权限；
- Webhook 除了校验来源 IP，还必须校验签名。
你可能觉得这样配置起来麻烦，但一旦出过事故，你就知道这些功夫非常值得。我有个朋友因为 WorkBuddy 连接器配了数据库管理员权限，一次误操作把线上测试表清空了大半，恢复数据花了好几个小时。权限最小化不是阻碍效率，恰恰是在保护你不被一次失误打回原点。
5.2 凭证存放与定期轮换
连接器配置里通常要填 API Key、AppSecret 这类凭证。最稳妥的做法是把凭证放到 WorkBuddy 的密钥管理模块或环境变量中，而不是直接写进指令或同步脚本里。如果你用 Git 管理配置文件，记得把包含凭证的文件加入.gitignore，否则下次git push就相当于公开了密钥。
凭证还要定期轮换。我目前的做法是每 90 天轮换一次外部应用的 AppSecret，日历上设置提醒；轮换后立刻验证连接器是否仍然正常工作。你可以在离线状态下修改凭证，但不能让 WorkBuddy 的同步任务长时间处于认证失败状态，否则缓存的数据会越积越多，恢复时压力也更大。
5.3 连接器季度巡检清单
连接不是配一次就能一劳永逸。外部 API 版本升级、字段废弃、权限策略调整，都会让连接器慢慢“生锈”。我在团队里推了一个季度巡检机制，内容不复杂，但很管用：
- 查看近期同步日志里有没有 4xx/5xx 错误；
- 核对连接器的 API 版本是否仍在官方支持范围；
- 检查授权范围是否仍是当前项目所需的最小集合；
- 测试一次冷启动，确保定时任务能正常恢复；
- 轮换高风险凭证。
每次巡检大概花 20 分钟。20 分钟换来的，是避免“某天凌晨同步失败但没人发现”的尴尬。
最后说一点个人体会。WorkBuddy 的“连接篇”写到这里，我最大的感受是：连接本质上是一种工程习惯，而不是一次性配置工作。你越早把目录权限、API 凭证、同步频率、排错链路这些细节做成固定套路，WorkBuddy 就越像一个真正的工作台，而不是一个偶尔给你惊喜的玩具。我整理这些内容的时候，相当于重新走了一遍自己踩过的坑，希望你在配置连接时能少绕点路。如果你之后遇到更奇怪的连接问题，欢迎带着日志和报错码来交流，我有空一定会回复。
