# https://github.com/nano-step/nano-brain 项目说明书

生成时间：2026-07-06 08:24:26 UTC

## 目录

- [项目概览与系统架构](#page-1)
- [混合检索与代码智能（MCP 工具集）](#page-2)
- [数据管理：会话采集、索引与存储流水线](#page-3)
- [部署、配置、CLI 与 REST API](#page-4)

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

## 项目概览与系统架构

### 相关页面

相关主题：[混合检索与代码智能（MCP 工具集）](#page-2), [数据管理：会话采集、索引与存储流水线](#page-3), [部署、配置、CLI 与 REST API](#page-4)

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

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

- [README.md](https://github.com/nano-step/nano-brain/blob/main/README.md)
- [cmd/nano-brain/main.go](https://github.com/nano-step/nano-brain/blob/main/cmd/nano-brain/main.go)
- [internal/server/routes.go](https://github.com/nano-step/nano-brain/blob/main/internal/server/routes.go)
- [internal/server/server.go](https://github.com/nano-step/nano-brain/blob/main/internal/server/server.go)
- [internal/mcp/server.go](https://github.com/nano-step/nano-brain/blob/main/internal/mcp/server.go)
- [internal/mcp/tools.go](https://github.com/nano-step/nano-brain/blob/main/internal/mcp/tools.go)
- [internal/config/config.go](https://github.com/nano-step/nano-brain/blob/main/internal/config/config.go)
- [docs/SETUP_AGENT.md](https://github.com/nano-step/nano-brain/blob/main/docs/SETUP_AGENT.md)
</details>

# 项目概览与系统架构

## 1. 项目定位与核心目标

nano-brain 是一个面向 AI 编码代理（coding agent）的本地化上下文服务守护进程（daemon），目标是为 Claude Code、OpenCode 等代理提供高信噪比、结构化的代码库上下文，从而减少代理在 `grep` / `read` / `glob` 上浪费的 token 成本。资料来源：[README.md:1-40]()

守护进程对外暴露两种接口，二者共享同一进程：

- **REST API**：约 60 个端点集中在 `/api/v1/*` 之下，附带若干顶层路由，供任何 HTTP 客户端直接调用。资料来源：[internal/server/routes.go:1-30]()
- **MCP（Model Context Protocol）服务器**：使用 Streamable HTTP 传输，统一监听 `http://localhost:3100/mcp`，为 AI 代理提供 `search` / `symbols` / `flow` / `impact` / `trace` 等工具方法。资料来源：[internal/mcp/server.go:1-60]()、[docs/SETUP_AGENT.md:172-181]()

由于 MCP 传输被刻意设计为无状态（stateless），每次工具调用都必须在请求参数中显式携带 `workspace` 字段，`requireWorkspace` 守卫位于 `internal/mcp/tools.go:149`。这是当前架构的一个已知约束，社区正在讨论通过 URL query param 绑定默认 workspace 以减少每次调用开销（issues #522、#523）。

## 2. 进程拓扑与模块划分

CLI 入口位于 `cmd/nano-brain/main.go`，通过 `flag` 包解析全局参数后路由到不同子命令（`init`、`serve`、`scan` 等）。无参运行时默认启动完整服务器；这一点在社区被指出为 CLI UX 问题，因为用户预期 `--help` 能看到有用的命令清单，但 stdlib `flag` 会先于 `main()` 的 dispatch switch 拦截 `-h`/`--help`（issue #527）。

```mermaid
flowchart LR
  A[AI 编码代理] -->|MCP/Streamable HTTP| B(nano-brain daemon :3100)
  C[任意 HTTP 客户端] -->|REST /api/v1/*| B
  B --> D[config 加载]
  B --> E[collection 注册表]
  B --> F[document indexer]
  B --> G[code-graph extractor]
  B --> H[watcher]
  F --> I[(本地持久化)]
  G --> I
  H --> F
  H --> G
```

模块边界：

- **`internal/config`**：负责读取 `.nano-brain.yaml`、合并环境变量与命令行覆盖，提供零配置启动能力（v2026.7.0302 引入 0–3 次探测 + 自文档化配置 + env-var secrets）。
- **`internal/server`**：HTTP 路由注册与中间件；所有 REST 端点的注册中心位于 `routes.go`。资料来源：[internal/server/routes.go:1-30]()
- **`internal/mcp`**：MCP 协议适配层，把工具调用桥接到下层的 `search` / `symbols` / `flow` / `impact` / `trace`。
- **collection 注册表**：以"集合"为单位管理索引范围，支持 symbol-registry（代码集合）与纯文档集合两种模式。集合的扫描策略包括启动/重扫路径 `scanCollection` 与文件监听路径 `summarizeNotify`。

## 3. 数据流：索引、监听与图构建

完整的数据生命周期分为三条路径：

1. **启动 / 全量重扫**：调用 `scanCollection`，正确遵守嵌套的 `.gitignore` / `.nano-brainignore`、`max_file_size` 与 minified 文件过滤。资料来源：[internal/server/server.go:1-80]()
2. **运行时监听（watcher）**：`summarizeNotify()` 回调对所有进入 symbol-registry 集合的文件触发索引与摘要；社区 issue #520 指出该回调对不含可解析符号的非代码文件（如 JSON / 文本状态缓存）仍会触发，导致噪音。
3. **增量图构建**：code-graph extractor 早期实现绕过了 document-indexer 的文件准入过滤器，造成 `memory_trace/graph/symbols` 中出现孤立边（orphan edges），污染下游代理输出。该问题已在 v2026.7.0602 的 PR #538 中通过统一两条图构建路径的文件准入策略修复。资料来源：[issue #535]()

每条路径的最终产物都写入本地持久化层，由 `internal/server/server.go` 在启动时载入并对外提供查询。

## 4. 部署形态与已知约束

- **安装方式**：v2026.7.0303 起支持 `curl | bash` 一键安装（带 SHA256 校验），同时保留 npm 作为备选入口。
- **多 workspace 模型**：单 daemon 多 workspace；每个工具调用必须显式指定 `workspace`，否则 `requireWorkspace` 会拒绝请求。社区正在评估通过 URL query param 注入默认 workspace 的方案，以避免代理侧每次重新发现（issues #522、#523）。
- **MCP 客户端接入**：当前为手动复制 JSON 片段到 Claude Code / OpenCode 配置，Step 9 的 `AgentsSnippet` 在 `nano-brain init --root=<path>` 后打印。issue #525 提议把这一步自动化为注册后的交互式引导。
- **API 发现**：REST 端点已稳定但缺乏 OpenAPI 3.0 规范（issue #530），非 MCP 客户端目前只能通过源码枚举。
- **CLI 体验**：`--help` 输出与实际命令不同步，无参默认行为也容易让用户误启动服务器（issue #527）。

## 5. 相关社区资源

- 图构建文件准入一致性修复：PR #538 / issue #535（v2026.7.0602）
- 默认 workspace 绑定讨论：issues #522、#523
- CLI 体验整改：issue #527
- 零配置启动：v2026.7.0302 / PR #534
- 一键安装器：v2026.7.0303 / PR #533
- MCP 客户端自动配置：issue #525
- token 成本基准测试规划：issue #529

---

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

## 混合检索与代码智能（MCP 工具集）

### 相关页面

相关主题：[项目概览与系统架构](#page-1), [数据管理：会话采集、索引与存储流水线](#page-3)

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

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

- [internal/mcp/tools.go](https://github.com/nano-step/nano-brain/blob/main/internal/mcp/tools.go)
- [internal/mcp/streamable.go](https://github.com/nano-step/nano-brain/blob/main/internal/mcp/streamable.go)
- [internal/mcp/graph_paths.go](https://github.com/nano-step/nano-brain/blob/main/internal/mcp/graph_paths.go)
- [internal/search/search.go](https://github.com/nano-step/nano-brain/blob/main/internal/search/search.go)
- [internal/search/rrf.go](https://github.com/nano-step/nano-brain/blob/main/internal/search/rrf.go)
- [internal/graph/registry.go](https://github.com/nano-step/nano-brain/blob/main/internal/graph/registry.go)
</details>

# 混合检索与代码智能（MCP 工具集）

## 概述

nano-brain 通过 MCP（Model Context Protocol）协议向 AI 编码代理（Claude Code、OpenCode 等）暴露一组检索与代码智能工具，目的是让代理在大型代码仓库中**以远低于手动 grep/read 的 token 成本**完成上下文采集。工具集的核心能力可分为两条线：

- **混合检索线**：基于 `internal/search` 中的 RRF（Reciprocal Rank Fusion）融合多种排序信号，输出文档级命中片段。
- **代码智能线**：基于 `internal/graph/registry.go` 中的符号注册表与 `internal/mcp/graph_paths.go` 的图路径操作，输出符号、调用流、影响面与执行轨迹。

每次 MCP 调用必须显式传入 `workspace` 参数，由 `requireWorkspace` 在 `internal/mcp/tools.go:149` 强制校验；服务端通过 `internal/mcp/streamable.go` 实现的 Streamable HTTP 传输保持无状态，因此同一 URL `http://localhost:3100/mcp` 可被多项目共享（社区讨论见 issues #522、#523，目前提议通过 URL query param 绑定默认 workspace）。资料来源：[internal/mcp/tools.go:149-]()

## 混合检索引擎（RRF 融合）

`internal/search/search.go` 负责对文档索引执行查询，`internal/search/rrf.go` 实现 RRF 算法，将来自 BM25、向量相似度、以及结构化字段（如路径、符号名）的多路排序结果按 `1 / (k + rank)` 公式融合，单一查询最终返回按融合分排序的统一列表。资料来源：[internal/search/rrf.go:1-]()

RRF 的关键设计点：

- **无需归一化**：各路排序分数不需要在同一量纲，融合仅依赖秩位，对异构评分鲁棒。
- **可配置 k 参数**：默认 k≈60，调节高排名片段的权重。
- **混合于混合**：每路内部可再叠加过滤（如 `.gitignore`、`max_file_size`、minified 排除），融合后输出。

社区正在规划 benchmark（issue #529）以量化使用 `search` 工具相对 `grep/read` 的 token 节省。

## 代码智能工具集

`internal/mcp/tools.go` 注册的 MCP 工具主要包括：

| 工具名 | 作用 | 依赖 |
|--------|------|------|
| `search` | RRF 混合检索文档片段 | `internal/search` |
| `symbols` | 查询符号定义/引用 | `internal/graph/registry.go` |
| `flow` | 顺/逆调用图遍历 | `internal/mcp/graph_paths.go` |
| `impact` | 计算变更影响面（BFS/反向可达） | 图 + 符号注册表 |
| `trace` | 输出执行/调用轨迹 | 图 + 监控事件 |

每个工具都接收 `workspace` 与查询参数，工具实现层从 `internal/graph/registry.go` 读取符号注册表（按文件路径哈希存储符号节点），再交由 `graph_paths.go` 中的 BFS/DFS 执行图遍历。资料来源：[internal/graph/registry.go:1-]()、[internal/mcp/graph_paths.go:1-]()

```mermaid
flowchart LR
  Agent[AI Agent] -->|MCP call| Streamable[streamable.go<br/>无状态 HTTP]
  Streamable --> Tools[tools.go<br/>注册与校验]
  Tools -->|search| Search[search.go + rrf.go]
  Tools -->|symbols/flow/impact/trace| Graph[graph_paths.go]
  Graph --> Registry[registry.go<br/>符号节点]
  Search --> Index[(文档索引)]
  Registry --> GraphData[(代码图边)]
  Search --> Resp[统一响应]
  Graph --> Resp
```

## 文件许可与已知缺陷

代码图构建与文档索引**共享同一文件许可策略**，但历史上存在两条代码路径（`scanCollection` 启动/重扫路径 vs. watcher 实时路径）应用了不同过滤器。issue #535 指出：watcher 路径绕过了 `.gitignore`、`max_file_size`、minified 排除，导致**孤立图边**进入 `memory_trace/graph/symbols`，污染代理返回结果。最新发布 v2026.7.0602（PR #538）已通过 `fix(watcher): unify graph-build file admission to stop orphan edges` 统一了两条路径的过滤器。资料来源：[internal/mcp/tools.go:1-]()

类似地，issue #520 提出 `summarizeNotify()` 应仅对**实际产出符号**的文件触发摘要，避免对 JSON/文本缓存做无谓的 LLM 摘要开销。资料来源：[internal/graph/registry.go:1-]()

## 工具集演进方向

社区已识别以下待办：

1. **OpenAPI 3.0 规范**（#530）：REST API 已有约 60 个端点，缺少机器可读的 schema 描述。
2. **MCP 客户端自动配置**（#525）：`nano-brain init` 后应自动写入 Claude Code / OpenCode 的 MCP 配置，而非依赖手动复制 JSON。
3. **默认 workspace 绑定**（#522、#523）：通过 URL query param 省略显式 `workspace` 参数。
4. **Token 成本基准**（#529）：与 `grep/read` 对比建立量化证据。

资料来源：[internal/mcp/streamable.go:1-]()、[internal/mcp/graph_paths.go:1-]()

## 小结

混合检索与代码智能 MCP 工具集以 RRF 融合检索为前端入口、以符号注册表与图路径为后端，在无状态 Streamable HTTP 上向 AI 代理提供低 token 成本的上下文采集。文件许可统一（v2026.7.0602）已修复孤立图边缺陷，下一步重点是协议层（OpenAPI、自动 MCP 配置、workspace 默认绑定）与基准评测。

---

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

## 数据管理：会话采集、索引与存储流水线

### 相关页面

相关主题：[项目概览与系统架构](#page-1), [混合检索与代码智能（MCP 工具集）](#page-2)

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

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

- [internal/harvest/engine.go](https://github.com/nano-step/nano-brain/blob/main/internal/harvest/engine.go)
- [internal/harvest/runner.go](https://github.com/nano-step/nano-brain/blob/main/internal/harvest/runner.go)
- [internal/harvest/opencode_sqlite.go](https://github.com/nano-step/nano-brain/blob/main/internal/harvest/opencode_sqlite.go)
- [internal/harvest/claudecode.go](https://github.com/nano-step/nano-brain/blob/main/internal/harvest/claudecode.go)
- [internal/codesummarize/service.go](https://github.com/nano-step/nano-brain/blob/main/internal/codesummarize/service.go)
- [internal/summarize/pipeline.go](https://github.com/nano-step/nano-brain/blob/main/internal/summarize/pipeline.go)
</details>

# 数据管理：会话采集、索引与存储流水线

## 概述

nano-brain 为 AI 编码 Agent 提供本地化上下文服务，整个数据管理子系统围绕三条核心流水线协作：**会话采集**（`internal/harvest`）、**文档/代码索引**（`internal/summarize`、`internal/codesummarize`）以及基于 **SQLite** 的统一持久化。本页说明这些模块的职责划分、调用关系，以及 v2026.7.0602（PR #538）修复的关键一致性约束。

## 1. 会话采集层（Harvest）

会话采集层是整个数据管线的入口，负责把外部 AI 客户端（OpenCode、Claude Code 等）的本地会话数据转换为 nano-brain 内部统一的 session/message 模型。

- **调度器**：`internal/harvest/engine.go` 探测本机已安装的 AI 客户端并按类型选择具体后端。 资料来源：[internal/harvest/engine.go:20-90]()
- **Runner 编排**：`internal/harvest/runner.go` 负责单客户端的轮询、游标推进与防抖，确保增量采集不会重复写入。 资料来源：[internal/harvest/runner.go:1-80]()
- **OpenCode 后端**：`internal/harvest/opencode_sqlite.go` 直接读取 OpenCode 的本地 SQLite 数据库，复用其表结构还原 session 与 message 序列。 资料来源：[internal/harvest/opencode_sqlite.go:1-60]()
- **Claude Code 后端**：`internal/harvest/claudecode.go` 解析 Claude Code 的本地 JSONL/JSON 存储，转换为统一的内部 session 模型。 资料来源：[internal/harvest/claudecode.go:1-80]()

采集结果统一写入 SQLite 的会话表，供后续 `memory_trace` 与图谱构建复用。

## 2. 文档与代码索引流水线

采集得到的工作区内容需经过两层处理才能被 Agent 检索：**通用文档索引**与**代码专用摘要/符号注册**。

- **通用索引**：`internal/summarize/pipeline.go` 对 collection 内每个文件做读取、分块并写入搜索索引，供 MCP `search` 工具使用。 资料来源：[internal/summarize/pipeline.go:1-120]()
- **代码专用服务**：`internal/codesummarize/service.go` 解析源码 AST，提取符号（函数/类型/变量）并注册到 symbol registry，供 `symbols`、`flow`、`impact`、`trace` 等工具查询。 资料来源：[internal/codesummarize/service.go:1-150]()

这两条管线必须共享同一套文件准入过滤器，这是 issue #535 / PR #538 修复的核心问题：此前的 code-graph 提取器绕过了 `.gitignore`、`max_file_size`、minified 检测，导致 `memory_trace/graph/symbols` 中出现指向被忽略文件的孤立边，污染 Agent 检索结果。

## 3. 启动/重扫路径与文件准入一致性

启动或手动 `rescan` 走的是 `scanCollection` 路径，它正确地嵌套解析 `.gitignore` 与 `.nano-brainignore`，并应用 `max_file_size` 与 minified 检测。watcher 在文件变更后触发的 `summarizeNotify` 回调必须与该路径共用同一过滤器——issue #520 指出该回调过去会对任何被索引进 code collection 的文件无差别触发，对实际不产出符号的文件（如 JSON 状态缓存）应避免无意义的摘要与通知。

PR #538（v2026.7.0602）正是通过统一两路径的准入逻辑来消除孤立边 资料来源：[internal/summarize/pipeline.go:60-140]() 资料来源：[internal/codesummarize/service.go:40-180]()。

```mermaid
flowchart LR
  A[AI 客户端本地存储] --> B[harvest engine]
  B --> C[opencode_sqlite / claudecode]
  C --> D[(SQLite: sessions)]
  D --> E[summarize pipeline]
  E --> F[document index]
  C --> G[codesummarize service]
  G --> H[symbol registry + graph]
  W[watcher] -->|summarizeNotify| E
  W -->|on change| G
```

## 4. 存储后端与运维要点

- **持久化**：所有数据（会话、文档块、符号、图谱边、`memory_trace`）均落在本地 SQLite，零外部依赖。
- **启动顺序**：先 `scanCollection` 建立基线索引，再启动 watcher 接管增量事件。
- **Agent 集成**：MCP 客户端通过 `http://localhost:3100/mcp` 读取上述索引，工具调用须显式带 `workspace` 参数（issue #522/#523 讨论了通过 URL query 绑定默认工作区的方案）。
- **配置入口**：`nano-brain init --root=<path>` 走 zero-config 流程（PR #534），自动探测并注册工作区。
- **REST 暴露**：约 60 个 `/api/v1/*` 端点（issue #530 推动补齐 OpenAPI 规范）独立于 MCP，HTTP 客户端可直接调用。

相关社区讨论：[issue #535 file admission](https://github.com/nano-step/nano-brain/issues/535)、[#520 summarizeNotify 门控](https://github.com/nano-step/nano-brain/issues/520)、[#522/#523 workspace 绑定](https://github.com/nano-step/nano-brain/issues/522)、[#530 OpenAPI 规范](https://github.com/nano-step/nano-brain/issues/530)。

---

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

## 部署、配置、CLI 与 REST API

### 相关页面

相关主题：[项目概览与系统架构](#page-1), [数据管理：会话采集、索引与存储流水线](#page-3)

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

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

- [install.sh](https://github.com/nano-step/nano-brain/blob/main/install.sh)
- [cmd/nano-brain/init.go](https://github.com/nano-step/nano-brain/blob/main/cmd/nano-brain/init.go)
- [cmd/nano-brain/init_serve.go](https://github.com/nano-step/nano-brain/blob/main/cmd/nano-brain/init_serve.go)
- [cmd/nano-brain/mcp_client_config.go](https://github.com/nano-step/nano-brain/blob/main/cmd/nano-brain/mcp_client_config.go)
- [cmd/nano-brain/doctor.go](https://github.com/nano-step/nano-brain/blob/main/cmd/nano-brain/doctor.go)
- [cmd/nano-brain/daemon.go](https://github.com/nano-step/nano-brain/blob/main/cmd/nano-brain/daemon.go)
- [internal/server/routes.go](https://github.com/nano-step/nano-brain/blob/main/internal/server/routes.go)
- [internal/mcp/tools.go](https://github.com/nano-step/nano-brain/blob/main/internal/mcp/tools.go)
- [docs/SETUP_AGENT.md](https://github.com/nano-step/nano-brain/blob/main/docs/SETUP_AGENT.md)
</details>

# 部署、配置、CLI 与 REST API

nano-brain 提供三套面向用户与集成者的入口：基于 `install.sh` 与 npm 的一行安装器、面向运维的 CLI 子命令集合，以及与 MCP 解耦的独立 REST API。本页围绕这三条路径梳理部署、配置与对外接口。

## 安装与零配置初始化

自 v2026.7.0303 起，发布了一条 `curl | bash` 的一行安装器，并在安装过程中校验二进制 SHA256，npm 仍作为备选发行通道。资料来源：[install.sh:1-40]()。

安装完成后，在项目根目录执行 `nano-brain init --root=<path>` 即可完成零配置探测（v2026.7.0302 引入）。`init` 子命令会进行 0–3 次自描述探针，生成自文档化的配置文件，并将敏感字段写入环境变量而非明文文件。资料来源：[cmd/nano-brain/init.go:1-80]()。`init` 流程结束后会打印 `AgentsSnippet`，给出可直接粘贴到 Claude Code / OpenCode 等客户端 MCP 配置的 JSON 片段；这仍是当前主要的注册路径，相关自动化提案见 issue #525。资料来源：[cmd/nano-brain/mcp_client_config.go:1-60]()。

## CLI 子命令与生命周期

CLI 的分发入口位于 `cmd/nano-brain`，全局 flag 由 Go 标准库 `flag` 包解析，因此 `-h/--help` 当前仅展示 6 个全局选项（见 issue #527）；不带参数运行时会直接进入真正的 server 启动流程。主要子命令如下：

| 子命令 | 作用 | 关键源文件 |
| --- | --- | --- |
| `init` | 零配置探测、生成 `.nano-brain` 配置 | [cmd/nano-brain/init.go](https://github.com/nano-step/nano-brain/blob/main/cmd/nano-brain/init.go) |
| `serve` | 启动 HTTP + MCP 守护进程 | [cmd/nano-brain/init_serve.go](https://github.com/nano-step/nano-brain/blob/main/cmd/nano-brain/init_serve.go) |
| `daemon` | 管理后台守护进程（启停/状态查询） | [cmd/nano-brain/daemon.go](https://github.com/nano-step/nano-brain/blob/main/cmd/nano-brain/daemon.go) |
| `doctor` | 诊断依赖、环境与索引健康度 | [cmd/nano-brain/doctor.go](https://github.com/nano-step/nano-brain/blob/main/cmd/nano-brain/doctor.go) |
| `mcp-client-config` | 输出 MCP 客户端配置片段 | [cmd/nano-brain/mcp_client_config.go](https://github.com/nano-step/nano-brain/blob/main/cmd/nano-brain/mcp_client_config.go) |

`serve` 启动后会同时监听 REST 端口与 `/mcp` 端点，二者共享同一进程但协议栈独立。资料来源：[cmd/nano-brain/init_serve.go:40-120]()。`doctor` 用于在 CI 与本地对依赖、文件系统权限、索引一致性进行体检。资料来源：[cmd/nano-brain/doctor.go:1-50]()。

## REST API 形态

REST 层位于 `internal/server/routes.go`，目前对外暴露约 60 个端点，集中在 `/api/v1/*` 命名空间，并保留若干顶层路由；该层与 MCP 服务彼此独立，任何 HTTP 客户端都可以绕过 MCP 直接调用。资料来源：[internal/server/routes.go:1-40]()。

当前存在一个显著缺口：仓库尚未提供 OpenAPI 3.0 规范文件（issue #530），导致非 MCP 客户端缺少可被工具自动发现的契约。补充 spec 之后，客户端 SDK 生成与文档站点都可以基于单一事实源展开。

```mermaid
flowchart LR
    User[用户/脚本] -->|curl/HTTP| REST[/REST API :port/api/v1/*/]
    Agent[AI Agent] -->|Streamable HTTP| MCP[/mcp :3100/mcp/]
    REST --> Core[内部核心服务]
    MCP --> Core
    Core --> FS[(工作区索引)]
```

## MCP 工作区绑定与配置收敛

MCP 采用 Streamable HTTP 传输，端点统一为 `http://localhost:3100/mcp`，刻意保持无状态，因此每次调用都必须在入参中显式提供 `workspace`。资料来源：[internal/mcp/tools.go:140-180]()、`requireWorkspace`。这一设计带来的副作用是：客户端无法从 URL 本身推断当前项目，agent 必须在每次调用前自行决定 `workspace` 取值（issue #522、#523 提议通过 URL query param 提供默认值以跳过 agent 侧发现）。

为缓解上述摩擦，CLI 在 `init` 与 `serve` 之后都会打印 `AgentsSnippet`，由用户将其粘贴进 Claude Code / OpenCode 的 MCP 配置。issue #525 提出在该步骤之上做交互式自动配置，从而避免每增加一个客户端就要手工复制粘贴一次 JSON。资料来源：[docs/SETUP_AGENT.md:160-200]()。

## 已知运维痛点

- CLI `-h/--help` 几乎无内容，且无参数会直接进入 server 流程（issue #527）。
- 缺少 OpenAPI spec，REST API 对外不可发现（issue #530）。
- MCP 调用必须显式传 `workspace`，无 URL 级别的默认绑定（issue #522、#523）。
- 工作区注册到客户端仍需手工粘贴 `AgentsSnippet`，无自动化收尾（issue #525）。

这些痛点共同指向下一步演进方向：在 CLI 帮助输出、OpenAPI 契约、MCP 默认工作区、客户端自动注册四个层面补齐缺口，使部署—配置—接入形成可重复的最小闭环。

---

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

---

## Doramagic 踩坑日志

项目：nano-step/nano-brain

摘要：发现 30 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 失败模式：installation: Interactive MCP client auto-configuration after workspace registration。

## 1. 安装坑 · 失败模式：installation: Interactive MCP client auto-configuration after workspace registration

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: Interactive MCP client auto-configuration after workspace registration
- 对用户的影响：Developers may fail before the first successful local run: Interactive MCP client auto-configuration after workspace registration
- 证据：failure_mode_cluster:github_issue | https://github.com/nano-step/nano-brain/issues/525 | Interactive MCP client auto-configuration after workspace registration

## 2. 安装坑 · 失败模式：installation: v2026.7.0303

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v2026.7.0303
- 对用户的影响：Upgrade or migration may change expected behavior: v2026.7.0303
- 证据：failure_mode_cluster:github_release | https://github.com/nano-step/nano-brain/releases/tag/v2026.7.0303 | v2026.7.0303

## 3. 安装坑 · 来源证据：Code-graph extractor bypasses document-indexer file filters (.gitignore, max_file_size, minified) → orphan edges poison…

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Code-graph extractor bypasses document-indexer file filters (.gitignore, max_file_size, minified) → orphan edges poison memory_trace/graph/symbols for agents
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/nano-step/nano-brain/issues/535 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 4. 安装坑 · 来源证据：Interactive MCP client auto-configuration after workspace registration

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Interactive MCP client auto-configuration after workspace registration
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/nano-step/nano-brain/issues/525 | 来源类型 github_issue 暴露的待验证使用条件。

## 5. 安装坑 · 来源证据：MCP: bind default workspace via URL query param, skip agent-side discovery

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：MCP: bind default workspace via URL query param, skip agent-side discovery
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/nano-step/nano-brain/issues/523 | 来源类型 github_issue 暴露的待验证使用条件。

## 6. 安装坑 · 来源证据：watcher: gate code-summarize notify on files that actually yield symbols

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：watcher: gate code-summarize notify on files that actually yield symbols
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/nano-step/nano-brain/issues/520 | 来源类型 github_issue 暴露的待验证使用条件。

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

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

## 8. 配置坑 · 失败模式：configuration: Add OpenAPI 3.0 spec for the REST API, so non-MCP clients can discover all endpoints

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: Add OpenAPI 3.0 spec for the REST API, so non-MCP clients can discover all endpoints
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Add OpenAPI 3.0 spec for the REST API, so non-MCP clients can discover all endpoints
- 证据：failure_mode_cluster:github_issue | https://github.com/nano-step/nano-brain/issues/530 | Add OpenAPI 3.0 spec for the REST API, so non-MCP clients can discover all endpoints

## 9. 配置坑 · 失败模式：configuration: CLI --help is misleading: -h/--help shows nothing useful, no-args starts a real server, help...

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: CLI --help is misleading: -h/--help shows nothing useful, no-args starts a real server, help list is stale
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: CLI --help is misleading: -h/--help shows nothing useful, no-args starts a real server, help list is stale
- 证据：failure_mode_cluster:github_issue | https://github.com/nano-step/nano-brain/issues/527 | CLI --help is misleading: -h/--help shows nothing useful, no-args starts a real server, help list is stale

## 10. 配置坑 · 失败模式：configuration: MCP: bind default workspace via URL query param, skip agent-side discovery

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: MCP: bind default workspace via URL query param, skip agent-side discovery
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: MCP: bind default workspace via URL query param, skip agent-side discovery
- 证据：failure_mode_cluster:github_issue | https://github.com/nano-step/nano-brain/issues/523 | MCP: bind default workspace via URL query param, skip agent-side discovery, failure_mode_cluster:github_issue | https://github.com/nano-step/nano-brain/issues/522 | MCP: bind default workspace via URL query param, skip agent-side discovery

## 11. 配置坑 · 失败模式：configuration: v2026.7.0103

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v2026.7.0103
- 对用户的影响：Upgrade or migration may change expected behavior: v2026.7.0103
- 证据：failure_mode_cluster:github_release | https://github.com/nano-step/nano-brain/releases/tag/v2026.7.0103 | v2026.7.0103

## 12. 配置坑 · 失败模式：configuration: v2026.7.0302

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v2026.7.0302
- 对用户的影响：Upgrade or migration may change expected behavior: v2026.7.0302
- 证据：failure_mode_cluster:github_release | https://github.com/nano-step/nano-brain/releases/tag/v2026.7.0302 | v2026.7.0302

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

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

## 14. 运行坑 · 失败模式：runtime: Benchmark: token cost of context-gathering with nano-brain vs. manual grep/read

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this runtime risk before relying on the project: Benchmark: token cost of context-gathering with nano-brain vs. manual grep/read
- 对用户的影响：Developers may hit a documented source-backed failure mode: Benchmark: token cost of context-gathering with nano-brain vs. manual grep/read
- 证据：failure_mode_cluster:github_issue | https://github.com/nano-step/nano-brain/issues/529 | Benchmark: token cost of context-gathering with nano-brain vs. manual grep/read

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

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

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/nano-step/nano-brain | no_demo; severity=medium

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

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

## 18. 安全/权限坑 · 来源证据：Add OpenAPI 3.0 spec for the REST API, so non-MCP clients can discover all endpoints

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add OpenAPI 3.0 spec for the REST API, so non-MCP clients can discover all endpoints
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/nano-step/nano-brain/issues/530 | 来源类型 github_issue 暴露的待验证使用条件。

## 19. 安全/权限坑 · 来源证据：Benchmark: token cost of context-gathering with nano-brain vs. manual grep/read

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Benchmark: token cost of context-gathering with nano-brain vs. manual grep/read
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/nano-step/nano-brain/issues/529 | 来源类型 github_issue 暴露的待验证使用条件。

## 20. 安全/权限坑 · 来源证据：CLI --help is misleading: -h/--help shows nothing useful, no-args starts a real server, help list is stale

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：CLI --help is misleading: -h/--help shows nothing useful, no-args starts a real server, help list is stale
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/nano-step/nano-brain/issues/527 | 来源类型 github_issue 暴露的待验证使用条件。

## 21. 能力坑 · 失败模式：capability: watcher: gate code-summarize notify on files that actually yield symbols

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: watcher: gate code-summarize notify on files that actually yield symbols
- 对用户的影响：Developers may hit a documented source-backed failure mode: watcher: gate code-summarize notify on files that actually yield symbols
- 证据：failure_mode_cluster:github_issue | https://github.com/nano-step/nano-brain/issues/520 | watcher: gate code-summarize notify on files that actually yield symbols

## 22. 能力坑 · 失败模式：conceptual: Harness recalibration: differential gates R90-R92, retire state file, Claude Code enforcement...

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this conceptual risk before relying on the project: Harness recalibration: differential gates R90-R92, retire state file, Claude Code enforcement hook
- 对用户的影响：Developers may hit a documented source-backed failure mode: Harness recalibration: differential gates R90-R92, retire state file, Claude Code enforcement hook
- 证据：failure_mode_cluster:github_issue | https://github.com/nano-step/nano-brain/issues/536 | Harness recalibration: differential gates R90-R92, retire state file, Claude Code enforcement hook

## 23. 运行坑 · 失败模式：performance: Code-graph extractor bypasses document-indexer file filters (.gitignore, max_file_size, minif...

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this performance risk before relying on the project: Code-graph extractor bypasses document-indexer file filters (.gitignore, max_file_size, minified) → orphan edges poison memory_trace/graph/symbols for agents
- 对用户的影响：Developers may hit a documented source-backed failure mode: Code-graph extractor bypasses document-indexer file filters (.gitignore, max_file_size, minified) → orphan edges poison memory_trace/graph/symbols for agents
- 证据：failure_mode_cluster:github_issue | https://github.com/nano-step/nano-brain/issues/535 | Code-graph extractor bypasses document-indexer file filters (.gitignore, max_file_size, minified) → orphan edges poison memory_trace/graph/symbols for agents

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

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

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

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

## 26. 维护坑 · 失败模式：maintenance: v2026.7.0102

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v2026.7.0102
- 对用户的影响：Upgrade or migration may change expected behavior: v2026.7.0102
- 证据：failure_mode_cluster:github_release | https://github.com/nano-step/nano-brain/releases/tag/v2026.7.0102 | v2026.7.0102

## 27. 维护坑 · 失败模式：maintenance: v2026.7.0104

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v2026.7.0104
- 对用户的影响：Upgrade or migration may change expected behavior: v2026.7.0104
- 证据：failure_mode_cluster:github_release | https://github.com/nano-step/nano-brain/releases/tag/v2026.7.0104 | v2026.7.0104

## 28. 维护坑 · 失败模式：maintenance: v2026.7.0201

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v2026.7.0201
- 对用户的影响：Upgrade or migration may change expected behavior: v2026.7.0201
- 证据：failure_mode_cluster:github_release | https://github.com/nano-step/nano-brain/releases/tag/v2026.7.0201 | v2026.7.0201

## 29. 维护坑 · 失败模式：maintenance: v2026.7.0301

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v2026.7.0301
- 对用户的影响：Upgrade or migration may change expected behavior: v2026.7.0301
- 证据：failure_mode_cluster:github_release | https://github.com/nano-step/nano-brain/releases/tag/v2026.7.0301 | v2026.7.0301

## 30. 维护坑 · 失败模式：maintenance: v2026.7.0601

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v2026.7.0601
- 对用户的影响：Upgrade or migration may change expected behavior: v2026.7.0601
- 证据：failure_mode_cluster:github_release | https://github.com/nano-step/nano-brain/releases/tag/v2026.7.0601 | v2026.7.0601

<!-- canonical_name: nano-step/nano-brain; human_manual_source: deepwiki_human_wiki -->