# codebase-memory-mcp 操作手册（Windows 版）

> 适用版本：**v0.12.1**（本目录中的 `codebase-memory-mcp.exe` 已在本机验证可运行）
> 官方仓库：<https://github.com/DeusData/codebase-memory-mcp>
> 本手册基于官方 README、Windows 排障文档，以及本机实际执行结果整理。

---

## 1. 先用 3 分钟搞懂它是干什么的

一句话：**它会把你的代码仓库"读"成一张地图（知识图谱），让 AI 编程助手不用再一个文件一个文件地翻代码。**

这张地图里有两类东西：

| 概念 | 通俗解释 | 例子 |
|------|----------|------|
| **节点（Node）** | 代码里的"东西" | 文件、函数、类、接口、路由、数据库表、Docker 镜像、K8s 资源…… |
| **边（Edge）** | 这些东西之间的关系 | A 调用了 B、文件导入了谁、哪个 Dockerfile 构建了哪个镜像、哪个服务部署到哪…… |

索引完成后，你可以问它：

- "谁调用了 `ProcessOrder`？"
- "改这个函数会影响哪些地方？"
- "这个服务最终是由哪个 Dockerfile 构建、跑的是哪个程序？"
- "这个功能相关的文档在哪？"

它有三种使用方式，互相独立，按需选择：

```
┌─────────────────────────────────────────────────────────┐
│  1. MCP 服务  → 给 Claude Code / Codex / Cursor 等 AI 用 │
│  2. 命令行     → 自己在终端里查                            │
│  3. 网页 UI    → CBM Lens，可视化看代码地图                 │
└─────────────────────────────────────────────────────────┘
```

**几个关键特点：**

- **完全本地**：索引和查询都在你的电脑上完成，不需要 API Key，不上传代码，也没有遥测。
- **索引会持久化**：建一次索引，以后重启还能用；文件改了还能自动增量更新。
- **不需要 Docker / Node / Python**：主程序是一个独立的 `.exe`，语法解析器都编译在里面。
- **支持 162 种语言/文件格式**，包括代码、Markdown、PDF、OpenAPI、Terraform、K8s、Docker 等。

---

## 2. 你手里的文件是什么

当前目录 `D:\env\codebase-memory-mcp-ui-windows-amd64` 里有：

| 文件 | 作用 |
|------|------|
| `codebase-memory-mcp.exe` | 主程序。**已包含网页 UI（CBM Lens）**，约 333 MB。 |
| `install.ps1` | 官方安装/更新脚本。注意：它会**重新从 GitHub 下载**最新版。 |
| `LICENSE` | MIT 许可证。 |
| `THIRD_PARTY_NOTICES.md` | 第三方组件声明。 |

先确认程序能跑：

```powershell
cd D:\env\codebase-memory-mcp-ui-windows-amd64
.\codebase-memory-mcp.exe --version
```

本机实测输出：

```
codebase-memory-mcp 0.12.1
```

> 如果你用的是 Git Bash，把 `.\` 换成 `./` 即可。

---

## 3. 安装（二选一）

安装并不是"必须"的：直接在当前目录运行 exe 也能用 CLI 和网页。
但如果你要让 **Claude Code / Codex / Cursor 等 AI 助手稳定调用它**，建议安装，因为安装会做三件事：

1. 把 exe 放到固定目录并加入 PATH；
2. 自动写入已安装 AI 客户端的 MCP 配置；
3. 安装配套的 skill、子代理（Scout / Verify / Auditor）和上下文 hooks。

### 方式 A：用现有 exe 安装（推荐，不用重新下载）

适合：网络访问 GitHub 不稳定，或者你只想用当前这个 0.12.1 版本。

打开 **PowerShell**，执行：

```powershell
cd D:\env\codebase-memory-mcp-ui-windows-amd64

# 第一步：预览会改哪些东西（不会真的修改）
.\codebase-memory-mcp.exe install --dry-run -y

# 第二步：确认无误后正式安装
.\codebase-memory-mcp.exe install -y --force
```

本机 `--dry-run` 的实测结果（你的机器可能略有不同）：

- 安装目标：`C:\Users\admin\.local\bin\codebase-memory-mcp.exe`
- 检测到 8 个 AI 客户端：Claude Code、Codex、OpenCode、VS Code、Cursor、OpenClaw、Cline、Copilot CLI
- 会写入各客户端的 MCP 配置、skills、agents 和 hooks
- 会把 `C:\Users\admin\.local\bin` 加入当前用户 PATH

常用参数：

```powershell
# 只配置 Claude Code（不碰其他客户端）
.\codebase-memory-mcp.exe install -y --force --clients=claude

# 只看有哪些客户端代号
.\codebase-memory-mcp.exe install --clients

# 只装程序，不修改任何 AI 客户端配置
.\codebase-memory-mcp.exe install -y --force --skip-config

# 装到自定义目录
.\codebase-memory-mcp.exe install -y --force --dir="D:\tools\cbm"
```

> ⚠️ 安装会修改 AI 客户端的配置文件。如果你暂时不想动它们，用 `--skip-config`。
> 安装完成后，**关掉并重新打开终端**，PATH 才会生效。

### 方式 B：运行官方 install.ps1

适合：网络正常，想自动下载最新版并校验 SHA-256。

它会：下载 release 压缩包 → 校验 checksum → 校验压缩包内容 → 试运行 → 停止旧守护进程 → 替换二进制 → 写入客户端配置。

```powershell
cd D:\env\codebase-memory-mcp-ui-windows-amd64

# 如果文件被浏览器/Invoke-WebRequest 标记为"来自 Internet"
Unblock-File .\install.ps1

# 如果执行策略报错
Set-ExecutionPolicy -Scope Process Bypass

# 安装（默认目录：%LOCALAPPDATA%\Programs\codebase-memory-mcp）
.\install.ps1

# 可选参数
.\install.ps1 --skip-config
.\install.ps1 --dir="D:\tools\cbm"
```

> 如果公司网络无法访问 GitHub，方式 B 会卡在下载；直接用方式 A。

### 安装后验证

**新开一个终端**，执行：

```powershell
codebase-memory-mcp --version
```

如果提示找不到命令，说明 PATH 还没刷新，或安装目录不在 PATH 里。可以临时用完整路径调用，或检查用户环境变量 `Path`。

### 关于杀毒软件误报

官方说明：Microsoft Defender 可能把发布版二进制报成 `Trojan:Script/Wacatac.B!ml`，这是**已知误报**（同类误报也命中过 `gh`、llama.cpp、Godot 等）。发布包有 SHA-256 校验，并且每个 release 都经过 VirusTotal 扫描。详见仓库 `SECURITY.md`。

---

## 4. 打开网页界面（CBM Lens）

这是最直观的使用方式：把代码仓库变成可点击、可缩放的"地图"。

### 4.1 启动

```powershell
# 建议先把界面语言设为中文（可选）
codebase-memory-mcp config set ui-lang zh

# 启动本地服务并自动打开浏览器
codebase-memory-mcp daemon start --open --port=9749
```

浏览器会打开：**<http://127.0.0.1:9749>**

本机已验证：服务启动后该地址返回 HTTP 200，UI 正常提供。

常用守护进程命令：

```powershell
codebase-memory-mcp daemon status   # 查看是否在运行、端口、版本
codebase-memory-mcp daemon stop     # 用完关掉
```

> 说明：`daemon` 是"常驻后台服务"，负责网页、文件监听、后台索引等长期任务。
> 不启动它也能用 MCP 和 CLI，只是它们每次要自己临时启动，速度稍慢。

### 4.2 索引第一个项目

1. 打开页面后，点左上角**项目菜单** → **Add project index**（也可以按 `Alt+P`）。
2. 选择你的代码仓库文件夹。
3. 给索引起个名字（后面 CLI 和 URL 都会用到这个名字）。
4. 点击开始索引，观察进度。
   - 索引在后台运行，**可以关掉对话框**，之后从项目菜单重新打开进度。
5. 索引完成后打开项目：
   - 想先看整体 → 进 **Architecture**
   - 想直接读代码 → 进 **Explore**

> 文件不会被移动或复制，索引数据单独存在本地缓存目录里。

### 4.3 六个工作区分别干什么

| 工作区 | 适合做什么 |
|--------|------------|
| **Explore（浏览）** | 像 IDE 一样浏览文件树，用 Monaco 编辑器看源码；右侧显示"文件影响"（谁依赖这个文件）和"代码详情"（光标所在函数的调用者、被调用者、引用、相关测试）。 |
| **Galaxy（星系图）** | 在 3D 图里搜索节点，一层层展开邻居，查看调用路径；按 `Ctrl+K` 全局搜索符号/文件/文件夹。 |
| **Architecture（架构）** | 文件夹 3D 地图、入口点、路由、热点、系统结构、行为路径。选中节点或连线可查看证据。 |
| **ADR（架构决策记录）** | 阅读/编辑项目的架构决策文档。保存后存进索引，与 `manage_adr` 工具共享。 |
| **Coverage（覆盖率）** | 查看哪些文件被索引了、哪些只解析了一部分、哪些被跳过/排除。**查不到东西时先来这里看。** |
| **System（系统）** | 查看守护进程状态、索引列表、日志（可按项目/级别/文字过滤）。 |

### 4.4 架构视图里的五个视角

- **Overview（总览）**：3D 文件夹地图，高度可表示源码体积，颜色可表示语言或类型。
- **Entry points（入口点）**：从某个入口函数出发，沿着静态调用图往下看。
- **Routes（路由）**：服务地图与端点连接，区分"部署元数据"和"索引到的路由证据"。
- **Hotspots（热点）**：按 fan-in、复杂度等信号找被频繁引用的代码。它是"热度"，**不是代码质量评分**。
- **System structure / Behavior（系统结构 / 行为）**：组件依赖、循环依赖；从起点到终点的静态调用路径及源码证据。注意：这是**可能**的调用关系，不代表运行时真实执行顺序。

### 4.5 收藏某个视图

URL 支持直接定位，例如：

```
http://127.0.0.1:9749/?project=我的项目&workspace=architecture
```

`workspace` 可选：`explore`、`galaxy`、`architecture`、`adr`、`coverage`、`system`。

### 4.6 用 AI 解释代码（可选）

右上角机器人图标 → 选择本地模型 → **Download & load**。

- 默认模型 Qwen2.5 Coder 0.5B，约 **567 MB**，从 Hugging Face 下载。
- 需要浏览器支持 **WebGPU + shader-f16**。
- **推理在浏览器本地完成**，不需要 API Key，不会把代码发到云端。
- 问"谁调用了 `xxx`"这类问题时，答案直接来自索引图谱，不经过模型；模型只负责补充一句解释。

> 这个聊天只能"解释"你给它的代码，不能改文件、不能执行命令。

### 4.7 关闭

```powershell
codebase-memory-mcp daemon stop
```

---

## 5. 命令行用法（CLI）

CLI 的价值：不打开 AI、不打开网页，也能快速查图谱；也方便写脚本。

### 5.1 基本格式

```powershell
codebase-memory-mcp cli [全局选项] <工具名> [工具参数]
```

全局选项：

| 选项 | 作用 |
|------|------|
| `--quiet` | 只显示错误 |
| `--progress` | 强制显示索引进度（stderr 被重定向时有用） |
| `--verbose` | 显示更多诊断信息 |
| `--json` | 输出完整的 MCP 结果信封 |
| `--format json` | 输出结构化 JSON（写在工具参数里） |

### 5.2 索引项目

```powershell
# 同步索引（项目大时可能等很久）
codebase-memory-mcp cli index_repository --repo-path "D:\work\my-project"

# 只做快速索引（不做语义分析，适合先跑通）
codebase-memory-mcp cli index_repository --repo-path "D:\work\my-project" --mode fast

# 自定义项目名（之后 --project 用这个名字）
codebase-memory-mcp cli index_repository --repo-path "D:\work\my-project" --name my-project
```

索引模式：

| 模式 | 用途 |
|------|------|
| `full` | 完整索引 + 语义分析（默认） |
| `moderate` | 过滤后索引 + 语义分析 |
| `fast` | 过滤后索引，不做语义分析 |
| `cross-repo-intelligence` | 跨项目关联服务 |

**大项目建议用异步模式**，避免客户端超时：

```powershell
# 先确保常驻守护进程在跑
codebase-memory-mcp daemon start

# 启动后台索引，立即返回
codebase-memory-mcp cli index_repository --repo-path "D:\work\my-project" --async true

# 轮询状态（repo_path 要和上面一致）
codebase-memory-mcp cli index_repository --repo-path "D:\work\my-project" --status true
```

状态值：`queued` / `running` / `cancelling` / `succeeded` / `failed` / `cancelled`。

> 注意：如果异步索引的 CLI 命令是守护进程的**唯一**客户端，命令退出后任务会失去宿主，因此会被拒绝。先 `daemon start`，或开着一个 MCP 会话。

### 5.3 查看已索引的项目

```powershell
codebase-memory-mcp cli list_projects
codebase-memory-mcp cli list_projects --format json --detail stats
```

返回的 `name` 就是后面 `--project` 要用的值。

### 5.4 常用查询

```powershell
# 按名字找函数/类（正则）
codebase-memory-mcp cli search_graph --project my-project --name-pattern ".*Handler.*" --label Function

# 查调用链：谁调用 / 被谁调用
codebase-memory-mcp cli trace_path --project my-project --function-name ProcessOrder --direction both --depth 3

# 直接写 Cypher 风格查询（只读）
codebase-memory-mcp cli query_graph --project my-project --query "MATCH (f:Function)-[:CALLS]->(g) WHERE f.name = 'main' RETURN g.name LIMIT 20"

# 读某个函数的源码（参数是 qualified name）
codebase-memory-mcp cli get_code_snippet --project my-project --qualified-name "my-project.src.order.ProcessOrder"

# 看一个文件的声明大纲
codebase-memory-mcp cli get_file_outline --project my-project --file-path "src/order.c"

# 架构概览
codebase-memory-mcp cli get_architecture --project my-project

# 改代码前：哪些符号受影响
codebase-memory-mcp cli detect_changes --project my-project --scope impact

# 只看改了哪些文件
codebase-memory-mcp cli detect_changes --project my-project --scope files

# 索引覆盖情况（哪些文件没被完整解析）
codebase-memory-mcp cli check_index_coverage --project my-project
```

`qualified name`（限定名）的格式是：

```
<项目名>.<路径部分>.<名称>
```

不知道限定名时，先用 `search_graph` 搜。

### 5.5 每个工具的完整参数

```powershell
codebase-memory-mcp cli <工具名> --help
```

例如：

```powershell
codebase-memory-mcp cli trace_path --help
codebase-memory-mcp cli search_graph --help
```

### 5.6 输出小技巧

```powershell
# 机器可读 JSON，方便配合 jq / PowerShell 处理
codebase-memory-mcp cli list_projects --format json

# 完整 MCP 信封
codebase-memory-mcp cli --json get_architecture --project my-project

# 安静模式 + JSON
codebase-memory-mcp cli --quiet list_projects --format json
```

---

## 6. 接入 AI 编程助手（MCP）

### 6.1 自动配置（推荐）

如果你在第 3 步运行了 `install`（没有加 `--skip-config`），它已经自动配置了检测到的客户端。

本机 `--dry-run` 检测到的客户端：

```
Claude-Code  Codex  OpenCode  VS-Code  Cursor  OpenClaw  Cline  Copilot-CLI
```

安装后：

1. **重启 AI 客户端**（不是只重开窗口，必要时完全退出再启动）。
2. 在 Claude Code 里输入 `/mcp`，应该能看到 `codebase-memory-mcp`，并且有 **17 个工具**。
3. 直接对助手说：**"索引这个项目"** 或 **"Index this project"**。

### 6.2 安装给 AI 客户端加了什么

| 组件 | 作用 |
|------|------|
| **MCP 配置** | 让客户端能调用 17 个图谱工具 |
| **Instructions / Skill** | 教 AI 优先用图谱查、检查索引新鲜度和覆盖率、什么时候该读源码 |
| **Scout / Verify / Auditor 三个子代理** | 三档工作方式：快速初查 / 按任务验证（默认） / 有边界的完整审计 |
| **Hooks** | 在会话开始、压缩后、Grep/Read 等操作时，自动补充图谱上下文 |

Hooks 是**只加上下文、不拦截**的（fail-open），不会阻止你原本的工具调用。

> 不同客户端支持程度不同，例如 Cursor 不装 hooks，部分客户端只装 skill 或 MCP。
> 完整的 45 个客户端支持矩阵见官方 README 的 "Multi-Agent Support"。

### 6.3 手动配置（不想用 install 时）

以 Claude Code 为例，在用户级 `~/.claude.json` 或项目级 `.mcp.json` 中加入：

```json
{
  "mcpServers": {
    "codebase-memory-mcp": {
      "command": "C:/Users/你的用户名/.local/bin/codebase-memory-mcp.exe",
      "args": []
    }
  }
}
```

注意：

- 路径**必须是绝对路径**，JSON 里反斜杠要转义（或直接用 `/`）。
- 改完重启客户端。
- 手动配置只提供 MCP 工具，不含 skill / 子代理 / hooks。

### 6.4 直接用 Claude Code 插件（另一种方式）

```bash
claude plugin marketplace add DeusData/codebase-memory-mcp
claude plugin install codebase-memory@codebase-memory
```

> **不要和 `install` 同时用**，否则会出现两个工具命名空间（`mcp__codebase-memory-mcp__*` 和 `mcp__plugin_...__*`）。
> 想要完整功能选 `install`；只想加个 MCP 服务选插件。

### 6.5 和 AI 对话的推荐问法

安装 skill 后，AI 会知道优先查图谱。你可以直接这样问：

- "用 codebase-memory 查一下 `ProcessOrder` 被谁调用。"
- "这个仓库的架构概览是什么？"
- "改 `src/order.c` 里的 `ProcessOrder` 会影响哪些地方？顺便看看相关测试。"
- "这个服务是怎么部署的？镜像、Dockerfile、入口程序分别是什么？"
- "索引覆盖率怎么样？有没有文件没被解析？"

---

## 7. 五个典型使用场景

### 场景 1：接手一个陌生仓库

```powershell
codebase-memory-mcp cli index_repository --repo-path "D:\work\unknown-repo" --mode fast
codebase-memory-mcp cli get_architecture --project unknown-repo
codebase-memory-mcp cli search_graph --project unknown-repo --name-pattern ".*[Mm]ain.*"
```

然后打开网页，进 **Architecture → Overview** 看整体，再进 **Explore** 读代码。

### 场景 2：查一个函数的上下游

```powershell
codebase-memory-mcp cli search_graph --project my-project --name-pattern ".*ProcessOrder.*"
codebase-memory-mcp cli trace_path --project my-project --function-name ProcessOrder --direction both --depth 5
```

`direction`：

- `inbound`：谁调用我（找调用者）
- `outbound`：我调用谁（找依赖）
- `both`：双向

### 场景 3：改代码前评估影响

```powershell
# 基于 git diff，列出受影响的符号和传播范围
codebase-memory-mcp cli detect_changes --project my-project --scope impact

# 只关心测试影响
codebase-memory-mcp cli detect_changes --project my-project --scope tests
```

建议先提交或至少保存当前改动，再对比。

### 场景 4：查部署链路

```powershell
# 服务 → 工作负载 → 镜像 → Dockerfile → 程序
# --function-name 填索引里的服务/工作负载名称
codebase-memory-mcp cli trace_path --project my-project --function-name <服务或工作负载名> --mode run

# K8s 资源 / 路由 / 控制器拓扑
codebase-memory-mcp cli trace_path --project my-project --function-name <资源或路由名> --mode topology

# CI job / 脚本 / Make 目标部署了什么
codebase-memory-mcp cli trace_path --project my-project --function-name <job或脚本名> --mode deploy
```

> 这些是**静态关系**：动态变量、模板未解析的地方可能断链。查不到时先看 Coverage。

### 场景 5：把架构决策写进索引

```powershell
codebase-memory-mcp cli manage_adr --project my-project --mode outline
codebase-memory-mcp cli manage_adr --project my-project --mode get
```

网页里的 **ADR** 工作区可以直接编辑。它保存的是索引里的文档，**不会修改你仓库里的文件**。

---

## 8. 配置、数据与文件位置

### 8.1 本机实际位置（已验证）

| 内容 | 路径 |
|------|------|
| 安装目录（方式 A） | `C:\Users\<你>\.local\bin\` |
| 安装目录（方式 B 默认） | `C:\Users\<你>\AppData\Local\Programs\codebase-memory-mcp\` |
| **索引与配置缓存** | `C:\Users\<你>\.cache\codebase-memory-mcp\` |
| 配置数据库 | `C:\Users\<你>\.cache\codebase-memory-mcp\_config.db` |
| 日志 | `C:\Users\<你>\.cache\codebase-memory-mcp\logs\` |
| 守护进程日志 | `...\logs\cbm-daemon.log` |
| 网页日志 | `...\logs\ui.log` |
| 进程冲突记录 | `...\logs\daemon-conflicts.ndjson` |
| 安装/更新记录 | `...\logs\activation-events.ndjson` |

索引是 SQLite 数据库（WAL 模式），重启后仍然存在。

> 想整体重置：先 `daemon stop`，再删除 `%USERPROFILE%\.cache\codebase-memory-mcp`。
> 想换存储位置：设置环境变量 `CBM_CACHE_DIR`（见 8.4）。

### 8.2 运行时配置

```powershell
codebase-memory-mcp config list
codebase-memory-mcp config get auto_index
codebase-memory-mcp config set <key> <value>
codebase-memory-mcp config reset <key>
```

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `auto_index` | `false` | 新项目在 MCP 会话首次连接时自动索引 |
| `auto_index_limit` | `50000` | 自动索引的最大文件数 |
| `auto_watch` | `true` | 允许 MCP 会话注册的后台文件监听 |
| `watcher_enabled` | `true` | 是否启动后台监听线程（改完要 `daemon stop` 再启动） |
| `watch_non_git` | `false` | 非 git 目录是否也轮询变化 |
| `doc_candidates` | `auto` | 文档↔代码候选匹配；大仓库可设 `false` 提速 |
| `ui-lang` | `auto` | 网页语言：`en` / `zh` / `auto` |
| `ui_enabled` | 见当前配置 | 是否提供网页 UI |
| `ui_port` | `9749` | 网页端口 |
| `index_max_files` | `off` | 单次索引的最大源文件数 |
| `index_max_source_mb` | `off` | 单次索引的最大源码体积（MiB） |

> `index_max_*` 一旦超限，**整次索引失败**，而不是发布一个残缺的图；已有索引会保留。

### 8.3 忽略不想索引的目录

索引默认会跳过 `.git`、`node_modules` 等，并遵循 `.gitignore`。
还可以在仓库根目录放一个 `.cbmignore`（语法和 `.gitignore` 一样）：

```gitignore
dist/
build/
vendor/
*.min.js
data/models/
```

优先级：内置规则 → `.gitignore` 层级 → `.cbmignore`。
符号链接始终跳过。

### 8.4 环境变量

| 变量 | 默认 | 说明 |
|------|------|------|
| `CBM_CACHE_DIR` | `%USERPROFILE%\.cache\codebase-memory-mcp` | 索引和配置的存放目录 |
| `CBM_ALLOWED_ROOT` | 未设置 | 限制 `index_repository` 只能索引这个目录下的路径。**把服务暴露给不可信调用方时建议设置。** |
| `CBM_LOG_LEVEL` | 按角色 | `debug` / `info` / `warn` / `error` / `none` |
| `CBM_WORKERS` | 自动检测 | 并行索引线程数（1–256） |
| `CBM_MEM_BUDGET_MB` | 自动检测 | 内存图谱预算上限（MiB） |
| `CBM_DIAGNOSTICS` | `false` | 设为 `1` 生成 `trajectory.ndjson` / `snapshot.json` 诊断文件 |
| `CBM_DOWNLOAD_URL` | GitHub Releases | 更新时的下载地址（测试/自建镜像用） |

示例：

```powershell
$env:CBM_CACHE_DIR = "D:\cbm-data"
codebase-memory-mcp config list
```

> 守护进程会"记住"启动它时的环境变量。改了这类变量后，要先关掉所有 CBM 会话和守护进程，再重新启动。

### 8.5 自定义文件扩展名

有些框架用特殊后缀（如 `.blade.php`、`.mjs`）。在仓库根目录建 `.codebase-memory.json`：

```json
{
  "extra_extensions": {
    ".blade.php": "php",
    ".mjs": "javascript"
  }
}
```

全局配置放在 `%USERPROFILE%\.config\codebase-memory-mcp\config.json`。项目配置优先。

---

## 9. 更新与卸载

### 9.1 更新

`update` **不会自己替换二进制**，而是打印出应该运行的安装脚本命令：

```powershell
codebase-memory-mcp update
```

按提示执行（安装脚本是幂等的，重跑就是更新）：

```powershell
powershell -File "C:\Users\<你>\.local\bin\install.ps1"
```

如果你是用方式 A 安装的，并且没有把 `install.ps1` 放到安装目录，直接重新下载新版压缩包，再用新 exe 执行一次 `install -y --force` 即可。

### 9.2 卸载

```powershell
# 先预览
codebase-memory-mcp uninstall --dry-run

# 卸载程序 + 清理它写入的 AI 客户端配置，但保留索引
codebase-memory-mcp uninstall -y

# 连索引一起删除（明确同意）
codebase-memory-mcp uninstall -y --delete-indexes
```

默认**保留**已有索引。安装目录里的 `install.ps1` 不会被删除，只会在输出里告诉你路径。

---

## 10. 常见问题排查

| 现象 | 原因 / 解决 |
|------|-------------|
| 网页打不开 / `server unreachable` | 确认守护进程在跑：`daemon status`；确认端口：`http://127.0.0.1:9749`；必要时 `config set ui_enabled true` 后 `daemon stop` + `daemon start`。 |
| 网页提示 `Architecture is not available yet` | `?project=` 里的项目名和索引名不完全一致。从项目菜单里选，或 `list_projects` 查准确名字。 |
| `index_repository` 失败 | 传**绝对路径**；Windows 路径加引号。 |
| 索引在客户端里超时 | 用 `--async true` 启动，再 `--status true` 轮询。 |
| `trace_path` 返回 0 条 | 名字不精确。先 `search_graph --name-pattern ".*关键字.*"` 找到准确名称。 |
| 查询结果像是别的项目 | 加 `--project 项目名`。用 `list_projects` 确认。 |
| 某些文件查不到 | 去 Coverage 看是否被跳过/只解析了一部分；检查 `.gitignore` / `.cbmignore`。 |
| 大仓库索引很慢/内存高 | 先用 `--mode fast`；用 `.cbmignore` 排除 `dist/`、模型目录、大二进制；必要时设 `index_max_files` / `index_max_source_mb`。 |
| Windows 索引 worker 卡住/崩溃（旧版） | v0.10.5 之前有已知问题；当前 0.12.1 已改进。仍出现时用 `.cbmignore` 排除大二进制/媒体/模型目录。 |
| `daemon-conflicts.ndjson` 里有冲突 | 同时运行的 CBM 进程版本、构建、缓存目录必须完全一致。关掉旧进程，统一升级。 |
| 安装后 `/mcp` 看不到服务 | `.mcp.json` 里路径必须是绝对路径；重启客户端；用 `echo '{}' | codebase-memory-mcp.exe` 测试是否输出 JSON。 |
| PATH 里找不到命令 | 重开终端；检查 `%USERPROFILE%\.local\bin` 是否在用户 PATH。 |
| 杀毒软件报毒 | 已知误报，见第 3 节。 |

### 要看日志时

- 网页里：**System → Logs**（可按项目、级别、文字过滤）。
- 文件：`%USERPROFILE%\.cache\codebase-memory-mcp\logs\cbm-daemon.log`、`ui.log`。
- 内存/性能问题：设置 `CBM_DIAGNOSTICS=1` 后复现，生成 `trajectory.ndjson`（只有资源计数，不含源码或查询内容）。

---

## 11. 隐私与安全

- **索引和查询全在本地完成**，不上传源码，不收集遥测。
- **程序自己不会主动联网**：不后台检查更新、不 phone home。
- 会联网的情况只有三种：
  1. 你运行安装/更新脚本时下载 release；
  2. 你在网页里主动下载本地聊天模型（来自 Hugging Face）；
  3. 你自己配置的 AI 客户端本身需要联网。
- 网页只监听 **127.0.0.1（loopback）**，局域网其他机器访问不到。
- 如果可能被不可信的程序调用 MCP，设置 `CBM_ALLOWED_ROOT`，把可索引范围限制在指定目录内。

---

## 12. 速查表（可以只记这一页）

```powershell
# ---- 安装 ----
.\codebase-memory-mcp.exe install --dry-run -y          # 预览
.\codebase-memory-mcp.exe install -y --force            # 安装
.\codebase-memory-mcp.exe install -y --force --clients=claude

# ---- 网页 ----
codebase-memory-mcp config set ui-lang zh
codebase-memory-mcp daemon start --open --port=9749
codebase-memory-mcp daemon status
codebase-memory-mcp daemon stop

# ---- 索引 ----
codebase-memory-mcp cli index_repository --repo-path "D:\work\repo"
codebase-memory-mcp cli index_repository --repo-path "D:\work\repo" --mode fast
codebase-memory-mcp cli index_repository --repo-path "D:\work\repo" --async true
codebase-memory-mcp cli index_repository --repo-path "D:\work\repo" --status true
codebase-memory-mcp cli list_projects

# ---- 查询 ----
codebase-memory-mcp cli search_graph --project P --name-pattern ".*Foo.*"
codebase-memory-mcp cli trace_path --project P --function-name Foo --direction both --depth 3
codebase-memory-mcp cli query_graph --project P --query "MATCH (f:Function) RETURN f.name LIMIT 10"
codebase-memory-mcp cli get_code_snippet --project P --qualified-name "P.src.a.Foo"
codebase-memory-mcp cli get_file_outline --project P --file-path "src/a.c"
codebase-memory-mcp cli get_architecture --project P
codebase-memory-mcp cli detect_changes --project P --scope impact
codebase-memory-mcp cli check_index_coverage --project P

# ---- 配置 ----
codebase-memory-mcp config list
codebase-memory-mcp config set auto_index true
codebase-memory-mcp config set auto_watch false
codebase-memory-mcp config reset auto_index

# ---- 维护 ----
codebase-memory-mcp update
codebase-memory-mcp uninstall --dry-run
codebase-memory-mcp uninstall -y
```

---

## 附录 A：17 个 MCP 工具速查

| 工具 | 一句话作用 |
|------|------------|
| `index_repository` | 索引仓库；支持 `async` / `status` |
| `list_projects` | 列出已索引项目，`detail:"stats"` 看节点/边数量 |
| `delete_project` | 删除项目及其图数据、ADR |
| `index_status` | 查看某项目的索引状态和新鲜度 |
| `check_index_coverage` | 检查指定路径/范围是否被索引、是否完整 |
| `search_graph` | 结构搜索 + BM25 全文 + 语义搜索 |
| `search_code` | 在已索引文件里做 grep 式文本搜索 |
| `trace_path` | 调用链/数据流/跨服务/拓扑/部署/运行路径追踪 |
| `query_graph` | 只读 Cypher 子集查询 |
| `get_graph_schema` | 查看节点/边类型和属性定义；**建议先用它** |
| `compare_graphs` | 比较两个索引快照的增删 |
| `get_code_snippet` | 按限定名读取源码 |
| `get_file_outline` | 按源码顺序列出一个文件的声明大纲 |
| `get_architecture` | 架构概览：语言、包、路由、热点、聚类、ADR |
| `detect_changes` | 把 git diff 映射到受影响符号和影响范围 |
| `manage_adr` | 架构决策记录的增删改查 |
| `ingest_traces` | 导入外部采集的运行轨迹，作为"观测到的调用" |

---

## 附录 B：概念对照表

| 英文 | 中文 | 你可以怎么理解 |
|------|------|----------------|
| MCP | Model Context Protocol | AI 客户端调用外部工具的通用协议 |
| Graph / Knowledge Graph | 知识图谱 | 代码的"对象 + 关系"地图 |
| Node / Edge | 节点 / 边 | 代码实体 / 实体间关系 |
| Qualified Name | 限定名 | `<项目>.<路径>.<名称>` 形式的唯一标识 |
| Index | 索引 | 把代码解析后存进本地数据库的结果 |
| Coverage | 覆盖率 | 哪些文件真的被索引到了 |
| ADR | Architecture Decision Record | 架构决策记录 |
| Daemon | 守护进程 | 常驻后台，提供网页、监听、后台索引 |
| MCP Tool | MCP 工具 | AI 可以调用的一个能力，共 17 个 |
| Watcher | 文件监听器 | 文件变了自动重新索引 |

---

## 附录 C：本手册在本机的验证记录

| 验证项 | 结果 |
|--------|------|
| `codebase-memory-mcp.exe --version` | `0.12.1` |
| `--help` | 列出 17 个工具、45 个客户端 |
| `config list` | 正常读取配置 |
| `list_projects` | 正常返回（当前 0 个项目） |
| `install --dry-run` | 检测到 8 个客户端；默认安装到 `C:\Users\admin\.local\bin` |
| `daemon start --port=9749` + HTTP 请求 | 返回 HTTP 200，UI 正常 |
| `daemon status` / `daemon stop` | 正常 |
| 索引缓存目录 | `C:\Users\admin\.cache\codebase-memory-mcp` |

> 说明：本次只做了只读验证，**没有执行正式安装**，也没有修改任何 AI 客户端的配置。需要安装时请按第 3 节自行执行。
