描述
codebase-snapshot 是一个工具，旨在将代码库转换为一组适合 LLM 的部分，遵循严格的字节预算。它解决了将大型代码库输入语言模型时面临的挑战，因为文件可能过大而上下文窗口又过小。该工具以确定性方式运行，确保在输入不变的情况下输出一致。
阅读更多
其核心功能围绕创建一个 `snapshot/` 目录，包含纯文本部分。每个部分受限于 `maxPartBytes` 的上限；超过此预算的文件会被截断，并带有明确的省略标记。对于非常大的文件，它提供头/尾摘录。除了代码部分外，它还生成一个 `manifest.json` 文件。该清单作为一个全面的索引，列出每个包含的文件及其详细信息，如层、类型、语言、部分、哈希和结构摘要。重要的是，它还记录每个被排除的文件及其省略的具体原因，例如 `gitignore`、`sensitive-file` 或 `binary`。
维护上下文完整性的一个关键特性是 `validate` 命令。该命令会重新哈希代码库与生成的快照进行比较，如果检测到任何漂移，则以非零代码退出。这确保了 LLM 上下文保持新鲜和准确，防止模型使用过时的代码。该工具默认安全，跳过凭证文件，除非明确请求，遮蔽敏感字符串，并通过拒绝覆盖未创建的目录来防止意外删除源代码。
codebase-snapshot 支持广泛的编程语言和框架，包括 TypeScript、JavaScript、Python、Go、Rust、Java/Kotlin、C#/.NET、PHP、Ruby、C/C++、Vue、Svelte、Astro、Next.js、Nuxt、Remix、Angular、Solid、NestJS、Express、Fastify、Koa、Django、FastAPI、Flask、Laravel 和 Rails，通常无需配置。它提供 25 个自动预设，贡献层、类型、生态系统忽略模式和推荐的部分预算。对于非 TypeScript 语言，它生成导入/导出/类/函数摘要，将其标记为 `ast`、`structural` 或 `heuristic` 以指示其可靠性。
除了人类交互，codebase-snapshot 还为 AI 代理而构建。它提供机器可读的合同和可安装的技能，允许代理自主驱动整个过程。代理可以使用 `generate`、`validate`、`report` 和 `explain` 等命令来管理快照、检查漂移、审计秘密以及理解文件的包含/排除。该工具还支持程序化 API 访问，以便集成到更大的系统中。其全面的文档涵盖安装、CLI 参考、配置、快照输出模式以及有效使用 LLM（如 ChatGPT、Claude 和 Cursor）的指南。
- 类别AI 编程助手
- 定价模式免费
- 部署CLI, Programmatic API
- 平台Node.js 18+
codebase-snapshot的核心功能
确定性快照生成
严格的字节预算限制
全面的 manifest.json 索引
使用 `validate` 命令进行漂移验证
自动检测 25 个项目预设
支持多种编程语言和框架
敏感信息遮蔽和文件排除
为 AI 代理提供机器可读的合同
可安装的代理技能
程序化 API 访问
详细的报告和审计
引导首次运行设置
可配置的输出工件
针对大文件的内存限制处理
使用 `diff` 命令进行快照比较
如何使用 codebase-snapshot？
安装：使用 npm、yarn、pnpm 或 bun 全局安装 `codebase-snapshot` 或作为项目依赖。
快速开始：在项目目录中运行 `snapshot` 以进行引导首次运行或自动生成。
配置：使用 `init` 命令进行交互式设置，写入自文档化的 `snapshot.config.ts` 文件。
生成快照：执行 `snapshot generate` 创建适合 LLM 的快照目录。
验证快照：运行 `snapshot validate` 将快照与当前代码库进行比较并检查漂移。
解释路径：使用 `snapshot explain <path>` 理解特定文件为何被包含、跳过或其位置。
审计报告：生成 `snapshot report` 以获取健康指标、层详细信息和秘密审计。
codebase-snapshot的使用案例
- LLM 上下文生成
- AI 代理代码分析
- 代码审查自动化
- 开发者入职
- 上下文窗口管理
- 代码库审计
- 确保上下文新鲜度
- 跨代码库比较
