feat: 增加公共 HSMS 连接 API

CHANGELOG.md

@@ -42,5 +42,10 @@
   StreamFrame 重试间隔并关闭指数退避，Passive 监听重试保持独立。
 - 增加按接收进展与会话代次隔离的 T8 监视、专用超时异常，以及部分长度
   头、部分 Payload、陈旧回调、替换会话和真实 TCP 超时测试。
+- 增加公共 <code>HsmsConnection</code> 与不可变
+  <code>HsmsConnectionOptions</code>，组合动态消息收发、Selected 等待、
+  单消费者事件流、入站一次性回复和控制命令。
+- 增加公共 API 选项边界、生命周期、等待/事务取消和 Active/Passive
+  双端真实 TCP 往返测试；入站回复令牌绑定原连接与原运输会话。
 
 [Unreleased]: https://github.com/CSJ608/SecsFrame/compare/main...HEAD

README.md

@@ -28,13 +28,16 @@
 共用的内部 HSMS-SS 状态机已经覆盖 TCP 会话、Select、Linktest、Reject、
 Deselect、Separate、T6/T7 和 Selected 数据门控。内部数据事务 actor
 进一步提供实际写出后启动的 T3、复合事务键关联、入站回复和会话失效
-隔离。Item 用法与边界见
+隔离。公共 <code>HsmsConnection</code> 将这些内部层组合成显式计时
+配置、动态消息收发、状态等待和单消费者事件流。Item 用法与边界见
 [docs/SECS-II-ITEMS.md](docs/SECS-II-ITEMS.md)，消息集成见
 [docs/SECS-MESSAGES.md](docs/SECS-MESSAGES.md)，传输适配边界见
 [docs/STREAMFRAME-ADAPTER.md](docs/STREAMFRAME-ADAPTER.md)，状态机边界见
 [docs/HSMS-SESSION-STATE-MACHINE.md](docs/HSMS-SESSION-STATE-MACHINE.md)，
 数据事务边界见
 [docs/HSMS-DATA-TRANSACTIONS.md](docs/HSMS-DATA-TRANSACTIONS.md)，
+公共连接用法见
+[docs/HSMS-CONNECTION.md](docs/HSMS-CONNECTION.md)，
 整体路线图见
 [docs/ROADMAP.md](docs/ROADMAP.md)。
 

docs/ARCHITECTURE.md

@@ -120,6 +120,18 @@ HSMS 头 Session ID 与 System Bytes。没有 W-Bit 的出站消息在写出后
 和测试边界见
 [HSMS-DATA-TRANSACTIONS.md](HSMS-DATA-TRANSACTIONS.md)。
 
+### 公共连接外观
+
+<code>HsmsConnection</code> 是运输、会话和数据事务 actor 之上的薄公共
+组合层。它要求显式网络、协议 Session ID 和 T3/T5/T6/T7/T8 配置，公开
+动态消息发送、一次性入站回复、控制命令、Selected 等待和单消费者事件
+流。公共层不暴露 transport Session generation、StreamFrame
+<code>StreamConnectionOptions</code> 或 #38/#39 的回调适配。
+
+连接内部独占消费事务事件，并分别更新状态等待信号与公共事件 channel，
+因此 readiness 等待不会与业务消息消费者竞争。详细生命周期和取消语义
+见 [HSMS-CONNECTION.md](HSMS-CONNECTION.md)。
+
 ### 严格与兼容分离
 
 默认按标准拒绝畸形帧、非法 Item 和无效状态转换。对现场设备的已知偏差通过命名明确的兼容选项启用，并记录来源、风险和测试向量。

docs/COMPATIBILITY.md

@@ -32,3 +32,13 @@ StreamFrame #38（未完成帧超时）和 #39（会话感知发送确认与消
 
 具体机制、测试证据和已知代价见
 [STREAMFRAME-ADAPTER.md](STREAMFRAME-ADAPTER.md)。
+
+## 跨实现测试依赖
+
+计划中的 secs4net 互操作夹具只能使用 nuget.org 发布的官方 NuGet 包，
+并在 <code>Directory.Packages.props</code> 中固定明确版本。不得使用
+本地源码 checkout、ProjectReference、本地 feed 或自行修改的程序集作为
+互操作对端。源码仓库只读参考不进入 SecsFrame 的还原、构建或测试图。
+
+夹具和文档必须记录官方包 ID、版本、运行框架、测试方向与通过/失败结果，
+避免把本地差异误判为上游互操作能力。

docs/HSMS-CONNECTION.md

@@ -0,0 +1,104 @@
+# 公共 HSMS 连接 API
+
+## 范围
+
+<code>HsmsConnection</code> 是当前基础层的最小公共入口。它在内部组合
+StreamFrame 运输适配、HSMS-SS 会话 actor 和数据事务 actor，调用方不需要
+接触 transport Session generation、发送确认回调或内部 channel。
+
+当前公共能力包括：
+
+- Active 或 Passive TCP 连接以及 Select 会话建立；
+- 等待 Selected 状态和读取当前状态；
+- 发送任意动态 <code>SecsMessage</code>，无需消息目录或预生成类型；
+- W-Bit Primary 的 T3 关联与 Secondary 返回；
+- 接收入站 Primary 或未匹配消息，并使用不可伪造令牌回复一次；
+- Linktest、Deselect 和 Separate 控制命令；
+- 状态、数据、未消费控制消息和解码失败的单消费者异步事件流。
+
+Host/Equipment 是后续业务能力角色，不由 Active/Passive 推断。
+
+## 显式配置
+
+<code>HsmsConnectionOptions</code> 构造时必须给出：
+
+| 配置 | 当前用途 |
+|---|---|
+| IP 地址、端口 | Active 的远端地址或 Passive 的本地监听地址 |
+| ConnectionMode | 只表示哪一端建立 TCP 连接 |
+| SessionId | 出站 Data Message 使用的协议 Session ID |
+| T3 | W-Bit Primary 写完后等待 Secondary |
+| T5 | Active TCP 连接失败后的固定重试间隔 |
+| T6 | Select、Linktest、Deselect 控制响应等待 |
+| T7 | TCP 建立后等待进入 Selected |
+| T8 | 未完成消息接收进展等待 |
+
+仓库没有内置或暗示标准默认值。T5 必须能无损转换成 StreamFrame 使用的
+整毫秒范围；Passive 监听重试不被解释成 T5。每个取值应依据团队合法获得
+的 E37/E37.1 版本、设备通信手册和互操作证据确定。
+
+## 生命周期
+
+~~~csharp
+var options = new HsmsConnectionOptions(
+    IPAddress.Parse("192.0.2.10"),
+    port: 5000,
+    HsmsConnectionMode.Active,
+    sessionId: 0,
+    t3: TimeSpan.FromSeconds(45),
+    t5: TimeSpan.FromSeconds(10),
+    t6: TimeSpan.FromSeconds(5),
+    t7: TimeSpan.FromSeconds(10),
+    t8: TimeSpan.FromSeconds(5));
+
+await using var connection = new HsmsConnection(options);
+connection.Start();
+await connection.WaitUntilSelectedAsync(cancellationToken);
+
+var secondary = await connection.SendAsync(
+    new SecsMessage(
+        stream: 1,
+        function: 1,
+        replyExpected: true),
+    cancellationToken);
+~~~
+
+以上计时值只演示 API 形状，不是标准推荐值。
+
+<code>Start</code> 只能调用一次，连接活动期由
+<code>DisposeAsync</code> 结束。<code>WaitUntilSelectedAsync</code>
+不消费业务事件；取消它只取消本次等待，不停止连接。
+
+<code>GetEventsAsync</code> 同一时刻只允许一个消费者；枚举器结束或释放
+后可以重新获取。连接内部先独占消费事务 actor 的事件，再写入公共事件
+流，因此 Selected 等待不会和业务接收争抢消息。调用方通常应使用一个
+长期事件循环处理：
+
+- <code>StateChanged</code>：状态转换和可选错误；
+- <code>DataMessageReceived</code>：携带
+  <code>HsmsIncomingDataMessage</code>；
+- <code>ControlMessageReceived</code>：未被当前控制或数据事务认领的帧；
+- <code>DataMessageDecodeFailed</code>：原始帧和严格解码错误。
+
+入站消息只有 <code>ReplyExpected</code> 为真时可以回复。回复自动复制原
+协议 Session ID 与 System Bytes，并绑定原 transport session；开始回复
+后令牌不可再次使用，也不会在替换连接上重放。
+
+## 取消与失败
+
+- 出站无 W-Bit 消息在整帧写完后完成；
+- 出站 W-Bit Primary 在整帧写完后启动 T3；
+- 取消发送会结束本地等待，不会自动关闭 Selected 会话，也不能撤回已经
+  上线的字节；迟到 Secondary 作为未匹配入站消息上报；
+- Deselect、Separate、断线、替换会话或释放会结束绑定旧会话的等待；
+- 事件枚举的取消只结束该消费者；连接仍须显式释放。
+
+当前具体异常类型仍以 <code>TimeoutException</code>、
+<code>IOException</code>、<code>OperationCanceledException</code> 和参数/
+状态异常为稳定分类；更细的公共诊断模型将在互操作证据后再收敛。
+
+## 验证边界
+
+真实 TCP 测试使用两个公共连接完成 Select、Linktest、嵌套 Item
+Primary/Secondary、重复回复拒绝和取消后保持 Selected。它证明当前实现
+各层能够组合工作，不替代 SEMI 一致性认证或第三方设备互操作。

docs/HSMS-DATA-TRANSACTIONS.md

@@ -86,8 +86,12 @@ Active/Passive 双端真实 TCP 回环另行覆盖 Select 后的 Primary/Seconda
 
 ## 标准核对边界
 
-实现追踪 SEMI E5-0725、E37-0222 与 E37.1-0819。发布公共事务 API 前，
-仍须使用团队合法获得的版本核对 Primary/Secondary 定义、W-Bit 与
-Function 约束、T3 的精确启停、SxF0/S9Fx 对事务的影响、System Bytes
-分配规则及 Reject 后处理。仓库不得提交标准正文、状态表或由付费材料
-机械转换的测试资料，也不据当前工程测试声明完整合规。
+实现追踪 SEMI E5-0725、E37-0222 与 E37.1-0819。扩大公共事务 API 或
+声明合规前，仍须使用团队合法获得的版本核对 Primary/Secondary 定义、
+W-Bit 与 Function 约束、T3 的精确启停、SxF0/S9Fx 对事务的影响、
+System Bytes 分配规则及 Reject 后处理。仓库不得提交标准正文、状态表
+或由付费材料机械转换的测试资料，也不据当前工程测试声明完整合规。
+
+<code>HsmsDataTransactionManager</code> 仍是内部 actor；公共调用方通过
+<code>HsmsConnection</code> 使用其动态发送、入站回复和事件能力。公共
+生命周期与取消语义见 [HSMS-CONNECTION.md](HSMS-CONNECTION.md)。

docs/HSMS-SESSION-STATE-MACHINE.md

@@ -77,13 +77,15 @@ System Bytes。旧会话的帧、发送完成和计时器回调不会推进替
 <code>StreamFrameHsmsTransport</code> 完成 Select、Linktest 和 Deselect
 流程；其上的事务回环还完成带嵌套 Item 的 Primary/Secondary 往返。数据
 事务细节见 [HSMS-DATA-TRANSACTIONS.md](HSMS-DATA-TRANSACTIONS.md)。
+公共 <code>HsmsConnection</code> 另行验证同一路径的外部组合契约，见
+[HSMS-CONNECTION.md](HSMS-CONNECTION.md)。
 测试证明当前实现路径可互操作，不替代认证工具或第三方设备互操作证据。
 
 ## 尚未实现
 
 - 授权标准核对后的 T5/T8 默认值和完整标准语义；
 - 自动周期 Linktest 调度；
-- 公共会话 API、Host/Equipment 能力 API；
+- Host/Equipment 能力 API；
 - 与 secs4net 或真实设备的跨实现互操作矩阵。
 
 实现这些行为前，需要使用团队合法获得的 SEMI E37-0222 与 E37.1-0819

docs/ROADMAP.md

@@ -16,14 +16,17 @@
 - [x] Linktest、Reject、Deselect 控制消息与对应 T6 分支。
 - [x] Selected 数据发送、Primary/Secondary 关联、T3 与入站同事务回复。
 - [x] 显式 T5 固定重连节流、T8 接收进展监视和跨会话旧回调隔离。
+- [x] 最小公共连接外观、显式 T3/T5/T6/T7/T8 配置、动态消息事件与
+  确定的取消/释放语义。
 - [ ] 使用授权 E37/E37.1 核对 T5/T8 默认值与精确启停边界。
-- Host、Equipment 双角色回环集成测试，以及与 secs4net 的互操作测试。
-
-阶段 1 的下一最小切片是稳定最小公共连接外观：公开动态消息收发、会话
-状态、显式 T3/T5/T6/T7/T8 配置和确定的取消/关闭语义，同时继续把
-StreamFrame #38/#39 细节隔离在内部。随后建立与 secs4net 的跨实现
-Select、Linktest 和 Primary/Secondary 互操作夹具。任何标准默认值和
-完整合规结论都依赖团队合法获得的 E37/E37.1 副本与一致性测试。
+- Host、Equipment 双角色回环集成测试，以及与 nuget.org 官方 secs4net
+  包的互操作测试。
+
+阶段 1 的下一最小切片是跨实现互操作夹具：通过中央包管理固定
+nuget.org 官方 secs4net 包版本，覆盖 Select、Linktest 和
+Primary/Secondary。不得引用、构建或链接本地 secs4net 源码 checkout。
+随后根据互操作结果收敛公共诊断模型。任何标准默认值和完整合规结论都
+依赖团队合法获得的 E37/E37.1 副本与一致性测试。
 
 ## 阶段 2：GEM 通用能力
 

docs/STANDARDS.md

@@ -56,5 +56,7 @@
 - 未经验证的“完整合规”“通过认证”等声明。
 
 本项目只读参考 StreamFrame 和 MIT 许可的 secs4net 以交叉理解公开协议
-实现，没有复制参考仓库代码。未来如引入实质性开源代码，必须保留对应
-版权与许可证文本，并在变更说明中记录来源。
+实现，没有复制参考仓库代码。该 secs4net 源码 checkout 不参与互操作
+构建；互操作夹具只允许使用 nuget.org 发布并固定版本的官方 NuGet 包。
+未来如引入实质性开源代码，必须保留对应版权与许可证文本，并在变更说明
+中记录来源。