1. 从 Claude Code 的终端 UI 说起为什么一个 CLI 需要 React Ink你可能用过不少命令行工具它们大多长这样一行命令敲下去输出一堆文本滚动、退出、完事。但 Claude Code 不一样——它有模态对话框、实时进度条、语法高亮、Vim 模式、分组折叠甚至还有 FPS 监控。这些通常只在 GUI 应用里出现的东西全被塞进了一个终端窗口里。支撑这套 UI 的技术底座是 React Ink。简单说React Ink 让你用 React 的组件模型去描述终端界面你写Box、Text它负责把这些组件树转换成 ANSI 转义序列最终渲染到终端。对熟悉 React 的开发者来说这几乎是把 Web 前端那套心智模型直接搬到了命令行。Claude Code 的src/ink/目录下有 96 个文件src/vim/有 5 个文件再加上src/components/、src/context/、src/screens/构成了一套完整的终端 UI 工程体系。这套体系解决的核心问题是在字符网格的约束下如何做出接近 GUI 的交互体验。这篇文章面向的是想用 React Ink 构建工业级 CLI 的开发者。我会从组件分层、状态管理、Vim 键位适配三个角度拆解它的工程化实践并给出可复制的 Ink 渲染配置与键位映射片段。你不需要读过 Claude Code 的全部源码但需要对 TypeScript 和 React 有基本了解。先说清楚一件事React Ink 不是银弹。它的渲染模型是「全量重绘 diff」在终端这种低刷新率环境里性能优化是绕不开的坎。Claude Code 用 FPS 监控来追踪渲染性能这个思路值得借鉴。下面我会一步步带你把一个最小可用的 Ink 终端 UI 跑起来再逐步加上状态管理和 Vim 键位。2. 前置准备TaoToken 接入与 Ink 项目初始化在动手写 UI 之前得先把模型调用这条链路打通。Claude Code 本身是 AI 编程助手它的 UI 里大量交互比如对话、代码补全都依赖后端模型。如果你要复刻类似的终端 UI建议先把 API 接入配好这样后面调试交互时不会卡在「请求发不出去」上。TaoToken 提供了兼容 Anthropic 风格的 API 接入方式Base URL 是https://taotoken.net/api。你需要先在控制台创建一个 API Key然后把它写进环境变量或配置文件。这一步不复杂但有几个坑我后面会讲。2.1 获取 API Key 与配置 Base URL打开 TaoToken 控制台在 API Keys 页面创建一个新 Key。创建时注意选择对应的权限范围如果你只是本地调试给最小权限就行。拿到 Key 之后不要直接硬编码在源码里用环境变量管理export TAOTOKEN_API_KEYsk-你的key export TAOTOKEN_BASE_URLhttps://taotoken.net/api如果你用的是 Claude Code 或类似的 CLI 工具通常需要在配置文件里指定 Base URL 和 Key。以 Claude Code 的settings.json为例配置片段大概长这样{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的key } }注意ANTHROPIC_BASE_URL后面不要加/v1TaoToken 的 API 路径已经处理好了。如果你手动拼/v1/messages反而会 404。2.2 初始化 Ink 项目接下来初始化一个 TypeScript 项目装上 Ink 和 Reactmkdir ink-cli-demo cd ink-cli-demo npm init -y npm install ink react npm install -D typescript types/react ts-node npx tsc --inittsconfig.json里需要开启 JSX 支持{ compilerOptions: { target: ES2020, module: commonjs, jsx: react-jsx, strict: true, esModuleInterop: true, outDir: dist } }这里有个细节Ink 用的是 React 的 custom renderer所以jsx要设成react-jsx或react不能用preserve。另外module建议用commonjs因为 Ink 的某些依赖在 ESM 下会有兼容问题。2.3 最小可运行示例写一个最简单的 Ink 应用验证环境是否正常// src/index.tsx import React from react; import { render, Box, Text } from ink; const App () ( Box flexDirectioncolumn padding{1} Text colorgreenInk 终端 UI 已启动/Text Text dimColor按 CtrlC 退出/Text /Box ); render(App /);运行npx ts-node src/index.tsx如果终端里出现绿色文字说明环境没问题。这一步看起来简单但它是后面所有复杂交互的基础。我建议你先把这个跑通再往下走。3. 可复制配置Ink 渲染配置与 Vim 键位映射片段这一节是全文的核心。我会给出两组可直接复制的配置一组是 Ink 的渲染配置包括 ANSI 解析和色彩处理另一组是 Vim 键位映射。这两块是工业级 CLI 的关键也是 Claude Code 源码里最值得借鉴的部分。3.1 Ink 渲染配置ANSI 解析与色彩级别终端输出的内容往往带有 ANSI 转义序列比如ls --color的结果。Ink 默认的Text组件不解析这些序列你需要自己写一个解析器把 ANSI 控制码转换成 React 组件树。Claude Code 的Ansi.tsx就是这么做的。下面是一个简化版的 ANSI 解析配置你可以直接放进项目// src/components/Ansi.tsx import React from react; import { Text } from ink; type Span { text: string; fg?: string; bg?: string; bold?: boolean; dim?: boolean; }; const ANSI_REGEX /\x1b\[([0-9;]*)m/g; export function parseAnsi(input: string): Span[] { const spans: Span[] []; let lastIndex 0; let current: Span { text: }; let match: RegExpExecArray | null; while ((match ANSI_REGEX.exec(input)) ! null) { const text input.slice(lastIndex, match.index); if (text) { spans.push({ ...current, text }); } const codes match[1].split(;).map(Number); current applyCodes(current, codes); lastIndex match.index match[0].length; } const tail input.slice(lastIndex); if (tail) spans.push({ ...current, text: tail }); return spans; } function applyCodes(span: Span, codes: number[]): Span { const next { ...span }; for (const code of codes) { if (code 0) { next.fg undefined; next.bg undefined; next.bold false; next.dim false; } else if (code 1) next.bold true; else if (code 2) next.dim true; else if (code 30 code 37) next.fg basicColor(code - 30); else if (code 90 code 97) next.fg brightColor(code - 90); } return next; } const basicColor (i: number) [black, red, green, yellow, blue, magenta, cyan, white][i]; const brightColor (i: number) [gray, redBright, greenBright, yellowBright, blueBright, magentaBright, cyanBright, whiteBright][i]; export const Ansi: React.FC{ children: string } ({ children }) ( {parseAnsi(children).map((span, i) ( Text key{i} color{span.fg} backgroundColor{span.bg} bold{span.bold} dimColor{span.dim} {span.text} /Text ))} / );这个解析器覆盖了最常见的 SGR 码0/1/2/30-37/90-97。如果你需要 truecolor 支持可以扩展applyCodes处理38;2;r;g;b这种序列。色彩级别是另一个坑。不同终端对色彩的支持不一样xterm.js 支持 truecolor但 chalk 库可能检测不到tmux 可能报告比实际支持更高的色彩级别。Claude Code 的colorize.ts里有两个函数专门处理这个// src/utils/colorize.ts export function boostChalkLevelForXtermJs(): boolean { if (process.env.TERM_PROGRAM vscode) { // xterm.js 支持 truecolor但 chalk 可能只检测到 256 色 return true; } return false; } export function clampChalkLevelForTmux(): boolean { if (process.env.TMUX) { // tmux 可能报告 truecolor但实际只支持 256 色 return true; } return false; }在你的 Ink 应用启动时调用这两个函数可以避免颜色显示异常。具体做法是在render之前设置 chalk 的 levelimport chalk from chalk; if (boostChalkLevelForXtermJs()) chalk.level 3; if (clampChalkLevelForTmux()) chalk.level 2;3.2 Vim 键位映射状态机与 MotionClaude Code 的 Vim 模式实现遵循标准的 Vim 操作语法operator count motion/text-object。它的状态机在transitions.ts里核心转换流程是Normal → (Count) → Operator → Motion/TextObject → 执行下面是一个可复制的键位映射配置你可以直接用在 Ink 的useInput里// src/vim/keymap.ts export type VimMode normal | insert | visual; export type VimState { mode: VimMode; count: number; operator: string | null; pending: string | null; }; export const initialVimState: VimState { mode: normal, count: 0, operator: null, pending: null, }; export function transition(state: VimState, input: string): VimState { const next { ...state }; if (next.mode insert) { if (input \x1b) { next.mode normal; next.pending null; } return next; } // 数字累积 count if (/^[1-9]$/.test(input)) { next.count next.count * 10 Number(input); return next; } // operator 输入 if ([d, c, y].includes(input)) { if (next.operator input) { // dd / cc / yy next.operator null; next.count 0; return next; } next.operator input; return next; } // motion 输入 if ([h, j, k, l, w, b, e, 0, $].includes(input)) { if (next.operator) { // 执行 operator motion next.operator null; next.count 0; } else { // 纯移动 next.count 0; } return next; } // 进入 insert 模式 if (input i) { next.mode insert; return next; } return next; }然后在 Ink 组件里用useInput接入import { useInput } from ink; import { useState } from react; import { transition, initialVimState } from ./vim/keymap; const Editor () { const [vim, setVim] useState(initialVimState); useInput((input, key) { setVim((prev) transition(prev, input)); }); return Text当前模式{vim.mode} | count{vim.count}/Text; };这个状态机覆盖了h/j/k/l、w/b/e、0/$这些基本 motion以及d/c/y操作符和dd/cc/yy快捷操作。如果你需要 text object比如iw、i、i(可以在transition里加一个pending状态来处理i和a前缀。3.3 组件分层Box 布局与 ScrollViewInk 的Box组件类似 CSS Flexbox支持flexDirection、padding、margin、borderStyle等属性。Claude Code 的src/ink/components/里有一套完整的组件库包括Box.tsx、Button.tsx、TextInput.tsx、Spinner.tsx、ScrollView.tsx。下面是一个可复制的布局配置展示如何用Box做分层import React from react; import { Box, Text } from ink; export const Layout () ( Box flexDirectioncolumn height100% {/* 顶部状态栏 */} Box borderStylesingle paddingX{1} Text boldClaude Code UI/Text /Box {/* 主内容区 */} Box flexGrow{1} flexDirectionrow {/* 侧边栏 */} Box width{20} borderStylesingle paddingX{1} Text dimColor文件树/Text /Box {/* 编辑区 */} Box flexGrow{1} paddingX{1} Text主编辑区/Text /Box /Box {/* 底部状态栏 */} Box borderStylesingle paddingX{1} Text dimColorNormal | 1,1/Text /Box /Box );这个布局用了height100%和flexGrow{1}来撑满终端。注意 Ink 的Box不支持百分比宽度只能用固定值或flexGrow。4. 验证请求启动、交互与性能观测配置写完了接下来要验证它能不能跑起来。这一节我会带你走一遍完整的启动、交互和性能观测流程确保你的 Ink 应用不只是「能渲染」而是「能交互」。4.1 启动与基础交互先写一个带输入框的完整示例// src/index.tsx import React, { useState } from react; import { render, Box, Text, useInput } from ink; import { transition, initialVimState } from ./vim/keymap; const App () { const [vim, setVim] useState(initialVimState); const [lines, setLines] useStatestring[]([Hello, Ink!]); useInput((input, key) { const next transition(vim, input); setVim(next); if (next.mode insert input ! \x1b) { setLines((prev) { const last prev[prev.length - 1] ?? ; return [...prev.slice(0, -1), last input]; }); } }); return ( Box flexDirectioncolumn padding{1} Box borderStylesingle paddingX{1} Text bold colorcyanInk Vim Demo/Text /Box Box flexDirectioncolumn marginTop{1} {lines.map((line, i) ( Text key{i}{line}/Text ))} /Box Box marginTop{1} Text dimColor -- {vim.mode.toUpperCase()} -- | count: {vim.count} /Text /Box /Box ); }; render(App /);运行npx ts-node src/index.tsx你会看到一个带边框的终端界面。按i进入 insert 模式输入文字会追加到当前行按Esc回到 normal 模式按d再按d会触发删除操作这里只是状态变化实际删除逻辑需要你自己实现。4.2 性能观测FPS 监控终端 UI 的性能问题往往表现为输入延迟和界面卡顿。Claude Code 用 FPS 监控来追踪渲染性能这个思路你可以直接借鉴。下面是一个简化版的 FPS 监控 hook// src/hooks/useFps.ts import { useEffect, useRef, useState } from react; export function useFps(sampleMs 1000) { const [fps, setFps] useState(0); const frames useRef(0); const last useRef(Date.now()); useEffect(() { let raf: NodeJS.Timeout; const tick () { frames.current 1; const now Date.now(); if (now - last.current sampleMs) { setFps(Math.round((frames.current * 1000) / (now - last.current))); frames.current 0; last.current now; } raf setTimeout(tick, 16); }; tick(); return () clearTimeout(raf); }, [sampleMs]); return fps; }在组件里用const fps useFps(); return Text dimColorFPS: {fps}/Text;注意终端环境的刷新率远低于浏览器16ms 的 tick 只是近似值。实际观测时如果 FPS 持续低于 30说明渲染压力较大需要检查是否有组件在每次渲染时做了重计算。Claude Code 源码里有一个相关的性能问题修复注释值得引以为戒userFacingNameruns per-render for every bash message in history; with ~50 msgs one slow-to-tokenize command, this exceeds the shimmer tick → transition abort → infinite retry.这个问题的根因是每次渲染都调用userFacingName当消息数量多且某条命令 tokenize 慢时渲染超时导致动画中断和无限重试。解决方案是用useMemo缓存计算结果或者把重计算移到useEffect里。4.3 验证 API 请求如果你要验证模型调用链路可以用一个简单的请求测试// src/api/test.ts export async function testApi() { const res await fetch(https://taotoken.net/api/v1/messages, { method: POST, headers: { Content-Type: application/json, x-api-key: process.env.TAOTOKEN_API_KEY!, anthropic-version: 2023-06-01, }, body: JSON.stringify({ model: claude-3-5-sonnet-20241022, max_tokens: 64, messages: [{ role: user, content: ping }], }), }); if (!res.ok) { throw new Error(API error: ${res.status} ${await res.text()}); } return res.json(); }在 Ink 组件里调用这个函数把结果显示在界面上。如果返回正常说明 API 链路通了如果报错看下一节的排查清单。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth这一节列出我在调试 Ink API 接入时踩过的坑以及对应的排查方法。这些报错在 Claude Code 和类似工具里很常见你可以对照着看。5.1 401 Unauthorized最常见的报错。原因通常是 API Key 没配、配错位置、或者 Key 失效。排查步骤第一确认环境变量是否生效。在终端里执行echo $TAOTOKEN_API_KEY如果输出为空说明没导出成功。注意export只在当前 shell 会话有效如果你开了新终端需要重新导出。第二确认配置文件路径。Claude Code 的settings.json通常在~/.claude/settings.json如果你用的是项目级配置路径是.claude/settings.json。两个文件同时存在时项目级会覆盖全局级。第三确认 Key 的权限范围。如果你在 TaoToken 控制台创建 Key 时只给了只读权限调用写接口会返回 401。5.2 local proxy failed这个报错通常出现在你配置了本地代理但代理服务没启动或端口不对。注意这里说的代理是本地开发环境的 HTTP 代理不是网络层面的东西。排查步骤第一检查HTTP_PROXY和HTTPS_PROXY环境变量。如果设置了但代理服务没跑请求会失败。执行unset HTTP_PROXY HTTPS_PROXY再试。第二检查 Base URL 是否被代理规则拦截。有些代理工具会把taotoken.net也走代理导致连接失败。把taotoken.net加入直连列表。第三如果你用的是公司网络确认防火墙是否放行了taotoken.net的 443 端口。5.3 reading choices这个报错通常出现在流式响应解析时。Claude Code 的 API 返回是 SSE 流如果你用res.json()直接解析会报reading choices相关的错误。正确的做法是用res.body的 reader 逐块读取const reader res.body?.getReader(); const decoder new TextDecoder(); let buffer ; while (reader) { const { done, value } await reader.read(); if (done) break; buffer decoder.decode(value, { stream: true }); const lines buffer.split(\n); buffer lines.pop() ?? ; for (const line of lines) { if (line.startsWith(data: )) { const data line.slice(6); if (data [DONE]) continue; const json JSON.parse(data); // 处理 json.delta 等字段 } } }如果你不需要流式把请求体里的stream设为false然后用res.json()解析。5.4 OAuth 相关报错如果你用的是 OAuth 方式接入报错通常是invalid_grant或token expired。排查步骤第一检查 token 是否过期。OAuth token 通常有有效期过期后需要用 refresh token 换新的。第二检查settings.json里的oauthAccount字段是否完整。Claude Code 的 OAuth 配置需要accessToken、refreshToken、expiresAt三个字段。第三如果报redirect_uri mismatch检查你在 TaoToken 控制台配置的回调地址是否和代码里的一致。5.5 配置三件套对照表如果你用的是 CC Switch、Cline MCP 或 Codex 的auth.json确保以下三件套都配对了配置项值说明Base URLhttps://taotoken.net/api不要加/v1API Keysk-...从控制台获取Model IDclaude-3-5-sonnet-20241022按需替换以 Codex 的auth.json为例{ baseUrl: https://taotoken.net/api, apiKey: sk-你的key, model: claude-3-5-sonnet-20241022 }Cline MCP 的配置类似在mcp_settings.json里指定baseUrl和apiKey。CC Switch 则是在切换配置时确保这三个字段一致。6. 继续深入从 Ink 到工业级 CLI 的下一步到这里你已经有了一个能跑起来的 Ink 终端 UI带 Vim 键位和 FPS 监控。但离工业级还有距离。Claude Code 的src/ink/有 96 个文件我们只覆盖了最核心的部分。下面几个方向值得继续深入。BiDi 文本支持。Claude Code 的bidi.ts实现了双向文本渲染支持阿拉伯语、希伯来语等从右到左书写的语言。这在终端应用里很少见但如果你要做国际化这是绕不开的。核心函数是reorderBidi和reverseRange思路是把字符按 Unicode BiDi 算法重新排序。ANSI 到图片的转换。ansiToPng.ts和ansiToSvg.ts把终端输出转成图片用于会话分享和导出。实现方式是内嵌字体光栅化把 ANSI 转义序列解析成带样式的文本再渲染到 canvas 或 SVG。终端兼容性处理。clearTerminal.ts展示了不同终端模拟器对清屏序列的支持差异。Windows Terminal、mintty、xterm、iTerm2 各有各的脾气你需要检测当前终端类型并选择正确的控制序列。核心函数是isWindowsTerminal、isMintty、getClearTerminalSequence。状态管理的 store 模式。Claude Code 的src/state/用了类似 Zustand 的 store 模式通过useAppState(selector)订阅状态变化。这种模式比 React Context 更适合高频更新的场景因为 selector 可以精确控制重渲染范围。如果你想继续调试模型调用可以打开模型对话页面直接测试如果要把这套 UI 接入长期编码工作流Coding Plan 提供了更完整的配额管理API Keys 页面可以管理你的 Key 权限。接入文档里有更详细的参数说明。最后说一个实用技巧Ink 的Static组件可以渲染不需要更新的内容比如历史日志。把不变的部分放进Static只让变化的部分参与 diff能显著降低渲染压力。这个优化在消息列表场景下效果特别明显。
