lopax76/second-brain

# Second Brain (SB) [](https://github.com/lopax76/second-brain/actions/workflows/ci.yml) [](https://pypi.org/project/second-brain-graph/) [](LICENSE) [](pyproject.toml) [](pyproject.toml) **一个动态的、始终保持最新、低 token 的全项目映射** —— 包括文件、链接、领域和 机制 —— AI 助手可以**查询**它，而无需重新阅读所有内容；人类则可以将其作为 可导航的 **2D 社区地图**进行探索。 🇮🇹 [Leggi in italiano →](README.it.md)  _{真实多项目工作区（名称已匿名化）上的离线查看器：一张扁平的 2D 地图， 文件被着色并聚集为自动检测到的社区，并带有点击查看的详情面板。} ## 为什么需要它 随着时间的推移，项目会变得越来越复杂。文件发生偏移，有些成为孤立文件或悄然损坏， “什么在哪里以及它们如何连接”的心智模型变得越来越模糊，而 AI 助手**在一次又一次的 聊天中迷失了线索** —— 因此每次会话都从重新阅读和重新搜索文件开始。这既缓慢、不完备， 而且会**反复消耗 token** —— 并且随着项目的增长，情况只会变得更糟。 Second Brain 构建了项目的图结构，并在项目发生变化时保持其真实性 —— 内容哈希**门控** 精确标记出发生偏移的内容，而重建是一次快速的完整遍历（在模型之外，以近乎零 token 成本进行）。 助手**查询**它并获得紧凑的答案；人类打开 **2D 社区地图**即可一目了然地查看整个项目。 它**不是 RAG 系统**：没有 embeddings，没有向量存储，构建图也不需要 LLM。 它映射了文件之间的*结构*关系，这使其成为 RAG 的补充，并为了一件事而生：**以极低的 token 成本提供态势感知。** ## 有何不同之处 - **对您的源文件只读** — 它只进行索引，从不修改您的文件。可以在任何项目上运行而无需 承担风险。 - **文件即真理** — 图是派生的（位于 `.secondbrain/` 目录）且始终可重新生成； 内容永远不会被复制到其中。 - **零运行时依赖** — 核心完全基于 Python 标准库运行。没有 冲突，即时安装，适用于 CI / 容器 / 物理隔离环境。 - **设计上的低 token 成本** — 查询返回 id、类型、大小和连接，绝不返回文件 内容，因此为助手提供导向只需几百个 token，而不是数万个。 - **防偏移门控** — 当存在过期、孤立或损坏的内容时，拒绝认为图是“正常”的。 - **社区与影响范围** — 根据文件的链接方式（而非文件夹）自动检测项目的真实模块， 并仅需一次调用即可回答“如果我更改这个，什么会受到影响？”（上游/下游影响范围）。 - **`GRAPH_REPORT.md` 单页报告** — agent 优先读取的工件，而不是去 grep：god 节点、 社区、意外链接、决策和问题，每次构建都会重新生成。 - **离线图查看器** — 交互式力导向地图 (vis-network)，按 社区着色，支持搜索、带有相邻节点导航的点击检查面板，以及 每个社区的显示/隐藏图例。数据和库均内联在一个 HTML 文件中，因此完全可以 离线工作。该查看器**改编自 [Graphify](https://github.com/safishamsi/graphify)** (MIT) — 详见 [参考资料与来源](#references--sources)。 - **重要性排名 (PageRank)** — “god 节点”按*结构重要性*（重要文件所 依赖的文件）排名，而不是单纯计算链接数 — 纯 Python、确定性的实现。 - **任务感知检索 (`focus`)** — 给定一个任务，它在 token 预算内返回该任务的 *最小高价值子图*（基于匹配文件的个性化 PageRank）， 而不是整个摘要。 - **自刷新读取** — 每次查询都会检查低成本的 size+mtime 签名，仅在 项目实际发生变化时（包括未提交的编辑）进行重建，因此助手永远不会获取到 过期的地图 — 无需调度程序，也没有依赖。 - **可选的符号调用图** — `build --symbols` 会为 Python 添加函数/类节点和文件内的 `calls` 边（保守解析，不猜测边）；默认关闭以保持地图轻量。 - **GraphML 导出** — `export --format graphml` 可在 Gephi / yEd / Cytoscape / networkx 中打开图。 - **可选的 MCP server** — 将相同的低 token 查询暴露给支持 MCP 的助手，通过 可选的附加组件提供，因此核心保持零依赖。 ## 在真实项目上的效果（已匿名化） 在一个成熟的多仓库项目（隐去身份）上进行**只读**测量：跨 17 个顶层区域约有 1,684 个 知识文件，在 **~1.3 秒**内完成索引（生成的 `graph.json` 索引 = 0.91 MB）。 有三种方式可以在三个独立且干净的聊天中，回答关于该项目的相同四个问题 — *这里有什么、 列出所有记录的决策、哪些文件被截断/为空、连接最多的文件*： | 指标 | 无 (手动) | 如今 (手动) | 使用 Second Brain | |---|---|---|---| | 时间 | ~8.5 分钟 | ~9 分钟 | **~3–4 分钟** | | 工作 token | 不透明 | 不透明 | **~3–4k, 自动测量** | | **找到的决策** | 112 | 131 | **112 (精确，每次运行)** | | **截断的文件** | 3 | 0 (漏掉) | **2 (精确)** | | 统计的文件 | 2,174 | 2,174 | **1,684 (精确)** | | 可复现 / 可验证 | 否 | 否 | **是** | 有两点值得注意。(1) 两次手动运行**彼此不一致** — 112 对 131 个 决策，3 对 0 个截断文件（第二次完全错过了它们）— 因此手工方法是 非确定性且不可验证的：您无法区分正确答案 (112) 和 错误答案 (131)。(2) Second Brain 在每次运行中都返回**相同的答案** — 112，正确的计数 — 消耗的 token 少得多，且时间不到一半。其优势不在于一个别人无法达到的数字； 而是一个精确、可复现、可查询的答案，而不是碰运气。 仅仅是为了在整个项目中为助手*提供导向* — 这是您在**每次会话**中都要付费的 — 阅读精选的真理源文档需要约 **229,000 个 token**；而 `second-brain map` 摘要只需约 **270 个 token**：**少了约 800 倍**，并且随着项目的增长大致保持恒定（查询的是 完整索引，绝不加载到上下文中）。

它还发现了连精选文档也会遗漏的内容：真正**被截断/损坏的文件**（排除 UTF-16/编码误报）、**约 45 个空文件**、**约 1,390 个孤立文件 (~80%)**、 **112 个决策**以及现在变得明确且可查询的 **约 626 个交叉引用**，外加在索引后几秒钟内 **已经有 13 个文件过期**（这是一个不断写入的实时系统）— 这正是 为什么地图必须自我更新的原因。

_{图示 — SB 消除的连续性问题：在多次会话中，手工维护的地图 会随着孤立和过期文件的堆积而发生偏移，而可查询的图则保持最新。} ### 相同的结构，代码层 Second Brain 的代码导入层将整个工作区渲染为您可以真正阅读的图：  ## 安装 ``` pip install second-brain-graph # from PyPI pip install "second-brain-graph[mcp]" # + optional MCP server pip install -e . # or from a clone ``` [在 PyPI 上](https://pypi.org/project/second-brain-graph/)。需要 Python 3.10+。运行时 依赖：**无**（仅限标准库）。该软件包安装了 `second-brain` 命令 和 `second_brain` 导入模块。 ## 命令 每个命令都接受一个可选的项目路径（默认为 `.`）。**查询是自刷新的** — 它们 在首次使用时自动构建，并仅在项目实际发生更改时重建 — 因此助手永远不会 基于过期的地图进行回答（参见下文的*始终保持最新*）。 **构建与新鲜度** ``` second-brain build . # index the project -> .secondbrain/ (graph + GRAPH_REPORT.md) second-brain build . --symbols # also index the Python symbol layer (functions/classes + calls) second-brain gate . # anti-drift check: broken refs, stale files, orphans (exit≠0 if drifted) ``` **导向 — 优先阅读这些** ``` second-brain report . # GRAPH_REPORT.md: god nodes (PageRank), communities, churn, decisions, problems second-brain map . # compact digest: areas, sizes, most-connected files second-brain assess . # before/after: problems + token savings second-brain stats . # quick counts by node/edge type ``` **查询** ``` second-brain find util . # nodes whose name/path matches "util" second-brain neighbors second_brain/model.py . # a node and its connections second-brain impact second_brain/model.py . # blast radius: what breaks / what it depends on second-brain impact second_brain/model.py . --up # only what depends on it (run before editing!) second-brain impact --diff . --up # blast radius of your UNCOMMITTED changes (git diff) second-brain why second_brain/cli.py second_brain/model.py . # shortest path: how are two nodes linked? second-brain focus "token budget in the report" . # task-aware: the minimal high-value subgraph second-brain focus "auth flow" . --budget 4000 # ...within ~4000 tokens (default 2000) second-brain symbols second_brain/model.py . # function/class signatures of one Python file ``` **查看与导出** ``` second-brain view . # offline 2D community-map viewer -> .secondbrain/view.html second-brain view ./src/api # drill into one area in full detail (top-level view stays light) second-brain export . --format graphml --out graph.graphml # GraphML for Gephi/yEd/Cytoscape/networkx ``` **Agent 集成与自动保鲜** ``` second-brain agent install . # add the SB directive to CLAUDE.md/AGENTS.md + a Claude Code hook second-brain hook install . # git post-commit/post-checkout: rebuild the graph on every commit ``` **深入分析**只需将任何命令指向一个子文件夹 — `second-brain map ./src/api` 仅处理 该区域；通过 *backbone* 模式保持顶层视图轻量（领域 + 与知识连接的核心； 隔离的数据文件会被汇总到其所属区域节点上）。 ### 始终保持最新（自动刷新） 查询（`map` / `find` / `neighbors` / `impact` / `focus` / `report` 以及 MCP 工具）在回答之前会 检查低成本的 size+mtime 签名，并且**仅在项目发生更改时重建** — 包括 *未提交的*编辑。因此，无论助手何时使用，地图都是最新的，**无需调度程序且没有 依赖**。首次使用项目时会自动构建。要按原样提供已存储的图（跳过 检查），请设置 `SECOND_BRAIN_AUTO_REFRESH=0`。在极其庞大的单图项目中，您可以通过 `SECOND_BRAIN_REFRESH_TTL=` 来限制检查频率。仅基于文件属性的检查存在一个 很小的盲区 — 在与上次构建相同的文件系统时钟周期内进行的同等大小的编辑 — 而 `second-brain gate` （内容哈希）可以精确捕捉到这一点。 | 开关 | 效果 | |--------|--------| | `SECOND_BRAIN_AUTO_REFRESH=0` | 关闭自动刷新（提供已存储的图，速度更快，但可能过期） | | `SECOND_BRAIN_REFRESH_TTL=` | 将新鲜度检查限制为每个时间窗口一次（适用于庞大的 monorepo 图） | | `build --symbols` | 包含函数/类 + 调用层（默认关闭以保持地图轻量） | | `focus … --budget N` | 设定 `focus` 返回的任务上下文大小（默认 2000 tokens） | | `impact … --up` / `--down` / `--depth N` | 限制/限定影响范围的遍历深度 | | `view --backbone` | 强制在任何大小下进行骨干渲染（在约 8000 个节点以上时自动触发） | ### 查看图 1. **生成查看器：** `second-brain view .` 2. **打开它：** 双击它生成的文件 — `.secondbrain/view.html` — 在任何浏览器中。无需 服务器，也无需安装：数据和渲染库均内联在单个页面中，因此它可以完全离线工作。 3. **探索：** 图以扁平的 **2D 地图**形式布局，文件被着色并聚集到 **社区**中（根据它们的链接方式自动检测）。滚动缩放，右键拖动平移， 双击节点查看其详细信息（包括其影响半径）。使用左侧面板进行搜索、 切换分组（社区 / 区域 / 文件夹 / 类型）、聚焦单个社区，或仅显示 孤立节点。 ## 查询层（面向 AI 助手） `second-brain map`、`find`、`neighbors`、`impact`、`why`、`focus` 和 `report` 返回紧凑的、 预算控制的答案（id、类型、大小、连接 — 绝不包含文件内容）。可选的 **MCP server** 将这些查询暴露给支持 MCP 的助手： ``` pip install "second-brain-graph[mcp]" second-brain-mcp . # project_map / find / neighbors / subgraph / impact / impact_diff / why / focus / report / health ``` 请参阅 [`docs/mcp.md`](docs/mcp.md) 了解相关工具及其结构。 ## 工作原理 1. **索引** — 遍历项目，将每个文件分类为特定类型的节点，并提取边： Python 导入（通过 `ast`）、JS/TS 导入、文档引用（markdown 链接、 `[[wikilinks]]` 以及**正文中的纯路径提及** — 这是标准工具容易遗漏的部分），以及 区域归属。操作节点（在文档中找到的决策、来自 git 提交的会话） 也会被添加进来。 2. **保持最新** — 内容哈希差异精确告知**门控**自上次构建以来发生了什么变化； 重建是一次快速的完整遍历（在模型之外进行）。查询也会**自刷新**： 当项目发生更改时（包括未提交的编辑），它们会自动重建，因此 助手永远不会基于过期的地图工作。 3. **查询 / 查看** — 人类可以查看 2D 社区地图；助手查询低 token 层， 并针对手头的工作询问 `focus ""`，仅获取重要的切片。 **关于误报：** 正文中的纯路径提及本质上是带有噪声的。Second Brain 对此进行非对称处理 — markdown 链接和 wikilinks 是有意为之的（未解析的 链接会被报告为*损坏*），但纯正文提及**仅在解析为**真实文件时才被使用； 否则，它将被视为噪声丢弃，绝不会产生损坏的引用。深度的导入解析目前支持 Python 和 JS/TS；其他语言通过文档链接来丰富图。 完整的节点/边分类法、`graph.json` schema 以及分类规则记录在 [`docs/graph-format.md`](docs/graph-format.md) 中。 ## 自行尝试前后对比 在**独立且干净的聊天**中运行这些命令（只读），然后比较答案和 token/时间 成本。将 `/path/to/project` 替换为真实的项目。 **如今（您当前的方法）：** ``` READ-ONLY: do not modify, create, delete or move any file. On the project at /path/to/project, work with your NORMAL method (reference docs, memory, the tools you usually use). Give me a COMPLETE, ACCURATE picture answering these 4 questions: 1) how many files (excluding images, venvs, caches, .git) and the breakdown by type; 2) list ALL decisions recorded in the docs (D-XXX, ADR-N, RFC-N); 3) which files are truncated/corrupted (null-byte) or empty (zero-byte); 4) the 10 most-connected files. When done, tell me the time and tokens you used. ``` **使用 Second Brain**（索引已构建 — 查询它，而不是重新读取文件）： ``` READ-ONLY. Second Brain's index is already built — only query it. Use ONLY: python -m second_brain map "/path/to/project" python -m second_brain stats "/path/to/project" python -m second_brain find "/path/to/project" and read /path/to/project/.secondbrain/assessment.md. Answer the same 4 questions, then tell me the time and tokens you used. ``` ## 架构与模块 对您的源文件只读，零运行时依赖，确定性的。一切都位于 `second_brain/` 包中 — 每个公共模块及其功能如下： | 模块 | 职责 | |--------|----------------| | [`cli.py`](second_brain/cli.py) | 命令行接口 — 每一个 `second-brain` 命令。 | | [`mcp_server.py`](second_brain/mcp_server.py) | 可选的 MCP 服务器：通过 stdio 提供低 token 查询工具（附加组件 `[mcp]`）。 | | [`model.py`](second_brain/model.py) | 图数据模型：类型化节点/边、颜色、可 JSON 序列化的容器 + 邻接索引。 | | [`indexer.py`](second_brain/indexer.py) | 构建图：文件节点、区域、导入/引用边、可选的符号层。 | | [`classify.py`](second_brain/classify.py) | 将每个文件分类为类型化节点（基于启发式，可按项目配置）。 | | [`config.py`](second_brain/config.py) | 项目特定的 `.secondbrain.json` 配置（扩展/替换分类法）。 | | [`ignore.py`](second_brain/ignore.py) | `.secondbrainignore` 模式 + 合理的默认忽略项。 | | [`references.py`](second_brain/references.py) | 提取文档引用：markdown 链接、`[[wikilinks]]` 以及正文中的纯路径提及。 | | [`pycode.py`](second_brain/pycode.py) | 导入边：通过 `ast` 解析 Python，尽力解析 JS/TS（剥离注释）。 | | [`pysymbols.py`](second_brain/pysymbols.py) | 同一文件内的 Python 调用图（函数/类 + 保守的 `calls`）。 | | [`symbols.py`](second_brain/symbols.py) | 单个 Python 文件的函数/类签名（`symbols` 命令）。 | | [`freshness.py`](second_brain/freshness.py) | 内容哈希清单、低成本签名以及自刷新读取。 | | [`gate.py`](second_brain/gate.py) | 防偏移门控：损坏的引用 / 过期文件 / 孤立节点。 | | [`store.py`](second_brain/store.py) | 将派生存储持久化到 `.secondbrain/` 目录下（图、清单、签名、模式）。 | | [`query.py`](second_brain/query.py) | 低 token 查询层：`map` / `find` / `neighbors` / `subgraph` / `impact` / `focus`。 | | [`rank.py`](second_brain/rank.py) | PageRank 重要性（全局 + 个性化）— god 节点和 `focus` 背后的引擎。 | | [`communities.py`](second_brain/communities.py) | 社区检测（确定性标签传播）+ 意外的跨社区边。 | | [`operational.py`](second_brain/operational.py) | 操作节点：在文档中发现的决策、来自 git 提交的会话。 | | [`report.py`](second_brain/report.py) | 生成 `GRAPH_REPORT.md`（god 节点、社区、变动、决策、问题）。 | | [`assess.py`](second_brain/assess.py) | 一次性前后评估：隐藏的问题 + 节省的 token。 | | [`viewer.py`](second_brain/viewer.py) | 离线 2D 社区地图查看器（vis-network，改编自 Graphify）。 | | [`export.py`](second_brain/export.py) | 将图导出为 GraphML。 | | [`agent_integration.py`](second_brain/agent_integration.py) | 将 SB 接入 AI agent：CLAUDE.md/AGENTS.md 指令、Claude Code 钩子、git 钩子。 | 参考文档：[`graph.json` schema 与分类法](docs/graph-format.md) 和 [MCP 工具](docs/mcp.md)。 ## 状态与路线图 Beta 阶段 — **v0.5.0**。目前已支持：类型化图；防偏移**门控**；**自刷新 读取**（查询仅在项目更改时重建，无需调度程序）；离线 **2D 社区地图**查看器；低 token 查询层（`map` / `find` / `neighbors` / `subgraph` / `impact` — **外加用于您未提交更改影响范围的 `--diff`** — / **`why`** （两节点间的最短路径） / **`focus`**）；**PageRank** 重要性排名；**社区 检测**；**`GRAPH_REPORT.md`** 单页报告；操作节点（决策/会话）；可选的 **Python 符号调用图**（`build --symbols`）；**GraphML 导出**；可配置的 `.secondbrain.json` 分类法；**agent 集成**（`agent install` + git `hook install`）；以及 可选的 **MCP 服务器**。下一步：针对超大图的真正增量构建、更丰富的 引用解析、更多语言的符号层，以及可选的本地语义层。 ## 开发 ``` pip install -e ".[dev,mcp]" ruff check second_brain tests pytest -q ``` ## 参考资料与来源 **基于 / 改编自** - **[Graphify](https://github.com/safishamsi/graphify)** 作者 Safi Shamsi (MIT) — 交互式 图查看器以 Graphify 的查看器为模型；在此致谢。 - **[vis-network](https://github.com/visjs/vis-network)** (Apache-2.0 OR MIT) — 渲染 库，已离线打包。完整许可文本见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。 **概念与规范** - **PageRank** — S. Brin & L. Page, *The Anatomy of a Large-Scale Hypertextual Web Search Engine* (1998)；参见 [PageRank](https://en.wikipedia.org/wiki/PageRank)。用于重要性排名和 任务感知的 `focus`（个性化 PageRank）。 - **标签传播** — Raghavan, Albert & Kumara, *Near linear time algorithm to detect community structures* (2007)；参见 [Label propagation](https://en.wikipedia.org/wiki/Label_propagation_algorithm)。 用于确定性的社区检测。 - **Model Context Protocol** — [modelcontextprotocol.io](https://modelcontextprotocol.io)；MCP 服务器遵循此协议。 - **GraphML** — [graphml.graphdrawing.org](http://graphml.graphdrawing.org)；`export` 格式。 - **Python `ast`** — [docs.python.org/3/library/ast](https://docs.python.org/3/library/ast.html)； 用于精确的 Python 导入 + 符号解析。 - **BLAKE2** — [blake2.net](https://www.blake2.net)；用于保鲜的标准库内容哈希。 - **Keep a Changelog** — [keepachangelog.com](https://keepachangelog.com) · **Semantic Versioning** — [semver.org](https://semver.org)。 **项目文档** - [`docs/graph-format.md`](docs/graph-format.md) — 磁盘存储、节点/边分类法、`graph.json` schema、分类规则。 - [`docs/mcp.md`](docs/mcp.md) — MCP 工具及其结构。 - [CHANGELOG.md](CHANGELOG.md) · [CONTRIBUTING.md](CONTRIBUTING.md) · [SECURITY.md](SECURITY.md) · [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) · [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) ## 许可证 [MIT](LICENSE)。

标签：AI上下文管理, MCP, Python, SOC Prime, 代码图谱, 开发工具, 无后门, 逆向工具