第十四章　智能体队列与前端状态管理

// apps/frontend/src/renderer/stores/task-store.ts（简化）

/** 防止渲染进程 OOM：每个任务最多存储 5000 条日志 */
export const MAX_LOG_ENTRIES = 5000;

/** 卡片拖拽或任务跨列时用的 Kanban 列顺序 */
function createEmptyTaskOrder(): TaskOrderState {
  return {
    backlog: [],
    queue: [],
    in_progress: [],
    ai_review: [],
    human_review: [],
    done: [],
    pr_created: [],
    error: []
  };
}

export const useTaskStore = create<TaskState>((set, get) => ({
  tasks: [],
  selectedTaskId: null,
  taskOrder: null,

  // 高效的单任务更新：避免遍历整个任务数组
  updateTask: (taskId, updates) =>
    set(state => {
      const index = findTaskIndex(state.tasks, taskId);
      if (index < 0) return state;
      return {
        tasks: updateTaskAtIndex(state.tasks, index, task => ({
          ...task,
          ...updates
        }))
      };
    }),

  // 批量追加日志：限制上限防止内存溢出
  batchAppendLogs: (taskId, logs) =>
    set(state => {
      const index = findTaskIndex(state.tasks, taskId);
      if (index < 0) return state;
      return {
        tasks: updateTaskAtIndex(state.tasks, index, task => {
          const combined = [...(task.logs || []), ...logs];
          // 超出上限时，只保留最新的 MAX_LOG_ENTRIES 条
          const trimmed = combined.length > MAX_LOG_ENTRIES
            ? combined.slice(combined.length - MAX_LOG_ENTRIES)
            : combined;
          return { ...task, logs: trimmed };
        })
      };
    }),
}));

// 存储在 store 外部：避免触发不必要的重渲染
const taskLastActivity = new Map<string, number>();
const STUCK_ACTIVITY_THRESHOLD_MS = 60_000; // 60 秒

export function recordTaskActivity(taskId: string): void {
  taskLastActivity.set(taskId, Date.now());
}

export function hasRecentActivity(taskId: string): boolean {
  const lastActivity = taskLastActivity.get(taskId);
  if (!lastActivity) return false;
  return Date.now() - lastActivity < STUCK_ACTIVITY_THRESHOLD_MS;
}

const taskStatusChangeListeners = new Set<
  (taskId: string, oldStatus: TaskStatus | undefined, newStatus: TaskStatus) => void
>();

// 注册监听器，返回取消函数（符合 React useEffect 清理模式）
registerTaskStatusChangeListener: (listener) => {
  taskStatusChangeListeners.add(listener);
  return () => taskStatusChangeListeners.delete(listener);
},

export class AgentState {
  // 正在运行的进程：taskId -> AgentProcess
  private processes: Map<string, AgentProcess> = new Map();

  // 已主动停止的进程的 spawnId 集合
  private killedSpawnIds: Set<number> = new Set();

  // 自增计数器：每个新进程获得唯一 ID
  private spawnCounter: number = 0;

  // 任务-账户分配：用于 rate limit 路由
  private taskProfileAssignments: Map<string, TaskProfileAssignment> = new Map();

  generateSpawnId(): number {
    return ++this.spawnCounter;
  }

  markSpawnAsKilled(spawnId: number): void {
    this.killedSpawnIds.add(spawnId);
  }

  wasSpawnKilled(spawnId: number): boolean {
    return this.killedSpawnIds.has(spawnId);
  }
}

// 停止任务时
state.markSpawnAsKilled(process.spawnId);
process.child.kill('SIGTERM');

// 子进程 close 事件
child.on('close', (code, signal) => {
  if (state.wasSpawnKilled(spawnId)) {
    // 主动停止：正常清理
    state.clearKilledSpawn(spawnId);
    events.emitTaskCancelled(taskId);
  } else {
    // 意外退出：触发恢复
    events.emitTaskFailed(taskId, `Process exited with code ${code}`);
  }
});

constructor(...) {
  // 创建防抖版本：leading + trailing，300ms 间隔
  // 效果：立即执行第一次（leading），结束后执行最后一次（trailing）
  // 相当于：每秒最多 3-4 次写入，但总是能持久化最终状态
  const { fn: debouncedFn, cancel } = debounce(
    this.persistRoadmapProgress.bind(this),
    300,
    { leading: true, trailing: true }
  );
  this.debouncedPersistRoadmapProgress = debouncedFn;
  this.cancelPersistRoadmapProgress = cancel;
}

private async ensurePythonEnvReady(
  projectId: string,
  eventType: 'ideation-error' | 'roadmap-error'
): Promise<boolean> {
  const status = await this.processManager.ensurePythonEnvReady('AgentQueue');
  if (!status.ready) {
    this.emitter.emit(
      eventType,
      projectId,
      `Python environment not ready: ${status.error || 'initialization failed'}`
    );
    return false;
  }
  return true;
}

// 延迟创建：只有在需要时才启动 XState 状态机
export function getOrCreateTerminalActor(terminalId: string): TerminalActor {
  let actor = terminalActors.get(terminalId);
  if (!actor) {
    actor = createActor(terminalMachine);
    actor.start();
    terminalActors.set(terminalId, actor);
  }
  return actor;
}

// 发送事件到终端状态机
export function sendTerminalMachineEvent(
  terminalId: string,
  event: TerminalEvent
): void {
  const actor = getOrCreateTerminalActor(terminalId);
  const stateBefore = String(actor.getSnapshot().value);
  actor.send(event);
  const stateAfter = String(actor.getSnapshot().value);
  debugLog(`Machine ${terminalId}: ${event.type} (${stateBefore} -> ${stateAfter})`);
}

// 写入终端输出的路由函数
export function writeToTerminal(terminalId: string, data: string): void {
  // 总是缓冲：即使组件未挂载也不丢数据
  terminalBufferManager.append(terminalId, data);

  // 如果终端组件正在显示，直接写入 xterm
  const callback = xtermCallbacks.get(terminalId);
  if (callback) {
    callback(data);
  }
  // 如果没有 callback（用户切换到其他项目），只缓冲
  // 当用户切回来时，组件挂载时会从 buffer 回放
}

function updateTaskAtIndex(
  tasks: Task[],
  index: number,
  updater: (task: Task) => Task
): Task[] {
  if (index < 0 || index >= tasks.length) return tasks;

  const updatedTask = updater(tasks[index]);

  // 引用未变：直接返回原数组（零分配）
  if (updatedTask === tasks[index]) {
    return tasks;
  }

  // 只替换变化的元素：不克隆整个数组
  const newTasks = [...tasks];
  newTasks[index] = updatedTask;
  return newTasks;
}

// lab14/task-bus.ts
import { create } from 'zustand';
import { EventEmitter } from 'events';

export type TaskStatus = 'pending' | 'running' | 'done' | 'error' | 'stuck';

interface TaskState {
  id: string;
  status: TaskStatus;
  logs: string[];
  startedAt?: number;
}

interface TaskStore {
  tasks: Map<string, TaskState>;

  // TODO Part A: 添加任务，返回添加后的状态
  addTask: (id: string) => void;

  // TODO Part A: 更新任务状态，触发监听器
  updateStatus: (id: string, status: TaskStatus) => void;

  // TODO Part A: 追加日志，限制上限为 1000 条
  appendLog: (id: string, log: string) => void;
}

// 模块级：活动时间戳追踪（不触发重渲染）
const lastActivity = new Map<string, number>();
const STUCK_THRESHOLD_MS = 30_000; // 30 秒

export function recordActivity(taskId: string): void {
  // TODO Part A: 记录当前时间戳
}

export function isStuck(taskId: string): boolean {
  // TODO Part A: 检查距上次活动是否超过 STUCK_THRESHOLD_MS
  return false;
}

export const useTaskStore = create<TaskStore>((set, get) => ({
  tasks: new Map(),

  addTask: (id) => set(state => {
    // TODO Part A: 用 Map 的不可变更新模式添加任务
    // 提示：new Map([...state.tasks, [id, { id, status: 'pending', logs: [] }]])
    return state;
  }),

  updateStatus: (id, status) => set(state => {
    // TODO Part A: 更新任务状态
    return state;
  }),

  appendLog: (id, log) => set(state => {
    // TODO Part A: 追加日志，超过 1000 条时截断
    return state;
  }),
}));

// lab14/task-bus.ts（续）

// 状态变更监听器
const statusListeners = new Set<
  (id: string, oldStatus: TaskStatus, newStatus: TaskStatus) => void
>();

export function onStatusChange(
  listener: (id: string, old: TaskStatus, next: TaskStatus) => void
): () => void {
  // TODO Part B: 注册监听器，返回取消函数
  return () => {};
}

// 卡顿检测器：每 10 秒扫描一次运行中的任务
export function startStuckDetector(store: ReturnType<typeof useTaskStore.getState>): () => void {
  const interval = setInterval(() => {
    const { tasks, updateStatus } = store;
    for (const [id, task] of tasks) {
      if (task.status === 'running' && isStuck(id)) {
        // TODO Part B: 将任务状态更新为 'stuck'
        console.log(`Task ${id} is stuck!`);
      }
    }
  }, 10_000);

  // 返回清理函数
  return () => clearInterval(interval);
}

// lab14/process-tracker.ts

export class ProcessTracker {
  private processes = new Map<string, { pid: number; spawnId: number }>();
  private killedSpawnIds = new Set<number>();
  private counter = 0;

  generateSpawnId(): number {
    // TODO Part C: 返回自增的 spawnId
    return 0;
  }

  register(taskId: string, pid: number, spawnId: number): void {
    // TODO Part C: 注册进程
  }

  markKilled(spawnId: number): void {
    // TODO Part C: 标记为主动停止
  }

  handleExit(taskId: string, spawnId: number, code: number): 'cancelled' | 'crashed' {
    // TODO Part C: 根据 spawnId 是否在 killedSpawnIds 中，判断是停止还是崩溃
    // 记得清理 killedSpawnIds
    return 'crashed';
  }
}

// 验证：
const tracker = new ProcessTracker();
const spawnId = tracker.generateSpawnId(); // 应为 1
tracker.register('task-1', 12345, spawnId);
tracker.markKilled(spawnId);
console.log(tracker.handleExit('task-1', spawnId, 0)); // → 'cancelled'

const spawnId2 = tracker.generateSpawnId(); // 应为 2
tracker.register('task-2', 12346, spawnId2);
// 不调用 markKilled
console.log(tracker.handleExit('task-2', spawnId2, 1)); // → 'crashed'