企业官网建设流程全解析

折腾 WorkBuddy 前，先把这几件事搞清楚

如果你最近刷到过"WorkBuddy"这个词，大概率和我一样，是从 CodeBuddy 相关的讨论里顺藤摸瓜摸过来的。简单说，腾讯在 CodeBuddy 这个 AI 编程助手的底座上，推出的本地智能工作台 WorkBuddy，不再只是帮你补全代码、聊聊天，而是把代码生成、终端命令、文件读写、Git 操作这些东西揉进了一个桌面应用里。你可以把它理解成：一个更懂中文开发者习惯的 AI 工作环境，装上之后 AI 能直接在你本地干活，而不只是给你一段建议。

这篇教程解决的就是"怎么把它弄到你的电脑上"这件事，覆盖 Windows 和 macOS 两套平台。我不打算只写"去官网下载、双击下一步"这种没营养的话，而是会把我在多台机器上装 WorkBuddy 时遇到的坑、排错思路、以及装完之后的必要配置一起捋一遍。无论你之前用过 VS Code、Cursor 还是纯命令行，这篇都适用——唯一的门槛是，你需要会用终端执行几条命令。

1. 装之前先弄明白：WorkBuddy 到底装的是什么

1.1 WorkBuddy 和 CodeBuddy 是什么关系

你得先理解 WorkBuddy 的定位，否则装完很容易困惑。CodeBuddy 是腾讯云的 AI 编程助手，最早以 IDE 插件形式出现，功能偏向"对话式补全"：你写代码，它给建议，你提问，它回答。WorkBuddy 是同一个团队的延伸产品，但形态变了——它更接近一个独立的智能工作台（Agent），目标是让 AI 直接接管部分本地操作：创建文件、跑命令、查日志、改配置，而不是只停留在"输出面板"里。

这带来的直接后果是：装的不是一个纯编辑器，而是一个带着"操作权限"的 Agent 运行环境。这也是为什么安装教程不能只讲"双击安装包"，因为后面还有登录认证、目录授权、工具链检查这些步骤。权限没给够，AI 就只能在聊天框里输出文字，干不了实事。

1.2 它能做什么，装了之后实际能改善什么

我自己的体验是，WorkBuddy 解决的最大痛点是"上下文割裂"。在传统开发流程里，你要在 IDE、终端、文档、浏览器之间来回切换，AI 助手只看到了你贴给它的那几段代码，对项目整体结构一无所知。WorkBuddy 的思路是直接把工作目录交给 AI 代理，它自己会去读你项目里的文件、运行命令来验证结果、看到报错后主动修复。

具体到日常使用，我装好后最常用的是这几类操作：

• 让它初始化一个新项目脚手架，它直接在当前目录生成文件并安装依赖
• 让它排查本地服务的报错日志，它能自己跑到日志目录去翻、去过滤、定位问题
• 让它按规范生成 Git commit message，并且自动完成 add/commit
• 让它在指定的笔记目录里创建文档、整理内容

所以，这篇教程的核心价值不只是"把图标装出来"，而是让你装完之后，这个 Agent 真的能跑起来、能摸到你本地的文件、能执行命令、能配合你的日常工作流。

1.3 两种安装形态的取舍：客户端 vs 命令行

目前 WorkBuddy 的安装主要有两条路，我在 Windows 和 macOS 上都分别试过：

• 桌面客户端形态：官方提供的 GUI 安装包，Windows 是 exe，macOS 是 dmg。适合大多数人，安装直观，但有额外的图形界面进程，更新需要重新下载安装包。
• 命令行工具形态：通过 npm 全局安装 CLI 包，然后在终端里启动工作台界面。优点是更新方便、权限控制更清晰、适合习惯终端的开发者，但要求你提前装好 Node.js。

这篇文章两条路都会写，我的建议是：如果你平时不碰终端，走桌面客户端；如果你已经装了 Node.js，命令行形态更省心，后续升级时少点麻烦。

2. Windows 端安装全流程：从环境检查到工作台跑起来

2.1 安装前 5 分钟的环境预检

在 Windows 上装 WorkBuddy，最容易翻车的不是安装这一步，而是安装前的环境没检查。浪费时间踩坑不如先花五分钟确认三件事。

第一，确认 Windows 版本。WorkBuddy 官方对 Windows 10/11 64 位支持得最好，Windows 7 或 32 位系统就别折腾了，直接放弃。你可以在"设置 → 系统 → 关于"里看系统类型，确认是 64 位。

第二，确认 Node.js 是否已安装。开一个 PowerShell 或 CMD，执行：

node -v npm -v

如果提示找不到命令，去 Node.js 官网下载 LTS 版本的 Windows 安装包，一路下一步装好。建议装 18.0 或更高版本，WorkBuddy 的 CLI 依赖比较新的 Node.js 特性。如果你本机还在用 Node 16，建议先用 nvm-windows 切到 18/20 再继续，别硬上。

第三，确认终端环境。我用下来最顺的是 Windows Terminal 加 PowerShell 7，传统 CMD 也能跑，只是显示效果和 Tab 补全体验差一些。没有 Windows Terminal 的话直接在微软商店搜"Windows Terminal"装一个，免费。

2.2 图形界面安装路线：官网下载与 exe 安装

如果你选择桌面客户端，先打开 WorkBuddy 官网（这里注意，要用搜索引擎找官方入口，别在第三方下载站随便下），找到对应 Windows 的 exe 安装包。

下载完成后，有两点特别提醒：

第一，安装路径不要带中文和空格。很多人的用户名是中文拼音缩写还好，但如果你把路径改到"D:\软件\WorkBuddy"，后续某些工具在调用本地文件时可能会出莫名其妙的编码问题。我一般装在"C:\WorkBuddy"或保持默认路径。

第二，Windows 自带的安全中心和第三方杀毒软件可能会拦截。我实装时，Windows Defender 的"智能应用控制"第一次运行时弹了风险提示。这不是安装包有问题，而是新软件没有足够的用户基数、数字签名还没被信任。处理方式是：如果确认安装包是从官网下载的，在 Defender 提示页面选择"仍要运行"，或者提前把安装目录加入杀毒软件的白名单。

安装完成后，桌面上会出现 WorkBuddy 图标，双击启动，首次启动会让你登录账号，这一步先不用急，我会在后面的章节统一说明。

2.3 命令行安装路线：npm 全局安装与验证

如果你走 CLI 路线，在 PowerShell 里执行：

npm install -g @tencent/workbuddy-cli

这里有一个很重要的提醒：@tencent/workbuddy-cli是我目前可用的包名，但这个团队迭代很快，包名有过调整。如果你执行后报 404 或者提示包不存在，去官网或 GitHub 仓库查最新的全局安装命令，版本更新后命令略有变动是很正常的。

安装完成后，执行：

wb --version

如果能看到版本号，说明 CLI 装好了。接着在你想作为工作目录的文件夹里（我建议先开一个空文件夹测试），执行：

wb init

这一步会做两件事：一是在当前目录生成 WorkBuddy 的配置文件（比如.workbuddy目录和 settings 文件），二是检查运行环境，把缺失的依赖项列出来。按照提示补装即可。

2.4 Windows 上 PATH 环境变量的排障

wb命令提示"无法识别"是 Windows 上最常见的坑。原因是 npm 全局安装目录没有加入系统的 PATH。排查方式是手动找到 npm 全局 bin 目录：

npm prefix -g

这条命令会输出全局目录，比如C:\Users\<你的用户名>\AppData\Roaming\npm。接下来打开"系统属性 → 环境变量"，在"用户变量"中找到 Path，把这个 npm 目录添加进去，然后关掉终端重新打开，再执行wb --version。如果你之前是开着终端安装的，务必重开一个，环境变量不会热加载。

3. macOS 端安装全流程：Intel 和 M 系列芯片要区别对待

3.1 先确认你的 Mac 芯片类型

macOS 上与 Windows 最大的不同，在于芯片架构。你需要在"左上角苹果图标 → 关于本机"里确认处理器是 Apple Silicon（M1/M2/M3/M4 系列）还是 Intel。这会决定你下载哪个安装包，以及后续某些工具链是否要装 Rosetta。

一个很关键的点：如果你用的是 M4 这种新机器，有些没适配原生 ARM 的工具安装完会闪退或崩溃。WorkBuddy 的官方安装包已经分出了 Apple Silicon 和 Intel 两个版本，选错了装不上。命令行路线则要确认 Node.js 是否也是 ARM 版本。如果直接在官网下载的 Node.js pkg，通常会自动匹配架构，但如果你之前用 Homebrew 装过 Node，建议执行node -p "process.arch"，确认输出是arm64而不是x64。

3.2 桌面客户端安装与 macOS 权限处理

桌面客户端和 Windows 流程类似：官网下载 dmg，双击挂载，把 WorkBuddy 拖到 Applications 文件夹。但这里有几个 macOS 特有的问题要注意。

第一，首次打开时 Gatekeeper 可能会报"无法验证开发者"。如果你的系统是 macOS Sequoia 或更新版本，且应用是从官网下载的，可以在"系统设置 → 隐私与安全性"里看到"仍要打开"的按钮，点一下就好。注意，不建议去执行sudo spctl --master-disable开启"任何来源"——这个方法虽然能绕开所有拦截，但会让整个系统的安全性下降，没必要为装一个工具这么做。

第二，M 系列芯片如果下载错了 Intel 版，也可能出现打开后提示"已损坏"之类的情况，本质是 Rosetta 翻译层的兼容问题。直接用arch -arm64 open /Applications/WorkBuddy.app这种命令硬开不如老老实实重新下载 ARM 版。

第三，N 系列芯片用户里，装完 app 后首次启动需要授权"完全磁盘访问权限"。因为 WorkBuddy 要读你磁盘上的文件、在你授权的工作目录里执行命令，macOS 的 TCC 机制会在它第一次尝试访问受保护目录时弹窗，你在"系统设置 → 隐私与安全性 → 完全磁盘访问权限"里勾选即可。

3.3 macOS 命令行安装与权限细节

macOS 终端的命令行安装，核心还是 npm。但有一个 Windows 上不常见的麻烦：npm 全局安装目录的写入权限。系统自带的 Node.js 如果装在/usr/local下，npm 全局安装需要 sudo，而 sudo npm install 本身有风险，也容易让后续的全局包权限混乱。我个人的建议是：用 nvm 管理 Node.js，这样 npm 全局目录就在用户目录下，不需要 sudo。

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash # 重开终端，然后安装 Node 20 nvm install 20 nvm use 20

之后正常执行：

npm install -g @tencent/workbuddy-cli wb --version

如果执行wb提示"command not found"，大概率是 npm 的 bin 目录没在 PATH 里。用npm prefix -g拿到全局目录，然后在~/.zshrc里加一行export PATH="$(npm prefix -g)/bin:$PATH"，再source ~/.zshrc重载配置即可。

3.4 macOS 重装与数据迁移时的零散经验

热搜词里有人搜"macos重装"和"如何将整个硬盘的macos系统克隆到外置优盘"，我猜是担心重装以后要重新配置折腾所有开发环境。这里说一个我自己的经验：WorkBuddy 的配置集中在一个目录里，你只需要把~/.workbuddy目录和项目里的.workbuddy目录备份好，重装系统后直接拷回去即可恢复大部分配置。所以如果你有换机或者重装系统的计划，不用害怕，配置迁移成本很低。

4. 装完不等于完事：登录认证、目录授权和 Agent 功能验证

4.1 登录账号：微信扫码与云端模型调度

安装完成后，第一次启动 WorkBuddy 会让你登录。目前支持微信扫码登录和腾讯云账号登录，二者本质上都会拿到一个访问令牌，用于云端模型调度与配额管理。不要跳过这一步，否则就算界面能打开，发送对话请求时也会报 401 认证错误。

登录后建议先检查一下账号状态，Windows 和 macOS 都通用：在界面右上角的头像菜单里看有没有显示当前用户，以及有没有配额提示。有些早期测试版本需要在网页端先申请开通白名单，如果你登录后界面提示"无权限"，去官网检查一下自己的账号有没有被加入试用名单。

4.2 初始化工作目录：让 Agent 知道你允许它动哪些文件

登录之后第一步，不是急着跟它聊天，而是规划好工作目录。WorkBuddy 的 Agent 默认只会在你授权的工作目录内读写文件，不会全局乱跑。在桌面客户端里，可以通过"打开文件夹"来选择一个工作目录；在 CLI 里就是进入目录后执行wb init。

这里有一个细节建议：不要图省事直接选整个用户目录或者整个磁盘作为工作目录。Agent 读文件越深，上下文越大，响应越慢，而且误操作的面也会变宽。我自己习惯是每个项目单独建一个目录，WorkBuddy 指向项目根目录。比如~/projects/demo-app，只暴露这个目录给它，两边都干净。

4.3 验证 Agent 能力：跑一个能实际工作的任务

登录和目录都配置好之后，需要验证 Agent 是不是真的能干活。你可以让它做一个简单的实际任务来测试：在当前目录创建一个 README.md 文件，写入一段介绍文字，然后用ls或 Finder 检查文件是否真的生成了。

更进一步，让它初始化一个简易前端项目。比如直接给指令：

帮我在当前目录初始化一个 Vite + React 项目，并启动开发服务器，然后告诉我访问地址。

如果它真的能依次执行npm create vite、npm install、npm run dev这些命令，说明目录权限、终端执行权限都通了。这一步验证的是最核心的能力链路，通路了，后面的日常使用就顺畅了。

4.4 环境自检命令：w 命令别直接吞报错

如果你在人工验证之后发现 Agent 某些功能还是不可用，先运行自带的自检命令看看环境是否齐全。CLI 形态下执行：

wb doctor

它会检查 Node.js 版本、npm 全局包、git 配置、网络连通性等关键项。桌面客户端里一般可以在设置页面找到"环境检测"或"运行诊断"入口。我遇到过的情况是：Agent 能聊天，但执行终端命令时报"无法找到 git"，跑一次 doctor 立刻就发现了，原因是 PATH 里没有 git 的可执行路径，补上就恢复了。

4.5 常用命令速查表

5. 安装过程中最容易翻车的几个坑：完整排查链路

5.1 npm 安装卡住不动：换源是第一步，判断是网络还是包问题

先说说最常见的情况：执行npm install -g @tencent/workbuddy-cli之后，进度条半天不动，或者超时失败。很多人第一反应是网络问题，但网络问题也分好几种。

先区分是"下载不了"还是"解析不了"：如果报错信息里是ETIMEDOUT、ECONNRESET这种，通常是网络连接问题，优先考虑切换 npm 镜像源。执行：

npm config set registry https://registry.npmmirror.com

换源后重试安装。如果报错是ENOENT、404 Not Found，那就是包名写错了或者包真的不存在，去官网核实最新的包名，别在镜像源上死磕。

我这里要特别说明一下：不要为了加速去搜任何所谓"加速器"或第三方代理工具，完全没有必要。npm 官方源在国内换镜像源之后速度已经很好，我实测几百 MB 的包也能跑满带宽。如果换了镜像还慢，检查是不是公司网络有特殊的防火墙策略，换手机热点试一次就知道。

5.2 wb 命令提示"无法识别/command not found"

这个坑在前面 Windows 和 macOS 的章节分别提到了，但我想在这里做一次统一的排查梳理，因为这是 80% 的新手都会遇到的。

排查链路如下：

1. 先确认包是否真的装上了：npm list -g --depth=0，看输出里有没有 workbuddy-cli 相关包名。
2. 如果有，找到全局 bin 目录：npm prefix -g。
3. 手动执行这个目录下的命令，比如C:\Users\xxx\AppData\Roaming\npm\wb --version，如果能跑通，说明是 PATH 没配置好。
4. 配置 PATH：Windows 编辑用户变量 Path，macOS 编辑~/.zshrc或~/.bash_profile。

另外有个冷门原因：PowerShell 默认的执行策略可能阻止 npm 生成的.ps1脚本。如果命令提示不是"无法识别"而是"禁止运行脚本"，执行：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

然后重开终端。

5.3 macOS 提示"已损坏"或"无法验证开发者"：先别急着关 SIP

聊到 macOS 的权限问题，很多人一搜就搜到"关闭 SIP"或者"macos 任何来源"，但我强烈建议你不要一上来就动 SIP。SIP（系统完整性保护）是 macOS 的安全根基，关掉之后系统被恶意软件攻破的概率会高很多，而且装 WorkBuddy 完全没有必要做到这一步。

正确的处理逻辑是：先确认安装包来源，如果是官网下载的，在"系统设置 → 隐私与安全性"页面找"仍要打开"按钮；如果找不到，检查一下你是不是右键（或双指轻触）点开 app 时按了 Option 键，有时候需要按住 Option 再打开才能调出覆盖 Gatekeeper 的选项。

如果 App 已经打开过但闪退，打开"终端"输入：

sudo log show --last 5m --predicate 'processImagePath contains "WorkBuddy"'

看崩溃日志，通常是缺失动态库或者架构不对。架构不对就重新下载对应芯片版本的安装包。

5.4 Windows 杀毒软件拦截安装程序：先校验签名再操作

Windows 端最常见的翻车点是安全软件误报。先说怎么判断是误报：右键 exe 安装包 → 属性 → 数字签名，看签名者是否和官方一致。如果签名有效，就不用担心；如果签名无效，那就是安装包不对，去官网重新下载即可。

确认签名有效后，把安装目录加入 Windows Defender 排除列表，或者提前关闭"实时防护"（安装完记得重新打开），然后继续安装。装完后如果你还是不放心，可以执行：

Get-FileHash .\WorkBuddy-Setup.exe -Algorithm SHA256

把输出和官网公布的哈希值比对，完全一致就是官方原包。

5.5 登录后报 401 或配额不足：令牌过期与账号状态排查

有时候前一天还好好的，第二天打开 WorkBuddy 报 401，或者提示"配额不足"。先别急着重装，大概率是登录令牌过期。

桌面客户端的话，退出登录再重新登录即可；CLI 的话，看下当前配置里有没有登出命令，比如wb logout然后wb login。如果重登后仍然报配额不足，去官网的控制台里看自己的云资源配额用量是不是用完了——免费的初始配额用完是很正常的，它会有明确的提示，比如"本月对话次数已用尽"。

6. 装好之后值得做的进阶配置：自定义指令与 skill 扩展

6.1 自定义指令为什么值得花时间写

WorkBuddy 安装好、能跑通基础任务之后，体验和"充值过的 AI 助手"之间还差一层：自定义指令（Custom Instructions）。说白了，这是一段附加在每次对话中的全局语义，等效于"给 AI 写使用说明书"。

我推荐至少设置这几类自定义指令：

• 代码风格约束：比如"始终使用 TypeScript，函数需要 JSDoc 注释，禁止使用 any"
• 回答格式约束：比如"修改代码时先说明改动思路再给代码"
• 工作目录约束：比如"执行命令时禁止删除文件，危险命令需要二次确认"
• 语言约束：比如"代码注释和 commit message 使用英文"

这些约束能显著减少你每次对话重复交代的时间，而且能让 AI 的输出质量稳定在线。设置入口一般在 WorkBuddy 设置页的"自定义指令"或"个人偏好"里，格式是 Markdown，直接填写文本即可。

6.2 skill 是什么：让 Agent 长出"专项技能"

除了全局指令，WorkBuddy 支持 skill 机制。你可以把 skill 理解为一组"可复用的能力包"，它定义了一个特定任务的完整流程、相关的 prompt 和操作细节，AI 遇到相应场景时会自动调用或按指令加载。

目前社区里很多人已经在分享各自写好的 skill，比如：

• Git 协作类 skill：规定 commit message 的格式规范，自动替换分支合并模板
• 调试排查类 skill：按"复现步骤 → 查看日志 → 定位根因 → 修复 → 验证"五步法处理 bug
• 文档生成类 skill：从代码注释中抽取 API 文档，按项目模板生成 README
• 前端代码生成类 skill：指定组件库版本、样式方案、目录结构，生成页面代码

如果你自己第一次写 skill，我建议从一个最简单的场景开始，比如"帮我按项目模板生成每日工作周报"。把工作周报需要的章节、参考格式、最大篇幅等要求写清楚，保存为 skill，之后再执行"生成今天的工作周报"就能输出完全符合你预期的内容。

6.3 与 Obsidian 结合的配置思路：把笔记库变成 AI 知识库

有一个很受欢迎的玩法是把 WorkBuddy 和 Obsidian 做结合。思路很简单：把 Obsidian 的笔记库目录作为 WorkBuddy 的工作目录，然后写一个 skill 让它扫描笔记、总结知识、整理待办。

比如你可以在 skill 里这样描述：

工作目录是 Obsidian 笔记库根目录，所有 markdown 文件都是我的笔记。 任务类型：当我说"整理笔记"时，扫描最近一周修改过的文件，按主题归类，生成 MOC（Map of Content）文件，并更新到"汇总"目录下。

这样做的好处是，AI 真正读的是你本地的 markdown 文件，不涉及任何云同步或者第三方接口，数据都在自己手里。相比把笔记内容贴到网页版 AI 里问，私密性和可控性都好很多。

6.4 后续扩展方向：从自动签到脚本到 Linux 版本

装完 WorkBuddy 之后，我还能想到几个值得探索的方向。

第一，把重复性操作固化成 skill。热搜词里有人搜"workbuddy自动签到"，这个思路我很认可——如果你每天都要打开某个后台点签到，或者定期重复某个固定流程，完全可以写一个 skill，把操作步骤沉淀下来，让 Agent 每天按步骤执行，省下大量碎片时间。

第二，关注 Linux 版本。如果你手头有 Linux 服务器或者开发机，WorkBuddy 的 Linux 版本也值得尝试。安装思路和 Windows/macOS 的 CLI 路线一致，Node.js 环境准备好，npm 全局安装，然后在服务器上直接远程会话。

第三，和 Docker 环境结合。如果你的项目是在 Docker 容器里跑的，WorkBuddy 可以作为宿主机的控制面板，让 AI 帮你执行容器操作、查看容器日志。这个玩法需要你对 Docker 有一定基础，但非常能提升效率。

根据我自己的体会，WorkBuddy 这类工具刚装上的第一周，你大概率还是像用普通编辑器一样用它的对话功能。真正拉开体验差距的，是当你开始积累自己的自定义指令、skill，并且把工作目录规划和权限边界都理清楚之后——这时候它才从一个"能回答问题的聊天框"，变成真正在你电脑上干活的 Agent。希望这篇教程能帮你节省掉我当初踩坑的时间。