kin v0.6.4

subgraph surfaces["Access surfaces"]
    cli["kin CLI"]
    mcp["Kin MCP server"]
    editor["kin-editor for VS Code"]
end

daemon["kin daemon"]
authority["Graph authority<br/>entities, relations, changes, provenance"]
db["kin-db<br/>graph storage, snapshots,<br/>index, text and vector search"]
prims["kin-model, kin-blobs, kin-search,<br/>kin-vector, kin-infer, kin-lsp"]
vfs["kin-vfs<br/>transparent file projection"]
tools["Editors, compilers, build systems"]
git["Git<br/>import and export boundary"]
kinlab["KinLab<br/>hosted collaboration and control plane"]

people --> cli
people --> mcp
people --> editor
cli --> daemon
mcp --> daemon
editor --> daemon
daemon --> authority
authority --> db
db --> prims
authority <-->|"kin init imports, kin git export"| git
authority -->|"publish and sync"| kinlab
authority --> vfs
vfs --> tools

这些表面之下，是构成该系统的各个层级：

| 层级 | 作用 |
| --- | --- |
| **[kin-db](https://github.com/firelock-ai/kin-db)** | 图存储、快照、索引、文本搜索和向量搜索。 |
| **[kin-model](https://github.com/firelock-ai/kin-model)** | 在整个技术栈中共享的规范类型和领域模型。 |
| **[kin-blobs](https://github.com/firelock-ai/kin-blobs)** | 内容寻址的二进制大对象存储。 |
| **[kin-search](https://github.com/firelock-ai/kin-search)** | 词汇搜索原语和分阶段检索。 |
| **[kin-vector](https://github.com/firelock-ai/kin-vector)** | 向量与最近邻基础层。 |
| **[kin-infer](https://github.com/firelock-ai/kin-infer)** | 推理与嵌入基础层。 |
| **[kin-lsp](https://github.com/firelock-ai/kin-lsp)** | 语言服务器增强，为语义层提供数据。 |

这些是同一系统的实现层级，而非需要新用户自行组装的不同产品。它们中没有任何一个需要单独安装。

## 开源与 Kin 生态系统

Kin 的核心在 Apache-2.0 许可下开源：[kin](https://github.com/firelock-ai/kin)、
[kin-db](https://github.com/firelock-ai/kin-db)、[kin-vfs](https://github.com/firelock-ai/kin-vfs)
和 [kin-editor](https://github.com/firelock-ai/kin-editor)，以及配套的
kin-model、kin-blobs、kin-search、kin-vector、kin-infer、kin-lsp 和
kin-actions 库。

[KinLab](https://kinlab.ai) 是基于这一开源核心构建的专有产品，即上文所述的
托管协作与控制平面层。

同样的边界也适用于基准测试工作的共享方式。[基准测试
规范以及一个独立的、无依赖的捆绑验证器](https://github.com/firelock-ai/kin-bench-spec)
是公开的，因此无需访问生成该声明的系统即可对其加以核查。生成密封证据捆绑包的
运行器和证明基础设施（编排、固定版本发布证明门禁以及托管测量
环境）目前仍保持私有。规范和验证器先行开放；运行器可稍后开放。

## 最短的图支持路径

五条命令，而最后一条就是答案：```sh
curl -fsSL https://get.kinlab.dev/install | sh
exec "$SHELL" -l
cd /path/to/your/repository
kin init .
kin locate "where are webhook retries handled"

使用 `kin setup --intent editor` 走 VS Code 路径。用 `kin setup status --json` 确认生成的机器可读健康检查清单。

安装程序会解析[最新稳定版](https://github.com/firelock-ai/kin/releases/latest)，校验其已发布的 SHA-256 校验和，将受管二进制文件安装到 `~/.kin` 下，并启动设置。运行显式的 `agent` 意图可为检测到的受支持客户端配置内置 MCP 服务器。使用 `--intent local` 可在不进行 MCP 配置的情况下用于 CLI 和文件系统操作，或使用 `--intent editor` 走 VS Code 路径。

要仅移除由设置管理的集成，请运行 `kin setup uninstall`。对于默认的受管根目录（`~/.kin`），`kin setup uninstall --all` 还会停止所有 Kin 守护进程、移除旧的安装程序 PATH 块，并递归删除受管安装（`--dry-run` 可预览）。自定义的 `KIN_HOME` 绝不会被递归删除：请先运行账本范围的卸载，然后手动检查并删除该目录。修改过的由设置拥有的分片会阻止完全移除，除非你添加 `--force`，因此卸载绝不会静默覆盖用户编辑过的客户端或 shell 配置。在 Windows 上，CLI 会在运行进程退出后立即安排其锁定的安装目录进行删除。Windows 有意保留一个惰性的、仅限当前用户的同级权限 sidecar；保持该锁标识稳定可防止崩溃或并发的未来安装创建两个独立的变更权限。CLI 和 JSON 结果会披露这一保留的协调元数据，而不是声称零残留字节。

对于手动安装，每个归档及其 `.sha256` 文件均发布在 `https://github.com/firelock-ai/kin/releases/latest/download/` 下。动态资源名称为 `kin-macos-aarch64`、`kin-macos-x86_64`、`kin-linux-aarch64`、`kin-linux-x86_64` 和 `kin-windows-x86_64`；macOS 和 Linux 归档使用 `.tar.gz` 后缀，Windows 使用 `.zip` 后缀，如最新发布页所示。Windows zip 也是 PowerShell 安装程序和 npm 启动器所获取的文件。

npm 入口点解析相同的公共发布渠道：```sh
npm install -g @kinlab/kin@latest

你的交互式 shell 的 `PATH` 中有一个用户前缀，且仅此一处。脚本、CI 步骤、`docker exec` 以及 agent 客户端不会继承该前缀，因此请为它们提供二进制的绝对路径，而不是裸的 `kin`。有关注册形式，请参阅[与你的 agent 配合使用](#works-with-your-agent)。

一个 Homebrew tap 跟踪相同的发布渠道：```sh
brew install firelock-ai/kin/kin

在检测到的 Git 仓库中，`kin init` 以原子方式将完整的可达历史、引用、原始对象、精确的工作区树以及准入策略纳入 repository-v6 图权威。带有未提交编辑、暂存更改或未跟踪文件的工作区仍可准入：`kin init` 准入已提交状态，并披露其未准入的内容。它绝不会用精确 HEAD 快照或原始文件系统语义重建来替代。受支持的仓库本地远程 URL、refspec、分支跟踪和推送默认值会被封存到 Kin 的 Git 共存配置中；不安全、含糊或不支持的传输设置会在发布前以失败关闭方式处理。

准入还会为历史中每个受支持的实体源文件推导语义实体和关系层，并且 `kin init` 会报告其提交的持久化、按代际绑定的计数。`kin status` 报告该仓库权威视图；`kin graph status` 单独报告守护进程可变的实时查询图，该图可能包含后续推导的增强内容。查询表面在存在图拥有的增强内容时加以消费，并在缺失时报告其缺失，而不是用原始文件搜索掩盖这一缺口。

#### 哪些文件会成为实体

“受支持的实体源文件”指 Kin 的某个语言适配器认领的文件。适配器注册表是完整集合，仓库中的每个文件都通过它解析：

| 语言 | 扩展名 |
| --- | --- |
| TypeScript | `.ts`, `.tsx` |
| JavaScript | `.js`, `.jsx`, `.mjs`, `.cjs` |
| Python | `.py`, `.pyi` |
| Go | `.go` |
| Java | `.java` |
| Rust | `.rs` |
| C | `.c`, `.h` |
| C++ | `.cpp`, `.hpp`, `.cc`, `.cxx` |
| C# | `.cs` |
| Ruby | `.rb` |
| PHP | `.php` |
| Swift | `.swift` |
| Kotlin | `.kt`, `.kts` |
| HCL / Terraform | `.tf`, `.tfvars` |

当 `.h` 头文件的内容表明其为 C++ 时，会按 C++ 读取，因此 C++ 项目不会因 C 语法而丢失命名空间和模板。

其他所有内容均作为内容准入，并保持可通过历史和文本查询，但不会被解析为实体和关系。这包括 Markdown、HTML 和 CSS、SQL、YAML、JSON 和 TOML、shell 脚本、Objective-C、Scala、Elixir、Dart、Lua、R、Zig、Haskell 和 Nix。如果你的语言在该列表中，`locate` 和 `refs` 将无法在其中找到符号。

### 3. 向图提出一个真实问题```sh
kin locate "where are webhook retries handled"
kin refs ExactEntityName
kin trace ExactEntityName
kin overview

它与将另一个代理指向 MCP 服务器的不同之处在于，该规则是在代理内部强制执行的，而不是借用供应商的权限层。它拥有 Kin 的工具，外加恰好两个本地工具：`edit_file` 和 `write_file`。没有 shell、没有 grep、也没有文件读取工具，因此它无法通过原始文件搜索来回答仓库问题，而且它发明的工具会按名称被拒绝。当 Kin 报告空结果不可信时，代理会被告知答案是未知的，并得到指明的缺口，而不是断定该事物不存在。每次编辑都在 Kin 会话中的 Kin 事务内运行，因此更改带有命名代理的来源信息。先运行 `kin agent doctor --base-url <url>` 以检查两半都能应答。完整接口参见[CLI 参考](https://github.com/firelock-ai/kin/blob/main/docs/cli-reference.md#kin-agent)。

与 Claude Code、Codex、Cursor、Gemini 以及任何其他支持 MCP 的工具协作仍然是一等公民。`kin setup --intent agent` 一次即可配置它检测到的每个客户端。以下是当你更愿意直接安装 Kin 时，各客户端的单行命令。

在接入客户端之前，先在仓库中运行 `kin init .`，而不是之后。这些工具从图中应答，因此指向没有图的目录的客户端会得到一个背后空无一物的工具表面。`kin setup` 本身也说明了这一点：其往返检查会报告在它运行的目录“之上或之中没有已初始化的 Kin 仓库”，并告诉你在那里运行 `kin init` 然后重新运行 setup。

Claude Code，在会话内：```
/plugin marketplace add firelock-ai/kin
/plugin install kin@kin

Gemini CLI：```sh
gemini extensions install https://github.com/firelock-ai/kin

Kiro 接受与网页链接相同的内容：
[将 Kin 添加到 Kiro](https://kiro.dev/launch/mcp/add?name=kin&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40kinlab%2Fkin%22%2C%22mcp%22%2C%22start%22%5D%7D)。

Cline 接受下面这个标准条目，而不是单行命令。其 CLI 读取
`~/.cline/mcp.json`。在 VS Code 扩展中，打开 MCP Servers 面板，然后
打开 Configure 选项卡，再点击 Configure MCP Servers，并在其中添加该条目。

其他所有读取标准 MCP 配置的客户端都接受此条目：```json
{
  "mcpServers": {
    "kin": { "command": "npx", "args": ["-y", "@kinlab/kin", "mcp", "start"] }
  }
}

结果为 `PASS`、`NEEDS ATTENTION` 或 `WOULD BLOCK`，并附带从图中推导出的影响 Kin、修复所需上下文，以及两者背后的证据。作者身份是声明性的，而非经过验证。该命令不会阻止你的合并或改变图状态。它将证据交给人工或 CI 策略，然后就此打住。

## Kin 与 Git 的关系

与 Git 并行。仓库权威随时间演进。在棕地采用期间，Git 仍然是一个显式的导入/导出互操作边界；它从不回答 Kin 运行时查询，也不修复缺失的图真相。

- `kin init` 导入完整的可达 Git 历史及精确的父边。
  Kin 刻意没有部分历史或仅快照的初始化模式。
- 导入后，Kin 的图拥有仓库身份、树状态、历史、引用和语义关系。文件系统和 Git 视图都是投影。
- `kin git export --output ../repo.git` 从一个图拥有的权威代写入一个新的裸 Git 投影。它不查阅工作文件或环境中的 `.git/` 对象存储，并拒绝已存在或仓库内的目标位置。对象、引用和目录在无替换目标发布被确认前全部刷新。基于能力锚定的发布目前在 Unix 主机上可用；其他主机在创建导出前即拒绝。

这让团队能够迁移现有仓库，同时不放弃其编辑器、编译器、构建系统或 Git 互操作性，而 Kin 则成为权威。

## 平台与成熟度

核心运行时和文件系统投影具有不同的支持边界：

| 平台 | 核心 Kin 运行时 | `kin-vfs` 投影 |
| --- | --- | --- |
| macOS，Apple Silicon 和 Intel | 原生图、向量、守护进程、设置、MCP 和审查界面随发布归档提供。 | 在两种架构上均已提供并经过测试。它使用 `DYLD_INSERT_LIBRARIES`；受 SIP 保护或加固的程序可能拒绝注入。 |
| Linux x86_64 和 arm64 | `kin` 和 `kin-daemon` 是静态 musl 构建，旨在 glibc 和 musl 发行版上运行。 | 公共 VFS 可执行文件和 shim 是 GNU/glibc 构建，而非 musl 构建。它们针对固定的 glibc 下限 2.31 构建，并链接 OpenSSL 3，因此投影主机需要两者；Debian 12 可加载它们，而 Alpine 及其他 musl 发行版不支持作为投影主机。发布版拒绝发布其二进制文件要求超过该 glibc 下限的 Linux 归档。arm64 发布验证在 Ubuntu 24.04 上运行。 |
| 原生 Windows x86_64 | 早期支持：仓库可被接纳，图和词法查询可原生回答，但 MCP 和审查工作流尚未被安装验证端到端覆盖。WSL2 仍是完整 Kin 的推荐路径。 | 不提供。使用满足投影 glibc 边界的 Linux 发行版的 WSL2。 |

在上述所有情况下，图都是权威。shim、NFS 挂载、FUSE 挂载和 Windows ProjFS 是将该真相视为文件的四种方式，Kin 通过探测此主机可运行什么来选择：在可用处使用挂载，因为内核为其服务且任何进程都无法将其剥离，注入的 shim 作为 macOS 和 Linux 上的兼容性回退，而 ProjFS 在 Windows 上领先，因为那里不存在 shim。`kin vfs on` 启用所选方式，`kin vfs off` 停用它，`kin doctor` 带有一行说明当前生效的是哪种方式及其是否正常工作。在缺少某种模式的地方，Kin 会打印在你的平台上安装或启用它的确切命令行。
[docs/projection.md](https://github.com/firelock-ai/kin/blob/main/docs/projection.md) 包含完整的按平台表格。

首次索引会读取完整的可达 Git 历史，因此 `kin init` 在大型或长期存在的仓库上需要数分钟而非数秒，之后嵌入才开始。`init` 返回后，守护进程会在后台继续准备，大型仓库上的首次代理调用可能需要明显更长的时间来回答。

有界的 arm64 测试发现核心图和词法路径在 512 MB 下可用，但完整嵌入会下载约 522 MB 的模型，目前需要 2 GB 作为安全运行下限；1 GB 是不安全的边缘，512 MB 可能在嵌入期间终止。这些是观察到的 alpha 约束，而非普遍性的容量承诺。

成功的 `kin --version` 仅证明核心二进制文件可运行。它不证明 VFS 兼容性或实时的图支持投影。在受支持的 Unix 主机上，使用 `kin vfs status`，它会探测每种投影模式并打印实际生效的内容，然后使用 `kin setup status` 和真实的 `kin-vfs exec --workspace . -- <command>` 启动。VFS 启动器包含一个插入金丝雀，并在操作系统剥离 shim 时报告。
[kin-vfs README](https://github.com/firelock-ai/kin-vfs#current-platform-and-package-boundaries) 包含完整边界。

发布资产以校验和发布，发布工作流在其支持的运行器矩阵上运行匿名安装、守护进程/MCP、嵌入和真实的图支持 VFS 投影检查。该工作流本身是公开的：
[安装验证](https://github.com/firelock-ai/kin/actions/workflows/install-proof.yml)。绿色发布确立的是那些确切的工件和环境；它并非声称每个发行版、工具或仓库形态都已覆盖。

## 常见问题

### Kin 会取代 Git 吗？

与 Git 并行。仓库权威随时间演进。在棕地采用期间，Git 仍然是一个显式的导入/导出互操作边界，因此团队可以迁移现有仓库，同时不放弃其编辑器、编译器、构建系统或 Git 互操作性。

### 我的代码会离开我的机器吗？

Kin 将本地仓库工作保留在你的环境中，因此仓库摄取、图存储和本地查询都在那里运行。KinLab 是一个独立产品，在明确的访问和早期访问协议下增加托管协作。

### 它与哪些代理兼容？

与 Claude Code、Codex、Cursor、Gemini 以及任何支持 MCP 的工具保持一流兼容。`kin setup --intent agent` 一次配置它检测到的每个客户端。

### 它会阻止合并吗？

审查是建议性的，因此它标记风险而不阻止，合并决定仍由你的团队做出。`kin review shadow` 将证据交给人工或 CI 策略，然后就此打住。

## 验证姿态

已发布的预注册 Multi-SWE-Bench Go 验证包固定在一个较旧的构建上，而非移动中的最新版本，且不确立广泛的性能、令牌节省或类别获胜声明。比较性结果在此暂不提供，等待独立验证。

在[公共验证包](https://firelock.ai/labs/kin-proof)中阅读方法论、任务集、构建身份和工件。将超出该测量范围的主张视为假设，直到它们拥有自己的可复现验证。

## 写作

构建 Kin 的工程笔记，写下来以便陌生人可以复用，发布在 [kinlab.ai/blog](https://kinlab.ai/blog)，订阅源位于
[kinlab.ai/rss.xml](https://kinlab.ai/rss.xml)。

- [那个因为什么都没测量而通过的检查](https://kinlab.ai/blog/checks-that-cannot-fail)
- [你的代码搜索显示没有使用它。你能删除它吗？](https://kinlab.ai/blog/empty-answer-safe-to-delete)

## 学习与贡献

- [快速入门和高级配置](https://github.com/firelock-ai/kin/blob/main/docs/quickstart.md)
- [存储大小及其驱动因素](https://github.com/firelock-ai/kin/blob/main/docs/store-size.md)
- [MCP 工具参考](https://github.com/firelock-ai/kin/blob/main/docs/mcp-tools.md)
- [语言支持及各层级提取内容](https://github.com/firelock-ai/kin/blob/main/docs/language-support.md)
- [环境变量参考](https://github.com/firelock-ai/kin/blob/main/docs/env-vars.md)
- [图优先论点](https://github.com/firelock-ai/kin/blob/main/docs/thesis.md)
- [写入权威模型及其过渡状态](https://github.com/firelock-ai/kin/blob/main/docs/write-authority-model.md)
- [GitHub Discussions](https://github.com/firelock-ai/kin/discussions)
- [错误报告和功能请求](https://github.com/firelock-ai/kin/issues/new/choose)
- [贡献指南](https://github.com/firelock-ai/kin/blob/main/CONTRIBUTING.md)
- [私有安全报告](https://github.com/firelock-ai/kin/blob/main/SECURITY.md)

## 许可证

[Apache-2.0](https://github.com/firelock-ai/kin/blob/main/LICENSE)。

<p align="center"><em>记住自己的软件。</em></p>