排错指南

适用版本：4.0.8+

1) 报错：Session 方法不存在

原因：代码仍使用旧版快捷接口。

处理：迁移为新版接口。

• 开启会话：activate_session(session_id=...)
• 关闭会话：deactivate_session()
• 窗口控制：session.max_length + resize

2) 会话看起来“没记住”

排查顺序：

1. 是否已 activate_session(...)
2. 是否中途 deactivate_session()
3. 是否切换到了另一个 session_id
4. context_window 是否被策略裁剪过度

快速检查：

print(agent.activated_session.id)
print(len(agent.activated_session.full_context))
print(len(agent.activated_session.context_window))

3) session.input_keys / reply_keys 配了但记录为空

常见原因：

• 路径写错（字段不存在）
• 路径风格不一致（a.b vs a/b）
• 期望字段不在 result_data 顶层

建议：先用 None 记录全量，确认结构后再收敛键路径。

4) memo 一直不更新

原因：新版不会自动生成 memo，必须在执行策略里返回 new_memo。

检查：

• analysis_handler 是否返回了策略名
• 对应 execution_handler 是否返回第三项 new_memo

5) 导入 session 失败（JSON/YAML）

可能原因：

• 内容不是字典结构
• session_key_path 指向的不是 session 对象
• 文件编码与 encoding 不匹配

建议：

• 先直接 load_json_session(json_text) 验证
• 再切换到文件路径与 key path

6) 窗口过大导致成本上升

处理方式：

agent.set_settings("session.max_length", 12000)

必要时配合自定义策略，把 context_window 控制在最近 N 轮。