企业官网建设流程全解析

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 身份）、BandMethod（report SQL 与渲染器所接纳的精确零带宽方法）。

SKILL.md 中要求精确处理的四个 profile id，与源码中的注册条目一一对应：

对应常量定义见 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数组，保留原文

文档对响应处理给出了三条硬约束：

1. 只读report_only_observations数组，不要从生命周期的data数组中挑选——后者是带金额的常规机会，读取它会破坏"零带宽"前提；
2. 逐字保留（verbatim）服务端提供的title与observation，不允许改写、概括或"润色"诊断描述；
3. 只处理这四个精确的 repository-profile id：context-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 dollars"，verbose-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-bloat
• tool-catalog-utilization
• verbose-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 eval

operator 选定观察项后，工作流进入工程阶段。这一步的要求是：

1. 先找机制，再谈改动：检查仓库中"可能产生所观察到的聚合形态"的具体机制，并引用精确的调用点证据（exact callsite evidence）。禁止假定"profile 名字指明了原因"——context-window-profile这个标签本身不解释为什么上下文大。
2. 一个最小候选 + 一份配对评估：在动手编辑之前，提出一个最小候选改动（one minimal candidate change）和一份paired eval。

paired eval 的设计契约要求 baseline 与 candidate在完全相同的固定输入上运行，并记录四类信息：

随后请求 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 product's 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|inconclusive）

8. 关键设计决策小结

1. 观察 ≠ 行动：report-only 观察在源码中是封闭合约（optimizers.go 的reportOnlyOpportunityContracts），带宽恒为零，被排除在 Cave Plan、评分与提案之外。技能文本通过自动化测试强制与服务端合约保持逐字一致。
2. 人工决策不可绕过：显式 operator 选择是编辑代码的前置条件；旧提案文件（.caveman/proposals/*.md）被明确降级为不可信历史上下文。
3. paired eval 是优化的最低证据标准：同输入、同度量、记录质量检查与混淆因素；普通单测不构成优化证明。
4. 对云端生命周期完全只读：不建实验、不建提案、不改生命周期、不开 optimizer，连 Dismiss 都不执行——技能的唯一输出是本地通过对照验证的最小 diff 和一份诚实报告。
5. 报告诚实性：固定模板把 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