1. 项目目的与定位

caveman 是一个面向 Claude Code、Codex、Gemini CLI、Cursor、Windsurf、Cline、Copilot 等 30 余款 AI 编码代理的技能/插件合集，核心目标是在不损失技术准确性的前提下，把模型的输出 token 削减约 65–75%。仓库 README 用一句话概括其定位："Talk like smart caveman. Same brain, fewer tokens." 资料来源：README.md:1-15。

项目同时面向两类问题域：

• 输出压缩：通过 SKILL.md 系统提示约束模型在普通问答场景下使用"洞穴人风格"短句输出。资料来源：skills/caveman/README.md:1-12。
• 输入压缩：通过独立的 caveman-compress 技能对 CLAUDE.md、笔记、todo 等会被每轮自动加载的自然语言记忆文件做离线压缩，让每个会话启动时少读 token。资料来源：skills/caveman-compress/README.md:1-25。

2. 核心压缩原理

caveman 的压缩策略建立在"保形不保词"的原则上：技术内容必须逐字保留，语态外壳可以重写。规则层面主要分为三组——删除、保留、压缩——分别定义在不同组件中。

删除类规则（必须从原文中移除）：

• 冠词：a、an、the
• 填充词：just、really、basically、actually、simply、essentially、generally、quite、very、literally
• 客套语：please、kindly、thank you、thanks、sure、certainly
• 对冲词：perhaps、maybe、might、could potentially、would like to
• 引导句：I'll、I will、you can、we will、let me

资料来源：src/mcp-servers/caveman-shrink/compress.js:1-50 与 src/rules/caveman-activate.md:1-12。

保留类规则（任何情况下都不允许被改写）：

• 围栏代码块（`` ... `）和行内反引号（...`）必须按字节复制
• URL（https?://...）原样保留
• 文件系统路径（含 / 或 \）原样保留
• "代码形态" token：括号结尾、分号、JSON 类大括号、CamelCase / snake_case / dotted.path 标识符
• 标题文本、Markdown 列表层级、表格结构、Frontmatter
• 专有名词、人名、公司、日期、版本号、数值、环境变量

资料来源：skills/caveman-compress/SKILL.md:1-80 与 src/mcp-servers/caveman-shrink/compress.js:1-30。

压缩类规则（对保留之外的自然语言进行重写）：

• 使用短同义词：big 替代 extensive，fix 替代 implement a solution for，use 替代 utilize
• 允许使用碎片句："Run tests before commit" 替代 "You should always run tests before committing"
• 删除 you should、make sure to、remember to 这类指令软化词
• 合并语义重复的条目；多例同型时只留一例

资料来源：skills/caveman-compress/SKILL.md:60-80。

2.1 自动清晰规则（Auto-Clarity）

压缩并非全场景生效。系统提示规定，在以下情形自动回退到正常散文：安全警告、不可逆操作确认、用户重复追问、多步骤流程中碎片句可能产生歧义时。清晰部分结束后恢复压缩模式。资料来源：skills/caveman/README.md:14-22 与 src/rules/caveman-activate.md:1-12。

3. 压缩强度级别

caveman 提供六档强度，使用户可以根据场景在可读性与压缩率之间权衡：

资料来源：skills/caveman/README.md:8-22。

4. 架构与组件

caveman 是一个技能集合而非单一二进制，运行时按目标代理拆分为独立子包。下图展示了仓库主要组件及其相互关系：

graph TD
    A["SKILL.md 系统提示<br/>(caveman-activate.md)"] --> B["模型输出压缩<br/>~75% tokens"]
    C["caveman-compress 技能<br/>(Python CLI)"] --> D["离线文件压缩<br/>(CLAUDE.md/todos)"]
    E["caveman-shrink MCP<br/>(Node.js 代理)"] --> F["MCP 工具描述压缩"]
    G["cavecrew 子代理组"] --> H["子代理输出压缩"]
    I["caveman-commit"] --> J["提交信息压缩"]
    K["各平台安装器<br/>(Claude/Codex/Gemini/Cursor等)"] --> A
    K --> C
    K --> E
    K --> G
    K --> I

• 核心系统提示层：src/rules/caveman-activate.md 是注入到模型上下文的精简版规则集，用于约束实时输出。资料来源：src/rules/caveman-activate.md:1-12。
• 离线文件压缩层：caveman-compress 是一个 Python 包，对外暴露 cli、compress、detect、validate 四个模块（__all__ = ["cli", "compress", "detect", "validate"]，版本 1.0.0）。资料来源：skills/caveman-compress/scripts/__init__.py:1-12。压缩流程包含类型检测、调用 Claude 生成、输出验证、最多 2 次定向修复（cherry-pick fix）、失败时保留原文件。资料来源：skills/caveman-compress/SKILL.md:1-30。
• MCP 代理层：caveman-shrink 是一个 Node.js 实现的 MCP 代理，对工具描述等"安全字符串字段"做边界与 caveman-compress 完全一致的纯规则压缩（不调用模型）。资料来源：src/mcp-servers/caveman-shrink/compress.js:1-50 与 src/mcp-servers/caveman-shrink/package.json:1-30。注意：社区已记录该 MCP 注册时缺失上游命令导致每次加载失败的问题（issue #474），需在安装脚本中补充正确的 claude mcp add caveman-shrink -- npx -y caveman-shrink 配置。
• 子代理层：cavecrew 系列子代理（investigator/builder/reviewer）以紧凑输出契约替换 vanilla Explore/Code Reviewer，让子代理返回值占主线程上下文预算约为 1/3。资料来源：skills/cavecrew/SKILL.md:1-40。
• 提交信息层：caveman-commit 生成 ≤50 字符（硬上限 72）的 Conventional Commits 主题行，正文只在解释"为什么"时出现。资料来源：skills/caveman-commit/SKILL.md:1-30。

5. 社区关注的安全与边界

由于压缩过程涉及规则文件下载和 shell 安装，社区在 issue #528 中提出安全扫描对 caveman 标记了"高风险数据外泄"和"中风险路径遍历"。v1.9.0 已通过以下两项措施回应：

• curl|bash 和 detached 安装改为从不可变 v1.9.0 tag 下载 hook 文件，不再跟随 main 分支
• 每个 hook 文件在执行前对照 src/hooks/checksums.sha256 进行 SHA-256 校验，不匹配即中止安装

资料来源：v1.9.0 Release Notes。

此外，压缩规则天然具有语言敏感性——例如葡萄牙语（PT-BR）没有 the/a/an 这一类冠词系统，社区已经派生 Troglodita 作为葡萄牙语适配分支（issue #457），使用者在跨语言部署时需注意规则不可直接迁移。

See Also

• 安装与平台兼容
• caveman-compress 文件压缩流水线
• cavecrew 子代理输出契约
• caveman-shrink MCP 代理

概述与设计目标

caveman 项目的核心交付物是一组针对不同 AI 编程代理（agent）的"技能"（skill）——通过条件化模型输出，去除语法冗余以节省 token，同时保留所有技术细节。围绕这一核心能力，项目构建了一套多代理安装与分发系统，使同一套压缩规则能够以最小适配成本投送到 30 余款主流代理上。

项目的设计目标在三份主要文档中均有明确表述：让"大脑保持聪明，嘴巴保持简短"，并通过 lite、full、ultra 三个强度档位（wenyan-lite、wenyan-full、wenyan-ultra 为文言文变体）满足不同场景的压缩需求 README.md。分发系统须在不破坏各代理原生安装路径的前提下，把这些 SKILL.md、命令文件、钩子（hooks）以及 MCP 服务器正确写入目标环境。

安装器架构与分发流程

caveman 提供了多入口的安装路径，覆盖 npm、curl|bash、PowerShell 三类主流包管理与脚本执行场景：

• npm 入口：npx skills add JuliusBrussee/caveman -a <agent> 是最常用的安装命令，会被 npx 解析到仓库内的 bin/install.js 主入口 README.md。
• curl|bash 入口：通过 install.sh 一行脚本完成下载与分发。
• PowerShell 入口：irm https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.ps1 | iex 为 Windows 用户提供等价能力，但需注意 PSReadLine 的 $Args 变量优化会与脚本冲突（见下文故障排查）。

自 v1.9.0 起，curl|bash 与 detached 安装不再从 main 分支拉取钩子文件，而是固定从不可变的 v1.9.0 tag 下载，并在执行前对照 src/hooks/checksums.sha256 进行 SHA-256 完整性校验；任何校验失败都会中止安装 v1.9.0 发布说明。

下图展示从用户触发到各代理目录写入的端到端分发流程：

flowchart LR
    A[用户触发<br/>npx / curl / irm] --> B[入口脚本<br/>install.js / install.sh / install.ps1]
    B --> C{选择目标代理<br/>--only &lt;agent&gt;}
    C --> D[Claude Code]
    C --> E[OpenCode]
    C --> F[Gemini CLI]
    C --> G[Cursor / Windsurf / Cline]
    C --> H[IBM Bob / Codex / Copilot]
    B --> I[v1.9.0 完整性校验<br/>src/hooks/checksums.sha256]
    I --> J[写入 SKILL.md<br/>commands/* & hooks/*]
    D --> K[.claude/skills]
    E --> L[.config/opencode/commands]
    F --> M[extensions/caveman]
    G --> N[代理配置目录]

多代理插件矩阵

由于不同代理在文件约定、命令注册方式与钩子触发 API 上存在显著差异，分发系统为每款代理维护一份独立的插件清单。OpenCode 插件的命令文件直接暴露在仓库内，例如 caveman-compress.md 仅接受自然语言文件作为输入并自动备份原始版本为 *.original.md src/plugins/opencode/commands/caveman-compress.md；caveman-commit.md 则要求 Conventional Commits 格式、主题 ≤50 字符 src/plugins/opencode/commands/caveman-commit.md。

下表给出当前分发系统所覆盖的关键资产及其职责边界：

cavecrew 子代理的一个关键设计点是：所有结果以"文件路径:行号 — 符号 — 简短注释"的极简契约返回主线程，从而把子代理的工具输出再压缩一次进入主上下文，避免主线程被 2k token 的散文型结果灌满 skills/cavecrew/SKILL.md。

已知安装问题与故障排查

社区围绕安装与分发系统反馈的问题高度集中在三类：

1. OpenCode 文件缺失（ENOENT）：bin/install.js 的 OPENCODE_COMMAND_FILES 常量声明了若干命令文件，但当 caveman-compress.md 未被纳入发布包或镜像时，复制步骤即报 ENOENT: no such file or directory，导致 OpenCode 安装部分失败 issue #367、issue #426、issue #464、issue #482。
2. OpenCode 钩子 API 误用：src/plugins/opencode/plugin.js 注册了 session.created 与 tui.prompt.append 两个钩子键，但 OpenCode 的插件 API 并不支持它们作为可触发钩子，因此钩子永远不生效 issue #418。
3. MCP 服务器缺上游命令：bin/install.js:804 默认执行 claude mcp add caveman-shrink -- npx -y caveman-shrink，但 caveman-shrink 本身是一个用于包装上游的代理/中间件，没有独立上游时会话启动即失败 issue #474。

此外，社区还报告了 PowerShell 7 安装器与 $Args 变量优化冲突 issue #366、Gemini CLI 扩展的 frontmatter 与 TOML 不符合其扩展 schema issue #325、Zed/JetBrains 通过 ACP 接入 Claude Code 时缺少插件挂载点 issue #197，以及 IBM Bob 安装后无法激活 /caveman 命令 issue #523 等问题。CONTRIBUTING.md 强调新增顶层目录必须同步更新 package.json 的 files 数组，否则 npm 发布会漏包，这与 OpenCode 缺失命令文件的根因一致 CONTRIBUTING.md。

See Also

• caveman 主技能与档位说明：skills/caveman/SKILL.md
• 多代理分发源码：bin/install.js、install.sh、install.ps1
• MCP 代理服务器：src/mcp-servers/caveman-shrink/compress.js
• cavecrew 子代理编排：skills/cavecrew/SKILL.md
• v1.9.0 完整性校验清单：src/hooks/checksums.sha256

概述与设计目标

caveman 仓库以一组技能（SKILL.md）、子代理（agents/）与命令（commands/）为核心载荷，分发到 Claude Code、Codex、Gemini CLI、opencode、OpenClaw 等多种宿主。套件的共同设计目标是 用更少的 token 表达同等的技术语义：在保留代码、路径、URL、标识符的前提下，将自然语言压缩到极致。

主技能 caveman 在 skills/caveman/SKILL.md 中通过 frontmatter 声明触发条件（/caveman 显式调用或系统提示注入），并由 src/rules/caveman-activate.md 的精简规则提供底层语义：丢弃冠词、填充词、客套与对冲语气；保留一切技术细节；遇到安全告警、不可逆操作或用户重复提问时自动降级为正常措辞（Auto-Clarity）。

核心技能清单

下表覆盖套件中随安装器同步分发的全部技能与命令（资料来源：skills/caveman/README.md、skills/cavecrew/SKILL.md、CLAUDE.md）。

cavecrew 子代理与输出契约

cavecrew 不是单一技能，而是一组用于分担主线程 token 预算的子代理委派框架。资料来源：skills/cavecrew/SKILL.md。

套件内置三个 cavecrew 子代理，其输出必须严格遵守下列契约，主线程才能直接消费：

• cavecrew-investigator：以 path:line 加反引号包裹的符号为锚，返回短列表或 No match.；便于 grep path:\d+ 复用。
• cavecrew-builder：以 <path:line-range> — <change ≤10 words> 为基本单元，验证状态显式标注（verified: re-read OK | mismatch @ path:line）；超过能力时返回 too-big. / needs-confirm. / ambiguous. / regressed. 作为首词标记。
• cavecrew-reviewer：审查门控，frontmatter 当前固定 model: haiku 作为默认；社区 #521 指出该默认值在严格预合并场景下偏弱，需为评审角色提供 per-agent 模型覆盖入口。

委派决策表（来源同上）建议：跨文件、需要同等技术语义的探索任务优先使用 cavecrew-investigator；3+ 文件或横切重构使用 cavecrew-builder 或 feature-dev:code-architect；已有把握的单行答案直接由主线程回答。

命令分发与跨平台差异

opencode 与 Codex 宿主不直接读取 SKILL.md，而是消费位于 src/plugins/opencode/commands/ 与根 commands/ 下的命令存根：

• src/plugins/opencode/commands/caveman-compress.md：仅接受 .md、.txt、.typ、.tex 或无扩展名的自然语言文件；显式拒绝源码与配置文件，并禁止再次压缩已有的 .original.md 备份。文件被改写前先备份原版。
• src/plugins/opencode/commands/caveman-commit.md：在暂存内容存在时按 Conventional Commits 生成提交信息，标题 ≤50 字符、不带句号、正文仅解释 *why*。

这些命令随安装器被 copyfile 到 ~/.config/opencode/commands/。社区反复反馈该路径在 npx 安装时出现 ENOENT（#426、#464、#482、#367），原因是 bin/install.js 的 OPENCODE_COMMAND_FILES 数组在历史上遗漏了 caveman-compress.md，导致复制失败。#418 还指出 opencode 插件使用的 session.created / tui.prompt.append 钩子键名与宿主 API 不匹配，钩子从未触发；正确做法是使用宿主支持的钩子或回退到 AGENTS.md 始终开启的规则集。

caveman-shrink MCP 代理由 src/mcp-servers/caveman-shrink/compress.js 实现，是套件中唯一的 Node 运行时组件。它的边界与 Python 版 caveman-compress 一致：跳过围栏代码块、内联代码、URL、文件路径、类代码 token；其余段落则套用填充词、客套、对冲词等正则规则。社区 #474 反馈默认安装以 npx -y caveman-shrink 注入该 MCP 但缺失上游命令，造成每次启动失败——修复方式是补齐实际命令或将 MCP 注册变为可选。

关键不变式与扩展建议

CONTRIBUTING.md 明确了改动技能时的两条不变式：

1. 钩子必须静默失败。任何抛出会阻断 Claude Code 会话启动；参考 src/hooks/caveman-activate.js 的 try/catch 模式。
2. settings.json 必须经由 bin/lib/settings.js 读写。直接 JSON.parse 会因用户的 JSONC 注释而崩溃；写入前需调用 validateHookFields()，否则 Zod schema 会静默丢弃整份 settings.json。

新增技能或修改 frontmatter 时，应在 PR 中显式说明 CI 是否需要重同步 plugins/caveman/skills/（该目录是 npm 发布的镜像）。如 CLAUDE.md 所述，技能源在 skills/，CI 会同步到 plugins/caveman/skills/；修改前者但忘记后者会在不同宿主上得到不一致行为。

See Also

• caveman README
• skills/caveman/SKILL.md
• skills/cavecrew/SKILL.md
• CLAUDE.md
• CONTRIBUTING.md

概述

caveman 的"钩子架构、MCP 中间件与安全模型"是项目在多智能体（Claude Code、Codex、Gemini、opencode、OpenClaw 等）之间复用同一套压缩规则时，所依赖的三个相互关联的子系统：会话级生命周期钩子负责把规则注入到模型上下文中，caveman-shrink 负责在工具描述层面进一步削减 token，发布流程则通过固定版本与 SHA-256 校验保证这些钩子不会被中间人替换。三者共同构成了"省 token 但不省安全"的设计边界。资料来源：README.md、CLAUDE.md。

钩子系统架构

钩子系统按智能体类型采用不同的注入策略。Claude Code 通过 src/hooks/ 下的脚本在 SessionStart 时把规则写入上下文；opencode 使用 src/plugins/opencode/ 下的原生插件，理论上应在 session.created 与 tui.prompt.append 事件触发，但社区报告（issue #418）显示这两个事件名并非 opencode 官方支持的钩子键，因此钩子可能"装上但不触发"。Codex 在 plugins/caveman/ 下以插件形态分发并通过 .codex/hooks.json 注册；Gemini CLI 通过 GEMINI.md 上下文文件按会话加载。资料来源：CLAUDE.md。

每个钩子在被调用前必须通过 src/hooks/checksums.sha256 校验，校验锚点固定在 v1.9.0 标签上而非滚动 main 分支（v1.9.0 release notes）。curl|bash 与 detached 类型的安装都会下载该清单并对每个钩子文件做 SHA-256 比对，不匹配则中止安装流程。

flowchart LR
  A[用户启动 agent] --> B{SessionStart /<br/>session.created}
  B -->|钩子触发| C[读取 rules body]
  C --> D[SHA-256 校验<br/>checksums.sha256]
  D -->|通过| E[注入 SKILL.md / AGENTS.md]
  D -->|失败| F[中止并报错]
  E --> G[模型进入 caveman 模式]
  G --> H[工具描述 → caveman-shrink 代理]
  H --> I[返回压缩后文本]

MCP 中间件：caveman-shrink

caveman-shrink 是一个发布到 npm 的 MCP 代理，部署在 src/mcp-servers/caveman-shrink/，主入口 compress.js 用 Node 重写了 Python 端 caveman-compress 的边界规则。资料来源：src/mcp-servers/caveman-shrink/compress.js、src/mcp-servers/caveman-shrink/package.json。

其 API 为 compress(text, opts?) → { compressed, before, after }。绝不修改的边界包括：fenced 代码块、inline 代码、https?:// 形式的 URL、含 / 或 \ 的文件系统路径、"code-looking" token（带括号、分号、JSON 风格花括号）、以及 CamelCase / snake_case / dotted.path 形式的标识符。会压缩的则是文章（a/an/the）、填充词（just/really/basically/actually 等）、客套话（please/kindly/thank you/sure/certainly）、对冲语气（perhaps/maybe/might/could potentially），以及前导 "I'll / I will / you can / we will / let me"。这与 skills/caveman-compress/SKILL.md 中规定的"代码块逐字符复制"原则保持一致，确保压缩不会破坏技术语义。

安全模型

安全模型建立在"不可变来源 + 完整性校验 + 最小化远程行为"三道防线上。src/hooks/checksums.sha256 是 v1.9.0 首次签发的清单，所有从远程下载的钩子必须与该清单逐字节匹配；任何 main 分支的滚动更新都不会被新安装接收。资料来源：v1.9.0 release notes。

不过社区安全审计（issue #528）仍标出"高风险外泄"与"中风险路径穿越"两类问题，提示静态规则本身是文本，但钩子 shell（caveman-statusline.sh / .ps1）在错误参数下可能成为攻击面。caveman-shrink 的设计选择是"只读不写"——它不发起网络请求，只对传入字符串做正则替换；压缩函数也没有 eval 或子进程派发，因此即便被恶意输入污染，最坏情况也只是产生错误压缩结果而非任意代码执行。

常见失败模式

1. opencode 钩子静默失效：钩子名不在 opencode 官方 API 中，规则不会自动加载，需要用户手动将 AGENTS.md 放入项目根。资料来源：issue #418。
2. MCP 上游缺失：caveman-shrink 默认通过 claude mcp add caveman-shrink -- npx -y caveman-shrink 注册；若 npm 拉取失败或网络受限，每次会话都会看到加载错误。资料来源：issue #474。
3. opencode 安装 ENOENT：安装脚本引用 src/plugins/opencode/commands/caveman-compress.md 但该文件有时被裁剪掉，导致拷贝失败。资料来源：issue #426、#464。
4. PowerShell 7 变量优化冲突：install.ps1 在 PS7+ 下因 Args 变量被优化而触发 Cannot overwrite variable Args 错误。资料来源：issue #366。
5. Gemini 扩展加载器校验失败：agents 缺少必填 frontmatter 字段会导致整个扩展不可用。资料来源：issue #325。

参见

• 仓库主索引页（项目总览与安装）
• 压缩规则与 SKILL.md 系统提示词详解
• cavecrew 子代理契约与输出格式

Pitfall Log / 踩坑日志

项目：JuliusBrussee/caveman

摘要：发现 34 个潜在踩坑项，其中 5 个为 high/blocking；最高优先级：安装坑 - 来源证据：caveman does not work when installing for opencode。

1. 安装坑 · 来源证据：caveman does not work when installing for opencode

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：caveman does not work when installing for opencode
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/JuliusBrussee/caveman/issues/482 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

2. 安装坑 · 来源证据：npx install for opencode incomplete — no such file or directory src\plugins\opencode\commands\caveman-compress.md

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：npx install for opencode incomplete — no such file or directory src\plugins\opencode\commands\caveman-compress.md
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/JuliusBrussee/caveman/issues/464 | 来源类型 github_issue 暴露的待验证使用条件。

3. 安全/权限坑 · 失败模式：security_permissions: Security Scan Flags “Caution” Verdict for the *caveman* Skill (High‑risk Exfiltration & Mediu...

• 严重度：high
• 证据强度：source_linked
• 发现：Developers should check this security_permissions risk before relying on the project: Security Scan Flags “Caution” Verdict for the *caveman* Skill (High‑risk Exfiltration & Medium‑risk Path Traversal)
• 对用户的影响：Developers may expose sensitive permissions or credentials: Security Scan Flags “Caution” Verdict for the *caveman* Skill (High‑risk Exfiltration & Medium‑risk Path Traversal)
• 证据：failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/caveman/issues/528 | Security Scan Flags “Caution” Verdict for the *caveman* Skill (High‑risk Exfiltration & Medium‑risk Path Traversal)

4. 安全/权限坑 · 来源证据：Can't find or activate /caveman in IBM Bob

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Can't find or activate /caveman in IBM Bob
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/JuliusBrussee/caveman/issues/523 | 来源类型 github_issue 暴露的待验证使用条件。

5. 安全/权限坑 · 来源证据：Portuguese (PT-BR) adaptation: Troglodita

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Portuguese (PT-BR) adaptation: Troglodita
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/JuliusBrussee/caveman/issues/457 | 来源类型 github_issue 暴露的待验证使用条件。

6. 安装坑 · 失败模式：installation: Can't find or activate /caveman in IBM Bob

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Can't find or activate /caveman in IBM Bob
• 对用户的影响：Developers may fail before the first successful local run: Can't find or activate /caveman in IBM Bob
• 证据：failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/caveman/issues/523 | Can't find or activate /caveman in IBM Bob

7. 安装坑 · 失败模式：installation: Portuguese (PT-BR) adaptation: Troglodita

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Portuguese (PT-BR) adaptation: Troglodita
• 对用户的影响：Developers may fail before the first successful local run: Portuguese (PT-BR) adaptation: Troglodita
• 证据：failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/caveman/issues/457 | Portuguese (PT-BR) adaptation: Troglodita

8. 安装坑 · 失败模式：installation: ask about project

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: ask about project
• 对用户的影响：Developers may fail before the first successful local run: ask about project
• 证据：failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/caveman/issues/522 | ask about project

9. 安装坑 · 失败模式：installation: caveman does not work when installing for opencode

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: caveman does not work when installing for opencode
• 对用户的影响：Developers may fail before the first successful local run: caveman does not work when installing for opencode
• 证据：failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/caveman/issues/482 | caveman does not work when installing for opencode

10. 安装坑 · 失败模式：installation: caveman-shrink MCP registered with no upstream → fails on every load

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: caveman-shrink MCP registered with no upstream → fails on every load
• 对用户的影响：Developers may fail before the first successful local run: caveman-shrink MCP registered with no upstream → fails on every load
• 证据：failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/caveman/issues/474 | caveman-shrink MCP registered with no upstream → fails on every load

11. 安装坑 · 失败模式：installation: feat: per-agent model override for cavecrew subagents (reviewer hardcoded to haiku, too weak...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: feat: per-agent model override for cavecrew subagents (reviewer hardcoded to haiku, too weak as a review gate)
• 对用户的影响：Developers may fail before the first successful local run: feat: per-agent model override for cavecrew subagents (reviewer hardcoded to haiku, too weak as a review gate)
• 证据：failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/caveman/issues/521 | feat: per-agent model override for cavecrew subagents (reviewer hardcoded to haiku, too weak as a review gate)

12. 安装坑 · 失败模式：installation: npx install for opencode incomplete — no such file or directory src\plugins\opencode\commands...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: npx install for opencode incomplete — no such file or directory src\plugins\opencode\commands\caveman-compress.md
• 对用户的影响：Developers may fail before the first successful local run: npx install for opencode incomplete — no such file or directory src\plugins\opencode\commands\caveman-compress.md
• 证据：failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/caveman/issues/464 | npx install for opencode incomplete — no such file or directory src\plugins\opencode\commands\caveman-compress.md

13. 安装坑 · 失败模式：installation: opencode install fails with ENOENT for missing caveman-compress.md

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: opencode install fails with ENOENT for missing caveman-compress.md
• 对用户的影响：Developers may fail before the first successful local run: opencode install fails with ENOENT for missing caveman-compress.md
• 证据：failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/caveman/issues/426 | opencode install fails with ENOENT for missing caveman-compress.md

14. 安装坑 · 失败模式：installation: v1.7.0 — Stats receipts, smart installer, cavecrew, MCP-shrink

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v1.7.0 — Stats receipts, smart installer, cavecrew, MCP-shrink
• 对用户的影响：Upgrade or migration may change expected behavior: v1.7.0 — Stats receipts, smart installer, cavecrew, MCP-shrink
• 证据：failure_mode_cluster:github_release | https://github.com/JuliusBrussee/caveman/releases/tag/v1.7.0 | v1.7.0 — Stats receipts, smart installer, cavecrew, MCP-shrink

15. 安装坑 · 失败模式：installation: v1.8.0 — Lobster grunt. Opencode grunt. Brain still big.

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v1.8.0 — Lobster grunt. Opencode grunt. Brain still big.
• 对用户的影响：Upgrade or migration may change expected behavior: v1.8.0 — Lobster grunt. Opencode grunt. Brain still big.
• 证据：failure_mode_cluster:github_release | https://github.com/JuliusBrussee/caveman/releases/tag/v1.8.0 | v1.8.0 — Lobster grunt. Opencode grunt. Brain still big.

16. 安装坑 · 失败模式：installation: v1.8.1 — Hotfix: curl|bash one-liner

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v1.8.1 — Hotfix: curl|bash one-liner
• 对用户的影响：Upgrade or migration may change expected behavior: v1.8.1 — Hotfix: curl|bash one-liner
• 证据：failure_mode_cluster:github_release | https://github.com/JuliusBrussee/caveman/releases/tag/v1.8.1 | v1.8.1 — Hotfix: curl|bash one-liner

17. 安装坑 · 失败模式：installation: v1.8.2 — installer bug fixes

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v1.8.2 — installer bug fixes
• 对用户的影响：Upgrade or migration may change expected behavior: v1.8.2 — installer bug fixes
• 证据：failure_mode_cluster:github_release | https://github.com/JuliusBrussee/caveman/releases/tag/v1.8.2 | v1.8.2 — installer bug fixes

18. 安装坑 · 失败模式：installation: v1.9.0 — Rock pinned. Rock verified. opencode rock work now.

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v1.9.0 — Rock pinned. Rock verified. opencode rock work now.
• 对用户的影响：Upgrade or migration may change expected behavior: v1.9.0 — Rock pinned. Rock verified. opencode rock work now.
• 证据：failure_mode_cluster:github_release | https://github.com/JuliusBrussee/caveman/releases/tag/v1.9.0 | v1.9.0 — Rock pinned. Rock verified. opencode rock work now.

19. 安装坑 · 来源证据：caveman-shrink MCP registered with no upstream → fails on every load

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：caveman-shrink MCP registered with no upstream → fails on every load
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/JuliusBrussee/caveman/issues/474 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

20. 安装坑 · 来源证据：feat: per-agent model override for cavecrew subagents (reviewer hardcoded to haiku, too weak as a review gate)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：feat: per-agent model override for cavecrew subagents (reviewer hardcoded to haiku, too weak as a review gate)
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/JuliusBrussee/caveman/issues/521 | 来源类型 github_issue 暴露的待验证使用条件。

21. 安装坑 · 来源证据：opencode install fails with ENOENT for missing caveman-compress.md

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：opencode install fails with ENOENT for missing caveman-compress.md
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/JuliusBrussee/caveman/issues/426 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

22. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | github_repo:1201173969 | https://github.com/JuliusBrussee/caveman | host_targets=claude_code, claude, cursor

23. 配置坑 · 失败模式：configuration: bug(opencode): plugin hooks session.created and tui.prompt.append never fire — wrong API

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: bug(opencode): plugin hooks session.created and tui.prompt.append never fire — wrong API
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: bug(opencode): plugin hooks session.created and tui.prompt.append never fire — wrong API
• 证据：failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/caveman/issues/418 | bug(opencode): plugin hooks session.created and tui.prompt.append never fire — wrong API

24. 配置坑 · 来源证据：bug(opencode): plugin hooks session.created and tui.prompt.append never fire — wrong API

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：bug(opencode): plugin hooks session.created and tui.prompt.append never fire — wrong API
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/JuliusBrussee/caveman/issues/418 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。

25. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | github_repo:1201173969 | https://github.com/JuliusBrussee/caveman | README/documentation is current enough for a first validation pass.

26. 维护坑 · 失败模式：migration: benchmarks/run.py: default --model claude-sonnet-4-20250514 is retired (404) — bump to claude...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this migration risk before relying on the project: benchmarks/run.py: default --model claude-sonnet-4-20250514 is retired (404) — bump to claude-sonnet-4-6
• 对用户的影响：Developers may hit a documented source-backed failure mode: benchmarks/run.py: default --model claude-sonnet-4-20250514 is retired (404) — bump to claude-sonnet-4-6
• 证据：failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/caveman/issues/519 | benchmarks/run.py: default --model claude-sonnet-4-20250514 is retired (404) — bump to claude-sonnet-4-6

27. 维护坑 · 来源证据：benchmarks/run.py: default --model claude-sonnet-4-20250514 is retired (404) — bump to claude-sonnet-4-6

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：benchmarks/run.py: default --model claude-sonnet-4-20250514 is retired (404) — bump to claude-sonnet-4-6
• 对用户的影响：可能影响升级、迁移或版本选择。
• 证据：community_evidence:github | https://github.com/JuliusBrussee/caveman/issues/519 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

28. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | github_repo:1201173969 | https://github.com/JuliusBrussee/caveman | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | github_repo:1201173969 | https://github.com/JuliusBrussee/caveman | no_demo; severity=medium

30. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | github_repo:1201173969 | https://github.com/JuliusBrussee/caveman | no_demo; severity=medium

31. 安全/权限坑 · 来源证据：Security Scan Flags “Caution” Verdict for the *caveman* Skill (High‑risk Exfiltration & Medium‑risk Path Traversal)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Security Scan Flags “Caution” Verdict for the *caveman* Skill (High‑risk Exfiltration & Medium‑risk Path Traversal)
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/JuliusBrussee/caveman/issues/528 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。

32. 安全/权限坑 · 来源证据：ask about project

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：ask about project
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/JuliusBrussee/caveman/issues/522 | 来源类型 github_issue 暴露的待验证使用条件。

33. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | github_repo:1201173969 | https://github.com/JuliusBrussee/caveman | issue_or_pr_quality=unknown

34. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | github_repo:1201173969 | https://github.com/JuliusBrussee/caveman | release_recency=unknown