传统模型：  思考 → 行动 → 行动 → 行动 → 完成
              ↑
              （仅在开始时推理）

M2.1：      思考 → 行动 → 思考 → 行动 → 思考 → 行动 → 完成
              ↑            ↑              ↑
              （在每次工具调用之间持续推理）

这对智能体至关重要，因为：

长任务需要在多次交互中保持专注
工具输出会引入意料之外的信息，需要自适应调整
调试需要洞察决策过程，而不仅仅是输出结果

thinking 块（Anthropic SDK）或 reasoning_details 字段（OpenAI SDK）将推理过程暴露出来供分析。

关键特性

组件	描述
TraceCapture	包装 M2.1 API，捕获所有思考块及其完整上下文
TraceAnalyzer	检测上下文退化、工具混淆、指令漂移等模式
PromptOptimizer	基于分析结果，利用 M2.1 生成改进后的提示词
OptimizationLoop	自动化的捕获 → 分析 → 改进 → 重新运行的循环
SkillGenerator	将学习成果转换为可分享的 Agent Skill

模式检测

分析器会自动识别以下失败模式：

模式	描述	严重程度
`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 在每次动作之前的推理过程
工具调用 —— 调用了哪些工具以及相应的输入
工具结果 —— 每个工具返回的结果
最终响应 —— 智能体的输出
元数据 —— 使用的 Token 数、交互次数、成功/失败状态

分析的内容

分析器检查思考块以了解：

当前理解 —— 智能体对任务的理解是什么？
工具解读 —— 它如何解读每个工具的结果？
备选方案 —— 它评估了哪些选项？
目标意识 —— 它是否仍在追求原始目标？

示例

示例 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 将优化学习成果转换为可分享的 Agent Skill：

generated_skills/
└── comprehensive-research-agent/
    ├── SKILL.md              # 可分享的技能
    └── references/
        ├── optimization_summary.json
        ├── optimized_prompt.txt
        └── patterns_found.json

生成的技能内容示例：

## 需避免的模式

- **缺少验证**：对工具响应照单全收，未验证实际状态变更是否发生。
- **编造来源**：引用加载失败的来源。
- **忽略矛盾**：在工具结果相互冲突时仍继续执行。

## 推荐实践

- 每次工具调用后，明确陈述结果
- 分别追踪来源：'已尝试' 与 '已成功'
- 使用替代方法实现错误恢复
- 对关键声明进行多来源交叉验证

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                # 每次响应的最大 Token 数
)

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`（Lost in the Middle）

健壮性特性

优化器包含多项安全保障以应对现实中的不确定性：

解析弹性

LLM 响应并不总是产生有效的 JSON。系统能优雅处理此问题：

组件	降级行为
Analyzer	JSON 失败时通过正则表达式提取评分；默认为 50/100（而非 0）
Optimizer	多策略提示词提取：JSON → 正则 → 标记检测 → 代码块
Loop	最终提示词未变化时发出警告；追踪表现最佳的迭代

扩展测试结果（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 Skill

本项目包含一个 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 License

参考资料

与 MiniMax AI 合作构建
展示交错式思考在智能体调试中的强大能力

README.md Unescape Escape

Reasoning Trace Optimizer

问题

解决方案

为什么选择 MiniMax M2.1？