基于React与ink实现命令行AI助手思考内容折叠功能

最近在开发一个基于大语言模型的命令行工具时，遇到了一个典型的交互体验问题：当AI助手进行长链条的“思考”（Thinking）时，终端会被大段的中间推理过程刷屏。这些内容对调试很有价值，但对只想看最终结果的用户来说，却成了干扰信息。这让我联想到许多现代TUI（文本用户界面）工具中常见的“折叠”功能，于是决定动手为我的项目——姑且称之为“Pi”——实现一个简单的思考折叠机制。

本文将详细拆解如何为一个命令行AI助手实现思考内容的折叠与展开功能。无论你是在开发类似deepseek tui的交互工具，还是在使用OpenAI、Claude等模型的API构建应用时遇到了thinking内容展示的困扰，这篇文章都能提供一套完整的解决方案。我们将从问题分析、设计思路，一直讲到具体的代码实现、状态管理以及最佳实践，最终你将获得一个可复用的、增强CLI工具用户体验的组件。

1. 问题背景与核心需求

在AI驱动的命令行工具中，尤其是那些集成了复杂推理能力的大模型（如GPT-4、DeepSeek等），模型在生成最终答案前，常常会输出一系列的“思考”内容。这些内容在API中可能体现为content[].thinking字段（例如某些支持thinking模式的API），或者是工具调用（Tool Calls）过程中的中间推理步骤。

原始交互体验的问题：

1. 信息过载：冗长的思考过程直接打印到终端，淹没了最终答案，用户需要手动滚动查找。
2. 干扰核心输出：对于只想获取指令执行结果或简洁答案的用户，中间过程是噪音。
3. 不利于调试与审查：虽然思考过程对开发者很重要，但混合在正常输出中难以聚焦分析。

解决方案目标：实现一个折叠控件，默认隐藏详细的思考内容，用户可以通过快捷键（如Tab）或命令展开/收起，从而在“简洁模式”和“调试模式”间无缝切换。这类似于IDE中折叠代码块，或某些TUI中折叠日志详情的能力。

2. 技术选型与环境准备

本项目是一个Node.js命令行工具，核心依赖如下：

• 运行时：Node.js (>= 18.0.0)
• UI框架：ink&react- 用于在终端构建React组件式的交互界面。
• 文本布局：ink内置组件及ink-text。
• 状态管理：React Hooks (useState,useEffect)。
• 键盘交互：ink的useInputHook。

项目初始化与依赖安装：首先，确保你有一个Node.js项目。如果你从零开始，可以按以下步骤操作：

# 1. 初始化项目 mkdir pi-agent-tui && cd pi-agent-tui npm init -y # 2. 安装核心依赖 npm install ink react # 如果需要更复杂的文本样式，可以安装 npm install ink-text # 3. 创建入口文件 touch index.js

关键依赖说明：

• ink：它允许你使用React组件的方式来构建CLI界面，管理渲染、状态和用户输入，远比手动处理process.stdout和readline要高效和可靠。
• react：ink基于React，因此需要安装React。

我们的目标不是构建一个完整的pi agent或deepseek tui，而是聚焦于实现其中“思考折叠”这一个交互组件。因此，下面的代码将是一个独立的、可嵌入的组件。

3. 折叠组件的设计与核心状态

在设计折叠组件前，我们需要明确它的核心状态与属性。

组件属性 (Props)：

1. title(String): 折叠区域的标题，例如“🤔 模型思考过程”。
2. content(String): 需要被折叠隐藏的详细内容，即模型的thinking文本。
3. defaultExpanded(Boolean, 可选): 初始状态是展开还是收起，默认为false（收起）。
4. onToggle(Function, 可选): 当折叠状态改变时的回调函数，可用于外部状态同步。

组件内部状态 (State)：

1. isExpanded(Boolean): 控制内容当前是显示还是隐藏。
2. hasContent(Boolean): 用于判断是否有内容可折叠，避免渲染空折叠框。

交互逻辑：

• 用户按下Tab键时，切换isExpanded状态。
• 组件根据isExpanded决定渲染content还是占位提示（如“...”或“已折叠”）。
• 标题部分始终显示，并附带一个状态指示器（如[+]或[-]）。

4. 完整实现：ThinkingFoldable 组件

我们将创建一个名为ThinkingFoldable.js的组件文件。这是实现的核心。

// ThinkingFoldable.js import React, { useState, useEffect } from 'react'; import { Text, useInput } from 'ink'; /** * 一个可折叠的思考内容显示组件 * @param {Object} props * @param {string} props.title - 折叠区域的标题 * @param {string} props.content - 需要折叠的详细思考内容 * @param {boolean} [props.defaultExpanded=false] - 初始是否展开 * @param {function} [props.onToggle] - 折叠状态切换时的回调函数 */ const ThinkingFoldable = ({ title = 'Thinking', content, defaultExpanded = false, onToggle }) => { // 核心状态：是否展开 const [isExpanded, setIsExpanded] = useState(defaultExpanded); // 状态：是否有内容（防止渲染空折叠框） const [hasContent, setHasContent] = useState(false); // 监听 content 变化，更新 hasContent 状态 useEffect(() => { const hasContentNow = content && content.trim().length > 0; setHasContent(hasContentNow); }, [content]); // 处理键盘输入：Tab 键切换折叠状态 useInput((input, key) => { if (input === '\t' || key.tab) { // 支持 Tab 键 const newState = !isExpanded; setIsExpanded(newState); if (onToggle) { onToggle(newState); } } }); // 如果没有内容，则不渲染任何东西，或者渲染一个极简状态 if (!hasContent) { return null; // 或者可以返回 <Text>No thinking content.</Text> } // 构建状态指示符和标题 const indicator = isExpanded ? '[-]' : '[+]'; const fullTitle = `${indicator} ${title}`; return ( <> {/* 标题行，始终显示 */} <Text bold color="cyan"> {fullTitle} <Text color="gray"> (Press <Text bold>Tab</Text> to toggle)</Text> </Text> {/* 内容区域，根据状态决定显示内容还是占位符 */} {isExpanded ? ( // 展开状态：显示完整内容，通常用灰色等次要颜色 <Text color="gray" dimColor> {content.split('\n').map((line, idx) => ( <Text key={idx}> {line}</Text> // 添加缩进 ))} </Text> ) : ( // 折叠状态：显示省略号或简短提示 <Text color="gray" italic> {' ... (content folded)'} </Text> )} {/* 可选：在折叠块后加一个空行，增加可读性 */} <Text>{'\n'}</Text> </> ); }; export default ThinkingFoldable;

代码逐段解析：

1. 状态管理 (useState,useEffect):

   • isExpanded是组件的灵魂，控制着内容的显隐。
   • hasContent是一个优化项。如果API返回的thinking字段是空字符串或null，我们就不渲染整个折叠框，保持界面干净。useEffect用于在content属性变化时更新这个状态。

2. 键盘交互 (useInput):

   • ink提供的useInputHook让我们能轻松监听终端按键。这里我们监听Tab键（\t或key.tab）。
   • 当按下Tab，我们翻转isExpanded状态，并调用可选的onToggle回调，以便父组件知晓状态变化。

3. 条件渲染:

   • 如果hasContent为false，直接返回null，组件不渲染。
   • 根据isExpanded的值，决定是渲染完整的content（并添加缩进），还是渲染一个折叠状态的占位符（...）。

4. 样式与提示:

   • 使用<Text>组件的color、bold、italic、dimColor等属性来增强视觉效果。
   • 标题部分用醒目的颜色（如cyan），并明确提示用户使用Tab键切换。
   • 思考内容使用gray和dimColor，视觉上将其与主输出区分开，表明这是辅助信息。

5. 在主应用中使用折叠组件

现在，我们将在主应用文件中使用这个组件。假设我们有一个模拟的AI响应流。

// index.js import React, { useState, useEffect } from 'react'; import { render, Text, Box } from 'ink'; import ThinkingFoldable from './ThinkingFoldable.js'; // 模拟一个从API获取的AI响应，包含思考过程和最终答案 const mockAIResponse = { finalAnswer: '根据计算，圆的面积大约是78.54平方单位。', thinking: `用户请求计算半径为5的圆的面积。 我需要回忆圆的面积公式：面积 = π * r²。 其中，π（圆周率）通常取值3.14159，r是半径，此处为5。 因此，计算步骤为：3.14159 * (5 * 5) = 3.14159 * 25。 执行乘法：3.14159 * 25 = 78.53975。 四舍五入到两位小数，得到78.54。 所以最终答案是78.54平方单位。` }; const App = () => { const [response, setResponse] = useState(null); const [foldableKey, setFoldableKey] = useState(0); // 用于强制重渲染的key // 模拟数据加载 useEffect(() => { const timer = setTimeout(() => { setResponse(mockAIResponse); }, 500); return () => clearTimeout(timer); }, []); if (!response) { return <Text>等待AI响应...</Text>; } const handleThinkingToggle = (isNowExpanded) => { // 这里可以记录日志、发送分析事件等 console.log(`Thinking section is now ${isNowExpanded ? 'expanded' : 'collapsed'}`); // 如果需要，可以通过改变key来强制组件重置（非必需） // setFoldableKey(prev => prev + 1); }; return ( <Box flexDirection="column" padding={1}> <Text bold>🤖 AI 助手</Text> <Text>---</Text> {/* 1. 显示折叠的思考过程 */} <ThinkingFoldable key={`thinking-${foldableKey}`} // 可选：用于控制组件实例 title="模型推理过程" content={response.thinking} defaultExpanded={false} // 默认收起 onToggle={handleThinkingToggle} /> {/* 2. 显示最终答案 */} <Box borderStyle="round" borderColor="green" paddingX={1}> <Text bold color="green">答案：</Text> <Text> {response.finalAnswer}</Text> </Box> <Text>---</Text> <Text dimColor>提示：使用 Tab 键切换思考过程的显示/隐藏。</Text> </Box> ); }; // 使用 ink 渲染应用 render(<App />);

运行你的应用：确保package.json中配置了启动脚本。

// package.json { "name": "pi-agent-tui", "type": "module", "scripts": { "start": "node index.js" }, "dependencies": { "ink": "^4.0.0", "react": "^18.0.0" } }

然后在终端运行：

node index.js

你将看到一个简洁的界面，首先显示“模型推理过程”标题且处于折叠状态([+])，下方是醒目的最终答案。按下Tab键，思考内容会展开显示为灰色文本，再次按下Tab则收起。

6. 高级功能与优化实践

基础的折叠功能已经实现，但在生产环境中，我们可能需要更强大的功能。

6.1 处理流式输出与动态内容

许多AI API（如OpenAI的流式响应）是逐字返回的。我们的组件需要能处理动态增长的content。

// AdvancedThinkingFoldable.js (部分代码) import React, { useState, useEffect, useRef } from 'react'; const AdvancedThinkingFoldable = ({ title, contentStream }) => { const [isExpanded, setIsExpanded] = useState(false); const [accumulatedContent, setAccumulatedContent] = useState(''); const contentEndRef = useRef(null); // 模拟从流中累积内容 useEffect(() => { if (contentStream) { // 假设 contentStream 是一个异步生成器或事件发射器 // 这里简化为一个定时器模拟 const interval = setInterval(() => { setAccumulatedContent(prev => prev + '一段新的思考片段...\n'); }, 300); return () => clearInterval(interval); } }, [contentStream]); // 如果展开，自动滚动到底部（可选，取决于你的渲染库是否支持） useEffect(() => { if (isExpanded && contentEndRef.current) { // 调用某些TUI库的滚动API，或由父容器管理 } }, [isExpanded, accumulatedContent]); return ( <> <Text bold color="cyan" onClick={() => setIsExpanded(!isExpanded)}> {isExpanded ? '[-]' : '[+]'} {title} </Text> {isExpanded && ( <Box maxHeight={10} overflowY="auto"> {/* 限制最大高度并允许滚动 */} <Text color="gray"> {accumulatedContent || '（思考内容加载中...）'} </Text> <div ref={contentEndRef} /> {/* 用于滚动定位的锚点 */} </Box> )} </> ); };

关键点：对于流式内容，组件内部需要维护一个累积状态(accumulatedContent)。同时，考虑为展开的内容区域添加最大高度(maxHeight)和滚动(overflowY)，防止超长内容撑爆终端。

6.2 多折叠项与全局状态管理

当一次对话中有多次工具调用或多次思考时，你可能需要管理多个折叠项的状态。

// 使用一个状态对象来管理多个折叠项的展开状态 const [expandedStates, setExpandedStates] = useState({}); // 渲染多个折叠项 {thinkingSteps.map((step, index) => ( <ThinkingFoldable key={`step-${index}`} title={`思考步骤 ${index + 1}`} content={step.content} defaultExpanded={expandedStates[`step-${index}`] || false} onToggle={(expanded) => { setExpandedStates(prev => ({ ...prev, [`step-${index}`]: expanded })); }} /> ))} // 甚至可以添加全局控制 <Box> <Text>全局控制：</Text> <Text> <Text color="blue" onClick={() => setAllExpanded(true)}>[展开所有]</Text> {' | '} <Text color="blue" onClick={() => setAllExpanded(false)}>[收起所有]</Text> </Text> </Box>

6.3 样式与主题定制

通过Props允许自定义样式，使组件更灵活。

// ThinkingFoldable.js 增强版 Props ThinkingFoldable.propTypes = { // ... 其他props titleColor: PropTypes.string, contentColor: PropTypes.string, indicatorExpanded: PropTypes.string, indicatorCollapsed: PropTypes.string, foldedHint: PropTypes.string, }; // 在组件内部使用 const indicator = isExpanded ? (indicatorExpanded || '[-]') : (indicatorCollapsed || '[+]'); const foldedText = foldedHint || '... (content folded)'; // 应用颜色 <Text bold color={titleColor || 'cyan'}>...</Text>

7. 常见问题与排查思路

在实现和使用此类折叠组件时，你可能会遇到以下问题：

8. 最佳实践与工程建议

1. 键盘快捷键设计：

   • Tab键是折叠/展开的通用选择，但需注意它也可能用于焦点切换。确保你的TUI中焦点管理清晰。
   • 提供备用快捷键（如Ctrl+E），并在界面标题旁给予明确提示。
   • 考虑支持Ctrl+A（展开所有）和Ctrl+O（收起所有）等全局操作。

2. 可访问性与用户体验：

   • 状态指示器要清晰（[+]/[-]或▼/▶）。
   • 即使内容折叠，也最好显示一个简短的摘要或关键词（例如“思考过程包含3个步骤”），让用户知道折叠了什么。
   • 对于视力障碍用户，确保可以通过屏幕阅读器获取状态信息（虽然纯TUI中较难实现，但这是好的设计原则）。

3. 性能优化：

   • 记忆化：使用React.memo包装ThinkingFoldable组件，防止因父组件无关状态更新导致的重渲染。
   • 虚拟化：如果思考内容极其冗长（数万行），考虑实现一个虚拟滚动列表，只渲染视口内的行。ink本身不支持，但可以结合ink-box或自行计算。
   • 防抖渲染：对于高速的流式更新，不要每次字符到达都触发setState和重渲染，可以积累一小段时间（如100毫秒）的文本再更新。

4. 与AI API的集成：

   • 明确区分“思考”(thinking)和“最终输出”(final_output)。遵循类似OpenAI的reasoning或DeepSeek的thinking字段规范。
   • 处理API错误：当API返回类似“deepseek returned tool calls without replayable thinking content; continuing with degraded reasoning”的警告时，你的UI应该优雅降级，例如显示“思考内容不可用”而非一个空折叠框。
   • 持久化用户偏好：将用户默认的折叠状态（展开/收起）保存到本地配置文件（如~/.pi/config.json），下次启动时自动应用。

5. 测试策略：

   • 单元测试：测试组件的渲染逻辑（有无内容时）、状态切换逻辑。
   • 集成测试：模拟AI API流，测试组件在动态内容下的行为。
   • 快照测试：对组件的展开和收起状态进行UI快照测试，防止意外更改。

通过实现这样一个思考折叠组件，你显著提升了命令行AI工具的用户体验。它平衡了调试的详细性和使用的简洁性，是这个类别工具走向成熟和专业化的一个标志性功能。你可以将这个组件轻松集成到你的pi agent、deepseek tui或任何基于Node.js的AI CLI项目中。记住，好的工具不仅功能强大，更要体贴用户。