# `CMDC.Plugin.Builtin.Reflection`
[🔗](https://github.com/tupleyun/cmdc/blob/v0.5.3/lib/cmdc/plugin/builtin/reflection.ex#L1)

P2 反思循环插件 —「生产者-评审者」模型。

在 Agent 即将完成前触发评审，未通过则注入修改指令让 Agent 继续工作，
直到通过或达到 `max_reviews`。

## 两种评审模式

### 模式 A — **同智能体自评**（默认）

在 Agent 自身对话里注入 review prompt，让同一个 LLM 评审自己的输出。
优点：轻量、零额外成本；缺点：同模型自审存在"认知偏差"风险。

### 模式 B — **独立 Reviewer SubAgent**（推荐）

设置 `reviewer_subagent: true` 时，会启动一个独立的 SubAgent 作为
Reviewer（可搭配 `reviewer_model` 使用不同模型），对主 Agent 的最后一条
回复做评审。此模式实现真正的"生产者-评审者"角色分离，避开同模型自审偏差。

## 配置

    {CMDC.Plugin.Builtin.Reflection,
      reviewer_prompt: "你是一位严格的质量评审员...",
      reviewer_model: "qwen3-max",            # 可选，模式 B 时指定评审模型
      reviewer_subagent: false,                # 默认 false；true 启用 SubAgent
      criteria: ["事实准确性", "完整性"],       # 评审维度
      max_reviews: 3,                          # 最大 review 轮数（防死循环）
      pass_signal: "APPROVED"                  # 通过信号；可为字符串或 Regex
    }

`max_iterations` 是 `max_reviews` 的历史别名，向后兼容，优先使用 `max_reviews`。

## 状态机

    :idle ──before_finish──> :reviewing ──after_response(pass)──> :done
                                 │
                                 ├─after_response(fail)──> :reviewing  (保持，等下次 before_finish)
                                 └─max_reviews 达到──────> :done（强制通过）

一旦 `:done`，后续 `:before_finish` 不再触发评审（修复 v0.2 iteration reset bug）。

## 触发 Hook

- `:session_start` — 重置内部状态
- `:before_finish` — Agent 准备返回前触发评审
- `:after_response` — 评审期内检查回复是否含 `pass_signal`

---

*Consult [api-reference.md](api-reference.md) for complete listing*