# Reasoning Trace Optimizer

<p align="center">
  <strong>通过 MiniMax M2.1 的交错式思考能力，分析和调试 AI 智能体的推理过程并进行优化</strong>
</p>

<p align="center">
  <a href="#key-features">功能特性</a> |
  <a href="#quick-start">快速开始</a> |
  <a href="#how-it-works">工作原理</a> |
  <a href="#examples">示例</a> |
  <a href="#api-reference">API 参考</a>
</p>

---

## 问题

传统 AI 智能体以不透明的方式失败。你只能看到最终输出，却看不到决策背后的**原因**。当智能体：
- 调用了错误的工具
- 偏离了目标
- 编造信息

……你只能猜测问题出在哪里。

## 解决方案

**Reasoning Trace Optimizer** 利用 MiniMax M2.1 独特的**交错式思考**能力，在每次工具调用之间暴露智能体的推理过程。这使得以下功能成为可能：

1. **深度调试** —— 准确找出推理偏离预期行为的位置
2. **模式检测** —— 自动识别失败模式（上下文退化、工具混淆等）
3. **自动优化** —— 根据检测到的问题生成改进后的提示词
4. **可分享的技能** —— 将学习成果转换为可复用的 Agent Skill，供团队共享

## 为什么选择 MiniMax M2.1？

M2.1 的**交错式思考**与传统推理模型有本质区别：

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

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` | 模型不验证结果 | 高 |

每个检测到的模式包括：
- **证据** —— 思考块中的具体摘录
- **严重程度** —— 严重/高/中/低
- **建议** —— 对提示词的具体改进方案
- **置信度** —— 检测结果的可靠程度

---

## 快速开始

### 安装

```bash
cd examples/interleaved-thinking
pip install -e .
```

### 配置

设置你的 MiniMax API 密钥：

```bash
export ANTHROPIC_API_KEY=your_minimax_api_key
export ANTHROPIC_BASE_URL=https://api.minimax.io/anthropic
```

或者创建一个 `.env` 文件：

```env
ANTHROPIC_API_KEY=your_minimax_api_key
ANTHROPIC_BASE_URL=https://api.minimax.io/anthropic
```

### 基本用法

```python
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}")
```

---

## 工作原理

### 优化循环

```
┌─────────────────────────────────────────────────────────────────────────┐
│                       优化循环                                           │
│                                                                         │
│   ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐          │
│   │ 智能体   │───▶│ 捕获    │───▶│ 分析    │───▶│ 优化    │          │
│   │ 执行     │    │ 轨迹    │    │ 模式    │    │ 提示词  │          │
│   └──────────┘    └──────────┘    └──────────┘    └──────────┘          │
│        ▲                                               │                │
│        └───────────────────────────────────────────────┘                │
│                       （循环直至收敛或达到最大迭代次数）                    │
│                                                                         │
│   收敛条件：评分改善 < 阈值 或 评分 > 目标值                               │
└─────────────────────────────────────────────────────────────────────────┘
```

### 捕获的内容

每次智能体执行时，我们捕获：

1. **思考块** —— M2.1 在每次动作之前的推理过程
2. **工具调用** —— 调用了哪些工具以及相应的输入
3. **工具结果** —— 每个工具返回的结果
4. **最终响应** —— 智能体的输出
5. **元数据** —— 使用的 Token 数、交互次数、成功/失败状态

### 分析的内容

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

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

---

## 示例

### 示例 1：基本轨迹捕获

```python
# examples/01_basic_capture.py
from reasoning_trace_optimizer import TraceCapture

capture = TraceCapture()
trace = capture.run(
    task="解释什么是交错式思考，以及它为什么对 AI 智能体很重要。",
    system_prompt="你是一名 AI 研究员，需清晰地解释概念。"
)

# 输出：
# 捕获到 1 个思考块
# 第 0 轮："用户要求我解释'交错式思考'..."
```

### 示例 2：带分析的工具使用

```python
# 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 个工具（网页搜索、文件操作、笔记记录）的复杂研究任务：

```python
# 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
```

**演示的关键特性：**

1. **提示词增长限制** —— 将提示词扩展限制为原始大小的 3 倍，防止膨胀
2. **最佳评分追踪** —— 自动使用表现最佳的提示词，即使后续迭代出现退化
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
```

**生成的技能内容示例：**

```markdown
## 需避免的模式

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

## 推荐实践

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

---

## API 参考

### TraceCapture

```python
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

```python
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

```python
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

```python
generator = SkillGenerator()
skill_path = generator.generate(
    result=loop_result,           # 来自 OptimizationLoop
    skill_name="my-skill",        # 小写加连字符
    output_dir="./generated_skills",
    title="人类可读的标题"
)
```

---

## CLI 使用

```bash
# 捕获推理轨迹
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 库

```python
from reasoning_trace_optimizer import (
    TraceCapture,
    TraceAnalyzer,
    PromptOptimizer,
    OptimizationLoop,
    LoopConfig,
    SkillGenerator,
)
```

---

## 贡献

本项目是 [Agent Skills for Context Engineering](https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering) 系列的一部分。

---

## 许可证

MIT License

---

## 参考资料

- [MiniMax M2.1 文档](https://www.minimax.io/platform/docs)
- [MiniMax API 参考](https://www.minimax.io/platform/docs/M2.1)
- [交错式思考指南](./docs/interleavedthinking.md)
- [智能体泛化研究](./docs/agentthinking.md)
- [Anthropic API 兼容性](./docs/m2-1.md)

---

<p align="center">
  <strong>与 MiniMax AI 合作构建</strong><br>
  展示交错式思考在智能体调试中的强大能力
</p>