录制信号解码¶

decode_signal_recording 回答的是所选协议解码器在现有录制中观察到了什么。它使用调用者提供的 sigrok-cli 0.7.2 以及 Linux 上的 libsigrokdecode。需要 util-linux prlimit（默认为 /usr/bin/prlimit，可通过绝对路径 REA_SIGROK_PRLIMIT_COMMAND 覆盖）。限制器会在解码器启动前设置软、硬地址空间限制。macOS 和 Windows 会被拒绝，因为此适配器无法在这些主机上强制执行该限制。它不采集样本，也不与硬件通信。

export REA_SIGROK_COMMAND=/absolute/path/to/sigrok-cli
rea decode-signal-recording /artifacts/uart.vcd \
  --decoders uart:rx=RX:baudrate=9600 --input_format vcd \
  --annotations uart=rx-data --format json

对应的 MCP 请求为：

{
  "name": "decode_signal_recording",
  "arguments": {
    "path": "/artifacts/uart.vcd",
    "decoders": "uart:rx=RX:baudrate=9600",
    "input_format": "vcd",
    "annotations": "uart=rx-data"
  }
}

decoders 使用 sigrok 的解码器堆栈以及选项/通道语法。通道名称必须与录制匹配；REA 不会猜测接线、波特率或协议。每个选定的解码器通道都需要一个目标，例如 uart:rx=RX；单独的通道键（如 uart:rx）缺少该目标。当 sigrok 报告所选通道目标缺失或未知时，即使 sigrok 继续使用回退注释并成功退出，REA 也会针对 decoders 返回 invalid_request。诊断信息和任何部分 stdout 会保留在 captured_output 中；无关的生产者警告不会改变请求状态。

省略 input_format 会请求 sigrok 自动检测。REA 使用一个不可变的私有副本，其文件名保留所选录制的最终后缀，包括诸如 .csv 的点文件基本名称。基于文件名的格式检测会获得该提示，而不会将调用者的目录暴露给 sigrok。输入操作数是私有工作空间内的显式相对路径，因此名为 - 的录制会作为文件打开，而不是作为 sigrok 的标准输入操作数。省略 annotations 会保留所有注释类别。两项省略的选择都会记录为 null。

如果 sigrok 将显式选择的输入格式报告为未知，REA 会针对 input_format 返回 invalid_request，保留生产者诊断信息，并建议修正格式或将其省略以进行自动检测。标记选项解析器 会在选项键未知时发出警告。当该诊断的键与所选 input_format 选项完全匹配时，即使退出码为零，REA 也会返回 invalid_request。回退输出和诊断信息保留在 captured_output 中；无关的选项警告保持可见，但不会拒绝请求。匹配会保留完整的诊断标题，包括所选键内的 LF；嵌入的警告子字符串不会构成拒绝。一次已完成的非零 --version 探测属于配置拒绝，附带其捕获的输出以及所选的 sigrok/prlimit 配置指引。有关格式、解码器堆叠和注释选择器，请参阅上游手册。不接受任意命令行标志。

输出默认为 50 行以字面 LF 分隔的行。使用 line_offset 和 line_limit 获取后续页面，或使用 MCP line_limit: null / CLI --all_lines 获取全部剩余输出。output_window 报告 total_lines、returned_lines 和 has_more；这些计数的是显示行，不是注释或样本。所选窗口内的行尾、空行和文本保持不变。REA 不会将显示文本解析为协议事实，正如上游的注释输出指南所解释的那样。分页不会缩短解码过程，生产者输出仍必须满足其限制。使用注释类别选择来减少生产者输出。每次调用都会独立检查源摘要；不要将不同摘要的页面组合在一起。

每个选择器限制为 8,192 个 UTF-16 代码单元，启动前编码后的选择器参数（UTF-8、选项前缀、终止符和 64 位 argv 指针）总量限制为 32 KiB。这为 Linux execve 的最低参数/环境预算保留了余量；但大型继承环境仍可能将其耗尽。

返回的 Evidence 包含输入路径/摘要、确切选择、已配置和已解析的工具路径/摘要、完整版本横幅（包括库版本）、带样本编号范围的注释文本以及 stderr。例如，1104-1938 uart-1: 52 是样本范围上的生产者显示文本，不是时间戳，也不是经独立验证的协议事实。有效的 UTF-8 文本会逐字保留；不会将其解析为无损二进制负载。如果任何 sigrok stdout 或 stderr 流不是有效的 UTF-8，REA 将返回 unreadable_output，在 captured_output 中提供替换解码后的文本，并在 details.diagnostics.invalid_utf8_streams 中指明受影响的流。它不会将该文本报告为成功的 Evidence。有效的字面替换字符仍是普通的生产者文本。空输出并不表明不存在流量。即使 sigrok 以零退出，警告仍然可见，包括单独版本探测中的 tool.version_diagnostics。运行后的身份校验失败会指明所涉及的工具、限制器或私有副本，而不是归咎于已被认可的来源。资源信号失败会保留信号和有效限制，而不推断其确切原因。

REA 解码录制的私有只读副本，在解码后验证该副本以及所选可执行文件和资源限制器，并在所属进程清理后移除工作区。描述符、进程或工作区清理失败时会保留所有权以供重试，一次性 CLI 会等待重试，而不会替换原始失败或已完成的 Evidence。已完成的观察结果在取消或清理失败后仍保留在 MCP 会话中；有界运行后完整性检查会在响应用户的延迟中止之前完成。源文件永远不会传给 sigrok。调用者提供的工具及其库/解码器模块是受信任的，哈希标识的是字节，而不是发布者真实性。

输入副本在读取前被限制为 32 MiB，每条命令有 30 秒的截止时间，收集期间合并的 stdout/stderr 被限制为 4 MiB。过大的输出会失败，而不会变为“截断的成功”。这些限制并不构成操作系统沙箱。执行前，prlimit 强制执行每个进程 1 GiB 地址空间、每个文件 64 MiB、30 CPU 秒，并禁止核心转储。更严格的继承软/硬限制会被保留；Evidence 记录有效的上限。软限制和硬限制都在执行前设置，因此解码器分配和压缩录制展开不能超过每进程地址空间上限。这些不是聚合的进程内存或文件系统配额。所选限制器是受信任的，其路径、摘要和参数会保留在 Evidence 中。

验证¶

npm run build:cached
REA_SIGROK_COMMAND=/absolute/path/to/sigrok-cli node scripts/verify-signal-recording.mjs

验证器合成一个携带 REA 的 9600 波特 8N1 UART VCD，然后检查实际的 CLI/MCP 一致性、公告的 schema、存储的 Evidence、源哈希、注解过滤/自动检测、无效解码器/输入失败、缺失通道拒绝并保留部分输出，以及清理。一个可选的位置参数 REA 入口点可验证已安装的包。真实工具通道需要 Linux、sigrok-cli 0.7.2 和 libsigrokdecode。一个单独的内核限制回归测试检查继承的软/硬限制，并验证过大的分配会在消耗内存之前被拒绝。其他格式、解码器和物理采集并未由 UART 测试夹具所确立。在声称某个特定 Linux 构建已通过验证之前，必须检查工作流结果。较早的 macOS 工具检查并不确立当前的受限集成，该集成有意拒绝不受支持的主机。

一次只准入一个解码，包括采集和清理。多余的请求在获取另一个文件或工作进程之前会收到可重试的容量错误。关闭时停止准入并排空已接受的工作；失败的清理仍保持所属关系，且可重试。

在选择设置前发现解码器¶

inspect_signal_decoders / inspect-signal-decoders 查询已安装的 sigrok 目录，而无需打开录制或扫描设备：

rea inspect-signal-decoders --query uart
rea inspect-signal-decoders --decoder uart --query baud
rea inspect-signal-decoders --decoder i2c --offset 0 --limit 50

省略 decoder 可搜索解码器 ID 和名称。提供单个精确的解码器 ID 可读取其字面帮助，包括必需/可选通道、选项、注解类别和文档。query 是大小写不敏感的字面子串；匹配到的帮助保留原始的从 1 开始的行号。空查询选择全部。offset 跳过匹配项；limit 默认为 50。MCP limit: null 或 CLI --all 返回所有剩余匹配项；CLI --all 和 --limit 冲突。该窗口报告已检查、匹配和返回的记录以及 has_more。过滤后的空页面并不能证明安装中没有解码器。当 sigrok 报告所选的解码器 ID 未安装时，帮助和解码会返回 invalid_request，其中指明 decoder 或 decoders；省略 decoder 可列出已安装的 ID。已安装但加载失败的解码器仍属于执行失败。

发现功能在构造记录对象之前拒绝超过 65,535 个行分隔符（65,536 行的表示预算），此外还有 4 MiB 输出上限。超出该预算是资源失败，带有捕获的输出。返回的文本会被复制，因此保留的页面不会使完整的生产者输出保持存活。

发现功能与解码共享其拥有的进程、准入槽、资源限制、清理重试和 Evidence 传递。它记录可执行文件和限制器的身份、版本横幅和警告。版本检查失败和格式错误的生产者输出会保留诊断信息。目录名称、帮助行和版本输出遵循解码的 UTF-8 处理方式：格式错误的流会产生 unreadable_output 错误，并带有替换解码后的捕获文本，受影响的流在 details.diagnostics.invalid_utf8_streams 中标识。帮助是生产者文本，不是独立验证的参数 schema。每个请求都会重新探测；它不会缓存，也不会声称页面在安装变更后保持稳定。库/解码器模块仍是受信任的，并且不会被完全指纹识别。目录输出包括其可执行文件的 SHA-256，而不是完整安装的摘要。