Sourcebook

sourcebook

捕捉 AI Agent 忘记修改的文件。

代码变更的安全层。sourcebook 会分析 git 差异，检查变更是否完整——标记那些本应修改却未修改的文件。基于规则的结构检测，加上 AI 驱动的语义分析。干净的差异中零误报。

npx sourcebook init          # sets up Claude Code hooks + generates CLAUDE.md
npx sourcebook check         # check your current diff for missing files
npx sourcebook scan-history  # see what you've been missing

它能捕捉什么

你的 AI Agent 修改了处理程序。它更新测试了吗？同级模块呢？引用旧值的配置呢？

sourcebook 会根据代码仓库的实际结构检查你的差异：

• 缺失的测试文件——源文件已更改，测试文件却没有
• 同级模块——导入了你修改内容或被你修改内容导入的文件
• 共同变更文件——在 git 提交中历史上总是一起变更的文件
• 枢纽文件影响范围——你修改了拥有 50 个以上依赖项的内容

使用 --ai：跨模块语义关系、需要迁移的字段重命名、过时的验证逻辑。

关键数据

指标	结果
完整性门禁	100% 准确（30/30 个差异）
误报率	干净差异中为 0%
测试文件检测率	73%
同级文件检测率	71%
AI 分析成本	每次运行约 $0.012

四种使用方式

1. CLI

对任意差异运行。无需设置。

npx sourcebook check              # check staged/unstaged changes
npx sourcebook check --ai         # add AI semantic analysis (requires ANTHROPIC_API_KEY)
npx sourcebook check --quiet      # exit code only (for CI/scripts)
npx sourcebook check --branch main  # compare vs a branch

2. Claude Code Hooks

一条命令即可配置提交前钩子。Agent 编辑文件后，sourcebook 检查差异，Agent 查看缺失内容——这一切都在提交完成之前进行。

npx sourcebook init   # generates CLAUDE.md + installs hooks

3. MCP 服务

已发布至官方 MCP 注册表。Agent 可以按需查询代码仓库结构、影响范围、约定和共同变更数据。

npx sourcebook serve

添加到你的 MCP 客户端：

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

4. GitHub App（即将推出）

对每个拉取请求自动进行完整性检查。加入候补名单。

命令

命令	描述
sourcebook check	分析当前差异的完整性
sourcebook check --ai	添加 AI 驱动的语义分析（需要 ANTHROPIC_API_KEY）
sourcebook check --quiet	仅返回退出代码——有发现时为 1，干净时为 0
sourcebook check --json	结构化 JSON 输出
sourcebook check --branch main	将 HEAD 与某个分支进行比较
sourcebook check --threshold 0.9	自定义共同变更关联阈值（0-1）
sourcebook init	设置 Claude Code Hooks + 生成 CLAUDE.md/AGENTS.md
sourcebook scan-history	回溯扫描最近的提交
sourcebook hooks	安装或检查 Claude Code Hooks
sourcebook truth	生成代码仓库真实情况图（2.5D 可视化）
sourcebook serve	启动 MCP 服务
sourcebook update	重新分析，同时保留手动编辑内容
sourcebook diff	显示将发生的变更（发现变更时退出代码为 1）
sourcebook watch	源文件变更时自动重新生成上下文文件
sourcebook ask <query>	以自然语言查询代码库知识

工作原理

层 A——基于规则（无需 LLM，不到 1 秒）

1. 共同变更分析——挖掘 git 历史，找出一起变更的文件。如果你修改了 auth.ts，且它在 88% 的提交中都会与 session.ts 一起变更，sourcebook 就会标记 session.ts。
2. 测试文件检测——通过命名约定和共同变更历史，将源文件映射到测试文件。
3. 导入关系图——构建依赖关系图，并检查导入（或被导入）你所修改文件的文件是否也需要更新。
4. 枢纽检测——当你修改了入度较高（依赖项众多）的文件时发出标记。这类变更会产生影响范围。

Layer B — AI 驱动（约 $0.012/次运行）

将差异以及依赖关系上下文发送给 Claude Sonnet。它能捕捉 Layer A 无法发现的语义关系，例如需要迁移的字段重命名、假设旧架构的验证逻辑，以及没有导入链接的跨模块依赖。

每条 AI 建议都必须附上依赖关系引用。虚构的文件路径会被过滤掉。完整性门槛可确保零误报：如果差异实际上是完整的，Layer B 就会保持静默。

配置

# Required for --ai flag only
export ANTHROPIC_API_KEY=sk-ant-...

无需其他配置。sourcebook 会直接读取仓库的 Git 历史记录和文件结构。

语言支持

语言	导入图	Git 分析	规范检测
TypeScript / JavaScript	完整	完整	完整
Python	完整	完整	完整
Go	完整	完整	完整
Rust	完整	完整	部分

研究

基于真实基准测试，而非主观臆测：

• 查看验证结果 — 方法和准确性数据
• 基准测试：19 项任务、10 个仓库、4 种语言 — 受控的 Agent 性能测试
• 为什么自动生成的上下文会让 Agent 表现变差 — 塑造了我们方案的 ETH Zurich 研究发现

许可证

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

---

sourcebook.run · GitHub · npm · @maroond_