SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场agent-flow-visualization

agent-flow-visualization

编程与开发

查看项目

更新于 10-14 19:31

技能介绍

Agent Flow 是一款 VS Code 扩展，用于实时可视化 Claude Code 智能体编排。它把智能体执行渲染为可交互的节点图，展示工具调用、分支、子智能体协作与耗时，将 Claude Code 的黑盒执行变为透明、可调试的流程。

用途

Agent Flow 面向需要观察和调试 Claude Code 智能体运行过程的开发者。它把智能体的执行过程以节点图形式呈现，帮助定位失败的工具调用、意外的分支、重复循环以及耗时异常等问题。

主要能力

  • 实时可视化：以交互式节点图渲染 Claude Code 智能体编排，展示工具调用、分支、子智能体协调与时间信息。
  • 节点类型：图中包含智能体/子智能体（圆形）、工具调用（矩形）、工具结果（虚线矩形）、分支（菱形）、返回（箭头）等节点。
  • 多会话支持：以标签页跟踪多个并发的 Claude Code 会话，每个会话拥有独立的可视化画布。
  • 交互画布：支持平移（拖拽空白画布）、缩放（滚轮/捏合）、点击节点查看详情、双击空白画布重置视图。
  • 面板：提供时间线（按时间顺序展示所有事件及耗时）、对话记录（智能体与工具之间的完整消息历史）、文件热力图（哪些文件受到最多关注）。
  • 事件流方式：通过 Claude Code 钩子系统实现零延迟事件流；也可读取 JSONL 事件日志文件进行回放或监控。

使用方式

安装：

  • 通过 VS Code Marketplace：打开 VS Code 扩展（Cmd+Shift+X），搜索 "Agent Flow"（作者 simon-p），点击安装；或直接访问 marketplace.visualstudio.com/items?itemName=simon-p.agent-flow。

要求：

  • VS Code 1.85 或更高版本
  • 已安装并可访问 Claude Code CLI
  • Node.js（用于 Claude Code）

快速开始：

  1. 打开命令面板：Cmd+Shift+P（Mac）/ Ctrl+Shift+P（Win/Linux）
  2. 运行命令：> Agent Flow: Open Agent Flow
  3. 在工作区中启动 Claude Code 会话，Agent Flow 会自动检测并开始流式传输。

键盘快捷键：Mac 为 Cmd+Alt+A；Win/Linux 为 Ctrl+Alt+A。

命令：

  • Agent Flow: Open Agent Flow：在当前编辑器列打开可视化器
  • Agent Flow: Open Agent Flow to Side：在侧边编辑器列打开
  • Agent Flow: Connect to Running Agent：手动连接到特定智能体会话
  • Agent Flow: Configure Claude Code Hooks：设置 Claude Code 钩子以进行实时事件流传输

配置（settings.json）：

  • agentVisualizer.eventLogPath：要监视/回放的 JSONL 事件日志文件路径
  • agentVisualizer.autoOpen：智能体会话开始时自动打开可视化器
  • agentVisualizer.devServerPort：开发服务器端口（0 = 生产模式，使用构建产物）

Claude Code 钩子设置： Agent Flow 使用 Claude Code 的钩子系统实现零延迟事件流。首次打开时会自动配置钩子，也可通过命令面板运行 "Agent Flow: Configure Claude Code Hooks" 手动重新配置。手动配置时，Agent Flow 会启动一个本地 HTTP 服务器接收事件，钩子将 Claude Code 生命周期事件（工具调用、响应、会话开始/结束）转发给扩展。钩子在 ~/.claude/settings.json 或项目级 .claude/settings.json 中配置，包含 PreToolUse 和 PostToolUse 等，命令形如 curl -s -X POST http://localhost:PORT/hook -H 'Content-Type: application/json' -d @-。Agent Flow 会自动管理该配置，建议优先使用命令面板命令。

JSONL 事件日志模式： 用于回放过去的会话或监视在 VS Code 之外生成的日志文件。设置 agentVisualizer.eventLogPath 指向日志文件，Agent Flow 会跟踪该文件并在事件到达时可视化。适用场景包括：智能体运行的事后调试、与队友共享智能体执行记录、CI/CD 流水线智能体监控。

JSONL 事件格式：每行是一个 JSON 事件对象，例如： {"type":"session_start","sessionId":"abc123","timestamp":"2026-03-21T10:00:00Z","model":"claude-opus-4-5"} {"type":"tool_use","sessionId":"abc123","toolName":"bash","input":{"command":"ls -la"},"timestamp":"2026-03-21T10:00:01Z"} {"type":"tool_result","sessionId":"abc123","toolName":"bash","output":"total 48\n...","timestamp":"2026-03-21T10:00:02Z"} {"type":"message","sessionId":"abc123","role":"assistant","content":"I can see the files...","timestamp":"2026-03-21T10:00:03Z"}

适用场景

  • 调试失败的智能体运行：观察图中红色/错误节点、意外分支、循环（智能体重复尝试同一工具），点击失败的工具节点检查输入/输出，查看时间线面板找出耗时异常的工具调用。
  • 回放已保存的会话：将 Claude Code 输出保存为 JSONL，再让 Agent Flow 指向该文件。
  • 自动可视化所有智能体会话：设置 agentVisualizer.autoOpen 为 true。
  • 并排编码与可视化：使用 "Agent Flow: Open Agent Flow to Side" 在分屏编辑器中打开可视化器，同时保持代码文件可访问。

限制与注意事项

  • 需要 VS Code 1.85 或更高版本。
  • 需要已安装并可访问 Claude Code CLI 以及 Node.js。
  • 若设置了 agentVisualizer.eventLogPath，Agent Flow 会从文件读取而非使用钩子；如需实时钩子流式传输，应清空该设置。
  • 多会话按 Claude Code 的唯一会话 ID 区分；若会话合并异常，需检查每个 claude 进程是否全新启动（未复用已有会话 ID）。
  • 故障排查：若未检测到会话，确认 Claude Code 在同一工作区文件夹运行、钩子已配置、钩子服务器正在运行（Output 面板查看 "Agent Flow hook server listening"），或使用 "Connect to Running Agent" 手动指定会话；若图为空或不更新，检查 eventLogPath 设置并重载 VS Code 窗口；若扩展未加载，检查 VS Code 版本与扩展是否启用。

开发与贡献

仓库：git clone https://github.com/patoles/agent-flow，然后 cd agent-flow、npm install。构建：npm run build；开发监视：npm run watch；使用开发服务器（热重载）：设置 "agentVisualizer.devServerPort": 3000 后运行 npm run dev。

扩展结构： agent-flow/ ├── src/ │ ├── extension.ts # VS Code 扩展入口点 │ ├── hookServer.ts # 接收 Claude Code 钩子事件的 HTTP 服务器 │ ├── sessionManager.ts # 管理多个智能体会话 │ ├── webviewProvider.ts # Webview 面板管理 │ └── logWatcher.ts # JSONL 文件跟踪监视器 ├── webview/ │ ├── src/ │ │ ├── App.tsx # 主 React 应用 │ │ ├── Graph.tsx # 节点图画布（可能为 D3 或 React Flow） │ │ ├── Timeline.tsx # 时间线面板 │ │ └── Transcript.tsx # 消息对话记录面板 │ └── package.json └── package.json # 扩展清单

许可证：Apache 2.0。