Skip to main content
Cookbook

接入千问办公与 WorkBuddy

在千问办公与 WorkBuddy 中安装 Knowledge Studio Skill，用自然语言检索企业知识库并获得带来源的回答

背景说明

Knowledge Studio 将知识库的列举、检索与问答能力封装为 Agent Skill。在千问办公或 WorkBuddy 中安装该 Skill 后，你用自然语言描述需求即可，客户端会自动调用检索脚本，并在回答末尾标注内容来自哪个知识库、哪份文档、哪一节。 与在对话中临时上传附件相比，知识库由服务端统一维护。文档更新后，所有成员检索到的都是最新版本，无需重复分发文件。 本文面向日常办公用户，全程无需编写代码。
该 Skill 提供的是检索与问答能力。知识库的创建与文档导入在控制台完成，参见创建知识库。

准备工作

开通服务并创建 API Key

事项操作
开通知识库服务打开知识库页面，点击立即开通，等待一至两分钟生效
创建 API Key在设置 → API Key 页面创建，格式为 sk- 开头的字符串
准备知识库至少有一个知识库，且其中文档的状态为解析完成
sk-sp- 开头的是 Coding Plan Key，不支持知识库服务，调用时会返回 401 InvalidApiKey。请确认创建的是标准 sk- Key。

控制台 API-Key 页面，点击右上角 创建API-KEY 后复制密钥

创建 API Key

检查运行环境

Skill 通过本地 Python 脚本调用检索接口，需确认设备已安装 Python 3。在终端或命令提示符中执行： 
python3 --version
能够显示版本号即满足要求。Windows 如提示找不到命令，从 python.org 下载安装，安装过程中勾选 Add python.exe to PATH。

配置 API Key

Skill 从系统环境变量中读取 API Key，配置一次后长期有效。两个客户端的配置方式相同。
  • Windows
  • macOS
  1. 在开始菜单中搜索并打开 编辑系统环境变量
  2. 点击 环境变量，在 用户变量 区域点击 新建
  3. 变量名填写 DASHSCOPE_API_KEY，变量值填写你的 API Key
  4. 保存后重启客户端
API Key 是访问凭证，泄露后他人可直接调用你的知识库。请勿在聊天群中传播，也不要输入到客户端对话框。按上述方式配置后，Skill 会自动读取，无需在对话中提供。

安装 Skill

Skill 包名为 alibabacloud-bailian-rag-knowledgebase，源码位于 aliyun/alibabacloud-aiops-skills 仓库的 skills/aiml/sfm/alibabacloud-bailian-rag-knowledgebase 目录。

千问办公

千问办公的 Skill 统一存放于 ~/.qwenworkcn/skills/，支持以下两种安装方式。 方式一：对话安装（推荐） 在对话框中发送以下内容，千问办公会自动完成下载、放置与加载： 
请安装这个仓库里的 alibabacloud-bailian-rag-knowledgebase 技能：
https://github.com/aliyun/alibabacloud-aiops-skills
该方式要求客户端所在网络可访问 GitHub。企业网络存在出网限制时，安装会失败或长时间无响应，此时改用方式二。

千问办公自动完成克隆仓库、校验技能结构、安装到 ~/.qwenworkcn/skills/ 并验证结果

千问办公对话安装 Skill
方式二：界面上传
  1. 打开上述仓库页面，点击 Code → Download ZIP，得到 alibabacloud-aiops-skills-master.zip
  2. 在千问办公中点击左侧 扩展 → 技能，再点击页面右上角 + 添加
  3. 在弹出的安装技能窗口中拖入或选择该 zip 压缩包，点击 安装

千问办公 扩展 → 技能 → 右上角 + 添加，上传包含 SKILL.md 的 zip 压缩包

千问办公界面上传技能
上传窗口接受两种形式：包含 SKILL.md 的 zip 压缩包，或直接拖入单个 SKILL.md 文件。如果上传整仓 zip 后未识别到技能，把 skills/aiml/sfm/alibabacloud-bailian-rag-knowledgebase 目录单独压缩成 zip 再上传。

WorkBuddy

  1. 打开 aliyun/alibabacloud-aiops-skills，点击 Code → Download ZIP 并解压
  2. 取出 skills/aiml/sfm/alibabacloud-bailian-rag-knowledgebase 目录
  3. 在 WorkBuddy 的技能页面点击 + 添加技能，在下拉菜单中选择 上传技能
  4. 拖入或选择该目录完成导入

WorkBuddy 点击 + 添加技能，下拉菜单中选择 上传技能

WorkBuddy 添加技能入口

上传技能窗口：文件夹或 zip 均可，需包含 SKILL.md 文件

WorkBuddy 上传技能窗口

验证安装

Skill 安装后需重启客户端才会加载。重启后在对话中发送： 
列出我账号下的知识库
返回知识库名称列表即表示安装成功。

返回知识库 ID、名称与描述列表，右侧可见本次调用的技能

验证安装：列出知识库

功能及示例 Prompt

功能示例 Prompt
查看可用知识库列出我账号下的知识库
在指定知识库中检索在产品文档知识库中检索认证方式相关内容
自动选择知识库问答我们的产品支持哪些认证方式？先查知识库再回答
跨多个知识库检索在产品文档和客服问答两个知识库中检索退款政策
要求标注来源查一下差旅报销标准，并注明来自哪份文档的哪一节
限定只用检索结果作答查知识库回答这个问题，检索不到就说明无法确认，不要推测
未指定知识库时，Skill 会根据问题内容从知识库列表中选出 1 至 3 个最相关的库分别检索，合并结果后作答。

办公场景使用示例

撰写材料时引用公司口径

帮我写这周的项目周报。产品能力的描述先查知识库确认，不要凭印象撰写，
每条后面注明来自哪份文档。
Skill 会按周报涉及的能力点分别检索，用检索到的原文改写，并在段末标注来源。可避免材料中出现尚未发布的功能描述。

回复客户前确认能力范围

客户询问我们的知识库支持哪些数据源、能否接入语雀。先查知识库，
只依据检索到的内容回答，检索不到的部分直接说明无法确认。
其中限定只依据检索结果作答的要求较为关键，可避免生成看似合理但并不存在的答案。售前与客服场景建议固定加上该约束。

查询公司制度

出差住宿标准是多少？按公司报销制度回答，并给出制度文件名与条款位置。
制度类文档更新频繁。知识库完成增量同步后，客户端检索到的始终是最新版本，无需重新分发文件。

常见问题

现象原因处理方式
客户端提示无此技能，或提问后无响应安装后未重启客户端完全退出客户端后重新打开。仍无效时，确认技能目录下存在 SKILL.md 文件，且未嵌套多余的上级目录
返回 401 InvalidApiKey环境变量未生效，或使用了 sk-sp- 开头的 Key重新配置环境变量，确认为 sk- 开头，配置后重启客户端
返回 403 Forbidden 或提示服务未开通未开通知识库服务在知识库页面点击立即开通，等待一至两分钟后重试
能够回答但未标注来源提问时未提出要求在问题中补充要求注明来源文档
检索不到确实存在的内容文档仍在解析中，或提问用词与文档差异较大在控制台确认文档状态为解析完成，并调整提问用词。另可参考检索效果优化

进阶配置

以上为面向办公用户的标准安装方式。如需更灵活的部署方案，可参考本节内容。

使用 MCP 连接器

MCP 连接器不依赖本地 Python 环境，只需填写服务地址与鉴权头。千问办公在 扩展 → 连接器 → + 添加 中粘贴配置；WorkBuddy 写入 ~/.workbuddy/mcp.json，或通过 插件 → MCP 服务器 → 配置 MCP 进入。 
{
  "mcpServers": {
    "knowledge_studio": {
      "type": "streamable-http",
      "url": "https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/indices/rag/mcp",
      "headers": {
        "Authorization": "Bearer sk-xxxxxxxx"
      }
    }
  }
}
{workspaceId} 为控制台地址中的业务空间 ID，形如 llm-xxxxxxxx。type 的取值由客户端各自规定，千问办公为 streamable-http，Qoder 等编码类客户端为 streamableHttp，服务地址与鉴权头一致。提供的工具及参数见服务渠道。

千问办公 扩展 → 连接器 → + 添加，可选择手动填写配置或粘贴 JSON 配置

千问办公添加 MCP 连接器
WorkBuddy 官方 MCP 文档的示例以本地命令行服务为主，远程服务的字段名请以客户端配置页面的表单为准。连接失败时改用 Skill 方式。

批量安装到多台设备

先通过命令获取 Skill 包，再复制到客户端的技能目录： 
npx skills add aliyun/alibabacloud-aiops-skills \
  --skill alibabacloud-bailian-rag-knowledgebase \
  --agent claude-code -g -y --full-depth --copy

cp -R ~/.claude/skills/alibabacloud-bailian-rag-knowledgebase ~/.qwenworkcn/skills/
命令需带 --copy 参数。默认安装的是指向原位置的符号链接，复制到其他目录后会失效，客户端无法读取 Skill 内容。
WorkBuddy 的技能目录未在官方文档中公开，~/.workbuddy/skills/ 为社区约定路径，不同版本可能不适用。批量部署前请先在单台设备上验证，否则仍使用界面上传方式。

接入其他 Agent

控制台 应用集成 → 服务渠道 的 Agent Skill 区域提供各 Agent 对应的安装命令与技能目录，选择所用 Agent 即可获取可直接执行的命令。编码类客户端的完整清单与配置说明见快速配置到 Agent。

检索质量与访问范围

本文两种接入方式均按知识库 ID 直接检索，不会套用知识检索服务中配置的多库权重与排序策略。如需统一提升检索质量，在知识库侧调整切片方式与标签。如需限制客户端可访问的知识库范围，将这些知识库置于独立业务空间，并仅下发该空间的 API Key。仅在提问中限定范围不构成权限控制。
开始使用
Playground
数据接入
知识服务
Cookbook
应用集成
设置、计费与限制