1. 从一条命令行说起为什么终端里的 AI 助手必须能执行命令你有没有过这种体验在终端里敲了半天命令突然忘了某个参数怎么拼于是切到浏览器搜一下再切回来继续敲或者面对一个报错信息复制出来丢给网页版 AI等它分析完再手动把命令贴回终端。整个流程割裂得像在用两台电脑干活。这个项目的出发点就一句话终端里的 AI 助手应该是可以执行命令的。不是只给你一段建议让你自己复制粘贴而是它理解你的意图之后直接在当前 shell 环境里把命令跑起来把结果拿回来继续推理形成一个闭环。听起来像是给终端加了个“会动手的副驾驶”。但真正动手做起来你会发现这件事远比“调个 API 然后 exec 一下”复杂得多。它涉及命令安全边界、上下文管理、执行结果回传、多轮对话状态保持、以及最关键的——怎么让 AI 知道“现在这台机器上有什么、能干什么”。这篇文章适合两类人看一类是日常在终端里讨生活的开发者、运维、数据工程从业者想知道这东西到底怎么落地另一类是想自己动手做一个终端 AI 执行器的工程师我会把架构选型、核心实现、踩坑经验都摊开讲。全文基于我在实际构建这类工具时的真实思路和操作记录代码和配置都可以直接参考复现。2. 整体设计思路为什么不是“套壳聊天框”2.1 核心需求拆解从“给建议”到“给结果”普通的终端 AI 工具本质是一个聊天框。你问它“怎么查看当前目录下最大的十个文件”它回你一段du -ah . | sort -rh | head -n 10然后你自己复制、粘贴、回车。这个模式的问题在于AI 不知道执行结果无法根据结果继续帮你。如果命令报错了你还得把错误信息再贴回去它才能给出修正建议。而“可执行命令”的终端 AI 助手目标是把这三步压缩成一步你说意图它生成命令它执行它读结果它决定下一步。整个过程你只需要确认或授权。这就从“问答工具”变成了“任务代理”。我把它拆成四个核心能力意图理解把自然语言转成可执行的命令序列而不是一段解释。环境感知知道当前工作目录、操作系统、已安装的工具、环境变量避免生成一个这台机器上根本不存在的命令。安全执行在真正跑命令之前判断这条命令是否危险是否需要用户确认是否应该被拦截。结果回传与多轮推理把 stdout、stderr、退出码结构化地喂回给模型让它基于真实结果继续。这四个能力缺一个产品体验就会塌。尤其是安全执行这是整个项目里最容易被低估、也最容易出事的部分。2.2 方案选型三种架构路线的取舍在动手之前我对比了三种主流实现路线每种都有明确的适用场景和代价。方案实现方式优点缺点适用场景Shell 包装器写一个脚本拦截用户输入调用模型再执行返回的命令实现简单几十行就能跑无法多轮推理上下文丢失快个人快速验证独立 CLI 程序用 Python/Go/Rust 写一个独立命令内部维护会话状态状态可控扩展性强需要处理终端交互、信号、管道日常主力工具终端模拟器插件在终端软件内部做插件直接操作 PTY体验最丝滑能拿到完整终端状态绑定特定终端移植性差深度定制用户我最终选了独立 CLI 程序这条路线。原因很直接它不绑定任何特定终端软件在本地终端、远程会话、CI 环境里都能跑同时它又能自己维护会话状态支持多轮推理。Shell 包装器太薄终端插件太重独立程序是那个“刚刚好”的甜点区。提示如果你只是想快速验证想法先用 Shell 包装器跑通“输入-生成-执行-回传”这个最小闭环再决定要不要重写成独立程序。不要一上来就追求完美架构。2.3 技术栈选择与理由具体技术栈上我用了 Python 作为主语言理由有三点。第一生态里处理终端交互的库足够成熟prompt_toolkit能做出接近原生的交互体验。第二调用模型 API 的 SDK 最全切换模型供应商的成本最低。第三团队里大部分人能读懂 Python后续维护门槛低。核心依赖清单如下# 交互式命令行界面 prompt_toolkit3.0.0 # 终端样式与颜色 rich13.0.0 # 模型调用以通用接口为例 httpx0.24.0 # 配置管理 pyyaml6.0 # 命令解析与安全校验 shlex # 标准库无需安装这里有个选型细节值得说我特意没有用subprocess.run(shellTrue)这种最省事的执行方式。原因后面安全章节会详细讲简单说就是shellTrue会把整条命令交给 shell 解释注入风险极高而且你很难在执行前做精确的静态分析。3. 核心细节解析命令执行引擎怎么搭3.1 命令生成让模型输出结构化指令而非纯文本最朴素的做法是让模型直接输出一条命令字符串然后你拿去执行。但实测下来这种做法在多命令场景下会崩。模型可能输出带 markdown 代码块的文本可能输出多条命令但没告诉你执行顺序也可能在命令里夹带解释文字。我的做法是强制模型输出结构化 JSON格式如下{ reasoning: 用户想查看磁盘占用最大的目录先用 du 统计, commands: [ { cmd: du -h --max-depth1 /home, description: 统计 /home 下各一级目录占用, risk_level: low, need_confirm: false } ], next_step_hint: 根据输出决定是否深入某个子目录 }这个结构里reasoning字段是给用户看的让用户知道 AI 为什么这么干commands是真正要执行的risk_level和need_confirm是安全层要用的next_step_hint帮助多轮推理时保持方向。强制 JSON 输出的关键是在系统提示词里明确约束并且用模型的 JSON 模式如果支持。我试过只靠提示词约束模型有大约 5% 的概率会输出非 JSON 内容加上 JSON 模式后这个概率降到接近零。3.2 环境感知让 AI 知道“这台机器上有什么”这是很多人会忽略的一环。如果你不告诉模型当前环境它可能生成一个fd命令但这台机器上只装了find或者生成一个 macOS 特有的pbcopy但用户在 Linux 上。我的做法是在会话初始化时采集一份环境快照注入到系统提示词里import platform import shutil import os def collect_env_snapshot(): snapshot { os: platform.system(), os_version: platform.release(), shell: os.environ.get(SHELL, unknown), cwd: os.getcwd(), available_tools: [] } # 探测常用工具是否存在 common_tools [git, docker, kubectl, jq, rg, fd, curl, wget, python3, node] for tool in common_tools: if shutil.which(tool): snapshot[available_tools].append(tool) return snapshot这份快照不需要每次对话都重新采集会话开始时采一次用户切换目录时更新cwd即可。实测下来注入环境快照后模型生成“不存在的命令”的概率下降了大概七成。注意环境快照里不要采集任何敏感信息比如环境变量里的密钥、token。只采集工具是否存在、系统类型、当前目录这类非敏感信息。3.3 执行隔离子进程、超时与输出截断命令执行本身用subprocess模块但有几个参数必须设置好否则会出各种诡异问题。import subprocess import shlex def execute_command(cmd_str, timeout30, max_output10000): try: # 用 shlex.split 而非 shellTrue避免注入 args shlex.split(cmd_str) result subprocess.run( args, capture_outputTrue, textTrue, timeouttimeout, cwdos.getcwd() ) stdout result.stdout[:max_output] stderr result.stderr[:max_output] return { exit_code: result.returncode, stdout: stdout, stderr: stderr, truncated: len(result.stdout) max_output or len(result.stderr) max_output } except subprocess.TimeoutExpired: return {exit_code: -1, stdout: , stderr: 命令执行超时, truncated: False} except FileNotFoundError: return {exit_code: -2, stdout: , stderr: f命令不存在: {args[0]}, truncated: False}三个关键点超时防止命令卡死输出截断防止一个cat大文件把上下文撑爆shlex.split替代shellTrue防止注入。输出截断的阈值我设的是 10000 字符超过就截断并标记truncated让模型知道输出不完整。3.4 多轮推理把执行结果结构化回传命令执行完结果要回传给模型。这里不能简单地把 stdout 拼成一段文本丢回去那样模型很难区分“这是命令输出”还是“这是用户新输入”。我的做法是构造一条结构化的工具返回消息def build_tool_result(command, result): return { role: tool, content: json.dumps({ command: command, exit_code: result[exit_code], stdout: result[stdout], stderr: result[stderr], truncated: result[truncated] }, ensure_asciiFalse) }模型收到这条消息后能清楚知道哪条命令执行了、退出码是多少、输出是什么。基于这些信息它决定是继续执行下一条命令还是给出最终结论。这个闭环是多轮推理的基础。4. 实操过程从零搭一个可用的终端 AI 执行器4.1 项目骨架与主循环先搭一个最小可运行的主循环。整个程序的核心就是一个while循环读用户输入调模型执行命令回传结果直到模型给出最终答复。import json from prompt_toolkit import PromptSession from prompt_toolkit.history import InMemoryHistory class TerminalAgent: def __init__(self, model_client): self.client model_client self.session PromptSession(historyInMemoryHistory()) self.messages [] self.env_snapshot collect_env_snapshot() self._init_system_prompt() def _init_system_prompt(self): system_prompt f你是一个终端命令执行助手。 当前环境信息 {json.dumps(self.env_snapshot, ensure_asciiFalse, indent2)} 你的职责 1. 理解用户意图生成可执行的命令 2. 必须以 JSON 格式输出包含 reasoning 和 commands 字段 3. 危险命令必须标记 need_confirm 为 true 4. 根据命令执行结果继续推理直到任务完成 self.messages.append({role: system, content: system_prompt}) def run(self): while True: user_input self.session.prompt( ) if user_input.strip() in (exit, quit): break self.messages.append({role: user, content: user_input}) self._process_turn() def _process_turn(self): while True: response self.client.chat(self.messages) self.messages.append({role: assistant, content: response}) parsed self._parse_response(response) if not parsed or not parsed.get(commands): # 模型给出最终答复本轮结束 print(parsed.get(reasoning, response)) break for cmd in parsed[commands]: if cmd.get(need_confirm): if not self._ask_confirm(cmd): continue result execute_command(cmd[cmd]) self.messages.append(build_tool_result(cmd[cmd], result))这个骨架跑起来之后你就能体验到“说一句话AI 帮你执行命令并继续推理”的完整流程了。4.2 安全确认机制的具体实现安全确认不是简单弹个 y/n而是要把命令的意图、风险点讲清楚让用户能快速判断。def _ask_confirm(self, cmd): print(f\n[需要确认] {cmd[description]}) print(f命令: {cmd[cmd]}) print(f风险等级: {cmd[risk_level]}) answer input(是否执行? [y/N] ).strip().lower() return answer y风险等级怎么定我维护了一个规则表对命令做静态匹配风险等级匹配规则处理方式high包含rm -rf、mkfs、dd、 /dev/强制确认且高亮警告medium包含rm、mv、chmod、chown、kill需要确认low只读命令如ls、cat、grep、find直接执行这个规则表不可能覆盖所有情况但能拦住绝大多数误操作。实测下来用户对 medium 和 high 的确认接受度很高因为确认框里写清楚了命令在干什么。4.3 会话状态与上下文窗口管理多轮对话跑久了上下文会越来越长最终超出模型窗口。我的处理策略是保留系统提示词 最近 N 轮完整对话 更早对话的摘要。def trim_messages(self, messages, max_turns10): system messages[0] rest messages[1:] if len(rest) max_turns * 2: return messages # 保留最近 max_turns 轮 recent rest[-(max_turns * 2):] # 更早的内容做摘要 older rest[:-(max_turns * 2)] summary self._summarize(older) return [system, {role: system, content: f历史摘要: {summary}}] recent摘要这一步可以再调一次模型也可以简单地把更早的命令和结果压缩成一行。我倾向于用模型做摘要因为能保留语义但要注意摘要本身也会消耗 token所以只在超过阈值时才触发。4.4 输出渲染让终端里的结果可读终端里全是纯文本如果 AI 返回一大段 JSON用户根本没法看。我用rich库做渲染把 reasoning、命令、执行结果分块展示用颜色区分状态。from rich.console import Console from rich.panel import Panel from rich.syntax import Syntax console Console() def render_command(cmd): console.print(Panel( Syntax(cmd[cmd], bash, thememonokai), titlef[{cmd[risk_level]}] {cmd[description]}, border_styleyellow if cmd[risk_level] ! low else green )) def render_result(result): if result[exit_code] 0: console.print(result[stdout], stylewhite) else: console.print(result[stderr], stylered)渲染这块看起来是小事但实际体验差别巨大。没有渲染的时候用户面对一屏 JSON 完全不知道发生了什么有了渲染命令、结果、状态一目了然。5. 常见问题与排查技巧实录5.1 命令执行类问题速查问题现象可能原因排查方法解决方案命令报“不存在”环境快照未包含该工具检查shutil.which结果补充工具探测列表命令卡住不返回命令进入交互模式等待输入加timeout参数对交互式命令加-y或重定向 stdin输出乱码命令输出非 UTF-8检查textTrue编码指定encodingutf-8, errorsreplace管道命令失败shlex.split不解析管道检查命令是否含 相对路径找不到cwd 与预期不符打印os.getcwd()执行前显式设置 cwd这里重点说管道命令的问题。shlex.split(ls | grep py)会得到[ls, |, grep, py]直接传给subprocess.run会报错因为|不是ls的参数。管道、重定向、这些 shell 特性用shellFalse是处理不了的。我的折中方案是检测到命令包含 shell 元字符时走一个受限的 shell 执行路径但先做严格的安全校验。校验通过才允许shellTrue否则拒绝执行并提示用户拆分命令。5.2 模型输出类问题模型不按 JSON 格式输出是最常见的问题。除了用 JSON 模式我还在解析层做了容错import re def _parse_response(self, response): # 先尝试直接解析 try: return json.loads(response) except json.JSONDecodeError: pass # 尝试提取 markdown 代码块里的 JSON match re.search(r(?:json)?\s*(\{.*?\})\s*, response, re.DOTALL) if match: try: return json.loads(match.group(1)) except json.JSONDecodeError: pass # 尝试提取第一个完整 JSON 对象 match re.search(r\{.*\}, response, re.DOTALL) if match: try: return json.loads(match.group(0)) except json.JSONDecodeError: pass return None三层容错下来基本能兜住 99% 的格式问题。剩下 1% 就让模型重新生成一次。5.3 实操避坑心得第一个坑不要相信模型对“危险”的判断。我一开始把风险判断完全交给模型结果它把rm -rf /tmp/test标成了 low。后来改成“模型标记 本地规则二次校验”双保险才靠谱。模型负责理解意图本地规则负责兜底。第二个坑输出截断要告诉模型。早期我只截断不标记模型看到不完整的输出会做出错误推理。加上truncated字段后模型知道“输出被截断了”会主动建议用head或grep缩小范围。第三个坑会话历史不要无限增长。我试过不裁剪历史跑到第 20 轮的时候 token 直接爆了而且响应速度肉眼可见地变慢。加上裁剪和摘要后长会话的稳定性好了很多。第四个坑命令执行的工作目录要显式管理。用户说“进入某个目录然后看看”模型可能生成cd xxx ls但cd在shellFalse下不生效。我的做法是拦截cd命令直接更新 agent 的cwd状态而不是真的执行cd。提示cd、export、alias这类改变 shell 状态的命令在子进程模型下都不会持久化。要么拦截它们单独处理要么明确告诉用户这些命令不生效。6. 安全边界与扩展方向6.1 命令白名单与黑名单的取舍纯黑名单拦不住所有危险命令纯白名单又太死板。我最终用的是黑名单硬拦截 白名单软放行 灰名单需确认的三层策略。黑名单是绝对禁止的比如rm -rf /、mkfs、dd of/dev/sda这类直接拒绝执行连确认都不给。白名单是只读命令直接跑。灰名单是需要确认的覆盖大部分写操作。这个策略的维护成本在于黑名单要持续更新。我的经验是黑名单只放“一旦执行就无法挽回”的命令其他都归到灰名单让用户确认。宁可多确认几次也不要误删数据。6.2 后续可以怎么扩展这个项目跑通之后有几个自然的扩展方向。一是接入本地模型把命令生成放在本地跑敏感环境里更放心。二是命令模板库把高频操作沉淀成模板模型直接调用模板而不是每次重新生成。三是执行审计日志记录每条命令的执行时间、结果、用户确认情况方便回溯。我个人最想加的是命令解释模式用户输入一条命令AI 不执行而是逐段解释这条命令在干什么。这个功能对学习终端命令特别有用而且完全没有安全风险。6.3 我个人的使用体会用了几个月下来最大的感受是终端 AI 执行器的价值不在于“帮你敲命令”而在于“帮你记住上下文”。以前排查一个问题要在多个终端窗口之间来回切换现在一个会话里就能完成“查看状态、分析日志、定位问题、执行修复”的完整链路。但我也踩过一个印象深刻的坑。有一次让 AI 清理临时文件它生成了一条find /tmp -type f -delete我手快点了确认结果把正在用的一个临时文件也删了。从那以后我给所有-delete、-exec rm这类命令都加了强制二次确认而且确认框里会列出“将要删除的文件数量”。这个细节后来救了我好几次。如果你也在做类似的东西我的建议是先把安全层做扎实再追求功能丰富。一个能执行命令的 AI 助手能力越大误操作的代价也越大。安全确认不是拖慢体验的累赘而是让你敢放心用它的前提。