Cminors/contextpack

# ContextPack 在 AI 编程助手开始修改代码之前，为它提供一份简明且聚焦的代码库简报。 [中文](README.zh-CN.md) | **English** | [基准测试](benchmarks/README.md) [](#project-status) [](package.json) [](LICENSE) [](https://github.com/Cminors/contextpack/actions/workflows/ci.yml) ContextPack 是一款用于 JavaScript 和 TypeScript 代码库的本地命令行工具。只需用一句话描述编程任务，它就能找出 AI 编程助手应优先检查的代码、测试、代码库规则及相关文件。随后，它会创建一份 `context.md` 简报，您可以将其提供给 Codex、Cursor、Claude Code 或其他编程代理。 ``` Your task description ↓ ContextPack analyzes the repository locally ↓ .contextpack/tasks//context.md ↓ Give context.md and the original task to your coding assistant ``` ContextPack 不会调用 LLM，不需要 API 密钥，不会上传您的代码库，也不会编辑您的源代码。 ## 它解决什么问题？ 大型代码库可能包含成百上千个文件。编程助手可以自行搜索，但广泛的探索会消耗上下文，并且可能会漏掉测试、导出接口或本地指令（例如 `AGENTS.md`）。 ContextPack 只回答一个具体问题： 它不负责编写实现代码。它负责准备助手在开始工作前应该阅读的代码库简报。 ## 适用人群？ 适合人群： - 使用 Codex、Cursor、Claude Code 或其他 AI 编程助手的人； - 已经拥有 JavaScript 或 TypeScript 代码库的人； - 希望减少在大型代码库中盲目探索的人； - 愿意尝试实验性工具并报告问题的测试者。 暂不适合人群： - 没有代码库、只想要通用聊天机器人的人； - Python、Go、Rust、Java 或其他非 JS/TS 项目； - 期望该工具自动编辑或提交代码的用户； - 需要稳定的商业 SLA 或经过验证的代理成功率提升的团队。 ## 新手快速入门 您不需要理解 ContextPack 的排名算法，但需要打开终端并复制命令。 如果您不知道如何在文件夹中打开终端： - Windows 11：右键点击文件夹中的空白处，选择 **Open in Terminal**。您也可以选中文件资源管理器的地址栏，输入 `powershell`，然后按回车键。 - macOS：打开终端，输入 `cd `（注意末尾带空格），将目标文件夹拖入终端窗口，然后按回车键。 - VS Code / Cursor：打开项目并选择 **Terminal → New Terminal**。 ### 步骤 0：确保您有可供分析的代码库 目标项目至少需要包含一个受支持的源文件： ``` .js .jsx .ts .tsx .mjs .cjs .mts .cts ``` 请从项目根目录（通常包含 `package.json`、`src/` 或 `.git/` 的目录）运行 ContextPack。 ### 步骤 1：安装 Node.js 从 [官方 Node.js 下载页面](https://nodejs.org/en/download) 安装当前的 LTS 版本。ContextPack 需要 Node.js 20 或更高版本；新测试者应使用当前的 LTS 版本。 安装完成后，打开一个新的终端并运行： ``` node --version npm --version ``` 当两个命令都打印出版本号时，即可继续。 基础静态分析不需要 Git，但安装 [Git](https://git-scm.com/downloads/) 可以启用提交历史和协同变更信号。这也会让下载和更新 ContextPack 变得更简单。 ### 步骤 2：获取并安装源码预览版 请暂时不要运行 `npm install -g contextpack`——npm 包尚未发布。 如果已安装 Git，请运行： ``` git clone https://github.com/Cminors/contextpack.git cd contextpack npm ci npm run build npm link ``` 未安装 Git 的操作： 1. 打开 [ContextPack GitHub 页面](https://github.com/Cminors/contextpack)。 2. 选择绿色的 **Code** 按钮，然后选择 **Download ZIP**。 3. 解压该 ZIP 文件。 4. 在解压后的 ContextPack 目录中打开终端。 5. 运行： ``` npm ci npm run build npm link ``` 验证安装： ``` contextpack --version ``` 预期输出： ``` 0.1.0 ``` ### 步骤 3：在您的项目中运行它 首先切换到您想要分析的 JavaScript 或 TypeScript 项目目录。 Windows 示例： ``` cd "C:\Users\your-name\Documents\my-project" contextpack task "fix the missing message after login timeout" ``` macOS / Linux 示例： ``` cd ~/projects/my-project contextpack task "fix the missing message after login timeout" ``` 任务描述可以用英文或中文编写。请描述需要更改的内容以及发生的位置： ``` contextpack task "add SMS verification to the administrator login flow" contextpack task "fix upload progress stopping at 99% for large files" contextpack task "add a created-at filter to the order list" ``` 请避免不包含任何有用上下文的描述： ``` fix it improve the code there is a bug ``` ### 步骤 4：查找生成的文件 命令执行完成后，会打印类似如下的信息： ``` Context pack: C:\path\to\my-project\.contextpack\tasks\fix-login-timeout Selected 8 snippets; estimated 7421/12000 tokens. ``` 输出目录包含： ``` .contextpack/tasks// ├── context.md # This is the file most users need └── manifest.json # Rankings, scores, and diagnostic data ``` 如果您的文件管理器没有显示 `.contextpack`，请在 VS Code、Cursor 或终端中打开该项目。以点开头的目录可能是被隐藏的。 ### 步骤 5：将结果提供给您的编程助手 上传、拖拽或将 `context.md` 粘贴到您的编程助手中，并附上原始任务。 您可以复制以下提示词： ``` The attached context.md was generated by ContextPack from the current repository and task. Read its repository rules, candidate files, snippets, relationships, and risk notes first. Then complete this task: fix the missing message after login timeout. If ContextPack's suggestions conflict with the actual repository, trust the repository. ``` `context.md` 只是辅助证据，而非绝对答案。助手仍需自行检查代码库、运行测试并验证其修改。 ## 最常用命令 ### 生成上下文包 ``` contextpack task ``` 所有选项： ``` contextpack task \ --budget 12000 \ --format both \ --history 500 \ --output ``` | 选项 | 用途 | 默认值 | |---|---|---:| | `--budget <4000..32000>` | 最大预估上下文 token 预算 | `12000` | | `--format markdown\|json\|both` | 输出 Markdown、JSON 或两者皆有 | `both` | | `--history ` | 用于历史信号分析的本地 Git 提交数 | `500` | | `--output ` | 自定义输出目录 | 自动生成 | ### 解释推荐结果 ``` contextpack explain src/auth.ts --task "add GitHub OAuth" contextpack explain loginWithGithub --task "add GitHub OAuth" ``` ### 显示帮助 ``` contextpack --help contextpack task --help contextpack explain --help ``` ## 故障排除 ### 无法识别 `contextpack` / 找不到命令 请返回 ContextPack 源码目录并运行： ``` npm run build npm link ``` 然后关闭并重新打开您的终端。如果全局链接仍然无效，请直接在目标项目目录中运行构建好的 CLI。 Windows： ``` node "C:\path\to\contextpack\dist\cli.js" task "your task" ``` macOS / Linux： ``` node "/path/to/contextpack/dist/cli.js" task "your task" ``` ### 无法识别 `node` 或 `npm` 这表示未安装 Node.js，或者安装后终端未重启。请安装当前的 LTS 版本，关闭所有终端窗口，然后重试。 ### `未找到受支持的 JavaScript 或 TypeScript 源文件` 当前目录不包含受支持的 JS/TS 文件。请确保您已切换到实际的项目根目录，而不是 ContextPack 目录、您的桌面或空文件夹。 ### ContextPack 提示该目录不是 Git 代码库 这不是致命错误。静态分析会在没有 Git 历史信号的情况下继续进行。当您需要完整的排名信号集时，请安装 Git 并使用 Git 代码库。 ### 分析耗时过长 在大型代码库上的首次运行可能会较慢。请减少历史窗口大小： ``` contextpack task "your task" --history 100 ``` 请勿在包含多个无关项目的目录中运行 ContextPack。请先切换到真正的项目根目录。 ### 推荐结果与任务无关 - 使任务描述更具体。 - 包含业务对象、故障症状或功能位置。 - 检查您是否处于正确的分支和正确的代码库根目录下。 - 在 [GitHub Issues](https://github.com/Cminors/contextpack/issues) 中提交该问题，并附上经过脱敏处理的任务描述和 `manifest.json`。在提交前，请务必移除任何您不想公开的内容。 ### ContextPack 会更改我的代码库吗？ 不会。常规的 `task` 和 `explain` 命令只会读取代码库，并在 `.contextpack/` 目录下写入生成的文件。它们不会编辑源文件、创建提交或调用外部 AI 服务。 ## 更新与卸载 如果您是通过 Git 克隆的，请使用以下命令更新源码预览版： ``` cd contextpack git pull npm ci npm run build npm link ``` 如果您下载的是 ZIP，请再次下载并解压最新版本，然后重新运行 `npm ci`、`npm run build` 和 `npm link`。 使用以下命令移除全局链接： ``` npm uninstall -g contextpack ``` 此操作不会移除源码目录或其他项目中已生成的 `.contextpack/` 结果。 ## 它会生成什么？ `context.md` 包含： - 任务和代码库快照； - 排名后的文件和符号； - 解释每个选定文件的理由证据； - import、export、测试以及 Git 协同变更关系； - 适用的 `AGENTS.md`、`CLAUDE.md`、Copilot 和 Cursor 规则； - 现有的测试、类型检查和构建命令； - 因预算限制而被省略的相关文件； - 受 token 预算限制的源代码片段。 `manifest.json` 提供机器可读的候选文件、得分明细、依赖关系、预算、警告和时间数据。它主要用于诊断和集成。 ## 隐私与安全 - 分析在本地运行。 - 不需要 LLM 或 API 密钥。 - 代码库和生成结果不会被上传。 - 排除 `.env`、私钥、凭据、依赖目录和构建输出。 - 匹配常见机密模式的代码片段不会被输出。 - Git 命令使用参数数组，而不是通过字符串拼接调用 shell。 - 历史评估使用隔离的 worktree，不会切换当前工作区。 自动化过滤无法保证识别出每一个敏感值。在将 `context.md` 发送给第三方服务之前，请务必先进行人工审查。 ## 支持范围 目前支持： - JavaScript、JSX、TypeScript、TSX、MJS、CJS、MTS 和 CTS； - npm、pnpm、Yarn 和 Bun 项目元数据； - 单一代码库和常见的 workspace/monorepo 布局； - `tsconfig` 路径别名； - 有界的 TypeScript 符号和依赖关系； - 本地 Git 标题、文件协同变更历史和常见的代理指令文件； - 使用英文和中文编写的任务描述。 暂不支持或尚未验证： - 自动更改代码或自动执行代理； - Python、Go、Rust、Java 和其他语言； - 任意大规模重构、安全审计或完整的 Bug 诊断； - 托管账户、团队协作或内置的 LLM 调用； - 关于 ContextPack 能可靠提升最终编程代理成功率的声明。 ## 基准测试与当前能力 ContextPack 目前有两条评估赛道： 1. 历史回放：检查是否能检索到实际发生变更的文件； 2. SWE-bench Multilingual JS/TS：评估针对真实 issue 的文件级和行级检索能力。 当前主要结果： | 评估项目 | 样本数 | Recall@10 | MRR | 衡量指标 | |---|---:|---:|---:|---| | MCP TypeScript SDK, 标题模式 | 20 | 0.439 | 0.635 | 中型代码库的文件检索 | | MCP TypeScript SDK, 关键词消融 | 20 | 0.341 | 0.402 | 移除答案提示后的检索表现 | | SWE-bench Axios 问题 | 6 | 0.617 | 0.205 | 针对真实 issue 的文件与代码区域冒烟测试 | 感知查询的区域定位将 Axios 的行级召回率从任何预算下的 `0.000` 分别提升至 100、250 和 500 行输出时的 `0.167`、`0.355` 和 `0.411`。在 500 行时有效命中率达到了 `0.667`，但这仍是一个包含六个任务的冒烟测试结果，且区域噪音较高——不足以作为代理普遍成功的证据。 有关方法论、原始结果、局限性和已废弃的实验，请参阅 [基准测试文档](benchmarks/README.md)。 ## 面向维护者的评估命令 普通测试者不需要使用这些命令。 ``` # 历史回放 contextpack eval --commits 20 --budget 12000 --query-mode title contextpack eval --commits 20 --budget 12000 --query-mode keyword-ablated # 准备 pinned 的 SWE-bench JS/TS dataset npm run benchmark:prepare:swebench # 真实 issue/patch 检索评估 contextpack eval-issues --instance axios__axios-4738 contextpack eval-issues --repo axios/axios contextpack eval-issues --line-budgets 100,250,500 ``` 评估数据集和代码库快照会保留在已被忽略的 `.benchmarks/` 缓存目录中。真实 issue 报告会将文件的 Recall/MRR 与实际输出的代码区域分开处理。Gold 标签仅在检索生成预测结果后使用。 ## 报告测试问题 请提交一个 [GitHub Issue](https://github.com/Cminors/contextpack/issues) 并包含以下信息： - 操作系统； - `node --version` 和 `npm --version` 的输出； - 您运行的 ContextPack 命令； - 完整的错误信息； - 代码库的大致大小和结构； - 如果是推荐结果不佳，请提供脱敏后的任务描述和 `manifest.json`。 请勿上传私有源代码、token、`.env` 文件或其他凭据。 ## 项目状态 ContextPack 是一个未发布的实验性源码预览版。核心 CLI、包结构、自动化测试、性能冒烟测试、真实 issue 评估以及首个感知查询的区域定位器已就绪。npm 发布、正式版本发布、零知识安装、完整的 43 任务验证以及广泛可靠的文件内定位功能尚未完成。 当前目标是让一小群测试者能够安全地使用该项目，并报告易于理解的反馈——而不是对其进行广泛推广。 ## 开发说明 ``` npm ci npm run check npm run test:coverage npm run perf:smoke ``` 当前质量标准：68 个测试通过，行覆盖率超过 88%，没有生产依赖漏洞，以及确定性的 360 文件性能冒烟测试。GitHub CI验证 Node.js 20 和 22 版本。 ## 许可证 [MIT](LICENSE)

标签：AI编程助手, JavaScript/TS, MITM代理, RAG, SOC Prime, 上下文检索, 开发工具, 数据可视化, 文档结构分析, 本地工具, 自动化攻击