这是知识库系列的第二篇。上一篇我写了怎么部署腾讯开源的 WeKnora 知识库，以及排查"17 篇文档一篇都搜不出来"的踩坑过程。部署只是第一步——真正的问题在于，部署完之后，你和你的 AI Agent 该怎么用好它？ 这篇讲我为这个问题写的答案：一个叫 scheme-writer 的 skill。

一、知识库建好了，然后呢？

很多人对知识库的期待是这样的：建好库、灌进文档，然后对着 AI 说一句"帮我查一下漏洞管理流程"，AI 就该乖乖去检索、给出带出处的回答。

现实是：大多数 AI Agent（哪怕是很强的编程 Agent）并不会主动去用你那个知识库。它们不知道你的知识库在哪、不知道用什么 API、不知道怎么认证、不知道检索结果该怎么用。你把 WeKnora 部署在 http://<your-server-ip>，Agent 对此一无所知。

于是出现了一个尴尬的局面：知识库在那一头孤零零地等着被问，Agent 在这一头不知道门在哪。

更尴尬的是，知识库往往不止一个：

  • 本地知识库——我用 Obsidian 维护的个人/团队笔记（Markdown 文件，躺在磁盘上）；
  • 企业内部专用知识库——比如上一篇部署的 WeKnora，存的是制度、规范、客户文档；
  • 云端知识库——Notion、飞书文档，或者公有云的 RAG 服务。

这三个库各管一摊，Agent 要用它们得分别学三套玩法。这正是 skill 这种东西该解决的问题。

我写了一个叫 scheme-writer 的 skill，目标很朴素：给 Agent 装上一个"知识库遥控器"，让它用一套统一的方法，操作本地、云端、企业内部这三类知识库。

二、scheme-writer 是什么

一句话：它是一个可以装进任何支持 skill 的 AI Agent 里的知识库操作技能。

支持 skill 机制的 Agent 现在越来越多——Claude Code、workbuddy、Trae Solo 都能加载 skill。scheme-writer 就是一组 Markdown 说明（SKILL.md）加上几个 Python 脚本，丢进 Agent 的 skills 目录就能用。

它给 Agent 提供了五个核心能力：

能力作用典型触发
知识库语义检索（kb_search）按问题从指定库拉相关片段“从《技术规范库》查一下…”
知识库列表（kb_list）列出当前账号可见的所有库用户没指定用哪个库时
库内文档清单（kb_docs）看某个库里到底有哪些文档、解析状态如何“库里有什么"“为什么搜不到”
文档上传归档（kb_upload）把写好的内容上传回知识库“把这份方案归档到《方案库》”
首次配置（init）对话内引导配置 URL / 密钥 / 别名第一次使用或重新配置

这五个能力拼起来，就构成了一个完整的”检索 → 写作 → 归档“闭环：Agent 从知识库拉素材、整理成方案、再写回知识库沉淀。知识不再是单向消费，而是能持续积累。

三、核心卖点：打通三类知识库

这是这个 skill 最值得讲的地方。

3.1 本地知识库：Agent 的原生领地

本地知识库（比如我的 Obsidian vault）对 Agent 来说是"主场”——文件就是磁盘上的 Markdown，Agent 天生能读、能写、能搜索。这部分不需要 skill 介入，Agent 用自带的文件工具就能搞定。

但问题是：本地库的检索是关键词级的，不是语义级的。 Agent 用 grep 搜"漏洞管理"，只能命中字面包含这四个字的文件；它没法像 RAG 那样理解"高危漏洞多久要修"的语义。

3.2 企业内部知识库：scheme-writer 的主战场

企业库（WeKnora 这类）有真正的语义检索能力，但藏在 API 后面。Agent 要用它，得知道：

  • 端点地址（/api/v1/knowledge-search）
  • 认证方式（X-API-Key 头，不是常见的 Bearer Token）
  • 请求体结构（query、knowledge_base_id、top_k、min_score）
  • 响应字段（不同版本字段名还不一样：chunks / results / data）

这些细节如果让 Agent 每次"临时查文档 + 手写 curl"，既慢又容易错。scheme-writer 把这些全部封装好了：Agent 只需要说"检索漏洞管理"，skill 内部处理好所有 API 细节、字段兼容、错误归一化。

3.3 云端知识库：架构可扩展

云端库（Notion、飞书、公有云 RAG）各有各的 API。scheme-writer 当前的实现对接的是 WeKnora 协议，但它的设计是可插拔的知识库后端——只要某个云端库暴露了"检索/列表/上传"这几个原语，就能用同一套 skill 接口接入。

📷 [截图占位]：三类知识库的打通示意——本地 Obsidian、企业 WeKnora、云端服务，通过 scheme-writer 统一为 Agent 可调用的原语。

三库打通的真正含义不是把数据搬到一起，而是让 Agent 用统一的思维模型去操作它们：

  • 要语义检索 → 走企业库（kb_search）；
  • 要看本地笔记 → 走文件操作；
  • 要把成果沉淀 → 归档到指定的库（kb_upload）。

Agent 不用记三套玩法，一套就够。

四、跨 Agent 可移植：装哪都能用

skill 这种形态有个被低估的好处：它是声明式的。

一个 skill 就是一个 SKILL.md（告诉 Agent “什么场景下用什么脚本、按什么规则”）加若干脚本。它不依赖某个特定 Agent 的私有 API，只要 Agent 支持"加载 skill 目录 + 执行脚本"这套机制，就能用。

我在几个 Agent 上都跑过 scheme-writer：

  • Claude Code——主力环境，对话内配置体验最好；
  • workbuddy——同样支持 skill 加载，配置一次多会话复用；
  • Trae Solo——轻量 Agent，装上即用。

配置都是同一份（存在 ~/.claude/scheme-writer/.env 或对应 Agent 的配置目录），脚本同一套，行为一致。这意味着你写一次 skill，换 Agent 不用重学。

对企业来说这点很关键：Agent 工具会换，但"怎么用知识库"这套方法论和配置不该绑死在某个 Agent 上。

五、几个让它好用的设计细节

光有功能不够，好不好用取决于细节。这个 skill 里有几个我比较得意的设计。

5.1 对话内配置，零终端切换

第一次用的时候，Agent 会自动检测配置状态。如果没配过，它不会把你赶到终端去敲命令，而是在对话里用选择题的方式一步步问：

  • “你的知识库地址是？"（给个默认值）
  • “API Key 是？"（立刻写进本地文件，不在对话里回显）
  • “要不要给某个库起个好记的别名？”

整个过程像填表，全部在聊天框里完成。配置好之后，后续使用零打扰。

📷 [截图占位]：Agent 在对话内引导配置知识库的交互过程。

5.2 安全规范：密钥绝不回显

企业场景下，密钥管理是命门。这个 skill 立了几条硬规矩：

  • API Key 只通过本地 .env 文件注入，绝不出现在对话、脚本日志、提交历史里；
  • 查看配置时，Key 只显示前几位和后几位，中间打码；
  • 提示用户：如果在对话里粘贴过 Key，用完立刻在服务端轮换一次。

这些不是花架子。一旦 Agent 把企业内部库的 Key 写进了某次对话记录或日志，泄露面就很难收口。

5.3 统一错误信封，让 Agent 能"看懂"失败

知识库调用会失败——超时、认证过期、库不存在、文档还在解析。如果这些错误以一坨原始报错文本返回，Agent 往往不知道该怎么办。

skill 把所有错误归一化成语义化的错误码 + 结构化 JSON：auth（密钥问题）、kb_not_found（库写错了）、timeout（超时）、server（服务端故障）。Agent 看到 auth 就知道该提示用户轮换密钥，看到 kb_not_found 就知道该重新列库确认 ID。失败也变得可处理。

5.4 诊断能力：为什么搜不到东西

这个能力我在上一篇踩坑文里重度用过。kb_docs 能列出某个库里每篇文档的 parse_status（解析状态），是排查"文档上传了却搜不到"的关键工具。

它甚至透出一个组合诊断信号：当列表显示某库 doc_count > 0（有文档）但 chunk_count = 0（没有索引块）时，skill 会提示——这不是文档问题，是向量化没完成，去看 embedding 配置。这种"把运维诊断塞进 skill"的做法，省了无数排查时间。

5.5 上传必须显式确认

写完方案想归档？skill 绝不自动上传。每次上传前，Agent 会先说一句：

“确认：正在将《XX方案》上传到《方案库》…（取消请说’停’）”

等一拍，给你反悔的机会。这是为了避免 Agent 自作主张往企业库里塞东西——在企业场景，“误上传"和"漏上传"一样麻烦。

六、实战：一次完整的三库协作

把上面这些拼起来，看一个真实的协作流程。假设需求是：“帮我从企业知识库查漏洞管理相关制度，写一份漏洞管理方案，写完归档到方案库，同时把要点记到我的本地笔记。”

Agent 会这样跑：

  1. 检索企业库：调 kb_search，从 WeKnora 拉出漏洞管理制度的相关片段（带相似度分数，低于阈值的丢弃）；
  2. 补充本地库：用文件搜索看看本地 Obsidian 里有没有相关的个人笔记或历史方案，作为补充素材；
  3. 写作：综合两路素材，先出大纲、确认后展开成完整方案；
  4. 归档企业库：上传前确认，调 kb_upload 把方案写回《方案库》；
  5. 沉淀本地库：把方案要点存成本地 Markdown 笔记，建好双链。

整个过程里，企业库负责权威的、语义检索的素材，本地库负责个人的、可沉淀的积累，Agent 在中间统一调度。 这就是我说的"三库打通"落地后的样子。

📷 [截图占位]：一次完整的检索→写作→归档流程，展示 Agent 调用知识库工具的过程。

七、诚实的局限

不想把它吹成万能钥匙，几个真实的局限：

  • 当前实现主要对接 WeKnora 协议。要接其他云端库（Notion、飞书原生 API），需要按相同的原语写适配——架构留了口子，但适配工作还得做；
  • 跨库检索结果的排序是粗粒度的。不同库的相似度分数不一定可比，目前是分库返回、简单合并，没有做全局二次重排；
  • 多标签上传有 workaround。WeKnora 的上传接口只支持单个标签，skill 暂时把多标签拼到标题前缀——能用，但会轻微污染标题，等服务端支持多标签后要清理；
  • 依赖 Agent 的 skill 执行能力。skill 写得再好，最终效果还是看 Agent 能不能正确理解和调用它。不同 Agent 的执行水平有差异。

八、写在最后

知识库的真正价值，不在于你部署了多强大的引擎，而在于它有没有被真正用起来。

很多人部署完 RAG 平台就束之高阁，因为日常工作时根本想不起来"现在该去查那个库”。scheme-writer 这类 skill 想解决的，就是这个"最后一公里”：让用知识库这件事，变成 Agent 的本能，而不是你的额外负担。

如果你也在用 Claude Code、workbuddy、Trae Solo 这类支持 skill 的 Agent，又正好有个想用起来的知识库，不妨照这个思路给 Agent 装一个"知识库遥控器”。一旦 Agent 学会了自己去查库、归档，你会发现知识库这个东西，终于"活"了。

相关阅读

  • 上一期：《腾讯开源 WeKnora 知识库部署实战（含踩坑排查）》
  • WeKnora 项目：https://github.com/Tencent/WeKnora

如果你也在给 Agent 做知识库 skill，或者想知道某个具体能力的实现细节，欢迎留言交流。