队列管理

一句话概述

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

解决的痛点

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

概述

位置: 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`	队列项目的执行数据

队列项目状态

typescript

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

调度器状态

typescript

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

使用示例

基本队列面板

tsx

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

function QueueSection() {
  return <QueuePanel />
}

独立调度器面板

tsx

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

function SchedulerControls() {
  return <SchedulerPanel />
}

嵌入式队列列表列

tsx

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

function EmbeddedQueue() {
  return <QueueListColumn />
}

队列 Store 操作

tsx

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`	恢复键绑定超时时间（毫秒）

队列项目结构

typescript

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"
屏幕阅读器支持:
- 状态变化被宣布
- 进度更新被朗读
- 错误消息被宣布

队列管理 ​

一句话概述 ​

解决的痛点 ​

概述 ​

核心功能 ​

组件层次结构 ​

Props API ​

QueuePanel ​

SchedulerPanel ​

QueueListColumn ​

状态管理 ​

Zustand Stores ​

队列项目状态 ​

调度器状态 ​

使用示例 ​

基本队列面板 ​

独立调度器面板 ​

嵌入式队列列表列 ​

队列 Store 操作 ​

配置 ​

调度器配置 ​

队列项目结构 ​

可访问性 ​

相关链接 ​

队列管理

一句话概述

解决的痛点

概述

核心功能

组件层次结构

Props API

QueuePanel

SchedulerPanel

QueueListColumn

状态管理

Zustand Stores

队列项目状态

调度器状态

使用示例

基本队列面板

独立调度器面板

嵌入式队列列表列

队列 Store 操作

配置

调度器配置

队列项目结构

可访问性

相关链接