shai Shell Assistant 实现原理:PTY 监控与 Shell Hook 注入全解析

原创2026-11-14 15:39:272,217 阅读

shai Shell Assistant 实现原理:PTY 监控与 Shell Hook 注入全解析

shai 是一个用 Rust 编写的终端编程代理(coding agent),它的 Shell Assistant 模式可以像"影子"一样包裹住你正在使用的 shell,实时监控每一条命令的执行过程,并在命令失败时用 AI 自动分析错误、给出修正方案。本文带你从零拆解这套机制:shai 如何通过 PTY(伪终端)监控 捕获 Shell 的所有输入输出,又如何零侵入地注入 Shell Hook 来追踪每条命令的前后状态。

shai 终端 AI 编程代理界面,Shell Assistant 的宿主 TUI

shai Shell Assistant 是什么:给终端装上"AI 眼睛"

正常情况下,你敲下一条命令后如果报错,只能靠自己猜哪里写错了。开启 shai 的 Shell Assistant 后,它会:

  • 📡 监听你的 shell,记录每条命令、退出码和输出
  • 🔍 当命令执行失败时,自动拉取最近的历史上下文
  • 🛠️ 调用 LLM 分析错误原因,并生成一条可直接运行的修正命令
  • ⌨️ 在终端里让你一键确认执行(回车运行 / Esc 取消)

整个过程由三条子命令控制,详见 docs/cli-reference.md:

shai on       # 开启:进入被监控的 shell 会话
shai off      # 关闭:退出监控
shai status   # 查看当前是否处于监控状态

下图是 Shell Assistant 的真实效果:用户输入 weather 命令失败后,shai 自动用一条 curl 命令替换并成功执行。

shai shell assistant 演示:命令报错后自动给出并执行修正命令

架构总览:一个转发进程如何"包住"你的 Shell

Shell Assistant 的核心是三个协作模块,都位于 shai-cli 包内:

模块 职责 源码位置
PTY 管理器 创建伪终端、fork 子 shell、双向转发 I/O shai-cli/src/shell/pty.rs
终端控制器 把用户终端切到 raw 模式、同步窗口大小 shai-cli/src/shell/terminal.rs
Hook 生成器 为不同 shell 生成注入脚本 shai-cli/src/shell/rc.rs
会话服务器 Unix socket 服务,存储命令历史 shai-cli/src/fc/server.rs

理解它的关键,是看清进程关系:shai 的父进程充当"中间人",一端连着你的真实终端,一端连着被 fork 出来的"影子 shell",所有数据都必须经过它中转——这正是它能旁路监控一切的根本原因。

核心一:PTY 监控是如何工作的

创建一对伪终端(master / slave)

一切从 create_pty_pair() 开始。它按标准 POSIX 流程,用四个系统调用造出一对"电话线":

  • posix_openpt 打开主端(master fd)
  • grantpt + unlockpt 授权解锁
  • ptsname 取到从端设备名,再 open 打开从端(slave fd)

master 端交给 shai 父进程掌控,slave 端则交给子 shell 当作它自己的标准输入输出。两者通过内核的伪终端驱动互相通信。

fork 出"影子 shell"

在 setup_child_process() 里,子进程做了一连串"变身"动作:

  1. 写入环境变量 SHAI_SESSION_ID——这是整个会话的唯一身份标识,后续所有 Hook、socket 都靠它定位
  2. setsid + ioctl(TIOCSCTTY) 让它成为新会话的终端
  3. dup2 把 slave fd 复制成标准输入/输出/错误(0/1/2)
  4. 最后 execl 以 -i(交互式)参数启动真实 shell

从此,你以为在跟自己的 shell 对话,其实对面是 shai 的转发层。

双向 I/O 转发与 raw 模式

shai on 会先把你的终端切换为 raw mode(见 terminal.rs 的 setup_raw_mode()),关闭行缓冲与按键回显,确保每个按键都能被精确捕获。

随后 handle_io_forwarding() 建立两条"传送带":

  • 输入通道:一个独立线程读取你的键盘输入 → 写入 master fd → 到达影子 shell
  • 输出通道:主循环从 master fd 读出 shell 的所有输出 → 一份打印到你的屏幕,另一份喂给历史服务器(io_server.add_output)

💡 妙就妙在"一份数据、两处投递":你照常看到 shell 输出,而 shai 在暗处默默把输出归档到了对应的命令记录里。

退出 shell 时,TerminalManager 通过 Drop 自动把终端还原回原样,不会残留 raw 状态。

窗口大小同步

handle_sigwinch() 注册了一个 SIGWINCH 信号处理器:当你拖动终端窗口时,它会把新的尺寸通过 TIOCSWINSZ 同步到伪终端,让 shell 内的全屏程序(如 less、vim)都能正确重排。

核心二:Shell Hook 是如何"零侵入"注入的

监控到了输入输出还不够——shai 必须精确知道"哪条命令正在执行、它的退出码是多少"。这靠注入一段 Hook 脚本实现,全程不修改你的 ~/.bashrc。

生成临时 rc 文件并 source 进去

inject_shai_hooks() 的工作方式非常巧妙:

  1. 根据 shell 类型,用 generate_rc_content() 生成一段 Hook 脚本
  2. 写入一个临时文件(NamedTempFile)
  3. 向 master fd 直接"敲入"一条命令:source '/tmp/xxxx'
  4. 把临时文件 keep() 下来,等会话结束时再删除

因为 shell 是交互式的,这条 source 命令会被当作"你亲手敲下的"命令执行,Hook 随即生效。

五种 Shell 各有其挂载点

shai 支持 sh / bash / zsh / fish / powershell,每种都用它原生的扩展点挂 Hook(rc.rs):

Shell 前置捕获(precmd) 后置捕获(postcmd)
bash / sh trap 'shai_precmd' DEBUG 读 $BASH_COMMAND PROMPT_COMMAND 里读 $?
zsh add-zsh-hook preexec add-zsh-hook precmd
fish fish_preexec 事件 fish_postexec 事件
powershell PSReadLine 的 AddToHistoryHandler 覆写 prompt 函数

Hook 触发时会调用 shai 的两个"隐藏子命令":

shai precmd "git push"        # 命令执行前:上报待执行命令
shai postcmd 1 "git push"     # 命令执行后:上报退出码 + 命令

🛡️ 每个 Hook 都会先做自我过滤,跳过以 shai 开头的命令,避免"上报 shai 自己"造成死循环。

MAGIC_COOKIE:消除注入回显的巧思

source 一个文件时,shell 会把文件内容"回显"到屏幕上,非常难看。shai 的解法(见 rc.rs 第 5 行 与 pty.rs 第 284-300 行):

  • 在 rc 脚本末尾 echo 一个魔法标记 >>>SHAI_HOOKS_INJECTED<<<
  • 父进程在 I/O 循环里,逐字节吞掉从注入开始到该标记出现为止的所有回显,再吞掉随后的空行

于是你看到的界面干干净净,仿佛这段 Hook 从未存在过。

数据闭环:precmd → 执行 → postcmd

Unix socket + MessagePack 协议

所有 Hook 上报都通过本地 Unix socket 传递,socket 路径是 /tmp/shai_history_{SHAI_SESSION_ID}(见 server.rs 第 24 行)。消息格式定义在 protocol.rs 的 ShaiRequest:

  • PreCmd { cmd }:命令即将执行
  • PostCmd { cmd, exit_code }:命令已执行完毕
  • GetAllCmd / GetLastCmd { n } / Clear / Status:查询与统计

序列化用 MessagePack,并在消息前加 4 字节长度前缀(ShaiProtocol::write_message),既紧凑又支持流式解析。客户端封装在 fc/client.rs,precmd/postcmd 子命令在 main.rs 中被处理。

用环形缓冲区记录每条命令的输出

每条命令对应一个 CommandEntry,包含命令文本、时间戳、退出码、耗时,以及一块环形缓冲区(AllocRingBuffer<u8>)用来暂存该命令的输出。环形结构天然限长,避免某条 cat 大文件 撑爆内存——这正是"一份数据两处投递"里,输出被归档到的目的地。

命令失败时,触发 clifix 自动修复

真正的"魔法"在 handle_postcmd()。当收到一个非零退出码(且不是信号导致的 128+)时:

  1. 调用 get_last_commands(50) 拉取最近 50 条命令作为上下文
  2. 交给 LLM 分析——系统提示词定义在 clifixer/prompt.rs,教模型识别"命令不存在 / 参数错误 / 路径问题 / 权限不足"等常见错误模式
  3. 强制以 JSON Schema 结构返回 { short_rational, fixed_cli }(见 clifixer/fix.rs),温度设为 0.1 保证稳定
  4. 终端进入交互态:打印错误理由 + 橙色高亮的修正命令,按 Enter 直接执行、并写回 shell 历史;按 Esc 取消

完整流程串讲

把上面拼起来,一次命令执行的完整链路是:

graph LR
    A[你敲下命令] --> B[raw mode 捕获]
    B --> C[转发到影子 shell]
    C --> D[precmd Hook 上报命令]
    D --> E[shell 真正执行]
    E --> F[输出: 一份上屏 + 一份归档]
    F --> G[postcmd Hook 上报退出码]
    G --> H{退出码 == 0 ?}
    H -->|是| I[记录完成]
    H -->|否| J[clifix: 拉历史 → LLM 修复]
    J --> K[回车执行 / Esc 取消]

而整个会话的生命周期由环境变量 SHAI_SESSION_ID 贯穿始终:run_pty() 检测它来防止嵌套开启(已在会话中会直接提示);kill_pty() 则靠它定位父进程并发送 SIGHUP 干净退出;pty_status() 用它判断开关状态。

关键源码速查索引

想深入阅读,按下面的路径入手即可:

常见问题 FAQ

会不会污染我的 .bashrc / .zshrc? 不会。Hook 写在临时文件里,通过 source 动态加载,会话结束时自动删除,你的配置文件原封不动。

支持哪些 Shell? sh、bash、zsh、fish、powershell。shai 会通过 $SHELL 等环境变量自动探测(detect_shell()),也可用 shai on -s <shell> 手动指定。

它是怎么知道命令"失败"了? 靠 shell 原生的 $? / $status 退出码。postcmd Hook 捕获退出码后,只有非零(且非信号类)才触发 LLM 分析,成功命令不会打扰你。

小结

shai 的 Shell Assistant 用一套极其克制的工程手法,实现了"无感"的终端 AI 辅助:

  • 🎭 PTY 双向转发:用伪终端做中间人,旁路捕获所有 I/O
  • 🪝 原生 Hook 注入:借各 shell 的 preexec/precmd 扩展点,零配置追踪命令生命周期
  • 🔧 MAGIC_COOKIE:优雅抹除注入回显,界面保持纯净
  • 🤖 clifix 闭环:失败即分析、即修复、即执行,形成完整反馈

整套机制只依赖 Unix 系统调用、本地 socket 和一个 LLM,却让你在命令行多了一位随叫随到的"救火队友"。想动手验证,从 shai on 开始就够了。

登录后查看全文
shai