johnQ
b390c29af3
skill-gate / gate (pull_request) Waiting to run
- scan-skill.sh: loopback 不算风险、命中走允许清单 - 11 个文件的 /Users/<机器名> 绝对路径去环境化（脚本 $HOME、文档 ~） - 允许清单登记运维环境地址与示例占位符（非凭据），附理由 - scan: 57 warns -> 0 warns / 0 high - 新增 .gitea/workflows/skill-gate.yml（validate --strict + scan + catalog --check + 测试）
101 lines
2.4 KiB
Markdown
101 lines
2.4 KiB
Markdown
# 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": "~/coding/qiudl/ai-proj-helper/hooks/session-context.sh",
|
||
"timeout": 10
|
||
}
|
||
]
|
||
}
|
||
],
|
||
"PreToolUse": [
|
||
{
|
||
"matcher": "Bash",
|
||
"hooks": [
|
||
{
|
||
"type": "command",
|
||
"command": "~/coding/qiudl/ai-proj-helper/hooks/pre-tool-confirm.sh",
|
||
"timeout": 30
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 方式 2：一键安装脚本
|
||
|
||
```bash
|
||
bash ~/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 脚本跟随仓库分发，方便团队一致部署
|