bundlebox

bundlebox

为 AI 编码 Agent 打造的零 Token 软件工厂。
扫描、打包、路由并运行 Claude Code、Codex、Gemini CLI、Cursor、Copilot、OpenCode、Aider 和任何自定义 Agent 的工作，并衡量每次会话使用和节省的 Token。

AI 编码 Agent 按其读取的内容计费，而它读取的大部分内容是背景信息，而非判断：符号位于何处、两个表是否一致、哪个命令能验证更改、与上周相比有哪些变化。bundlebox 会在 Agent 打开答案之前，先通过解析、计数、路径检查或差异比较回答所有这类问题；然后将答案打包成适合 Agent 上下文窗口的简报，以经过测量的最精简标志组合启动 Agent，并在之后衡量会话使用和节省了多少内容。它本身从不调用模型。

bb genesis   ->  a world     a doc becomes surfaces, rules and capabilities  0 tokens
bb scan      ->  findings    what is wrong, with evidence                    0 tokens
bb fix       ->  patches     local actuators close what they can             0 tokens
bb cookbook  ->  a board     what the RUNNING system does, run by the kernel 0 tokens
bb simulate  ->  limits      what it does at a hundred callers               0 tokens
bb compile   ->  units       what to do about the rest, packed to one window
bb pinpoint  ->  a brief     where the work is, quoted and budgeted, before a model opens
bb arc       ->  an index    every declaration in one file, read in microseconds  0 tokens
bb route     ->  lanes       who does it, where, in what wave
bb run       ->  sessions    the only verb that spends
bb finish    ->  a ledger    what proves this done, declared first and run after   0 tokens
bb git       ->  PRs         commit, push, draft PR, review, gated merge     0 tokens
bb runbook   ->  the system  is it up, is it ANSWERING, what broke since    0 tokens
bb recom     ->  an answer   what was already driven, and whether it holds   0 tokens
bb recom gate->  a decision  and therefore whether to drive at all           0 tokens
bb dotty     ->  a screen    what it showed, as rows a session can diff      0 tokens
bb sieve     ->  a window    a tool result shrunk before it is billed twice    0 tokens
bb uptake    ->  a verdict   of everything wired in, what sessions reached for 0 tokens
bb monitor   ->  the window  what the 5-hour block has left, and the guard   0 tokens
bb session   ->  the bill    what a session used and saved, measured         0 tokens
bb lathe     ->  automation  what this box did by hand more than twice, as scripts 0 tokens
bb env       ->  a checklist what a complete .bundlebox holds, and whether this has 0 tokens

在参考工作区上的测量结果（使用 bb session、bb tokens profile --probe、bb buckmaster episodes 重新生成）：

	之前	之后
每个启动会话的初始上下文窗口，开始工作前	44.3k tokens	29.2k tokens（−34%）
规划相同发现结果	5 个会话，预计 1.3M	2 个会话，351k（−74%）
一次流水线运行（bb pipeline run intake）	226 次 Agent 轮次	133 秒，0 个模型 Token

安装

npm i -g bundlebox
# or
curl -fsSL https://raw.githubusercontent.com/blackswanalpha/bundlebox/main/scripts/install.sh | sh

需要 Node ≥ 20 和 git。支持 Linux、macOS 和 Windows：CI 会在这三个系统上使用 Node 20、22 和 24 运行完整测试套件。Windows 上仍有两个已知问题——通过管道传递的验收门会报告最后一条命令的退出代码，而不是首次失败的退出代码，因为 cmd.exe 没有 set -o pipefail（不通过管道传递的验收门结果准确）；bb session 可能无法找到转录记录，因为尚未验证 Claude Code 在该系统上为其项目目录使用的名称。三个可选的 Rust 和 Python 组件可提升速度和智能程度；没有它们时，所有功能也都能平稳降级：

• Rust 内核（bbk）：目录树遍历、指纹、Token 估算、重复窗口、符号索引、带真实超时的验收门、工作树。 bb kernel install 会获取发布版二进制文件；bb kernel build 会使用 cargo 编译。 没有它时，会运行 JS 实现；自检会确保两者的答案完全一致。
• Rust 索引编译器（arc）：将派生的符号表编译成一个二进制索引，供读取和搜索防护直接查询；在冷启动钩子进程中，速度比扫描符号表快 13 倍。运行 bb arc build 编译；符号表变动时，bb snapgen build 会重新编译。如果索引缺失、被截断或内容并非索引，所有读取器都会回退到扫描符号表，因为“没有索引”和“没有声明任何内容”代表不同的答案。
• Python 专家系统（bundlebox_expert，仅使用标准库）：包含可解释推导、置信度收缩、转录信号、进程模型和记忆的规则引擎。bb buckmaster 需要 python3 ≥ 3.9；零 Token 路径上的任何功能都不需要 Python。

没有 npm 依赖。03:00 运行的 cron 工作进程会执行磁盘上已有的内容，否则便不运行。

从这里开始

cd your-repo
bb init            # detect languages, agents and gates; write .bundlebox/config.json
bb doctor          # what this box can run, which runtime serves each op
bb wire --apply    # hooks, skills, instruction blocks and MCP entries for every agent
bb env up --apply  # build everything a session reads, so nothing is derived by searching
bb scan            # the detectors. Seconds, 0 tokens
bb findings        # what the store holds; bb explain <id> for one
bb pinpoint gaps   # every open finding as a located, quoted, budgeted brief
bb pinpoint next   # make one of them the ACTIVE brief the guards answer from
bb compile         # findings -> units, each packed to one window (dry run)
bb route           # units -> lanes (dry run)
bb run             # writes the exact prompt and command per lane, spawns nothing
bb run --apply     # spawns the sessions
bb finish check    # run the acceptance ledger; unproven never reads as green
bb session         # what the last session used and saved

也可以从文档入手，而不是从代码入手：

bb genesis docs/PRD.md --base http://127.0.0.1:4400   # surfaces, rules, capabilities, a seeded corpus
bb genesis plan                                       # what nothing covers, ranked and tiered
bb genesis pack                                       # one small brief per surface
bb genesis send calendar --run --spend                # the only step that costs anything
bb cookbook check && bb cookbook run                  # the kernel executes what came back
bb mainboard gaps                                     # the first stage that does not hold, and its fix
bb console                                            # one page: the pipeline, the window, every session

所有动词命令在使用 --apply 之前都只是试运行。只有 run 和 bridge send 会产生费用。

接入 Agent

bb wire --apply 会为检测到的每个 Agent 安装四项内容：标记之间的指令块、Agent 支持时安装的钩子、Agent 会加载的技能，以及 MCP 服务条目。bb unwire 只会移除它自己的指令块、条目、钩子行和技能。

Agent	指令	钩子	技能	MCP
Claude Code	CLAUDE.md	UserPromptSubmit（构建简报）、PreToolUse Read/Grep/Bash（提供简报内容）、SessionStart（表格索引）、PostToolUse（筛选器，在 sieve.enabled 启用前关闭）、PreCompact、SessionEnd（账单）	.claude/skills	.mcp.json
Codex CLI	AGENTS.md	—	.codex/skills	.codex/config.toml
Gemini CLI	GEMINI.md	—	—	.gemini/settings.json
Cursor	.cursor/rules/bundlebox.mdc	—	—	.cursor/mcp.json
GitHub Copilot	.github/copilot-instructions.md	—	—	.vscode/mcp.json
OpenCode	AGENTS.md	—	—	opencode.json
Cline / Roo	.clinerules/bundlebox.md	—	—	—
Windsurf	.windsurf/rules/bundlebox.md	—	—	—
Aider	.aider.conf.yml 会读取 AGENTS.md	—	—	—
任意命令	lanes.custom_command，包含 {prompt_file} {cwd} {model}	—	—	—

我们提供了两项技能，在触发前不会产生任何开销，而指令块不具备这个特性：它会出现在每个系统提示词中，无论会话是否与之相关，都会计费。bb-finish 是由可运行的关卡支持的完成规范；antislop 是一套文风规则，说明每条规则的代价以及应该如何改写。

bb mcp 会通过 stdio 以 JSON-RPC 2.0 提供 bb_pinpoint、bb_context、bb_snapgen、bb_findings、bb_scan、bb_oversight_brief、bb_explain、bb_tokens_estimate 和 bb_session，且无需依赖项。

bb wire --apply 会为上表中的每个 Agent 写入条目。对于它不管理的 Agent：

{ "mcpServers": { "bundlebox": { "command": "npx", "args": ["-y", "bundlebox", "mcp"] } } }

Claude Code 可以将其作为单行内容使用，也可以作为插件使用；插件会一并包含两项技能和钩子：

claude mcp add bundlebox -- npx -y bundlebox mcp
# or
/plugin marketplace add blackswanalpha/bundlebox
/plugin install bundlebox@bundlebox

完整指南涵盖了本表未列出的 Agent、如何接入 bundlebox 不认识的 Agent，以及如何将 Agent 作为通道驱动： docs/agents.md。随后，bb uptake 会报告会话使用了哪些已安装的功能。

建议失效；解决办法是强制执行

bb uptake 测出了这一差距。在此工作区的 15 个会话中，MCP 工具触发次数为 0；在打开了五个或更多不同文件的 13 个会话中，pinpoint 触发了 3 次；在运行搜索的 15 个会话中，参考表被使用了 5 次。这 13 个会话各自打开了 30 到 598 个文件。向 Agent 提供的一切都只是建议，而建议大约有四分之三的时间会输给模型自身的习惯。

因此，接入方式改变了。

直接运行，不要只作建议。 UserPromptSubmit 会在任务型提示词上自行构建简报——耗时 0.47 秒，远低于 15 秒的预算，因为 pinpoint 读取的每项输入都是已存储的产物，它不会计算这些输入。进入上下文窗口的是地图，约 300 个 token。

提供它找到的内容。 PreToolUse 会拒绝读取简报已引用区域的请求，并在拒绝原因中返回引用内容；拒绝完全重复的读取；拒绝符号表已能回答的声明搜索请求，并返回相应行；对于因预算限制而被截掉的文件，则会在打开前询问。范围内的文件不会被完全禁止读取——Claude Code 需要先成功读取一次才能编辑，因此拒绝信息会指出范围，并允许这次读取。Grep 是声明的工具，而实测记录中的搜索发生在 Bash 中，所以两者都会受到限制。

根据具体程度和路径排序。 强制执行简报会提高错误定位的代价。在候选集合上使用逆文档频率，可避免树中到处出现的名称因精确匹配而胜过罕见名称的宽松匹配；目录名 wire 现在也会作为判断文件用途的依据。明确指定的文件会优先固定，而不是参与评分。

动词

动词	回答的问题	成本
scan, findings, explain, fix	十六种通用检测器，提供证据和预期价值分流；本地执行器会先写入补丁，再处理文件	0
compile, route, context, gates	打包到窗口中的单元，附带引用区域和提升的证据；带冲突的通道、亲和关系和波次；此范围是否合适	0
run	在选定的 Agent 上运行通道；环境变量允许列表；硬超时；以验收结果作为判定；unproven 会阻止 --pr	消耗资源
git	提交、推送、草拟 PR、评审 → findings、受门控的合并，以及防护机制	0
tokens, session	估算、校准、探测开销、价格；每个会话的用量和节省量，标记为 MEASURED / ESTIMATE	0（探测会消耗一个轮次）
snapgen, oversight	带指纹的表格；巨型文件、臃肿、重复、氛围编码标记，以及各自生成的准则	0
pinpoint	一个问题 → 一份包含定位、引用和预算的简报。gaps 会将每条未解决的 finding、每项 oversight 测量结果，以及每项失败或缺少证据的声明标准都转化为简报；next 会将其中一份设为会话的 ACTIVE 简报，PreToolUse 防护机制会依据这份记录作出响应。unproven 永远不会被归并为 failed；失败标准的范围是未通过该标准的 finding 所涉及的文件，而不是整个区域——交接一个目录不等于完成定位	0
arc	声明索引。每次工具调用时，防护机制都会问一个问题——这个名称是否已声明，以及声明在哪里——此前通过逐行对 20,000 行 Markdown 使用正则表达式来回答。arc 会将这些表编译为一个二进制文件：两个排序后的 ID 数组，一个按名称排序，另一个按反转后的名称排序，因此精确匹配、前缀匹配和后缀匹配都只需进行一次二分查找。92.4KB 中包含 2,322 条声明。使用表格时每次调用耗时 1.80ms，使用索引时冷启动耗时 0.14ms，热启动耗时 0.073ms	0
finish	验收台账，根据活动简报和检测到的门禁生成，在工作开始前写入，并在工作完成后运行。CHECK: 行是 shell 代码，因此 status 和 lint 都不会执行它，只有 approve 这个动词可以越过这道边界——它会绑定命令、预期结果、解析后的工作目录、shell、超时和继承的 PATH；其中任一项变动时都会再次询问。lint 会在编写时捕获无法失败的判定条件；reverify 会重新运行未通过的工作的可运行门禁	0
lathe	将此工作区中手动完成超过两次的操作生成为脚本、片段、样板和补全。基于磁盘上已有产物的四种计数模型——会话运行过的动词和命令中的封闭连续序列、专家的逻辑结果模型、维护者的衰减记忆，以及编译索引上的前缀熵。每一行都会注明其依据；不会仅凭一次出现就提出建议	0
env	完整的 .bundlebox 应包含什么，以及当前这个是否齐全。每一行都是某个会话原本需要通过搜索整个代码树来生成的产物，而且每一行都由不会消耗资金的动词生成，因此缺少一行就意味着有人要为此付出一个轮次。bb env up --apply 会运行引导设备	0
genesis	将文档或提示词转化为世界模型、带种子的语料库，以及填充语料库的简报；覆盖情况通过集合差计算	0
cookbook, simulate	在运行中的系统上模拟某个角色的一周，由内核执行；以相对于基线的预算，测试并发量逐步增加时的同一请求	0
mainboard, failsafe	一个台账的六种视图，以及哪个流水线阶段未能正常运作；正在失败的内容、原因和操作	0
runbook	声明的服务和组；如果某组的笼位总量超过可用内存，up 会拒绝启动；--wait 会在服务作出响应时返回；将 40,000 行日志归纳为二十种特征，以及此工作区已付出代价才学到的故障，并为其标注名称	0
recom	这项自动化是否已经运行，以及结果是否仍然成立；记录会声明其依据的事实，并在每次读取时重新探测——结果为 fresh、指出发生变动内容的 stale，或 unknown。bb recom gate <id> -- <cmd> 会将该判定直接接入决策，因此只有当原有结论不再成立时才会执行高成本操作	0
dotty	屏幕显示的内容，通过 Chrome DevTools Protocol 实现，无需依赖：供人查看的 PNG 和供会话使用的无障碍摘要、命令前后的画面，以及对空白画面给出的 BLANK 判定	0
slop	每份简报、提交消息和 PR 正文在为通道计费前都会经过的文风规则集；以及 antislop 技能，它阐明了同样的十五条规则、每条规则的代价，以及替代写法	0
sieve	输入轴：工具结果在进入窗口前会经过清理、去重或省略，因此后续每个轮次都不必重新发送 4,000 行日志。Read/Edit/Write 绝不会被触及，错误行会保留在裁剪结果中间部分之外，被丢弃的中间内容会写入磁盘，以便通过 grep 恢复。接入前，bb sieve replay 会根据此工作区自己的对话记录测量效果	0
uptake	已安装不等于已使用：记录会话实际调用了哪些已接入界面——MCP 工具、bb 本身、pinpoint、参考表——并对照各界面适用的场景，列出每次未能调用的情况以及会话改用了什么。若某界面通过系统提示词提供，则报告为不可观测，绝不记为 0%	0
frames	基于工厂自身数据构建的数据框架，评测以 JSON 文件呈现，供人讨论	0
auditor	在工作开始前声明门槛——范围、标准、治理、保证，均根据代码树自身的信号推导——然后由 gate 在工作完成后检查，其中 unproven 绝不会被视为通过。摄入按日期划分的区域评审，将其作为 findings 并检查偏移	0
monitor, console	五小时工作块、消耗速率，以及每项支出前的防护机制；供工作区使用的只读页面	0
pipeline, buckmaster, bridge, scripts	带门禁和指纹跳过机制的齿轮；情节、信号、规则、模型、记忆、结果；通往 Agent 的唯一打包入口；带标签的脚本	0（bridge 使用 --run --spend 时会消耗资源）
snapgen skeleton, blast, callers	文件中不含函数体的声明（在此代码树上，阅读量减少 13 倍）；差异可能通过导入边影响到什么，以及阅读它的成本；哪些文件导入某个符号，与哪些文件仅仅提及它分开报告	0
bench swebench	在公开的 SWE-bench Verified 实例上测试同样的两条分支：打包后的窗口是否包含维护者自己补丁触及的文件，以及成本是多少。衡量定位和上下文，而非解决率	0
wire, mcp, hook	安装到 Agent 中；通过 MCP 提供服务；钩子处理器	0
init, doctor, selftest, update, kernel, cron	设置；此设备能运行什么；静默失败检查；更新器；内核；无人值守的工作进程	0

预算模型

projected = overhead + brief + payload × churn + reserve

开销通过探测得出，而不是凭空假定。载荷是定位到的区域，加上符号被点名时扩大的余量，而不是整个文件。变化量是人人都会忘记的一项，测得约为 2.4。预留空间按单元类型计算。结论为 FITS、TIGHT、SPLIT 或 HEAVY；拆分时会遵循目录的局部性原则。五个杠杆按测量顺序作用于这些项：精简标志栈、限定区域而非文件、只说一次、缓存稳定的前缀，以及可选的本地压缩代理（在线路上使用，并单独报告一行）。参见 EXPLANATION.md。

实测值与估算值

每份报告中都会出现两类数字，且绝不会相加：used 和 cache-saved 根据对话记录实测；automation-saved 是估算值，以范围形式显示。没有价格的大模型只报告 token 数，不报告成本。无法检查的动词会标记为 unknown。没有验收记录的单元会标记为 unproven，而不是通过。

还有第三个数字，它在两端都经过实测。bb bench 会将同一任务运行两次——一次在前面加上工厂，一次不加——并报告差值：

bb bench init                 # a suite from the open findings that name a file
bb bench run                  # both arms, per task, with the losses printed
bb bench show --json

BARE 会在代码树中搜索任务相关词语，读取搜索输出，并打开排名靠前的各个文件中首个匹配项附近的一个范围；这就是在没有安装任何工具的机器上，实际会话的操作方式。PACKED 则是针对同一任务的单个 bb pinpoint 提示词。两种方式都由同一个估算器统计磁盘上的文本，因此都不会调用大模型，并且在同一代码树上再次运行会得到相同的数字。若某个任务使用 PACKED 的成本高于 BARE，它也会列在表中，而不会被省略。

每份 bb pinpoint 简报还会多一个章节，而且最值得先读：这份简报无法确定的内容。 未检测到门禁、符号表中没有匹配项、未定位到区域、文件中没有证据、为适应范围限制而不得不删减——这些情况都会连同原因一并说明，而不会靠猜测补齐，并会进行评分，以便比较两份简报。提问需要一轮；错误的假设则要付出一次评审的代价。

控制台

bb console 会在 127.0.0.1:7788 为工作区提供一个只读页面；bb console build 则会将同一页面写入单个文件，并将状态嵌入其中。它绑定到环回地址，没有写入路由，页面上的任何内容都不会调用大模型。

它采用推送而非轮询。存储内容是文件，因此文件系统本身就知道何时发生变化：/api/stream 会监视文件系统，每次变化时重新计算一次状态，无论打开了多少个标签页，然后将状态发送出去。10s 定时器两头都不合适——一次运行完成后，九秒内都看不到更新；而空闲工作区则会在每个打开的标签页中每分钟重新计算全部内容六次。页眉始终会显示连接所处的状态（live、polling、reconnecting、static），因为无法告诉你服务器连接已断开的仪表板，比明确显示离线的仪表板更糟：过时的数字看起来仍然像数字。

route	它回答的问题
GET /	页面：工厂节省了什么、窗口、流水线以及每个会话
GET /health	{ok, service, version} — 唯一一个无需读取存储内容即可响应的路由
GET /api/state	页面渲染的所有内容，以 JSON 格式返回
GET /api/bench	上次 bb bench 的运行结果：每项任务的 bare、packed 和 saved
GET /api/stream	服务器发送的事件：状态会在存储内容发生变化时推送

架构

bin/bb.js            the entrypoint
src/                 Node, ESM, zero dependencies — every verb, the adapters, the store, the console
skills/              the skills bb wire installs: bb-finish, antislop
kernel/              Rust — bbk: walk, fingerprint, estimate, dupes, symbols, anchor, gate, worktree,
                     and the scenario runner, the load simulator and the health probe
arc/                 Rust — the declaration index compiler. src/arc/read.js is the in-process reader,
                     which is where the speed-up lands; the binary is the reference implementation
expert/              Python (stdlib) — rule engine, triage, confidence, signals, rules, graph, model, memory,
                     the world derivation, coverage planning, scenario selection and board verdicts
.bundlebox/          per-repo: config.json, cookbook/ (corpora), genesis/ (world models),
                     var/ (store, boards, simulations, calibration), out/ (tables, briefs, packs, the page)

内核在线程上运行语料，每个工作线程使用一个连接，并共享一个节流器；一个需要两分钟、共 130 步的语料，在真实限流器下运行时长为两分钟，而在本地镜像上运行不到一秒。它只使用 http，因为 TLS 是它必须在不依赖任何外部组件的情况下构建的依赖项——当基础地址为 https、内核缺失，或语料使用超出内核文档所述子集的模式时，会运行 JavaScript 引擎；状态面板会注明运行的是哪个引擎以及原因。test/scenario.test.js 确保两者给出相同答案。

三个运行时通过测试保持一致：test/kernel.test.js 和 test/expert.test.js 确保内核和专家系统与 JS 的答案一致。对于只有一个运行时支持的事实，只实现一次；两个运行时都支持的内容则保持一致。

配置

一个文件 .bundlebox/config.json，只保存你修改过的键。所有默认值及其原因都记录在 src/core/config.js 中。测量值保存在 .bundlebox/var/calibration.json，并通过读取后合并的方式写入。

{
  "lanes": { "agent": "claude", "max_parallel": 4, "model": "sonnet", "daily_budget_usd": 20 },
  "budget": { "max_tokens": 160000, "churn_factor": 2.4, "anchor_widen": 0.45 },
  "kernel": { "gates": { ".": { "quick": "npm test", "full": "npm run lint && npm test" } } },
  "detectors": { "promote_at": "medium" }
}

文档

• docs/agents.md：如何将 bundlebox 集成到每个 Agent 中，以及如何通过它们运行工作
• docs/index.html：参考网站
• EXPLANATION.md：设计论述、流程，以及相较于原始版本的改动
• whitepaper/bundlebox-whitepaper.md
• docs/review-of-the-original.md：参考实现中发现的缺陷
• docs/prices.md：价格表来源说明
• docs/prior-art.md：阅读过的七个项目、借鉴之处及未采用的内容
• CHANGELOG.md 和 changelogs/
• CONVENTIONS.md：代码组织方式，供贡献者参考

发布

在 main 上创建 vX.Y.Z 标签后，会为五个目标构建内核，发布到 npm 并附带来源证明，同时创建包含二进制文件和变更日志的 GitHub 发布版本。 bb update 每天至多检查一次注册表；bb update --apply 会执行安装。

许可证

MIT。src/finish/vendor/ 来自 Leonxlnx/unlazy 2.1.0（MIT，提交 1667149），仅更名，未作其他修改； src/finish/vendor/PROVENANCE.md 记录了每处更名及未作其他改动的原因。bundlebox 最初是一个用标准库 Python 编写、接入单个工作区的工厂；这个软件包是它经过重建和修正后的可移植核心。可选的 wire 集成通过进程边界与 headroom 通信，绝不导入它。