# @ankurhalder/codebase-snapshot 中文文档

规范地址：https://npmcn.com/package/%40ankurhalder/codebase-snapshot/

版本：4\.4\.1
npm 元数据更新时间：2026-11-04T19:13:51.501Z
中文译文更新时间：2026-11-06T14:03:13.705Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40ankurhalder/codebase-snapshot
原文对照：https://npmcn.com/package/%40ankurhalder/codebase-snapshot/?lang=original
项目主页：https://github.com/ankurhalder/codebase-snapshot#readme
源码仓库：https://github.com/ankurhalder/codebase-snapshot

弃用说明：Renamed to codebase-snapshot, which is the supported package\. Run: npx codebase-snapshot@latest setup

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.7 MB，23 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：1 个
- 首次发布：2026-11-03T12:51:33.398Z
- 最新版本发布：2026-11-04T17:42:29.572Z
- 近 30 天下载量：3666（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：19（近 12 个月 19 个）

## 中文简介

生产级 LLM 密码库快照生成器、审计员和 AST 分配器

## 安装

```sh
npm install @ankurhalder/codebase-snapshot
```

也可以使用：`pnpm add @ankurhalder/codebase-snapshot`、`yarn add @ankurhalder/codebase-snapshot`、`bun add @ankurhalder/codebase-snapshot`

## README

# 密码基相机

**将任何寄存器转换为 LLM 已准备好的快照 : 编码装入到大小预算下标记 由JSON清单编制索引,并进行秘密审计——在一个指令中.**

[![npm version](https://img.shields.io/npm/v/@ankurhalder/codebase-snapshot.svg)](https://www.npmjs.com/package/@ankurhalder/codebase-snapshot) [![npm downloads](https://img.shields.io/npm/dw/@ankurhalder/codebase-snapshot.svg)](https://www.npmjs.com/package/@ankurhalder/codebase-snapshot) [![license](https://img.shields.io/badge/license-MIT-blue.svg)](https://npmcn.com/package/%40ankurhalder/codebase-snapshot/LICENSE) [![node](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org/)

```bash
npx @ankurhalder/codebase-snapshot generate
```

写着 `./snapshot/` ——您可以跳入聊天的目录,提示,RAG管道或 资料库审查。 它在TypeScript和JavaScript项目上工作,在Python,Go,Rust,Python上工作, Java/Kotlin,C#/.NET,PHP,Ruby,C/C++,Vue,斯维尔特和Astro,没有配置.

![How it works](https://raw.githubusercontent.com/ankurhalder/codebase-snapshot/main/docs/how-it-works.svg)

* * *

## 为什么

给模型输入一个真正的寄存器很尴尬:文件太大, 上下文窗口太宽 量小,用手挑什么是最重要的 不规模或重复. `codebase-snapshot` 这样做 确定:

-   **每部分一个文件,从不超出预算.** `maxPartBytes` 是一个硬天花板。 一个更大的文件 而不是预算被删节 带有明确的省略标记 命名预算而不是 吹出极限——及以上 `largeFileBytes` 改为头/尾节取出.
-   **一个索引,不只是文本.** `manifest.json` 列出每个包含的文件及其层、类型, 语言、部分、散列和结构摘要——以及 _不包括_ 与原因相关的文件.
-   **很明显是现在.** `validate` 将寄存器与快照和出入口重新连接 在任何漂移上,非零, 所以管道可以门 在上下文是新鲜的.
-   **何所决定.** 两次运行于未改变输入时给出字节相同的 `parts/`, (中文(简体) ), `reports/navigation.md` 财务报告和审定财务报表 `reports/project-tree.md`,同样 `manifest.fingerprint`。仅限 `manifest.json`,快照's `README.md`, (中文(简体) ), `reports/audit.md` 财务报告和审定财务报表 `.codebase-snapshot` 运行之间的变化,因为它们携带 时间戳,一个运行的id和一个pid.
-   **默认安全.** 证书文件被跳过, 除非请求, 密形字符串是 已编辑, 且错误的输出目录无法删除源代码 .
-   **被特工们使用 不仅仅是人类.** 机器可读合同和可安装技能 让一个没有前科的特工来推动这一切.

## 安装

```bash
npx @ankurhalder/codebase-snapshot generate      # no install, one-off
npm install -D @ankurhalder/codebase-snapshot    # or add it to a project
```

任何npm相容的客户端作品——npm,纱线(经典和Berry有严格的PnP),pnpm和包子—— 在释放前,每个都与被包装的柏油丸核对。 要求数 **节点.js 18+**。 。 。 .

→ [安装指南](https://npmcn.com/package/%40ankurhalder/codebase-snapshot/docs/install.md)

## 快开始

一个命令执行整个第一次运行——检测工程,写一个注释配置,添加 npm 脚本和 devDependency, 安装它, 生成快照 :

```bash
npx @ankurhalder/codebase-snapshot setup
```

```bash
# Or step by step, if you want to see each stage:
npx @ankurhalder/codebase-snapshot init --yes   # config + scripts + devDependency + .gitignore
npm install                                     # the package, into node_modules
npm run snapshot                                # generate
npm run snapshot:validate                       # exit 0 = current with disk
```

`setup` 保存存储器已有的配置 `setup --no-install` 跳过安装 (CI,离线,或锁文件,你宁愿不碰).

```
📸 Generating snapshot for: /Users/you/project
   Branch: main | Part budget: 300 KB

✅ Snapshot generated in 0.14s:
   - Tracked files: 128
   - Total lines:   9,431
   - Total size:    0.41 MB
   - Parts written: 3 under snapshot/parts/
   - Reports:       snapshot/reports/ (project-tree, navigation, audit)
   - Manifest:      snapshot/manifest.json
   - Fingerprint:   e4607b570268c8def0911babbace97e4a0196d9eaf2cac22c8847500883d70aa
   - Integrity:     passed
```

指纹是全部打印出来的——全部64个六十六个字符,从未被擦出过,也是一样的 值为 `manifest.fingerprint`。 。 。 .

## 你得到的东西

```
snapshot/
├── README.md                  human summary of this snapshot
├── manifest.json              machine index: files, parts, hashes, config, skips
├── parts/part-001.md …        the code, grouped and size-budgeted
└── reports/
    ├── project-tree.md        directory tree of included files
    ├── navigation.md          links between layers, kinds and parts
    └── audit.md               secrets, large files, parse diagnostics, git state
```

每件文物都可以关闭(`--skip-artifacts`, (中文(简体) ), `--only-artifacts`,或配置.

→ [快照输出和显示方案](https://npmcn.com/package/%40ankurhalder/codebase-snapshot/docs/output.md)

## 建为可信任的整个仓库

一个快照只有在你能相信的情况下才有用,所以工具对它所做的一切都明确了 _没有_ 包含:

-   **没有什么是默默地放弃的.** 每个被排除的路径都记录在 `manifest.skipped[]` 带有 原因.. `binary`, (中文(简体) ), `gitignore`, (中文(简体) ), `default-ignore`, (中文(简体) ), `sensitive-file`, (中文(简体) ), `sensitive-path`, (中文(简体) ), `symlink`, (中文(简体) ), `outside-root`, (中文(简体) ), `read-error`, (中文(简体) ), `not-file`, (中文(简体) ), `nested-repository`, (中文(简体) ), `excluded` - 和 `explain <path>` 回答任何单一路径的相同问题.
-   **编码有说明,没有猜到.** UTF-16 文件被转码而不是消失为 “ 二进制” ; 一个无效的 UTF-8 被保存但标签 `utf-8-lossy` 计数 无法解码的字节,所以你永远不要误把摩吉贝克当作源.
-   **数来描述所排放的东西.** `includedBytes` 财务报告和审定财务报表 `includedLines` 从 块,而不是磁盘上的文件.
-   **漂流被检查,而不是假设.** `validate` 比较每个文件的散列 _财务报告和审定财务报表_ 一、导 言 设置快照的生成方式, 因此改变预算、 层规则或秘密模式 漂移而不是沉默.
-   **内存被限制.** 2 MB 以上的文件不解析结构摘要( 也就是 50 MB 文件) 用于达到3GB的内存),以及一个目录或3000级路径中的130000个文件 扫描没有崩溃.
-   **`diff` 比较有效载荷,不只是路径.** 两张不同来源的快照 设置是这样说的,而不是报告“0已更改”.
-   **当 git 无法列出文件时** ——被中断的克隆人,被脱水 `.git`, (中文(简体) ), `safe.directory` —— 说 跑步拒绝而不是悄悄地扫描 不同的东西,和 `--discovery walk` 这是 有记录的出逃舱门.

## 支助项目

25个预设,自动从寄存器中检测到——每个贡献层,类型, 生态系统忽略了模式和所建议的部分预算.

|  |  |  |  |
| :-- | :-- | :-- | :-- |
| 下一个.js | 坚果 | 斯维尔特基特 | 重混合 |
| 天体 | 角质 | 固态 | Vue + 维特 |
| 反应 + Vite | 网点JS | 快递 /快递 / Koa | 节点库 |
| 单曲 | 强哥 | FastAPI / 弗拉斯克语 | Python 库 |
| 走开 | 锈 | 爪哇/ 春季 | . NET 网络 |
| 拉维尔(菲律宾) | 铁路(Ruby) | Terraform / docker inform 中标 | 只读文档 |
| 常规倒置 |  |  |  |

非TypeScript语言获得进出口/类/功能摘要,而不是处理 作为不透明的文本。 Vue,斯维尔特和Astro脚本块通过真正的TypeScript编译器. 每份摘要都有标签 `ast`, (中文(简体) ), `structural` 或者说 `heuristic` 你知道该相信多少.. 例如, Python 是一行扫描 `heuristic`,而JSON和马克当得到 `structural` 形状.

→ [预设表格和检测规则](https://npmcn.com/package/%40ankurhalder/codebase-snapshot/docs/configuration.md#project-presets)

## 图标

| 命令 | 对 |
| :-- | :-- |
| `generate` _(默认)_ | 写快照. |
| `validate` 编号 : `check` | 将快照与寄存器进行比较; 退出 `1` 在漂流. |
| `report` | 快照健康 分层测量 秘密审计. |
| `init` | 交互式( 或) `--yes`) 设置写出自文档配置. |
| `explain <path>` | 为什么包含一条路径,它降落在哪个部分,或者它被跳过的原因. |
| `diff <a> <b>` | 比较两个快照. |
| `describe` | 机器可读合同`--format json`) (中文(简体) ). |
| `skill` | 打印或安装代理技能 . |

退出代码 : `0` 成功 · `1` 漂移或拒绝的一代 `2` 使用错误.

→ [完整的 CLI 参考](https://npmcn.com/package/%40ankurhalder/codebase-snapshot/docs/cli.md)

## 对于人工智能特工

代理人需要的一切都可以作为数据提供,工具可以安装自己的技能:

```bash
# The contract: workflow, every option and default, exit codes, presets, safety rules
npx @ankurhalder/codebase-snapshot describe --format json

# Install the skill into the registries agent tools read: .claude/skills/, .cursor/rules/
# (it adds those files to .gitignore, and never touches your own AGENTS.md)
npx @ankurhalder/codebase-snapshot skill --install
```

一个特工只说"用" `npx @ankurhalder/codebase-snapshot`" 能够阅读合同,遵循其 命令工作流程,并生成一个未经帮助的验证快照——该路径由测试覆盖.

→ [用这个做人工智能](https://npmcn.com/package/%40ankurhalder/codebase-snapshot/docs/agent.md) • 妇女 [一般事务人员(其他职等)](https://github.com/ankurhalder/codebase-snapshot/blob/main/AGENTS.md) • 妇女 [页:1](https://github.com/ankurhalder/codebase-snapshot/blob/main/llms.txt)

## 配置

`snapshot.config.ts` (或 `.mjs`)写作者 `init` 与 **每个** 设置当前 值,评论和分组,因此作为参考值加倍. 删除任何行都是安全的: 默认是真实的。 该对象通过名称导出 - `export default { … }` 实值 `import/no-anonymous-default-export`,默认情况下在 `eslint-config-next`。 。 。 .

```js
const config = {
  maxPartBytes: "120k",                                   // hard budget per part
  excludePatterns: ["vendor/**", "**/*.min.js"],
  artifacts: { monolith: false },                         // single-file output stays off
  budgets: { default: "120k", byLayer: { docs: 40_000 } },
  includeSensitiveFiles: false,                           // .env, *.pem … stay out
};

export default config;
```

→ [配置参考](https://npmcn.com/package/%40ankurhalder/codebase-snapshot/docs/configuration.md)

## 程序化 API

```js
import { generateSnapshot, resolveConfig, validateSnapshot, loadConfigFile } from "@ankurhalder/codebase-snapshot";

// Pass the repository explicitly: loadConfigFile returns only the config it found, so a
// directory with no config file would leave resolveConfig scanning process.cwd() instead.
const dir = "/path/to/repo";
const config = resolveConfig(await loadConfigFile(dir), { cwd: dir });
const manifest = generateSnapshot(config);
const validation = validateSnapshot(config);
```

通用JS工作也一样(`require("@ankurhalder/codebase-snapshot")`页:1 都一样 CLI和API共享一个执行,所以CLI所做的一切在这里都可以得到.

## 文档

|  |  |
| :-- | :-- |
| [安装](https://npmcn.com/package/%40ankurhalder/codebase-snapshot/docs/install.md) | 每个客户端, 版本 pinning, 代理技能安装 |
| [CLI 参考](https://npmcn.com/package/%40ankurhalder/codebase-snapshot/docs/cli.md) | 命令、选项、退出代码、实例 |
| [配置](https://npmcn.com/package/%40ankurhalder/codebase-snapshot/docs/configuration.md) | 每个设定,全部25预设,预算,钩子,秘密 |
| [快照输出](https://npmcn.com/package/%40ankurhalder/codebase-snapshot/docs/output.md) | 目录布局和完整的显示方案 |
| [AI探员](https://npmcn.com/package/%40ankurhalder/codebase-snapshot/docs/agent.md) | 合同 技能 代理人应该回避什么 |
| [解决问题](https://npmcn.com/package/%40ankurhalder/codebase-snapshot/docs/troubleshooting.md) | 每条消息和做什么 |
| [更改日志](https://npmcn.com/package/%40ankurhalder/codebase-snapshot/CHANGELOG.md) | 释放历史和断开更改 |
| [维基](https://github.com/ankurhalder/codebase-snapshot/wiki) | 指南、食谱、FAQ |

## 安全问题

-   **默认排除证书文件** —— 说 `.env`, (中文(简体) ), `*.pem`, (中文(简体) ), `*.key`, (中文(简体) ), `.npmrc`, (中文(简体) ), `.netrc`, (中文(简体) ), `.git-credentials`, (中文(简体) ), `id_rsa`, (中文(简体) ), `.kube/config`, (中文(简体) ), `*.tfstate` 列入 `manifest.skipped[]` 与缘由.
-   **机密已经编辑** 普通文件内: 只有匹配的跨度被遮盖, 绝不是 整个线, 并且没有节选到达任何文物.
-   **输出目录由工具拥有.** 每次运行都会被写入到抓取目录和 在解剖学上互换; 前一个快照在失败中幸存.
-   **它拒绝替换它没有创建的目录**这样 `--out-dir src` 不能毁灭 源代码.

## 捐款

欢迎提出问题和拉动要求——见 [捐款额](https://github.com/ankurhalder/codebase-snapshot/blob/main/CONTRIBUTING.md) 编辑 [行为守则](https://github.com/ankurhalder/codebase-snapshot/blob/main/CODE_OF_CONDUCT.md)安全报告: [警卫](https://npmcn.com/package/%40ankurhalder/codebase-snapshot/SECURITY.md)。 。 。 .

## 许可证

[麻省理工学院](https://npmcn.com/package/%40ankurhalder/codebase-snapshot/LICENSE) 安库尔·哈尔德

## 常见问题

### @ankurhalder/codebase-snapshot 是什么？

生产级 LLM 密码库快照生成器、审计员和 AST 分配器注意：该包已被作者标记为弃用——Renamed to codebase-snapshot, which is the supported package\. Run: npx codebase-snapshot@latest setup

### 如何安装 @ankurhalder/codebase-snapshot？

在项目目录运行 npm install @ankurhalder/codebase-snapshot，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 snap、codebase-snapshot，可以用 npx snap 直接运行。

### @ankurhalder/codebase-snapshot 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @ankurhalder/codebase-snapshot 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @ankurhalder/codebase-snapshot 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @ankurhalder/codebase-snapshot 可以商用吗？

@ankurhalder/codebase-snapshot 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @ankurhalder/codebase-snapshot 的下载量有多少？

根据 npm 官方下载统计，@ankurhalder/codebase-snapshot 在 2026/10/07 – 2026/11/05 这 30 天内被下载 3,666 次，日均约 122 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @ankurhalder/codebase-snapshot 还在维护吗？

最新版本 4\.4\.1 发布于 2026/11/05（3 天前）；至今共发布 19 个版本，其中过去 12 个月发布了 19 个；首次发布于 2026/11/03。作者已将其标记为弃用，新项目建议寻找替代方案。