caveman 精简规则文件实战：一份 15 行激活规则如何部署到任意编码代理

caveman-activate.md 是 caveman 项目中的“最小可行激活规则集”：仅 15 行 Markdown，却定义了整套简洁沟通风格的核心规则、强度切换命令、退出短语与行为边界。本文逐行拆解这份规则文件的内容与设计意图，并结合 caveman-init.js 部署矩阵、caveman-activate.js SessionStart 钩子与 SKILL.md 完整规则集，说明它如何被分发到 Cursor、Windsurf、Cline 等多种代理的配置体系中，以及运行时如何被动态注入、过滤与验证。读完本文，你将掌握该规则的完整语义、落盘机制与幂等管理原理。

规则文件定位：三层规则体系中的“基线层”

caveman 项目（slogan 是 “why use many token when few token do trick”）的简洁风格规则实际上存在三层载体，src/rules/caveman-activate.md 是其中面向非 Claude Code 环境的基线层：

载体	位置	服务对象	注入方式
完整规则集（事实源）	skills/caveman/SKILL.md	Claude Code 插件会话	SessionStart 钩子运行时读取、按级别过滤后注入
基线激活规则	src/rules/caveman-activate.md	Cursor / Windsurf / Cline / Copilot / AGENTS.md 等	安装期静态写入各代理规则文件
引导片段	src/rules/caveman-openclaw-bootstrap.md	OpenClaw 工作区	写入 SOUL.md，指向本仓库 SKILL.md

SKILL.md 开头即与规则文件同句——“Respond terse like smart caveman. All technical substance stay. Only fluff die.”——说明两者共享同一规则语言。规则文件是这份完整规则集的浓缩版，保留全部可执行指令，但去掉强度表与示例段，以适配各代理规则文件的字数约束。

完整内容如下（15 行原文，逐行解释见下一节）：

Respond terse like smart caveman. All technical substance stay. Only fluff die.

Rules:
- Drop: articles (a/an/the), filler (just/really/basically), pleasantries, hedging
- Fragments OK. Short synonyms. Technical terms exact. Code unchanged.
- Pattern: [thing] [action] [reason]. [next step].
- Not: "Sure! I'd be happy to help you with that."
- Yes: "Bug in auth middleware. Fix:"

Switch level: /caveman lite|full|ultra|wenyan-lite|wenyan-full|wenyan-ultra
Stop: "stop caveman" or "normal mode"

Auto-Clarity: drop caveman for security warnings, irreversible actions, user confused. Resume after.

Boundaries: code/commits/PRs written normal.

逐行拆解：每行规则的技术意图

核心风格规则（Rules 块）

第一条 “Respond terse like smart caveman” 是双重身份：既是总指令，也是部署工具的识别哨兵——caveman-init.js 中定义 SENTINEL = 'Respond terse like smart caveman'，用于检测目标仓库里是否已存在旧版（未加围栏的）规则块。

Rules 块四行各自承担一个职能：

• Drop 行：枚举必须删除的语言成分——冠词（a/an/the）、填充词（just/really/basically）、客套话、含糊措辞（hedging）。这是 token 削减的主要来源。
• Fragments OK 行：允许句子碎片，鼓励短同义词（如用 “big” 而非 “extensive”），同时锁死两条红线——技术术语必须精确、代码块不得改动。对应 SKILL.md 的更完整版本还补充了“不造新缩写（cfg/impl/req/res/fn）”“不用因果箭头（→）”等 tokenizer 层面的量化结论。
• Pattern 行：规定输出骨架为 [thing] [action] [reason]. [next step].（对象—动作—原因，下一步），使简洁风格仍然因果完整、可执行。
• Not/Yes 对照行：用反例（“Sure! I'd be happy to help you with that.”）与正例（“Bug in auth middleware. Fix:”）做行为锚定。对照示例比纯描述性规则更能稳定模型行为，这一点在钩子注释中亦有印证——caveman-activate.js 的注释明确写道：早期仅注入两句摘要“太弱了，模型会在会话中途漂回冗长风格”，完整带示例的规则锚定行为更可靠。

强度切换与退出（Switch level / Stop）

/caveman lite|full|ultra|wenyan-lite|wenyan-full|wenyan-ultra 定义了六个强度档位：

• lite / full / ultra 是英文简洁三档：lite 保留冠词与完整句法、仅去填充；full 去冠词、允许碎片（经典 caveman）；ultra 进一步剥离连词、一词达意，并禁止任何自造缩写与箭头符号。
• wenyan-lite / wenyan-full / wenyan-ultra 是文言文变体，SKILL.md 的强度表说明 wenyan-full 追求完全文言文、以字符计可削减 80–90%，wenyan-ultra 在保留文言语感的前提下极限缩写。

在 Claude Code 环境中，/caveman 命令由 caveman-mode-tracker.js（UserPromptSubmit 钩子）解析，支持的自然语言触发词还包括 “talk like caveman” 等，完整模式白名单见 caveman-activate.js 的 FALLBACK_VALID_MODES：off, lite, full, ultra, wenyan-lite, wenyan, wenyan-full, wenyan-ultra, commit, review, compress。注意规则文件只列六个 prose 档位，而 off 由 Stop 短语承担，commit/review/compress 则属于独立技能模式（见下文“独立模式”）。

Stop: "stop caveman" or "normal mode" 给出两条自然语言退出通道。SKILL.md 的 Boundaries 还将其扩展为“退出后级别不再持久，直至再次切换或会话结束”。

Auto-Clarity：安全优先的自动降级

“Auto-Clarity: drop caveman for security warnings, irreversible actions, user confused. Resume after.” 这一行是简洁风格的安全阀：遇到安全警告、不可逆操作确认、用户困惑/重复提问时，自动切回正常行文，讲清后再恢复简洁风格。SKILL.md 给出了更完整的触发清单（多步序列碎片化易误读、压缩本身造成技术歧义）和一个破坏性操作的格式示例：

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

DROP TABLE users;

Caveman resume. Verify backup exist first.

Boundaries：风格不落盘

“Boundaries: code/commits/PRs written normal.” 划定最后一条边界：任何持久化到聊天之外的产物——代码、注释、commit message、issue/PR 正文、文档——一律正常行文，因为它们的读者是其他人类。SKILL.md 进一步将记忆文件、第三方消息、缺陷单（defect/bug-report）都列入正常行文范围。

部署矩阵：caveman-init.js 如何分发规则文件

caveman-init.js 是该规则文件的官方部署器，支持 node src/tools/caveman-init.js [target-dir] [--dry-run] [--force] [--only <agent>] 用法，也可通过 curl 管道单文件运行。其代理清单（caveman-init.js）如下：

代理	落盘路径	模式	附加 frontmatter
Cursor	.cursor/rules/caveman.mdc	replace（整体拥有）	alwaysApply: true
Windsurf	.windsurf/rules/caveman.md	replace	trigger: always_on
Cline	.clinerules/caveman.md	replace	无
Copilot	.github/copilot-instructions.md	append（围栏块）	无
opencode	.opencode/AGENTS.md	append（围栏块）	无
AGENTS.md	AGENTS.md	append（围栏块）	无
OpenClaw	~/.openclaw/workspace/{skills/caveman/, SOUL.md}	独立安装器	见 caveman-openclaw-bootstrap.md

Cursor 与 Windsurf 的 frontmatter 字段（alwaysApply / trigger: always_on）正是让规则文件“always-on”生效的关键——这解释了文件名中 “activate” 一词的含义：它不是某次会话的临时指令，而是每次请求都会加载的常驻规则。

围栏机制与幂等刷新

对 append 型目标（用户也在编辑的共享文件），规则块被 <!-- caveman-begin --> / <!-- caveman-end --> 围栏包裹（caveman-init.js）。重跑时的处理逻辑（caveman-init.js）：

1. 围栏成对且唯一 → 原地刷新：仅替换围栏之间的字节，用户前后内容原样保留；内容一致则跳过；
2. 围栏残缺（孤立 BEGIN、END 在 BEGIN 之前）→ 判定为“损坏的围栏”而非围栏，报告并拒绝写入，防止二次运行把损坏复利放大；
3. 存在旧版无围栏块（以 SENTINEL 识别）→ 标记 skipped-legacy-unfenced，不贸然改写被跟踪的仓库文件。

规则正文的事实源管理

部署工具内置了一份与规则文件逐字镜像的 RULE_BODY 常量（caveman-init.js），使 curl 管道单文件运行无需 src/rules/ 目录；loadRuleBody()（caveman-init.js）优先读取仓库内 src/rules/caveman-activate.md，找不到才退回内嵌镜像。这意味着规则文件本身是单一事实源，安装工具只是其消费者。

所有写入走 writeAtomic()（caveman-init.js）：先写临时文件再 rename 覆盖，针对 EPERM/EBUSY/EACCES 做有限重试——因为这些文件落在用户仓库的受跟踪路径上，一次中断的半截写入会污染已提交文件。

运行时注入：SessionStart 钩子与完整规则集

规则文件解决的是静态分发；在 Claude Code 中，规则的真正运行时载体是 caveman-activate.js 这个 SessionStart 钩子，它每次会话启动（及 resume / clear / compact / fork）都向 stdout 输出规则集，Claude Code 将其作为隐藏系统上下文注入——模型可见，用户不可见（机制图解见 src/hooks/README.md）。

SKILL.md 解析与强度过滤

钩子不直接使用 src/rules/caveman-activate.md，而是在三个候选位置依次查找 SKILL.md（caveman-activate.js）：

1. $CLAUDE_PLUGIN_ROOT/skills/caveman/SKILL.md —— 插件安装时由 Claude Code 设置的环境变量，权威来源；
2. ../../skills/caveman/SKILL.md —— 插件目录布局或仓库检出；
3. ../skills/caveman/SKILL.md —— 独立安装（hooks 在 $CLAUDE_CONFIG_DIR/hooks/，技能在 $CLAUDE_CONFIG_DIR/skills/caveman/）。

找到后，钩子剥掉 YAML frontmatter，再按当前会话级别做行级过滤（caveman-activate.js）：强度表中只保留表头行与当前级别那一行，- lite: / - full: 形式的示例行同样只保留当前级别的。三个候选全部落空时，才退回钩子内置的最小规则集（caveman-activate.js）——其内容与 src/rules/caveman-activate.md 同源，并额外补充了 Persistence、语言保持（压缩风格不压缩语言）、Auto-Clarity 展开等段落。

每会话模式状态与 source 分支

钩子从 stdin 的 hook payload 中解析 source、cwd、session_id（caveman-activate.js），模式状态按会话隔离：每个 Claude Code 窗口把模式存到 $CLAUDE_CONFIG_DIR/.caveman-sessions/<session_id>.mode（默认 ~/.claude/.caveman-sessions/），$CLAUDE_CONFIG_DIR/.caveman-active 仅作为“最后写入者胜”的兼容镜像，且镜像永不写入字面 off（src/hooks/README.md）。

关键在于 source 的分支处理（caveman-activate.js）：

• RESET_SOURCES = { startup, clear }：真正的新会话或用户显式 /clear，才重新推导配置默认模式（环境变量 CAVEMAN_DEFAULT_MODE → 向上查找的 .caveman.json/.caveman/config.json → 用户配置 → 内置默认 full，解析顺序见 caveman-activate.js）；
• compact / resume / fork 等延续型事件只读取该会话已存模式，绝不重推默认值——这正是修复“用户说了 stop caveman，下一次自动压缩又把 caveman 悄悄重新武装”缺陷的核心；off 也以字面值持久化，使“停用”能跨越压缩存活；
• payload 到达是事件驱动的：在第一个完整 JSON 对象上即触发激活而非等 EOF（规避 Windows 管道 close 滞后耗尽 5 秒预算的问题），并设 2000ms 看门狗（caveman-activate.js），看门狗触发时 source 按 unknown 处理、绝不重置模式。

独立模式与 off

commit、review、compress 三个模式不属于简洁强度档，而是各有独立技能文件；命中时钩子只输出一行激活声明（CAVEMAN MODE ACTIVE — level: commit. Behavior defined by /caveman-commit skill.）即退出（caveman-activate.js）。off 模式则跳过一切规则输出、仅持久化状态并打印 OK（caveman-activate.js）。另外 wenyan 是 wenyan-full 的别名，统一归一为 wenyan-full 标签（caveman-activate.js）。

安装器复用：opencode 的 always-on 块

除 caveman-init.js 外，统一安装器 bin/install.js 在 opencode 集成路径中直接读取 src/rules/caveman-activate.md 原文，包上同样的 begin/end 围栏后写入目标 AGENTS.md。刷新策略与 init 工具一致：围栏块字节与当前规则文件一致则跳过，不一致则原地替换围栏间字节并保留用户内容；遗留的无围栏块在 --force 下先备份（AGENTS.md.bak）再迁移，绝不整文件覆盖。这保证了同一份 15 行规则在三种分发渠道（init 工具、opencode 安装器、钩子回退规则集）中保持逐字一致。

测试验证

仓库测试对整条链路做了回归覆盖：

• tests/test_hooks.py：test_activate_emits_skill_md_not_fallback_from_repo_layout 验证钩子从仓库布局解析到 SKILL.md（断言输出含 ## Intensity 表、含 | **full** | 行而不含 | **lite** | 行——即强度过滤生效）；test_activate_prefers_claude_plugin_root 验证 CLAUDE_PLUGIN_ROOT 优先级；test_activate_does_not_nudge_when_custom_statusline_exists 验证已配置自定义 statusline 时不重复提示。
• tests/test_hooks.py 的 SessionStartSourceTests 专门回归 source 分支与持久化 off 行为。
• tests/test_caveman_init.js：验证 init 工具在目标目录生成 .cursor/rules/caveman.mdc、.windsurf/rules/caveman.md、.clinerules/caveman.md 等内容。
• tests/test_hook_missing_sibling.js：验证 caveman-config.js 缺失时钩子降级仍工作（回退模式白名单与真实模块保持一致由该测试断言）。

小结

src/rules/caveman-activate.md 用 15 行完成了四件事：定义可执行的简洁风格规则（Drop/Fragments/Pattern/Not-Yes 对照）、声明六档强度切换与退出通道、内置 Auto-Clarity 安全阀、划定“风格不落盘”边界。它作为单一事实源被 caveman-init.js 部署到 Cursor、Windsurf、Cline、Copilot、AGENTS.md 等七个目标，被 bin/install.js 复用为 opencode 的 always-on 块，又是 caveman-activate.js 运行时回退规则的同源版本；而 Claude Code 会话中更完整的 SKILL.md 规则集则由 SessionStart 钩子按每会话级别动态过滤注入。围栏机制、原子写入、source 分支与持久化 off 状态共同保证了这份规则在幂等重跑、多窗口并存、自动压缩等场景下行为一致。理解这条从 15 行文本到多代理落盘再到会话级注入的完整链路，是掌握 caveman token 削减机制的关键。