← 返回信息流
AI 资讯Hacker News·6 天前

用于构建 Claude Code 挂钩的 Python 实用包

原标题：Python utility package for building Claude Code hooks

速览

该Python实用包旨在简化Claude Code挂钩的开发过程。它提供了构建自定义挂钩所需的工具，使开发者能够扩展Claude Code的功能。这一工具对于希望深度定制AI编程助手的开发者具有重要意义。

AI 深度解读

Python 工具包 claude-hook-utils：简化 Claude Code 钩子开发

背景

Anthropic 推出的 Claude Code 是一款强大的 AI 编程助手，它允许开发者通过“钩子（Hooks）”机制在代码执行的关键节点插入自定义逻辑。这种机制赋予了开发者对 AI 行为的高度控制权，例如在执行工具调用前进行验证、在工具执行后响应结果、拦截用户提示词，或在会话开始时初始化状态。

然而，原生构建这些钩子面临着显著的工程挑战。开发者需要处理繁琐的样板代码，包括从标准输入（stdin）解析 JSON、验证输入数据结构、按照特定 Schema 格式化响应以及优雅地处理错误。这种重复性的工作不仅降低了开发效率，还增加了出错的风险。为了解决这一痛点，社区推出了 claude-hook-utils 这一 Python 实用程序包，旨在通过最小化样板代码，让开发者能够专注于核心的验证逻辑。

核心内容

claude-hook-utils 是一个轻量级的 Python 库，专门用于构建 Claude Code 的自定义钩子脚本。它通过提供类型安全的数据类、构建器模式以及辅助方法，极大地简化了钩子的开发流程。

核心功能与特性

  1. 最小化样板代码：该包自动处理了从 stdin 读取 JSON、解析输入、验证结构以及格式化响应等底层细节。开发者只需关注业务逻辑。
  2. 类型安全与结构化：
    • 使用 Typed Dataclasses 定义输入数据，确保类型安全。
    • 提供响应构建器模式，方便构造符合官方 Schema 的输出。
  3. 明确的控制权：虽然提供了输入辅助方法，但开发者完全掌控何时跳过、允许或拒绝钩子的执行。
  4. 多钩子支持：单个 Python 程序可以同时处理多种类型的钩子事件。
  5. 无重型依赖：核心包依赖极少。如果需要使用 AI SDK，开发者可自行引入，保持了库的轻量级特性。

支持的钩子类型

该库支持 Claude Code 的四种主要钩子事件：

  • PreToolUse：在工具执行前验证工具调用。
  • PostToolUse：在工具执行后响应结果。
  • UserPromptSubmit：在 Claude 看到用户提示词之前进行拦截。
  • SessionStart：在会话开始时初始化状态。

开发示例与实现逻辑

开发者只需继承 HookHandler 类并覆盖所需的方法即可。以下是一个验证 PHP 数据类是否包含 TypeScript 注解的示例：

from claude_hook_utils import HookHandler, PreToolUseInput, PreToolUseResponse

class DataClassValidator(HookHandler):
    def pre_tool_use(self, input: PreToolUseInput) -> PreToolUseResponse | None:
        # 如果不是数据类文件，则跳过
        if not input.file_path_matches('**/app/Data/**/*.php'):
            return None
        
        # 检查是否包含必需的注解
        if input.content and '#[TypeScript()]' not in input.content:
            return PreToolUseResponse.deny(
                "Data classes must have #[TypeScript()] annotation for type generation"
            )
        return PreToolUseResponse.allow()

if __name__ == "__main__":
    DataClassValidator().run()

在此示例中，PreToolUseInput 提供了丰富的上下文信息，如 session_id、cwd、tool_name（如 Write, Edit, Bash）以及 tool_input。它还提供了便捷的辅助方法，如 file_path_matches() 用于路径匹配，以及属性访问器如 file_path、content 和 command，以便快速获取工具输入中的特定字段。

响应方面，PreToolUseResponse 提供了静态方法：

  • allow(reason=None)：允许工具执行。
  • deny(reason)：阻止工具执行，并将原因作为反馈展示给 Claude。
  • ask(reason)：请求用户确认后再继续。
  • with_updated_input(**updates)：在允许执行的同时修改工具输入。

配置与集成

钩子脚本需要在 .claude/settings.json 中进行配置。例如，将上述验证器配置为在 Write 或 Edit 工具调用前执行：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "python3 /path/to/data_class_validator.py"
          }
        ]
      }
    ]
  }
}

调试与日志记录

为了便于调试，该库内置了基于 JSONL（JSON Lines）格式的日志记录功能。日志按命名空间（插件名称）组织，默认存储在 {cwd}/.claude/logs/{namespace}/hooks.jsonl。

开发者可以通过 HookLogger 轻松集成日志：

from claude_hook_utils import HookHandler, HookLogger

class MyHandler(HookHandler):
    def __init__(self):
        super().__init__(
            logger=HookLogger.create_default("MyHandler", namespace="my-plugin")
        )

    def pre_tool_use(self, input: PreToolUseInput) -> PreToolUseResponse | None:
        self.logger.info("Checking file", file_path=input.file_path)
        # ... 验证逻辑 ...
        self.logger.decision("allow", reason="Validation passed")
        return PreToolUseResponse.allow()

日志输出包含时间戳、级别、钩子名称、命名空间、会话 ID 以及消息内容，支持通过环境变量 CLAUDE_HOOK_LOG_DIR 和 CLAUDE_HOOK_LOG_NAMESPACE 自定义日志路径和命名空间。

更多应用场景

该库适用于多种代码规范检查场景：

  • Vue 组件验证：检查 <script>、<template> 和 <style> 标签的顺序，以及是否使用了 <script setup lang="ts">。
  • 控制器路径验证：确保 PHP 控制器文件位于 app/Http/Controllers/ 目录下。
  • 架构规范检查：禁止在控制器中使用 FormRequest 类，强制使用 Data 类。
  • 文件追踪：通过维护内部状态（如 _pending_writes 集合），在 pre_tool_use 和 post_tool_use 之间跟踪文件写入操作。

关键要点

  • 简化开发：claude-hook-utils 消除了处理 JSON 解析、输入验证和响应格式化的重复性样板代码。
  • 类型安全：利用 Python 的 Typed Dataclasses 和类型提示，提供清晰的输入输出结构，减少运行时错误。
  • 灵活的控制流：支持 allow、deny、ask 以及修改输入等操作，赋予开发者对 AI 行为的细粒度控制。
  • 轻量级架构：核心包依赖极少，易于集成到现有项目中，不引入沉重的运行时负担。
  • 内置调试支持：提供标准化的 JSONL 日志记录，便于追踪钩子执行过程和调试问题。
  • 广泛适用性：适用于多种编程语言和框架的代码规范检查（如 PHP、Vue.js），支持路径匹配和内容内容检查。

意义与影响

claude-hook-utils 的出现标志着 AI 辅助编程工具从“被动响应”向“主动治理”迈出了重要一步。

首先，它降低了自定义 AI 行为的工作门槛。以往，构建可靠的钩子需要开发者深入理解 Claude Code 的内部通信协议和 JSON 结构，而现在，通过一个简单的 Python 库，开发者可以像编写普通单元测试一样编写钩子逻辑。这将促进团队内部代码规范的自动化执行，例如强制特定的文件结构、命名约定或安全最佳实践。

其次，它增强了 AI 编程的可预测性和安全性。通过 PreToolUse 钩子，开发者可以在 AI 实际修改文件之前拦截并验证其意图，防止错误的代码生成或潜在的安全漏洞。这种“人在回路”（Human-in-the-loop）或“策略在回路”（Policy-in-the-loop）的机制，使得 AI 能够更紧密地融入现有的工程工作

相关推荐

查看原文 →github.com