# https://github.com/JuliusBrussee/caveman 项目说明书 生成时间：2026-06-14 20:31:11 UTC ## 目录 - [项目概览与压缩原理](#page-1) - [多代理安装与分发系统](#page-2) - [技能、子代理与命令套件](#page-3) - [钩子架构、MCP 中间件与安全模型](#page-4) ## 项目概览与压缩原理 ### 相关页面 相关主题：[多代理安装与分发系统](#page-2), [技能、子代理与命令套件](#page-3), [钩子架构、MCP 中间件与安全模型](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/JuliusBrussee/caveman/blob/main/README.md) - [skills/caveman/README.md](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman/README.md) - [src/rules/caveman-activate.md](https://github.com/JuliusBrussee/caveman/blob/main/src/rules/caveman-activate.md) - [skills/caveman-compress/SKILL.md](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-compress/SKILL.md) - [skills/caveman-compress/scripts/__init__.py](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-compress/scripts/__init__.py) - [skills/caveman-compress/scripts/compress.py](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-compress/scripts/compress.py) - [src/mcp-servers/caveman-shrink/compress.js](https://github.com/JuliusBrussee/caveman/blob/main/src/mcp-servers/caveman-shrink/compress.js) - [src/mcp-servers/caveman-shrink/package.json](https://github.com/JuliusBrussee/caveman/blob/main/src/mcp-servers/caveman-shrink/package.json) - [skills/cavecrew/SKILL.md](https://github.com/JuliusBrussee/caveman/blob/main/skills/cavecrew/SKILL.md) - [skills/caveman-commit/SKILL.md](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-commit/SKILL.md) - [src/plugins/opencode/commands/caveman-compress.md](https://github.com/JuliusBrussee/caveman/blob/main/src/plugins/opencode/commands/caveman-compress.md)
# 项目概览与压缩原理 ## 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 提供六档强度，使用户可以根据场景在可读性与压缩率之间权衡： | 级别 | 行为特征 | 典型压缩率 | |------|----------|------------| | `lite` | 仅删除填充词和对冲词，保留完整句子，专业但紧凑 | ~30–40% | | `full`（默认） | 删除冠词、允许碎片句、使用短同义词 | ~65–75% | | `ultra` | 裸碎片句，使用缩写（DB、auth、fn），箭头表示因果 | ~75–85% | | `wenyan-lite` | 轻度文言文压缩 | ~50–60% | | `wenyan-full` | 最大文言文压缩 | ~80–90% | | `wenyan-ultra` | 极限文言压缩 | ~85–92% | 资料来源：[skills/caveman/README.md:8-22]()。 ## 4. 架构与组件 caveman 是一个技能集合而非单一二进制，运行时按目标代理拆分为独立子包。下图展示了仓库主要组件及其相互关系： ```mermaid graph TD A["SKILL.md 系统提示
(caveman-activate.md)"] --> B["模型输出压缩
~75% tokens"] C["caveman-compress 技能
(Python CLI)"] --> D["离线文件压缩
(CLAUDE.md/todos)"] E["caveman-shrink MCP
(Node.js 代理)"] --> F["MCP 工具描述压缩"] G["cavecrew 子代理组"] --> H["子代理输出压缩"] I["caveman-commit"] --> J["提交信息压缩"] K["各平台安装器
(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](https://github.com/JuliusBrussee/caveman/releases/tag/v1.9.0)。 此外，压缩规则天然具有语言敏感性——例如葡萄牙语（PT-BR）没有 `the/a/an` 这一类冠词系统，社区已经派生 `Troglodita` 作为葡萄牙语适配分支（issue #457），使用者在跨语言部署时需注意规则不可直接迁移。 ## See Also - [安装与平台兼容](./INSTALL.md) - [caveman-compress 文件压缩流水线](./caveman-compress.md) - [cavecrew 子代理输出契约](./cavecrew.md) - [caveman-shrink MCP 代理](./caveman-shrink-mcp.md) --- ## 多代理安装与分发系统 ### 相关页面 相关主题：[项目概览与压缩原理](#page-1), [技能、子代理与命令套件](#page-3), [钩子架构、MCP 中间件与安全模型](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/JuliusBrussee/caveman/blob/main/README.md) - [CONTRIBUTING.md](https://github.com/JuliusBrussee/caveman/blob/main/CONTRIBUTING.md) - [skills/caveman/SKILL.md](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman/SKILL.md) - [skills/caveman-compress/SKILL.md](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-compress/SKILL.md) - [skills/caveman-commit/SKILL.md](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-commit/SKILL.md) - [skills/cavecrew/SKILL.md](https://github.com/JuliusBrussee/caveman/blob/main/skills/cavecrew/SKILL.md) - [src/plugins/opencode/commands/caveman-compress.md](https://github.com/JuliusBrussee/caveman/blob/main/src/plugins/opencode/commands/caveman-compress.md) - [src/plugins/opencode/commands/caveman-commit.md](https://github.com/JuliusBrussee/caveman/blob/main/src/plugins/opencode/commands/caveman-commit.md) - [src/mcp-servers/caveman-shrink/package.json](https://github.com/JuliusBrussee/caveman/blob/main/src/mcp-servers/caveman-shrink/package.json) - [src/mcp-servers/caveman-shrink/compress.js](https://github.com/JuliusBrussee/caveman/blob/main/src/mcp-servers/caveman-shrink/compress.js) - [skills/caveman-compress/scripts/compress.py](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-compress/scripts/compress.py) - [plugins/caveman/skills/caveman-compress/scripts/compress.py](https://github.com/JuliusBrussee/caveman/blob/main/plugins/caveman/skills/caveman-compress/scripts/compress.py)
# 多代理安装与分发系统 ## 概述与设计目标 caveman 项目的核心交付物是一组针对不同 AI 编程代理（agent）的"技能"（skill）——通过条件化模型输出，去除语法冗余以节省 token，同时保留所有技术细节。围绕这一核心能力，项目构建了一套多代理安装与分发系统，使同一套压缩规则能够以最小适配成本投送到 30 余款主流代理上。 项目的设计目标在三份主要文档中均有明确表述：让"大脑保持聪明，嘴巴保持简短"，并通过 `lite`、`full`、`ultra` 三个强度档位（`wenyan-lite`、`wenyan-full`、`wenyan-ultra` 为文言文变体）满足不同场景的压缩需求 [README.md](https://github.com/JuliusBrussee/caveman/blob/main/README.md)。分发系统须在不破坏各代理原生安装路径的前提下，把这些 SKILL.md、命令文件、钩子（hooks）以及 MCP 服务器正确写入目标环境。 ## 安装器架构与分发流程 caveman 提供了多入口的安装路径，覆盖 npm、curl|bash、PowerShell 三类主流包管理与脚本执行场景： - **npm 入口**：`npx skills add JuliusBrussee/caveman -a ` 是最常用的安装命令，会被 npx 解析到仓库内的 `bin/install.js` 主入口 [README.md](https://github.com/JuliusBrussee/caveman/blob/main/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 发布说明](https://github.com/JuliusBrussee/caveman/releases/tag/v1.9.0)。 下图展示从用户触发到各代理目录写入的端到端分发流程： ```mermaid flowchart LR A[用户触发
npx / curl / irm] --> B[入口脚本
install.js / install.sh / install.ps1] B --> C{选择目标代理
--only <agent>} 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 完整性校验
src/hooks/checksums.sha256] I --> J[写入 SKILL.md
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](https://github.com/JuliusBrussee/caveman/blob/main/src/plugins/opencode/commands/caveman-compress.md)；`caveman-commit.md` 则要求 Conventional Commits 格式、主题 ≤50 字符 [src/plugins/opencode/commands/caveman-commit.md](https://github.com/JuliusBrussee/caveman/blob/main/src/plugins/opencode/commands/caveman-commit.md)。 下表给出当前分发系统所覆盖的关键资产及其职责边界： | 资产路径 | 类型 | 职责 | |---------|------|------| | `skills/caveman/SKILL.md` | 主技能 | 条件化模型按强度档位输出压缩散文 | | `skills/caveman-commit/SKILL.md` | 提交消息技能 | 生成 Conventional Commits 格式消息，仅输出不执行 | | `skills/caveman-compress/SKILL.md` | 文件压缩技能 | 调用 `python3 -m scripts` 压缩长 markdown 并备份 | | `skills/cavecrew/SKILL.md` | 子代理编排技能 | 指导主线程在 `investigator` / `builder` / `reviewer` 三类 cavecrew 子代理间路由 | | `src/plugins/opencode/commands/*` | OpenCode 命令 | 把上述技能暴露为 `/caveman-*` 命令 | | `src/mcp-servers/caveman-shrink/` | MCP 代理服务器 | 在 Node 运行时内对工具描述等字段做边界安全的压缩 | cavecrew 子代理的一个关键设计点是：所有结果以"文件路径:行号 — 符号 — 简短注释"的极简契约返回主线程，从而把子代理的工具输出再压缩一次进入主上下文，避免主线程被 2k token 的散文型结果灌满 [skills/cavecrew/SKILL.md](https://github.com/JuliusBrussee/caveman/blob/main/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](https://github.com/JuliusBrussee/caveman/issues/367)、[issue #426](https://github.com/JuliusBrussee/caveman/issues/426)、[issue #464](https://github.com/JuliusBrussee/caveman/issues/464)、[issue #482](https://github.com/JuliusBrussee/caveman/issues/482)。 2. **OpenCode 钩子 API 误用**：`src/plugins/opencode/plugin.js` 注册了 `session.created` 与 `tui.prompt.append` 两个钩子键，但 OpenCode 的插件 API 并不支持它们作为可触发钩子，因此钩子永远不生效 [issue #418](https://github.com/JuliusBrussee/caveman/issues/418)。 3. **MCP 服务器缺上游命令**：`bin/install.js:804` 默认执行 `claude mcp add caveman-shrink -- npx -y caveman-shrink`，但 `caveman-shrink` 本身是一个用于包装上游的代理/中间件，没有独立上游时会话启动即失败 [issue #474](https://github.com/JuliusBrussee/caveman/issues/474)。 此外，社区还报告了 PowerShell 7 安装器与 `$Args` 变量优化冲突 [issue #366](https://github.com/JuliusBrussee/caveman/issues/366)、Gemini CLI 扩展的 frontmatter 与 TOML 不符合其扩展 schema [issue #325](https://github.com/JuliusBrussee/caveman/issues/325)、Zed/JetBrains 通过 ACP 接入 Claude Code 时缺少插件挂载点 [issue #197](https://github.com/JuliusBrussee/caveman/issues/197)，以及 IBM Bob 安装后无法激活 `/caveman` 命令 [issue #523](https://github.com/JuliusBrussee/caveman/issues/523) 等问题。`CONTRIBUTING.md` 强调新增顶层目录必须同步更新 `package.json` 的 `files` 数组，否则 npm 发布会漏包，这与 OpenCode 缺失命令文件的根因一致 [CONTRIBUTING.md](https://github.com/JuliusBrussee/caveman/blob/main/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` --- ## 技能、子代理与命令套件 ### 相关页面 相关主题：[项目概览与压缩原理](#page-1), [多代理安装与分发系统](#page-2), [钩子架构、MCP 中间件与安全模型](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [skills/caveman/SKILL.md](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman/SKILL.md) - [skills/caveman/README.md](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman/README.md) - [skills/caveman-commit/SKILL.md](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-commit/SKILL.md) - [skills/caveman-commit/README.md](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-commit/README.md) - [skills/caveman-compress/SKILL.md](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-compress/SKILL.md) - [skills/caveman-compress/scripts/__init__.py](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-compress/scripts/__init__.py) - [skills/cavecrew/SKILL.md](https://github.com/JuliusBrussee/caveman/blob/main/skills/cavecrew/SKILL.md) - [src/rules/caveman-activate.md](https://github.com/JuliusBrussee/caveman/blob/main/src/rules/caveman-activate.md) - [src/plugins/opencode/commands/caveman-compress.md](https://github.com/JuliusBrussee/caveman/blob/main/src/plugins/opencode/commands/caveman-compress.md) - [src/plugins/opencode/commands/caveman-commit.md](https://github.com/JuliusBrussee/caveman/blob/main/src/plugins/opencode/commands/caveman-commit.md) - [src/mcp-servers/caveman-shrink/compress.js](https://github.com/JuliusBrussee/caveman/blob/main/src/mcp-servers/caveman-shrink/compress.js) - [src/mcp-servers/caveman-shrink/package.json](https://github.com/JuliusBrussee/caveman/blob/main/src/mcp-servers/caveman-shrink/package.json) - [CLAUDE.md](https://github.com/JuliusBrussee/caveman/blob/main/CLAUDE.md) - [CONTRIBUTING.md](https://github.com/JuliusBrussee/caveman/blob/main/CONTRIBUTING.md)
# 技能、子代理与命令套件 ## 概述与设计目标 `caveman` 仓库以一组技能（`SKILL.md`）、子代理（`agents/`）与命令（`commands/`）为核心载荷，分发到 Claude Code、Codex、Gemini CLI、opencode、OpenClaw 等多种宿主。套件的共同设计目标是 **用更少的 token 表达同等的技术语义**：在保留代码、路径、URL、标识符的前提下，将自然语言压缩到极致。 主技能 `caveman` 在 [skills/caveman/SKILL.md](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman/SKILL.md) 中通过 frontmatter 声明触发条件（`/caveman` 显式调用或系统提示注入），并由 [src/rules/caveman-activate.md](https://github.com/JuliusBrussee/caveman/blob/main/src/rules/caveman-activate.md) 的精简规则提供底层语义：丢弃冠词、填充词、客套与对冲语气；保留一切技术细节；遇到安全告警、不可逆操作或用户重复提问时自动降级为正常措辞（Auto-Clarity）。 ## 核心技能清单 下表覆盖套件中随安装器同步分发的全部技能与命令（资料来源：[skills/caveman/README.md](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman/README.md)、[skills/cavecrew/SKILL.md](https://github.com/JuliusBrussee/caveman/blob/main/skills/cavecrew/SKILL.md)、[CLAUDE.md](https://github.com/JuliusBrussee/caveman/blob/main/CLAUDE.md)）。 | 名称 | 入口文件 | 主要职责 | 触发方式 | |------|----------|----------|----------| | `caveman` | `skills/caveman/SKILL.md` | 压缩模型输出为 ultra-tight 文风；六档强度（`lite`/`full`/`ultra`/`wenyan-lite`/`wenyan-full`/`wenyan-ultra`） | `/caveman [lite|full|ultra|wenyan]`、SessionStart 钩子注入 | | `caveman-commit` | `skills/caveman-commit/SKILL.md` | 生成 Conventional Commits 提交信息；标题 ≤50 字符、正文仅解释 *why* | `/caveman-commit`、`/commit`、暂存变更时自动触发 | | `caveman-compress` | `skills/caveman-compress/SKILL.md` | 压缩自然语言记忆文件（`CLAUDE.md`、todos、preferences）并保留 `.original.md` 备份 | `/caveman-compress ` | | `cavecrew` | `skills/cavecrew/SKILL.md` | 子代理委派指南与输出契约 | 在主线程中按需委派 | | `caveman-review` | `skills/caveman-review/SKILL.md` | 一行式代码审查，格式 `L: . .` | 代码评审场景 | | `caveman-help` / `caveman-stats` | `skills/caveman-help/`、`skills/caveman-stats/` | 帮助文档与统计展示 | 命令调用 | ## cavecrew 子代理与输出契约 `cavecrew` 不是单一技能，而是一组用于分担主线程 token 预算的子代理委派框架。资料来源：[skills/cavecrew/SKILL.md](https://github.com/JuliusBrussee/caveman/blob/main/skills/cavecrew/SKILL.md)。 套件内置三个 cavecrew 子代理，其输出必须严格遵守下列契约，主线程才能直接消费： - **`cavecrew-investigator`**：以 `path:line` 加反引号包裹的符号为锚，返回短列表或 `No match.`；便于 `grep path:\d+` 复用。 - **`cavecrew-builder`**：以 ` — ` 为基本单元，验证状态显式标注（`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](https://github.com/JuliusBrussee/caveman/blob/main/src/mcp-servers/caveman-shrink/compress.js) 实现，是套件中唯一的 Node 运行时组件。它的边界与 Python 版 `caveman-compress` 一致：跳过围栏代码块、内联代码、URL、文件路径、类代码 token；其余段落则套用填充词、客套、对冲词等正则规则。社区 #474 反馈默认安装以 `npx -y caveman-shrink` 注入该 MCP 但缺失上游命令，造成每次启动失败——修复方式是补齐实际命令或将 MCP 注册变为可选。 ## 关键不变式与扩展建议 [CONTRIBUTING.md](https://github.com/JuliusBrussee/caveman/blob/main/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](https://github.com/JuliusBrussee/caveman/blob/main/CLAUDE.md) 所述，技能源在 `skills/`，CI 会同步到 `plugins/caveman/skills/`；修改前者但忘记后者会在不同宿主上得到不一致行为。 ## See Also - [caveman README](https://github.com/JuliusBrussee/caveman#readme) - [skills/caveman/SKILL.md](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman/SKILL.md) - [skills/cavecrew/SKILL.md](https://github.com/JuliusBrussee/caveman/blob/main/skills/cavecrew/SKILL.md) - [CLAUDE.md](https://github.com/JuliusBrussee/caveman/blob/main/CLAUDE.md) - [CONTRIBUTING.md](https://github.com/JuliusBrussee/caveman/blob/main/CONTRIBUTING.md) --- ## 钩子架构、MCP 中间件与安全模型 ### 相关页面 相关主题：[项目概览与压缩原理](#page-1), [多代理安装与分发系统](#page-2), [技能、子代理与命令套件](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/JuliusBrussee/caveman/blob/main/README.md) - [CLAUDE.md](https://github.com/JuliusBrussee/caveman/blob/main/CLAUDE.md) - [skills/caveman-compress/SKILL.md](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-compress/SKILL.md) - [skills/caveman-compress/scripts/compress.py](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-compress/scripts/compress.py) - [src/mcp-servers/caveman-shrink/compress.js](https://github.com/JuliusBrussee/caveman/blob/main/src/mcp-servers/caveman-shrink/compress.js) - [src/mcp-servers/caveman-shrink/package.json](https://github.com/JuliusBrussee/caveman/blob/main/src/mcp-servers/caveman-shrink/package.json) - [src/plugins/opencode/commands/caveman-compress.md](https://github.com/JuliusBrussee/caveman/blob/main/src/plugins/opencode/commands/caveman-compress.md) - [src/plugins/opencode/commands/caveman-commit.md](https://github.com/JuliusBrussee/caveman/blob/main/src/plugins/opencode/commands/caveman-commit.md) - [skills/cavecrew/SKILL.md](https://github.com/JuliusBrussee/caveman/blob/main/skills/cavecrew/SKILL.md)
# 钩子架构、MCP 中间件与安全模型 ## 概述 caveman 的"钩子架构、MCP 中间件与安全模型"是项目在多智能体（Claude Code、Codex、Gemini、opencode、OpenClaw 等）之间复用同一套压缩规则时，所依赖的三个相互关联的子系统：会话级生命周期钩子负责把规则注入到模型上下文中，caveman-shrink 负责在工具描述层面进一步削减 token，发布流程则通过固定版本与 SHA-256 校验保证这些钩子不会被中间人替换。三者共同构成了"省 token 但不省安全"的设计边界。资料来源：[README.md](https://github.com/JuliusBrussee/caveman/blob/main/README.md)、[CLAUDE.md](https://github.com/JuliusBrussee/caveman/blob/main/CLAUDE.md)。 ## 钩子系统架构 钩子系统按智能体类型采用不同的注入策略。Claude Code 通过 `src/hooks/` 下的脚本在 `SessionStart` 时把规则写入上下文；opencode 使用 `src/plugins/opencode/` 下的原生插件，理论上应在 `session.created` 与 `tui.prompt.append` 事件触发，但社区报告（[issue #418](https://github.com/JuliusBrussee/caveman/issues/418)）显示这两个事件名并非 opencode 官方支持的钩子键，因此钩子可能"装上但不触发"。Codex 在 `plugins/caveman/` 下以插件形态分发并通过 `.codex/hooks.json` 注册；Gemini CLI 通过 `GEMINI.md` 上下文文件按会话加载。资料来源：[CLAUDE.md](https://github.com/JuliusBrussee/caveman/blob/main/CLAUDE.md)。 每个钩子在被调用前必须通过 `src/hooks/checksums.sha256` 校验，校验锚点固定在 v1.9.0 标签上而非滚动 `main` 分支（v1.9.0 release notes）。`curl|bash` 与 detached 类型的安装都会下载该清单并对每个钩子文件做 SHA-256 比对，不匹配则中止安装流程。 ```mermaid flowchart LR A[用户启动 agent] --> B{SessionStart /
session.created} B -->|钩子触发| C[读取 rules body] C --> D[SHA-256 校验
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](https://github.com/JuliusBrussee/caveman/blob/main/src/mcp-servers/caveman-shrink/compress.js)、[src/mcp-servers/caveman-shrink/package.json](https://github.com/JuliusBrussee/caveman/blob/main/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](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-compress/SKILL.md) 中规定的"代码块逐字符复制"原则保持一致，确保压缩不会破坏技术语义。 ## 安全模型 安全模型建立在"不可变来源 + 完整性校验 + 最小化远程行为"三道防线上。`src/hooks/checksums.sha256` 是 v1.9.0 首次签发的清单，所有从远程下载的钩子必须与该清单逐字节匹配；任何 main 分支的滚动更新都不会被新安装接收。资料来源：[v1.9.0 release notes](https://github.com/JuliusBrussee/caveman/releases/tag/v1.9.0)。 不过社区安全审计（[issue #528](https://github.com/JuliusBrussee/caveman/issues/528)）仍标出"高风险外泄"与"中风险路径穿越"两类问题，提示静态规则本身是文本，但钩子 shell（`caveman-statusline.sh` / `.ps1`）在错误参数下可能成为攻击面。`caveman-shrink` 的设计选择是"只读不写"——它不发起网络请求，只对传入字符串做正则替换；压缩函数也没有 `eval` 或子进程派发，因此即便被恶意输入污染，最坏情况也只是产生错误压缩结果而非任意代码执行。 ## 常见失败模式 1. **opencode 钩子静默失效**：钩子名不在 opencode 官方 API 中，规则不会自动加载，需要用户手动将 `AGENTS.md` 放入项目根。资料来源：[issue #418](https://github.com/JuliusBrussee/caveman/issues/418)。 2. **MCP 上游缺失**：`caveman-shrink` 默认通过 `claude mcp add caveman-shrink -- npx -y caveman-shrink` 注册；若 npm 拉取失败或网络受限，每次会话都会看到加载错误。资料来源：[issue #474](https://github.com/JuliusBrussee/caveman/issues/474)。 3. **opencode 安装 ENOENT**：安装脚本引用 `src/plugins/opencode/commands/caveman-compress.md` 但该文件有时被裁剪掉，导致拷贝失败。资料来源：[issue #426](https://github.com/JuliusBrussee/caveman/issues/426)、[#464](https://github.com/JuliusBrussee/caveman/issues/464)。 4. **PowerShell 7 变量优化冲突**：`install.ps1` 在 PS7+ 下因 `Args` 变量被优化而触发 `Cannot overwrite variable Args` 错误。资料来源：[issue #366](https://github.com/JuliusBrussee/caveman/issues/366)。 5. **Gemini 扩展加载器校验失败**：agents 缺少必填 frontmatter 字段会导致整个扩展不可用。资料来源：[issue #325](https://github.com/JuliusBrussee/caveman/issues/325)。 ## 参见 - 仓库主索引页（项目总览与安装） - 压缩规则与 SKILL.md 系统提示词详解 - cavecrew 子代理契约与输出格式 --- --- ## Doramagic 踩坑日志 项目：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