claude-code/docs/superpowers/plans/2026-06-13-workflow-panel-redesign.md

Workflow Panel Redesign Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: 把 /workflows 面板从双栏（左 run 列表 / 右 phase+agent）原地重写为三区焦点模型（顶 run tab + 左 phase 筛选侧栏 + 右 agent 列表），零引擎改动。

Architecture: run_started 事件已携带 meta.phases，store 落地 declaredPhases 即可显示 pending phase。面板拆成 TabsBar / PhaseSidebar / AgentList + 共享 status.ts（状态→字符/颜色）与 selectors.ts（合并/过滤纯函数），WorkflowsPanel 持焦点状态机（activeRunId / focusColumn / selectedPhaseIndex / selectedAgentIndex），useWorkflowKeyboard 改焦点轮转键位。

Tech Stack: TypeScript strict、React/@anthropic/ink、bun:test、Biome。无 ink-testing-library——测试走纯函数 + 数据契约路线（与现有 WorkflowsPanel.test.tsx 一致）。

---

项目约定（覆盖 skill 默认，执行前必读）

1. 提交规则（CLAUDE.md）：git commit 仅在用户明确要求时执行。下方每个 Task 末尾的 "Commit" 步骤是逻辑切分点（该 task 自洽、可独立提交）——实际是否真正 git commit 由用户在执行时决定。默认：完成一个 Task 后不自动 commit，改在每个里程碑（Task 3 / Task 7）结束统一问用户。
2. 测试策略：项目未引入 ink-testing-library（grep 全 src/ 无结果）。组件不写渲染测试。所有可测逻辑必须抽成纯函数（status.ts / selectors.ts / routeWorkflowKey）并 TDD；组件只保证 tsc + biome 通过。
3. 类型规范：生产代码禁 as any；.tsx 120 行宽 + 强制分号；.ts 80 行宽 + 按需分号。feature() 仅用在 if/三元条件位（本计划不涉及 feature flag）。
4. Mock 规范：本计划涉及的 store/纯函数测试无需 mock（纯逻辑）。若后续集成测试需要，用共享 tests/mocks/log.ts / debug.ts，mock 底层副作用而非业务模块。
5. 每 Task 结束：bun run precheck 必须零错误（typecheck + lint:fix + test）。

文件结构

文件	动作	职责
src/workflow/progress/store.ts	改	RunProgress.declaredPhases + AgentProgress.outputShape；reducer 落地
src/workflow/panel/status.ts	新建	状态→字符/颜色映射（STATUS_DOT 从 WorkflowList 迁入）+ agentVisual
src/workflow/panel/selectors.ts	新建	mergePhases / filterAgentsByPhase / tabLabel 纯函数
src/workflow/panel/useWorkflowKeyboard.ts	改写	routeWorkflowKey 纯函数 + 焦点模型 handlers
src/workflow/panel/TabsBar.tsx	新建	顶部 run tab 行
src/workflow/panel/PhaseSidebar.tsx	新建	左 phase 列表（含 All + pending）
src/workflow/panel/AgentList.tsx	新建	右 agent 列表（按 phase 过滤）
src/workflow/panel/WorkflowsPanel.tsx	重写	焦点状态机 + 组装；保留导出 clampSelected
src/workflow/panel/WorkflowList.tsx	删除	职责迁入 TabsBar + status.ts
src/workflow/panel/WorkflowDetail.tsx	删除	职责拆入 PhaseSidebar + AgentList
src/workflow/__tests__/WorkflowsPanel.test.tsx	改	STATUS_DOT import 改从 status.js；保留 clampSelected 契约
src/workflow/__tests__/progressStore.test.ts	改	加 declaredPhases / outputShape 用例
src/workflow/__tests__/status.test.ts	新建	状态映射 + agentVisual
src/workflow/__tests__/selectors.test.ts	新建	mergePhases / filterAgentsByPhase / tabLabel
src/workflow/__tests__/useWorkflowKeyboard.test.ts	新建	routeWorkflowKey
docs/features/workflow-scripts.md	改	§六 更新三区布局/键位

---

Task 1: store 落地 declaredPhases + outputShape

Files:

• Modify: src/workflow/progress/store.ts:4-11（AgentProgress）、store.ts:13-24（RunProgress）、store.ts:46-62（ensure）、store.ts:78-83（run_started）、store.ts:107-123（agent_done）

• Test: src/workflow/__tests__/progressStore.test.ts

• Step 1: 在 progressStore.test.ts 末尾追加失败测试

test('run_started 落地 declaredPhases（来自 meta.phases，顺序保留）', () => {
  const { bus, store } = newStore()
  bus.emit({
    type: 'run_started',
    runId: 'r1',
    workflowName: 'w',
    meta: {
      name: 'w',
      description: 'd',
      phases: [{ title: 'Find' }, { title: 'Review' }, { title: 'Verify' }],
    },
  })
  expect(store.get('r1')!.declaredPhases).toEqual(['Find', 'Review', 'Verify'])
})

test('run_started meta 为 null → declaredPhases = []', () => {
  const { bus, store } = newStore()
  bus.emit({ type: 'run_started', runId: 'r1', workflowName: 'w', meta: null })
  expect(store.get('r1')!.declaredPhases).toEqual([])
})

test('agent_done 落地 outputShape（ok·object / ok·text / dead 无）', () => {
  const { bus, store } = newStore()
  bus.emit({ type: 'run_started', runId: 'r1', workflowName: 'w', meta: null })
  bus.emit({ type: 'agent_started', runId: 'r1', agentId: 0, phase: 'A' })
  bus.emit({ type: 'agent_started', runId: 'r1', agentId: 1, phase: 'A' })
  bus.emit({ type: 'agent_started', runId: 'r1', agentId: 2, phase: 'A' })
  bus.emit({
    type: 'agent_done', runId: 'r1', agentId: 0, phase: 'A',
    result: { kind: 'ok', output: { x: 1 }, usage: { outputTokens: 1 } },
  })
  bus.emit({
    type: 'agent_done', runId: 'r1', agentId: 1, phase: 'A',
    result: { kind: 'ok', output: 'hi', usage: { outputTokens: 1 } },
  })
  bus.emit({ type: 'agent_done', runId: 'r1', agentId: 2, phase: 'A', result: { kind: 'dead' } })
  const agents = store.get('r1')!.agents
  expect(agents.find(a => a.id === 0)?.outputShape).toBe('object')
  expect(agents.find(a => a.id === 1)?.outputShape).toBe('text')
  expect(agents.find(a => a.id === 2)?.outputShape).toBeUndefined()
})

• Step 2: 跑测试确认失败

Run: bun test src/workflow/__tests__/progressStore.test.ts Expected: 3 个新用例 FAIL（declaredPhases undefined / 无 outputShape）

• Step 3: 改 AgentProgress 加 outputShape（store.ts:4-11）

export type AgentProgress = {
  /** 引擎盖戳的唯一 id，精确关联 started/done（修旧 LIFO 竞态）。 */
  id: number
  label?: string
  phase?: string
  status: 'running' | 'done'
  resultKind?: string
  /** 仅 done·ok 时有意义：output 是对象→'object'，否则→'text'。dead/skipped 无。 */
  outputShape?: 'text' | 'object'
}

• Step 4: 改 RunProgress 加 declaredPhases（store.ts:13-24）

export type RunProgress = {
  runId: string
  workflowName: string
  status: 'running' | 'completed' | 'failed' | 'killed'
  phases: Array<{ title: string; status: 'running' | 'done' }>
  /** 来自 run_started.meta.phases[].title；面板据此显示 pending(○) phase。无 meta → []。 */
  declaredPhases: string[]
  currentPhase: string | null
  agents: AgentProgress[]
  agentCount: number
  returnValue?: unknown
  error?: string
  updatedAt: number
}

• Step 5: ensure() 初始化 declaredPhases: []（store.ts:46-62，在 currentPhase: null, 上一行加）

        phases: [],
        declaredPhases: [],
        currentPhase: null,

• Step 6: reducer run_started 分支落地 declaredPhases（store.ts:74-77）

      case 'run_started':
        p.workflowName = event.workflowName
        p.status = 'running'
        p.declaredPhases = event.meta?.phases?.map(ph => ph.title) ?? []
        break

• Step 7: reducer agent_done 两处落地 outputShape（store.ts:107-123）

补建分支（if (!a) 内）加 outputShape：

      case 'agent_done': {
        let a = p.agents.find(x => x.id === event.agentId)
        if (!a) {
          a = {
            id: event.agentId,
            label: event.label,
            phase: event.phase,
            status: 'done',
            ...(event.result.kind === 'ok'
              ? {
                  outputShape:
                    typeof event.result.output === 'object' &&
                    event.result.output !== null
                      ? ('object' as const)
                      : ('text' as const),
                }
              : {}),
          }
          p.agents.push(a)
          p.agentCount = p.agents.length
        } else {
          a.status = 'done'
          a.resultKind = event.result.kind
          if (event.result.kind === 'ok') {
            a.outputShape =
              typeof event.result.output === 'object' &&
              event.result.output !== null
                ? 'object'
                : 'text'
          }
        }
        break
      }

• Step 8: 跑测试确认通过

Run: bun test src/workflow/__tests__/progressStore.test.ts Expected: 全部 PASS（含原有用例——它们 meta: null → declaredPhases: []，不破坏）

• Step 9: precheck

Run: bun run precheck Expected: 零错误

• Step 10: Commit（逻辑切分点，实际提交待用户确认）

git add src/workflow/progress/store.ts src/workflow/__tests__/progressStore.test.ts
git commit -m "feat(workflow): store 落地 declaredPhases + agent outputShape"

---

Task 2: 新建 status.ts（状态映射 + agentVisual）

Files:

• Create: src/workflow/panel/status.ts

• Test: src/workflow/__tests__/status.test.ts

• Step 1: 写失败测试 status.test.ts

import { expect, test } from 'bun:test'
import type { AgentProgress, RunProgress } from '../progress/store.js'
import {
  STATUS_DOT,
  RUN_STATUS_COLOR,
  PHASE_MARK,
  PHASE_COLOR,
  agentVisual,
} from '../panel/status.js'

test('STATUS_DOT / RUN_STATUS_COLOR 覆盖四种 run 状态且为非空字符', () => {
  const statuses: RunProgress['status'][] = ['running', 'completed', 'failed', 'killed']
  for (const s of statuses) {
    expect(STATUS_DOT[s].length).toBeGreaterThan(0)
    expect(RUN_STATUS_COLOR[s]).toBeTruthy()
  }
  expect(STATUS_DOT.running).toBe('●')
  expect(STATUS_DOT.completed).toBe('✓')
  expect(STATUS_DOT.failed).toBe('✗')
  expect(STATUS_DOT.killed).toBe('■')
})

test('PHASE_MARK / PHASE_COLOR 覆盖 running/done/pending', () => {
  expect(PHASE_MARK.running).toBe('●')
  expect(PHASE_MARK.done).toBe('✓')
  expect(PHASE_MARK.pending).toBe('○')
  expect(PHASE_COLOR.pending).toBe('subtle')
})

test('agentVisual：running → ● warning running', () => {
  const a: AgentProgress = { id: 1, status: 'running' }
  expect(agentVisual(a)).toEqual({ mark: '●', color: 'warning', suffix: 'running' })
})

test('agentVisual：done·object → ✓ success object', () => {
  const a: AgentProgress = { id: 1, status: 'done', resultKind: 'ok', outputShape: 'object' }
  expect(agentVisual(a)).toEqual({ mark: '✓', color: 'success', suffix: 'object' })
})

test('agentVisual：done·text → ✓ success text', () => {
  const a: AgentProgress = { id: 1, status: 'done', resultKind: 'ok', outputShape: 'text' }
  expect(agentVisual(a)).toEqual({ mark: '✓', color: 'success', suffix: 'text' })
})

test('agentVisual：dead → ✗ error dead', () => {
  const a: AgentProgress = { id: 1, status: 'done', resultKind: 'dead' }
  expect(agentVisual(a)).toEqual({ mark: '✗', color: 'error', suffix: 'dead' })
})

• Step 2: 跑测试确认失败（模块不存在）

Run: bun test src/workflow/__tests__/status.test.ts Expected: FAIL（无法 import ../panel/status.js）

• Step 3: 创建 src/workflow/panel/status.ts

import type { AgentProgress, RunProgress } from '../progress/store.js'

/** run 状态 → 圆点字符（顶部 tab 用）。 */
export const STATUS_DOT: Record<RunProgress['status'], string> = {
  running: '●',
  completed: '✓',
  failed: '✗',
  killed: '■',
}

/** run 状态 → ink theme 颜色 token（沿用现有 WorkflowList 配色）。 */
export const RUN_STATUS_COLOR: Record<RunProgress['status'], string> = {
  running: 'warning',
  completed: 'success',
  failed: 'error',
  killed: 'subtle',
}

/** phase 在侧栏的合并状态（含 pending：meta 声明但未启动）。 */
export type PhaseStatus = 'running' | 'done' | 'pending'

export const PHASE_MARK: Record<PhaseStatus, string> = {
  running: '●',
  done: '✓',
  pending: '○',
}

export const PHASE_COLOR: Record<PhaseStatus, string> = {
  running: 'warning',
  done: 'success',
  pending: 'subtle',
}

/** agent 行的视觉三件套：标记字符 + 颜色 + 行尾文字后缀。 */
export type AgentVisual = { mark: string; color: string; suffix: string }

/**
 * agent 状态 → 视觉。
 * - running → ● warning
 * - done·dead → ✗ error
 * - done·ok：outputShape='object' → object；否则 text
 */
export function agentVisual(a: AgentProgress): AgentVisual {
  if (a.status === 'running') return { mark: '●', color: 'warning', suffix: 'running' }
  if (a.resultKind === 'dead') return { mark: '✗', color: 'error', suffix: 'dead' }
  return {
    mark: '✓',
    color: 'success',
    suffix: a.outputShape === 'object' ? 'object' : 'text',
  }
}

• Step 4: 跑测试确认通过

Run: bun test src/workflow/__tests__/status.test.ts Expected: 全部 PASS

• Step 5: precheck

Run: bun run precheck Expected: 零错误

• Step 6: Commit（逻辑切分点）

git add src/workflow/panel/status.ts src/workflow/__tests__/status.test.ts
git commit -m "feat(workflow): 抽 panel status.ts 状态映射 + agentVisual"

---

Task 3: 新建 selectors.ts（mergePhases / filterAgentsByPhase / tabLabel）

Files:

• Create: src/workflow/panel/selectors.ts

• Test: src/workflow/__tests__/selectors.test.ts

• Step 1: 写失败测试 selectors.test.ts

import { expect, test } from 'bun:test'
import type { AgentProgress, RunProgress } from '../progress/store.js'
import { ALL_PHASE, mergePhases, filterAgentsByPhase, tabLabel } from '../panel/selectors.js'

function run(partial: Partial<RunProgress>): RunProgress {
  return {
    runId: 'r1',
    workflowName: 'w',
    status: 'running',
    phases: [],
    declaredPhases: [],
    currentPhase: null,
    agents: [],
    agentCount: 0,
    updatedAt: 1,
    ...partial,
  }
}

test('mergePhases：声明顺序优先，实际 phase 追加未声明的，计数 done/total', () => {
  const r = run({
    declaredPhases: ['Find', 'Review', 'Verify'],
    phases: [
      { title: 'Find', status: 'done' },
      { title: 'Review', status: 'running' },
    ],
    agents: [
      { id: 1, phase: 'Find', status: 'done', resultKind: 'ok', outputShape: 'text' },
      { id: 2, phase: 'Find', status: 'done', resultKind: 'dead' },
      { id: 3, phase: 'Review', status: 'running' },
    ],
  })
  expect(mergePhases(r)).toEqual([
    { title: 'Find', status: 'done', done: 2, total: 2 },
    { title: 'Review', status: 'running', done: 0, total: 1 },
    { title: 'Verify', status: 'pending', done: 0, total: 0 },
  ])
})

test('mergePhases：实际出现但未声明的 phase 追加到末尾', () => {
  const r = run({
    declaredPhases: ['Find'],
    phases: [
      { title: 'Find', status: 'done' },
      { title: 'Adhoc', status: 'running' },
    ],
    agents: [],
  })
  expect(mergePhases(r).map(p => p.title)).toEqual(['Find', 'Adhoc'])
})

test('filterAgentsByPhase：All / undefined → 全部；指定 → 仅该 phase', () => {
  const agents: AgentProgress[] = [
    { id: 1, phase: 'A', status: 'running' },
    { id: 2, phase: 'B', status: 'done', resultKind: 'ok', outputShape: 'text' },
  ]
  expect(filterAgentsByPhase(agents, undefined)).toHaveLength(2)
  expect(filterAgentsByPhase(agents, ALL_PHASE)).toHaveLength(2)
  expect(filterAgentsByPhase(agents, 'A')).toEqual([agents[0]])
})

test('tabLabel：workflow 名 + runId 后 4 位短码', () => {
  expect(tabLabel('review-changes', 'wf_abc123def')).toBe('review-changes#3def')
})

• Step 2: 跑测试确认失败

Run: bun test src/workflow/__tests__/selectors.test.ts Expected: FAIL（模块不存在）

• Step 3: 创建 src/workflow/panel/selectors.ts

import type { AgentProgress, RunProgress } from '../progress/store.js'
import type { PhaseStatus } from './status.js'

/** 「不筛选」固定项的 title（侧栏第一行）。 */
export const ALL_PHASE = 'All'

/** 合并后的 phase（含 pending），带该 phase 下 agent 的 done/total 计数。 */
export type MergedPhase = {
  title: string
  status: PhaseStatus
  done: number
  total: number
}

/**
 * 合并 declaredPhases（meta 声明）与 run.phases（实际 running/done）：
 * - 声明顺序优先；未在 declared 但实际出现的 phase 追加末尾。
 * - 实际无记录 → pending；否则取实际 status。
 * - done/total = 该 phase 下 done / 全部 agent 数。
 */
export function mergePhases(run: Pick<RunProgress, 'declaredPhases' | 'phases' | 'agents'>): MergedPhase[] {
  const actualByTitle = new Map(run.phases.map(p => [p.title, p]))
  const seen = new Set<string>()
  const out: MergedPhase[] = []
  const push = (title: string): void => {
    if (seen.has(title)) return
    seen.add(title)
    const actual = actualByTitle.get(title)
    const status: PhaseStatus = !actual ? 'pending' : actual.status
    const inPhase = run.agents.filter(a => a.phase === title)
    out.push({
      title,
      status,
      done: inPhase.filter(a => a.status === 'done').length,
      total: inPhase.length,
    })
  }
  for (const t of run.declaredPhases) push(t)
  for (const p of run.phases) push(p.title)
  return out
}

/**
 * 按选中 phase 筛选 agent。
 * selectedPhase 为 undefined 或 ALL_PHASE → 全部。
 */
export function filterAgentsByPhase(
  agents: AgentProgress[],
  selectedPhase: string | undefined,
): AgentProgress[] {
  if (selectedPhase === undefined || selectedPhase === ALL_PHASE) return agents
  return agents.filter(a => a.phase === selectedPhase)
}

/** tab 标签：workflow 名 + `#` + runId 末 4 位（同名 run 消歧）。 */
export function tabLabel(workflowName: string, runId: string): string {
  return `${workflowName}#${runId.slice(-4)}`
}

• Step 4: 跑测试确认通过

Run: bun test src/workflow/__tests__/selectors.test.ts Expected: 全部 PASS

• Step 5: precheck

Run: bun run precheck Expected: 零错误

• Step 6: 里程碑检查点 —— 向用户确认是否提交 Task 1-3

完成纯逻辑层（store + status + selectors）。按项目约定，此处询问用户是否提交，再进入组件层。

---

Task 4: useWorkflowKeyboard 改焦点模型（抽 routeWorkflowKey 纯函数）

Files:

• Modify: src/workflow/panel/useWorkflowKeyboard.ts（整体改写）

• Test: src/workflow/__tests__/useWorkflowKeyboard.test.ts

• Step 1: 写失败测试 useWorkflowKeyboard.test.ts

import { expect, test } from 'bun:test'
import { routeWorkflowKey } from '../panel/useWorkflowKeyboard.js'

test('Tab → nextTab；Shift+Tab → prevTab', () => {
  expect(routeWorkflowKey('', { tab: true })).toBe('nextTab')
  expect(routeWorkflowKey('', { tab: true, shift: true })).toBe('prevTab')
})

test('q / Esc → quit', () => {
  expect(routeWorkflowKey('q', {})).toBe('quit')
  expect(routeWorkflowKey('', { escape: true })).toBe('quit')
})

test('x → kill；r → resume；n → newRun', () => {
  expect(routeWorkflowKey('x', {})).toBe('kill')
  expect(routeWorkflowKey('r', {})).toBe('resume')
  expect(routeWorkflowKey('n', {})).toBe('newRun')
})

test('←/→ 切焦点列；↑/↓ 列内移动', () => {
  expect(routeWorkflowKey('', { leftArrow: true })).toBe('focusLeft')
  expect(routeWorkflowKey('', { rightArrow: true })).toBe('focusRight')
  expect(routeWorkflowKey('', { upArrow: true })).toBe('moveUp')
  expect(routeWorkflowKey('', { downArrow: true })).toBe('moveDown')
})

test('无关输入 → null', () => {
  expect(routeWorkflowKey('z', {})).toBeNull()
  expect(routeWorkflowKey('', {})).toBeNull()
})

• Step 2: 跑测试确认失败

Run: bun test src/workflow/__tests__/useWorkflowKeyboard.test.ts Expected: FAIL（routeWorkflowKey 不存在）

• Step 3: 整体改写 src/workflow/panel/useWorkflowKeyboard.ts

import { useInput } from '@anthropic/ink'

/** 焦点所在列。 */
export type FocusColumn = 'phases' | 'agents'

/** useInput 的 key 对象子集（仅声明用到的字段，避免耦合 ink Key 类型）。 */
type KeyEvent = {
  tab?: boolean
  shift?: boolean
  escape?: boolean
  leftArrow?: boolean
  rightArrow?: boolean
  upArrow?: boolean
  downArrow?: boolean
}

/** 键 → 动作（纯函数，便于单测；无渲染依赖）。 */
export type WorkflowKeyAction =
  | 'nextTab'
  | 'prevTab'
  | 'focusLeft'
  | 'focusRight'
  | 'moveUp'
  | 'moveDown'
  | 'kill'
  | 'resume'
  | 'newRun'
  | 'quit'

export function routeWorkflowKey(input: string, key: KeyEvent): WorkflowKeyAction | null {
  // @anthropic/ink 的 key.tab 对 Tab 键置 true；个别环境回落到 '\t'
  if (key.tab || input === '\t') return key.shift ? 'prevTab' : 'nextTab'
  if (key.escape || input === 'q') return 'quit'
  if (input === 'x') return 'kill'
  if (input === 'r') return 'resume'
  if (input === 'n') return 'newRun'
  if (key.leftArrow) return 'focusLeft'
  if (key.rightArrow) return 'focusRight'
  if (key.upArrow) return 'moveUp'
  if (key.downArrow) return 'moveDown'
  return null
}

/** 焦点模型回调（WorkflowsPanel 注入）。 */
export type WorkflowKeyboardHandlers = {
  nextTab: () => void
  prevTab: () => void
  focusLeft: () => void
  focusRight: () => void
  moveUp: () => void
  moveDown: () => void
  killFocused: () => void
  resumeFocused: () => void
  newRun: () => void
  quit: () => void
}

/**
 * /workflows 面板键位（焦点轮转模型）：
 * - Tab / Shift+Tab：切顶部 run tab
 * - ← / →：phases ↔ agents 焦点切换
 * - ↑ / ↓：当前焦点列内移动
 * - x kill · r resume · n new · q / Esc quit
 */
export function useWorkflowKeyboard(h: WorkflowKeyboardHandlers): void {
  useInput((input, key) => {
    const action = routeWorkflowKey(input, key as KeyEvent)
    if (action === null) return
    switch (action) {
      case 'nextTab':
        h.nextTab()
        break
      case 'prevTab':
        h.prevTab()
        break
      case 'focusLeft':
        h.focusLeft()
        break
      case 'focusRight':
        h.focusRight()
        break
      case 'moveUp':
        h.moveUp()
        break
      case 'moveDown':
        h.moveDown()
        break
      case 'kill':
        h.killFocused()
        break
      case 'resume':
        h.resumeFocused()
        break
      case 'newRun':
        h.newRun()
        break
      case 'quit':
        h.quit()
        break
    }
  })
}

• Step 4: 跑测试确认通过

Run: bun test src/workflow/__tests__/useWorkflowKeyboard.test.ts Expected: 全部 PASS

• Step 5: precheck

Run: bun run precheck Expected: 零错误

• Step 6: Commit（逻辑切分点）

git add src/workflow/panel/useWorkflowKeyboard.ts src/workflow/__tests__/useWorkflowKeyboard.test.ts
git commit -m "refactor(workflow): 键位改焦点轮转模型 + 抽 routeWorkflowKey"

---

Task 5: 新建三个展示组件 TabsBar / PhaseSidebar / AgentList

这三个是无状态展示组件（props 驱动），不写渲染测试（项目无 ink-testing-library）。靠 tsc + biome 保证类型/格式。

Files:

• Create: src/workflow/panel/TabsBar.tsx

• Create: src/workflow/panel/PhaseSidebar.tsx

• Create: src/workflow/panel/AgentList.tsx

• Step 1: 创建 src/workflow/panel/TabsBar.tsx

import React from 'react';
import { Box, Text } from '@anthropic/ink';
import type { RunProgress } from '../progress/store.js';
import { RUN_STATUS_COLOR, STATUS_DOT } from './status.js';
import { tabLabel } from './selectors.js';

/**
 * 顶部 run tab 行：每个 run 一个 tab（状态点 + 名 + #短码）。
 * 当前 tab 用橙色 ═ 下划线高亮。
 */
export function TabsBar({
  runs,
  activeRunId,
}: {
  runs: RunProgress[];
  activeRunId: string | null;
}): React.ReactNode {
  if (runs.length === 0) {
    return <Text color="subtle">(no runs)</Text>;
  }
  return (
    <Box>
      {runs.map(r => {
        const active = r.runId === activeRunId;
        const label = tabLabel(r.workflowName, r.runId);
        const underline = '═'.repeat(label.length + 2);
        return (
          <Box key={r.runId} flexDirection="column" marginRight={2}>
            <Box>
              <Text color={RUN_STATUS_COLOR[r.status]}>{STATUS_DOT[r.status]}</Text>
              <Text> </Text>
              <Text color={active ? 'claude' : undefined} bold={active}>
                {label}
              </Text>
            </Box>
            <Text color={active ? 'claude' : undefined}>{active ? underline : ''}</Text>
          </Box>
        );
      })}
    </Box>
  );
}

• Step 2: 创建 src/workflow/panel/PhaseSidebar.tsx

import React from 'react';
import { Box, Text } from '@anthropic/ink';
import type { AgentProgress } from '../progress/store.js';
import { PHASE_COLOR, PHASE_MARK } from './status.js';
import { ALL_PHASE, type MergedPhase } from './selectors.js';

/**
 * 左 phase 侧栏：第一行 All（汇总 done/total），其后 merged phases（含 pending ○）。
 * 选中行铺橙底（文字色不变）；selectedIndex=0 表示 All。
 */
export function PhaseSidebar({
  phases,
  agents,
  selectedIndex,
}: {
  phases: MergedPhase[];
  agents: AgentProgress[];
  selectedIndex: number;
}): React.ReactNode {
  const totalAgents = agents.length;
  const doneAgents = agents.filter(a => a.status === 'done').length;
  const allRow = { title: ALL_PHASE, done: doneAgents, total: totalAgents };
  const rows = [allRow, ...phases];

  return (
    <Box flexDirection="column">
      {rows.map((row, i) => {
        const selected = i === selectedIndex;
        const isAll = i === 0;
        const mark = isAll ? ' ' : PHASE_MARK[row.status];
        const color = isAll ? undefined : PHASE_COLOR[row.status];
        const prefix = selected ? '▶' : ' ';
        return (
          <Box key={row.title}>
            <Text backgroundColor={selected ? 'claude' : undefined}>
              {prefix}
              {mark} {row.title.padEnd(10)} {row.done}/{row.total}
            </Text>
          </Box>
        );
      })}
    </Box>
  );
}

• Step 3: 创建 src/workflow/panel/AgentList.tsx

import React from 'react';
import { Box, Text } from '@anthropic/ink';
import type { AgentProgress } from '../progress/store.js';
import { agentVisual } from './status.js';

const LABEL_WIDTH = 18;

/**
 * 右 agent 列表（已按选中 phase 过滤）。
 * 光标行铺橙底；每行：标记 + label + 行尾状态文字（running/object/text/dead）。
 */
export function AgentList({
  agents,
  selectedIndex,
}: {
  agents: AgentProgress[];
  selectedIndex: number;
}): React.ReactNode {
  if (agents.length === 0) {
    return <Text color="subtle">(no agents in this phase)</Text>;
  }
  return (
    <Box flexDirection="column">
      {agents.map((a, i) => {
        const v = agentVisual(a);
        const selected = i === selectedIndex;
        const label = (a.label ?? `agent-${a.id}`).slice(0, LABEL_WIDTH).padEnd(LABEL_WIDTH);
        return (
          <Box key={a.id}>
            <Text backgroundColor={selected ? 'claude' : undefined}>
              <Text color={v.color}>{v.mark}</Text> {label} <Text color="subtle">{v.suffix}</Text>
            </Text>
          </Box>
        );
      })}
    </Box>
  );
}

• Step 4: 类型检查 + lint

Run: bun run precheck Expected: 零错误（三个组件未被引用，tsc 仍编译它们；无 lint 报错）

• Step 5: Commit（逻辑切分点）

git add src/workflow/panel/TabsBar.tsx src/workflow/panel/PhaseSidebar.tsx src/workflow/panel/AgentList.tsx
git commit -m "feat(workflow): 新增 TabsBar/PhaseSidebar/AgentList 展示组件"

---

Task 6: 重写 WorkflowsPanel + 删旧组件 + 修测试 import

Files:

• Modify: src/workflow/panel/WorkflowsPanel.tsx（整体重写）

• Delete: src/workflow/panel/WorkflowList.tsx

• Delete: src/workflow/panel/WorkflowDetail.tsx

• Modify: src/workflow/__tests__/WorkflowsPanel.test.tsx:4（STATUS_DOT import 改源）

• Step 1: 重写 src/workflow/panel/WorkflowsPanel.tsx

import React, { useEffect, useState, useSyncExternalStore } from 'react';
import { Box, Text } from '@anthropic/ink';
import type { LocalJSXCommandContext, LocalJSXCommandOnDone } from '../../types/command.js';
import { getWorkflowService } from '../service.js';
import type { RunProgress } from '../progress/store.js';
import { AgentList } from './AgentList.js';
import { PhaseSidebar } from './PhaseSidebar.js';
import { TabsBar } from './TabsBar.js';
import {
  type FocusColumn,
  type WorkflowKeyboardHandlers,
  useWorkflowKeyboard,
} from './useWorkflowKeyboard.js';
import { ALL_PHASE, filterAgentsByPhase, mergePhases } from './selectors.js';

/**
 * 夹紧选中索引到有效区间（空列表→0；越界→末位；负/NaN→0）。
 * 抽成模块级纯函数：面板内调用 + 单测覆盖同一逻辑，避免行为漂移。
 */
export function clampSelected(selected: number, len: number): number {
  if (len === 0) return 0;
  const n = Math.trunc(selected);
  if (Number.isNaN(n) || n < 0) return 0;
  return Math.min(n, len - 1);
}

/**
 * /workflows 主面板：三区焦点模型（顶 tab + 左 phase 侧栏 + 右 agent 列表）。
 *
 * - useSyncExternalStore 订阅 WorkflowService（store 返回稳定快照，无变更不重渲染）。
 * - 焦点状态：activeRunId / focusColumn('phases'|'agents') / selectedPhaseIndex(0=All) / selectedAgentIndex。
 * - 键位：Tab 切 run · ←/→ 切焦点列 · ↑/↓ 列内移动 · x kill · r resume · q/Esc 退出。
 */
export function WorkflowsPanel({
  onDone,
  context,
}: {
  onDone: LocalJSXCommandOnDone;
  context: LocalJSXCommandContext;
}): React.ReactNode {
  const svc = getWorkflowService();
  const runs = useSyncExternalStore(
    svc.subscribe,
    () => svc.listRuns(),
    () => [],
  );

  const [activeRunId, setActiveRunId] = useState<string | null>(null);
  const [focusColumn, setFocusColumn] = useState<FocusColumn>('phases');
  const [selectedPhaseIndex, setSelectedPhaseIndex] = useState(0);
  const [selectedAgentIndex, setSelectedAgentIndex] = useState(0);

  // runs 变化时：activeRunId 失效（被 kill / 首次）→ 夹紧到首个
  useEffect(() => {
    if (runs.length === 0) {
      if (activeRunId !== null) setActiveRunId(null);
      return;
    }
    if (!runs.some(r => r.runId === activeRunId)) {
      setActiveRunId(runs[0]!.runId);
    }
  }, [runs, activeRunId]);

  const focused: RunProgress | undefined = runs.find(r => r.runId === activeRunId);
  const phases = focused ? mergePhases(focused) : [];
  // 侧栏含 All 行：phases 数组前补一项 → 总行数 = phases.length + 1
  const phaseRowCount = phases.length + 1;
  const clampedPhase = clampSelected(selectedPhaseIndex, phaseRowCount);

  // 选中 phase title（0 = All = undefined）
  const selectedPhaseTitle =
    clampedPhase === 0 ? undefined : phases[clampedPhase - 1]?.title;

  const visibleAgents = focused
    ? filterAgentsByPhase(focused.agents, selectedPhaseTitle)
    : [];
  const clampedAgent = clampSelected(selectedAgentIndex, visibleAgents.length);

  const switchTab = (runId: string): void => {
    setActiveRunId(runId);
    setFocusColumn('phases');
    setSelectedPhaseIndex(0);
    setSelectedAgentIndex(0);
  };

  const nextTab = (): void => {
    if (runs.length === 0) return;
    const idx = runs.findIndex(r => r.runId === activeRunId);
    const next = runs[(idx + 1) % runs.length]!;
    switchTab(next.runId);
  };
  const prevTab = (): void => {
    if (runs.length === 0) return;
    const idx = runs.findIndex(r => r.runId === activeRunId);
    const next = runs[(idx - 1 + runs.length) % runs.length]!;
    switchTab(next.runId);
  };

  const handlers: WorkflowKeyboardHandlers = {
    nextTab,
    prevTab,
    focusLeft: () => setFocusColumn('phases'),
    focusRight: () => setFocusColumn('agents'),
    moveUp: () => {
      if (focusColumn === 'phases')
        setSelectedPhaseIndex(s => clampSelected(s - 1, phaseRowCount));
      else setSelectedAgentIndex(s => clampSelected(s - 1, visibleAgents.length));
    },
    moveDown: () => {
      if (focusColumn === 'phases')
        setSelectedPhaseIndex(s => clampSelected(s + 1, phaseRowCount));
      else setSelectedAgentIndex(s => clampSelected(s + 1, visibleAgents.length));
    },
    killFocused: () => {
      if (focused) svc.kill(focused.runId);
    },
    resumeFocused: () => {
      if (!focused) return;
      const canUseTool = context.canUseTool;
      if (!canUseTool) {
        onDone('resume 需要 canUseTool 上下文，请在主会话中用 /<name> resume 重试。');
        return;
      }
      void svc
        .launch(
          { resumeFromRunId: focused.runId, name: focused.workflowName },
          context,
          canUseTool,
        )
        .catch(e => onDone(`resume 失败：${(e as Error).message}`));
    },
    newRun: () =>
      onDone('Tip: 用 /<name> 启动命名 workflow，或通过 Workflow 工具带 name 参数。'),
    quit: () => onDone(),
  };
  useWorkflowKeyboard(handlers);

  const running = runs.filter(r => r.status === 'running').length;
  const done = runs.length - running;
  const phaseHeader = selectedPhaseTitle ?? ALL_PHASE;

  return (
    <Box flexDirection="column" borderStyle="round" borderColor="claude" paddingX={1}>
      <Box justifyContent="space-between">
        <Text bold>Workflows</Text>
        <Text color="subtle">
          {running} running · {done} done
        </Text>
      </Box>

      <Box marginTop={1}>
        <TabsBar runs={runs} activeRunId={activeRunId} />
      </Box>

      <Box flexDirection="row" marginTop={1}>
        <Box width="25%" flexDirection="column">
          <Text color={focusColumn === 'phases' ? 'claude' : 'subtle'} bold>
            PHASES
          </Text>
          <PhaseSidebar
            phases={phases}
            agents={focused?.agents ?? []}
            selectedIndex={clampedPhase}
          />
        </Box>
        <Text color="subtle">│</Text>
        <Box flexGrow={1} flexDirection="column">
          <Text color={focusColumn === 'agents' ? 'claude' : 'subtle'} bold>
            AGENTS · {phaseHeader}
          </Text>
          <AgentList agents={visibleAgents} selectedIndex={clampedAgent} />
        </Box>
      </Box>

      <Box marginTop={1}>
        <Text color="subtle">
          Tab 切 run · ←/→ 切焦点 · ↑/↓ 移动 · x kill · r resume · q quit
        </Text>
      </Box>
    </Box>
  );
}

• Step 2: 删除旧组件

Run:

rm src/workflow/panel/WorkflowList.tsx src/workflow/panel/WorkflowDetail.tsx

• Step 3: 修 WorkflowsPanel.test.tsx 的 import（第 2-4 行）

把：

import type { RunProgress } from '../progress/store.js';
import { clampSelected } from '../panel/WorkflowsPanel.js';
import { STATUS_DOT } from '../panel/WorkflowList.js';

改为：

import type { RunProgress } from '../progress/store.js';
import { clampSelected } from '../panel/WorkflowsPanel.js';
import { STATUS_DOT } from '../panel/status.js';

• Step 4: 更新 WorkflowsPanel.test.tsx 的 RunProgress 字段契约用例（第 28-47 行）

旧用例构造 RunProgress 时缺 declaredPhases，tsc 会报错。补字段：

把第 29-38 行的 const run: RunProgress = { ... } 改为：

  const run: RunProgress = {
    runId: 'r1',
    workflowName: 'review',
    status: 'running',
    phases: [{ title: 'Find', status: 'done' }],
    declaredPhases: ['Find', 'Review'],
    currentPhase: 'Review',
    agents: [{ id: 1, label: 'review:api', phase: 'Review', status: 'running' }],
    agentCount: 1,
    updatedAt: 1,
  };

同样补第 51-61 行（completed）和第 62-72 行（failed）的 declaredPhases: []。

• Step 5: precheck

Run: bun run precheck Expected: 零错误。重点核对：

• STATUS_DOT import 已切到 status.js，无悬空引用。

• WorkflowList.tsx / WorkflowDetail.tsx 删除后无残留 import（grep 已确认仅 WorkflowsPanel 与 test 引用，均已处理）。

• clampSelected 契约测试仍绿。

• Step 6: Commit（逻辑切分点）

git add -A src/workflow/panel/ src/workflow/__tests__/WorkflowsPanel.test.tsx
git commit -m "refactor(workflow): WorkflowsPanel 重写为三区焦点模型 + 删旧双栏组件"

---

Task 7: 文档更新 + 全量 precheck

Files:

• Modify: docs/features/workflow-scripts.md:138-148（§六）

• Step 1: 更新 docs/features/workflow-scripts.md §六

把第 138-148 行（§六「监控面板：/workflows」整段）替换为：

## 六、监控面板：`/workflows`

`/workflows` 打开三区焦点面板（local-jsx，全屏）：

- **顶部 tabs**：每个 run 一个 tab（状态圆点 + workflow 名 + `#runId短码`）；同名脚本多次跑会多个 tab。
- **左 phase 侧栏**：`All` + 合并 meta 声明的 phase（未启动 `○` pending 灰）与实际 phase（`●` running / `✓` done）；选中即决定右栏筛选。
- **右 agent 列表**：按选中 phase 过滤；状态色 + 行尾文字（`running` / `object` / `text` / `dead`）。

**键位**：`Tab`/`Shift+Tab` 切 run · `←`/`→` 切左右焦点列（phases ↔ agents）· `↑`/`↓` 列内移动 · `r` resume · `x` kill · `n` 新建提示 · `q`/`Esc` 退出。

**视觉**：无内框，左右一条竖线分隔；聚焦列标题橙粗；选中/光标行铺橙底（`backgroundColor`），文字色不变。

进度按引擎 `agentId` 精确关联 `agent_done`（解决并发 LIFO 竞态）。pending phase 来自 `run_started` 事件携带的 `meta.phases`，store 落地 `declaredPhases`，面板 `mergePhases` 合并。`useSyncExternalStore` 订阅 `WorkflowService`，稳定快照，无变更不重渲染。

• Step 2: 全量 precheck

Run: bun run precheck Expected: 零错误（typecheck + lint:fix + 全量 test）

• Step 3: 里程碑检查点 —— 向用户确认是否提交 Task 4-7

组件层 + 文档完成。按项目约定，此处询问用户是否提交。

---

Self-Review（计划作者已完成）

1. Spec coverage — 对照 spec 各节：

• §4 数据模型（declaredPhases）→ Task 1 ✓
• §4 gap 补充（outputShape，为 §8 object 标记服务）→ Task 1 ✓
• §5/§8 视觉（tab/phase/agent 状态映射 + agentVisual）→ Task 2 ✓
• §6 焦点状态机 + 筛选语义 + tabLabel → Task 3（selectors）+ Task 6（WorkflowsPanel 状态）✓
• §6 键位表 → Task 4（routeWorkflowKey + handlers）✓
• §7 组件拆分（TabsBar/PhaseSidebar/AgentList/status/selectors）→ Task 2/3/5 ✓
• §7 删 WorkflowList/WorkflowDetail + 修 test import → Task 6 ✓
• §9 测试（纯函数 TDD，无 ink-testing-library）→ Task 1-4 ✓
• §10 里程碑 M1-M4 → Task 1(M1) / 2-3(M2 纯逻辑) / 4-6(M2 组件) / 7(M3 测试+M4 文档) ✓

2. Placeholder scan — 无 TBD/TODO/"add error handling"/"similar to"。每个代码步给完整代码。

3. Type consistency —

• MergedPhase（selectors.ts 定义）在 PhaseSidebar.tsx 引用一致 ✓
• AgentVisual / agentVisual（status.ts）在 AgentList.tsx 引用一致 ✓
• FocusColumn / WorkflowKeyboardHandlers（useWorkflowKeyboard.ts）在 WorkflowsPanel.tsx 引用一致 ✓
• declaredPhases / outputShape 在 store.ts 定义、selectors.test/WorkflowsPanel.test 构造一致 ✓
• ALL_PHASE 常量在 selectors.ts 定义、PhaseSidebar/WorkflowsPanel 引用一致 ✓
• routeWorkflowKey 返回的 action union 与 handlers 方法名一一对应 ✓

---

Execution Handoff

Plan complete and saved to docs/superpowers/plans/2026-06-13-workflow-panel-redesign.md. Two execution options:

1. Subagent-Driven (recommended) — 每个 Task 派一个新 subagent，Task 间做 spec/quality 两段 review，迭代快。

2. Inline Execution — 在本会话按 Task 顺序执行，批次推进、检查点停下 review。

两种方式都遵循项目约定：git commit 仅在你明确要求时执行（Task 末尾的 commit step 是逻辑切分点，默认不自动提交，里程碑末尾统一问你）。

选哪种？