上下文打包器 gokulgawande/context-forge

🚀 ContextForge（ctxforge）

为 LLM 快速生成可检查、感知 token 的上下文。

💡 为什么选 ContextForge？

做架构评审、重构、调试时，把本地代码库的上下文喂给 Claude 3.5 Sonnet、GPT-4o、DeepSeek 这类 AI 模型很关键。可手动复制粘贴容易出错：

* 💸 看不见 token： 靠猜上下文大小，会撑爆上下文窗口、截断提示词，或者收到意料之外的 API 账单。
* 🚨 泄露凭据： 不小心带上 .env、私钥、云配置，基础设施就可能被攻破。
* 🌀 上下文臃肿： 二进制资源、压缩后的 bundle、lockfile、层层嵌套的子目录，白白吃掉几千个 token。
* 🧱 边界不清： 粘进去的代码没有明确、统一的分隔符，模型容易看糊涂。
* 📜 无法审计： 没有清单，你就很难核实哪些文件被包含、被跳过、被改写过。

ContextForge 用一个确定性的本地优先命令行解决这些问题。 它扫描你的仓库，按目录生效 Git 忽略规则，强制排除敏感文件，在内存里脱敏密钥，按 cl100k_base 计算 token 数，执行大小与 token 预算，按目标 LLM 格式化输出，还能生成结构化 JSON 清单，供后续检查。

⚡ 快速开始

不用全局安装，直接跑：

npx ctxforge .

或者全局安装：

npm install -g ctxforge

常用工作流

1. Copy formatted Claude XML directly to your system clipboard
ctxforge --format xml --copy

2. Preview included files, token counts, and DeepSeek cost estimate
ctxforge --dry-run --model deepseek

3. Save Markdown context with a machine-readable audit manifest
ctxforge -o context.md --manifest manifest.json

4. Enforce a strict output budget of 50,000 tokens (fails safely if exceeded)
ctxforge -o context.md --max-output-tokens 50000

🛡️ 安全策略与内容保护

ContextForge 内置防御性控制，尽量降低意外泄露数据的风险：

1. 强制排除敏感路径

默认排除常见含凭据的路径，即使 .gitignore 里没写也一样。用 --no-gitignore 关掉 .gitignore，绝不会关掉这些安全保护：
* 环境文件： .env、.env.、.env（例如 .env.local、production.env）。
* 密钥与证书： .pem、.key、.p12、.pfx、.pkcs8、.crt、.cer、.der、.ppk、.ovpn。
* SSH 密钥： id_rsa、id_dsa、id_ecdsa、id_ed25519。
* 云服务与认证配置： .aws/credentials、.aws/config、.docker/config.json、.kube/config、.netrc、.npmrc。

2. 尽力而为的内容级密钥脱敏

源码里可识别、高置信度的密钥模式会被自动检测，并在内存中替换为安全的脱敏标记（例如 [REDACTED SECRET: aws-access-key-id]）。
* 检测的模式： 私钥块（-----BEGIN ... PRIVATE KEY-----）、AWS Access Key ID（AKIA...）、GitHub 个人访问令牌 / OAuth 令牌（ghp_...、github_pat_...）、Slack 访问令牌、Google API 密钥、OpenAI 密钥（sk-...）、Anthropic 密钥（sk-ant-...）。
* 非破坏性： 磁盘上的文件绝不修改。脱敏只在内存中进行。
* 局限： 启发式检测只针对已知的凭据格式。它认不出所有自定义、加密或混淆过的 token。分享上下文之前，审计源码仍是开发者的责任。

3. 文件系统安全与符号链接遍历

* 指向仓库根目录之外的符号链接会被忽略（symlink-outside-root）。
* 循环符号链接和路径遍历尝试，会通过规范路径解析（realpathSync）安全拒绝。
* 输出文件和清单目标文件会自动排除在扫描之外，防止递归包含自身。

🌲 目录感知的忽略行为

ContextForge 评估 .gitignore 规则时会感知目录层级，与 Git 的语义一致：
* 目录作用域： 嵌套 .gitignore 文件里定义的规则（例如 packages/app/.gitignore）只作用于它所在的目录子树，不会泄漏到同级目录或父级根目录。
* 父级剪枝： 如果某个祖先目录被忽略模式排除（例如 dist/），它里面的文件无法再被子级的否定规则重新包含。
* 否定支持： 目录作用域内的否定模式（!keep.log）能正确取消忽略那些被更上层父级规则匹配到的文件。
* 非 Git 支持： 无论是否初始化 Git，这些功能在目录中的行为都保持一致。

📦 资源保护与 token 预算

为防止内存耗尽和上下文生成失控：

* 单文件大小限制（--max-file-size <mb>）： 跳过超过指定大小的单个文件（默认：10MB）。
* 输入总量限制（--max-total-size <mb>）： 候选文件的累计大小超过限制时，停止并报错（默认：50MB）。避免超大仓库导致内存溢出崩溃。
* 硬性输出 token 预算（--max-output-tokens <count>）： 硬性边界校验。最终生成的上下文超出 token 预算时：
* 导出模式报错中止（退出码 1）。
* 不写输出文件，同时阻止复制到剪贴板。
* 在 --dry-run 下，明确报告预算通过还是超出。

🛠️ 命令行参考

Usage: ctxforge [options] [path]

Arguments:
path Directory to crawl (default: ".")

Options:
-V, --version Output version number
-o, --output <filename> Save output to a file instead of stdout
-i, --ignore <patterns> Comma-separated glob patterns to ignore (e.g., ".test.ts,docs/")
-f, --format <format> Output format: markdown or xml (default: markdown)
-m, --model <name> Model for cost estimation (gpt-4, gpt-4o, claude-3-5-sonnet, claude-3-haiku, deepseek; default: gpt-4)
-c, --copy Copy generated context directly to system clipboard
--manifest <filename> Write a machine-readable JSON manifest report
--no-gitignore Disable .gitignore parsing (security exclusions remain active)
--dry-run Preview included files, tokens, and cost without generating output
--max-file-size <mb> Maximum individual file size in MB to process (default: 10)
--max-total-size <mb> Maximum aggregate input size in MB across all files (default: 50)
--max-output-tokens <count> Hard upper limit for output context tokens
-h, --help Display help for command

stdout 纯净保证

生成上下文输出到 stdout 时（不带 -o），stdout 里只有原始产物。所有加载动画、诊断信息、token 提示、跳过文件报告都走 stderr，因此 stdout 可以放心用于 shell 重定向：

ctxforge . > context.md

📄 输出格式

1. Markdown 格式（-f markdown，默认）

标准分隔格式，适用于 ChatGPT、GitHub Copilot 和通用大模型：

--- FILE: src/index.ts ---
import { Command } from 'commander';
// code ...
--- END FILE ---

2. Claude XML 格式（-f xml）

按 Anthropic 官方提示词指南 组织结构：
* 里的文件路径会转义，保证 XML 合法。
* <document_content> 里的文件内容安全包进 CDATA 段。内嵌的 ]]> 序列会安全拆分（]]]]>），保证 XML 解析器 100% 还原原始源码，不会提前闭合标签。

<documents>
<document index="1">
src/index.ts
<document_content>

</document_content>
</document>
</documents>

📊 Token 统计与模型定价

Token 计数原理

* 编码： 所有 token 计数都通过 tiktoken 使用 OpenAI 的 cl100k_base BPE 分词器计算。
* 全产物范围： token 计数覆盖整个生成输出，包括所有文件头、分隔符和 XML 框架。
* 原生与代理：
* 对于使用 cl100k_base 的模型（如 gpt-4），token 计数是原生的。
* 对于其他模型（gpt-4o、claude-3-5-sonnet、deepseek），计数标注为参考性代理估算，因为各家专有编码并不相同。

已验证的模型输入定价（截至 2026-10-26）

--dry-run 和命令行报告中的成本估算，反映已公布的标准输入费率：

| 模型 ID | 模型名称 | 服务商 | 费率 / 1M 输入 token | 验证来源 | 分词器性质 |
| gpt-4 | GPT-4 Turbo | OpenAI | $10.00 | openai.com/api/pricing | 原生 cl100k_base |
| gpt-4o | GPT-4o | OpenAI | $2.50 | openai.com/api/pricing | 代理（cl100k_base） |
| claude-3-5-sonnet | Claude 3.5 Sonnet | Anthropic | $3.00 | anthropic.com/pricing | 代理（cl100k_base） |
| claude-3-haiku | Claude 3 Haiku | Anthropic | $0.25 | anthropic.com/pricing | 代理（cl100k_base） |
| deepseek | DeepSeek-V3 | DeepSeek | $0.27 | deepseek.com | 代理（cl100k_base） |

免责声明：成本估算只覆盖上下文输入。真实 API 请求还要计入对话框架、系统提示词、输出 token 生成、提示词缓存折扣，以及服务商的实时调价。无法识别的模型名一律拒绝。

📜 审计清单（--manifest <file>）

指定 --manifest 后，ContextForge 会输出一份结构化 JSON 报告，记录本次运行：

{
"$schema": "https://raw.githubusercontent.com/gokulgawande/context-forge/main/schemas/manifest-v1.json",
"schemaVersion": "1.0.0",
"tool": { "name": "ctxforge", "version": "1.0.0" },
"generation": {
"format": "markdown",
"targetDirectory": ".",
"generatedAt": "2026-10-26T21:00:00.000Z"
},
"tokenAccounting": {
"tokenizer": "cl100k_base",
"isProxy": false,
"totalTokens": 21947,
"label": "21,947 tokens under cl100k_base (exact for GPT-4)"
},
"pricing": {
"available": true,
"modelId": "gpt-4",
"modelName": "GPT-4",
"inputCostPerMillion": 10.0,
"estimatedCost": 0.2195,
"currency": "USD",
"pricingVerifiedDate": "2026-10-26",
"pricingSource": "https://openai.com/api/pricing/",
"disclaimer": "Estimate covers context input only; excludes prompt framing, chat history, output tokens, and caching."
},
"budget": {
"maxFileSizeMb": 10,
"maxTotalSizeMb": 50,
"maxOutputTokens": null,
"budgetSatisfied": true
},
"metrics": {
"candidateFilesScanned": 18,
"includedFilesCount": 16,
"excludedFilesCount": 2,
"aggregateInputBytes": 85123,
"outputBytes": 92450,
"outputTokens": 21947
},
"security": {
"redactionCount": 1,
"redactionsByRule": { "aws-access-key-id": 1 },
"redactedFiles": ["src/config.ts"]
},
"files": [
{
"path": "src/index.ts",
"bytes": 2240,
"tokens": 580,
"sha256": "5a09b369e9a4f4d2f83539fb04bbd6e15904de22a84973347c617b7b13480397"
}
],
"exclusions": {
"countsByReason": { "sensitive-file": 1, "output-file-excluded": 1 },
"items": [{ "path": ".env", "reason": "sensitive-file" }]
},
"artifact": {
"sha256": "f7c3bc1d808e04732adf679965ccc34ca7ae3441eeecd33a68285513d80362b5"
}
}

关于 Schema URL：$schema 的 URL 指向仓库 main 分支上的权威 schema。在人工批准发布之前，本地工作尚未推送，因此一旦推送发布提交，这个 URL 就会在 GitHub 上公开可解析。

隐私保证：清单只记录相对路径、导出内容的真实 SHA-256 摘要，以及脱敏规则计数。清单从不记录原始文件内容、密钥值或环境变量。

⚙️ 配置文件（.ctxforgerc）

把项目设置持久化到仓库根目录的 .ctxforgerc 或 .ctxforge.json。

JSON 语法

{
"ignore": [".test.ts", "docs/*"],
"format": "xml",
"model": "claude-3-5-sonnet",
"maxFileSize": 5,
"maxTotalSize": 25,
"maxOutputTokens": 40000,
"manifest": "manifest.json"
}

优先级

设置按严格的优先级顺序解析：
1. 命令行参数（最高优先级）
2. 配置文件（.ctxforgerc / .ctxforge.json）
3. 内置默认值（最低优先级）

🧪 测试与验证

ContextForge 的测试套件覆盖单元、集成和 E2E 边界，通过率 100%：

Run full unit and E2E test suite
npm test

Build production bundle
npm run build

Verify packaging integrity
npm pack --dry-run

📄 许可证

基于 MIT License 分发。详见 LICENSE。

Engineered for safe, dependable developer context generation.