shai Shell Assistant 实现原理:PTY 监控与 Shell Hook 注入全解析
shai Shell Assistant 实现原理:PTY 监控与 Shell Hook 注入全解析
shai 是一个用 Rust 编写的终端编程代理(coding agent),它的 Shell Assistant 模式可以像"影子"一样包裹住你正在使用的 shell,实时监控每一条命令的执行过程,并在命令失败时用 AI 自动分析错误、给出修正方案。本文带你从零拆解这套机制:shai 如何通过 PTY(伪终端)监控 捕获 Shell 的所有输入输出,又如何零侵入地注入 Shell Hook 来追踪每条命令的前后状态。
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 命令替换并成功执行。
架构总览:一个转发进程如何"包住"你的 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() 里,子进程做了一连串"变身"动作:
- 写入环境变量
SHAI_SESSION_ID——这是整个会话的唯一身份标识,后续所有 Hook、socket 都靠它定位 setsid+ioctl(TIOCSCTTY)让它成为新会话的终端dup2把 slave fd 复制成标准输入/输出/错误(0/1/2)- 最后
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() 的工作方式非常巧妙:
- 根据 shell 类型,用 generate_rc_content() 生成一段 Hook 脚本
- 写入一个临时文件(
NamedTempFile) - 向 master fd 直接"敲入"一条命令:
source '/tmp/xxxx' - 把临时文件
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+)时:
- 调用
get_last_commands(50)拉取最近 50 条命令作为上下文 - 交给 LLM 分析——系统提示词定义在 clifixer/prompt.rs,教模型识别"命令不存在 / 参数错误 / 路径问题 / 权限不足"等常见错误模式
- 强制以 JSON Schema 结构返回
{ short_rational, fixed_cli }(见 clifixer/fix.rs),温度设为 0.1 保证稳定 - 终端进入交互态:打印错误理由 + 橙色高亮的修正命令,按 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() 用它判断开关状态。
关键源码速查索引
想深入阅读,按下面的路径入手即可:
- 入口与子命令:shai-cli/src/main.rs
- PTY 创建与 I/O 转发:shai-cli/src/shell/pty.rs
- Hook 脚本生成(五种 shell):shai-cli/src/shell/rc.rs
- raw 模式与窗口同步:shai-cli/src/shell/terminal.rs
- 会话服务器与请求处理:shai-cli/src/fc/server.rs
- 通信协议:shai-cli/src/fc/protocol.rs
- 命令历史数据结构:shai-cli/src/fc/history.rs
- 错误修复 Runner:shai-core/src/runners/clifixer/
常见问题 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 开始就够了。

