chore: add project configs, backend repair services, docs, and code quality tooling

- Add pre-commit hooks (ruff, black, prettier) and ESLint/Prettier configs
- Add backend repair services (execution, orchestration, preview) with tests
- Add project documentation (CLAUDE.md, README.md, design specs and plans)
- Add MissingTagsInlinePanel component for exception handling
- Add pyproject.toml with ruff/black configuration

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs/superpowers/specs/2026-05-07-workbench-refactor-design.md

@@ -0,0 +1,157 @@
+# WorkbenchPage 重构 — 设计规格
+
+> 创建日期: 2026-05-07
+> 状态: 设计中
+
+## 概述
+
+将 WorkbenchPage.jsx 从 ~800 行单体组件重构为 5 个聚焦组件 + 2 个自定义 hooks 的模块化架构，继承深色专业主题风格。
+
+### 核心痛点
+
+- 所有逻辑在一个文件（任务加载、WebSocket、配置展示、进度可视化、5阶段统计、文件列表、日志流）
+- 事件处理爆炸（handleStreamEvent 处理 10+ 种 WebSocket 事件类型）
+- 统计展示冗余（5 个阶段 40+ 个 StatCard 重复渲染）
+- 配置和控制耦合（目录配置展示和任务启动/监控逻辑混在一起）
+
+## 设计决策
+
+| 维度 | 决策 |
+|------|------|
+| 视觉风格 | 继承深色专业主题（indigo/slate，与异常中心一致） |
+| 组件拆分 | 6 个功能组件 + 2 个自定义 hooks |
+| 事件处理 | `useTaskStream` hook 封装 WebSocket 事件处理 |
+| 统计面板 | `StageStatsPanel` 通过 stage/stats props 消除 40+ 重复 StatCard |
+| 后端改动 | 无需改动 |
+
+## 组件架构
+
+```
+src/
+├── pages/
+│   └── WorkbenchPage.jsx              # ~120行容器（从~800行精简）
+├── components/workbench/
+│   ├── TaskControlPanel.jsx           # 目录配置展示 + 启动/重试按钮
+│   ├── TaskProgressBar.jsx            # 5阶段进度条（Scan→Preprocess→Match→Dedupe→Organize）
+│   ├── StageStatsPanel.jsx            # 5阶段统计面板（消除40+重复StatCard）
+│   ├── TaskInfoPanel.jsx              # 当前任务基本信息
+│   ├── TaskFileList.jsx               # 任务文件列表
+│   └── TaskLogStream.jsx              # 实时日志流
+├── hooks/
+│   ├── useTaskStream.js               # WebSocket 连接 + 10+ 事件类型处理
+│   └── useTaskRunner.js               # 任务启动/状态管理
+└── utils/
+    └── workbench.js                   # 阶段定义、空统计模板等共享常量
+```
+
+### 组件职责
+
+**WorkbenchPage** — 页面容器（~120行）
+- 通过 useTaskStream 和 useTaskRunner 管理顶层状态
+- 将 task/items/logs/config 通过 props 分发给子组件
+- 不包含任何渲染细节
+
+**TaskControlPanel** — 任务控制面板
+- Props: config, canStart, isRunning, isCompleted, isFailed, onStart, isStarting, errorMessage
+- 显示三个目录配置（输入/输出/回收站）
+- 根据状态显示不同的启动按钮和提示
+
+**TaskProgressBar** — 5阶段进度条
+- Props: task, isRunning, isCompleted, isFailed, progressWidth, progressLabel, latestFile
+- 5个圆形步骤节点 + 连接线 + 进度条
+- 状态颜色：running=emerald/active=emerald/completed=emerald/failed=rose
+
+**StageStatsPanel** — 阶段统计面板
+- Props: stageName, stats, stageConfig
+- 通过 STAGE_STATS_CONFIG 自动渲染该阶段的所有统计卡片
+- 消除原来 5 个阶段的重复 StatCard 排列
+
+**TaskInfoPanel** — 任务信息面板
+- Props: task, latestLogId, hasMoreLogs
+- 显示任务状态、当前阶段、开始/完成时间等基本信息
+
+**TaskFileList** — 任务文件列表
+- Props: items, isLoading
+- 文件项展示：路径、封面/歌词状态、各阶段状态徽章
+
+**TaskLogStream** — 实时日志流
+- Props: logs, logsEndRef
+- 分色日志行（error=rose/success=emerald/warning=amber/info=blue）
+
+### 自定义 Hooks
+
+**useTaskStream**
+- 封装 WebSocket 连接（createTaskStream）
+- 处理 10+ 事件类型：task.snapshot, task.started, stage.started, *.progress, stage.completed, task.completed, task.failed, log.appended
+- 管理 task, items, logs 状态
+- 返回 { task, items, logs, latestFile, hasMoreLogs, latestLogId, loadCurrentTask, startTask, ... }
+
+**useTaskRunner**
+- 封装任务启动/停止逻辑
+- runTask API 调用 + 409 冲突处理（已有运行中任务）
+- 返回 { isStarting, errorMessage, handleStart }
+
+### 数据流
+
+```
+WorkbenchPage (顶层 ~120行)
+  │
+  ├─ useTaskStream()     ──→ WebSocket → task/items/logs 状态
+  ├─ useTaskRunner()     ──→ 启动/停止逻辑
+  │
+  ├─ TaskControlPanel    ← config, canStart, isRunning, isStarting
+  ├─ TaskProgressBar     ← task, stageIndex, progressWidth
+  ├─ StageStatsPanel ×5  ← task.stats.{scan,preprocess,match,dedupe,organize}
+  ├─ TaskInfoPanel       ← task 基本信息
+  ├─ TaskFileList        ← items
+  └─ TaskLogStream       ← logs
+```
+
+## 阶段统计配置（消除重复）
+
+```javascript
+// utils/workbench.js
+export const STAGE_STATS_CONFIG = {
+  scan: [
+    { key: 'total_found', label: '候选音频', color: 'white' },
+    { key: 'queued', label: '成功入队', color: 'emerald' },
+    { key: 'skipped_locked', label: '最近写入跳过', color: 'amber' },
+    { key: 'skipped_invalid', label: '无效文件', color: 'rose', error: true },
+    // { key: 'ignored_non_audio', label: '静默忽略非音频', fullWidth: true }
+  ],
+  preprocess: [
+    { key: 'input_items', label: '输入项目', color: 'white' },
+    { key: 'output_items', label: '有效输出', color: 'emerald' },
+    // ... 其余字段
+  ],
+  match: [ /* ... */ ],
+  dedupe: [ /* ... */ ],
+  organize: [ /* ... */ ]
+};
+```
+
+StageStatsPanel 根据 stageName 查找配置，自动生成 `<StatCard>` 列表。
+
+## 兼容性
+
+- 保留所有现有功能不变
+- props 接口与现有 constants/STAGES 定义兼容
+- WebSocket 事件处理逻辑不变，仅位置改变
+- MissingTagsInlinePanel 保持不变
+
+## 非目标（不在本次范围）
+
+- 后端 API 修改
+- 新增任务类型
+- 配置表单重构（SettingsPage 独立优化）
+- MissingTagsInlinePanel 整合（后续单独优化）
+
+## 实现顺序
+
+1. **Phase 1**: 提取共享常量到 `utils/workbench.js`
+2. **Phase 2**: 创建 `useTaskStream` hook（最复杂，WebSocket 事件处理）
+3. **Phase 3**: 创建 `useTaskRunner` hook（任务启动逻辑）
+4. **Phase 4**: 创建 StageStatsPanel 组件（消除最大重复）
+5. **Phase 5**: 创建其余 5 个展示组件
+6. **Phase 6**: 重写 WorkbenchPage 为轻量容器
+7. **Phase 7**: 构建验证