reasoning-trace-optimizer

推理轨迹优化器

通过分析推理轨迹，调试并优化 AI Agent。此技能利用 MiniMax M2.1 的交错思考，深入洞察 Agent 的决策过程，并生成切实可行的改进方案。

激活时机

• 需要调试或分析 Agent 推理轨迹，或优化提示词时
• Agent 任务失败，用户想了解原因时
• 用户提到“上下文退化”“工具混淆”或“指令偏移”时
• 用户请求提升 Agent 性能或减少错误时
• 用户想从调试过程中提炼可分享的经验时
• 类似任务反复失败后

核心概念

交错思考

与只在开始时思考一次的标准推理模型不同，交错思考允许在每次工具交互之间进行推理。这一点至关重要，因为：

1. 长周期任务需要在多轮对话中保持专注
2. 外部扰动（工具输出、环境变化）需要实时适应
3. 调试需要了解决策是如何作出的，而不只是了解输出了什么

优化循环

Execute Agent → Capture Traces → Analyze Patterns → Optimize Prompt → Re-run
                                                          ↑____________|

每次迭代都会根据检测到的模式改进提示词，直至收敛。

模式检测

分析器会检测以下常见失败模式：

模式	描述
context_degradation	模型在较长上下文中逐渐遗失信息
tool_confusion	模型误解工具的能力或输出
instruction_drift	模型逐渐偏离原始指令
goal_abandonment	模型不再追求原始目标
circular_reasoning	模型重复执行相似操作，却没有进展
premature_conclusion	模型在完成任务前就得出结论

使用模式

模式 1：M2.1 Agent 调试

通过 M2.1 执行任务并分析其推理过程：

from reasoning_trace_optimizer import TraceCapture, TraceAnalyzer

capture = TraceCapture()
trace = capture.run(
    task="Search for Python tutorials and summarize them",
    system_prompt="You are a research assistant.",
    tools=[search_tool],
    tool_executor=execute_search
)

analyzer = TraceAnalyzer()
analysis = analyzer.analyze(trace)

print(f"Score: {analysis.overall_score}/100")
for pattern in analysis.patterns:
    print(f"Found: {pattern.type.value} - {pattern.suggestion}")

模式 2：完整优化循环

自动迭代，直至提示词得到优化：

from reasoning_trace_optimizer import OptimizationLoop, LoopConfig

config = LoopConfig(
    max_iterations=5,
    min_score_threshold=80.0,
)

loop = OptimizationLoop(config=config)
result = loop.run(
    task="Analyze this codebase and suggest improvements",
    initial_prompt="You are a code reviewer.",
    tools=[read_file_tool, search_tool],
    tool_executor=execute_tool
)

print(f"Improved: {result.initial_score} → {result.final_score}")
print(f"Final prompt:\n{result.final_prompt}")

模式 3：通用会话分析

分析任意 Agent 之前的思考过程（适用于 Claude、GPT 等）：

在 Claude Code 中激活此技能后，它可以分析当前会话的思考区块，识别问题并提出改进建议。

/reasoning-trace-optimizer analyze-session

模式 4：生成可分享的技能

将优化经验转化为可重复使用的 Agent Skills：

from reasoning_trace_optimizer import SkillGenerator

generator = SkillGenerator()
skill_path = generator.generate(
    result=loop_result,
    skill_name="web-search-best-practices",
    output_dir="./skills"
)

CLI 命令

# Capture reasoning trace
rto capture "Search for Python tutorials" -s "You are a helpful assistant."

# Analyze a task
rto analyze "Debug this code" -o analysis.txt

# Run optimization loop
rto optimize "Research AI papers" --max-iterations 5 --generate-skill

# Generate skill from artifacts
rto generate-skill my-skill-name --artifacts-dir ./optimization_artifacts

与 Claude Code 集成

失败时自动触发

将以下内容添加到钩子中，以便自动分析失败：

{
  "hooks": {
    "post_tool_error": {
      "command": "rto analyze-session --last-error"
    }
  }
}

按需分析

使用斜杠命令分析当前会话：

/reasoning-trace-optimizer

这将：

1. 从当前会话中提取思考区块
2. 识别模式和问题
3. 提出提示词改进建议
4. 可选择更新系统提示词

指南

1. 保留完整上下文：为获得最佳性能，M2.1 需要包含思考区块在内的完整响应历史
2. 使用合适的工具：清晰定义工具，确保描述明确无歧义
3. 设定切实可行的收敛阈值：每次迭代提升 5-10% 通常较为合适
4. 审查生成的技能：分享自动生成的技能前应先进行审查
5. 监控 Token 使用量：每次优化迭代都会消耗大量 Token

示例

优化前

System: You are a helpful assistant.

Issue: Agent called wrong tools, lost track of goal after 3 turns
Score: 45/100
Patterns: tool_confusion, goal_abandonment

优化后

System: You are a research assistant focused on finding accurate information.

IMPORTANT GUIDELINES:
- Always verify search results before summarizing
- If a tool returns an error, try an alternative approach
- Keep track of your original goal throughout the task
- Validate findings against multiple sources when possible

Issue: None
Score: 85/100
Patterns: None detected

参考资料

• MiniMax M2.1 文档：https://platform.minimax.io/docs
• 交错思考指南：参见 docs/interleavedthinking.md
• Agent 泛化：参见 docs/agentthinking.md

---

技能元数据

创建日期：2025-01-11 作者：Muratcan Koylan 版本：0.1.0 技术支持：MiniMax M2.1 合作信息：与 MiniMax AI 合作构建