1实现原理 · 为什么它能做到
这是本批里少见的「有真代码」的 skill：SKILL.md 的核心指令只有一条——在 SKILL.md 所在目录执行 `python3 -m scripts <绝对路径>`，全部压缩逻辑在自带的 Python 包里。
skills/caveman-compress/SKILL.md
The compression scripts live in `scripts/` (adjacent to this SKILL.md). If the path is not immediately available, search for `scripts/__main__.py` next to this SKILL.md. 2. From the directory containing this SKILL.md, run: python3 -m scripts <absolute_filepath>
注：这里在做什么：把「LLM 压缩」包成一条可重跑的 CLI。scripts/__main__.py 只有两行（from .cli import main; main()），cli.py 做参数/存在性/类型检查后调 compress.py 的 compress_file()。
压缩动作是把文件正文送去 Claude：优先走 Anthropic SDK（需 ANTHROPIC_API_KEY），否则退化为本地 `claude --print` CLI 子进程（用用户桌面认证）。
skills/caveman-compress/scripts/compress.py
api_key = os.environ.get("ANTHROPIC_API_KEY") if api_key: try: import anthropic client = anthropic.Anthropic(api_key=api_key, timeout=CLAUDE_CALL_TIMEOUT_SECONDS) msg = client.messages.create( model=os.environ.get("CAVEMAN_MODEL", "claude-sonnet-4-5"),
注：决定性证据：这是本 skill 唯一的网络出口。回退分支用固定参数表、stdin 传 prompt，无 shell 参与——claude_bin = shutil.which("claude") or "claude"，args 为 [claude_bin, "--print", "--setting-sources", "", "--strict-mcp-config"]。模型可用 CAVEMAN_MODEL 覆盖，默认 claude-sonnet-4-5；单次调用超时 = LOCK_WAIT_SECONDS/(MAX_RETRIES+1) = 300s。
代码块在送模型前被替换成不可解读的标记，回来后按「每个标记恰好出现一次」恢复，否则整体拒绝写入——这是防止「压缩把命令改坏」的核心机制。
skills/caveman-compress/scripts/compress.py
def restore_code_blocks(text: str, blocks: List[Tuple[str, str]]) -> str: """Restore markers exactly; fail closed if model removed, copied, or altered one."""
注：标记形如 @@CAVEMAN_PRESERVED_CODE_<n>_<sha256前16位>@@（CODE_MARKER_PREFIX）；输入本身含该前缀则直接 ValueError；恢复后仍残留未知标记也拒绝。模型对代码块只有一个「原样搬运」的动作，改不了内容。
写完不算完：另有一套结构性校验器（validate.py）比对原文与压缩稿的标题、代码块、URL、路径、项目符号、行内代码，失败则带着错误清单再请 Claude「只修列出的错误」并重试，最多 2 次。
skills/caveman-compress/scripts/validate.py
validate_headings(orig, comp, result) validate_code_blocks(orig, comp, result) validate_urls(orig, comp, result) validate_paths(orig, comp, result) validate_bullets(orig, comp, result) validate_inline_codes(orig, comp, result)
注：校验极细：标题文本变化算 error（因为会打断文内锚点链接），仅层级变化算 warning；缩进 4 空格的代码块也要比对（注释里举了反例：`kubectl delete pod --all -n prod` 被改成 `-n dev` 却通过校验，会直接覆盖用户文件）。压缩稿先写成 <file>.caveman-staged 校验通过后才覆盖真身。
写入是「先备份、回读校验、原子替换、保留权限位与换行风格」的一条链，多处是为修历史数据丢失事故而写的。
skills/caveman-compress/scripts/compress.py
write_bytes_atomic(backup_path, original_raw) if backup_path.read_bytes() != original_raw: print(f"❌ Backup write verification failed: {backup_path}")
注：备份是字节级原样副本（不是重渲染），且备份成功后还要读回比对；write_bytes_atomic 走 mkstemp+fsync+os.replace 并保留原权限位（注释点名 issue #655 的 0 字节事故）；read_source 严格 UTF-8 解码，非 UTF-8 直接拒绝（issue #686），并按多数行判定 CRLF/LF 原样写回（issue #762）。
有硬性输入闸门：文件 >500KB 拒绝、疑似凭证/密钥的文件名拒绝、空文件拒绝、已有备份则中止（防覆盖）。
skills/caveman-compress/scripts/compress.py
MAX_FILE_SIZE = 500_000 # 500KB
注：敏感名 denylist（SENSITIVE_BASENAME_REGEX）覆盖 .env*、.netrc、credentials*、secret(s)*、password(s)*、id_rsa/ed25519、authorized_keys、*.pem/key/p12/pfx/crt/cer/jks/keystore/asc/gpg；另有路径组件与名字 token 归一化匹配（.ssh/.aws/.gnupg/.kube/.docker、api-keys → apikeys 等）。注释直言理由：'Compressing them ships raw bytes to the Anthropic API — a third-party data boundary'。
并发用 OS 原生文件锁（POSIX fcntl.flock / Windows msvcrt.locking），锁键 = 备份路径的 sha256 前 16 位；不支持锁的文件系统降级为「无协调继续跑」，锁目录/锁文件遇到符号链接直接拒绝。
skills/caveman-compress/scripts/compress.py
return _state_base_dir("locks") / f"{digest}.lock"
注：LOCK_WAIT_SECONDS = 900（注释说明必须长于最坏运行：MAX_RETRIES+1 次调用 × 单次 300s）；EOPNOTSUPP/ENOSYS 视为「文件系统不支持」并打印告警后继续，ENOLCK 被刻意排除（注释解释它可能是瞬时锁记录耗尽，误判会导致真争用时无锁运行）。
非膨胀不变量：压缩结果按「去掉 frontmatter 的正文」比较，必须严格更短，否则中止且不动原文件；这条对修复路径也成立。
skills/caveman-compress/scripts/compress.py
if not _is_smaller_than_body(compressed_body, body): print(" Original file is untouched (no backup created).") return False
注：注释点名 issue #776：旧版只校验结构，一个更长的「压缩」也能通过校验并覆盖原文。frontmatter 单独剥离后逐字拼回（模型爱改 frontmatter）。
可压缩范围由 detect.py 的扩展名白名单/黑名单 + 仅对无扩展名文件的内容嗅探决定，.original.md 备份永不二次压缩。
skills/caveman-compress/scripts/detect.py
COMPRESSIBLE_EXTENSIONS = {".md", ".mdc", ".txt", ".markdown", ".rst", ".typ", ".typst", ".tex"}
注：SKIP_EXTENSIONS 覆盖 py/js/ts/json/yaml/toml/env/lock/css/html/go/sh 等；无扩展名时先看 shebang（→code）、JSON/YAML 嗅探（→config）、代码行占比 >40%（→code），否则 natural_language。COMMENT 说明：不在两个白/黑名单上的扩展名一律 unknown、永不压缩（fail-closed）。
2核心能力
01把自然语言记忆文件（CLAUDE.md / todo / preferences）原地压成 caveman 文风，减少每次会话的输入 token
02代码块/行内代码/URL/路径/标题/列表结构的「逐字保留」契约（掩码 + 校验双保险）
03自动备份到源目录之外（$XDG_DATA_HOME/caveman-compress/backups/<parent-dir-name>/，Windows 走 %LOCALAPPDATA%），避免被 skill 自动加载器二次读入
04失败安全：校验不过 → 定向修复重试 ≤2 次 → 仍不过则报错并保持原文件不变（连备份也删掉）
05预拒绝敏感文件：疑似凭证/密钥/PII 的文件名在读取前就被拒（不发送任何字节给第三方 API）
06并发安全：同一目标文件的跨会话互斥（OS 原生锁 + 900s 等待 + 超时给明确提示）
07兼容性细节：CRLF/LF 原样保留、权限位保留、原子写（避免中断留下 0 字节文件）、严格 UTF-8 拒绝而非静默丢弃字节
08附带基准工具：benchmark.py 用 tiktoken（可选装）对 original/compressed 配对算 token 节省率并跑同一套校验
3外部依赖
| 类型 | 依赖 |
|---|---|
| api | Anthropic Messages API（经 anthropic Python SDK） |
| cli | claude CLI（Claude Code / Claude desktop 认证） |
| package | anthropic（Python SDK，可选） |
| package | tiktoken（可选，仅 benchmark.py） |
| cli | python3（运行时不带第三方依赖；仅标准库 contextlib/errno/hashlib/os/re/shutil/stat/subprocess/tempfile/time/pathlib，Windows 用 msvcrt、POSIX 用 fcntl） |
4风险提醒 风险提醒：橙色 · 评估后使用
风险提醒：橙色 · 评估后使用
- 文件正文外发第三方模型 API（数据边界） — 压缩必须把文件原文送给 Anthropic（SDK 或 claude CLI）。记忆文件（CLAUDE.md、项目笔记）常含内部约定、路径、乃至业务信息；敏感文件名 denylist 只能拦住名字可疑者，正文里的秘密不会被拦。Snyk 亦给出 High Risk 评级（其 SECURITY.md 自承此项）。企业对代码/文档外发有合规要求时需先评估。
- 原地覆盖用户文件 — 默认行为是用压缩稿覆盖原文件（备份在 out-of-tree 数据目录）。虽有备份、暂存校验、原子写与失败回滚，但备份存在与否是「覆盖后唯一退路」，且 backup_path 已存在时会直接中止（防覆盖旧备份）——用户若清理过该目录，历史原始稿即不可恢复。
- 语义层面无校验，只有结构校验 — validate.py 保证标题/代码块/URL/路径/列表/行内代码不变，但不保证正文语义不被误改（常识性事实、数字、语气都可能被模型改写）。压缩「记忆文件」等同于让模型重写你的记忆。
- 依赖宿主环境的 CLI 与凭证 — 无 API key 时依赖本机 claude CLI 及其桌面认证；Windows 下曾出现解码问题（issue #152），说明回退路径的平台假设较脆弱；CAVEMAN_MODEL 可被环境覆盖，指向非预期模型时行为与默认不同。
- 启发式 denylist 可被改名绕过 — is_sensitive_path 是文件名/路径正则与 token 匹配，用户若把凭证文件改名（如 prod-notes.md）即会放行——注释中明确把 override 设计为「用户改名」而非「加 --force」，即有意不做交互式确认。
风险提醒：橙色，评估后使用。理由：① 执行自带 Python 脚本并触发子进程；② 读取 ANTHROPIC_API_KEY 环境变量（凭证面）；③ 把文件原文发送至第三方模型 API（Anthropic，外部数据边界，本 skill 自己的注释也称其为 'third-party data boundary'）；④ 原地覆盖用户文件（虽有备份、原子写与校验）。可选依赖为远程包（anthropic、tiktoken）。降档因素（未降至黄/绿）：无 shell=True 拼接、参数固定、有敏感名预拒绝、备份回读校验、非膨胀不变量、失败即回滚；其自带 SECURITY.md 亦承认 Snyk 给出 High Risk 评级。触发条件：仅当用户显式调用 /caveman-compress 或要求压缩某个记忆文件时才发生上述行为。
5第二遍独立确认
- [ok] SKILL.md 提到的脚本路径与运行方式 — `python3 -m scripts <file>` 成立：scripts/__main__.py 导入 cli.main 并调用；cli.py 校验参数个数与文件存在/类型后执行 compress_file。SKILL.md 提示的 'search for scripts/__main__.py' 与实际文件名一致。
- [ok] Anthropic 为唯一网络出口 — 六个脚本中无 urllib/requests/socket/curl/wget 命中；网络仅经 anthropic SDK client.messages.create 或 claude CLI 子进程。SDK 端点在源码中未硬编码，故 external_deps.endpoint 留空（不臆测）。
- [ok] 「subprocess 无 shell 注入」这一说法 — subprocess.run([claude_bin, "--print", "--setting-sources", "", "--strict-mcp-config"], input=prompt, ...) 为列表参数 + stdin，无 shell=True；SECURITY.md 亦声明 'Does not use shell=True or string interpolation in subprocess calls'。
- [ok] 「备份在源目录之外」是否属实（SKILL.md / Purpose 段） — backup_dir_for() 返回 _state_base_dir("backups")/filepath.parent.name，其中 _state_base_dir 为 $XDG_DATA_HOME/caveman-compress 或 ~/.local/share/caveman-compress（Windows 用 %LOCALAPPDATA%），确实不在源文件旁；注释给出理由（skill auto-loader 会二次读入 .original.md）。
- [ok] 敏感文件拒绝覆盖面的自评（第一遍称「覆盖 .env/credentials/密钥」） — 逐条核对 SENSITIVE_BASENAME_REGEX 与 SENSITIVE_PATH_COMPONENTS/SENSITIVE_NAME_TOKENS：.env*、.netrc、credentials*、secret(s)*、password(s)*、id_rsa/dsa/ecdsa/ed25519(.pub)、authorized_keys、known_hosts、*.pem|key|p12|pfx|crt|cer|jks|keystore|asc|gpg；路径组件含 .ssh/.aws/.gnupg/.kube/.docker 与 credential(s)/secret(s)；名字 token 含 secret/credential/password/passwd/apikey/accesskey/token/privatekey。属启发式 denylist（可被改名绕过），已在 analysis 注记，未夸大。
- [ok] 固定大小上限 500KB — compress_file 内 MAX_FILE_SIZE = 500_000 且在任何 API 调用之前检查；SECURITY.md 亦声明 'Files larger than 500KB are rejected before any API call is made'。
- [ok] 「校验不过则原文件不动」 — 压缩候选先写 <file>.caveman-staged 并对其跑 validate；只有 is_valid 才 _write_target(filepath, ...)，两次重试用尽后 unlink 暂存与备份并打印 'Failed after retries: original left untouched'。
- [ok] SKILL.md 压缩规则 vs 脚本提示词是否一致（有无文档吹牛） — SKILL.md 的 Remove/Preserve/Compress 规则与 build_compress_prompt 的 STRICT RULES 同向（保代码块、保行内代码、保 URL、保标题、保路径命令），脚本还把「不要给整体套一层 ```markdown 围栏」写进提示词，并有 strip_llm_wrapper 兜底剥离。无夸大。
6结论
适合：适合把 CLAUDE.md / todo / preferences 这类「每次会话都被读入」的记忆文件长期维护、且接受内容经由 Anthropic API 处理的团队或个人；尤其适合已经用 caveman 系（省 token）并希望把「输入侧」也压下来的用户。对反复迭代同一文件的场景，out-of-tree 备份 + 非膨胀不变量显著降低「越压越乱」的风险。
不适合：不适合：① 含凭证/客户数据/受合规约束内容的文件（正文外发第三方 API 不可控）；② 没有 Anthropic 凭证或 claude CLI 的环境（脚本会失败）；③ 期望「语义无损」压缩的人——它只保结构；④ 压缩代码/配置文件（白名单外一律拒）；⑤ 超过 500KB 的文档。另注意仅当显式 /caveman-compress 时触发，不会自动压文件。
安装 agent 直装可复制
① 本站镜像 更新 2026-09-15
方式 A · 人下载镜像包下载 caveman-compress.tar.gz
sha256:
方式 B · JSON 格式安装指南，复制给 agent52e12dda463f9c55…agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
② 上游 GitHub · 原始来源
来源信息 GitHub 原始
作者 / 仓库juliusbrussee / juliusbrussee/caveman
原始 GitHubjuliusbrussee/caveman ↗
Stars105691
最近推送2026-09-15
本 skill commit
15581d1400许可MIT（LICENSING.md 表格：`skills/` | MIT | Existing Caveman skill stays MIT and untouched.）。仓库为拆分授权：engine/ proxy/ rewriter/ browse/ mcp/ shrink/ 等 Engine-linked 目录为 BSL-1.1（LICENSE.BSL）；GitHub API license.spdx_id = NOASSERTION。
本站信息
收录日期2026-09-06
分类基础工具与工作流
侦查报告AI 侦查 · 2 遍 · 2026-09-06
本站镜像与 GitHub 原始是不同来源：本站锁定 commit 快照经 /r2 分发；GitHub 为实时上游，内容可能已更新。