企业官网建设流程全解析

1. 从「云端知识库越用越怕」到 qmd 本地索引：这篇文章在解决什么

前阵子和做研发的朋友聊起文档检索，大家几乎同一个状态：个人笔记、团队成员的项目文档、会议记录散落在 Obsidian 和本地目录里，真到要找资料的时候，要么在云盘里翻半天，要么怕客户信息上传到在线知识库出问题。后来社区里开始有人推 qmd 这种纯本地运行的 AI 搜索引擎，它能索引本地 Markdown 文档、会议记录，通过关键词搜索加语义搜索再加 LLM 重排序，把结果找出来。整个过程都在本机完成，断网也能跑，敏感数据不出设备。这篇文章就是用 TaoToken 给 Claude Code 接入大模型通道，顺着 qmd 已经建好的本地索引，把「本地检索 + AI 问答」跑成一条完整的 Agent 工作流。TaoToken 的统一 API 通道负责让 Claude Code 有模型可用，qmd 继续做它最擅长的本地索引和混合搜索；需要的 Key 在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end 创建，后面每个步骤都会具体说到。

先说清楚分工，免得后面绕晕：qmd 管的是「文档在我这台机器上，索引也在本机，谁能帮我搜出相关内容」；Claude Code 是「用户用自然语言提问，我要根据问题决定调什么工具、看哪些文档、最后汇总回答」；TaoToken 是 Claude Code 背后的大模型统一接入通道，不参与索引，也不碰你的文件内容。刚才提到的工作流里，敏感文档还是留在本地，qmd 的索引文件也在本地，只有 Claude Code 向 TaoToken 发起模型推理请求时才会出网。这样既拿到了 AI 的总结和组织能力，又不必把整套知识库搬上云。

2. 先把 qmd 本体装好：一条命令收编笔记和会议记录

qmd 支持用 bun 全局安装，也可以走 npm 或者 pnpm，我个人习惯用 bun，一条命令就能装完：

bun install -g https://github.com/tobi/qmd

装完之后顺手确认一下版本号，避免后面 MCP 插件调用时出现找不到命令的情况：

qmd --version

如果你用的包管理器不是 bun，比如 npm 全局目录存在权限问题，可以考虑用 pnpm 再装一次。工具本身不大，真正占地方的是后面qmd embed要下载的 embedding 模型文件，那个通常几百 MB 到几个 GB，需要留出磁盘空间。

安装完成后，把散落的文档「收编」进集合。集合（Collection）是 qmd 里最核心的组织单元，它不是一个数据库文件，而是一组对本地目录的描述。我给个人笔记、会议记录、工作文档分别建了三个集合：

qmd collection add ~/notes --name notes qmd collection add ~/Documents/meetings --name meetings qmd collection add ~/work/docs --name docs

路径根据自己的实际情况改。这里有一点要注意：qmd 索引的是目录里现有的 Markdown 文件，如果以后在这个目录下新增了文档，需要再跑一次增量同步，它本身不会实时监听文件系统变化。

为了让搜索结果的来源更可读，可以给每个集合补一句上下文描述：

qmd context add qmd://notes "Personal notes and ideas" qmd context add qmd://meetings "Meeting transcripts and notes" qmd context add qmd://docs "Work documentation"

这一步不是必须的，但当你搜到一个结果时，qmd 能告诉你这个文档属于哪个集合，方便 Claude Code 在回答里带上「这段内容来自 meetings 集合的 2024-01-15.md」，定位起来很快。

然后生成向量索引，语义搜索靠的就是这一步：

qmd embed

第一次运行会下载 embedding 模型文件，根据网络情况可能要等一阵子。之后再跑就快多了，它只处理新增或变更的文件。

3. 三种搜索方式里，最该记住的是混合搜索

索引建完之后，qmd 提供三种搜索方式，分别对应不同场景。我是按这个思路用的：

关键词搜索

qmd search "project timeline"

基于 BM25 全文检索，速度快，适合你记得确切关键词的情况。想拿给 AI Agent 用，可以加 JSON 输出：

qmd search "authentication" --json -n 10

-n 10控制返回条数，--json让输出变成结构化数据，Claude Code 解析起来比纯文本流畅很多。

语义搜索

qmd vsearch "how to deploy"

基于向量相似度，文档里没有「deploy」这个词，只要语义相近也能找出来。适合只有模糊印象、记不准术语的情况。

混合搜索

qmd query "quarterly planning process"

这是集大成者：先用本地 LLM 把原始查询扩展成多个变体，再同时跑关键词和语义搜索，最后用重排序模型把结果按相关度重新排一遍。直接拿它当默认命令用就行，搜索质量在这个工具里是最高的。

如果只想拿路径，不想要整篇内容：

qmd query "error handling" --all --files --min-score 0.4

--all表示在所有集合里搜，--files只返回文件路径，--min-score 0.4过滤掉低分结果。这样配合 Claude Code 使用时，可以先拿到一批文件路径，再让模型决定读哪几个。

需要读取完整内容时：

qmd get "meetings/2024-01-15.md"

也可以用索引里的文档 ID 获取，搜索结果里会带类似#abc123的短 ID：

qmd get "#abc123"

这些命令单独用已经很顺手了，但真正让它发挥价值的是下一步：接到 Claude Code 里，让模型在一个长会话里同时调度 qmd 搜索和语言推理。这也是为什么需要把模型通道切到 TaoToken——Claude Code 本身不自带大模型，它需要一个能访问模型的 API 地址。

4. Claude Code 装 qmd 插件后，把模型通道指到 TaoToken

Claude Code 接 qmd 分两步：第一步装 qmd 的插件，第二步把模型 Base URL 指到 TaoToken。

装插件用官方命令行：

claude marketplace add tobi/qmd claude plugin add qmd@qmd

装完插件之后，Claude Code 会拿到一组 qmd 工具，比如qmd_search、qmd_vsearch、qmd_query、qmd_get。这些工具的底层全都落在 qmd 命令上，索引和文档内容仍然在本机完成。Claude Code 负责的是判断「当前这个问题该调用哪个工具、返回结果如何组织成答案」。

这时候就轮到 TaoToken 登场了。Claude Code 官方默认的模型通道对国内开发者来说有配额和网络方面的门槛，绕过这些限制不是本文要讲的，也不该那么做；更稳的做法是让 Claude Code 走一个兼容通道，把模型请求发到你自己的 API 地址上。TaoToken 正好提供这种统一接入方式。打开 TaoToken 注册并创建 API Key，然后配置 Claude Code 的环境变量。

Claude Code 的全局配置在~/.claude/settings.json，像下面这样填：

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY", "ANTHROPIC_MODEL": "以 https://taotoken.net/?utm_source=taotoken_aicg_blog_end 模型广场为准" } }

三个环境变量缺一不可。ANTHROPIC_BASE_URL填的是接口地址，注意末尾不要加/v1，TaoToken 的接入文档里对这一点有明确说明。ANTHROPIC_AUTH_TOKEN填你从控制台创建的 Key，也就是上面说的YOUR_API_KEY，别和官网落地页地址搞混，那个是注册和创建 Key 用的，填进工具的是https://taotoken.net/api。ANTHROPIC_MODEL不要拍脑袋填一个模型名，去模型广场看当时提供哪些可用的 Claude 模型 ID，照着列表选。

这是 Claude Code 的标准环境变量配置方式，不是通用 JSON，是整个生态里和 Anthropic 官方客户端兼容的写法。改完之后重启 Claude Code，让配置生效。

顺带提一下，如果你更习惯在项目级配置里区分不同项目的模型，可以把这个 env 块放在项目根目录的.claude/settings.json里，只对当前项目生效。平时开发我用全局配置，不同客户项目需要隔离时再改成项目级。

5. 验证链路：让 Claude Code 去搜「数据库迁移那次会议的结论」

配置保存后，怎么确认两端真的打通了，而不是各自跑各自的？我的验证方法是给 Claude Code 提一个模糊的、没法靠模型知识回答的问题，强制它去调 qmd。比如问它：「去年讨论数据库迁移的会议记录，结论是什么？帮我列出当时提到的风险点。」

如果链路正常，Claude Code 会调用qmd_query做一次混合搜索，返回一批会议记录文件路径，再调用qmd_get读内容，最后结合两份文档给出回答。回答里应该能看到类似「根据 meetings 集合的 2024-06-18.md 和 2024-06-25.md，当时讨论的风险点主要有三个」这样的引用，而不是模型凭自己的记忆硬编一段。这一点很重要：qmd 没有搜索到内容，Claude Code 就不该有对应结论。

接着可以再测一个侧重点不太一样的查询：「我笔记里有没有提过模糊搜索的调优思路？」这个问题适合验证语义搜索，因为你的笔记里可能根本没写「模糊搜索」四个字，写的可能是「fuzzy match」或者「拼写纠错」。如果 qmd 能通过向量相似度把相关笔记捞回来，说明 embedding 索引是真的在工作，Claude Code 只是一个把结果翻译成自然语言的角色。

链路通了以后，再去 https://taotoken.net/?utm_source=taotoken_aicg_blog_end 看一眼这次交互有没有产生 API 调用记录。TaoToken 控制台的用量列表里，能看到刚才 Claude Code 发出的请求、对应模型和 token 消耗。这一步能帮你确认问题到底出在模型通道还是出在 qmd 插件，是排查问题最直接的分界点。

在 TaoToken 模型对话 里也可以用同一把 Key 发一条测试消息，确认模型 ID 和 Base URL 没填错。如果这里能通而 Claude Code 里不通，问题基本就在环境变量的加载路径上，去检查 settings.json 的位置和 JSON 格式即可。如果这里也不通，那就是 Key 或模型 ID 的问题，先去 控制台 API Keys 确认 Key 的状态和额度，再回到模型广场核对模型 ID。

6. 只有本篇会遇到的报错，逐个说清排查方向

跑这套「Claude Code + qmd + TaoToken」的组合，和纯 CLI 搜索不一样，报错来源分成三层，每一层的现象和修法都不同。这里只挑三个最常见的写。

第一层：qmd 命令本身找不到

错误现象是qmd: command not found，或者 Claude Code 插件报「Failed to execute qmd」之类的错。常见原因是 bun 的全局 bin 目录不在 PATH 里，解决办法是把 bun 的 bin 目录加到 shell 配置里，而不是重装工具。

第二层：模型通道报 404

如果 Claude Code 启动后模型请求直接 404，先检查ANTHROPIC_BASE_URL是不是被写成了https://taotoken.net/api/v1。TaoToken 的兼容地址末尾不带/v1，这一点和很多 OpenAI 风格网关不一样；多写一个/v1会直接导致路由对不上。另外确认ANTHROPIC_MODEL是不是填了模型广场里不存在的名字，拿不准就用广场列表里显示的原始 ID。

第三层：插件装上了但工具调不出来

claude marketplace add tobi/qmd执行成功，但对话中 Claude Code 一直不调用 qmd 工具，可能的原因有两个。一个是当前会话是插件安装前启动的，重启会话让工具列表重新加载；另一个是模型在长对话里判断「这个问题不需要外部搜索」，这种情况可以主动换一种说法提示它，比如「先用 qmd 搜索一下再回答」，把工具调用的意图表达得更明确。

另外给一个 CLI 直接验证的办法，如果你机器上装了@taotoken/taotoken，也可以不经过 Claude Code，直接确认模型通道可用：

npm install -g @taotoken/taotoken taotoken cc -k YOUR_API_KEY -u https://taotoken.net/api -m YOUR_MODEL_ID

-u后面同样不要加/v1。这条命令的作用是把模型通道这一层单独摘出来测试，通过之后再去查 Claude Code 的插件，问题定位会快很多。完整的 Claude Code 环境变量说明在 接入文档 里写得很细，遇到不确定的字段可以直接对照文档查。

7. 跑通之后，这套组合实际能做什么

链路验证通过后，我实际用得最多的是三个场景，都和本地知识库的隐私保护强相关。

第一个是会议记录回顾。以前团队开完会，想把某次关于备份策略的讨论找出来，得按日期翻文件。现在直接问 Claude Code：「6 月那几次例会里，有没有讨论过备份策略？把结论整理一下。」它会先让 qmd 做语义搜索，定位到 meetings 集合里的几次会议记录，再返回给模型汇总。整个过程不需要把会议记录传到任何云服务上。

第二个是技术文档检索。查某个内部 API 的用法时，Claude Code 可以先用qmd search搜出相关实现文件，读完后直接基于项目里的真实代码回答，而不是凭训练数据猜一段可能过时的写法。对于代码量大的仓库，这个价值很快就体现出来了。

第三个是写文档或周报前的资料收集。我让 Claude Code 针对某个主题先跑一轮qmd query --all --files --min-score 0.4，把相关的本地文档路径全捞出来，再逐个读取重点内容，最后在回答里列出每份文档说了什么。这样生成的初稿每条信息都有出处，不用像以前那样担心 AI 编造细节。

整套方案跑顺之后，你对自己的知识库会建立一种信任感：文档在本地，索引在本地，搜索也在本地，Claude Code 留在外面的只有最后那一层和模型 API 交互的内容。如果你刚装好 TaoToken 还没想好跑什么场景，建议先从自己的笔记目录开始建集合。索引好之后，挑一条之前死活想不起关键词的旧笔记，用qmd query搜一遍，再用 Claude Code 问一遍，感受一下「本地检索 + AI 问答」和单纯浏览器搜索的差别。之后需要长期大量调用的话，可以去看看 Coding Plan 是否更贴合你的用量。