homekb 如何为本地 Markdown 知识库实现语义搜索、AI 问答和 MCP？
要让一批本地 Markdown 不再只是“能全文检索的文件夹”，关键是把文件所有权、语义索引、问答模型和工具调用拆成清晰的层次。HomeKB 的做法是让 Markdown 原文、索引和写入动作留在自己的电脑上，再通过命令行、桌面端、网页端或 MCP 客户端访问同一个本地引擎。实际落地时，可以先完成本地语义搜索，再配置基于检索结果的 AI 问答，最后按使用场景接入本地或远程 MCP。这样每一步都能独立验证，也更容易判断数据究竟经过了哪里。
先理解 HomeKB 的组成
HomeKB 以 Rust 编写的命令行引擎为核心。引擎负责读取 Markdown、生成摘要和分块、建立向量索引、执行检索、回答问题以及读写笔记。桌面应用和 Web UI 都建立在同一套 RPC 接口之上，并不是各自维护一份知识库。默认目录是 ~/.homekb/notes/，也可以在初始化时指向已有的 Markdown 文件夹。
本地索引使用 SQLite 与 sqlite-vec。编译阶段会从文档生成摘要、分块、文档类型、建议问题和向量表示；检索阶段同时从文档摘要池和内容分块池执行近邻搜索，再使用 RRF 融合结果。对于“列出某一类全部内容”这类覆盖型问题，引擎还会改用整类枚举，而不是机械地只返回 top-K 结果。这个设计解释了为什么语义搜索不仅能寻找相同词语，还能按含义定位相关笔记。
远程访问由中继服务转发。家中电脑主动建立出站隧道，因此通常不需要公网 IP。官方中继保存配对关系、共享路由和令牌哈希，不把笔记、索引或搜索结果持久化；但远程请求会在 TLS 终止后经过中继内存，当前协议也不是端到端加密。若这一信任边界不可接受，应自托管中继，或只使用本地 CLI、桌面端和本地 MCP。
安装引擎并选择笔记目录
在 macOS 或 Linux 上可以通过 Homebrew 安装，在 Windows 上可以使用 Scoop，也可以下载预编译二进制。若选择从源码安装，则需要较新的 Rust 工具链。以下示例使用 Homebrew：
brew install do-md/tap/homekb
homekb init --notes "$HOME/Documents/notes" --openai-key "$OPENAI_API_KEY"
homekb statushomekb init 会创建数据目录和 ~/.homekb/config.toml。如果省略 --notes，引擎会使用默认笔记目录。配置文件可能包含 AI 服务密钥，因此同步整个 HomeKB 数据目录时应明确排除它。已有 Markdown 文件无需迁入专有数据库；将引擎指向原目录即可继续用编辑器和 Git 等原有工具管理文件。
也可以走浏览器优先的配对流程：
homekb pair该命令会使用内置的官方连接服务注册当前电脑，并输出一个十分钟内有效的一次性配对码。随后在 Web UI 输入配对码，在设置中分别配置 Embedding 和 Summary 提供方；Ask 提供方是可选项，因为接入的 MCP 智能体也可以使用自己的模型。官方预设覆盖 OpenAI、Gemini、Voyage、Cohere、DeepSeek 和 Qwen，也支持兼容 OpenAI 接口的自定义端点。
建立并验证语义索引
配置完成后，先执行增量编译，再分别检查状态和查询结果：
homekb reindex
homekb status
homekb query "项目为什么选择本地优先存储？"reindex 会处理新增或发生变化的文件，而不是要求每次从头构建全部内容。首次运行时应重点确认三个方面：笔记目录是否正确、Embedding 配置是否可调用、索引状态是否健康。查询时最好使用一条能够在已知笔记中找到答案、但用词与原文不完全相同的问题，这比搜索原文中的固定关键词更能验证语义检索是否真正生效。
持续使用的知识库还需要及时编译变更。在 macOS 上可以安装定时任务：
homekb watch --install --interval 300这个例子每五分钟检查并增量编译一次，也可在状态页面暂停或修改周期。Linux 和 Windows 当前需要把 homekb watch 交给各自的进程管理器运行，因为自动安装后台服务目前仅支持 macOS。修改 Markdown 后若查询仍返回旧内容，应先看状态和编译日志，而不是直接更换问答模型。
让 AI 基于笔记回答问题
语义查询只返回相关材料，问答命令则在检索之后调用已配置的模型，并附带来源引用：
homekb ask "总结知识库中关于本地优先架构的决定，并列出尚未解决的问题。"可靠使用问答功能的前提是把“检索不到”和“模型回答不佳”分开诊断。先用 homekb query 检查相关分块是否被召回；若召回为空或偏题，应检查文档是否已编译、Embedding 模型是否更换过，以及问题是否属于需要整类枚举的覆盖型请求。若检索材料正确而答案不理想，再检查 Summary 或 Ask 提供方的配置和提示方式。
更换 Embedding 模型或向量空间后，旧向量通常不能直接混用，应执行重建：
homekb rebuild
homekb status重建成本取决于笔记规模和所选服务，因此不应把它当作普通刷新操作。日常内容更新使用增量编译即可；只有向量模型、维度或相关索引基础发生变化时才需要完整重建。
接入 Codex、Claude Code 或 Cursor
HomeKB 的本地 MCP 服务通过标准输入输出运行，并直接调用本机引擎，不经过远程连接服务。自动安装命令会检测已经存在的 Claude Code、Codex 和 Cursor：
homekb mcp --install也可以只针对一个客户端注册：
homekb mcp --install codex
homekb mcp --install claude
homekb mcp --install cursor注册后，智能体可以使用 kb_search、kb_read、kb_create、kb_update、kb_list、kb_status 和 kb_share 等工具，完成语义搜索、读取、创建、更新和分享笔记。自动注册会写入引擎的绝对路径，可避免客户端环境变量中找不到 homekb 而出现连接失败。若需要移除注册，可执行 homekb mcp --uninstall。
接入后不要一开始就授权智能体批量修改文件。更稳妥的验证顺序是先调用状态工具，再搜索一条已知内容，随后读取命中的笔记，最后在测试目录中创建和更新一篇临时笔记。这样可以分别确认连接、索引、读取和写入权限，而不会在配置错误时影响真实资料。
远程 MCP 与自托管中继
需要让另一台设备上的 Claude 或 ChatGPT 访问家中知识库时，可以把官方远程 MCP 端点添加为自定义连接器，再通过 homekb pair 生成的一次性代码完成授权。此时查询仍由家中运行的引擎执行，中继负责转发 RPC、流和二进制资源。远端离线时，应先检查家中电脑的引擎和隧道是否运行，而不是重新建立索引。
对数据路径有更严格要求时，可以部署 Cloudflare Workers 版本或独立 Node 版本的中继，再把本机注册到自有服务。自托管能够把 HomeKB 官方运营方移出链路，但不会消除所选 AI 提供方对输入文本的处理，也不会自动带来端到端加密。因此，敏感知识库仍需结合模型提供方的数据策略、访问控制和网络环境进行评估。
常见问题与排查顺序
MCP 客户端显示无法连接
先重新执行针对该客户端的安装命令，确保配置使用引擎绝对路径。然后在终端运行 homekb status，确认二进制能够启动且配置可读。如果命令行正常而 MCP 失败，再重启客户端并检查它读取的是哪一份 MCP 配置。
搜索结果为空或与问题无关
确认目标文件扩展名和笔记目录无误，运行增量索引并查看状态。若刚更换 Embedding 提供方，应执行完整重建。还可以选取一篇内容明确的短笔记，用不同措辞查询其核心概念，以排除原问题过于宽泛或笔记本身信息不足。
网页端能打开但无法访问家中知识库
配对码只有有限有效期，过期后需要重新生成。已完成配对但仍离线时，检查隧道和后台服务状态。Linux 与 Windows 当前不会自动安装后台服务，需要由外部进程管理器保持 watch 和 tunnel 运行。
如何避免把隐私假设得过于乐观
本地优先不等于所有数据永远不离开电脑。笔记原文、索引和配置默认在本机，中继不持久化知识内容；但远程流量会经过中继内存，用于向量、摘要或回答的文本也会发送给自行配置的 AI 提供方。应按这一真实边界决定是否启用远程能力，并妥善保护配置文件中的密钥。
一套可重复的验收清单
完成部署后，可以用五个结果判断系统是否可用：普通 Markdown 仍能被原编辑器直接打开；修改一篇笔记后增量编译能识别变化；语义查询能用不同措辞找回目标内容；问答输出能够指向知识库中的来源；MCP 客户端能在测试笔记上完成搜索、读取和受控写入。若启用远程访问，还应验证家中电脑离线时客户端明确显示不可用，以及撤销配对或停止服务后旧连接不能继续操作。
HomeKB 当前的 Rust 引擎、本地 MCP、两种中继、Web UI 和 macOS 桌面壳已经可以协同工作，但项目并未宣称达到生产就绪状态，端到端加密、原生移动应用、冲突解决以及部分深度研究工具也尚未实现。把这些限制纳入部署决策，先从可回滚的小型知识库开始，就能在保留 Markdown 文件控制权的同时，逐步获得语义搜索、带来源的 AI 问答和 MCP 工具访问能力。
