firmwareloop 0.2.1__tar.gz → 0.3.0__tar.gz

{firmwareloop-0.2.1 → firmwareloop-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: firmwareloop
-Version: 0.2.1
+Version: 0.3.0
 Summary: AI Agent Firmware Development and Lab Automation Platform (Dual-Tier MCP Server)
 Author-email: WeilinZhang <19523330249@163.com>
 License: MIT
@@ -381,7 +381,7 @@ claude mcp remove --scope user agentic-hil
 ├── demo-firmware/    示例固件（CMake；宿主编译模拟 MCU，闭环验证载体）
 ├── demo-make/        示例固件（Make；构建测试载体）
 ├── docs/             DEPENDENCY_MATRIX / REUSE_PLAN / V0.0.2_GAP_VERIFICATION
-├── pyproject.toml    标准 Python 包配置与 CLI 入口声明 (v0.2.1)
+├── pyproject.toml    标准 Python 包配置与 CLI 入口声明 (v0.3.0)
 ├── .mcp.example.json 双层 MCP 配置模板（firmwareloop + agentic-hil）
 ├── AGENTS.md         通用智能体规范（Antigravity / Qoder / Cursor 等）
 ├── CLAUDE.md         Claude Code CLI 指南
@@ -391,7 +391,7 @@ claude mcp remove --scope user agentic-hil
 
 ---
 
-## 能力验证状态（v0.2.1）
+## 能力验证状态（v0.3.0）
 
 > 状态定义：`Implemented`（已实现）/ `Simulator Validated`（模拟验证）/
 > `Real Hardware Validated`（真机验证）/ `Experimental` / `Not Implemented`

{firmwareloop-0.2.1 → firmwareloop-0.3.0}/README.md

@@ -353,7 +353,7 @@ claude mcp remove --scope user agentic-hil
 ├── demo-firmware/    示例固件（CMake；宿主编译模拟 MCU，闭环验证载体）
 ├── demo-make/        示例固件（Make；构建测试载体）
 ├── docs/             DEPENDENCY_MATRIX / REUSE_PLAN / V0.0.2_GAP_VERIFICATION
-├── pyproject.toml    标准 Python 包配置与 CLI 入口声明 (v0.2.1)
+├── pyproject.toml    标准 Python 包配置与 CLI 入口声明 (v0.3.0)
 ├── .mcp.example.json 双层 MCP 配置模板（firmwareloop + agentic-hil）
 ├── AGENTS.md         通用智能体规范（Antigravity / Qoder / Cursor 等）
 ├── CLAUDE.md         Claude Code CLI 指南
@@ -363,7 +363,7 @@ claude mcp remove --scope user agentic-hil
 
 ---
 
-## 能力验证状态（v0.2.1）
+## 能力验证状态（v0.3.0）
 
 > 状态定义：`Implemented`（已实现）/ `Simulator Validated`（模拟验证）/
 > `Real Hardware Validated`（真机验证）/ `Experimental` / `Not Implemented`

{firmwareloop-0.2.1 → firmwareloop-0.3.0}/firmwareloop.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: firmwareloop
-Version: 0.2.1
+Version: 0.3.0
 Summary: AI Agent Firmware Development and Lab Automation Platform (Dual-Tier MCP Server)
 Author-email: WeilinZhang <19523330249@163.com>
 License: MIT
@@ -381,7 +381,7 @@ claude mcp remove --scope user agentic-hil
 ├── demo-firmware/    示例固件（CMake；宿主编译模拟 MCU，闭环验证载体）
 ├── demo-make/        示例固件（Make；构建测试载体）
 ├── docs/             DEPENDENCY_MATRIX / REUSE_PLAN / V0.0.2_GAP_VERIFICATION
-├── pyproject.toml    标准 Python 包配置与 CLI 入口声明 (v0.2.1)
+├── pyproject.toml    标准 Python 包配置与 CLI 入口声明 (v0.3.0)
 ├── .mcp.example.json 双层 MCP 配置模板（firmwareloop + agentic-hil）
 ├── AGENTS.md         通用智能体规范（Antigravity / Qoder / Cursor 等）
 ├── CLAUDE.md         Claude Code CLI 指南
@@ -391,7 +391,7 @@ claude mcp remove --scope user agentic-hil
 
 ---
 
-## 能力验证状态（v0.2.1）
+## 能力验证状态（v0.3.0）
 
 > 状态定义：`Implemented`（已实现）/ `Simulator Validated`（模拟验证）/
 > `Real Hardware Validated`（真机验证）/ `Experimental` / `Not Implemented`

{firmwareloop-0.2.1 → firmwareloop-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "firmwareloop"
-version = "0.2.1"
+version = "0.3.0"
 description = "AI Agent Firmware Development and Lab Automation Platform (Dual-Tier MCP Server)"
 readme = "README.md"
 authors = [

{firmwareloop-0.2.1 → firmwareloop-0.3.0}/tools/__init__.py

@@ -2,4 +2,4 @@
 FirmwareLoop - AI Agent Firmware Development and Lab Automation Platform.
 """
 
-__version__ = "0.2.1"
+__version__ = "0.3.0"

{firmwareloop-0.2.1 → firmwareloop-0.3.0}/tools/fw_mcp_server.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 """
-fw_mcp_server.py - FirmwareLoop High-Level Workflow & Device MCP Server (v0.2.1).
+fw_mcp_server.py - FirmwareLoop High-Level Workflow & Device MCP Server (v0.3.0).
 
 Exposes high-level firmware engineering and hardware management tools to AI Coding
 Agents (Antigravity CLI, Claude Code CLI, Qoder IDE, CodeBuddy IDE, Cursor) via the Model Context
@@ -360,6 +360,8 @@ def handle_fw_ndtdbg_stream(args: Dict[str, Any]) -> Dict[str, Any]:
         cmd.extend(["--fail-threshold", str(int(args["fail_threshold"]))])
     if args.get("require_target"):
         cmd.append("--require-target")
+    if args.get("pre_write"):
+        cmd.extend(["--pre-write", *[str(p) for p in args["pre_write"]]])
     _ndtdbg_reg_args(args, cmd)
     return _ndtdbg_run(cmd, timeout=int(duration_s) + 120)
 
@@ -1387,7 +1389,7 @@ TOOLS_REGISTRY = {
         "handler": handle_fw_ndtdbg_flash,
     },
     "fw_ndtdbg_stream": {
-        "description": "Stream-read a set of IIC registers from the NdtBox target chip (ChipSea Fxx) at a fixed interval via one long-lived USB session. Read-only. Writes CSV with timestamps; returns JSON summary (frames, FF_GAP/IO_FAIL counts, interval stats). For capturing sensor/debug data streams (e.g. PT488 0xEE 4-channel data). Typical combo: write_reg(0xBE=01, confirm) to start debug_mode, then stream(0xEE).",
+        "description": "Stream-read a set of IIC registers from the NdtBox target chip (ChipSea Fxx) at a fixed interval via one long-lived USB session. Read-only. Writes CSV with timestamps; returns JSON summary (frames, FF_GAP/IO_FAIL counts, interval stats, io_overhead). Supports two protocol profiles: continuous (pure-read polling) and request-response (pre_write command written before every frame, e.g. PT488 0x10/0x14 channels). Per-frame IO overhead is reported separately in io_overhead_avg_ms.",
         "inputSchema": {
             "type": "object",
             "properties": {
@@ -1437,6 +1439,11 @@ TOOLS_REGISTRY = {
                     "description": "Probe reg 0x10 before capture; abort with TARGET_MISMATCH when the chip does not answer.",
                     "default": False,
                 },
+                "pre_write": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Request-response protocol profile: commands 'addr:data' written before EVERY frame (e.g. ['0xEC:10']) so request-response channels refresh each read. Omit for continuous (pure-read) streams. Defaults from lab.yaml ndtdbg.stream.pre_write when omitted.",
+                },
                 "dll_dir": {"type": "string", "description": "NdtDebugTool lib dir; default from lab.yaml ndtdbg.dll_dir"},
                 "slave_addr": {"type": "string", "description": "IIC slave address, e.g. 0xA0; default from lab.yaml"},
             },
@@ -1619,7 +1626,7 @@ def process_request(req: Dict[str, Any]) -> Optional[Dict[str, Any]]:
                 },
                 "serverInfo": {
                     "name": "firmwareloop",
-                    "version": "0.2.1"
+                    "version": "0.3.0"
                 }
             }
         }
@@ -1754,7 +1761,7 @@ def _settle_stashed_entrypoints(stashed) -> None:
 def handle_cli_update() -> int:
     """Handle `firmwareloop update` command."""
     print("============================================================")
-    print("  FirmwareLoop Auto-Updater (v0.2.1)")
+    print("  FirmwareLoop Auto-Updater (v0.3.0)")
     print("============================================================")
 
     is_git_repo = os.path.exists(os.path.join(REPO_ROOT, ".git"))
@@ -2029,7 +2036,7 @@ def set_ndtdbg_dlldir(dll_path: str) -> str:
 def handle_cli_setup() -> int:
     """Handle `firmwareloop setup` command: simultaneously configure Antigravity CLI, Claude Code CLI, Qoder IDE, and CodeBuddy IDE."""
     print("============================================================")
-    print("  FirmwareLoop Multi-Agent Global Setup Helper (v0.2.1)")
+    print("  FirmwareLoop Multi-Agent Global Setup Helper (v0.3.0)")
     print("============================================================")
     print("")
 
@@ -2154,7 +2161,7 @@ def handle_cli_setup() -> int:
 def handle_cli_init() -> int:
     """Handle `firmwareloop init` command."""
     print("============================================================")
-    print("  FirmwareLoop Multi-Agent Project Initializer (v0.2.1)")
+    print("  FirmwareLoop Multi-Agent Project Initializer (v0.3.0)")
     print("============================================================")
     cwd = os.getcwd()
     print(f"[*] Initializing multi-agent guidelines & bench config in:\n    {cwd}\n")
@@ -2175,7 +2182,7 @@ def handle_cli_init() -> int:
 
 
 def print_cli_help() -> None:
-    print("""FirmwareLoop (fwloop) — AI Agent Firmware Engineering & Lab Automation Platform (v0.2.1)
+    print("""FirmwareLoop (fwloop) — AI Agent Firmware Engineering & Lab Automation Platform (v0.3.0)
 
 Usage:
   fwloop [command]   (or: firmwareloop [command])
@@ -2215,7 +2222,7 @@ def main() -> None:
                 sys.exit(2)
             sys.exit(handle_cli_ndtdebugtool(args[1]))
         elif cmd in ["version", "-v", "--version"]:
-            print("FirmwareLoop v0.2.1")
+            print("FirmwareLoop v0.3.0")
             sys.exit(0)
         elif cmd in ["help", "-h", "--help"]:
             print_cli_help()

{firmwareloop-0.2.1 → firmwareloop-0.3.0}/tools/lib/ndtdbg.py

@@ -106,6 +106,30 @@ def parse_reg_spec(spec: str) -> dict:
     return {"addr": addr, "len": length, "name": name or f"reg_{addr:02X}"}
 
 
+def parse_pre_write_spec(spec: str) -> dict:
+    """解析 pre-write spec 'addr:data' -> {'addr', 'data'} (请求-响应式协议每帧先写的命令)。
+
+    data 为 hex 载荷 (可含空格)。Fail-Closed: 格式/越界抛 CONFIG_ERROR。
+    """
+    parts = str(spec).split(":", 1)
+    if len(parts) != 2 or not parts[0] or not parts[1].strip():
+        raise NdtBoxError("CONFIG_ERROR", "pre-write spec 格式非法 (addr:data)", str(spec))
+    try:
+        addr = int(parts[0], 0)
+    except ValueError as exc:
+        raise NdtBoxError("CONFIG_ERROR", "pre-write spec addr 不是合法整数", str(spec)) from exc
+    if not 0 <= addr <= 0xFF:
+        raise NdtBoxError("CONFIG_ERROR", "pre-write spec addr 越界 (0..0xFF)", hex(addr))
+    data = parts[1].strip()
+    if len(data.replace(" ", "")) % 2 != 0:
+        raise NdtBoxError("CONFIG_ERROR", "pre-write spec data 不是偶数长度 hex", data)
+    try:
+        bytes.fromhex(data.replace(" ", ""))
+    except ValueError as exc:
+        raise NdtBoxError("CONFIG_ERROR", "pre-write spec data 含非法 hex 字符", data) from exc
+    return {"addr": addr, "data": data}
+
+
 def decode_payload(hex_str: str | None, mode: str) -> str | None:
     """hex 载荷按模式解码为 '|' 分隔数值串; mode=hex 或空载荷返回 None。
 
@@ -132,17 +156,23 @@ def decode_payload(hex_str: str | None, mode: str) -> str | None:
     return "|".join(str(v) for v in vals) if vals else None
 
 
-def interval_stats(frame_times_ms: list[float]) -> dict:
-    """帧完成时间序列 -> 实际间隔统计 {avg_ms, p95_ms, gaps_n}; 帧数 < 2 时返回空 dict。"""
+def interval_stats(frame_times_ms: list[float], target_ms: float | None = None) -> dict:
+    """帧开始时间序列 -> 实际间隔统计; 帧数 < 2 时返回空 dict。
+
+    gaps_n 语义 (实战修正): 仅统计间隔 > 2x 目标间隔的帧数 (真实缺帧/卡顿);
+    正常 IO 开销 (~10ms/帧) 不计入, 否则该指标永远接近 100% 失真。
+    """
     gaps = [round(b - a, 1) for a, b in zip(frame_times_ms, frame_times_ms[1:])]
     if not gaps:
         return {}
     ordered = sorted(gaps)
-    return {
-        "gaps_n": len(gaps),
+    out = {
         "interval_actual_avg_ms": round(sum(gaps) / len(gaps), 1),
         "interval_actual_p95_ms": ordered[min(len(ordered) - 1, int(len(ordered) * 0.95))],
     }
+    if target_ms is not None:
+        out["gaps_n"] = sum(1 for g in gaps if g > 2 * target_ms)
+    return out
 
 
 def strip_nfw(file_bytes: bytes, header_len: int = 256) -> bytes:

{firmwareloop-0.2.1 → firmwareloop-0.3.0}/tools/ndtdbg_bridge.ps1

@@ -463,11 +463,17 @@ try {
             $sRetry = if ($null -ne $cfg.retry) { [int]$cfg.retry } else { 2 }
             $sFailThr = if ($null -ne $cfg.fail_threshold) { [int]$cfg.fail_threshold } else { 50 }
             $sRequireTarget = [bool]$cfg.require_target
+            $sPreWrites = if ($cfg.pre_writes) { @($cfg.pre_writes) } else { @() }
             if ($sDurationS -le 0 -and $sMaxFrames -le 0) { Fail "CONFIG_ERROR" "stream 需要 duration_s 或 max_frames 之一 > 0" $null }
             if ($sInterval -lt 1) { Fail "CONFIG_ERROR" "stream interval_ms 必须 >= 1" $sInterval }
             foreach ($r in $sRegs) {
                 if (([int]$r.len) -lt 1 -or ([int]$r.len) -gt 256) { Fail "CONFIG_ERROR" "stream 读长度越界 (1..256)" $r.len }
             }
+            foreach ($pw in $sPreWrites) {
+                if ($null -eq $pw.addr -or -not $pw.data) { Fail "CONFIG_ERROR" "pre_writes 项需要 {addr, data}" $null }
+                if (([int]$pw.addr) -lt 0 -or ([int]$pw.addr) -gt 0xFF) { Fail "CONFIG_ERROR" "pre_writes addr 越界 (0..0xFF)" $pw.addr }
+                if (((Parse-Hex ([string]$pw.data)).Count + 2) -gt 256) { Fail "CONFIG_ERROR" "pre_writes 写事务过长 (含从机地址+寄存器地址须 <=256)" $pw.data }
+            }
 
             [Console]::OutputEncoding = [System.Text.Encoding]::UTF8
             $sw = [System.Diagnostics.Stopwatch]::StartNew()
@@ -495,48 +501,83 @@ try {
             $framesOk = 0; $framesGap = 0; $framesIoFail = 0
             $frameNo = 0
             $consecIoFail = 0
+            $frameIoMsSum = 0.0   # 帧内 IO 耗时累计 (帧完成 - 帧开始), 供 io_overhead_avg_ms
             $aborted = $false; $abortReason = ""
             $durationMsTotal = [int]($sDurationS * 1000)
             while ($true) {
                 $frameNo++
                 $frameStartMs = $sw.Elapsed.TotalMilliseconds
                 $hasIoFail = $false; $hasGap = $false
-                foreach ($r in $sRegs) {
-                    $reg = [int]$r.addr; $rlen = [int]$r.len
-                    $hexOut = "-"; $tag = "OK"
+
+                # --- pre-write (请求-响应式协议): 每帧先写请求寄存器再读数据 ---
+                # 写失败 -> 记 IO_FAIL 行并跳过本帧读 (请求未送达, 读到的是旧快照)
+                $preOk = $true
+                foreach ($pw in $sPreWrites) {
+                    $pAddr = [int]$pw.addr
+                    $pData = Parse-Hex ([string]$pw.data)
+                    $pwOk = $false
                     try {
-                        for ($attempt = 0; $attempt -le $sRetry; $attempt++) {
-                            $tx = New-Object byte[] 2
-                            $tx[0] = [byte]$SlaveAddr; $tx[1] = [byte]$reg
-                            $rb = New-Object byte[] $rlen
-                            if (Invoke-WriteRead $h $tx $rb) {
-                                # ForEach-Object 将管道元素绑定到 $_——scriptblock 用 param()
-                                # 形式收参恒为 null (Null 方法调用), 必须内联 $_
-                                $hexStr = (($rb | ForEach-Object { $_.ToString("X2") }) -join " ")
-                                $allFF = $true
-                                foreach ($b in $rb) { if ($b -ne 0xFF) { $allFF = $false; break } }
-                                if ($allFF) {
-                                    $tag = "FF_GAP"; $hexOut = $hexStr   # 总线高阻特征: 记录原值, 重试
-                                    if ($attempt -lt $sRetry) { Start-Sleep -Milliseconds 5 }
+                        $tx = New-Object byte[] (2 + $pData.Count)
+                        $tx[0] = [byte]$SlaveAddr; $tx[1] = [byte]$pAddr
+                        [Array]::Copy($pData, 0, $tx, 2, $pData.Count)
+                        for ($pwA = 0; $pwA -le $sRetry; $pwA++) {
+                            if (Invoke-WriteRead $h $tx (New-Object byte[] 0)) { $pwOk = $true; break }
+                            if ($pwA -lt $sRetry) { Start-Sleep -Milliseconds 5 }
+                        }
+                    } catch {
+                        $pwOk = $false
+                    }
+                    if (-not $pwOk) {
+                        $preOk = $false
+                        $tRel = [math]::Round($frameStartMs, 1)
+                        [Console]::WriteLine(("#F`t{0}`t{1}`t0x{2:X2}`t-`tIO_FAIL" -f $frameNo, $tRel, $pAddr))
+                        [Console]::Out.Flush()
+                    }
+                }
+
+                if ($preOk) {
+                    foreach ($r in $sRegs) {
+                        $reg = [int]$r.addr; $rlen = [int]$r.len
+                        $hexOut = "-"; $tag = "OK"
+                        try {
+                            for ($attempt = 0; $attempt -le $sRetry; $attempt++) {
+                                $tx = New-Object byte[] 2
+                                $tx[0] = [byte]$SlaveAddr; $tx[1] = [byte]$reg
+                                $rb = New-Object byte[] $rlen
+                                if (Invoke-WriteRead $h $tx $rb) {
+                                    # ForEach-Object 将管道元素绑定到 $_——scriptblock 用 param()
+                                    # 形式收参恒为 null (Null 方法调用), 必须内联 $_
+                                    $hexStr = (($rb | ForEach-Object { $_.ToString("X2") }) -join " ")
+                                    $allFF = $true
+                                    foreach ($b in $rb) { if ($b -ne 0xFF) { $allFF = $false; break } }
+                                    if ($allFF) {
+                                        $tag = "FF_GAP"; $hexOut = $hexStr   # 总线高阻特征: 记录原值, 重试
+                                        if ($attempt -lt $sRetry) { Start-Sleep -Milliseconds 5 }
+                                    } else {
+                                        $tag = "OK"; $hexOut = $hexStr
+                                        break
+                                    }
                                 } else {
-                                    $tag = "OK"; $hexOut = $hexStr
-                                    break
+                                    $tag = "IO_FAIL"; $hexOut = "-"
+                                    if ($attempt -lt $sRetry) { Start-Sleep -Milliseconds 5 }
                                 }
-                            } else {
-                                $tag = "IO_FAIL"; $hexOut = "-"
-                                if ($attempt -lt $sRetry) { Start-Sleep -Milliseconds 5 }
                             }
+                        } catch {
+                            # 单寄存器异常降级为 IO_FAIL 行继续采集, 不作废整个 stream (fail-closed 韧性)
+                            $tag = "IO_FAIL"; $hexOut = "-"
                         }
-                    } catch {
-                        # 单寄存器异常降级为 IO_FAIL 行继续采集, 不作废整个 stream (fail-closed 韧性)
-                        $tag = "IO_FAIL"; $hexOut = "-"
+                        if ($tag -eq "IO_FAIL") { $hasIoFail = $true }
+                        elseif ($tag -eq "FF_GAP") { $hasGap = $true }
+                        # t_rel 取帧开始时刻: 帧间隔统计不含 IO 开销 (否则 p95 永远略超 target);
+                        # 帧内 IO 耗时由 summary 的 io_overhead_avg_ms 单独暴露
+                        $tRel = [math]::Round($frameStartMs, 1)
+                        # 方法调用参数列表里逗号是参数分隔符, 必须括号把整个 -f 表达式包成单参数,
+                        # 否则 -f 只拿到 1 个参数, {1} 起索引越界 (FormatException)
+                        [Console]::WriteLine(("#F`t{0}`t{1}`t0x{2:X2}`t{3}`t{4}" -f $frameNo, $tRel, $reg, $hexOut, $tag))
+                        [Console]::Out.Flush()
                     }
-                    if ($tag -eq "IO_FAIL") { $hasIoFail = $true }
-                    elseif ($tag -eq "FF_GAP") { $hasGap = $true }
-                    $tRel = [math]::Round($sw.Elapsed.TotalMilliseconds, 1)
-                    [Console]::WriteLine("#F`t{0}`t{1}`t0x{2:X2}`t{3}`t{4}" -f $frameNo, $tRel, $reg, $hexOut, $tag)
-                    [Console]::Out.Flush()
                 }
+                $frameIoMsSum += ($sw.Elapsed.TotalMilliseconds - $frameStartMs)
                 if ($hasIoFail) { $framesIoFail++; $consecIoFail++ }
                 else {
                     if ($hasGap) { $framesGap++ } else { $framesOk++ }
@@ -552,9 +593,11 @@ try {
                 }
             }
             [STDataCollection.Icb]::USBIO_CloseDevice([uint32]0) | Out-Null
+            $ioOverhead = if ($frameNo -gt 0) { [math]::Round($frameIoMsSum / $frameNo, 1) } else { 0 }
             $sum = @{ ok = $true; action = "stream"; data = @{
                 frames_ok = $framesOk; frames_ff_gap = $framesGap; frames_io_fail = $framesIoFail;
                 frames_total = $frameNo; aborted = $aborted; abort_reason = $abortReason;
+                io_overhead_avg_ms = $ioOverhead;
                 duration_actual_ms = [int]$sw.Elapsed.TotalMilliseconds } }
             [Console]::WriteLine(($sum | ConvertTo-Json -Compress -Depth 5))
             [Console]::Out.Flush()

{firmwareloop-0.2.1 → firmwareloop-0.3.0}/tools/ndtdbg_cli.py

@@ -13,7 +13,7 @@ from datetime import datetime
 
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 from lib.ndtdbg import (ChipSeaFxx, NdtBoxError, NdtBoxIo, decode_payload,  # noqa: E402
-                        interval_stats, parse_reg_spec)
+                        interval_stats, parse_pre_write_spec, parse_reg_spec)
 
 sys.stdout.reconfigure(encoding="utf-8", errors="replace")
 
@@ -199,7 +199,7 @@ def cmd_poll(io: NdtBoxIo, duration_ms: int, interval_ms: int, max_frames: int,
 
 def cmd_stream(io: NdtBoxIo, config: dict, specs: list, interval_ms, duration_s: float,
                max_frames: int, out_path, decode: str, retry: int, fail_threshold,
-               require_target: bool) -> None:
+               require_target: bool, pre_write_specs=None) -> None:
     """高速连续采集 (只读): 桥进程内长驻 USB 会话, 单帧开销 = 一次 I2C 事务。
 
     帧语义: OK / FF_GAP (读成功但全 FF, 总线高阻特征, 只统计不熔断) /
@@ -227,8 +227,15 @@ def cmd_stream(io: NdtBoxIo, config: dict, specs: list, interval_ms, duration_s:
     if out_dir:
         os.makedirs(out_dir, exist_ok=True)
 
+    # pre-write (请求-响应式协议): CLI --pre-write 优先, 未传时回落 lab.yaml
+    # ndtdbg.stream.pre_write (产品协议 profile 沉淀); 两处均未配置 = 纯读 continuous
+    if pre_write_specs is None:
+        pre_write_specs = stream_cfg.get("pre_write") or []
+    pre_writes = [parse_pre_write_spec(s) for s in pre_write_specs]
+
     spec = {
         "regs": [{"addr": s["addr"], "len": s["len"], "name": s["name"]} for s in specs],
+        "pre_writes": [{"addr": p["addr"], "data": p["data"]} for p in pre_writes],
         "interval_ms": interval_ms, "duration_s": float(duration_s), "max_frames": max_frames,
         "retry": retry, "fail_threshold": fail_threshold, "require_target": require_target,
     }
@@ -266,6 +273,17 @@ def cmd_stream(io: NdtBoxIo, config: dict, specs: list, interval_ms, duration_s:
             data = io.stream_run(spec, on_row=on_row)
         except KeyboardInterrupt:
             data = None   # 桥被终止; 行级计数近似, CSV 已写数据保留
+        except NdtBoxError as exc:
+            fh.close()
+            hints = {
+                "PROBE_NOT_FOUND": "检查 NdtBox USB 连接与 CH341 驱动; 退出 STDataCollection.exe (USB 独占)",
+                "TARGET_MISMATCH": "检查 IIC 接线/上拉/供电/从机地址; 请求-响应式通道需先 write_reg 开启 debug_mode (如 0xBE=01)",
+            }
+            hint = hints.get(exc.error_class)
+            detail = exc.detail or ""
+            if hint:
+                detail = f"{detail}; 建议: {hint}" if detail else f"建议: {hint}"
+            fail(exc.error_class, exc.message, detail=detail or None)
     finally:
         fh.close()
 
@@ -279,14 +297,17 @@ def cmd_stream(io: NdtBoxIo, config: dict, specs: list, interval_ms, duration_s:
         "frames_io_fail": data.get("frames_io_fail", rows["IO_FAIL"]) if data else rows["IO_FAIL"],
         "frames_total": total if total else sum(rows.values()),
         "interval_target_ms": interval_ms,
+        "io_overhead_avg_ms": data.get("io_overhead_avg_ms") if data else None,
         "duration_actual_s": round((data.get("duration_actual_ms") or 0) / 1000.0, 2) if data
         else round((state["t"] or 0) / 1000.0, 2),
         "aborted": bool(data.get("aborted")) if data else True,
         "abort_reason": data.get("abort_reason") or ("interrupted" if data is None else ""),
     }
-    summary.update(interval_stats(frame_times))
+    summary.update(interval_stats(frame_times, target_ms=interval_ms))
     if decode != "hex":
         summary["decode"] = decode
+    if pre_writes:
+        summary["pre_write"] = [f"{p['addr']:#x}:{p['data']}" for p in pre_writes]
 
     if summary["aborted"] and summary["abort_reason"] == "fail_threshold":
         # 熔断: Fail-Closed 错误信封, 但 data 携带已采数据 summary
@@ -377,6 +398,9 @@ def build_parser() -> argparse.ArgumentParser:
                     help="连续 IO_FAIL 熔断阈值 (默认 lab.yaml ndtdbg.stream.fail_threshold 或 50; 0=不熔断)")
     st.add_argument("--require-target", action="store_true",
                     help="采集前探测 0x10, 无有效芯片应答则 TARGET_MISMATCH")
+    st.add_argument("--pre-write", nargs="+", default=None,
+                    help="请求-响应式协议: 每帧先写的命令 spec addr:data (如 0xEC:10); "
+                         "默认读 lab.yaml ndtdbg.stream.pre_write, 均未配置 = 纯读 continuous")
     return p
 
 
@@ -405,7 +429,7 @@ def main(argv=None) -> None:
             specs = [parse_reg_spec(s) for s in args.regs]
             cmd_stream(io, config, specs, args.interval_ms, args.duration_s,
                        args.max_frames, args.out, args.decode, args.retry,
-                       args.fail_threshold, args.require_target)
+                       args.fail_threshold, args.require_target, args.pre_write)
         else:  # pragma: no cover
             fail("CONFIG_ERROR", f"unknown cmd: {args.cmd}")
     except NdtBoxError as exc:

{firmwareloop-0.2.1 → firmwareloop-0.3.0}/tools/setup-agent-mcp.ps1

@@ -1,6 +1,6 @@
 <#
 .SYNOPSIS
-    Dual-Tier MCP setup and registration helper (v0.2.1).
+    Dual-Tier MCP setup and registration helper (v0.3.0).
     Inspects installed AI coding agents (Qoder, Claude Code, Antigravity, Cursor)
     and configures global MCP / skills or prints exact registration commands.
 
@@ -242,7 +242,7 @@ if ($Json) {
     Write-FwJson ([pscustomobject]$report)
 } else {
     Write-Host "============================================================" -ForegroundColor Cyan
-    Write-Host "  FirmwareLoop Dual-Tier MCP & Agent Setup Helper (v0.2.1)" -ForegroundColor Green
+    Write-Host "  FirmwareLoop Dual-Tier MCP & Agent Setup Helper (v0.3.0)" -ForegroundColor Green
     Write-Host "============================================================" -ForegroundColor Cyan
     Write-Host ""
     Write-Host "[1] Google Antigravity / Gemini CLI:" -ForegroundColor Yellow