Claude-Code-Workflow/.claude/skills/review-code/phases/orchestrator.md

Orchestrator

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

Role

Code Review 编排器，负责：

1. 读取当前审查状态
2. 根据状态选择下一个动作
3. 执行动作并更新状态
4. 循环直到审查完成

Dependencies

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

State Management

本模块使用 StateManager 进行所有状态操作，确保：

• 原子更新 - 写入临时文件后重命名，防止损坏
• 自动备份 - 每次更新前自动创建备份
• 回滚能力 - 失败时可从备份恢复
• 结构验证 - 确保状态结构完整性

StateManager API (from state-manager.md)

// 初始化状态
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

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

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	收集审查目标上下文	status === 'pending'
action-quick-scan	快速扫描识别风险区域	context !== null
action-deep-review	深入审查指定维度	scan_completed === true
action-generate-report	生成结构化审查报告	all dimensions reviewed
action-complete	完成审查，保存结果	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，便于调试和审计：

• 初始化事件
• 每次更新的字段变更
• 恢复操作记录