expect-pty 0.7.7 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 45e6676261fec4b5bcd7db41298fd513a47da86308a29f53702311a6b5219f59
-  data.tar.gz: 19354431d871147ebd778424288ea2d3a2f788d92e8674f6c779b8c560b23f1b
+  metadata.gz: ee45b8c572aa37af57de1fae7b298e0a73a1b1157bb77949edb3918b100b8a81
+  data.tar.gz: 6767f2e994b45d693e5701a9f153cc3991c48255c3bd6f0fec8ce5884aa72fb2
 SHA512:
-  metadata.gz: efdb068466acf441e74d839e9830d31f59ab18bf989726319dc6f97fb049d34a913ef53fdc399b6287bebc94d3993a5b97fb8fe41965c3c1a5e6ed3fb9aba924
-  data.tar.gz: c4c4d20ef93293c8958da3ffcf6f2ebc0245b37b07caea6fe5f2af3b9ef73ba29d365134f5c7be1a693a43a3c163724143a805ad4f19d27266df7ec7e9485717
+  metadata.gz: b2e908dc05179ec58c9cfa11d5105f9e1b1b4089996a588ae2f14dd93b5218e0478ad43e749320200b98d880da54d0381963f7dc59891e943f0d1092bf4b4783
+  data.tar.gz: ae06bd3ffdac6991bf510d10bf52665bfeaaaac6ea46a78b1e7fdc56f37fb6b4523c29e2a3519f6a374dd675df7cc94607c1b56923cf25bff89603bd95549362

data/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## Unreleased
 
+## 0.8.0 - 2026-10-11
+
+- 新增可复用的自动应答规则，支持重复确认、分页按键、动态回复和次数上限，按输入顺序处理提示且不延长等待期限，并提供批量脚本示例。
+- 修复直接软关闭在读尾、日志交付失败或取消时跳过资源清理的问题，保留原始异常和不发送 KILL 的约定，失败时跳过自然退出等待。
+- 减少结果快照、继续匹配、单对象写入和正则转义的临时分配，保留不可变结果、捕获、编码校验及部分写入进度。
+
+## 0.7.8 - 2026-10-11
+
+- 将内部资源所有权对象命名为 ResourceOwner，并统一源码、示例和测试辅助代码的中文注释。
+- 补齐字节前缀算法、脱敏窗口及基准、API 校验和示例辅助方法的契约注释，明确缓存、输入和副作用边界。
+
 ## 0.7.7 - 2026-10-11
 
 - 修复人工接管时终端模式交接中断、恢复异常覆盖业务主异常的问题；分别尝试恢复两侧输出、转义规则和终端模式。

data/README.md

@@ -38,6 +38,7 @@ The block closes the session and reaps its child process, including when the blo
 
 ## Features
 
+- Reusable automatic response rules for repeated confirmations, paging, and dynamic replies.
 - 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.

data/README.zh-CN.md

@@ -43,6 +43,12 @@ end
 - 多会话等待、IO 转发和人工终端接管。
 - 可选的 Logger 诊断、接收记录和流式脱敏。
 
+## 批量脚本自动应答
+
+`Expect::Responder` 支持复用自定义规则、重复确认、分页按键和正则捕获动态回复。
+每条命令按输入位置处理提示，规则可设置应答次数上限，应答不会延长等待期限。
+详见 [API 自动应答](docs/API.md#自动应答)，可运行 `ruby examples/auto_response.rb` 验证本地设备模拟。
+
 ## 文档
 
 - [API 参考](docs/API.md)

data/docs/API.md

@@ -22,6 +22,8 @@ Session 构造器不接收命令或操作参数。同一会话只能启动一次
 TERM；
 `hard_close(timeout: 0.2)` 关闭句柄后分阶段等待、TERM、KILL。后两者和 `wait(timeout: nil)` 返回真实 `Process::Status` 或
 nil。
+直接 `soft_close` 在读尾、日志或输出交付失败时仍尝试软关闭并保留原始异常；失败路径跳过剩余自然退出等待，
+尤其不会因 `timeout: nil` 阻塞异常传播，TERM 阶段仍使用 `term_timeout`，不会升级为 KILL。参数校验失败不关闭会话。
 借用 IO 不随会话关闭。输入 EOF、IO 关闭与子进程退出分别由 `eof?`、`closed?`、`process_status` 表示。
 
 ## 匹配与回调
@@ -63,6 +65,48 @@ nil。
 EncodingError。
 成功默认消费匹配前缀，超时保留缓冲，EOF 将余下内容放入 before 并清空缓冲。EOF 不表示子进程已经退出。
 
+## 自动应答
+
+已有 `PatternList#on` 配合 `Expect.continue` 可手写应答循环。批量脚本使用 `Expect::Responder` 复用规则，
+不必每条命令重新拼接回调；普通 `expect` 的声明优先级保持不变。
+
+```ruby
+rules = Expect::Responder.new do |responses|
+  responses.on("Apply change? [y/N] ", reply: "y\n", limit: 5)
+  responses.on("--More--", reply: " ", limit: 100)
+  responses.on(/Repeat code (\d+): /, limit: 1) { |session| session.puts(session.captures.first) }
+end.freeze
+
+# 登录并收取设备初始提示后，再逐条发送配置。
+commands.each do |command|
+  session.puts(command)
+  result = rules.expect(session, "device>", timeout: 30, deadline: Expect.monotonic + 60)
+  raise "command incomplete: #{result.error}" unless result.matched?
+end
+```
+
+- `on(pattern, reply: nil, limit: nil)` 只接受非空 String 或 Regexp；必须提供 String 回复或动作块，二者互斥。
+  静态字符串复制并冻结，块收到带 `before`、`match`、`captures` 的 Session；块返回值忽略，应答后继续等待。
+- `reply` 原样发送，行确认自行包含 `\n` 或 `\r`，分页可发送空格；空回复合法但不产生字节。
+  不内置通用“全部确认”规则，调用方应按目标设备及业务选择精确提示和回复。
+- `expect(session, *patterns, timeout: session.timeout, deadline: nil)` 仅处理一个 Session；也可使用与 `expect` 相同的
+  PatternList 块声明完成模式、EOF 和 timeout 回调。位置参数模式与块不能同时提供。
+- 自动应答与完成模式按最早的字节位置处理；同位置时完成模式先于应答，多个应答按声明顺序。
+  不按正则长度推测未完成提示，不在未知提示上猜测回复。仅将成功匹配的文本视为完成，业务错误输出需由调用方注册为终止模式并检查。
+- 每条规则的 `limit` 是一次等待内的最大应答次数，必须为正 Integer，nil 不限；每次调用独立计数。
+  超限或正则匹配空文本时，抛出 `Expect::Responder::ResponseError`，且不执行本次应答。触发该异常的匹配已经按普通匹配语义消费，
+  未读尾部留在会话中。应答发送失败原样传播，不自动重试可能已经部分交付的确认。
+- 应答不重置相对 timeout，deadline 仍是不可延长的总期限；沿用 Matcher 的协作式期限检查。
+  动作块、单次正则计算和写入不由匹配期限强行中断；应为会话配置 `write_timeout`。
+  timeout 和 EOF 返回普通 Result，默认未知提示等到超时。显式完成回调仍遵循 `Expect.continue` 契约。
+- 中途应答消费 `before` 和 `match`；最后 Result 仅表示完成、EOF 或超时，不汇总整条脚本输出。
+  需要全文时在发送命令前设置 `session.transcript`；逐段展示可在动作块打印 `before/match`，完成后打印最终 `before`。
+  完成后的尾部保留给下一轮。发送秘密前调用 `session.redact(secret)`，回复会经过正常写入诊断，规则摘要不展示内容。
+- 注册阶段不读写 IO；每次等待快照规则，回调中的规则修改仅影响以后等待。不接管会话资源，
+  不保证同一会话并发操作安全；设备的 SSH 登录和配置成功判定仍属于调用方。
+
+本地设备模拟见 `examples/auto_response.rb`；`examples/ssh_auto.rb` 接入精确规则并保留分段输出和完整 transcript。
+
 ## 会话属性与读写
 
 不提供全局配置或配置对象。构造器、工厂显式接受以下设置，会话可通过同名 reader/writer 修改；非法更新保留原值。

data/lib/expect/cleanup.rb

@@ -6,14 +6,21 @@ module Expect
   module Cleanup
     # 包括非局部返回在内的所有退出均清理；StandardError 只在没有原异常时传播。
     # 清理期间新发生的 Interrupt、SystemExit 等致命异常仍原样传播。
-    def self.always(on_exit)
-      yield
+    # report_completion 仅供关闭策略区分正常结束、取消及非局部退出，不改变异常优先级。
+    def self.always(on_exit, report_completion: false)
+      result = yield
+      completed = true
+      result
     rescue Exception # rubocop:disable Lint/RescueException -- 中断也必须清理，然后原样传播。
       failed = true
       raise
     ensure
       begin
-        on_exit.call
+        if report_completion
+          on_exit.call(completed && !failed && Thread.current.status != "aborting")
+        else
+          on_exit.call
+        end
       rescue StandardError
         raise unless failed
       end

data/lib/expect/interaction.rb

@@ -142,7 +142,7 @@ module Expect
           # 仅在本轮扫描复用组合文本；回调可能更换规则或消费缓冲，下一轮必须重新构造。
           text ||= history + buffer
           utf8_regexp ||= key.fixed_encoding? && key.encoding == Encoding::UTF_8
-          position = Pattern.new(value: key).locate(text, final:)
+          position = Pattern.new(value: key).locate(text, final:, captures: false)
           if position
             offset, length, = position
             raise ArgumentError, "escape regexp must consume at least one byte" if length.zero?

data/lib/expect/literal_prefix.rb

@@ -2,14 +2,19 @@
 
 module Expect
   # 计算字节窗口尾部与规则真前缀重合的最长长度；转义暂存和流尾脱敏使用同一边界判断。
-  # 不持有输入或修改缓冲，调用方可为冻结规则提供前缀表缓存；短规则不建立表。
+  # 不持有输入或修改缓冲；仅长候选的扫描需要 KMP 回退表，冻结规则可跨调用缓存该表。
   # @api private
   module LiteralPrefix
+    # 返回 buffer 后缀与 pattern 真前缀重合的最大字节数；真前缀不包含完整 pattern。
+    # 例如 "xAB" 与 "ABC" 返回 2；空输入、长度不足 2 的规则或没有重合时返回 0。
+    # 两个字符串须由调用方转为二进制编码；此处不转码、不校验，也不修改它们。
+    # prefix_tables 为可选的可变 Hash；仅冻结 pattern 使用缓存，否则为本次调用建立临时表。
     def self.length(buffer, pattern, prefix_tables = nil)
       maximum = [pattern.bytesize - 1, buffer.bytesize].min
       return 0 unless maximum.positive?
 
-      # 尾字节不在候选前缀内时无需扫描；最长候选本身命中时也不必构造 KMP 表。
+      # 重合前缀的末字节必须等于输入尾字节；排除无法结束在该字节上的更长候选。
+      # 最长候选直接命中时不必构造回退表；小于 64 字节的候选改用有界枚举。
       ending = pattern.rindex(buffer.byteslice(-1, 1), maximum - 1)
       return 0 unless ending
 
@@ -19,6 +24,7 @@ module Expect
 
       failure = prefix_tables && pattern.frozen? ? (prefix_tables[pattern] ||= []) : []
       extend_failure_table(pattern, failure, maximum)
+      # 只扫描可能重合的尾部；不匹配时沿回退表保留已有重合，避免从每个候选起点重扫。
       matched = 0
       index = buffer.bytesize - maximum
       while index < buffer.bytesize
@@ -30,6 +36,9 @@ module Expect
       matched
     end
 
+    # 将同一规则的可变回退表补齐到 length 项，已有项不重算，较长的缓存也不截断。
+    # failure[i] 是 pattern[0..i] 的最长真前缀与后缀重合长度，供失配时选择下一匹配状态。
+    # length 不超过规则的真前缀长度；表只能用于生成它的同一规则内容。
     def self.extend_failure_table(pattern, failure, length)
       failure << 0 if failure.empty?
       matched = failure.last
@@ -49,6 +58,8 @@ module Expect
       end
     end
 
+    # 从 maximum 向下枚举短候选，返回首个后缀重合长度，无命中时返回 0。
+    # 调用方已限制候选规模；每次比较只切取规则前缀，不创建完整输入的副本或回退表。
     def self.short_length(buffer, pattern, maximum)
       maximum.downto(1) do |length|
         return length if buffer.end_with?(pattern.byteslice(0, length))

data/lib/expect/logging.rb

@@ -10,7 +10,7 @@ module Expect
   # 宿主 Session 初始化目标与过滤器状态，并提供 pid、fileno 作为诊断元数据。
   # 三种输出各有边界：Logger 接收事件，transcript 接收脱敏字节，outputs 接收原协议字节。
   module Logging
-    # 调用方提供的诊断 Logger 与原始接收记录 writer，均由调用方管理生命周期。
+    # 调用方提供的诊断 Logger 与接收记录 writer，均由调用方管理生命周期。
     attr_reader :logger, :transcript
 
     # Logger 自己决定级别、格式与失败策略；nil 禁用诊断，不隐式写入 stderr。

data/lib/expect/matcher.rb

@@ -6,11 +6,13 @@ module Expect
   # @api private
   class Matcher
     # 固定本次参与的会话及初始期限；已处理 EOF 的会话仅从本次等待中移除。
-    def initialize(patterns, timeout, deadline: nil, consume: true, reset_timeout_on_read: false)
+    def initialize(patterns, timeout, deadline: nil, consume: true, reset_timeout_on_read: false,
+                   match_by_position: false)
       @patterns = patterns.finalize!
       @sessions = patterns.sessions
       @groups = patterns.text_groups
       @consume = consume
+      @match_by_position = match_by_position
       @reset_timeout_on_read = reset_timeout_on_read
       @timeout = Expect.duration(timeout)
       # 相对期限可因接收或 continue 重算，总期限始终固定；两者共用单调时钟。
@@ -73,12 +75,13 @@ module Expect
       end
     end
 
-    # 按声明组、会话、模式的顺序寻找首个匹配，不按文本中的出现位置重新排序。
+    # 普通等待按声明组、会话、模式选择；单会话自动应答选最早字节位置，同位置保留声明顺序。
     # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- 声明优先级与单轮缓冲须在同一次扫描保持一致。
     def find_match
       # 编译后的组内来源已按身份去重；借用仅活在本次无回调扫描，不跨越 IO 或用户回调。
       groups = @groups
       buffers = {}.compare_by_identity if groups.size > 1
+      earliest = nil
       groups.each do |sessions, patterns|
         sessions.each do |session|
           next if @handled_eof.key?(session)
@@ -100,11 +103,15 @@ module Expect
                        end
             # 正则本身不可由 IO 期限中断；恢复控制后也不能消费已过总期限的匹配。
             return nil if hard_expired?
-            return [session, pattern, position] if position
+            next unless position
+
+            return [session, pattern, position] unless @match_by_position
+
+            earliest = [session, pattern, position] if !earliest || position.first < earliest.last.first
           end
         end
       end
-      nil
+      earliest
     end
 
     # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
@@ -137,14 +144,15 @@ module Expect
 
     # 先记录并消费匹配，再执行回调；回调可选择结束、重置期限或保留期限继续。
     def handle_match(session, pattern, position)
-      previous_buffer = session.buffer
+      # 没有回调的终止匹配不可能继续，无须复制完整缓冲建立防空转快照。
+      previous_buffer = session.buffer if pattern.callback
       received_bytes = session.received_bytes
       result = session.record_match(pattern, position, consume: @consume)
       action = pattern.call(session)
       return result unless continuing?(action)
 
       # 同值赋回仍须防止空转；嵌套读取到的新字节即使内容相同，也能恢复匹配。
-      if session.received_bytes == received_bytes && session.buffer == previous_buffer
+      if session.received_bytes == received_bytes && session.scan_buffer == previous_buffer
         stalled = (@stalled_matches[session] ||= { buffer: previous_buffer, received_bytes:, patterns: [] })
         stalled[:patterns] << pattern
       end

data/lib/expect/pattern.rb

@@ -19,8 +19,9 @@ module Expect
 
     # 在缓冲中定位字符串或正则，返回 [字节偏移, 字节长度, 捕获组]；事件或未匹配返回 nil。
     # buffer 应为二进制字符串，offset 仅用于字面扫描；正则始终看到完整窗口以保留锚点语义。
+    # captures 为 false 时只求字节范围，转义扫描不分配随后丢弃的捕获字符串。
     # final 表示不会再有新输入，此时不完整的编码尾部也必须报错，不能永远当作等待分片。
-    def locate(buffer, final: false, offset: 0)
+    def locate(buffer, final: false, offset: 0, captures: true)
       case value
       when String
         offset = buffer.index(value, offset)
@@ -42,7 +43,7 @@ module Expect
 
         # 直接使用正则的字节范围，避免为转换字符偏移创建前缀切片；捕获组也返回字节串。
         offset, finish = found.byteoffset(0)
-        return [offset, finish - offset, found.captures.map { |capture| capture&.b }]
+        return [offset, finish - offset, captures ? found.captures.map { |capture| capture&.b } : []]
       end
       nil
     end

data/lib/expect/pattern_list.rb

@@ -2,7 +2,7 @@
 
 module Expect
   # 将 Ruby 模式和块回调整理为有序会话组；注册阶段不读取 IO、不执行匹配回调。
-  # 分组结构直接决定 Matcher 的“声明组 → 会话 → 模式”优先级，不能按匹配位置重排。
+  # 普通等待按“声明组 → 会话 → 模式”选择；单会话自动应答另按字节位置选择，同位置沿用声明顺序。
   class PatternList
     # 供匹配器读取的已编译分组和超时规则。
     # @api private

data/lib/expect/redactor.rb

@@ -13,7 +13,7 @@ module Expect
       filter.append(data) + filter.finish(partial: false)
     end
 
-    # pending 保存尚不能安全输出的原字节，hidden 的对应字节用 0/1 表示是否需要遮盖。
+    # 复制冻结替换文本与规则；pending 保存尚不能安全输出的原字节，hidden 用 0/1 标记遮盖。
     def initialize(patterns, replacement: "[FILTERED]")
       unless replacement.is_a?(String) && !replacement.empty?
         raise ArgumentError, "replacement must be a nonempty String"
@@ -67,6 +67,7 @@ module Expect
     private
 
     # 输出资格与秘密掩码分开保存；仅遇到被抑制的分片时才分配额外字节图。
+    # 三个字节窗口始终对齐；先标记完整命中，再释放最长规则长度减一之外的安全前缀。
     def append_chunk(data, visible:)
       raise ArgumentError, "data must be a String" unless data.is_a?(String)
 
@@ -147,6 +148,7 @@ module Expect
     end
 
     # 仅级别切换后的流需要按输出资格再分段，普通过滤不承担额外区间调用。
+    # 将指定掩码区间中可见的字节追加到 output；被抑制的明文会断开 masking，隐藏字节不会。
     def release_suppressed(output, starting, ending, hidden:)
       while starting < ending
         suppressed = @suppressed.getbyte(starting) == 1

data/lib/expect/{session_resources.rb → resource_owner.rb}

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
 module Expect
-  # 独立保存句柄和 PID 所有权，让终结器无需直接捕获会话即可清理遗弃资源。
-  # IO 是否关闭与子进程是否退出分别记录；不能仅凭句柄状态清空 PID 或伪造退出状态。
+  # 管理 IO 关闭责任和直属子进程归属，供显式关闭与 GC 回收共用。
+  # 不直接引用 Session、日志目标或用户回调；句柄关闭与进程退出分别记录。
   # @api private
-  class SessionResources
-    # 缓存已取得的状态；被外部回收的进程仍保留未知状态，不伪造成功。
+  class ResourceOwner
+    # 缓存已取得的 Process::Status；被外部回收的进程仍保留未知状态，不伪造成功。
     attr_accessor :status
     # own 控制句柄关闭责任，owner 控制进程回收责任；fork 后两者不能混为一谈。
     attr_reader :pid, :reader, :writer, :slave, :owner, :own
@@ -60,7 +60,7 @@ module Expect
       status
     end
 
-    # GC 兜底关闭所属句柄并终止尚存活的子进程；不执行用户代码或软关闭等待。
+    # GC 兜底关闭所属句柄并终止尚存活的子进程；不调用会话日志或转义回调，也不进行软关闭等待。
     # 可直接用绑定到资源对象的 Method 注册终结器，忽略 Ruby 传来的被回收对象 ID。
     def finalize(_object_id = nil)
       return unless owner == Process.pid
@@ -77,7 +77,7 @@ module Expect
 
     private
 
-    # GC 只做一次非阻塞回收和最多两次信号尝试；失败也把等待交给 detach，不运行用户回调。
+    # GC 只做一次非阻塞回收和最多两次信号尝试；失败也把等待交给 detach，不调用会话日志或转义回调。
     def finalize_child
       begin
         reap

data/lib/expect/responder.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Expect
+  # 可复用的自动应答规则；声明不持有会话，每次等待独立统计应答次数。
+  # 输入按字节位置处理，同位置的完成模式优先，其余按规则声明顺序。
+  class Responder
+    # 规则超限或匹配空文本时停止自动发送，避免反复确认和零宽应答循环。
+    class ResponseError < StandardError; end
+
+    # 建立规则集；块保留调用方 self，通过参数注册规则。
+    def initialize
+      @rules = []
+      yield self if block_given?
+    end
+
+    # 注册字面或正则提示；reply 原样写入，换行须显式包含，也可用块操作匹配会话。
+    # limit 是本规则在一次 expect 中允许的应答次数，nil 不限；规则文本和静态回复复制冻结。
+    def on(pattern, reply: nil, limit: nil, &block)
+      raise FrozenError, "responder is frozen" if frozen?
+      unless (pattern.is_a?(String) && !pattern.empty?) || pattern.is_a?(Regexp)
+        raise ArgumentError, "response pattern must be a nonempty String or Regexp"
+      end
+
+      validate_action!(reply, limit, block)
+
+      pattern = pattern.b.freeze if pattern.is_a?(String)
+      @rules << [pattern, reply&.b&.freeze, limit, block].freeze
+      self
+    end
+
+    # 等待完成模式或 EOF，同时自动处理提示；timeout 沿用会话默认值，应答不重置期限。
+    # 完成块使用 PatternList DSL；Result 只描述最后一次匹配，全文请用会话 transcript 保存。
+    # 每次等待快照规则，回调修改规则仅影响后续等待；不接管或关闭会话。
+    def expect(session, *patterns, timeout: (session.timeout if session.is_a?(Session)), deadline: nil, &block)
+      raise ArgumentError, "responder requires a Session" unless session.is_a?(Session)
+
+      raise ArgumentError, "provide patterns or a pattern block, not both" if block && !patterns.empty?
+
+      rules = @rules.dup.freeze
+      Expect.__send__(
+        :run_expect, [session], [], timeout, deadline:, consume: true,
+                                             reset_timeout_on_read: false, match_by_position: true
+      ) do |list|
+        patterns.each do |pattern|
+          case pattern
+          when :eof then list.eof
+          when :timeout then list.timeout
+          else list.on(pattern)
+          end
+        end
+        if block
+          block.parameters.empty? ? list.instance_exec(&block) : block.call(list)
+        end
+        unless list.sessions.all? { |source| source.equal?(session) }
+          raise ArgumentError, "response completion patterns must use the same Session"
+        end
+
+        register(list, rules)
+      end
+    end
+
+    # 摘要不展示模式、回复或回调闭包，避免意外记录凭据。
+    def inspect = "#<#{self.class} rules=#{@rules.size}>"
+
+    private
+
+    # 静态回复与动作块互斥，次数必须是明确的正整数，不做宽松转换。
+    def validate_action!(reply, limit, block)
+      unless (reply.is_a?(String) && !block) || (reply.nil? && block)
+        raise ArgumentError, "provide a String reply or a response block, not both"
+      end
+      return if limit.nil? || (limit.is_a?(Integer) && limit.positive?)
+
+      raise ArgumentError, "response limit must be a positive Integer"
+    end
+
+    # 计数只属于本轮；先检查再发送，不重试写入或回调失败的部分副作用。
+    def register(list, rules)
+      rules.each_with_index do |(pattern, reply, limit, block), index|
+        count = 0
+        list.on(pattern) do |session|
+          raise ResponseError, "response rule #{index + 1} matched empty text" if session.match.empty?
+          raise ResponseError, "response rule #{index + 1} exceeded its limit" if limit && count >= limit
+
+          count += 1
+          block ? block.call(session) : session.write(reply)
+          CONTINUE_WITHOUT_RESET
+        end
+      end
+    end
+  end
+end

data/lib/expect/session.rb

@@ -5,7 +5,7 @@ require_relative "interaction"
 
 module Expect
   # 一个真实 PTY 或 IO 会话；缓冲、最近结果和所属进程都保存在本对象中。
-  # SessionResources 保存可独立回收的资源账本；Matcher、Relay 仅在操作期间借用会话状态。
+  # ResourceOwner 保存可独立回收的资源账本；Matcher、Relay 仅在操作期间借用会话状态。
   # 日志与协议目标属于调用方，显式关闭和 GC 均不得接管这些借用对象。
   class Session
     include Logging
@@ -58,7 +58,7 @@ module Expect
 
       @slave.raw! if raw
       from_child = to_parent = nil
-      Cleanup.always(-> { SessionResources.close_handles(from_child, to_parent) }) do
+      Cleanup.always(-> { ResourceOwner.close_handles(from_child, to_parent) }) do
         # 错误管道的写端在 exec 成功时自动关闭；父进程据此区分成功启动与 exec 前失败。
         # 管道返回到多重赋值之间也属于接管区间，确保 ensure 始终能找到两个端点。
         Thread.handle_interrupt(Object => :never) { from_child, to_parent = IO.pipe }
@@ -181,7 +181,8 @@ module Expect
       raise IOError, "closed Expect session" if closed? || writer.closed?
 
       begin
-        data = objects.map { |object| object.to_s.b }.join
+        # 单对象不需要中间数组与 join 副本；to_s、诊断和部分写入仍经过同一条路径。
+        data = objects.size == 1 ? objects.first.to_s.b : objects.map { |object| object.to_s.b }.join
         trace_data(:sending, data)
       rescue WriteTimeout
         # 转换或诊断中的嵌套写入不属于当前命令；此时尚未向 writer 发送任何字节。
@@ -252,20 +253,28 @@ module Expect
 
     # 先在自然退出期限内收集尾部输出，再关闭句柄并最多发送 TERM；不会发送 KILL。
     # 尚未退出时返回 nil 并保留 PID，调用方可以继续等待或随后硬关闭。
+    # 读尾或交付失败仍完成软关闭，保留主异常；失败路径跳过自然等待，不升级为 KILL。
     def soft_close(timeout: 15, term_timeout: 1)
       period = Expect.duration(timeout)
       term_timeout = Expect.duration(term_timeout)
       raise ArgumentError, "term_timeout must be finite" unless term_timeout
 
       deadline = period && (Expect.monotonic + period)
-      until eof?
-        remaining = deadline && [deadline - Expect.monotonic, 0].max
-        break if remaining&.zero? || !to_io.wait_readable(remaining)
+      status = nil
+      cleanup = lambda do |completed|
+        # 读尾失败后不再等待自然退出，尤其不能用 nil 预算无限阻塞异常传播。
+        remaining = completed ? (deadline && [deadline - Expect.monotonic, 0].max) : 0
+        status = close_resources(timeout: remaining, term_timeout:, force: false)
+      end
+      Cleanup.always(cleanup, report_completion: true) do
+        until eof?
+          remaining = deadline && [deadline - Expect.monotonic, 0].max
+          break if remaining&.zero? || !to_io.wait_readable(remaining)
 
-        read_available
+          read_available
+        end
       end
-      close_resources(timeout: deadline ? [deadline - Expect.monotonic, 0].max : nil,
-                      term_timeout:, force: false)
+      status
     end
 
     # 立即关闭句柄，再分阶段等待、TERM、KILL；不收集剩余输出，返回已回收状态或 nil。
@@ -290,7 +299,7 @@ module Expect
       if @resources
         close(graceful:)
       elsif own
-        SessionResources.close_handles(reader, writer, slave)
+        ResourceOwner.close_handles(reader, writer, slave)
       end
     end
 
@@ -323,7 +332,8 @@ module Expect
     # 记录超时、EOF 或原始 IO 异常，保留当前缓冲快照并清除旧匹配及捕获组。
     # @api private
     def record_error(error)
-      @last_result = Result.new(error:, before: buffer, session: self, captures: [])
+      # Result 自行复制冻结文本，无须先通过公开 buffer 再复制一遍。
+      @last_result = Result.new(error:, before: @buffer, session: self, captures: [])
     end
 
     # 输入结束时将剩余缓冲放入 before 并清空，尝试回收但不终止仍活跃的子进程。
@@ -386,7 +396,7 @@ module Expect
     # 初始化前先登记所有权；参数校验失败也能释放已取得的端点。
     def initialize_io(reader, writer:, slave: nil, own: false, timeout: nil, write_timeout: nil,
                       buffer_limit: nil, logger: nil, transcript: nil, outputs: [])
-      @resources = SessionResources.new(reader, writer:, slave:, own:)
+      @resources = ResourceOwner.new(reader, writer:, slave:, own:)
       raise ArgumentError, "reader must be a real IO" unless reader.is_a?(IO) && !reader.closed?
       raise ArgumentError, "writer must be a real IO" unless writer.is_a?(IO) && !writer.closed?
 

data/lib/expect/version.rb

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

data/lib/expect.rb

@@ -5,12 +5,13 @@ require "io/console"
 require "stringio"
 require_relative "expect/version"
 require_relative "expect/result"
-require_relative "expect/session_resources"
+require_relative "expect/resource_owner"
 require_relative "expect/pattern"
 require_relative "expect/pattern_list"
 require_relative "expect/matcher"
 require_relative "expect/cleanup"
 require_relative "expect/session"
+require_relative "expect/responder"
 
 # PTY 会话的创建、匹配与转接入口；可变状态只属于返回的 Session。
 module Expect
@@ -72,7 +73,7 @@ module Expect
         if session && (block_given? || !initialized)
           session.cleanup_session(io, writer:, own:, graceful: initialized && graceful)
         elsif !session && own
-          SessionResources.close_handles(io, writer)
+          ResourceOwner.close_handles(io, writer)
         end
       end
       Cleanup.always(cleanup) do
@@ -149,7 +150,8 @@ module Expect
     end
 
     # 声明完成后固定模式；有参数块保留调用方 self，无参数块使用模式 DSL。
-    def run_expect(sessions, patterns, timeout, deadline:, consume:, reset_timeout_on_read:, &block)
+    def run_expect(sessions, patterns, timeout, deadline:, consume:, reset_timeout_on_read:,
+                   match_by_position: false, &block)
       timeout = duration(timeout)
       deadline = Float(deadline) unless deadline.nil?
       raise ArgumentError, "deadline must be finite" if deadline && !deadline.finite?
@@ -159,7 +161,7 @@ module Expect
       if block
         block.parameters.empty? ? pattern_list.instance_exec(&block) : block.call(pattern_list)
       end
-      Matcher.new(pattern_list, timeout, deadline:, consume:, reset_timeout_on_read:).run
+      Matcher.new(pattern_list, timeout, deadline:, consume:, reset_timeout_on_read:, match_by_position:).run
     end
   end
 end

data/sig/expect.rbs

@@ -1,4 +1,4 @@
-# Public Session API; internal matching and relay protocols are documented with @api private.
+# 公开 Session 接口；内部匹配与转接协议在源码中标记为 @api private。
 module Expect
   type duration = Numeric | String
   type pattern = String | Regexp | :eof | :timeout
@@ -263,6 +263,21 @@ module Expect
     def timeout: () ?{ (Array[Session]) -> untyped } -> PatternList
   end
 
+  class Responder
+    class ResponseError < StandardError
+    end
+
+    def initialize: () ?{ (Responder) -> untyped } -> void
+
+    def on: ((String | Regexp) pattern, ?reply: String?, ?limit: Integer?)
+      ?{ (Session) -> untyped } -> Responder
+
+    def expect: (Session session, *pattern patterns, ?timeout: duration?, ?deadline: duration?)
+      ?{ (PatternList) -> untyped } -> Result
+
+    def inspect: () -> String
+  end
+
   class Redactor
     def self.redact: (String data, Array[String] patterns, ?replacement: String) -> String
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: expect-pty
 version: !ruby/object:Gem::Version
-  version: 0.7.7
+  version: 0.8.0
 platform: ruby
 authors:
 - expect-pty contributors
@@ -76,9 +76,10 @@ files:
 - lib/expect/redactor.rb
 - lib/expect/relay.rb
 - lib/expect/relay_writer.rb
+- lib/expect/resource_owner.rb
+- lib/expect/responder.rb
 - lib/expect/result.rb
 - lib/expect/session.rb
-- lib/expect/session_resources.rb
 - lib/expect/version.rb
 - sig/expect.rbs
 homepage: https://github.com/gatework/expect-ruby