codebase-mirror

<p align="center"> <img src="docs/assets/codebase-memory-logo.png" alt="Codebase Memory project logo" width="240"> </p> # 代码库内存 V2 > **混合代码智能** — 原生 WASM 索引器（112 种语言）+ 人类记忆图 + Obsidian 保险库同步。 > V1（C 引擎，158 种语言）现作为 **备用**，适用于 V2 未原生支持的语言。 [](https://github.com/Cheurteenyt/codebase-mirror/actions/workflows/ci.yml) [](LICENSE) ## 什么是 Codebase Memory V2？ Codebase Memory V2 是一个 **混合** 代码智能系统： 1. **原生 WASM 索引器**（V2）— 通过 tree-sitter WASM 语法支持 112 种语言。 在 TypeScript/JavaScript 上具有最先进的语义精度：跨文件调用解析、模块有效性锁定、类型/值默认分离、内置真实性锁定。 语义版本 8。 2. **人类记忆图**（V2）— ADRs（架构决策记录）、缺陷笔记、重构计划、约定、遗留区标记、风险评估、活动日志 — 同步到与 Obsidian 兼容的 Markdown 保险库。 3. **V1 C 引擎**（备用）— 通过 tree-sitter C 支持 158 种语言。 作为 V2 未原生支持的语言的参考和备用。 V2 通过 `CodeGraphReader` 透明地读取 V1 的 SQLite 数据库。 V2 **部分自主**：它可以原生索引 TS/JS 项目，无需 V1，并为其他语言备用 V1。 ## 当前版本 参见 `v2/package.json` 和 `v2/CHANGELOG.md` 获取权威版本、测试计数和错误/优化历史。 ## 快速开始 ```bash cd v2 npm install npm run build npm test # 参见 v2/CHANGELOG.md 获取当前测试计数 # 原生索引项目（TS/JS 无需 V1） cbm-v2 index --project my-app --root /path/to/repo cbm-v2 index --project my-app --root /path/to/repo --incremental # 快速增量索引 # 尝试演示 node dist/cli/index.js demo # 初始化项目 node dist/cli/index.js init --project my-app # 运行诊断 node dist/cli/index.js doctor --project my-app # 启动图 UI（http://127.0.0.1:9749） node dist/cli/index.js ui --project my-app ``` ## CLI 参考 ### 核心命令 | 命令 | 描述 | |---|---| | `cbm-v2 index --project <p> --root <r>` | 原生索引项目（WASM，112 种语言） | | `cbm-v2 index --project <p> --root <r> --incremental` | 快速增量索引（跳过未更改的文件） | | `cbm-v2 index --project <p> --root <r> --dry-run` | 预览而不写入数据库 | | `cbm-v2 init` | 初始化 `.codebase-memory.json` 配置 | | `cbm-v2 doctor` | 运行诊断（Node 版本、数据库、保险库路径） | | `cbm-v2 stats` | 显示漂亮的统计仪表盘 | | `cbm-v2 demo` | 创建具有示例笔记 + 保险库的演示项目 | | `cbm-v2 mcp` | 运行为 MCP 服务器（JSON-RPC via stdio） | | `cbm-v2 ui` | 启动图 UI 网络服务器（端口 9749） | | `cbm-v2 watch` | 监视保险库更改并自动同步（守护进程） | ### 人类记忆命令 | 命令 | 描述 | |---|---| | `cbm-v2 human create --type ADR --title "ADR-001: ..."` | 创建笔记 | | `cbm-v2 human list [--type ADR] [--status active]` | 列出笔记 | | `cbm-v2 human show <id>` | 显示笔记（JSON，包括边） | | `cbm-v2 human link <noteId> --to-cbm-node <id> --edge DECIDES` | 将笔记链接到代码节点 | ### Obsidian 命令 | 命令 | 描述 | |---|---| | `cbm-v2 obsidian init` | 创建保险库目录结构 | | `cbm-v2 obsidian sync` | 双向同步（数据库 ↔ 保险库） | | `cbm-v2 obsidian sync --dry-run` | 预览而不写入 | | `cbm-v2 obsidian sync --direction export` | 仅导出（数据库 → 保险库） | | `cbm-v2 obsidian sync --direction import` | 仅导入（保险库 → 数据库） | | `cbm-v2 obsidian export` | 一次性导出（数据库 → 保险库） | | `cbm-v2 obsidian import` | 一次性导入（保险库 → 数据库） | | `cbm-v2 obsidian report` | 保险库文件报告（按目录） | | `cbm-v2 obsidian create-adr --title "ADR-003: ..."` | 创建 ADR + 数据库记录 | | `cbm-v2 obsidian create-module-note --module auth` | 创建模块笔记 | | `cbm-v2 obsidian create-route-note --method POST --path /api/login` | 创建路由笔记 | ### 报告命令 | 命令 | 描述 | |---|---| | `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` 命令通过 JSON-RPC 2.0 在 stdio 上公开 7 个工具： | 工具 | 类型 | 描述 | |---|---|---| | `get_project_overview` | 读取 | 高级项目统计（节点、笔记、覆盖率、新鲜度） | | `get_module_context` | 读取 | 完整模块上下文：代码 + 人类笔记 + ADRs + 缺陷 + 重构 | | `get_undocumented_hotspots` | 读取 | 无文档的关键代码节点 | | `create_human_note` | 写入 | 创建 ADR/缺陷笔记等 + 链接到代码节点 | | `link_note_to_code_node` | 写入 | 将现有笔记链接到代码节点 | | `search_code_and_memory` | 读取 | 代码图 + 人类记忆的统一搜索 | | `prepare_edit_context` ⭐ | 读取 | **旗舰** — 在编辑任何文件之前调用。 返回代码结构、依赖项、人类笔记、爆炸半径、风险评分、新鲜度和建议 | ### 连接 AI 代理 添加到您的 MCP 客户端配置（Claude Desktop、Cursor、Zed 等）： ```json { "mcpServers": { "codebase-memory-v2": { "command": "node", "args": ["/path/to/v2/dist/cli/index.js", "mcp", "--project", "my-app"] } } } ``` ## 工作原理 ``` ┌──────────────────────────────────────────────────────────────┐ │ 代码库内存 V2（混合） │ ├──────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────────────┐ ┌──────────────────────────┐ │ │ │ V2 原生索引器 │ │ V1 C 引擎（备用） │ │ │ │ tree-sitter WASM │ │ tree-sitter C │ │ │ │ 112 种语言 │ │ 158 种语言 │ │ │ │ 跨文件解析器 │ │ 参考/备用 │ │ │ │ 语义版本 8 │ │ │ │ │ └───────────┬─────────────┘ └──────────┬───────────────┘ │ │ │ │ │ │ v v │ │ ┌─────────────────────────────────────────────────────────┐│ │ │ SQLite 代码图（共享，V1 兼容模式） ││ │ └─────────────────────────────────────────────────────────┘│ │ │ │ │ v │ │ ┌─────────────────────────────────────────────────────────┐│ │ │ V2 人类记忆层 ││ │ │ 人类记忆数据库 • Obsidian 保险库同步 • 图形 UI ││ │ │ 7 个 MCP 工具 • 报告 • 智能层 ││ │ └─────────────────────────────────────────────────────────┘│ │ │ │ 存储： │ │ ~/.cache/codebase-memory-mcp/ │ │ <project>.db ← 代码图（V2 原生或 V1 C） │ │ <project>.human.db ← 人类记忆（V2，TS） │ │ <repo>/.codebase-memory-vault/ ← Obsidian 保险库（MD） │ │ <repo>/.codebase-memory.json ← 项目配置 │ └──────────────────────────────────────────────────────────────┘ ``` ## 原生索引器（V2 WASM） V2 包含一个 **原生代码索引器**，无需 V1 C 二进制文件： - **112 种语言** 通过预构建的 tree-sitter WASM 语法（`tree-sitter-wasm`） - **跨文件调用解析** — 持久的 `call_sites`、`imports`、`exports` 表；解析器将调用站点与文件间的定义相匹配 - **模块有效性锁定** — 检测重复导出、默认标记冲突、未解析的星源、无效内置函数 - **类型/值默认分离** — `interface`/`type alias` 默认值不计入运行时计数 - **内置真实性锁定** — `isBuiltin()` 来自 `node:module`；`node:fake` 被拒绝，`node:test` 被接受 - **增量索引** — 内容哈希 + mtime_ns 快速跳过；仅删除的快速路径 - **并行工作线程** — 多线程 WASM 解析适用于大型项目 - **语义版本控制** — `CURRENT_EXTRACTOR_SEMANTICS_VERSION = 8`；增量模式在提取器输出更改时强制完整重新索引 - **发现完整性锁定** — `DiscoveryResult` 具有结构化错误；部分发现保留现有图（无静默清除） - **规范根传播** — 符号链接根产生不带 `..` 的 `file_path` - **文件身份契约** — `dev:ino` 具有 `0:0` 备用；确定性硬链接选择 ### 限制 - V2 原生索引器在 **TypeScript/JavaScript** 上最为精确。 其他语言（Python、Go、Rust 等）通过结构解析但无跨文件解析。 - 对于具有 V1 级别精度的完整 158 种语言支持，请使用 V1 C 二进制文件作为备用。 - 图形 UI 限制在 ~2000 个节点以保证性能。 对于大型项目，请使用过滤器和仪表盘。 ## 人类记忆节点类型 | 标签 | Obsidian 目录 | 描述 | |---|---|---| | `ArchitectureNote` | `Architecture/` | 横向架构笔记 | | `ADR` | `ADR/` | 架构决策记录 | | `BugNote` | `Bugs/` | 已知缺陷 | | `RefactorPlan` | `Refactor/` | 计划的重构 | | `LegacyNote` | `Legacy/` | 遗留区标记 | | `Convention` | `Conventions/` | 编码/架构约定 | | `Prompt` | `Prompts/` | AI 代理的有用提示 | | `JournalEntry` | `Journal/` | 活动日志 | | `ModuleNote` | `Modules/` | 附加到模块的笔记 | | `RouteNote` | `Routes/` | 附加到 HTTP 路由的笔记 | | `RiskNote` | `Architecture/` | 风险评估 | ## 保险库格式 每个笔记有两个部分： ```markdown --- type: adr status: active cbm_node_ids: [1234] tags: [auth, security] --- # ADR-001: 使用 JWT 进行身份验证 ## 自动生成 > ⚠️ 此部分由 Codebase Memory V2 控制，可能会重新生成。 > 请勿编辑 — 您的更改将在下一次同步时丢失。 ### 元数据 - **类型**：ADR - **状态**：active - **Slug**：adr-001-use-jwt-for-authentication ### 代码链接 - [[1234]] — 模块：auth (`src/auth/index.ts:1`) --- ## 人类笔记 > ✏️ 此部分属于用户。 它将 **永远不会** 被覆盖。 ### 上下文 我们需要一个无状态的身份验证机制。 ### 决定 使用具有 HS256 签名的 JWT 令牌。 ``` `## 人类笔记` 部分 **永远不会** 被 V2 覆盖。 在 Obsidian 中自由编辑它 — 下一次同步保留您的编辑。 ## 图形 UI V2 图形 UI 取代 V1 的 3D Three.js 场景，采用更清洁的 2D d3-force 画布： - **仪表盘选项卡** （默认）：KPI、图的新鲜度、智能推荐 - **图形选项卡**：具有过滤器、平移/缩放、节点详细信息面板的 2D 力导向画布 - **项目选项卡**：具有节点/边计数和健康状态的项目列表 - **控制选项卡**：系统信息 ```bash cbm-v2 ui --project my-app # http://127.0.0.1:9749 cbm-v2 ui --project my-app --port 8080 ``` ## Docker ```bash # 构建 docker build -t cbm-v2 . # 运行 CLI docker run --rm cbm-v2 --help docker run --rm cbm-v2 demo # 运行 MCP 服务器（挂载缓存卷） docker run --rm -i -v cbm-cache:/root/.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) — 保险库格式和同步 - [人类记忆模式](docs/HUMAN_MEMORY_GRAPH_SCHEMA.md) — SQL 模式 ### 参考 - [MCP 工具](docs/MCP_TOOLS.md) — 所有 7 个 MCP 工具，含输入/输出示例 - [CLI 参考](docs/CLI_REFERENCE.md) — 所有 CLI 命令，包括 `cbm-v2 index` - [智能层](docs/INTELLIGENCE.md) — 图形感知 + prepare_edit_context - [代币经济](docs/TOKEN_ECONOMY.md) — V2 如何节省 API 代币（-67% 至 -87%） ### 项目 - [贡献](CONTRIBUTING.md) — 如何贡献 - [维护者指南](MAINTAINERS_GUIDE.md) — 内部约定和不变式 - [AI 协作协议](docs/AI_COLLABORATION_PROTOCOL.md) — 外部审计、GLM 检查点和重置恢复 - [许可证](LICENSE) — MIT ## 安全 - **本地优先**：无网络调用，无遥测 - **保留人类笔记**：`## 人类笔记` 部分永远不会被覆盖（回归测试） - **路径遍历保护**：`obsidian_path` 验证为 `..` 和反斜杠；`assertPathInsideRoot` 使用 `path.relative` 进行跨平台包含 - **发现完整性锁定**：部分发现（子树 EACCES，致命符号链接错误）保留现有图 — 无静默清除。 损坏的符号链接（ENOENT）被视为警告，而不是致命错误。 - **别名历史**（R153）：当别名曾经有效且现在已损坏时，旧规范目标的数据通过 `alias_history` 表保留。 防止静默历史目标删除。 - **警告传播**（R152+R153）：所有发现警告（损坏的符号链接、ELOOP、TOCTOU 竞争）都在 `IndexResult.warnings` 中显示，带有根相对路径。 CLI 甚至在成功时也会打印它们（`SUCCESS_WITH_WARNINGS` 结果）。 - **类型结果**（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 快速跳过；仅删除的快速路径避免重新解析未更改的文件 - **并行工作线程**：具有 >20 个更改文件的项目的多线程 WASM 解析 - **稳定的 UI 监听器**：`GraphCanvas` 为回调使用引用 — 监听器在过滤器切换时不会重新绑定 ## 许可证 MIT — 参见 [LICENSE](LICENSE)。