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）。

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

概述

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 工具主要包括：

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

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 默认绑定）与基准评测。

概述

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。

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、#520 summarizeNotify 门控、#522/#523 workspace 绑定、#530 OpenAPI 规范。

安装与零配置初始化

自 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 启动流程。主要子命令如下：

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 生成与文档站点都可以基于单一事实源展开。

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 默认工作区、客户端自动注册四个层面补齐缺口，使部署—配置—接入形成可重复的最小闭环。

Pitfall Log / 踩坑日志

项目：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