# https://github.com/shdra06/ai-mind-map 项目说明书

生成时间：2026-06-23 18:37:57 UTC

## 目录

- [项目概览](#page-overview)
- [安装与代理集成](#page-installation)
- [系统架构](#page-architecture)
- [知识图谱与变更跟踪](#page-knowledge-graph)

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

## 项目概览

### 相关页面

相关主题：[安装与代理集成](#page-installation), [系统架构](#page-architecture)

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

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

- [README.md](https://github.com/shdra06/ai-mind-map/blob/main/README.md)
- [package.json](https://github.com/shdra06/ai-mind-map/blob/main/package.json)
- [src/context/compressor.ts](https://github.com/shdra06/ai-mind-map/blob/main/src/context/compressor.ts)
- [src/context/token-budget.ts](https://github.com/shdra06/ai-mind-map/blob/main/src/context/token-budget.ts)
- [src/context/progressive-disclosure.ts](https://github.com/shdra06/ai-mind-map/blob/main/src/context/progressive-disclosure.ts)
- [src/change-tracker/diff-engine.ts](https://github.com/shdra06/ai-mind-map/blob/main/src/change-tracker/diff-engine.ts)
- [src/change-tracker/change-log.ts](https://github.com/shdra06/ai-mind-map/blob/main/src/change-tracker/change-log.ts)
</details>

# 项目概览

## 项目定位与目标

AI Mind Map 是一个 **MCP（Model Context Protocol）服务器**，其核心目标是显著降低 AI 编程助手（如 Claude、Cursor、Copilot 等）在处理代码库时的 Token 消耗。根据官方说明，它通过持久化的代码库记忆、知识图谱和智能上下文管理，可实现 **80–99% 的 Token 减少**，从而避免 AI 反复读取整个代码库造成的浪费。

资料来源：[README.md:1-30]()

项目以 `ai-mind-map` 作为 npm 包名发布，并通过 `bin` 字段同时提供 `ai-mind-map`（CLI 入口）和 `ai-mind-map-server`（MCP 服务器入口）两个可执行命令，方便用户通过 `npx ai-mind-map install` 一键完成安装与配置。

资料来源：[package.json:1-50]()

## 技术栈与依赖

项目使用 Node.js（`>=18.0.0`）作为运行环境，核心依赖包括：

| 依赖 | 用途 |
|------|------|
| `@modelcontextprotocol/sdk` | MCP 协议通信 |
| `better-sqlite3` | 本地持久化与 FTS5 全文检索 |
| `tree-sitter` + 各语言 grammar（可选依赖） | 多语言 AST 解析 |
| `simple-git` | Git 差异与历史分析 |
| `chokidar` | 文件系统实时监听 |
| `zod` | 运行时参数校验 |

资料来源：[package.json:50-90]()

`type: "module"` 表明整个项目采用原生 ESM，TypeScript 通过 `tsc` 编译为 `dist/` 目录下的 JavaScript 输出，并附带 `prepublishOnly` 钩子确保发布前完成构建与测试。

## 核心架构

AI Mind Map 的整体架构由三个主要子系统组成：**知识图谱（Knowledge Graph）**、**变更追踪（Change Tracker）**、**记忆系统（Memory）**，它们共同汇聚到 **上下文引擎（Context Engine）**，并最终通过 MCP 协议以 stdio 方式暴露给 AI Agent。

```mermaid
flowchart TB
    subgraph K["知识图谱"]
        TS[Tree-sitter AST]
        SQL[SQLite + FTS5]
        PR[PageRank]
    end
    subgraph C["变更追踪"]
        CH[Chokidar Watcher]
        GIT[Git Diff Engine]
        CL[Change Log + BM25]
    end
    subgraph M["记忆系统"]
        MEM[Persistent Memory]
        DEC[Decisions]
    end
    subgraph E["上下文引擎"]
        CMP[Content-Aware Compression]
        PD[Progressive Disclosure 3-Tier]
        TBM[Token Budget Manager]
    end
    K --> E
    C --> E
    M --> E
    E -->|MCP stdio| AI[AI Agent]
```

资料来源：[README.md:120-180]()、[src/context/progressive-disclosure.ts:1-30]()

## 关键模块说明

### 内容感知压缩（Content-Aware Compression）

`compressor.ts` 提供三种压缩等级 —— `minimal`（清理空白与注释）、`moderate`（保留签名与文档注释，用 `{ ... }` 替换函数体）、`aggressive`（仅保留签名或仅保留错误信息）。它会自动检测 `source_code`、`build_log`、`test_output`、`stack_trace`、`json_data`、`markdown`、`diff`、`config_file`、`plain_text` 共 9 种内容类型并选用相应策略。

资料来源：[src/context/compressor.ts:1-60]()

### 渐进式披露（Progressive Disclosure）

`progressive-disclosure.ts` 实现三层上下文加载：**Tier 1（常驻，≤500 tokens）** 包含项目身份、目录骨架与当前任务；**Tier 2（可搜索，≤2000 tokens）** 包含知识图谱查询结果、近期变更、相关记忆与活跃决策；**Tier 3（按需加载）** 才输出完整压缩文件内容、详细测试输出与历史 diff。每个层级都有独立的 Token 预算。

资料来源：[src/context/progressive-disclosure.ts:1-50]()

### Token 预算管理

`token-budget.ts` 借鉴 Aider 的 `--map-tokens` 思路，对 `graphResults`、`changeSummary`、`memoryRetrieval`、`fileContent` 四个组件分别分配预算，并支持智能截断、动态再分配与格式化预算报告。

资料来源：[src/context/token-budget.ts:1-60]()

### 变更追踪

`diff-engine.ts` 基于 `simple-git` 提供 Git 感知的差异分析，并在项目非 Git 仓库时回退到文件系统时间戳。`change-log.ts` 则使用 SQLite + FTS5 实现持久化变更历史，支持 BM25 排序检索、会话管理与按符号/时间范围查询。

资料来源：[src/change-tracker/diff-engine.ts:1-50]()、[src/change-tracker/change-log.ts:1-60]()

## 三层记忆模型

AI Mind Map 借鉴认知科学中的记忆分层，将记忆划分为：

- **工作记忆（Working Memory）**：当前任务上下文，全量加载；
- **情景记忆（Episodic Memory）**：会话摘要与近期决策，按需检索；
- **语义记忆（Semantic Memory）**：代码库图谱、架构与约定，仅查询、永不整体导出。

每条记忆都有重要性评分，访问时递增、随时间衰减（默认每天 5%），低于阈值时被剪枝，确保有用记忆得以保留、陈旧记忆自然消退。

资料来源：[README.md:180-220]()

## 安装与运行

最新 v2.0.0 版本在 CLI、Cyphter-like 图查询、测试套件、CI/CD 与安装器方面完成了生产级升级。用户可执行 `npx ai-mind-map install` 自动检测并配置 7 种主流 AI Agent；`ai-mind-map doctor` 用于诊断环境；`ai-mind-map index /path/to/project` 用于建立索引。

资料来源：[README.md:60-100]()

---

**See Also**
- [安装与配置](./installation.md)
- [MCP 工具参考](./tools-reference.md)
- [架构深入](./architecture.md)

---

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

## 安装与代理集成

### 相关页面

相关主题：[项目概览](#page-overview)

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

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

- [src/install.ts](https://github.com/shdra06/ai-mind-map/blob/main/src/install.ts)
- [install.sh](https://github.com/shdra06/ai-mind-map/blob/main/install.sh)
- [install.ps1](https://github.com/shdra06/ai-mind-map/blob/main/install.ps1)
- [setup.bat](https://github.com/shdra06/ai-mind-map/blob/main/setup.bat)
- [docs/AGENT_GUIDE.md](https://github.com/shdra06/ai-mind-map/blob/main/docs/AGENT_GUIDE.md)
- [templates/CLAUDE.md](https://github.com/shdra06/ai-mind-map/blob/main/templates/CLAUDE.md)
- [package.json](https://github.com/shdra06/ai-mind-map/blob/main/package.json)
- [README.md](https://github.com/shdra06/ai-mind-map/blob/main/README.md)
</details>

# 安装与代理集成

本页面向初次接触 **AI Mind Map** 的开发者与运维人员，介绍如何在不同操作系统上完成 MCP（Model Context Protocol）服务器的安装、依赖准备，以及如何与主流 AI 编码代理（Claude、Cursor、Copilot、Windsurf 等）进行集成。

## 项目定位与运行前置条件

AI Mind Map 本质上是一个本地运行的 MCP 服务器，通过 stdio 协议向 AI 代理暴露 **41 个工具**，覆盖知识图谱查询、语义搜索、变更追踪、记忆系统与高级分析等能力 [资料来源：[README.md:1-80]()]。整个服务器以 Node.js 进程方式驻留用户侧，依赖本地 SQLite 索引、Tree-sitter 解析器和 Git 仓库信息。

运行前必须满足的最低前置条件：

| 项目 | 要求 | 来源 |
|------|------|------|
| Node.js | `>= 18.0.0` | [package.json](package.json) 中 `engines` 字段 |
| 包管理器 | npm（随 Node.js 附带） | 由 `package.json` 推断 |
| 协议支持 | `@modelcontextprotocol/sdk ^1.12.1` | 依赖声明 |
| 持久化 | `better-sqlite3 ^11.8.2` | 依赖声明 |
| 文件监听 | `chokidar ^4.0.3` | 依赖声明 |
| 多语言 AST | 可选 `tree-sitter-*` 语言包 | optionalDependencies |

仓库要求 MIT 协议、TypeScript `^5.8.3` 编译、tsx `^4.22.4` 直接执行，因此开发模式也只需 Node.js 18+ 即可启动 [资料来源：[package.json:1-80]()]。

## 安装流程与跨平台脚本

仓库提供三条并行的安装入口，分别面向 Unix 类系统与 Windows 系统，目的是把"克隆 → 依赖安装 → 构建 → 注册到代理"串成一步。

### 通用安装步骤

1. 克隆仓库并进入目录。
2. 执行对应平台的安装脚本：
   - **macOS / Linux**：`./install.sh`
   - **Windows PowerShell**：`./install.ps1`
   - **Windows CMD**：`./setup.bat`
3. 脚本将完成 `npm install`、`npm run build`，并把构建产物 `dist/` 暴露给后续的代理注册步骤。

`src/install.ts` 承担安装编排逻辑，封装了与各平台脚本共享的步骤（依赖检查、构建、写入代理配置）[资料来源：[src/install.ts:1-120]()]。这种"脚本外壳 + TS 内核"的设计，让 PowerShell / Bash 脚本保持轻量、只做平台差异处理，把真正的安装语义集中在 TypeScript 模块里以便单测覆盖。

### 跨平台差异点

- **可执行权限**：Unix 脚本需要在首次运行前 `chmod +x install.sh`；Windows 脚本由 PowerShell 执行策略决定，可能需要 `Set-ExecutionPolicy -Scope Process Bypass` 临时放行。
- **路径分隔符**：`install.ps1` 与 `setup.bat` 自动处理反斜杠与盘符，而 `install.sh` 使用 POSIX 路径。
- **构建产物**：`npm run build` 在所有平台都生成相同的 `dist/index.js`，这是 MCP stdio 通信的入口 [资料来源：[README.md:1-80]()]。

## 代理集成：把 41 个工具接入 AI

安装完成后，需要让 AI 代理知道如何启动 MCP 服务器。这通过编辑代理自己的配置文件实现。

### 配置结构

AI Mind Map 期望的 MCP 配置遵循标准 JSON 形态，关键字段包括：

- `command`：Node.js 可执行文件绝对路径。
- `args`：数组，第一个元素是 `dist/index.js` 的绝对路径，后续参数可包含 `--project-root <path>`、`--log-level <info|debug>`。
- `env`：可选，用于覆盖默认行为（如自定义索引目录）。

[docs/AGENT_GUIDE.md](docs/AGENT_GUIDE.md) 中记录了 Claude Desktop、Cursor、Continue、Cline 等代理的具体配置片段，仓库还在 [templates/CLAUDE.md](templates/CLAUDE.md) 提供了一份 Claude 专属的 system prompt 模板，建议与 MCP 配置一并启用 [资料来源：[docs/AGENT_GUIDE.md:1-200]()][资料来源：[templates/CLAUDE.md:1-80]()]。

### 推荐的代理工作流

集成后，AI 代理可在一次会话内串联调用知识图谱、变更追踪与记忆工具：

```mermaid
flowchart LR
    A[AI 代理<br/>Claude/Cursor] -- stdio --> B[MCP 服务器<br/>dist/index.js]
    B --> C[知识图谱<br/>SQLite + Tree-sitter]
    B --> D[变更追踪<br/>simple-git + chokidar]
    B --> E[记忆系统<br/>Mem0 风格]
    B --> F[上下文引擎<br/>压缩 + 渐进披露]
    A -- 41 个工具调用 --> B
```

该工作流的核心收益来自 **三段式记忆**（工作记忆、情景记忆、语义记忆）与 **三档渐进披露**（Tier 1 ≤500 tokens、Tier 2 ≤2 000 tokens、Tier 3 按需）[资料来源：[README.md:1-120]()]。

## 常见失败模式与排错

集成过程中最常遇到的问题集中在依赖、路径与协议握手三方面。

1. **Node.js 版本过低**：若运行 `node -v` 输出低于 18.0.0，`better-sqlite3` 与 `tree-sitter` 的 native binding 可能加载失败。`engines` 字段已强制声明该下限 [资料来源：[package.json:1-80]()]。
2. **未执行 `npm run build`**：代理调用 `dist/index.js` 时报"模块未找到"，通常因为只跑了 `npm install`。`install.sh` / `install.ps1` 默认会执行构建，但手动开发流程可能遗漏。
3. **项目根目录错误**：服务器通过 `--project-root` 定位目标仓库，若代理配置里写错路径，Tree-sitter 索引与 Git diff 都会指向空目录。所有变更追踪工具（`mindmap_what_changed`、`mindmap_session_diff`）都会返回空结果。
4. **stdio 握手失败**：部分代理仅支持 HTTP/SSE 传输，而 AI Mind Map 当前仅暴露 stdio [资料来源：[README.md:1-80]()]。需要在代理侧选择"本地 stdio MCP 服务器"模式。
5. **可选语言解析器缺失**：`tree-sitter-bash`、`tree-sitter-c`、`tree-sitter-go` 等放在 `optionalDependencies` 中，安装失败不会阻断主流程，但对应语言的符号提取会降级为正则启发式 [资料来源：[package.json:1-80]()]。

## See Also

- 知识图谱与 PageRank 排序：[知识图谱与搜索](知识图谱与搜索.md)
- 上下文压缩与 Token 预算：[上下文引擎](上下文引擎.md)
- 变更追踪与 Git 集成：[变更追踪](变更追踪.md)
- 记忆系统与决策记录：[记忆与决策](记忆与决策.md)

---

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

## 系统架构

### 相关页面

相关主题：[知识图谱与变更跟踪](#page-knowledge-graph)

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

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

- [package.json](https://github.com/shdra06/ai-mind-map/blob/main/package.json)
- [README.md](https://github.com/shdra06/ai-mind-map/blob/main/README.md)
- [src/context/compressor.ts](https://github.com/shdra06/ai-mind-map/blob/main/src/context/compressor.ts)
- [src/context/token-budget.ts](https://github.com/shdra06/ai-mind-map/blob/main/src/context/token-budget.ts)
- [src/context/progressive-disclosure.ts](https://github.com/shdra06/ai-mind-map/blob/main/src/context/progressive-disclosure.ts)
- [src/change-tracker/diff-engine.ts](https://github.com/shdra06/ai-mind-map/blob/main/src/change-tracker/diff-engine.ts)
</details>

# 系统架构

## 概览

AI Mind Map 是一个基于 [Model Context Protocol (MCP)](https://github.com/shdra06/ai-mind-map/blob/main/package.json) 的服务端进程，目标是减少 AI 编码助手在阅读代码库时产生的 token 消耗。`package.json` 中将其定义为 "MCP server that reduces AI coding agent token usage by 80-99%"，并通过 `bin` 字段提供 `ai-mind-map` 与 `ai-mind-map-server` 两个可执行入口（[package.json:18-21]()）。

整体设计遵循分层原则：底层是多语言 AST 解析与 SQLite 知识图谱；中层是 git/文件系统感知的变更追踪与记忆系统；上层是面向 LLM 的上下文工程（压缩、预算管理、渐进披露）。三层共同对外暴露 41 个 MCP 工具，通过 stdio 与宿主 Agent（Claude、Cursor、Copilot 等）通信（[README.md:165-189]()）。

## 核心架构层次

下图描绘了运行时各模块的依赖关系与数据流向：

```mermaid
flowchart TB
    subgraph Host["AI Agent (Claude / Cursor / Copilot)"]
        UI[对话界面]
    end

    subgraph Core["AI Mind Map MCP Server"]
        KG[知识图谱<br/>Tree-sitter + SQLite FTS5 + PageRank]
        CT[变更追踪<br/>Chokidar + simple-git]
        MEM[记忆系统<br/>Mem0 风格 + 衰减]
        CE[上下文引擎]
        CE --> CMP[内容感知压缩]
        CE --> TBM[Token 预算管理]
        CE --> PD[渐进披露]
        KG --> CE
        CT --> CE
        MEM --> CE
    end

    UI <-->|stdio / MCP| Core
```

知识图谱、变更追踪、记忆系统三个子模块互相独立，但都将原始数据交给 **Context Engine** 做统一整形，再通过 MCP 协议输出。这种"中间层聚合"的设计避免了每个工具重复实现 token 控制逻辑（[README.md:165-189]()）。

## 上下文引擎（Context Engine）

上下文引擎是 AI Mind Map 区别于普通 codebase 索引器的关键，由三个相互协作的组件构成。

### 内容感知压缩

`src/context/compressor.ts` 实现了 `CompressionLevel`（`minimal` / `moderate` / `aggressive`）与 `ContentType`（`source_code`、`build_log`、`test_output`、`stack_trace`、`json_data`、`markdown`、`diff`、`config_file`、`plain_text`）二维分桶策略。`detectContentType` 通过对 diff 头、stack trace、测试输出等特征做正则匹配来决定走哪条压缩管线（[src/context/compressor.ts:73-101]()）。`compressSourceModerate` 保留签名、导入语句、文档注释，将函数体替换为 `{ ... }`，以中等代价换取高语义保留（[src/context/compressor.ts:148-186]()）。

### Token 预算管理

`src/context/token-budget.ts` 把响应按 `graphResults`、`changeSummary`、`memoryRetrieval`、`fileContent` 四个组件分别记账，通过 `BudgetReport` 给出剩余预算与相对原始全文的节省百分比（[src/context/token-budget.ts:27-49]()）。当组件超出预算时，会调用 `truncateToTokenBudget` 在逻辑边界（行/段落）处截断，避免切断符号名或括号。

### 渐进披露（Progressive Disclosure）

`src/context/progressive-disclosure.ts` 定义了三层上下文：

- **Tier 1（Always Loaded，≤ 500 tokens）**：项目身份、目录骨架、约定、当前任务。
- **Tier 2（Searchable，≤ 2000 tokens）**：图谱查询结果、最近变更、相关记忆、活跃决策。
- **Tier 3（On-Demand）**：完整文件内容、测试输出、历史 diff，按需取用（[src/context/progressive-disclosure.ts:48-58]()）。

`buildContextPackage` 在调用时按预算动态分配 Tier 3 容量，并通过 `breakdown` 数组返回每个组件的实际 token 占用与上限（[src/context/progressive-disclosure.ts:140-176]()）。这种"按需展开"的模式直接对应 README 中宣称的 80-99% token 节省（[README.md:191-205]()）。

## 变更追踪与工具暴露

`src/change-tracker/diff-engine.ts` 提供 git 感知的差异分析：优先通过 `simpleGit` 拉取 `DiffResultTextFile`，项目不在 git 控制下时回退到 `fs.stat` 的 mtime 比对。`DiffSummary` 同时返回人类可读文本和结构化的 `FileChange[]`，供上下文引擎在 Tier 2 注入（[src/change-tracker/diff-engine.ts:27-43]()）。

最终，41 个 MCP 工具（`mindmap_explain`、`mindmap_search`、`mindmap_recall` 等）通过 `src/index.ts` 注册到 `@modelcontextprotocol/sdk` 上，宿主 Agent 通过 stdio 调用。每个工具在内部都会调用上下文引擎的三个组件，从而保证响应始终受预算约束（[package.json:55-56]()）。

## 部署与生命周期

CLI 入口 `dist/cli.js` 暴露 `install`、`doctor`、`index`、`search`、`trace`、`recall`、`remember`、`status`、`changes` 等子命令；其中 `install` 会探测 7 种 AI Agent 并写入 MCP 配置，`doctor` 校验 Node 版本、SQLite、构建产物与 Agent 连接状态（[README.md:97-121]()）。生产构建依赖 `prepublishOnly` 脚本：先 `tsc` 编译再 `npm test`，确保发布前通过 `npx tsx --test` 单元测试（[package.json:23-34]()）。

## See Also

- [README.md](https://github.com/shdra06/ai-mind-map/blob/main/README.md)
- [package.json](https://github.com/shdra06/ai-mind-map/blob/main/package.json)
- [src/context/compressor.ts](https://github.com/shdra06/ai-mind-map/blob/main/src/context/compressor.ts)
- [src/context/token-budget.ts](https://github.com/shdra06/ai-mind-map/blob/main/src/context/token-budget.ts)
- [src/context/progressive-disclosure.ts](https://github.com/shdra06/ai-mind-map/blob/main/src/context/progressive-disclosure.ts)
- [src/change-tracker/diff-engine.ts](https://github.com/shdra06/ai-mind-map/blob/main/src/change-tracker/diff-engine.ts)

---

<a id='page-knowledge-graph'></a>

## 知识图谱与变更跟踪

### 相关页面

相关主题：[系统架构](#page-architecture)

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

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

- [package.json](https://github.com/shdra06/ai-mind-map/blob/main/package.json)
- [README.md](https://github.com/shdra06/ai-mind-map/blob/main/README.md)
- [src/change-tracker/diff-engine.ts](https://github.com/shdra06/ai-mind-map/blob/main/src/change-tracker/diff-engine.ts)
- [src/context/compressor.ts](https://github.com/shdra06/ai-mind-map/blob/main/src/context/compressor.ts)
- [src/context/token-budget.ts](https://github.com/shdra06/ai-mind-map/blob/main/src/context/token-budget.ts)
- [src/context/progressive-disclosure.ts](https://github.com/shdra06/ai-mind-map/blob/main/src/context/progressive-disclosure.ts)
</details>

# 知识图谱与变更跟踪

## 概述

AI Mind Map 是一个 MCP（Model Context Protocol）服务器，其核心目标是将 AI 编码代理的 token 消耗降低 80–99%。该系统由两大支柱构成：**知识图谱（Knowledge Graph）** 与 **变更跟踪（Change Tracker）**。知识图谱负责把代码库静态地建模为可查询的函数、类与调用关系图；变更跟踪则负责在会话之间捕捉"自上次以来发生了什么"。两者共同为上下文引擎（Context Engine）提供原材料，再经由内容感知压缩、分层加载与 token 预算管理，输出给 LLM 代理使用。资料来源：[README.md:18-32]()

在 v2.0.0 版本中，项目从单纯的代码库记忆工具升级为生产级系统，新增了 CLI、Cypher 查询、CI/CD 流程与安装脚本，同时修复了 `package-lock.json` 未包含在 CI 构建中的问题。资料来源：[package.json:34-58]()

## 知识图谱

### 架构组成

知识图谱子系统在 README 的架构图中占据左侧模块位置，由三类组件协作：

| 组件 | 职责 | 资料来源 |
|------|------|----------|
| Tree-sitter AST | 多语言抽象语法树解析 | [README.md:155-170]() |
| SQLite + FTS5 | 符号存储与全文检索 | [README.md:155-170]() |
| PageRank | 调用图重要性排序 | [README.md:155-170]() |

它把代码库解析为可查询的函数、类与调用关系节点，并对外暴露 6 个核心工具（`mindmap_search`、`mindmap_get_structure`、`mindmap_trace_dependencies`、`mindmap_get_signature`、`mindmap_find_references`、`mindmap_get_file_map`）。资料来源：[README.md:90-105]()

### 智能工具层

在基础图查询之上，AI Mind Map 提供了 3 个"智能工具"，号称可实现 99% 的 token 节省：

- `mindmap_explain`：单次调用返回一个符号的签名、调用者、被调用者、所在架构层、变更影响半径与 git 历史。
- `mindmap_git_changes`：基于 git 的符号级 diff，精确告知哪些函数被修改、哪些下游被影响。
- `mindmap_smart_search`：富上下文搜索，使 AI 不必再读取原始文件。

资料来源：[README.md:108-120]()

```mermaid
flowchart LR
    A[代码库源码] --> B[Tree-sitter AST 解析]
    B --> C[SQLite + FTS5 存储]
    C --> D[PageRank 排序]
    D --> E[知识图谱查询]
    E --> F[41 个 MCP 工具]
    E --> G[上下文引擎]
    H[Chokidar 文件监听] --> B
    I[Git Diff] --> G
```

## 变更跟踪

### Diff 引擎

变更跟踪的核心实现在 `src/change-tracker/diff-engine.ts` 中。该模块是无状态的（stateless）——所有公共方法都接收必要参数并返回结构化结果，类实例仅用于保存项目根路径与懒加载的 `simpleGit` 句柄。资料来源：[src/change-tracker/diff-engine.ts:38-52]()

引擎通过 `simpleGit` 库进行 git 感知分析，生成富有人类可读性的变更摘要，适合作为 LLM 会话的前导上下文，让代理在动手前就知道自上次访问后项目发生了什么。资料来源：[src/change-tracker/diff-engine.ts:3-12]()

### 核心数据模型

`DiffSummary` 是变更跟踪的聚合产物，其字段包括：

- `text`：多行人类可读摘要，可直接注入上下文。
- `changes`：逐文件变更记录数组（`FileChange[]`）。
- `totalLinesAdded` / `totalLinesRemoved`：新增与删除行数总计。
- `filesAffected`：受影响文件数。
- `usedGit`：是否真正使用了 git（否则回退到文件系统时间戳）。

`DiffQueryOptions` 则支持通过 `includePatterns` 与 `excludePatterns` 进行 glob 过滤，让用户能精确控制变更摘要的范围。资料来源：[src/change-tracker/diff-engine.ts:21-36]()

### Git 不可用时的回退

如果项目未处于 git 控制下，引擎会回退到文件系统时间戳分析，通过 `node:fs/promises` 的 `stat` 与 `readdir` 列举文件元信息。资料来源：[src/change-tracker/diff-engine.ts:3-12]()

## 与上下文引擎的协作

变更跟踪与知识图谱的输出并不是直接喂给 LLM 的，而是先经过上下文引擎的三道处理：

1. **内容感知压缩**（`src/context/compressor.ts`）：自动检测 9 种内容类型（`source_code`、`build_log`、`test_output`、`stack_trace`、`json_data`、`markdown`、`diff`、`config_file`、`plain_text`），并按 `minimal` / `moderate` / `aggressive` 三级强度施加不同的压缩策略。例如源码中度压缩会保留签名与文档注释、替换函数体为 `{ ... }`。资料来源：[src/context/compressor.ts:7-26](), [src/context/compressor.ts:121-160]()
2. **Token 预算管理**（`src/context/token-budget.ts`）：为 `graphResults`、`changeSummary`、`memoryRetrieval`、`fileContent` 四个组件分别分配预算，并在超限时进行智能截断。资料来源：[src/context/token-budget.ts:25-44]()
3. **渐进式披露**（`src/context/progressive-disclosure.ts`）：把上下文分为三层——Tier 1（始终加载，≤ 500 token）、Tier 2（可搜索，≤ 2000 token）、Tier 3（按需加载），确保代理先看到项目骨架与近期变更，细节仅在需要时调入。资料来源：[src/context/progressive-disclosure.ts:7-30]()

通过这种"图谱 + 变更 → 压缩 → 预算 → 分层"的流水线，AI Mind Map 实现了在保持代码理解深度的同时大幅压低 token 消耗。

## 常见使用模式

README 推荐的三种典型场景如下：

- **理解一个符号**：调用 `mindmap_explain` 即可获得签名、调用链、变更影响与历史。
- **查看自上次会话以来的变更**：调用 `mindmap_session_diff` 或 `mindmap_what_changed`，由 diff 引擎生成摘要。
- **实时同步**：通过 Chokidar 文件监听器在编码时持续更新图谱，使知识库始终保持新鲜。

资料来源：[README.md:108-140](), [README.md:155-170]()

## 故障排查

| 现象 | 可能原因 | 建议 |
|------|---------|------|
| `mindmap_session_diff` 返回空 | 项目未初始化 git | 初始化 git 仓库或依赖文件系统时间戳回退 |
| 图谱查询结果陈旧 | 文件监听器未启动 | 重启 `ai-mind-map-server` 进程 |
| 变更摘要过长触发截断 | 大量文件变更 | 配合 `includePatterns` / `excludePatterns` 缩小范围 |

## 参见

- 上下文压缩引擎：[src/context/compressor.ts](https://github.com/shdra06/ai-mind-map/blob/main/src/context/compressor.ts)
- Token 预算管理器：[src/context/token-budget.ts](https://github.com/shdra06/ai-mind-map/blob/main/src/context/token-budget.ts)
- 渐进式披露：[src/context/progressive-disclosure.ts](https://github.com/shdra06/ai-mind-map/blob/main/src/context/progressive-disclosure.ts)
- 变更跟踪 Diff 引擎：[src/change-tracker/diff-engine.ts](https://github.com/shdra06/ai-mind-map/blob/main/src/change-tracker/diff-engine.ts)
- 项目主页：[README.md](https://github.com/shdra06/ai-mind-map/blob/main/README.md)

---

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

---

## Doramagic 踩坑日志

项目：shdra06/ai-mind-map

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

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

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

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

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

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

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

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

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

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

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

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

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

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

<!-- canonical_name: shdra06/ai-mind-map; human_manual_source: deepwiki_human_wiki -->