一个完整的 Go 实现的 Claude AI 编程助手钩子系统，将所有 Shell 脚本的功能统一为一个 CLI 工具，每个子命令对应一个原始脚本的功能。

claude-hooks 是一套质量控制框架，覆盖代码质量、文档规范、安全防护、工作流控制等多个维度。所有代码都包含完整的中文注释，便于理解和扩展，并已对齐 Claude Code Hooks 官方 API：

• 输入字段遵循 session_id/transcript_path/hook_event_name 等标准命名，兼容顶层与 tool_input。
• 输出统一为 decision/reason/hookSpecificOutput JSON；阻断时返回退出码 2，其余为 0。

子命令	原始脚本	功能说明	复杂度
deny-check	deny-check.sh	命令拒绝检查	⭐⭐⭐⭐
check-ai-commit	check-ai-commit.sh	AI 签名检查	⭐⭐
check-continue	check-continue.sh	工作状态检查	⭐⭐⭐⭐⭐
check-plan	check-project-plan.sh	项目计划提醒	⭐
preserve-perms	preserve-file-permissions.sh	文件权限保护	⭐⭐⭐⭐
space-format	space-format.sh	中英文间距格式化	⭐⭐⭐⭐
auto-comment	auto-comment.sh	注释检查	⭐⭐
debug	debug-hook.sh	调试日志	⭐

第一梯队（最高优先级）：

子命令	功能说明	生命周期阶段	优先级
config-validator	配置文件验证器	PreToolUse	⭐⭐⭐⭐⭐
dependency-change-detector	依赖变更检测器	PostToolUse	⭐⭐⭐⭐⭐
test-coverage-reminder	测试覆盖提醒	PostToolUse	⭐⭐⭐⭐⭐
env-health-checker	环境健康检查	SessionStart	⭐⭐⭐⭐
session-summary-generator	会话摘要生成器	SessionEnd	⭐⭐⭐⭐

第二梯队（中优先级）：

子命令	功能说明	生命周期阶段	优先级
log-security-checker	日志安全检查	PreToolUse	⭐⭐⭐⭐
context-priority-marker	上下文优先级标记	PreCompact	⭐⭐⭐⭐
api-breaking-change-detector	API 破坏性变更检测	PostToolUse	⭐⭐⭐⭐
code-complexity-analyzer	代码复杂度分析	PostToolUse	⭐⭐⭐
subagent-quality-checker	子代理质量检查	SubagentStop	⭐⭐⭐

第三梯队（低优先级）：

子命令	功能说明	生命周期阶段	优先级
db-migration-reminder	数据库迁移提醒	PostToolUse	⭐⭐⭐
error-code-validator	错误码一致性检查	PreToolUse	⭐⭐⭐
i18n-string-checker	国际化字符串检查	PostToolUse	⭐⭐⭐
notification-enhancer	通知增强器	Notification	⭐⭐⭐
performance-regression-detector	性能回归检测	Stop	⭐⭐⭐

特殊功能：

子命令	功能说明	生命周期阶段	优先级
skill-activation-prompt	技能激活提示	UserPromptSubmit	⭐⭐⭐⭐

# 克隆或进入项目目录
cd /tmp/ccline

# 下载依赖
go mod download

# 构建二进制文件
go build -o bin/claude-hooks cmd/claude-hooks/main.go

# 查看帮助
./bin/claude-hooks --help

# 查看特定命令的帮助
./bin/claude-hooks deny-check --help

# 运行特定命令
echo '{"tool": "Bash", "tool_input": {"command": "rm -rf /"}}' | \
  ./bin/claude-hooks deny-check --log-level debug

安全防护的关键功能，防止 AI 执行危险命令。

工作原理：

1. 从 ~/.claude/settings.json 读取拒绝模式
2. 支持通配符模式匹配（如 rm -rf *）
3. 按分隔符 ;, &&, || 分割命令进行逐个检查
4. 任何片段匹配拒绝模式就拒绝执行

配置示例：

{
  "permissions": {
    "deny": ["Bash(rm -rf /)", "Bash(dd *)", "Bash(mkfs*)", "Bash(: | sudo:*)"]
  }
}

确保提交信息中没有 AI 生成标识，符合 CLAUDE.md 规范。

检测的 AI 签名：

• 🤖 Generated with
• Generated with Claude
• co-authored-by Claude
• AI Generated
• 其他类似标识

工作流控制的核心功能，智能判断 AI 是否完成工作。

多层检测逻辑（优先级从高到低）：

1. 错误检测 - 致命错误时停止催促

   • 403 错误、积分不足、网络超时等

2. 暗号检测 - 工作完成标识

   • 相信美好的事情即将发生. - 工作完成
   • 任务书需确认. - 需要用户确认

3. 重复检测 - 防止循环催促

   • 检测到已有催促提示时停止

4. 确认检测 - 等待用户输入

   • 检测 [y/n]、(yes/no) 等确认模式

5. spec 模式检测 - spec 工作流中不催促

   • 检测 /spec, /spec-init 等命令

防止编辑工具改变文件权限（特别是可执行文件）。

工作方式：

• 保存阶段（编辑前）：获取文件权限保存到缓存
• 恢复阶段（编辑后）：立即恢复权限，3 秒后再次恢复（双重保险）

自动格式化，符合《中文文案排版指北》规范。

格式化规则：

1. 中文 + 英文/数字 -> 插入空格（"我是 developer" -> "我是 developer"）
2. 英文/数字 + 中文 -> 插入空格（"I am 开发者" -> "I am 开发者"）
3. 中文 + 左括号 -> 插入空格（"这个(内容)" -> "这个 (内容)"）
4. 右括号 + 中文 -> 插入空格（"(内容)这个" -> "(内容) 这个"）
5. 右括号 + 英文/数字 -> 插入空格（"(content) 2023" -> "(content) 2023"）
6. 百分号 + 中文 -> 插入空格（"100%的人" -> "100% 的人"）
7. 保护命令替换 $(...)
8. 清除括号后的不必要空格

排除列表（space-exclusions.json）：

{
  "exclusions": ["iPhone", "MacBook", "Go语言", "API接口", "TCP/IP"]
}

提醒为新建文件和大规模编辑添加文档注释。

检查内容：

• Write 工具（新建文件）：要求添加文档注释
• MultiEdit 工具（大规模编辑）：要求检查文档完整性

检查当前会话是否存在项目计划，提示用户查看。

文件位置： ~/.claude/todos/{sessionID}.json

记录钩子执行的时间戳和输入数据，便于调试。

日志文件： /tmp/claude-hook-debug.log

使用方法：

# 查看实时日志
tail -f /tmp/claude-hook-debug.log

# 清空日志
./bin/claude-hooks debug

claude-hooks/
├── cmd/
│   └── claude-hooks/
│       └── main.go                 # CLI 主入口（cobra 框架）
├── internal/
│   ├── hooks/                      # 8个功能模块
│   │   ├── deny_check.go           # 命令拒绝检查 + glob 模式匹配
│   │   ├── ai_commit.go            # AI 签名检查
│   │   ├── continue_check.go       # 工作状态检查（最复杂）
│   │   ├── preserve_perms.go       # 文件权限保护
│   │   ├── space_format.go         # 中英文间距格式化 + 8条正则规则
│   │   ├── auto_comment.go         # 注释检查
│   │   ├── check_plan.go           # 项目计划提醒
│   │   └── debug.go                # 调试日志
│   ├── config/
│   │   └── config.go               # 配置文件管理 + JSON I/O
│   ├── types/
│   │   └── types.go                # 公共类型定义
│   └── utils/
│       ├── string.go               # 字符串工具
│       ├── file.go                 # 文件操作工具 + 跨平台兼容
│       └── platform.go             # 平台检测（如需要）
├── go.mod                          # 依赖管理
├── go.sum                          # 依赖锁定
└── README.md                       # 本文档

• 所有代码都包含详细的中文注释
• 每个函数都有功能说明和工作原理
• 复杂算法包含步骤分解注释

• 每个功能独立为一个模块
• 接口清晰，易于扩展
• 依赖关系简单明确

• 自动适配 macOS/Linux 差异
• 处理 BSD stat 和 GNU stat 不同
• 兼容不同的 sed 命令选项

• 使用 github.com/darkit/slog 标准库
• 支持多级日志（debug, info, warn, error）
• 便于调试和监控

• 正则表达式优化
• 文件缓存策略
• 并发处理（延迟权限恢复）

在 Claude 的钩子配置中调用：

# deny-check hook
./bin/claude-hooks deny-check < $CLAUDE_TOOL_INPUT

# check-ai-commit hook
./bin/claude-hooks check-ai-commit < $CLAUDE_TOOL_INPUT

# space-format hook
./bin/claude-hooks space-format < $CLAUDE_TOOL_INPUT

# 检查特定命令是否安全
echo '{"tool": "Bash", "tool_input": {"command": "ls"}}' | \
  ./bin/claude-hooks deny-check

# 格式化文件间距
./bin/claude-hooks space-format --script-dir .claude/scripts

import "cnb.cool/svn/claude-hooks/internal/hooks"

// 直接调用 Hook 函数
output := hooks.DenyCheck(input)

想要开发新的 Hook 功能或深入了解系统架构？请查阅以下文档：

Hook 开发指导手册 - 1500+ 行完整教程

包含内容：

• ✅ Hook 系统架构详解
• ✅ 9 个生命周期阶段深度剖析
• ✅ 从零开发简单 Hook（step-by-step）
• ✅ 从零开发复杂 Hook（完整示例）
• ✅ 8 个代码模板库
• ✅ 15 个新功能实现指南
• ✅ 测试、调试、性能优化
• ✅ 常见问题解答

Hook 快速参考 - 300 行速查手册

包含内容：

• 🔍 常用代码片段
• 📊 API 速查表
• 🎯 生命周期阶段速查
• 📝 配置文件格式
• 🐛 故障排查清单
• ⚡ 性能优化技巧

示例 Hook 实现 - 可运行的示例

包含文件：

• simple_hook.go - 简单 Hook 示例（TODO 检测器）
• complex_hook.go - 复杂 Hook 示例（配置文件验证器）
• hook_test.go - 完整的测试用例

1. 初学者：阅读快速参考手册 → 运行示例代码 → 修改简单示例
2. 进阶开发者：阅读完整开发指南 → 开发复杂 Hook → 贡献新功能
3. 系统架构师：深入研究生命周期阶段 → 设计 Hook 协同 → 优化系统性能

---

1. 在 internal/hooks/ 创建新文件

package hooks

func NewFeature(input *types.HookInput) *types.HookOutput {
    // 实现功能逻辑
    return &types.HookOutput{Continue: true}
}

2. 在 cmd/claude-hooks/main.go 添加命令

var newFeatureCmd = &cobra.Command{
    Use: "new-feature",
    Short: "新功能说明",
    RunE: func(cmd *cobra.Command, args []string) error {
        input, _ := config.LoadJSONFromStdin()
        output := hooks.NewFeature(input)
        return config.OutputJSON(output)
    },
}

func init() {
    rootCmd.AddCommand(newFeatureCmd)
}

3. 编写中文注释和文档

💡 提示：详细步骤请参考 Hook 开发指导手册 第 7 章和第 8 章

go build ./...
go vet ./...

go test ./...

• .claude/scripts/ - 原始 Shell 脚本
• CLAUDE.md - 项目规范和最佳实践
• ~/.claude/settings.json - 拒绝命令配置
• ~/.claude/todos/ - 项目计划存储
• /tmp/claude_file_permissions.txt - 权限缓存
• /tmp/claude-hook-debug.log - 调试日志

相比 Shell 脚本的优势：

方面	Shell	Go
启动时间	~100ms	~5ms
JSON 解析	jq	标准库
正则支持	基础	完整
类型检查	无	静态
可维护性	低	高

MIT License

欢迎提交 PR 和 Issue。所有代码应遵循以下规范：

1. 完整的中文注释
2. 遵循 Go 官方风格指南
3. 单元测试覆盖
4. 提交信息符合规范

A: 使用 --log-level debug 标志查看详细日志：

./bin/claude-hooks deny-check --log-level debug < input.json

A:

• settings.json: ~/.claude/settings.json
• space-exclusions.json: .claude/scripts/space-exclusions.json

A: 直接删除缓存文件：

rm /tmp/claude_file_permissions.txt
rm /tmp/claude-hook-debug.log

A: 支持 Linux 和 macOS，已做跨平台兼容处理。

• 完整实现所有 8 个 Hook 功能
• 所有代码包含详细中文注释
• 支持 cobra CLI 框架
• 完整的模块化设计
• 跨平台兼容

---

快速链接：

• 原始 Shell 脚本
• 项目规范
• Issue Tracker