MicahAI/Claude-Kaptn
GitHub: MicahAI/Claude-Kaptn
Kaptn 是一个 Claude Code 插件，通过自定义规则引擎自动管理 AI agent 的工具调用权限，提供会话级限额、循环检测和完整审计追踪。
Stars: 0 | Forks: 0
# Kaptn
**Claude Code 工具批准的 AutoPilot。** Kaptn 依托于 Claude Code 的
PreToolUse hook，并根据*你的*规则决定每一次工具调用——批准
常规操作，阻止危险行为，上报异常情况——同时提供单次会话
预算、失控循环制动，以及记录你的 AI agent 所作所为的完整审计追踪。
```
Claude wants to run: rm -rf build/
Kaptn: deny (rule=block-file-deletes)
Claude wants to run: git status
Kaptn: allow (rule=allow-safe-commands) ← no prompt, logged
Claude wants to call: mcp__some_server__tool (301st time this session)
Kaptn: ask (limit_exceeded: max_per_session 300/300)
```
## 为什么需要
AI 编程 agent 要么对每个权限都烦扰你，要么毫无权限限制地运行。
Kaptn 提供了折中方案：这是一个策略层，会自动批准你信任的操作，
强制停止你不信任的操作，按会话对其余操作进行速率限制，并
编写一份你能真正用来回答问题的审计日志——*昨天哪些会话
运行了哪些命令，以及是谁批准了它们？*
## 安装（30秒）
在 Claude Code 中：
```
/plugin marketplace add MicahAI/Claude-Kaptn
/plugin install kaptn@claude-kaptn
```
要求：PATH 中有 Python 3.10+。仅此而已——不需要服务器，不需要 pip
安装，也不需要编辑设置。新会话会被立即接管；
状态和配置存放在 `~/.kaptn/` 中。
然后，在任何会话中：
- `/kaptn:status` — 规则、实时的单次会话用量与上限对比、审计摘要
- `/kaptn:log` — 近期决策
- `/kaptn:reset` — 清除限制和循环暂停
## 规则
`~/.kaptn/kaptn.config.json`（首次运行时会以合理的默认值创建）。
每次工具调用都会被归类到一个类别中——`file_read`、
`file_write`、`file_delete`、`command_safe`、`command_unsafe`、`search`、
`tool_call`、`unknown`——这是根据工具的真实名称和输入得出的（Bash
命令会按管道段进行解析；最危险的段决定结果，且 `sudo` 永远是不安全的）。规则按以下顺序匹配：
```
{
"id": "allow-file-writes",
"category": "file_write",
"action": "approve",
"conditions": { "exclude_patterns": ["**/.env*", "**/secrets/**"] },
"limits": { "max_per_session": 500 }
}
```
- **动作**：`approve`、`deny`、`escalate`（转入 Claude
Code 的常规权限提示）。
- **带覆盖的拒绝**：规则 `deny` 会以*询问*的形式呈现，用户可以
覆盖；添加 `"hard_deny": true` 可直接阻止。循环检测
的拒绝总是进行强制阻断——这就是防失控刹车。
- **限制是针对每个 Claude 会话的**：`max_per_session`、`max_per_minute`、
`max_consecutive`。每次对话都有其独立的额度。
- **Fail-open**：如果 Kaptn 无法运行（Python 版本过旧、状态损坏），它
会静默地转入 Claude Code 的常规权限流程。Kaptn 只会
*减少*提示，绝不会扩大无人值守运行的范围。
配置更改会在下一次工具调用时生效——无需重启。
## 审计追踪
每一个决策——允许、拒绝、询问、循环刹车——都被记录在 SQLite
（`~/.kaptn/kaptn_audit.db`）中，包含时间戳、会话、类别、确切的
命令或路径、匹配的规则，以及当时的限制状态。
```
scripts/kaptn-ctl log -n 50 # or /kaptn:log in a session
```
## 进阶：daemon 模式
如需长时间运行的决策服务器（实时 HTTP 状态端点、launchd
集成），请安装该软件包并使用完整的 CLI：
```
python3 -m venv .venv && .venv/bin/pip install -e .
.venv/bin/kaptn help
```
`kaptn claude install` 会注册一个基于设置的 hook，与 localhost 上的
`kaptn claude serve` 进行通信；`kaptn status` / `kaptn stop` /
`kaptn reset` 可用于管理任一模式。详见
[docs/CLAUDE_CODE.md](docs/CLAUDE_CODE.md)。
## 出处
提取自 [MicahAI/Kaptn](https://github.com/MicahAI/Kaptn)，该项目还可以通过 Chrome DevTools Protocol 远程控制 Windsurf/Cascade。
此仓库是仅针对 Claude 的版本：相同的规则引擎，被打包为
一流的 Claude Code 插件。
## 许可证
MIT
标签：AI编程辅助, Claude Code, Homebrew安装, TCP/UDP协议, 审计日志, 工具调用授权, 自动化控制, 逆向工具