Claude-Code-Workflow/docs/zh-CN/features/queue.md

队列管理

一句话概述

队列管理页面提供对问题执行队列的集中控制，配备调度器控件、状态监控和会话池管理。

---

解决的痛点

痛点	当前状态	队列解决方案
执行无序	没有统一的任务队列	带分组项目的集中化队列
调度器状态未知	不知道调度器是否在运行	实时状态指示器（空闲/运行/暂停）
无执行控制	无法启动/停止队列处理	带确认的开始/暂停/停止控件
并发限制	同时运行太多会话	可配置的最大并发会话数
无可见性	不知道队列中有什么	统计卡片 + 带状态跟踪的项目列表
资源浪费	空闲会话消耗资源	带超时配置的会话池概览

---

概述

位置: ccw/frontend/src/pages/QueuePage.tsx（旧版），ccw/frontend/src/components/terminal-dashboard/QueuePanel.tsx（当前）

用途: 查看和管理问题执行队列，配备调度器控件、进度跟踪和会话池管理。

访问方式: 导航 → 问题 → 队列标签页 或 终端仪表板 → 队列浮动面板

布局:

+--------------------------------------------------------------------------+
|  队列面板标题栏                                                             |
+--------------------------------------------------------------------------+
|  调度器状态栏                                                               |
|  +----------------+  +-------------+  +-------------------------------+         |
|  | 状态徽章       |  | 进度         |  | 并发数 (2/2)                  |         |
|  +----------------+  +-------------+  +-------------------------------+         |
+--------------------------------------------------------------------------+
|  调度器控件                                                                |
|  +--------+  +--------+  +--------+  +-----------+                          |
|  | 开始  |  | 暂停  |  | 停止   |  | 配置      |                          |
|  +--------+  +--------+  +--------+  +-----------+                          |
+--------------------------------------------------------------------------+
|  队列项目列表                                                              |
|  +---------------------------------------------------------------------+    |
|  | QueueItemRow（状态、issue_id、session_key、操作）                  |    |
|  | - 状态图标（待处理/执行中/已完成/被阻塞/失败）                    |    |
|  | - Issue ID / 项目 ID 显示                                           |    |
|  | - 会话绑定信息                                                       |    |
|  | - 进度指示器（对于执行中的项目）                                     |    |
|  +---------------------------------------------------------------------+    |
|  | [更多队列项目...]                                                    |    |
|  +---------------------------------------------------------------------+    |
+--------------------------------------------------------------------------+
|  会话池概览（可选）                                                         |
|  +--------------------------------------------------------------------------+
|  | 活动会话 | 空闲会话 | 总会话数                                        |
|  +--------------------------------------------------------------------------+

---

核心功能

功能	描述
调度器状态	实时状态指示器（空闲/运行/暂停），带视觉徽章
进度跟踪	显示队列总体完成百分比的进度条
开始/暂停/停止控件	控制队列执行，停止操作时带确认对话框
并发显示	显示当前活动会话数与最大并发会话数
队列项目列表	所有队列项目的可滚动列表，附带状态、Issue ID 和会话绑定
状态图标	项目状态的视觉指示器（待处理/执行中/已完成/被阻塞/失败）
会话池	活动会话、空闲会话和总会话数的概览
配置面板	调整最大并发会话数和超时设置
空状态	队列为空时的友好消息，附带添加项目的说明

---

组件层次结构

QueuePage（旧版）/ QueuePanel（当前）
├── QueuePanelHeader
│   ├── 标题
│   └── 标签切换器（队列 | 编排器）
├── SchedulerBar（内联在 QueueListColumn 中）
│   ├── 状态徽章
│   ├── 进度 + 并发数
│   └── 控制按钮（播放/暂停/停止）
├── QueueItemsList
│   └── QueueItemRow（重复）
│       ├── 状态图标
│       ├── Issue ID / 项目 ID
│       ├── 会话绑定
│       └── 进度（对于执行中的项目）
└── SchedulerPanel（独立）
    ├── 状态部分
    ├── 进度条
    ├── 控制按钮
    ├── 配置部分
    │   ├── 最大并发会话数
    │   ├── 会话空闲超时
    │   └── 恢复键绑定超时
    └── 会话池概览

---

Props API

QueuePanel

Prop	类型	默认值	描述
embedded	boolean	false	面板是否嵌入在另一个组件中

SchedulerPanel

Prop	类型	默认值	描述
-	-	-	此组件不接受任何 props（所有数据来自 Zustand store）

QueueListColumn

Prop	类型	默认值	描述
-	-	-	此组件不接受任何 props（所有数据来自 Zustand store）

---

状态管理

Zustand Stores

Store	选择器	用途
queueSchedulerStore	selectQueueSchedulerStatus	当前调度器状态（空闲/运行/暂停）
queueSchedulerStore	selectSchedulerProgress	队列总体完成百分比
queueSchedulerStore	selectQueueItems	所有队列项目的列表
queueSchedulerStore	selectCurrentConcurrency	活动会话计数
queueSchedulerStore	selectSchedulerConfig	调度器配置
queueSchedulerStore	selectSessionPool	会话池概览
queueSchedulerStore	selectSchedulerError	错误消息（如果有）
issueQueueIntegrationStore	selectAssociationChain	用于高亮显示的当前关联链
queueExecutionStore	selectByQueueItem	队列项目的执行数据

队列项目状态

type QueueItemStatus =
  | 'pending'      // 等待执行
  | 'executing'    // 正在处理中
  | 'completed'    // 成功完成
  | 'blocked'      // 被依赖项阻塞
  | 'failed';      // 失败并报错

调度器状态

type QueueSchedulerStatus =
  | 'idle'     // 无项目或已停止
  | 'running'  // 活动处理项目
  | 'paused';  // 临时暂停

---

使用示例

基本队列面板

import { QueuePanel } from '@/components/terminal-dashboard/QueuePanel'

function QueueSection() {
  return <QueuePanel />
}

独立调度器面板

import { SchedulerPanel } from '@/components/terminal-dashboard/SchedulerPanel'

function SchedulerControls() {
  return <SchedulerPanel />
}

嵌入式队列列表列

import { QueueListColumn } from '@/components/terminal-dashboard/QueueListColumn'

function EmbeddedQueue() {
  return <QueueListColumn />
}

队列 Store 操作

import { useQueueSchedulerStore } from '@/stores/queueSchedulerStore'

function QueueActions() {
  const startQueue = useQueueSchedulerStore((s) => s.startQueue)
  const pauseQueue = useQueueSchedulerStore((s) => s.pauseQueue)
  const stopQueue = useQueueSchedulerStore((s) => s.stopQueue)
  const updateConfig = useQueueSchedulerStore((s) => s.updateConfig)

  const handleStart = () => startQueue()
  const handlePause = () => pauseQueue()
  const handleStop = () => stopQueue()
  const handleConfig = (config) => updateConfig(config)

  return (
    <div>
      <button onClick={handleStart}>开始</button>
      <button onClick={handlePause}>暂停</button>
      <button onClick={handleStop}>停止</button>
      <button onClick={() => handleConfig({ maxConcurrentSessions: 4 })}>
        设置最大值为 4
      </button>
    </div>
  )
}

---

配置

调度器配置

设置	类型	默认值	描述
maxConcurrentSessions	number	2	同时运行的最大会话数
sessionIdleTimeoutMs	number	60000	空闲会话超时时间（毫秒）
resumeKeySessionBindingTimeoutMs	number	300000	恢复键绑定超时时间（毫秒）

队列项目结构

interface QueueItem {
  item_id: string;
  issue_id?: string;
  sessionKey?: string;
  status: QueueItemStatus;
  execution_order: number;
  created_at?: number;
  updated_at?: number;
}

---

可访问性

• 键盘导航:

  • Tab - 在队列项目和控件之间导航
  • Enter/Space - 激活按钮
  • Escape - 关闭对话框

• ARIA 属性:

  • 控制按钮上的 aria-label
  • 状态更新的 aria-live 区域
  • 当前队列项目的 aria-current
  • 队列项目列表上的 role="list"

• 屏幕阅读器支持:

  • 状态变化被宣布
  • 进度更新被朗读
  • 错误消息被宣布

---

相关链接

• 问题中心 - 统一的问题、队列和发现管理
• 终端仪表板 - 带集成队列面板的终端优先工作空间
• 发现 - 发现会话跟踪
• 会话 - 会话管理和详情