wehub-skill-sync
620 lines
19 KiB
Markdown
620 lines
19 KiB
Markdown
# 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>
|