|
| 1 | +--- |
| 2 | +title: "RexCli TUI 重构:基于 React Ink 的现代终端交互" |
| 3 | +description: "RexCli 把 TUI 安装程序从手动字符串渲染迁移到 React Ink + Ink UI 组件架构,提升交互体验和代码可维护性。" |
| 4 | +date: 2026-04-02 |
| 5 | +tags: [RexCli, TUI, Ink, React, Terminal, Onboarding] |
| 6 | +--- |
| 7 | + |
| 8 | +# RexCli TUI 重构:基于 React Ink 的现代终端交互 |
| 9 | + |
| 10 | +之前的 TUI 安装程序用手动字符串拼接来渲染界面,代码维护成本高,交互体验也比较基础。这次重构把它迁移到 **React Ink + Ink UI** 组件架构,让终端交互更现代化。 |
| 11 | + |
| 12 | +## 为什么要重构 |
| 13 | + |
| 14 | +旧的 TUI 实现有几个问题: |
| 15 | + |
| 16 | +- 手动拼接 ANSI 字符串来控制颜色、布局,改动一处很容易影响其他地方 |
| 17 | +- 缺少真正的组件抽象,状态管理分散在各处 |
| 18 | +- 没有路由概念,屏幕切换逻辑写得很散乱 |
| 19 | + |
| 20 | +Ink 是专为终端设计的 React 渲染器,能用 React 组件模型来写 CLI 交互界面。配合 Ink UI 的内置组件(Select、TextInput、ConfirmInput),可以大大简化开发。 |
| 21 | + |
| 22 | +## 新架构 |
| 23 | + |
| 24 | +``` |
| 25 | +scripts/lib/tui-ink/ |
| 26 | +├── App.tsx # MemoryRouter + Routes 配置 |
| 27 | +├── index.tsx # render() 入口 |
| 28 | +├── hooks/ |
| 29 | +│ └── useSetupOptions.ts # 共享配置状态 |
| 30 | +├── screens/ |
| 31 | +│ ├── MainScreen.tsx # 主菜单 |
| 32 | +│ ├── SetupScreen.tsx # Setup 配置 |
| 33 | +│ ├── UpdateScreen.tsx # Update 配置 |
| 34 | +│ ├── UninstallScreen.tsx # Uninstall 配置 |
| 35 | +│ ├── DoctorScreen.tsx # Doctor 配置 |
| 36 | +│ ├── SkillPickerScreen.tsx # 技能选择器 |
| 37 | +│ └── ConfirmScreen.tsx # 执行确认 |
| 38 | +├── components/ |
| 39 | +│ ├── Header.tsx # 顶部标题栏 |
| 40 | +│ ├── Footer.tsx # 底部快捷键提示 |
| 41 | +│ ├── Checkbox.tsx # 勾选组件 |
| 42 | +│ └── ScrollableSelect.tsx # 滚动选择列表 |
| 43 | +└── types.ts # 共享类型定义 |
| 44 | +``` |
| 45 | + |
| 46 | +### 路由导航 |
| 47 | + |
| 48 | +使用 `react-router` 的 `MemoryRouter` 来管理屏幕切换: |
| 49 | + |
| 50 | +``` |
| 51 | +/ (MainScreen) |
| 52 | + → /setup |
| 53 | + → /update |
| 54 | + → /uninstall |
| 55 | + → /doctor |
| 56 | +
|
| 57 | +/setup → /skill-picker?owner=setup |
| 58 | +/setup → /confirm?action=setup |
| 59 | +
|
| 60 | +/skill-picker → 返回上一屏 |
| 61 | +/confirm → 执行 → 显示结果 → 返回主菜单 |
| 62 | +``` |
| 63 | + |
| 64 | +### 状态管理 |
| 65 | + |
| 66 | +`useSetupOptions` hook 提供全局配置状态,各屏幕共享: |
| 67 | + |
| 68 | +```typescript |
| 69 | +interface SetupOptions { |
| 70 | + components: { |
| 71 | + browser: boolean; |
| 72 | + shell: boolean; |
| 73 | + skills: boolean; |
| 74 | + superpowers: boolean; |
| 75 | + }; |
| 76 | + wrapMode: 'all' | 'repo-only' | 'opt-in' | 'off'; |
| 77 | + scope: 'global' | 'project'; |
| 78 | + client: 'all' | 'codex' | 'claude' | 'gemini' | 'opencode'; |
| 79 | + selectedSkills: string[]; |
| 80 | +} |
| 81 | +``` |
| 82 | + |
| 83 | +### 自定义组件 |
| 84 | + |
| 85 | +Ink UI 的 Select 不支持滚动窗口模式,所以自己实现了 `ScrollableSelect`: |
| 86 | + |
| 87 | +- 键盘 ↑/↓ 导航 |
| 88 | +- Space 选择 |
| 89 | +- 支持分组显示(Core / Optional) |
| 90 | +- 显示技能描述和已安装标记 |
| 91 | + |
| 92 | +## 依赖 |
| 93 | + |
| 94 | +```bash |
| 95 | +npm install ink @inkjs/ui react react-router |
| 96 | +``` |
| 97 | + |
| 98 | +- `ink` 4.x - React 终端渲染器 |
| 99 | +- `@inkjs/ui` - 内置交互组件 |
| 100 | +- `react` 18.x + `react-router` 7.x |
| 101 | + |
| 102 | +Node 版本:项目要求 `>=22 <23`,Ink 4.x 支持 Node 18+,完全兼容。 |
| 103 | + |
| 104 | +## 视觉效果 |
| 105 | + |
| 106 | +- 当前项:粗体 + cyan 颜色 |
| 107 | +- 已安装标记:绿色 `(installed)` |
| 108 | +- 描述文字:灰色 `dimColor` |
| 109 | +- 分组标题:黄色或 inverse |
| 110 | +- 错误/成功:红色/绿色 |
| 111 | + |
| 112 | +## 兼容性 |
| 113 | + |
| 114 | +非交互模式(无 TTY)保持原有 CLI 参数模式不变: |
| 115 | + |
| 116 | +```bash |
| 117 | +aios setup --components browser,shell --scope global |
| 118 | +aios update --client codex |
| 119 | +aios doctor |
| 120 | +``` |
| 121 | + |
| 122 | +入口检测 TTY 后自动调用 Ink 版本。 |
| 123 | + |
| 124 | +## 相关链接 |
| 125 | + |
| 126 | +- Ink 文档:<https://github.com/vadimdemedes/ink> |
| 127 | +- Ink UI 文档:<https://github.com/vadimdemedes/ink-ui> |
| 128 | +- 设计文档:`docs/superpowers/specs/2026-04-02-ink-tui-design.md` |
| 129 | +- 实现计划:`docs/superpowers/plans/2026-04-02-ink-tui-refactor.md` |
0 commit comments