Caveman 压缩会话模式：六档强度的 Token 精简规则设计与 Hook 实现剖析

在 Claude Code 会话中，模型输出的每一句寒暄、冠词和套话都在消耗 output token。本文围绕 caveman 仓库中的核心技能定义文件 SKILL.md 展开，完整解析它的六档压缩强度（lite/full/ultra 及三个 wenyan 文言文档位）、压缩规则的每一条例外与禁令、Auto-Clarity 安全回退机制与会话边界，并结合 caveman-activate.js、caveman-parse.js 等 Hook 源码说明这套规则如何被加载、按档位过滤、持久化与逐轮强化。读完后你将能够完整掌握 caveman 模式的启用/切换/退出方法，并理解"压缩风格、不压缩语言"背后的工程实现。

SKILL.md：一份写给模型的会话规则集

plugins/caveman/skills/caveman/SKILL.md 是 caveman 压缩模式的唯一事实来源（single source of truth）。它的 YAML frontmatter 声明了技能的触发面：

name: caveman
description: >
  Ultra-compressed communication mode that cuts output tokens while keeping
  technical accuracy. Levels: lite, full, ultra and the wenyan variants. Use for
  /caveman, "caveman mode", "talk like caveman", "be brief" or "less tokens".

正文只有一句话点明设计哲学：

Respond terse like smart caveman. All technical substance stay. Only fluff die. （像聪明的原始人一样简洁地回答。所有技术实质保留，只有虚词去死。）

值得强调的是：这不是一个"翻译腔段子"，而是一份可直接注入模型上下文的完整行为规则集——Hook 会在每个会话开始时把它作为隐藏上下文注入（下文第三节会给出源码证据）。仓库根 README.md 中"平均 1214 → 294 tokens，约 65% 的 output 缩减"的示例表即针对此类对话风格，且 README 在 docs/HONEST-NUMBERS.md 中诚实声明：技能只缩减 output token，input 与推理 token 不受影响，技能本身每轮还会增加约 1–1.5k 的 input token。

持久性（Persistence）：默认档位与会话级生效

原文档 Persistence 一节的完整规则如下：

• 激活后成为整个会话每一轮回复的默认风格，直到用户说 "stop caveman" 或 "normal mode" 才退出；
• 长会话中必须保持简洁，不允许"填充词漂移"（filler drift）——即聊得越久越啰嗦；
• 默认档位为 full；
• 切换命令：/caveman lite|full|ultra|wenyan-lite|wenyan-full|wenyan-ultra|off。

这个"会话级持久"的承诺在源码中是真实兑现的。从 caveman-mode-tracker.js 可以看到，每个 Claude Code 窗口拥有自己的模式状态文件（$CLAUDE_CONFIG_DIR/.caveman-sessions/<session_id>.mode），~/.claude/.caveman-active 只是"最后写入者胜出"的镜像，供第三方 statusline 读取；src/hooks/README.md 进一步说明该镜像永远不包含字面量 off——退出模式即删除文件，避免旧版工具把 off 误当作激活档位渲染成 [CAVEMAN:OFF]。

压缩规则（Rules）：删什么、禁什么、保留什么

这是 SKILL.md 中信息密度最高的部分。规则原文全部为英文（这本身也是刻意的：规则文本会被原样注入模型上下文），下面逐条拆解。

删除清单

• 冠词（a/an/the）、填充词（just/really/basically/actually/simply）、客套话（sure/certainly/of course/happy to）、模糊限定（hedging）；
• 允许使用句子片段（Fragments OK）；
• 使用短同义词："big" 而不是 "extensive"，"fix" 而不是 "implement a solution for"；
• 不叙述工具调用（no tool-call narration）、不使用装饰性表格和 emoji；
• 非经要求不倾倒长原始错误日志，只引用最短的决定性一行。

三条"看似省 token 实则不省"的禁令

文档里最值得注意的是几条反直觉规则，其背后都有 tokenizer 层面的量化理由：

1. 禁止自造缩写（cfg/impl/req/res/fn）。理由：tokenizer 会把这些缩写拆成和完整单词相同的 token 序列——零节省，读者还要额外解码。标准技术缩写（DB/API/HTTP）可以，因为它们是高频词、tokenizer 有现成编码。
2. 禁止因果箭头（→）。箭头本身独占一个 token，并不比文字短，还牺牲可读性。
3. 禁止"为像原始人而加词"。例如 "when it not" 比 "when not" 多花一个 token 且语义相同；"sees" 和 "see" 都是单 token，破坏动词形式没有任何收益。原文的判据一句话讲透：if caveman phrasing not shorter than plain phrasing, use plain（若原始人句式不比平实句式短，就用平实的）。

文档中 skills/caveman/README.md 与插件版 SKILL.md 存在一处刻意的演进差异：README 的 ultra 档示例还保留了 "Inline obj prop → new ref → re-render" 的箭头写法，而 SKILL.md（当前事实来源）已明确将箭头和自造缩写从 ultra 档中移除，并标注 "measured zero token saving under tokenizer"（实测在 tokenizer 下零节省）。这说明规则集是随 tokenizer 实测结果迭代收紧的。

保真红线

• 永不删除 not/never/no/only/except——丢失否定词导致的语义反转比省下的任何 token 都更糟；
• 数字与单位必须精确；
• 技术术语精确、代码块原封不动、错误信息原样引用；
• 语言保真：严格按用户的主流语言回复，"压缩的是风格，不是语言"（Compress the style, not the language）；技术术语、代码、API 名、CLI 命令、commit 类型关键字（feat/fix/...）与精确错误串逐字保留，除非用户明确要求翻译；
• "删冠词"只适用于有冠词的语言；日语、泰语等靠小品词/后置助词承载格与角色的语言要保留这些语法标记，压缩的是礼貌语和填充语。

输出模式（Pattern）

回复模板固定为：[thing] [action] [reason]. [next step].，文档给出正误对照：

Not: "Sure! I'd be happy to help you with that. The issue you're experiencing is likely caused by..."

Yes: "Bug in auth middleware. Token expiry check use < not <=. Fix:"

同时禁止"双答案"（正常回答 + 原始人版本重复一遍）、禁止 "caveman mode on"、"Caveman:" 前缀或与回复本身冗余的复述；用户询问当前模式时直接平实回答。工具调用则要求"直接发射"：调用前后不加开场白、计划或进度说明，调用之间的文字只允许用于澄清、安全/不可逆警告或消歧。

六档强度（Intensity）与对照示例

SKILL.md 的 Intensity 表是档位定义的唯一权威（plugins/caveman/skills/caveman/SKILL.md 第 40–47 行）：

档位	变化内容
lite	去填充词/模糊限定。保留冠词 + 完整句子。专业但紧凑
full	默认档。删冠词、片段 OK、短同义词。经典原始人。无工具调用叙述、无装饰表格/emoji；标准缩写可用，禁止自造缩写
ultra	因果链不产生歧义时剥除连词；一词能表达就不多词；每个事实只说一次。禁止 prose 缩写（cfg/impl/req/res/fn/auth），禁止箭头（X → Y）；代码符号、函数名、API 名、错误串永不触碰
wenyan-lite	半文言。去填充/模糊但保留语法结构，文言腔调
wenyan-full	文言最大化简洁。全文言文，80–90% 字符（非 token）压缩。古典句式、动词先于宾语、主语常省略、文言虚词（之/乃/為/其）
wenyan-ultra	保持文言文感下的极限缩略，极致短促

文档随后给出两组六个档位的完整对照示例，这是理解各档差异最直观的部分：

示例一，"Why React component re-render?"（为什么 React 组件会重渲染？）：

• lite: "Your component re-renders because you create a new object reference each render. Wrap it in useMemo."
• full: "New object ref each render. Inline object prop = new ref = re-render. Wrap in useMemo."
• ultra: "Inline obj prop, new ref, re-render. useMemo."
• wenyan-lite: "組件頻重繪，以每繪新生對象參照故。以 useMemo 包之。"
• wenyan-full: "每繪新生對象參照，故重繪；以 useMemo 包之則免。"
• wenyan-ultra: "新參照則重繪。useMemo 包之。"

示例二，"Explain database connection pooling."（解释数据库连接池）：

• lite: "Connection pooling reuses open connections instead of creating new ones per request. Avoids repeated handshake overhead."
• full: "Pool reuse open DB connections. No new connection per request. Skip handshake overhead."
• ultra: "Pool reuse open DB connections. No per-request handshake."
• wenyan-full: "池蓄已開之連，不逐請而新開，省握手之費。"
• wenyan-ultra: "池蓄連，免逐請新開，省握手。"

最后有一条范围禁令：文言字仅出现在 wenyan 档位；在非 wenyan 档位上不得为缩句把普通词换成文言字。

Auto-Clarity：安全回退机制

压缩风格在以下五类场景中自动切回正常散文：

1. 安全警告（Security warnings）；
2. 不可逆操作的确认（Irreversible action confirmations）；
3. 片段顺序或省略连词可能造成误读的多步操作序列；
4. 压缩本身制造技术歧义时（原文举例："migrate table drop column backup first" 在没有冠词/连词时步骤顺序不明）；
5. 用户要求澄清或重复提问。

清晰部分讲完后恢复 caveman 风格。文档给出一条破坏性操作的格式示范（并注明：示例只展示格式，警告正文要用会话语言写）：

Warning: This will permanently delete all rows in the users table and cannot be undone.

DROP TABLE users;

Caveman resume. Verify backup exist first.

这段设计解决了"压缩省 token"与"关键操作必须零歧义"的冲突：风格可以省，语义不能省。

Boundaries：压缩止步于聊天之外

Boundaries 一节划定了压缩的作用域边界，原文规则为：

• 聊天之外一律正常书写：代码、注释、commit message、文档、issue/PR/MR/缺陷/工单/bug report 正文、memory 文件、第三方消息（/caveman-compress 单独豁免）；
• "Open a defect" / "file a bug" 与 "open issue" 同义：正文是写给其他人类看的，必须用正常英文；
• "stop caveman" 或 "normal mode" 立即恢复正常风格；
• 档位持续生效，直到被修改或会话结束。

实现纵深：SKILL.md 如何进入模型上下文

规则写得再好，若不进入模型上下文就是空文。src/hooks/caveman-activate.js 是 SessionStart Hook，它在每次会话事件（startup/resume/clear/compact/fork）触发时执行三件事：解析并持久化本会话模式、注入规则集、检测 statusline 配置缺失并提示。

关键在规则注入的运行时读取逻辑（caveman-activate.js 第 356–404 行）：

1. 按候选路径读 SKILL.md：优先 $CLAUDE_PLUGIN_ROOT/skills/caveman/SKILL.md（Claude Code 调用插件 Hook 时设置该环境变量），其次 ../../skills/caveman/SKILL.md（插件或仓库检出布局），再次 ../skills/caveman/SKILL.md（独立安装布局）。全部落空才退回一段硬编码的最小规则集——注释明确说明运行时读取是为了"SKILL.md 的修改自动传播，没有会过期的硬编码副本"。
2. 按档位过滤：剥离 YAML frontmatter 后，逐行处理——强度表只保留表头 + 当前激活档那一行（匹配 | **level** | 格式）；示例行只保留 - <level>: 与当前档匹配的行（wenyan 会先归一化为 wenyan-full 标签，见第 343 行）。这意味着模型每轮看到的规则集是"公共规则 + 当前档专属定义与示例"，六个档位的互斥示例不会互相干扰。
3. 逐轮强化：caveman-mode-tracker.js 作为 UserPromptSubmit Hook，在每条用户消息后注入一行 CAVEMAN MODE ACTIVE (<mode>) — session ruleset applies.。注释解释了必要性：SessionStart 只注入一次，而上下文压缩（compaction）会剪掉规则、其他插件可能每轮注入竞争风格，逐轮提醒让 caveman 保持在模型注意力里。

模式解析：/caveman 与自然语言触发

模式切换由 caveman-parse.js 统一解析——注释说明它被抽出来作为"单一事实来源"，使 Claude Code Hook 与 opencode 插件不可能解析漂移。核心行为：

• resolveModeArg（第 90–114 行）：裸 /caveman 激活为配置的默认档；off/stop/disable 清除模式；wenyan-full 归一化为存储别名 wenyan（配置层存储的是 wenyan，展示层标签是 wenyan-full）；拼写错误的档位不会静默回退到默认值，而是返回 unresolved，由 caveman-mode-tracker.js 第 224–242 行 生成提示告知用户"档位未变 + 合法档位列表"，且拒绝的输入绝不回显进模型上下文。
• 自然语言触发（第 150–206 行）：退出意图优先于激活意图计算（"turn caveman mode off" 不会被激活模式误吞），识别 "stop/disable/deactivate caveman"、"normal mode"（仅在命令位或带 caveman 语境时匹配，避免误伤 vim normal mode 的讨论）、"talk like caveman"、"less tokens / be brief / fewer tokens" 等短语。
• 引用免疫：提示词中被 "..." 或 `...` 包裹的片段在匹配前会被置空（QUOTED_SPAN_REGEX），这样在 bug report 里引用文档原句 'Say "stop caveman"' 不会真的把模式关掉；问句（what/how/why 开头）不触发激活；以 / 开头的命令文本不参与自然语言匹配，防止别的斜杠命令的参数误触 caveman 触发器。

完整的合法模式列表（含独立档 commit/review/compress）定义在 caveman-activate.js 的 FALLBACK_VALID_MODES（第 71–75 行），独立档有各自的技能文件与命令，通过 /caveman-commit 等独立命令设置，且 caveman-mode-tracker.js 第 248–304 行 会记住被独立档"顶替"前的 prose 档位，在下一条普通提示词上自动恢复——这正是 SKILL.md 承诺的 "Level persist until changed or session end" 在一过性技能场景下的工程兑现。

会话状态与降级设计

SKILL.md 承诺的持久性依赖可靠的状态文件读写。实现上有两处值得一提的健壮性设计：

• 按会话隔离 + 镜像兼容：状态存于 $CLAUDE_CONFIG_DIR/.caveman-sessions/<session_id>.mode，session_id 缺失或畸形时回退到旧的全局标志文件，行为等价于升级前（caveman-mode-tracker.js 第 128–131 行）；
• 降级不翻转用户意图：caveman-config.js 缺失或导出形状不对时，Hook 用内联的降级桩代替，而不是抛 MODULE_NOT_FOUND。降级桩的 getDefaultMode 会按真实解析顺序（环境变量 CAVEMAN_DEFAULT_MODE → 仓库内 .caveman.json/.caveman/config.json 向上遍历 → 用户配置 → 内置默认 full）重新推导，caveman-activate.js 第 77–123 行 的注释点明原因：若降级忽略团队检查入库的 defaultMode: "off"，会把"项目选择退出 caveman"反转成"强制注入"。配置解析还支持仓库级 .caveman.json 设 defaultMode: "off" 让整个项目退出 caveman（caveman-mode-tracker.js 第 306–314 行 的 getDefaultMode(data.cwd) !== 'off' 门控）。

实操速查

操作	方式
激活默认档（full）	/caveman
切换档位	/caveman lite、/caveman ultra、/caveman wenyan-lite 等
退出	/caveman off，或说 "stop caveman" / "normal mode"
自然语言激活	"talk like caveman"、"be brief"、"less tokens"
项目级退出	仓库内 .caveman.json 或 .caveman/config.json 设 "defaultMode": "off"
当前模式显示	statusline 徽章 [CAVEMAN] / [CAVEMAN:ULTRA] / [CAVEMAN:WENYAN]，配置见 src/hooks/README.md
会话 token 用量	/caveman-stats

命令侧的实现载体是 commands/caveman.toml，其 prompt 模板把档位参数与 SKILL.md 规则摘要一起下发；src/rules/caveman-activate.md 则是注入其他宿主（如 OpenClaw）时的精简规则副本，二者均派生自 SKILL.md 这一事实来源。

小结

caveman 技能文件是一份"以 tokenizer 实测为依据、以语义保真为红线"的输出压缩规则集：六个强度档位覆盖从"去填充词"到"极限文言"的压缩光谱；Auto-Clarity 保证安全警告与不可逆操作永远零歧义；Boundaries 把压缩严格限制在聊天范围内，代码、提交、工单正文一律正常书写。配套的 SessionStart 与 UserPromptSubmit Hook 负责把规则按当前档位过滤后注入上下文、逐轮强化、按会话持久化，并以降级桩和引用免疫等防御性设计保证规则在残缺安装、多窗口、跨 compaction 场景下依然可靠。对想进一步核实的读者，建议按 SKILL.md → caveman-activate.js → caveman-parse.js → tests/test_caveman_parse.js 的顺序阅读源码与测试。