feat: 增加 Trace 结构化诊断导出

CHANGELOG.md

@@ -21,6 +21,10 @@
 
 ### 新增
 
+- 增加独立 <code>SecsFrame-DiagnosticTrace/1</code> 信封，为公共
+  <code>HsmsDiagnostic</code> 提供确定性受限字段快照导出与严格读取。
+- 诊断快照只保留代码、层级、操作、状态、计时器和可选协议标量，明确排除
+  原异常与未解码帧；增加黄金向量、畸形字段、资源限制和敏感内容不泄漏测试。
 - 增加默认关闭的 Trace 时序重放；按 allowlist 筛选后的 Sent 记录时间戳
   计算间隔，支持显式速度倍率和缩放后单次等待封顶。
 - 增加时序倒退预验证、筛选间隔、缩放/封顶、等待取消和默认零等待测试；

README.md

@@ -19,7 +19,7 @@
 | `SecsFrame` | SECS-II 数据模型、HSMS-SS 会话与事务基础 |
 | `SecsFrame.Gem` | GEM 通用状态模型与能力服务 |
 | `SecsFrame.Sml` | 动态消息的确定性 SML 调试读写 |
-| `SecsFrame.Trace` | 已解码消息的导出、结构化脱敏与受控重放 |
+| `SecsFrame.Trace` | 已解码消息与受限诊断快照的导出、结构化脱敏与受控重放 |
 | `SecsFrame.Smn` | E173 SMN 日志、文档与消息表示 |
 | `SecsFrame.Sedd` | E172 SEDD 设备接口数据字典 |
 
@@ -43,7 +43,8 @@ Equipment 应用发送策略的 Collection Event、报警目录查询、单报
 不进入线上通讯路径。
 <code>SecsFrame.Trace</code> 在该文本层上提供版本化的数据消息 Trace 信封、
 严格的 Item 路径脱敏、显式 allowlist 重放，以及默认关闭的缩放/封顶时序
-重放；它不会接管连接事件消费者，也不会复用原事务标识。
+重放；独立诊断信封只保存稳定标量，不保存异常或原始帧。该包不会接管连接
+事件消费者，也不会复用原事务标识。
 Item 用法与边界见
 [docs/SECS-II-ITEMS.md](docs/SECS-II-ITEMS.md)，消息集成见
 [docs/SECS-MESSAGES.md](docs/SECS-MESSAGES.md)，传输适配边界见

docs/ARCHITECTURE.md

@@ -17,6 +17,8 @@ E172 SEDD 与 E173 SMN 是可选元数据/表示层，不进入核心通讯路
 解码的数据消息；它不订阅内部 transport 或创建第二个公共事件消费者。
 Trace 的时序重放必须显式启用，只在允许发送记录之间等待，并继续通过公共
 发送 API 创建新事务；默认重放不引入时间等待。
+结构化诊断使用独立只读快照信封：只复制公共诊断的稳定标量，明确排除原
+异常和未解码帧，也不能进入重放路径。
 
 ## 核心原则
 
@@ -166,6 +168,7 @@ HSMS 头 Session ID 与 System Bytes。没有 W-Bit 的出站消息在写出后
 - `SecsFrame.Sml` 依赖 `SecsFrame`，不得依赖 GEM 或线上传输实现。
 - `SecsFrame.Trace` 依赖 `SecsFrame.Sml` 与 `SecsFrame`，重放必须回到
   公共发送 API，不得直接构造或写出保留旧事务标识的线上帧；可选时序只
-  控制相邻发送前的等待，不得绕过连接状态、T3 或显式 allowlist。
+  控制相邻发送前的等待，不得绕过连接状态、T3 或显式 allowlist。诊断
+  导出不得隐式包含 <code>Exception</code> 或 <code>HsmsFrame</code>。
 - 核心包不得依赖 GEM、SML/SMN、依赖注入容器或具体日志实现。
 - 状态机计时使用可替换的时间抽象，测试不得依赖真实长时间等待。

docs/HSMS-DIAGNOSTICS.md

@@ -71,6 +71,14 @@ Session ID 与 System Bytes；拒绝诊断保留远端状态或原因字节。
 工艺数据。库不自动格式化、写日志或上传它。应用在记录前应按自己的数据
 分类策略做脱敏和长度限制；常规指标优先只使用代码、层级、操作和计时器。
 
+<code>SecsFrame.Trace</code> 提供独立的
+<code>SecsFrame-DiagnosticTrace/1</code> 受限字段快照信封。
+<code>SecsTraceDiagnosticRecord.Create</code> 只复制稳定代码、层级、操作、
+状态、计时器与可选协议标识/状态字节，不复制 <code>Error</code> 或
+<code>Frame</code>。这使结构化诊断可以确定性导出，但协议 Session ID、
+System Bytes 和远端状态字节仍属于运维元数据，导出文件仍应使用适当的
+访问控制与保留策略。具体格式和示例见 [TRACE.md](TRACE.md)。
+
 ## 标准边界
 
 诊断名称描述 SecsFrame 已实现并测试的工程行为，不新增 SEMI 默认值，也

docs/ROADMAP.md

@@ -99,7 +99,8 @@ E30-0526 材料。下一可执行优先级已转入阶段 3；SML 调试读写
 消息的版本化 Trace 导出、结构化脱敏与显式 allowlist 受控重放；重放通过
 公共发送 API 创建新事务，不复用旧会话或 System Bytes。可选时序重放也已
 完成：只使用允许发送记录的相邻时间戳，支持显式加速和缩放后单次等待封顶，
-默认重放仍不等待。
+默认重放仍不等待。结构化 HSMS 诊断现可通过独立受限信封导出；快照只包含
+稳定标量，明确排除异常和原始帧。
 
 ## 阶段 3：元数据与工具
 
@@ -108,11 +109,13 @@ E30-0526 材料。下一可执行优先级已转入阶段 3；SML 调试读写
 - E172 SEDD 设备字典导入、校验与发现。
 - [x] 已解码数据消息的 Trace 导出、结构化脱敏和受控重放基线。
 - [x] 显式启用、可缩放且单次等待封顶的 Trace 重放时序。
-- 控制消息、结构化诊断和故障原始样本等互操作诊断扩展。
+- [x] 不包含异常与原始帧的受限结构化诊断 Trace 导出和严格读取。
+- 控制消息和故障原始样本等互操作诊断扩展。
 
 当前 Trace 基线不接管连接事件流，也不把原始标识写回线上。时序重放默认
-关闭，并继续经过显式 allowlist 与公共发送 API。后续控制与故障诊断扩展
-必须先定义原始字节的数据分级、默认不导出策略和可验证脱敏边界。
+关闭，并继续经过显式 allowlist 与公共发送 API。诊断快照始终排除
+<code>Error</code> 与 <code>Frame</code>。后续控制与故障原始样本扩展必须先
+定义原始字节的数据分级、默认不导出策略和可验证脱敏边界。
 E173 SMN 与 E172 SEDD 仍需先核对授权标准及允许分发的 Schema/表示形式。
 
 ## 发布门槛

docs/TRACE.md

@@ -7,7 +7,8 @@
 - 确定性的 <code>SecsFrame-Trace/1</code> 文本导出和严格读取；
 - 按 Stream、Function 与 Item List 路径执行的结构化替换脱敏；
 - 只选择显式允许的本地发送记录，并通过正常公共发送 API 串行重放；
-- 可选按缩放且封顶的源时间间隔执行受控时序重放。
+- 可选按缩放且封顶的源时间间隔执行受控时序重放；
+- 不包含异常和原始帧的结构化 HSMS 诊断快照导出与严格读取。
 
 当前切片不是原始网络抓包器，不记录 TCP 字节、transport Session generation、
 控制帧或异常对象，也不会接管 <code>HsmsConnection</code> 的单消费者事件流。
@@ -54,6 +55,39 @@ Item、值和文本长度限制。解析错误使用包含记录索引与字符
 该格式是 SecsFrame 的版本化诊断信封，不是 SEMI 标准、PCAP 或原始 HSMS
 wire trace。协议标识只用于问题关联，不能作为新连接上的重放标识。
 
+## 结构化诊断信封
+
+<code>SecsTraceDiagnosticRecord</code> 从公共 <code>HsmsDiagnostic</code>
+创建只包含稳定标量的受限字段快照：
+
+~~~csharp
+if (connectionEvent.Diagnostic is { } diagnostic)
+{
+    var record = SecsTraceDiagnosticRecord.Create(
+        DateTimeOffset.UtcNow,
+        diagnostic);
+    var text = new SecsTraceDiagnosticCodec().Encode(new[] { record });
+}
+~~~
+
+独立信封固定使用 LF 与 11 个单空格分隔字段：
+
+~~~text
+SecsFrame-DiagnosticTrace/1
+Diagnostic 2026-08-29T05:00:00.0000000Z T3Timeout Transaction WaitForSecondary Selected T3 10 0x10203040 - -
+~~~
+
+字段依次为 UTC 时间、诊断代码、层级、操作、会话状态、可选计时器、协议
+Session ID、System Bytes、远端状态字节和被拒绝的 SType。枚举只接受当前
+已定义的精确名称；协议字节使用固定宽度大写十六进制。codec 同样限制记录数
+和总文本长度，并通过 <code>SecsTraceParseException</code> 报告记录索引与
+字符偏移。
+
+快照 API 不提供 <code>Error</code> 或 <code>Frame</code> 字段，创建快照时也
+不会读取或格式化它们，因此异常消息和未解码帧负载不会进入导出文本。该格式
+与 <code>SecsFrame-Trace/1</code> 消息信封相互独立，不能交给重放器。协议
+标识和状态字节仍是运维元数据；存储和共享文件时仍需执行访问控制与保留策略。
+
 ## 结构化脱敏
 
 脱敏发生在不可变 Item 树上，而不是对 SML 文本做字符串替换：
@@ -143,4 +177,6 @@ var results = await new SecsTraceReplayer().ReplayWithTimingAsync(
 资源限制、路径漂移、规则重叠、敏感值不进入导出文本、预验证零发送，以及
 时序缩放/封顶、筛选间隔、时间倒退预验证、等待取消和默认零等待。真实 TCP
 测试还验证重新分配 Session ID/System Bytes 并获得新 Secondary。它证明
-当前工具组合边界，不代表设备命令安全性或 SEMI 一致性认证。
+当前工具组合边界，不代表设备命令安全性或 SEMI 一致性认证。诊断信封另有
+黄金向量、可选字段往返、严格枚举/十六进制、资源限制及异常/帧内容不泄漏
+测试。