vishal2612200/agentpack

# AgentPack

你的 agent 起步时一无所知。AgentPack 递给它地图。

为 Codex, Claude Code, Cursor, Windsurf, Copilot, Cline, Kiro, OpenCode, MCP, CI 以及 markdown 工作流提供经过排名的仓库上下文。

本地预检 排名的文件 技能路由 温暖的缓存 测试 + 命令 凭据 无云端索引

你熟悉这种模式。你让一个 agent 修复一个 bug。它对半个仓库执行 `rg`，打开了错误的文件，漏掉了测试，然后又把你原本就有的架构重新发现了一遍。 AgentPack 优先执行仓库定位流程。 ``` agentpack route --task "fix auth token expiry" -> files that probably matter -> skills and rules that fit the task -> tests that probably prove it -> rules, commands, warnings -> compact context before the agent edits ``` AgentPack 不是另一个编程 agent。它是一个你部署在现有 agent 前端的本地上下文引擎。 ## 核心卖点 ``` Without AgentPack: agent explores first, edits later. With AgentPack: agent starts near the right files. ``` 无云端索引。无 embeddings。无用于扫描/排名/打包的模型调用。仅依靠本地仓库分析、排名的上下文，以及记录了包含或跳过了哪些内容的凭据。 它不是仓库转储。它不是第二大脑。它也不是保证你的 agent 绝对正确的承诺。 它是一份预检地图：可能的文件、可能的测试、合适的本地技能或规则、命令、警告，以及一个你的 agent 在修改代码前可以进行查阅的精简包。 首次运行会构建本地摘要和仓库信号。随后的运行会复用该缓存，因此 agent 可以减少重复探索，将更多预算花在实际的更改上。 ## 快速开始 ``` pipx install agentpack-cli agentpack --version ``` 在你的仓库内： ``` agentpack init --yes agentpack route --task "fix auth token expiry" agentpack task set "fix auth token expiry" agentpack pack --task auto ``` 然后将 `.agentpack/context.md` 交给你的 agent，或者让支持 MCP 的 agent 直接调用 AgentPack 工具。 如果不需要安装即可一次性使用： ``` pipx run --spec agentpack-cli agentpack route --task "fix auth token expiry" ``` 对于 JavaScript/TypeScript 项目，提供了 npm 包装器： ``` npx @vishal2612200/agentpack --version npx @vishal2612200/agentpack init --yes npx @vishal2612200/agentpack task set "fix auth token expiry" npx @vishal2612200/agentpack pack --task auto ``` ## 快速演示 首先进行任务路由： ``` agentpack route --task "fix billing webhook retry handling" ``` AgentPack 会返回可能的文件、测试、规则、命令和警告，而不会更改源文件。 当任务指向已知的工作流、框架、语言或仓库约定时，它还会推荐匹配的技能或 agent 规则。 接下来构建上下文包： ``` agentpack task set "fix billing webhook retry handling" agentpack pack --task auto ``` AgentPack 会将本地上下文写入 `.agentpack/` 目录下，其中包括选定的文件、被省略的文件凭据、新鲜度检查以及 token 统计信息。 它会复用已缓存的文件摘要和快照元数据，因此重复打包不会从零开始。 ## AgentPack 为你的 Agent 提供了什么 - 针对当前任务排名的文件 - 针对当前任务的技能和规则路由 - 可能的测试与命令 - 仓库规则与 agent 指令 - 符合预算限制的精简上下文包 - 缓存的摘要，以加快重复定位的速度 - 供审查使用的被省略文件凭据 - 当任务或 git 状态发生变化时的新鲜度警告 - 当选定的上下文遗漏了实际更改的文件时，提供本地基准测试数据 ## 目前的证明 AgentPack 目前的公开基准测试只检查一个狭窄的领域：选定的上下文是否与历史提交中实际更改的文件存在重叠。 当前范围的结果： | 信号 | 结果 | 开发者含义 | |---|---:|---| | 公开提交案例 | 108 | 真实的历史文件选择检查 | | 平均召回率 | 66.0% | AgentPack 是否包含了重要的文件？ | | Token 精确度 | 51.1% | 打包的内容中有多少是有用的，而不是噪音？ | | 打包 p50 | 315 tokens | 典型的精简起始上下文 | | 打包 p95 | 1,137 tokens | 较大但仍然有界的起始上下文 | 来源：[`benchmarks/results/2026-06-14-public.md`](benchmarks/results/2026-06-14-public.md)。基准测试指南：[`docs/benchmarking.md`](docs/benchmarking.md)。 这很有用，但并不神奇。它表明 AgentPack 通常能将有意义的文件放入一个小包中。它并未声称每个 agent 都能完成得更快或写出更好的代码。Agent 成功率的 A/B 基准测试应该报告任务成功率、工具调用次数、token 成本以及首次定位到正确文件的时间。 ## 我们接下来想要证明什么 AgentPack 最终应该展示： - 更少的 agent 文件读取次数 - 更少的工具调用次数 - 更快的首次正确定位文件速度 - 更低的总上下文成本 - 相等或更好的任务成功率 ## 兼容工具 - Codex - Claude Code - Cursor - Windsurf - Antigravity - MCP 工具 - CI 和 PR 审查工作流 - 基于通用 markdown 的 LLM 工作流 详见 [`docs/integrations.md`](docs/integrations.md) 和 [`docs/mcp-context-engine.md`](docs/mcp-context-engine.md)。 ### Agent 和 IDE 插件 AgentPack 可以通过轻量级的插件和 IDE 集成层来使用，从而让 agent 从经过排名的仓库上下文开始运行。Codex 提供了一个打包的插件骨架；Cursor, Windsurf, Copilot, Cline, Kiro, OpenCode, Claude Code, Antigravity 和通用 agent 通过可移植的规则、hooks 和原生集成存根使用相同的本地 CLI/MCP 引擎。 在 Codex 内部： ``` @agentpack-route fix auth token expiry @agentpack-pack fix auth token expiry @agentpack-review ``` 该插件会调用本地的 AgentPack 引擎。它不会上传代码，也不会将 AgentPack 转变为编程 agent。 详见 [`docs/agent-plugins.md`](docs/agent-plugins.md) 和 [`docs/codex-plugin.md`](docs/codex-plugin.md)。 ## AgentPack 的对比分析 | 工具类型 | 它的作用 | AgentPack 的不同之处 | |---|---|---| | 仓库转储工具 | 转储选定或所有文件 | AgentPack 根据任务对文件进行排名 | | 编程 agent | 编辑代码 | AgentPack 在编辑前准备好上下文 | | IDE 搜索 | 按需查找文件 | AgentPack 在 agent 启动前进行预路由 | | 技能/规则 | 改变 agent 行为 | AgentPack 为任务路由匹配的技能或规则 | | 缓存预热工具 | 加速重复扫描 | AgentPack 在上下文工作流中复用摘要和快照 | ## 何时使用 在以下情况使用 AgentPack： - 仓库很大或拆分在多个包中 - monorepo 结构导致文件发现成本很高 - agent 在跨任务时重复进行相同的探索工作 - CI 或 PR 审查需要可复现的上下文 - agent 浪费工具调用去打开无关文件 - 任务经常遗漏测试、配置、生成的规则或仓库约定 - 团队拥有实用的技能/规则，但 agent 无法可靠地选择正确的内容 - 重复的 agent 会话不断重新发现相同的仓库结构 在以下情况不要使用 AgentPack： - 仓库很小 - 问题是一次性的且只读 - 你已经确切知道要编辑哪些文件 - 你需要自主编程，而不是准备上下文 - 原生 IDE 搜索对于任务来说已经足够 ## 工作原理 AgentPack 在本地扫描仓库，构建并复用文件摘要，索引本地技能和规则，结合文件名、git、配置、依赖、摘要和基准测试信号，根据任务对可能的文件进行排名，然后生成精简的上下文包。 它可以通过 CLI、markdown 文件、MCP 工具、hooks、插件和 CI 暴露相同的工作流。 深入了解：[`docs/architecture.md`](docs/architecture.md)、[`docs/how-agentpack-works.md`](docs/how-agentpack-works.md) 和 [`docs/commands.md`](docs/commands.md)。 ## 信任与隐私 - 默认本地优先 - 无云端索引 - 扫描、排名、打包、统计或基准测试过程中无 embeddings 或 API 调用 - 生成的文件存放在 `.agentpack/` 下 - 在你的机器外部共享之前，请先审查打包内容 详情：[`docs/privacy.md`](docs/privacy.md)、[`docs/threat-model.md`](docs/threat-model.md)、[`docs/data-flow.md`](docs/data-flow.md) 和 [`SECURITY.md`](SECURITY.md)。 ## 安装说明 需要 Python 3.10+，并已在 Python 3.10-3.14 上测试。PyPI 包名为 `agentpack-cli`；命令为 `agentpack`。 对于常规安装，请使用 `pipx`，因为许多 macOS/Linux 的 Python 发行版会通过 PEP 668 的 `externally-managed-environment` 错误阻止全局的 `pip install`。 如有需要，请先安装 `pipx`： ``` # macOS brew install pipx # Ubuntu/Debian sudo apt install pipx # Fedora sudo dnf install pipx # Arch sudo pacman -S python-pipx pipx ensurepath ``` ## 文档 - [`docs/index.md`](docs/index.md)：文档主页 - [`docs/architecture.md`](docs/architecture.md)：pipeline、数据流、包布局和渲染预算核算 - [`docs/commands.md`](docs/commands.md)：完整的 CLI 命令参考 - [`docs/configuration.md`](docs/configuration.md)：配置、评分权重、`.agentignore` 和 git 集成 - [`docs/integrations.md`](docs/integrations.md)：agent 设置、MCP 工作流、hooks 和原生集成状态 - [`docs/agent-plugins.md`](docs/agent-plugins.md)：插件和 IDE 分发层 - [`docs/codex-plugin.md`](docs/codex-plugin.md)：轻量级 Codex 插件命令和本地工作流 - [`docs/mcp-context-engine.md`](docs/mcp-context-engine.md)：MCP 工具和上下文工作流 - [`docs/benchmarking.md`](docs/benchmarking.md)：质量标准、发布门槛和公开产物 - [`docs/limitations.md`](docs/limitations.md)：项目范围、已知限制和路线图 ## 状态 Alpha 阶段：`0.3.25`。 已在真实会话中运行、测试并使用。Python 和 JavaScript/TypeScript 拥有最强大的支持。API 在 1.0 版本之前可能会发生变化。 平台支持目标为 macOS、Linux 和带有 Git for Windows 的 Windows PowerShell。目前尚不支持 `cmd.exe` 和纯 Git 设置。 名称说明：PyPI 包名为 `agentpack-cli`，npm 包名为 `@vishal2612200/agentpack`，命令为 `agentpack`。本项目与 AgentPack 数据集论文或其他同名仓库无关。 ## License MIT

标签：AI编程助手, MITM代理, SOC Prime, 上下文工程, 上下文管理, 上下文缓存, 代码检索, 开发工具, 文档结构分析, 逆向工具