# Orchestrator

根据当前状态选择并执行下一个审查动作。

## Role

Code Review 编排器，负责：
1. 读取当前审查状态
2. 根据状态选择下一个动作
3. 执行动作并更新状态
4. 循环直到审查完成

## Dependencies

- **State Manager**: [state-manager.md](./state-manager.md) - 提供原子化状态操作、自动备份、验证和回滚功能

## State Management

本模块使用 StateManager 进行所有状态操作，确保：
- **原子更新** - 写入临时文件后重命名，防止损坏
- **自动备份** - 每次更新前自动创建备份
- **回滚能力** - 失败时可从备份恢复
- **结构验证** - 确保状态结构完整性

### StateManager API (from state-manager.md)

```javascript
// 初始化状态
StateManager.initState(workDir)

// 读取当前状态
StateManager.getState(workDir)

// 更新状态（原子操作，自动备份）
StateManager.updateState(workDir, updates)

// 获取下一个待审查维度
StateManager.getNextDimension(state)

// 标记维度完成
StateManager.markDimensionComplete(workDir, dimension)

// 记录错误
StateManager.recordError(workDir, action, message)

// 从备份恢复
StateManager.restoreState(workDir)
```

## Decision Logic

```javascript
function selectNextAction(state) {
  // 1. 终止条件检查
  if (state.status === 'completed') return null;
  if (state.status === 'user_exit') return null;
  if (state.error_count >= 3) return 'action-abort';

  // 2. 初始化阶段
  if (state.status === 'pending' || !state.context) {
    return 'action-collect-context';
  }

  // 3. 快速扫描阶段
  if (!state.scan_completed) {
    return 'action-quick-scan';
  }

  // 4. 深入审查阶段 - 使用 StateManager 获取下一个维度
  const nextDimension = StateManager.getNextDimension(state);
  if (nextDimension) {
    return 'action-deep-review';  // 传递 dimension 参数
  }

  // 5. 报告生成阶段
  if (!state.report_generated) {
    return 'action-generate-report';
  }

  // 6. 完成
  return 'action-complete';
}
```

## Execution Loop

```javascript
async function runOrchestrator() {
  console.log('=== Code Review Orchestrator Started ===');

  let iteration = 0;
  const MAX_ITERATIONS = 20;  // 6 dimensions + overhead

  // 初始化状态（如果尚未初始化）
  let state = StateManager.getState(workDir);
  if (!state) {
    state = StateManager.initState(workDir);
  }

  while (iteration < MAX_ITERATIONS) {
    iteration++;

    // 1. 读取当前状态（使用 StateManager）
    state = StateManager.getState(workDir);
    if (!state) {
      console.error('[Orchestrator] Failed to read state, attempting recovery...');
      state = StateManager.restoreState(workDir);
      if (!state) {
        console.error('[Orchestrator] Recovery failed, aborting.');
        break;
      }
    }
    console.log(`[Iteration ${iteration}] Status: ${state.status}`);

    // 2. 选择下一个动作
    const actionId = selectNextAction(state);

    if (!actionId) {
      console.log('Review completed, terminating.');
      break;
    }

    console.log(`[Iteration ${iteration}] Executing: ${actionId}`);

    // 3. 更新状态：当前动作（使用 StateManager）
    StateManager.updateState(workDir, { current_action: actionId });

    // 4. 执行动作
    try {
      const actionPrompt = Read(`phases/actions/${actionId}.md`);

      // 确定当前需要审查的维度（使用 StateManager）
      const currentDimension = StateManager.getNextDimension(state);

      const result = await Task({
        subagent_type: 'universal-executor',
        run_in_background: false,
        prompt: `
[WORK_DIR]
${workDir}

[STATE]
${JSON.stringify(state, null, 2)}

[CURRENT_DIMENSION]
${currentDimension || 'N/A'}

[ACTION]
${actionPrompt}

[SPECS]
Review Dimensions: specs/review-dimensions.md
Issue Classification: specs/issue-classification.md

[RETURN]
Return JSON with stateUpdates field containing updates to apply to state.
`
      });

      const actionResult = JSON.parse(result);

      // 5. 更新状态：动作完成（使用 StateManager）
      StateManager.updateState(workDir, {
        current_action: null,
        completed_actions: [...(state.completed_actions || []), actionId],
        ...actionResult.stateUpdates
      });

      // 如果是深入审查动作，标记维度完成
      if (actionId === 'action-deep-review' && currentDimension) {
        StateManager.markDimensionComplete(workDir, currentDimension);
      }

    } catch (error) {
      // 错误处理（使用 StateManager.recordError）
      console.error(`[Orchestrator] Action failed: ${error.message}`);
      StateManager.recordError(workDir, actionId, error.message);

      // 清除当前动作
      StateManager.updateState(workDir, { current_action: null });

      // 检查是否需要恢复状态
      const updatedState = StateManager.getState(workDir);
      if (updatedState && updatedState.error_count >= 3) {
        console.error('[Orchestrator] Too many errors, attempting state recovery...');
        StateManager.restoreState(workDir);
      }
    }
  }

  console.log('=== Code Review Orchestrator Finished ===');
}
```

## Action Catalog

| Action | Purpose | Preconditions |
|--------|---------|---------------|
| [action-collect-context](actions/action-collect-context.md) | 收集审查目标上下文 | status === 'pending' |
| [action-quick-scan](actions/action-quick-scan.md) | 快速扫描识别风险区域 | context !== null |
| [action-deep-review](actions/action-deep-review.md) | 深入审查指定维度 | scan_completed === true |
| [action-generate-report](actions/action-generate-report.md) | 生成结构化审查报告 | all dimensions reviewed |
| [action-complete](actions/action-complete.md) | 完成审查，保存结果 | report_generated === true |

## Termination Conditions

- `state.status === 'completed'` - 审查正常完成
- `state.status === 'user_exit'` - 用户主动退出
- `state.error_count >= 3` - 错误次数超限（由 StateManager.recordError 自动处理）
- `iteration >= MAX_ITERATIONS` - 迭代次数超限

## Error Recovery

本模块利用 StateManager 提供的错误恢复机制：

| Error Type | Recovery Strategy | StateManager Function |
|------------|-------------------|----------------------|
| 状态读取失败 | 从备份恢复 | `restoreState(workDir)` |
| 动作执行失败 | 记录错误，累计超限后自动失败 | `recordError(workDir, action, message)` |
| 状态不一致 | 验证并恢复 | `getState()` 内置验证 |
| 用户中止 | 保存当前进度 | `updateState(workDir, { status: 'user_exit' })` |

### 错误处理流程

```
1. 动作执行失败
   |
2. StateManager.recordError() 记录错误
   |
3. 检查 error_count
   |
   +-- < 3: 继续下一次迭代
   +-- >= 3: StateManager 自动设置 status='failed'
             |
             Orchestrator 检测到 status 变化
             |
             尝试 restoreState() 恢复到上一个稳定状态
```

### 状态备份时机

StateManager 在以下时机自动创建备份：
- 每次 `updateState()` 调用前
- 可通过 `backupState(workDir, suffix)` 手动创建命名备份

### 历史追踪

所有状态变更记录在 `state-history.json`，便于调试和审计：
- 初始化事件
- 每次更新的字段变更
- 恢复操作记录