claude-code/docs/superpowers/specs/2026-06-14-effort-panel-design.md

Effort 交互面板（EffortPanel）设计

日期: 2026-06-14 作者: brainstorming session 产物 状态: 待实施 关联: src/commands/effort/、src/utils/effort.ts、src/components/EffortPanel/（新增）

---

1. 概述

把当前的 /effort slash 命令从纯文本式交互升级为终端内的可视化选择面板。

• 触发：/effort（无参）打开面板；/effort <level> 直跳路径保留
• 视觉：横向 slider，两端标 Faster / Smarter，刻度为 low / medium / high / xhigh / max / ultracode
• 交互：←/→ 移动光标，Enter 确认，Esc 取消
• ultracode 仅作视觉占位，确认后提示用户走 /ultracode <context> 启动
• 第二阶段加波纹动画（详见 §6）

2. 用户故事

• 作为开发者，我希望按 /effort 就能可视化地选择努力等级，而不用记 5 个枚举值
• 作为高频用户，我希望 /effort high 这种直跳仍可用，避免脚本/习惯被打断
• 作为设置了 CLAUDE_CODE_EFFORT_LEVEL 的用户，我希望面板提示我"env 优先级更高"，而不是默默忽略我的选择
• 作为想试 ultracode 的用户，我希望面板让我知道这个"档位"存在，但落地要走它自己的命令

3. 不在本期范围

• 不修改 EffortValue / EffortLevel 类型
• 不修改 src/utils/effort.ts 的任何纯函数
• 不新增专用全局热键（仅通过 /effort 触发）
• 不在面板里包含 auto 选项（仍走 /effort auto）
• 不真正"启用 ultracode"——面板对 ultracode 仅作视觉提示与文案引导

4. 架构与文件结构

src/
├── commands/effort/
│   ├── effort.tsx              ← 改造：call() 在 args 为空时返回 <EffortPanel>，
│   │                              有参时维持原 executeEffort() 路径
│   └── index.ts                ← 不变
├── components/EffortPanel/
│   ├── EffortPanel.tsx         ← 新增：面板主体（渲染 + 键盘交互 + onDone 通道）
│   ├── effortPanelState.ts     ← 新增：纯函数 reducer（移动光标、确定选项），
│   │                              抽离便于单测
│   └── __tests__/
│       ├── EffortPanel.test.tsx        ← 渲染 / 键盘交互 / env 警告 / ultracode 提示
│       └── effortPanelState.test.ts    ← reducer 纯函数测试

复用清单（不重写）

• executeEffort() / setEffortValue() / unsetEffortLevel()：留在 effort.tsx，面板确认时调用
• EFFORT_LEVELS / getDisplayedEffortLevel() / getEffortEnvOverride() / getEffortValueDescription() / modelSupportsEffort()：从 src/utils/effort.ts 直接 import
• useInput 或 useKeyboard：从 @anthropic/ink 取
• <ApplyEffortAndClose> 组件：作为面板 Enter 后的"写入并退出"流程组件复用（或迁入 EffortPanel 内部）

类型层面

不动 EffortValue / EffortLevel。面板内部用一个新类型 PanelPosition 表示光标位置：

type PanelPosition = 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'ultracode';

它仅在面板内部使用，不进入 AppState、不进入 settings.json、不参与 API 调用。

5. 交互流程

触发与初始光标

/effort<回车>（无参）
  → call() 检测 args === ''
  → 渲染 <EffortPanel onDone={onDone} appStateEffort={effortValue} model={model} />
  → 光标初始位置：
       env override 存在时 → env 设定的档位（让用户立刻看到生效值）
       否则 → getDisplayedEffortLevel(model, appStateEffort)

状态机

状态：{ cursor: PanelPosition }

事件：
  ← (ArrowLeft)    → cursor 左移一位（low 处不左移，保持 low）
  → (ArrowRight)   → cursor 右移一位（ultracode 处不右移，保持 ultracode）
  Home / h         → cursor = low
  End / l          → cursor = ultracode
  Enter            → 确认分支（见下）
  Esc / Ctrl+C / q → 取消，onDone("Effort unchanged.")

确认后的两条分支

分支 A：cursor ∈ {low, medium, high, xhigh, max}

调 executeEffort(cursor)
  → setEffortValue 写 settings + AppState
  → 拿到 result.message
onDone(result.message)

（与现有 /effort high 完全一致的消息体例，含 env override 警告）

分支 B：cursor === 'ultracode'

不调 executeEffort
onDone("ultracode 不是 effort 档位。请使用 /ultracode <context> 启动多 agent workflow。")

取消路径

不调 executeEffort、不写 AppState、不写 settings。onDone("Effort unchanged.")。

不变路径（仍走原 effort.tsx 逻辑）

• /effort low|medium|high|xhigh|max：直跳
• /effort auto|unset：unsetEffortLevel
• /effort help|-h|--help：help 文本
• /effort current|status：ShowCurrentEffort

焦点与键盘独占

面板挂载时通过 Ink useInput 抢占键盘；卸载时自动释放（与 AskUserQuestionPermissionRequest 一致）。

6. 视觉布局

基本形态（无 env override）

Effort

       Faster                                                          Smarter
       ─────────────────────────▲──────────────────────────────────────────────
       low        medium       high       xhigh        max        ultracode
                                                      xhigh + workflows

       ←/→ adjust · Enter confirm · Esc cancel

视觉规则

元素	规则
▲ 光标	跟随 cursor 状态移动，永远指向当前 cursor 位置
当前生效档位（active）	当 cursor ≠ active 时，active 档渲染为加粗 + 旁标 (active)；当 cursor === active 时只显示 ▲，避免双标记
ultracode 副标签	固定字符串 xhigh + workflows，dim 色
两极文字 Faster / Smarter	与面板等宽左右对齐；中间用一行 ─ 填充
底栏提示	←/→ adjust · Enter confirm · Esc cancel，dim 色
标题 Effort	加粗，居中或左对齐

双标记渲染（cursor ≠ active）

env override 时会出现，例如：

Effort
⚠ CLAUDE_CODE_EFFORT_LEVEL=high overrides this session

       Faster                                                          Smarter
       ────────────────────────▲────────────────────────▲──────────────────────
       low        medium      (high) active   xhigh        max        ultracode
                                                      xhigh + workflows

       ←/→ adjust · Enter confirm · Esc cancel

• ▲ 上方：cursor 位置（xhigh）
• (high) active：env 锁定的真实生效档位

两个标记视觉上必须区分：cursor 用三角符号，active 用括号文字 + 颜色。

模型不支持 effort 时（modelSupportsEffort(model) === false）

Effort

  当前模型 <model> 不支持 effort 参数。面板已禁用。

       Faster                                                          Smarter
       ────────────────────────────────────────────────────────────────────────
       low        medium       high       xhigh        max        ultracode

       Esc to close

光标不显示，左右键无效，Enter 无效，只能 Esc 退出。

终端窄屏（< 60 cols）适配

简化策略：宽度 < 60 时退化为垂直列表，每档一行；否则保持横向 slider。这一项不阻塞首版，先按横向渲染，必要时溢出，后续看实际效果再调。

7. 背景波纹动画（第二阶段，单独 commit）

触发条件

仅在 cursor 停在 ultracode 时启动波纹；移开时立即停止（不淡出，干脆）。常态零干扰。

视觉概念

ultracode 是面板的"能量溢出口"。波纹从 ultracode 字符位置（右下区域）为震源，向左/向上辐射同心圆波，铺满整个面板的留白区域（文字字符之间的空隙、─ 分隔线的空白段）。文字层永远清晰可读。

字符集（强度 → 字符）

强度	字符
0.0	(空格)
0.1	·
0.3	∙
0.5	░
0.7	▒
0.9	▓
波峰	~ → ◌ → ○ → ◑ → ● 循环

波纹数学

对每个字符格:
  dx = x - sourceX
  dy = (y - sourceY) * 1.5
  dist = sqrt(dx*dx + dy*dy)
  
  phase = dist * 0.4 - time * 0.012
  wave = sin(phase)
  falloff = max(0, 1 - dist / 40)
  intensity = max(0, wave) * falloff
  
  if (dist < 6):    // 震源附近高频涟漪
    intensity = max(intensity, 0.5 + 0.5 * sin(time * 0.02 - dist * 1.2))
  
  char = pick(intensity)

参数上线后调。

渲染策略（双层不冲突）

Ink 不支持真正的 z-index 层叠，用字符替换模拟：

1. 每帧生成 height × width 字符矩阵（背景层）
2. 渲染每个面板行时，先取该行对应的波纹字符序列，然后在文字字符应该出现的位置覆盖背景字符
3. 文字字符永远胜出，波纹只占空隙

实现位置

新增（第二阶段）：

• src/components/EffortPanel/rippleAnimation.ts — pickChar / computeRippleLine / mergeLayers 纯函数
• src/components/EffortPanel/useRippleFrame.ts — hook，内部调 useAnimationFrame(60) 返回当前帧矩阵
• 在 EffortPanel.tsx 的 render 中叠加（仅 cursor === 'ultracode' 时启用）

性能预算

• 面板 80×10 = 800 格，每帧 800 次 sin/sqrt ≈ 0.05ms
• Ink 重绘 10 行 <Text> 节点，与现有 Spinner 同量级
• 帧率 16fps，useAnimationFrame 自带 viewport 不可见暂停 + 失焦减速

风险与对策

风险	对策
波纹干扰文字可读性	文字字符覆盖背景字符，永远胜出；波纹颜色用 theme.textDisabled
终端窄屏 < 60 cols	sourceX 跟随 ultracode 实际位置；窄屏时降级为单行波纹
性能（旧机器）	useAnimationFrame 已自带暂停/减速
测试稳定性	字符选择是纯函数，可固定 time 注入做帧快照测试

8. 数据流

状态来源

┌─────────────────────────────────────────────────┐
│ src/state/AppState.tsx                          │
│   effortValue: EffortValue | undefined          │
└─────────────────────────────────────────────────┘
              ▲
              │ useAppState(s => s.effortValue)
              │
┌─────────────────────────────────────────────────┐
│ EffortPanel.tsx                                 │
│   props: appStateEffort, model, onDone          │
│   local: cursor: PanelPosition                  │
└─────────────────────────────────────────────────┘
              │
              │ Enter 确认
              ▼
┌─────────────────────────────────────────────────┐
│ executeEffort(cursor)                           │
│   → updateSettingsForSource('userSettings', …)  │
│   → logEvent('tengu_effort_command', …)         │
│   → 返回 { message, effortUpdate? }             │
└─────────────────────────────────────────────────┘
              │
              │ <ApplyEffortAndClose> setAppState(...)
              ▼
┌─────────────────────────────────────────────────┐
│ onDone(result.message)                          │
│   → REPL 渲染 assistant 消息                    │
└─────────────────────────────────────────────────┘

优先级链（不修改）

env CLAUDE_CODE_EFFORT_LEVEL  >  AppState.effortValue  >  model default

面板只写 AppState + settings.json，不直接操作 env。env 存在时，面板可操作但顶部警告（详见 §6 双标记）。

9. 边界与错误处理

场景	行为
模型不支持 effort	面板挂载但禁用，文字提示 + 仅允许 Esc（详见 §6）
env override 设定	顶部加黄色警告行 ⚠ CLAUDE_CODE_EFFORT_LEVEL=<value> overrides this session；光标可移动；Enter 仍写 settings 但顶部警告解释生效值不变
cursor === 'ultracode' 时 Enter	走分支 B，输出引导文案，不调 executeEffort
settings 写入失败（磁盘满/权限）	executeEffort 现有错误路径会返回 result.error，面板沿用，onDone 输出错误消息
终端窄屏 < 60 cols	退化为垂直列表，不阻塞首版
用户按 Ctrl+C 之外的中断信号	视同 Esc，onDone("Effort unchanged.")
面板挂载后 AppState 被外部改变（如 /model 切换）	cursor 不订阅 active 变化，挂载时计算一次初始值后只跟随用户操作。若用户切了 model 想看新档位，关掉面板重开即可。简化实现，行为可预测

10. 测试计划

纯函数（effortPanelState.test.ts）

• moveLeft(cursor) 在 low 处保持 low
• moveRight(cursor) 在 ultracode 处保持 ultracode
• home(cursor) / end(cursor) 边界
• getInitialCursor(appStateEffort, envOverride, model) 优先级
• isUltracode(cursor) 守卫

组件（EffortPanel.test.tsx）

渲染：

• 无 env 时显示基本形态
• env override 时顶部警告 + 双标记
• 模型不支持时禁用面板
• ultracode 副标签 xhigh + workflows 出现

键盘：

• ← 移动光标、→ 移动光标、Home/End 跳转
• Enter 在普通档位 → 调用 executeEffort、onDone 收到正确 message
• Enter 在 ultracode → 不调 executeEffort、onDone 收到引导文案
• Esc → 不调 executeEffort、onDone 收到 "Effort unchanged."

集成（effort.tsx 的 call 函数）：

• 无参 → 返回 <EffortPanel> JSX
• 有参 → 不渲染面板，走 executeEffort

波纹相关（第二阶段）

• pickChar(intensity) 各强度边界
• computeRippleLine 固定 time 快照
• mergeLayers 文字覆盖背景、文字字符永远胜出
• useRippleFrame 仅在 cursor === 'ultracode' 时订阅时钟

11. 实现阶段划分（两个 commit）

Commit 1：基础面板（先做）

• 新增 src/components/EffortPanel/EffortPanel.tsx
• 新增 src/components/EffortPanel/effortPanelState.ts
• 新增 src/components/EffortPanel/__tests__/EffortPanel.test.tsx
• 新增 src/components/EffortPanel/__tests__/effortPanelState.test.ts
• 改造 src/commands/effort/effort.tsx：无参时返回 <EffortPanel>，有参维持原状
• 运行 bun run precheck，必须零错误通过
• commit message: feat(effort): /effort 无参时打开横向 slider 选择面板

Commit 2：波纹动画（基础稳定后再做）

• 新增 src/components/EffortPanel/rippleAnimation.ts
• 新增 src/components/EffortPanel/useRippleFrame.ts
• 新增对应测试
• 在 EffortPanel.tsx 中叠加渲染（仅 cursor === 'ultracode' 时）
• 运行 bun run precheck
• commit message: feat(effort): ultracode 档位铺满波纹背景动画

两阶段切开的好处：动画是创意工作，可能在调参上反复；基础功能稳定后即使动画翻车也能直接 revert 第二个 commit，不影响主功能。

12. 验收清单

• /effort 无参打开面板，光标停在当前生效档
• ←/→ 移动光标，到边界不再继续
• Enter 在 5 档之一时写 settings + AppState + 输出与 /effort X 同款消息
• Enter 在 ultracode 时输出引导文案，不写任何状态
• Esc 时不写任何状态，输出 "Effort unchanged."
• env override 时顶部警告 + 双标记
• 模型不支持时面板禁用，仅 Esc 可退出
• /effort low|auto|help|current 等原有路径行为不变
• bun run precheck 零错误