ctx_driver 0.2.1 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f464dca50ead7d5fa1f1febf62807a0aa46647176a4c3e7a3b88f68bfe5cd37
-  data.tar.gz: 2f2df95523cb1f684717696dac14dfbad9c774f80479e5e3513f6a648f2886e9
+  metadata.gz: f367f0f7740b02d2812c31c9ec1b53f89425b7c7edf5f5d11543aceb625d2e50
+  data.tar.gz: f2a16b61cda4b685acd25e972f4609f6dd5cebc89acfc73e059dd93a18160222
 SHA512:
-  metadata.gz: 0452e5b24a4b7f6e2d96546a7babd4e54e87e95cb7eb3dab07a6eab15b37e426a7d0dad8b25ff84cbad4b535c74b590aea5fed95d51170997601ddab02132aed
-  data.tar.gz: d0ab0794e5c4dfe19937abdb8dac61022822306eba0b849779b88f91a2bba2ef81c02d399835698e0bc1f9141a9a994927bc4be5e1aa0ab23c37a9bc35f14999
+  metadata.gz: ce35190d1e7ea2121026ec74cc63014f309896bd4a89be594145027ded978677a99fd3e28a8db23435dbc62408673a4cc49129d3965d67da7bcd09c28039d46f
+  data.tar.gz: f0fda5a4aa24f72689229146e19adfc2a7ea0d22af61e77c08b1f8c5f1b751c924718373fdfbe5884b75384053dcfd9f5fa4f8140f33c33bc22984a9255cfb79

data/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 Changes to the public contract are recorded here. Versions follow Semantic Versioning.
 
+## 0.2.3 (2026-10-18)
+
+- Hide borrowed session, clock and response internals from inspection and pretty printing, including response string interpolation, without changing explicit output access.
+- Reuse frozen clock values directly while retaining defensive snapshots for mutable times.
+
+## 0.2.2 (2026-10-18)
+
+- Adapt optional native sessions to net-connector 0.13.0 and newer, including command results, terminal decoding and safe error codes.
+- Preserve response bodies before observation-clock callbacks can reuse their buffers, while retaining source evidence when decoding fails.
+- Remove padded first-line command echoes without changing body indentation, and validate one-command input before consulting native sessions.
+- Centralize command-text validation and safely share frozen command, body and timestamp values to avoid redundant snapshot allocations.
+- Verify both dependency-free offline loading and the optional adapter through an installed package and a local PTY process.
+
 ## 0.2.1 (2026-10-17)
 
 - Correct installation documentation to state the required ctx_parser 0.2.x API.

data/README-zh.md

@@ -72,17 +72,19 @@ puts "SHA-256: #{capture.evidence.first[:sha256]}"
 
 ## 公开契约与限制
 
-`Reader.new(session:, clock:).read(command)` 返回 `Capture`。通过 `success?`、`skipped?`、`failure`、`evidence` 检查结果；正文仅显式通过 `body` 读取，`to_h`、`as_json`、`inspect` 不包含正文。
+`Reader.new(session:, clock:).read(command)` 返回 `Capture`。通过 `success?`、`skipped?`、`failure`、`evidence` 检查结果；正文仅显式通过 `body` 读取，`to_h`、`as_json`、`inspect` 不包含正文。`Reader`、借用会话适配器 `Session` 及其回执的 `inspect`/`PP` 不展开调用方对象，也不查询连接状态；回执的字符串插值同样安全。原始输出与解码正文仍可通过回执的显式 API 访问。
 
 自定义会话实现 `connected?` 和 `send_commands([command])`。回执提供 `output`、布尔 `success?`、数组 `steps`、成功正文 `value!` 及失败时的 `error`。成功读取必须只有一个完成步骤。只有会话显式声明 `preserve_session_on_rejection:` 关键字时才传入该选项。
 
+net-connector 仍为可选依赖，使用适配器的宿主需自行声明 `gem "net-connector", ">= 0.13.0"`。`examples/connector.rb` 通过本地 PTY 子进程验证已安装连接器，不连接网络设备。
+
 单个 reader 顺序使用；跨设备并发分别创建 reader。连接、关闭、凭据和批准命令选择由宿主负责，Reader 不判断任意命令是否只读。普通执行/回执异常转为安全诊断，取消信号继续传播。执行或响应处理被中断后，当前 Reader 记录 `command_aborted`，后续查询跳过；不会凭 `connected?` 仍为 true 就复用同步状态未知的会话，也不会替宿主关闭连接。
 
-时钟必须可调用且返回 Time，时间在取得时立即复制。正文在检查后续会话状态之前复制。`Capture` 校验字段与状态：成功必须有字符串正文（允许空串），失败没有正文，跳过必须有失败原因且没有执行证据。墙上时钟可能回拨，时间字段不用于推断单调耗时。
+时钟必须可调用且返回 Time，可变时间在取得时保存副本，已冻结的 Time 直接复用。正文和来源摘要在观察时钟及会话状态回调之前固定，避免回调复用缓冲区后混入另一条响应。`Capture` 校验字段与状态：成功必须有字符串正文（允许空串），失败没有正文，跳过必须有失败原因且没有执行证据。墙上时钟可能回拨，时间字段不用于推断单调耗时。
 
 详细厂商语义、历史验证记录和 Motor 专用集成说明保留在[架构参考](docs/architecture-zh.md)。其中宿主集成代码需要 Motor，不属于独立 gem API。适配层位于 [Motor 仓库](https://github.com/gatework/motor/tree/main/backend/lib) 的 `backend/lib/baseline`、`backend/lib/vxlan` 和 `backend/lib/wireless`。
 
-原生 `Net::Connector::Base` 会话通过 `execute_operation` 自动适配，不连接、不提权。只去除已匹配的提示符和首行命令回显；连接器因拒绝命令而关闭时，后续读取跳过，不自动重连。自定义会话仍可实现 `send_commands` 协议。
+net-connector **0.13.0 及以上版本**的原生 `Net::Connector::Base` 会话通过 `execute_operation` 自动适配，不连接、不提权。只去除已匹配的提示符和首行命令回显；连接器因拒绝命令而关闭时，后续读取跳过，不自动重连。自定义会话仍可实现 `send_commands` 协议。
 
 ## 领域术语
 
@@ -101,7 +103,7 @@ bundle exec rake build
 
 `bundle exec rake` 执行 RSpec、RuboCop 及离线示例。测试放在 `spec/`，沿用项目 RSpec 约定；样例采用合成或脱敏证据。新增会话适配时补充成功、拒绝、断链、取消、非法回执及证据保留回归。离线测试不代表所有设备版本均通过实机验证。
 
-`bundle exec ruby -Ilib benchmark/body.rb` 测量合成回显的正文解码时间及对象分配，并校验正文内容；不代表设备网络吞吐。
+`bundle exec ruby -Ilib benchmark/body.rb` 测量正文解码，`bundle exec ruby -Ilib benchmark/reader.rb` 每轮测量 10,000 次顺序采集；两者均输出合成回显下的耗时与对象分配，并校验内容。比较版本时保持 Ruby、输入和主机一致，不据此推断设备网络吞吐。
 
 使用声明的最低 Ruby 版本检查兼容性。方法用途统一使用简明中文注释；复杂实现还需说明业务规则、实现思路及关键分支。保持公开返回值与错误契约。真实回显和凭据不可进入示例、fixture、日志或发布包。
 

data/README.md

@@ -72,9 +72,11 @@ puts "SHA-256: #{capture.evidence.first[:sha256]}"
 
 ## Public contract and limits
 
-`Reader.new(session:, clock:).read(command)` returns a `Capture`. Inspect `success?`, `skipped?`, `failure`, and `evidence`; access the body explicitly through `body`. `to_h`, `as_json`, and `inspect` omit the body.
+`Reader.new(session:, clock:).read(command)` returns a `Capture`. Inspect `success?`, `skipped?`, `failure`, and `evidence`; access the body explicitly through `body`. `to_h`, `as_json`, and `inspect` omit the body. `Reader`, the borrowed `Session` adapter, and its response use safe `inspect`/`PP` displays that do not traverse caller-owned objects or consult connection state. Response string interpolation is also safe; raw output and decoded bodies remain available through explicit response APIs.
 
-A custom session implements `connected?` and `send_commands([command])`. Already loaded `Net::Connector::Base` sessions are adapted automatically through `execute_operation`, without connecting or requesting privilege. The adapter removes the matched prompt and first-line command echo, and keeps raw bytes only in the explicit capture evidence boundary. A native connector that closes on command rejection stays closed; later reads are skipped. A response exposes `output`, a boolean `success?`, an array `steps`, `value!` for a successful body, and `error` on failure. A successful read must contain exactly one completed step. The optional `preserve_session_on_rejection:` keyword is supplied only when the session explicitly declares it.
+A custom session implements `connected?` and `send_commands([command])`. Already loaded `Net::Connector::Base` sessions from net-connector **0.13.0 or newer** are adapted automatically through `execute_operation`, without connecting or requesting privilege. The adapter removes the matched prompt and first-line command echo, and keeps raw bytes only in the explicit capture evidence boundary. A native connector that closes on command rejection stays closed; later reads are skipped. A response exposes `output`, a boolean `success?`, an array `steps`, `value!` for a successful body, and `error` on failure. A successful read must contain exactly one completed step. The optional `preserve_session_on_rejection:` keyword is supplied only when the session explicitly declares it.
+
+net-connector remains optional: applications using this adapter must declare `gem "net-connector", ">= 0.13.0"` themselves. `examples/connector.rb` exercises the installed adapter through a local PTY process without opening network connections.
 
 Use each reader sequentially; create separate readers for concurrent devices. The caller owns connection, disconnection, credentials, and approved command selection. Reader does not decide whether arbitrary command text is read-only. Standard execution/response errors become safe diagnostics; cancellation signals propagate.
 
@@ -86,7 +88,7 @@ A command receipt belongs to one execution; a `Capture` holds its processed body
 
 Cancellation during execution or response processing propagates and marks the reader with `command_aborted`. Later reads are skipped even if the borrowed session still reports connected; the host retains responsibility for closing or replacing it.
 
-The clock must be callable and return `Time`. Times and response bodies are copied before later callbacks can mutate them. Successful captures require a string body (including an empty string); failed captures have no body, and skipped captures require a failure without execution evidence. Wall-clock timestamps can move backwards and are not elapsed-time measurements.
+The clock must be callable and return `Time`. Mutable times and response bodies are copied before later callbacks can mutate them; frozen `Time` values are reused directly, and immutable bodies may be shared. The observation clock runs after the source fingerprint and body snapshot have been fixed, so its callback cannot mix two responses. Successful captures require a string body (including an empty string); failed captures have no body, and skipped captures require a failure without execution evidence. Wall-clock timestamps can move backwards and are not elapsed-time measurements.
 
 ## Development and tests
 
@@ -103,7 +105,7 @@ bundle exec rake build
 
 Use the declared minimum Ruby version for compatibility checks. Document source methods and non-obvious business logic in concise Chinese, preserve public return/error contracts, and never add raw device captures or credentials to examples, fixtures, logs, or release archives.
 
-Run `bundle exec ruby -Ilib benchmark/body.rb` to measure body decoding and allocations against synthetic output, with semantic checks. This does not measure device network throughput.
+Run `bundle exec ruby -Ilib benchmark/body.rb` to measure body decoding, or `bundle exec ruby -Ilib benchmark/reader.rb` for 10,000 sequential captures per trial. Both report allocations and elapsed time against synthetic output, with semantic checks. Compare versions under the same Ruby, input and host; these do not measure device network throughput.
 
 ## Release
 

data/docs/architecture-zh.md

@@ -26,7 +26,7 @@ capture.evidence # command / sha256 / bytes / observed_at
 会话协议为 `connected?` 和 `send_commands([command])`。返回值须提供 `output`、布尔 `success?`、数组 `steps`；
 成功必须只有一个步骤，`value!` 必须返回正文字符串，失败通过 `error` 提供原因。
 `output` 用于原始来源摘要，`value!` 是连接器处理后的正文，两者不要求相等。
-自定义协议由宿主清理正文；原生 `Net::Connector::Base` 由可选适配器绑定当前完整提示符，并在证据摘要生成后去除命令回显及提示符。适配器不主动加载 net-connector，不连接、不提权。调用方只传目录中已批准的查询。
+自定义协议由宿主清理正文；net-connector 0.13.0 及以上版本的原生 `Net::Connector::Base` 由可选适配器绑定当前完整提示符，并在证据摘要生成后去除命令回显及提示符。适配器不主动加载 net-connector，不连接、不提权。调用方只传目录中已批准的查询。
 
 只有会话方法显式声明 `preserve_session_on_rejection:` 时，才传 `true`。
 原生 net-connector 关闭拒绝命令后的会话时，Reader 保留该关闭状态；自定义适配器只有确认会话仍可用，才允许下一条独立命令。
@@ -35,15 +35,24 @@ capture.evidence # command / sha256 / bytes / observed_at
 
 响应处理异常保留此前取得的 SHA256、字节数与时间。没有回执时不伪造摘要。
 `Capture` 的正文与元数据分别复制、冻结；正常序列化不包含正文、异常对象、消息或凭据。
-字段 `started_at/completed_at` 为采集阶段时间；证据的 `observed_at` 为实际收到响应的时间。
+字段 `started_at/completed_at` 为采集阶段时间；证据的 `observed_at` 为响应快照固定后的观察时间，不等同于传输层最后一个字节的到达时间。
 命令失败与领域健康状态分开，Reader 不产生 pass/fail 或完整库存判断。
 
 `StandardError` 在单命令执行、响应验证和状态查询边界转换为安全诊断；取消信号继续抛出。执行或响应处理未能完成回执时，ensure 保留原有失败或记录 `command_aborted`，包括不进入 rescue 的 Thread.kill。此 Reader 后续只返回 skipped，不关闭借用会话、不重放命令。
 
-开始时间在执行回调之前保存副本，正文在后续状态回调之前保存副本。注入时钟必须可调用并返回 Time；时间允许因墙上时钟校准而回拨。`Capture` 拒绝类型错误以及成功/失败/跳过状态与正文或证据矛盾的回执。
+开始时间在执行回调之前保存副本，正文和来源摘要在观察时钟及后续状态回调之前固定；已经冻结的字符串和时间允许安全共享。注入时钟必须可调用并返回 Time；时间允许因墙上时钟校准而回拨。`Capture` 拒绝类型错误以及成功/失败/跳过状态与正文或证据矛盾的回执。
 
 原生适配器只读取渲染后正文的首行来判断回显，不构造全部行数组；成功路径不再调用连接器 `value!` 重复拼接输出，失败仍由连接器原样抛出错误。`benchmark/body.rb` 使用合成回显验证内容、耗时和分配量，不提供真实设备网络性能结论。
 解析异常由领域 Collector 在本条命令或本次 AP 子任务内隔离。
 调用方须顺序使用同一个 Reader；跨设备并发各自建立 Reader。
 
 运行依赖由 gemspec 声明；会话所有权与命令来源响应时间契约保持不变。没有环境变量、数据库表或调度入口。
+
+
+## 当前执行边界
+
+内部 `Command` 模块统一 Reader、Capture 与原生 Session 的单行命令校验及不可变文本快照，不判断命令是否只读。宿主仍决定批准的查询与会话所有权。
+
+来源摘要先固定，正文提取失败仍保留有效证据；观察时钟在正文快照之后调用。时钟响应无效时返回 response 阶段失败并不发布缺少时间的证据，取消则传播并抑制后续查询。适配器仅在首行和命令去除首尾空白后相等时去除回显，正文缩进和后续同名行保留。
+
+`script/verify_package.rb` 先验证不含 net-connector 的安装和离线示例，再独立安装可选连接器，通过包内本地 PTY 示例验证适配器，避免工作区或旧锁文件掩盖已发布依赖的接口变化。

data/examples/connector.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "ctx_driver"
+require "net/connector"
+
+# 用本地 PTY 驱动已安装连接器的完整会话；不连接网络设备。
+class ExampleConnectorTransport < Net::Connector::Transports::Pty
+  # 子进程先给出提示符，随后逐条回显查询和合成正文。
+  def argv
+    [ RbConfig.ruby, "-e", '$stdout.sync = true; print "device>"; while (line = gets); print line, "  interface Ethernet1/1 up\r\ndevice>"; end' ]
+  end
+end
+
+configuration = Net::Connector::Configuration.new(host: "192.0.2.1", username: "audit", command_timeout: 2, login_timeout: 2)
+device = Net::Connector.build(:cisco_ios, configuration: configuration, transport: ExampleConnectorTransport.new(configuration))
+begin
+  device.connect
+  reader = CtxDriver::Reader.new(session: device)
+  2.times do
+    capture = reader.read("  show interfaces  ")
+    abort "Connector capture failed" unless capture.success? && capture.body == "  interface Ethernet1/1 up\n"
+    abort "Connector evidence missing" unless capture.evidence.one? && capture.evidence.first[:bytes].positive?
+    abort "Borrowed session was closed" unless device.connected?
+  end
+  puts "Connector adapter: PTY, command echo, evidence and borrowed ownership passed"
+ensure
+  device.close
+end

data/lib/ctx_driver/capture.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "ctx_parser/immutable"
+require_relative "command"
 
 module CtxDriver
   # 原始正文须显式读取；默认检查与序列化仅展示采集元数据。
@@ -9,9 +10,7 @@ module CtxDriver
 
     # 冻结单条命令回执及其正文、时间、证据和失败元数据。
     def initialize(command:, body: nil, started_at:, completed_at:, evidence: [], failure: nil, skipped: false)
-      unless command.is_a?(String) && !command.strip.empty? && !/[\x00-\x1f\x7f]/.match?(command)
-        raise ArgumentError, "One command without control characters is required"
-      end
+      command = Command.snapshot(command)
       raise ArgumentError, "Capture body must be text or nil" unless body.nil? || body.is_a?(String)
       unless started_at.is_a?(Time) && completed_at.is_a?(Time)
         raise ArgumentError, "Capture timestamps must be Time values"
@@ -25,9 +24,10 @@ module CtxDriver
       raise ArgumentError, "Failed captures cannot contain a body" if failure && !body.nil?
       raise ArgumentError, "Skipped captures require failure without evidence" if skipped && (failure.nil? || evidence.any?)
 
-      @command = command.dup.freeze
-      @body = body&.dup&.freeze
-      @started_at, @completed_at = started_at.dup.freeze, completed_at.dup.freeze
+      @command = command
+      @body = body.nil? || body.frozen? ? body : body.dup.freeze
+      @started_at = started_at.frozen? ? started_at : started_at.dup.freeze
+      @completed_at = completed_at.frozen? ? completed_at : completed_at.dup.freeze
       @evidence, @failure = [ evidence, failure ].map { |value| CtxParser::Immutable.copy(value) }
       @skipped = skipped
       freeze

data/lib/ctx_driver/command.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module CtxDriver
+  # 单条命令的值边界；只校验文本完整性，是否为只读查询由宿主决定。
+  module Command
+    # 校验并固定命令；已有冻结文本可以安全共享。
+    def self.snapshot(value)
+      unless value.is_a?(String) && !value.strip.empty? && !/[\x00-\x1f\x7f]/.match?(value)
+        raise ArgumentError, "One command without control characters is required"
+      end
+
+      value.frozen? ? value : value.dup.freeze
+    end
+  end
+  private_constant :Command
+end

data/lib/ctx_driver/failure.rb

@@ -29,7 +29,7 @@ module CtxDriver
     # 已加载 net-connector 时复用其稳定诊断词表，否则使用调用方的回退代码。
     def self.code(error, fallback)
       value = error.code if error.respond_to?(:code)
-      defined?(Net::Connector::ErrorMetadata) ? Net::Connector::ErrorMetadata.code(value) || fallback : fallback
+      defined?(Net::Connector::Error::Metadata) ? Net::Connector::Error::Metadata.code(value) || fallback : fallback
     rescue StandardError
       fallback
     end

data/lib/ctx_driver/reader.rb

@@ -26,10 +26,7 @@ module CtxDriver
 
     # 执行一条经过校验的查询，保留独立结果或失败。
     def read(command)
-      unless command.is_a?(String) && !command.strip.empty? && !/[\x00-\x1f\x7f]/.match?(command)
-        raise ArgumentError, "One command without control characters is required"
-      end
-      command = command.dup.freeze
+      command = Command.snapshot(command)
       started_at = current_time
       if failure
         return Capture.new(command: command, started_at: started_at, completed_at: current_time,
@@ -44,6 +41,9 @@ module CtxDriver
       @session_failure ||= detect_session_failure
     end
 
+    # 仅显示边界类型，避免遍历借用会话、时钟或触发外部状态查询。
+    def inspect = "#<#{self.class.name}>"
+
     private
 
     # 立即保存时钟快照，避免后续用户回调改变已记录的时区或时间。
@@ -51,7 +51,7 @@ module CtxDriver
       time = @clock.call
       raise TypeError, "Clock must return a Time" unless time.is_a?(Time)
 
-      time.dup.freeze
+      time.frozen? ? time : time.dup.freeze
     end
 
     # 分离执行与回执校验；后续校验失败时仍保留已取得的证据。
@@ -68,8 +68,7 @@ module CtxDriver
         output = receipt.output
         raise TypeError, "Command output must be text" unless output.is_a?(String)
 
-        evidence = [ { command: command, sha256: Digest::SHA256.hexdigest(output), bytes: output.bytesize,
-          observed_at: current_time.getutc.iso8601(6) } ]
+        evidence = [ { command: command, sha256: Digest::SHA256.hexdigest(output), bytes: output.bytesize } ]
         success = receipt.success?
         unless [ true, false ].include?(success) && receipt.steps.is_a?(Array) && (!success || receipt.steps.one?)
           raise TypeError, "One query must return one completed command"
@@ -78,7 +77,7 @@ module CtxDriver
           body = receipt.value!
           raise TypeError, "Command body must be text" unless body.is_a?(String)
 
-          body = body.dup.freeze
+          body = body.dup.freeze unless body.frozen?
         else
           command_failure = Failure.details(receipt.error, fallback: :command_failed, stage: :execute)
         end
@@ -86,6 +85,16 @@ module CtxDriver
         fallback = stage == :execute ? :command_execution_failed : :invalid_command_result
         command_failure = Failure.details(error, fallback: fallback, stage: stage)
       end
+      # 外部时钟回调只在正文与摘要固定后调用，不能复用本条响应缓冲区。
+      begin
+        unless evidence.empty?
+          observed_at = current_time.getutc.iso8601(6)
+          evidence = [ evidence.first.merge(observed_at: observed_at) ]
+        end
+      rescue StandardError => error
+        evidence = []
+        command_failure ||= Failure.details(error, fallback: :invalid_command_result, stage: :response)
+      end
       state_failure = detect_session_failure
       # 单命令失败但会话仍可用时继续独立查询；断链或状态不明才阻止后续提交。
       @session_failure = command_failure || state_failure if state_failure

data/lib/ctx_driver/session.rb

@@ -1,10 +1,21 @@
 # frozen_string_literal: true
 
+require_relative "command"
+
 module CtxDriver
   # 适配已加载的 net-connector；不连接、不提权，也不恢复已关闭的借用会话。
   class Session
     # 先交出原始回执，Reader 建立证据后才按需解码正文。
     Response = Data.define(:result) do
+      # 不依赖原始回执自身的脱敏实现，默认检查不展开来源结果。
+      def inspect = "#<#{self.class.name}>"
+
+      # Data 的默认 to_s 保留原始成员检查实现，日志插值也须脱敏。
+      def to_s = inspect
+
+      # Data 的 PP 默认按成员展开，显式限制为安全表示。
+      def pretty_print(printer) = printer.text(inspect)
+
       def output = result.output
       def steps = result.steps
       def success? = result.success?
@@ -15,9 +26,9 @@ module CtxDriver
         # 成功路径无需再次拼接全部输出；失败仍交由连接器保留异常契约。
         result.value! unless result.success?
         step = result.steps.fetch(0)
-        body = Net::Connector::TerminalText.render(step.output.delete_suffix(step.prompt.to_s))
+        body = Net::Connector::Terminal::Text.render(step.output.delete_suffix(step.prompt.to_s))
         first = body.each_line("\n").first
-        first && first.strip == step.command.text ? body.delete_prefix(first) : body
+        first && first.strip == step.command.text.strip ? body.delete_prefix(first) : body
       end
     end
     private_constant :Response
@@ -27,18 +38,23 @@ module CtxDriver
       @session = session
     end
 
+    # 不展开调用方拥有的连接器，也不查询连接状态。
+    def inspect = "#<#{self.class.name}>"
+
     # 复用连接器的真实状态，避免失败后隐式重连。
     def connected? = @session.connected?
 
     # 单命令操作保护响应正文，并绑定当前完整提示符。
     def send_commands(commands)
-      raise ArgumentError, "Expected one query" unless commands.one?
+      raise ArgumentError, "Expected one query" unless commands.is_a?(Array) && commands.one?
+
+      text = Command.snapshot(commands.first)
 
-      prompt = Net::Connector::TerminalText.render(@session.current_prompt.to_s).strip
+      prompt = Net::Connector::Terminal::Text.render(@session.current_prompt.to_s).strip
       raise ArgumentError, "Session prompt is unavailable" if prompt.empty?
 
       pattern = /(?:\A|(?<=[\r\n]))[ \t\x00]*#{Regexp.escape(prompt)}[ \t\x00]*[\r\n]*\z/
-      command = Net::Connector::Command.new(commands.first, prompt: pattern, output_sensitive: true)
+      command = Net::Connector::Command.new(text, prompt: pattern, output_sensitive: true)
       result = @session.execute_operation(Net::Connector::Script.new([ command ]), name: :ctx_driver, privilege: false)
       Response.new(result)
     end

data/lib/ctx_driver/version.rb

@@ -2,5 +2,5 @@
 
 module CtxDriver
   # 公开包版本，供 RubyGems 元数据和运行时调用方共用。
-  VERSION = "0.2.1"
+  VERSION = "0.2.3"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ctx_driver
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.3
 platform: ruby
 authors:
 - Gatework contributors
@@ -63,9 +63,11 @@ files:
 - README.md
 - docs/architecture-zh.md
 - docs/release.md
+- examples/connector.rb
 - examples/offline.rb
 - lib/ctx_driver.rb
 - lib/ctx_driver/capture.rb
+- lib/ctx_driver/command.rb
 - lib/ctx_driver/failure.rb
 - lib/ctx_driver/reader.rb
 - lib/ctx_driver/session.rb