# https://github.com/RodCor/kimetsu 项目说明书

生成时间：2026-07-05 12:50:48 UTC

## 目录

- [项目概览与 monorepo 结构](#page-1)
- [Brain 存储、嵌入与检索管线](#page-2)
- [主机代理集成、CLI 与 MCP / 嵌入守护进程接口](#page-3)
- [Brain 分享、Kimetsu Remote、基准测试与常见运维问题](#page-4)

<a id='page-1'></a>

## 项目概览与 monorepo 结构

### 相关页面

相关主题：[Brain 存储、嵌入与检索管线](#page-2), [主机代理集成、CLI 与 MCP / 嵌入守护进程接口](#page-3), [Brain 分享、Kimetsu Remote、基准测试与常见运维问题](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/RodCor/kimetsu/blob/main/README.md)
- [Cargo.toml](https://github.com/RodCor/kimetsu/blob/main/Cargo.toml)
- [CHANGELOG.md](https://github.com/RodCor/kimetsu/blob/main/CHANGELOG.md)
- [crates/kimetsu-core/src/lib.rs](https://github.com/RodCor/kimetsu/blob/main/crates/kimetsu-core/src/lib.rs)
- [crates/kimetsu-core/src/paths.rs](https://github.com/RodCor/kimetsu/blob/main/crates/kimetsu-core/src/paths.rs)
- [npm/kimetsu/README.md](https://github.com/RodCor/kimetsu/blob/main/npm/kimetsu/README.md)
- [crates/kimetsu-remote/src/lib.rs](https://github.com/RodCor/kimetsu/blob/main/crates/kimetsu-remote/src/lib.rs)
</details>

# 项目概览与 monorepo 结构

Kimetsu 是一个面向 AI 编码代理（coding harness）的持久化记忆层。其核心目标是消除代理在会话内对仓库与历史上下文的"重复探索"成本，通过本地 `brain.db` 知识库向宿主 CLI（Claude Code、Codex、Pi 等）按需注入语义化上下文。当前发布版本为 **v2.5.0**，仓库根目录同时管理 Rust 工作区与 npm 发布包 资料来源：[README.md:1-40]()。

## 项目定位与版本演进

Kimetsu 从 v0.8 系列开始打通 npm 分发通道，使 Rust 项目不必依赖本地工具链即可安装；v0.9 引入了 SessionEnd 自动蒸馏器（distiller）来收割会话记忆 资料来源：[CHANGELOG.md:1-60]()。v1.0 引入跨编码器远程重排阶段（cross-encoder rerank），标志 `brain.db` 从纯文本检索升级为带 ANN 索引与 reranker 的混合检索架构 资料来源：[CHANGELOG.md:60-120]()。v2.0 的旗舰方向是"不再重复探索"——既覆盖 `brain.db`，也覆盖代码仓库内的已知信息，并新增可插拔的存储后端；旧版 `project.toml` 与 `brain.db` 会在打开时自动完成 schema v3 → v6 的原地迁移，无需手工操作 资料来源：[CHANGELOG.md:120-180]()。

## Monorepo 工作区结构

仓库根 `Cargo.toml` 定义了 Cargo Workspace，统一管理多个 crates 之间的依赖与版本号。各子 crate 的职责如下：

| 子 crate | 角色 | 关键命令 |
|---|---|---|
| `kimetsu-core` | 核心库：路径解析、`brain.db` schema、嵌入抽象、telemetry | 被 `kimetsu` 与 `kimetsu-remote` 复用 |
| `kimetsu` | CLI 入口，`bin` crate | `kimetsu brain …`、`kimetsu plugin install <target>` |
| `kimetsu-remote` | 远程服务（含 MCP 适配） | `kimetsu-remote serve --reranker …` |

`kimetsu-core` 自身已作为独立 crate 发布到 crates.io（issue #22 提及其版本与 npm 包的版本协调问题）资料来源：[crates/kimetsu-core/src/lib.rs:1-40]()。`crates/kimetsu-core/src/paths.rs` 集中处理项目根目录、数据库路径与配置文件的定位逻辑，是所有上层命令共享的路径原语层 资料来源：[crates/kimetsu-core/src/paths.rs:1-60]()。

```mermaid
flowchart TB
    subgraph Workspace["Cargo Workspace (repo root)"]
        CLI["kimetsu (CLI bin)"]
        Remote["kimetsu-remote (server)"]
        Core["kimetsu-core (lib)"]
        CLI --> Core
        Remote --> Core
    end
    subgraph Distribution
        Cratesio["crates.io"]
        NPM["npm (kimetsu / kimetsu-ai)"]
    end
    Core --> Cratesio
    CLI --> NPM
```

## 特性标记与测试矩阵

为了保持默认构建轻量，`kimetsu-core` 与相关 crate 通过 cargo feature flag 控制重型依赖。`embeddings` 特性门控了守护进程、重排器与 ANN 索引的单元测试——这意味着 `cargo test --workspace` 在默认特性下不会执行它们。CI 现状问题（issue #22）指出，目前缺少一个 Linux job 来运行 `cargo test --workspace --features embeddings`，使得相关测试只能手动跑 资料来源：[Cargo.toml:1-80]()。

## 分发与安装路径

仓库采用双渠道发布：Rust crate 通过 crates.io 安装，CLI 二进制则通过 npm 包装层分发，后者按 esbuild/turbo 模型拆分 per-platform 包（`@kimetsu-ai/linux-x64`、`@kimetsu-ai/darwin-arm64`、`@kimetsu-ai/win32-x64` 等），平台包在安装时由 `npm install -g kimetsu-ai` 自动选用 资料来源：[npm/kimetsu/README.md:1-40]()。`kimetsu-remote` 单独提供 `serve` 子命令，可在 MCP 集成下被宿主代理以 HTTP/HTTP+SSE 方式调用，对应 `kimetsu_brain_context` 工具入口 资料来源：[crates/kimetsu-remote/src/lib.rs:1-60]()。

## 已知边界与社区关注点

几个近期 issue 折射出 monorepo 结构带来的边界条件：`kimetsu brain bench --remote` 在 `--remote` 模式下多次指定 `--embedders` 时会因 `OnceLock` 单例在子进程内不可重置，导致第二轮组合使用了第一组的嵌入向量（issue #23）；`brain export` 当前不会剥离 `(context: …)` 后缀，分享出去存在隐私泄漏风险（issue #24）。两者都涉及核心 crate 的全局状态与序列化语义，是后续重构需要重点关注的耦合点 资料来源：[CHANGELOG.md:180-220]()。

---

<a id='page-2'></a>

## Brain 存储、嵌入与检索管线

### 相关页面

相关主题：[主机代理集成、CLI 与 MCP / 嵌入守护进程接口](#page-3), [Brain 分享、Kimetsu Remote、基准测试与常见运维问题](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [crates/kimetsu-brain/src/lib.rs](https://github.com/RodCor/kimetsu/blob/main/crates/kimetsu-brain/src/lib.rs)
- [crates/kimetsu-brain/src/schema.rs](https://github.com/RodCor/kimetsu/blob/main/crates/kimetsu-brain/src/schema.rs)
- [crates/kimetsu-brain/src/embeddings.rs](https://github.com/RodCor/kimetsu/blob/main/crates/kimetsu-brain/src/embeddings.rs)
- [crates/kimetsu-brain/src/ann.rs](https://github.com/RodCor/kimetsu/blob/main/crates/kimetsu-brain/src/ann.rs)
- [crates/kimetsu-brain/src/scoring.rs](https://github.com/RodCor/kimetsu/blob/main/crates/kimetsu-brain/src/scoring.rs)
- [crates/kimetsu-brain/src/reinforce.rs](https://github.com/RodCor/kimetsu/blob/main/crates/kimetsu-brain/src/reinforce.rs)
</details>

# Brain 存储、嵌入与检索管线

## 概述

`kimetsu-brain` 是 kimetsu 的记忆与检索子系统，承担三大职责：(1) 把 Agent 在交互过程中产生的"记忆条目"(memories) 持久化到本地 SQLite 数据库 `brain.db`；(2) 在写入时为每条记忆生成稠密向量 (embedding)，在查询时为提示词生成同维向量；(3) 在检索阶段结合 ANN 最近邻、关键词打分与远程 cross-encoder 重排，最终向 Agent 返回按相关度排序的上下文片段。`kimetsu-brain` 自身是 lean 默认构建；embedder 模型加载、ANN 索引和重排器统一位于 `--features embeddings` feature gate 之后，对应 CI 中需要单独跑的 embeddings-gated 测试套件 ([issue #22](https://github.com/RodCor/kimetsu/issues/22))。

## 存储层与 Schema

`schema.rs` 维护 `brain.db` 的全部表结构与迁移逻辑。v2.0 起 schema 已演进到 v6，向前兼容老版本 `project.toml` 与 `brain.db`，在打开时自动执行 v3 → v6 的迁移。核心实体包括 `memories`（记忆正文、来源会话、时间戳）、`embeddings`（与 memory 1:1 关联的向量序列化行）、`context_served`（v1.5.0 新增的遥测表，保存每次被召回的原始查询文本），以及强化学习使用的反馈表。schema 是整条管线的"事实源"，embeddings 表与 memories 表通过 `memory_id` 强绑定，确保向量与文本不会脱钩 ([cr: kimetsu-brain/src/schema.rs:1-120](https://github.com/RodCor/kimetsu/blob/main/crates/kimetsu-brain/src/schema.rs))。

## 嵌入管线

`embeddings.rs` 封装了 embedder 的运行时单例。进程内使用 `OnceLock` 缓存已初始化的 embedder，避免重复加载 ONNX/HF 模型。暴露 `embed(text) -> Vec<f32>` 与 `embed_batch(texts)` 两个入口，写入路径在 `lib.rs` 的 `record` 系列函数中被调用。注意：bench 子命令 (`brain bench --remote`) 在 `--embedders a,b,c` 多 embedder 串行场景下，进程级单例会先被第一个 combo 初始化，后续 combo 的记忆会被错误地以 combo 1 的向量播种，造成跨模型行污染 ([issue #23](https://github.com/RodCor/kimetsu/issues/23))。导出子命令 `brain export` 当前按字面写入 `(context: …)` 后缀，存在共享/发布场景的隐私风险 ([issue #24](https://github.com/RodCor/kimetsu/issues/24))。

## 检索与打分管线

检索由三层组成，按调用顺序串联：

1. **ANN 召回**：`ann.rs` 实现近似最近邻索引（当前为内存 HNSW/暴力混合），用查询向量在 `embeddings` 表上做 top-K 召回。
2. **本地打分**：`scoring.rs` 在 ANN 召回集合上叠加 BM25/词项打分，并按 memory 的 `kind`、`source` 等字段做先验加权。
3. **远程重排**：`lib.rs` 在 `kimetsu_brain_context` 调用出口处把候选集送至 `kimetsu-remote serve`，由其 cross-encoder reranker（默认 `jina-reranker-v1-tiny-en`，可用 `--reranker off` 关闭）做最终排序 ([cr: kimetsu-brain/src/lib.rs:200-320](https://github.com/RodCor/kimetsu/blob/main/crates/kimetsu-brain/src/lib.rs))。

```mermaid
flowchart LR
    Q[查询文本] --> EMB[embeddings.rs<br/>embed]
    EMB --> ANN[ann.rs<br/>ANN top-K]
    ANN --> SC[scoring.rs<br/>BM25 + 先验]
    SC --> RR[kimetsu-remote<br/>cross-encoder]
    RR --> CTX[返回 context.served]
    CTX --> RF[reinforce.rs<br/>反馈闭环]
```

## 强化学习回路

`reinforce.rs` 把每次 `context.served` 与 Agent 的下游反馈（如 token 选择、用户接受/拒绝）关联，回写到 `feedback` 表，并在下一次 `record` 时用于：(a) 调整 `scoring.rs` 中各 memory 的先验权重；(b) 触发对低质/陈旧条目的衰减。这构成 v1.0.0 引入的 proactive recall 能力——让越被复用且被正向反馈的记忆越靠前，避免 Agent 重复探索 ([cr: kimetsu-brain/src/reinforce.rs:1-90](https://github.com/RodCor/kimetsu/blob/main/crates/kimetsu-brain/src/reinforce.rs))。

---

<a id='page-3'></a>

## 主机代理集成、CLI 与 MCP / 嵌入守护进程接口

### 相关页面

相关主题：[Brain 存储、嵌入与检索管线](#page-2), [Brain 分享、Kimetsu Remote、基准测试与常见运维问题](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [crates/kimetsu/src/main.rs](https://github.com/RodCor/kimetsu/blob/main/crates/kimetsu/src/main.rs)
- [crates/kimetsu/src/cli.rs](https://github.com/RodCor/kimetsu/blob/main/crates/kimetsu/src/cli.rs)
- [crates/kimetsu-agent/src/lib.rs](https://github.com/RodCor/kimetsu/blob/main/crates/kimetsu-agent/src/lib.rs)
- [crates/kimetsu-agent/src/harness.rs](https://github.com/RodCor/kimetsu/blob/main/crates/kimetsu-agent/src/harness.rs)
- [crates/kimetsu-agent/src/claude_code.rs](https://github.com/RodCor/kimetsu/blob/main/crates/kimetsu-agent/src/claude_code.rs)
- [crates/kimetsu-agent/src/codex.rs](https://github.com/RodCor/kimetsu/blob/main/crates/kimetsu-agent/src/codex.rs)
- [crates/kimetsu-agent/src/pi.rs](https://github.com/RodCor/kimetsu/blob/main/crates/kimetsu-agent/src/pi.rs)
- [crates/kimetsu-remote/src/lib.rs](https://github.com/RodCor/kimetsu/blob/main/crates/kimetsu-remote/src/lib.rs)
- [crates/kimetsu-remote/src/rerank.rs](https://github.com/RodCor/kimetsu/blob/main/crates/kimetsu-remote/src/rerank.rs)
- [crates/kimetsu-remote/src/embed.rs](https://github.com/RodCor/kimetsu/blob/main/crates/kimetsu-remote/src/embed.rs)
</details>

# 主机代理集成、CLI 与 MCP / 嵌入守护进程接口

## 1. 概述与架构分层

kimetsu 采用分层设计，将「主机代理 / Harness」「CLI 入口」「MCP 协议适配」与「嵌入守护进程」四个职责解耦。`kimetsu` 二进制在用户终端承担 CLI 角色；`kimetsu-agent` 库抽象各类 coding harness（Claude Code、Codex、Pi）的差异；`kimetsu-remote` 子命令则独立提供嵌入与重排序服务，供本地或远程 agent 通过统一接口调用。这种分层使 agent 可以在不重启守护进程的情况下切换 harness，也允许嵌入模型在 CI 等受限环境中以远程服务方式部署。

资料来源：[crates/kimetsu/src/main.rs:1-80](), [crates/kimetsu-agent/src/lib.rs:1-60](), [crates/kimetsu-remote/src/lib.rs:1-40]()

## 2. CLI 命令树与子命令

`kimetsu` 的顶层 CLI 入口由 `cli.rs` 中的 clap 派生结构定义，核心子命令包括 `brain`、`plugin`、`agent`、`remote` 等：

- `kimetsu brain ...`：操作本地 brain 数据库（`context`、`ingest`、`bench`、`export` 等子命令）。
- `kimetsu plugin install <target> [--scope workspace|global]`：在 workspace（`.claude/`、`.codex/`）或全局（`~/.claude/`、`~/.codex/`）安装 Kimetsu 表面。
- `kimetsu agent ...`：直接以编程方式驱动 harness，绕过插件层。
- `kimetsu-remote serve [--reranker <id>]`：以守护进程方式暴露 `embed`、`rerank`、`brain_context` 等 RPC。

所有子命令共享 `Cli::command()` 派生的帮助文本，并通过 `--features embeddings` 编译开关控制 daemon / reranker / ANN 相关代码的包含。

资料来源：[crates/kimetsu/src/cli.rs:1-200](), [crates/kimetsu/src/main.rs:80-160]()

## 3. 主机代理 Harness 集成

`harness.rs` 定义了一个 `Harness` trait，封装了「会话事件钩子」「MCP server 注册」「记忆收割触发」三类回调。`claude_code.rs`、`codex.rs`、`pi.rs` 分别为 Claude Code、Codex、Pi 提供具体实现：

| Harness | 配置文件 | MCP 注册位置 | 收割钩子 |
|---|---|---|---|
| Claude Code | `.claude/` 或 `~/.claude/` | `mcpServers`（`.claude.json`） | `SessionEnd` 钩子 |
| Codex | `.codex/` 或 `~/.codex/` | `config.toml` 中的 `[mcp_servers]` | `SessionEnd` 钩子 |
| Pi | `~/.pi/` | Pi 的 MCP 注册 API | 进程内事件总线 |

`plugin install` 子命令调用 `Harness::install(scope)` 将 Kimetsu 提供的 MCP 工具（如 `kimetsu_brain_context`、`kimetsu_brain_ingest`）注入对应 harness 的配置文件，从而让 coding agent 在不修改自身代码的前提下获得 brain 访问能力。安装过程是非破坏性的：已有配置会以合并方式更新，新增条目写入前会做 JSON / TOML schema 校验。

资料来源：[crates/kimetsu-agent/src/harness.rs:1-180](), [crates/kimetsu-agent/src/claude_code.rs:1-220](), [crates/kimetsu-agent/src/codex.rs:1-180](), [crates/kimetsu-agent/src/pi.rs:1-160]()

## 4. MCP 协议与嵌入守护进程接口

MCP（Model Context Protocol）通信基于 JSON-RPC over stdio。`kimetsu-remote serve` 启动后作为 MCP server，对外暴露的工具集与 harness 端一一对应，并通过内部的 `embed.rs` 与 `rerank.rs` 模块实现：

```mermaid
flowchart LR
    A[Harness Agent] -->|stdio JSON-RPC| B[plugin shim]
    B -->|UNIX socket / TCP| C[kimetsu-remote serve]
    C --> D[embed.rs<br/>embed / embed_batch]
    C --> E[rerank.rs<br/>cross-encoder]
    C --> F[brain.db<br/>SQLite + ANN]
```

`embed.rs` 使用 `OnceLock` 维护嵌入器单例；`rerank.rs` 在 `kimetsu_brain_context` 调用链上以「retrieval → rerank」两阶段排序，默认模型为 `jina-reranker-v1-tiny-en`，可通过 `--reranker` 切换或设为 `"off"` 关闭。需要注意的是，由于 `OnceLock` 在同一进程内仅初始化一次，当 `kimetsu brain bench --remote` 配合多个 `--embedders` 组合执行时，第二个组合的 memory 会被错误地以第一个组合的向量注入，产生跨模型污染；该问题已在 issue #23 中记录，需通过进程隔离方式绕过。

资料来源：[crates/kimetsu-remote/src/lib.rs:40-260](), [crates/kimetsu-remote/src/embed.rs:1-140](), [crates/kimetsu-remote/src/rerank.rs:1-200]()

## 5. 常见问题与社区关注点

- **多 embedder 串扰**：issue #23 指明 `--remote` 模式下 `OnceLock` 单例会污染后续 combo，建议用子进程或显式重启守护进程隔离。
- **导出隐私**：issue #24 建议 `kimetsu brain export` 新增 `--redact` 标志以剥离 `(context: …)` 后缀，便于发布 benchmark 数据集。
- **CI 覆盖**：issue #22 提出在 CI 中加入 `cargo test --workspace --features embeddings` 任务，使 daemon / reranker / ANN 单元测试纳入自动化回归。
- **新 harness 支持**：issue #17（已关闭）记录了 Pi 的支持路径，作为「good first issue」类增强的参考模板。

资料来源：[GitHub issue #17](), [GitHub issue #22](), [GitHub issue #23](), [GitHub issue #24]()

---

<a id='page-4'></a>

## Brain 分享、Kimetsu Remote、基准测试与常见运维问题

### 相关页面

相关主题：[Brain 存储、嵌入与检索管线](#page-2), [主机代理集成、CLI 与 MCP / 嵌入守护进程接口](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [crates/kimetsu-brain/src/packs.rs](https://github.com/RodCor/kimetsu/blob/main/crates/kimetsu-brain/src/packs.rs)
- [crates/kimetsu-brain/src/redact.rs](https://github.com/RodCor/kimetsu/blob/main/crates/kimetsu-brain/src/redact.rs)
- [crates/kimetsu-brain/src/sync.rs](https://github.com/RodCor/kimetsu/blob/main/crates/kimetsu-brain/src/sync.rs)
- [crates/kimetsu-brain/src/lifecycle.rs](https://github.com/RodCor/kimetsu/blob/main/crates/kimetsu-brain/src/lifecycle.rs)
- [crates/kimetsu-brain/src/maintenance.rs](https://github.com/RodCor/kimetsu/blob/main/crates/kimetsu-brain/src/maintenance.rs)
- [crates/kimetsu-brain/src/benchmark.rs](https://github.com/RodCor/kimetsu/blob/main/crates/kimetsu-brain/src/benchmark.rs)
</details>

# Brain 分享、Kimetsu Remote、基准测试与常见运维问题

本页聚焦 Kimetsu Brain 在「分享（导出/打包）」、`kimetsu-remote` 服务形态、`brain bench` 基准测试以及发布/CI 运维中常见的几类问题。内容来源于 `kimetsu-brain` crate 中与 pack、redact、sync、lifecycle、maintenance、benchmark 直接相关的源码模块。

## 1. Brain 分享：导出与可发布包（packs）

`packs.rs` 是 Brain 导出/打包能力的核心，负责把项目内的 `brain.db` 与相关元数据序列化为可分发的归档（如 tarball）。分享场景通常分为两种：内部备份（保留 `(context: …)` 后缀）与对外发布基准数据集（需要剥离上下文痕迹）。`packs.rs` 与 `redact.rs` 协作时，会按需调用 redaction 流水线。

| 字段 | 用途 |
|------|------|
| `text` | 原始记忆文本（可能含 `(context: …)`） |
| `vector` | 嵌入向量（仅 `--embedders` 指定时导出） |
| `tags` | 记忆标签与作用域 |
| `source` | 记录来源（agent/SessionEnd/手工） |

资料来源：[crates/kimetsu-brain/src/packs.rs:1-120]() 资料来源：[crates/kimetsu-brain/src/redact.rs:1-80]()

## 2. `brain export --redact`：可发布导出

`redact.rs` 实现 `--redact` 标志所需的脱敏逻辑：将 `(context: …)` 后缀从 memory 文本中剥离，同时保留 `(text)` 主体，确保对外发布的脑（benchmark 数据集、分享给协作者的脑）不含用户工作上下文。

- **输入**：`Memory { text, vector, tags, source }`
- **处理**：正则匹配尾部 `(context: …)` 段并截断；如开启 `--redact-vectors`，则同时将 `vector` 字段置空
- **输出**：脱敏后的 `Memory`，可安全写入公开包

目前该能力对应社区 Issue #24（`brain export --redact: strip context trails for shareable exports`），属于分享场景下尚未完全合并的增强项。资料来源：[crates/kimetsu-brain/src/redact.rs:40-160]()

## 3. Kimetsu Remote：跨进程服务与同步

`sync.rs` 与 `lifecycle.rs` 共同支撑 `kimetsu-remote serve` 这一服务端形态：客户端通过 `kimetsu_brain_context` MCP 工具触发检索，服务端完成 ANN 召回 + 远程 cross-encoder rerank，再将 top-K 返回。`--reranker` 默认为 `jina-reranker-v1-tiny-en`，可设为 `off` 或任意 ONNX id。

```mermaid
flowchart LR
    A[Agent / MCP client] --> B[kimetsu-remote serve]
    B --> C[ANN recall]
    C --> D[Cross-encoder rerank]
    D --> E[top-K context]
    E --> A
```

- **生命周期**：`lifecycle.rs` 负责 schema 升级（v3 → v6 自动迁移）、连接健康检查、graceful shutdown
- **同步**：`sync.rs` 处理多客户端并发读、写入幂等性以及 `(context: …)` 后缀在远端的可读性还原

资料来源：[crates/kimetsu-brain/src/sync.rs:60-200]() 资料来源：[crates/kimetsu-brain/src/lifecycle.rs:30-180]()

## 4. `brain bench` 与多 embedder 陷阱

`benchmark.rs` 实现 `kimetsu brain bench [--remote] [--embedders <id1,id2,...>]`，用来度量不同嵌入模型组合下的召回质量。社区 Issue #23 指出了一个静默退化：在 `--remote` 模式下，bench 进程内的 embedder 单例由 `OnceLock` 持有，第一个 combo 完成后该单例被「冻结」，导致后续 combo 的 seed memories 实际被第一个 combo 的向量注入，造成跨模型行污染，最终退化为纯词法召回。

规避方式：
- 对每个 `--embedders` 值起独立 bench 进程（`--remote` 子进程隔离）
- 或在 `maintenance.rs` 中显式调用 embedder 重建钩子

`maintenance.rs` 还承担 vacuum、ANN 索引重建与统计信息刷新，常在 bench 前作为预热步骤。资料来源：[crates/kimetsu-brain/src/benchmark.rs:1-260]() 资料来源：[crates/kimetsu-brain/src/maintenance.rs:20-150]()

## 5. 常见运维问题

### 5.1 CI 未覆盖 embeddings 测试

Issue #22 指出当前 `cargo test --workspace` 仅以默认（lean）特性运行，daemon / reranker / ANN 单测被 `embeddings` 特性门控，从未进入 CI。修复方式是在 Linux runner 上新增 `cargo test --workspace --features embeddings` 任务。

### 5.2 版本戳错位（v1.5.0 → v1.5.1）

v1.5.0 二进制在工作区版本号 bump 之前构建，自报 `1.0.0`，导致 crates.io 已存在 `kimetsu-core@1.0.0` 时发布受阻。npm 禁止复用版本号，v1.5.1 仅修正版本戳、特性集一致；运维时应始终安装 v1.5.1。

### 5.3 插件安装作用域

v0.8.4 起，`kimetsu plugin install <target> --scope global` 会把 Kimetsu surface 写入 `~/.claude/`、`~/.codex/` 等用户级目录，CI/容器场景下应显式 `--scope project` 避免污染镜像。

资料来源：[crates/kimetsu-brain/src/lifecycle.rs:120-240]() 资料来源：[crates/kimetsu-brain/src/sync.rs:200-320]() 资料来源：[crates/kimetsu-brain/src/maintenance.rs:150-260]()

## 6. 小结

- **分享**走 `packs.rs` + `redact.rs`，对外发布务必启用 `--redact`
- **Remote 服务**由 `sync.rs` + `lifecycle.rs` 提供，含远程 rerank
- **Bench**（`benchmark.rs`）在 `--remote` 多 embedder 场景下需进程隔离，避免单例污染
- **运维**关注 CI `embeddings` 特性、版本戳与插件作用域

资料来源：[crates/kimetsu-brain/src/packs.rs:120-260]() 资料来源：[crates/kimetsu-brain/src/redact.rs:160-280]()

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：RodCor/kimetsu

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

## 1. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/RodCor/kimetsu | host_targets=claude_code, claude, openclaw, mcp_host, cursor

## 2. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/RodCor/kimetsu | README/documentation is current enough for a first validation pass.

## 3. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/RodCor/kimetsu | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/RodCor/kimetsu | no_demo; severity=medium

## 5. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/RodCor/kimetsu | no_demo; severity=medium

## 6. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/RodCor/kimetsu | issue_or_pr_quality=unknown

## 7. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/RodCor/kimetsu | release_recency=unknown

<!-- canonical_name: RodCor/kimetsu; human_manual_source: deepwiki_human_wiki -->