mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-01 15:03:57 +08:00
2fb93d20e0
- Introduced comprehensive documentation for the queue management feature, detailing its pain points, core functionalities, and component structure. - Added terminal dashboard documentation, highlighting its layout, core features, and usage examples. - Created an index page in Chinese for Claude Code Workflow, summarizing its purpose and core features, along with quick links to installation and guides.
284 lines
9.7 KiB
Markdown
284 lines
9.7 KiB
Markdown
# 队列管理
|
||
|
||
## 一句话概述
|
||
**队列管理页面提供对问题执行队列的集中控制，配备调度器控件、状态监控和会话池管理。**
|
||
|
||
---
|
||
|
||
## 解决的痛点
|
||
|
||
| 痛点 | 当前状态 | 队列解决方案 |
|
||
|------|----------|--------------|
|
||
| **执行无序** | 没有统一的任务队列 | 带分组项目的集中化队列 |
|
||
| **调度器状态未知** | 不知道调度器是否在运行 | 实时状态指示器（空闲/运行/暂停） |
|
||
| **无执行控制** | 无法启动/停止队列处理 | 带确认的开始/暂停/停止控件 |
|
||
| **并发限制** | 同时运行太多会话 | 可配置的最大并发会话数 |
|
||
| **无可见性** | 不知道队列中有什么 | 统计卡片 + 带状态跟踪的项目列表 |
|
||
| **资源浪费** | 空闲会话消耗资源 | 带超时配置的会话池概览 |
|
||
|
||
---
|
||
|
||
## 概述
|
||
|
||
**位置**: `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;
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 可访问性
|
||
|
||
- **键盘导航**:
|
||
- <kbd>Tab</kbd> - 在队列项目和控件之间导航
|
||
- <kbd>Enter</kbd>/<kbd>Space</kbd> - 激活按钮
|
||
- <kbd>Escape</kbd> - 关闭对话框
|
||
|
||
- **ARIA 属性**:
|
||
- 控制按钮上的 `aria-label`
|
||
- 状态更新的 `aria-live` 区域
|
||
- 当前队列项目的 `aria-current`
|
||
- 队列项目列表上的 `role="list"`
|
||
|
||
- **屏幕阅读器支持**:
|
||
- 状态变化被宣布
|
||
- 进度更新被朗读
|
||
- 错误消息被宣布
|
||
|
||
---
|
||
|
||
## 相关链接
|
||
|
||
- [问题中心](/features/issue-hub) - 统一的问题、队列和发现管理
|
||
- [终端仪表板](/features/terminal) - 带集成队列面板的终端优先工作空间
|
||
- [发现](/features/discovery) - 发现会话跟踪
|
||
- [会话](/features/sessions) - 会话管理和详情
|