docs: establish plugin documentation and development workflows

.agents/skills/wavebench-plugin-development/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: wavebench-plugin-development
+description: >-
+  Develop, review, package, and validate production instrument plugins in the
+  wavebench-instrument-plugins monorepo. Use when work primarily changes a
+  vendor-manual audit for a concrete driver, plugin descriptor, driver, parser,
+  profile, tests, entry point, build metadata, package build or isolated
+  lifecycle validation, conformance manifest, hardware-evidence tooling, or
+  repository-wide plugin development scripts. Do not use for runtime plugin
+  installation or removal without repository changes, ordinary WaveBench
+  operation, WaveBench Core implementation, documentation-led work, or
+  unrelated VISA/SCPI projects.
+license: MIT
+metadata:
+  author: "WaveBench maintainers"
+  version: "1.1.0"
+  project: "wavebench-instrument-plugins"
+  specification: "https://agentskills.io/specification"
+---
+
+# WaveBench plugin development workflow
+
+## Core objective
+
+以可安装、可发现、可卸载、可离线验证且不意外接触仪器的状态交付 WaveBench 生产插件。新协议先完成本地手册整理和项目原创审计，再按 capability 做最小纵向切片，让包元数据、production descriptor、实现、测试与发行产物表达同一套事实。
+
+本流程面向 Codex 或兼容 Agent Skills 的宿主，仓库要求 Python 3.11+。验证使用已同步的 WaveBench 开发环境；实时仪器工作还需要明确授权、已确认接线和 Core 安全流程。
+
+## Invocation boundary
+
+仅在插件仓的生产交付物是主要任务时使用本 Skill，例如修改 `packages/wavebench-*` 下的 driver、descriptor、parser、profile、测试或打包配置，或者修改仓库级开发、目录生成、conformance 与实机证据工具。
+
+以下任务不属于本 Skill：
+
+- 只安装、配置、查询或操作现有 WaveBench 插件：交给 WaveBench 操作流程；宿主提供 `$wavebench` 时使用它。
+- 主要交付物是文档审计、信息架构或页面改写：交给文档工作流；宿主提供 `$wavebench-docs` 时使用它。
+- 修改 WaveBench Core 的公共模型、CLI 或运行时：在 Core 仓按 Core 开发流程处理。
+- 与本仓无关的 VISA、SCPI 或电子学任务。
+
+如果插件开发包含实时仪器验收，本 Skill 负责仓库代码、包、harness 和证据格式；实时授权、接线、写入、恢复与最终设备状态同时服从 WaveBench Core 安全合同。宿主提供 `$wavebench` 时同时加载；未提供时停止在离线阶段。
+
+## Start every task
+
+1. 用 `git rev-parse --show-toplevel` 确认位于 `wavebench-instrument-plugins` 根目录，并执行 `git status --short --branch`。保留无关用户改动，禁止隐式清理、reset 或覆盖。
+2. 将任务归为新驱动／新协议、离线评审、离线代码修改、包与生命周期、只读实机证据或受控实机写入。默认只做离线工作。
+3. 新驱动、新型号、新命令或新 capability 先检查本地厂商资料与项目原创审计；普通 bug 修复只复核受影响协议范围。随后读取包的 `pyproject.toml`、production descriptor、实现入口和聚焦测试。
+4. 涉及 Core 类型或语义时，先判断现有 kind、capability 和消费路径能否完整表达；不能表达时按跨仓合同流程处理，不在插件内复制公共接口。
+5. 若仓库有 `.codegraph/`，先用 CodeGraph 定位符号、调用方和测试，再完整读取即将修改的文件。
+6. 安装依赖、同步 `.venv`、构建发行产物、合并 `main` 或连接仪器前，说明影响范围、预期结果和停止条件。
+
+## Risk classes
+
+| 类别 | 典型操作 | 默认处理 |
+| --- | --- | --- |
+| 离线评审 | 检查 descriptor、parser、测试、diff | 可直接进行，不加载插件、不连接仪器 |
+| 离线代码 | driver、profile、FakeTransport、仓库脚本 | 先跑聚焦测试，再扩大验证范围 |
+| 包与生命周期 | metadata、entry point、wheel、sdist、安装和卸载 | 使用隔离环境，检查发现、导入和卸载回退 |
+| 实机证据 | conformance、只读查询、受控写入 | 需要单独授权；先过离线门禁和 Core 安全门禁 |
+
+## Non-negotiable contracts
+
+- 包内 `pyproject.toml` 与 production descriptor 是版本、entry point、兼容范围、型号和 capability 的权威来源。生成式目录只能读取并呈现这些事实。
+- 厂商手册原件和转换结果只放在被忽略且不进入 sdist 的 `doc/vendor-local/`；提交项目原创的手册基线、协议审计和 capability 处置，不提交或复制厂商原文。
+- Identity-first 是强制门禁：正式 descriptor 必须先声明 `<kind>.idn`。允许 manual-backed identity；实机证据单独记录，不能由手册推断为 hardware-verified。
+- entry point、`driver_id`、distribution、version 与 `source` 必须一致；一个包可以有多个用途明确的 production entry point，不能假定所有包只有一个。
+- descriptor 模块导入和 `descriptor()` 调用不得扫描资源、打开 transport、执行协议命令或读写文件。仪器 I/O 只能在 factory 通过 `DriverContext.open_transport()` 开始。
+- 方法存在、README、milestone、测试草案或历史证据都不能单独提升 production capability。声明前必须核对 Core 合同、生产实现、profile、安全语义和与风险匹配的验证。
+- 手册明确、Core 合同完整且离线测试通过的 capability 可以在尚无实机证据时声明，但必须明确标记 manual-backed／hardware-not-verified，不得声称物理效果、精度或固件行为已经验证。
+- 测试默认使用 FakeTransport 或等价离线替身。禁止用真实实验室地址、串口、序列号、凭据、原始波形、截图或命令日志填充跟踪文件或发行产物。
+- 不盲目重试写入、触发、采集或结果不明的操作。未知写入结果必须 fail closed，并由 latch、停止策略或上层恢复合同处理，同时覆盖测试。
+- 不假定所有包拥有相同的 conformance、恢复、wheel 内容或发布流程。先检查当前包已有合同和测试。
+- 各插件独立版本。只有 wheel 内容或安装合同发生变化的包才在合并前提升自身版本，其他包不联动。
+- 合并到 `main` 即视为本仓发布；不要求 Git tag、GitHub Release 或 PyPI。合并和 push 仍需要用户授权，验证通过不能自动扩大权限。
+
+## Load only the relevant reference
+
+触发 Skill 后只读取与当前任务匹配的文件：
+
+| 任务 | 追加读取 |
+| --- | --- |
+| 从厂商手册准备新驱动、新型号／协议／capability，或处理 Core 缺口与全新仪器类型 | 先读 [instrument-driver-workflow.md](references/instrument-driver-workflow.md) |
+| 已进入正式包、descriptor、entry point、兼容范围或 capability 准入 | [repository-contract.md](references/repository-contract.md) |
+| 已开始 driver、parser、profile、测试、修复、重构或代码评审 | [development-validation.md](references/development-validation.md) |
+| 已进入 editable 环境、metadata、wheel、sdist、安装或卸载阶段 | [packaging-and-lifecycle.md](references/packaging-and-lifecycle.md) |
+| 已进入 conformance、实机 harness、证据升级、隐私或恢复阶段 | [conformance-and-hardware-evidence.md](references/conformance-and-hardware-evidence.md) |
+| Skill 本身的维护或触发回归 | [eval-prompts.md](references/eval-prompts.md) |
+
+多阶段任务只加载当前阶段的 reference，通过退出门后再加载下一阶段；不能因为最终可能涉及打包或实机就预加载全部文件。Reference 只从本入口直接链接，保持一层目录。普通 driver 修改不预加载打包或实机章节，非 Skill 维护不读取 eval。
+
+## Baseline validation
+
+按改动风险逐层增加验证，不把全仓测试当作每次修改的起点：
+
+```bash
+python3 scripts/dev_env.py check
+.venv/bin/python -m pytest -q packages/<package>/tests/<focused-test>.py
+.venv/bin/python -m ruff check <changed-paths>
+python scripts/generate_plugin_catalog.py --check
+.venv/bin/python -m wavebench plugin package check packages/<package>
+git diff --check
+```
+
+只运行与改动相关的命令。metadata、descriptor 或正式包集合变化后，开发环境和生成式目录可能需要更新；先按对应 reference 核对，不能把旧 `.venv` 的通过结果当作当前源码的证明。
+
+## Handoff
+
+交接先说明生产行为是否完成，再列出：改动包和 entry point、运行的离线测试与结果、生成或检查的发行产物、跳过或失败的门禁、Core 兼容假设，以及是否改动虚拟环境、本地配置或真实仪器。若接触过硬件，还必须记录最终设备状态、未恢复设置和证据位置。

.agents/skills/wavebench-plugin-development/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "WaveBench Plugin Development"
+  short_description: "开发、验证、打包并安全验收 WaveBench 仪器插件生产代码"
+  default_prompt: "使用 $wavebench-plugin-development 按仓库合同开发或审查仪器插件，并运行与风险匹配的离线验证。"
+
+policy:
+  allow_implicit_invocation: true

.agents/skills/wavebench-plugin-development/references/conformance-and-hardware-evidence.md

@@ -0,0 +1,81 @@
+# Conformance and hardware evidence
+
+在修改 conformance manifest、实机验收 harness、证据升级规则、脱敏、恢复或安全写入时读取本页。本页不授权连接仪器。
+
+## Evidence levels
+
+根据 capability 风险与现有 Core 合同选择证据，不把所有包强制套进同一层级：
+
+| 级别 | 证明内容 | 默认环境 |
+| --- | --- | --- |
+| 静态合同 | metadata、descriptor、profile 与 Core 类型一致 | 纯离线 |
+| 离线行为 | FakeTransport、parser、失败和恢复请求符合合同 | 纯离线 |
+| 查询证据 | 型号、固件、transport 下的只读行为 | 明确授权的实机只读 |
+| 受控写入 | 输出、配置、触发或采集及其读回和恢复 | 明确授权的受控实机 |
+| 量值证据 | 外部仪器观测、误差与适用条件 | 经确认接线和量程的实机 |
+
+只有 Core 合同或当前包的 promotion gate 要求时才生成正式 conformance。Acceptance、诊断日志和历史记录各有用途，不能因为存在一份实机文件就提升 production capability。
+
+## Before live work
+
+实时操作必须另有明确授权，并服从 WaveBench Core 的安全与恢复规则。宿主提供 `$wavebench` 时同时加载；未提供时停止在离线阶段并报告依赖。开始前：
+
+1. 确认目标型号、资源、固件、transport、当前接线、负载／终端和允许的写入范围。
+2. 先完成静态、FakeTransport、包检查和 harness 离线测试。
+3. 找到当前包已有的 evidence 工具、setup template、测试和记录格式；禁止临时拼接裸 SCPI 代替受审阅 harness。
+4. 确认初始输出、保护、耦合、量程和 session 状态，并定义失败时立即停止的条件。
+5. 明确哪些状态可恢复、哪些不可回读或不可恢复，以及最终必须验证的安全状态。
+
+任何信息不清楚时停止在离线阶段，不猜测实验室资源或仪器状态。
+
+## Harness contract
+
+实机 harness 应把安全合同做成可离线测试的代码：
+
+- setup 采用严格 schema，拒绝未知字段、越界值和示例占位符。
+- 默认诊断模式不写入；写入模式需要显式开关和独立确认。
+- 使用 WaveBench lease、session、driver 和 capability gate，不绕过为裸 transport 命令串。
+- 在写前记录必要快照，并为每次 query、write、trigger、capture 设置硬上限。
+- 不盲目重试。写入结果不明时停止后续操作，锁停受影响输出，并按 Core 合同请求恢复。
+- 恢复后新建或重新确认 session，实际读回输出和关键状态；进程退出码不代表设备已安全。
+- 即使证据序列化、审计或关闭失败，也优先执行确定性的安全停止路径。
+
+离线测试必须覆盖初始状态拒绝、未知写入结果、恢复失败、额外 I/O、超限、脱敏和 session 关闭。
+
+## Evidence privacy and scope
+
+正式证据只保留审计所需最小信息，并限定：
+
+- 插件 distribution 与版本、driver ID、descriptor digest 或既有 binding。
+- 经脱敏的型号、固件范围与 transport 类别。
+- capability、操作模式、条件、预期、观察结果和失败代码。
+- harness 版本、时间和适用的 Core 合同版本。
+
+禁止写入仓库或发行物：真实 IP、串口、VISA resource、序列号、账户与 token、未脱敏 IDN、原始波形、截图、完整 SCPI transcript 和本地文件路径。示例使用保留地址或明确的占位值。
+
+文件权限、证据目录和保留策略按当前 harness 既有合同执行。某个包要求私有 `0600` 文件不代表所有 conformance manifest 都采用相同权限。
+
+## Promotion gate
+
+准备把实验证据用于 production capability 前逐项确认：
+
+1. production driver 和 descriptor 已实现待验证合同，harness 没有临时扩充 descriptor 来伪造当前能力。
+2. 证据与实际 wheel、descriptor 和 Core 版本绑定，digest 由既有工具生成并验证。
+3. 适用型号、固件、transport、接线和限制足够具体，不外推到未验证系列。
+4. 失败、恢复与最终状态都有证据，不只保存正常路径截图或日志。
+5. 包内测试验证 manifest schema、脱敏、binding 和发行物包含范围。
+6. 生成式目录从 production descriptor 得到 capability，而不是反向读取验收文档。
+
+证据不足时准确保留为 Experimental、Historical、unsupported 或 unavailable，不复制整个开发过程到用户 Reference。
+
+## Live completion report
+
+实时交接必须写明：
+
+- 实际访问的仪器类别、型号／固件范围与 transport 类别，不暴露私有标识。
+- 执行的 read、write、trigger 或 capture 范围和计数上限。
+- 初始状态、恢复动作、最终读回状态和不可恢复设置。
+- 证据文件位置、脱敏结果、绑定状态和失败代码。
+- 未运行、被拒绝或结果不明的步骤。
+
+只要最终安全状态没有读回确认，就不能把验收报告为完整通过。

.agents/skills/wavebench-plugin-development/references/development-validation.md

@@ -0,0 +1,100 @@
+# Development and validation
+
+在修改 driver、parser、profile、测试或仓库级开发代码，以及进行插件代码评审时读取本页。默认目标是用最小离线改动证明生产行为，不连接真实仪器。
+
+## Establish the local contract
+
+开始修改前只读取与任务直接相关的材料：
+
+1. 新驱动、新型号、新命令或新 capability 先读取项目原创的手册基线、协议审计和处置记录，再核对本地厂商原件的相关范围；普通 bug 修复只复核受影响命令。
+2. 受影响包的 `pyproject.toml`、production descriptor 和入口重导出。
+3. 即将修改的 driver、parser、profile 或工具，以及所有直接调用方。
+4. 聚焦测试、共享 fixture 和该包已有的 wheel／lifecycle 测试。
+5. 包 README 与 `doc/README*` 只用于找到型号边界和证据入口，不把其摘要当作源码合同。
+6. 涉及公共类型、capability 或恢复语义时，读取当前依赖范围对应的 WaveBench Core 模型与测试。
+
+不同仪器类型、厂商和包的实现并不统一。通道编号、单位、错误队列、二进制块、timeout、重试、状态恢复和多 entry point 行为都必须从当前包事实确认，不能从相邻包类推。
+
+## Minimal implementation loop
+
+1. 新协议先更新项目原创审计，固定手册依据、未知项、Core 映射和安全边界。
+2. 用现有失败测试、复现或明确合同固定问题边界。
+3. 在所有调用路径共享的最小正确位置修改；不为单一实现新增抽象层。
+4. 用 FakeTransport 或当前包已有替身验证准确命令、顺序、解析、边界和失败行为。
+5. 先运行聚焦测试，再运行包级测试；只有共享代码或仓库级工具受影响时才扩大到全仓。
+6. 检查 descriptor、metadata、生成内容、证据状态和公开摘要是否因行为变化而需要同步。
+
+不要为获得绿色测试而放宽生产限制、吞掉异常、增加盲目重试或让测试依赖实际实验室资源。
+
+## Driver and parser checks
+
+按适用范围检查：
+
+- 输入在发出 SCPI 前完成类型、范围、通道和枚举验证。
+- query 与 write 的确切格式、终止符、单位和顺序由 FakeTransport 断言。
+- parser 拒绝截断、缺字段、非有限数值、超大长度和设备错误，不静默猜测。
+- 二进制块同时限制单次读取、总点数、query 次数和操作总量；普通文本重试策略不得套用到 capture。
+- 有状态查询、错误队列读取、autoscale、fetch 或 screenshot 的副作用在合同和测试中明确。
+- 写入完成状态不明时不重放命令；返回 fail-closed 结果并保留上层恢复所需信息。
+- 会改变输出、保护、触发或采集状态的操作具备前置条件、读回验证和停止策略。
+- 厂商 quirk 留在型号实现或 profile，不泄漏成 Core 的通用假设。
+
+## FakeTransport coverage
+
+优先复用当前包 fixture。测试至少覆盖改动路径的：
+
+- 正常请求、精确响应解析和返回类型。
+- 边界值与非法参数在 I/O 前拒绝。
+- 设备错误、timeout、畸形响应和不完整二进制数据。
+- query／write 次数上限和不允许的额外命令。
+- 失败后状态、latch、恢复请求或 session 健康度。
+- descriptor/factory 分界：descriptor 加载为零 I/O，factory 才打开 transport。
+
+测试名称应描述可观察合同，不依赖实现内部行号或临时变量。
+
+## Validation ladder
+
+根据变更逐级运行，前一级失败时先停止并处理根因：
+
+```bash
+python3 scripts/dev_env.py check
+.venv/bin/python -m pytest -q packages/<package>/tests/<focused-test>.py
+.venv/bin/python -m pytest -q packages/<package>/tests
+.venv/bin/python -m ruff check <changed-paths>
+git diff --check
+```
+
+以下情况再扩大验证：
+
+- 修改共享仓库脚本、跨包约定或 Core 兼容处理：运行相关根测试，必要时运行全仓测试。
+- 修改 metadata、entry point、descriptor 或正式包集合：检查生成式目录和开发环境漂移，并执行 package check。
+- 修改构建包含范围、入口发现或卸载行为：执行实际 wheel／sdist 和隔离生命周期测试。
+- 修改 conformance 或实机 harness：先运行其全部离线测试，再考虑单独授权的实时验收。
+
+不要声称「全仓通过」，除非实际运行了全仓命令。报告精确命令、通过数量、跳过项和未运行门禁。
+
+## Diff review mode
+
+用户要求评审时只报告可操作问题，不直接修改。按优先级检查：
+
+1. 可能导致错误命令、危险输出、状态损坏、数据丢失或恢复失败的问题。
+2. descriptor 与 production 实现、metadata 或 Core 合同不一致。
+3. wheel、sdist、发现、升级和卸载回退缺口。
+4. 缺少会让错误逃逸的测试，尤其是失败、边界与零 I/O 导入测试。
+5. 私有资源、厂商资料或原始证据进入 Git 或发行物。
+
+每条 finding 给出文件和最小行范围、触发条件、实际影响与修复方向。没有 finding 时明确说明剩余测试或实机验证风险。
+
+## Documentation boundary
+
+为具体新驱动或 capability 整理本地厂商资料、手册基线、协议审计和处置记录属于本开发流程，并且必须先于相应代码。代码变更附带的短小 README 或 Reference 同步也属于本流程，但仍以源码事实为准。若主要任务变成全仓文档盘点、拆分、迁移或页面重写，切换到 `$wavebench-docs`；不要让生产开发 Skill 承担文档信息架构。
+
+## Completion report
+
+说明：
+
+- 哪个包、entry point 与生产行为发生变化。
+- 哪些测试证明正常与失败路径。
+- 是否同步 metadata、descriptor、目录或构建产物。
+- 哪些门禁因范围、依赖或授权未运行。
+- 是否访问网络、改动 `.venv`、本地配置或真实仪器。