feat: implement scope generic extensions R1.3

README.md

@@ -7,7 +7,7 @@
 
 WaveBench 是一个用 Python 编写的实验室自动测量台，面向电子设计竞赛调试和日常实验。它把仪器控制、实验步骤和采集证据放在同一条命令链中，支持先离线检查 plan，再决定是否连接硬件。
 
-当前仓库开发线为 `0.8.22`，最新稳定 tag 为 `v0.8.0`。不同版本的命令和能力可能不同，以对应 tag 中的文档为准。
+当前仓库开发线为 `0.8.23`，最新稳定 tag 为 `v0.8.0`。不同版本的命令和能力可能不同，以对应 tag 中的文档为准。
 
 ## 🌟 特别鸣谢
 

docs/project/contributing/WaveBench_插件开发指南.md

@@ -130,6 +130,23 @@ capability 名必须与 `kind` 同前缀。例如 scope 只能声明 `scope.*`
 
 多通道 scope 如声明 `scope.capture_waveforms`，必须先配置全部通道，只执行一次 acquisition 和 OPC 等待，再逐通道读取。不得退化为每个通道独立触发。
 
+### 采用 scope R1.3 扩展
+
+准备实现截图、采集控制或 typed trace 时，先阅读
+[scope 通用扩展接口 RFC](../rfcs/WaveBench_scope通用扩展接口RFC.md)和
+[核心实施说明](../rfcs/WaveBench_scope通用扩展接口RFC_核心实施说明.md)。采用条件如下：
+
+- wheel 依赖和 descriptor 均要求 WaveBench `0.8.23` 或更高的 `0.8.x` 版本；
+- 从 `wavebench.instruments` 导入公共 Protocol、model 和 `ScopeDescriptorExtensions`；
+- descriptor 提供 capability 对应的静态 profile；
+- driver 实现 snapshot、baseline、restore 和 fresh verify，不把 session token 暴露给插件代码；
+- `CHDR`、`CORD`、`WFSU` 等临时 transfer 设置逐字段映射、恢复和核对；
+- binary framing 与具体 resource/backend 的 EOM 能力一致，不能用短读、换行或 timeout 猜测边界；
+- fake conformance、包检查和实机验收分别通过后，再修改正式 descriptor。
+
+未采用新增 capability 的旧插件不需要提高核心版本下限。旧 `scope capture --screenshot` 不承载
+新 `scope.screenshot_v2`；新插件应使用独立截图 Service 或 `wavebench scope screenshot capture`。
+
 ## 配置 options
 
 插件私有配置放在对应的 `[<kind>.options]` 表中，并为每个键定义 `OptionSpec`。适合 `OptionSpec` 的内容包括分块点数、插件专用超时和明确枚举；resource、backend、通用 timeout、安全限制和输出状态仍由核心配置管理。

docs/project/reference/WaveBench_数据输出格式.md

@@ -783,3 +783,43 @@ correction_limited,slope_limited
 - 曲面矩阵只来自 CSV 已有节点。`failed` 点写为缺失值并留洞，绝不补点或域外外推；圆点才表示真实采样。`warning` 点和成功自动恢复点使用独立标记，hover 保留首次 warning、重试次数、首次与最终采集路径。
 - 单幅值或不足 2 × 2 的 response 不生成伪曲面，只保留静态 Bode 图。缺少 `report3d` extra 时报告仍能生成，并显示安装提示。
 - 移动 `report.html` 时必须同时携带同级 `report-assets/`。PDF compact 路径完全不加载 Plotly，继续作为单文件静态视觉归档。
+
+## Scope R1.3 操作产物
+
+`wavebench scope screenshot capture` 和 `wavebench scope trace fetch` 分别写入显式指定的 PNG/NPY
+文件，并写入一个 JSON artifact。默认 artifact 路径是在二进制输出路径后追加 `.json`；已有文件
+不会被覆盖。
+
+Service 结果 schema 固定为：
+
+```json
+{
+  "schema": "wavebench.scope.result.v1",
+  "result": {},
+  "diagnostics": {
+    "schema": "wavebench.scope.operation.v1",
+    "schema_version": 1
+  },
+  "observed_state": null,
+  "files": {}
+}
+```
+
+`result` 只保存可审计摘要：
+
+- screenshot 保存媒体类型、尺寸、请求与实际请求、framing、payload 字节数和 SHA-256；
+- trace 保存 typed metadata、点数、dtype、payload 字节数和 SHA-256；其中摘要对象是按 C order
+  排列的数组原始字节，不是 `.npy` 容器文件；
+- acquisition 保存类型化运行状态或完成证据。
+
+`diagnostics` 保存 correlation、context、session epoch、UTC 时间、deadline 来源、phase、binary
+budget 摘要、baseline nonce 摘要、恢复、fresh verify、error policy 和最终 session health。原始图片、
+波形数组、完整命令、resource 和 baseline nonce 不写入 JSON artifact。`files` 在持久化 artifact
+中只保存文件名；CLI 当前结果可以显示调用方提供的完整路径。
+
+PNG/NPY 写入失败或 artifact 写入失败都必须按失败处理。CLI 目前不使用覆盖选项；需要重跑时应
+选择新的输出路径或先由人工处理旧文件。Service 已产生结构化 operation diagnostics 后失败时，
+CLI 仍会在请求的 artifact 路径写入 `status = "failed"`、安全错误 envelope 和恢复证据；不会创建
+伪成功的 PNG/NPY。artifact 自身无法写入时，CLI 删除本轮刚生成的 PNG/NPY，并在错误结果中
+报告 `scope_artifact.reason_code = "write_failed"`；若部分输出无法删除，还会报告
+`scope_output.reason_code = "remove_failed"`。

docs/project/reference/plugins/WaveBench_可执行仪器插件API.md

@@ -139,6 +139,7 @@ def descriptor() -> InstrumentDescriptor:
 | `distribution`、`version`、`source`、`origin` | entry point 加载后由 registry 按已安装分发覆盖 | 不得用于插件内部授权、信任或功能分支 |
 | `scope_coupling_policy` | 值由类型约定为三种策略 | scope 必须准确声明；无法证明时使用 `unknown`，核心会默认拒绝无法确认高阻的采集 |
 | `config_fields` | 当前只展示；为空时由 `option_specs` 推导 `options.<name>` | 只列出用户实际可配置的字段，不代表核心会按此字段授权 |
+| `scope_extensions` | 仅允许 scope descriptor 使用，类型必须为 `ScopeDescriptorExtensions` | 为 R1.3 capability 提供静态截图、采集控制和 trace profile；旧插件保持 `None` |
 
 ### `scope_coupling_policy`
 
@@ -236,7 +237,10 @@ factory 必须同步返回，不得返回 coroutine、context manager 或 `(driv
 
 capability 必须与 descriptor 的 `kind` 使用相同前缀。当前 V2 loader 会拒绝未知 capability，但不会单独拒绝「已知但前缀属于其他 kind」的组合；插件测试必须覆盖该项。
 
-方法签名以 [`contracts.py`](../../../../src/wavebench/instruments/contracts.py) 为准，返回对象以 [`models.py`](../../../../src/wavebench/instruments/models.py) 为准。当前 capability 到方法的映射如下。
+旧接口的方法签名以 [`contracts.py`](../../../../src/wavebench/instruments/contracts.py) 为准，返回
+对象以 [`models.py`](../../../../src/wavebench/instruments/models.py) 为准。Scope R1.3 的 Protocol
+和 model 由 [`scope_extensions.py`](../../../../src/wavebench/instruments/scope_extensions.py) 定义，
+并从 `wavebench.instruments` 导出。当前 capability 到方法的映射如下。
 
 ### Scope
 
@@ -261,9 +265,46 @@ capability 必须与 descriptor 的 `kind` 使用相同前缀。当前 V2 loader
 | `scope.fft_status` | `get_fft_status` |
 | `scope.reference_metadata` | `get_reference_waveform_metadata` |
 | `scope.cursor_readout` | `get_cursor_readout` |
+| `scope.screenshot_profile` | `get_screenshot_profile` |
+| `scope.screenshot_v2` | `get_screenshot_profile`、`capture_screenshot`、`snapshot_screenshot_state`、`restore_screenshot_state`、`verify_screenshot_state_restored` |
+| `scope.acquisition_run_state` | `get_acquisition_run_state` |
+| `scope.acquisition_control` | `get_acquisition_run_state`、`start_continuous`、`stop_acquisition`、`acquire_single`、`snapshot_acquisition_control`、`restore_acquisition_control`、`verify_acquisition_control_restored` |
+| `scope.trace_metadata` | `get_trace_metadata` |
+| `scope.fetch_trace` | `get_trace_metadata`、`fetch_trace`、`snapshot_trace_transfer_state`、`restore_trace_transfer_state`、`verify_trace_transfer_state_restored` |
+| `scope.error_drain_v1` | `drain_errors` |
 
 `scope.capture_waveforms` 的固定语义是：先配置全部目标通道，只执行一次 acquisition 和 OPC 等待，再逐通道读取。不得静默退回逐通道重复触发。回调、失败时部分结果和返回字典的签名以 `MultiChannelScopeDriver` 为准。
 
+### Scope R1.3 扩展
+
+R1.3 的 Protocol 和 model 从 `wavebench.instruments` 导出。声明任一新增 capability 时，wheel
+依赖和 descriptor 的 `wavebench_min_version` 都必须为 `0.8.23` 或更高的 `0.8.x` 版本。
+
+profile 依赖如下：
+
+| capability | 必需 descriptor profile |
+| --- | --- |
+| `scope.screenshot_profile`、`scope.screenshot_v2` | `scope_extensions.screenshot_profile` |
+| `scope.acquisition_control` | `scope_extensions.acquisition_control_profile` |
+| `scope.trace_metadata`、`scope.fetch_trace` | `scope_extensions.trace_profile` |
+
+`scope.acquisition_control` 还必须同时声明 `scope.acquisition_run_state`。缺少 profile、方法或核心
+版本门时，核心会拒绝 descriptor；只实现方法而不声明 capability，不会产生隐式能力。
+
+公共调用入口为 `ScopeService` 和以下 CLI：
+
+```text
+wavebench scope screenshot profile
+wavebench scope screenshot capture
+wavebench scope acquisition status|start|single|stop
+wavebench scope trace metadata|fetch
+```
+
+旧 `scope capture --screenshot` 继续服务声明 `scope.screenshot` 的插件。插件同时声明旧能力
+和 `scope.screenshot_v2` 时，旧命令仍走 legacy 路径；只有 v2、没有旧能力时，核心会在仪器
+I/O 前拒绝嵌入请求。需要 v2 截图时使用独立的 `scope screenshot capture`。父 capture 字段
+闭包在后续实现前不得由插件自行模拟。
+
 ### Source
 
 | capability | 必须可调用的方法 |

docs/project/rfcs/README.md

@@ -12,3 +12,6 @@ RFC 使用以下状态：
 ## 当前 RFC
 
 - [transport 重放与 session 健康 RFC](WaveBench_transport重放与session健康RFC.md)：定义查询重放、结构化传输错误、共享 session 健康状态、恢复授权和版本迁移。
+- [scope 通用扩展接口 RFC](WaveBench_scope通用扩展接口RFC.md)：`Accepted R1.3`，定义 operation context、binary budget、截图、采集控制、trace、错误策略及恢复验证合同。公共合同已进入核心 `0.8.23` 开发线；插件按 capability 单独 opt-in。
+- [scope 通用扩展接口 RFC：R1.3 Acceptance Addendum A1](WaveBench_scope通用扩展接口RFC-R1.3-acceptance-addendum.md)：记录公共 capability 注册采用的 P0/P1 验收门和离线完成证据。
+- [scope 通用扩展接口 RFC：核心实施说明](WaveBench_scope通用扩展接口RFC_核心实施说明.md)：记录 backend、公共 Service/CLI、artifact、版本门、旧 capture 分流和插件迁移边界。

docs/project/rfcs/WaveBench_scope通用扩展接口RFC-R1.3-acceptance-addendum.md

@@ -0,0 +1,79 @@
+# WaveBench scope 通用扩展接口 RFC：R1.3 Acceptance Addendum A1
+
+> 状态：`Accepted`（核心 `0.8.23` 开发线已通过离线 A1 门）
+> 适用正文：[WaveBench scope 通用扩展接口 RFC](WaveBench_scope通用扩展接口RFC.md)
+> 目的：记录从内部基础设施到公共 capability 注册的验收门和完成证据
+> 同步来源：WaveBench Instrument Plugins `a013891`
+
+本文件是总 RFC 第十二节的可单独审阅索引，不是第二套并行合同。字段、Protocol、数值和
+失败语义以总 RFC 为唯一事实源；本文件记录核心 `0.8.23` 开发线完成公共注册时采用的验收顺序。
+
+## 验收结果
+
+| 项目 | 结果 | 证据 |
+| --- | --- | --- |
+| P0/P1 核心 fixture | 通过 | `tests/test_scope_phase_coordinator.py`、`tests/test_scope_binary_contract.py`、`tests/test_scope_extension_service.py` |
+| 两类 backend wrapper | 通过 | PyVISA 与 RsInstrument 的 VISA `INSTR` definite-block/message EOM；SocketIO/serial 零发送拒绝 |
+| transfer、截图和采集 fixture | 通过 | 核心 fake fixture 与 SDS800X HD conformance fixture |
+| 公共接口 | 通过 | `ScopeDescriptorExtensions`、公共 capability/operation registry、`ScopeService`、CLI、artifact schema、`0.8.23` 版本门 |
+| 旧插件兼容 | 通过 | DS1000Z、RTM2000、SDS800X HD 离线插件测试；未声明新 capability 的 descriptor 行为不变 |
+| SDS3000 迁移审计 | 插件侧待同步 | 运行相关测试通过；手工 capability 矩阵仍按旧核心 19 项记录，需更新为 26 项后再决定 opt-in 范围 |
+| 实机覆盖 | 不属于离线 A1 结论 | 每个准备 opt-in 的插件仍需单独执行 resource/backend 和仪器状态恢复验收 |
+
+离线 A1 通过只允许核心发布合同和插件开始迁移，不表示某个型号已经通过新 capability 的实机
+验收。
+
+## 历史实施边界
+
+公共注册前，核心只允许实现下列私有或 feature-gated 组件：
+
+- operation context、非嵌套 phase coordinator 和跨 phase 不重置的 binary ledger；
+- acquisition、screenshot、transfer 的 typed snapshot / baseline / restore / verify 模型；
+- capability-method/descriptor gate、legacy artifact 和 fake/conformance fixture。
+
+## P0 门
+
+1. 核心必须实现 `ScopeTraceTransferRecoveryDriver`；`fetch_trace` 在 transfer 状态可能变化时必须
+   使用带 `context_id`、epoch、nonce 的 `ScopeTraceTransferBaseline`，并用 descriptor profile
+   的固定 restore order/step 上限完成逐字段 restore/verify；`CHDR`、`CORD`、`WFSU` 等字段
+   不得只靠文字承诺。
+2. 核心必须实现 `ScopeDescriptorExtensions`、`SCOPE_CAPABILITY_METHODS` 和 required Protocol；
+   缺 profile 或方法时在零 I/O 阶段拒绝，方法存在但未声明 capability 时不自动暴露。
+3. 核心固定并测试以下常量：
+
+   | operation | response / total / query / resync | default timeout |
+   | --- | --- | --- |
+   | `scope.screenshot_v2` | `262144 / 262144 / 1 / 0` | `5000 ms` |
+   | `scope.acquisition_start/single` | binary `—` | `30000 ms` |
+   | `scope.fetch_trace` | `8388608 / 67108864 / 256 / 65536` | `60000 ms` |
+
+   profile/connection 只能收紧；超出同步上限、无法证明边界或终止设置恢复失败时统一
+   close + `poisoned`。
+4. `OperationRequest.deadline`、`before_and_after` 默认 error timing、recovery `disabled`、
+   每次 I/O 的剩余 deadline 计算和 artifact 字段已有负向测试。
+
+## P1 门
+
+- 旧 capture 嵌入 screenshot 只采用父 operation 字段闭包；没有完整字段闭包则 I/O 前拒绝，
+  截图或恢复失败使父 capture 失败，不注册 composite operation。
+- screenshot、acquisition、transfer baseline 必须绑定 context、session epoch、opaque nonce，
+  按一次性消费状态拒绝重放。
+- `identity_delta` 只有在 `ScopeAcquisitionControlProfile.identity_semantics` 为
+  `unique_within_session_epoch` 时可用；否则只接受完整 state transition。
+- phase coordinator 必须通过现有 normal gate 与 recovery/verification authorization 的
+  非嵌套顺序桥接，driver 不接收 session token。
+- R1.3 公共 trace 只包含 analog/digital/reference；spectrum、math、fft_phase、frequency
+  axis 和新增单位移入后续 RFC。
+
+## 退出条件
+
+核心按以下条件决定是否注册 capability：
+
+1. P0/P1 fake/conformance fixture 全部通过；
+2. 至少两个独立仪器族或 backend 证明 transfer restore、binary framing 和失败恢复；
+3. Service、CLI、descriptor、registry、artifact schema 和版本门完成核心评审；
+4. 未决的 trace extensions、continuation 和 poisoned-session reopen 设计不被当前 capability
+   隐式引用。
+
+上述条件已在核心 `0.8.23` 开发线的离线验收中满足。插件现在可以准备迁移，但只有在插件自身
+conformance、包检查和实机验收通过后，才能在正式 descriptor 中声明对应 capability。