Cherry Studio 知识库工具指南用 kb_list / kb_search / kb_read / kb_manage 实现私有文档问答与知识库维护【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio本指南围绕 Cherry Studio 内置cherry-toolsMCP 服务暴露的四个知识库工具mcp__cherry-tools__kb_list、kb_search、kb_read、kb_manage展开讲解 Agent 如何从用户自有文档中检索并引用答案、如何安全地对知识库执行增删与重建索引等变更操作。读完本文你将掌握知识库工具的条件可用性判定、标准读取链路、审批门控的变更流程以及出错时的恢复策略并能结合 Cherry Studio 源码理解这些工具背后的混合检索、Concept ID 寻址与作用域隔离机制。工具全景四个 kb_* 工具各自的职责知识库工具由 Cherry Studio 内置的进程内 MCP 服务器承载定义于 cherryKnowledgeTools.ts通过mcp__cherry-tools__*前缀注入到 Agent 会话中。四个工具覆盖读与写两个方向工具方向职责mcp__cherry-tools__kb_list读枚举当前作用域内的知识库或展开单个知识库查看其文档列表与文档 ID含组织树浏览mcp__cherry-tools__kb_search读在作用域内的知识库上执行语义/混合检索返回命中片段mcp__cherry-tools__kb_read读读取指定文档内容或对文档内容执行正则 grep两种模式由参数pattern路由mcp__cherry-tools__kb_manage写变更知识库内容新增、删除、重建索引re-index审批门控且删除是破坏性操作原文档明确指出本指南只负责路由、编排顺序与安全边界不重述参数形状——每个工具精确的参数名、枚举与必填字段应以会话中实时暴露的 live tool schema 为权威来源。在调用前务必先读取该工具的 schema。条件可用性kb_* 工具何时出现、何时消失四个kb_*工具并非总是可用它们只在 Agent 拥有作用域内知识库时出现作用域来源有二Agent 静态绑定的知识库binding或用户在本轮对话中通过 Composer 选择的知识库从源码结构看作用域被建模为显式的KnowledgeScope类型none/unrestricted/restricted见 cherryKnowledgeTools.ts。之所以不直接用裸 ID 数组是因为共享检索核心把空数组解释为允许全部知识库只有unrestricted变体才允许向下传递空列表——这样可以保证空作用域永远不会被静默重解释为所有知识库工具列表与每次调用都会重新推导作用域resolveKnowledgeScope未授权调用会被拒绝fail-closed。注意Composer 选择在连接建立时即被冻结修改它需要重建连接而非重新列出工具。判定规则如果会话的实时工具列表中没有kb_*说明本会话没有任何文档作用域——此时应向用户说明并引导其绑定或选择一个知识库而不是转而使用 Web 搜索并暗示答案来自用户的文档。工具缺失不代表可以绕路这一点与 SKILL.md 中的全局规则一致能力不可用时如实说明并停止绝不假装调用成功或编造结果。读取工作流kb_list → kb_search → kb_read当答案应该来自用户自有文档时Agent 应留在知识库工具内部不要用 Web 搜索替代。标准顺序kb_list枚举作用域内的知识库或传入baseId展开单个知识库查看其文档与其 ID源码中对应listOrOutlineKnowledge的两种模式见 cherryKnowledgeTools.tskb_search在作用域内的知识库上做检索拿到回答问题的片段kb_read检索定位到具体文档后读取该文档或对其执行pattern正则 grep。回答时必须附上引用的文档来源citation。源码支撑混合检索、Top-K 截断与相关性阈值读取链路的底层实现在 KnowledgeQueryService.ts。search()的核心行为可以归纳为以下几点模式选择知识库一旦完成向量索引即为hybrid向量 BM25否则退化为bm25纯词法。该模式在每次调用时重新计算不会与知识库状态漂移KnowledgeQueryService.ts候选过取以topK的 5 倍常量KNOWLEDGE_SEARCH_OVERFETCH_FACTOR 5过取候选硬上限 200 条KNOWLEDGE_SEARCH_CANDIDATE_CAP目的是在可见性过滤缺失、跨库、未完成项会被丢弃之后仍能保证最终结果数量达到 topK重排与截断重排发生在截断之前重排器能看到完整的过取候选集无重排模型时该步骤为直通pass-through相关性阈值最终结果会应用知识库自身的threshold相关性阈值过滤再输出排名。知识库的索引与存储架构见 features/knowledge/README.md每个知识库一个index.sqlitebetter-sqlite3 sqlite-vec持久化分块 嵌入后的文本服务于混合检索与 Concept ID 寻址。源码支撑kb_read 的两种模式与防失控设计kb_read的读取/grep 两种模式实现在 KnowledgeConceptService.tsreadConcept按 Concept ID即物料的相对路径OKF §2读取文档支持[charStart, charEnd)切片。单次返回被硬限制在CONCEPT_READ_MAX_CHARS 20000字符避免超大文档淹没 Agent 上下文返回的totalChars与truncated字段让调用方可以分页继续读取grepConcept对文档索引文本执行全局、默认忽略大小写的正则匹配。默认返回最多CONCEPT_GREP_DEFAULT_MAX_MATCHES 50条匹配硬上限CONCEPT_GREP_MAX_MATCHES 200每条匹配附带 1 起始行号、文档绝对偏移和前后各CONCEPT_GREP_SNIPPET_PAD 60字符的片段。为防灾难性回溯如(a)$冻结主进程事件循环正则逐行执行、单行上限CONCEPT_GREP_MAX_LINE_CHARS 2000字符锚点^/$因而按行绑定匹配不能跨行。变更工作流kb_manage 的审批与 ID 纪律kb_manage会变更知识库新增 / 删除 / 重建索引且删除是破坏性操作。原文档给出三条铁律先解析确切的 base/document ID用kb_list/kb_search定位 ID绝不要猜 ID。从源码看deleteConcepts/refreshConcepts按 Concept ID 批量解析解析失败的 ID 会落入notFound数组而不让整个批次失败KnowledgeConceptService.ts但 Agent 仍应核对返回的applied/notFound以确认变更真实生效调用kb_manage一次让审批流程运行该工具由会话的审批模式门控——Claude Code 路径依赖其逐调用权限提示AI-SDK 路径使用needsApproval见 cherryKnowledgeTools.ts 与 SKILL.md 的全局规则。只有在用户意图明确后才调用永远不要直接编辑底层文件来达到同样效果那会跳过kb_manage执行的重新索引与簿记工作。知识库的写入只允许通过这些工具完成这与 SKILL.md 中不要绕过 Cherry 的变更边界的全局规则一致例如不得用 shell 手改知识库或 MCP 配置文件。若审批被拒绝立即停止并报告不要通过 shell 或文件编辑绕路重试同一变更效果。这是不可协商的纪律——绕过工具意味着绕过作用域、审批与索引一致性三层保障。恢复与错误处理原文档给出两类典型故障的处置路径空结果 / 弱检索结果先细化查询refine query、尝试另一个知识库、或扩大作用域再考虑升级处理。只有当用户明确接受使用公开来源作答时才允许对知识库未命中的情况回退到 Web 搜索——并且必须在回答中说明这一点工具错误结果如坏 ID读取错误消息并修正调用参数不要静默重试同样的参数。这一点同时对应 SKILL.md 中的全局错误纪律。端到端示例从问题到带引用的回答原文档给出如下典型场景What did our Q3 architecture doc say about the caching layer?正确的工具序列是kb_list确认有知识库在作用域内并定位到 Q3 架构文档及其 IDkb_search检索 caching layer拿到相关片段kb_read读取命中结果或对其执行 grep 精确定位带引用作答指出答案来自哪份文档。全程不发起 Web 搜索——这是私有知识用户期望答案源自其自有文档。深入阅读源码地图关注点位置工具暴露、作用域推导与审批路由cherryKnowledgeTools.ts工具编排总览与全局规则SKILL.md混合检索、Top-K、重排与阈值KnowledgeQueryService.tsConcept ID 读取/grep、组织树、概念级删除/刷新KnowledgeConceptService.ts知识库摄取流水线与存储架构features/knowledge/README.md最后再次强调kb_*工具的参数形状以会话中的实时 schema 为准本指南只提供路由、顺序与安全约束。掌握有条件可用 → 先 list 后 search 再 read → 变更必走审批、ID 必先解析 → 出错修正而非盲重试这条链路即可让 Agent 可靠地服务于用户的私有文档问答与知识库维护。【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Cherry Studio 知识库工具指南：用 kb_list / kb_search / kb_read / kb_manage 实现私有文档问答与知识库维护
Cherry Studio 知识库工具指南用 kb_list / kb_search / kb_read / kb_manage 实现私有文档问答与知识库维护【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio本指南围绕 Cherry Studio 内置cherry-toolsMCP 服务暴露的四个知识库工具mcp__cherry-tools__kb_list、kb_search、kb_read、kb_manage展开讲解 Agent 如何从用户自有文档中检索并引用答案、如何安全地对知识库执行增删与重建索引等变更操作。读完本文你将掌握知识库工具的条件可用性判定、标准读取链路、审批门控的变更流程以及出错时的恢复策略并能结合 Cherry Studio 源码理解这些工具背后的混合检索、Concept ID 寻址与作用域隔离机制。工具全景四个 kb_* 工具各自的职责知识库工具由 Cherry Studio 内置的进程内 MCP 服务器承载定义于 cherryKnowledgeTools.ts通过mcp__cherry-tools__*前缀注入到 Agent 会话中。四个工具覆盖读与写两个方向工具方向职责mcp__cherry-tools__kb_list读枚举当前作用域内的知识库或展开单个知识库查看其文档列表与文档 ID含组织树浏览mcp__cherry-tools__kb_search读在作用域内的知识库上执行语义/混合检索返回命中片段mcp__cherry-tools__kb_read读读取指定文档内容或对文档内容执行正则 grep两种模式由参数pattern路由mcp__cherry-tools__kb_manage写变更知识库内容新增、删除、重建索引re-index审批门控且删除是破坏性操作原文档明确指出本指南只负责路由、编排顺序与安全边界不重述参数形状——每个工具精确的参数名、枚举与必填字段应以会话中实时暴露的 live tool schema 为权威来源。在调用前务必先读取该工具的 schema。条件可用性kb_* 工具何时出现、何时消失四个kb_*工具并非总是可用它们只在 Agent 拥有作用域内知识库时出现作用域来源有二Agent 静态绑定的知识库binding或用户在本轮对话中通过 Composer 选择的知识库从源码结构看作用域被建模为显式的KnowledgeScope类型none/unrestricted/restricted见 cherryKnowledgeTools.ts。之所以不直接用裸 ID 数组是因为共享检索核心把空数组解释为允许全部知识库只有unrestricted变体才允许向下传递空列表——这样可以保证空作用域永远不会被静默重解释为所有知识库工具列表与每次调用都会重新推导作用域resolveKnowledgeScope未授权调用会被拒绝fail-closed。注意Composer 选择在连接建立时即被冻结修改它需要重建连接而非重新列出工具。判定规则如果会话的实时工具列表中没有kb_*说明本会话没有任何文档作用域——此时应向用户说明并引导其绑定或选择一个知识库而不是转而使用 Web 搜索并暗示答案来自用户的文档。工具缺失不代表可以绕路这一点与 SKILL.md 中的全局规则一致能力不可用时如实说明并停止绝不假装调用成功或编造结果。读取工作流kb_list → kb_search → kb_read当答案应该来自用户自有文档时Agent 应留在知识库工具内部不要用 Web 搜索替代。标准顺序kb_list枚举作用域内的知识库或传入baseId展开单个知识库查看其文档与其 ID源码中对应listOrOutlineKnowledge的两种模式见 cherryKnowledgeTools.tskb_search在作用域内的知识库上做检索拿到回答问题的片段kb_read检索定位到具体文档后读取该文档或对其执行pattern正则 grep。回答时必须附上引用的文档来源citation。源码支撑混合检索、Top-K 截断与相关性阈值读取链路的底层实现在 KnowledgeQueryService.ts。search()的核心行为可以归纳为以下几点模式选择知识库一旦完成向量索引即为hybrid向量 BM25否则退化为bm25纯词法。该模式在每次调用时重新计算不会与知识库状态漂移KnowledgeQueryService.ts候选过取以topK的 5 倍常量KNOWLEDGE_SEARCH_OVERFETCH_FACTOR 5过取候选硬上限 200 条KNOWLEDGE_SEARCH_CANDIDATE_CAP目的是在可见性过滤缺失、跨库、未完成项会被丢弃之后仍能保证最终结果数量达到 topK重排与截断重排发生在截断之前重排器能看到完整的过取候选集无重排模型时该步骤为直通pass-through相关性阈值最终结果会应用知识库自身的threshold相关性阈值过滤再输出排名。知识库的索引与存储架构见 features/knowledge/README.md每个知识库一个index.sqlitebetter-sqlite3 sqlite-vec持久化分块 嵌入后的文本服务于混合检索与 Concept ID 寻址。源码支撑kb_read 的两种模式与防失控设计kb_read的读取/grep 两种模式实现在 KnowledgeConceptService.tsreadConcept按 Concept ID即物料的相对路径OKF §2读取文档支持[charStart, charEnd)切片。单次返回被硬限制在CONCEPT_READ_MAX_CHARS 20000字符避免超大文档淹没 Agent 上下文返回的totalChars与truncated字段让调用方可以分页继续读取grepConcept对文档索引文本执行全局、默认忽略大小写的正则匹配。默认返回最多CONCEPT_GREP_DEFAULT_MAX_MATCHES 50条匹配硬上限CONCEPT_GREP_MAX_MATCHES 200每条匹配附带 1 起始行号、文档绝对偏移和前后各CONCEPT_GREP_SNIPPET_PAD 60字符的片段。为防灾难性回溯如(a)$冻结主进程事件循环正则逐行执行、单行上限CONCEPT_GREP_MAX_LINE_CHARS 2000字符锚点^/$因而按行绑定匹配不能跨行。变更工作流kb_manage 的审批与 ID 纪律kb_manage会变更知识库新增 / 删除 / 重建索引且删除是破坏性操作。原文档给出三条铁律先解析确切的 base/document ID用kb_list/kb_search定位 ID绝不要猜 ID。从源码看deleteConcepts/refreshConcepts按 Concept ID 批量解析解析失败的 ID 会落入notFound数组而不让整个批次失败KnowledgeConceptService.ts但 Agent 仍应核对返回的applied/notFound以确认变更真实生效调用kb_manage一次让审批流程运行该工具由会话的审批模式门控——Claude Code 路径依赖其逐调用权限提示AI-SDK 路径使用needsApproval见 cherryKnowledgeTools.ts 与 SKILL.md 的全局规则。只有在用户意图明确后才调用永远不要直接编辑底层文件来达到同样效果那会跳过kb_manage执行的重新索引与簿记工作。知识库的写入只允许通过这些工具完成这与 SKILL.md 中不要绕过 Cherry 的变更边界的全局规则一致例如不得用 shell 手改知识库或 MCP 配置文件。若审批被拒绝立即停止并报告不要通过 shell 或文件编辑绕路重试同一变更效果。这是不可协商的纪律——绕过工具意味着绕过作用域、审批与索引一致性三层保障。恢复与错误处理原文档给出两类典型故障的处置路径空结果 / 弱检索结果先细化查询refine query、尝试另一个知识库、或扩大作用域再考虑升级处理。只有当用户明确接受使用公开来源作答时才允许对知识库未命中的情况回退到 Web 搜索——并且必须在回答中说明这一点工具错误结果如坏 ID读取错误消息并修正调用参数不要静默重试同样的参数。这一点同时对应 SKILL.md 中的全局错误纪律。端到端示例从问题到带引用的回答原文档给出如下典型场景What did our Q3 architecture doc say about the caching layer?正确的工具序列是kb_list确认有知识库在作用域内并定位到 Q3 架构文档及其 IDkb_search检索 caching layer拿到相关片段kb_read读取命中结果或对其执行 grep 精确定位带引用作答指出答案来自哪份文档。全程不发起 Web 搜索——这是私有知识用户期望答案源自其自有文档。深入阅读源码地图关注点位置工具暴露、作用域推导与审批路由cherryKnowledgeTools.ts工具编排总览与全局规则SKILL.md混合检索、Top-K、重排与阈值KnowledgeQueryService.tsConcept ID 读取/grep、组织树、概念级删除/刷新KnowledgeConceptService.ts知识库摄取流水线与存储架构features/knowledge/README.md最后再次强调kb_*工具的参数形状以会话中的实时 schema 为准本指南只提供路由、顺序与安全约束。掌握有条件可用 → 先 list 后 search 再 read → 变更必走审批、ID 必先解析 → 出错修正而非盲重试这条链路即可让 Agent 可靠地服务于用户的私有文档问答与知识库维护。【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
