> ## Documentation Index
> Fetch the complete documentation index at: https://qitor.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 方法模板

> 使用内置方法模板（Self-Refine、Reflexion、LATS、MoA、Magentic-One）以最少的样板代码实现经过验证的智能体模式。

QitOS 提供**方法模板**——即现成的 Agent + Critic 组合，实现了知名的智能体推理模式。每个模板封装了专用的状态、评论器和智能体，让你无需重写控制循环即可应用该模式。

## 什么是方法模板？

方法模板由以下部分组成：

| 组件         | 角色                                                                        |
| ---------- | ------------------------------------------------------------------------- |
| **State**  | `StateSchema` 子类，包含模式专用字段（反思记录、草稿、精炼次数等）                                  |
| **Critic** | `Critic` 子类，通过在适当时机返回 `retry`、`continue` 或 `stop` 来驱动模式循环                 |
| **Agent**  | `AgentModule` 子类，具有模式感知的 `build_system_prompt()`、`prepare()` 和 `reduce()` |

评论器是核心：它评估每个步骤，决定是否重试（附带指令补丁）、继续或停止。智能体通过模式上下文（先前的反思、草稿版本、批评意见）丰富提示词。

## Self-Refine

**Self-Refine** 模式（Madaan et al. 2023）迭代过程：**生成 → 批评 → 精炼**，直到质量达到阈值或达到最大精炼次数。

### 适用场景

* 质量比速度更重要的文本生成任务
* 摘要、翻译、带自评估的代码生成
* 任何迭代改进能可靠产生更好输出的任务

### 快速开始

```python theme={null}
from qitos.recipes.self_refine import SelfRefineAgent, SelfRefineCritic

agent = SelfRefineAgent(llm=my_llm)
result = agent.run(
    task="撰写关于...研究论文的简洁摘要",
    critics=[SelfRefineCritic(max_refinements=3, quality_threshold=0.7)],
    max_steps=10,
    return_state=True,
)
print(result.state.draft)        # 精炼后的输出
print(result.state.final_result) # 如果提取到 FINAL ANSWER
```

### 工作原理

1. **生成**：智能体生成初始草稿。
2. **批评**：`SelfRefineCritic` 使用启发式评分评估草稿质量（经过更多精炼的较长草稿得分更高；非常短的草稿会被惩罚）。在生产环境中，请替换为基于 LLM 的评分器。
3. **精炼**：如果分数低于 `quality_threshold` 且仍有精炼次数，评论器返回 `retry` 并附带 `instruction_patch` 要求智能体改进。智能体在下一次提示中可以看到之前的草稿和批评。
4. **接受**：当分数达到阈值或达到 `max_refinements` 时，评论器返回 `continue` 或 `stop`。

### SelfRefineCritic 参数

| 参数                  | 默认值 | 描述                 |
| ------------------- | --- | ------------------ |
| `max_refinements`   | 3   | 最大精炼迭代次数           |
| `quality_threshold` | 0.7 | 接受草稿的最低分数（0.0–1.0） |

### SelfRefineState 字段

| 字段                 | 类型          | 描述         |
| ------------------ | ----------- | ---------- |
| `draft`            | `str`       | 当前草稿文本     |
| `refinement_count` | `int`       | 目前已进行的精炼次数 |
| `max_refinements`  | `int`       | 精炼预算       |
| `critique_history` | `List[str]` | 累积的批评记录    |

## Reflexion

**Reflexion** 模式（Shinn et al. 2023）迭代过程：**行动 → 评估 → 反思 → 带记忆重试**。在失败时，评论器生成语言反思存储在状态中，并注入到未来的提示词中。

### 适用场景

* 调试和纠错任务，智能体需要从失败中学习
* 失败后应尝试不同策略的任务
* 多次尝试的问题（编码、推理），反思能改进后续尝试

### 快速开始

```python theme={null}
from qitos.recipes.reflexion import ReflexionAgent, ReflexionCritic

agent = ReflexionAgent(llm=my_llm)
result = agent.run(
    task="调试 tests/test_module.py 中失败的测试",
    critics=[ReflexionCritic(max_reflections=3)],
    max_steps=15,
    return_state=True,
)
print(result.state.reflections)    # 语言反思列表
print(result.state.final_result)  # 如果提取到 FINAL ANSWER
```

### 工作原理

1. **行动**：智能体采取行动完成任务。
2. **评估**：`ReflexionCritic` 检查是否失败（错误、非零返回码、空结果）。
3. **反思**：在失败时，评论器从错误上下文生成语言反思，并以 `instruction_patch` 形式返回 `retry`。反思存储在 `state.reflections` 中。
4. **带记忆重试**：智能体的 `build_system_prompt()` 包含所有先前的反思，因此 LLM 可以避免重复相同的错误。

### ReflexionCritic 参数

| 参数                  | 默认值 | 描述             |
| ------------------- | --- | -------------- |
| `max_reflections`   | 3   | 强制停止前的最大反思迭代次数 |
| `success_threshold` | 0.6 | 认为轨迹成功的最低分数    |

### ReflexionState 字段

| 字段                    | 类型          | 描述       |
| --------------------- | ----------- | -------- |
| `reflections`         | `List[str]` | 累积的语言反思  |
| `reflection_count`    | `int`       | 已生成的反思数量 |
| `max_reflections`     | `int`       | 反思预算     |
| `last_action_success` | `bool`      | 上一步是否成功  |
| `attempt`             | `int`       | 当前尝试编号   |

## LATS

**LATS** 模式（Zhou et al. 2023）将蒙特卡洛树搜索应用于语言智能体：**选择 → 扩展 → 评估 → 回溯**。失败的轨迹生成反思，引导未来探索避开类似错误。

### 适用场景

* 需要系统探索多条解路的任务
* 逻辑谜题、编程挑战和多步推理
* 尝试不同策略能提高成功率的问题

### 快速开始

```python theme={null}
from qitos.recipes.lats import LATSAgent, LATSCritic

agent = LATSAgent(llm=my_llm)
result = agent.run(
    task="解决逻辑谜题 ...",
    critics=[LATSCritic(max_simulations=5, exploration_weight=1.41)],
    max_steps=20,
    return_state=True,
)
print(result.state.best_answer)    # 找到的最佳答案
print(result.state.best_reward)    # 最佳奖励分数
```

### LATSCritic 参数

| 参数                   | 默认值  | 描述            |
| -------------------- | ---- | ------------- |
| `max_simulations`    | 5    | 最大模拟迭代次数      |
| `exploration_weight` | 1.41 | UCB1 探索常数 (c) |
| `success_threshold`  | 0.8  | 提前停止的奖励阈值     |

### LATSState 字段

| 字段                 | 类型          | 描述       |
| ------------------ | ----------- | -------- |
| `simulations_done` | `int`       | 已完成的模拟次数 |
| `max_simulations`  | `int`       | 模拟预算     |
| `best_reward`      | `float`     | 目前最佳奖励   |
| `best_answer`      | `str`       | 最佳轨迹的答案  |
| `reflections`      | `List[str]` | 失败路径的反思  |

## MoA（混合智能体）

**MoA** 模式（Wang et al. 2024）独立运行多个提议者并综合其输出：**提议 → 聚合**。提议的多样性提高质量，即使单个提议者较弱。

### 适用场景

* 受益于多元视角或创造性回应的任务
* 分析、评估和综合问题
* 通过集成推理提升质量

### 快速开始

```python theme={null}
from qitos.recipes.moa import MoAOrchestrator, MoACritic

agent = MoAOrchestrator(llm=my_llm)
result = agent.run(
    task="评估...的系统架构设计",
    critics=[MoACritic(proposer_count=3, max_rounds=1)],
    max_steps=15,
    return_state=True,
)
print(result.state.synthesis)  # 聚合后的答案
```

### MoACritic 参数

| 参数                  | 默认值 | 描述          |
| ------------------- | --- | ----------- |
| `proposer_count`    | 3   | 预期的提议数量     |
| `max_rounds`        | 1   | 最大提议-聚合轮数   |
| `quality_threshold` | 0.6 | 接受综合结果的最低分数 |

## Magentic-One

**Magentic-One** 模式（Furtado et al. 2024）使用编排器的双账本架构：**规划 → 委派 → 跟踪进度 → 停滞时重新规划**。编排器维护事实库和任务账本，委派给专家智能体，在停滞时重新规划。

### 适用场景

* 需要协调不同能力的复杂多步任务
* 编排器需要根据中间结果调整计划的场景
* 涉及研究、编码和分析子任务的开放性问题

### 快速开始

```python theme={null}
from qitos.recipes.magentic_one import (
    MagenticOneOrchestrator,
    ProgressCritic,
    MagenticOneState,
)

agent = MagenticOneOrchestrator(llm=my_llm)
result = agent.run(
    task="研究并总结...的最新发现",
    critics=[ProgressCritic(max_stalls=3)],
    max_steps=30,
    return_state=True,
)
print(result.state.fact_bank)        # 累积的事实
print(result.state.completed_tasks)  # 已完成的子任务
```

### ProgressCritic 参数

| 参数                   | 默认值 | 描述         |
| -------------------- | --- | ---------- |
| `max_stalls`         | 3   | 最大连续无进展步数  |
| `progress_threshold` | 0.5 | 认为有进展的最低分数 |

### MagenticOneState 字段

| 字段                 | 类型          | 描述       |
| ------------------ | ----------- | -------- |
| `fact_bank`        | `List[str]` | 累积的事实和推测 |
| `task_ledger`      | `List[str]` | 当前的子任务计划 |
| `completed_tasks`  | `List[str]` | 已完成的子任务  |
| `stall_count`      | `int`       | 连续无进展步数  |
| `specialist_calls` | `int`       | 专家委派次数   |

## 脚手架工具

使用 `qit new` CLI 命令从内置 cookiecutter 模板脚手架生成新智能体项目：

```bash theme={null}
# 使用默认设置创建新智能体
pip install qitos[cookiecutter]
qit new --agent-name my_agent --agent-description "我的自定义智能体"

# 列出可用模板
qit list-templates

# 完全自定义创建
qit new \
  --agent-name code_reviewer \
  --agent-description "审查代码中的安全问题" \
  --author "我的团队" \
  --default-model qwen-plus \
  --max-steps 20
```

脚手架生成的项目包括：

* `src/agent.py` — 包含 State、init\_state、build\_system\_prompt、reduce 的 Agent 类
* `configs/default.yaml` — 默认模型和步骤配置
* `tests/test_agent.py` — 基本冒烟测试
* `snowl_compat.py` — Snowl 评估兼容适配器
* `eval_config.yaml` — 评估配置

## 构建自定义方法模板

要创建自定义方法模板，请遵循相同的 Agent + Critic 模式：

1. **定义状态**，扩展 `StateSchema` 并添加模式的跟踪字段
2. **实现评论器**，当模式需要迭代时返回带有 `instruction_patch` 和 `state_patch` 的 `retry`
3. **实现智能体**，其 `build_system_prompt()` 从状态中注入模式上下文

```python theme={null}
from dataclasses import dataclass, field
from typing import Any, Dict, List
from qitos import AgentModule, Decision, StateSchema
from qitos.engine.critic import Critic
from qitos.engine.critic_result import CriticResult
from qitos.kit.parser import ReActTextParser

@dataclass
class MyMethodState(StateSchema):
    iteration: int = 0
    max_iterations: int = 5
    history: List[str] = field(default_factory=list)

class MyMethodCritic(Critic):
    def evaluate(self, state, decision, results):
        if not isinstance(state, MyMethodState):
            return CriticResult(action="continue")
        if state.iteration < state.max_iterations:
            return CriticResult(
                action="retry",
                score=0.5,
                instruction_patch="尝试不同的方法。",
                state_patch={"iteration": state.iteration + 1},
            )
        return CriticResult(action="stop", reason="已达最大迭代次数。")

class MyMethodAgent(AgentModule[MyMethodState, Dict[str, Any], Any]):
    def __init__(self, llm=None, **kwargs):
        super().__init__(llm=llm, model_parser=ReActTextParser(), **kwargs)

    def init_state(self, task, **kwargs):
        return MyMethodState(task=task, max_steps=kwargs.get("max_steps", 10))

    def build_system_prompt(self, state):
        prompt = "你是一个方法智能体。迭代直到完成。"
        if state.history:
            prompt += "\n\n之前的尝试：\n" + "\n".join(state.history)
        return prompt

    def prepare(self, state, observation):
        return f"任务：{state.task}\n迭代：{state.iteration}"

    def reduce(self, state, observation, decision, action_results):
        return state
```