mirrors / skillhub-005-reasoning-trace-optimizer

项目文件夹

skillhub-005-reasoning-trace-optimizer
文件
main
T
wehub-skill-sync 8e3cfdf19f chore: import zh skill reasoning-trace-optimizer
2026-07-13 21:35:32 +08:00

620 行
19 KiB
Markdown
原始文件 永久链接 Blame 文件历史

此文件含有模棱两可的 Unicode 字符
此文件含有可能会与其他字符混淆的 Unicode 字符。 如果您是想特意这样的，可以安全地忽略该警告。 使用 Escape 按钮显示他们。
# 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>
在新工单中引用 查看 Git Blame 复制永久链接