升级版扣子助手能力拆解

项目概览

扣子助手是一款采用对话流模式搭建的智能客服产品 ，所有用户 Query（提问）统一交由智能体绑定的对话流处理。其核心功能包括知识检索、问答、知识库管理、会话管理、用户反馈等。
为了提升产品性能，满足用户日益增长的需求，在编排、效果与用户满意度等方面进行优化，我们对扣子开平台右下角的扣子助手进行了全方位升级。
相比旧版，升级版扣子助手具备以下优势：

• 编排更简洁：包括开始、结束、子工作流在内，共计 8 个节点，均为常用的高频节点。
• 效果更优秀：经由扣子罗盘评测，问答准确性提高 2 倍，准召率90%以上。
• 满意度更高：通过赞踩功能收集用户反馈，满意度相对于旧版大幅大幅提升。

解决方案

扣子助手智能体采用对话流模式搭建，所有用户 Query 统一交由智能体绑定的对话流处理。

• 知识检索：升级版扣子助手采用多路检索方案，综合火山方舟知识库和 llms.txt 协议，结合豆包模型的深度思考能力，大幅提升知识检索的准确性。
• 智能问答：对话流接收用户 Query 之后，大模型会调用知识库检索，并综合分析检索结果，生成回复。
• 反馈处理：扣子 API 和 Chat SDK 支持用户针对某个对话提交反馈，开发者可通过扣子罗盘获取反馈内容，定向优化助手问答能力。

升级版扣子助手已沉淀为扣子官方模板，向扣子用户全方位开放扣子官方智能客服的全新实践方案，开发者可以快速复制模板，并将其改造为适合自己业务场景的智能客服。详细信息可参考如何复刻扣子助手。

对话流设计

扣子助手的核心能力是智能问答，我们需要用户的每个提问都默认检索知识库，以提高答案的准确性，所以选取了对话流模式的智能体来实现，其中智能问答部分由对话流完成。
扣子助手的对话流核心流程如下：

1. 改写问题：综合对话上下文，将用户提问改写为一个完整的问题，便于模型理解用户问题，同样可以提高知识库检索的准确性。例如用户第一轮提问“什么是工作流”，第二轮提问“怎么用呢”，此时第二轮问题会被改写为“如何使用工作流”，便于后续流程处理。
2. 检索知识库：使用改写后的用户问题去检索知识库，获取到相关性最高的内容切片。知识库环节依赖火山方舟知识库和 llms.txt 协议的技术文档内容，双管齐下提升检索效果。
   • 方舟知识库：通过一个子工作流节点实现。先调用火山知识库插件获取相关切片，再通过代码节点将返回的切片信息格式化，添加文档链接。
   • llms.txt 协议：通过读取链接插件来读取准备好的 llms.txt 文件内容，其中包含扣子文档中心的完整目录结构，便于大模型按需查看并递归读取。
3. 模型思考并生成回复：将知识库检索结果提供给大模型，大模型基于现有的信息进行深度思考，并自主规划、调用工具，最终生成完整的问题回复。

工作流整体编排如下：

子工作流编排如下：

1 改写问题：多轮对话

Query 改写（Query Rewriting）是信息检索流程中一个非常重要的环节，它直接影响着搜索结果质量和相关性。在扣子助手中，问题改写环节由对话流大模型节点完成。
我们可以通过系统提示词赋予大模型一个问题改写专家的人设，并为其开启多轮会话的能力。每次对话过程中，大模型除用户问题以外，还会获取到前几轮对话的用户问题，便于模型理解本次对话的上下文和语境，从而将本次用户问题改写为模型更容易理解的表述，也会使知识库检索的精确度更高。

2 检索知识：网页+知识库

作为一个商业化的开发者产品，我们希望扣子助手的知识完全精准且可靠，每一轮的问题回复都应主动检索知识库，从可靠的知识范围内查找相关性最高的回复，而不是采用互联网上未经考证的知识数据。所以，扣子助手的私域知识由扣子文档中心提供，检索方式采用以下两种：

• RAG：采用火山方舟知识库，相较于扣子知识库的性能更强、检索速度和准确性更高，适合企业级知识库检索场景。
• LLMs.txt 协议：为扣子文档中心实现 llms.txt 协议，配合豆包 1.6 深度思考模型的能力，智能体可以递归地从 llms.txt 文件中找到符合要求的文档内容。

通过火山方舟知识库实现 RAG

RAG （Retrieval-Augmented Generation 检索增强生成）技术被广泛应用于问答类型的智能体搭建中。RAG 指的是在回答问题或生成文本时，先从大规模文档库中检索相关信息，然后利用这些检索到的信息来生成响应或文本，从而提高回复内容的质量。 RAG 技术的应用可以很好地解决大模型专业知识不足的问题，让大模型在回答用户问题前先参考知识库中的相关内容，可极大抑制大模型的幻觉现象。
扣子的知识库能力由火山方舟知识库提供，我们可以通过方舟知识库实现 RAG。方舟知识库支持百亿级向量检索规模，可广泛应用于智能问答、智能搜索、推荐系统和数据去重等领域。
将扣子产品文档导出为离线文件，并上传至火山方舟知识库即可。除了上传离线文件之外，方舟知识库还提供多种数据导入和更新的方式，开发者可以根据自己的知识载体类型灵活选择，例如传入网页 URL、将离线文件上传至 TOS 再导入方舟知识库、通过 API 上传离线文件等等。

通过 LLMs.txt 协议读取网页

除了 RAG 以外，我们还希望大模型在回答用户问题之前先主动从在线文档中心搜索答案，以增强知识检索环节的内容丰富性。但是扣子文档中心是网页形式，大模型在处理网站信息时面临上下文窗口的限制，并且将 HTML 页面内容转为模型已读的文本时，也容易丢失关键信息。
使用 LLMs.txt 协议可以很好地解决这个问题。LLMs.txt 协议是一个致力于推动 /llms.txt 文件标准化的提案，为大模型提供更高效、精准的网站内容访问方式。当然，LLMs.txt 协议只是配合火山方舟知识库 RAG 的附加方案，可以在一定程度上提升问答能力。
在扣子助手方案中，我们为扣子实现了 llms.txt 协议，并整理了文件 https://www.coze.cn/llms.txt。该 llms.txt 将扣子的文档大纲与对应文档链接列举了出来，结合豆包 1.6 模型的深度思考与插件能力，智能体可以递归地从 llms.txt 找到符合要求的内容。
例如对小助手提问“介绍一下消息评价”。小助手会首先利用工具读取 https://www.coze.cn/llms.txt，然后从读取到的大纲内容中，发现有关消息评价的链接地址 https://www.coze.cn/api/open/docs/dev_how_to_guides/message_feedback，接着进一步读取有关消息评价的信息，最后总结输出。
需要注意的是，此方案需要编写代码，要求开发者具备一定的代码基础，开发者可以按需选择。

3 生成回复：豆包深度思考模型

检索知识库、获取信息之后，还需要由大模型来理解这些信息，并将其整理为用户可理解的答案回复。我们选择豆包 1.6 深度思考模型来完成生成回复这一步骤。
豆包 1.6 深度思考模型具备深度思考能力、复杂问题处理能力强，且具备多模态能力，可以识别和理解文档中的图片信息，同时具备出色的上下文理解能力，可支持上下文关联对话，能够根据之前的对话内容准确理解用户意图。此外，豆包 1.6 深度思考模型还具备递归读取链接的能力，大模型可以按需读取llms.txt 文件，并自主思考规划，主动查看目录中的文档内容，获取和用户问题相关的关键信息，用于生成更高质量的回复。
需要注意的是，在生成回复的模型节点，除了上游知识库节点的输入信息，我们还为模型配置了两个工具：

• 链接读取插件：用于输入准备好的 llms.txt 文件。
• 检索知识库工作流：用于检索火山方舟知识库。

这样做的好处是，如果大模型判断前置节点获取的信息量不足，可以自主规划，再次调用这两个工具获得更丰富的信息。

4 反馈处理

智能客服发布上线之后，还需要通过用户反馈的能力来收集反馈意见，例如用户对于不准确的答案可以点踩，以便开发者定向调优。在之前的扣子智能客服方案中，此流程通过多维表格的字段捷径实现，AI 分析问题类型和问答效果。
经过一段时间的功能迭代，扣子现已支持收集 API 和 SDK 渠道的智能体反馈。扣子助手发布到 Chat SDK 之后，每一轮对话用户都可以点赞或者点踩，开发者通过扣子罗盘查看赞踩数据，筛选出点踩的问答记录定向分析与调优。详细说明可以参考消息评价。

如何复刻扣子助手

你可以快速复制扣子助手模板，并将其改造为专属于自己业务的智能客服。

模板下载

准备工作

• 收集产品资料。收集各种形式的产品资料，以便后续流程中上传知识库，作为智能客服的知识来源。产品资料可以是在线文档中心地址（例如扣子文档中心），也可以是离线文件（例如 word 文档）。
• 获取火山引擎账号密钥，获取方式可查看获取火山密钥。

步骤一：搭建火山知识库

搭建智能客服的第一步是准备知识库。在扣子助手方案中，我们使用火山知识库来实现 RAG，第一步是创建火山知识库，并将收集到的产品资料上传至知识库中。
通过 API 上传产品资料时，我们需要将文档中心链接作为元数据上传至知识库，利用火山知识库插件检索与召回，这样知识库插件能获取元数据信息（文档中心链接），模型回复可附链接方便用户查看详情。

1.1 创建火山知识库

1. 在火山引擎知识库控制台，单击创建知识库。
2. 在创建知识库页面的基本信息区域，完成如下配置。
   具体参数配置说明，请参考创建知识库。 在智能客服场景中，你可以参考以下配置：
   • 数据类型：非结构化数据。产品资料通常是 word、markdown、pdf 等文件格式，属于非结构化数据。
   • 标签：为了便于模型获得检索结果对应的文档链接，我们需要为知识库定义一个 doc_url 的标签，格式为 string，后续上传文件时为文档添加对应链接标签， 例如“扣子品牌升级”这篇文档对应的标签为 “doc_url=https://www.coze.cn/open/docs/guides/new_coze_brand”。
   • 文本向量化模型等其他配置：可采用默认配置。
     
3. 设置完成后，单击创建知识库。
   创建完成后，需要记录知识库的名称，后续插件节点中会用到。

1.2 上传产品资料到知识库

此步骤中，我们将准备好的产品资料上传到火山方舟知识库。支持的上传方式如下：

• 控制台上传：需要手动上传并手动打标。根据你的产品资料类型和所在位置，选择合适的上传方式即可。操作步骤可参考导入文档和添加标签。

• API 上传：通过 API 可以批量上传文档，并将文档中心链接作为标签一同上传至知识库，后续检索时可以通过火山知识库插件获取标签信息（文档中心链接）。

以上传扣子产品介绍文档为例，调用 /api/knowledge/doc/add API 向已创建的知识库添加文档，并添加元数据（meta）。

curl -X 'POST' 'https://api-knowledgebase.mlp.cn-beijing.volces.com/api/knowledge/doc/add' \
-H 'Accept: application/json' \
-H 'Authorization: HMAC-SHA256 Credential=AKLTNDc5ZmVlZDVmMTIzNDM1NzgzZTUx****/20250916/cn-north-1/air/request, SignedHeaders=content-type;host;x-content-sha256;x-date, Signature=f8ce45d4eb91cbcaeb43cda55ce0a83a1bfb72********' \
-H 'Content-Type: application/json' \
-H 'Host: api-knowledgebase.mlp.cn-beijing.volces.com' \
-H 'X-Content-Sha256: 35ee23d393f1d075f9953bb0056cd00a41df4d648badbaa53b96043636****' \
-H 'X-Date: 20250916T122420Z' 
-d '{
  "resource_id": "kb-d6d0d0f6641e****",
  "add_type": "url",
  "doc_id": "_65869b19fbcd1403077de2c6_67f4defd342188054c13****",
  "doc_name": "扣子品牌升级",
  "doc_type": "markdown",
  "url": "https://www.coze.cn/api/open/docs/guides/new_coze_brand",
  "meta": [
    {
      "field_name": "doc_url",
      "field_type": "string",
      "field_value": "https://www.coze.cn/open/docs/guides/new_coze_brand"
    },
    {
      "field_name": "doc_llms_url",
      "field_type": "string",
      "field_value": "https://www.coze.cn/api/open/docs/guides/new_coze_brand"
    }
  ]
}
'

步骤二：（可选）实现 llms.txt 协议

llms.txt 是为了利用豆包 1.6 模型的深度思考能力，使模型在自主规划的过程中按需递归查看文档内容，获取到更丰富的信息，可以作为知识库 RAG 方案的补充。
关于此协议的详细信息及实现方式，可参考 https://llmstxt.org/，若有需要，开发者应自行实现相关的逻辑。制作 llms.txt 并上传到网站根目录中，通常需要编写代码来处理 Markdown 格式的文件，实现 llms.txt 协议，这要求开发者具备一定的技术背景。
在扣子助手方案中，我们为扣子实现了 llms.txt 协议，具体步骤如下：

1. 生成 llms.txt 文件：llms.txt 文件内容是文档中心的完整目录结构，格式为 markdown，便于模型理解文档中心的目录结构，可以递归查看文档内容。你可以参考扣子的 llms.txt 来准备 llms.txt 文件。
2. 生成多个离线文件：通过代码将扣子文档所有内容转为 markdown 格式，每一篇文档保存为一个文件，和官网文档中心的文档页面一一对应，llms.txt 中的目录结构一一对应。例如扣子文档页面什么是扣子。
3. 将生成的文件上传至扣子文档中心的根目录中，以便大模型调用插件工具来阅读查看。

步骤三：复制并修改模板配置

完成知识库内容准备后，就可以复制模板进行智能体搭建了。

1. 下载扣子助手工作流模板。
2. 将模板导入到你的工作空间。
3. 创建一个智能体，设置智能体名称和头像。
4. 根据实际需求，设置开场白文案和预置问题。
   

3.2 修改子工作流

子工作流名为 coze_knowledge_template，用于根据关键词检索火山知识库，并经由代码节点处理返回的切片数据，附上切片对应的文档链接。此步骤中你需要为子工作流重新设置名称与描述，并将知识库和火山密钥替换为你自己的信息。

1. （可选）修改子工作流名称与描述。
   在资源库中找到名为 coze_knowledge_template 的工作流，为其修改一个新的名称、设置新的描述信息。
2. 打开工作流，修改插件节点的输入变量配置。
   • ak：输入你的火山引擎账号 AK。
   • sk：输入你的火山引擎账号 SK。
   • collection_name：输入已创建的火山知识库名称。
3. 发布子工作流。
   

3.3 修改主工作流

主工作流名为 coze_assist_template，你需要修改名称及描述，并替换工作流中的各项节点配置，将其改造为适合自己业务场景的工作流。

1. （可选）修改工作流名称。
   在资源库中找到名为 coze_assist_template 的工作流，为其修改一个新的名称。

2. 打开工作流，修改以下节点配置。

   节点名称与类型	修改说明	示例
   查询在线文档（插件节点）	将输入变量中的 url 变量值改为你的官网文档中心地址。
   生成回复（大模型节点）	技能：确认已添加技能中包括检索火山知识库的子工作流、链接读取插件。 输入：无需修改，维持原配置即可。 系统提示词：替换其中的关键信息，例如将“扣子小助手”相关的文案替换为适合自己业务场景的文案。

3. 单击试运行测试工作流，输入一个产品问题，工作流测试通过后，再单击发布。

步骤四：发布智能体

如果不需要赞踩功能，你可以将智能体发布到飞书等任意渠道，让对应渠道的用户可以使用并体验这个智能客服。
如果你也需要实现扣子助手的赞踩功能，可以将智能体发布为 Chat SDK，并集成到你的自建网站中。用户唤醒小助手并完成问答交互后，可以点击赞踩图标，提交满意度反馈。

3.1 发布为 Chat SDK

1. 在智能体编排页面右上角单击发布。
2. 选择 Chat SDK 渠道，并单击发布。
   未发布为 Chat SDK 的智能体，使用 Chat SDK 时会报错，提示：智能体已经被解绑。
   
3. 确认审核通过。
   你可以在发布历史页面查看每次发布的审核结果，审核通过后才能执行后续操作安装 Chat SDK。

3.2 集成 Chat SDK

成功发布 Chat SDK 之后，你可以在本地项目中通过 script 标签的形式加载 Chat SDK 的 js 代码。
开发者可以在 WebChatClient 方法的 ui.chatBot 参数中，配置是否允许用户对智能体的回答进行评价（点赞 / 点踩）。详细参数说明参见安装并使用 Chat SDK。
开启消息评价的示例代码如下：

ui: { 
    chatBot: { 
        // 基础UI配置 
        title: "智能助手", 
         
        // 消息评价功能配置（独立模块） 
        feedback: { 
            isNeedFeedback: true,  // 是否启用反馈功能 
            feedbackPanel: {       // 反馈面板详细配置 
                title: '您对这个回答有什么看法？请告诉我们', 
                placeholder: '请详细描述您的问题...', 
                tags: [             // 反馈标签选项 
                    { 
                        label: '信息不正确' 
                    }, 
                    { 
                        label: '涉及敏感信息', 
                        isNeedDetail: true  // 选择此标签时需要填写详细说明 
                    }, 
                    { 
                        label: '回答不完整' 
                    }, 
                    { 
                        label: '其他问题', 
                        isNeedDetail: true  // 选择此标签时需要填写详细说明 
                    } 
                ] 
            } 
        } 
    } 
} 

通过上述代码，开发者可以轻松地在 App 中启用消息评价功能，用户可直接在智能体或扣子应用回复的消息下方操作点赞 / 点踩。消息评价的界面效果类似如下图所示。

步骤五：日志分析

对于发布到 Chat SDK 的智能体，如果用户单击了赞踩图标提交反馈，开发者可以通过扣子罗盘筛选赞踩对话，定向优化智能体问答效果。
开发者可以在扣子罗盘中根据 Feedback-Coze 对话 字段筛选消息的评价数据，以便快速收集和分析用户意见。通过对点踩的数据进行分析，开发者可以了解智能体回复的质量，并针对性地优化算法、调整知识库内容或改进对话逻辑。仅智能体或扣子应用的所有者和协作者可以查看消息评价数据。

1. 在扣子罗盘左侧导航栏选择观测 > Trace，在 Trace 列表中选择某条消息，或通过过滤器筛选消息评价的数据。查看方式选择 All Span，数据来源选择 Coze 智能体或 Coze 应用，过滤字段设置为 Feedback-Coze 对话属于点赞或点踩。
   
2. 在 Trace 详情页面的调用树中单击 Message 节点，在右侧查看该消息的反馈结果和标签。
   

经验沉淀

为什么使用火山知识库插件，而不是知识库节点

我们通过 API 方式上传产品资料到火山知识库，并在将产品资料对应的文档中心链接作为元数据一并上传到知识库中，并使用火山知识库插件实现知识库的检索与召回，本质上是直接调用火山知识库检索的 API。这样做的好处是，知识库插件可以获取到知识库文档的元数据信息，也就是文档资料对应的文档中心链接，这些信息会传递给模型，模型在回复中可以附上链接，便于用户查看详细内容。

为什么要专门制作一个子工作流

火山知识库插件召回的信息中包含切片内容和元数据信息，我们需要通过代码节点将这两个关键信息从插件输出中提取出来，并拼接为指定的格式，便于模型阅读和理解。
大模型节点中需要配置火山知识库，让豆包模型自主规划、深度思考，自行调用知识库获取信息，然而我们还需要代码节点来格式化知识库切片，这种场景下必须通过子工作流的形式为大模型配置技能。

为什么要重复添加知识库

在新版小助手中，我们使用了两次知识库节点：

• 大模型节点之前：默认通过用户 Query 去检索知识库、为模型节点提供 llms.txt 的输入。
• 大模型节点中：让模型自主规划，判断是否调用知识库。

这是因为大模型节点之前的知识库获取的信息有可能是不完善的，我们希望模型自主判断信息是否重置，并且可以在信息不足的情况下主动检索知识库、查看 llms.txt 文件，获取更丰富的信息，所以不仅在开始节点中默认检索知识库，也同时在模型节点中添加了知识库工作流和链接读取插件（用于读取 llms.txt 文件）。

功能拓展

扣子助手模板仍在持续优化中，未来将支持转接人工坐席等功能，你也可以根据业务需求为其添加更多拓展能力。

Trace 标注

扣子罗盘提供了人工 Trace 标注和 Trace 自动回流的能力。智能客服发布上线之后，开发者可以在扣子罗盘的 Trace 页面查看线上的每一条问答记录，其中包括智能体的输入输出、每个处理节点的输出输出内容、时长等数据。针对这些 Trace 数据，开发者还可以手动添加标记，例如对用户问题进行分类、提取 Trace 并回流到评测集，以供后续新版本智能体评测等等，详细说明可参考人工标注 Trace。