Caveman caveman-optimize报告型观察的优化评估工作流——operator 决策与 paired eval 证据驱动【免费下载链接】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本文基于 skills/caveman-optimize/SKILL.md 深入讲解 Caveman 项目中caveman-optimize技能的完整工作流如何读取report_only_observations观察项、如何强制 operator 显式选择、如何设计 paired eval配对评估并执行最小候选改动 双侧基线验证。读完后你将掌握一套证据优先、拒绝伪造节省金额的 LLM 成本优化评估方法论并理解其在 Caveman 源码中report-only 机会合约、退役 id 围栏、CLI 命令与技能测试的完整实现边界。1. 技能定位观察是诊断输入不是行动指令caveman-optimize是 Caveman 的agent-native技能套件成员之一另含caveman-setup、caveman-discover、caveman-evidence-review、caveman-manage其 注册信息 声明 delivery 渠道为cli和web。该技能的 frontmatter 描述为一句话概括Turn a Caveman optimization observation into an operator-chosen candidate with a paired baseline evaluation. Use when asked to inspect or evaluate a Caveman optimization report. Needs explicit approval.它的核心设计哲学在文档开头就写明了Caveman 的report-only 观察项report-only observations只是诊断输入。它们描述的是已记录的聚合形态recorded aggregate shapes而不是Cave Plan 行动项moves节省金额估算savings estimates实现配方implementation recipes实验资格experiment eligibility代码修改安全的证明。因此整个工作流必须保持operator-chosen操作者自主选择与 evidence-first证据优先。这一点在 skills/registry.json 的摘要中同样有对应Evaluate an operator-chosen report-only observation with paired evidence.1.1 底层依据report-only 机会是封闭词汇表从源码结构看这些report-only 观察并非随口定义的类别而是服务端与 CLI 共享的不可变合约。在 shared/platform/optimizers/optimizers.go 中ReportOnlyOpportunityContract结构体为每个 report 投影定义了三个字段OpportunityID持久化/公开 join key、EvidenceDetectorID经验证的检测器 bundle 身份、BandMethodreport SQL 与渲染器所接纳的精确零带宽方法。SKILL.md 中要求精确处理的四个 profile id与源码中的注册条目一一对应SKILL.md 中的 profile id源码中的 BandMethod 常量context-window-profilecontext_window_profile_report_only_zero.v1tool-catalog-profiletool_catalog_profile_report_only_zero.v1tool-output-size-profiletool_output_size_profile_report_only_zero.v1exploration-load-profileexploration_load_profile_report_only_zero.v1对应常量定义见 optimizers.go 第 44–47 行四个 profile 条目注册于第 72、74、83、85 行。BandMethod命名中的report_only_zero直接印证了文档所述immutable zero band不可变零带宽——这类观察的计费带宽恒为零即永远不产生机会金额。IsReportProjectionOnlyOpportunity()函数optimizers.go 第 91 行的注释进一步明确了这类观察的权限边界admitted by the dedicated report API but excluded from Cave Plan, scoring, proposals, and every lifecycle mutation except Dismiss——即被专用 report API 接纳但从 Cave Plan、评分、提案以及除 Dismiss 之外的所有生命周期变更中排除。这与 SKILL.md 第 4 节report-only rows permit dismissal only的规则完全吻合。2. 第一步读取精确的观察项2.1 前提已登录的 CLI 会话工作流的第一步要求已登录的 Caveman CLI 会话然后运行caveman opportunities list从 packages/cli/src/index.ts 可以看到该命令的实现opportunities list子命令直接发起GET /api/v1/opportunities并打印 JSON 响应。opportunities也在遥测命令白名单TELEMETRY_COMMAND_ALLOWLIST中属于受监控的正式命令面。2.2 只读report_only_observations数组保留原文文档对响应处理给出了三条硬约束只读report_only_observations数组不要从生命周期的data数组中挑选——后者是带金额的常规机会读取它会破坏零带宽前提逐字保留verbatim服务端提供的title与observation不允许改写、概括或润色诊断描述只处理这四个精确的 repository-profile idcontext-window-profile、tool-catalog-profile、tool-output-size-profile、exploration-load-profile。2.3 三条禁令不按价值排序、不编金额、不点名调用点文档明确禁止对这些 profile 做三件事Do not rank them by value——它们没有价值带宽排序无从谈起invent a dollar figure——禁止发明任何美元数字turn aggregate evidence into a claim about a particular callsite——聚合证据不能升格为对某个具体调用点的断言。这与源码中退役 id 的历史注释形成呼应在 optimizers.go 第 262–265 行 可以看到前身的tool-catalog-utilization被标注为 no longer claims unused-catalog dollarsverbose-tool-output被标注为 byte-length estimates no longer mint headroom——即字节长度估计不再铸造任何 headroom节省空间。Caveman 用版本化的 id 演进表达了同样的立场旧 id 可以估算金额新的 profile id 只能描述形态。2.4 故障处理停止并报告阻塞点如果 CLI 不可用、认证失败、或响应中不存在report_only_observations数组正确动作是停止编辑并报告精确的阻塞点exact blocker。文档还特别封死了一条退路Do not fall back to a raw gateway Cave Plan or a project API key: those surfaces do not provide this contract.不要回退到原始网关的 Cave Plan 或项目 API key——那些接口面不提供这份合约。这条约束甚至被写进了自动化测试packages/cli/tests/verbs-gate.runtime.mjs 的测试用例caveman-optimize keeps report-only profiles off SDK and raw-gateway recovery paths会直接读取 SKILL.md 正文断言其必须包含 Do not fall back to a raw gateway Cave Plan or a project API key且不得出现GET $GATEWAY/sdk/v1/ccr/handle、recoveryHandle、cave.compress等 SDK/原始网关恢复路径的字样。这意味着技能文本本身被视为被测试保护的合约文本而非普通说明。2.5 退役 id 的历史围栏文档还维护了一份永不复活清单这三个 id绝不允许被选中或应用context-window-bloattool-catalog-utilizationverbose-tool-output在陈旧提案、本地文件或旧响应中遇到它们时只当作历史上下文处理绝不复活其金额、配方或生命周期主张。源码侧对这份清单有精确对应。optimizers.go 第 189–206 行 的retiredOpportunityIDs列表一个不可变的历史 join key 词汇表中恰好包含这三个 id并伴随IsRetiredOpportunity()/RetiredOpportunityIDs()查询函数retiredOpportunityIDs的注释解释了保留动机Their family memberships below remain unchanged so historical dedup identity never shifts——家族成员关系保持不变以确保历史去重身份永不漂移。测试 packages/cli/tests/skills.runtime.mjs 第 168 行 的断言 caveman-optimize uses report-only observations and cannot select retired money ids 则从技能文本侧锁死了同一边界SKILL.md 必须引用report_only_observations、必须逐字提及四个 profile id、必须包含 explicit operator choice 与 paired eval 字样且不得提及任何退役的金额型 id。此外如果唯一看似可行动的项目是unlabeled-traffic应移交给caveman-discover技能打标labeling不是 profile 优化。在 optimizers.go 第 147–150 行unlabeled-traffic被归入enablementOnlyOpportunityContracts——一种exact-zero enablement observation with a Dismiss-only lifecycle同样不可执行。skills/caveman-discover/SKILL.md 明确接手了这部分工作盘点仓库中的 LLM 工作流、生成 slug 命名表、经用户批准后接线x-cave-workflow标签。3. 第二步强制 operator 显式选择这一步是工作流的人工决策闸门规则如下呈现所有可用的受支持观察项但不做任何排序no ranking每项展示四要素id、精确的title、精确的observation、last_seen_at在检查候选调用点或修改任何代码之前必须先获得explicit operator choice显式的操作者选择如果当前不存在任何受支持的观察项原样停止不做任何编辑stop with no edit.caveman/proposals/*.md若存在只能作为不可信的历史上下文不能替代当前响应或操作者的选择。这条提案文件不可信规则值得强调它防止 Agent 被仓库里残留的旧提案说服——旧文件既没有经过本轮服务端确认也不代表操作者意图。4. 第三步设计最小候选改动与 paired evaloperator 选定观察项后工作流进入工程阶段。这一步的要求是先找机制再谈改动检查仓库中可能产生所观察到的聚合形态的具体机制并引用精确的调用点证据exact callsite evidence。禁止假定profile 名字指明了原因——context-window-profile这个标签本身不解释为什么上下文大。一个最小候选 一份配对评估在动手编辑之前提出一个最小候选改动one minimal candidate change和一份paired eval。paired eval 的设计契约要求 baseline 与 candidate在完全相同的固定输入上运行并记录四类信息必须记录的项说明任务结果 / 质量检查哪一项检查必须保持在可接受范围内the task-outcome or quality check that must remain acceptable成本度量双臂使用同一个token / 字节 / provider 计数的成本度量the same token, byte, or provider-counted cost measure for both arms精确的 fixture使用的确切 fixture、命令与环境the exact fixture, command, and environment used混淆因素任何阻止公平比较的 confounder 都要如实声明随后请求 operator 批准候选与评估设计。如果仓库缺少固定 fixture、相关的质量检查、或统一的度量方法则停止并命名缺失的度量仪器name the missing instrumentation。文档还给出了一句关键判断Ordinary unit tests alone do not prove an optimization.普通的单元测试不能证明一个优化成立——因为优化断言需要同输入、同度量、双臂对照而常规单测通常不具备这些要素。这与仓库中evals/与benchmarks/目录的定位一致Caveman 用独立的评估/基准基础设施如 benchmarks/run.py、evals/measure.py承担配对度量职责而不是依赖业务单测。5. 第四步只应用已批准的候选应用阶段的纪律diff 限定在有证据的调用点Keep the diff at the evidenced callsite并保留既有的安全控制运行 paired baseline/candidate 评估 仓库的聚焦代码检查focused code checks双臂输入或度量不一致 → 整个比较作废discard the comparison质量回退或资源结果不确定 →只回滚本次候选编辑并报告该候选未赢得采纳did not earn adoption。最后一条是 SKILL.md 中最严格的权限围栏与 optimizers.go 中IsReportProjectionOnlyOpportunity注释的 every lifecycle mutation except Dismiss 互为表里Do not create a Caveman experiment or proposal, mark an opportunity implemented, change its lifecycle, or switch on an optimizer. Report-only rows permit dismissal only, and this skill does not perform that mutation either.翻译过来不得创建 Caveman 实验或提案、不得把机会标记为已实现、不得变更其生命周期、不得打开 optimizer 开关report-only 行只允许 Dismiss 这一种变更而且本技能连这个 Dismiss 都不执行。也就是说caveman-optimize对云端生命周期是完全只读的——它产出的唯一变更是你本地仓库里那个通过了 paired eval 的最小 diff。6. 第五步报告观察而不是节省金额工作流以一份固定格式的报告收尾。SKILL.md 给出的报告模板原文如下Observation: id — server title Recorded profile: server observation, verbatim Candidate: file:line and approved change Paired eval: identical input/fixture, baseline result, candidate result Quality check: actual result Code checks: commands and actual results Accounting: report-only profile; $0 opportunity band; no inferred or verified savings Decision: keep, reject, or inconclusive注意Accounting一行的固定措辞$0 opportunity band; no inferred or verified savings——机会带宽为零且既没有推断的节省也没有验证的节省。这不是模板装饰而是对该观察类别数学性质的如实陈述report-only profile 的 BandMethod 全是*_report_only_zero.v1带宽恒为零所以任何节省 X 美元的表述在合约层面就是假的。Decision行也只有三种合法取值keep保留改动、reject拒绝、inconclusive不确定——没有 win 或 saved N% 这类选项。文档最后一条原则划定了本地 paired eval 的证据边界Never convert token or byte reduction into dollars without provider-complete, same-request accounting supplied by the products verified methods. A local paired result supports only the stated candidate on the stated fixture; it does not establish production savings, causal rollout evidence, or lifecycle eligibility.没有产品提供的provider-complete、同请求核算verified methods不得把 token/字节减少换算成美元。本地配对结果只支持所述候选、在所述 fixture 上的结论不构成生产节省证明、因果上线证据或生命周期资格。这与 optimizers.go 第 21–24 行 的HeadroomCapVersion注释combined cross-family high band was bounded by matching provider-complete, catalog-priced daily spend指向同一套会计纪律金额主张只能来自 provider-complete 的核算来自产品验证的方法。7. 端到端流程图与边界速查把五步串起来caveman-optimize的完整控制流是caveman opportunities list (需已登录 CLI 会话) │ ├─ 失败/无 report_only_observations ──▶ 停止 报告 exact blocker │ ▼ 只读 report_only_observations保留 title/observation 原文 │ ├─ 只有 unlabeled-traffic ──▶ 移交 caveman-discover ├─ 遇到退役 id ──▶ 仅作历史上下文不复活 ▼ 呈现全部受支持观察不排序──▶ 等待 explicit operator choice │ ▼ 检查调用点机制 精确证据 ──▶ 提出最小候选 paired eval 设计 │ 缺 fixture/质量检查/度量 ──▶ 停止并命名缺失 ▼ 请求批准 ──▶ 只应用已批准候选运行 paired eval 聚焦代码检查 │ 双臂输入/度量不一致 ──▶ 丢弃比较 │ 质量回退/结果不确定 ──▶ 回滚本次编辑 ▼ 输出固定格式报告Observation / Candidate / Paired eval / Accounting: $0 band / Decision: keep|reject|inconclusive8. 关键设计决策小结观察 ≠ 行动report-only 观察在源码中是封闭合约optimizers.go 的reportOnlyOpportunityContracts带宽恒为零被排除在 Cave Plan、评分与提案之外。技能文本通过自动化测试强制与服务端合约保持逐字一致。人工决策不可绕过显式 operator 选择是编辑代码的前置条件旧提案文件.caveman/proposals/*.md被明确降级为不可信历史上下文。paired eval 是优化的最低证据标准同输入、同度量、记录质量检查与混淆因素普通单测不构成优化证明。对云端生命周期完全只读不建实验、不建提案、不改生命周期、不开 optimizer连 Dismiss 都不执行——技能的唯一输出是本地通过对照验证的最小 diff 和一份诚实报告。报告诚实性固定模板把 Accounting 钉死为 $0 opportunity band; no inferred or verified savings金额换算只允许通过 provider-complete 的同请求核算完成。这套工作流本质上把LLM 成本优化从看起来省了多少的估算游戏改造成同输入双臂对照 显式人工批准 零金额声明的可审计过程。如果你想进一步了解观察项的打标侧unlabeled-traffic的处理可参考 skills/caveman-discover/SKILL.md若要理解生命周期与金额主张的完整围栏建议阅读 shared/platform/optimizers/optimizers.go 及其 测试。【免费下载链接】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），仅供参考