firmwareloop 0.1.9__tar.gz → 0.2.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: firmwareloop
-Version: 0.1.9
+Version: 0.2.1
 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.1.9)
+├── pyproject.toml    标准 Python 包配置与 CLI 入口声明 (v0.2.1)
 ├── .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.1.9）
+## 能力验证状态（v0.2.1）
 
 > 状态定义：`Implemented`（已实现）/ `Simulator Validated`（模拟验证）/
 > `Real Hardware Validated`（真机验证）/ `Experimental` / `Not Implemented`

{firmwareloop-0.1.9 → firmwareloop-0.2.1}/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.1.9)
+├── pyproject.toml    标准 Python 包配置与 CLI 入口声明 (v0.2.1)
 ├── .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.1.9）
+## 能力验证状态（v0.2.1）
 
 > 状态定义：`Implemented`（已实现）/ `Simulator Validated`（模拟验证）/
 > `Real Hardware Validated`（真机验证）/ `Experimental` / `Not Implemented`

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: firmwareloop
-Version: 0.1.9
+Version: 0.2.1
 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.1.9)
+├── pyproject.toml    标准 Python 包配置与 CLI 入口声明 (v0.2.1)
 ├── .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.1.9）
+## 能力验证状态（v0.2.1）
 
 > 状态定义：`Implemented`（已实现）/ `Simulator Validated`（模拟验证）/
 > `Real Hardware Validated`（真机验证）/ `Experimental` / `Not Implemented`

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

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

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

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

{firmwareloop-0.1.9 → firmwareloop-0.2.1}/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.1.9).
+fw_mcp_server.py - FirmwareLoop High-Level Workflow & Device MCP Server (v0.2.1).
 
 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
@@ -20,6 +20,7 @@ Tools provided:
   - fw_ndtdbg_write_reg: NdtBox IIC register write, double-gated (ndtdbg_cli.py)
   - fw_ndtdbg_capture_seq: NdtBox register sequence + concurrent I2C capture for waveform evidence (ndtdbg_cli.py)
   - fw_ndtdbg_flash: NdtBox IIC firmware flash (.bin/.nfw, full-chip erase, double-gated) (ndtdbg_cli.py)
+  - fw_ndtdbg_stream: NdtBox high-rate register stream capture to CSV via one long-lived USB session (read-only) (ndtdbg_cli.py)
   - fw_logic_capture: Logic analyzer protocol capture (logic_capture.ps1)
   - fw_logic_decode: Logic analyzer protocol decoding & assertion (logic_decode.ps1)
   - fw_get_evidence: Read structured audit run evidence (artifacts/runs/)
@@ -330,6 +331,39 @@ def handle_fw_ndtdbg_flash(args: Dict[str, Any]) -> Dict[str, Any]:
     return _ndtdbg_run(cmd, timeout_s)
 
 
+def handle_fw_ndtdbg_stream(args: Dict[str, Any]) -> Dict[str, Any]:
+    """Stream-read a set of IIC registers at a fixed interval via one long-lived
+    USB session (sampling loop runs inside the 32-bit bridge process, so the
+    per-frame overhead is one StreamI2C transaction, not a full cold start).
+    Read-only. Writes CSV with timestamps; returns JSON summary."""
+    cli_script = os.path.join(REPO_ROOT, "tools", "ndtdbg_cli.py")
+    regs = args.get("regs") or ["0xEE:8"]
+    duration_s = min(max(float(args.get("duration_s", 10)), 0.0), 600.0)
+    max_frames = int(args.get("max_frames", 0))
+    if duration_s <= 0 and max_frames <= 0:
+        return {"ok": False, "error_class": "CONFIG_ERROR",
+                "error": "stream requires duration_s or max_frames > 0"}
+    cmd = [PYTHON_EXE, cli_script, "stream", "--regs", *[str(r) for r in regs]]
+    if args.get("interval_ms") is not None:
+        cmd.extend(["--interval-ms", str(int(args["interval_ms"]))])
+    cmd.extend(["--duration-s", str(duration_s)])
+    if max_frames > 0:
+        cmd.extend(["--max-frames", str(max_frames)])
+    if args.get("out_path"):
+        cmd.extend(["--out", str(args["out_path"])])
+    decode = args.get("decode", "hex")
+    if decode != "hex":
+        cmd.extend(["--decode", decode])
+    if args.get("retry") is not None:
+        cmd.extend(["--retry", str(int(args["retry"]))])
+    if args.get("fail_threshold") is not None:
+        cmd.extend(["--fail-threshold", str(int(args["fail_threshold"]))])
+    if args.get("require_target"):
+        cmd.append("--require-target")
+    _ndtdbg_reg_args(args, cmd)
+    return _ndtdbg_run(cmd, timeout=int(duration_s) + 120)
+
+
 def handle_fw_ndtdbg_capture_seq(args: Dict[str, Any]) -> Dict[str, Any]:
     """单次调用内并发: 逻辑分析仪抓取与 NdtBox 寄存器序列同时进行。
 
@@ -1352,6 +1386,65 @@ 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).",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "regs": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Register specs 'addr:len[:name]', e.g. ['0xEE:8:ch', '0x20:138:event']. Default ['0xEE:8'].",
+                    "default": ["0xEE:8"],
+                },
+                "interval_ms": {
+                    "type": "integer",
+                    "description": "Target sampling interval in ms. Actual interval = max(interval_ms, io_time); jitter recorded in summary.",
+                    "default": 100,
+                },
+                "duration_s": {
+                    "type": "number",
+                    "description": "Total capture duration in seconds (capped at 600). Either duration_s or max_frames must be > 0.",
+                    "default": 10,
+                },
+                "max_frames": {
+                    "type": "integer",
+                    "description": "Stop after N frames (alternative to duration_s).",
+                    "default": 0,
+                },
+                "out_path": {
+                    "type": "string",
+                    "description": "CSV output path. Default: <cwd>/lab/streams/ndtdbg_stream_<ts>.csv",
+                },
+                "decode": {
+                    "type": "string",
+                    "enum": ["hex", "int16le", "uint16le", "int8", "uint8"],
+                    "description": "Optional decoded columns besides raw hex (int16le for PT488 0xEE channels).",
+                    "default": "hex",
+                },
+                "retry": {
+                    "type": "integer",
+                    "description": "Retries per frame per register on all-0xFF / IO error before marking the frame FAILED.",
+                    "default": 2,
+                },
+                "fail_threshold": {
+                    "type": "integer",
+                    "description": "Abort capture after N consecutive IO_FAIL frames (0 = never abort); already-captured data is kept and returned.",
+                    "default": 50,
+                },
+                "require_target": {
+                    "type": "boolean",
+                    "description": "Probe reg 0x10 before capture; abort with TARGET_MISMATCH when the chip does not answer.",
+                    "default": False,
+                },
+                "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"},
+            },
+            "required": ["regs"],
+            "additionalProperties": False,
+        },
+        "handler": handle_fw_ndtdbg_stream,
+    },
     "fw_ndtdbg_capture_seq": {
         "description": "One-call protocol evidence: concurrently runs a NdtBox register write sequence and a sigrok I2C capture, returning the capture path for fw_logic_decode. NOTE: the default sequence (0xBE=01, 0x01=BE 42, poll 0x01, readback 0xBE) is an EXAMPLE only - always pass your target firmware's real register protocol via writes/poll_reg/poll_expect. Writes are double-gated (confirm: true + lab.yaml ndtdbg.write_allowed); degrades to sequence-only execution (capture_skipped) when sigrok-cli is missing.",
         "inputSchema": {
@@ -1526,7 +1619,7 @@ def process_request(req: Dict[str, Any]) -> Optional[Dict[str, Any]]:
                 },
                 "serverInfo": {
                     "name": "firmwareloop",
-                    "version": "0.1.9"
+                    "version": "0.2.1"
                 }
             }
         }
@@ -1615,10 +1708,53 @@ def process_request(req: Dict[str, Any]) -> Optional[Dict[str, Any]]:
     return None
 
 
+def _local_bin_entrypoints() -> list:
+    """uv tool 入口点 exe (~/.local/bin)——本命令自身与常驻 MCP server 都从这里运行。"""
+    home = os.path.expanduser("~")
+    return [os.path.join(home, ".local", "bin", name)
+            for name in ("fwloop.exe", "fw-mcp.exe", "agentic-hil.exe")]
+
+
+def _stash_local_bin_entrypoints() -> list:
+    """升级前把入口点 exe 重命名让位 (Windows 允许 rename 运行中的 exe, 不允许覆盖写)。
+
+    否则 `fwloop update` 第一次必然失败: uv 复制新 fwloop.exe 的目标文件正是当前
+    命令自己的启动映像 (被锁定, os error 32), 第二次则因 "Nothing to upgrade"
+    跳过入口点同步。返回 [(原路径, 备份路径)]。
+    """
+    stashed = []
+    for path in _local_bin_entrypoints():
+        if not os.path.isfile(path):
+            continue
+        stash = path + ".upgrading"
+        try:
+            if os.path.exists(stash):   # 上次升级残留 (旧映像仍被运行中进程持有)
+                os.remove(stash)
+            os.rename(path, stash)
+            stashed.append((path, stash))
+            print(f"[*] Entrypoint stashed for upgrade: {os.path.basename(path)} -> .upgrading")
+        except OSError:
+            pass   # 让位失败不阻塞升级: uv 直接覆盖, 若 os error 32 走针对性诊断
+    return stashed
+
+
+def _settle_stashed_entrypoints(stashed) -> None:
+    """升级收尾: uv 已写入新入口点 -> 删备份 (旧映像仍被运行中进程持有时留待下次);
+    uv 未写入 (升级失败/中止) -> 还原旧入口点, 保证 fwloop 命令不消失。"""
+    for path, stash in stashed:
+        try:
+            if os.path.isfile(path):
+                os.remove(stash)          # 新 exe 已就位, 备份可弃
+            else:
+                os.rename(stash, path)    # 升级未完成: 还原
+        except OSError:
+            pass                          # 旧映像仍被本命令/常驻 MCP 持有, 留待下次清理
+
+
 def handle_cli_update() -> int:
     """Handle `firmwareloop update` command."""
     print("============================================================")
-    print("  FirmwareLoop Auto-Updater (v0.1.9)")
+    print("  FirmwareLoop Auto-Updater (v0.2.1)")
     print("============================================================")
 
     is_git_repo = os.path.exists(os.path.join(REPO_ROOT, ".git"))
@@ -1661,19 +1797,24 @@ def handle_cli_update() -> int:
         uv_path = shutil.which("uv")
         if uv_path:
             print("[*] Upgrading firmwareloop via `uv tool upgrade firmwareloop`...")
+            # 关键: 入口点 exe (.local\bin\fwloop.exe) 正被本命令自身运行——Windows 禁止
+            # 覆盖运行中的 exe (os error 32), 不让位则第一次 upgrade 必然失败。
+            # rename 让位 (运行中的 exe 允许重命名), uv 复制新入口点后在收尾阶段清理/还原。
+            stashed = _stash_local_bin_entrypoints()
             try:
                 res = subprocess.run([uv_path, "tool", "upgrade", "firmwareloop"])
-                if res.returncode == 0:
-                    print("\n============================================================")
-                    print("[+] FirmwareLoop has been upgraded to the latest version!")
-                    print("============================================================")
-                    return 0
-                else:
-                    print(f"[-] uv tool upgrade returned code {res.returncode}")
-                    return res.returncode
-            except Exception as e:
-                print(f"[-] Error upgrading via uv tool: {e}")
-                return 1
+            finally:
+                _settle_stashed_entrypoints(stashed)
+            if res.returncode == 0:
+                print("\n============================================================")
+                print("[+] FirmwareLoop has been upgraded to the latest version!")
+                print("============================================================")
+                return 0
+            print(f"[-] uv tool upgrade returned code {res.returncode}")
+            print("    工具环境可能已升级成功, 仅入口点 exe 未更新 (os error 32 = 文件被占用)。")
+            print("    占用者通常是本命令自身或常驻的 MCP server 进程; 关闭 IDE 后重跑一次")
+            print("    `fwloop update` 即可完成收尾。")
+            return res.returncode
         else:
             print("[*] Upgrading via pip (`pip install --upgrade firmwareloop`)...")
             res = subprocess.run([sys.executable, "-m", "pip", "install", "--upgrade", "firmwareloop"])
@@ -1888,7 +2029,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.1.9)")
+    print("  FirmwareLoop Multi-Agent Global Setup Helper (v0.2.1)")
     print("============================================================")
     print("")
 
@@ -2013,7 +2154,7 @@ def handle_cli_setup() -> int:
 def handle_cli_init() -> int:
     """Handle `firmwareloop init` command."""
     print("============================================================")
-    print("  FirmwareLoop Multi-Agent Project Initializer (v0.1.9)")
+    print("  FirmwareLoop Multi-Agent Project Initializer (v0.2.1)")
     print("============================================================")
     cwd = os.getcwd()
     print(f"[*] Initializing multi-agent guidelines & bench config in:\n    {cwd}\n")
@@ -2034,7 +2175,7 @@ def handle_cli_init() -> int:
 
 
 def print_cli_help() -> None:
-    print("""FirmwareLoop (fwloop) — AI Agent Firmware Engineering & Lab Automation Platform (v0.1.9)
+    print("""FirmwareLoop (fwloop) — AI Agent Firmware Engineering & Lab Automation Platform (v0.2.1)
 
 Usage:
   fwloop [command]   (or: firmwareloop [command])
@@ -2074,7 +2215,7 @@ def main() -> None:
                 sys.exit(2)
             sys.exit(handle_cli_ndtdebugtool(args[1]))
         elif cmd in ["version", "-v", "--version"]:
-            print("FirmwareLoop v0.1.9")
+            print("FirmwareLoop v0.2.1")
             sys.exit(0)
         elif cmd in ["help", "-h", "--help"]:
             print_cli_help()

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

@@ -79,6 +79,72 @@ def parse_module_connect(data: bytes) -> int:
     return int.from_bytes(data[:2], "little")
 
 
+# ---------------------------------------------------------------------------
+# stream 连续采集 (纯函数部分, 平台无关可单测)
+# ---------------------------------------------------------------------------
+
+def parse_reg_spec(spec: str) -> dict:
+    """解析寄存器 spec 'addr:len[:name]' -> {'addr', 'len', 'name'}。
+
+    addr 支持 0x 前缀; name 省略时自动生成 reg_<hex>。Fail-Closed: 格式/越界抛 CONFIG_ERROR。
+    """
+    parts = str(spec).split(":")
+    if len(parts) < 2 or len(parts) > 3 or not parts[0] or not parts[1]:
+        raise NdtBoxError("CONFIG_ERROR", "reg spec 格式非法 (addr:len[:name])", str(spec))
+    try:
+        addr = int(parts[0], 0)
+        length = int(parts[1], 0)
+    except ValueError as exc:
+        raise NdtBoxError("CONFIG_ERROR", "reg spec addr/len 不是合法整数", str(spec)) from exc
+    if not 0 <= addr <= 0xFF:
+        raise NdtBoxError("CONFIG_ERROR", "reg spec addr 越界 (0..0xFF)", hex(addr))
+    if not 1 <= length <= 256:
+        raise NdtBoxError("CONFIG_ERROR", "reg spec len 越界 (1..256)", str(length))
+    name = parts[2].strip() if len(parts) == 3 else ""
+    if name and not all(c.isalnum() or c == "_" for c in name):
+        raise NdtBoxError("CONFIG_ERROR", "reg spec name 只允许字母/数字/下划线", name)
+    return {"addr": addr, "len": length, "name": name or f"reg_{addr:02X}"}
+
+
+def decode_payload(hex_str: str | None, mode: str) -> str | None:
+    """hex 载荷按模式解码为 '|' 分隔数值串; mode=hex 或空载荷返回 None。
+
+    'BD 00 AB 00' + int16le -> '189|171' (小端); int16le 对 >=0x8000 做 C# (short) 有符号语义。
+    """
+    if mode == "hex" or not hex_str or hex_str == "-":
+        return None
+    try:
+        raw = bytes.fromhex(hex_str.replace(" ", ""))
+    except ValueError as exc:
+        raise NdtBoxError("CONFIG_ERROR", "hex 载荷非法", hex_str) from exc
+    vals: list[int] = []
+    if mode in ("int16le", "uint16le"):
+        for i in range(0, len(raw) - len(raw) % 2, 2):
+            v = int.from_bytes(raw[i:i + 2], "little")
+            if mode == "int16le" and v >= 0x8000:
+                v -= 0x10000
+            vals.append(v)
+    elif mode in ("int8", "uint8"):
+        for b in raw:
+            vals.append(b - 256 if (mode == "int8" and b >= 0x80) else b)
+    else:
+        raise NdtBoxError("CONFIG_ERROR", "decode 模式非法 (hex/int16le/uint16le/int8/uint8)", mode)
+    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。"""
+    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),
+        "interval_actual_avg_ms": round(sum(gaps) / len(gaps), 1),
+        "interval_actual_p95_ms": ordered[min(len(ordered) - 1, int(len(ordered) * 0.95))],
+    }
+
+
 def strip_nfw(file_bytes: bytes, header_len: int = 256) -> bytes:
     """.nfw 固件: 去 256 字节文件头 (ChipSea.cs LoadFile)。"""
     if len(file_bytes) <= header_len:
@@ -263,6 +329,62 @@ class NdtBoxIo:
             raise NdtBoxError("CONFIG_ERROR", "run_ops 空序列", None)
         return self._bridge_pipe("run", json.dumps(ops, separators=(",", ":")), timeout_ms)
 
+    def stream_run(self, spec: dict, on_row=None) -> dict:
+        """stream action: 桥进程内长驻 USB 会话连续采集 (读循环在 32 位桥内, 消除逐帧冷启动)。
+
+        spec: {"regs":[{"addr","len","name"}...], "interval_ms","duration_s","max_frames",
+               "retry","fail_threshold","require_target"}
+        on_row(parts): 每寄存器读完成回调, parts = ['#F', frame, t_rel_ms, reg, hex|'-', tag]
+                       (tag: OK / FF_GAP / IO_FAIL), tab 分隔。
+        末行 JSON 为桥 summary (frames_* / aborted / abort_reason / duration_actual_ms);
+        桥失败抛 NdtBoxError; Ctrl+C 传播 KeyboardInterrupt, finally 杀桥进程
+        (已回调数据由调用方持有, CSV 保留)。
+        """
+        if not os.path.exists(PS32):
+            raise NdtBoxError("CONFIG_ERROR", f"32 位 PowerShell 不存在: {PS32}")
+        if not os.path.exists(self.bridge_ps1):
+            raise NdtBoxError("CONFIG_ERROR", f"桥脚本不存在: {self.bridge_ps1}")
+        args = [PS32, "-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass",
+                "-File", self.bridge_ps1, "-Action", "stream",
+                "-DllDir", self.dll_dir, "-SlaveAddr", str(self.slave_addr),
+                "-Speed", str(self.speed)]
+        proc = subprocess.Popen(args, stdin=subprocess.PIPE, stdout=subprocess.PIPE,
+                                stderr=subprocess.PIPE, text=True, encoding="utf-8",
+                                errors="replace")
+        try:
+            proc.stdin.write(json.dumps(spec, separators=(",", ":")))
+            proc.stdin.close()
+        except Exception:
+            pass
+        summary: dict | None = None
+        try:
+            for line in proc.stdout:
+                line = line.rstrip("\r\n")
+                if not line:
+                    continue
+                if line.startswith("#F\t"):
+                    if on_row:
+                        on_row(line.split("\t"))
+                elif line.startswith("{"):
+                    summary = json.loads(line)
+                # 其他行 (未来 #progress 等) 忽略
+        finally:
+            try:
+                if proc.poll() is None:
+                    proc.kill()
+                stderr_tail = (proc.stderr.read() or "").strip()[-400:]
+                proc.wait(timeout=10)
+            except Exception:
+                stderr_tail = ""
+        if summary is None:
+            raise NdtBoxError("UNKNOWN_ERROR", "桥 stream 无 summary 输出 (进程提前退出/挂死被终止)",
+                              stderr_tail or None)
+        if not summary.get("ok"):
+            raise NdtBoxError(summary.get("error_class", "UNKNOWN_ERROR"),
+                              summary.get("error", "桥 stream 返回失败"),
+                              summary.get("detail"))
+        return summary.get("data", {})
+
     def flash_exec(self, plan: dict, timeout_ms: int | None = None) -> dict:
         """单进程完整固件烧录 (bridge "flash"), 复刻原厂 GUI 进程模型:
         usb2io(IO10) 断电复位进 boot + USBIOX IIC 全序列在**同一进程同一会话**内连续执行,

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

@@ -4,7 +4,7 @@
 # 输出: stdout 单行 JSON {ok, action, data} 或 {ok:false, error_class, error, detail}。
 param(
     [Parameter(Mandatory = $true)]
-    [ValidateSet("open", "read", "write", "version", "connect", "poll", "close", "raw", "vbrt", "run", "flash")]
+    [ValidateSet("open", "read", "write", "version", "connect", "poll", "close", "raw", "vbrt", "run", "flash", "stream")]
     [string]$Action,
 
     [string]$DllDir,
@@ -440,6 +440,126 @@ try {
             Write-Output (@{ ok = $true; action = "flash"; data = @{ verify = "pass"; pages_written = $wTotal; read_windows = $rTotal } } | ConvertTo-Json -Compress -Depth 4)
             exit 0
         }
+        "stream" {
+            # 高速连续采集 (只读): 单桥进程长驻 USB 会话, 循环内只做 I2C 事务 + sleep——
+            # 消除逐帧 spawn 的冷启动开销 (进程+DLL+USB 会话 ≈2s), 单帧开销 = 一次 StreamI2C 事务。
+            # stdin JSON: {"regs":[{"addr":238,"len":8,"name":"ch"},...],"interval_ms":100,
+            #              "duration_s":10,"max_frames":0,"retry":2,"fail_threshold":50,
+            #              "require_target":false}
+            # 输出行协议 (tab 分隔, 全 ASCII, Python 端逐行消费写 CSV):
+            #   #F\t<frame>\t<t_rel_ms>\t<reg>\t<hex|- >\t<tag>   每寄存器一行 (tag: OK/FF_GAP/IO_FAIL)
+            #   末行 JSON: {ok, action:"stream", data:{frames_ok, frames_ff_gap, frames_io_fail,
+            #              frames_total, aborted, abort_reason, duration_actual_ms}}
+            # 帧语义 (提案 §4.2): OK=读成功且非全FF; FF_GAP=读成功但全FF (总线高阻特征, 只统计不熔断);
+            #   IO_FAIL=重试后仍 StreamI2C=false, 连续计数, 达 fail_threshold 熔断 (优雅收尾保留已采数据)。
+            $cfgJson = [Console]::In.ReadToEnd()
+            $cfg = $cfgJson | ConvertFrom-Json
+            if (-not $cfg) { Fail "CONFIG_ERROR" "stream 需要 stdin 传入配置 JSON" $null }
+            $sRegs = @($cfg.regs)
+            if ($sRegs.Count -eq 0) { Fail "CONFIG_ERROR" "stream regs 为空" $null }
+            $sInterval = if ($null -ne $cfg.interval_ms) { [int]$cfg.interval_ms } else { 100 }
+            $sDurationS = [double]$cfg.duration_s
+            $sMaxFrames = if ($null -ne $cfg.max_frames) { [int]$cfg.max_frames } else { 0 }
+            $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
+            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 }
+            }
+
+            [Console]::OutputEncoding = [System.Text.Encoding]::UTF8
+            $sw = [System.Diagnostics.Stopwatch]::StartNew()
+            $h = Open-Device 0   # 打不开 -> Fail PROBE_NOT_FOUND (发生在任何 #F 行之前)
+
+            if ($sRequireTarget) {
+                $tb = New-Object byte[] 2
+                $tb[0] = [byte]$SlaveAddr; $tb[1] = 0x10
+                $vb = New-Object byte[] 4
+                $verOk = $false
+                for ($vt = 0; $vt -le $sRetry; $vt++) {
+                    if ((Invoke-WriteRead $h $tb $vb)) {
+                        $meaningful = $false
+                        foreach ($b in $vb) { if ($b -ne 0 -and $b -ne 0xFF) { $meaningful = $true; break } }
+                        if ($meaningful) { $verOk = $true; break }
+                    }
+                    Start-Sleep -Milliseconds 100
+                }
+                if (-not $verOk) {
+                    [STDataCollection.Icb]::USBIO_CloseDevice([uint32]0) | Out-Null
+                    Fail "TARGET_MISMATCH" "stream 起始探测失败 (0x10 无有效应答); 检查接线/上拉/供电/地址, 或去掉 require_target" $null
+                }
+            }
+
+            $framesOk = 0; $framesGap = 0; $framesIoFail = 0
+            $frameNo = 0
+            $consecIoFail = 0
+            $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"
+                    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 = "IO_FAIL"; $hexOut = "-"
+                                if ($attempt -lt $sRetry) { Start-Sleep -Milliseconds 5 }
+                            }
+                        }
+                    } catch {
+                        # 单寄存器异常降级为 IO_FAIL 行继续采集, 不作废整个 stream (fail-closed 韧性)
+                        $tag = "IO_FAIL"; $hexOut = "-"
+                    }
+                    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()
+                }
+                if ($hasIoFail) { $framesIoFail++; $consecIoFail++ }
+                else {
+                    if ($hasGap) { $framesGap++ } else { $framesOk++ }
+                    $consecIoFail = 0   # 读成功帧 (OK/FF_GAP) 重置连续失败计数
+                }
+                if ($sFailThr -gt 0 -and $consecIoFail -ge $sFailThr) { $aborted = $true; $abortReason = "fail_threshold"; break }
+                if ($sMaxFrames -gt 0 -and $frameNo -ge $sMaxFrames) { break }
+                $elapsedMs = $sw.Elapsed.TotalMilliseconds
+                if ($sDurationS -gt 0 -and $elapsedMs -ge $durationMsTotal) { break }
+                if ($sDurationS -gt 0) {
+                    $wait = $sInterval - ($elapsedMs - $frameStartMs)
+                    if ($wait -gt 0) { Start-Sleep -Milliseconds ([int]$wait) }
+                }
+            }
+            [STDataCollection.Icb]::USBIO_CloseDevice([uint32]0) | Out-Null
+            $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;
+                duration_actual_ms = [int]$sw.Elapsed.TotalMilliseconds } }
+            [Console]::WriteLine(($sum | ConvertTo-Json -Compress -Depth 5))
+            [Console]::Out.Flush()
+            exit 0
+        }
     }
 } catch {
     Fail "UNKNOWN_ERROR" "bridge 异常: $($_.Exception.Message)" $_.ScriptStackTrace

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

@@ -9,9 +9,11 @@ import argparse
 import json
 import os
 import sys
+from datetime import datetime
 
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-from lib.ndtdbg import ChipSeaFxx, NdtBoxError, NdtBoxIo  # noqa: E402
+from lib.ndtdbg import (ChipSeaFxx, NdtBoxError, NdtBoxIo, decode_payload,  # noqa: E402
+                        interval_stats, parse_reg_spec)
 
 sys.stdout.reconfigure(encoding="utf-8", errors="replace")
 
@@ -195,6 +197,112 @@ def cmd_poll(io: NdtBoxIo, duration_ms: int, interval_ms: int, max_frames: int,
     ok("poll", result, log=f"poll({duration_ms}ms, {interval_ms}ms): {len(frames)} frames")
 
 
+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:
+    """高速连续采集 (只读): 桥进程内长驻 USB 会话, 单帧开销 = 一次 I2C 事务。
+
+    帧语义: OK / FF_GAP (读成功但全 FF, 总线高阻特征, 只统计不熔断) /
+    IO_FAIL (重试后仍无应答, 连续计数达 fail_threshold 熔断)。Ctrl+C 优雅收尾,
+    CSV 已采数据保留, summary 标记 aborted。
+    """
+    # 默认值: lab.yaml ndtdbg.stream 段可覆盖内置默认 (均有默认值, 非必填)
+    stream_cfg = (config.get("ndtdbg") or {}).get("stream") or {}
+    if interval_ms is None:
+        interval_ms = int(stream_cfg.get("default_interval_ms", 100))
+    if fail_threshold is None:
+        fail_threshold = int(stream_cfg.get("fail_threshold", 50))
+    if duration_s <= 0 and max_frames <= 0:
+        fail("CONFIG_ERROR", "stream 需要 --duration-s 或 --max-frames 之一 > 0",
+             detail=f"duration_s={duration_s}, max_frames={max_frames}")
+
+    if not out_path:
+        out_path = os.path.join("lab", "streams",
+                                datetime.now().strftime("ndtdbg_stream_%Y%m%d_%H%M%S.csv"))
+    abs_out = os.path.abspath(out_path)
+    windir = os.environ.get("WINDIR", r"C:\Windows")
+    if abs_out.lower().startswith(windir.lower() + os.sep):
+        fail("CONFIG_ERROR", "输出路径拒绝写入系统目录", abs_out)
+    out_dir = os.path.dirname(abs_out)
+    if out_dir:
+        os.makedirs(out_dir, exist_ok=True)
+
+    spec = {
+        "regs": [{"addr": s["addr"], "len": s["len"], "name": s["name"]} for s in specs],
+        "interval_ms": interval_ms, "duration_s": float(duration_s), "max_frames": max_frames,
+        "retry": retry, "fail_threshold": fail_threshold, "require_target": require_target,
+    }
+
+    rows = {"ok": 0, "FF_GAP": 0, "IO_FAIL": 0}   # 行级计数 (Ctrl+C 时桥内帧级统计丢失, 以此近似)
+    frame_times: list = []                         # 帧完成 t_rel_ms 序列 (间隔统计)
+    state = {"frame": None, "t": None}
+
+    fh = open(abs_out, "w", encoding="utf-8", newline="")
+    try:
+        header = "frame,timestamp_iso,t_rel_ms,reg,raw_hex"
+        if decode != "hex":
+            header += "," + ",".join(f"{s['name']}_decoded" for s in specs)
+        fh.write(header + "\n")
+
+        def on_row(parts: list) -> None:
+            # 桥行协议: '#F', frame, t_rel_ms, reg, hex|'-', tag (hex 已空格分隔, 直接透传)
+            frame = int(parts[1]); t_rel = float(parts[2])
+            reg = parts[3]; hexs = parts[4]; tag = parts[5] if len(parts) > 5 else "OK"
+            line = (f"{frame},{datetime.now().isoformat(timespec='milliseconds')},"
+                    f"{t_rel:g},{reg},{hexs}")
+            if decode != "hex":
+                line += "," + (decode_payload(hexs, decode) or "")
+            if tag != "OK":
+                line += f";{tag}"
+            fh.write(line + "\n")
+            if frame != state["frame"]:
+                if state["t"] is not None:
+                    frame_times.append(state["t"])
+                state["frame"] = frame
+            state["t"] = t_rel
+            rows[tag] = rows.get(tag, 0) + 1
+
+        try:
+            data = io.stream_run(spec, on_row=on_row)
+        except KeyboardInterrupt:
+            data = None   # 桥被终止; 行级计数近似, CSV 已写数据保留
+    finally:
+        fh.close()
+
+    if state["t"] is not None:
+        frame_times.append(state["t"])
+    total = data.get("frames_total") if data else sum(rows.values())
+    summary = {
+        "csv_path": abs_out,
+        "frames_ok": data.get("frames_ok", rows["ok"]) if data else rows["ok"],
+        "frames_ff_gap": data.get("frames_ff_gap", rows["FF_GAP"]) if data else rows["FF_GAP"],
+        "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,
+        "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))
+    if decode != "hex":
+        summary["decode"] = decode
+
+    if summary["aborted"] and summary["abort_reason"] == "fail_threshold":
+        # 熔断: Fail-Closed 错误信封, 但 data 携带已采数据 summary
+        print(json.dumps({
+            "schema": "ndtdbg-result/v1", "ok": False, "error_class": "STREAM_ABORTED",
+            "error": f"连续 IO_FAIL 达到熔断阈值 {fail_threshold}, 已采数据保留于 CSV",
+            "data": summary,
+        }, ensure_ascii=False))
+        sys.exit(1)
+    payload = {"schema": "ndtdbg-result/v1", "ok": True, "action": "stream", "data": summary}
+    if data is None:
+        payload["log"] = "用户中断, 已采数据保留"
+    print(json.dumps(payload, ensure_ascii=False))
+    sys.exit(0)
+
+
 def cmd_flash_bin(io: NdtBoxIo, config: dict, file_path: str, erase_ms: int, confirm: bool) -> None:
     # 烧录 = 整片擦除 + 页写, 破坏性高于 write-reg, 同款双闸门
     allowed = (config.get("ndtdbg") or {}).get("write_allowed", False)
@@ -249,6 +357,26 @@ def build_parser() -> argparse.ArgumentParser:
     f.add_argument("--file", required=True,
                    help="固件文件 (.bin 自动 128 对齐补 0xFF; .nfw 去 256 头)")
     f.add_argument("--erase-ms", type=int, default=2000, help="擦除等待 ms (对齐原厂 2000)")
+
+    st = sub.add_parser("stream", parents=[common],
+                        help="高速连续采集寄存器组到 CSV (单会话长驻, 只读)")
+    st.add_argument("--regs", nargs="+", default=["0xEE:8"],
+                    help="寄存器 spec addr:len[:name], 如 0xEE:8:ch 0x20:138:event")
+    st.add_argument("--interval-ms", type=int, default=None,
+                    help="目标采样间隔 ms (默认 lab.yaml ndtdbg.stream.default_interval_ms 或 100)")
+    st.add_argument("--duration-s", type=float, default=0,
+                    help="采集总时长秒 (与 --max-frames 至少一个 > 0)")
+    st.add_argument("--max-frames", type=int, default=0,
+                    help="达到 N 帧后停止 (与 --duration-s 二选一)")
+    st.add_argument("--out", help="CSV 输出路径 (默认 lab/streams/ndtdbg_stream_<ts>.csv)")
+    st.add_argument("--decode", choices=["hex", "int16le", "uint16le", "int8", "uint8"],
+                    default="hex", help="decoded 附加列的解码模式 (默认仅 raw hex)")
+    st.add_argument("--retry", type=int, default=2,
+                    help="每帧每寄存器重试次数 (全 FF / IO 错误, 默认 2)")
+    st.add_argument("--fail-threshold", type=int, default=None,
+                    help="连续 IO_FAIL 熔断阈值 (默认 lab.yaml ndtdbg.stream.fail_threshold 或 50; 0=不熔断)")
+    st.add_argument("--require-target", action="store_true",
+                    help="采集前探测 0x10, 无有效芯片应答则 TARGET_MISMATCH")
     return p
 
 
@@ -273,6 +401,11 @@ def main(argv=None) -> None:
             cmd_poll(io, args.duration_ms, args.interval_ms, args.max_frames, args.full)
         elif args.cmd == "flash-bin":
             cmd_flash_bin(io, config, args.file, args.erase_ms, args.confirm)
+        elif args.cmd == "stream":
+            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)
         else:  # pragma: no cover
             fail("CONFIG_ERROR", f"unknown cmd: {args.cmd}")
     except NdtBoxError as exc:

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

@@ -1,6 +1,6 @@
 <#
 .SYNOPSIS
-    Dual-Tier MCP setup and registration helper (v0.1.9).
+    Dual-Tier MCP setup and registration helper (v0.2.1).
     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.1.9)" -ForegroundColor Green
+    Write-Host "  FirmwareLoop Dual-Tier MCP & Agent Setup Helper (v0.2.1)" -ForegroundColor Green
     Write-Host "============================================================" -ForegroundColor Cyan
     Write-Host ""
     Write-Host "[1] Google Antigravity / Gemini CLI:" -ForegroundColor Yellow