Hive Debugger 交互式调试伴侣，帮助开发者识别并修复Hive代理在运行时遇到的问题。该调试器分析三个层级（L1/L2/L3）的运行日志，对问题进行分类，并提供可行的修复建议。

何时使用此技能：

你的代理失败或产生意外结果时
你需要理解为什么特定节点反复重试
工具调用失败，你需要确定根本原因
代理执行停滞或耗时过长
你希望在开发期间实时监控代理行为

此技能与在TUI模式下运行的代理一起工作，提供对执行行为的监督级别洞察。

永远在线代理感知

一些代理使用terminal_nodes=[]（“永远在线”模式），意味着它们无限循环，从不进入“完成”的执行状态。对于这些代理：

状态为“进行中”或“暂停”的会话是正常的，不是失败
高步骤计数、长时间和多次节点访问是预期行为
代理仅在用户明确退出时停止 —— 没有图驱动的完成
调试重点应该放在单个节点访问和迭代的质量上，而不是会话是否达到了终端状态
对话记忆在循环中累积 —— 注意上下文溢出和陈旧数据问题

**如何识别永远在线代理：**检查agent.py或agent.json中的terminal_nodes=[]（空列表）。如果为空，则代理是永远在线的。

先决条件

在使用此技能之前，请确保：

你有一个导出的代理在exports/{agent_name}/
代理至少运行过一次（存在日志）
启用了运行时日志记录（Hive框架中的默认设置）
你可以访问代理的工作目录~/.hive/agents/{agent_name}/

工作流程

第1阶段：设置和上下文收集

**目标：**理解被调试的代理

操作：

询问开发者需要调试哪个代理：
- 获取代理名称（例如，“deep_research_agent”，“deep_research_agent”）
- 确认代理存在于exports/{agent_name}/
确定代理工作目录：
- 计算：~/.hive/agents/{agent_name}/
- 验证此目录存在并包含会话日志
读取代理配置：
- 读取文件：exports/{agent_name}/agent.json
- 从JSON中提取目标信息：
  - goal.id - 目标标识符
  - goal.success_criteria - 成功的样子
  - goal.constraints - 代理必须遵循的规则
- 提取图信息：
  - 从graph.nodes中列出节点ID
  - 从graph.edges中列出边
存储调试会话的上下文：
- agent_name
- agent_work_dir（例如，/home/user/.hive/deep_research_agent）
- goal_id
- success_criteria
- constraints
- node_ids

示例：

开发者：“我的deep_research_agent代理一直在失败”

你：“我将帮助调试deep_research_agent代理。让我收集上下文...”

[读取exports/deep_research_agent/agent.json]

收集到的上下文：
- 代理：deep_research_agent
- 目标：deep-research
- 工作目录：/home/user/.hive/deep_research_agent
- 成功标准：[“制作一份有引用来源的综合研究报告”]
- 约束：[“必须引用所有来源”，“必须涵盖多个视角”]
- 节点：[“intake”，“research”，“analysis”，“report-writer”]

第2阶段：模式选择

**目标：**选择最适合当前情况的调试方法

操作：

询问开发者他们想要使用哪种调试模式。使用AskUserQuestion提供这些选项：

实时监控模式
- 描述：连续监控活跃的TUI会话，每5-10秒轮询一次日志，立即警报新问题
- 最适合：你希望实时捕捉问题时的现场调试会话
- 注意：需要代理目前正在运行
事后分析模式
- 描述：详细分析已完成或失败的运行，深入研究特定会话
- 最适合：理解为什么过去的执行失败
- 注意：调试中最常见的模式
历史趋势模式
- 描述：分析多次运行中的模式，识别反复出现的问题
- 最适合：寻找反复发生的系统性问题
- 注意：对于运行了很多次的代理很有用

实现：

使用AskUserQuestion呈现这些选项并让开发者选择。
存储会话中选定的模式。

第3阶段：分诊（L1分析）

**目标：**确定哪些会话需要关注

操作：

使用MCP工具查询高层运行摘要：

query_runtime_logs(
    agent_work_dir="{agent_work_dir}",
    status="needs_attention",
    limit=20
)

分析结果：
- 查看needs_attention: true的运行
- 检查attention_summary.categories中的问题类型
- 记录问题会话的run_id
- 检查status字段：“degraded”，“failure”，“in_progress”
- **对于永远在线代理：**状态为“进行中”或“暂停”的会话是正常的 —— 这些代理永远不会达到“完成”。只标记needs_attention: true或实际错误指示器（工具失败，重试循环，缺少输出）的会话。高步骤计数本身并不表示问题。
关注标志触发器理解： 从runtime_logger.py，当运行被标记时：
- retry_count > 3
- escalate_count > 2
- latency_ms > 60000
- tokens_used > 100000
- total_steps > 20
向开发者展示发现：
- 总结需要关注多少次运行
- 列出最近的有问题的运行
- 显示每个的注意类别
- 询问他们想要调查哪个运行（如果有多个）

示例输出：

发现2次运行需要关注：

1. session_20260206_115718_e22339c5（30分钟前）
   状态：降级
   类别：missing_outputs, retry_loops

2. session_20260206_103422_9f8d1b2a（2小时前）
   状态：失败
   类别：tool_failures, high_latency

你想要调查哪个运行？

第4阶段：诊断（L2分析）

**目标：**确定哪些节点失败以及存在的模式

操作：

使用MCP工具查询每个节点的详细信息：

query_runtime_log_details(
    agent_work_dir="{agent_work_dir}",
    run_id="{selected_run_id}",
    needs_attention_only=True
)

使用问题分类法对问题进行分类：

10个问题类别：

类别	检测模式	含义
缺少输出	`exit_status != "success"`, `attention_reasons`包含“missing_outputs”	节点没有使用set_output调用所需的键
工具错误	`tool_error_count > 0`, `attention_reasons`包含“tool_failures”	工具调用失败（API错误，超时，认证问题）
重试循环	`retry_count > 3`, `verdict_counts.RETRY > 5`	裁判反复拒绝输出
守卫失败	`guard_reject_count > 0`	输出验证失败（错误的类型，缺少键）
执行停滞	`total_steps > 20`, `verdict_counts.CONTINUE > 10`	EventLoopNode没有进展。警告：永远在线代理可能合理地有高步骤计数 —— 检查代理是否被卡在面向客户的节点（正常）与真正陷入循环
高延迟	`latency_ms > 60000`, `avg_step_latency > 5000`	慢速工具调用或LLM响应
面向客户的问题	`client_input_requested`但没有`user_input_received`	在用户输入之前过早地set_output
边缘路由错误	`exit_status == "no_valid_edge"`, `attention_reasons`包含“routing_issue”	没有边匹配当前状态
内存/上下文问题	`tokens_used > 100000`, `context_overflow_count > 0`	对话历史太长
违反约束	将输出与目标约束进行比较	代理违反了目标级别的规则

**永远在线代理警告：**如果代理使用terminal_nodes=[]，会话永远不会达到“完成”状态。这是有意为之。当调试这些代理时，重点放在：

单个节点访问是否成功（而不是图“完成”）
每个循环迭代的质量 —— 输出是否在循环中改进或降级？
面向客户的节点是否正确地阻塞用户输入
内存累积问题：前一个循环的陈旧数据，多次迭代中的上下文溢出
对话压缩行为：对话是否无限制地增长？

分析每个标记的节点：
- 节点ID和名称
- 退出状态
- 重试计数
- 裁决分布（ACCEPT/RETRY/ESCALATE/CONTINUE）
- 注意原因
- 执行的总步骤
向开发者展示诊断：
- 列出问题节点
- 对每个问题进行分类
- 突出最严重的问题
- 显示证据（重试计数，错误类型）

示例输出：

对session_20260206_115718_e22339c5的诊断：

问题节点：research
├─ 退出状态：escalate
├─ 重试计数：5（高）
├─ 裁决计数：{RETRY: 5, ESCALATE: 1}
├─ 注意原因：["high_retry_count", "missing_outputs"]
├─ 总步骤：8
└─ 类别：缺少输出 + 重试循环

根本问题：research节点因为未设置所需输出而陷入重试循环。

第5阶段：根本原因分析（L3分析）

**目标：**通过检查详细日志来理解到底出了什么问题

操作：

使用MCP工具查询详细的工具/LLM日志：

query_runtime_log_raw(
    agent_work_dir="{agent_work_dir}",
    run_id="{run_id}",
    node_id="{problem_node_id}"
)

根据问题类别进行分析：

对于缺少输出：
- 检查step.tool_calls中set_output的使用
- 查找跳过set_output的条件逻辑
- 检查LLM是否调用了其他工具
对于工具错误：
- 检查step.tool_results中的错误消息
- 识别错误类型：速率限制，认证失败，超时，网络错误
- 记录哪个特定的工具失败
对于重试循环：
- 检查裁判的step.verdict_feedback
- 查找重复的失败原因
- 确定是否每次都是一样的问题
对于守卫失败：
- 检查step.guard_results中的验证错误
- 识别缺少的键或类型不匹配
- 将实际输出与预期模式进行比较
对于执行停滞：
- 检查step.llm_response_text中的重复
- 查找LLM陷入同一行动循环
- 检查工具调用是否成功但没有进展
提取证据：
- 具体错误消息
- 工具调用参数和结果
- LLM响应文本
- 裁判反馈
- 逐步进展
制定根本原因解释：
- 清楚地说明发生了什么
- 解释为什么会发生
- 显示日志中的证据

示例输出：

对research的根本原因分析：

逐步分解：

第3步：
- 工具调用：web_search(query="latest AI regulations 2026")
- 结果：找到了相关文章和来源
- 裁决：RETRY
- 反馈："缺少所需的输出'research_findings'。你找到了来源但没有调用set_output。"

第4步：
- 工具调用：web_search(query="AI regulation policy 2026")
- 结果：找到了额外的政策信息
- 裁决：RETRY
- 反馈："仍然缺少'research_findings'。使用set_output保存你的发现。"

第5-7步：类似模式继续...

根本原因：节点成功地通过web_search找到了研究来源，但LLM没有调用set_output保存结果。它继续搜索而不是完成任务。

第6阶段：修复建议

**目标：**提供开发者可以实施的可行解决方案

操作：

根据在第4阶段识别的问题类别，使用这些模板提供具体的修复建议：

模板1：缺少输出（面向客户节点）

## 问题：面向客户节点过早set_output

**根本原因：**节点在接收用户输入之前调用了set_output

**修复：**使用STEP 1/STEP 2提示模式

**文件编辑：**`exports/{agent_name}/nodes/{node_name}.py`

**更改：**
1. 更新system_prompt以包含明确的步骤指导：
   ```python
   system_prompt = """
   第1步：分析用户输入并决定采取什么行动。
   在此步骤中不要调用set_output。

   第2步：在收到反馈或完成分析后，
   只有在那时才调用set_output并带上你结果。
   """

如果某些输入是可选的（比如重试边上的反馈），添加nullable_output_keys：
```
nullable_output_keys=["feedback"]
```

验证：

使用测试输入运行代理
验证面向客户节点在调用set_output之前等待用户输入


#### 模板2：重试循环

```markdown
## 问题：裁判反复拒绝输出

**根本原因：**{从verdict_feedback中插入具体原因}

**修复选项：**

**选项A - 如果输出实际上正确：**调整裁判评估规则
- 文件：`exports/{agent_name}/agent.json`
- 更新`evaluation_rules`部分以接受当前输出格式
- 示例：如果裁判期望列表但得到字符串，更新规则以接受两者

**选项B - 如果提示模糊：**澄清节点指令
- 文件：`exports/{agent_name}/nodes/{node_name}.py`
- 使system_prompt更明确地说明输出格式和要求
- 添加正确输出的示例

**选项C - 如果工具不可靠：**添加重试逻辑和回退
- 考虑使用替代工具
- 添加手动回退选项
- 更新提示以优雅地处理工具失败

**验证：**
- 使用测试输入运行节点
- 确认裁判在第一次尝试时接受输出
- 检查重试计数保持为0

模板3：工具错误

## 问题：{tool_name}失败，错误类型为{error_type}

**根本原因：**{从日志中插入具体错误消息}

**修复策略：**

**如果是API速率限制：**
1. 在工具重试逻辑中添加指数退避
2. 减少API调用频率
3. 考虑缓存结果

**如果是认证失败：**
1. 使用：
   ```bash
   /hive-credentials --agent {agent_name}

验证API密钥环境变量
如有需要更新mcp_servers.json

如果是超时：

在mcp_servers.json中增加超时：
```
{
  "timeout_ms": 60000
}
```
考虑使用更快的替代工具
将大请求分成小块

验证：

手动测试工具调用
确认成功响应
监控重复错误


#### 模板4：边缘路由错误

```markdown
## 问题：节点{node_id}没有有效的边缘

**根本原因：**没有边缘条件与当前状态匹配

**文件编辑：**`exports/{agent_name}/agent.json`

**分析：**
- 当前节点输出：{显示实际输出键}
- 现有边缘条件：{列出边缘条件}
- 为什么没有匹配：{解释不匹配}

**修复：**
添加缺失的边缘到图中：
```json
{
  "edge_id": "{node_id}_to_{target_node}",
  "source": "{node_id}",
  "target": "{target_node}",
  "condition": "on_success"
}

**替代方案：**更新现有边缘条件以涵盖这种情况

验证：

使用相同输入运行代理
验证边缘成功穿越
检查执行是否继续到下一个节点


#### 模板5：执行停滞

```markdown
## 问题：EventLoopNode没有进展

**根本原因：**{插入分析 - 例如，"LLM重复相同的失败行动"}

**文件编辑：**`exports/{agent_name}/nodes/{node_name}.py`

**修复：**更新system_prompt以引导LLM摆脱循环

**添加此指导：**
```python
system_prompt = """
{现有提示}

重要提示：如果工具调用多次失败：
1. 尝试替代方法或不同工具
2. 如果没有替代方案有效，用部分结果调用set_output
3. 不要重复相同的失败行动超过3次

进步比完美更重要。即使数据不完整也要向前推进。
"""

**额外修复：**降低max_iterations以防止无限循环

# 在节点配置中
max_node_visits=3  # 防止陷入僵局

验证：

使用相同输入运行节点，该输入导致停滞
验证它在合理尝试后退出（< 10步）
确认它最终调用set_output


#### 模板6：检查点恢复（修复后恢复）

```markdown
## 恢复策略：从最后一个干净检查点恢复

**情况：**你已经修复了问题，但失败的会话卡在执行中途

**解决方案：**从失败前的检查点恢复执行

### 选项A：自动从最新检查点恢复（推荐）

使用CLI参数在启动TUI时自动恢复：

```bash
PYTHONPATH=core:exports python -m {agent_name} --tui \
    --resume-session {session_id}

这将：

从state.json加载会话状态
从它暂停/失败的地方继续
立即应用你的修复

选项B：从特定检查点恢复（时间旅行）

如果你需要回到早期的点：

PYTHONPATH=core:exports python -m {agent_name} --tui \
    --resume-session {session_id} \
    --checkpoint {checkpoint_id}

示例：

PYTHONPATH=core:exports python -m deep_research_agent --tui \
    --resume-session session_20260208_143022_abc12345 \
    --checkpoint cp_node_complete_intake_143030

选项C：使用TUI命令

或者，正常启动TUI并使用命令：

# 启动TUI
PYTHONPATH=core:exports python -m {agent_name} --tui

# 在TUI中，使用命令：
/resume {session_id}                    # 从会话状态恢复
/recover {session_id} {checkpoint_id}   # 从特定检查点恢复

每个选项的使用时机：

使用/resume（或–resume-session）时：

你修复了凭证并希望重试
代理暂停了，你希望继续
代理失败了，你希望从最后状态重试

使用/recover（或–resume-session + --checkpoint）时：

你需要回到早期的检查点
你希望从特定点尝试不同的路径
调试需要时间旅行到早期状态

查找可用检查点：

使用MCP工具程序性地找到并检查检查点：

# 列出所有会话以找到失败的一个
list_agent_sessions(agent_work_dir="~/.hive/agents/{agent_name}", status="failed")

# 检查会话状态
get_agent_session_state(agent_work_dir="~/.hive/agents/{agent_name}", session_id="{session_id}")

# 找到干净的检查点以从中恢复
list_agent_checkpoints(agent_work_dir="~/.hive/agents/{agent_name}", session_id="{session_id}", is_clean="true")

# 比较检查点以了解发生了什么变化
compare_agent_checkpoints(
    agent_work_dir="~/.hive/agents/{agent_name}",
    session_id="{session_id}",
    checkpoint_id_before="cp_node_complete_intake_143030",
    checkpoint_id_after="cp_node_complete_research_143115"
)

# 在特定检查点检查内存
get_agent_checkpoint(agent_work_dir="~/.hive/agents/{agent_name}", session_id="{session_id}", checkpoint_id="cp_node_complete_intake_143030")

或在TUI中：

/sessions {session_id}

验证：

使用--resume-session立即测试你的修复
不需要从头开始运行
会话继续时应用了你的代码更改```

选择正确的模板：

将问题类别与第4阶段匹配
使用第5阶段的具体细节进行自定义
包括实际错误消息和代码片段
提供文件路径和行号（如果可能）
总是包括恢复命令（模板6）在提供修复建议后

第7阶段：验证支持

**目标：**帮助开发者确认他们的修复有效

操作：

根据修复类型建议适当的测试：

对于节点级修复：

# 使用hive-test运行基于目标的测试
/hive-test --agent {agent_name} --goal {goal_id}

# 或运行特定测试场景
/hive-test --agent {agent_name} --scenario {specific_input}

对于快速手动测试：

# 启动交互式TUI仪表板
hive tui

然后使用箭头键从列表中选择代理并按Enter运行它。

提供MCP工具查询以验证修复：

检查问题是否已解决：

query_runtime_logs(
    agent_work_dir="~/.hive/agents/{agent_name}",
    status="needs_attention",
    limit=5
)
# 如果完全修复，应显示0个结果

验证特定节点行为：

query_runtime_log_details(
    agent_work_dir="~/.hive/agents/{agent_name}",
    run_id="{new_run_id}",
    node_id="{fixed_node_id}"
)
# 应显示exit_status="success", retry_count=0

监控回归：
- 多次运行代理
- 检查类似问题是否重新出现
- 验证修复是否适用于不同的输入

提供验证清单：

验证清单：
□ 已将推荐修复应用到代码
□ 使用测试输入运行代理
□ 检查运行时日志显示没有关注标志
□ 验证特定节点成功完成
□ 使用多个输入进行测试
□ 原始问题没有回归
□ 代理满足成功标准

示例互动：

开发者：“我对research进行了修复。我该如何测试它？”

你：“让我们通过以下步骤验证修复：

1. 启动TUI仪表板：
   hive tui
   然后从列表中选择你的代理并按Enter运行它。

2. 完成后，我会检查日志...”

[开发者运行代理]

开发者：“它完成了！你能检查它是否有效吗？”

你：“正在检查...”

[调用query_runtime_log_details以获取新运行的详情]

结果：
- 节点：research
- 退出状态：成功 ✓
- 重试计数：0 ✓
- 总步骤：2 ✓
- 没有关注标志 ✓

“太棒了！修复有效。research现在：
- 第一次尝试就成功完成
- 不需要重试
- 正确调用set_output

你的代理现在应该可以正常工作了！”

MCP工具使用指南

三个级别的可观察性

L1：query_runtime_logs - 会话级摘要

**何时使用：**初步分诊，识别问题运行，监控趋势
**返回：**状态、关注标志、时间戳的运行列表

示例：

query_runtime_logs(
    agent_work_dir="/home/user/.hive/deep_research_agent",
    status="needs_attention",
    limit=20
)

L2：query_runtime_log_details - 节点级详细信息

**何时使用：**诊断哪些节点失败，理解重试模式
**返回：**每个节点的完成详细信息，重试计数，裁决

示例：

query_runtime_log_details(
    agent_work_dir="/home/user/.hive/deep_research_agent",
    run_id="session_20260206_115718_e22339c5",
    needs_attention_only=True
)

L3：query_runtime_log_raw - 步骤级详细信息

**何时使用：**根本原因分析，理解确切的失败
**返回：**完整的工具调用，LLM响应，裁判反馈

示例：

query_runtime_log_raw(
    agent_work_dir="/home/user/.hive/deep_research_agent",
    run_id="session_20260206_115718_e22339c5",
    node_id="research"
)

会话和检查点工具

list_agent_sessions - 浏览会话并过滤

**何时使用：**寻找可恢复的会话，识别失败的会话，第3阶段分诊
**返回：**状态、时间戳、is_resumable、current_node、quality的会话列表

示例：

list_agent_sessions(
    agent_work_dir="/home/user/.hive/agents/twitter_outreach",
    status="failed",
    limit=10
)

get_agent_session_state - 加载完整会话状态（不包括内存值）

**何时使用：**检查会话进度，检查is_resumable，检查路径
**返回：**用memory_keys/memory_size代替内存值的完整状态

示例：

get_agent_session_state(
    agent_work_dir="/home/user/.hive/agents/twitter_outreach",
    session_id="session_20260208_143022_abc12345"
)

get_agent_session_memory - 从会话中获取内存内容

**何时使用：**第5阶段根本原因分析，检查生成的数据
**返回：**所有内存键+值，或单个键的值

示例：

get_agent_session_memory(
    agent_work_dir="/home/user/.hive/agents/twitter_outreach",
    session_id="session_20260208_143022_abc12345",
    key="twitter_handles"
)

list_agent_checkpoints - 列出会话的检查点

**何时使用：**第6阶段恢复，寻找干净的检查点以从中恢复
**返回：**带有类型、节点、干净状态的检查点摘要

示例：

list_agent_checkpoints(
    agent_work_dir="/home/user/.hive/agents/twitter_outreach",
    session_id="session_20260208_143022_abc12345",
    is_clean="true"
)

get_agent_checkpoint - 加载特定检查点的完整状态

**何时使用：**检查检查点的确切状态，与当前状态进行比较
**返回：**完整的检查点：内存快照，执行路径，指标

示例：

get_agent_checkpoint(
    agent_work_dir="/home/user/.hive/agents/twitter_outreach",
    session_id="session_20260208_143022_abc12345",
    checkpoint_id="cp_node_complete_intake_143030"
)

compare_agent_checkpoints - 比较两个检查点之间的内存

**何时使用：**理解数据流，找到状态分歧的地方
**返回：**内存差异（添加/删除/更改的键）+执行路径差异

示例：

compare_agent_checkpoints(
    agent_work_dir="/home/user/.hive/agents/twitter_outreach",
    session_id="session_20260208_143022_abc12345",
    checkpoint_id_before="cp_node_complete_intake_143030",
    checkpoint_id_after="cp_node_complete_research_143115"
)

查询模式

模式1：自上而下的调查（最常见）

1. L1：找到问题运行
2. L2：识别失败的节点
3. L3：分析具体失败

模式2：特定节点调试

1. L2：获取所有运行中特定节点的详细信息
2. L3：深入了解最严重的失败

模式3：实时监控

每10秒循环一次：
  1. L1：检查新的需要关注运行
  2. 如果发现：警报并深入L2

模式4：会话状态+检查点恢复

1. list_agent_sessions：找到失败/暂停的会话
2. get_agent_session_state：检查是否可以恢复，查看执行路径
3. get_agent_session_memory：检查生成了哪些数据
4. list_agent_checkpoints：找到失败前干净的检查点
5. compare_agent_checkpoints：了解检查点之间发生了什么变化
6. 推荐带有特定检查点的恢复命令

完整示例演练

场景：deep_research_agent代理失败

开发者说：“我的deep_research_agent一直在失败。它没有正确保存研究结果。”

第1阶段：设置

你：“我将帮助调试deep_research_agent代理。让我收集上下文...”

[读取exports/deep_research_agent/agent.json]

上下文：
- 代理：deep_research_agent
- 目标：deep-research
- 工作目录：~/.hive/agents/deep_research_agent
- 成功标准：[“成功发送5条个性化的外展消息”]
- 约束：[“必须验证句柄存在”，“必须个性化消息”]
- 节点：research, profile-analyzer, message-composer, outreach-sender

第2阶段：模式选择

你：“你更喜欢哪种调试方法？”

[使用AskUserQuestion呈现3种模式选项]

开发者选择：“事后分析模式”

第3阶段：分诊（L1）

你：“查询运行时日志以找到问题运行...”

[调用query_runtime_logs，状态为“needs_attention”]

结果：
- 发现1次运行需要关注
- session_20260206_115718_e22339c5（30分钟前）
- 状态：降级
- 类别：missing_outputs, retry_loops

第4阶段：诊断（L2）

你：“分析节点级细节...”

[为该会话调用query_runtime_log_details]

结果：
- 问题节点：research
- 退出状态：escalate
- 重试计数：5
- 裁决计数：{RETRY: 5, ESCALATE: 1}
- 注意原因：["high_retry_count", "missing_outputs"]
- 总步骤：8

诊断：research存在重试循环+缺少输出问题
类别：缺少输出 + 重试循环

第5阶段：根本原因（L3）

你：“深入研究research的详细日志...”

[为节点research调用query_runtime_log_raw]

证据：
第3步：web_search("latest AI regulations 2026") → 找到文章
  裁决：RETRY
  反馈："缺少所需的输出'research_findings'。你找到了来源但没有调用set_output。"

第4步：web_search("AI regulation policy 2026") → 找到更多信息
  裁决：RETRY
  反馈："仍然缺少'research_findings'。使用set_output保存你的发现。"

第5-7步：相同模式重复...

根本原因：节点成功地通过web_search找到了研究来源，但LLM没有调用set_output保存结果。它继续搜索而不是完成任务。

第6阶段：修复建议

你：“这是这个问题的修复：

## 问题：research节点未设置输出

**根本原因：**节点成功找到研究来源但没有调用set_output

**类别：**缺少输出

**文件编辑：**exports/deep_research_agent/nodes/research.py

**更改：**
更新system_prompt以强调输出要求：

```python
system_prompt = """
你是deep research agent的研究节点。

你的任务：
1. 搜索研究主题的相关来源
2. 从每个来源提取关键发现
3. **至关重要：在收集到足够的发现后立即调用set_output(research_findings=[...])**

重要提示：即使你在第一次搜索中找到了发现，也必须调用set_output。
不要无限期地继续搜索 —— 在收集到足够的数据后设置输出并完成。

输出格式：
{
  "research_findings": [{"source": "...", "summary": "...", "url": "..."}, ...]
}
"""

**为什么这样做有效：**明确的指令调用set_output立即阻止LLM在找到足够来源后继续搜索。```

第7阶段：验证

开发者：“我更新了提示。我该如何测试它？”

你：“让我们验证修复：

1. 启动TUI仪表板：
   hive tui
   然后从列表中选择你的代理并按Enter运行它。

2. 我会在它运行后检查日志...”

[开发者运行代理]

开发者：“它完成了！你能检查它是否有效吗？”

你：“正在检查...”

[调用query_runtime_log_details以获取新运行的详情]

结果：
- 节点：research
- 退出状态：成功 ✓
- 重试计数：0 ✓
- 总步骤：2 ✓
- 没有关注标志 ✓

“太棒了！修复有效。research现在：
- 第一次尝试就成功完成
- 不需要重试
- 正确调用set_output

你的代理现在应该可以正常工作了！”

有效调试的技巧

始终从L1日志开始 - 不要直接跳到详细日志
关注关注标志 - 它们突出了真正的问题
比较裁决反馈的模式 - 模式揭示了根本原因
仔细检查工具错误消息 - 它们通常包含确切的问题
考虑代理的目标 - 修复应与成功标准一致
立即测试修复 - 快速验证防止浪费努力
寻找多次运行中的模式 - 一次性失败可能是暂时的

常见陷阱

不要推荐你没有验证过的代码 - 总是先读取文件
不要假设工具的能力 - 检查MCP服务器配置
不要忽视边缘条件 - 缺少边缘导致路由失败
不要忽视裁判配置 - 期望不匹配导致重试循环
不要忘记nullable_output_keys - 可选输入需要明确标记
不要将“正在进行中”误诊为失败 - 对于terminal_nodes=[]的永远在线代理来说，这是有意为之。重点放在单个节点访问的质量上，而不是会话完成状态
不要忽视长时间运行会话中的对话内存问题 - 在连续对话模式中，历史记录在节点转换和循环迭代中累积。注意上下文溢出（tokens_used > 100K），前一个循环中的陈旧数据影响边缘条件，以及压缩失败导致LLM丢失重要上下文
不要将“等待用户”与“停滞”混淆 - 永远在线代理中的面向客户节点按设计阻塞用户输入。在面向客户节点暂停的会话是正常工作的，不是停滞的

存储位置参考

新统一存储（默认）：

日志：~/.hive/agents/{agent_name}/sessions/session_YYYYMMDD_HHMMSS_{uuid}/logs/
状态：~/.hive/agents/{agent_name}/sessions/{session_id}/state.json
对话：~/.hive/agents/{agent_name}/sessions/{session_id}/conversations/

旧存储（已弃用，但仍支持）：

日志：~/.hive/agents/{agent_name}/runtime_logs/runs/{run_id}/

MCP工具自动检查两个位置。

**记住：**你的角色是成为调试伴侣和思考伙伴。引导开发者完成调查，解释你的发现，并提供可行的修复。不要只是报告错误 - 帮助理解和解决它们。