Atuin pty-proxy 完全指南：叠加式搜索弹窗与命令输出捕获的实现与配置

Atuin pty-proxy 完全指南叠加式搜索弹窗与命令输出捕获的实现与配置【免费下载链接】atuin✨ Making your shell magical项目地址: https://gitcode.com/gh_mirrors/at/atuin导读atuin pty-proxy是 Atuin 推出的实验性轻量级 PTY 代理PTY proxy让你在不更换现有终端或 Shell 的前提下获得两项全新能力——搜索 TUI 以弹窗形式叠加在原有输出之上关闭后完美还原以及按命令捕获终端输出并将其提供给 Atuin AI 与外部 Agent。本文以官方参考文档 pty-proxy 为主线结合仓库源码crates/atuin-pty-proxy/与配套文档完整讲解其工作原理、配置方法、输出捕获与隐私机制读完即可在自己的 zsh / bash / fish / nu 环境中启用并理解其内部行为。什么是 pty-proxyatuin pty-proxy是一个实验性的轻量级 PTY 代理。与常规做法不同它不需要替换你的终端或 Shell而是作为一个介于终端与 Shell 之间的透明代理进程运行。当前它支持 bash、zsh、fish 与 nu 四种 Shell各 Shell 的支持等级详见 Supported platforms。注意atuin pty-proxy是旧命令atuin hex的替代品。出于向后兼容atuin hex目前仍然可用但最终会被移除。从仓库源码看该功能位于独立 cratecrates/atuin-pty-proxy/中并且仅在 Unix 平台编译lib.rs中所有模块均标注#[cfg(unix)]Windows 构建仅提供一个unsupported占位。在crates/atuin/src/command/mod.rs中atuin pty-proxy被注册为顶层子命令同时被pty-proxycargo feature 门控。pty-proxy 解决的两个问题问题一搜索 TUI 的呈现方式。Atuin 的搜索 TUI 长期面临一个权衡要么以全屏 alt-screen 模式接管整个终端要么以内联模式清空你之前的输出。两种方式体验都不理想。有了 pty-proxy 后Atuin 弹窗可以渲染在你原有输出之上关闭弹窗时 pty-proxy 又能把之前的输出完整恢复。问题二命令输出不可见。以往 Atuin 只记录命令文本AI 只能猜命令为什么失败。pty-proxy 位于终端与 Shell 之间因此能够记录每条命令实际打印的内容让 AI 读到真实的错误信息。如果你已经在使用 tmux其实可以不用 pty-proxy 解决第一个问题在 Atuin 配置中设置[tmux] enabled true参考 config 中 tmux 相关小节搜索 UI 就会在窗格上方以弹窗形式打开窗格内容保持不动。命令输出捕获从 OSC 133 标记到 daemon 内存捕获链路pty-proxy 能看到每条命令输出靠的是OSC 133 提示符标记FinalTerm / iTerm2 提出的 prompt markers 数据模型Shell 在提示符、输入行、命令执行、命令结束等时刻向终端输出特定的 OSC 133 转义序列pty-proxy 读取这些标记以此判断一条命令的输出在哪里结束、下一条从哪里开始。具体捕获流程如下Shell 输出 OSC 133 标记如A提示符开始、B命令输入、C命令执行、D命令结束并携带退出码与history_id参数pty-proxy 中的解析线程crates/atuin-pty-proxy/src/screen.rs的spawn_parser_thread把数据同时喂给屏幕快照仿真器与CommandCaptureTrackercrates/atuin-pty-proxy/src/capture.rsCommandCaptureTracker内部用 vt100 终端仿真器渲染输出按 OSC 133 的 zonePrompt / Input / Output跟踪当前处于哪个阶段仅在 Output zone 累积内容收到带history_id的D命令结束标记后把渲染后的输出连同字节数、终端宽高等信息打包成CommandCapture通过CommandCaptureSink回调送出crates/atuin/src/command/mod.rs中semantic_command_capture_config()建立的转发线程把捕获结果通过 daemon 的 gRPC 客户端调用register_command_output交给 daemondaemon 以命令的Atuin history ID为键将输出保存在内存中。捕获的是渲染后的输出而非原始字节流这一点非常关键。由于 pty-proxy 用 vt100 仿真器驱动数据捕获到的输出是最终渲染结果而不是回放的原始转义序列。capture.rs的测试用例crates/atuin-pty-proxy/src/capture.rs给出了直观证明光标绝对定位one\r\ntwo\r\n\x1b[1;1Hzzz\r\n捕获为zzz\ntwo按最终屏幕位置而非写入顺序进度条反复重绘0%\r 50%\r100%\r\n捕获为100%退格擦除oops\x08\x08\x08\x08done\r\n捕获为done滚出屏幕的输出也会通过 scrollback 缓冲保留output_that_scrolls_off_the_screen_is_kept测试。同时CommandCapture结构体还包含output_observed_bytes终端实际观察到的原始字节数与渲染后文本长度不同以及terminal_width/terminal_height这些元数据会被一并交给 daemon。输出截断策略为避免内存无限增长捕获设有上限。CaptureConfig::max_output_bytes来自 Atuin 设置中output.limits().max_output_size见crates/atuin/src/command/mod.rs。当单条命令输出超过上限时捕获采用split_evenly 策略保留输出的开头与结尾两段丢弃中间部分。capture.rs对截断做了很精细的处理两个分片都保证不保留被切断的半行——这是为了后续的密钥脱敏redaction不失效如果AWS_SECRET_ACCESS_KEYxxx恰好在处被切断脱敏正则将无法匹配测试a_credential_split_across_the_cut_does_not_survive验证了无论切断点落在哪里hunter这样的凭证值都不会逃过脱敏output_observed_bytes统计的是终端实际看到的全部字节数与保留多少无关a_capture_that_lost_its_middle_still_reports_every_byte_observed。边界情况与健壮性捕获器对真实终端的各种脏数据做了大量容错均有测试佐证重复的 prompt 标记被容忍命令标记先于 prompt 标记出现部分 Shell 顺序颠倒也能正确处理缺失history_id的结束标记会暂存捕获等待后续带 ID 的标记补上标记被网络/管道切成任意字节片段包括逐字节推送仍能完整识别交替屏幕alt-screen如 vim 全屏编辑器上的输出不会被捕获alternate_screen_output_is_not_captured测试因为那里通常不是命令输出终端尺寸变化resize时捕获内容会按新尺寸重排resizing_reflows_the_capture测试。输出捕获的前置条件输出捕获需要pty-proxy 和 daemon 同时运行且默认什么都不捕获。详细的安装步骤、保留限制与隐私说明见 Reading Command Output。也就是说仅启用 pty-proxy 而没有 daemon 时捕获链路会在crates/atuin/src/command/mod.rs的run_pty_proxy中退化为proxy.run(None, ...)不创建捕获配置。另外当设置了环境变量ATUIN_TERMINAL时也会跳过捕获semantic_command_capture_config中is_truthy_env(ATUIN_TERMINAL)直接返回None。初始化两种方式可共存方式一通过 Atuin 配置推荐最简单的启用方式是在 Atuin 配置文件默认为~/.config/atuin/config.toml中写入[pty_proxy] enabled true设置后你现有的atuin init一行就会自动启动代理无需额外修改 Shell 配置。其实现位于crates/atuin/src/command/client/init.rs的pty_proxy_init()当settings.pty_proxy.enabled为真时atuin init会把 pty-proxy 的 exec 前导脚本atuin_pty_proxy::init_script嵌入到输出的初始化脚本最前面。默认值为falsecrates/atuin-client/src/settings.rs中set_default(pty_proxy.enabled, false)。启动性能提示以这种方式启用时代理在你atuin init所在位置启动该行之前被 source 的所有内容都会在代理内部再执行一遍。这本身无害但为了最快的启动速度请尽量把atuin init行放在 Shell 配置文件的尽可能靠前的位置。方式二显式初始化各 Shell 专属写法你也可以在 Shell 配置中显式初始化 pty-proxy。请把下面的 init 行放在配置文件的尽可能靠前位置并且位于常规atuin init调用之前。两种方式可以安全共存——代理只会启动一次。 zshshell eval $(atuin pty-proxy init zsh) bashshell eval $(atuin pty-proxy init bash) fish将下面的代码加入 ~/.config/fish/config.fish 的 is-interactive 代码块 shell atuin pty-proxy init fish | source Nushell在 Nushell 中执行 shell mkdir ~/.local/share/atuin/ atuin pty-proxy init nu | save -f ~/.local/share/atuin/pty-proxy-init.nu 然后在 config.nu 中、**常规 atuin init 之前**加入 shell source ~/.local/share/atuin/pty-proxy-init.nu Nushell 的 source 命令要求静态文件路径所以必须先预生成该文件。如果atuin不在 PATH 中如果atuin二进制默认不在PATH里你应在设置好 PATH 之后立刻初始化 pty-proxy。例如一个将 Atuin 安装在~/.atuin/bin/atuin的 bash 用户配置可以这样写export PATH$HOME/.atuin/bin:$PATH eval $(atuin pty-proxy init bash) # ... 其他 shell 配置 ... eval $(atuin init bash)init 脚本做了哪些事源码级解读atuin pty-proxy init shell生成的不是普通的环境变量而是一段把当前 Shell 重新 exec 进 pty-proxy 的前导脚本crates/atuin-pty-proxy/src/pty_proxy.rs的init_script。以 bash/zsh 共享的BASH_ZSH_INIT为例脚本逻辑如下判断当前是否为交互式 Shell、stdin/stdout 是否为 TTY以及是否已经处于代理中通过__atuin_pty_proxy_owns_tty变量防重复调用atuin __internal pty-proxy-active见crates/atuin/src/command/client/internal.rs询问这个终端是否已经跑在 Atuin PTY 代理里返回 1 则说明已经是代理子进程不再重复启动若此前代理启动失败设置了ATUIN_PTY_PROXY_FAILED环境变量则停止避免无限循环地尝试生成新代理否则exec atuin pty-proxy --shell $BASHbash或exec atuin pty-proxy --shell ${${_atuin_pty_proxy_zsh#-}:c}zsh把自己替换为代理进程。pty_proxy.rs的测试every_init_execs_pty_proxy、every_init_asks_atuin_whether_this_terminal_has_a_proxy、init_no_ops_when_emitted_twice分别验证了必定 exec 代理必定询问代理状态重复 emit 不会重复检测这几条保证。关于--shell参数每个 Shell 都会把自己的解释器绝对路径内嵌进--shell参数这样 pty-proxy 启动的是 source 了 init 的那个二进制而不是通过$PATH解析否则在同时装有/usr/bin/bash与/opt/homebrew/bin/bash的机器上可能选错。zsh 优先用ZSH_ARGZEROzsh 5.3处理了登录 Shell 的-zsh前导横线并用:c修饰符把裸命令名解析为绝对路径。CLI 参数速览atuin pty-proxy命令本身crates/atuin-pty-proxy/src/pty_proxy.rs支持参数说明--debug-osc133高亮 OSC 133 的 prompt / input / output / exit-code 区域用于调试--shell PATH指定 pty-proxy 应启动的 Shell 二进制路径默认使用系统登录 Shell仅在无子命令时有效init [shell]输出指定 Shell 的初始化脚本省略 shell 时自动检测依次检查命令行参数、ATUIN_SHELL、SHELL环境变量失败时要求显式指定 bash / zsh / fish / nu--debug-osc133也可通过环境变量ATUIN_PTY_PROXY_DEBUG1开启RuntimeOptions::new中env_flag(ATUIN_PTY_PROXY_DEBUG)。开启后终端中会看到类似[OSC133:A prompt]、[OSC133:D exit0]的标注见screen.rs的debug_highlighting_reaches_the_screen_but_not_the_capture测试——这些标注只出现在屏幕快照里不会混入捕获输出。工作原理代理如何透明地接管终端atuin pty-proxy不带子命令运行的执行体在crates/atuin-pty-proxy/src/runtime.rs的run()中大致流程如下创建 PTY 对读取当前终端尺寸用portable_pty的native_pty_system().openpty()创建一对主从 PTY尺寸与终端一致建立屏幕服务 socket以当前 TTY 的设备标识TtyId包含 dev 与 rdev 两个部分在安全临时目录/tmp/atuin-uid/中生成 socket 路径如pty-proxy-24-34828.sock见screen.rs的socket_name绑定UnixListener并启动SocketServer线程——搜索 TUI 的弹窗屏幕快照就是从这个 socket 读取的socket 的命名同时包含 dev 和 rdev避免多路复用器窗格与容器内devpts编号重启造成的碰撞测试socket_names_differspawn 子 Shell在从 PTY 上启动指定的 Shell默认取--shell或系统登录 Shell并设置环境变量ATUIN_PTY_PROXY_ACTIVE1、ATUIN_PTY_PROXY_SOCKETsocket 路径若 socket 初始化失败则改为设置ATUIN_PTY_PROXY_FAILED1防止子 Shell 无限尝试再启代理set_child_env及对应测试同时把SHELL环境变量修正为实际 spawn 的 Shell 路径并恢复用户启动时的 umaskAtuin 启动早期会设置严格 umask不能让它泄漏给 Shell见runtime.rs对 issue #3695 的注释数据泵一个线程把从 PTY master 读到的数据原样写回 stdout同时拷贝一份送给解析线程供屏幕快照与输出捕获使用若开启--debug-osc133则先经过高亮器另一个线程把 stdin 数据写入 PTY master信号与尺寸监听SIGWINCH终端尺寸变化时同步调整 PTY 尺寸并通知解析线程spawn_resize_handler同时CwdUpdater持续同步代理进程的 CWD 到子 Shell 的 CWD保证 tmux 等程序能正确追踪工作目录退出等待子 Shell 退出恢复终端 raw mode清理 socket 文件以子进程退出码退出退出码超限时兜底为 1见process_exit_code测试。屏幕快照与弹窗搜索crates/atuin-pty-proxy/src/screen.rs的解析线程维护一个 vt100 屏幕仿真器带 50 行 scrollback 容量用于应对终端尺寸收缩再恢复时的内容还原。搜索 UI 需要弹窗时客户端通过 socket 发出ScreenRequest服务端把编码后的屏幕内容wire 格式为[rows: u16 BE][cols: u16 BE][cursor_row: u16 BE][cursor_col: u16 BE]后跟每行[len: u32 BE][行内预生成 ANSI 字节]见encode_screen写回。客户端无需自己的 vt100 解析器直接把预格式化好的 ANSI 逐行写到 stdout 即可叠加渲染。在crates/atuin/src/command/client/search/interactive.rs中当检测到当前运行在 pty-proxy 内atuin_pty_proxy::parent_socket_path()能取到 socket且请求了 inline 模式时搜索 UI 会切换到popup 模式它先抓取当前屏幕快照保存渲染自己的界面退出时再把快照内容恢复回去——这就是弹窗叠加在输出之上、关闭后完美还原的实现原理。一个重要的只属于直接子进程约束screen.rs的is_pty_proxy_child()/parent_socket_path()判定逻辑是只有当当前进程的终端就是代理创建的那个子 PTY时才认为在代理里。如果中间隔着 tmux / screen 的 PTY则判定为不在代理内测试a_shell_in_a_pty_nested_inside_the_proxy_is_not_attached用双层 PTY 验证了这一点。这意味着在代理内再开 tmux其窗格不会继承弹窗与屏幕快照能力——这也正是官方文档建议tmux 用户直接使用[tmux] enabled true的原因。隐私、保留策略与权限控制输出捕获涉及命令的实际输出因此隐私设计是 pty-proxy 文档与实现的重中之重。官方说明集中在 Reading Command Output要点如下仅内存存储捕获的输出保存在 daemon 的内存中只存在于本机保留上限每条命令最多保留 1MB 输出每个 Shell 会话保留最近 128 条命令的输出合计最多 32MB超限截断单条输出超过 1MB 时保留开头 512KB 与结尾 512KB——这两段通常是最有价值的部分生命周期daemon 停止时输出即丢失只有 daemon 运行期间捕获的命令才可用随历史删除删除某条历史记录时其捕获的输出也会一并删除仅记录入库命令Atuin 只为进入历史记录的命令保留输出。如果某命令未被记录例如store_failed false时失败的命令其输出也会被丢弃按需发送Atuin 不会主动把任何输出发给 LLM只有当 LLM 请求某条具体命令的输出时才会发送且默认情况下 Atuin AI 会先征求你的许可。在实现层crates/atuin/src/command/mod.rs的转发线程还做了一层密钥脱敏当settings.secrets_filter开启时输出会经过atuin_common::secrets::redact()处理把疑似凭证如AWS_SECRET_ACCESS_KEY...替换为掩码后再交给 daemon——因为输出里可能包含命令行从未显示过的敏感信息例如cat .env。脱敏只在确实有内容被替换时才复制字符串干净输出绝大多数情况零拷贝直达 daemon。权限控制输出读取由AtuinOutput权限规则控制见 Tools Permissions。如果希望 Atuin AI 每次读取输出前不再询问可配置[permissions] allow [AtuinOutput]要彻底关闭该能力在 Atuin 配置中把ai.capabilities.enable_history_output设为false参见 settings 文档。与 Atuin AI 及其他 Agent 的联动捕获输出最大的价值在于让 AI 看到真实发生了什么Atuin AI 可以回答这条命令为什么失败了——它通过AtuinOutput工具读取真实错误信息而不是仅凭命令文本猜测Claude Code、Cursor 等外部 Agent 可以通过 Atuin 的 MCP server 做同样的事。启动输出读取的三步走详见 Reading Command Output启用 daemon配置[daemon] enabled true, autostart truedaemon 的完整说明见 daemon 参考文档按上文任一方式启用 pty-proxyinit 行放在atuin init之前重启 Shell或重新 source 配置。此后该会话中每条命令的输出都会被捕获并提供给 AI。验证方式故意运行一条会失败的命令然后在搜索界面按?打开 Atuin AI 并询问失败原因它会请求使用AtuinOutput工具读取输出后给出基于真实错误的回答。支持状态与注意事项Shell支持等级说明zshTier 1官方积极支持bashTier 1官方积极支持fishTier 1官方积极支持nushellTier 2社区支持pty-proxy 可用但 inline 弹窗、dotfiles、Atuin AI 等功能暂不支持平台方面pty-proxy 目前仅支持 UnixLinux、macOS、WSL-2 等Windows 的 Tier 1 支持矩阵中明确标注无 pty-proxy见 docs/docs/support.md。macOS 上注意alt#回放等个别键位差异。几点实操提醒daemon 必须同时运行输出捕获依赖 daemon 的内存存储单独启用 pty-proxy 不会产生任何捕获启动顺序显式 init 时atuin pty-proxy init行必须位于常规atuin init之前且尽量靠前以减少 Shell 配置在代理内重复执行的开销多路复用器兼容性代理内部再嵌套 tmux/screen 时其窗格不享受弹窗屏幕快照若你是 tmux 用户优先使用[tmux] enabled true方案调试遇到 OSC 133 区域划分异常时可用atuin pty-proxy --debug-osc133启动并观察 prompt / input / output / exit-code 各区域的标注辅助定位 Shell 集成脚本问题。参考路径速查官方参考文档docs/docs/reference/pty-proxy.md、docs/docs/ai/command-output.md、docs/docs/reference/daemon.md、docs/docs/support.md核心实现crates/atuin-pty-proxy/src/pty_proxy.rsCLI 与 init 脚本、crates/atuin-pty-proxy/src/runtime.rsPTY 运行时、crates/atuin-pty-proxy/src/capture.rsOSC 133 捕获与截断、crates/atuin-pty-proxy/src/screen.rs屏幕快照与 socket 服务集成点crates/atuin/src/command/mod.rs捕获配置与 daemon 转发、crates/atuin/src/command/client/init.rspty_proxy.enabled自动初始化、crates/atuin/src/command/client/internal.rspty-proxy-active探测、crates/atuin/src/command/client/search/interactive.rspopup 模式设置项crates/atuin-client/src/settings.rsPtyProxy { enabled }默认false【免费下载链接】atuin✨ Making your shell magical项目地址: https://gitcode.com/gh_mirrors/at/atuin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考