SuperAPI AI 工具集

ink-tui

编程与开发

查看项目

更新于 11-06 03:07

技能介绍

用途

ink-tui 面向 Node.js/TypeScript 命令行工具,帮助开发者用 Ink(React for CLIs)和 @inkjs/ui 构建可交互的终端界面。资料中明确适用的场景包括:多步骤 CLI 安装或配置向导、响应式且由会话状态驱动的终端界面、为 CLI 添加实时进度/加载指示/状态展示,以及任何需要比顺序问答更丰富的 Node.js/TypeScript CLI。

主要能力与架构

该技能采用响应式、会话驱动的模式:渲染出的屏幕是会话状态的纯函数。业务逻辑通过 store setter 设置状态,路由器推导应激活哪个屏幕,不通过命令式方式推送屏幕。关键组成:

  • WizardSession(src/lib/wizard-session.ts):所有向导决策的唯一事实来源。
  • WizardRouter(src/ui/tui/router.ts):声明式流程管线,每个屏幕带 isComplete 谓词。
  • WizardStore(src/ui/tui/store.ts):基于 nanostores 的响应式 store,提供显式 setter,通过 useSyncExternalStore 触发 React 重渲染。
  • WizardUI(src/ui/wizard-ui.ts):连接业务逻辑与 store 的接口,由 InkUI(TUI)和 LoggingUI(CI)实现。
  • 屏幕注册表(src/ui/tui/screen-registry.tsx):把屏幕名映射到组件的工厂函数,App.tsx 保持不变。
  • 服务(src/ui/tui/services/):通过 props 注入屏幕,React 组件内不做动态导入。
  • 覆盖层:用于中断栈的中断/错误模态框,与流程正交。

使用方式

新增屏幕的固定步骤:在 src/ui/tui/screens/ 创建组件;在 router.ts 的 Screen 枚举中添加;在 flow 数组中加入带 isComplete 谓词的 FlowEntry;在 screen-registry.tsx 注册。其他文件无需改动。

新增 store 状态有两种模式:会话状态(影响屏幕解析)需在 WizardSession 加字段、在 WizardStore 加调用 emitChange() 的 setter、在 WizardUI 接口及两个实现中加方法;观察状态(仅展示,如智能体进度)需在 WizardStore 加私有 atom、加 getter/setter,并在 WizardUI 接口及两个实现中加方法。

布局原语位于 src/ui/tui/primitives/,应优先复用而非从零搭建,统一从 index.ts 桶导出;共享样式常量(Colors、Icons、HAlign、VAlign)在 src/ui/tui/styles.ts。可运行 pnpm try --playground 查看所有原语效果。

状态比较统一使用 TypeScript 枚举,避免字符串字面量,如 Screen、Overlay、Flow(router.ts),RunPhase、OutroKind(wizard-session.ts),TaskStatus(wizard-ui.ts)。

依赖与渲染模型

关键依赖:ink(核心,终端 React 渲染器,使用 Yoga 实现 Flexbox)、react(peer 依赖)、@inkjs/ui(官方组件库,含 Select、TextInput、Spinner、ProgressBar、ConfirmInput、MultiSelect、Badge、StatusMessage、Alert、OrderedList、UnorderedList)、figures(跨平台 Unicode/ASCII 符号回退)。资料明确不应使用旧的独立包 ink-text-input、ink-select-input、ink-spinner,@inkjs/ui 已取代它们。

Ink 使用类似 react-dom 的模型:每个 <Box> 是 flex 容器,所有可见文本必须放在 <Text> 内;样式通过 <Box> 和 <Text> 的 props 设置;交互用 useInput();终端宽度用 useStdout().stdout.columns;滚动用 <Box overflow="hidden"> 加手动偏移;默认 flexDirection 为横向,纵向需显式设置。

终端兼容与限制

技能给出终端兼容实践:小终端需检查 useStdout().stdout.columns 和 rows;检测到 !process.stdin.isTTY 时回退到 LoggingUI;CI 环境用 --ci 标志走 LoggingUI(无 TUI、无提示);start-tui.ts 通过 ANSI 转义码强制黑色背景;纯黑文字使用 color="#000000" 而非 color="black"(终端把 ANSI 黑色渲染为灰色);Ctrl+C 由 Ink 通过 useApp().exit() 处理。

参考文件包括 references/ARCHITECTURE.md(响应式架构)、PRIMITIVES.md(布局原语目录)、INK-API.md(Ink 组件与 hook API)、INKJS-UI.md(@inkjs/ui 组件目录与示例)、TERMINAL-COMPAT.md(终端检测与优雅降级)、PATTERNS.md(布局模式与设计配方)。资料未提供该技能的安装方式、收费模式、具体版本号与运行环境要求,这些暂未提供。