1. 从一条命令说起为什么要给 AI Agent 造一个终端最早用 Claude Code 的时候我的工作流其实很原始开一个终端窗口跑 Claude Code再开一个窗口手动敲命令两边来回切。它说你执行一下 npm run build我复制粘贴过去它说看一下这个报错我再把输出贴回去。一天下来手指在 CmdTab 上按到发酸脑子里的上下文被切得七零八落。后来我想明白一件事AI Agent 的能力上限很大程度上不取决于模型本身而取决于它能看到和操作多少真实环境。模型再聪明如果只能靠人肉搬运终端输出那它永远是个隔着玻璃指挥的顾问而不是能下场干活的工程师。Claude Code 本身已经能直接执行终端命令了但它的执行是一次性的——跑一条、拿结果、再跑下一条中间没有持久会话也没法同时管好几个任务。这就是我动手写这个终端项目的起点。核心目标有三个第一让 Claude Code 能真正操控一个持久化的终端会话而不是每次从零开始第二支持同时指挥多个 Agent各干各的互不干扰第三整个交互走 MCPModel Context Protocol协议让 Agent 和终端之间的通信标准化、可扩展。说白了我要的不是一个更好看的终端而是一个给 Agent 用的终端——它的第一用户是 AI第二用户才是我。这个定位一变整个设计思路就完全不同了。传统终端优化的是人的输入效率而这个终端优化的是 Agent 的上下文获取效率和并发调度能力。如果你也在做 Agent 开发或者天天和 Claude Code 打交道被复制粘贴终端输出这件事折磨过那这套思路应该对你有用。下面我把整个设计、实现和踩过的坑完整拆一遍。2. 整体架构设计Agent、终端与 MCP 的三方协作2.1 为什么是 MCP而不是自己写一套 RPC一开始我考虑过自己定义一套 JSON-RPC 协议Agent 通过 HTTP 调终端服务。但很快放弃了原因很实际Claude Code 原生支持 MCP我不需要重新发明轮子。MCP 是什么简单说它是 Anthropic 主导的一套标准协议让 AI 模型能以统一的方式调用外部工具和数据源。你可以把它理解成AI 世界的 USB 接口——只要你的服务实现了 MCP任何支持 MCP 的客户端Claude Code、各种 IDE 插件、自研 Agent 框架都能直接接入不用为每个客户端单独适配。这个选择带来的好处是复利式的。我写完这个终端 MCP Server 之后不光 Claude Code 能用任何接了 MCP 的工具都能用。后来我把它接到 VS Code 的 Claude Code 插件里几乎零改动就跑通了。如果当初自己写 RPC每接一个新客户端都得改一遍代码。提示MCP 的核心价值在于一次实现处处可用。做 Agent 工具时优先考虑 MCP 而不是私有协议长期维护成本会低很多。2.2 三层结构会话层、执行层、协议层整个系统我拆成了三层每层职责清晰方便单独调试和替换。会话层Session Layer负责管理多个终端会话的生命周期。每个会话是一个独立的 PTY伪终端有自己的工作目录、环境变量、进程树。这一层的关键是隔离——Agent A 在跑前端构建Agent B 在跑数据库迁移两者的输出不能串味。执行层Execution Layer负责真正把命令送进 PTY并把输出捕获回来。这里最麻烦的是怎么判断一条命令执行完了。终端不像函数调用有明确的返回值你得靠提示符、退出码、超时等多种信号综合判断。协议层Protocol Layer就是 MCP Server 本身把会话和执行能力暴露成标准工具tool供 Agent 调用。这一层要做参数校验、权限控制、结果格式化。三层之间通过内部接口通信我特意让执行层不依赖 MCP这样即使以后换协议执行逻辑也不用动。2.3 技术选型为什么用 Rust 写核心热词里基于 Rust 语言 AI Agent出现频率很高我确实选了 Rust 来做核心执行层。理由有三个第一PTY 操作是系统级编程涉及 fork、exec、文件描述符管理Rust 的nixcrate 对这些封装得很干净而且内存安全不会出现 C 里那种 fd 泄漏导致终端卡死的问题。第二并发模型。多个 Agent 同时操作多个终端需要高并发且低开销。Rust 的 async/await 配合 tokio处理几十个并发会话毫无压力而且没有 GC 停顿输出捕获的延迟很稳定。第三单二进制分发。编译出来就是一个可执行文件扔到任何 Linux 服务器上就能跑不用装运行时。这对部署到远程开发机特别友好。当然MCP Server 的外层我用 TypeScript 写因为官方 SDK 是 TS 的生态最成熟。核心执行层用 Rust 编译成二进制通过 stdio 和 TS 层通信。这种混合架构听起来复杂实际上边界很清晰各取所长。3. 核心细节解析PTY、会话隔离与输出捕获3.1 伪终端PTY到底解决了什么问题很多人以为执行命令就是std::process::Command一把梭但那样跑出来的进程和真实终端里跑的是两回事。最典型的差异很多程序会检测自己是否运行在 TTY 里如果不是就关闭彩色输出、禁用交互式提示、改变缓冲策略。举个我踩过的坑用普通子进程跑npm run build输出是块缓冲的要等进程结束才一次性吐出来Agent 根本看不到实时进度。换成 PTY 之后输出变成行缓冲Agent 能一条条读到编译日志体验完全不同。PTY 的本质是一对虚拟设备master 端和 slave 端。子进程连着 slave表现得就像连着真实终端我在 master 端读写就能捕获所有输出、注入所有输入。Linux 上用posix_openpt、grantpt、unlockpt这一套Rust 的portable-ptycrate 把这些都封装好了。// 创建 PTY 对并启动 shell 的核心逻辑简化版 let pty_system native_pty_system(); let pair pty_system.openpty(PtySize { rows: 40, cols: 120, pixel_width: 0, pixel_height: 0, })?; let mut cmd CommandBuilder::new(bash); cmd.cwd(/workspace); let child pair.slave.spawn_command(cmd)?; // master 端用于读写 let mut reader pair.master.try_clone_reader()?; let mut writer pair.master.take_writer()?;注意rows和cols的设置。这个不是随便填的它决定了终端里程序的换行行为。如果设得太小ls输出会被截断成多行Agent 解析起来很痛苦设得太大某些程序又会输出超宽的行。我实测下来 120x40 是个比较平衡的值既能容纳大部分表格输出又不会让单行过长。3.2 会话隔离每个 Agent 一个独立世界多 Agent 场景下隔离是刚需。我见过太多两个 Agent 抢同一个终端导致的诡异 bugA 刚cd到某个目录B 一条命令把目录删了A 后续所有命令全崩。我的做法是每个会话一个独立 PTY 独立工作目录 独立环境变量表。会话创建时指定一个 ID后续所有操作都带上这个 ID路由到对应的 PTY。隔离维度实现方式不隔离的后果进程空间独立 PTY 独立 shell 进程一个 Agent 的kill误杀另一个的进程工作目录每会话独立 cwd 状态cd互相覆盖路径全乱环境变量会话级 env map一个改了 PATH另一个找不到命令输出流独立缓冲区输出串味Agent 读到别人的日志环境变量这块有个细节不能简单继承父进程的 env 就完事。因为 Agent 经常需要临时设置变量比如export API_KEYxxx然后跑命令。如果所有会话共享一份 env这个 export 会污染其他会话。所以我在会话层维护了一份 env 副本每次执行命令时动态注入。3.3 输出捕获怎么知道命令跑完了这是整个项目最难的部分没有之一。终端不像 HTTP 请求有明确的 response你怎么知道npm run build是跑完了还是在等输入我综合了四种信号按优先级判断信号一退出码。如果命令是前台执行且 shell 能拿到退出码这是最可靠的。但问题是在持久会话里命令是注入进去的shell 不会主动告诉你退出码除非你用特殊技巧。信号二提示符匹配。每个 shell 的提示符有固定格式我让会话启动时设置一个独特的提示符比如带随机 token 的PS1命令执行完提示符重新出现就说明结束了。这个方法很稳但遇到交互式程序比如vim、python的 REPL就失效了。信号三静默超时。如果一段时间内没有新输出就认为命令结束了。这个简单粗暴但对npm run dev这种持续输出的命令会误判。信号四显式标记。我在注入命令时会在末尾追加一个echo特殊标记比如echo __DONE_$RANDOM__。读到这个标记就确定命令结束了。实际实现里我用的是提示符 显式标记双保险配合一个可配置的超时兜底。对于明确知道是长驻进程的命令比如启动 dev serverAgent 可以显式声明这条命令不要等结束直接返回。注意不要只依赖超时判断命令结束。我早期版本用固定 5 秒超时结果pip install慢的时候被误判为结束Agent 拿到半截输出就开始分析闹了不少笑话。4. 实操过程从零搭起一个 Agent 终端4.1 环境准备与依赖安装先说环境。我主要在 Ubuntu 上开发macOS 也测过Windows 需要 WSL。核心依赖就几个# Rust 工具链 curl --proto https --tlsv1.2 -sSf https://sh.rustup.rs | sh # Node.js跑 MCP Server 外层 # 建议用 nvm 管理版本Node 18 nvm install 20 # 核心 Rust 依赖Cargo.tomlCargo.toml 里的关键依赖[dependencies] portable-pty 0.8 # PTY 操作 tokio { version 1, features [full] } # 异步运行时 serde { version 1, features [derive] } # 序列化 serde_json 1 anyhow 1 # 错误处理portable-pty是 WezTerm 团队维护的跨平台支持好比直接用nix省心很多。tokio 用 full feature 是因为要同时处理多个会话的读写需要完整的异步能力。MCP Server 外层用官方 SDKnpm install modelcontextprotocol/sdk4.2 会话管理器的实现要点会话管理器是整个系统的中枢我用一个HashMapSessionId, Session来维护所有活跃会话外面套一层ArcMutex保证并发安全。struct Session { id: String, pty_pair: PtyPair, child: Boxdyn Child Send, cwd: PathBuf, env: HashMapString, String, output_buffer: ArcMutexVecDequeString, last_activity: Instant, } struct SessionManager { sessions: ArcMutexHashMapString, Session, max_sessions: usize, }几个关键设计点输出缓冲区用VecDeque而不是Vec。因为 Agent 读取输出后旧数据要能高效移除VecDeque的pop_front是 O(1)Vec的remove(0)是 O(n)。会话跑久了缓冲区里可能积累几万行这个差异很明显。last_activity用于回收僵尸会话。Agent 有时候会忘记关闭会话我加了个后台任务定期扫描超过 30 分钟无活动的会话自动清理。不然跑一天下来几十个僵尸 PTY 挂着系统资源全被吃光。max_sessions做上限保护。默认 20 个防止某个失控的 Agent 疯狂创建会话把机器搞崩。4.3 命令注入与输出读取的完整流程一条命令从 Agent 发出到拿到结果完整走这么几步Agent 通过 MCP 调用execute_command传入session_id和command协议层校验参数路由到执行层执行层从会话管理器取出对应会话把命令 结束标记写入 PTY 的 master 端异步读取任务持续从 master 端读输出追加到缓冲区检测到结束标记或提示符停止读取把缓冲区内容格式化后返回给 Agent写入这一步有个坑必须处理换行符。不同 shell 对\n和\r\n的处理不一样我统一用\n并且在命令末尾确保只有一个换行否则会多执行一次空命令。// 注入命令 let full_command format!({}\necho \__DONE_{}__\\n, command, token); writer.write_all(full_command.as_bytes())?; writer.flush()?;读取这一步我用 tokio 的spawn起一个独立任务循环读 master 端读到数据就追加到缓冲区同时检查是否包含结束标记。tokio::spawn(async move { let mut buf [0u8; 4096]; loop { match reader.read(mut buf).await { Ok(0) break, Ok(n) { let chunk String::from_utf8_lossy(buf[..n]).to_string(); let mut buffer output_buffer.lock().await; buffer.push_back(chunk.clone()); if chunk.contains(done_marker) { break; } } Err(_) break, } } });提示from_utf8_lossy是必须的。终端输出里经常混着 ANSI 转义序列和非法 UTF-8 字节直接from_utf8会报错。用 lossy 版本把非法字节替换成占位符虽然会丢一点信息但不会让整个读取任务崩掉。4.4 多 Agent 并发调度的实操多 Agent 场景下我做了两层调度第一层是会话级隔离前面说过了每个 Agent 一个会话。第二层是命令级排队同一个会话内命令必须串行执行。因为终端本质是串行的你没法在同一个 shell 里同时跑两条命令除非用后台化但那样输出就乱了。我在会话里加了一个命令队列Agent 提交的命令进队列执行层按顺序取出执行。这样即使 Agent 并发提交多条命令也不会互相干扰。// 会话内的命令队列 struct Session { // ... command_queue: ArcMutexVecDequeCommand, is_busy: ArcAtomicBool, }实测下来这套机制能稳定支撑 10 个 Agent 同时工作每个 Agent 管一个会话各自跑各自的构建、测试、部署任务互不干扰。CPU 占用在 8 核机器上大概 30% 左右内存每个会话约 20MB很轻量。5. 常见问题与排查技巧实录5.1 命令卡住不返回怎么办这是最高频的问题。表现是 Agent 调用execute_command后一直等直到超时。排查思路按顺序来第一步确认是不是交互式程序。vim、top、less这类程序会一直占着终端等用户输入。解决办法是在命令前加非交互参数比如git --no-pager log、npm ci --no-audit。或者用yes |管道喂输入。第二步检查是不是在等输入。有些命令会弹[Y/n]确认Agent 看不到提示就一直等。我加了个检测如果输出末尾匹配到[Y/n]、password:、continue?这类模式就主动返回让 Agent 决定怎么处理。第三步看是不是死锁。如果命令本身没问题但 PTY 缓冲区满了写端没读进程会阻塞在 write 上。这种情况通常是读取任务挂了检查读取任务的日志。现象可能原因解决方式一直无输出交互式程序等待输入加非交互参数或喂输入输出到一半停住PTY 缓冲区满检查读取任务是否存活超时但命令实际在跑超时设置太短调大超时或声明为长驻命令返回乱码编码问题用 lossy 解码过滤 ANSI5.2 输出里混入 ANSI 转义序列终端输出里全是\x1b[32m这种颜色控制码Agent 读起来很痛苦还会浪费 token。我的处理是在返回给 Agent 之前做一次 ANSI 清洗。用一个正则把\x1b\[[0-9;]*[a-zA-Z]这类序列全部去掉。但要注意有些程序用 ANSI 做光标定位比如进度条直接删掉会留下重复内容。对这类我额外做了回车覆盖处理遇到\r就回到行首覆盖模拟真实终端行为。fn clean_ansi(input: str) - String { let re Regex::new(r\x1b\[[0-9;]*[a-zA-Z]).unwrap(); re.replace_all(input, ).to_string() }注意清洗 ANSI 会丢失颜色信息但对 Agent 来说颜色本来就没意义反而占 token。如果你需要保留颜色给人类看可以做成可选参数。5.3 会话泄漏与资源回收跑了一段时间后我发现系统里堆了一堆僵尸 PTYps aux一看全是bash进程。根因是 Agent 创建会话后如果任务异常中断没有调用关闭接口。我的解决方案是双保险主动回收后台任务每 5 分钟扫一次超过 30 分钟无活动的会话强制关闭先发SIGTERM5 秒后还在就SIGKILL。被动兜底MCP Server 进程退出时注册一个清理钩子把所有子进程杀掉。Rust 里可以用Droptrait 实现。impl Drop for Session { fn drop(mut self) { let _ self.child.kill(); let _ self.child.wait(); } }这个Drop实现救了我很多次。有次 MCP Server 崩溃重启所有旧会话自动清理没有留下任何僵尸进程。5.4 Agent 安全别让终端变成后门热词里agent安全是个绕不开的话题。给 Agent 一个能执行任意命令的终端本质上就是把机器的控制权交出去了。我做了几层防护命令白名单/黑名单。默认允许常见开发命令对rm -rf /、mkfs、dd这类危险命令直接拦截。黑名单不是万能的但能挡住大部分误操作。工作目录限制。会话的 cwd 被限制在指定根目录下cd ..超出范围会被拒绝。这个用路径规范化 前缀检查实现。资源限制。每个会话限制 CPU 时间和内存防止某个 Agent 跑个死循环把机器拖垮。Linux 上用setrlimit在 fork 之后、exec 之前设置。审计日志。所有执行的命令都记日志包括时间、会话 ID、命令内容、退出状态。出问题能追溯。提示安全防护要默认拒绝而不是默认允许。我一开始图省事只拦了几个明显危险的命令结果 Agent 用find / -delete把临时目录清了个干净。后来改成白名单模式只放行明确需要的命令世界清净了。6. 这套终端还能怎么扩展项目跑通之后我发现它的扩展空间比想象中大。接入更多 Agent 框架。因为走的是 MCP任何支持 MCP 的框架都能接。我试过把它接到自研的 Python Agent 上改了几行配置就跑通了。热词里提到的各种 Agent 框架只要支持 MCP理论上都能用。终端复用与共享。现在的会话是独占的但有些场景下多个 Agent 需要看同一个终端比如一个负责执行一个负责监控。我在设计一个只读订阅模式允许多个 Agent 订阅同一个会话的输出流但不注入命令。持久化与回放。把会话的完整输入输出录下来存成文件之后可以回放。这对调试 Agent 行为特别有用——你能精确看到 Agent 每一步看到了什么、做了什么。远程终端。现在跑在本地但架构上执行层和协议层是分离的把执行层部署到远程服务器协议层通过 SSH 隧道连过去就能实现本地 Agent 操控远程终端。这个我还在做主要难点是网络延迟下的输出同步。与 IDE 深度集成。VS Code 的 Claude Code 插件已经能用了但体验还比较粗糙。理想状态是 Agent 在 IDE 里直接操作集成终端输出实时显示在面板上人机可以随时接管。这个需要改插件工作量不小但值得做。我个人在实际操作中的体会是给 Agent 造工具最重要的不是功能多而是边界清晰、行为可预测。Agent 不像人它不会感觉不对劲就停下来所以工具本身必须把异常情况处理干净把危险操作拦在门外。这套终端我迭代了大概两个月大部分时间不是花在让它能跑而是花在让它跑得稳、跑得安全上。如果你也在做类似的东西建议一开始就把安全和资源回收设计进去不然后面补起来很痛苦。
1. 从一条命令说起为什么要给 AI Agent 造一个终端最早用 Claude Code 的时候我的工作流其实很原始开一个终端窗口跑 Claude Code再开一个窗口手动敲命令两边来回切。它说你执行一下 npm run build我复制粘贴过去它说看一下这个报错我再把输出贴回去。一天下来手指在 CmdTab 上按到发酸脑子里的上下文被切得七零八落。后来我想明白一件事AI Agent 的能力上限很大程度上不取决于模型本身而取决于它能看到和操作多少真实环境。模型再聪明如果只能靠人肉搬运终端输出那它永远是个隔着玻璃指挥的顾问而不是能下场干活的工程师。Claude Code 本身已经能直接执行终端命令了但它的执行是一次性的——跑一条、拿结果、再跑下一条中间没有持久会话也没法同时管好几个任务。这就是我动手写这个终端项目的起点。核心目标有三个第一让 Claude Code 能真正操控一个持久化的终端会话而不是每次从零开始第二支持同时指挥多个 Agent各干各的互不干扰第三整个交互走 MCPModel Context Protocol协议让 Agent 和终端之间的通信标准化、可扩展。说白了我要的不是一个更好看的终端而是一个给 Agent 用的终端——它的第一用户是 AI第二用户才是我。这个定位一变整个设计思路就完全不同了。传统终端优化的是人的输入效率而这个终端优化的是 Agent 的上下文获取效率和并发调度能力。如果你也在做 Agent 开发或者天天和 Claude Code 打交道被复制粘贴终端输出这件事折磨过那这套思路应该对你有用。下面我把整个设计、实现和踩过的坑完整拆一遍。2. 整体架构设计Agent、终端与 MCP 的三方协作2.1 为什么是 MCP而不是自己写一套 RPC一开始我考虑过自己定义一套 JSON-RPC 协议Agent 通过 HTTP 调终端服务。但很快放弃了原因很实际Claude Code 原生支持 MCP我不需要重新发明轮子。MCP 是什么简单说它是 Anthropic 主导的一套标准协议让 AI 模型能以统一的方式调用外部工具和数据源。你可以把它理解成AI 世界的 USB 接口——只要你的服务实现了 MCP任何支持 MCP 的客户端Claude Code、各种 IDE 插件、自研 Agent 框架都能直接接入不用为每个客户端单独适配。这个选择带来的好处是复利式的。我写完这个终端 MCP Server 之后不光 Claude Code 能用任何接了 MCP 的工具都能用。后来我把它接到 VS Code 的 Claude Code 插件里几乎零改动就跑通了。如果当初自己写 RPC每接一个新客户端都得改一遍代码。提示MCP 的核心价值在于一次实现处处可用。做 Agent 工具时优先考虑 MCP 而不是私有协议长期维护成本会低很多。2.2 三层结构会话层、执行层、协议层整个系统我拆成了三层每层职责清晰方便单独调试和替换。会话层Session Layer负责管理多个终端会话的生命周期。每个会话是一个独立的 PTY伪终端有自己的工作目录、环境变量、进程树。这一层的关键是隔离——Agent A 在跑前端构建Agent B 在跑数据库迁移两者的输出不能串味。执行层Execution Layer负责真正把命令送进 PTY并把输出捕获回来。这里最麻烦的是怎么判断一条命令执行完了。终端不像函数调用有明确的返回值你得靠提示符、退出码、超时等多种信号综合判断。协议层Protocol Layer就是 MCP Server 本身把会话和执行能力暴露成标准工具tool供 Agent 调用。这一层要做参数校验、权限控制、结果格式化。三层之间通过内部接口通信我特意让执行层不依赖 MCP这样即使以后换协议执行逻辑也不用动。2.3 技术选型为什么用 Rust 写核心热词里基于 Rust 语言 AI Agent出现频率很高我确实选了 Rust 来做核心执行层。理由有三个第一PTY 操作是系统级编程涉及 fork、exec、文件描述符管理Rust 的nixcrate 对这些封装得很干净而且内存安全不会出现 C 里那种 fd 泄漏导致终端卡死的问题。第二并发模型。多个 Agent 同时操作多个终端需要高并发且低开销。Rust 的 async/await 配合 tokio处理几十个并发会话毫无压力而且没有 GC 停顿输出捕获的延迟很稳定。第三单二进制分发。编译出来就是一个可执行文件扔到任何 Linux 服务器上就能跑不用装运行时。这对部署到远程开发机特别友好。当然MCP Server 的外层我用 TypeScript 写因为官方 SDK 是 TS 的生态最成熟。核心执行层用 Rust 编译成二进制通过 stdio 和 TS 层通信。这种混合架构听起来复杂实际上边界很清晰各取所长。3. 核心细节解析PTY、会话隔离与输出捕获3.1 伪终端PTY到底解决了什么问题很多人以为执行命令就是std::process::Command一把梭但那样跑出来的进程和真实终端里跑的是两回事。最典型的差异很多程序会检测自己是否运行在 TTY 里如果不是就关闭彩色输出、禁用交互式提示、改变缓冲策略。举个我踩过的坑用普通子进程跑npm run build输出是块缓冲的要等进程结束才一次性吐出来Agent 根本看不到实时进度。换成 PTY 之后输出变成行缓冲Agent 能一条条读到编译日志体验完全不同。PTY 的本质是一对虚拟设备master 端和 slave 端。子进程连着 slave表现得就像连着真实终端我在 master 端读写就能捕获所有输出、注入所有输入。Linux 上用posix_openpt、grantpt、unlockpt这一套Rust 的portable-ptycrate 把这些都封装好了。// 创建 PTY 对并启动 shell 的核心逻辑简化版 let pty_system native_pty_system(); let pair pty_system.openpty(PtySize { rows: 40, cols: 120, pixel_width: 0, pixel_height: 0, })?; let mut cmd CommandBuilder::new(bash); cmd.cwd(/workspace); let child pair.slave.spawn_command(cmd)?; // master 端用于读写 let mut reader pair.master.try_clone_reader()?; let mut writer pair.master.take_writer()?;注意rows和cols的设置。这个不是随便填的它决定了终端里程序的换行行为。如果设得太小ls输出会被截断成多行Agent 解析起来很痛苦设得太大某些程序又会输出超宽的行。我实测下来 120x40 是个比较平衡的值既能容纳大部分表格输出又不会让单行过长。3.2 会话隔离每个 Agent 一个独立世界多 Agent 场景下隔离是刚需。我见过太多两个 Agent 抢同一个终端导致的诡异 bugA 刚cd到某个目录B 一条命令把目录删了A 后续所有命令全崩。我的做法是每个会话一个独立 PTY 独立工作目录 独立环境变量表。会话创建时指定一个 ID后续所有操作都带上这个 ID路由到对应的 PTY。隔离维度实现方式不隔离的后果进程空间独立 PTY 独立 shell 进程一个 Agent 的kill误杀另一个的进程工作目录每会话独立 cwd 状态cd互相覆盖路径全乱环境变量会话级 env map一个改了 PATH另一个找不到命令输出流独立缓冲区输出串味Agent 读到别人的日志环境变量这块有个细节不能简单继承父进程的 env 就完事。因为 Agent 经常需要临时设置变量比如export API_KEYxxx然后跑命令。如果所有会话共享一份 env这个 export 会污染其他会话。所以我在会话层维护了一份 env 副本每次执行命令时动态注入。3.3 输出捕获怎么知道命令跑完了这是整个项目最难的部分没有之一。终端不像 HTTP 请求有明确的 response你怎么知道npm run build是跑完了还是在等输入我综合了四种信号按优先级判断信号一退出码。如果命令是前台执行且 shell 能拿到退出码这是最可靠的。但问题是在持久会话里命令是注入进去的shell 不会主动告诉你退出码除非你用特殊技巧。信号二提示符匹配。每个 shell 的提示符有固定格式我让会话启动时设置一个独特的提示符比如带随机 token 的PS1命令执行完提示符重新出现就说明结束了。这个方法很稳但遇到交互式程序比如vim、python的 REPL就失效了。信号三静默超时。如果一段时间内没有新输出就认为命令结束了。这个简单粗暴但对npm run dev这种持续输出的命令会误判。信号四显式标记。我在注入命令时会在末尾追加一个echo特殊标记比如echo __DONE_$RANDOM__。读到这个标记就确定命令结束了。实际实现里我用的是提示符 显式标记双保险配合一个可配置的超时兜底。对于明确知道是长驻进程的命令比如启动 dev serverAgent 可以显式声明这条命令不要等结束直接返回。注意不要只依赖超时判断命令结束。我早期版本用固定 5 秒超时结果pip install慢的时候被误判为结束Agent 拿到半截输出就开始分析闹了不少笑话。4. 实操过程从零搭起一个 Agent 终端4.1 环境准备与依赖安装先说环境。我主要在 Ubuntu 上开发macOS 也测过Windows 需要 WSL。核心依赖就几个# Rust 工具链 curl --proto https --tlsv1.2 -sSf https://sh.rustup.rs | sh # Node.js跑 MCP Server 外层 # 建议用 nvm 管理版本Node 18 nvm install 20 # 核心 Rust 依赖Cargo.tomlCargo.toml 里的关键依赖[dependencies] portable-pty 0.8 # PTY 操作 tokio { version 1, features [full] } # 异步运行时 serde { version 1, features [derive] } # 序列化 serde_json 1 anyhow 1 # 错误处理portable-pty是 WezTerm 团队维护的跨平台支持好比直接用nix省心很多。tokio 用 full feature 是因为要同时处理多个会话的读写需要完整的异步能力。MCP Server 外层用官方 SDKnpm install modelcontextprotocol/sdk4.2 会话管理器的实现要点会话管理器是整个系统的中枢我用一个HashMapSessionId, Session来维护所有活跃会话外面套一层ArcMutex保证并发安全。struct Session { id: String, pty_pair: PtyPair, child: Boxdyn Child Send, cwd: PathBuf, env: HashMapString, String, output_buffer: ArcMutexVecDequeString, last_activity: Instant, } struct SessionManager { sessions: ArcMutexHashMapString, Session, max_sessions: usize, }几个关键设计点输出缓冲区用VecDeque而不是Vec。因为 Agent 读取输出后旧数据要能高效移除VecDeque的pop_front是 O(1)Vec的remove(0)是 O(n)。会话跑久了缓冲区里可能积累几万行这个差异很明显。last_activity用于回收僵尸会话。Agent 有时候会忘记关闭会话我加了个后台任务定期扫描超过 30 分钟无活动的会话自动清理。不然跑一天下来几十个僵尸 PTY 挂着系统资源全被吃光。max_sessions做上限保护。默认 20 个防止某个失控的 Agent 疯狂创建会话把机器搞崩。4.3 命令注入与输出读取的完整流程一条命令从 Agent 发出到拿到结果完整走这么几步Agent 通过 MCP 调用execute_command传入session_id和command协议层校验参数路由到执行层执行层从会话管理器取出对应会话把命令 结束标记写入 PTY 的 master 端异步读取任务持续从 master 端读输出追加到缓冲区检测到结束标记或提示符停止读取把缓冲区内容格式化后返回给 Agent写入这一步有个坑必须处理换行符。不同 shell 对\n和\r\n的处理不一样我统一用\n并且在命令末尾确保只有一个换行否则会多执行一次空命令。// 注入命令 let full_command format!({}\necho \__DONE_{}__\\n, command, token); writer.write_all(full_command.as_bytes())?; writer.flush()?;读取这一步我用 tokio 的spawn起一个独立任务循环读 master 端读到数据就追加到缓冲区同时检查是否包含结束标记。tokio::spawn(async move { let mut buf [0u8; 4096]; loop { match reader.read(mut buf).await { Ok(0) break, Ok(n) { let chunk String::from_utf8_lossy(buf[..n]).to_string(); let mut buffer output_buffer.lock().await; buffer.push_back(chunk.clone()); if chunk.contains(done_marker) { break; } } Err(_) break, } } });提示from_utf8_lossy是必须的。终端输出里经常混着 ANSI 转义序列和非法 UTF-8 字节直接from_utf8会报错。用 lossy 版本把非法字节替换成占位符虽然会丢一点信息但不会让整个读取任务崩掉。4.4 多 Agent 并发调度的实操多 Agent 场景下我做了两层调度第一层是会话级隔离前面说过了每个 Agent 一个会话。第二层是命令级排队同一个会话内命令必须串行执行。因为终端本质是串行的你没法在同一个 shell 里同时跑两条命令除非用后台化但那样输出就乱了。我在会话里加了一个命令队列Agent 提交的命令进队列执行层按顺序取出执行。这样即使 Agent 并发提交多条命令也不会互相干扰。// 会话内的命令队列 struct Session { // ... command_queue: ArcMutexVecDequeCommand, is_busy: ArcAtomicBool, }实测下来这套机制能稳定支撑 10 个 Agent 同时工作每个 Agent 管一个会话各自跑各自的构建、测试、部署任务互不干扰。CPU 占用在 8 核机器上大概 30% 左右内存每个会话约 20MB很轻量。5. 常见问题与排查技巧实录5.1 命令卡住不返回怎么办这是最高频的问题。表现是 Agent 调用execute_command后一直等直到超时。排查思路按顺序来第一步确认是不是交互式程序。vim、top、less这类程序会一直占着终端等用户输入。解决办法是在命令前加非交互参数比如git --no-pager log、npm ci --no-audit。或者用yes |管道喂输入。第二步检查是不是在等输入。有些命令会弹[Y/n]确认Agent 看不到提示就一直等。我加了个检测如果输出末尾匹配到[Y/n]、password:、continue?这类模式就主动返回让 Agent 决定怎么处理。第三步看是不是死锁。如果命令本身没问题但 PTY 缓冲区满了写端没读进程会阻塞在 write 上。这种情况通常是读取任务挂了检查读取任务的日志。现象可能原因解决方式一直无输出交互式程序等待输入加非交互参数或喂输入输出到一半停住PTY 缓冲区满检查读取任务是否存活超时但命令实际在跑超时设置太短调大超时或声明为长驻命令返回乱码编码问题用 lossy 解码过滤 ANSI5.2 输出里混入 ANSI 转义序列终端输出里全是\x1b[32m这种颜色控制码Agent 读起来很痛苦还会浪费 token。我的处理是在返回给 Agent 之前做一次 ANSI 清洗。用一个正则把\x1b\[[0-9;]*[a-zA-Z]这类序列全部去掉。但要注意有些程序用 ANSI 做光标定位比如进度条直接删掉会留下重复内容。对这类我额外做了回车覆盖处理遇到\r就回到行首覆盖模拟真实终端行为。fn clean_ansi(input: str) - String { let re Regex::new(r\x1b\[[0-9;]*[a-zA-Z]).unwrap(); re.replace_all(input, ).to_string() }注意清洗 ANSI 会丢失颜色信息但对 Agent 来说颜色本来就没意义反而占 token。如果你需要保留颜色给人类看可以做成可选参数。5.3 会话泄漏与资源回收跑了一段时间后我发现系统里堆了一堆僵尸 PTYps aux一看全是bash进程。根因是 Agent 创建会话后如果任务异常中断没有调用关闭接口。我的解决方案是双保险主动回收后台任务每 5 分钟扫一次超过 30 分钟无活动的会话强制关闭先发SIGTERM5 秒后还在就SIGKILL。被动兜底MCP Server 进程退出时注册一个清理钩子把所有子进程杀掉。Rust 里可以用Droptrait 实现。impl Drop for Session { fn drop(mut self) { let _ self.child.kill(); let _ self.child.wait(); } }这个Drop实现救了我很多次。有次 MCP Server 崩溃重启所有旧会话自动清理没有留下任何僵尸进程。5.4 Agent 安全别让终端变成后门热词里agent安全是个绕不开的话题。给 Agent 一个能执行任意命令的终端本质上就是把机器的控制权交出去了。我做了几层防护命令白名单/黑名单。默认允许常见开发命令对rm -rf /、mkfs、dd这类危险命令直接拦截。黑名单不是万能的但能挡住大部分误操作。工作目录限制。会话的 cwd 被限制在指定根目录下cd ..超出范围会被拒绝。这个用路径规范化 前缀检查实现。资源限制。每个会话限制 CPU 时间和内存防止某个 Agent 跑个死循环把机器拖垮。Linux 上用setrlimit在 fork 之后、exec 之前设置。审计日志。所有执行的命令都记日志包括时间、会话 ID、命令内容、退出状态。出问题能追溯。提示安全防护要默认拒绝而不是默认允许。我一开始图省事只拦了几个明显危险的命令结果 Agent 用find / -delete把临时目录清了个干净。后来改成白名单模式只放行明确需要的命令世界清净了。6. 这套终端还能怎么扩展项目跑通之后我发现它的扩展空间比想象中大。接入更多 Agent 框架。因为走的是 MCP任何支持 MCP 的框架都能接。我试过把它接到自研的 Python Agent 上改了几行配置就跑通了。热词里提到的各种 Agent 框架只要支持 MCP理论上都能用。终端复用与共享。现在的会话是独占的但有些场景下多个 Agent 需要看同一个终端比如一个负责执行一个负责监控。我在设计一个只读订阅模式允许多个 Agent 订阅同一个会话的输出流但不注入命令。持久化与回放。把会话的完整输入输出录下来存成文件之后可以回放。这对调试 Agent 行为特别有用——你能精确看到 Agent 每一步看到了什么、做了什么。远程终端。现在跑在本地但架构上执行层和协议层是分离的把执行层部署到远程服务器协议层通过 SSH 隧道连过去就能实现本地 Agent 操控远程终端。这个我还在做主要难点是网络延迟下的输出同步。与 IDE 深度集成。VS Code 的 Claude Code 插件已经能用了但体验还比较粗糙。理想状态是 Agent 在 IDE 里直接操作集成终端输出实时显示在面板上人机可以随时接管。这个需要改插件工作量不小但值得做。我个人在实际操作中的体会是给 Agent 造工具最重要的不是功能多而是边界清晰、行为可预测。Agent 不像人它不会感觉不对劲就停下来所以工具本身必须把异常情况处理干净把危险操作拦在门外。这套终端我迭代了大概两个月大部分时间不是花在让它能跑而是花在让它跑得稳、跑得安全上。如果你也在做类似的东西建议一开始就把安全和资源回收设计进去不然后面补起来很痛苦。
