WezTermpane:send_text()深度指南原样向 Pane 写入文本的 Lua API 与 CLI 实践【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/weztermpane:send_text(text)是 WezTerm 的 Pane 对象 提供的最基础输入方法之一用于把一段文本原样as-is写入目标 pane 的输入流不经过剪贴板、也不做任何换行或粘贴协议处理。它常被用于启动自动化gui-startup、超链接回调、交互选择器回填等场景是配置驱动终端行为的核心粘合剂。读完本文你将掌握send_text的精确语义与底层实现链路、它与send_paste/paste的本质区别以及如何在 Lua 配置与wezterm cli命令行中正确使用它。方法与核心语义send_text自 20220624-141144-bd1b7c5d 版本起可用其 Lua 方法签名如下pane:send_text(text)参数text字符串类型是要发送到 pane 的文本。返回值无。写入失败时例如 pane 已关闭或底层 I/O 报错会抛出 Lua 错误。语义文档原文只有一句话——Sends text to the pane as-is即逐字节原样发送不做任何转换。这意味着不会像粘贴那样经过剪贴板不会按canonicalize_pasted_newlines重写换行符不会因应用开启了 bracketed paste 模式而包裹粘贴标记。一个典型调用是把换行符显式拼进文本里模拟敲下回车pane:send_text(cargo build\n)由于是原样发送若省略结尾的\n或\r命令只会出现在输入行中而不会被执行——这是send_text使用中最常见、也最容易踩到的坑。源码实现从 Lua 到 PTY 的完整写入链路send_text的 Lua 绑定位于 lua-api-crates/mux/src/pane.rs#L118-L125其核心逻辑非常精简methods.add_method(send_text, |_, this, text: String| { let mux get_mux()?; let pane this.resolve(mux)?; pane.writer() .write_all(text.as_bytes()) .map_err(|e| mlua::Error::external(format!({:#}, e)))?; Ok(()) });可以拆解出三个关键步骤解析 pane 句柄this.resolve(mux)把 Lua 侧的 Pane 对象解析为当前 mux 实例中真实存在的 pane依据 mux/src/pane.rs 中Panetrait 对pane_id的关联。获取写入端pane.writer()返回MappedMutexGuard_, dyn std::io::Write见 mux/src/pane.rs#L249即该 pane 的输出流。原样写字节write_all(text.as_bytes())直接把字符串转成 UTF-8 字节写入与粘贴路径完全解耦。对于本地 panewriter()的实现在 mux/src/localpane.rs#L428-L434它映射到该 pane 所关联伪终端PTY的写入端因此send_text的内容最终会进入 PTY 的输入通道等效于用户直接在终端里键入这些字符。从代码结构看远端 pane如 SSH domain的writer则会走客户端通道把数据投递到远端两种场景下原样发送的语义保持一致。send_text与send_paste/paste的关键区别Pane 对象同时提供了三个向 pane 喂文本的方法语义差异直接影响选型方法语义换行符处理bracketed pastepane:send_text(text)原样写入输入流as-is完全不处理不参与pane:send_paste(text)模拟剪贴板粘贴按canonicalize_pasted_newlines重写bracketed paste 模式下不重写终端开启时按 bracketed paste 发送pane:paste(text)与send_paste等价同上同上对比文档 send_paste 指出send_paste的效果是像从剪贴板粘贴但实际不涉及剪贴板并且新行会依据canonicalize_pasted_newlines被重写例如在 cmd.exe 场景转换为 CRLF、在 Unix 场景保持 LF。而send_text完全没有这层约定它适合发送精确可控的字节流比如命令串、快捷键序列或结构化协议文本send_paste则适合把大段带换行的内容贴进全屏编辑器vim、less 等而不会触发误执行。实现上二者也完全分叉send_paste调用pane.send_paste(text)见 lua-api-crates/mux/src/pane.rs#L100-L106本地实现进一步交给终端模拟器层处理换行与粘贴模式见 mux/src/localpane.rs#L440-L447而send_text始终直通writer。实战场景一gui-startup中的启动编排send_text最常见的用途是在 GUI 启动时自动铺设开发环境。gui-startup事件gui-startup 文档在wezterm start启动、默认程序创建之前触发一次适合在其中创建窗口并立即向 pane 注入命令。下面节选自官方gui-startup文档中的双 workspace 启动示例创建 coding workspace 后在构建 pane 里立刻执行cargo build并为 automation workspace 的 pane 预填一条命令local wezterm require wezterm local mux wezterm.mux local config {} wezterm.on(gui-startup, function(cmd) local args {} if cmd then args cmd.args end local project_dir wezterm.home_dir .. /wezterm local tab, build_pane, window mux.spawn_window { workspace coding, cwd project_dir, args args, } local editor_pane build_pane:split { direction Top, size 0.6, cwd project_dir, } -- 在构建 pane 中立即启动构建任务 build_pane:send_text cargo build\n local tab, pane, window mux.spawn_window { workspace automation, args { ssh, vault }, } mux.set_active_workspace coding end) return config注意示例中命令尾部显式携带\n因为send_text原样发送回车必须由调用方提供否则 shell 只会把字符排到提示符后而不执行。实战场景二超链接回调中驱动 ShellWezTerm 的超链接配方hyperlinks 配方展示了send_text更精细的用法当用户点击一个file://超链接时通过open-uri事件判断前台进程是否为 shell若是则直接把cd/ls/ 编辑器命令敲进当前 paneif uri:find ^file: 1 and not pane:is_alt_screen_active() then local url wezterm.url.parse(uri) if is_shell(pane:get_foreground_process_name()) then local success, stdout, _ wezterm.run_child_process { file, --brief, --mime-type, url.file_path, } if success then if stdout:find directory then pane:send_text( wezterm.shell_join_args { cd, url.file_path } .. \r ) pane:send_text(wezterm.shell_join_args { ls, -a, -p, --group-directories-first, } .. \r) return false end -- 文本文件则在当前 pane 中打开编辑器 if stdout:find text then pane:send_text( wezterm.shell_join_args { nvim, url.file_path } .. \r ) return false end end end end这里用wezterm.shell_join_args对路径做正确的 shell 转义再拼接\r触发执行——既避免了手动拼接字符串的注入风险也体现了先构造命令、再原样送入的推荐写法。实战场景三InputSelector 交互回填send_text也常与 InputSelector 配合用户在弹出选择器中选定条目后把所选内容写回终端。官方示例中回调拿到id/label后直接调用pane:send_text(id)action wezterm.action_callback(function(window, pane, id, label) if not id and not label then wezterm.log_info cancelled else wezterm.log_info(you selected , id, label) pane:send_text(id) end end)对于这种把选择结果注入输入行的需求send_text的原样语义正是关键它不会像send_paste那样可能触发换行重写把半成品文本直接变成一次误执行。CLI 等价命令wezterm cli send-text在 Lua 配置之外WezTerm 还提供同源功能的命令行工具wezterm cli send-textCLI 文档。与 Lua API 的原样发送不同CLI 版本默认以类似粘贴的方式发送若目标 pane 处于 bracketed paste 模式文本会被包装为 bracketed paste--no-paste选项则切换为直通发送语义与 Lua 的send_text对齐。$ wezterm cli send-text hello there也可以从标准输入读取文本$ echo hello there | wezterm cli send-text完整参数源自 send-text 帮助文档Usage: wezterm cli send-text [OPTIONS] [TEXT] Arguments: [TEXT] The text to send. If omitted, will read the text from stdin Options: --pane-id PANE_ID Specify the target pane. The default is to use the current pane based on the environment variable WEZTERM_PANE --no-paste Send the text directly, rather than as a bracketed paste -h, --help Print help--pane-id的默认解析依赖WEZTERM_PANE环境变量见 wezterm/src/cli/send_text.rs#L24-L25即当前 pane的定位由 shell 集成注入的环境变量决定命令实现上--no-paste分支通过WriteToPane通道原样写入默认分支通过SendPaste通道按粘贴处理见 wezterm/src/cli/send_text.rs#L38-L49。使用要点与边界换行必须自理send_text不做任何补全要让命令立即执行务必自带\r回车或\n换行根据目标程序对换行风格的敏感度选择。若通过wezterm cli send-text从 stdin 送整段文本管道输入通常已包含换行无需额外处理。不参与 bracketed paste向 vim、less 等全屏程序发送命令时send_text的内容按普通键盘输入处理不会被打包成粘贴块需要粘贴语义时改用send_paste/paste。错误处理写入失败会抛出 Lua 错误错误信息包含底层 I/O 原因在事件回调中建议用pcall包裹或配合日志观察。目标必须是 Pane本方法属于 Pane 对象事件回调的pane参数、或mux.spawn_window返回值中的 pane 均可用对窗口级别做输入注入不存在等价 API。文本编码字符串按 UTF-8 字节写入非 ASCII 内容同样原样透传无需额外转义。小结pane:send_text(text)以最直白的原样写入语义成为 WezTerm Lua 配置中自动化终端输入的基础设施实现上它直接穿透到 pane 的 writer本地即 PTY 写入端语义上与走剪贴板、换行重写、bracketed paste 的send_paste明确分家。从gui-startup启动编排、超链接回调驱动 shell到 InputSelector 回填再到wezterm cli send-text的外部注入理解原样、自理换行这六个字就能准确驾驭这一 API 的全部用法。【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/wezterm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考