sourcebook

AI 可以阅读你的代码，但它仍然不知道你的项目是如何运作的。

sourcebook 可以捕获团队成员脑海中的项目知识——包括规范、模式、陷阱以及代码的实际存放位置——并将其转化为编码智能体可以使用的上下文。

npx sourcebook init

像 Repomix 这样的工具会将整个代码库提供给 AI。而 sourcebook 提供的是你的项目知识。

为什么

AI 编码智能体大部分的上下文窗口都花在“定位”上——在进行实际工作之前阅读文件以建立心理模型。大多数上下文文件（CLAUDE.md，.cursorrules）都很通用，且很快就会过时。

研究表明，自动生成的、重述显而易见信息的上下文实际上会使智能体的表现下降 2-3%。唯一有帮助的上下文是非显性信息——即智能体无法仅通过阅读代码就能发现的项目知识。

sourcebook 只提取智能体总是遗漏的内容：存在于团队成员脑海中而非代码中的规范、隐藏的依赖关系、脆弱区域和主导模式。

它能发现什么

• 导入图 + PageRank — 按结构重要性对文件进行排名，识别具有最广泛影响范围的枢纽文件

• Git 历史取证 — 还原的提交（“不要这样做”的信号）、协同变更耦合（隐性依赖）、快速重构（难以正确实现的代码）、废弃方案中的反模式

• 规范检测 — 命名模式、导出风格、导入组织、桶导出 (barrel exports)、路径别名、类型提示用法、错误处理风格

• 框架检测 — Next.js, Expo, Supabase, Tailwind, Express, TypeScript, Django, FastAPI, Flask, Go (Gin, Echo, Fiber)

• 感知上下文衰减的格式化 — 顶部放置关键约束，中间放置参考信息，底部放置操作提示（针对 LLM 的注意力模式进行了优化）

• 智能预算执行 — 当上下文超出 Token 预算时，优先丢弃低优先级部分（始终保留关键约束）

快速开始

# Generate CLAUDE.md + AGENTS.md for your project
npx sourcebook init

# Generate for a specific tool
npx sourcebook init --format claude,agents  # CLAUDE.md + AGENTS.md (default)
npx sourcebook init --format cursor         # .cursor/rules/sourcebook.mdc + .cursorrules
npx sourcebook init --format copilot        # .github/copilot-instructions.md
npx sourcebook init --format agents         # AGENTS.md only
npx sourcebook init --format all            # All of the above

# Re-analyze while preserving your manual edits
npx sourcebook update

# See what changed since last generation (exit code 1 = changes found)
npx sourcebook diff

# Limit output to a token budget (drops low-priority sections first)
npx sourcebook init --budget 1000

命令

选项

语言支持

GitHub Action

在每次合并时自动更新上下文文件：

# .github/workflows/sourcebook.yml
name: Update context files
on:
  push:
    branches: [main]

jobs:
  sourcebook:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: maroondlabs/sourcebook@main
        with:
          format: all

输出示例

在 cal.com 上运行（10,456 个文件）：

sourcebook
Extracting repo truths...

✓ Scanned project structure
  10,456 files, 3 frameworks detected
✓ Extracted 11 findings

  ● Core modules: types.ts imported by 183 files — widest blast radius
  ● Circular deps: bookingScenario.ts ↔ getMockRequestData.ts
  ● Co-change: auth/provider.ts ↔ middleware/session.ts (88% correlation)
  ● Dead code: 1,907 orphan files detected
  ● Conventions: named exports preferred (26:2 ratio)
  ● Barrel exports: 40 index.ts re-export files
  ● Commit style: Conventional Commits (feat/fix/docs)

✓ Wrote CLAUDE.md
✓ Wrote AGENTS.md

工作原理

sourcebook 执行五次分析，全部是确定性的且在本地运行——无需 LLM，无需 API 密钥，无需网络调用：

1. 静态分析 — 框架检测、构建命令、项目结构、环境变量

2. 导入图 — 构建所有导入的有向图，运行 PageRank 以找到结构上最重要的文件

3. Git 取证 — 从提交历史中挖掘还原记录、反模式、协同变更耦合、变动热点和废弃方案

4. 规范推断 — 对源文件进行采样，以检测命名、导入、导出、错误处理和类型注解模式

5. 预算执行 — 如果输出超过 Token 预算，智能地丢弃低优先级部分（先丢弃补充发现，绝不丢弃关键约束）

然后应用可发现性过滤器：对于每一个发现，询问“智能体能否通过阅读代码发现这一点？”如果可以，则丢弃。只有非显性信息才会进入输出。

输出格式针对抗上下文衰减进行了优化——关键约束位于文件的顶部和底部（LLM 最关注的地方），轻量级参考信息位于中间。

MCP 服务器

sourcebook serve 启动一个本地 MCP（模型上下文协议）服务器，向任何兼容 MCP 的 AI 客户端（如 Claude Desktop、Cursor 等）公开实时代码库智能。

你的 AI 智能体不再依赖静态上下文文件，而是可以按需查询项目的架构：在编辑前查看影响范围，在编写代码前检查规范，从 Git 历史中挖掘反模式。

安装

将 sourcebook 添加到你的 MCP 客户端配置中：

{
  "mcpServers": {
    "sourcebook": {
      "command": "npx",
      "args": ["-y", "sourcebook", "serve", "--dir", "/path/to/your/project"]
    }
  }
}

Claude Code — 在终端运行：

claude mcp add sourcebook -- npx -y sourcebook serve --dir /path/to/your/project

或者手动添加到 ~/.claude/claude_desktop_config.json。

Claude Desktop — 添加到 ~/Library/Application Support/Claude/claude_desktop_config.json。

Cursor — 添加到项目中的 .cursor/mcp.json 或全局的 ~/.cursor/mcp.json。

其他 MCP 客户端 — 任何支持 STDIO 传输的客户端都可以使用上述相同的配置块。

更新配置后重启客户端。

可用工具

服务器会将扫描结果缓存在内存中——后续的工具调用速度很快。向 analyze_codebase 传递 refresh: true 可强制重新扫描。

路线图

• [x] .cursor/rules/sourcebook.mdc + 旧版 .cursorrules 输出

• [x] .github/copilot-instructions.md 输出

• [x] sourcebook update — 重新分析同时保留手动编辑

• [x] sourcebook diff — 显示更改内容（CI 友好的退出代码）

• [x] --budget <tokens> — 基于 PageRank 的智能优先级排序

• [x] 从还原的提交和删除的文件中检测反模式

• [x] Python 支持 (Django, FastAPI, Flask, pytest)

• [x] Go 支持 (Gin, Echo, Fiber, 模块布局)

• [x] 用于 CI 的 GitHub Action

• [x] sourcebook serve — MCP 服务器模式

• [ ] 框架知识包（社区贡献）

• [ ] 用于更深入规范检测的 Tree-sitter AST 解析

• [ ] 带有上下文质量评分的托管仪表板

研究基础

构建于以下研究成果之上：

• 苏黎世联邦理工学院 AGENTS.md 研究 — 自动生成的显而易见上下文会损害智能体性能

• Karpathy 的 autoresearch — 精选上下文 (program.md) 是提高智能体效能的第一杠杆

• Aider 的 repo-map — 在导入图上运行 PageRank 以确定结构重要性

• Chroma 的上下文衰减研究 — LLM 对上下文中间信息的准确率下降 30% 以上

许可证

BSL-1.1 — 源码可见，免费使用，不得作为托管服务提供。将于 2030-03-25 转换为 MIT 许可证。详情请参阅 LICENSE。