说句实话最近这几个月我写的代码里最值回票价的就是这个给 AI Agent 私有定制的终端。它解决的事情一句话能讲明白让 Claude Code 能直接操控我机器上的真实终端并且我还能同时拉多个 Agent 一起干活互不抢键盘、互相不搅乱会话。这个终端不是传统意义上给人类用的终端模拟器而是给 Agent 当“手脚”的终端服务。核心诉求拆开就三条第一Claude Code 要能执行任意终端命令并读到输出第二终端会话要能长期复用不要每条命令都从头开一个 shell环境变量、当前目录、历史状态全丢了第三多个 Agent 可以同时接入每个 Agent 有自己的会话上下文也可以按需共享同一个终端画面。我把这套东西用 Rust 从头写了一遍底层走 PTY对外暴露成可供 Claude Code 调用的工具服务。今天这篇就是把思路、架构、关键代码、踩坑记录都摊开来讲。1. 项目背景与核心需求拆解1.1 原生能力的最大痛点命令执行是一次性的先聊一个很多人刚接触 Claude Code 都会遇到的落差。它本身是有 Bash 工具能力的你可以直接让它“帮我跑一下npm run test”它也能执行。但它的默认执行模型是起一个临时 shell执行命令拿回 stdout/stderr然后 shell 就销毁了。这在简单场景下没问题可一旦涉及长时间运行的进程、交互式命令、或者需要保持某个工作目录反复操作的场景就非常难受。举个具体例子。我想让 Agent 帮我调试一个后端服务需要先后执行export MY_ENVxxx、cd /project/service、启动服务、然后看日志。如果用 Claude Code 原生的命令工具每一条命令都是独立的进程环境变量不共享当前目录不保留服务开了之后 Agent 甚至没法按CtrlC去正确中断它。你需要在每一条提示词里把绝对路径和环境变量再重申一遍这体验基本属于“能用但反人类”。交互式命令就更别想了。你想让 Agent 用vim改文件、用htop看负载、甚至操作redis-cli的交互模式原生工具链直接抓瞎。它的能力模型是“命令输入 输出返回”而真实终端是一个双向流式的交互环境会输出颜色转义序列会等待用户按键会有后台任务。所以本质上Agent 缺的不是执行命令的能力而是一个和人类一样握在手里的终端句柄。1.2 需求清单一个终端要能扛住三件事我在项目初期把需求收敛成三条硬性功能其余都算加分项命令执行Agent 能向终端写入任意命令并且拿到结构化或者纯文本化的完整输出。注意是“任意”包括带管道、带重定向、带交互式循环的复合命令。会话复用每个终端会话是常驻的 PTY 进程Agent 可以跨多次工具调用反复读写同一个会话。当前目录、环境变量、PATH 都保持连续性就像你每次把终端窗口放在那里不动只是有人代替你在敲键盘。多 Agent 调度系统要能创建多个会话允许不同的 Agent 分别持有不同会话也可以允许多个 Agent 共同操作一个会话需要加锁和队列。更关键的是会话之间互相隔离不能出现两个 Agent 的输出交错污染。第三点是我特别看重的。很多人都说“多 Agent 协调”是未来但真正上手时你会发现多 Agent 最大的麻烦根本不是模型能力而是共享资源的管理。终端就是这个共享资源里最容易被搞乱的一类。1.3 为什么现成方案都差点意思在决定从零写之前我花了不少时间审视现成工具。比如 tmux它确实是终端复用界的标准答案能起窗格、能 detach、能恢复会话但它面向的是人不是 Agent。它没有一个清晰的“命令执行 返回结果”的工具协议Agent 要操作 tmux要么通过tmux send-keys这种字符串拼凑要么就得自己解析 pane 里输出的内容。解析状态还是得自己造轮子。还有一类方案是网页终端比如 ttyd、wetty 这类它们能把终端丢到浏览器里。问题是它们的设计目标是给人用的远程终端交互协议基于 websocket 的即时按键流Agent 调用起来不够结构化——Agent 需要的不是“像人一样按每个键”而是一个可以“输入一行命令、拿回一批输出”的稳定接口。终端模拟器类项目比如 tabby 我也研究过。tabby 是非常优秀的终端应用它的标签页管理、会话组织、主题系统都值得参考但它归根结底是 GUI 程序不是一个可以被第三方程序通过本地接口操作的终终端服务。我想要的是把 tabby 这种“多标签会话有序管理”的思想抽出来做成一个 headless 的、能被 Claude Code 通过工具协议调用的终端服务。这部分后面会细说。所以结论很清晰要满足 Agent 的终端操控需求就必须自建一层“终端编排层”。它介于 Agent 和系统的 shell 之间负责创建 PTY、维护会话、解析输出、分发输入。2. 核心架构设计与关键选型2.1 整体架构控制平面与数据平面整个系统的设计我分成了两个平面。控制平面负责会话管理、Agent 身份识别、任务调度数据平面负责 PTY 的读写、输出捕获、事件通知。从上层往下看大致是这样一条链路调用方Claude Code 通过 MCPModel Context Protocol工具调用我的终端服务或者直接 HTTP 调用。接入层接收工具请求解析参数比如“向会话 3 写入命令ls -la等待输出”。会话管理器找到或创建对应会话把这次写操作放入该会话的命令队列防止并发写冲突。PTY 进程层每个会话对应一个真实的伪终端进程默认 shell 可以选 zsh/bash/powershell。输出处理模块轮询或异步读取 PTY 输出剥离 ANSI 颜色码同时把完整的回滚缓冲存进环形队列供 Agent 按需查询。数据平面最麻烦因为终端输出是持续的、无序的、带有大量控制字符的。你没法保证“写一条命令就能精确拿到这条命令对应的输出”因为进程可能是异步的、可能输出了一屏幕日志、可能在等待输入。所以我的设计里加了一个“命令边界”的概念Agent 写命令时我会先写入一个唯一的标记串然后持续读取输出直到在输出流里再次看到这个标记串或者达到超时时间。这就模仿了人类在终端里执行的“敲命令、等输出”的过程。2.2 为什么选 Rust内存安全、并发、和单文件交付选型阶段我对比过 Go、Node.js 和 Rust。Node.js 写事件 I/O 确实快但要在生产环境做 PTY 的原生绑定时控制底层文件描述符和进程信号总觉得隔着一层。Go 的并发模型很棒编译产物也干净但 Windows 下的 PTY 支持ConPTY绑定不如 Rust 生态里现成的库顺手。最终选 Rust理由有三个内存安全 多线程操作同一个金融级缓冲时不用担心野指针。终端数据处理本质上是多生产者单消费者的模型Rust 的所有权和通道机制能把这个模型表达得非常干净。tokioportable-pty让我既能做异步 I/O又能跨平台创建 PTY。Rust 生态里的portable-pty库是我目前看到对跨平台 PTY 封装得最优雅的库Linux/macOS 走/dev/ptsWindows 走 ConPTY上层代码基本不用改。编译成单二进制部署。一个ai-terminald二进制扔到服务器上直接跑不需要 Node 运行时不需要 Python 虚拟环境。我用一个类比给团队讲过这个设计给 Agent 写终端就像给机器人装遥控器。这个遥控器本身不需要屏幕但需要一个稳定的信号通道、一个按键队列、和一根能随时连接任意机器的电缆。Rust 恰好能把“通道 队列 电缆”做得又小又稳。2.3 借鉴 tabby 的会话管理思想tabby 的交互设计里有两点让我很受启发。第一是它把每个终端标签页当作一个独立会话单元切换标签页就是切换会话会话的生命周期跟标签页绑定第二是它提供了全局搜索和回滚浏览让我感觉“终端的过去是可以被翻阅的”。我决定把这个思想抽出来加一层 Agent 视角。在我的系统里每个会话也有一份回滚缓冲但我不只是让人类翻阅而是让 Agent 通过工具调用主动查询get_terminal_history(session_id, since_line)。这样 Claude Code 可以一直看到它在运行某个长任务期间遗漏的日志输出。这其实是把“人类在终端窗口里往上滚动”这一步变成了机器可调用的 API。2.4 工具调用协议让 Claude Code 理解终端要让 Claude Code 调用我的终端服务最自然的方式不是写一堆 prompt 让模型去猜而是把能力做成标准工具。目前我是用 MCP 协议暴露的同时也保留一个 HTTP JSON 接口做调试和兼容。MCP 工具定义大致会暴露这几类能力spawn_session创建新会话参数包括 shell 类型、工作目录、窗口尺寸。exec_command向会话写入单行命令等待输出返回。send_signal向会话发送CtrlC、CtrlD之类的信号。read_output读取指定会话的回滚缓冲。list_sessions列出所有活动会话。destroy_session强制结束一个会话。用 MCP 的好处是 Claude Code 原生支持而且模型会自动依据工具的 description 决定何时调用、传什么参数。我只需要在配置里指向自己写的 MCP server 即可。3. 实操从零搭建这个终端服务3.1 环境准备与第一版依赖我的开发环境主力是 macOS Linux 服务器兼顾 Windows 测试。Rust 工具链直接用官方 stable 版本即可需要把tokio、portable-pty、serde_json、towerHTTP 层加入依赖。安装 Claude Code 本身也很简单。macOS 或者 Linux 下最常用的做法是打开终端执行官方给出的安装命令。安装完成后执行claude --version能看到版本号就算成功。Windows 上也能用但要注意它默认依赖的操作 shell 是 PowerShell这和 macOS/Linux 的体验稍有差异。如果你在 Ubuntu 下配置注意先确认 Node 运行时版本满足官方要求因为 Claude Code 本体是 npm 包分发的不过也有桌面版安装包可以直接使用。这里必须多说一句关于地区可用性的问题。新装的时候如果有人遇到类似“not available in your country”的提示我的建议只有一个以官方文档列出的支持范围为准走官方支持的渠道配好账号和环境。不要去尝试任何绕过限制的办法合规使用才是长期能稳定跑项目的前提。3.2 核心模块创建 PTY 并接管输入输出代码上最关键的一段是创建 PTY 然后拿到读写句柄。portable-pty的使用方式非常直观先构造一个native_pty_system()再创建命令。use portable_pty::{CommandBuilder, native_pty_system, PtySize}; use std::sync::Arc; use tokio::io::{AsyncReadExt, AsyncWriteExt}; use tokio::sync::Mutex; pub struct TerminalSession { pub id: String, pub writer: ArcMutexBoxdyn std::io::Write Send, // 回滚缓冲存放最近 N 行纯文本输出 pub buffer: ArcMutexVecString, } pub fn create_pty_session(id: String, cwd: str, rows: u16, cols: u16) - ResultTerminalSession, Boxdyn std::error::Error { let pty_system native_pty_system(); let mut cmd CommandBuilder::new(zsh); cmd.cwd(cwd); cmd.env(TERM, xterm-256color); let pair pty_system.openpty(PtySize { rows, cols, pixel_width: 0, pixel_height: 0 })?; let child pair.slave.spawn_command(cmd)?; drop(child); // 子进程后续由 PTY 持有这里只需要读写端 let writer pair.master.try_clone_writer()?; let reader pair.master.try_clone_reader()?; // 启动读循环把输出解析后写入回滚缓冲 tokio::spawn(async move { let mut reader reader; let mut buf [0u8; 4096]; // 这里需要把字符串按 UTF-8 边界处理避免截断乱码 let mut left Vec::new(); loop { match reader.read(mut buf).await { Ok(0) | Err(_) break, Ok(n) { left.extend_from_slice(buf[..n]); // 简单处理按 UTF-8 边界截断后转 String // 实际项目里应该用 lossy 转换 保留残留字节 let s String::from_utf8_lossy(left); // 此处应剥离 ANSI并把完整行 push 到 buffer } } } }); Ok(TerminalSession { id, writer: Arc::new(Mutex::new(writer)), buffer: Arc::new(Mutex::new(Vec::new())) }) }注意几个关键点。第一slave.spawn_command返回的child是需要持有的如果直接drop子进程不会死因为会话端仍然持有文件描述符但如果想跟踪进程退出状态最好单独保存。第二cwd参数会被 shell 当作启动目录所以 Agent 完全可以指定某个项目目录作为会话的家。第三TERMxterm-256color是为了让大部分终端程序正确输出颜色和交互控制码。3.3 输出处理ANSI 转义与回滚缓冲这是全项目里最容易阴沟翻船的地方。终端输出并不是干净的文本而是带一堆转义序列。比如当你执行ls时输出里可能包含高亮颜色码\x1b[38;5;27m如果你直接把原始字节传给模型模型会被这些控制字符干扰导致“看得到但读不懂”。所以我做了一个清洗层。保留原始字节流给人类查日志用同时生成一份“纯文本视图”给 Agent。纯文本视图要做的事有移除 ANSI 颜色和样式序列比如\x1b[0m、\x1b[1;31m。处理光标控制移动序列比如\x1b[1A光标上移一行否则最终文本的行序会错乱。处理回车符和退格符尤其是进度条场景。一个常见的坑是top这类全屏交互程序会不断用转义序列重绘整个界面回滚缓冲里全是“垃圾”。我的处理方案是对 Agent 读取输出时只读取“当前静态帧”而不是流式全文。具体来说当 Agent 调用exec_command执行一条命令并等待返回时我会在命令结束或超时时从回滚缓冲里取出从命令写入点到当前时刻新增的行并做一次重绘压缩。这样至少能保证 Agent 拿到的不是满屏的重复帧。3.4 命令边界标记与超时策略让 Agent“写命令→拿输出”这种轮询式交互核心难题是知道“当前命令的输出到哪了”。我采用的最朴素但有效的方案就是写边界标记。echo \n__CMD_DONE_MARKER_${RANDOM}_${RANDOM}__我先向 PTY 写入用户要执行的命令再单独另起一行写入这个echo标记然后持续读取 PTY 输出直到读取内容里出现这个标记串。标记出现在输出里意味着上一条命令已经执行完shell 已经回到提示符状态之后的输出是干净的新输入。这个技巧解决了我 80% 的命令边界问题但它有一个缺限如果命令本身输出过同样的标记内容或者命令卡住了不返回就失效了。所以必须配合超时。超时策略我按命令类型做了区分。简单命令默认 10 秒编译类命令给 60 秒长任务命令支持调用方显式传wait_for_seconds。一旦超时我不会直接杀掉进程而是返回截止到超时时刻的部分输出并附带一个timeout: true标志。这样 Claude Code 可以自己决定是继续等待、发CtrlC还是再调一次read_output查后续输出。3.5 多 Agent 并发调度多 Agent 同时指向同一个终端的场景最大的风险是输入互相覆盖。两个 Agent 同时执行exec_command一个写cd /app另一个写rm -rf build最终 shell 收到的可能是一条拼接起来的乱命。我的方案是给每个会话加一个带“归属标识”的命令队列。所有权模型很简单一个会话默认只允许一个 Agent 持有“操作权”其他 Agent 的写入请求会排队。如果业务上确实需要多个 Agent 协作同一个会话可以显式开启共享模式共享模式下每条命令都会附加上来源 Agent 的标识并且对写操作加锁。输出侧呢我会给每批输出加上起始标记这样不同 Agent 执行互不干扰。实际开发里我还加了“任务编排”的概念。你可以通过 HTTP 接口一次提交多个任务比如“Agent A 负责准备环境Agent B 负责跑测试Agent C 负责汇总日志”调度器会为每个 Agent 分配独立会话并把最终各会话的结果汇总到你指定的输出文件里。这算是我个人对“多 Agent 指挥”这个需求的实现雏形。4. Claude Code 接入与命令执行配置4.1 让 Claude Code 真正“操控”终端并不是所有场景都需要自己写 MCP Server。先说一种轻量思路Claude Code 自带 Bash 工具你可以在提示词里让它“通过 Bash 工具运行命令”它确实能执行。但如果你想让它操作我们的常驻会话就需要把 MCP Server 接上。把你编译好的二进制启动成本地监听模式然后配置 Claude Codeclaude mcp add ai-terminal --transport stdio --command /usr/local/bin/ai-terminald -- --mcp或者用项目级配置文件.mcp.json{ mcpServers: { ai-terminal: { command: /usr/local/bin/ai-terminald, args: [--mcp], env: { LOG_LEVEL: info } } } }配置好后你在 Claude Code 里发起一个新会话它就能看到spawn_session、exec_command、send_signal这一组工具。接下来你可以直接跟它说“帮我在项目目录开一个会话然后运行make build如果遇到报错就读取滚动缓冲里的内容分析后修复再跑。”它会自动决定如何组合这些工具。4.2 接入第三方模型DeepSeek、Qwen、GLM 的兼容层因为项目主要围绕 Claude Code但实际团队里有人没有合适的环境或者想要更低的调用成本换来换去很麻烦。这时接入第三方模型就很有价值。目前 Claude Code 支持通过环境变量指认 API 路由层这本质上就是兼容 Anthropic API 格式的任意服务。我常用的方式是使用一个叫 CC Switch 的社区工具来切换模型供应商。它本质上是维护一个配置文件在启动 Claude Code 前设置好ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN这两个环境变量。比如接入 DeepSeek 时指向它的 Anthropic 兼容端点Qwen 就指向阿里云 DashScope 的兼容端点GLM 则指向智谱的兼容端点。三者都是国内大模型 API 的合法使用场景。切换之后要注意一个模型能力差异问题。Claude Code 的提示词链路对模型跟着终端输出做工具调用的要求很高如果目标模型不支持足够长的上下文或工具调用能力弱就会出现“看不到输出”或者“不敢调用工具”的情况。我的经验是先用小任务验证模型能否正确读懂终端输出的纯文本再逐渐放权让它执行更多步骤。4.3 VSCode 联动与桌面版差异在 VSCode 里我会把终端服务跑成一个独立进程然后在 VSCode 终端里手动claude启动控制。VSCode 的 Claude Code 插件也支持加载项目级.mcp.json这样在编辑器的图形界面里就能看到我的终端会话列表。唯一要留意的是 VSCode 集成终端本身也有 PTY 层如果插件控控制台和我的终端服务同时尝试操作同一个 shell会产生资源竞争。所以我的建议是在 VSCode 里只使用插件面板接入 MCP 工具而把真实 shell 交给我自己的服务。Claude Code 桌面版和命令行版的接入逻辑不太一样。桌面版自带一套账户管理和界面同样能配置 MCP Server但它的运行环境是打包好的配置文件路径不同。遇到问题时先claude doctor或者检查桌面版商店里的设置页别急着去改全局配置。5. 常见问题与排查实录5.1 常见问题速查表这一节整理几个我在写终端过程中被问得最多、也踩得最多的坑。现象可能原因解决方向右键菜单没有“在终端打开”系统未正确注册终端模拟器或扩展未启用检查终端应用是否安装完整macOS 可在系统设置里重置默认终端gnome 环境用gnome-terminal或安装nautilus-open-terminal执行命令后拿到的输出全是颜色字符没剥离 ANSI 转义序列在输出处理层增加 ANSI 清洗保存两份视图Agent 写入的中文命令乱码字符编码不一致统一 PTY 内部编码为 UTF-8Windows 下设置代码页为 65001CtrlC发不进进程把信号当普通输入写入 PTY用 PTY 的信号方法发送VINTR通常是写\x03并配合signal系统调用两个 Agent 同时输入导致命令拼接缺少会话锁加入写锁 命令队列禁止并行写入同一会话会话长时间不输出但进程活着可能是进程在等待输入或打印到 stderr增加 read 轮询同时读 stdout/stderr超时返回部分输出并标记Claude Code 提示版本太旧npm 包没更新执行官方支持的全新安装命令重新安装最新版本VSCode 解释器与终端版本不一致环境变量在不同终端里初始化路径不同在settings.json或终端 profile 中显式指定解释器路径新装 Claude Code 后提示区域不支持地域可用性限制以官方文档支持范围为准按官方渠道处理账号与安装多会话后端服务在 Linux 上不能新建 PTY/dev/pts未挂载容器内检查设备挂载或启动容器时加--privileged并确保tty开启5.2 印象最深的三个坑第一个坑是回车换行。在 PTY 中shell 默认会把换行符转换成\r\n如果你直接用\n解析看起来很多行顺序是对的但一旦遇到\r没处理好的文本模型读取时就会在段落中间多出换行。这个坑花了很久才定位到因为终端显示上完全正常只有把原始字节 dump 出来才看到 CR 和 LF 的混排。第二个坑是进度条类输出。执行npm install或者docker pull时终端会反复输出\x1b[2K清行和回车回滚缓冲如果按行存储会被刷出几十个半行状态。最终 Agent 读到的可能是一堆重复的阶段行。我的解法是在存储回滚缓冲时对连续的重绘刷新进行合并只在最终帧稳定的情况下才写入历史记录。第三个坑是 shell 提示符本身。zsh 或 bash 的提示符里如果混入了转义序列或者包含动态信息例如 Git 分支那么它在回滚缓冲里会占不少字符甚至干扰命令边界的判定。后来我给 shell 设置了一个干净的专用提示符PS1[ai-terminal]$ 并在记录回滚时把提示符行自动过滤。这个小改动让 Agent 读取输出的准确率大幅提升。5.3 给新手的几点建议如果你也想做类似的事情我的建议是不要一上来就贪大求全。先用script命令记录终端输出来模拟 PTY或者直接用一个现成的 PTY 库写一个最小服务能跑通ls、pwd、git status就足够了。之后再慢慢加回滚、加多会话、加 MCP 接入。给 Agent 写终端本质上是“把终端协议变成数据处理管道”的过程先把管道打通再谈调度。另外读回滚缓冲时记得控制返回给模型的体积。默认一屏是 24 行 x 80 列可 Agent 一次取 2000 行文本很容易浪费上下文窗口。我给read_output加了一个from_line和max_lines参数让模型按需翻页。写在最后这段开发经历最大的收获不是某个具体功能而是我终于逼自己把终端协议从“会用”理解到了“能实现”的层次。PTY 的细节、ANSI 转义的解析、TTY 信号的处理这些曾经被视为底层的领域在 Agent 时代反而成了构建自动化能力的关键基础设施。最后再分享一个小技巧你的终端会话回滚缓冲其实是一个极好的“项目状态快照”。我会在每次 Claude Code 运行完一个重要任务后把read_output的结果追加写入一个session.log第二天或者下一轮 Agent 启动时直接让它先读这个日志再工作效果比任何手写总结都可靠。如果你也正在搞 Agent 自动化强烈建议试试这个做法。
说句实话最近这几个月我写的代码里最值回票价的就是这个给 AI Agent 私有定制的终端。它解决的事情一句话能讲明白让 Claude Code 能直接操控我机器上的真实终端并且我还能同时拉多个 Agent 一起干活互不抢键盘、互相不搅乱会话。这个终端不是传统意义上给人类用的终端模拟器而是给 Agent 当“手脚”的终端服务。核心诉求拆开就三条第一Claude Code 要能执行任意终端命令并读到输出第二终端会话要能长期复用不要每条命令都从头开一个 shell环境变量、当前目录、历史状态全丢了第三多个 Agent 可以同时接入每个 Agent 有自己的会话上下文也可以按需共享同一个终端画面。我把这套东西用 Rust 从头写了一遍底层走 PTY对外暴露成可供 Claude Code 调用的工具服务。今天这篇就是把思路、架构、关键代码、踩坑记录都摊开来讲。1. 项目背景与核心需求拆解1.1 原生能力的最大痛点命令执行是一次性的先聊一个很多人刚接触 Claude Code 都会遇到的落差。它本身是有 Bash 工具能力的你可以直接让它“帮我跑一下npm run test”它也能执行。但它的默认执行模型是起一个临时 shell执行命令拿回 stdout/stderr然后 shell 就销毁了。这在简单场景下没问题可一旦涉及长时间运行的进程、交互式命令、或者需要保持某个工作目录反复操作的场景就非常难受。举个具体例子。我想让 Agent 帮我调试一个后端服务需要先后执行export MY_ENVxxx、cd /project/service、启动服务、然后看日志。如果用 Claude Code 原生的命令工具每一条命令都是独立的进程环境变量不共享当前目录不保留服务开了之后 Agent 甚至没法按CtrlC去正确中断它。你需要在每一条提示词里把绝对路径和环境变量再重申一遍这体验基本属于“能用但反人类”。交互式命令就更别想了。你想让 Agent 用vim改文件、用htop看负载、甚至操作redis-cli的交互模式原生工具链直接抓瞎。它的能力模型是“命令输入 输出返回”而真实终端是一个双向流式的交互环境会输出颜色转义序列会等待用户按键会有后台任务。所以本质上Agent 缺的不是执行命令的能力而是一个和人类一样握在手里的终端句柄。1.2 需求清单一个终端要能扛住三件事我在项目初期把需求收敛成三条硬性功能其余都算加分项命令执行Agent 能向终端写入任意命令并且拿到结构化或者纯文本化的完整输出。注意是“任意”包括带管道、带重定向、带交互式循环的复合命令。会话复用每个终端会话是常驻的 PTY 进程Agent 可以跨多次工具调用反复读写同一个会话。当前目录、环境变量、PATH 都保持连续性就像你每次把终端窗口放在那里不动只是有人代替你在敲键盘。多 Agent 调度系统要能创建多个会话允许不同的 Agent 分别持有不同会话也可以允许多个 Agent 共同操作一个会话需要加锁和队列。更关键的是会话之间互相隔离不能出现两个 Agent 的输出交错污染。第三点是我特别看重的。很多人都说“多 Agent 协调”是未来但真正上手时你会发现多 Agent 最大的麻烦根本不是模型能力而是共享资源的管理。终端就是这个共享资源里最容易被搞乱的一类。1.3 为什么现成方案都差点意思在决定从零写之前我花了不少时间审视现成工具。比如 tmux它确实是终端复用界的标准答案能起窗格、能 detach、能恢复会话但它面向的是人不是 Agent。它没有一个清晰的“命令执行 返回结果”的工具协议Agent 要操作 tmux要么通过tmux send-keys这种字符串拼凑要么就得自己解析 pane 里输出的内容。解析状态还是得自己造轮子。还有一类方案是网页终端比如 ttyd、wetty 这类它们能把终端丢到浏览器里。问题是它们的设计目标是给人用的远程终端交互协议基于 websocket 的即时按键流Agent 调用起来不够结构化——Agent 需要的不是“像人一样按每个键”而是一个可以“输入一行命令、拿回一批输出”的稳定接口。终端模拟器类项目比如 tabby 我也研究过。tabby 是非常优秀的终端应用它的标签页管理、会话组织、主题系统都值得参考但它归根结底是 GUI 程序不是一个可以被第三方程序通过本地接口操作的终终端服务。我想要的是把 tabby 这种“多标签会话有序管理”的思想抽出来做成一个 headless 的、能被 Claude Code 通过工具协议调用的终端服务。这部分后面会细说。所以结论很清晰要满足 Agent 的终端操控需求就必须自建一层“终端编排层”。它介于 Agent 和系统的 shell 之间负责创建 PTY、维护会话、解析输出、分发输入。2. 核心架构设计与关键选型2.1 整体架构控制平面与数据平面整个系统的设计我分成了两个平面。控制平面负责会话管理、Agent 身份识别、任务调度数据平面负责 PTY 的读写、输出捕获、事件通知。从上层往下看大致是这样一条链路调用方Claude Code 通过 MCPModel Context Protocol工具调用我的终端服务或者直接 HTTP 调用。接入层接收工具请求解析参数比如“向会话 3 写入命令ls -la等待输出”。会话管理器找到或创建对应会话把这次写操作放入该会话的命令队列防止并发写冲突。PTY 进程层每个会话对应一个真实的伪终端进程默认 shell 可以选 zsh/bash/powershell。输出处理模块轮询或异步读取 PTY 输出剥离 ANSI 颜色码同时把完整的回滚缓冲存进环形队列供 Agent 按需查询。数据平面最麻烦因为终端输出是持续的、无序的、带有大量控制字符的。你没法保证“写一条命令就能精确拿到这条命令对应的输出”因为进程可能是异步的、可能输出了一屏幕日志、可能在等待输入。所以我的设计里加了一个“命令边界”的概念Agent 写命令时我会先写入一个唯一的标记串然后持续读取输出直到在输出流里再次看到这个标记串或者达到超时时间。这就模仿了人类在终端里执行的“敲命令、等输出”的过程。2.2 为什么选 Rust内存安全、并发、和单文件交付选型阶段我对比过 Go、Node.js 和 Rust。Node.js 写事件 I/O 确实快但要在生产环境做 PTY 的原生绑定时控制底层文件描述符和进程信号总觉得隔着一层。Go 的并发模型很棒编译产物也干净但 Windows 下的 PTY 支持ConPTY绑定不如 Rust 生态里现成的库顺手。最终选 Rust理由有三个内存安全 多线程操作同一个金融级缓冲时不用担心野指针。终端数据处理本质上是多生产者单消费者的模型Rust 的所有权和通道机制能把这个模型表达得非常干净。tokioportable-pty让我既能做异步 I/O又能跨平台创建 PTY。Rust 生态里的portable-pty库是我目前看到对跨平台 PTY 封装得最优雅的库Linux/macOS 走/dev/ptsWindows 走 ConPTY上层代码基本不用改。编译成单二进制部署。一个ai-terminald二进制扔到服务器上直接跑不需要 Node 运行时不需要 Python 虚拟环境。我用一个类比给团队讲过这个设计给 Agent 写终端就像给机器人装遥控器。这个遥控器本身不需要屏幕但需要一个稳定的信号通道、一个按键队列、和一根能随时连接任意机器的电缆。Rust 恰好能把“通道 队列 电缆”做得又小又稳。2.3 借鉴 tabby 的会话管理思想tabby 的交互设计里有两点让我很受启发。第一是它把每个终端标签页当作一个独立会话单元切换标签页就是切换会话会话的生命周期跟标签页绑定第二是它提供了全局搜索和回滚浏览让我感觉“终端的过去是可以被翻阅的”。我决定把这个思想抽出来加一层 Agent 视角。在我的系统里每个会话也有一份回滚缓冲但我不只是让人类翻阅而是让 Agent 通过工具调用主动查询get_terminal_history(session_id, since_line)。这样 Claude Code 可以一直看到它在运行某个长任务期间遗漏的日志输出。这其实是把“人类在终端窗口里往上滚动”这一步变成了机器可调用的 API。2.4 工具调用协议让 Claude Code 理解终端要让 Claude Code 调用我的终端服务最自然的方式不是写一堆 prompt 让模型去猜而是把能力做成标准工具。目前我是用 MCP 协议暴露的同时也保留一个 HTTP JSON 接口做调试和兼容。MCP 工具定义大致会暴露这几类能力spawn_session创建新会话参数包括 shell 类型、工作目录、窗口尺寸。exec_command向会话写入单行命令等待输出返回。send_signal向会话发送CtrlC、CtrlD之类的信号。read_output读取指定会话的回滚缓冲。list_sessions列出所有活动会话。destroy_session强制结束一个会话。用 MCP 的好处是 Claude Code 原生支持而且模型会自动依据工具的 description 决定何时调用、传什么参数。我只需要在配置里指向自己写的 MCP server 即可。3. 实操从零搭建这个终端服务3.1 环境准备与第一版依赖我的开发环境主力是 macOS Linux 服务器兼顾 Windows 测试。Rust 工具链直接用官方 stable 版本即可需要把tokio、portable-pty、serde_json、towerHTTP 层加入依赖。安装 Claude Code 本身也很简单。macOS 或者 Linux 下最常用的做法是打开终端执行官方给出的安装命令。安装完成后执行claude --version能看到版本号就算成功。Windows 上也能用但要注意它默认依赖的操作 shell 是 PowerShell这和 macOS/Linux 的体验稍有差异。如果你在 Ubuntu 下配置注意先确认 Node 运行时版本满足官方要求因为 Claude Code 本体是 npm 包分发的不过也有桌面版安装包可以直接使用。这里必须多说一句关于地区可用性的问题。新装的时候如果有人遇到类似“not available in your country”的提示我的建议只有一个以官方文档列出的支持范围为准走官方支持的渠道配好账号和环境。不要去尝试任何绕过限制的办法合规使用才是长期能稳定跑项目的前提。3.2 核心模块创建 PTY 并接管输入输出代码上最关键的一段是创建 PTY 然后拿到读写句柄。portable-pty的使用方式非常直观先构造一个native_pty_system()再创建命令。use portable_pty::{CommandBuilder, native_pty_system, PtySize}; use std::sync::Arc; use tokio::io::{AsyncReadExt, AsyncWriteExt}; use tokio::sync::Mutex; pub struct TerminalSession { pub id: String, pub writer: ArcMutexBoxdyn std::io::Write Send, // 回滚缓冲存放最近 N 行纯文本输出 pub buffer: ArcMutexVecString, } pub fn create_pty_session(id: String, cwd: str, rows: u16, cols: u16) - ResultTerminalSession, Boxdyn std::error::Error { let pty_system native_pty_system(); let mut cmd CommandBuilder::new(zsh); cmd.cwd(cwd); cmd.env(TERM, xterm-256color); let pair pty_system.openpty(PtySize { rows, cols, pixel_width: 0, pixel_height: 0 })?; let child pair.slave.spawn_command(cmd)?; drop(child); // 子进程后续由 PTY 持有这里只需要读写端 let writer pair.master.try_clone_writer()?; let reader pair.master.try_clone_reader()?; // 启动读循环把输出解析后写入回滚缓冲 tokio::spawn(async move { let mut reader reader; let mut buf [0u8; 4096]; // 这里需要把字符串按 UTF-8 边界处理避免截断乱码 let mut left Vec::new(); loop { match reader.read(mut buf).await { Ok(0) | Err(_) break, Ok(n) { left.extend_from_slice(buf[..n]); // 简单处理按 UTF-8 边界截断后转 String // 实际项目里应该用 lossy 转换 保留残留字节 let s String::from_utf8_lossy(left); // 此处应剥离 ANSI并把完整行 push 到 buffer } } } }); Ok(TerminalSession { id, writer: Arc::new(Mutex::new(writer)), buffer: Arc::new(Mutex::new(Vec::new())) }) }注意几个关键点。第一slave.spawn_command返回的child是需要持有的如果直接drop子进程不会死因为会话端仍然持有文件描述符但如果想跟踪进程退出状态最好单独保存。第二cwd参数会被 shell 当作启动目录所以 Agent 完全可以指定某个项目目录作为会话的家。第三TERMxterm-256color是为了让大部分终端程序正确输出颜色和交互控制码。3.3 输出处理ANSI 转义与回滚缓冲这是全项目里最容易阴沟翻船的地方。终端输出并不是干净的文本而是带一堆转义序列。比如当你执行ls时输出里可能包含高亮颜色码\x1b[38;5;27m如果你直接把原始字节传给模型模型会被这些控制字符干扰导致“看得到但读不懂”。所以我做了一个清洗层。保留原始字节流给人类查日志用同时生成一份“纯文本视图”给 Agent。纯文本视图要做的事有移除 ANSI 颜色和样式序列比如\x1b[0m、\x1b[1;31m。处理光标控制移动序列比如\x1b[1A光标上移一行否则最终文本的行序会错乱。处理回车符和退格符尤其是进度条场景。一个常见的坑是top这类全屏交互程序会不断用转义序列重绘整个界面回滚缓冲里全是“垃圾”。我的处理方案是对 Agent 读取输出时只读取“当前静态帧”而不是流式全文。具体来说当 Agent 调用exec_command执行一条命令并等待返回时我会在命令结束或超时时从回滚缓冲里取出从命令写入点到当前时刻新增的行并做一次重绘压缩。这样至少能保证 Agent 拿到的不是满屏的重复帧。3.4 命令边界标记与超时策略让 Agent“写命令→拿输出”这种轮询式交互核心难题是知道“当前命令的输出到哪了”。我采用的最朴素但有效的方案就是写边界标记。echo \n__CMD_DONE_MARKER_${RANDOM}_${RANDOM}__我先向 PTY 写入用户要执行的命令再单独另起一行写入这个echo标记然后持续读取 PTY 输出直到读取内容里出现这个标记串。标记出现在输出里意味着上一条命令已经执行完shell 已经回到提示符状态之后的输出是干净的新输入。这个技巧解决了我 80% 的命令边界问题但它有一个缺限如果命令本身输出过同样的标记内容或者命令卡住了不返回就失效了。所以必须配合超时。超时策略我按命令类型做了区分。简单命令默认 10 秒编译类命令给 60 秒长任务命令支持调用方显式传wait_for_seconds。一旦超时我不会直接杀掉进程而是返回截止到超时时刻的部分输出并附带一个timeout: true标志。这样 Claude Code 可以自己决定是继续等待、发CtrlC还是再调一次read_output查后续输出。3.5 多 Agent 并发调度多 Agent 同时指向同一个终端的场景最大的风险是输入互相覆盖。两个 Agent 同时执行exec_command一个写cd /app另一个写rm -rf build最终 shell 收到的可能是一条拼接起来的乱命。我的方案是给每个会话加一个带“归属标识”的命令队列。所有权模型很简单一个会话默认只允许一个 Agent 持有“操作权”其他 Agent 的写入请求会排队。如果业务上确实需要多个 Agent 协作同一个会话可以显式开启共享模式共享模式下每条命令都会附加上来源 Agent 的标识并且对写操作加锁。输出侧呢我会给每批输出加上起始标记这样不同 Agent 执行互不干扰。实际开发里我还加了“任务编排”的概念。你可以通过 HTTP 接口一次提交多个任务比如“Agent A 负责准备环境Agent B 负责跑测试Agent C 负责汇总日志”调度器会为每个 Agent 分配独立会话并把最终各会话的结果汇总到你指定的输出文件里。这算是我个人对“多 Agent 指挥”这个需求的实现雏形。4. Claude Code 接入与命令执行配置4.1 让 Claude Code 真正“操控”终端并不是所有场景都需要自己写 MCP Server。先说一种轻量思路Claude Code 自带 Bash 工具你可以在提示词里让它“通过 Bash 工具运行命令”它确实能执行。但如果你想让它操作我们的常驻会话就需要把 MCP Server 接上。把你编译好的二进制启动成本地监听模式然后配置 Claude Codeclaude mcp add ai-terminal --transport stdio --command /usr/local/bin/ai-terminald -- --mcp或者用项目级配置文件.mcp.json{ mcpServers: { ai-terminal: { command: /usr/local/bin/ai-terminald, args: [--mcp], env: { LOG_LEVEL: info } } } }配置好后你在 Claude Code 里发起一个新会话它就能看到spawn_session、exec_command、send_signal这一组工具。接下来你可以直接跟它说“帮我在项目目录开一个会话然后运行make build如果遇到报错就读取滚动缓冲里的内容分析后修复再跑。”它会自动决定如何组合这些工具。4.2 接入第三方模型DeepSeek、Qwen、GLM 的兼容层因为项目主要围绕 Claude Code但实际团队里有人没有合适的环境或者想要更低的调用成本换来换去很麻烦。这时接入第三方模型就很有价值。目前 Claude Code 支持通过环境变量指认 API 路由层这本质上就是兼容 Anthropic API 格式的任意服务。我常用的方式是使用一个叫 CC Switch 的社区工具来切换模型供应商。它本质上是维护一个配置文件在启动 Claude Code 前设置好ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN这两个环境变量。比如接入 DeepSeek 时指向它的 Anthropic 兼容端点Qwen 就指向阿里云 DashScope 的兼容端点GLM 则指向智谱的兼容端点。三者都是国内大模型 API 的合法使用场景。切换之后要注意一个模型能力差异问题。Claude Code 的提示词链路对模型跟着终端输出做工具调用的要求很高如果目标模型不支持足够长的上下文或工具调用能力弱就会出现“看不到输出”或者“不敢调用工具”的情况。我的经验是先用小任务验证模型能否正确读懂终端输出的纯文本再逐渐放权让它执行更多步骤。4.3 VSCode 联动与桌面版差异在 VSCode 里我会把终端服务跑成一个独立进程然后在 VSCode 终端里手动claude启动控制。VSCode 的 Claude Code 插件也支持加载项目级.mcp.json这样在编辑器的图形界面里就能看到我的终端会话列表。唯一要留意的是 VSCode 集成终端本身也有 PTY 层如果插件控控制台和我的终端服务同时尝试操作同一个 shell会产生资源竞争。所以我的建议是在 VSCode 里只使用插件面板接入 MCP 工具而把真实 shell 交给我自己的服务。Claude Code 桌面版和命令行版的接入逻辑不太一样。桌面版自带一套账户管理和界面同样能配置 MCP Server但它的运行环境是打包好的配置文件路径不同。遇到问题时先claude doctor或者检查桌面版商店里的设置页别急着去改全局配置。5. 常见问题与排查实录5.1 常见问题速查表这一节整理几个我在写终端过程中被问得最多、也踩得最多的坑。现象可能原因解决方向右键菜单没有“在终端打开”系统未正确注册终端模拟器或扩展未启用检查终端应用是否安装完整macOS 可在系统设置里重置默认终端gnome 环境用gnome-terminal或安装nautilus-open-terminal执行命令后拿到的输出全是颜色字符没剥离 ANSI 转义序列在输出处理层增加 ANSI 清洗保存两份视图Agent 写入的中文命令乱码字符编码不一致统一 PTY 内部编码为 UTF-8Windows 下设置代码页为 65001CtrlC发不进进程把信号当普通输入写入 PTY用 PTY 的信号方法发送VINTR通常是写\x03并配合signal系统调用两个 Agent 同时输入导致命令拼接缺少会话锁加入写锁 命令队列禁止并行写入同一会话会话长时间不输出但进程活着可能是进程在等待输入或打印到 stderr增加 read 轮询同时读 stdout/stderr超时返回部分输出并标记Claude Code 提示版本太旧npm 包没更新执行官方支持的全新安装命令重新安装最新版本VSCode 解释器与终端版本不一致环境变量在不同终端里初始化路径不同在settings.json或终端 profile 中显式指定解释器路径新装 Claude Code 后提示区域不支持地域可用性限制以官方文档支持范围为准按官方渠道处理账号与安装多会话后端服务在 Linux 上不能新建 PTY/dev/pts未挂载容器内检查设备挂载或启动容器时加--privileged并确保tty开启5.2 印象最深的三个坑第一个坑是回车换行。在 PTY 中shell 默认会把换行符转换成\r\n如果你直接用\n解析看起来很多行顺序是对的但一旦遇到\r没处理好的文本模型读取时就会在段落中间多出换行。这个坑花了很久才定位到因为终端显示上完全正常只有把原始字节 dump 出来才看到 CR 和 LF 的混排。第二个坑是进度条类输出。执行npm install或者docker pull时终端会反复输出\x1b[2K清行和回车回滚缓冲如果按行存储会被刷出几十个半行状态。最终 Agent 读到的可能是一堆重复的阶段行。我的解法是在存储回滚缓冲时对连续的重绘刷新进行合并只在最终帧稳定的情况下才写入历史记录。第三个坑是 shell 提示符本身。zsh 或 bash 的提示符里如果混入了转义序列或者包含动态信息例如 Git 分支那么它在回滚缓冲里会占不少字符甚至干扰命令边界的判定。后来我给 shell 设置了一个干净的专用提示符PS1[ai-terminal]$ 并在记录回滚时把提示符行自动过滤。这个小改动让 Agent 读取输出的准确率大幅提升。5.3 给新手的几点建议如果你也想做类似的事情我的建议是不要一上来就贪大求全。先用script命令记录终端输出来模拟 PTY或者直接用一个现成的 PTY 库写一个最小服务能跑通ls、pwd、git status就足够了。之后再慢慢加回滚、加多会话、加 MCP 接入。给 Agent 写终端本质上是“把终端协议变成数据处理管道”的过程先把管道打通再谈调度。另外读回滚缓冲时记得控制返回给模型的体积。默认一屏是 24 行 x 80 列可 Agent 一次取 2000 行文本很容易浪费上下文窗口。我给read_output加了一个from_line和max_lines参数让模型按需翻页。写在最后这段开发经历最大的收获不是某个具体功能而是我终于逼自己把终端协议从“会用”理解到了“能实现”的层次。PTY 的细节、ANSI 转义的解析、TTY 信号的处理这些曾经被视为底层的领域在 Agent 时代反而成了构建自动化能力的关键基础设施。最后再分享一个小技巧你的终端会话回滚缓冲其实是一个极好的“项目状态快照”。我会在每次 Claude Code 运行完一个重要任务后把read_output的结果追加写入一个session.log第二天或者下一轮 Agent 启动时直接让它先读这个日志再工作效果比任何手写总结都可靠。如果你也正在搞 Agent 自动化强烈建议试试这个做法。
