homekb

# 首页知识库 一个个人 Markdown 知识库，存活在你的电脑上，并始终与你的 AI 保持联系 — 无论是在本地还是远程。 - **文件优先。** 你的笔记仍然是普通的 `.md` 文件，存放在一个你控制的文件夹中。 - **代理原生。** Claude Code、Codex、Claude、ChatGPT 等 MCP 客户端可以搜索、读取、创建、更新和分享笔记。 - **本地构建。** 索引、检索和写入操作都保留在你的家用电脑上；AI 调用使用你配置的提供商。 - **无需账户远程访问。** 通过一次性代码配对；中继存储关系和令牌哈希值，但绝不会存储你的知识库内容。 - **两个命令到你的手机。** 安装引擎，运行 `homekb pair`，并在 Web UI 中完成设置。 [English](README.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja.md) --- ## 你的知识生活在家里 HomeKB 将 Markdown 文件夹转换为语义知识库，而无需将所有权转移到云应用中。 将笔记放入 `~/.homekb/notes/` — 或将 HomeKB 指向现有的 Markdown 文件夹 — Rust 引擎将增量构建本地 sqlite-vec 索引。你可以按含义搜索、提问并获取引用、编辑笔记，或让 AI 代理通过 MCP 与库合作。 命令行引擎是产品核心。桌面应用和 Web UI 是同一 RPC 接口的渲染器，而中继仅是远程客户端和家用电脑上运行的引擎之间的管道。 --- ## 它能做什么 - 将 Markdown 编译为摘要、块、文档类型、建议问题和嵌入。 - 通过文档摘要和块的双池 KNN 检索，结合 RRF。 - 当问题询问覆盖范围而不是前 K 个匹配时，切换到整个类别枚举。 - 从本地笔记中回答问题，并提供来源引用。 - 通过 CLI 或 MCP 创建、读取、更新、列出和语义搜索笔记。 - 在家用设备上保留未发布的草稿，并在配对的客户端之间分享。 - 渲染 Markdown 和本地图片，上传粘贴或拖放的图片，并从桌面或 Web UI 编辑笔记。 - 为单个笔记创建可撤销的公共链接，带有可选密码和过期时间。 - 从 Web UI 管理计划编译并启动完整索引重建。 - 通过出站隧道连接远程浏览器和 AI 客户端 — 家用电脑无需公开 IP。 --- ## 工作原理 ```mermaid flowchart LR A["手机、浏览器或远程 AI"] -->|"TLS · 配对请求"| R["HomeKB 中继<br>无知识数据存储"] R -->|"出站 SSE 隧道"| E["HomeKB 引擎<br>您的电脑"] L["本地 AI 或桌面应用"] -->|"MCP 或回环 RPC"| E E --> N["Markdown 笔记"] E --> I["本地 sqlite-vec 索引"] ``` HomeKB 有三个独立且有用的部分： | 部分 | 角色 | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | **引擎** (`engine/`) | 一个自包含的 Rust CLI，用于编译、检索、问答、本地 MCP、本地 HTTP RPC、分享、配对和隧道。 | | **客户端** (`client/`) | 一个 Next.js UI，适用于两个界面：纯 Web 前端和 Tauri 桌面渲染器，安装并与本地引擎通信。 | | **中继** (`relay/`) | 可互换的 Cloudflare Workers 和 Node 目标，转发 RPC、流和二进制资产，但不存储知识库内容。 | 协议和数据布局合约位于 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。 --- ## 快速开始 引擎是一个 **独立的二进制文件** — 捆绑的 SQLite、rustls TLS、无运行时依赖且无需 Rust 工具链。可通过平台包管理器安装： ### 1. 安装引擎 ```bash # macOS / Linux — Homebrew brew install do-md/tap/homekb # macOS / Linux — 安装脚本 curl -fsSL https://raw.githubusercontent.com/do-md/homekb/main/install.sh | sh # Windows — Scoop scoop bucket add homekb https://github.com/do-md/scoop-bucket scoop install homekb ``` 或直接从 [最新发布](https://github.com/do-md/homekb/releases) 下载二进制文件。更喜欢从源代码构建？`cd engine && cargo install --path cli`（需要最近的 Rust 工具链）。 安装脚本将二进制文件放入 `~/.local/bin` 并自动将该目录添加到 shell 的 `PATH` 中（zsh、bash 和 fish）。打开新的终端 — 或 `source` shell rc 文件 — 以使 `homekb` 生效。 ### 2. 配对此电脑 ```bash homekb pair ``` 首次运行时，这会将计算机注册到 HomeKB 的内置官方连接服务，启动后台连接和计划编译服务（在 macOS 上），并打印一个有效期为十分钟的一次性代码。无需创建 HomeKB 账户。 自动后台服务安装目前仅限 macOS。有关 Linux 和 Windows，请参见 [当前状态](#当前状态)。 ### 3. 打开 Web UI 在手机或另一个浏览器上打开 [www.homekb.app](https://www.homekb.app)，并输入代码。服务地址已为默认路径选中。 ### 4. 在浏览器中完成 - 打开 **设置** 并配置 **嵌入** 和 **摘要**。**询问** 是可选的，因为连接的 MCP 代理会带来自己的模型。 - 为 OpenAI、Gemini、Voyage、Cohere、DeepSeek 或 Qwen 选择内置预设，或使用自定义 OpenAI 兼容端点。 - 打开 **状态** 以查看首次编译。在 macOS 上，配对后默认启用计划编译；您可以暂停或在那里更改间隔。 您的 Markdown 文件现在保留在家庭电脑上，而配对的浏览器可以远程搜索、读取、编辑和管理库。 --- ## macOS 桌面应用 更喜欢在托管知识库的 Mac 上使用原生窗口？[下载最新的 HomeKB 桌面应用](https://github.com/do-md/homekb/releases/latest/download/HomeKB_aarch64.dmg)。当前桌面版本支持 Apple Silicon Mac；引擎和 Web UI 仍然是主要的跨平台路径。 桌面应用是本地引擎和接口的原生外壳: - 如果 HomeKB 引擎已通过 Homebrew、安装脚本或另一个受支持的位置安装，则应用会找到并重用它 — 不会安装重复的引擎。 - 如果未找到引擎，则应用会下载最新的兼容引擎，本地安装并为您启动。 - 应用更新通过内置更新器到达，而引擎更新可以单独检查和安装。 您的笔记、索引和 AI 凭证保留在同一个本地 HomeKB 目录中，无论您使用桌面应用、CLI 还是 Web UI。 --- ## 从 CLI 使用 浏览器优先路径无需手动初始化。当您想在终端中配置提供商或将 HomeKB 指向现有的 Markdown 目录时，请使用 `homekb init`： ```bash homekb init --notes "$HOME/Documents/notes" --openai-key "$OPENAI_API_KEY" homekb reindex homekb query "我对本地优先存储有什么决定？" homekb ask "总结我关于本地优先存储的笔记。" ``` 如果没有 `--notes`，HomeKB 使用 `~/.homekb/notes/`。`homekb init` 创建数据目录和 `~/.homekb/config.toml`。Web UI 中可用的相同提供商预设可以在文件中配置；请参见 [AI 提供商配置](docs/ARCHITECTURE.md#ai-provider-presets)。 要在 macOS 上让编译在后台运行： ```bash homekb watch --install --interval 300 ``` 您也可以在应用的 **状态** 页面上启用、暂停和更改此计划。对于 Linux 和 Windows，目前请通过进程管理器运行 `homekb watch`。 --- ## 连接 AI HomeKB 向每个 MCP 客户端公开相同的工具： `kb_search` · `kb_read` · `kb_create` · `kb_update` · `kb_list` · `kb_status` · `kb_share` 一条命令将引擎注册到 Claude Code、Codex 和 Cursor（如果已安装）： ```bash homekb mcp --install ``` 传递一个值以定位一个代理（`homekb mcp --install claude` / `codex` / `cursor`）；`homekb mcp --uninstall` 再次删除注册。引擎注册其自己的绝对路径，因此即使 `~/.local/bin` 不在代理的 PATH 上，它也有效 — 手动注册裸 `homekb` 命令是经典方式，得到一个不透明的“连接失败”。 此本地 MCP 服务器在 stdio 上运行，直接调用引擎。无需连接服务。 对于另一个设备上的 Claude 或 ChatGPT，请添加官方远程 MCP 端点作为自定义连接器： ```text https://homekb-relay.wangjintaoapp.workers.dev/api/mcp ``` 运行 `homekb pair` 生成代码，然后在连接器的 OAuth 授权页面上输入。相同的一次性代码配对浏览器和 AI 客户端，并在十分钟后过期。更喜欢自己操作连接服务？请参见 [自托管连接服务](#自托管连接服务)。 --- ## 数据和信任模型 | 数据 | 存储位置 | | ------------------------- | ------------------------------------------------------------------------------------------------------- | | 笔记 | `~/.homekb/notes/` 或您配置的任何 Markdown 目录。 | | 草稿和资产 | `~/.homekb/drafts/` 和 `~/.homekb/assets/`。 | | 搜索快照 | `~/.homekb/index/index.db`，一个适合云盘同步的单一文件快照。 | | 工作数据库 | 平台应用程序数据目录，保持在数据根目录之外，以避免云同步/WAL 损坏。 | | 配置和 AI 密钥 | `~/.homekb/config.toml`。排除此文件如果您同步整个数据根目录。 | | 中继状态 | 配对关系、共享路由和 SHA-256 令牌哈希值 — 无笔记或索引。 | 有两个界限值得明确说明： - **静止状态：** 中继存储没有笔记、附件、搜索结果或索引内容。您的家用电脑仍然是事实来源。 - **传输中：** 远程请求通过中继内存后 TLS 终止。用于嵌入、摘要或答案的文本到达您配置的 AI 提供商。当前协议不是端到端加密的。自托管中继将 HomeKB 操作员从此信任路径中移除；它不会移除您选择的 AI 提供商。 默认设置使用 HomeKB 的官方托管中继，它存储零知识库数据。 [自托管连接服务](#自托管连接服务) 完全删除该操作员。 请参见 [中继信任边界](docs/ARCHITECTURE.md#relay-trust-boundary) 获取完整模型。 --- ## 引擎命令 HomeKB 遵循 Git 风格的子命令模型 — 无 REPL 和客户端依赖。 ```text homekb init 创建数据树和配置 homekb reindex 增量编译更改的笔记 homekb watch 运行计划增量编译 homekb query 语义搜索 homekb ask 从库中回答并提供引用 homekb new 创建 Markdown 笔记 homekb status 检查索引健康 homekb rebuild 为新的嵌入向量空间重建 homekb mcp 通过 stdio 提供本地 MCP homekb serve 提供本地 HTTP RPC 和资产 homekb register 注册到连接服务 homekb pair 在首次运行时引导默认连接，然后生成一次性代码 homekb share 创建、列出或撤销公共笔记链接 homekb tunnel 保持家庭与中继的连接 homekb start 启动此机器的后台服务 homekb stop 暂停后台服务（可逆；保留所有内容） homekb uninstall 从此机器上卸载引擎 — 绝不会触及您的笔记 ``` 运行 `homekb <command> --help` 获取完整选项。 在 macOS 上，`homekb watch --install` 管理与应用 **状态** 页面上公开的相同计划编译服务；任一界面都可以启用它或更改其间隔。 ### 暂停或删除引擎 三个渐进命令管理引擎在机器上的占用 — 例如备用计算机或您要移交的计算机。 **它们都不会删除您的知识库：** `~/.homekb/`（笔记、资产、索引、草稿和 `config.toml`）始终保持完整。 ```bash homekb stop # 暂停：停止后台隧道 + 编译服务。所有内容保持安装； # 随时可以恢复，远程设备只需看到家庭设备离线。 homekb uninstall # 预览完整删除 — 打印它将执行的操作且不更改任何内容。 homekb uninstall --yes # 删除引擎：注销连接服务（保留 AI 密钥）， # 停止服务，删除可再生工作数据库 + 日志，删除二进制文件。 ``` `homekb uninstall` 绝不会删除 `~/.homekb/` 下的任何内容，因此重新安装引擎并运行 `homekb reindex` 可以准确恢复您的库。Homebrew 和 Scoop 安装由包管理器留下（`brew uninstall homekb` / `scoop uninstall homekb`）。这些服务命令目前仅限 macOS； 在 Linux 和 Windows 上，请通过进程管理器停止前台 `homekb tunnel` / `homekb watch` 进程。 --- ## 开发 引擎： ```bash cd engine cargo test cargo build ``` Web UI 和 Node 中继： ```bash cd client npm install --include=dev npm run dev # Web UI：http://localhost:3000 npm run relay:dev # Node 中继：http://localhost:8787 npm test ``` Cloudflare Workers 中继： ```bash cd relay/cf npm install --include=dev npx wrangler dev ``` 桌面开发使用 Tauri 2 和相同的客户端代码。启动 Web 开发服务器，然后从 `client/` 运行 `npm run tauri dev`。 有关贡献规则和协议优先工作流程，请阅读 [AGENTS.md](AGENTS.md) 和 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。 --- ## 当前状态 - Rust 引擎、本地 MCP、Node 中继、Cloudflare Workers 中继、Web UI 和 macOS 桌面外壳已实现并一起测试。 - 已通过 claude.ai、Claude 移动应用和 ChatGPT Web 验证远程 MCP 配对。 - 引擎作为预构建的二进制文件提供，适用于 macOS（Apple Silicon + Intel）、Linux（x86_64，glibc ≥ 2.35）和 Windows（x86_64），并在每个 `engine-v*` 标签上发布，可通过 Homebrew、Scoop 或安装脚本安装。 - 后台服务安装仅限 macOS；Linux 和 Windows 目前在外部进程管理器下运行 `watch` 和 `tunnel`。 - 端到端加密、原生移动应用、冲突解决和 ChatGPT Deep Research `search`/`fetch` 工具尚未实现。 HomeKB 尚未被视为生产就绪。设计故意公开和可检查，同时分发和首次运行体验正在完成。 --- ## 自托管连接服务 默认路径使用 HomeKB 的托管 Cloudflare Workers 中继。运行自己的中继是一种可选的主权升级：它从远程请求路径中删除 HomeKB 运营的服务，同时保留相同的配对和客户端工作流程。 - 使用 [Cloudflare Workers 指南](relay/cf/README.md) 部署 Workers 目标。 - 或运行独立的 Node 目标：一个进程，一个 SQLite 文件，以及相同的协议。 将家用电脑注册到您的服务，保持其出站连接运行，并生成新的代码： ```bash homekb register --relay https://your-relay.example.com homekb tunnel --install --interval 0 # macOS；计划编译单独管理 homekb watch --install --interval 300 # macOS homekb pair ``` 如果您已经完成了快速入门，则后台服务已安装；`homekb register --relay ...` 切换服务并自动重启已安装的连接，因此您只需在之后运行 `homekb pair`。在 Linux 和 Windows 上，在您的进程管理器下运行 `homekb tunnel` 和 `homekb watch`。 对于远程 Claude 或 ChatGPT 连接器，请使用 `https://your-relay.example.com/api/mcp`。Web UI 接受相同的服务地址和配对代码。 --- ## 许可证 HomeKB 仓库拥有的源代码根据 [MIT License](LICENSE) 提供：您可以根据许可条款使用、修改、分发、 sublicense 和出售它。 MIT License 不重新授权第三方依赖。特别是，`@do-md/core-react@0.2.14` 根据 PolyForm Noncommercial License 1.0.0 许可，并保留其非商业用途限制。 在分发完整的 HomeKB 构建之前，请参阅 [第三方通知](THIRD_PARTY_NOTICES.md)。 --- ## 文档和反馈 - [架构和协议合约](docs/ARCHITECTURE.md) - [产品设计简介](docs/DESIGN-BRIEF.md) - [Cloudflare 中继部署](relay/cf/README.md) - [GitHub 问题](https://github.com/do-md/homekb/issues)