多智能体可观测性系统

通过全面的钩子事件追踪，为 Claude Code 代理提供实时监控与可视化功能。欢迎点击此处观看【关于使用 Opus 4.6 进行多智能体编排的最新深度解析】（https://youtu.be/RpUTF_U4kiw）。借助 Claude Opus 4.6 以及多智能体编排功能，您现在可以快速组建由专业代理组成的团队，这些代理可并行工作；而这一可观测性系统则能让您追踪整个集群中每一次工具调用、任务交接以及代理生命周期中的各类事件。

🎯 概述

本系统通过实时捕获、存储并可视化 Claude Code 的【钩子事件】（https://docs.anthropic.com/en/docs/claude-code），为 Claude Code 代理的行为提供完整的可观测性支持。借助会话跟踪、事件过滤以及实时更新等功能，该系统能够实现对多个并发代理的全方位监控。

🏗️ 架构

Claude 代理 → 钩子脚本 → HTTP POST → Bun 服务器 → SQLite → WebSocket → Vue 客户端

📋 设置要求

在开始之前，请确保已安装以下组件：

• Claude Code - Anthropic 提供的 Claude 官方 CLI 工具
• Astral uv - 快速 Python 包管理器（用于钩子脚本）
• Bun、npm 或 yarn - 用于运行服务器和客户端
• just（可选） - 项目配方的命令行运行器
• Anthropic API 密钥 - 设置为 ANTHROPIC_API_KEY 环境变量
• OpenAI API 密钥（可选） - 用于在使用“just-prompt MCP”工具时实现多模型支持
• ElevenLabs API 密钥（可选） - 用于音频功能
• Firecrawl API 密钥（可选） - 用于网页抓取功能

配置 .claude 目录

要在您的代码库中启用可观测性功能，需将 .claude 目录复制到项目根目录。

要将可观测性钩子集成到您的项目中：

1. 将整个 .claude 目录复制到项目根目录：

   cp -R .claude /path/to/your/project/
   

2. 更新 settings.json 配置：

   打开项目中的 .claude/settings.json 文件，并将 source-app 参数修改为您的项目标识：

   {
     "hooks": {
       "PreToolUse": [
         {
           "matcher": "",
           "hooks": [
             {
               "type": "command",
               "command": "uv run .claude/hooks/pre_tool_use.py"
             },
             {
               "type": "command",
               "command": "uv run .claude/hooks/send_event.py --source-app YOUR_PROJECT_NAME --event-type PreToolUse --summarize"
             }
           ]
         }
       ],
       "PostToolUse": [
         {
           "matcher": "",
           "hooks": [
             {
               "type": "command",
               "command": "uv run .claude/hooks/post_tool_use.py"
             },
             {
               "type": "command",
               "command": "uv run .claude/hooks/send_event.py --source-app YOUR_PROJECT_NAME --event-type PostToolUse --summarize"
             }
           ]
         }
       ],
       "UserPromptSubmit": [
         {
           "hooks": [
             {
               "type": "command",
               "command": "uv run .claude/hooks/user_prompt_submit.py --log-only"
             },
             {
               "type": "command",
               "command": "uv run .claude/hooks/send_event.py --source-app YOUR_PROJECT_NAME --event-type UserPromptSubmit --summarize"
             }
           ]
         }
       ]
       // ... （适用于所有 12 个钩子事件的类似模式：通知、停止、子代理停止、子代理启动、预压缩、会话启动、会话结束、权限请求、后工具使用失败）
     }
   }
   

   请将 YOUR_PROJECT_NAME 替换为您的项目唯一标识（例如：my-api-server、react-app 等）。

3. 确保可观测性服务器正在运行：

   # 从可观测性项目目录（即该代码库）中运行
   ./scripts/start-system.sh
   

现在，每当 Claude Code 执行相关操作时，您的项目便会将事件发送至可观测性系统。

🚀 快速入门

您可以通过运行本仓库的 .claude 配置，快速了解其工作原理。

# 1. 启动服务器与客户端
just start          # 或者：./scripts/start-system.sh

# 2. 在浏览器中打开 http://localhost:5173

# 3. 打开 Claude Code 并运行以下命令：
运行 `git ls-files`，以了解代码库的整体结构。

# 4. 在客户端中实时查看事件流

# 5. 将 `.claude` 文件夹复制到其他希望发送事件的项目中。
cp -R .claude <您希望发送事件的代码库所在目录>

使用 just（推荐）

justfile 可以为您提供便捷的常见操作配方：

just              # 列出所有可用的配方
just start        # 启动服务器 + 客户端
just stop         # 停止所有进程
just restart      # 先停止再启动
just server       # 仅启动服务器（开发模式）
just client       # 仅启动客户端
just install      # 安装所有依赖项
just health       # 检查服务器/客户端的状态
just test-event   # 发送一个测试事件
just db-reset     # 重置数据库
just hooks        # 列出所有钩子脚本
just open         # 在浏览器中打开仪表板

📁 项目结构

claude-code-hooks-multi-agent-observability/
│
├── apps/                    # 应用组件
│   ├── server/             # Bun TypeScript 服务器
│   │   ├── src/
│   │   │   ├── index.ts    # 主服务器，包含 HTTP 和 WebSocket 端点
│   │   │   ├── db.ts       # SQLite 数据库管理与迁移
│   │   │   └── types.ts    # TypeScript 接口
│   │   ├── package.json
│   │   └── events.db       # SQLite 数据库（已忽略）
│   │
│   └── client/             # Vue 3 TypeScript 客户端
│       ├── src/
│       │   ├── App.vue     # 主应用，支持主题与 WebSocket 管理
│       │   ├── components/
│       │   │   ├── EventTimeline.vue      # 带自动滚动功能的事件列表
│       │   │   ├── EventRow.vue           # 单个事件展示
│       │   │   ├── FilterPanel.vue        # 多选筛选器
│       │   │   ├── ChatTranscriptModal.vue # 聊天历史查看器
│       │   │   ├── StickScrollButton.vue  # 滚动控制按钮
│       │   │   └── LivePulseChart.vue     # 实时活动图表
│       │   ├── composables/
│       │   │   ├── useWebSocket.ts        # WebSocket 连接逻辑
│       │   │   ├── useEventColors.ts      # 颜色分配系统
│       │   │   ├── useChartData.ts        # 图表数据聚合
│       │   │   └── useEventEmojis.ts      # 事件类型表情符号映射
│       │   ├── utils/
│       │   │   └── chartRenderer.ts       # Canvas 图表渲染
│       │   └── types.ts    # TypeScript 接口
│       ├── .env.sample     # 环境配置模板
│       └── package.json
│
├── .claude/                # Claude Code 集成
│   ├── hooks/             # Hook 脚本（Python + uv）
│   │   ├── send_event.py          # 通用事件发送器（涵盖全部 12 种事件类型）
│   │   ├── pre_tool_use.py        # 工具验证、阻断与汇总
│   │   ├── post_tool_use.py       # 结果日志记录，并结合 MCP 工具检测
│   │   ├── post_tool_use_failure.py # 工具失败日志记录
│   │   ├── permission_request.py  # 权限请求日志记录
│   │   ├── notification.py        # 用户交互事件（基于类型感知的 TTS）
│   │   ├── user_prompt_submit.py  # 用户提示日志记录与验证
│   │   ├── stop.py               # 会话结束（通过 stop_hook_active 保护机制）
│   │   ├── subagent_stop.py      # 子代理完成任务，并跟踪转录路径
│   │   ├── subagent_start.py     # 子代理生命周期启动追踪
│   │   ├── pre_compact.py        # 根据自定义指令进行上下文压缩
│   │   ├── session_start.py      # 以代理类型与模型启动会话
│   │   ├── session_end.py        # 会话结束时进行原因追踪
│   │   └── validators/           # 保护机制验证器
│   │       ├── validate_new_file.py     # 验证文件创建
│   │       └── validate_file_contains.py # 验证文件内容部分
│   │
│   ├── agents/team/       # 代理团队定义
│   │   ├── builder.md     # 工程化代理，配备 linting hook
│   │   └── validator.md   # 只读验证代理
│   │
│   ├── commands/          # 自定义斜杠命令
│   │   └── plan_w_team.md # 团队协作规划命令
│   │
│   ├── status_lines/      # 状态行脚本
│   │   └── status_line_v6.py # 上下文窗口使用情况显示
│   │
│   └── settings.json      # Hook 配置（涵盖全部 12 种事件）
│
├── justfile               # 任务运行器脚本（just start、just stop 等）
│
├── scripts/               # 实用脚本
│   ├── start-system.sh   # 启动服务器与客户端
│   ├── reset-system.sh   # 停止所有进程
│   └── test-system.sh    # 系统验证
│
└── logs/                 # 应用日志（已忽略）

🔧 组件详情

1. Hook 系统（.claude/hooks/）

如果你想精通 Claude Code 的 Hook，请观看 此视频。

Hook 系统可拦截 Claude Code 生命周期中的各类事件：

• send_event.py：核心脚本，负责将事件数据发送至可观测性服务器

  • 支持全部 12 种 Hook 事件类型，并对事件字段进行特定转发
  • 支持使用 --add-chat 标志，以纳入对话历史
  • 将事件特有字段（如 tool_name、tool_use_id、agent_id、notification_type 等）作为顶级属性进行转发，以便更便捷地进行查询
  • 在发送前验证服务器连接是否正常

• 事件专用 Hook（共 12 个）：每个 Hook 都实现了验证与数据提取功能

  • pre_tool_use.py：阻止危险命令，对工具使用情况进行验证，并按工具类型汇总工具输入
  • post_tool_use.py：通过 MCP 工具检测（如 mcp_server、mcp_tool_name）捕捉执行结果
  • post_tool_use_failure.py：记录工具执行失败的日志
  • permission_request.py：记录权限请求事件
  • notification.py：根据 notification_type 感知用户交互，通过 TTS 进行跟踪（如权限提示、空闲提示等）
  • user_prompt_submit.py：记录用户提示，并支持 JSON 格式验证，符合 {"decision": "block"} 的模式
  • stop.py：通过 stop_hook_active 保护机制记录会话结束，防止无限循环
  • subagent_stop.py：监控子代理任务完成情况，并跟踪转录路径
  • subagent_start.py：追踪子代理生命周期的启动事件
  • pre_compact.py：根据自定义指令，对上下文进行压缩，并在备份文件名中保留相关指示
  • session_start.py：记录会话启动时的 agent_type、model 以及 source 字段
  • session_end.py：记录会话结束时的原因追踪（包括 bypass_permissions_disabled）

2. 服务器（apps/server/）

Bun 提供的 TypeScript 服务器，具备实时能力：

• 数据库：SQLite，采用 WAL 模式，支持并发访问
• 端点：
  • POST /events - 接收来自代理的事件
  • GET /events/recent - 分页获取事件，并支持筛选
  • GET /events/filter-options - 显示可用的筛选选项
  • WS /stream - 实时广播事件
• 功能：
  • 自动完成 Schema 迁移
  • 事件验证
  • 通过 WebSocket 向所有客户端进行广播
  • 聊天转录数据存储

3. 客户端（apps/client/）

基于 Vue 3 的实时可视化应用：

• 视觉设计：

  • 双色系统：应用颜色（左侧边框）+ 会话颜色（第二侧边框）
  • 渐变指示器，用于实现清晰的视觉区分
  • 支持深浅主题切换
  • 响应式布局，搭配流畅的动画效果

• 功能特性：

  • 实时 WebSocket 更新
  • 多条件筛选（应用、会话、事件类型）
  • 实时脉冲图，以会话色条和事件类型指示器呈现
  • 时间范围选择（1分钟、3分钟、5分钟），并自动进行数据聚合
  • 聊天记录查看器，支持语法高亮显示
  • 自动滚动，同时支持手动控制
  • 事件限制功能（可通过 VITE_MAX_EVENTS_TO_DISPLAY 进行配置）

• 工具表情符号系统：

  • 每种工具类型都配有专属的表情符号（如 Bash：💻、阅读：📖、写作：✍️、编辑：✏️、任务：🤖 等）
  • 工具事件会显示组合表情符号：事件表情符号 + 工具表情符号（例如，PreToolUse:Bash 代表 PreToolUse：Bash）
  • MCP 工具以 🔌 前缀显示
  • 工具名称徽章会与事件类型一同显示在时间轴上

• 实时脉冲图：

  • 基于 Canvas 的实时可视化
  • 每个柱状图均采用会话特定的颜色
  • 柱状图上会显示事件类型与工具组合表情符号
  • 动画流畅，且带有发光效果
  • 对过滤器变化高度自适应

🔄 数据流

1. 事件生成：Claude Code 执行某项操作（如工具使用、通知等）
2. 钩子激活：根据 settings.json 配置，运行相应的钩子脚本
3. 数据采集：钩子脚本收集上下文信息（工具名称、输入、输出、会话 ID）
4. 数据传输：send_event.py 通过 HTTP POST 将 JSON 数据包发送至服务器
5. 服务器处理：
   • 验证事件结构
   • 以 SQLite 存储数据，并附带时间戳
   • 向 WebSocket 客户端广播事件
6. 客户端更新：Vue 应用接收事件，并实时更新时间轴

🎨 事件类型与可视化

事件类型	表情符号	用途	颜色编码	特殊显示
PreToolUse	🔧	工具执行前	会话相关	工具名称 + 工具表情符号及详细信息
PostToolUse	✅	工具执行后	会话相关	工具名称 + 工具表情符号及结果
PostToolUseFailure	❌	工具执行失败	会话相关	错误详情及中断状态
PermissionRequest	🔐	请求权限	会话相关	工具名称及权限建议
Notification	🔔	用户交互	会话相关	通知消息及类型
Stop	🛑	响应完成	会话相关	总结与聊天记录
SubagentStart	🟢	子代理启动	会话相关	代理 ID 及类型
SubagentStop	👥	子代理完成	会话相关	代理详情及记录路径
PreCompact	📦	上下文压缩	会话相关	触发器及自定义指令
UserPromptSubmit	💬	用户提示提交	会话相关	提示内容：“用户消息”（斜体）
SessionStart	🚀	会话启动	会话相关	来源、模型及代理类型
SessionEnd	🏁	会话结束	会话相关	结束原因（清除/退出/离开/其他）

用户提示提交事件（v1.0.54+）

UserPromptSubmit 钩子会在 Claude 处理用户提示之前捕获所有用户提示。在 UI 中：

• 显示为“用户消息”（斜体文本）
• 在内联中展示实际的提示内容（截断至 100 个字符）
• 当启用 AI 摘要功能时，右侧会显示摘要
• 有助于追踪用户意图和对话流程

🔌 集成

新项目

1. 复制事件发送者：

   cp .claude/hooks/send_event.py YOUR_PROJECT/.claude/hooks/
   

2. 在 .claude/settings.json 中添加：

   {
     "hooks": {
       "PreToolUse": [{
         "matcher": ".*",
         "hooks": [{
           "type": "command",
           "command": "uv run .claude/hooks/send_event.py --source-app YOUR_APP --event-type PreToolUse"
         }]
       }]
     }
   }
   

本项目

已成功集成！钩子既可执行验证，又具备可观测性：

{
  "type": "command",
  "command": "uv run .claude/hooks/pre_tool_use.py"
},
{
  "type": "command",
  "command": "uv run .claude/hooks/send_event.py --source-app cc-hook-multi-agent-obvs --event-type PreToolUse"
}

🧪 测试

# 系统验证
./scripts/test-system.sh

# 快速测试事件，仅需执行
just test-event

# 检查服务器/客户端健康状况
just health

# 手动测试事件
curl -X POST http://localhost:4000/events \
  -H "Content-Type: application/json" \
  -d '{
    "source_app": "test",
    "session_id": "test-123",
    "hook_event_type": "PreToolUse",
    "payload": {"tool_name": "Bash", "tool_input": {"command": "ls"}}
  }'

# 直接测试钩子脚本
just hook-test pre_tool_use

⚙️ 配置

环境变量

将 .env.sample 复制到项目根目录下的 .env 文件中，并填写您的 API 密钥：

应用根目录（.env 文件）：

• ANTHROPIC_API_KEY – Anthropic Claude API 密钥（必填）
• ENGINEER_NAME – 您的姓名（用于日志记录/身份识别）
• OPENAI_API_KEY – OpenAI API 密钥（可选）
• ELEVENLABS_API_KEY – ElevenLabs API 密钥（可选，用于 TTS）
• FIRECRAWL_API_KEY – Firecrawl API 密钥（可选，用于网页抓取）

客户端（.env 文件，位于 apps/client/.env）：

• VITE_MAX_EVENTS_TO_DISPLAY=100 – 最大显示事件数量（超出时会移除最旧的事件）

服务器端口

• 服务器：4000（HTTP/WebSocket）
• 客户端：5173（Vite 开发服务器）

🤖 代理团队

本项目支持 Claude Code 代理团队，用于协调多代理工作流。团队可通过 .claude/settings.json 中的 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 环境变量启用。

团队代理

• 构建者（.claude/agents/team/builder.md）：负责单次执行一项任务的工程代理。包含 PostToolUse 钩子，用于对 Write/Edit 操作进行 ruff 和 ty 验证。
• 验证者（.claude/agents/team/validator.md）：只读验证代理，可在不修改文件的情况下对工作进行检查。无法使用 Write、Edit 或 NotebookEdit 工具。

与团队协作规划

使用 /plan_w_team 切换命令，创建基于团队的实施计划：

/plan_w_team "新增 X 功能"

此命令会生成一个规格文档，位于 specs/ 目录下，其中包含任务分解、团队成员分配、依赖关系以及验收标准。计划会经过 Stop 钩子验证器的校验，确保各必填部分均已完整填写。

执行计划的方式如下：

/build specs/<plan-name>.md

🔭 多智能体编排与可观测性

智能体工程真正的挑战已不再在于模型能做什么——而是我们能否精准地引导工程师并为他们构建所需的结果，并将这些结果转化为可重用的系统。多智能体编排通过让您可以快速组建由专业智能体组成的团队，使每个智能体都能在某一特定任务上发挥卓越能力，实现并行工作，并在任务完成后自动关闭。如需完整参考，请参阅官方提供的 Claude Code 智能体团队文档。

编排工作流

完整的多智能体编排生命周期遵循以下模式：

1. 创建团队 — TeamCreate 用于搭建协调层
2. 创建任务 — TaskCreate 构建集中式任务列表，驱动所有工作流程
3. 启动智能体 — Task 将专用智能体（如构建器、验证器等）部署到各自的 Tmux 窗口中，每个智能体拥有独立的上下文窗口
4. 并行执行任务 — 智能体同时执行各自分配的任务，并通过 SendMessage 进行通信
5. 终止智能体 — 完成任务的智能体将被优雅地终止
6. 删除团队 — TeamDelete 清理所有协调状态

可观测量的重要性

当您有多个智能体并行运行——每个智能体都拥有自己的上下文窗口、会话 ID 和任务分配——您就需要实时了解整个群体中正在发生的一切。若缺乏可观测性，您只能在规模上进行“氛围式”编码。而有了可观测性，您就可以：

• 通过仪表板实时追踪所有智能体间的每一条工具调用
• 依据智能体所属的泳道进行筛选，以深入分析单个智能体的行为
• 跟踪任务的生命周期——查看 TaskCreate、TaskUpdate 和 SendMessage 事件在各智能体之间流转的过程
• 提前发现故障——在 PostToolUseFailure 和 PermissionRequest 事件中，问题会在连锁反应发生之前被及时发现
• 测量系统的吞吐量——实时脉冲图能够清晰展示您的智能体群组中的活动密度

正是这一点，将工程师与“氛围式”编码者区分开来：只有真正理解底层运作机制，您才能自信地扩展计算资源，从而以更稳健的方式提升影响力。

🛡️ 安全功能

• 通过 deny_tool() JSON 模式阻止危险的 rm -rf 命令（仅允许在特定目录中执行）
• 防止访问敏感文件（.env、私钥）
• 在 stop.py 和 subagent_stop.py 中加入 stop_hook_active 保护机制，防止无限循环的钩子触发
• 钩子验证器确保在计划文件完成前，已包含必要的字段
• 执行前对所有输入进行验证

📊 技术栈

• 服务器：Bun、TypeScript、SQLite
• 客户端：Vue 3、TypeScript、Vite、Tailwind CSS
• 钩子：Python 3.11+、Astral uv、TTS（ElevenLabs 或 OpenAI）、大语言模型（Claude 或 OpenAI）
• 通信：HTTP REST、WebSocket

主导 AI 智能体编码

并为软件工程的未来做好准备

学习战术智能体编码模式，尽在 战术智能体编码

关注 IndyDevDan YouTube 频道，不断提升您的智能体编码优势。

Claude Code 多智能体可观测系统 · 快速上手指南

环境准备

组件	版本要求	安装命令（国内镜像）
Claude Code	最新版	npm install -g @anthropic-ai/claude-code
uv	≥0.2	`curl -LsSf https://astral.sh/uv/install.sh
Bun	≥1.1	`curl -fsSL https://bun.sh/install
just（可选）	≥1.25	cargo install just

国内用户可把 https://bun.sh/install 换成 https://mirrors.tuna.tsinghua.edu.cn/bun/install.sh

环境变量

export ANTHROPIC_API_KEY="sk-ant-xxx"
# 可选
export OPENAI_API_KEY="sk-xxx"
export ELEVENLABS_API_KEY="xxx"
export FIRECRAWL_API_KEY="xxx"

安装步骤

1. 克隆仓库

git clone https://github.com/disler/claude-code-hooks-multi-agent-observability.git
cd claude-code-hooks-multi-agent-observability

2. 一键安装依赖

just install        # 或手动：
# cd apps/server && bun install
# cd apps/client && bun install

3. 启动系统

just start          # 或 ./scripts/start-system.sh

4. 浏览器打开 http://localhost:5173

基本使用

1. 体验演示

# 在任意目录启动 Claude Code
claude

# 在 Claude 里执行
Run git ls-files to understand the codebase.

浏览器会实时滚动显示事件。

2. 接入自己的项目

# 复制钩子目录
cp -R .claude /path/to/your/project/

# 修改项目名
sed -i 's/YOUR_PROJECT_NAME/my-app/g' /path/to/your/project/.claude/settings.json

3. 常用命令

just open           # 打开仪表盘
just test-event     # 发送测试事件
just db-reset       # 清空数据
just stop           # 停止服务

完成！现在所有 Claude Code 操作都会实时出现在仪表盘。