先说个现象。很多人装完 WorkBuddy 之后的第一周基本就是问它几个问题、让它帮忙写个周报然后就没有然后了。不是它不行是你根本还没把它接到你的工作里。我常打一个比方刚装好的 WorkBuddy 就像一台没插网线、没装驱动的电脑摆在桌上挺好看但干不了活。真正让这类效率智能体从玩具变成工具的分界线就是连接——连上模型、连上文件、连上你的历史记忆、连上钉钉、连上知识库、连上那些定时脚本。这一篇是《WorkBuddy 实战蓝皮书》的第三篇前两篇分别讲的是安装环境准备和基础上手操作这篇专门处理连接。顺便回应两个网上经常看到的问题一是 WorkBuddy 和 CodeBuddy 到底啥区别二是有个热梗问WorkBuddy 就是小龙虾吗——那纯属圈子里开玩笑的称呼不用太当真真正值钱的是它背后那套连接架构。下面我把这几个月实际部署、排障、搭自动化流程的经验全部拆开讲。1. 连接到底连的是什么拆开 WorkBuddy 的四种连接能力1.1 为什么很多人用不起来差的就是连接密度我见过太多人把 WorkBuddy 当成一个更聪明的聊天框来用。问它帮我写个会议纪要模板它写得确实不错然后呢没了。下周一开会你还是手动开录音、手动整理、手动发到群里。这就是典型的能对话但没连接。WorkBuddy 的定位从来不是聊天机器人而是一个工作台。工作台意味着它要跟你的真实工作环境发生交互读你指定的文件夹、查你团队的知识库、调你多维表里的数据、到点给你推送消息。每接通一条线它的实用价值就翻一倍。我把这种能力拆成四层后面所有操作都是围绕这四层展开的。1.2 第一层连接模型通道WorkBuddy 本身不生产智能它需要背后接一个大模型的 API 或本地模型服务。这是最底层、也是最先要打通的一条连接。这条线断了上面所有功能都是空中楼阁。很多网络连接失败、启动卡住的问题根源都在这层。1.3 第二层连接上下文所谓上下文连接就是让 AI 在动手之前能拿到它需要的背景资料。包括历史对话记录、本地记忆、知识库文档、你授权的文件夹内容。没有这层连接它只能靠模型自身的通用知识回答你那跟你用网页版有什么区别有了这层连接它才知道你上周讨论到什么程度、你团队的项目代号是什么、你惯用的周报格式长什么样。1.4 第三层连接外部系统工具这是连接篇里最重头的部分。包括钉钉多维表定期同步、定时发送微信消息、调用内部 wiki 接口、跑定时脚本、对接网页版的 Webhook 等等。这层连接解决的是AI 说了话之后谁来执行的问题。我后面会专门讲这几个场景的落地配置。1.5 第四层连接开发者生态WorkBuddy 有开发者平台也提供网页版和本地版。这一层面向的是有开发能力的人通过 API 把 WorkBuddy 嵌入你自己的系统或者通过 Webhook 让别人调用你封装好的技能。到这一步它就不再只是一个客户端工具而是你自动化体系里的一个大脑节点。1.6 顺带说清 WorkBuddy 和 CodeBuddy 的分工这个问题在网上被反复问。从我实际使用的体感来说CodeBuddy 主攻代码场景更像一个坐在你旁边的结对编程助手你给它看代码、让它补全、让它解释报错它的主战场是 IDE 和代码仓库。WorkBuddy 主攻工作流场景它关心的不是某一段代码而是这个任务由哪些步骤组成、每一步需要调什么资源、最后结果怎么推给你。简单说一个面向码代码的过程一个面向跑通业务的过程。两者有重叠但发力点不同。2. 跑通环境连接从本地部署到模型通道配置2.1 网页版、Linux 版、本地部署怎么选很多人的第一个问题是我到底该用网页版还是老老实实在自己机器上装一个我的建议很直接想拿它当玩具用网页版想拿它当生产力工具必须本地部署。网页版的优势是零门槛浏览器打开就能用官方帮你维护模型通道和存储适合体验功能。但它的局限性也很明显定时任务、文件夹访问这类连接能力会受到托管环境的限制比如它没法直接读你公司内网的多维表也没法在你没打开浏览器的时候帮你执行定时任务。Linux 版和本地部署适合真正的重度用户。我自己就在 Ubuntu 服务器上部署了一套用容器方式跑好处有三个第一数据不出内网公司敏感资料不会经过第三方托管链路第二可以直连内网里的各个系统比如企业微信机器人、内部 wiki、数据库第三可以设置 crontab 级别的调度真正做到7×24 小时待命。注意网上有人问WorkBuddy 启动非常慢怎么办大部分情况是因为本地部署时首次启动要校验模型文件、初始化技能索引。如果你机器性能一般第一次启动等三五分钟是正常的第二次启动会快很多。2.2 模型通道配置的实操细节无论你选哪种部署方式模型通道配置都是避不开的一步。我以本地部署为例配置一般集中在config.toml或环境变量里。核心就三件事模型服务地址、API Key、模型名称。[model] provider openai-compatible # 也可能填 vllm / ollama / 官方通道 base_url http://127.0.0.1:8000/v1 api_key sk-你的密钥 model_name qwen2.5-32b-instruct temperature 0.3这段配置里最容易出问题的三个点我逐个说base_url 填错。很多人会漏掉后面的/v1后缀导致握手失败。大多数兼容 OpenAI 协议的服务都要求 URL 最后带/v1。model_name 和实际服务不匹配。你本地部署的模型可能叫qwen2.5-32b-instruct但服务端注册名可能带了时间戳或版本号。先用curl http://127.0.0.1:8000/v1/models查一下真实返回的模型 ID再填到配置里。api_key 权限不足。有些网关服务支持多 Key 多权限如果你的 Key 只开了只读权限模型调用会被拒。确保 Key 至少具备model:invoke权限。2.3 网络连接失败的完整排查链路以 3002 错误为例网上搜 WorkBuddy 时workbuddy 网络连接失败 3002是高频词。我自己的服务器也出过这个错误码这里把完整排查链路写出来下次你遇到可以直接照做。3002 这个错误码按官方文档和我实际抓包的经验属于网络通道建立失败也就是客户端和服务端之间的 TCP/TLS 链路没有正常建立。常见原因按优先级排序如下DNS 解析失败。别笑这是最高频的。先执行nslookup your.workbuddy.endpoint或dig看能不能解析出 IP。如果内网 DNS 没有放行这个域名就会报 3002。端口不通。默认 HTTPS 走 443但如果你配了自建网关用了非标端口要检查防火墙。用telnet your-host 443或者nc -vz your-host 443验证。SSL/TLS 证书问题。自建服务经常用自签证书WorkBuddy 客户端默认会校验证书链。如果是内网测试环境可以在客户端配置里把verify_ssl临时设为false先跑通但生产环境不建议这么干。超时设置太短。如果你的模型服务在远端推理响应时间本身就长客户端默认连接超时可能不够。把超时从默认 30 秒调到 120 秒再试。我实际遇到 3002 那次最后定位到是公司内网网关策略阻止了客户端访问外部的模型 API 地址。因为客户端配置里写了外网模型服务地址而服务器所在网段只允许白名单域名出网。解决办法是把模型服务地址改成内网部署的模型网关。整个排查过程大约半小时但如果没有这套链路很容易在配置层面反复折腾。提示遇到网络类报错先别急着改配置。按域名解析 → 端口连通 → 证书校验 → 超时设置 → 访问策略的顺序逐层排查比瞎猜高效得多。2.4 启动非常慢的两个真正原因很多人启动 WorkBuddy 时卡在启动界面然后就去网上搜workbuddy 启动非常慢。我拆过启动日志慢通常出在两个环节第一是模型元数据加载。如果配置里连的是远端模型网关启动时客户端会去拉取模型列表、校验模型可用性。如果网关响应慢或网络有延迟启动就会卡。解决办法是在配置里手动指定model_name跳过模型列表拉取。第二是技能和插件初始化。WorkBuddy 启动时会扫描技能目录为每个 Skill 建立索引。如果你塞了几十个第三方技能每个技能都带描述文件和脚本索引构建时间会显著拉长。优化方式是精简技能数量把不常用的技能移到备份目录启动时就不会被扫描。3. 连接私有数据记忆迁移、文件夹权限与知识库接入3.1 历史对话记录和本地记忆迁移用了一段时间之后WorkBuddy 会积累一批很有价值的资产历史对话记录和本地记忆。这些东西相当于 AI 的工作经验换机器如果不迁移你就等于把老员工开除了。本地部署的话对话记录一般以 SQLite 或 JSONL 的形式存在数据目录里。迁移三步走找到数据目录整体打包备份。以我 Ubuntu 上的安装路径为例一般在~/.workbuddy/或你自定义的WORKBUDDY_DATA环境变量指向的目录。在新机器上安装相同版本先把数据目录解压过去再启动服务。注意版本差异尽量大版本一致避免数据库结构不兼容。启动后进入设置页检查记忆和历史会话是否还在。如果发现技能引用失效多半是因为记忆里记录了旧机器的绝对路径需要重新授权。有个细节迁移后一定要重新检查文件夹授权范围。记忆里那些技能引用的路径在新机器上可能不存在或者权限配置被重置了。我迁移过一次workbuddy 能想起来我之前的对话但每次执行读取文件夹操作都说无权限排查了半天才发现是新机器的工作目录没加进授权列表。3.2 访问文件夹范围设置给 AI 划定物理边界WorkBuddy 访问你本机文件不是无限制的它需要你显式授权哪些目录可以被读取。这既是安全设计也是效率设计。设置路径通常是设置 → 权限 → 文件夹访问范围 → 添加允许访问的目录。你要遵循的是最小权限原则它干活需要读哪些目录就给哪些目录。比如它要帮你整理周报那就只授权~/Documents/reports和~/Projects/team-share不要图省事直接把整个 home 目录授权了。为什么这么强调两个原因。一是安全WorkBuddy 的技能可以调用脚本执行命令如果一个第三方技能被诱导去读你的私钥目录危害很大。二是效率授权目录太广会导致技能搜索文件时被大量无关文件淹没上下文里塞满垃圾回答质量反而下降。我在网上看到有人问workbuddy 如何设置访问文件夹范围实际上官方文档里有明确说明设置完会生成一个权限清单。我建议你定期检查这份清单把不再需要的目录移除。3.3 把 WeKnora 这类开源知识检索组件接进来团队内部知识库的接入是 WorkBuddy 从个人助手变成团队助手的关键一步。我在生产环境用的是开源知识库问答组件WeKnora来做多源知识检索然后把它接进 WorkBuddy。简单说WeKnora 这类组件做的事情是把你的 wiki 页面、内部网页、离线文档抓取下来做切片和向量化然后提供一个检索接口。WorkBuddy 本身不需要知道文档存在哪它只需要在回答问题时先去 WeKnora 检索相关内容把命中片段作为上下文再组织答案。接入思路不复杂核心是把 WeKnora 封装成 WorkBuddy 可调用的一个工具。它的检索 API 一般是标准 HTTP 接口示例请求如下curl -X POST http://your-weknora-host/api/search \ -H Content-Type: application/json \ -d { query: 项目周报模板口径, top_k: 5 }返回结果通常是文档片段和相似度分数。你可以写一个几十行的 Python 脚本把这个检索能力封装成 WorkBuddy 的 Skill后面第五章会讲具体怎么封装让模型在回答前先调一次检索再基于检索结果组织答案。这样做的好处是立竿见影的原来你问它我们团队的周报模板是什么它只能瞎编现在它能从你们的 wiki 里把真实模板捞出来给你。生成式 AI 最怕一本正经地胡说八道接上知识库检索就是最好的纠偏手段。3.4 LLM wiki 的落地用法workbuddy llm wiki也是热搜词之一。所谓 LLM wiki我理解就是给大模型看的知识库跟给人看的 wiki 不同它的写作方式要更适合被检索和切片。实践中我的建议是把团队规范、操作手册、常用口径统一沉淀成 wiki 页面每个页面标题要清晰正文第一段就给出结论然后才是细节。比如周报模板.md的开头直接写标准周报包含上周总结、本周计划、风险项三个板块而不是先铺垫一堆背景。接入节奏分三步先把最高频的 20~30 个页面做结构化整理覆盖常用模板、命令手册、业务流程。让 WeKnora或你选的检索组件抓取并建索引。在 WorkBuddy 里建一个知识库检索 回答的 Skill测试检索命中率。注意知识库不是一次建完就完事的。我每两周会让爬虫重新抓一次 wiki不然新更新内容永远检索不到。很多团队接入知识库后觉得不好用八成是索引停在两周前。4. 连接外部系统钉钉多维表、定时微信消息与开发者 API4.1 钉钉多维表的定期同步用连接器替代手工搬运我在团队里用得最频繁的连接场景就是让 WorkBuddy 每天自动同步钉钉多维表里的项目数据。以前的做法是每天上班第一件事打开多维表导出 Excel再把关键数字粘到汇报文档里。现在这个动作完全交给了 WorkBuddy。实现思路是通过 WorkBuddy 的连接器配置钉钉多维表的访问凭证然后用定时任务触发同步。连接器配置核心参数包括app_key和app_secret钉钉开放平台的凭证base_id多维表工作台 IDtable_id具体数据表 IDsync_mode全量同步 or 增量同步定时同步的配置我用的是标准的 cron 表达式。比如每个工作日上午 9 点同步一次0 9 * * 1-5有一点必须强调定时任务执行的前提是你的 WorkBuddy 服务端一直开着。很多人在网页版上配置了定时任务然后关掉浏览器以为任务会照常执行——不会的。所以生产环境的定时任务一定要挂在本地部署的服务上。实测下来增量同步比全量同步稳定得多。全量同步每次要拉整张表数据量大时容易超时而且会占用大量 token。增量同步依赖多维表的modified_at字段只拉取最近变更的数据既快又省。4.2 定时发送微信消息的实现方式与注意点workbuddy 定时发送微信消息这个需求非常普遍但我必须先泼一盆冷水不要直接做个人微信的自动定时发送。个人微信的自动化存在风控风险轻则消息发不出去重则账号被限制把关键业务流程挂在个人微信自动化上极不明智。正确姿势是走企业微信机器人 Webhook。在群里添加一个自定义机器人拿到 Webhook 地址之后任何程序都可以往这个地址 POST 一段 JSON实现消息推送。示例脚本如下import requests import json webhook_url https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key你的机器人key def push(title, content): data { msgtype: markdown, markdown: { content: f## {title}\n\n{content} } } resp requests.post(webhook_url, datajson.dumps(data), headers{Content-Type: application/json}) return resp.json() if __name__ __main__: push(每日早报, 1. 本周项目A进度正常\n2. 项目B有风险)然后把这段脚本交给 WorkBuddy 的定时任务调度。每天上午 8 点 50 分它会先去查多维表数据、去知识库检索口径再把这几个数据源的内容拼成一条早报推送到群里。整个过程不需要任何人手动参与。注意企业微信机器人 Webhook 有频率限制官方建议每 20 秒最多 20 条消息。正常办公场景根本用不满但如果你的脚本在循环里疯狂推送会被限流甚至封掉 Webhook。4.3 开发者平台与网页版的 API 化把 WorkBuddy 当服务用WorkBuddy 除了交互界面还提供了开发者平台。这意味着你可以在自己的代码里调用 WorkBuddy 的能力而不只是打开界面跟它聊。这层连接适合有一定开发能力的用户我列几个典型用法内部系统触发某个事件时自动让 WorkBuddy 生成一份报告。你的网页后端接入 WorkBuddy 的会话 API把 AI 能力集成进自己的产品。通过 Webhook 接收 WorkBuddy 技能执行完毕的回调做后续联动。最简单的 API 调用方式是先获取 access_token然后用标准 HTTP 请求创建会话、发送消息。示例import requests token_url https://your-workbuddy-host/api/v1/auth/token session_url https://your-workbuddy-host/api/v1/sessions # 获取 token token_resp requests.post(token_url, json{api_key: your-api-key}) token token_resp.json()[access_token] # 创建会话并发送消息 headers {Authorization: fBearer {token}} session_resp requests.post(session_url, headersheaders, json{name: 自动报告生成}) session_id session_resp.json()[id] msg_resp requests.post(f{session_url}/{session_id}/messages, headersheaders, json{ content: 请根据最近一周的多维表数据生成项目周报 }) print(msg_resp.json())有开发能力的读者应该已经感觉到了这一步把 WorkBuddy 从一个工具变成了平台能力。我的实际感受是当你能在自己的代码里调用它的时候自动化方案的设计空间一下子大了很多。4.4 一个综合工作流示例从数据到消息的全链路前面几节讲的都是单个连接这一节我把它们串起来看一个真实在跑的全链路工作流。场景每天早上给团队推送一份项目健康早报。整个流程分三步第一步触发器。用 cron 在每天早上 08:50 触发daily_health_report技能。第二步处理逻辑。技能执行三件事调用钉钉多维表连接器拉取最近一天更新的项目进度数据调用 WeKnora 知识库检索获取团队定义的风险判定口径比如延期超过 3 天视为高风险把数据交给大模型按口径生成结构化早报。第三步输出。调用企业微信机器人 Webhook 推送早报同时写入一份 JSON 日志方便以后追溯。这个工作流的好处是每一个环节单独拎出来都不难但连起来之后就形成了自动化闭环。AI 的决策判断什么是风险、怎么描述进度、外部系统的数据多维表、知识库的口径判断判定标准、消息触达企业微信四条线通过 WorkBuddy 串在一起。这比我之前用的纯脚本方案灵活得多因为业务口径变化时我只需要改 wiki 里的口径文档不需要改代码逻辑。5. 把连接沉淀成 Skill自定义指令推荐与封装思路5.1 Skill 的本质不是提示词是可复用的小型自动化单元很多人以为 WorkBuddy 的 Skill 就是一段精心设计的提示词这是最大的误解。真正好用的 Skill 是提示词 脚本 参数约定的组合体它把让 AI 干活这件事标准化成可复用的自动化单元。一个标准 Skill 的目录结构大致是这样daily_report/ ├── SKILL.md ├── scripts/ │ ├── fetch_data.py │ └── push_msg.py └── assets/ └── template.mdSKILL.md描述这个技能是做什么的、输入参数有哪些、执行流程是什么。scripts/放实际的可执行脚本比如拉数据的、推消息的。assets/放模板和静态资源。为什么推荐把脚本独立出来而不是塞在提示词里因为脚本可以做校验、重试和幂等处理。比如拉取多维表数据时网络抖动导致拉取失败脚本里可以自动重试三次推送消息之前脚本可以先校验消息长度、检查必填字段。这些能力是纯提示词做不到的。5.2 几个实测好用的 Skill 方向我根据自己的使用场景整理了下面这几个值得优先做的 Skill供你参考Skill 名称输入输出关键参数周报生成器时间段、项目名结构化周报文本数据来源、模板路径会议纪要整理音频转写文本决议 待办清单输出模板、待办提取规则多维表周汇总表 ID、统计维度汇总报告维度字段、对比周期知识库问答用户问题带引用的回答检索组件地址、top_k以会议纪要整理为例以前是开完会手动把录音丢给工具转文字再手动总结再手动提炼待办。做成 Skill 之后只需把转写文本丢给它输出就是格式统一的会议决议 待办 负责人。这不是能力上的飞跃但节省的重复劳动非常可观。5.3 手写一个 Skill 的完整示例这里我演示如何把前面钉钉多维表同步 企业微信推送封装成一个 Skill。新建daily_report目录先写 SKILL.md# Daily Report Skill ## 用途 每天定时生成项目进度早报并推送到企业微信群。 ## 输入参数 - project_ids: 项目 ID 列表 - push_url: 企业微信机器人 Webhook 地址 ## 执行流程 1. 调用 scripts/fetch_data.py 拉取多维表数据 2. 调用 scripts/push_msg.py 把报告推送到企业微信再写scripts/push_msg.py伪代码如下import sys import json import requests def build_markdown(data): lines [## 今日项目早报, ] for project in data: lines.append(f- **{project[name]}**: {project[status]}) return \n.join(lines) def push(webhook, content): payload {msgtype: markdown, markdown: {content: content}} resp requests.post(webhook, jsonpayload, timeout10) resp.raise_for_status() if __name__ __main__: input_data json.loads(sys.stdin.read()) markdown build_markdown(input_data[projects]) push(input_data[push_url], markdown)关键点是Skill 的输入输出要尽量结构化。SKILL.md 里明确输入参数脚本处理具体格式转换这样同一个 Skill 可以复用到不同群、不同项目的场景。5.4 编写自定义指令时最容易踩的三个坑第一指令太宽泛。如果你写的是生成项目周报五个字AI 就不知道用哪个模板、参考哪些数据、推给谁。一定要把数据来源、模板路径、输出目的地写清楚。第二没给失败出口。Skill 执行过程中一定会遇到异常比如多维表接口超时、webhook 被限流。好的 Skill 必须定义失败时怎么办要么重试、要么降级为邮件通知、要么写到错误日志。没有失败处理的 Skill 在生产环境就是定时炸弹。第三忘了权限配置。前文反复强调过Skill 能访问哪些目录、能执行哪些系统命令都受权限配置约束。如果你写了一个 Skill但它的脚本需要读取一个未授权目录执行就会失败。所以在写好 Skill 后第一件事就是确认它的目录访问范围。6. 我实际踩过的连接坑一份排障笔记6.1 网络类问题的表现与处理除了前文说的 3002 网络通道建立失败还有几个高频错误401 UnauthorizedAPI Key 错误或已过期。先检查环境变量是否生效再检查 Key 是否还有额度。403 ForbiddenKey 有权限但操作被禁止常见于调用了未授权的 API 接口。去开发者平台确认这个 Key 绑定的权限范围。模型名不存在服务端返回 404 或者模型列表里找不到你配置的名字。按我前面说的先用 curl 拉一遍模型列表核对。超时模型推理时间超过客户端超时阈值。优先调大超时时间同时检查模型服务本身负载是否过高。6.2 文件夹授权过小导致的技能失效有一次我配置了一个知识库同步 Skill运行时报找不到文件。我看路径也没问题权限清单里也加了目录。后来才发现我授权的是~/wiki目录但 Skill 的脚本以 systemd 服务身份运行时HOME环境变量指向的是/root导致脚本实际解析出的路径是/root/wiki而不是我以为的/home/user/wiki。这个坑非常隐蔽。解决办法有两个一是全部使用绝对路径二是在脚本里显式设置HOME环境变量而不是依赖系统默认值。6.3 钉钉多维表同步时的字段类型问题钉钉多维表的字段类型改动会静默影响同步结果。比如某个字段原来存的是数字后来有人把字段类型改成文本同步脚本如果直接做数值计算就会报错而且这个错误不是每次都出现只在数据变更时触发。我现在的做法是在同步脚本里加一层字段类型校验发现类型不匹配就先记录告警而不是直接让任务失败。这样至少能保证群里准时收到消息只是内容里会带上数据源字段类型异常的提示。6.4 记忆迁移后的路径引用失效前面提过记忆迁移。这里再补一个具体案例迁移后我的周报生成器 Skill 一直报没权限访问目录。排查下来发现记忆里记录的是旧机器上的路径/home/olduser/reports新机器实际路径是/home/newuser/reports。WorkBuddy 的权限粒度是基于路径的旧路径不在授权清单里自然被拒绝。在语言层面做一次批量替换把记忆导出文件里的旧路径全局替换成新路径或者干脆清掉与该 Skill 相关的旧记忆让它重新学习一次。我更推荐后者因为记忆里混杂了太多环境相关的内容与其逐个修不如让它重新积累。6.5 给新手的三天连接上车清单如果你也想把 WorkBuddy 从聊天框变成生产力工具我建议按这个顺序动手第一天先搞定模型通道配置确保能正常对话然后把常用的文档目录加进文件夹访问范围。第二天配置历史对话记录和记忆存储的位置找一个内部 wiki 页面接一个检索组件测试知识库问答。第三天配置第一个外部连接企业微信 Webhook 推送再做一个最简单的定时任务比如每天早上推一条消息验证全套链路。按这个顺序走三天后你就拥有一个能读本地文件、能查团队知识、能定时推送消息的工作台了。别一上来就追求复杂连接这个东西通了第一条后面的路自然会越走越宽。我在真实环境里踩过的坑基本都写在上面了希望你能绕开。