摘要你能在终端里运行 React 吗Ink 让这成为可能。cc-haha 的终端界面基于 Ink——一个用 React 组件渲染命令行的框架。本文深入解析 Ink 的渲染原理、cc-haha 的组件架构、异步生成器驱动的对话循环以及如何用 React 的思维模式构建一个复杂的 TUI 应用。一、Ink 是什么Ink 是一个基于 React 的库让你用熟悉的 JSX 组件来构建命令行界面TUI。它内部使用yoga-layoutFacebook 的跨平台布局引擎来计算终端中的布局。React 组件Ink reconcileryoga-layoutANSI 转义序列终端输出核心理念把终端当作一个 80x24 的浏览器窗口用 Flexbox 布局用 React 状态管理。二、cc-haha 的 Ink 组件架构AppChatScreenPermissionDialogStatusBarAgentPanelMessageListInputBoxUserMessageAssistantMessageToolCallBlockConfirmBoxRuleEditorModelIndicatorTokenCounterMemoryStatus2.1 核心组件组件职责关键实现App根组件管理路由和全局状态useAppStatehookChatScreen主对话界面消息列表 输入框MessageList消息滚动列表useScroll 虚拟滚动优化AssistantMessageAI 回复渲染Markdown 代码高亮 打字机效果ToolCallBlock工具调用展示可折叠的折叠面板PermissionDialog权限确认弹窗模态框 快捷键绑定StatusBar底部状态栏固定高度实时更新三、对话循环异步生成器驱动cc-haha 的核心对话循环不是传统的 Promise 链而是async generator// 伪代码queryLoop 的核心结构asyncfunction*queryLoop(userInput:string){// 1. 构建请求消息constmessagesbuildMessages(userInput)// 2. 发送 API 请求conststreamawaitanthropic.messages.create({messages,stream:true,tools:availableTools,})// 3. 流式消费响应forawait(constchunkofstream){if(chunk.typecontent_block_delta){yield{type:text,content:chunk.delta.text}}elseif(chunk.typetool_use){yield{type:tool_use,name:chunk.name,input:chunk.input}// 4. 执行工具constresultawaitexecuteTool(chunk.name,chunk.input)yield{type:tool_result,result}// 5. 工具结果送回模型继续生成// 递归进入下一轮 queryLoop}}}为什么用 async generator流式输出每个 token 可以立即 yield不需要等完整响应中断支持消费者可以随时 break取消后续生成工具调用链工具结果可以无缝送回模型形成循环背压控制消费者处理慢时生成器自动暂停四、状态管理React 哲学在终端cc-haha 的 TUI 状态管理与 Web 应用没有本质区别// useAppState hook简化版functionuseAppState(){const[messages,setMessages]useStateMessage[]([])const[isStreaming,setIsStreaming]useState(false)const[pendingPermission,setPendingPermission]useStatePermission|null(null)constsendMessageasync(content:string){setMessages(prev[...prev,{role:user,content}])setIsStreaming(true)forawait(constchunkofqueryLoop(content)){if(chunk.typetext){setMessages(prevupdateLastAssistantMessage(prev,chunk.content))}elseif(chunk.typetool_use){setMessages(prev[...prev,{role:assistant,toolUse:chunk}])}elseif(chunk.typepermission_request){setPendingPermission(chunk.permission)// 等待用户确认...constallowedawaitwaitForPermissionResponse()setPendingPermission(null)}}setIsStreaming(false)}return{messages,isStreaming,pendingPermission,sendMessage}}五、Ink 组件示例5.1 自定义进度条// components/ProgressBar.tsx import { Box, Text } from ink interface ProgressBarProps { percent: number width?: number } export function ProgressBar({ percent, width 30 }: ProgressBarProps) { const filled Math.round((percent / 100) * width) const empty width - filled return ( Box Text colorgreen{█.repeat(filled)}/Text Text colorgray{░.repeat(empty)}/Text Text {percent.toFixed(1)}%/Text /Box ) }5.2 可折叠的工具调用展示// components/ToolCallBlock.tsx import { useState } from react import { Box, Text, useInput } from ink export function ToolCallBlock({ tool, result }) { const [isExpanded, setIsExpanded] useState(false) useInput((input, key) { if (key.return) setIsExpanded(!isExpanded) }) return ( Box flexDirectioncolumn borderStyleround padding{1} Text bold colorcyan {isExpanded ? ▼ : ▶} {tool.name} /Text {isExpanded ( Text dimColorInput: {JSON.stringify(tool.input)}/Text Text colorgreenResult: {result}/Text / )} /Box ) }六、性能优化技巧6.1 虚拟滚动终端高度有限消息多了会卡顿。cc-haha 使用虚拟滚动只渲染可见区域functionuseVirtualScroll(items:any[],itemHeight:number,containerHeight:number){const[scrollTop,setScrollTop]useState(0)conststartIndexMath.floor(scrollTop/itemHeight)constendIndexMath.min(startIndexMath.ceil(containerHeight/itemHeight),items.length)constvisibleItemsitems.slice(startIndex,endIndex)constoffsetYstartIndex*itemHeightreturn{visibleItems,offsetY,setScrollTop}}6.2 节流渲染流式输出时每收到一个 token 就重新渲染会导致 CPU 飙升。使用节流import{useThrottle}fromusehooks-tsfunctionStreamingText({stream}){constthrottledTextuseThrottle(stream.text,50)// 50ms 节流returnText{throttledText}/Text}总结cc-haha 的 TUI 界面证明了React 不限于浏览器Ink 框架用 JSX Flexbox 构建命令行界面Async Generator流式对话循环的天然选择React 哲学hooks、组件化、状态管理全部适用性能优化虚拟滚动 节流渲染确保大会话不卡顿开发建议Ink 组件调试时使用DEBUGink环境变量查看渲染日志复杂布局先用Box的borderStylesingle可视化边界终端颜色使用chalk的语义化颜色名而非硬编码 ANSI 码参考资料Ink 官方文档yoga-layout 文档React ReconcilerANSI 转义序列在终端里写 React听起来像是一个悖论。但 Ink 让这成为了可能——而且非常自然。如果你熟悉 React那么构建 TUI 界面几乎没有学习曲线。