# Codebase 内存 V2
[](https://github.com/Cheurteenyt/codebase-mirror/actions/workflows/ci.yml)
[](LICENSE)
## 这是什么？
Codebase Memory V2 是一个**混合型**代码智能系统：
1. **原生 WASM 索引器** (V2) — 通过 tree-sitter WASM 语法支持 112 种语言。在 TypeScript/JavaScript 上具备最先进的语义精度：跨文件 CALLS 解析、模块有效性锁、类型/值默认分离、内置真值锁。语义版本 8。
2. **人类记忆图谱** (V2) — ADR、bug 记录、重构计划、约定、遗留区域标记、风险评估、活动日志 — 同步至兼容 Obsidian 的 Markdown 库。
3. **V1 C 引擎**（独立的生产者/参考） — 通过 tree-sitter C 支持 158 种语言。如果操作员单独运行 V1，V2 可以通过 `CodeGraphReader` 读取生成的兼容 SQLite 数据库。
V2 执行原生索引而无需调用 V1。它不会自动回退到 V1，不会合并 V1 和 V2 的输出，也不会按需创建 V1 数据库。
## 当前版本
请参阅 `v2/package.json` 和 `v2/CHANGELOG.md` 以获取权威版本、测试计数以及 bug/优化历史。
## 快速开始
要求 Node.js >= 22.12.0。仓库的 `.nvmrc` 和 `.node-version`
在开发中选择 Node 24 LTS。
```
cd v2
npm ci
# 仅 Backend CLI + MCP server
npm run build
npm test # see v2/CHANGELOG.md for current test count
# 原生索引项目（TS/JS 无需 V1）
node dist/cli/index.js index --project my-app --root /path/to/repo
node dist/cli/index.js index --project my-app --root /path/to/repo --incremental
# 尝试 demo
node dist/cli/index.js demo
# 初始化您的项目
node dist/cli/index.js init --project my-app
# 运行 diagnostics
node dist/cli/index.js doctor --project my-app
# 在启动之前构建完整的 package，包括 Graph UI
npm run build:package
node dist/cli/index.js ui --project my-app
# 允许 Control 浏览/索引您 home 目录之外的 repository
node dist/cli/index.js ui --project my-app --allowed-root /srv/repos
```
`npm ci` 会安装依赖项，但不会将此包自带的 `cbm-v2`
二进制文件放入你的 `PATH` 中。请如上所述在源代码检出中使用
`node dist/cli/index.js`，或者如果你更喜欢简短的 `cbm-v2` 命令，
则运行一次 `npm link`。
## CLI 参考
### 核心命令
| 命令 | 描述 |
|---|---|
| `cbm-v2 index --project
--root ` | 原生索引项目（WASM，112 种语言） |
| `cbm-v2 index --project --root --incremental` | 快速增量索引（跳过未更改的文件） |
| `cbm-v2 index --project --root --discovery-mode fast` | 明确指定用于基准测试/速度敏感运行的降低覆盖率完全重建；与 `--incremental` 不兼容 |
| `cbm-v2 index --project --root --dry-run` | 预览而不写入 DB |
| `cbm-v2 init` | 初始化 `.codebase-memory.json` 配置 |
| `cbm-v2 doctor` | 运行诊断（Node 版本、DB、库路径） |
| `cbm-v2 stats` | 显示美观的统计仪表板 |
| `cbm-v2 demo` | 创建带有示例笔记和库的演示项目 |
| `cbm-v2 mcp` | 作为 MCP 服务器运行（基于 stdio 的 JSON-RPC） |
| `cbm-v2 ui [--allowed-root ]` | 启动图形 UI Web 服务器（端口 9749）；可选择允许额外的本地浏览/索引根目录 |
| `cbm-v2 watch` | 监视库的更改并自动同步（daemon） |
### 人类记忆命令
| 命令 | 描述 |
|---|---|
| `cbm-v2 human create --type ADR --title "ADR-001: ..."` | 创建笔记 |
| `cbm-v2 human list [--type ADR] [--status active]` | 列出笔记 |
| `cbm-v2 human show ` | 显示笔记（JSON，包含边） |
| `cbm-v2 human link --to-cbm-node --edge DECIDES` | 将笔记链接到代码节点 |
### Obsidian 命令
| 命令 | 描述 |
|---|---|
| `cbm-v2 obsidian init` | 创建库目录结构 |
| `cbm-v2 obsidian sync` | 双向同步（DB ↔ 库） |
| `cbm-v2 obsidian sync --dry-run` | 预览而不写入 |
| `cbm-v2 obsidian sync --direction export` | 仅导出（DB → 库） |
| `cbm-v2 obsidian sync --direction import` | 仅导入（库 → DB） |
| `cbm-v2 obsidian export` | 一次性导出（DB → 库） |
| `cbm-v2 obsidian import` | 一次性导入（库 → DB） |
| `cbm-v2 obsidian report` | 库文件报告（按目录） |
| `cbm-v2 obsidian create-adr --title "ADR-003: ..."` | 创建 ADR + DB 记录 |
| `cbm-v2 obsidian create-module-note --module auth` | 创建 ModuleNote |
| `cbm-v2 obsidian create-route-note --method POST --path /api/login` | 创建 RouteNote |
### 报告命令
| 命令 | 描述 |
|---|---|
| `cbm-v2 report hotspots` | 关键模块（高连接度 + 复杂度） |
| `cbm-v2 report undocumented` | 没有人类笔记的代码节点 |
| `cbm-v2 report risk` | 高耦合、死代码、脆弱的接口 |
### 备份命令
| 命令 | 描述 |
|---|---|
| `cbm-v2 backup export --output backup.json` | 将所有笔记 + 边导出为 JSON |
| `cbm-v2 backup import backup.json` | 从 JSON 备份导入 |
| `cbm-v2 backup import backup.json --dry-run` | 预览导入 |
## MCP 工具 (7)
`cbm-v2 mcp` 命令通过基于 stdio 的 JSON-RPC 2.0 暴露 7 个工具：
| 工具 | 类型 | 描述 |
|---|---|---|
| `get_project_overview` | read | 高层级项目统计（节点、笔记、覆盖率、新鲜度） |
| `get_module_context` | read | 完整模块上下文：代码 + 人类笔记 + ADR + bug + 重构 |
| `get_undocumented_hotspots` | read | 没有文档的关键代码节点 |
| `create_human_note` | write | 创建 ADR/BugNote 等 + 链接到代码节点 |
| `link_note_to_code_node` | write | 将现有笔记链接到代码节点 |
| `search_code_and_memory` | read | 跨代码图谱 + 人类记忆的统一搜索 |
| `prepare_edit_context` ⭐ | read | **旗舰功能** — 在编辑任何文件之前调用。返回代码结构、依赖项、人类笔记、影响范围、风险评分、新鲜度和建议 |
### 连接 AI 代理
添加到你的 MCP 客户端配置中（Claude Desktop、Cursor、Zed 等）：
```
{
"mcpServers": {
"codebase-memory-v2": {
"command": "node",
"args": ["/absolute/path/to/codebase-mirror/v2/dist/cli/index.js", "mcp", "--project", "my-app"]
}
}
}
```
对于 Codex，在运行 `npm run build` 后，将本地 STDIO 服务器添加到 `~/.codex/config.toml` 或受信任
项目的 `.codex/config.toml` 中：
```
[mcp_servers.codebase_memory_v2]
command = "node"
args = ["/absolute/path/to/codebase-mirror/v2/dist/cli/index.js", "mcp", "--project", "my-app"]
```
在 Windows 上，全局文件是 `%USERPROFILE%\.codex\config.toml`。使用带有
正斜杠的绝对路径，例如
`D:/Mycodex/codebase-mirror/v2/dist/cli/index.js`，或者转义 TOML 字符串中的
每个反斜杠。编辑配置后重启 Codex，然后使用
`codex mcp list` 或 `/mcp` 验证连接。
## 工作原理
```
┌──────────────────────────────────────────────────────────────┐
│ Codebase Memory V2 (hybrid) │
├──────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────┐ ┌──────────────────────────┐ │
│ │ V2 Native Indexer │ │ V1 C Engine (separate) │ │
│ │ tree-sitter WASM │ │ tree-sitter C │ │
│ │ 112 languages │ │ 158 languages │ │
│ │ cross-file resolver │ │ DB producer/reference │ │
│ │ semantics v8 │ │ │ │
│ └───────────┬─────────────┘ └──────────┬───────────────┘ │
│ │ │ │
│ v v │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ SQLite code graph (produced by one indexer per run) ││
│ └─────────────────────────────────────────────────────────┘│
│ │ │
│ v │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ V2 Human Memory Layer ││
│ │ Human Memory DB • Obsidian vault sync • Graph UI ││
│ │ 7 MCP tools • Reports • Intelligence layer ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ Storage: │
│ ~/.cache/codebase-memory-mcp/ │
│ .db ← code graph (V2 or separate V1) │
│ .human.db ← human memory (V2, TS) │
│ /.codebase-memory-vault/ ← Obsidian vault (MD) │
│ /.codebase-memory.json ← project config │
└──────────────────────────────────────────────────────────────┘
```
## 原生索引器 (V2 WASM)
V2 包含一个**原生代码索引器**，它不需要 V1 C 二进制文件：
- **112 种语言**，通过预构建的 tree-sitter WASM 语法 (`tree-sitter-wasm`)
- **跨文件 CALLS 解析** — 持久化的 `call_sites`、`imports`、`exports` 表；解析器将跨文件的调用点与定义进行匹配
- **模块有效性锁** — 检测重复导出、默认标记冲突、未解析的星号源、无效内置对象
- **类型/值默认分离** — `interface`/`type alias` 默认值不计入运行时统计
- **内置真值锁** — 从 `node:module` 获取的 `isBuiltin()`；拒绝 `node:fake`，接受 `node:test`
- **增量索引** — 内容哈希 + mtime_ns 快速跳过；仅删除快速路径
- **并行 worker** — 针对大型项目的多线程 WASM 解析
- **语义版本控制** — `CURRENT_EXTRACTOR_SEMANTICS_VERSION = 8`；当提取器输出发生更改时，增量模式会强制进行完全重新索引
- **发现完整性锁** — 带有结构化错误的 `DiscoveryResult`；部分发现会保留现有图谱（不会静默擦除）
- **规范根路径传播** — 符号链接的根路径生成的 `file_path` 不包含 `..`
- **文件身份契约** — 带有 `0:0` 回退的 `dev:ino` 去重；确定性的硬链接选择
### 限制
- V2 原生索引器在 **TypeScript/JavaScript** 上精度最高。其他语言（Python、Go、Rust 等）会进行结构化解析，但不具备跨文件解析能力。
- 如果需要 V1 支持的 158 种语言的覆盖范围和精度，请单独运行 V1 C 二进制文件以生成项目数据库，然后再从 V2 中打开它。
- 图形 UI 最多支持 1,000 个节点，以保证可预测的传输和模拟成本。对于大型项目，请使用过滤器和仪表板。
## 人类记忆节点类型
| 标签 | Obsidian 目录 | 描述 |
|---|---|---|
| `ArchitectureNote` | `Architecture/` | 横向架构笔记 |
| `ADR` | `ADR/` | 架构决策记录 |
| `BugNote` | `Bugs/` | 已知 bug |
| `RefactorPlan` | `Refactor/` | 计划的重构 |
| `LegacyNote` | `Legacy/` | 遗留区域标记 |
| `Convention` | `Conventions/` | 编码/架构约定 |
| `Prompt` | `Prompts/` | 对 AI 代理有用的提示词 |
| `JournalEntry` | `Journal/` | 活动日志 |
| `ModuleNote` | `Modules/` | 附加到模块的笔记 |
| `RouteNote` | `Routes/` | 附加到 HTTP 路由的笔记 |
| `RiskNote` | `Architecture/` | 风险评估 |
## 库格式
每个笔记有两个部分：
```
---
type: adr
status: active
cbm_node_ids: [1234]
tags: [auth, security]
---
# ADR-001：使用 JWT 进行身份验证
## 自动生成
> ⚠️ This section is controlled by Codebase Memory V2 and may be regenerated.
> Do not edit — your changes would be lost on the next sync.
### Metadata
- **Type**: ADR
- **Status**: active
- **Slug**: adr-001-use-jwt-for-authentication
### 代码链接
- [[1234]] — Module:auth (`src/auth/index.ts:1`)
---
## 人工笔记
> ✏️ This section belongs to the user. It will **never** be overwritten.
### 上下文
We needed a stateless auth mechanism.
### 决策
Use JWT tokens signed with HS256.
```
`## HUMAN NOTES` 部分**绝不**会被 V2 覆盖。可以在 Obsidian 中自由编辑它 — 下次同步会保留你的修改。
## 图形 UI
V2 图形 UI 用更简洁的 2D d3-force 画布取代了 V1 的 3D Three.js 场景：
- **仪表板选项卡**（默认）：KPI、图谱新鲜度、智能建议
- **图谱选项卡**：带有过滤器、平移/缩放、节点详细信息面板的 2D 力导向画布
- **项目选项卡**：包含节点/边数量和健康状态的项目列表
- **控制选项卡**：系统信息
```
# 在源码检出中的 v2/ 目录下
npm run build:package
node dist/cli/index.js ui --project my-app
# 或者，在 npm link / 全局安装之后
cbm-v2 ui --project my-app --port 8080
# 将用户 home 目录之外的 repository 添加到 Control allowlist
cbm-v2 ui --project my-app --allowed-root /srv/repos /mnt/work
```
打开 `http://127.0.0.1:9749/` 进入项目选择器，或直接访问
`http://127.0.0.1:9749/?tab=graph&project=my-app` 查看交互式图形。
默认情况下，允许访问主目录和所选项目的索引根目录。
必须使用 `--allowed-root` 明确授予额外的控制选项卡浏览/索引根目录；
路径在进行包含检查之前会被规范化。
## Docker
```
# 构建
docker build -t cbm-v2 .
# 运行 CLI
docker run --rm cbm-v2 --help
docker run --rm cbm-v2 demo
# 运行 MCP server（挂载 cache volume）
docker run --rm -i -v cbm-cache:/home/node/.cache/codebase-memory-mcp cbm-v2 mcp --project my-app
```
## 文档
### 架构与当前状态
- [V2 架构](docs/V2_ARCHITECTURE.md) — 混合索引器、发现、解析器、语义
- [V2 当前状态](docs/V2_CURRENT_STATE.md) — 版本、稳定功能、限制、阻碍
- [V2 路线图](docs/V2_ROADMAP.md) — 历史存档（0.15.9 时代）
- [Obsidian 集成](docs/OBSIDIAN_INTEGRATION.md) — 库格式与同步
- [人类记忆 Schema](docs/HUMAN_MEMORY_GRAPH_SCHEMA.md) — SQL schema
### 参考
- [MCP 工具](docs/MCP_TOOLS.md) — 包含输入/输出示例的所有 7 个 MCP 工具
- [CLI 参考](docs/CLI_REFERENCE.md) — 包含 `m-v2 index` 在内的所有 CLI 命令
- [智能层](docs/INTELLIGENCE.md) — 图谱感知 + prepare_edit_context
- [Token 经济](docs/TOKEN_ECONOMY.md) — 历史 v0.15.9 工作流估算（-67% 到 -87%），非当前传输基准
- [性能、Token 与 UI 审计](docs/PERFORMANCE_TOKEN_UI_AUDIT_2026-07-15.md) — 当前的紧凑型与美观型空白传输测量
### 项目
## 安全性
- **本地优先**：无网络调用，无遥测
- **保留 HUMAN NOTES**：`## HUMAN NOTES` 部分绝不会被覆盖（已经过回归测试）
- **路径遍历保护**：针对 `..` 和反斜杠验证 `obsidian_path`；`assertPathInsideRoot` 使用 `path.relative` 进行跨平台包含检查
- **发现完整性锁**：部分发现（子树 EACCES、致命的符号链接错误）会保留现有图谱 — 不会静默擦除。损坏的符号链接 (ENOENT) 被视为警告，而不是致命错误。
- **别名历史** (R153)：当符号链接别名之前有效而现在损坏时，旧规范目标的数据将通过 `alias_history` 表保留。防止静默删除历史目标。
- **警告传播** (R152+R153)：所有发现警告（损坏的符号链接、ELOOP、TOCTOU 竞争）都会出现在 `IndexResult.warnings` 中，并带有相对于根目录的路径。即使成功（`SUCCESS_WITH_WARNINGS` 结果），CLI 也会打印它们。
- **类型化结果** (R153)：`IndexResult.outcome` 为 `SUCCESS` | `SUCCESS_WITH_WARNINGS` | `STALE` | `PARTIAL` | `FAILED`。退出代码：0（成功）、1（错误）、2（过时但无错误）。
- **根发现验证**：`assertDiscoveryRoot` 在任何 DB 变更之前验证 stat + isDirectory + realpath + readdir
- **备份轮换**：每个笔记最多 5 个 `.bak` 文件
- **试运行**：可在 `obsidian sync`、`obsidian export`、`obsidian import`、`backup import` 上使用
- **一致的同步哈希**：`markSynced` 为导出和导入方向计算相同的 DB 派生哈希，使冲突检测变得可靠（R14 修复）
## 性能
- **消除 N+1 查询**：所有热路径均使用批量抓取（`getBulkNotesByCbmNodeIds`、`getBulkNodeDegrees`、`getBulkEdges`）
- **SQL 级别限制**：`getBulkNotesByCbmNodeIds` 使用 `ROW_NUMBER() OVER (PARTITION BY ...)` 在数据库级别限制每个节点的数量
- **增量索引**：内容哈希 + mtime_ns 快速跳过；仅删除快速路径避免了重新解析未更改的文件
- **并行 worker**：针对具有 >20 个更改文件的项目进行多线程 WASM 解析
- **稳定的 UI 监听器**：`GraphCanvas` 为回调使用 refs — 在切换过滤器时不会重新绑定监听器
## 许可证
MIT — 见 [LICENSE](LICENSE)。