观测：事实投影与外发通道

会话记录支撑历史查询与投影，包属运行检查观察独立事实。遥测在获准后复制规范记录，经部署脱敏规则交给独立报告通道；交接和导出都不替代会话持久化。

规范事实、包属检查与获准遥测

箭头表示标注的调用或依赖关系；点击组件定位正文。完整关系见下方文字说明。

文字关系说明与章节链接

规范 Session 记录 →（折叠已提交事件）→ 会话查询投影；规范 Session 记录 →（获准后复制前缀）→ 遥测捕获协调器；遥测捕获协调器 →（外发记录副本）→ 部署脱敏扩展；部署脱敏扩展 →（转换后交接）→ 会话遥测适配后端；会话遥测适配后端 →（创建并使用通道）→ 独立 OTel 日志通道；包属事件与可变数据 →（观察所属关系）→ 不变量注册器与检查。

规范 Session 记录 · 会话查询投影 · 包属事件与可变数据 · 遥测捕获协调器 · 部署脱敏扩展 · 不变量注册器与检查 · 会话遥测适配后端 · 独立 OTel 日志通道

会话事实派生查询与投影

Session 记录包含已接纳输入、已结算输出、重试安排和工具结果等事实，投影把它们变成统计与回合轮廓。实时流用于展示正在生成的片段，不能替代结算后的记录。

排查读文件任务时，先判断请求是否接纳、工具是否返回、模型是否结算以及检查点是否成功，比只看界面最后一行更精确。恢复与查询沿同一记录解释历史，也减少不同查询结果之间的状态不一致。

包属检查观察运行关系

dsh-invariants 为包提供运行时检查注册与选择机制。配置按准确包名和允许、阻止正则决定启用范围，非法配置与重复注册会失败；异常带包归属，便于定位责任方。

dsh-invariants · 接口摘录，省略上下文 · ctx.invariants.register · docs/subsystems/invariants.md

// 为准确包名注册运行检查，子 fiber 生命周期绑定注册与插件。
register(packageName: string, installer: InvariantInstaller): () => void

检查通过子 fiber 注入并随生命周期释放。这里依据固定版本说明其注册机制，不把某一时期对所有包伴生文件的编写要求推广成永久规则；检查能发现已声明关系的破坏，不等于覆盖所有业务正确性。

获准捕获后转换外发副本

dsh-session-telemetry 负责规范捕获、脱敏和游标，session-telemetry-otel 将记录交给配置的报告后端。ledger 表达记录事实，ops 表达运行观察，瞬时流不进入同等持久账目，请求正文也不是默认报告内容。

dsh-session-telemetry · 接口摘录，省略上下文 · session-telemetry/record · docs/subsystems/session-telemetry.md · ctx.sessionTelemetry.emit · docs/subsystems/session-telemetry.md

// 外发记录的同步脱敏瀑布，仅改导出副本，异常时扣留该记录。
'session-telemetry/record'(record: SessionTelemetryRecord, next: () => SessionTelemetryRecord): SessionTelemetryRecord

// 向报告后端交接脱敏记录；调用完成不表示远端已经收到。
abstract emit(record: SessionTelemetryRecord): void

分享模式表达允许披露的范围，不能作为已发送回执。固定版本后端请求上限为四百万字节，交接后仍可能丢失或重复，接收端可按 session.id、format_version 与 event.seq 对账目去重。

独立报告通道与格式演进

dsh-otel 提供报告器工厂，仅挂载服务不会自动创建队列、网络连接或身份；普通产品与会话通道彼此独立，由消费者配置捕获策略、连接和关闭。

dsh-otel · 接口摘录，省略上下文 · ctx.otel.createSessionLogReporter · docs/subsystems/otel.md

// 创建独立且有字节上限的会话报告通道，由消费者负责关闭。
createSessionLogReporter(options: SessionLogOptions): SessionLogReporter

会话格式则由 session-format 与相邻迁移包处理，不能用遥测字段变化来解释日志可读性。插件和配置的演进还要遵守注册撤销、已发布格式和请求可重建等既有义务，观察工具应揭示这些变化，不得补写未发生的事件。

辅助示例

构建后的总结迟迟没有出现：Session 中可先确认工具已结束，再查看是否记录 llm/retry 与下一次尝试；运行时检查可能指出某个插件关系异常，遥测可能帮助汇总故障分布。即使本地已交接遥测，仍不能宣布远端分析平台已收到全部事件，更不能依靠它恢复尚未结算的输出。

设计取舍

把事实记录、运行检查和外发观测分开，既能支持本地恢复，也能控制外发内容与成本；代价是诊断需要对照持久性与完整性保证不同的多类数据。最佳努力遥测适合观察趋势与辅助排错，严格恢复仍应依赖负责持久数据的组件和明确的提交状态。

观测：事实投影与外发通道 ​

会话事实派生查询与投影 ​

包属检查观察运行关系 ​

获准捕获后转换外发副本 ​

独立报告通道与格式演进 ​