1. 为什么要把 WorkBuddy 和腾讯乐享放在一起用

1.1 一个真实场景引出的需求

先说一个我自己的经历。团队里有个做售前支持的小组，日常最头疼的事情不是写方案，而是找资料。产品参数散在共享盘、历史投标文档躺在个人电脑、FAQ 靠老员工口口相传。新人入职第一周基本干不了活，全在问“这个文档在哪”“上次那个客户案例谁有”。后来我们上了腾讯乐享做企业知识库，文档总算有了统一入口，但新的问题又来了：知识库是“死”的，你得知道关键词才能搜到东西，搜出来的还经常是三五年前的旧版本。

WorkBuddy 这类 Agent 工作台的出现，恰好补上了这块短板。它能把知识库从“被动检索”变成“主动调用”——你不需要记住文档叫什么名字，只需要把问题描述清楚，Agent 自己去知识库里翻、去比对、去组织答案。腾讯乐享负责“存”，WorkBuddy 负责“用”，这个组合跑通之后，我们那个售前小组的新人上手周期从一周压缩到了两天。

这篇文章就是把这套组合拳的完整思路拆开讲清楚。不管你是想给团队搭一个能问答的知识库，还是自己在折腾 Agent 和 RAG 流水线，下面这些内容都能直接拿去参考。我会从整体设计思路讲到具体配置步骤，再到踩过的坑和排查方法，尽量做到看完就能动手。

1.2 核心概念先对齐：Agent、RAG、LLM Wiki 到底是什么关系

在动手之前，有几个概念必须先理清楚，不然配置的时候容易迷糊。

Agent（智能体）你可以理解成一个“会自己想办法的助手”。普通程序是你给它固定指令它执行，Agent 是你给它一个目标，它自己决定先做什么后做什么、调用哪些工具。WorkBuddy 就是这样一个 Agent 工作台，它本身不存知识，但它能连接各种知识源。

RAG（检索增强生成）是 Agent 用知识库的一种典型方式。简单说就是：用户提问 → 系统去知识库里检索相关片段 → 把片段和问题一起交给大模型 → 大模型基于这些片段组织答案。好处是答案有依据，不容易胡编。

LLM Wiki这个词最近很热，它强调的是“面向大模型的知识组织方式”。传统 Wiki 是给人看的，目录层级、超链接都是为人类阅读习惯设计的；LLM Wiki 是给模型看的，更强调内容的原子化、语义清晰、便于切片和检索。腾讯乐享本身是给人用的企业 Wiki，但我们可以通过一些处理手段，让它对 Agent 更友好。

这三者的关系可以这样理解：腾讯乐享是仓库，RAG 是取货的流程，WorkBuddy 是那个帮你取货并加工的人，而 LLM Wiki 的思路决定了你的仓库怎么摆货才最好取。

1.3 这套组合适合谁，不适合谁

适合的场景很明确：团队已经有或愿意建一个集中的文档库，日常有大量“查资料、找答案、整理信息”的需求，且这些需求重复度高、答案相对固定。比如售前支持、客服问答、内部 IT 帮助台、新人培训。

不太适合的场景也要说清楚：如果你的知识更新极其频繁（比如每天变好几次），或者答案需要大量实时外部数据，那这套组合只能解决一部分问题，还需要配合其他数据源。另外，如果团队里没人愿意维护知识库内容，那再好的工具也是白搭——垃圾进垃圾出，这个道理在 Agent 时代依然成立。

2. 整体架构设计与选型考量

2.1 为什么是腾讯乐享做知识源，而不是直接丢文件给 Agent

很多人第一反应是：我直接把一堆 PDF、Word 丢给 WorkBuddy 不就行了，为什么要多一层腾讯乐享？

我试过直接丢文件，问题很明显。第一，文件一多就乱，版本管理全靠文件名，方案_final_v3_真的最终版.docx这种命名谁都经历过。第二，权限没法控制，Agent 一检索可能把敏感文档的内容也带出来。第三，文件格式五花八门，解析质量参差不齐，扫描件 PDF 直接抓瞎。

腾讯乐享作为企业知识库，天然解决了这几个问题：它有结构化的目录、有版本历史、有权限体系、有全文检索。把乐享作为“唯一事实来源”，Agent 只从这里取数据，内容的可信度和可控性都高一个档次。而且乐享的文档大多是人工整理过的，质量比散落的原始文件高不少。

2.2 WorkBuddy 在链路中扮演什么角色

WorkBuddy 不是简单的“问答机器人”，它的价值在于编排。一个完整的问答链路可能包含好几步：理解用户意图 → 判断该查哪个知识库 → 检索 → 如果结果不够好就换个关键词再查 → 组织答案 → 必要时追问澄清。这些步骤的调度就是 Agent 的核心能力。

具体到和乐享的配合，WorkBuddy 主要做三件事。一是意图路由，用户问的是产品问题还是流程问题，分别去乐享里不同的空间找。二是检索策略控制，比如先做关键词检索，命中率低再走语义检索。三是答案组装，把检索到的多个片段去重、排序、拼成一段通顺的回答，而不是把原文一股脑贴出来。

2.3 数据流向与关键节点

整条链路的数据流向大致是这样的：

用户在 WorkBuddy 界面提问 → WorkBuddy 解析意图 → 调用乐享的检索接口 → 乐享返回相关文档片段 → WorkBuddy 对片段做重排和过滤 → 交给大模型生成答案 → 返回给用户并附上来源链接。

这里面有几个关键节点值得注意。检索接口的返回质量直接决定上限，如果乐享那边搜出来的东西就不对，后面再怎么加工也没用。片段重排是很多人忽略的一步，原始检索结果往往按相关度粗排，但 Agent 需要根据具体问题做二次排序。来源标注很重要，让用户能点回去看原文，既增加信任感，也方便纠错。

2.4 选型对比：几种常见方案的取舍

如果团队没有专门的算法工程师，WorkBuddy 这种开箱即用的 Agent 工作台是性价比最高的选择。自建 RAG 流水线虽然灵活，但光是文档解析、切片策略、向量库选型这几件事就够折腾好几周，而且效果未必比成熟产品好。

3. 知识库侧的准备工作：让乐享对 Agent 更友好

3.1 文档结构怎么整理才利于检索

这是整套方案里最容易被低估、但影响最大的一环。我见过太多团队知识库建得跟杂物间一样，Agent 再聪明也救不回来。

核心原则是一个文档只讲一件事。不要把产品介绍、报价、售后政策全塞进一个文档里。理想状态下，每个文档对应一个明确的问答场景。比如“XX产品标准版报价”单独成文，“XX产品售后响应时效”单独成文。这样检索的时候命中精度高，片段也干净。

目录层级不要太深，建议控制在三层以内。太深的层级会让检索路径变长，而且很多检索工具对深层文档的权重处理并不理想。如果内容确实多，宁可多加几个一级目录，也不要一层套一层。

3.2 标题和摘要的写法直接影响命中率

Agent 检索时，标题和摘要的权重通常很高。所以标题不要写“文档1”“通知”这种无意义的名字，要写清楚内容。比如“2024年Q3产品价格调整说明”就比“价格通知”好得多。

摘要这块，乐享支持给文档写简介，一定要写。摘要里把核心关键词自然放进去，相当于给检索系统多一个抓手。我一般建议摘要控制在 100 字以内，包含“是什么、解决什么问题、关键参数”三要素。

3.3 内容切片的粒度控制

RAG 检索的基本单位是“片段”，片段切得好不好直接决定答案质量。切太大，检索出来的内容冗余，模型容易被无关信息干扰；切太小，上下文丢失，答案不完整。

我的经验是，按语义段落切，而不是按固定字数切。一个完整的操作步骤、一个独立的产品特性说明，就是一个自然的切片单元。乐享的文档如果本身结构清晰（用了标题、列表、表格），切片质量会好很多。所以前面强调的文档结构整理，在这里就体现出价值了。

如果文档里有大量表格，建议把表格转成“字段：值”的列表形式，或者至少保证表头清晰。很多解析工具对复杂表格的处理都不太理想，转成列表能显著提升检索效果。

3.4 权限与安全边界设置

Agent 能访问的内容范围必须提前划定。在乐享里，可以通过空间权限和文档权限两层来控制。建议给 WorkBuddy 单独建一个访问账号，只授予它需要的那部分知识库的读取权限。

敏感内容（比如合同模板、客户名单、内部财务数据）坚决不要放进 Agent 可访问的范围。这不是不信任工具，而是最小权限原则的基本要求。万一 Agent 被诱导问出敏感信息，权限边界就是最后一道防线。

提示：定期审查 Agent 账号的权限，人员变动或知识库结构调整后及时更新，避免权限残留。

4. WorkBuddy 侧的配置与编排实操

4.1 接入乐享知识源的具体步骤

WorkBuddy 连接外部知识源一般通过 API 或连接器的方式。腾讯乐享提供了开放接口，可以在 WorkBuddy 的知识源配置里填入对应的接口地址和鉴权信息。

具体操作路径大致是：进入 WorkBuddy 的知识库管理 → 添加知识源 → 选择“腾讯乐享”或“自定义 API” → 填入乐享的接口地址、AppID、AppSecret → 测试连接 → 选择要同步的空间和文档范围 → 设置同步频率。

同步频率这块，如果知识库更新不频繁，每天同步一次就够；如果更新频繁，可以设置成每小时。但要注意，频繁同步会消耗接口调用额度，也可能造成检索时的数据不一致（同步到一半的状态）。建议在业务低峰期做全量同步，日常用增量同步。

4.2 检索策略的参数调优

WorkBuddy 里和检索相关的参数主要有几个：返回片段数量（top_k）、相似度阈值、是否开启重排。

top_k不是越大越好。返回太多片段，模型处理负担重，还容易引入噪声。一般从 5 开始试，根据效果调整。如果发现答案经常缺信息，可以加到 8 或 10；如果答案经常跑题，就降到 3 或 4。

相似度阈值决定了“多不相关才算不相关”。设太高，可能什么都搜不到；设太低，一堆无关内容涌进来。建议先设一个中间值（比如 0.7 左右，具体看平台的定义），然后根据实际问答效果微调。

重排功能如果平台支持，建议开启。它会在初步检索之后，用更精细的模型对结果重新排序，通常能明显提升前几条的准确率。

4.3 给 WorkBuddy 定规则：让 Agent 行为可控

WorkBuddy 支持给 Agent 设定系统提示词或行为规则，这是让它“听话”的关键。我一般会定这么几条规则：

• 回答必须基于检索到的知识库内容，检索不到就明确说“知识库中没有相关信息”，不要自己编。
• 回答末尾附上引用的文档标题和链接。
• 如果用户问题模糊，先追问澄清再检索。
• 涉及价格、政策等敏感信息时，只引用知识库原文，不做推断和延伸。

这些规则看起来简单，但能极大减少 Agent 胡说的概率。尤其是第一条和第四条，是保证答案可信度的底线。

4.4 多轮对话与上下文管理

Agent 和普通搜索的一个大区别是支持多轮对话。用户可以先问“XX产品有哪些版本”，再问“标准版多少钱”，Agent 要能理解“标准版”指的是上一轮提到的产品。

这依赖上下文管理。WorkBuddy 一般会自动维护对话历史，但要注意历史太长会稀释当前问题的权重。建议设置一个合理的上下文窗口，比如保留最近 5 轮对话。如果对话很长，可以考虑做摘要压缩，把早期对话浓缩成一句话保留。

另外，多轮对话里容易出现指代消解问题。用户说“它”“那个”“上面说的”，Agent 要能正确对应到之前的实体。这个在配置时可以加一条规则，让 Agent 在不确定指代对象时主动确认。

5. 常见问题与排查技巧实录

5.1 检索不到内容怎么办

这是最高频的问题。排查顺序建议从下往上：先确认文档在不在乐享里、权限对不对，再确认同步有没有成功，最后看检索参数。

我遇到过好几次是权限问题——文档明明在，但 Agent 账号没权限，检索结果就是空的。还有一次是同步任务失败了但没告警，知识库停留在三天前的状态。所以同步日志一定要看，最好设置失败告警。

如果权限和同步都没问题，那就是检索策略的事。试试换个关键词，或者调低相似度阈值。有时候是用户问法和文档写法差异太大，比如用户问“怎么退款”，文档写的是“售后处理流程”，这种语义鸿沟需要靠语义检索或同义词配置来弥补。

5.2 答案不准确或答非所问

答案不准，八成是检索环节出了问题。先看检索出来的片段是不是相关的，如果不相关，问题在检索；如果相关但答案还是错，问题在生成环节。

检索不相关，可能是切片粒度不对，或者文档本身内容就乱。生成环节出错，通常是提示词没写好，模型自由发挥太多。这时候把规则收紧，强调“只基于给定内容回答”，通常能改善。

还有一种情况是知识库里有多个版本的文档，检索时把旧版本也搜出来了，模型综合了新旧信息给出矛盾答案。解决办法是做好版本管理，旧文档及时归档或标注失效。

5.3 响应速度慢的优化思路

Agent 问答比普通搜索慢是正常的，因为多了模型生成这一步。但如果慢到影响使用，就要优化了。

主要瓶颈通常在检索和生成两处。检索慢可能是知识库太大、索引没建好，或者同步任务占用了资源。生成慢可能是模型选得太大，或者返回的片段太多导致输入过长。可以试试换更轻量的模型，或者减少 top_k。

还有一个容易被忽略的点是网络链路。如果 WorkBuddy 和乐享不在同一网络环境，每次调用都要走公网，延迟会明显增加。条件允许的话，尽量让它们在同一内网环境。

5.4 常见问题速查表

5.5 几个我踩过的坑

第一个坑是过度依赖自动同步。有次乐享里更新了重要文档，但同步任务因为接口限流失败了，Agent 还在用旧内容回答，差点造成误导。后来我加了一个手动触发同步的按钮，重要更新后手动同步一次，心里踏实。

第二个坑是提示词写得太宽松。早期我写的规则是“尽量基于知识库回答”，结果模型经常“尽量”之外自己发挥。改成“必须基于知识库，无相关内容时明确告知”之后，胡说的情况少了很多。提示词里的措辞，差一个字效果可能差很多。

第三个坑是忽略了文档里的表格。有份产品对比文档全是表格，检索出来的片段是一堆错位的文字，模型根本读不懂。后来把表格转成了列表，问题解决。所以文档格式对 Agent 的友好度，真的需要专门考虑。

6. 效果验证与持续迭代

6.1 怎么判断这套组合有没有跑通

别只看“能不能回答”，要看回答得对不对、全不全、有没有依据。我一般用一组固定问题做回归测试，每次调整配置后跑一遍，对比答案质量。

测试问题要覆盖几类：直接能从文档找到答案的、需要综合多个文档的、知识库里没有的（看它会不会老实说不知道）、以及容易混淆的（看它能不能区分相似概念）。这四类都表现正常，才算基本跑通。

6.2 收集反馈持续优化知识库

Agent 的问答日志是金矿。定期看用户都问了什么、哪些问题回答得不好，反过来指导知识库的补充和优化。很多团队知识库建完就不管了，这是最大的浪费。

我习惯每周抽半小时看一遍问答记录，把高频问题和差评问题记下来，该补文档补文档，该改写法改写法。坚持一个月，问答准确率会有肉眼可见的提升。

6.3 后续可以扩展的方向

跑通基础问答之后，可以往几个方向扩展。一是接入更多知识源，比如把工单系统、CRM 里的数据也接进来，让 Agent 能回答更个性化的问题。二是做主动推送，不等用户问，Agent 根据场景主动提示相关信息。三是和业务流程打通，比如 Agent 回答完问题后直接生成工单或触发后续动作。

不过扩展之前，先把基础问答做扎实。我见过太多团队一上来就想搞大而全，结果基础检索都没做好，后面全是空中楼阁。

提示：每次扩展新知识源或新功能后，都要重新跑一遍回归测试，确保没有破坏原有能力。

这套 WorkBuddy 加腾讯乐享的组合，说到底解决的是“知识找得到、用得上”这个老问题。工具在变，但底层逻辑没变：内容要整理好，权限要管住，效果要持续盯。把这三点做到位，Agent 才能真正成为团队的生产力，而不是一个花架子。