# Claude Code Hooks

本目录包含 ai-proj-helper 体系的 Claude Code 钩子脚本。

**REQ-20260416-0017 P0 批 — 源自 devflow-claude 借鉴**

## 脚本清单

| 脚本 | 事件 | 作用 |
|------|------|------|
| `session-context.sh` | SessionStart | 从分支名解析 REQ-ID，注入需求上下文到会话 |
| `pre-tool-confirm.sh` | PreToolUse (Bash) | 拦截生产发布、force push、docker 生产容器、reset --hard 等危险操作 |

## 安装（用户级，一次即可）

### 方式 1：编辑 `~/.claude/settings.json`

```jsonc
{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/Users/donglinlai/coding/qiudl/ai-proj-helper/hooks/session-context.sh",
            "timeout": 10
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "/Users/donglinlai/coding/qiudl/ai-proj-helper/hooks/pre-tool-confirm.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}
```

### 方式 2：一键安装脚本

```bash
bash /Users/donglinlai/coding/qiudl/ai-proj-helper/hooks/install.sh
```

## 验证

### SessionStart hook

1. 切到一个带 REQ-ID 的分支：`git checkout feat/REQ-20260416-0017-xxx`
2. 打开新的 Claude Code 会话
3. 会话开头应看到 `# 需求上下文（SessionStart Hook）` 块

### PreToolUse hook

让 AI 尝试执行这些命令中的任一条，应弹出原生确认对话框：

- `git push origin main`
- `git push --force`
- `tea pr merge --base main`
- `docker rm ai_postgres_prod`
- `git reset --hard`

## 依赖

- `bash` (macOS / Linux 默认)
- `jq` (PreToolUse hook 需要，`brew install jq`)
- `python3` (SessionStart hook 解析 JSON)
- `curl` (SessionStart hook 调 MCP API)

## 自定义

### 修改 MCP API 地址

在项目根目录创建 `.ai-proj-env`：

```bash
export AI_PROJ_API_BASE="https://api.ai-proj.example.com"
export AI_PROJ_MCP_KEY="your-mcp-api-key"
```

或设置全局环境变量。

### 拦截更多命令

编辑 `pre-tool-confirm.sh`，在 `REASON` 赋值的 elif 链中增加规则。

## 设计原则

1. **快速失败退出**：不处理的命令立即 `exit 0`，不影响性能
2. **非侵入性**：网络/依赖缺失时静默退出，不阻塞正常工作流
3. **可复现**：hook 脚本跟随仓库分发，方便团队一致部署