第 7 章 助理连接配置 · 配套实验¶
本章实验用于验证助理机制（运行前提、各渠道接入、远程任务特性与排查方法）等知识点。 图例：★ 必做实验（仅需 WorkBuddy 基础环境 + 手机微信）；○ 可选实验（需企业微信管理员/开发者认证等条件）。 说明：助理支持 6 个国内主流即时通讯平台——微信助理（推荐）、微信客服号、企微助理、QQ 机器人、飞书、钉钉，另有独立的元宝派接入指南（官方文档《WorkBuddy 接入元宝派指南》）与微信小程序移动端入口；微信渠道（微信助理/微信客服号）支持直接扫码绑定，企业微信、QQ、飞书、钉钉通常需要先在对应平台完成应用或机器人配置。实验 7.2 需要手机微信扫码；实验 7.4 需要企业微信管理员权限（或 QQ 开发者实名认证）。
实验总览¶
| 编号 | 实验名称 | 验证知识点 | 前置条件 | 类型 |
|---|---|---|---|---|
| 7.1 | 运行四前提自查 | 开机/运行/联网/不休眠四前提与防休眠设置 | 完成 1.1 | ★ |
| 7.2 | 微信助理接入 | 扫码绑定、手机下发任务、结果回传 | 手机微信 | ★ |
| 7.3 | 微信小程序多端协同 | 云上模式 vs 连接电脑（本机模式）；桌面端开启“允许移动端连接”且同一账号 | 手机微信、微信小程序 | ○ |
| 7.4 | 企业微信接入 | 长连接扫码绑定；URL 回调（Token/EncodingAESKey + Webhook 回填） | 企业微信管理员权限 | ○ |
| 7.5 | 远程任务特性验证 | 助理专属文件夹、上下文保留、单会话限制 | 完成 7.2 | ★ |
| 7.6 | 四步排查法演练 | 官方 FAQ 排查流程；实践六远程遥控场景 | 完成 7.2 | ★ |
实验 7.1 运行四前提自查¶
- 实验目的：核对助理（远程任务）的四个核心运行前提，并完成防休眠设置。
- 前置条件：完成实验 1.1。
- 操作步骤：
- 对照四前提逐项自查（官方文档《助理（远程任务）》）： ① 电脑保持开机，并运行 WorkBuddy——官方明确“使用助理时，电脑需要保持开机并运行 WorkBuddy”，且“WorkBuddy 必须保持运行状态”； ② WorkBuddy 已登录，与移动端使用同一账号（或已关联），保证账号一致性； ③ 网络连接正常——官方要求“确保网络连接正常”，电脑和手机均能正常访问互联网； ④ 电脑不休眠——官方明确“如果电脑休眠、断网或关闭 WorkBuddy，远程访问将暂时中断”。
- 完成防休眠设置（官方文档《微信助理接入指南（推荐）》）：
- Mac 笔记本请保持打开并接通电源；如果合盖使用，建议外接显示器使电脑不休眠；
- 可在 WorkBuddy 设置中开启“锁屏远程”，防止长时间任务被中断（具体入口以产品实际界面为准）；
- Windows 用户可在系统电源设置中将“使计算机进入睡眠状态”设为“从不”（具体入口以操作系统实际界面为准）；
- 如需长期运行任务（定时巡检、持续集成监控等），可准备一台专属常开主机，在上面安装项目依赖、凭证、插件和工具，保持 WorkBuddy 持续运行。
- 记录本机网络出口与防火墙情况，确认电脑能够正常访问互联网；使用代理或防火墙时，需确保不影响 WorkBuddy 与平台的 WebSocket 长连接等通信（具体配置以产品实际界面为准）。
- 预期结果与验收标准：
- 四前提全部满足：电脑开机、WorkBuddy 运行并登录、网络正常、电脑不休眠；
- 防休眠设置已完成，长时间无操作后电脑不会休眠，远程访问不会因休眠、断网或关闭 WorkBuddy 而中断。
- 官方文档出处：（官方文档《助理（远程任务）》）
实验 7.2 微信助理接入¶
- 实验目的：完成微信助理扫码绑定，并在手机端远程下发任务、查看结果回传。
- 前置条件：手机微信（需 >= 8.0.70）；电脑已安装 WorkBuddy（>= 4.6.4）；完成实验 7.1。
- 操作步骤：
- 核对绑定前置要求（官方文档《微信助理接入指南（推荐）》）：macOS / Windows 上安装 WorkBuddy >= 4.6.4；手机上已登录微信 >= 8.0.70；WorkBuddy 和微信使用同一账号登录（或已关联）；电脑和手机均能正常访问互联网；WorkBuddy 保持运行状态。
- 打开助理设置：打开 WorkBuddy，在左侧“助理”栏点击齿轮图标，进入“助理设置”；在集成列表中找到“微信助理集成”，点击右侧的“配置”按钮。
- 生成绑定二维码：点击“配置”后，按钮会短暂显示为“绑定中...”，WorkBuddy 正在生成用于绑定的二维码；二维码生成后直接显示在卡片下方。
- 扫码完成绑定：打开手机微信，扫描该二维码即可完成绑定。注意：二维码有时效限制，如果二维码过期或扫码失败，请重新点击“配置”生成新的二维码。
- 确认绑定状态：扫码完成后，卡片状态会变为“已绑定”；如果后续需要更换账号，可以点击“解绑”后重新绑定（WorkBuddy 当前一对一绑定，切换账号需先解绑再使用新账号扫码）。
- 手机下发任务与结果回传：微信助理接入无需填写 App ID、App Secret 等开发凭证，只需扫码即可完成绑定。绑定后即可在微信中：
- 发送文字消息启动新的任务，或继续“助理”板块中未完成的会话；
- 发送后续指令、回答 WorkBuddy 的追问、指导进行中的工作；
- 批准命令执行、文件修改等需要确认的操作；
- 查看任务输出、差异对比；当 WorkBuddy 完成任务或需要您关注时，在微信中收到通知；
- 消息类型支持文字消息、图片消息（截图或文档照片）、文件消息（转发文件）、语音消息（需微信语音转文字功能）。
- 跨设备接续验证：当微信消息到达时，WorkBuddy 会自动切换到“助理”标签页并加载对应的会话；回到电脑后可在“助理”页面查看远程任务的完整执行记录，包括思考过程、操作步骤、生成文件及最终结果（具体以产品实际界面为准）。
- （可选）微信客服号是另一种绑定通道，与微信助理功能相同、绑定流程一致（扫码即可），可根据需要选择其中一种使用（官方文档《微信客服号接入指南》）。
- 预期结果与验收标准：
- 扫码后绑定成功，卡片状态为“已绑定”；
- 手机下发任务后电脑端正常执行，执行过程与最终结果回传到微信聊天窗口；
- 能在电脑端“助理”页面看到对应的远程会话与完整执行记录。
- 官方文档出处：（官方文档《微信助理接入指南（推荐）》）
实验 7.3 微信小程序多端协同（可选）¶
- 实验目的：验证 WorkBuddy 微信小程序的“云上模式”与“连接电脑（本机模式）”两种执行环境及其使用前提。
- 前置条件：手机微信、WorkBuddy 微信小程序；完成实验 7.2。
- 操作步骤：
- 在微信中打开 WorkBuddy 小程序（官方文档《WorkBuddy 小程序简介》，具体入口与界面以产品实际界面为准）。
- 体验“云上模式”：不依赖个人电脑在线，直接在小程序内下发任务，任务在云上执行，查看任务产物。
- 体验“连接电脑（本机模式）”：先在桌面端开启“允许移动端连接”，且两端（小程序与桌面端）登录同一账号；再通过小程序远程操控电脑端，查看任务、续聊、停止任务（具体入口以产品实际界面为准）。
- 对比两种模式的使用前提与差异：云上模式无需电脑即可执行任务；“连接电脑（本机模式）”需要电脑端 WorkBuddy 运行、已开启“允许移动端连接”且两端使用同一账号。
- 预期结果与验收标准：
- 云上模式无需电脑即可完成任务并查看产物；
- 连接电脑（本机模式）能远程查看电脑端任务与产物，可续聊、停止任务；
- 能说出两种模式的使用前提与差异。
- 官方文档出处：（官方文档《WorkBuddy 小程序简介》）
实验 7.4 企业微信接入（可选）¶
- 实验目的：验证企业微信长连接扫码绑定与 URL 回调两种接入模式，掌握 Bot ID/Secret 与 Token/EncodingAESKey 的获取与回填。
- 前置条件：拥有一个可创建智能机器人的企业微信账号（管理员可在管理后台创建，普通成员可在客户端“工作台”创建）；电脑已安装 WorkBuddy >= 4.6.4；完成实验 7.1。
- 操作步骤：
- 前置检查（官方文档《企微助理接入指南》）：已安装 WorkBuddy >= 4.6.4；拥有一个可创建智能机器人的企业微信账号（如还没有，可前往企业微信官网免费注册一个企业）；电脑和手机均能正常访问互联网；WorkBuddy 保持运行。
- 长连接模式（推荐，扫码绑定）：
- 管理员路径：打开浏览器，访问企业微信管理后台，使用管理员账号登录后，依次点击“安全与管理”→“管理工具”→“智能机器人”→“创建机器人”；如果先进入 AI 自动生成页面，请点击左下角的“手动创建”，在创建页面直接选择“API 模式创建”；
- 普通成员路径：打开企业微信客户端，进入“工作台”→“智能机器人应用”→“创建机器人”；如先进入 AI 自动生成页面，请点击左下角的“手动创建”，再选择“API 模式创建”；
- 填写基本信息：机器人名称（建议填写容易识别的名字，如“WorkBuddy 助手”）；管理员设置“可见范围”，普通成员设置“可使用成员”（选择员工、部门或标签）；保存后，在“API 配置”区域选择“使用长连接”；
- 获取凭证：在“API 配置”区域复制 Bot ID；点击“点击获取”获取 Secret，并妥善保存；
- 在 WorkBuddy 中完成绑定：打开 WorkBuddy，点击左下角头像菜单中的“设置-助理设置”，在“集成（BETA）”区域找到“企微助理集成”，点击“配置”；在弹窗中选择“WebSocket 长连接”，有两种绑定方式可选：① 点击快捷绑定接入，使用企微扫码完成绑定；② 手动填写刚才复制的 Bot ID 和 Secret，点击“注册”完成绑定；
- 提示：长连接模式配置步骤更少，不需要再填写 URL、Token 或 Encoding-AESKey，也不需要回填 Webhook URL。
- URL 回调模式（备选方案）：
- 在企业微信机器人创建页面，“API 配置”区域选择“使用 URL 回调”；点击 Token 和 Encoding-AESKey 输入框右侧的“随机获取”，并妥善保存这两个参数（请务必保存好，否则后续无法完成注册）；
- 打开 WorkBuddy，进入“助理设置”→“企微 AIBot 集成”→“配置”；在注册弹窗中切换到“使用 URL 回调”；填入刚才获取的 Token 和 Encoding-AESKey，点击“注册”；注册成功后，复制生成的 Webhook URL；
- 回到企业微信的机器人创建页面，将刚才复制的 Webhook 地址粘贴到 URL 输入框，点击“保存”完成配置；
- 说明：URL 回调的消息校验基于平台通用的 Token 签名与 EncodingAESKey 加解密机制；该模式适用于需要 Webhook 回调的场景（具体以产品实际界面为准）。
-
开始使用：在企业微信通讯录的“企业创建的”分组下找到刚刚创建的机器人，点击“发消息”；发送一条简单消息，例如：
进行联通测试，如果配置正确，WorkBuddy 会接收到消息并在企业微信中返回回复。 5. 分别用手机企业微信向两种模式下发任务，验证消息可达；回到电脑端在“助理”页面查看远程任务的完整执行记录（思考过程、操作步骤、生成文件及最终结果）。 - 预期结果与验收标准： - 长连接模式：扫码或凭据绑定成功，机器人能正常回复，任务可达； - URL 回调模式：完成 Webhook 回填后消息可达，Token/EncodingAESKey 校验通过； - 能对比两种模式的适用场景：长连接模式配置更简单、无需回填 Webhook URL；URL 回调模式适用于需要 Webhook 回调的场景；并理解“企业微信、QQ、飞书、钉钉通常需要先在对应平台完成应用或机器人配置”。 - 官方文档出处：（官方文档《企微助理接入指南》）
实验 7.5 远程任务特性验证¶
- 实验目的：验证远程（助理）任务与本地普通任务的区别（官方文档《助理（远程任务）》对比表）。
- 前置条件：完成实验 7.2。
- 操作步骤：
- 通过手机下发一个任务，确认远程任务的工作目录固定使用“助理”专属文件夹（对比：普通任务可自由指定工作目录）。
- 在同一会话中多次追问，确认远程任务上下文保留完整对话历史、不可清空；与本地普通任务“可清空历史重新开始”对比。
- 尝试在手机端同时发起多个任务，确认助理仅一个会话，所有远程指令集中处理（对比：普通任务支持多个并行任务）。
- 回到电脑端打开“助理”页面，查看远程任务的完整执行记录，包括思考过程、操作步骤、生成文件及最终结果；验证官方建议“本地操作优先使用主界面的普通任务；需要远程触发或统一查看记录时，再使用助理”。
- （可选）验证远程控制安全边界：绑定身份在“助理设置”中配置，支持灵活换绑不同移动端平台；WorkBuddy 助理对每一条远程指令执行多层来源校验；涉及文件删除、系统配置修改、批准命令执行等操作需确认后方可执行（具体以产品实际界面为准）。
- 预期结果与验收标准：
- 远程任务使用“助理”专属文件夹，无法随意切换目录；
- 远程会话历史完整保留、不可清空；
- 仅一个活跃会话，所有远程指令集中处理；
- 与第 7 章对比表（工作目录、新建对话、上下文管理三个对比项）一致。
- 官方文档出处：（官方文档《助理（远程任务）》）
实验 7.6 四步排查法演练¶
- 实验目的：模拟故障场景，按“四步排查法”定位问题，并融入实践六“远程遥控 WorkBuddy”的通勤/外出场景，完成用手机遥控电脑执行任务的完整流程。
- 前置条件：完成实验 7.2。
- 操作步骤：
- 构造一个故障场景：让电脑进入休眠（或关闭 WorkBuddy、断开网络），从手机发送任务，观察无响应。
- 按四步排查（口径依据各接入指南“常见问题”章节，官方文档《助理（远程任务）》）： ① 检查 WorkBuddy 状态：确认电脑上的 WorkBuddy 正在运行，且“助理”服务已开启（未关闭）； ② 检查绑定/连接状态：返回“助理设置”检查对应集成状态是否仍为“已绑定/已连接”；如一直停留在“绑定中...”或扫码后未显示“已绑定”，可重新生成二维码后再次扫码，或重启 WorkBuddy 后重新绑定； ③ 核对凭据（凭据型渠道）：长连接模式核对 Bot ID 和 Secret；URL 回调模式核对 Token 和 EncodingAESKey；QQ 核对 AppID 和 AppSecret；飞书核对 App ID、App Secret、Encrypt Key；钉钉核对 Client ID（AppKey）和 Client Secret（AppSecret）以及 AES Key、Token；元宝派核对 AppID（App Key）和 AppSecret（App Secret）——确保与平台侧完全一致、无多余空格； ④ 检查网络连接：确保电脑能够正常访问网络，电脑和手机均能正常访问互联网。
- 修复故障（唤醒电脑、重新打开并登录 WorkBuddy、恢复网络、重新绑定等）后，重新下发任务确认恢复。
-
融入实践六场景，完成完整远程流程（官方文档《实践六：远程遥控 WorkBuddy》）：
- 通勤时用手机继续远程对话编程：用自然语言描述当前问题、预期目标和可接受的处理范围，例如：
- 手机远程完成电脑文件跨端传输：在移动端明确说明文件名称、所在目录与目标动作，例如：
- 遵循使用建议：先给清晰目标（远程场景下避免模糊指令）；减少高风险操作（涉及删除、覆盖、批量移动时，建议先要求预览）；保留关键文件名（跨端操作时明确文件名和目录能显著提升成功率）。
- 预期结果与验收标准：
- 能按顺序完成四步排查并定位根因；
- 修复后任务恢复正常，消息可达并回传结果；
- 能完成通勤/外出场景下用手机遥控电脑执行任务的完整流程；
- 能总结“手机无响应”的最常见原因（电脑休眠、WorkBuddy 未运行或助理服务关闭、绑定状态异常、凭据错误、网络问题）。
- 官方文档出处：（官方文档《助理（远程任务）》）（官方文档《实践六：远程遥控 WorkBuddy》）