uniTerm AI Agent 实现原理:工具调用 + 终端注入,终端里的 AI 如何真正执行命令
uniTerm AI Agent 实现原理:工具调用 + 终端注入,终端里的 AI 如何真正执行命令
uniTerm 是一款覆盖 SSH、RDP、SFTP、数据库、Kubernetes 等 30+ 协议的 All-in-one 终端,其内置 AI Agent 不只是“聊天”,而是能通过工具调用把命令真正注入到你打开的终端里执行,并自主读取输出、多轮循环直到任务完成。本文拆解这套“工具调用 + 终端注入”的实现原理。
从“只会聊天”到“真正执行”:AI Agent 的核心思路
大多数终端助手的做法是调用一个独立的 shell 进程跑命令,这种方式看不到你终端里的上下文,也无法操作交互式程序。uniTerm 走的是另一条路:
- 工具调用(Tool Use):把“执行命令、看屏幕、收输出、发按键”封装成标准 LLM 工具,模型用 JSON 声明式地“发起调用”;
- 终端注入(Terminal Injection):命令不是另开进程,而是像人打字一样,被注入到你当前活跃的终端会话中,输出再通过屏幕模拟器还原成干净的文本。
两者结合,AI 才能像真人一样在终端里干活:跑命令、看结果、遇到密码提示就补输入、命令没跑完就继续等。
第一部分:工具调用层——AI 能用的“手”
前端在 frontend/src/services/llm.ts 中定义了内置工具集 AVAILABLE_TOOLS,发给大模型时作为 tools 参数附在请求上。核心工具有 7 个:
| 工具 | 作用 | 类比 |
|---|---|---|
execute_command |
在终端执行命令并等待返回 | 敲一行命令 |
start_command |
启动长驻命令(如 npm run dev) |
起一个后台服务 |
capture_terminal |
瞬时截取当前屏幕内容 | 看一眼屏幕 |
collect_output |
不发送任何内容,只等待并收集输出 | 继续等命令跑完 |
send_terminal_key |
向终端发送文本或 Ctrl+C / Ctrl+D / 回车 | 回答交互提示 |
interrupt_command |
发送 Ctrl+C 中断当前命令 | 卡住时打断 |
ask_user |
以选项形式向用户提问 | 让人做决定 |
命令必须自带“风险等级”
一个容易被忽略的设计:execute_command 和 start_command 要求模型必须给每条命令标注风险等级 risk:read(只读)、write(修改但非破坏)、dangerous(可能破坏系统)。
在 frontend/src/services/agent.ts 中,getRisk 遵循“默认关闭”原则——模型不标注或标注错误时一律按 dangerous 处理。结合用户设置的确认模式(确认所有 / 只确认写入 / 只确认危险 / 全部放行),命中确认的规则时命令会暂停执行、弹出确认卡片,由用户点按后才真正下发。这意味着 AI 提的每条命令,最终把关权都在你手里。
Agent 主循环:一轮只做一个动作
前端 agent.ts 中的 runAgent 是多轮循环的执行器:请求模型 → 解析响应中的 tool_use 块 → 强制只保留第一个工具调用(toolUses.length > 1 时直接截断)→ 校验参数 → 确认/执行 → 把结果作为 tool 消息追加进历史 → 再次请求模型,直到模型不再调用工具。
“一次只执行一个工具”是刻意为之:终端是串行的,同一时刻只能有一个执行者,并发工具调用会让命令和输出互相污染。循环中任何一步失败(比如模型输出了非法 JSON 参数)都会把错误“回喂”给模型让它重试,而不是直接崩溃。
第二部分:终端注入层——命令如何“打进”你的终端
数据流:从前端到 PTY
前端执行入口在 frontend/src/services/terminalAgent.ts 的 executeCommand:
resolveActiveSession定位目标终端——优先用户“AI 锁定”的面板,其次当前活动面板,也可用panel参数指定标题;- 调用后端绑定
StartForeground(sessionId, command, timeoutMs)启动一个“前台作业”(Job),拿到jobId; - 以 150ms 间隔轮询
PollForeground(jobId, offset, pageSize),按字节偏移增量拉取输出(base64 编码),直到作业状态变为exited/timeout等。
后端对应 app_mcp.go 中的 StartForeground,它把会话适配成 ptyAdapter 后交给 backend/mcp/job.go 的 Registry.StartWithScreen。真正的“注入”就发生在这里:
- 写命令:
pty.Write(command + newline)——就是把命令文本加回车直接写进活动终端的输入流,和键盘输入等价。换行符还会按环境自适应:Windows 本地 / PowerShell / Windows OpenSSH 用\r,POSIX shell 用\n; - 先挂监听后写命令:注册
OnData数据监听(数据“抽头”)并确认安装完成后才Write,保证命令一产生输出就被捕获,一个字节都不丢。
屏幕模拟器:把“乱码流”变成干净文本
终端输出不是纯文本,而是混杂 ANSI 转义序列的字节流——光标定位、清屏、颜色、重绘帧。如果直接把这些字节当输出喂给 AI,Windows ConPTY + OpenSSH 场景下会出现大量“重绘帧”重复文本,模型会被污染。
uniTerm 的解法是在作业内嵌一个 Screen 屏幕模拟器(backend/mcp/job.go 的 Screen 结构):一个 200×60 的字符网格加状态机,解析 CSI/OSC/光标/滚动等序列,把原始字节流“播放”成网格状态,再用**水位线(watermark)**机制只提取新产生的逻辑行输出。效果是:重绘帧只会修改网格而不会追加字节,AI 拿到的就是屏幕上“人看到的样子”,且每行只出现一次。
CaptureScreen(给 capture_terminal 用)也复用了同一套模拟器:每个会话挂一个常驻数据抽头持续喂入,随时可以取最近 N 行——这就是 AI 能“看到屏幕”的原理。
如何知道命令“跑完了”
“输出停了一秒”不等于“命令结束了”。uniTerm 在 backend/mcp/completion.go 的 CompletionCommand 中给命令包了一层完成令牌(nonce):支持探测的 shell 执行完命令后会在输出中打印形如 __UT_<jobId>;<exitCode>__ 的隐藏标记,扫描器看到该标记才判定 exited 并拿到真实退出码。静音和提示符出现都不算完成。
超时也不会丢失现场:作业转入 timeout 状态后,数据抽头、屏幕模拟器和会话锁都保持活跃,AI 调用 collect_output 时通过 Registry.Collect 恢复原作业继续收集,中途产生的输出一点不丢。
并发安全:一个终端只有一个执行者
backend/mcp/job.go 的 Registry 维护 busy 表:同一会话已有前台作业时,新的 Start 直接返回 session is busy with another execution。这是防止两个 AI 同时往一个终端里“打字”导致命令交叉、完成标记错乱的关键设计。全局还有 8 个并发作业上限、64KB 单作业输出上限(轮询侧上限更大)等保护。
一次完整的多轮执行长什么样
把两层合起来,一个“检查两台机器磁盘”的请求会经历这样的循环:
- 模型调用
execute_command(risk=read),注入df -h等命令,前端确认通过后StartForeground启动作业; - 完成令牌被检测到,退出码 0,输出经屏幕模拟器整理、按 head/tail 行截断(默认保头部 50 行 + 尾部 300 行),作为
tool消息回喂; - 模型判断还有第二台主机没查,继续发起下一个
execute_command; - 若中途命令卡住,模型可
collect_output分段等待;若出现密码或 y/n 提示,用send_terminal_key补输入;实在跑不完就interrupt_command打断重来; - 模型输出纯文本总结、不再调用工具,循环结束。
整个过程中用户随时能看到每条命令正在终端里真实执行,也能在任意时刻点“停止”——停止请求会通过 shouldCancel 回传给作业,注入 Ctrl+C 并标记中断。
安全设计小结
- 风险分级 + 确认模式:命令执行前的最后一道闸是用户本人;
- 默认关闭:风险等级缺失或非法时按
dangerous处理; - 参数强校验:模型输入被视为不可信数据,逐字段类型校验,非法输入回喂重试而非直接执行;
- 单执行者锁:会话级 busy 锁 + 全局并发上限;
- 输出有界:字节级上限 + 行级 head/tail 截断,防止超长输出撑爆上下文。
写在最后
uniTerm 的 AI Agent 本质上把“人机接口”标准化成了两套协议:对模型是标准 Tool Use JSON,对终端是 PTY 字节流。工具调用层负责“AI 说什么”,终端注入层负责“AI 怎么做到”——命令像人一样被打进你正在用的终端,输出像人一样从屏幕上被读出来。这套架构也同时被 uniTerm 的 MCP Server 复用,外部 AI 客户端可以走同一套前台作业引擎操作你的终端。
想动手了解细节,可以从这几个文件读起:
- 工具定义:frontend/src/services/llm.ts
- Agent 循环与确认逻辑:frontend/src/services/agent.ts
- 前端执行/轮询:frontend/src/services/terminalAgent.ts
- 作业引擎与屏幕模拟器:backend/mcp/job.go
- 完成令牌探测:backend/mcp/completion.go
- 后端会话桥接:app_mcp.go


