内容
# KB-1 本地版
KB-1 本地版是一个开源的、本地优先的知识库，适用于个人和代理在同一个保险库中工作。您的 Markdown 文件保留在您的机器上，并始终是可靠的来源。
访问 [kb-1.ai](https://kb-1.ai) 以了解更多关于 KB-1 的信息。开源本地产品现已可用；付费的 KB-1 云服务即将推出，暂未对公众开放。
> [!IMPORTANT]
> 当前公开版本为 KB-1 本地版。KB-1 云身份、组织访问、远程中继和托管服务暂未对公众开放注册。
请参阅 `VISION.md` 和 `docs/architecture/` 以获取当前产品和架构文档。
> [!NOTE]
> KB-1 本地版正在积极开发中。在稳定版本发布之前，命令和接口可能会在修订之间发生变化。
## 免费本地版现已开放，付费云服务即将推出
开源守护进程包括本地保险库引擎、Web 应用程序、API 和 MCP 端点。您可以将其用于个人或开发工作流，无需 KB-1 帐户或订阅。
KB-1 云服务暂未公开可用。 当它开放时，付费云服务将添加协调和操作层，以便在单个本地机器不再足够时使用：
- **云身份和组织访问：** 为批准的个人和代理提供身份验证访问，绑定到云身份和组织成员资格，以及团队存在感，而不是将每个人视为受信任的本地调用者。
- **身份验证远程访问：** 通过安全的云中继连接自托管保险库，无需直接将守护进程端口暴露给公共互联网。您的机器仍然是可靠的内容权威。
- **托管服务（计划中）：** 选择 KB-1 托管服务，当其可用时，如果您不想操作始终在线的守护进程。KB-1 将运行隔离的保险库环境，并管理其生命周期和持久性。
简而言之，付费服务将提供共享身份、团队访问、远程访问和可选的托管操作。它不会限制对您自己的文件的本地访问。 请在 [kb-1.ai](https://kb-1.ai) 上了解更多信息。
当前和计划中的部署模式是：
- **仅本地：** 运行开源守护进程并连接本地代理，无需 KB-1 云登录。守护进程不提供云用户、组织、团队存在感或按用户权限；访问仅限于守护进程主机和操作员故意提供的任何私有网络路径。
- **云连接自托管（即将推出）：** 将守护进程和持久的保险库文件保留在您控制的机器上，然后添加 KB-1 云身份、组织成员资格、中继路由和批准的非本地用户和代理的访问权限。
- **托管（计划中）：** 使用 KB-1 云，而 KB-1 运行存储托管保险库的守护进程。托管可用性将单独宣布。
云服务是本地用户的附加功能。无需 KB-1 云登录即可运行守护进程、使用其本地 Web 应用程序或将代理连接到其本地 MCP 端点。
## 安全模型
KB-1 本地版是一个受信任的本地服务，而不是多用户服务器。它不为其本地 HTTP、WebSocket 或 MCP 接口添加身份验证或按用户授权。保持其绑定到默认的环回地址 (`127.0.0.1`)，除非您故意将其置于私有、访问受控的网络路径后面。不要将守护进程端口直接暴露给公共互联网。
保险库默认位于 `~/.kb1/vaults/` 下。在迁移或重大升级之前，请备份 `~/.kb1/`。有关报告和部署指南，请参阅 [安全](SECURITY.md)。
## 先决条件
- Node.js 20.19.x、22.12+ 或 24+。CI 使用 Node 24。
- Corepack，随当前 Node.js 版本附带。
- Git。
在安装依赖项之前，请启用仓库声明的包管理器：
```bash
git clone https://github.com/metatheoryinc/kb-1-daemon.git
cd kb-1-daemon
corepack enable
corepack install
pnpm install
```
工作区使用 `package.json` 中声明的 pnpm 版本；请勿使用 npm 或 Yarn 安装依赖项。
下面的命令示例使用 POSIX shell。在 Windows PowerShell 上，请在命令之前使用 `$env:NAME="value"` 设置环境变量，例如 `$env:KB1_PORT="17382"; pnpm dev`。
## 从源码快速入门
从检出运行本地守护进程和 Web UI：
```bash
pnpm dev
```
默认运行将守护进程状态存储在 `~/.kb1` 中。对于一次性运行，请使用隔离的主目录：
```bash
KB1_HOME=$(mktemp -d) pnpm dev
```
| 接口 | URL | 备注 |
| --- | --- | --- |
| 应用程序（UI + API） | http://127.0.0.1:7382 | 守护进程前门提供两者；API 位于 `/api/*` 下 |
| MCP | http://127.0.0.1:7382/mcp | 本地代理的流式 HTTP MCP 端点 |
| Storybook | http://localhost:6006 | `pnpm storybook`；如果 6006 被占用，请传递 `-p <port>` |
启动后，请验证守护进程是否健康：
```bash
curl http://127.0.0.1:7382/api/health
```
然后在浏览器中打开 http://127.0.0.1:7382。新的守护进程主目录会创建一个启动器 `demo-vault`，因此 UI 立即有内容。
## 连接代理
为 MCP 兼容的代理提供本地端点：
```text
http://127.0.0.1:7382/mcp
```
对于 Claude Code：
```bash
claude mcp add kb-1 --transport http http://127.0.0.1:7382/mcp
```
要求代理调用 `list_vaults`，然后将返回的 `id` 作为其余 KB-1 工具所需的 `vaultId` 参数。
端口/环境变量覆盖：`KB1_PORT`（守护进程）、`KB1_HOST`（绑定主机）、`KB1_WEB_PORT`（Vite 开发服务器，默认为 `5173`）、`KB1_WEB_PROXY_TARGET`（可选的 Vite 开发代理目标）和 `KB1_HOME`（守护进程状态目录，默认为 `~/.kb1`）。中继/隧道从 `KB1_RELAY_URL` 加 `KB1_RELAY_TOKEN` 运行；可选的守护进程身份字段为 `KB1_DAEMON_VERSION` 和 `KB1_DAEMON_BUILD`。`KB1_ACTOR_DEFAULT` 控制默认本地参与者属性（`user` 或 `unknown`），而 `KB1_HISTORY_COALESCE_WINDOW_MS` 控制笔记历史提交合并。
在首次启动时，旧的 `~/.kb2` 主目录将被复制到 `~/.kb1`。在删除源之前，守护进程会检查目标中每个常规源文件是否存在于相同的相对路径且具有相同的字节长度。符号链接和空目录不会被检查，并且预先存在的主目录可能包含其他文件。如果您需要内容级验证或回滚副本，请单独进行备份。运行时配置仅限 KB-1。
## Docker
Docker 是第二种运行方式。由于 KB-1 本地版不提供本地身份验证，请仅将容器端口发布到环回地址：
```bash
docker build -f apps/daemon/Dockerfile -t kb-1-daemon .
docker run --rm \
-p 127.0.0.1:7382:7382 \
-v kb1-home:/data/kb1 \
kb-1-daemon
```
然后应用程序可在 http://127.0.0.1:7382 访问。不要用 `0.0.0.0` 替换环回主机，除非您已添加访问受控的私有网络边界。更多容器和迁移详细信息请参见 [打包路径](docs/packaging/daemon.md)。
## 常见设置问题
- `pnpm: command not found`：从此仓库运行 `corepack enable` 和 `corepack install`，然后重试 `pnpm install`。
- 意外的安装或构建错误：确认 `node --version` 报告 20.19.x、22.12+ 或 24+。
- 端口 `7382` 已被占用：使用另一个守护进程端口运行，例如 `KB1_PORT=17382 pnpm dev`。
- Vite 端口 `5173` 已被占用：使用另一个 Web 开发端口运行，例如 `KB1_WEB_PORT=5174 pnpm dev`。
- 您想要一个干净的试验状态而不影响现有数据：运行 `KB1_HOME=$(mktemp -d) pnpm dev`。
- Docker 启动但浏览器无法连接：确认映射包括 `127.0.0.1:7382:7382`，然后打开 http://127.0.0.1:7382。
## 贡献者检查
在打开拉取请求之前，请运行完整的工作区检查：
```bash
pnpm check
```
`pnpm check` 运行工作区类型检查、测试和构建。它对贡献者有用，但仅用于本地尝试应用程序不需要。
## 中继/隧道
> [!NOTE]
> 守护进程侧的中继客户端和协议包含用于开发和集成工作。KB-1 云中继访问暂未公开可用。
中继支持是守护进程侧的可选功能。要将守护进程指向中继端点，请设置 `KB1_RELAY_URL` 和 `KB1_RELAY_TOKEN`；仅提供其中一个将导致启动配置错误。`KB1_DAEMON_VERSION` 和 `KB1_DAEMON_BUILD` 是中继注册期间发送的可选身份元数据。
当存在中继配置时，守护进程在本地 HTTP 服务器启动后打开出站 WebSocket 连接。中继端点接收到用户的机器上没有传入端口暴露。内部隧道客户端将稳定的线路路径附加到配置的中继 URL：用于控制套接字的 `/__kb1_tunnel/control` 和用于 WebSocket 回拨流的 `/__kb1_tunnel/dialback`。
本地生命周期 API 是：
- `GET /api/relay/status`
- `POST /api/relay/connect`
- `POST /api/relay/disconnect`
状态响应使用 `{ ok: true, relay }`，其中 `relay` 具有 `configured`、`started`、`controlConnected` 和 `reconnectScheduled`。如果未配置中继，状态保持可读，`configured: false`，`connect` 返回 `relay_not_configured`，`disconnect` 是无操作。
中继内容请求仍使用正常的保险库范围 API 接口。没有默认保险库假设：调用者首先发现保险库，然后地址特定保险库 ID。中继写入可以使用 `x-kb1-actor` JSON 头属性上游参与者，类型为 `kind: "user"` 或 `kind: "integration"`，以及可选的 `id`、`name` 和 `client` 字符串。没有该头，守护进程使用 `KB1_ACTOR_DEFAULT`。
## 本地 API 原语
`GET /api/vaults` 是发现原语。它将每个服务的保险库列为 `{ id, displayName, metadata? }`；`id` 是每个内容 API 使用的保险库 slug。守护进程对内容路由没有隐含的默认保险库。
保险库管理位于 `POST /api/vaults`、`PUT /api/vaults/:id`（仅重命名显示名称）、`PUT /api/vaults/:id/metadata` 和 `DELETE /api/vaults/:id`。删除所有保险库是有效的：`GET /api/vaults` 然后返回一个空列表，直到创建新的保险库。
新创建的保险库从捆绑的启动器工具包中播种，当它们没有用户内容时。空主目录的首次启动会以这种方式创建 `demo-vault` 启动保险库。现有或迁移的保险库不会被重新播种或覆盖。
`POST /api/vaults/:id/ops/flush` 是单个保险库的备份原语。它强制保险库中的所有脏活文档会话通过现有的文档会话物化路径，并仅在写入完成后返回：
```json
{ "ok": true, "flushed": 1, "durableAsOf": "2026-06-12T09:00:00.000Z" }
```
在快照或同步保险库之前调用它。干净的保险库返回 `flushed: 0`。如果任何会话无法持久化，响应使用与 API 其余部分相同的规范化失败语法，现有保存警告事件路径仍然触发。
`GET /api/vaults/:id/events` 是单个保险库的工具原语。它是观察者、备份触发器和实时树刷新的服务端事件流。事件报告更改类型、保险库相对路径、参与者属性和时间戳，以获取已持久化的内容、文件/文件夹创建/删除/移动、文件夹元数据更改、外部文件更改和持久化失败/恢复。事件负载永远不会携带文件内容；消费者通过正常读取 API 获取内容。
内容路由也是保险库范围的：例如，`GET /api/vaults/:id/tree`、`GET /api/vaults/:id/search?q=...`、`GET|PUT|DELETE /api/vaults/:id/files/{path}`、`POST /api/vaults/:id/files/{path}/splice`、`append`、`prepend` 和 `move`、`GET|PUT /api/vaults/:id/raw/{path}` 用于附件、`/api/vaults/:id/folders` 下的文件夹路由，以及 `/api/vaults/:id/files/{path}/yjs` 处的 Yjs 套接字。
请注意，笔记历史记录是 Git 支持的，并且在 `GET /api/vaults/:id/files/{path}/history` 处最佳努力提供。历史记录跟随 KB-1 在 Git 能够提供历史记录的情况下移动提交到重命名。MCP 历史记录对齐仍是一个开放的决定。
## MCP
守护进程在与应用程序和 API 相同的环回端口上托管流式 HTTP MCP 服务器，位于 `/mcp`。启动守护进程，然后将其添加到 Claude Code：
```bash
KB1_HOME=$(mktemp -d) KB1_PORT=17992 pnpm dev:daemon
claude mcp add kb-1 --transport http http://127.0.0.1:17992/mcp
```
可用工具：`list_vaults`、`vault_info`、`list_files`、`list_attachments`、`read_attachment`、`upload_attachment`、`read_note`、`create_note`、`edit_note`、`append_note`、`prepend_note`、`delete_note`、`move_note`、`create_folder`、`delete_folder`、`move_folder`、`get_folder_metadata`、`set_folder_metadata`、`search`。
工作流程：首先调用 `list_vaults`，然后将返回的 `id` 作为其他工具所需的 `vaultId` 参数。
`read_note` 返回一个 `baseline` 用于编辑循环。`edit_note` 使用与 REST API 相同的锚定拼接合约：过时基准返回 `stale_doc` 和当前内容，以及模糊匹配返回 `match_count`，而持久化失败会显示为不写入审计行。`list_files` 包括内联文件夹元数据。`set_folder_metadata` 持久化耐用文件夹颜色/图标元数据，并作为 `mcp_client` 进行审计。`move_note` 和 `move_folder` 不会重写链接。附件工具在保险库相对路径上操作：`list_attachments` 发现它们，`read_attachment` 返回图像块或 base64 元数据，而 `upload_attachment` 编写小型内联 base64 附件。
对齐目标：UI 可达的服务支持的操作要么具有跨相同保险库服务边界的 MCP 工具，要么列为 `docs/architecture/mcp-parity.md` 中的显式空白。目前开放的对齐决策包括保险库生命周期 CRUD 和笔记历史记录。
## 其他命令
```bash
pnpm smoke:yjs # 针对正在运行的守护进程的双客户端 Yjs 编辑烟雾测试
pnpm storybook # 在端口 6006 上进行组件开发
```
## 布局
- `apps/daemon` — 本地服务器 (`kb1d`)，唯一的运行时写入者
- `apps/web` — 本地 Web UI，由守护进程提供服务
- `packages/doc-session` — 由 Markdown 文件支持的 Yjs 文档会话
- `packages/editor` — 纯文本编辑和提及/装饰器支持
- `packages/local-mcp` — 保险库服务上的流式 HTTP MCP 工具
- `packages/tunnel-client` — 守护进程侧的中继/隧道客户端
- `packages/tunnel-protocol` — 共享的中继/隧道协议类型
- `packages/ui` — 组件库 + Storybook
- `packages/vault-core` — 文件系统支持的保险库操作和历史记录
- `packages/vault-service` — 由守护进程路由和 MCP 组成的服务边界
- `docs/architecture/` — 本地产品的架构笔记和不变式
## 项目政策
- [贡献](CONTRIBUTING.md)
- [支持](SUPPORT.md)
- [安全](SECURITY.md)
- [行为准则](CODE_OF_CONDUCT.md)
- [发布流程](docs/releasing.md)
- [Apache 2.0 许可证](LICENSE)
