SpiderBrain：你仓库的理解层

仓库会告诉 AI 智能体代码是什么。但它从不告诉它什么重要、一次变更会影响到什么，或者某件事为什么会以这种方式构建。于是每个智能体每次会话都从零重新推导结构，而且总会推导得有点偏差。

SpiderBrain 为仓库提供了一个已提交的、不含源码的理解层：一张关于其结构、依赖和爆炸半径的确定性地图，任何 AI 编码智能体都可以零配置读取。本仓库是该层中开放、MIT 许可的部分：读取器，以及格式规范。

• 网站：https://spiderbrain.ai

• 确定性基准：https://contextbenchmark.com

一行即可使用

当仓库带有 .spiderbrain/ 文件夹时，将读取器指向它：

npx spiderbrain mcp --root .

MCP 客户端的工作目录通常不是你的仓库，因此请用 --root <path>、--root=<path> 或 SPIDERBRAIN_ROOT 环境变量显式传入仓库。否则服务器会提供工作目录，并报告未找到理解层——这是一个错误答案，而不是一个错误。

这会启动一个 MCP 服务器，你的编码智能体（Claude Code、Cursor 或任何 MCP 客户端）都可以查询。工具：sb_blast、sb_impact、sb_path、sb_keystones、sb_map、sb_ask。无需账户、无需安装 SpiderBrain、无需配置。真实的会话记录见 examples/agent-session.md。

更喜欢终端：

npx spiderbrain blast src/server/health.ts   # what a change here reaches
npx spiderbrain impact                        # what YOUR CURRENT DIFF reaches
npx spiderbrain keystones                     # the load-bearing files
npx spiderbrain map src/auth/session.ts       # what a file is + touches
npx spiderbrain path src/a.ts src/b.ts        # how one file reaches another
npx spiderbrain verify --allow-stale          # folder untampered? see note below

为什么已提交的 brain 需要 --allow-stale。 verify 检查两件事：structure.ndjson 是否仍与其记录的指纹匹配，以及 brain 是否在当前 HEAD 上完成评分。提交该文件夹本身也是一次提交，因此提交到仓库的 brain 总是至少落后一个提交，第二个检查在全新克隆上永远无法通过。--allow-stale 保持完整性检查严格，并且只容忍这一点。当你在 CI 中于所测试的提交上构建 brain 时（此时时效性是真实的），请去掉该标志。

Related MCP server: mcp-codebase-intelligence

智能体是一等公民

每个命令都接受 --json 并输出一个机器可读对象，退出码也是约定的一部分：0 正常，1 检查失败，2 用法错误，3 无理解层。CI 可以据此设置门禁：

npx spiderbrain impact --fail-over 200   # fail a PR whose blast exceeds 200 files
npx spiderbrain verify                   # fail a build whose folder is stale or edited (drop --allow-stale to require currency)

现成的工作流——PR 爆炸半径评论和新鲜度门禁——位于 examples/。

没有文件夹？注册表回退

当仓库没有 .spiderbrain/ 文件夹时，读取器会在公共 SpiderBrain 注册表中查找同一仓库的非官方 brain（通过 origin 远程匹配，带有明确标签，并经过指纹验证）。如果存在已提交的文件夹，它总是优先；维护者可以用 npx spiderbrain create 发布官方 brain。

这个仓库也吃自己的狗粮

本仓库带有自己已提交的 .spiderbrain/ 文件夹，它源自真实的导入图（node scripts/build-own-brain.mjs，以确定性方式重新生成，并在 CI 中验证）。克隆它，然后向它询问关于它自己的问题：

npx spiderbrain keystones      # read/src/core.mjs is the load-bearing file
npx spiderbrain verify --allow-stale   # the committed fingerprint matches the bytes

为你的仓库赋予理解层

export SPIDERBRAIN_API_KEY=sb_live_...     # https://spiderbrain.ai/dashboard?tab=keys
npx spiderbrain create

获取你已评分的 brain，并写入不含源码的 .spiderbrain/ 文件夹以及一个 AGENTS.md 块。将两者都提交，之后每个接触该仓库的智能体都会读取它。

离线 vs 云端

• 离线（免费、确定性、来自已提交的字节）：结构、依赖、爆炸半径、关键节点。同一仓库、同一问题、同一答案，逐字节一致。

• 云端（设置 SPIDERBRAIN_API_KEY）：文件背后的原因（记录的决策及其推理）、始终新鲜的评分，以及语义搜索。在 https://spiderbrain.ai/dashboard?tab=keys 获取密钥。

export SPIDERBRAIN_API_KEY=sb_live_...
npx spiderbrain why src/billing/charge.ts

文件夹里有什么

已提交的 .spiderbrain/ 文件夹是不含源码的：只有文件路径、结构和可由边推导的爆炸半径。绝不含你的源代码。绝不含评分权重。其确切内容和确定性保证记录在 SPEC.md 中。

每个文件夹都在其 manifest.json 中带有一个指纹；读取器在加载时会重新计算它，因此手工编辑或损坏的文件夹会被标记，而你查询的地图就是已发布的地图。

本仓库（三个 MIT 包 + 规范）

• spiderbrain/ — spiderbrain，即那一个命令。一个薄薄的调度器，负责下面两个包。

• read/ — @spiderbrain/read，消费：文件夹加载器、爆炸半径遍历、CLI、MCP 服务器、云端客户端。零依赖。

• create/ — @spiderbrain/create，生产：获取你已评分的 brain，并写入理解集 + AGENTS.md。

• SPEC.md — .spiderbrain/ 公共文件夹格式。

每个作用域包都可以独立安装：只发布理解层的 CI 任务只需要 @spiderbrain/create；只读取的 MCP 配置指向 @spiderbrain/read。当你只是想要这个东西时，输入 spiderbrain 即可。

对 brain 进行评分的引擎（解析和评分模型）是专有的，归 SpiderBrain 所有。这里开放的是格式、读取器和生产客户端，因此任何人都可以读取或写入已发布的理解层，或构建一个做到这一点的工具。

许可证

MIT。参见 LICENSE。