项目文件夹
您已经派生过 skillhub-005-reasoning-trace-optimizer
skillhub-005-reasoning-trace-optimizer
aweminds推理轨迹优化器
通过分析 MiniMax M2.1 交错式思维的推理轨迹，调试并优化 AI 智能体
功能特性 | 快速开始 | 工作原理 | 示例 | API 参考
问题
传统 AI 智能体以不透明的方式失败。你看到最终输出，但看不到为什么做出这些决策。当一个智能体：
- 调用了错误的工具
- 偏离了目标
- 编造信息
……你只能猜测哪里出了问题。
解决方案
推理轨迹优化器利用 MiniMax M2.1 独特的交错式思维能力，在每次工具调用之间暴露智能体的推理过程。这实现了：
- 深度调试 - 精确查看推理在何处偏离了预期行为
- 模式检测 - 自动识别失败模式（上下文退化、工具混淆等）
- 自动优化 - 基于检测到的问题生成改进后的提示词
- 可共享技能 - 将学习成果转化为可复用的智能体技能，供团队共享
为什么选择 MiniMax M2.1？
M2.1 的交错式思维与传统推理模型有本质区别：
传统模式： 思考 → 行动 → 行动 → 行动 → 完成
↑
(仅在开始时推理)
M2.1 模式： 思考 → 行动 → 思考 → 行动 → 思考 → 行动 → 完成
↑ ↑ ↑
(每次工具调用之间持续推理)
这对智能体至关重要，因为：
- 长任务需要在多个轮次中保持专注
- 工具输出会引入需要适应的意外信息
- 调试需要了解决策过程，而不仅仅是输出
thinking 块（Anthropic SDK）或 reasoning_details 字段（OpenAI SDK）暴露了这些推理过程以供分析。
关键特性
| 组件 | 描述 |
|---|---|
| TraceCapture | 封装 M2.1 API，捕获所有包含完整上下文的思维块 |
| TraceAnalyzer | 检测上下文退化、工具混淆、指令漂移等模式 |
| PromptOptimizer | 基于分析结果，使用 M2.1 生成改进后的提示词 |
| OptimizationLoop | 自动化的捕获 → 分析 → 改进 → 重新运行循环 |
| SkillGenerator | 将学习成果转化为可共享的智能体技能 |
模式检测
分析器自动识别以下失败模式：
| 模式 | 描述 | 严重程度 |
|---|---|---|
context_degradation |
模型在长上下文中丢失信息 | 高 |
tool_confusion |
模型误解工具能力 | 高 |
instruction_drift |
模型偏离原始指令 | 中 |
hallucination |
模型生成无依据的信息 | 严重 |
goal_abandonment |
模型停止追求原始目标 | 高 |
circular_reasoning |
模型重复类似动作而无进展 | 中 |
premature_conclusion |
模型在完成任务前得出结论 | 中 |
missing_validation |
模型未验证结果 | 高 |
每个检测到的模式包括：
- 证据 - 来自思维块的具体摘录
- 严重程度 - 严重/高/中/低
- 建议 - 针对提示词的具体改进
- 置信度 - 检测的确定程度
快速开始
安装
cd examples/interleaved-thinking
pip install -e .
配置
设置你的 MiniMax API 密钥：
export ANTHROPIC_API_KEY=your_minimax_api_key
export ANTHROPIC_BASE_URL=https://api.minimax.io/anthropic
或者创建一个 .env 文件：
ANTHROPIC_API_KEY=your_minimax_api_key
ANTHROPIC_BASE_URL=https://api.minimax.io/anthropic
基本用法
from reasoning_trace_optimizer import TraceCapture, TraceAnalyzer
# 捕获推理轨迹
capture = TraceCapture()
trace = capture.run(
task="解释量子计算",
system_prompt="你是一名科学教育者。"
)
print(f"捕获到 {len(trace.thinking_blocks)} 个思维块")
# 分析推理过程
analyzer = TraceAnalyzer()
analysis = analyzer.analyze(trace)
print(f"总体评分：{analysis.overall_score}/100")
for pattern in analysis.patterns:
print(f" [{pattern.severity.value}] {pattern.type.value}")
print(f" 建议：{pattern.suggestion}")
工作原理
优化循环
┌─────────────────────────────────────────────────────────────────────────┐
│ 优化循环 │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ 智能体 │───▶│ 捕获 │───▶│ 分析 │───▶│ 优化 │ │
│ │ 执行 │ │ 轨迹 │ │ 模式 │ │ 提示词 │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ ▲ │ │
│ └───────────────────────────────────────────────┘ │
│ (循环直至收敛或达到最大迭代次数) │
│ │
│ 收敛条件：评分提升 < 阈值 或 评分 > 目标值 │
└─────────────────────────────────────────────────────────────────────────┘
捕获的内容
对于每次智能体执行，我们捕获：
- 思维块 - M2.1 在每个动作之前的推理
- 工具调用 - 调用了哪些工具以及输入了什么
- 工具结果 - 每个工具返回了什么
- 最终响应 - 智能体的输出
- 元数据 - 使用的令牌数、执行的轮次、成功/失败
分析的内容
分析器检查思维块以了解：
- 当前理解 - 智能体对任务的理解是什么？
- 工具解读 - 它如何解读每个工具的结果？
- 考虑的替代方案 - 它评估了哪些选项？
- 目标意识 - 它是否仍在追求原始目标？
示例
示例 1：基本轨迹捕获
# examples/01_basic_capture.py
from reasoning_trace_optimizer import TraceCapture
capture = TraceCapture()
trace = capture.run(
task="解释什么是交错式思维以及它为什么对 AI 智能体重要。",
system_prompt="你是一名 AI 研究员，正在清晰地解释概念。"
)
# 输出：
# 捕获到 1 个思维块
# 第 0 轮："用户要求我解释'交错式思维'..."
示例 2：带分析的工具使用
# examples/02_tool_usage.py
from reasoning_trace_optimizer import TraceCapture, TraceAnalyzer
# 定义工具
tools = [
{
"name": "get_weather",
"description": "获取某个城市的当前天气",
"input_schema": {...}
}
]
capture = TraceCapture()
trace = capture.run(
task="比较旧金山和纽约的天气",
tools=tools,
tool_executor=execute_tool
)
# 分析
analyzer = TraceAnalyzer()
analysis = analyzer.analyze(trace)
# 输出：
# 评分：85/100
# 思维块：3
# 工具调用：4 (get_weather x2, get_forecast x2)
# 模式：未检测到
示例 3：完整优化循环
此示例演示了一个包含 7 个工具（网络搜索、文件操作、笔记记录）的复杂研究任务：
# examples/03_full_optimization.py
from reasoning_trace_optimizer import OptimizationLoop, LoopConfig, SkillGenerator
config = LoopConfig(
max_iterations=3,
min_score_threshold=85.0,
convergence_threshold=5.0,
save_artifacts=True,
)
loop = OptimizationLoop(config=config)
result = loop.run(
task="""研究"AI 智能体的上下文工程"并创建一份摘要...""",
initial_prompt="你是一名研究助手。",
tools=TOOLS,
tool_executor=execute_tool,
)
# 生成可共享的技能
generator = SkillGenerator()
skill_path = generator.generate(result, skill_name="research-agent")
示例 3 的实际输出：
======================================================================
优化结果
======================================================================
总迭代次数：3
已收敛：是
迭代 1（评分：69/100）
├── 任务完成：是
├── 思维块：6
├── 工具调用：16
├── 发现的模式：2
│ ├── [低] missing_validation
│ └── [低] incomplete_reasoning
├── 优势：出色的目标遵循，全面的来源多样性
└── 警告：提示词增长过大（2979 字符），限制增长
迭代 2（评分：60/100） ← 检测到回退！
├── 任务完成：是
├── 思维块：8
├── 工具调用：16
├── 发现的模式：3
│ ├── [中] incomplete_reasoning
│ ├── [中] missing_validation
│ └── [低] tool_misuse
迭代 3（评分：66/100）
├── 任务完成：是
├── 思维块：8
├── 工具调用：16
└── 发现的模式：3
→ 使用来自迭代 1 的最佳提示词（评分：67.6）
所有迭代中的工具使用情况：
├── read_url：20 次调用
├── web_search：12 次调用
├── list_directory：7 次调用
├── save_note：6 次调用
└── write_file：3 次调用
保存的笔记：6 条带有标记发现的研究笔记
写入的文件：./output/research_summary.md（11,357 字符）
生成的技能：./generated_skills/comprehensive-research-agent/SKILL.md
展示的关键特性：
- 提示词增长限制 - 通过将扩展限制为原始大小的 3 倍来防止提示词膨胀
- 最佳评分跟踪 - 自动使用表现最佳的提示词，即使后续迭代出现回退
- 回退检测 - 在评分下降时发出警告，并可在连续回退后停止
生成的产物
优化产物
每次优化运行都会创建可供检查的产物：
optimization_artifacts/
├── summary.json # 总体结果
├── final_prompt.txt # 优化后的提示词
├── iteration_1/
│ ├── trace.json # 完整推理轨迹
│ ├── analysis.json # 模式检测结果
│ └── optimization.json # 所做的提示词更改
├── iteration_2/
│ └── ...
└── iteration_3/
└── ...
生成的技能
SkillGenerator 将优化学习成果转化为可共享的智能体技能：
generated_skills/
└── comprehensive-research-agent/
├── SKILL.md # 可共享的技能
└── references/
├── optimization_summary.json
├── optimized_prompt.txt
└── patterns_found.json
生成的技能内容示例：
## 应避免的模式
- **缺少验证**：不加验证地接受工具响应，未检查实际状态变化是否发生。
- **编造来源**：引用加载失败的来源。
- **忽略矛盾**：在工具结果冲突时继续执行。
## 推荐实践
- 每次工具调用后，明确陈述结果
- 单独跟踪来源：'已尝试' vs '已成功'
- 使用替代方法实现错误恢复
- 将关键声明与多个来源交叉引用
API 参考
TraceCapture
capture = TraceCapture(
api_key="...", # MiniMax API 密钥
base_url="https://api.minimax.io/anthropic", # API 端点
model="MiniMax-M2.1" # 使用的模型
)
trace = capture.run(
task="...", # 要执行的任务
system_prompt="...", # 系统提示词
tools=[...], # 工具定义（Anthropic 格式）
tool_executor=fn, # 执行工具的函数
max_turns=10, # 最大对话轮次
max_tokens=4096 # 每次响应的最大令牌数
)
TraceAnalyzer
analyzer = TraceAnalyzer(
api_key="...",
base_url="https://api.minimax.io/anthropic",
model="MiniMax-M2.1"
)
analysis = analyzer.analyze(trace)
# 返回：包含模式、评分、建议的 AnalysisResult
quick_score = analyzer.quick_score(trace)
# 返回：用于快速反馈的浮点数（0-100）
OptimizationLoop
config = LoopConfig(
# 迭代控制
max_iterations=5, # 最大优化迭代次数
convergence_threshold=3.0, # 如果改进 < 此百分比则停止
min_score_threshold=75.0, # 如果评分超过此值则停止
regression_threshold=8.0, # 如果评分下降这么多则发出警告
# 优化行为
use_best_prompt=True, # 使用表现最佳的提示词，而非最终提示词
max_prompt_growth=5.0, # 将提示词扩展限制为原始大小的 5 倍
# 输出选项
save_artifacts=True, # 保存轨迹和分析
artifacts_dir="./artifacts" # 保存位置
)
loop = OptimizationLoop(config=config)
result = loop.run(task, initial_prompt, tools, tool_executor)
# 返回：包含迭代、最终提示词、评分的 LoopResult
优化保障措施：
- 最佳提示词跟踪：保留产生最高评分的提示词
- 提示词增长限制：通过限制大小扩展来防止提示词膨胀
- 回退检测：在评分下降时发出警告，在连续回退后停止
评分预期：
| 任务复杂度 | 典型评分范围 | 备注 |
|---|---|---|
| 简单（1-2 个工具） | 80-95 | 直接的任务快速收敛 |
| 中等（3-5 个工具） | 70-85 | 多工具协调增加了变异性 |
| 复杂（6+ 个工具，多步骤） | 60-75 | 长推理链中的固有方差 |
包含许多工具和步骤的复杂研究任务通常会稳定在 65-75 左右，原因是：
- 工具输出变异性影响推理路径
- 多种有效方法导致不同的评分
- 多步骤智能体执行的随机性
优化器专注于相对改进和模式消除，而不是达到特定的绝对评分。
SkillGenerator
generator = SkillGenerator()
skill_path = generator.generate(
result=loop_result, # 来自 OptimizationLoop
skill_name="my-skill", # 小写字母加连字符
output_dir="./generated_skills",
title="人类可读标题"
)
CLI 用法
# 捕获推理轨迹
rto capture "解释交错式思维" -s "你是一名 AI 研究员。"
# 分析任务并输出结果
rto analyze "调试这段代码片段" -o analysis.txt
# 运行完整优化循环
rto optimize "研究 AI 论文" --max-iterations 5 --generate-skill
# 从之前的优化生成技能
rto generate-skill my-skill-name --artifacts-dir ./optimization_artifacts
使用的真实世界来源
示例 3 使用真实文档 URL 进行逼真模拟：
| 来源 | URL |
|---|---|
| Anthropic 文档 | docs.anthropic.com/en/docs/build-with-claude/* |
| Anthropic 研究 | anthropic.com/research/building-effective-agents |
| OpenAI 文档 | platform.openai.com/docs/guides/* |
| MiniMax M2.1 | minimax.io/platform/docs/M2.1 |
| DAIR.AI | promptingguide.ai/techniques |
| LangChain | python.langchain.com/docs/how_to/debugging |
| arXiv 论文 | arxiv.org/abs/2307.03172（迷失在中间） |
鲁棒性特性
优化器包含多项保障措施以处理真实世界的变异性：
解析弹性
LLM 响应并不总是产生有效的 JSON。系统优雅地处理此问题：
| 组件 | 回退行为 |
|---|---|
| 分析器 | 当 JSON 失败时，通过正则表达式模式提取评分；默认为 50/100（而非 0） |
| 优化器 | 多策略提示词提取：JSON → 正则表达式 → 标记检测 → 代码块 |
| 循环 | 当最终提示词未更改时发出警告；跟踪表现最佳的迭代 |
扩展测试结果（10 次迭代）
真实世界测试揭示了重要见解：
迭代 评分 模式 工具调用 备注
────────────────────────────────────────────────
1 69/100 4 22 基线
2 66/100 3 14 -
3 61/100 3 17 -
4 72/100 3 20 ← 最佳评分
5 59/100 4 16 -
6 50/100* 0 15 *解析器回退激活
7 70/100 3 12 恢复
8 64/100 3 14 -
9 64/100 3 18 -
10 70/100 3 19 最终
* 迭代 6：JSON 解析失败，回退返回中性评分
关键学习：
- 由于随机模型行为，评分在迭代之间波动 ±15 分
- 最佳评分（72）在运行中期达到，而非结束时
use_best_prompt=True正确选择了迭代 4 的提示词- 解析失败现在被优雅处理，而不是返回 0 分
架构
reasoning_trace_optimizer/
├── __init__.py # 公共 API 导出
├── models.py # 数据模型（Pydantic）
│ ├── ThinkingBlock # 单个推理片段
│ ├── ToolCall # 工具调用记录
│ ├── ReasoningTrace # 完整执行轨迹
│ ├── Pattern # 检测到的失败模式
│ ├── AnalysisResult # 完整分析输出
│ └── LoopResult # 优化循环结果
├── capture.py # TraceCapture - M2.1 API 封装器
├── analyzer.py # TraceAnalyzer - 模式检测（带回退解析）
├── optimizer.py # PromptOptimizer - 提示词改进（带回退提取）
├── loop.py # OptimizationLoop - 完整循环（带最佳评分跟踪）
├── skill_generator.py # SkillGenerator - 创建技能
└── cli.py # 命令行界面
集成
Claude Code 技能
此项目包含一个 Claude Code 技能（SKILL.md），支持：
- 失败时自动触发 - 在智能体任务失败时进行分析
- 按需分析 - 使用
/reasoning-trace-optimizer命令 - 会话分析 - 分析当前对话中的思维过程
Python 库
from reasoning_trace_optimizer import (
TraceCapture,
TraceAnalyzer,
PromptOptimizer,
OptimizationLoop,
LoopConfig,
SkillGenerator,
)
贡献
此项目是 Agent Skills for Context Engineering 集合的一部分。
许可证
MIT 许可证
参考
与 MiniMax AI 合作构建
展示交错式思维在智能体调试中的强大能力