expect-pty 0.7.4 → 0.7.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2b48d4fb81d2c6f7035133387df5641fb420b5c108e7257c2348f4ad119edecf
-  data.tar.gz: c6dcfa0a5edc30db418739decdaa262a480e905a234ddf179c67c609edac56a4
+  metadata.gz: 1052a03b9bb9ac46051468e651c168d714f6be11aabd4bd8e2171dd390e2065a
+  data.tar.gz: 7c178220cc65517015144b2711679a3a26739efe1156dd144a26cb64fdfd6b46
 SHA512:
-  metadata.gz: 3a310e67d4303ebc2d9a2db7231722ab59b52a46bca2cf1aa32a1abd0de63a956867c17f4013df5029d21e4df509c8c6980fcc4193484f1e485b84e0933dff64
-  data.tar.gz: 19a972f1e1c19a64ba9b18f2148d0436c2f0a4211261f4a3396447b5863d8e6ac9e8f30322cb28e92ef45a5e8801dc519593c6a82044dacb42fe33b0ed17b1e0
+  metadata.gz: 31b82ff772bc59ec35a4e3318be96b2b9c4b240898395c1bd8c543ed67515461d9ba282da415a1e208fbd9fb8f03390445cec132725873a039b3d75181fc552d
+  data.tar.gz: 1a7d7adfd64345c4e0d405657edd252e841430f65c335dc638708f43cdf20c4c12b4b8da28fe70b235801f8af50905595a6f982035a5ff73e9baafd02c8453d3

data/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## Unreleased
 
+## 0.7.6 - 2026-10-09
+
+- 修复会话关闭时日志异常覆盖原始错误的问题，保留进程等待、线程中断或句柄关闭的失败原因，并继续尝试完成诊断与 transcript 收尾。
+- 优化长秘密的流尾脱敏和长字面转义扫描，减少近似前缀输入下的耗时与临时对象，保持分片、重叠和部分秘密的过滤行为。
+
+## 0.7.5 - 2026-10-08
+
+- 修复 PTY、启动错误管道和工厂初始化的异步中断交接窗口；线程中断或终止后立即关闭已取得的句柄，保持用户初始化协议可中断。
+- 修复 `write_transcript` 在对象转换期间切换或禁用目标时的记录归属；整条补记与脱敏尾部交付到同一目标。
+- 将纯文本扫描组和 EOF 处理器索引在模式声明完成时编译，减少多来源 EOF 派发的重复扫描；保留来源身份、声明顺序、显式冻结和规则复用行为。
+- 使用增量 KMP 扫描长字面转义的潜在后缀，并按冻结规则复用前缀表，避免未命中时逐短前缀比较造成平方耗时和大量临时字符串。
+- 更新 RubyGems 摘要和文档入口，直接描述 Ruby PTY Gem；README 改为英文默认首页，精简快速开始并提供独立简体中文版及文档导航。
+
 ## 0.7.4 - 2026-10-06
 
 - **连续匹配**：修复回调中嵌套读取相同内容的新消息后漏触发匹配、最终超时的问题，保留零宽匹配和同值赋回的防空转保护。

data/README.md

@@ -2,442 +2,55 @@
 
 [![CI](https://github.com/gatework/expect-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/gatework/expect-ruby/actions/workflows/ci.yml)
 
-用 Ruby 自动操作交互式程序：启动拥有控制终端的子进程，等待文本或正则，发送输入，处理超时、EOF 和回调，也能接管已有
-IO、同时监听多个会话和转接人工交互。交互能力参考 [Expect.pm](https://github.com/jacoby/expect.pm)，接口采用 Ruby
-的属性、关键字参数和代码块。
+[English](README.md) · [简体中文](README.zh-CN.md)
 
-要求 **Ruby 3.4+、POSIX 系统（Linux/macOS）**。运行时仅使用 Ruby 标准库，其中可独立安装的 gem 已在 gemspec 中声明，由
-RubyGems/Bundler 解析。推荐入口 **`require "expect/pty"`**；本项目提供独立的 `Expect` 模块和 `Expect::Session` 会话，不修改标准库的
-`IO#expect`。
+A Ruby library for automating interactive programs through POSIX pseudo-terminals. Start a child process, wait for text or regular expressions, send input, and manage timeouts, callbacks, and cleanup with Ruby objects and blocks.
 
-源码中的解释性注释主要使用中文；欢迎用中文或英文提交 issue 和 PR，参与方式见 [贡献指南](CONTRIBUTING.md)。
+RubyGems package: **expect-pty**. Requires Ruby 3.4+ on Linux or macOS.
 
-## 安装和运行
+## Install
 
-项目和仓库名为 `expect-ruby`，Gem 名为 `expect-pty`。在应用的 Gemfile 中添加以下内容，然后运行 `bundle install`：
+Add the gem to your Gemfile:
 
-```ruby
-gem "expect-pty", "~> 0.7.4", require: "expect/pty"
-```
+~~~ruby
+gem "expect-pty", require: "expect/pty"
+~~~
 
-也可直接执行 `gem install expect-pty`。需要跟随开发分支时，可从 GitHub 安装：
+Then run `bundle install`, or install it directly with `gem install expect-pty`.
 
-```ruby
-gem "expect-pty", git: "https://github.com/gatework/expect-ruby.git", branch: "main", require: "expect/pty"
-```
+## Quick start
 
-本地开发可改用 `gem "expect-pty", path: "/path/to/expect-ruby", require: "expect/pty"`，也可在源码目录构建安装：
-
-```sh
-mkdir -p tmp
-gem build expect-pty.gemspec --output tmp/expect-pty-0.7.4.gem
-gem install ./tmp/expect-pty-0.7.4.gem
-```
-
-```ruby
+~~~ruby
 require "expect/pty"
 
-Expect.spawn("/bin/sh", "-i") do |shell|
-  shell.puts("printf 'hello ruby\\n'")
-  if shell.expect(/^hello ruby\r?$/, timeout: 3).matched?
-    puts shell.match
-  else
-    warn shell.error
-  end
-  shell.puts("exit")
-  shell.soft_close(timeout: 2)
-end
-```
-
-块返回其执行结果，退出时关闭会话并回收子进程，异常和 `break` 也执行清理。构造或启动失败时同样释放已创建的资源；清理中的
-`StandardError` 不替换本次作用域已有的主异常，没有主异常时仍传播；清理中新发生的 `Interrupt` / `SystemExit` 不吞掉。
-无块形式需用 `ensure` 显式调用 `close`。`Expect::Session.new` 可以先创建 PTY，通过 `slave.echo=` /
-`slave.winsize=` 设置终端，然后调用 `session.spawn`。工厂返回、回调参数和 `Result#session` 都是同一个真实 Session。
-
-多个命令参数原样传给 Ruby `exec`；单个命令字符串使用 Ruby 的 shell 语义。不可信参数应使用独立参数形式。支持
-`env: { "NAME" => "value" }` 和 `chdir: "/path"`。同一会话只能启动一次，启动失败抛出 `Expect::SpawnError`。
-
-## 会话设置与操作参数
+program = "STDOUT.sync = true; print 'ready>'; STDIN.gets; puts 'done'"
+Expect.spawn("ruby", "-e", program) do |session|
+  prompt = session.expect("ready>", timeout: 5)
+  raise "child did not become ready" unless prompt.matched?
 
-```ruby
-logger = Logger.new($stderr, level: Logger::INFO)
-Expect.spawn("/bin/sh", "-i", timeout: 3, buffer_limit: 65_536,
-             logger: logger, outputs: [$stdout]) do |session|
-  session.timeout = 5
-  session.puts("exit")
+  session.puts("continue")
+  result = session.expect("done", timeout: 5)
+  puts result.match if result.matched?
 end
-```
-
-所有设置显式传给会话，不提供全局默认配置或配置基类。需要应用默认值时，由调用方保存 Hash，再用关键字展开传入。
-各会话独立保存以下属性，修改不会影响其他会话；借用的 logger、transcript 和输出对象可以由调用方共享。
-
-| 会话属性        | 默认值 | 行为                                                  |
-|-----------------|--------|-------------------------------------------------------|
-| `timeout`       | `nil`  | `session.expect` 的默认相对期限；`nil` 无限、`0` 轮询 |
-| `write_timeout` | `nil`  | 写入遇到背压或 EINTR 时的等待期限                     |
-| `buffer_limit`  | `nil`  | 匹配缓冲保留的尾部字节数；正整数或 `nil`              |
-| `logger`        | `nil`  | 借用支持 `add` / `debug?` 的诊断 logger               |
-| `transcript`    | `nil`  | 借用支持 `write` 的接收字节记录目标                   |
-| `outputs`       | `[]`   | 原始接收字节的转发目标数组，可包含 `$stdout`          |
-
-这些属性都有同名 reader/writer；非法赋值不改变原设置。超时必须有限且非负。输出数组在设置时复制，读取时也返回副本。
-
-只属于一次操作的策略放在该操作的关键字中：`spawn(raw: false)` 控制子终端，`expect(consume: true,
-reset_timeout_on_read: false)` 控制匹配消费和输入重置，`interact(raw: true)` 控制本地终端模式，
-`close(graceful: false)` 控制清理顺序。工厂的 `graceful:` 决定块退出时的关闭策略。`Session.new` 只接收会话属性，
-命令、`env:`、`chdir:` 和 `raw:` 由之后的 `session.spawn` 接收；均无旧名称别名。
-
-## 等待和匹配
-
-```ruby
-session.expect("literal text", /value=(\d+)/, timeout: 5)
-session.timeout = 5
-session.expect("ready")                # 使用会话超时
-session.expect("ready", timeout: nil)  # 无限等待
-session.expect("ready", timeout: 0)    # 匹配现有缓冲，并最多轮询读取一次
-session.expect(timeout: 1)             # 仅收集输出，直到超时或 EOF
-```
-
-字符串始终按字面匹配，包括 `"-i"`、`"-re"`、`"timeout"` 和 `"eof"`；正则直接使用 Ruby `Regexp`
-。按声明顺序选择第一个能匹配的模式，不按它们在文本中的位置排序。返回不可变 `Expect::Result`，`number` 为模式的 **1
-起始序号**；超时、EOF 或 IO 错误时 `number` 为 `nil`。
-判断成功使用 `matched?`，不能直接判断 Result 对象的真值。超时使用单调时钟。
-
-```ruby
-result = session.expect(/value=(\d+)/, timeout: 3)
-result.matched?
-result.timeout?
-result.eof?
-result.number
-result.captures
-result.session
-result.error # nil、:timeout、:eof 或原始 IOError / SystemCallError 对象
-
-result => { number:, match:, captures: }
-```
-
-`Result` 使用原生 Ruby `Data`，支持 `to_h`、位置和键模式解构。结果、文本和捕获数组均为不可变快照；
-来源会话与原始异常保持原对象。不提供字段写入、`to_a` 或隐式 `to_ary`。会话提供 `last_result`，以及 `match`、
-`before`、`after`、`match_number`、`captures`、`error` 快捷读取方法。
-
-成功匹配后删除匹配内容及其之前的内容，尾部留给下次匹配；超时保留缓冲，EOF 将未匹配内容放入 `before` 并清空缓冲。EOF
-与子进程退出是不同事件，使用 `wait` / `process_status` 判断进程结果。底层 IO 错误保留原始异常，回调中的普通异常直接抛出。
-
-接收缓冲、匹配和捕获值为 `ASCII-8BIT` 字节串，保留控制字符、NUL 和无效 UTF-8。固定 UTF-8
-正则会等待读取末尾拆开的字符收齐后再匹配，以免尾部锚点提前命中；显示捕获内容时可 `.dup.force_encoding("UTF-8")`
-。任意二进制流请用字面字符串或二进制正则 `/.../n`。固定 UTF-8 正则遇到无效数据抛出 `EncodingError`；EOF
-时仍未收齐的字符也属于无效编码，匹配缓冲保留原字节供诊断或二进制匹配。缓冲上限按字节截断，应为文本设置足够的上限。
-
-正则完全遵循 Ruby：`^` / `$` 是行锚点，`\A` / `\z` 是整个缓冲的锚点，`/m` 让点号匹配换行；不再提供全局正则模式开关。
-
-IO 等待的 `timeout` 不会中断单次正则计算。处理用户提供的正则或不可信长输出时，应使用有限时的正则实例，例如
-`Regexp.new('prompt>\\s*', timeout: 0.05)`；该限制同样适用于 `on_sequence`。正则超时原样抛出 `Regexp::TimeoutError`
-，匹配缓冲保留，库不会修改进程全局 `Regexp.timeout`。`timeout: 0` 仍会匹配已有缓冲，不代表禁止正则计算。长输出可用日志保存全文，按业务需要设置
-`buffer_limit` 限制匹配窗口；缩小窗口会改变 `before` 和跨窗口匹配范围。
-
-`session.buffer_discarded_bytes` 是只读的会话累计计数，只统计 `buffer_limit` 裁剪掉的字节。
-读取新数据、赋值 `buffer` 或调低上限触发裁剪时递增；成功匹配、`clear_buffer`、EOF 消费和转接交接均不计入。
-关闭会话不会清零。日志在实际读取时保存完整接收内容，不受匹配窗口裁剪影响；它可按显式注册的秘密脱敏。
-
-## 回调、事件与多会话
-
-```ruby
-session.expect(timeout: 10) do
-  on(/username:\s*/i) do |connection|
-    connection.puts("demo")
-    Expect.continue
-  end
-  on(/password:\s*/i) do |connection|
-    connection.puts(password)
-    Expect.continue(reset_timeout: false)
-  end
-  on("ready>")
-  eof { |connection| warn "EOF: #{connection.before}" }
-  timeout { |sessions| warn "timeout: #{sessions.length} session(s)" }
-end
-```
-
-回调通过闭包访问局部变量。无参数声明块在模式构建器中执行；希望保留调用方 `self` 时使用 `do |patterns|`，调用
-`patterns.on(...)`。所有模式注册完成后才读取 IO；注册异常或 `break` 不消费输入。块和位置模式不能混用。注册完成后规则冻结，回调不能再向本次等待追加模式。
-
-`Expect.continue` 继续等待并重新计时；`Expect.continue(reset_timeout: false)`
-保留原期限。回调返回后若保留的期限已过，不再扫描新的文本匹配，未消费的输入留给下一次等待。无回调或返回其他值时结束本次匹配。超时回调只有返回重置计时的
-`Expect.continue` 才再次等待。EOF 回调继续时移除该源并等待其余会话；已知的 EOF 仍依次派发，全部 EOF 时直接返回，期限已过时仅对剩余活跃源触发超时。
-
-`expect` 另接受 `deadline:`，值为 `Expect.monotonic` 时钟上的绝对秒数，`nil` 表示不设总期限。总期限与普通
-`timeout` 取较早者，接收重置、文本/EOF 继续及超时回调均不能延长它。同一个 deadline 可用于连续多次等待：
-
-```ruby
-deadline = Expect.monotonic + 60
-session.expect("ready", timeout: 5, deadline: deadline, reset_timeout_on_read: true)
-session.expect("done", timeout: 5, deadline: deadline, reset_timeout_on_read: true)
-```
-
-上例每次等待允许最多 5 秒无新输入，两次等待共用 60 秒总预算。到达总期限后返回超时，不消费已缓冲的文本或读取新数据；已经确认的
-EOF 仍可派发，全部来源结束时返回 EOF。`timeout: 0`
-在总期限尚未到达时仍保留一次非阻塞轮询。总期限使用协作检查，不中断正在执行的回调、同步日志或单次正则；正则完成后若总期限已到，不消费其匹配结果。它不自动传给回调中的写入或其他操作。
-
-`eof` / `timeout` 声明会占用模式序号，但事件返回的 `number` 为 `nil`。一个等待只能注册一个超时回调；它接收
-**所有仍在监听的会话**。不需要回调时，可将 `:eof` / `:timeout` 作为位置事件参数。
-
-```ruby
-Expect.expect(timeout: 5) do
-  on(/ready/, from: [first, second]) { |connection| puts connection.inspect }
-  on("done", from: third)
-end
-
-Expect.expect("ready", from: [first, second], timeout: 5)
-```
-
-`from:` 指定一个或多个会话；实例块默认当前会话，模块方法需提供来源。相邻且来源列表按对象身份及顺序相同的模式组成一组，按组、会话、模式顺序匹配。模块方法省略超时为无限等待。
-
-`expect(consume: false)` 时，继续回调通常应自行消费匹配，例如 `connection.buffer = connection.after`
-。如果回调没有改变缓冲，当前模式会等待缓冲变化后才重新匹配，避免反复处理同一内容。被信号中断的匹配 select/read 会自动重试，保留原期限。
-
-## 已有 IO、写入和终端
-
-```ruby
-Expect.open(socket) do |connection|
-  connection.expect("prompt>", timeout: 5)
-  connection.puts("command")
-end
-
-ready = Expect.readable_sessions(first, second, timeout: 5)
-```
-
-`Expect.open` 支持可 `select` 的 File、管道、Socket 和 PTY，`writer:` 可指定独立写端。默认借用 IO，关闭会话不关闭原始 IO；
-`own: true` 转移关闭责任，初始化中的属性校验失败也会释放接管的 IO。未知关键字在 Ruby 调用入口拒绝，此时不接管 IO。`StringIO`
-可以用作 transcript 和 outputs，不能用作读取会话。
-
-用于写入或转接的真实 IO 应在首次写入前设置 `io.sync = true`，并由调用方保证没有未刷新的 Ruby 写缓冲；`write_nonblock`
-可能先阻塞刷新已有缓冲，这一步不受本库的 IO 等待期限控制。已有缓冲应在交付给本库前由调用方排空，库不会绕过缓冲或改变字节顺序。
-
-`readable_sessions` 返回可读的会话对象数组，不消费数据、不包含已关闭会话、同一会话只返回一次。默认 `timeout: 0`；`nil`
-无限等待。同一会话应由一个读取者驱动，多会话共同监听使用 `Expect.expect`。
-
-| API                                                           | 行为                                        |
-|---------------------------------------------------------------|---------------------------------------------|
-| `write(*objects)`                                             | 通过 `to_s` 转换并写入所有字节，返回字节数  |
-| `puts(*objects)`                                              | 原生 IO 风格的换行、数组递归和 `nil` 返回值 |
-| `session << object`                                           | 写入并返回会话，可链式追加                  |
-| `send_slow(*objects, delay:)`                                 | 每个字符之前等待指定秒数，同时收集返回数据  |
-| `buffer` / `buffer=`                                          | 获取副本 / 复制字节并应用上限               |
-| `clear_buffer`                                                | 清空缓冲并返回旧内容                        |
-| `to_io.console_mode` / `to_io.console_mode=`                  | 原生终端模式快照与恢复                      |
-| `to_io.winsize` / `to_io.winsize=`                            | 原生 `[rows, cols]` 窗口尺寸接口            |
-| `slave` / `tty_name` / `to_io` / `writer` / `fileno` / `tty?` | 底层 IO 和终端信息                          |
-
-`send_slow` 在每次写入后只检查已经可读的回复，不附加固定等待；返回时不保证收齐最后一个字符引发的回复，完整对话请继续使用
-`expect`。
-失败时 `WriteTimeout#bytes_written` 累计这次 `send_slow` 已发送的所有字符及当前字符的部分字节；
-转换对象或交付回复引发的内层写入不计入。新增包装异常通过 `cause` 保留原错误，可按原始字节偏移续发剩余内容。
-
-大块写入遇到背压时同时读取输出，避免双向传输互相阻塞。背压等待超过 `write_timeout` 抛出 `Expect::WriteTimeout`，
-`error.bytes_written` 给出本次 `write` 已被底层接受的字节数；这些字节不回滚，不要从头重发整个命令。写入、等待和背压读取中的
-`EINTR` 均保留原期限重试。控制字符可直接发送，例如 `session.write("\x03")`，其信号作用取决于终端设置。`send`、`public_send`、
-`__send__` 保留 Ruby 反射语义。
-
-`write_timeout` 是背压相关期限：持续成功的正数短写不会因为总耗时超过它而失败，也不会强行打断同步用户代码。
-它与匹配的 `timeout/deadline`、整次 `interconnect` 的总 `timeout` 分别计算。非空写入要求底层返回实际接受的正整数字节数，
-且不能超过本次片段长度；非法计数立即抛出 `IOError`，空写入仍返回 0。
-
-终端操作直接使用 Ruby `io/console`：例如 `session.to_io.echo = false`、`session.to_io.winsize = [24, 80]`。
-需要作用域恢复时使用原生 `raw` / `cooked` 块；本库不启动 `stty` 子进程。
-
-## 诊断、接收记录与人工交互
-
-```ruby
-require "logger"
-
-logger = Logger.new($stderr, level: Logger::DEBUG)
-File.open("session.log", File::WRONLY | File::CREAT | File::APPEND, 0o600) do |transcript|
-  Expect.spawn("/bin/sh", "-i", logger: logger, transcript: transcript) do |session|
-    session.redact(password, token) # 在首次通信前注册需要保护的原始字节
-    session.outputs = [$stdout, another_session]
-    session.write_transcript("annotation\n")
-    session.puts("exit")
-  end
-end
-```
-
-三类目标职责独立：`logger` 接收结构化诊断；`transcript` 仅记录实际读取的接收字节；`outputs` 原样转发协议字节。
-所有目标均由调用方创建和关闭。`transcript = nil` 停止记录，替换前先交付旧流过滤尾部；`write_transcript` 补写记录，返回
-`nil`，
-不发送到子进程。writer 必须返回实际接受的字节数，支持短写；路径与 callable 不会自动包装成 writer。
-
-`logger` 采用 Ruby Logger 的 `add` / `debug?` 协议，默认 `nil` 禁用。Logger 自己决定级别、格式及输出位置；可直接注入兼容该协议的
-ActiveSupport logger，本库不依赖 ActiveSupport。生命周期和匹配使用 INFO，收发字节使用 DEBUG，不生成缓冲快照诊断。
-`add` 的 message 是冻结的 Hash，包含 `event`、`pid`、`fd`、`message`，其中 message 字符串也被冻结；progname 为 `"Expect"`。
-自定义格式使用 Logger 的 formatter；事件不含会话对象。logger 的返回值不控制匹配。
-
-所有会话默认没有 stdout 输出。需要显示时显式把 `$stdout` 放进 `outputs`。普通 `expect` 按读取顺序同步执行诊断、
-transcript 和 outputs，目标须及时消费；匹配期限不会中断这些代码。慢目标需要独立调度时使用 `interconnect`。
-交付接收字节期间，这些目标的回调可以匹配已有缓冲或驱动独立会话；若递归读取同一会话的新输入，会抛出 `ReentrancyError`，
-避免后读字节抢先进入其他目标。转义回调中的嵌套匹配不受此限制。
-记录不重复包含发送字节，但终端回显可能作为接收内容返回；敏感会话须控制回显、显示和目标文件权限。
-
-`redact` 复制并追加非空字符串秘密，以 `[FILTERED]` 遮盖 transcript、`write_transcript` 及收发诊断，支持跨分片和重叠秘密。
-匹配缓冲、Result 和 outputs 始终保留原始字节。它不推断编码、终端转义、哈希或其他变换后的秘密，也不能删除已交付的记录。
-临时关闭 DEBUG 仍保留连续脱敏上下文；关闭期间的原始字节不会在重新启用或冲刷尾部时补记。
-直接 `write` 的发送诊断描述尝试发送的内容；转接到 Session 时，发送诊断按底层实际接受的片段推进，并与直接写入共用过滤状态。
-转接诊断失败后，恢复只补未写入的后缀；若诊断内嵌套写入超时，外层 `bytes_written` 保留转接进度，内层异常通过 `cause` 获取。
-
-过滤器最多延迟最长秘密长度减一的尾部字节，EOF、目标替换和显式关闭时交付剩余内容；流边界的疑似秘密前缀也会遮盖。
-发送与接收诊断独立保留过滤状态，因此实际写入分块可能变化。GC 兜底不调用用户代码；需显式关闭会话以交付过滤尾部，
-然后由调用方关闭 transcript 和 logger。
-
-应用需要过滤自己的日志或错误文本时，可以直接使用独立的字节过滤器，无需打开 PTY 或创建会话：
-
-```ruby
-require "expect/redactor"
-
-safe_message = Expect::Redactor.redact(message, [password], replacement: "[REDACTED]")
-filter = Expect::Redactor.new([password], replacement: "[REDACTED]")
-output.write(filter.append(chunk)) # 每个输出流使用独立实例
-output.write(filter.finish)
-```
-
-`patterns=` 用由非空字符串组成的数组替换后续规则，空数组表示不注册秘密；输入数组、字符串和替换标记都会复制，
-无效更新不改变已有规则或暂存数据。已输出的内容不能撤回，更新后也会保留先前标记为隐藏的尾部区间。
-`redact` 处理完整文本，只匹配完整秘密；`finish` 默认还隐藏未完成的秘密前缀。已确定输入完整的调用方可用
-`finish(partial: false)`。连续或重叠的隐藏区间合并成一个替换标记。过滤不自动识别终端控制符或编码，过滤器本身不持有 IO，
-也不负责会话作用域或异常对象的安全字段选择。该公共接口从 0.5.0 开始提供。
-
-```ruby
-session.interact(input: $stdin, escape: "\x1d", output: $stdout) # Ctrl-]
-
-Expect.open($stdin) do |input|
-  input.outputs = [session]
-  session.outputs = [$stdout]
-  input.on_sequence("\x1d") { false }
-  Expect.interconnect(input, session, timeout: 60)
-end
-```
-
-`on_sequence(sequence) { ... }` 注册字符串、原生正则或 `:eof`，通过闭包传递参数。无回调、返回 `nil` / `false` 停止，其他 Ruby
-真值（包括 `0`）继续；字符串 `"EOF"` 按字面匹配。转接返回导致停止的会话，超时或所有 EOF 回调均继续时返回 `nil`。
-
-`interconnect` 统一调度真实 IO 的非阻塞读写；慢目标不会阻止其他源前进，等待同时受总 `timeout` 和目标会话的 `write_timeout`
-约束。总期限到达返回 `nil`，目标写期限先到则抛出 `WriteTimeout`。超时后的字面转义前缀只尝试非阻塞发送，不再等待下游。作为写入目标但未显式列出的
-Session，背压期间读取的回复保留在其匹配缓冲；需要同时转发这些回复时，把它也传给 `interconnect`。
-正数总期限会在扫描及继续回调返回后检查，包括延迟执行的转义回调和 EOF 回调；到期后保留尚未处理的输入。
-`timeout: 0` 保留处理当前缓冲及首次非阻塞轮询的行为。回调明确停止时仍返回对应会话。
-
-每个源独立保存待发送数据以及各目标的发送位置，`source.pending_output?` 表示仍有未交付内容。超时或异常后再次对同一源调用
-`interconnect`，会接着发送未完成的后缀，已完成的目标不会重复接收；转义回调在前缀交付后执行。待发送数据与 `buffer`
-中尚未处理的输入分开保存，修改 `outputs` 仅影响后续数据，旧数据仍发往原目标。恢复时不要把原始数据再次赋给 `buffer`
-，也不要在排空旧输出前插入新的直接写入；关闭源会话会放弃其待发送数据。转接保留的输入暂不按 `buffer_limit` 裁剪，下次匹配时重新应用该上限。
-
-自定义写入对象必须及时返回实际接受的字节数，短写入会继续发送后缀，零、负数或非法返回值抛出 `IOError`
-。对象若先写入再抛错而不报告进度，库无法推断其副作用。日志、用户回调及自定义 `write` / `flush` 同步运行，应由调用方保证它们不会无限阻塞；上述
-IO 期限不会强行中断这些代码。普通 `expect` 的同步 transcript 和 outputs 也不受匹配等待期限限制。
-
-字面转义可以跨读取完整过滤，尾部留给下次调用。正则转义使用历史记录，默认最多保留最近 65,536 字节；设置 `buffer_limit`
-后改用该值。正则及其锚点作用于当前历史窗口，超过窗口的跨读取正则无法匹配，已实时转发的前缀也无法撤回；零长度正则匹配抛出
-`ArgumentError`。日志包括被转接过滤的转义，显式启用 `redact` 时遮盖注册秘密；在 `expect` / `interconnect` 之间切换不会重复记录。
-正则历史只连接连续输入：匹配消费了字节、显式 `buffer=` / `clear_buffer` 或窗口实际裁剪后会清除旧历史。
-非消费匹配、未丢弃字节的空等待及内部缓冲交接仍保留历史，因此连续转接可以继续识别跨调用转义。
-
-一次转接尚未返回时，递归 `interconnect` 的来源若与活跃来源重叠，会在移动缓冲和修改发送游标前抛出
-`Expect::ReentrancyError`。完全独立的来源仍可嵌套转接；`on_sequence` 中的嵌套 `expect` 及返回后再次转接仍受支持。
-自定义 `write` 若已产生副作用却抛错、未返回计数，库无法推断已接受的字节数，此时不能保证恢复交付恰好一次。
-这一保护不代表所有会话 API 都可以跨线程并发调用。
-
-`interact` 默认 `raw: true`，自动设置并恢复本地输入终端模式，同时保留输出换行处理；`raw: false` 将设置交给调用方。
-通用的 `interconnect` 只负责字节转发，由调用方管理终端模式。`interact` 会恢复临时 outputs 和转义设置，包括超时和异常路径。
-
-对同一连接重复传入同一个原始输入 IO 时，`interact` 会复用输入包装器，接续上次预读的尾部。包装器由该连接持有，关闭连接时释放，但不关闭借用的原始
-IO；已关闭的输入或包装器不再复用。需要跨连接共享或自行管理输入生命周期时，显式传入 `Expect.open(input)` 创建的会话。
-
-## 软关闭、硬关闭与进程状态
-
-```ruby
-status = session.soft_close(timeout: 3, term_timeout: 1)
-status ||= session.hard_close(timeout: 0.2)
-
-session.close(graceful: true) # 先软关闭，必要时继续硬关闭
-```
-
-- `soft_close`：等待自然 EOF 并收集尾部输出，然后关闭所属 IO、等待进程退出；超时后最多发送 TERM， **不发送 KILL**。`timeout:`
-  是自然退出阶段的期限（默认 15 秒），`term_timeout:` 是发 TERM 后的等待时间（默认 1 秒）。未退出返回 `nil`，保留 PID，可继续
-  `wait` 或 `hard_close`。
-- `hard_close`：立即关闭所属 IO，不收集尾部输出；等待 `timeout:`，必要时发送 TERM 再等待同样时长，仍未退出则 KILL 并最多等待
-  1 秒。默认 `timeout: 0.2`，必须有限。
-- 两者返回已回收的 `Process::Status`，没有子进程或尚未回收时返回 `nil`；重复调用保留已获得的状态。借用 IO 不关闭。
-- `close(graceful: false)`：可选先软关闭，`ensure` 中硬关闭，返回 `nil`。块生命周期使用它完成清理；软关闭发生日志异常时也会回收子进程。
-- `wait(timeout: nil)`：等待并回收，返回 `Process::Status`；超时返回 `nil`。`process_status` 非阻塞查询，`exit_code`
-  读取普通退出码，信号退出看 `process_status.termsig`。
-- `closed?` 表示会话 IO 已关闭；`alive?` / `pid` 表示子进程状态。软关闭后可能同时 `closed? == true`、`alive? == true`。成功回收后
-  PID 为 `nil`。
-
-关闭只负责会话直接启动的子进程；垃圾回收提供非阻塞的强制清理兜底，不执行软关闭等待。优先使用块或 `ensure` 管理资源。
-
-## 安全注意事项
-
-- 将不可信命令和参数分别传给 `spawn`，例如 `Expect.spawn("ssh", host)`；单个命令字符串会使用 Ruby 的 shell 语义。
-- 接收记录和诊断可能包含密码回显、令牌和其他敏感字节。调用方负责文件权限与留存，按需关闭 transcript、outputs 和 logger。
-- `spawn` 在子进程中使用 `fork` 后的 Ruby 操作与 `exec`。高度多线程的宿主进程，尤其使用第三方 C 扩展时，可能受到 fork
-  时其他线程持锁的影响；尽量在启动其他线程前创建会话，并在自己的运行环境中验证。
-- 不可信正则可能耗费较长时间；使用带 `timeout:` 的 `Regexp` 实例，并为匹配缓冲设置合适的 `buffer_limit`。普通 `expect` 的
-  IO 期限不打断单次正则或同步回调。
-
-## 示例和验证
-
-```sh
-bundle install
-bundle exec rake              # RuboCop + 完整测试
-script/ci                     # 与 CI 相同：检查、测试、构建和隔离安装验证
-ruby examples/dialogue.rb
-ruby examples/kibitz/test_kibitz.rb
-ruby examples/ssh_auto.rb      # 登录后执行命令，再交给人工输入
-ruby examples/ssh_auto.rb --no-interact
-ruby examples/ssh_interact.rb --auto
-```
-
-普通测试使用真实 PTY、管道和 socket，无需 SSH 服务或账户。Kibitz
-的双终端示例与验证见 [examples/kibitz/](examples/kibitz/README.md)。
-
-[GitHub Actions](https://github.com/gatework/expect-ruby/actions/workflows/ci.yml) 在推送 `main`、推送 `v*` 标签、提交到
-`main` 的 Pull Request 或手动触发时运行。流水线覆盖 Ubuntu 24.04 / macOS 15 与 Ruby 3.4、4.0 的 4 种组合；每个环境执行
-`script/ci`，包括真实 PTY 测试和构建包的隔离安装验证。Ubuntu / Ruby 4.0 作业保留已验证的 Gem 构建产物 14 天，可从该次工作流的
-Artifacts 下载。
-
-运行前先执行 `bundle install`。Gem 库的开发锁文件 `Gemfile.lock` 保留在本地，各 Ruby 环境按 `Gemfile` 解析兼容依赖。生成文件写入已忽略的
-`tmp/`，Gem 构建产物位于 `tmp/ci/`，发布候选包位于 `tmp/release/`。安装验证会清除外部 Bundler 环境，分别运行普通 RubyGems
-加载和只声明 `expect-pty` 的 Bundler 应用，检查运行时依赖、终端模式、窗口大小及真实 PTY 对话。更新工作流中的 Action
-时，应同步更新固定的提交 SHA 和版本注释。
-
-运行时依赖只在 `expect-pty.gemspec` 声明，开发依赖放在 Gemfile 的 `development` / `test` 组；安装或使用本库不会引入
-Minitest、Rake、RuboCop 及发布工具的依赖。
-
-| 运行时模块         | Gem           | 用途                     |
-|--------------------|---------------|--------------------------|
-| `io/console`       | `io-console`  | 终端模式和窗口大小       |
-| `IO#wait_readable` | Ruby 3.2 内置 | IO 可读等待，无独立 gem  |
-| `logger`           | `logger`      | 标准诊断协议与级别       |
-| `stringio`         | `stringio`    | Ruby `puts` 语义         |
-| `pty`              | Ruby 自带扩展 | POSIX 伪终端，无独立 gem |
+~~~
 
-仅发布 RubyGems 使用 `ruby script/release.rb --rubygems-only`，直接复用本机已有的 Gem 登录状态；添加 `--dry-run`
-可先完成本地检查、测试、构建和安装验证。需要同时创建 GitHub Release 时使用 `ruby script/release.rb`，也可以在 GitHub Actions
-推送版本标签触发 OIDC 可信发布，或手动恢复同一标签。版本准备、可信发布配置和失败重试见 [发布说明](docs/RELEASING.md)。
+The block closes the session and reaps its child process, including when the block raises. Use separate command arguments for untrusted input; a single command string follows Ruby shell semantics.
 
-SSH 示例用 `SSH_USER`、`SSH_HOST`、`SSH_KNOWN_HOSTS` 配置，密码隐藏输入或从 `EXPECT_PASSWORD` 读取；非本地主机要求受信任的
-known_hosts 文件。`ssh_auto.rb` 顶部 `COMMANDS` 可直接修改，日志写入 `tmp/ssh-auto/`，权限 0600。
+## Features
 
-多脚本验证入口为 `test/integration/ssh_scripts.rb`，人工/自动接管入口为 `examples/ssh_interact.rb`
-，详细配置及日志检查见 [SSH 测试说明](test/integration/README.md)。
+- Exact byte-string and Ruby Regexp matching, immutable results, callbacks, timeouts, and EOF handling.
+- Explicit PTY sessions or borrowed IO sessions, with scoped cleanup and process status.
+- Multi-session waits, IO forwarding, and interactive terminal handoff.
+- Optional Logger diagnostics, receive transcripts, and streaming redaction.
 
-当前行为边界见 [接口说明](docs/COMPATIBILITY.md)，本次与历史验证分列在 [验证记录](docs/VERIFICATION.md)
-。此次重构直接移除了旧入口，不提供兼容别名。
-防火墙连接器已迁移到相邻的 `algosec` 项目；本库只保留 `Expect` 与 `expect-pty` 通用传输能力。
+## Documentation
 
-## 类型、文档与 0.7.0 接口变更
+- [API reference](docs/API.md)
+- [Compatibility and behavior boundaries](docs/COMPATIBILITY.md)
+- [Migration guide](docs/MIGRATION.md)
+- [Performance notes](https://github.com/gatework/expect-ruby/blob/main/docs/PERFORMANCE.md)
+- [Examples](https://github.com/gatework/expect-ruby/tree/main/examples)
 
-0.7.0 将 `Expect` 改为模块，公开真实 `Session`，移除全局配置、门面、终端命令包装和旧日志接口。
-最低仍为 Ruby 3.4，保留不可变 `Result`。完整接口见 [API 文档](docs/API.md)，从 0.6.x 或更早版本升级前请阅读
-[迁移说明](docs/MIGRATION.md)。类型签名随 Gem 发布在 `sig/expect.rbs`。
+In a repository checkout, run the test suite and package checks with `script/ci`. The suite uses local PTYs, pipes, and sockets; SSH credentials are not required.
 
-发布包仅包含运行源码、类型签名和使用文档。测试、基准、示例及维护脚本请从仓库取得；
-运行 `bundle exec rake api` 验证文档覆盖与 RBS 声明，运行 `bundle exec yard doc --output-dir tmp/yard`
-生成 HTML 文档。签名验证不代表全库已经通过静态类型检查。
+Licensed under the MIT License. Contributions are welcome in English or Chinese; see [CONTRIBUTING.md](https://github.com/gatework/expect-ruby/blob/main/CONTRIBUTING.md).

data/README.zh-CN.md

@@ -0,0 +1,56 @@
+# expect-ruby
+
+[![CI](https://github.com/gatework/expect-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/gatework/expect-ruby/actions/workflows/ci.yml)
+
+[English](README.md) · [简体中文](README.zh-CN.md)
+
+一个通过 POSIX 伪终端自动操作交互式程序的 Ruby 库。启动子进程、等待文本或正则匹配、发送输入，并用 Ruby 对象和代码块管理超时、回调与资源清理。
+
+RubyGems 包名：**expect-pty**。要求 Ruby 3.4+，支持 Linux 和 macOS。
+
+## 安装
+
+在 Gemfile 中添加：
+
+~~~ruby
+gem "expect-pty", require: "expect/pty"
+~~~
+
+然后运行 `bundle install`，或直接运行 `gem install expect-pty`。
+
+## 快速开始
+
+~~~ruby
+require "expect/pty"
+
+program = "STDOUT.sync = true; print 'ready>'; STDIN.gets; puts 'done'"
+Expect.spawn("ruby", "-e", program) do |session|
+  prompt = session.expect("ready>", timeout: 5)
+  raise "子进程未就绪" unless prompt.matched?
+
+  session.puts("continue")
+  result = session.expect("done", timeout: 5)
+  puts result.match if result.matched?
+end
+~~~
+
+代码块退出时会关闭会话并回收子进程，异常路径也会执行清理。不可信命令参数应分别传入；单个命令字符串遵循 Ruby shell 语义。
+
+## 功能
+
+- 按字节精确匹配字符串，或使用 Ruby Regexp；支持不可变结果、回调、超时和 EOF。
+- 显式管理 PTY 会话或借用 IO 会话，支持作用域清理和进程状态查询。
+- 多会话等待、IO 转发和人工终端接管。
+- 可选的 Logger 诊断、接收记录和流式脱敏。
+
+## 文档
+
+- [API 参考](docs/API.md)
+- [兼容性和行为边界](docs/COMPATIBILITY.md)
+- [迁移指南](docs/MIGRATION.md)
+- [性能说明](https://github.com/gatework/expect-ruby/blob/main/docs/PERFORMANCE.md)
+- [示例](https://github.com/gatework/expect-ruby/tree/main/examples)
+
+在源码仓库中运行 `script/ci` 执行测试和打包检查。测试使用本地 PTY、管道和 socket，不需要 SSH 凭据。
+
+本项目使用 MIT 许可证。欢迎提交中文或英文贡献，详见[贡献指南](https://github.com/gatework/expect-ruby/blob/main/CONTRIBUTING.md)。

data/docs/API.md

@@ -96,6 +96,7 @@ Logger 自身控制级别和格式。INFO 记录生命周期/匹配，DEBUG 增
 
 `transcript=` 接收 nil 或 writer；路径打开、权限和关闭由调用方通过 File.open 管理，不接收路径或 callable。
 `write_transcript(*objects)` 补写接收记录并返回 nil；不发送到子进程。writer 必须返回实际接受的正整数字节数，支持短写。
+调用开始时没有 transcript 则不转换参数；对象的 `to_s` 若切换目标，整条补记及脱敏尾部使用转换完成后的目标，禁用目标则不写入。
 logger、transcript、outputs 一律借用，显式关闭冲刷过滤尾部，但不会关闭这些目标。
 
 `redact(*secrets)` 追加非空字符串，仅过滤 transcript 和诊断，不更改匹配、Result 或 outputs。

data/docs/COMPATIBILITY.md

@@ -0,0 +1,65 @@
+# Ruby 接口与 Expect 语义边界
+
+## Tcl Expect 语义边界
+
+参考 Tcl Expect 的[官方手册](https://core.tcl-lang.org/expect/doc/trunk/expect.man)、
+[`expect.c`](https://core.tcl-lang.org/expect/raw/expect.c?ci=trunk) 的 `eval_cases` / `expMatchProcess` / 计时循环，
+以及 [`exp_inter.c`](https://core.tcl-lang.org/expect/raw/exp_inter.c?ci=trunk) 的 `intMatch` 与终端恢复流程。
+本库借鉴交互模型，保留以下明确差异，不承诺 Tcl 脚本或完整功能兼容。
+
+| Tcl Expect 能力                       | 本库的 Ruby 表达与边界                                                                                                              |
+|---------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------|
+| `spawn`、`send`、`expect`、`interact` | PTY 会话、`write` / `puts`、原生模式块和人工接管；`send` 保留 Ruby 反射语义                                                         |
+| `exp_continue` / `-continue_timer`    | `Expect.continue` / `Expect.continue(reset_timeout: false)`；使用单调时钟和秒数关键字参数                                           |
+| 匹配后消费输入、`-notransfer`         | `before` / `match` / `after` 与每轮等待的 `consume: false`；无进展回调不会原地重复执行                                              |
+| glob、exact、regexp 模式              | 字符串只作字面匹配，正则采用 Ruby `Regexp`；锚点和多行行为遵守 Ruby                                                                 |
+| `match_max`、`full_buffer`            | `buffer_limit` 只保留尾部字节，默认无限；`buffer_discarded_bytes` 统计累计裁剪量，无缓冲满事件                                      |
+| 前置/后置模式、后台匹配               | 没有全局隐式规则或后台读取器；调用方显式组合模式块，每个会话由一个读取者驱动                                                        |
+| `interact` 的部分正则匹配             | Tcl 的 `CANMATCH` 可以暂存潜在匹配；Ruby 原生正则不提供该接口，本库使用有限历史窗口，已转发前缀不能撤回。需要完整过滤时使用字面转义 |
+| `close` 与 `wait`                     | IO 结束与进程退出仍分开判断；本库的块生命周期和 `close` 会额外回收直属子进程                                                        |
+
+长输出任务应通过 transcript 或 outputs 流式保存，并按提示长度设置 `buffer_limit`。只读 `buffer_discarded_bytes`
+提供会话累计裁剪字节数，正常匹配消费和清空不计入；它不是无损缓冲满事件。后台匹配与共享前置/后置模式也需要独立的取消、优先级和资源归属约定，尚未实现。
+
+`expect` 的 `deadline:` 是额外的绝对单调时钟总期限，限制相对 `timeout` 的所有重置，不改变已知 EOF 派发和未指定总期限时的零超时轮询。会话
+`logger` 与接收记录 `transcript` 独立；显式 `redact` 仅过滤日志和诊断，协议转发与匹配仍使用原始字节。
+
+## 历史实现参考：Perl Expect.pm
+
+交互能力参考 [jacoby/expect.pm](https://github.com/jacoby/expect.pm)，源码基准为版本 1.38、提交
+`2ea0e4ce20a896c95cb4c94e781f1b1f3145150d`。此项目独立实现，使用 MIT 许可，没有复制 Perl 实现代码；原项目作者及维护者为
+Austin Schutz、Roland Giersig、Dave Jacoby，采用与 Perl 相同的许可。此处仅记录早期行为验证参考，不表示本 Gem 实现其 API、接受 Perl 语法或与其保持兼容。
+
+## 保留的交互能力
+
+仍支持真实控制终端、精确/正则匹配、模式优先级、捕获组、二进制与分片
+UTF-8、EOF/超时回调、绝对期限与接收重置、多会话、缓冲上限、慢速写入和背压、借用 writer 的接收记录、标准 Logger 诊断、outputs
+转发图、人工接管、跨读取转义及终端恢复。
+
+`expect` / `last_result` 返回不可变七字段 `Data`，匹配序号通过 `number` 读取。使用 `to_h` 或模式解构；
+字段及文本快照不可修改，不提供 `to_a`。日志按实际读取时记录，转接与匹配切换不重复写日志；显式启用 `redact` 时过滤已注册秘密。
+
+## 软关闭与硬关闭
+
+参考原版的策略边界：`soft_close` 先收集剩余输出，关闭所属句柄，等待退出并最多发送 TERM； **不发送 KILL**。未退出返回 `nil`，保留
+PID。`hard_close` 不等待输出，必要时 TERM、KILL 并回收子进程。关闭会话 IO 不代表子进程已经退出。
+
+Ruby 使用关键字指定各阶段期限，关闭方法返回 `Process::Status` 或 `nil`。`close(graceful: true)` 或工厂块的
+`graceful: true`
+先尝试软关闭，再在 `ensure` 中硬关闭；这对应原版销毁时可选软关闭、随后硬关闭的清理策略。`close` 返回 `nil`；GC
+兜底直接强制清理，不阻塞等待。
+
+## 有意采用的 Ruby 语义
+
+- 默认 `outputs: []`，需要显示时显式加入 `$stdout`。会话设置由关键字传入并按实例隔离，没有全局默认配置。
+- `Expect` 为模块，公开 `Expect::Session`；回调和结果引用真实 Session，不经过门面转换。
+- `raw`、`consume`、`reset_timeout_on_read`、`graceful` 都是所属操作的显式关键字；不保存同名布尔配置。
+- logger/transcript/outputs 均借用。文件打开、权限和关闭由调用方负责；兼容标准 Logger 协议的 ActiveSupport logger 可直接注入。
+- 仅 `nil` 和 `false` 为假，`0` 为真。转接回调也采用此规则。
+- 字符串始终是字面文本；只有 `:eof` / `:timeout` 是事件，`"EOF"` 是普通转义文本。
+- 超时回调接收所有仍在监听的会话；重复注册超时回调抛出 `ArgumentError`。
+- `write` 返回字节数，`puts` 返回 `nil`，`<<` 返回会话。
+- 启动失败抛出 `Expect::SpawnError` 并回收；EOF 不主动终止仍存活的进程。借用 IO 不关闭，接管 IO
+  在方法体进入后的初始化失败或会话关闭时释放；未知关键字在调用入口拒绝，不接管 IO。
+- Perl 特有的正则、IO::Pty 继承 API、全局信号 handler 和 Solaris 字节删除补丁不移植。Ruby 使用 `to_io`、`slave`、`io/console`
+  和原生正则。

data/lib/expect/interaction.rb

@@ -2,6 +2,7 @@
 
 require_relative "relay_writer"
 require_relative "relay"
+require_relative "literal_prefix"
 
 # 为会话补充人工接管和多路 IO 转接；核心会话定义位于 session.rb。
 module Expect
@@ -102,7 +103,7 @@ module Expect
         end
 
         # 暂存可能构成字面转义的最长后缀，保证 STOP 分两次读取时 ST 不会提前发给子进程。
-        held = final ? 0 : hold_literal_prefix(buffer, sequences)
+        held = final ? 0 : hold_literal_prefix(buffer, sequences, session.literal_prefix_tables)
         return :timeout if expired?(deadline)
 
         count = [buffer.bytesize - held, READ_SIZE].min
@@ -174,17 +175,13 @@ module Expect
     end
 
     # 只暂存可能拼成完整字面转义的最长后缀。
-    def self.hold_literal_prefix(buffer, sequences)
+    def self.hold_literal_prefix(buffer, sequences, prefix_tables = {})
       held = 0
       sequences.each_key do |key|
         next if key.is_a?(Regexp)
 
-        [key.bytesize - 1, buffer.bytesize].min.downto(1) do |prefix_length|
-          next unless buffer.end_with?(key.byteslice(0, prefix_length))
-
-          held = [held, prefix_length].max
-          break
-        end
+        prefix_length = LiteralPrefix.length(buffer, key, prefix_tables)
+        held = prefix_length if prefix_length > held
       end
       held
     end
@@ -219,7 +216,16 @@ module Expect
 
     # 仅供转接内部保存和恢复注册表，避免公开可变 Hash 绕过 on_sequence 的校验。
     # @api private
-    attr_accessor :sequences
+    attr_reader :sequences
+
+    # @api private
+    def sequences=(sequences)
+      @sequences = sequences
+      @literal_prefix_tables&.delete_if { |sequence, _table| !sequences.key?(sequence) }
+    end
+    # 冻结字面规则对应的 KMP 前缀表，跨转接复用，避免每个读块重新编译长规则。
+    # @api private
+    attr_reader :literal_prefix_tables
     # 让同步写入的背压读取遵守当前转接的数据所有权，退出后恢复普通匹配缓冲。
     # @api private
     attr_accessor :interaction_buffer

data/lib/expect/literal_prefix.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Expect
+  # 计算字节窗口尾部与规则真前缀重合的最长长度；转义暂存和流尾脱敏使用同一边界判断。
+  # 不持有输入或修改缓冲，调用方可为冻结规则提供前缀表缓存；短规则不建立表。
+  # @api private
+  module LiteralPrefix
+    def self.length(buffer, pattern, prefix_tables = nil)
+      maximum = [pattern.bytesize - 1, buffer.bytesize].min
+      return 0 unless maximum.positive?
+
+      # 尾字节不在候选前缀内时无需扫描；最长候选本身命中时也不必构造 KMP 表。
+      ending = pattern.rindex(buffer.byteslice(-1, 1), maximum - 1)
+      return 0 unless ending
+
+      maximum = ending + 1
+      return maximum if buffer.end_with?(pattern.byteslice(0, maximum))
+      return short_length(buffer, pattern, maximum - 1) if maximum < 64
+
+      failure = prefix_tables && pattern.frozen? ? (prefix_tables[pattern] ||= []) : []
+      extend_failure_table(pattern, failure, maximum)
+      matched = 0
+      index = buffer.bytesize - maximum
+      while index < buffer.bytesize
+        byte = buffer.getbyte(index)
+        matched = failure[matched - 1] while matched.positive? && byte != pattern.getbyte(matched)
+        matched += 1 if byte == pattern.getbyte(matched)
+        index += 1
+      end
+      matched
+    end
+
+    def self.extend_failure_table(pattern, failure, length)
+      failure << 0 if failure.empty?
+      matched = failure.last
+      index = failure.length
+      while index < length
+        byte = pattern.getbyte(index)
+        if byte == pattern.getbyte(matched)
+          matched += 1
+          failure << matched
+          index += 1
+        elsif matched.positive?
+          matched = failure[matched - 1]
+        else
+          failure << 0
+          index += 1
+        end
+      end
+    end
+
+    def self.short_length(buffer, pattern, maximum)
+      maximum.downto(1) do |length|
+        return length if buffer.end_with?(pattern.byteslice(0, length))
+      end
+      0
+    end
+
+    private_class_method :extend_failure_table, :short_length
+  end
+
+  private_constant :LiteralPrefix
+end

data/lib/expect/logging.rb

@@ -51,10 +51,13 @@ module Expect
 
     # 向接收记录补写内容，不发送给子进程或 outputs；脱敏尾部可能延迟交付，返回 nil。
     def write_transcript(*objects)
+      return unless transcript
+
+      data = objects.map { |object| object.to_s.b }.join
+      # to_s 可切换或禁用记录目标；整条记录与其过滤尾部必须属于转换完成后的同一目标。
       target = transcript
       return unless target
 
-      data = objects.map { |object| object.to_s.b }.join
       if @secrets
         @transcript_redactor ||= Redactor.new(@secrets)
         data = @transcript_redactor.append(data)
@@ -84,6 +87,12 @@ module Expect
 
     private
 
+    # 关闭时两种记录都要尝试完成；后续 writer 的常规异常不能覆盖先发生的诊断异常。
+    # 不关闭借用目标，新的 Interrupt/SystemExit 仍由 Cleanup 原样传播。
+    def finish_logging
+      Cleanup.always(-> { self.transcript = nil }) { flush_diagnostics }
+    end
+
     # 向目标写入并在支持时立即 flush，使日志和终端输出及时可见。
     # 这里遵循同步写入协议，不受 Matcher 的 IO 等待期限中断；慢目标转接应使用 Relay。
     # 短写只推进已确认的字节数；目标抛错时不猜测它是否已经产生副作用。

data/lib/expect/matcher.rb

@@ -9,7 +9,7 @@ module Expect
     def initialize(patterns, timeout, deadline: nil, consume: true, reset_timeout_on_read: false)
       @patterns = patterns.finalize!
       @sessions = patterns.sessions
-      @groups = patterns.groups
+      @groups = patterns.text_groups
       @consume = consume
       @reset_timeout_on_read = reset_timeout_on_read
       @timeout = Expect.duration(timeout)
@@ -62,9 +62,9 @@ module Expect
     # 按声明组、会话、模式的顺序寻找首个匹配，不按文本中的出现位置重新排序。
     # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- 声明优先级与单轮缓冲须在同一次扫描保持一致。
     def find_match
-      # 单组且来源不重复时无需缓存；借用仅活在本次无回调扫描，不跨越 IO 或用户回调。
+      # 编译后的组内来源已按身份去重；借用仅活在本次无回调扫描，不跨越 IO 或用户回调。
       groups = @groups
-      buffers = {}.compare_by_identity if groups.size > 1 || (groups.first && groups.first.first.size > @sessions.size)
+      buffers = {}.compare_by_identity if groups.size > 1
       groups.each do |sessions, patterns|
         sessions.each do |session|
           next if @handled_eof.key?(session)

data/lib/expect/pattern_list.rb

@@ -6,7 +6,7 @@ module Expect
   class PatternList
     # 供匹配器读取的已编译分组和超时规则。
     # @api private
-    attr_reader :groups, :timeout_pattern
+    attr_reader :groups, :text_groups, :timeout_pattern
 
     # 建立默认来源，并将位置参数中的文本、正则、:eof、:timeout 转成统一模式。
     def initialize(sessions = [], patterns = [])
@@ -51,6 +51,8 @@ module Expect
     # 这里只去重会话对象；不同会话包装同一 IO 时的读取归属由 Matcher 决定。
     # @api private
     def sessions
+      return @sessions if frozen?
+
       groups.flat_map(&:first).each_with_object({}.compare_by_identity) do |session, unique|
         unique[session] = true
       end.keys
@@ -59,6 +61,8 @@ module Expect
     # 收集指定会话的所有 EOF 处理器，保留原注册顺序。
     # @api private
     def eof_patterns_for(session)
+      return (@eof_groups[session] || []).flatten(1) if frozen?
+
       groups.flat_map do |sessions, patterns|
         sessions.any? { |candidate| candidate.equal?(session) } ? patterns.select(&:eof?) : []
       end
@@ -76,17 +80,44 @@ module Expect
     # @api private
     def finalize!
       validate!
+      freeze
+    end
+
+    # 显式 Ruby freeze 与引擎完成注册遵循相同编译路径，不能把浅冻结误判为编译完成。
+    # @api private
+    def freeze
+      return self if frozen?
+
+      @sessions = sessions.freeze
+      compile_groups
       groups.each do |sessions, patterns|
         sessions.freeze
         patterns.freeze
       end
       groups.each(&:freeze).freeze
       @default_sessions.freeze
-      freeze
+      super
     end
 
     private
 
+    # 声明只编译一次；运行状态仍属于 Matcher，冻结后的列表可以供不同等待复用。
+    # EOF 索引只保存各组模式数组的引用，避免把共享模式按来源数重复复制。
+    def compile_groups
+      @text_groups = []
+      @eof_groups = {}.compare_by_identity
+      groups.each do |sources, patterns|
+        eof, text = patterns.partition(&:eof?).each(&:freeze)
+        sources = sources.uniq(&:object_id).freeze
+        @text_groups << [sources, text].freeze unless text.empty?
+        next if eof.empty?
+
+        sources.each { |source| (@eof_groups[source] ||= []) << eof }
+      end
+      @text_groups.freeze
+      @eof_groups.each_value(&:freeze).freeze
+    end
+
     # 校验并复制来源列表，将模式加入相邻的相同来源组或新建组。
     def add(value, from, callback)
       sessions = Array(from).dup

data/lib/expect/redactor.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "literal_prefix"
+
 module Expect
   # 单个日志字节流的过滤器。保留最长秘密长度减一的尾部，跨 write/read 分片仍可识别。
   # 掩码与原字节一起留存；重叠命中的区间取并集，已经输出的掩码不重复生成。
@@ -78,20 +80,13 @@ module Expect
 
     # 流关闭时无法再等待后续字节，默认隐藏与秘密开头一致的未完成尾部。
     def mark_partial_secrets
-      tail = @pending.byteslice(-1, 1)
-      return unless tail
+      return if @pending.empty?
 
       @patterns.each do |pattern|
-        length = [pattern.bytesize - 1, @pending.bytesize].min
-        # 前缀必须以当前尾字节结束；只收紧最高候选长度，密集候选仍沿用简单倒序扫描。
-        next unless length.positive? && (offset = pattern.rindex(tail, length - 1))
-
-        (offset + 1).downto(1) do |candidate|
-          next unless @pending.end_with?(pattern.byteslice(0, candidate))
+        length = LiteralPrefix.length(@pending, pattern)
+        next unless length.positive?
 
-          @hidden[-candidate, candidate] = "\1" * candidate
-          break
-        end
+        @hidden[-length, length] = "\1" * length
       end
     end
 

data/lib/expect/session.rb

@@ -20,7 +20,8 @@ module Expect
     def initialize(timeout: nil, write_timeout: nil, buffer_limit: nil, logger: nil, transcript: nil, outputs: [])
       master = slave = nil
       Cleanup.on_failure(-> { cleanup_session(master, writer: master, slave:, own: true) }) do
-        master, slave = PTY.open
+        # 取得原生句柄与登记局部所有权不可被异步中断拆开；后续参数协议仍立即响应中断。
+        Thread.handle_interrupt(Object => :never) { master, slave = PTY.open }
         initialize_io(master, writer: master, slave:, own: true, timeout:, write_timeout:, buffer_limit:,
                               logger:, transcript:, outputs:)
       end
@@ -59,7 +60,8 @@ module Expect
       from_child = to_parent = nil
       Cleanup.always(-> { SessionResources.close_handles(from_child, to_parent) }) do
         # 错误管道的写端在 exec 成功时自动关闭；父进程据此区分成功启动与 exec 前失败。
-        from_child, to_parent = IO.pipe
+        # 管道返回到多重赋值之间也属于接管区间，确保 ensure 始终能找到两个端点。
+        Thread.handle_interrupt(Object => :never) { from_child, to_parent = IO.pipe }
         to_parent.close_on_exec = true
         @command = command.map { |part| part.dup.freeze }.freeze
         # 原生 fork 返回后先登记 PID，再交付线程中断或终止，避免清理时遗漏新子进程。
@@ -397,6 +399,7 @@ module Expect
       @buffer_discarded_bytes = 0
       @outputs = []
       @sequences = {}
+      @literal_prefix_tables = {}
       @pending_writes = []
       @interact_inputs = {}.compare_by_identity
       @interact_output = nil
@@ -500,30 +503,26 @@ module Expect
         failure ||= error
         nil
       end
-      # IO 关闭与进程退出独立记录：软关闭可能已经 closed?，但仍保留活跃 PID。
-      cleanup.call { @resources.close_handles }
-      @closed = true
-      @interact_inputs&.delete_if do |_io, input|
-        cleanup.call do
-          input.close(graceful: false)
-          true
+      # 日志收尾是本作用域的清理：不能覆盖进程等待/中断或已记录的句柄错误。
+      Cleanup.always(-> { finish_logging }) do
+        # IO 关闭与进程退出独立记录：软关闭可能已经 closed?，但仍保留活跃 PID。
+        cleanup.call { @resources.close_handles }
+        @closed = true
+        @interact_inputs&.delete_if do |_io, input|
+          cleanup.call do
+            input.close(graceful: false)
+            true
+          end
         end
+        @interact_output = nil
+        @pending_writes&.clear
+        @relay_history&.clear
+        @relay_callback = nil
+        status = close_child(timeout:, term_timeout:, force:)
+        raise failure if failure
+
+        status
       end
-      @interact_output = nil
-      @pending_writes&.clear
-      @relay_history&.clear
-      @relay_callback = nil
-      status = close_child(timeout:, term_timeout:, force:)
-      completed = true
-      status
-    ensure
-      begin
-        cleanup.call { flush_diagnostics }
-      ensure
-        cleanup.call { self.transcript = nil }
-      end
-      # 用本次流程的完成状态判断异常传播，不能误把调用者 rescue 中的异常当成当前错误。
-      raise failure if failure && completed
     end
 
     # 句柄清理失败不改变进程策略；未回收 PID 保留给重复关闭或终结器继续处理。

data/lib/expect/version.rb

@@ -2,5 +2,5 @@
 
 module Expect
   # Gem 与库共用的版本号；独立文件使 gemspec 无需加载完整会话实现。
-  VERSION = "0.7.4"
+  VERSION = "0.7.6"
 end

data/lib/expect.rb

@@ -47,9 +47,15 @@ module Expect
               timeout: nil, write_timeout: nil, buffer_limit: nil, logger: nil, transcript: nil, outputs: [])
       session = nil
       spawned = false
-      cleanup = -> { session&.close(graceful: spawned && graceful) if block_given? || !spawned }
+      cleanup = lambda do
+        if session && (block_given? || !spawned)
+          session.cleanup_session(nil, writer: nil, own: false, graceful: spawned && graceful)
+        end
+      end
       Cleanup.always(cleanup) do
-        session = Session.new(timeout:, write_timeout:, buffer_limit:, logger:, transcript:, outputs:)
+        # 先持有对象再初始化，构造完成到工厂接管之间不能留下无人负责关闭的窗口。
+        session = Session.allocate
+        session.__send__(:initialize, timeout:, write_timeout:, buffer_limit:, logger:, transcript:, outputs:)
         session.spawn(*command, env:, chdir:, raw:)
         spawned = true
         block_given? ? yield(session) : session

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: expect-pty
 version: !ruby/object:Gem::Version
-  version: 0.7.4
+  version: 0.7.6
 platform: ruby
 authors:
 - expect-pty contributors
 bindir: bin
 cert_chain: []
-date: 2026-10-07 00:00:00.000000000 Z
+date: 2026-10-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: io-console
@@ -51,8 +51,8 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '3.0'
-description: Automate interactive programs with exact and regexp matching, Ruby blocks,
-  multi-session waits, logging and terminal interaction.
+description: Automate interactive programs with PTY sessions, pattern matching, callbacks,
+  timeouts, logging and multi-session IO.
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -60,11 +60,14 @@ files:
 - CHANGELOG.md
 - LICENSE
 - README.md
+- README.zh-CN.md
 - docs/API.md
+- docs/COMPATIBILITY.md
 - docs/MIGRATION.md
 - lib/expect.rb
 - lib/expect/cleanup.rb
 - lib/expect/interaction.rb
+- lib/expect/literal_prefix.rb
 - lib/expect/logging.rb
 - lib/expect/matcher.rb
 - lib/expect/pattern.rb
@@ -84,6 +87,7 @@ licenses:
 metadata:
   rubygems_mfa_required: 'true'
   source_code_uri: https://github.com/gatework/expect-ruby
+  documentation_uri: https://github.com/gatework/expect-ruby/blob/main/docs/API.md
   changelog_uri: https://github.com/gatework/expect-ruby/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/gatework/expect-ruby/issues
 rdoc_options: []
@@ -102,5 +106,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.16
 specification_version: 4
-summary: Ruby PTY automation with the Expect.pm interaction model
+summary: Ruby PTY automation for interactive programs
 test_files: []