caveman subagent-tax 深度解析本地测量编码 harness 首请求前缀税的方法论与实现【免费下载链接】caveman why use many token when few token do trick — Claude Code skill that cuts 65% of tokens by talking like caveman项目地址: https://gitcode.com/GitHub_Trending/caveman1/caveman本文基于 caveman 仓库中的 METHOD.md系统讲解packages/subagent-tax这个测量工具如何工作它用本地 HTTP sink 冒充 LLM 服务端点让每个已安装的编码 harnessClaude Code、Codex、Gemini CLI、OpenCode、pi、cursor-agent向本地回环端口发出一次真实的首次 agent-turn 请求捕获并解析其中的前缀——系统提示词加全部工具 schema——从而量化每次子代理subagent调用都要重新付出的上下文代价。读完后你将理解其四阶段测量管线、est/exact两级 token 记账规则、variant 标注体系、写时脱敏机制以及每个已知局限背后的协议级原因。测量对象首请求前缀以及 basis: inferred在展开机制之前必须确立 METHOD.md 开篇就写死的边界声明Basis 永远是inferred推断。该工具捕获的唯一一件事是每个已安装 harness 发出的第一个 agent-turn 请求的大小——即系统提示词加工具 schema 组成的前缀。这个前缀会在该 harness 每次调用包括它派生的每个 subagent 的每次调用中随请求一起重新发送。它不是任何供应商计费用量、花费或节省数字。词表纪律工具刻意不用verified一词——在 caveman 仓库中它是节省记账savings-accounting的保留术语已经核对过的配方与约定一律称为confirmed。这一词表约定在 lib/harnesses.mjs 的注释中被再次强调。subagent tax这个名称由此而来agent 每派生一个子代理harness 的完整前缀就原封不动重发一遍前缀越大、工具越多这个税越重。测量管线四阶段全解析阶段 1本地 sink 冒充四种线协议核心组件是 lib/sink.mjs一个绑定在回环端口server.listen(port, 127.0.0.1, ...)见 sink.mjs#L372-L377上的本地 HTTP 服务器。它冒充供应商端点的程度由 classifyRequest 的路径形状分类决定覆盖四种线协议、JSON 与 SSE 两种形态协议 kind匹配路径anthropic-messages/messagesopenai-responses/responsesopenai-chat/chat/completionsgemini-generatecontent:generateContent/:streamGenerateContentanthropic-count-tokens/count_tokens分类顺序有讲究count_tokens必须排在messages之前判断。对每个识别出的协议buildResponse 返回一个最小但合法的 DONE 补全stop_reason: end_turn/finish_reason: stop/finishReason: STOP并带 1 token 的假 usage使 harness 认为回合已结束而不会重试。流式请求由wantsStream判定body 的stream: true、:streamGenerateContent路径、altsse或Accept: text/event-streamSSE 事件序列完整模拟例如 OpenAI Responses 的response.created到response.completed九段事件流。sink 还对GET /models返回伪造模型列表满足 harness 启动时的模型目录探测。每个带 body 的请求都会被捕获落盘记录seq、时间戳、方法、脱敏后的 URL 与 header、body_bytes原始长度与脱敏后的 body文件名形如001-anthropic-messages.json。sink 也可以独立运行node sink.mjs --port N --capture DIR --verbosestdout 输出机器可解析的SINK_READY/CAPTURE行。阶段 2一次性启动与代理中和每个 harness 由 lib/harnesses.mjs 注册表中的配方recipe以一次性方式启动LLM 流量被重定向到 sink。统一提示词是PROMPT Reply with exactly: DONEharnesses.mjs#L23。一个关键安全细节如果用户环境配置了 HTTP 代理捕获到的前缀会被代理送离本机——这是工具承诺绝不允许发生的事。因此 run.mjs#L200-L205 在子进程环境中把HTTP_PROXY/HTTPS_PROXY/ALL_PROXY大小写两套全部置空并把NO_PROXY/no_proxy设为127.0.0.1,localhost,::1确保回环流量不经过任何继承的代理。所有捕获在写入时即被脱敏见后文 Repro pack 一节。阶段 3进程树停杀——以捕获为准不以退出为准METHOD.md 的表述是Measurement succeeds on capture; the harness completing its turn is not required, and a harness that never exits is still measured. 实现上POSIX 端以detached选项让子进程独立成进程组process-tree.mjs#L66-L71停树时向-pid发SIGTERM1.5 秒宽限后升级SIGKILLstopTreeWindows 端用taskkill /pid pid /t /fforceKillTree。等待循环以 200ms 轮询一旦看到 LLM 请求 捕获静默满 grace 期或到达 timeout、或 harness 已退出即停树见 run.mjs#L225-L238。信号处理SIGINT/SIGTERM/SIGHUP 与 exit保证 Ctrl-C 不会留下孤儿进程树。阶段 4分析器与 primary 选择规则分析器 lib/analyze.mjs 把捕获拆分为系统提示词字符数system_chars、逐工具 schema 字符数tools数组每项带name与chars、消息开销messages_chars以及——在 MCP 命名约定已被 confirmed 时——MCP 工具与内建工具的拆分。Primary 选择规则是方法论的核心之一实现在 pickPrimary携带最多工具 schema 的捕获为 primary平局取最早seq最小。原因harness 会在真正的 agent turn 之间穿插小型 warmup、标题生成、路由调用其中有些也带一两个工具——若按第一个带工具的请求选会把路由调用的几百字节误当前缀。若没有任何捕获带工具取 body 最大者且该行pick_rule字段会写明largest-body (no capture carried tools)终端输出也会提示。畸形捕获被跳过、绝不致命tools/messages/input字段以非数组形状到达时expectArray 抛错该记录进入skipped_captures并携带错误信息而不是被静默计成 0 个工具——假的 0 工具读数会被误读成真实测量。其他 harness 的测量因此存活。真实机器上的样例输出README.md 记录了一台真实机器2026-08-07的运行结果——你的机器会不同这正是该工具的意义harness status wire tools mcp system schemas body input tokens variant ------------ ------------ ---------------------- ----- --- ------ ------- ---- ------------ ------------------------------- claude ok anthropic-messages 91 63 42k 219k 267k ~43k (est) real config opencode ok openai-responses 10 - 68k 20k 87k ~14k (est) isolated config codex ok openai-responses 11 - 40k 10k 52k ~8.3k (est) minimal home (floor) gemini ok gemini-generatecontent 8 - 30k 8.3k 39k ~6.3k (est) isolated home (api-key mode) pi ok anthropic-messages 4 - 23k 2.8k 26k ~4.1k (est) isolated home (4 default tools) cursor-agent unmeasurable - - - - - - - -README 对该机器 claude 行的解读值得逐字理解267k 字符请求体中 219k 是工具 schema91 个工具中 63 个来自 MCP 服务器/插件——约占 schema 权重的 69%约合每次调用 24k 估算 token而 agent 还没做任何事。单个Workflowschema 就有 20.8k 字符一个 Notion MCP 工具有 17.1k 字符。同时它明确说明这行不是在说claude 是 pi 的 10 倍那一行是某个人装有 63 个 MCP 工具的真实安装而 pi 行是 4 个内建工具的地板值。比较二者量的是插件装载不是 harness 本身。fixtures/example-report.json是同一台机器的脱敏完整报告fixtures/example-report.json保留了文档化形状供与新鲜运行做 diff——例如其中 claude 行tools_count: 91、mcp_tools_count: 63、mcp_tools_chars: 155480、tokens: { tokens: 42665, basis: est, ratio: 6.4 }codex 行的mcp_tools_count为null打印为-。配置处理绝不修改你的配置的准确含义METHOD.md 用一个专门章节界定No recipe modifies the users configuration files. That is not the same as running in isolationclaude 刻意对着真实配置运行因为用户自己的插件和 MCP 服务器正是被测量的税。启动真实二进制于真实环境会拉起那些 MCP 服务器、运行它们的 hooks并在~/.claude/projects留下会话转录。工具在启动任何东西之前打印这段披露——对应 run.mjs#L368-L379 中对touchesRealConfigharness 的 stderr 提示。其他所有 harness 对着隔离的临时 home/config 目录运行。--isolate把 claude 也切到隔离的CLAUDE_CONFIG_DIR。注意 Claude Code 的登录态就存放在该目录中因此隔离运行通常以Not logged in退出、报告无捕获——harness 自己的首行输出会被作为原因harness_said字段呈现。各 harness 配方的具体手法见 harnesses.mjs#L27-L186harness重定向方式关键细节claudeANTHROPIC_BASE_URL指向 sink 占位ANTHROPIC_API_KEY额外设CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC1、DISABLE_AUTOUPDATER1压掉非必要流量--isolate时追加CLAUDE_CONFIG_DIRhomeDircodexCODEX_HOME临时目录 最小config.toml定义名为 sink 的 providerwire_api responses真实配置会触发后台 memory-agent 调用与副作用网络 I/O插件 git clone、MCP OAuth 握手零接触公共工具不能默认触发故用最小 home 作为地板gemini隔离HOMEGEMINI_API_KEYapi-key 模式GEMINI_BASE_URL隔离 HOME 保护用户真实~/.gemini的 OAuth 登录-m固定非 gemini-3 模型跳过对纯文本 sink 回复会陷入重试循环的 strict-JSON 预检分类器opencodeOPENCODE_CONFIG_CONTENT内联注入 sink provider 完整 XDG 隔离config/data/cache 三目录用户真实配置可能收窄模型目录导致运行失败已观察到XDG 隔离同时保证auth.json不被查阅pi隔离 home 最小models.json仅 id 的模型条目即可pi 是精简委派基线其默认 4 工具集就是对比点无 env 隔离时 pi 会 fail closed 报 Unknown provider绝不回退到真实 providerVariant 标注行是标注的不是静默混合的每个 harness 的variant字段说明该行测量的是哪种配置表格完整继承自 METHOD.mdharnessvariant原因claudereal config用户实际的税——含插件/MCPallow/disallow-tool 标志本来也不会把 schema 从请求中剥掉codexminimal home (floor)真实配置运行会触发后台 memory-agent 调用与副作用网络 I/O地板值是诚实的零接触默认geminiisolated home (api-key mode)保护用户的 OAuth 登录-m固定非 gemini-3 模型以跳过对 sink 重试循环的 strict-JSON 预检分类器opencodeisolated config用户真实配置可能收窄模型目录并破坏运行XDG 隔离同时保证其 auth.json 不被查阅piisolated home (4 default tools)pi 是精简委派基线其默认工具集即对比点核心纪律地板行floor与真实配置行real config是不同构造。比较它们量的是插件装载不是 harness——表格打印 variant 列就是为了防止有人不小心这么比诚实性honesty区块还会用文字再说一遍。variant字段的赋值逻辑在 run.mjs#L289-L292真实配置时取reg.variant隔离时取reg.isolateVariant。网络承诺零供应商调用两个显式例外测量本身不发起任何供应商 API 调用。METHOD.md 列出两个显式例外--count-tokensopt-in把捕获的 anthropic 协议 body——你的真实系统提示词——POST 到 Anthropic 免费的count_tokens端点把那些行从估算升级为供应商精确值。需要ANTHROPIC_API_KEY没有 key 时警告并保持估算调用失败时标注est (count_tokens failed)而非静默降级。源码中这三条全部兑现run.mjs#L258-L269且 tokens.mjs 的buildCountTokensRequest把捕获的model/system/tools/messages字段原样透传重建请求保证计数对象就是 harness 实际发送的内容端点https://api.anthropic.com/v1/messages/count_tokens是独立免费速率桶。harness 自身的边路流量遥测、更新检查配方能压就压claude 的DISABLE_AUTOUPDATER等codex 配方刻意用最小临时 home因为真实配置会触发插件 git clone 与 MCP OAuth 握手。Token 记账两级台阶绝不混合lib/tokens.mjs 只实现两种口径est估算chars ÷ ratioratio 默认6.4打印到两位有效数字并带~前缀。该校准于 2026-08-07 在一台机器上对照供应商精确的 Claude Code 前缀运行得到实测区间5.9–6.9 chars/token±8% 带宽6.4 取中点tokens.mjs#L10-L12再多位数就是噪声。关键警告该校准源自 Anthropic tokenizer却应用于所有协议——codex/opencodeo200k与 gemini 的行在此之外还叠加一层未量化的跨 tokenizer 误差。跨 harness 的 token 比较只能视为近似字符列chars才是精确的。exact精确对捕获 body 原文调用 Anthropiccount_tokens。仅适用于 Anthropic 协议行其他供应商的 tokenizer 绝不被近似为 exacttokens.mjs#L31-L50。打印格式由 report.mjs#L30-L36 的formatTokens控制est 值四舍五入到两位有效数字~43k (est)exact 值完整打印12,345 (exact)。列可读性与可比性METHOD.md 对表格各列给出可比性规则system/schemas/body是捕获的已清洗请求的JSON 字符数。body是分析后的总量report.json同时保留脱敏前的原始body_bytes二者相差几个字符脱敏替换使 body 轻微变形body_bytes始终记录原始长度。system按协议组装——顶层system/instructions加上messages/input内部的 system/developer 角色条目因为多个 harness 把指令的主体放在那里对应 analyze.mjs 中anthropicParts同时累加body.system与 system 角色消息、openaiResponsesParts同时累加body.instructions与 system 角色 input 项。因此该列的跨 harness 比较是近似的。t1st是到首个被捕获 LLM 请求的墙钟时间包含 harness 启动——它不是延迟基准。mcp列为-未知除非该 harness 的 MCP 命名约定已被 confirmed目前只有 Claude Code 的mcp__server__tool约定CLAUDE_MCP_PATTERN /^mcp__/analyze.mjs#L82。-绝不意味着零。重复测量--repeat N与中位数行单次运行是单点观察。--repeat N让每个 harness 跑 N 次报告行取中位数试次total_chars排序后取中位并附观察到的 min–max 展布——明确声明这是一台机器上 N 次运行的区间不是置信区间、也不是方差声明。所有试次的捕获都保留trial-2/、trial-3/…目录展布可审计。实现见 run.mjs#L315-L328 的summarizeTrials按total_chars排序取medianspread对象含min_chars/max_chars/median_chars/all_chars。表头随之多出一列spread (n)显示min–max (ok/total)。Repro pack--out产物与写时脱敏--out默认./subagent-tax-report/产出的 repro pack 包含report.json完整逐工具拆分、校准、诚实性行、每 harness 的原始捕获、harness 输出日志stdout 与 stderr 合并到harness-output.log因为 harness 常把Not logged in/Model not found打在 stdout、所用临时配置、以及覆盖所有产物的manifest.sha256。两个工程细节拒绝写入非自建的目录claimOutDir 检查目标目录若非空且不含本工具写入的.subagent-tax-report标记文件直接退出码 2 拒绝——防止误清空用户目录。manifest 遍历不跟符号链接report.mjs#L72-L83 用lstatSync而非stat跳过 symlink避免对--out下的链接取哈希或陷入链接环。写时脱敏在 sink.mjs 中定义捕获落盘前执行覆盖四类凭证类 headerauthorization、x-api-key、cookie、x-goog-api-key…与账号/设备/会话标识类 headerx-claude-code-session-id、x-codex-turn-metadata、x-gemini-api-privileged-user-id、x-session-id、thread-id…值替换为redacted:sha256:12——保留 12 位哈希使相等性仍可检查同一会话的多次请求仍可关联携带凭证的 query 参数?key、api_key、apikey、access_token——Gemini 支持?keybody 中任意深度的同类标识字段user_id、device_id、account_uuid、prompt_cache_key、safety_identifier、conversation_id、session_id/sessionId、installation_id按 key 名递归删除替换邮箱地址Claude Code 把账号邮箱嵌在系统提示词里与凭证形状字符串sk-*、ghp_*/gho_*、AKIA*、xox*、AIza*仅用高精度正则替换值保留可比对哈希。仍然敏感body 本身就是你 harness 的真实系统提示词——本地路径、skill 清单、MCP 工具名、任何全局指令文件。发布 repro pack 前必须人工审阅。签名manifest.sha256是哈希链而非签名。METHOD.md 说明发布签名结果走 CaveBench Ed25519 receipt 路径及其治理文档提及治理定义于docs/cavebench/GOVERNANCE.md该文件不在本仓库内founder-keyed且仅在发布时执行report.mjs#L85-L87 的注释也重申hash manifest, not a signature。已知局限协议级原因METHOD.md 的 Known limitations 一节逐条给出了可验证的技术原因cursor-agent 报unmeasurable且不是因为无法重定向隐藏的-e/--endpoint标志确实能把它指向本地服务器2026-08-07 已核查。但到达的内容不带前缀——客户端在双向 Connect/HTTP-2 RPC 上流式传输agent.v1.AgentRunRequestprotobufschema 里只有会话轮次、模型标识符和用户自己的 MCP 工具没有系统提示词字段、没有内建工具 schema且其 bundle 中找不到任何 LLM 供应商主机名。agent 循环跑在 Cursor 的服务器上前缀从不经过本地网络。唯一客户端侧本可测量的切片是用户自己的 MCP 工具 schema。注册表中该条目的unmeasurableReason与此一致harnesses.mjs#L137-L152。opencode 的线协议在此是 OpenAI Responses经其内建 openai provider尽管生态文档常称其为 chat completions使用ai-sdk/openai-compatibleprovider 时它说 chat。分析器两者都处理。首个捕获后即停意味着多请求启动序列codex memory agent、opencode title 调用被捕获但不被穷尽探索它们仍可见于all_captures。harness 检测运行bin --versionrun.mjs#L108-L127仅有 shell alias 或函数的 harness 会报 not installed。Windowsnpm 命令 shim 经PATH/PATHEXT解析然后直接启动其 Node 入口点、不经 shellprocess-tree.mjs#L10-L64 的resolveWindowsCommandparseWindowsNodeShim解析 cmd-shim 中的目标脚本仅接受 ≤256KB 且为 Node 目标的 shim清理用taskkill /t /f原生 Windows CI 覆盖启动与进程树契约。复现与验证METHOD.md 给出的复现命令在packages/subagent-tax目录下node run.mjs # all installed harnesses node run.mjs --list # whats installed recipe status node run.mjs --harness claude,pi --repeat 3 node --test tests/*.test.mjs # harness-free test suite (fake-harness e2e)完整 flag 一览默认值来自 run.mjs#L26-L31 的参数解析--harness a,b,c 选择 harness默认全部已安装 --out DIR repro pack 位置默认 ./subagent-tax-report --timeout N 每 harness 放弃前的秒数默认 90 --grace N 最后一次捕获后的静默秒数再停默认 3 --ratio N 估算用 chars-per-token默认 6.4已校准 --repeat N 每 harness 跑 N 次中位数行 观察 min–max 展布 --isolate 测 harness 地板而非真实配置 --count-tokens anthropic 行升级为供应商精确 token会把捕获 body 发往 api.anthropic.com需 ANTHROPIC_API_KEYopt-in绝不自动 --json 机器可读报告输出到 stdout --list 注册表 检测结果所有带值 flag 都校验参数缺失或非数字值会立即报错而不是挂死NaN deadline或在全部测完后崩溃——这是 parseArgs 注释中明确记录的修复动机。测试套件tests/完全无需真实 harness用 fake-harness 做端到端验证e2e.test.mjs、sink.test.mjs、analyze.test.mjs、report.test.mjs、process-tree.test.mjs、tokens.test.mjs、args.test.mjsfixtures/anthropic-first-request.json 是一份脱敏的真实首请求捕获供分析器测试使用。小结subagent-tax 的方法论可以浓缩为四条纪律测量的是本地捕获的字符数而非账单basis: inferred, always、每个数字都带口径标签est/exact、variant、pick_rule、-表示未知而非零、行与行之间不静默混合variant 列强制标注构造差异、产物可审计raw captures manifest 写时脱敏 拒绝覆盖非自建目录。它回答的问题是你的 harness 每次调用——以及它派生的每个 subagent 的每次调用——到底要重发多大的前缀而答案的形态哪一列精确、哪一列近似、哪一行是地板、哪一行是真实装载在 METHOD.md 与 README.md 中都被逐一写明。【免费下载链接】caveman why use many token when few token do trick — Claude Code skill that cuts 65% of tokens by talking like caveman项目地址: https://gitcode.com/GitHub_Trending/caveman1/caveman创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考