1. 从一条命令说起：为什么要给 AI Agent 造一个终端
最早用 Claude Code 的时候，我的工作流其实很原始：开一个终端窗口跑 Claude Code，再开一个窗口手动敲命令，两边来回切。它说"你执行一下 npm run build"，我复制粘贴过去；它说"看一下这个报错"，我再把输出贴回去。一天下来，手指在 Cmd+Tab 上按到发酸，脑子里的上下文被切得七零八落。
后来我想明白一件事：AI Agent 的能力上限，很大程度上不取决于模型本身，而取决于它能"看到"和"操作"多少真实环境。模型再聪明，如果只能靠人肉搬运终端输出，那它永远是个"隔着玻璃指挥"的顾问，而不是能下场干活的工程师。Claude Code 本身已经能直接执行终端命令了，但它的执行是"一次性"的——跑一条、拿结果、再跑下一条，中间没有持久会话，也没法同时管好几个任务。
这就是我动手写这个终端项目的起点。核心目标有三个：第一，让 Claude Code 能真正操控一个持久化的终端会话，而不是每次从零开始；第二，支持同时指挥多个 Agent，各干各的互不干扰；第三，整个交互走 MCP（Model 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 抢同一个终端"导致的诡异 bug：A 刚cd到某个目录，B 一条命令把目录删了，A 后续所有命令全崩。
我的做法是每个会话一个独立 PTY + 独立工作目录 + 独立环境变量表。会话创建时指定一个 ID，后续所有操作都带上这个 ID，路由到对应的 PTY。
| 隔离维度 | 实现方式 | 不隔离的后果 |
|---|---|---|
| 进程空间 | 独立 PTY + 独立 shell 进程 | 一个 Agent 的kill误杀另一个的进程 |
| 工作目录 | 每会话独立 cwd 状态 | cd互相覆盖，路径全乱 |
| 环境变量 | 会话级 env map | 一个改了 PATH，另一个找不到命令 |
| 输出流 | 独立缓冲区 | 输出串味，Agent 读到别人的日志 |
环境变量这块有个细节：不能简单继承父进程的 env 就完事。因为 Agent 经常需要临时设置变量，比如export API_KEY=xxx然后跑命令。如果所有会话共享一份 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 server），Agent 可以显式声明"这条命令不要等结束"，直接返回。
注意：不要只依赖超时判断命令结束。我早期版本用固定 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.toml）Cargo.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 外层用官方 SDK：
npm install @modelcontextprotocol/sdk4.2 会话管理器的实现要点
会话管理器是整个系统的中枢，我用一个HashMap<SessionId, Session>来维护所有活跃会话，外面套一层Arc<Mutex<>>保证并发安全。
struct Session { id: String, pty_pair: PtyPair, child: Box<dyn Child + Send>, cwd: PathBuf, env: HashMap<String, String>, output_buffer: Arc<Mutex<VecDeque<String>>>, last_activity: Instant, } struct SessionManager { sessions: Arc<Mutex<HashMap<String, 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: Arc<Mutex<VecDeque<Command>>>, is_busy: Arc<AtomicBool>, }实测下来，这套机制能稳定支撑 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 解码，过滤 ANSI |
5.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 会话泄漏与资源回收
跑了一段时间后，我发现系统里堆了一堆僵尸 PTY，ps aux一看全是bash进程。
根因是 Agent 创建会话后，如果任务异常中断，没有调用关闭接口。我的解决方案是双保险：
主动回收：后台任务每 5 分钟扫一次，超过 30 分钟无活动的会话强制关闭，先发SIGTERM，5 秒后还在就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 不像人，它不会"感觉不对劲就停下来"，所以工具本身必须把异常情况处理干净，把危险操作拦在门外。这套终端我迭代了大概两个月，大部分时间不是花在"让它能跑"，而是花在"让它跑得稳、跑得安全"上。如果你也在做类似的东西，建议一开始就把安全和资源回收设计进去，不然后面补起来很痛苦。
