# 1639 Spec 8e3cf9db > agent-debug-sidebar Specification - Skill: `tools-only/1639-spec-8e3cf9db` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add tools-only/1639-spec-8e3cf9db` - Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/1639-spec-8e3cf9db/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tools-only (https://skillmd.com/u/tools-only) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/tools-only/1639-spec-8e3cf9db --- # agent-debug-sidebar Specification ## Purpose TBD - created by archiving change add-agent-debug-sidebar. Update Purpose after archive. ## Requirements ### Requirement: Debug Event Streaming 系统 SHALL 在 SSE 流中新增 `debug` 类型事件，承载 Agent 执行链路的调试信息。 - 系统 SHALL 在 OrchestratorAgent 完成意图分类后发射 `debug(classification)` 事件，包含 intent、rationale、selected_agent、stock_codes - 系统 SHALL 在路由到子 Agent 前发射 `debug(routing)` 事件，包含 from_agent、to_agent、is_parallel 标志 - 系统 SHALL 在 Agent 开始执行时发射 `debug(agent_start)` 事件，包含 agent 名称、input_summary 和可选的 parent_agent（嵌套调用场景） - 系统 SHALL 在 Agent 执行完成时发射 `debug(agent_end)` 事件，包含 duration_ms 和 tool_calls_count - 系统 SHALL 在 Tool 调用完成时发射 `debug(tool_result)` 事件，包含 tool 名称、args、result_summary 和 duration_ms - 系统 SHALL 在 Agent 间任务移交时发射 `debug(handoff)` 事件，包含 from_agent、to_agent 和 shared_data_summary - 系统 SHALL 在 Agent 间通过共享缓存传递数据时发射 `debug(data_sharing)` 事件，包含 from_agent、to_agent、data_key 和 data_summary - 系统 SHALL 保证 `debug` 事件不影响现有 thinking/tool/content/done/error 事件的发送和处理 - 系统 SHALL 在 `done` 事件的 metadata 中收集所有 `debug_events` 数组用于持久化 #### Scenario: Orchestrator 意图分类后发送分类调试事件 - **GIVEN** 用户发送消息 "分析贵州茅台的日K线" - **WHEN** OrchestratorAgent 完成 LLM 意图分类 - **THEN** SSE 流中产出一条 `{type: "debug", debug_type: "classification"}` 事件 - **AND** 事件 data 包含 `intent`, `rationale`, `selected_agent`, `stock_codes` #### Scenario: Agent 执行开始和结束时发送边界事件 - **GIVEN** Orchestrator 将请求路由到 MarketAgent - **WHEN** MarketAgent 开始执行 - **THEN** SSE 流中产出 `{type: "debug", debug_type: "agent_start", agent: "MarketAgent"}` - **WHEN** MarketAgent 执行完成 - **THEN** SSE 流中产出 `{type: "debug", debug_type: "agent_end", agent: "MarketAgent", data: {duration_ms, tool_calls_count, success}}` #### Scenario: Tool 调用完成时发送结果摘要事件 - **GIVEN** MarketAgent 正在执行中 - **WHEN** 工具 `get_daily_data` 调用完成并返回结果 - **THEN** SSE 流中产出 `{type: "debug", debug_type: "tool_result"}` 事件 - **AND** 事件 data 包含 `tool`, `args`, `result_summary`, `duration_ms` #### Scenario: 多 Agent 并行执行时发送各自独立的调试事件 - **GIVEN** 用户查询涉及多个 Agent 并行处理 - **WHEN** Orchestrator 并发调度 MarketAgent 和 ReportAgent - **THEN** 每个 Agent 分别产出独立的 agent_start/tool_result/agent_end 事件 - **AND** 每条事件的 `agent` 字段标识所属 Agent #### Scenario: debug 事件向后兼容 - **GIVEN** 前端版本不识别 `debug` 事件类型 - **WHEN** 收到 `debug` 类型 SSE 事件 - **THEN** 前端忽略该事件，不影响现有对话功能 #### Scenario: Agent Handoff 移交时发送 handoff 事件 - **GIVEN** MarketAgent 完成技术分析 - **WHEN** Orchestrator 根据 AGENT_HANDOFF_MAP 将任务移交给 BacktestAgent - **THEN** SSE 流中产出 `{type: "debug", debug_type: "handoff"}` 事件 - **AND** 事件 data 包含 `from_agent: "MarketAgent"`, `to_agent: "BacktestAgent"`, `shared_data_summary` #### Scenario: Agent 嵌套调用时标记父子关系 - **GIVEN** ChatAgent 通过 execute_workflow 工具函数创建 WorkflowAgent - **WHEN** WorkflowAgent 开始执行 - **THEN** SSE 流中产出 `{type: "debug", debug_type: "agent_start", data: {parent_agent: "ChatAgent"}}` 事件 #### Scenario: Agent 间通过共享缓存传递数据时发送 data_sharing 事件 - **GIVEN** MarketAgent 将行情数据写入 AgentSharedCache - **WHEN** ReportAgent 从缓存读取该数据 - **THEN** SSE 流中产出 `{type: "debug", debug_type: "data_sharing"}` 事件 - **AND** 事件 data 包含 `from_agent`, `to_agent`, `data_key`, `data_summary` --- ### Requirement: A2A Interaction Visualization 系统 SHALL 在调试侧栏中可视化 Agent 间的交互关系，包括并行执行、任务移交、嵌套调用和数据共享四种模式。 - 系统 SHALL 对并行执行的 Agent 以泳道（Swim Lanes）模式展示，每个 Agent 占据独立列 - 系统 SHALL 对 Agent Handoff 移交以带箭头的连接消息展示，标注来源 Agent、目标 Agent 和共享数据摘要 - 系统 SHALL 对嵌套调用的子 Agent 以缩进嵌套方式展示在父 Agent 区块内部 - 系统 SHALL 对 Agent 间数据共享以系统通知消息展示，标注数据来源、目标和数据摘要 #### Scenario: 并行 Agent 以泳道模式展示 - **GIVEN** Orchestrator 并发调度 MarketAgent 和 ReportAgent - **WHEN** 调试侧栏渲染这两个 Agent 的事件流 - **THEN** MarketAgent 和 ReportAgent 的调试消息分别在左右两个泳道中展示 - **AND** 各泳道内的消息按时间排列，包含各自的 tool 调用和完成状态 #### Scenario: Agent Handoff 以箭头连接展示 - **GIVEN** MarketAgent 执行完成后移交给 BacktestAgent - **WHEN** 调试侧栏渲染 handoff 事件 - **THEN** 显示带箭头的紫色连接消息 `📊 MarketAgent → 🔬 BacktestAgent` - **AND** 展示移交的共享数据摘要 #### Scenario: 嵌套调用以缩进子级展示 - **GIVEN** ChatAgent 内部创建并执行了 WorkflowAgent - **WHEN** 调试侧栏渲染 WorkflowAgent 的事件 - **THEN** WorkflowAgent 的所有调试消息以缩进方式嵌套在 ChatAgent 的消息区块内 - **AND** 嵌套区块有明显的左边框标识层级关系 #### Scenario: 数据共享以系统通知展示 - **GIVEN** MarketAgent 通过 AgentSharedCache 向 ReportAgent 传递了股票数据 - **WHEN** 调试侧栏渲染 data_sharing 事件 - **THEN** 显示居中的系统通知消息 - **AND** 标注 `MarketAgent → ReportAgent` 和数据键名及摘要 --- ### Requirement: Agent Debug Sidebar UI 系统 SHALL 在对话界面右侧提供可折叠的调试侧栏，以群聊式消息流展示 Agent 执行链路。 - 系统 SHALL 提供调试开关按钮，点击后在右侧展开调试侧栏 - 系统 SHALL 默认收起调试侧栏，不影响对话主区域的可用性 - 系统 SHALL 以时间顺序展示 Orchestrator 调度消息（蓝色气泡）、Agent 执行消息（绿色气泡）、Tool 调用消息（灰色系统消息） - 系统 SHALL 为不同 Agent 分配独立的图标以便区分 - 系统 SHALL 支持 Tool 调用消息的折叠/展开，展开后显示 args 代码块和 result_summary #### Scenario: 用户打开调试侧栏查看实时推理过程 - **GIVEN** 用户在对话界面中 - **WHEN** 用户点击调试开关按钮 - **THEN** 右侧展开调试侧栏（默认 360px 宽度） - **AND** 侧栏以时间序列展示调试消息流 #### Scenario: 群聊式消息展示不同角色 - **GIVEN** 调试侧栏已打开且正在流式响应 - **WHEN** 收到不同类型的 debug 事件 - **THEN** Orchestrator 消息以蓝色气泡左对齐展示（头像 🤖） - **AND** Agent 消息以绿色气泡左对齐展示（各 Agent 有独立图标） - **AND** Tool 调用以灰色系统消息居中展示（图标 🔧） #### Scenario: Tool 调用展示输入输出详情 - **GIVEN** 调试侧栏收到 tool_result 事件 - **WHEN** 渲染该条调试消息 - **THEN** 默认显示工具名称和耗时的摘要行 - **AND** 点击展开后显示 args（JSON 代码块）和 result_summary（折叠区域） #### Scenario: 侧栏默认折叠不影响对话体验 - **GIVEN** 用户首次使用对话功能 - **WHEN** 进入对话界面 - **THEN** 调试侧栏默认收起，仅在右侧边缘显示一个展开图标按钮 - **AND** 对话主区域占满剩余宽度 --- ### Requirement: Debug History Playback 系统 SHALL 支持查看历史消息的调试信息，从消息 metadata 中恢复完整推理链路。 - 系统 SHALL 在 assistant 消息上提供"查看调试"入口 - 系统 SHALL 将调试数据随消息 metadata.debug_events 持久化到数据库 - 系统 SHALL 从 metadata 中恢复历史调试消息并在侧栏展示 #### Scenario: 查看历史消息的调试详情 - **GIVEN** 用户浏览历史对话消息 - **WHEN** 用户点击某条 assistant 消息上的"查看调试"按钮 - **THEN** 右侧调试侧栏展开 - **AND** 显示该条消息对应的完整 Agent 调试链路 #### Scenario: 调试数据随消息持久化 - **GIVEN** 一次对话流式响应完成 - **WHEN** assistant 消息保存到数据库 - **THEN** 该消息的 metadata 中包含 `debug_events` 字段 --- ### Requirement: Debug Timeline Overview 系统 SHALL 在调试侧栏顶部提供执行时间线概览，可视化 Agent 和 Tool 的执行时序。 - 系统 SHALL 以横向时间条展示各 Agent 的执行区间 - 系统 SHALL 对并行执行的 Agent 用多行展示 #### Scenario: 显示 Agent 执行时间线 - **GIVEN** 调试侧栏已打开 - **WHEN** 一次对话涉及 Orchestrator → MarketAgent 的调度链路 - **THEN** 侧栏顶部显示横向时间线 - **AND** 时间线上标注各阶段的时间区间 #### Scenario: 并行 Agent 在时间线上多行显示 - **GIVEN** 一次对话并行执行了 MarketAgent 和 ReportAgent - **WHEN** 查看调试时间线 - **THEN** MarketAgent 和 ReportAgent 在时间线上分别占据独立的行 --- ### Requirement: Responsive Layout 系统 SHALL 保证调试侧栏适配不同屏幕宽度，不损害对话主区域的可用性。 - 系统 SHALL 在视口宽度 ≥ 1400px 时以三栏并列模式展示 - 系统 SHALL 在视口宽度 1024-1400px 时以 overlay 模式展示调试侧栏 - 系统 SHALL 在视口宽度 < 1024px 时以 drawer 模式展示调试侧栏 #### Scenario: 大屏三栏并列布局 - **GIVEN** 浏览器视口宽度 ≥ 1400px - **WHEN** 调试侧栏打开 - **THEN** 会话列表、对话主区、调试侧栏三栏并列显示 #### Scenario: 中屏覆盖模式 - **GIVEN** 浏览器视口宽度在 1024-1400px 之间 - **WHEN** 调试侧栏打开 - **THEN** 调试侧栏以 overlay 模式覆盖在对话区域上方 - **AND** 可通过点击遮罩或关闭按钮收起