代码图谱记忆 LoveDoLove/dsh-codebase-memory-mcp

@lovedolove/dsh-codebase-memory-mcp

独立 Codebase Memory MCP 桥接插件，用于 DeepSeek Harness（DSH）。
注册六个知识图谱代码工具，自动启动 codebase-memory-mcp 守护进程及其图谱可视化 Web UI，并附带一个内置智能体技能和一个 /cbm 状态命令。

M8ven Score

功能

- 六个知识图谱代码工具，原生注册在 DSH 工具界面上（cbm_projects、cbm_search、cbm_snippet、cbm_arch、cbm_trace、 cbm_search_code）。内置技能的说明指出，图谱查询返回精确的结构化结果只需约 500 token，而 grep 需要约 80K。
- 自动启动的后台守护进程与 Web UI —— 插件加载时，以子进程方式启动 codebase-memory-mcp --ui=true，走 stdio JSON-RPC 2.0（MCP 握手 2025-03-26），并打印 codebase-memory UI is live: http://localhost:9749/。共享客户端会在守护进程退出时自动重启，并在插件关闭时将其释放。
- 系统提示词引导 —— 注入一节 Codebase Memory — Knowledge Graph Policy，告诉模型何时优先使用图谱工具，而不是 grep/read。
- 内置智能体技能 —— skills/codebase-memory/SKILL.md 注册为原生内置技能服务商（codebase-memory，rank 600，模型和用户均可调用），因此面向模型的 skill 工具可以加载它。
- /cbm 斜杠命令 —— 报告解析出的可执行文件路径、Web UI 链接，以及守护进程中当前已索引的项目。
- 优雅降级 —— 只有 tools 是硬依赖（inject: ['tools']）； systemPrompt、skills、commands 通过延迟的 ctx.inject() 挂载，所以宿主服务缺失时直接跳过对应功能。
- 跨平台可执行文件检测 —— 支持 CBM_EXE 覆盖、用户和系统目录、当前工作目录、PATH，以及 WSL 互操作回退，可从 Linux/WSL 定位到可访问的 codebase-memory-mcp.exe。

环境要求

| 组件 | 版本 |
| DeepSeek Harness | >=0.1.2-rc.1 <0.3.0-0（dsh.compatibility.dshVersions） |
| Node.js | >=18 <25（engines） |
| codebase-memory-mcp 可执行文件 | 任意近期版本（已在 0.11.0 上测试） |

可选同级依赖（在 peerDependencies 中声明，存在时从 DSH 运行时解析）：@deepseek-ai/cordis >=4.0.1-rc.1 <5.0.0-0，以及 @deepseek-ai/dsh-commands、@deepseek-ai/dsh-skill、 @deepseek-ai/dsh-system-prompt、@deepseek-ai/dsh-tools >=0.1.2-rc.1 <0.3.0-0.

启动 DSH 之前先安装可执行文件。 插件加载时会解析二进制文件；找不到就不会启动守护进程，cbm_ 工具也不会注册。之后再安装二进制文件，需要重新加载配置档。

安装

1. 安装 codebase-memory-mcp 可执行文件

插件只是一座桥——代码索引和查询由 codebase-memory-mcp 运行时完成（上游项目、文档）：

Installs the CLI and downloads/caches the native runtime for your platform
npm install -g codebase-memory-mcp

Verify it runs
codebase-memory-mcp --version

也可以下载对应平台的发布二进制文件，放到插件会搜索的位置之一：

- ~/.local/bin/codebase-memory-mcp（Linux/macOS 用户 bin 目录）
- /usr/local/bin/ 或 /usr/bin/（系统目录）
- 当前工作目录，或 PATH 上的任意位置
- %USERPROFILE%\AppData\Local\Programs\codebase-memory-mcp\codebase-memory-mcp.exe（Windows）

或者用 CBM_EXE=/path/to/codebase-memory-mcp 直接指定路径。

2. 把插件安装到 DSH 配置档

dsh plugin --profile web add @lovedolove/dsh-codebase-memory-mcp

（把 web 换成你的配置档名——web、headless、sdk、acp……）

这条命令会把包安装转发到配置档目录。由于包声明了 dsh.bundle.patch，DSH 会把 @lovedolove/dsh-codebase-memory-mcp 追加到配置档的 dsh.profile.bundles 列表，自动激活 bundle。

其他安装方式：

- Web 侧边栏 → Plugins 页面：搜索这个包并安装（Creator 模式下 plugin_manager 工具提供同样的操作）。
- 手动接线：把包加到配置档 $DSH_HOME/profiles/<name>/package.json 的 dependencies 里，并在 dsh.profile.bundles 下列出它，然后在该目录执行一次包安装。随包发布的 bundle 补丁（cordis.patch.yml，声明为 dsh.bundle.patch）会挂载插件：

- insert:
- id: codebase-memory
name: '@lovedolove/dsh-codebase-memory-mcp'

3. 启动 DSH

插件加载时你会看到：

[codebase-memory] 🔍 codebase-memory UI is live: http://localhost:9749/

日志里还有：

[codebase-memory] registered tools: cbm_projects, cbm_search, cbm_snippet, cbm_arch, cbm_trace, cbm_search_code
[codebase-memory] registered system prompt guidance
[codebase-memory] registered /cbm command
[codebase-memory] registered skill: codebase-memory

用法

让智能体用它

插件会把知识图谱策略注入系统提示词，并打包 codebase-memory 技能，让智能体自己挑对工具。
典型工作流：

1. cbm_projects() —— 确认项目已建索引（默认从工作区推断项目）。
2. cbm_search(name_pattern=".auth.") —— 按名称/标签/路径查找符号。
3. cbm_trace(symbol="login", direction="both", max_depth=3) —— 追踪调用方与被调用方。
4. cbm_snippet(qualified_name="app.auth.login") —— 读取精确定义，不用加载整个文件。
5. cbm_arch(directory="src") —— 获取目录级组件概览。

快速决策表（来自内置技能）：

| 问题 | 工具调用 |
| 谁调用了 X？ | cbm_trace(symbol="...", direction="inbound") |
| X 调用了什么？ | cbm_trace(symbol="...", direction="outbound") |
| 完整调用上下文 | cbm_trace(symbol="...", direction="both") |
| 按名称模式查找 | cbm_search(name_pattern="...") |
| 读取源码片段 | cbm_snippet(qualified_name="...") |
| 目录架构 | cbm_arch(directory="...") |
| 在仓库中做文本搜索 | cbm_search_code(query="...") |
| 列出已建索引的项目 | cbm_projects() |

用 /cbm 查看状态

🔍 Codebase Memory MCP
• Executable: /home/you/.local/bin/codebase-memory-mcp
• Web UI: http://localhost:9749/

Indexed Projects:
home-you-my-repo

如果找不到可执行文件，/cbm 会报告： ⚠️ codebase-memory-mcp executable not found. Install codebase-memory-mcp or set CBM_EXE.

Web UI

守护进程启动时带了 --ui=true，所以会在 http://localhost:9749/ 提供 HTTP 图可视化 UI（这是运行时的默认端口；上游二进制接受 --port=N 并会持久化该设置 —— 插件的提示词和 /cbm 都按默认的 9749 处理）。

可用工具

六个工具都接受 project（显式项目 slug）和/或 repo（仓库根路径，自动转成 slug），并且都标记为并发安全。
结果以文本返回。

| 工具 | 描述 | 参数（★ = 必填） |
| cbm_projects | 列出守护进程中已建索引的所有项目 | （无）* |
| cbm_search | 在知识图谱中搜索符号或文件 | name_pattern、label（Function \| Class \| Interface \| File）、file_path_pattern、limit（默认 50）、project、repo |
| cbm_snippet | 获取符号的精确源码片段 | qualified_name、file_path、start_line、end_line、project、repo |
| cbm_arch | 目录的架构摘要（组件、入口点、依赖） | directory（相对于仓库根目录）、depth（默认 2）、project、repo |
| cbm_trace | 沿图谱追踪入向/出向调用路径 | ★ symbol、direction（inbound \| outbound \| both，默认 both）、max_depth（默认 3）、project、repo |
| cbm_search_code | 对已建索引的文件做快速文本正则搜索 | ★ query、file_pattern、limit（默认 50）、project、repo |
每个工具都会转发到守护进程的 MCP tools/call 方法（list_projects、search_graph、get_code_snippet、get_architecture、 trace_path、search_code），超时 120 秒；工具级错误会作为失败的工具结果返回。

配置

环境变量

| 变量 | 作用 |
| CBM_EXE | 显式指定 codebase-memory-mcp 可执行文件的路径（必须存在；优先级高于其他所有查找方式）。 |
| CBM_DEFAULT_PROJECT | 当工具调用既没传 project 也没传 repo 时，用作兜底的项目 slug。 |

项目解析顺序

调用工具时，项目按以下顺序解析：

1. 显式传入的 project 参数，
2. repo 参数对应的 slug，
3. CBM_DEFAULT_PROJECT，
4. 当前工作目录对应的 slug。

slug 映射规则：/home/user/my-repo → home-user-my-repo；Windows 路径保留盘符前缀，例如 C:\Users\me\app → C-Users-me-app。

守护进程自动启动

插件生效时守护进程会立即启动（除非进程运行在 node --test 下），并且每次工具调用都会确保它处于运行状态，所以子进程挂掉后会被透明地重启。插件销毁时，守护进程会连同所有待处理的请求一起终止。

开发与测试

Unit + integration test suite (node --test)
npm test

Verify npm package packing
npm run pack:check

测试套件覆盖路径 slug 化、findExe/CBM_EXE 查找、stdio JSON-RPC 客户端（启动、握手、工具调用、错误）、工具注册、针对模拟 Cordis 上下文执行完整的 apply()，以及——当宿主机安装了真实可执行文件时——一次实时的 list_projects 往返调用（否则跳过该测试）。CI 在 Ubuntu 上使用 Node 20、22、24 运行测试套件。

仓库结构：

src/index.mjs # Cordis plugin: apply(), system prompt, /cbm command
src/bridge.mjs # stdio JSON-RPC client, executable discovery, cbm_* tools
src/skills.mjs # bundled skill provider registration
skills/codebase-memory/SKILL.md # agent-facing skill
cordis.patch.yml # bundle patch that mounts the plugin

发布

每次推送到 main 都会运行 Publish 工作流：它先跑测试套件，然后通过 Trusted Publishing（OIDC）把包发布到 npm。如果当前版本已存在，工作流会递增补丁版本号，并用 [skip publish] 提交回去，避免死循环；提交信息里任何位置包含 [skip publish] 都会完全跳过发布运行。

许可证

MIT © 2025 LoveDoLove