第 5 章连接器与资料库 · 配套实验¶

本章实验用于验证连接器（内置/自定义 MCP、OAuth 授权）与资料库（连接、双模搜索、引用与存回）等知识点。图例：★ 必做实验（仅需 WorkBuddy 基础环境）；○ 可选实验（需额外账号/权限/配置）。说明：连接器是 WorkBuddy 与外部服务之间的桥梁，技术形态分为 MCP + CLI（标准化协议）与 Skill + CLI（内置脚本），二者在数据收集和权限边界上遵循一致原则。本章实验普遍需要外部账号授权（腾讯文档、QQ 邮箱、乐享、ima 等），请提前准备可用账号与对应 App（如 QQ 邮箱 App），授权时请仔细阅读权限范围（scope）说明。

实验总览¶

编号	实验名称	验证知识点	前置条件	类型
5.1	内置连接器接入	连接器管理入口、OAuth 扫码授权、scope 权限确认、连接状态（绿色圆点）	一个可用账号（QQ 邮箱/腾讯文档/乐享等）及对应 App	○
5.2	自定义 MCP 连接器	mcp.json 配置（command/args/env 或 url/headers）、MCP Server 状态验证	一个可运行的 MCP 服务，或使用腾讯云 MCP 市场现成配置	○
5.3	资料库连接与双模搜索	连接资料库平台（腾讯文档/ima/乐享）；语义搜索 vs 关键词搜索	完成 5.1 的资料库类连接，或直接连接腾讯文档/ima/乐享	○
5.4	资料引用与存回闭环	引用资料（添加到任务）→ AI 加工 → 产物上传到云端（取→用→存）	完成 5.3	○

实验 5.1 内置连接器接入¶

实验目的：走通一个内置连接器的 OAuth 授权接入流程，理解权限 scope 确认与连接状态，认识内置连接器清单及其技术形态。
前置条件：准备一个可用账号（推荐 QQ 邮箱或腾讯文档/腾讯乐享）；QQ 邮箱需手机端安装 QQ 邮箱 App（7.1.5 / 鸿蒙 0.2.9 及更新版本）用于扫码。
操作步骤（以 QQ 邮箱为例）：
打开连接器管理入口：在左侧导航栏中点击“连接器”，进入连接器管理页面。页面展示所有可用连接器，当前支持 QQ 邮箱、腾讯乐享、腾讯文档、TAPD 和腾讯网盘，并支持自定义连接器；也可在消息框中快捷管理连接器。
选择连接器并发起连接：在连接器管理页面找到“QQ 邮箱”卡片，点击右侧的“+”按钮发起连接。QQ 邮箱连接器支持收发、搜索和整理 QQ 邮件，可用自然语言读取邮件内容、汇总邮件线程、管理文件夹。
扫码授权：系统跳转到 QQ 邮箱授权页面并显示二维码，使用手机 QQ 邮箱 App 扫码进行授权。
确认权限（scope）：在手机端确认 WorkBuddy 申请的访问权限，包括：
- 账号信息：获取邮箱账号基础信息；
- 读取邮件：读取收件箱内近一个月的邮件；
- 发送邮件：代为发送邮件；
- 删除邮件（可选）：已删除邮件会移入“已删除”文件夹。确认无误后点击“同意授权”。
完成连接：手机端显示“授权成功”后，点击浏览器弹窗中的“打开”完成连接（取消或者直接关闭网页可能会导致操作中断，需要重新配置连接器）。回到 WorkBuddy，QQ 邮箱卡片名称旁会出现绿色圆点，并提示“连接器 QQ 邮箱已连接”，右侧显示启用/禁用开关。如需管理授权应用，可前往 QQ 邮箱 App“设置 - 账号 - 安全管理 - 登录设备和授权码 - 应用授权”。
验证调用：在对话中发起一个使用该连接器的任务，如：
```
读取我收件箱最近一封邮件并总结要点
```
确认授权范围内的数据可被访问（连接器自身的读写不消耗积分；WorkBuddy 对外部数据进行理解、汇总时消耗积分）。 - 扩展（可选）：按同样流程连接“腾讯乐享”：找到腾讯乐享卡片点击“+”→ 阅读授权确认页（通过乐享知识库 MCP，WorkBuddy 将能够：按你拥有的权限访问知识库、搜索查询知识库中的内容、协助创建与管理知识库中的内容）→ 点击“立即前往授权”→ 使用微信登录或手机号登录乐享知识库 → 确认页面显示的账号信息与权限后点击“继续”→ 回到 WorkBuddy，腾讯乐享卡片名称旁出现绿色圆点，右侧显示启用/禁用开关。 - 预期结果与验收标准： - 扫码授权流程完成，连接器卡片名称旁出现绿色圆点，提示“已连接”，右侧显示启用/禁用开关； - 任务能访问授权范围内的数据（如收件箱近一个月的邮件）； - 能说出 OAuth 的核心思想（用户授权、颁发令牌、凭令牌访问，不提供账号密码）及 QQ 邮箱授权的 scope 清单（账号信息/读取邮件/发送邮件/删除邮件）； - 能说出连接器的技术形态（MCP + CLI / Skill + CLI）与内置连接器清单（QQ 邮箱、腾讯文档、腾讯乐享、腾讯会议、TAPD、腾讯网盘等）。 - 官方文档出处：（官方文档《连接器》）

实验 5.2 自定义 MCP 连接器¶

实验目的：配置一个自定义 MCP 连接器并验证连通，理解 mcp.json 中命令型（stdio）与地址型（Streamable HTTP）两类配置的区别。
前置条件：具备一个可运行的 MCP 服务（本地命令型服务或远程地址型服务）；如无自建服务，可使用腾讯云 MCP 市场的现成配置。
操作步骤：
打开配置入口：在连接器管理页面点击右上角的“自定义连接器”按钮，安装自定义的 MCP 服务（自定义连接器的配置方式与 MCP 配置类似，详细说明可参考 MCP）；也可从侧边栏“插件”进入，点击右上角“MCP 服务器”→“配置 MCP”打开配置编辑器。
选择配置级别：WorkBuddy 支持两种配置级别——用户级（~/.workbuddy/mcp.json，配置一次所有项目复用，适合频繁跨项目使用的能力，如企微机器人通知）与项目级（<项目目录>/.workbuddy/mcp.json，仅当前项目生效，适合专属服务）。
填写 mcp.json：以下为官方示例（接入企业微信机器人 WeCom Bot）。先在企业微信群中“添加群机器人”获取 WebHook URL，再将 your-webhook-url 替换为实际地址后保存：
```
{
  “mcpServers”: {
    “wecom”: {
      “command”: “uvx”,
      “args”: [“wecom-bot-mcp-server”],
      “env”: {
        “WECOM_WEBHOOK_URL”: “your-webhook-url”
      }
    }
  }
}
```
其中命令型（stdio 传输）通过 command、args、env 启动本地 MCP 服务；地址型（Streamable HTTP 传输）通过 url、headers 连接远程 MCP 服务（具体字段以产品实际界面为准）。
确认配置状态：保存后在界面中查看 MCP Server 状态——🟢 绿色表示连接成功、可正常使用；🔴 红色表示配置异常，需检查配置内容、命令环境或地址（配置失败时优先确认 JSON 的括号、引号是否完整）。
验证调用：配置完成后用自然语言描述需求即可，WorkBuddy 会自动调用对应的 MCP Server。官方示例指令：
```
请通过企业微信机器人通知：正式产品已发布，请 @xxxx 进行验收。
```
6. 拓展（可选）：如无自建服务，可访问腾讯云 MCP 市场获取现成的 MCP 资源配置代码完成接入。 - 预期结果与验收标准： - 配置保存后 MCP Server 状态为绿色（连接成功，无红色错误状态）； - 自然语言指令能触发工具调用（如企微机器人通知成功送达群聊）； - 能说出 mcp.json 中命令型（stdio：command/args/env）与地址型（Streamable HTTP：url/headers）两类配置的区别，以及用户级/项目级配置的适用场景； - 配置失败时能根据红色状态与 JSON 格式检查定位问题。 - 官方文档出处：（官方文档《MCP》）（官方文档《连接器》）

实验 5.3 资料库连接与双模搜索¶

实验目的：连接资料库平台并对比语义搜索与关键词搜索的入口与效果。
前置条件：完成实验 5.1 中资料库类连接（或直接连接腾讯文档/ima 知识库/乐享知识库，推荐腾讯文档）。
操作步骤：
连接平台（以腾讯文档为例）：在左侧边栏点击“资料库”，选择“腾讯文档”→ 点击“立即前往授权”→ 使用微信/QQ 扫码登录对应文档账户 → 在手机端确认权限详情：读取文档内容（读取您的各类型文件、文件夹及具体内容）、编辑与管理文件（代表您进行查看、编辑、创建及管理操作）→ 同意后即可使用。连接后 WorkBuddy 将获得登录用户的腾讯文档权限。
- ima 知识库：选择“ima 知识库”→ 点击“立即前往授权”→ 微信扫码登录 ima 知识库 → 再次“确认授权”（WorkBuddy 将获得：在 WorkBuddy 中查看我的知识库列表；查看或搜索知识库资料；将知识库文件添加到任务或者将文件保存到 ima 知识库）。
- 乐享知识库：选择“乐享知识库”→ 点击“立即前往授权”→ 使用微信扫码登录或手机号登录（首次登录需要绑定手机号）→ 点击“继续”完成授权（WorkBuddy 将获得：读取知识库权限；搜索和查询知识内容；创建和编辑知识内容）。
使用语义搜索：新建任务，用自然语言描述需要的文档即可找到，如：
```
找一下上个月关于用户增长的报告
```
观察检索结果。 3. 使用关键词搜索：打开资料库，在右上方搜索框输入关键词，回车后即可搜索到对应文件；资料库支持按文档标题和按文档所有者两种检索方式，观察“精准命中”。 4. 组合使用：先语义搜索缩小范围，再关键词精确定位。 - 预期结果与验收标准： - 资料库连接成功，云端文档可被检索； - 语义搜索能理解意图（任务中用自然语言描述即命中），关键词搜索能精确命中（资料库右上方搜索框输入标题/所有者关键词）； - 能举例说明两种搜索的入口差异与适用场景； - 能说出所连平台授予 WorkBuddy 的权限清单（如腾讯文档：读取文档内容、编辑与管理文件）。 - 官方文档出处：（官方文档《资料库》）（官方文档《腾讯文档》）（官方文档《乐享知识库》）（官方文档《WorkBuddy × ima 功能指引》）

实验 5.4 资料引用与存回闭环¶

实验目的：完整走通“取资料 → AI 加工 → 存回沉淀”闭环，掌握任务中引用资料与产物上传到云端的操作入口。
前置条件：完成实验 5.3（资料库已连接腾讯文档/乐享/ima 且有可用文档）。
操作步骤：
取——将资料添加到任务：在资料库中选中对应文件，点击“添加到任务”；或鼠标悬停对应文件，点击“添加到任务”图标。不仅支持选择在线文档，腾讯文档可以直接打开的 Word、Excel、PPT、PDF 等本地文件也可以在资料库中勾选，并添加到任务。乐享知识库与 ima 知识库还支持在新建任务的输入框上方“上传文件”图标处打开知识库，支持勾选整个团队空间/知识库或选择文件，点击“确定”添加到对话。
用——描述任务让 Agent 加工：在输入框中描述任务操作，如“提炼摘要 / 翻译 / 数据分析”；也可采用《实践十一》的官方示例指令，如：
```
帮我汇总这份腾讯文档里的评论，按‘问题、建议、待确认事项’分类整理
帮我从这份项目文档中提炼出适合周会汇报的 5 条重点
```
3. 存——产物上传到云端：在右侧产物中找到需要的文件，点击“上传到云端”，选择对应平台储存：腾讯文档（选择“腾讯文档”储存）；乐享知识库（选择“乐享知识库”储存，保存支持按照团队空间储存）；ima 知识库（保存支持按个人/共享/订阅三类知识库储存）。上传成功后到云端平台确认文件可见。 4. 扩展（实践十一场景）：腾讯文档连接成功后，即可用一句话管理腾讯文档——文档创建、内容整理、表格与收集表处理、多人协作汇总、权限查询与会议纪要沉淀。官方示例指令：
```
帮我创建一份腾讯文档，标题是‘项目复盘’，并先生成一个包含背景、问题、结论和行动项的结构。
帮我新建一个腾讯文档在线表格，用来记录招聘进度，字段包含候选人、岗位、面试轮次、状态和备注。
```
- 预期结果与验收标准： - 文件成功引用到任务并被 AI 加工（勾选/悬停“添加到任务”→ 输入框描述任务）； - 产物一键存回云端（右侧产物“上传到云端”→ 选择平台），可在对应平台查看（乐享按团队空间储存）； - 能复述“取 → 用 → 存”三步及各自操作入口； - 能用一句话让 WorkBuddy 检索、汇总、创建或管理腾讯文档。 - 官方文档出处：（官方文档《资料库》）（官方文档《内容管理》）（官方文档《腾讯文档》）（官方文档《乐享知识库》）（官方文档《WorkBuddy × ima 功能指引》）（官方文档《实践十一：一句话，管理你的腾讯文档》）

第 5 章 连接器与资料库 · 配套实验¶

实验总览¶

实验 5.1 内置连接器接入¶

实验 5.2 自定义 MCP 连接器¶

实验 5.3 资料库连接与双模搜索¶

实验 5.4 资料引用与存回闭环¶

第 5 章连接器与资料库 · 配套实验¶