# task-kanban

> TUI 看板介面，即時監控 Task-Orchestrator V2 工作流執行狀態

- Author: CHC
- Repository: howjerry/weekly-checkin
- Version: 20260126132637
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/howjerry/weekly-checkin
- Web: https://mule.run/skillshub/@@howjerry/weekly-checkin~task-kanban:20260126132637

---

# Task Kanban - TUI Kanban Board for Task-Orchestrator V2

---
name: task-kanban
description: TUI 看板介面，即時監控 Task-Orchestrator V2 工作流執行狀態
argument-hint: "[feature_name]"
user-invocable: true
context: current
agent: null
allowed-tools:
  - Bash
  - Read
---

## 功能概述

Task Kanban 是一個終端機使用者介面（TUI）應用程式，提供即時視覺化監控 Task-Orchestrator V2 的工作流執行狀態。透過三欄看板視圖、Loop 狀態追蹤、品質指標面板和即時日誌顯示，讓開發者能夠直觀地掌握任務進度。

### 核心特性

- **三欄看板視圖**: Pending、In Progress、Done 欄位即時更新
- **Loop 狀態追蹤**: 顯示當前 Loop 名稱、迭代次數、通過/失敗狀態
- **品質指標面板**: Build、Lint、Test、Coverage、Review 狀態一覽
- **即時日誌顯示**: 色彩編碼的日誌訊息，支援捲動和篩選
- **任務詳情彈窗**: 檢視完整任務描述、依賴關係和錯誤訊息
- **鍵盤導航**: 完整的鍵盤快捷鍵支援

## 使用方式

### 基本用法

```bash
# 啟動看板監控指定 feature
task-kanban my-feature

# 使用自訂 specs 目錄
task-kanban my-feature --specs-dir /path/to/specs

# 顯示版本資訊
task-kanban --version
```

### Claude Code 整合

在 Claude Code 中執行：

```
/task-kanban my-feature
```

此命令將在新終端機視窗中啟動 TUI 看板介面。

## 介面佈局

```
+------------------------------------------------------------------+
|                        Task Kanban - my-feature                   |
+------------------------------------------------------------------+
|  PENDING (5)      |  IN PROGRESS (1)    |  DONE (10)             |
|-------------------|---------------------|------------------------|
|  [015] [US2]      |  > [016] [US2]      |  [001] [Setup]         |
|  實作資料驗證     |    建立 API 端點    |  初始化專案            |
|                   |                     |                        |
|  [017] [US2]      |                     |  [002] [Setup]         |
|  撰寫單元測試     |                     |  配置依賴              |
|                   |                     |                        |
+------------------------------------------------------------------+
|  LOOP STATUS                           |  QUALITY METRICS        |
|----------------------------------------|-------------------------|
|  Current: unit_test_loop               |  Build:    [SUCCESS]    |
|  Iteration: 2/5                        |  Lint:     [CLEAN]      |
|  Status: RETRYING                      |  Tests:    [RUNNING]    |
|  Last Error: Coverage 75% < 80%        |  Coverage: 75%          |
|                                        |  Review:   [PENDING]    |
+------------------------------------------------------------------+
|  LOGS                                                    [Auto]  |
|------------------------------------------------------------------|
|  10:30:15 [INFO]  Starting unit_test_loop iteration 2            |
|  10:30:16 [DEBUG] Running pytest with coverage...                |
|  10:30:20 [WARN]  Coverage below threshold: 75% < 80%            |
|  10:30:21 [INFO]  Invoking fix-context-builder...                |
+------------------------------------------------------------------+
```

## 鍵盤快捷鍵

| 按鍵 | 功能 |
|------|------|
| `Arrow Up/Down` | 在任務清單中上下移動 |
| `Arrow Left/Right` | 在欄位之間切換 |
| `Enter` | 開啟選中任務的詳情彈窗 |
| `Escape` | 關閉彈窗或取消操作 |
| `q` | 退出應用程式 |
| `r` | 手動重新載入資料 |
| `l` | 切換日誌面板展開/收合 |
| `f` | 切換日誌篩選等級 |

## 狀態指示器

### 任務狀態

| 狀態 | 顯示 | 說明 |
|------|------|------|
| Pending | 白色 | 等待執行 |
| In Progress | 黃色 + 動畫 | 正在執行 |
| Done | 綠色 + 勾選 | 已完成 |
| Failed | 紅色 | 執行失敗 |

### Loop 狀態

| 狀態 | 顏色 | 說明 |
|------|------|------|
| `pending` | 灰色 | 尚未開始 |
| `in_progress` | 黃色 | 執行中 |
| `passed` | 綠色 | 通過 |
| `failed` | 紅色 | 失敗 |
| `retrying` | 橘色 | 重試中 |

### 品質指標

| 狀態 | 顯示 |
|------|------|
| `Pending` | `[PENDING]` 灰色 |
| `Success/Clean/Passed` | `[SUCCESS]` 綠色 |
| `Failed/Dirty` | `[FAILED]` 紅色 |
| `Running` | `[RUNNING]` 黃色 |

## 技術規格

### 效能需求

| 指標 | 要求 |
|------|------|
| 更新延遲 | < 100ms |
| CPU 使用率（閒置） | < 5% |
| 記憶體使用 | < 50MB |
| 檔案監控防抖 | 50ms |

### 系統需求

- **Python**: >= 3.10
- **終端機**: 支援 256 色
- **最小寬度**: 80 字元
- **最小高度**: 24 行

### 依賴套件

```
textual>=0.50
rich>=13.0
watchdog>=3.0
pyyaml>=6.0
```

## 智能啟動（推薦）

Task Kanban 提供智能啟動機制，可自動處理環境建立和依賴安裝。

### 快速啟動

```bash
# Unix/WSL/macOS
cd .claude/skills/task-kanban
./run.sh my-feature

# Windows PowerShell
cd .claude\skills\task-kanban
.\run.ps1 my-feature
```

### 啟動選項

| 選項 | 說明 | 範例 |
|------|------|------|
| `--mode=current` | 在當前終端啟動 | `./run.sh my-feature --mode=current` |
| `--mode=new_tab` | 在新終端 tab 啟動（預設） | `./run.sh my-feature --mode=new_tab` |
| `--reinstall` | 強制重建虛擬環境 | `./run.sh --reinstall` |

### 支援的終端

| 環境 | 終端 | 新 Tab 支援 |
|------|------|-------------|
| WSL | Windows Terminal | wt.exe -w 0 new-tab |
| macOS | iTerm2 | osascript |
| macOS | Terminal.app | osascript |
| Linux | GNOME Terminal | gnome-terminal --tab |
| Linux | Konsole | konsole --new-tab |
| Windows | Windows Terminal | wt -w 0 new-tab |

### 啟動流程

```
1. 檢測 Python (3.12 -> 3.11 -> 3.10)
          |
          v
2. 虛擬環境存在？
   |- 否 -> 使用 uv/venv 建立
   +- 是 -> 繼續
          |
          v
3. 依賴已安裝？
   |- 否 -> 使用 uv/pip 安裝
   +- 是 -> 繼續
          |
          v
4. 偵測終端環境
          |
          v
5. 啟動 task-kanban
```

### 故障排除

**問題：Python 版本不足**
```
[ERROR] 找不到 Python 3.10 或更高版本
```
解決方案：安裝 Python 3.10+ https://www.python.org/downloads/

**問題：虛擬環境損壞**
```bash
./run.sh my-feature --reinstall
```

**問題：終端不支援新 tab**
```bash
# 使用當前終端模式
./run.sh my-feature --mode=current
```

---

## 手動安裝方式

### 從專案目錄安裝

```bash
cd .claude/skills/task-kanban
pip install -e .
```

### 驗證安裝

```bash
task-kanban --version
# 輸出: task-kanban 0.1.0
```

## 監控的檔案

Task Kanban 監控以下檔案的變更：

| 檔案 | 用途 |
|------|------|
| `specs/{feature}/tasks.md` | 任務清單和狀態 |
| `specs/{feature}/.session-state.yaml` | Loop 狀態和進度 |
| `.claude/logs/changes.log` | 即時日誌訊息 |

## 錯誤處理

### 檔案不存在

如果必要檔案不存在，介面會顯示提示訊息並等待檔案建立。

### 解析錯誤

如果檔案格式不正確，會在日誌面板顯示警告，並保持上次成功載入的狀態。

### 終端機太小

如果終端機視窗太小，會顯示警告訊息要求調整視窗大小。

## 專案結構

```
.claude/skills/task-kanban/
├── SKILL.md              # 本文件
├── pyproject.toml        # 專案配置
├── src/
│   ├── __init__.py
│   ├── __main__.py       # 入口點
│   ├── app.py            # 主應用程式
│   ├── models/           # 資料模型
│   │   ├── __init__.py
│   │   ├── task.py       # Task 模型
│   │   ├── loop_state.py # LoopState 模型
│   │   └── quality_metrics.py
│   ├── parsers/          # 檔案解析器
│   │   ├── __init__.py
│   │   ├── tasks_parser.py
│   │   ├── session_state_parser.py
│   │   └── log_parser.py
│   ├── widgets/          # UI 元件
│   │   ├── __init__.py
│   │   ├── kanban_board.py
│   │   ├── task_card.py
│   │   ├── loop_status_panel.py
│   │   ├── quality_metrics_panel.py
│   │   ├── log_panel.py
│   │   └── task_detail_modal.py
│   └── monitors/         # 檔案監控
│       ├── __init__.py
│       └── file_monitor.py
└── tests/                # 測試
    ├── __init__.py
    ├── conftest.py
    ├── unit/
    └── integration/
```

## 使用範例

### 範例 1: 監控開發工作流

```bash
# 在一個終端機視窗中啟動 Task Orchestrator
/task-orchestrator my-feature

# 在另一個終端機視窗中啟動看板監控
task-kanban my-feature
```

看板將即時顯示任務進度，當 Task Orchestrator 完成任務時，任務卡片會自動從 "In Progress" 移動到 "Done" 欄位。

### 範例 2: 追蹤 Loop 狀態

當 Unit Test Loop 執行時，Loop Status 面板會顯示：

```
Current: unit_test_loop
Iteration: 1/5
Status: IN_PROGRESS
```

如果測試失敗，狀態會變為 `RETRYING`，並顯示錯誤訊息：

```
Current: unit_test_loop
Iteration: 2/5
Status: RETRYING
Last Error: Coverage 75% < 80%
```

### 範例 3: 檢視任務詳情

1. 使用方向鍵選擇任務
2. 按 `Enter` 開啟詳情彈窗
3. 檢視完整描述、依賴關係和錯誤訊息
4. 按 `Escape` 關閉彈窗

### 範例 4: 篩選日誌

預設顯示所有日誌等級。按 `f` 可循環切換篩選：

- `ALL` - 顯示所有日誌
- `INFO` - 只顯示 INFO 及以上
- `WARNING` - 只顯示 WARNING 及以上
- `ERROR` - 只顯示 ERROR

### 範例 5: 快速導航

```
# 在 Pending 欄位
↓ - 移動到下一個待處理任務
→ - 切換到 In Progress 欄位

# 在任意欄位
q - 退出應用程式
r - 重新載入所有資料
```

## 疑難排解

### 問題：看板顯示 "No tasks"

**原因**: tasks.md 檔案不存在或格式不正確。

**解決方案**:
1. 確認 `specs/{feature}/tasks.md` 存在
2. 確認任務格式正確：`- [ ] [001] [US1] 任務描述`

### 問題：Loop 狀態顯示 "No active loop"

**原因**: `.session-state.yaml` 檔案不存在。

**解決方案**:
1. 確認 Task Orchestrator 正在執行
2. 確認 `specs/{feature}/.session-state.yaml` 存在

### 問題：終端機顯示亂碼

**原因**: 終端機不支援 256 色或 Unicode。

**解決方案**:
1. 使用支援 256 色的終端機（如 iTerm2、Windows Terminal）
2. 設定終端機編碼為 UTF-8

## 相關文件

- `specs/task-kanban/spec.md` - 功能規格
- `specs/task-kanban/plan.md` - 實施計畫
- `specs/task-kanban/tasks.md` - 任務清單
- `.claude/rules/workflow-orchestration.md` - 工作流規則

## 版本歷史

### v0.1.0 (2026-01-25)

- 初始版本
- 三欄看板視圖
- Loop 狀態追蹤
- 品質指標面板
- 即時日誌顯示
- 鍵盤導航
- 任務詳情彈窗