企业官网建设流程全解析

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 会话中。四个工具覆盖"读"与"写"两个方向：

原文档明确指出：本指南只负责"路由、编排顺序与安全边界"，不重述参数形状——每个工具精确的参数名、枚举与必填字段，应以会话中实时暴露的 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 搜索替代。标准顺序：

1. kb_list：枚举作用域内的知识库；或传入baseId展开单个知识库，查看其文档与其 ID（源码中对应listOrOutlineKnowledge的两种模式，见 cherryKnowledgeTools.ts）；
2. kb_search：在作用域内的知识库上做检索，拿到回答问题的片段；
3. 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.sqlite（better-sqlite3 + sqlite-vec），持久化分块 + 嵌入后的文本，服务于混合检索与 Concept ID 寻址。

源码支撑：kb_read 的两种模式与防失控设计

kb_read的读取/grep 两种模式实现在 KnowledgeConceptService.ts：

• readConcept：按 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会变更知识库（新增 / 删除 / 重建索引），且删除是破坏性操作。原文档给出三条铁律：

1. 先解析确切的 base/document ID：用kb_list/kb_search定位 ID，绝不要猜 ID。从源码看，deleteConcepts/refreshConcepts按 Concept ID 批量解析，解析失败的 ID 会落入notFound数组而不让整个批次失败（KnowledgeConceptService.ts），但 Agent 仍应核对返回的applied/notFound以确认变更真实生效；
2. 调用kb_manage一次，让审批流程运行：该工具由会话的审批模式门控——Claude Code 路径依赖其逐调用权限提示，AI-SDK 路径使用needsApproval（见 cherryKnowledgeTools.ts 与 SKILL.md 的全局规则）。只有在用户意图明确后才调用；
3. 永远不要直接编辑底层文件来达到同样效果：那会跳过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?"

正确的工具序列是：

1. kb_list：确认有知识库在作用域内，并定位到 Q3 架构文档及其 ID；
2. kb_search：检索 "caching layer"，拿到相关片段；
3. kb_read：读取命中结果（或对其执行 grep 精确定位）；
4. 带引用作答：指出答案来自哪份文档。

全程不发起 Web 搜索——这是私有知识，用户期望答案源自其自有文档。

深入阅读：源码地图

最后再次强调：kb_*工具的参数形状以会话中的实时 schema 为准，本指南只提供路由、顺序与安全约束。掌握"有条件可用 → 先 list 后 search 再 read → 变更必走审批、ID 必先解析 → 出错修正而非盲重试"这条链路，即可让 Agent 可靠地服务于用户的私有文档问答与知识库维护。

【免费下载链接】cherry-studio🍒 Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio