caveman-compress 技能实战把 CLAUDE.md 等记忆文件压缩成穴居人语法降低每轮会话输入 Token【免费下载链接】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-compress是 caveman 项目中的一个 Claude Code 技能skill核心思路一句话概括把每次会话都要加载的项目记忆文件CLAUDE.md、todo 清单、偏好说明从啰嗦的自然语言压缩成「穴居人式」短句从而降低每轮会话固定的输入 token 开销同时把可读的原始版本备份到项目目录之外、不会被技能自动加载器二次摄入的地方。阅读本文你将掌握如何触发/caveman-compress命令、它背后的「检测 → 压缩 → 校验 → 定点修复 → 重试」执行链、哪类内容会被原样保留、哪类文件被坚决跳过以及仓库源码层面对代码块保真、备份安全与敏感文件防护的实现细节。本技能的定义文档位于 plugins/caveman/skills/caveman-compress/SKILL.md同一份技能在仓库根目录另有本地副本 skills/caveman-compress/SKILL.mdskills/caveman-compress/README.md 声明本地副本位于skills/caveman-compress/。下文分析与阅读路径均以仓库相对路径给出。一、为什么记忆文件值得压缩每会话重复读入的 token 成本CLAUDE.md这类项目记忆文件会在每次会话启动时被 Claude 加载。文件越大每次开启项目就要为同样的内容重复支付一次输入 token。按仓库 README 的估算口径「一份 1,000 token 的项目记忆文件每打开一次项目就多消耗 1,000 输入 token100 次会话即 100,000」——这正是 skills/caveman-compress/README.md 中「Why This Matter」一节说明的动机模型。caveman-compress的解法不是删除信息而是改写自然语言部分去掉填充词、把长句改成短语、合并重复条目同时对代码、路径、URL 等「不能碰的内容」做字节级保真。它只处理自然语言文本天然适合CLAUDE.md、todo、偏好文件这类「散文 少量结构化内容」的混合文档。需要强调的是仓库实测的是结构化保真 token 计数下降。README 给出 5 组真实夹具的平均 token 节省约 46%详见下文第七节并明确说明这些数据「不证明语义等价或任务质量等价」——这是基于当前仓库内容的准确表述不应夸大为普适的压缩率承诺。二、触发方式与基本使用技能的 YAML frontmatter 声明了两个触发途径Slash Command/caveman-compress filepath自然语言意图当用户要求「压缩某个记忆文件」时由 Agent 触发用法与CLAUDE.md中说明一致形式为/caveman-compress filepath实际示例来自 README/caveman-compress CLAUDE.md /caveman-compress docs/preferences.md /caveman-compress todos.md整个流程会经历压缩后的文件就地覆盖原文件CLAUDE.md而人类可读的原版被保存为CLAUDE.original.md——注意它不会放在源文件旁边而是放进项目目录树之外的数据目录以免技能自动加载器把备份当成「活文件」再次摄入。备份目录规则macOS / Linux$XDG_DATA_HOME/caveman-compress/backups/parent-dir-name/Windows%LOCALAPPDATA%\caveman-compress\backups\parent-dir-name\若未设置XDG_DATA_HOMEPOSIX 环境实际回退到~/.local/share见 skills/caveman-compress/scripts/compress.py。想恢复可读版本时去该数据目录编辑*.original.md然后再次运行技能即可基于新内容重新压缩。三、一次压缩的完整执行链CLI 入口到写入回读SKILL.md 中「Process」一节描述了 CLI 的工作步骤。技能的 Python 实现位于scripts/与 SKILL.md 同级入口为python3 -m scripts absolute_filepath由 skills/caveman-compress/scripts/main.py 转发到cli.py的main()。调用链与关键源码对应如下前置检查不消耗 token——cli.py校验命令行参数个数、文件存在、是普通文件并做resolve()随后调用detect_file_type()与should_compress()做文件类型判定非自然语言文件直接跳过并退出退出码 0出错返回非零。CLI 在启动阶段还对stdout/stderr强制reconfigure(encodingutf-8, errorsreplace)避免 Windows 默认 cp1252 控制台碰到 emoji 状态符时崩溃。安全与容量闸门——compress_file()在 compress.py 中先做三项互不依赖的快速拒绝文件不存在、超过 500KB 上限MAX_FILE_SIZE 500_000、命中敏感路径名单。这三项检查刻意放在加锁之前执行避免一次被拒的调用在共享状态目录留下永久锁文件。跨会话文件锁——file_lock() 使用操作系统原生文件锁POSIX 用fcntl.flockWindows 用msvcrt.locking锁路径是(parent-dir-name, stem)身份经 SHA-256 摘要后生成的.lock文件。崩溃或被杀掉的进程会自动释放锁无需手工清理陈旧标记。等待上限LOCK_WAIT_SECONDS 90015 分钟超过则抛出LockTimeoutError让用户重试。类型检测无 token——由 detect.py 完成返回natural_language / code / config / unknown四种分类详见下文第四节。Claude 压缩消耗一次调用——见 call_claude()优先使用 Anthropic Python SDK设置了ANTHROPIC_API_KEY时模型取环境变量CAVEMAN_MODEL默认claude-sonnet-4-5max_tokens8192未设置密钥时回退到claude --printCLI复用桌面端已有登录态并且固定参数列表、文件内容经 stdin 传入而非 shell 参数。校验输出无 token——由 validate.py 对「备份 vs 压缩结果」做结构化比对详见下文第五节。出错则定点修复、最多重试 2 次——校验失败后构造build_fix_prompt()compress.py只针对错误清单做补丁式修复如把 ORIGINAL 中缺失的 URL / 代码块 / 标题原文精确补回 COMPRESSED明确禁止重新压缩或改写未报错段落。MAX_RETRIES 2。最后一次失败时脚本把原始字节原样写回、删除备份并报告错误源文件保持未动。写入——所有写入均走原子替换路径 write_bytes_atomic()先mkstemp建同目录临时文件、写字节、fsync、再os.replace覆盖目标并保留原文件权限位。这样即使中途编码失败目标文件也只会「从一个完整有效文件跳到另一个」绝不出现半截写入。这里有个值得注意的细节SKILL.md说「若校验失败后仍失败就报告用户并保持源文件不动」而实现里实际上分为两步——第一步把备份写盘后先做一次备份回读字节比对不一致就直接中止且不触碰源文件compress.py然后才覆盖源文件进入校验循环校验彻底失败时再恢复原始字节并删除备份compress.py。也就是说「先保全再改写最后回滚」数据安全优先。四、可压缩与不可压缩的边界检测器的判定规则SKILL.md 的「Boundaries」一节划出了文件边界detect.py是它的代码化实现允许压缩自然语言类型判定.md、.txt、.markdown、.rst、.typ、.typst、.tex可压缩无扩展名但内容判定为自然语言如TODO可压缩需内容启发式通过*.original.md备份文件永远跳过禁止压缩代码 / 配置.py、.js、.ts、.tsx、.jsx、.json、.yaml、.yml、.toml、.env、.lock、.css、.scss、.html、.xml、.sql、.sh、.go、.rs、.java等均定义于 COMPRESSIBLE_EXTENSIONS / SKIP_EXTENSIONS。边界判断还有几层额外兜底来自 detect.py无扩展名的已知代码文件名单KNOWN_CODE_FILENAMESDockerfile、Makefile、Jenkinsfile、Gemfile、Justfile、Procfile、CMakeLists.txt等。原因很实际——Dockerfile没有后缀.dockerfile规则匹配不到它而CMakeLists.txt会误搭.txt顺风车。扩展名缺失时的内容启发式shebang#!判定为代码前 10KB 能解析为 JSON 判为 config前 30 行 YAML 特征占比超过 60% 判为 config前 50 行中超过 40% 命中CODE_PATTERNSimport/def/class/function/JSON 键值对/赋值字面量等判为 code。.original.md后缀直接排除保证永远不会对备份再压缩。对混合内容文件散文 代码规则明确只压缩散文段把代码段当作只读区域且不得围绕代码合并相邻章节。检测阶段无法确定某行属于代码还是散文时保持原样。五、校验器让「该保留的」一个都不能少SKILL.md 反复强调「Preserve EXACTLY」而真正守住这条底线的是压缩后自动运行的校验器validate(original_path, compressed_path)。它不消耗任何 token把备份原始内容与当前压缩文件逐项比对校验项规则处置标题validate_headings标题数量、标题文本与顺序必须完全一致文本/顺序改动 error会破坏文档内锚点链接仅级别变化 warningslug 不变链接仍有效代码块validate_code_blocks围栏代码块与 4 空格缩进代码块逐字节相等不等 errorURLvalidate_urlshttp(s)://...集合一致丢失或新增 error文件路径validate_paths以./..//盘符开头或带点号尾名的「确定路径」不能丢硬性丢失 error模糊差异 warning项目符号validate_bullets符号数量变化超过 15%warning行内代码validate_inline_codes反引号内联代码按 Counter 计数一致丢失 error新增 warningvalidate_paths值得一提路径正则是有意「粗略」的普通散文里的pros/cons、Node/browser这类带斜杠的组合也可能被匹配到因此只有无歧义路径前导./、../、/、盘符或末段是name.ext带点号文件名丢失才报 error其余只降级为 warning——见 validate.py 的注释。为什么校验要做到 error 级别源码注释里给出了惨痛教训式的理由4 空格缩进代码块如果不单独抽取校验kubectl delete pod --all -n prod这类命令会被散文判定逻辑漏掉出现「干净通过校验但命令已被悄悄改写」的假阳性——那将直接覆盖用户文件是这类工具最恶劣的失败模式validate.py。校验只产生 error/warning不直接改文件真正触发「定点修复 重试」循环的是 error 列表这在第三节的执行链中已说明。六、压缩规则删什么、保什么、怎么改SKILL.md 的「Compression Rules」是本技能的语言学核心按「删 / 保 / 改」三层组织逐条如下。6.1 Remove这些词删掉冠词a、an、the填充词just、really、basically、actually、simply、essentially、generally客套语sure、certainly、of course、happy to、Id recommend模糊兜底it might be worth、you could consider、it would be good to冗余措辞改写in order to→tomake sure to→ensurethe reason is because→because连接性水分however、furthermore、additionally、in addition6.2 Preserve EXACTLY绝不改动围栏代码块与缩进代码块行内代码反引号...内容URL 与 Markdown 链接文件路径/src/components/...、./config.yaml命令npm install、git commit、docker build技术术语库名、API 名、协议名、算法名专有名词项目名、人名、公司名日期、版本号、数值环境变量$HOME、NODE_ENVCRITICAL RULE原文级强约束任何位于...之间的内容必须逐字节照抄——不删注释、不动空格、不重排行、不缩短命令、不做任何简化行内代码同理反引号内的任何字符都不得修改。若文件含代码块代码块一律视作只读区域仅压缩其外的文本且不得围绕代码合并段落。代码块保真在实现上还有更硬的一层保障压缩前脚本先用mask_code_blocks()把围栏块与 4 空格缩进块整体替换为CAVEMAN_PRESERVED_CODE_序号_哈希这样的不透明行标记让模型根本「看不到」代码原文压缩后restore_code_blocks()再把标记还原成原块并要求每个标记恰好出现一次——模型若移动、复制或改写任何代码块直接抛错并拒绝写入compress.py。相比单纯在提示词里叮嘱「别动代码」这种做法把保护从「模型自觉」升级成了「结构强制」。6.3 Preserve Structure结构骨架原样所有 Markdown 标题标题文本逐字保留只压缩标题下方的正文项目符号层级保留嵌套深度有序列表保留编号表格压缩单元格文字、保留表格结构Markdown 文件开头的 Frontmatter / YAML 头整体原样保留Frontmatter 的保真同样是工程化处理的split_frontmatter()compress.py在压缩前把---包裹的 YAML 头从输入中外科手术式剥离压缩完成后原样前缀回输出。原因见源码注释压缩模型在提示词强调保留结构的情况下仍习惯性改写或删除 frontmatter——干脆让它根本接触不到。顺带一提本技能自己的 SKILL.md 文件开头就带 YAML frontmatter它自身就是一个很好的观察样本。6.4 Compress正文怎么改用短同义词写big而非extensivefix而非implement a solution foruse而非utilize允许短语碎片Run tests before commit而非You should always run tests before committing去掉you should、make sure to、remember to直接陈述动作合并「换种说法表达同一意思」的冗余条目多个示例演示同一模式时只保留一个七、压缩前后的模式对照SKILL.md「Pattern」给出了两组原文与压缩结果的对照这里完整保留便于直观把握「信息量与 token 数」的取舍尺度。示例一原句You should always make sure to run the test suite before pushing any changes to the main branch. This is important because it helps catch bugs early and prevents broken builds from being deployed to production.压缩后Run tests before push to main. Catch bugs early, prevent broken prod deploys.示例二原句The application uses a microservices architecture with the following components. The API gateway handles all incoming requests and routes them to the appropriate service. The authentication service is responsible for managing user sessions and JWT tokens.压缩后Microservices architecture. API gateway route all requests to services. Auth service manage user sessions JWT tokens.注意第二例中技术名词microservices architecture、API gateway、JWT tokens均被原样保留改变的只是连接语和句子结构——与第六节「Preserve technical terms」规则吻合。实测收益来自仓库自身夹具skills/caveman-compress/README.md 记录了对 tests/caveman-compress 目录下 5 组真实夹具每组一份.md压缩稿 一份.original.md原文的实测结果文件原文 token压缩后 token节省claude-md-preferences.md70628559.6%project-notes.md114553553.3%claude-md-project.md112263643.3%todo-list.md62738838.1%mixed-with-code.md88856036.9%平均89848146%README 同时声明所有夹具的标题、代码块、URL、文件路径校验全部通过但该结果「不证明语义等价或任务质量等价」——即校验保证的是结构不损坏而非压缩稿能在任意任务上完全替代原文。mixed-with-code.md这类含代码的混合文件节省相对较低36.9%与「代码区域不可压缩」的边界规则相互印证。该数据可复算仓库提供了 benchmark.py用tiktoken的o200k_base编码计数无 tiktoken 时回退为词数对每对夹具跑同一套validate。以python3 -m scripts.benchmark或直接运行脚本即可复现上表。八、备份策略与「树外数据目录」的设计动机备份不放在源文件旁边是刻意的设计决定。如果CLAUDE.original.md与CLAUDE.md同目录Claude Code 等工具在扫描项目记忆文件时会把备份当活文件摄入白白为「已经压缩掉的原文」再次付 token——与压缩的目的背道而驰。所以备份落到平台相关的用户数据目录见第二节路径并由父目录名 文件 stem 构成键降低不同项目间碰撞概率。实现上有三点值得一提备份与压缩写入同样走原子写 回读校验备份先写盘并做字节级回读比对确认磁盘上确实落下了完整原文才允许碰源文件若备份已存在脚本直接中止以防覆盖旧的原始内容compress.py。严格 UTF-8 解码read_source()compress.py拒绝任何非 UTF-8 文件并给出可操作的错误信息——压缩是就地重写无法解码的字节会在这场往返中永久消失所以「读不准就不许写」。它还从原始字节中检测行尾CRLF/LF写入时原样还原避免把用户文件的换行风格全局改掉。锁目录/文件的反符号链接防护锁目录要求 0700 权限、锁文件以O_NOFOLLOW打开防止预先放置的符号链接把锁操作重定向到别处见 compress.py 注释。九、安全边界什么文件被「先拒后问」压缩的本质是「把文件内容发给第三方大模型 API」这决定了数据边界必须是显式的。除了第五、八节提到的边界与原子写还有一道敏感路径闸门is_sensitive_path()compress.py通过正则与路径组件命中对.env*、.netrc、credentials*、secret*、password*、id_rsa/authorized_keys/known_hosts、*.pem/*.key/*.p12/*.asc/*.gpg等文件以及.ssh、.aws、.gnupg、.kube、.docker及名字含secret/credential/token/apikey等令牌的目录一概硬性拒绝——即使这些文件扩展名恰好是.txt能通过自然语言筛选。误判时用户需改名后重试错误信息里会明确说明原因。skills/caveman-compress/SECURITY.md 对该技能被静态扫描工具Snyk标为 High Risk 的成因做了逐条澄清subprocess仅在未配置ANTHROPIC_API_KEY时以claude --print兜底参数列表固定、无 shell 插值、内容经 stdin 传入文件读写只碰用户指定的目标文件与树外备份目录明确不做的事不执行文件内容、除 Anthropic API 外不发网络请求、不访问用户指定路径以外的文件、不使用shellTrue或字符串拼接、除被压缩文件本身外不采集传输任何数据认证行为有ANTHROPIC_API_KEY走 SDK否则走claudeCLI 复用桌面登录态500KB 上限在发起任何 API 调用前生效。这些约束与仓库里 skills/caveman-compress/scripts/compress.py 的实际代码相互印证也与 SKILL.md 的 Process/压缩规则形成一致的「先拒绝、后压缩、再验证」安全策略。十、把技能接入项目安装与运行前提README 明确说明该技能随caveman插件内置安装一次 caveman 即可使用/caveman-compress无需单独安装。若需本地文件技能代码位于插件发布副本plugins/caveman/skills/caveman-compress/含本技能 SKILL.md 与scripts/仓库级本地副本skills/caveman-compress/SKILL.md、README.md、SECURITY.md、scripts/基准夹具tests/caveman-compress/下 5 组.md/.original.md对照对运行前提Python 3.10 及以上需要可用的 Claude 访问渠道Anthropic SDK 密钥或已登录的claudeCLI。可选环境变量CAVEMAN_MODEL默认claude-sonnet-4-5、ANTHROPIC_API_KEY。压缩由 Agent 依据 SKILL.md 的指引在包含scripts/的目录下以python3 -m scripts absolute_filepath方式执行若路径不可直接获得应先在本技能目录旁定位 scripts/main.py。结语一条「省 token」的工程化路径caveman-compress把「记忆文件太大导致每会话重复付 token」这个朴素痛点做成了一个有明确边界与自愈机制的工程方案自然语言散文交给模型压缩并接受结构校验代码与元数据靠屏蔽标记 校验器双重保护原始内容由树外原子备份兜底敏感文件在最前端被拒绝。它的价值不在于把压缩率吹得多高而在于压缩过程可验证、可回滚、绝不越界——对任何依赖CLAUDE.md这类常驻记忆文件、又在意长会话 token 成本的 Claude Code 工作流而言都是值得纳入日常工具箱的一环。【免费下载链接】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），仅供参考
caveman-compress 技能实战：把 CLAUDE.md 等记忆文件压缩成穴居人语法，降低每轮会话输入 Token
caveman-compress 技能实战把 CLAUDE.md 等记忆文件压缩成穴居人语法降低每轮会话输入 Token【免费下载链接】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-compress是 caveman 项目中的一个 Claude Code 技能skill核心思路一句话概括把每次会话都要加载的项目记忆文件CLAUDE.md、todo 清单、偏好说明从啰嗦的自然语言压缩成「穴居人式」短句从而降低每轮会话固定的输入 token 开销同时把可读的原始版本备份到项目目录之外、不会被技能自动加载器二次摄入的地方。阅读本文你将掌握如何触发/caveman-compress命令、它背后的「检测 → 压缩 → 校验 → 定点修复 → 重试」执行链、哪类内容会被原样保留、哪类文件被坚决跳过以及仓库源码层面对代码块保真、备份安全与敏感文件防护的实现细节。本技能的定义文档位于 plugins/caveman/skills/caveman-compress/SKILL.md同一份技能在仓库根目录另有本地副本 skills/caveman-compress/SKILL.mdskills/caveman-compress/README.md 声明本地副本位于skills/caveman-compress/。下文分析与阅读路径均以仓库相对路径给出。一、为什么记忆文件值得压缩每会话重复读入的 token 成本CLAUDE.md这类项目记忆文件会在每次会话启动时被 Claude 加载。文件越大每次开启项目就要为同样的内容重复支付一次输入 token。按仓库 README 的估算口径「一份 1,000 token 的项目记忆文件每打开一次项目就多消耗 1,000 输入 token100 次会话即 100,000」——这正是 skills/caveman-compress/README.md 中「Why This Matter」一节说明的动机模型。caveman-compress的解法不是删除信息而是改写自然语言部分去掉填充词、把长句改成短语、合并重复条目同时对代码、路径、URL 等「不能碰的内容」做字节级保真。它只处理自然语言文本天然适合CLAUDE.md、todo、偏好文件这类「散文 少量结构化内容」的混合文档。需要强调的是仓库实测的是结构化保真 token 计数下降。README 给出 5 组真实夹具的平均 token 节省约 46%详见下文第七节并明确说明这些数据「不证明语义等价或任务质量等价」——这是基于当前仓库内容的准确表述不应夸大为普适的压缩率承诺。二、触发方式与基本使用技能的 YAML frontmatter 声明了两个触发途径Slash Command/caveman-compress filepath自然语言意图当用户要求「压缩某个记忆文件」时由 Agent 触发用法与CLAUDE.md中说明一致形式为/caveman-compress filepath实际示例来自 README/caveman-compress CLAUDE.md /caveman-compress docs/preferences.md /caveman-compress todos.md整个流程会经历压缩后的文件就地覆盖原文件CLAUDE.md而人类可读的原版被保存为CLAUDE.original.md——注意它不会放在源文件旁边而是放进项目目录树之外的数据目录以免技能自动加载器把备份当成「活文件」再次摄入。备份目录规则macOS / Linux$XDG_DATA_HOME/caveman-compress/backups/parent-dir-name/Windows%LOCALAPPDATA%\caveman-compress\backups\parent-dir-name\若未设置XDG_DATA_HOMEPOSIX 环境实际回退到~/.local/share见 skills/caveman-compress/scripts/compress.py。想恢复可读版本时去该数据目录编辑*.original.md然后再次运行技能即可基于新内容重新压缩。三、一次压缩的完整执行链CLI 入口到写入回读SKILL.md 中「Process」一节描述了 CLI 的工作步骤。技能的 Python 实现位于scripts/与 SKILL.md 同级入口为python3 -m scripts absolute_filepath由 skills/caveman-compress/scripts/main.py 转发到cli.py的main()。调用链与关键源码对应如下前置检查不消耗 token——cli.py校验命令行参数个数、文件存在、是普通文件并做resolve()随后调用detect_file_type()与should_compress()做文件类型判定非自然语言文件直接跳过并退出退出码 0出错返回非零。CLI 在启动阶段还对stdout/stderr强制reconfigure(encodingutf-8, errorsreplace)避免 Windows 默认 cp1252 控制台碰到 emoji 状态符时崩溃。安全与容量闸门——compress_file()在 compress.py 中先做三项互不依赖的快速拒绝文件不存在、超过 500KB 上限MAX_FILE_SIZE 500_000、命中敏感路径名单。这三项检查刻意放在加锁之前执行避免一次被拒的调用在共享状态目录留下永久锁文件。跨会话文件锁——file_lock() 使用操作系统原生文件锁POSIX 用fcntl.flockWindows 用msvcrt.locking锁路径是(parent-dir-name, stem)身份经 SHA-256 摘要后生成的.lock文件。崩溃或被杀掉的进程会自动释放锁无需手工清理陈旧标记。等待上限LOCK_WAIT_SECONDS 90015 分钟超过则抛出LockTimeoutError让用户重试。类型检测无 token——由 detect.py 完成返回natural_language / code / config / unknown四种分类详见下文第四节。Claude 压缩消耗一次调用——见 call_claude()优先使用 Anthropic Python SDK设置了ANTHROPIC_API_KEY时模型取环境变量CAVEMAN_MODEL默认claude-sonnet-4-5max_tokens8192未设置密钥时回退到claude --printCLI复用桌面端已有登录态并且固定参数列表、文件内容经 stdin 传入而非 shell 参数。校验输出无 token——由 validate.py 对「备份 vs 压缩结果」做结构化比对详见下文第五节。出错则定点修复、最多重试 2 次——校验失败后构造build_fix_prompt()compress.py只针对错误清单做补丁式修复如把 ORIGINAL 中缺失的 URL / 代码块 / 标题原文精确补回 COMPRESSED明确禁止重新压缩或改写未报错段落。MAX_RETRIES 2。最后一次失败时脚本把原始字节原样写回、删除备份并报告错误源文件保持未动。写入——所有写入均走原子替换路径 write_bytes_atomic()先mkstemp建同目录临时文件、写字节、fsync、再os.replace覆盖目标并保留原文件权限位。这样即使中途编码失败目标文件也只会「从一个完整有效文件跳到另一个」绝不出现半截写入。这里有个值得注意的细节SKILL.md说「若校验失败后仍失败就报告用户并保持源文件不动」而实现里实际上分为两步——第一步把备份写盘后先做一次备份回读字节比对不一致就直接中止且不触碰源文件compress.py然后才覆盖源文件进入校验循环校验彻底失败时再恢复原始字节并删除备份compress.py。也就是说「先保全再改写最后回滚」数据安全优先。四、可压缩与不可压缩的边界检测器的判定规则SKILL.md 的「Boundaries」一节划出了文件边界detect.py是它的代码化实现允许压缩自然语言类型判定.md、.txt、.markdown、.rst、.typ、.typst、.tex可压缩无扩展名但内容判定为自然语言如TODO可压缩需内容启发式通过*.original.md备份文件永远跳过禁止压缩代码 / 配置.py、.js、.ts、.tsx、.jsx、.json、.yaml、.yml、.toml、.env、.lock、.css、.scss、.html、.xml、.sql、.sh、.go、.rs、.java等均定义于 COMPRESSIBLE_EXTENSIONS / SKIP_EXTENSIONS。边界判断还有几层额外兜底来自 detect.py无扩展名的已知代码文件名单KNOWN_CODE_FILENAMESDockerfile、Makefile、Jenkinsfile、Gemfile、Justfile、Procfile、CMakeLists.txt等。原因很实际——Dockerfile没有后缀.dockerfile规则匹配不到它而CMakeLists.txt会误搭.txt顺风车。扩展名缺失时的内容启发式shebang#!判定为代码前 10KB 能解析为 JSON 判为 config前 30 行 YAML 特征占比超过 60% 判为 config前 50 行中超过 40% 命中CODE_PATTERNSimport/def/class/function/JSON 键值对/赋值字面量等判为 code。.original.md后缀直接排除保证永远不会对备份再压缩。对混合内容文件散文 代码规则明确只压缩散文段把代码段当作只读区域且不得围绕代码合并相邻章节。检测阶段无法确定某行属于代码还是散文时保持原样。五、校验器让「该保留的」一个都不能少SKILL.md 反复强调「Preserve EXACTLY」而真正守住这条底线的是压缩后自动运行的校验器validate(original_path, compressed_path)。它不消耗任何 token把备份原始内容与当前压缩文件逐项比对校验项规则处置标题validate_headings标题数量、标题文本与顺序必须完全一致文本/顺序改动 error会破坏文档内锚点链接仅级别变化 warningslug 不变链接仍有效代码块validate_code_blocks围栏代码块与 4 空格缩进代码块逐字节相等不等 errorURLvalidate_urlshttp(s)://...集合一致丢失或新增 error文件路径validate_paths以./..//盘符开头或带点号尾名的「确定路径」不能丢硬性丢失 error模糊差异 warning项目符号validate_bullets符号数量变化超过 15%warning行内代码validate_inline_codes反引号内联代码按 Counter 计数一致丢失 error新增 warningvalidate_paths值得一提路径正则是有意「粗略」的普通散文里的pros/cons、Node/browser这类带斜杠的组合也可能被匹配到因此只有无歧义路径前导./、../、/、盘符或末段是name.ext带点号文件名丢失才报 error其余只降级为 warning——见 validate.py 的注释。为什么校验要做到 error 级别源码注释里给出了惨痛教训式的理由4 空格缩进代码块如果不单独抽取校验kubectl delete pod --all -n prod这类命令会被散文判定逻辑漏掉出现「干净通过校验但命令已被悄悄改写」的假阳性——那将直接覆盖用户文件是这类工具最恶劣的失败模式validate.py。校验只产生 error/warning不直接改文件真正触发「定点修复 重试」循环的是 error 列表这在第三节的执行链中已说明。六、压缩规则删什么、保什么、怎么改SKILL.md 的「Compression Rules」是本技能的语言学核心按「删 / 保 / 改」三层组织逐条如下。6.1 Remove这些词删掉冠词a、an、the填充词just、really、basically、actually、simply、essentially、generally客套语sure、certainly、of course、happy to、Id recommend模糊兜底it might be worth、you could consider、it would be good to冗余措辞改写in order to→tomake sure to→ensurethe reason is because→because连接性水分however、furthermore、additionally、in addition6.2 Preserve EXACTLY绝不改动围栏代码块与缩进代码块行内代码反引号...内容URL 与 Markdown 链接文件路径/src/components/...、./config.yaml命令npm install、git commit、docker build技术术语库名、API 名、协议名、算法名专有名词项目名、人名、公司名日期、版本号、数值环境变量$HOME、NODE_ENVCRITICAL RULE原文级强约束任何位于...之间的内容必须逐字节照抄——不删注释、不动空格、不重排行、不缩短命令、不做任何简化行内代码同理反引号内的任何字符都不得修改。若文件含代码块代码块一律视作只读区域仅压缩其外的文本且不得围绕代码合并段落。代码块保真在实现上还有更硬的一层保障压缩前脚本先用mask_code_blocks()把围栏块与 4 空格缩进块整体替换为CAVEMAN_PRESERVED_CODE_序号_哈希这样的不透明行标记让模型根本「看不到」代码原文压缩后restore_code_blocks()再把标记还原成原块并要求每个标记恰好出现一次——模型若移动、复制或改写任何代码块直接抛错并拒绝写入compress.py。相比单纯在提示词里叮嘱「别动代码」这种做法把保护从「模型自觉」升级成了「结构强制」。6.3 Preserve Structure结构骨架原样所有 Markdown 标题标题文本逐字保留只压缩标题下方的正文项目符号层级保留嵌套深度有序列表保留编号表格压缩单元格文字、保留表格结构Markdown 文件开头的 Frontmatter / YAML 头整体原样保留Frontmatter 的保真同样是工程化处理的split_frontmatter()compress.py在压缩前把---包裹的 YAML 头从输入中外科手术式剥离压缩完成后原样前缀回输出。原因见源码注释压缩模型在提示词强调保留结构的情况下仍习惯性改写或删除 frontmatter——干脆让它根本接触不到。顺带一提本技能自己的 SKILL.md 文件开头就带 YAML frontmatter它自身就是一个很好的观察样本。6.4 Compress正文怎么改用短同义词写big而非extensivefix而非implement a solution foruse而非utilize允许短语碎片Run tests before commit而非You should always run tests before committing去掉you should、make sure to、remember to直接陈述动作合并「换种说法表达同一意思」的冗余条目多个示例演示同一模式时只保留一个七、压缩前后的模式对照SKILL.md「Pattern」给出了两组原文与压缩结果的对照这里完整保留便于直观把握「信息量与 token 数」的取舍尺度。示例一原句You should always make sure to run the test suite before pushing any changes to the main branch. This is important because it helps catch bugs early and prevents broken builds from being deployed to production.压缩后Run tests before push to main. Catch bugs early, prevent broken prod deploys.示例二原句The application uses a microservices architecture with the following components. The API gateway handles all incoming requests and routes them to the appropriate service. The authentication service is responsible for managing user sessions and JWT tokens.压缩后Microservices architecture. API gateway route all requests to services. Auth service manage user sessions JWT tokens.注意第二例中技术名词microservices architecture、API gateway、JWT tokens均被原样保留改变的只是连接语和句子结构——与第六节「Preserve technical terms」规则吻合。实测收益来自仓库自身夹具skills/caveman-compress/README.md 记录了对 tests/caveman-compress 目录下 5 组真实夹具每组一份.md压缩稿 一份.original.md原文的实测结果文件原文 token压缩后 token节省claude-md-preferences.md70628559.6%project-notes.md114553553.3%claude-md-project.md112263643.3%todo-list.md62738838.1%mixed-with-code.md88856036.9%平均89848146%README 同时声明所有夹具的标题、代码块、URL、文件路径校验全部通过但该结果「不证明语义等价或任务质量等价」——即校验保证的是结构不损坏而非压缩稿能在任意任务上完全替代原文。mixed-with-code.md这类含代码的混合文件节省相对较低36.9%与「代码区域不可压缩」的边界规则相互印证。该数据可复算仓库提供了 benchmark.py用tiktoken的o200k_base编码计数无 tiktoken 时回退为词数对每对夹具跑同一套validate。以python3 -m scripts.benchmark或直接运行脚本即可复现上表。八、备份策略与「树外数据目录」的设计动机备份不放在源文件旁边是刻意的设计决定。如果CLAUDE.original.md与CLAUDE.md同目录Claude Code 等工具在扫描项目记忆文件时会把备份当活文件摄入白白为「已经压缩掉的原文」再次付 token——与压缩的目的背道而驰。所以备份落到平台相关的用户数据目录见第二节路径并由父目录名 文件 stem 构成键降低不同项目间碰撞概率。实现上有三点值得一提备份与压缩写入同样走原子写 回读校验备份先写盘并做字节级回读比对确认磁盘上确实落下了完整原文才允许碰源文件若备份已存在脚本直接中止以防覆盖旧的原始内容compress.py。严格 UTF-8 解码read_source()compress.py拒绝任何非 UTF-8 文件并给出可操作的错误信息——压缩是就地重写无法解码的字节会在这场往返中永久消失所以「读不准就不许写」。它还从原始字节中检测行尾CRLF/LF写入时原样还原避免把用户文件的换行风格全局改掉。锁目录/文件的反符号链接防护锁目录要求 0700 权限、锁文件以O_NOFOLLOW打开防止预先放置的符号链接把锁操作重定向到别处见 compress.py 注释。九、安全边界什么文件被「先拒后问」压缩的本质是「把文件内容发给第三方大模型 API」这决定了数据边界必须是显式的。除了第五、八节提到的边界与原子写还有一道敏感路径闸门is_sensitive_path()compress.py通过正则与路径组件命中对.env*、.netrc、credentials*、secret*、password*、id_rsa/authorized_keys/known_hosts、*.pem/*.key/*.p12/*.asc/*.gpg等文件以及.ssh、.aws、.gnupg、.kube、.docker及名字含secret/credential/token/apikey等令牌的目录一概硬性拒绝——即使这些文件扩展名恰好是.txt能通过自然语言筛选。误判时用户需改名后重试错误信息里会明确说明原因。skills/caveman-compress/SECURITY.md 对该技能被静态扫描工具Snyk标为 High Risk 的成因做了逐条澄清subprocess仅在未配置ANTHROPIC_API_KEY时以claude --print兜底参数列表固定、无 shell 插值、内容经 stdin 传入文件读写只碰用户指定的目标文件与树外备份目录明确不做的事不执行文件内容、除 Anthropic API 外不发网络请求、不访问用户指定路径以外的文件、不使用shellTrue或字符串拼接、除被压缩文件本身外不采集传输任何数据认证行为有ANTHROPIC_API_KEY走 SDK否则走claudeCLI 复用桌面登录态500KB 上限在发起任何 API 调用前生效。这些约束与仓库里 skills/caveman-compress/scripts/compress.py 的实际代码相互印证也与 SKILL.md 的 Process/压缩规则形成一致的「先拒绝、后压缩、再验证」安全策略。十、把技能接入项目安装与运行前提README 明确说明该技能随caveman插件内置安装一次 caveman 即可使用/caveman-compress无需单独安装。若需本地文件技能代码位于插件发布副本plugins/caveman/skills/caveman-compress/含本技能 SKILL.md 与scripts/仓库级本地副本skills/caveman-compress/SKILL.md、README.md、SECURITY.md、scripts/基准夹具tests/caveman-compress/下 5 组.md/.original.md对照对运行前提Python 3.10 及以上需要可用的 Claude 访问渠道Anthropic SDK 密钥或已登录的claudeCLI。可选环境变量CAVEMAN_MODEL默认claude-sonnet-4-5、ANTHROPIC_API_KEY。压缩由 Agent 依据 SKILL.md 的指引在包含scripts/的目录下以python3 -m scripts absolute_filepath方式执行若路径不可直接获得应先在本技能目录旁定位 scripts/main.py。结语一条「省 token」的工程化路径caveman-compress把「记忆文件太大导致每会话重复付 token」这个朴素痛点做成了一个有明确边界与自愈机制的工程方案自然语言散文交给模型压缩并接受结构校验代码与元数据靠屏蔽标记 校验器双重保护原始内容由树外原子备份兜底敏感文件在最前端被拒绝。它的价值不在于把压缩率吹得多高而在于压缩过程可验证、可回滚、绝不越界——对任何依赖CLAUDE.md这类常驻记忆文件、又在意长会话 token 成本的 Claude Code 工作流而言都是值得纳入日常工具箱的一环。【免费下载链接】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），仅供参考
