capt-hook Skill 技能

技能简介

captain-hook（PyPI 包名 capt-hook）是一款「别再对 Claude 重复同样的话」的 Claude Code 护栏工具。它持续挖掘你的会话转录，把你在几十次会话里反复给出的纠正沉淀为规则，并自动开 PR，把每条规则变成有类型、有测试的 Python Hook。无论是拦截 git push --force、禁止 rm -rf，还是逼着 Agent 在宣称完成之前真的跑过测试，都只需要声明一次，之后由 Hook 在对应事件点强制执行，而不是指望模型每次都能记住你的叮嘱。

核心能力

• 命令级拦截：block_command 声明黑名单命令与理由，Agent 执行到 PreToolUse 时被阻断并看到提示与替代建议（如改用 --force-with-lease）。
• 解析命令行的守卫：evt.command 给出解析后的命令树，可遍历 && 与管道中的每个 rm 调用，检查目标是否过宽，甚至把 rm 自动改写为 trash。
• 会话审查器：会话结束时自动读取转录，保留其中的常驻纠正；当同一模式在多次会话中反复出现，自动开 PR 将其固化为 Hook。
• Stop 门禁：gate 在 Agent 想结束回合时检查条件——编辑了 Python 文件却没跑 pytest，就无法收工；跑过测试后门禁自动让位。
• 类型化条件与 LLM Hook：对工具、文件、命令、转录历史提供类型化过滤器；正则难以判定时可改用模型裁决的 LLM Hook。
• 内置 Hook 包与测试：自带 general、python、go 三套 Hook 包；uvx capt-hook test 可在 CI 中回归测试，Hook 写坏了直接构建失败。

安装配置

1. 安装 CLI：brew install --formula yasyf/tap/captain-hook（也可用 uvx capt-hook 直接运行）。
2. 部署宿主：uvx capt-hook helper install 安装固定签名的宿主应用到 ~/Applications/Captain Hook.app。
3. 初始化仓库：uvx capt-hook init 创建 .claude/hooks/ 目录、接线 Claude Code 设置并启动会话审查器。
4. Agent 代装：在 Agent 里粘贴 /plugin marketplace add yasyf/captain-hook + /plugin install captain-hook@captain-hook 即可。

使用步骤

1. 安装并初始化：装好公式包后依次执行 helper install 与 init。
2. 声明第一条拦截：在 .claude/hooks/safety.py 中用 block_command(["git","push","--force"], reason=..., tests=...) 写下命令、理由与内联测试。
3. 验证生效：下一次 Agent 尝试强推时会收到 BLOCKED: ... 提示并改用安全命令；随后运行 uvx capt-hook test 确认测试全绿。
4. 启用会话审查：日常照常使用 Claude Code，审查器会跟踪你输入的纠正，用 uvx capt-hook status 查看从首次出现到 PR 的推进状态。
5. 合并固化：审阅并合并自动开出的 PR，此后该规则由 Hook 强制执行。

适用场景

• 危险命令防护：阻止强推、破坏性删除、越权部署等一次性不可逆操作。
• 把口头纠正变成制度：诸如「用 uv 别用 pip」这类说了十几遍的要求，固化为可执行规则。
• 完成质量门禁：Agent 宣称完成之前必须有真实测试记录，杜绝「测试是红的却说做完了」。
• 团队统一护栏：Hook 以代码形式进仓库，团队成员与所有 Agent 会话共享同一套约束。

适用人群

日常使用 Claude Code 并反复纠正同一问题的开发者；重视 CI 与代码审查、希望 Agent 行为可测试可回归的工程团队；需要对 AI 编程过程施加硬性安全约束的技术负责人。

工作原理

captain-hook 依托 Claude Code 的 Hook 机制工作：init 在仓库写入 .claude/hooks/ 并接线设置，之后每个事件（如 PreToolUse、Stop）都调用固定版本的 capt-hook 执行你声明的规则。命令字符串先被解析成结构化调用树，规则基于解析结果判定放行或阻断，判定逻辑由内联测试覆盖。会话审查器则在会话结束读取转录，提取反复出现的纠正并按「首次出现 → 跟踪 → 开 PR」的流水线推进，合并后即成为常驻 Hook。整个链路是确定性的代码执行，不依赖模型自觉。

官方链接

• PyPI 主页：https://pypi.org/project/capt-hook/
• GitHub 仓库：https://github.com/yasyf/captain-hook
• 文档站点：https://yasyf.github.io/captain-hook/