# 调试工具 (Debugging Tools)

## 1. 概述

调试是软件开发中不可或缺的一环，而对于复杂的、由LLM驱动的Agent应用来说，调试尤其具有挑战性。传统的调试器（如pdb）在面对非确定性、分布式、长链条的Agent执行过程时，往往力不从心。因此，我们需要一套专门为Agent应用设计的、可视化的、交互式的调试工具，以帮助开发者快速定位和解决问题。

## 2. 设计目标

*   **可视化 (Visualization)**: 将抽象的Agent执行过程以直观、易于理解的图形化界面展示出来。
*   **可追溯性 (Traceability)**: 能够清晰地追溯任何一个输出结果的完整生成路径，包括所有的中间步骤、数据和决策。
*   **交互性 (Interactivity)**: 允许开发者在调试过程中与Agent进行交互，例如检查中间状态、修改数据、甚至手动触发某个步骤。
*   **低侵入性 (Low-Intrusiveness)**: 调试工具本身不应显著影响Agent的正常运行性能，并可以按需开启或关闭。

## 3. 核心调试工具

### 3.1 可视化认知流 (Visual Cognitive Flow)

这是一个Web界面的调试工具，它将Agent处理一个任务的完整认知流程（Cognitive Flow）以流程图或泳道图的形式展示出来。

*   **界面组件**:
    *   **任务列表**: 显示最近执行的任务列表，点击可查看详情。
    *   **主视图**: 以图形化方式展示选定任务的执行流程图。每个节点代表一个执行单元（如Planner, Tool Caller, RAG, Responder等）。
    *   **节点详情面板**: 点击流程图中的任意节点，可以查看该节点的详细信息，包括：
        *   **输入 (Input)**: 该节点接收到的完整输入数据（如Prompt, 上下文）。
        *   **输出 (Output)**: 该节点生成的完整输出数据（如LLM的原始响应, 工具调用的结果）。
        *   **配置 (Configuration)**: 该节点的关键配置信息（如使用的模型、温度参数等）。
        *   **耗时 (Duration)**: 该节点的执行耗时。
    *   **时间线视图**: 按时间顺序展示所有事件和日志。

*   **数据流**: 
    1.  Agent框架在执行过程中，通过一个标准的事件总线（Event Bus）发出各种调试事件（如`step_started`, `step_finished`, `llm_queried`, `tool_called`）。
    2.  这些事件被一个调试服务（Debug Service）捕获，并持久化存储（如存入一个SQLite或MongoDB数据库）。
    3.  调试工具的Web前端通过API从调试服务中拉取数据，并进行可视化渲染。

### 3.2 时间旅行调试 (Time-Travel Debugging)

时间旅行调试是可视化认知流的进一步增强。它不仅记录了执行的“快照”，还允许开发者“回放”整个执行过程。

*   **核心功能**:
    *   **执行回放**: 在可视化认知流的界面上，提供一个播放控件（播放、暂停、上一步、下一步），允许开发者像看视频一样，一步步地回放整个任务的执行过程。
    *   **状态检查**: 在回放的任何一个时间点，都可以暂停并检查当时Agent的完整状态，包括内存、上下文、变量值等。
    *   **假设分析 (What-if Analysis)**: （高级功能）在回放过程中，允许开发者修改某个节点的输入或输出，然后从该点开始重新执行，以观察不同的执行路径和结果。例如，“如果当时LLM返回的是另一个工具调用会怎么样？”

*   **实现原理**: 
    *   要实现时间旅行，需要在事件收集中记录下每个步骤之间传递的、完整的、可序列化的数据状态。这会带来较大的存储开销，因此通常只在开发环境或按需开启。

## 4. 与其他组件的集成

*   **CLI**: `agent run --debug` 命令可以一键启动Agent应用和与之配套的调试工具Web UI。
*   **SDK**: SDK提供的API在执行时，会自动发出调试事件。开发者也可以通过SDK提供的`debugger`对象，在自己的能力代码中发送自定义的调试事件。
    ```python
    from agent_sdk.debug import debugger

    @capability(name="my_custom_logic")
    def my_logic(input):
        # ... some logic ...
        processed_data = process(input)
        # 发送一个自定义调试事件，可以在UI中看到
        debugger.log("Data processed", data=processed_data)
        # ... more logic ...
    ```
*   **IDE集成**: 在VS Code等IDE中，可以直接启动调试会话，并在代码中设置“认知断点”（Cognitive Breakpoint）。当Agent执行到某个特定能力或步骤时，会自动暂停，并在IDE中激活相关的调试视图。

## 5. 实现考量

*   **性能开销**: 调试信息的收集和存储会带来性能开销。需要提供不同级别的调试模式（如`off`, `basic`, `full`），并允许开发者通过配置来控制调试信息的粒度。
*   **UI技术栈**: Web UI可以使用现代前端框架（如React, Vue）来构建，利用D3.js或Mermaid.js等库来绘制流程图。
*   **数据存储**: 调试数据可以存储在文件中（如SQLite），也可以存储在专门的NoSQL数据库中，以便于查询和分析。