firmwareloop 0.6.0__tar.gz → 0.6.1__tar.gz

{firmwareloop-0.6.0 → firmwareloop-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: firmwareloop
-Version: 0.6.0
+Version: 0.6.1
 Summary: AI Agent Firmware Development and Lab Automation Platform (Dual-Tier MCP Server)
 Author-email: WeilinZhang <19523330249@163.com>
 License: MIT
@@ -382,7 +382,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.6.0)
+├── pyproject.toml    标准 Python 包配置与 CLI 入口声明 (v0.6.1)
 ├── .mcp.example.json 双层 MCP 配置模板（firmwareloop + agentic-hil）
 ├── AGENTS.md         通用智能体规范（Antigravity / Qoder / Cursor 等）
 ├── CLAUDE.md         Claude Code CLI 指南
@@ -392,7 +392,7 @@ claude mcp remove --scope user agentic-hil
 
 ---
 
-## 能力验证状态（v0.6.0）
+## 能力验证状态（v0.6.1）
 
 > 状态定义：`Implemented`（已实现）/ `Simulator Validated`（模拟验证）/
 > `Real Hardware Validated`（真机验证）/ `Experimental` / `Not Implemented`

{firmwareloop-0.6.0 → firmwareloop-0.6.1}/README.md

@@ -354,7 +354,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.6.0)
+├── pyproject.toml    标准 Python 包配置与 CLI 入口声明 (v0.6.1)
 ├── .mcp.example.json 双层 MCP 配置模板（firmwareloop + agentic-hil）
 ├── AGENTS.md         通用智能体规范（Antigravity / Qoder / Cursor 等）
 ├── CLAUDE.md         Claude Code CLI 指南
@@ -364,7 +364,7 @@ claude mcp remove --scope user agentic-hil
 
 ---
 
-## 能力验证状态（v0.6.0）
+## 能力验证状态（v0.6.1）
 
 > 状态定义：`Implemented`（已实现）/ `Simulator Validated`（模拟验证）/
 > `Real Hardware Validated`（真机验证）/ `Experimental` / `Not Implemented`

{firmwareloop-0.6.0 → firmwareloop-0.6.1}/firmwareloop.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: firmwareloop
-Version: 0.6.0
+Version: 0.6.1
 Summary: AI Agent Firmware Development and Lab Automation Platform (Dual-Tier MCP Server)
 Author-email: WeilinZhang <19523330249@163.com>
 License: MIT
@@ -382,7 +382,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.6.0)
+├── pyproject.toml    标准 Python 包配置与 CLI 入口声明 (v0.6.1)
 ├── .mcp.example.json 双层 MCP 配置模板（firmwareloop + agentic-hil）
 ├── AGENTS.md         通用智能体规范（Antigravity / Qoder / Cursor 等）
 ├── CLAUDE.md         Claude Code CLI 指南
@@ -392,7 +392,7 @@ claude mcp remove --scope user agentic-hil
 
 ---
 
-## 能力验证状态（v0.6.0）
+## 能力验证状态（v0.6.1）
 
 > 状态定义：`Implemented`（已实现）/ `Simulator Validated`（模拟验证）/
 > `Real Hardware Validated`（真机验证）/ `Experimental` / `Not Implemented`

{firmwareloop-0.6.0 → firmwareloop-0.6.1}/pyproject.toml

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

{firmwareloop-0.6.0 → firmwareloop-0.6.1}/tools/__init__.py

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

{firmwareloop-0.6.0 → firmwareloop-0.6.1}/tools/doctor.ps1

@@ -129,28 +129,110 @@ Add-FwCheck 'pyvisa' {
 }
 
 # COM ports present (UART candidates) - informational, never hardcoded.
-# Prefer Agentic HIL's enumeration (hardware-aware) when installed, else WMI.
+# P2-1: agentic-hil 优先, 兜底改用 pyserial comports (SetupAPI, 覆盖 CH341/CP210x/
+# FTDI 等 USB 适配器; Win32_SerialPort 在 Windows 上常漏报 USB CDC/厂商适配器,
+# 实战漏掉真实 DUT 口 COM3 (USB-SERIAL CH341) 导致 agent 误开蓝牙虚拟口)。
+# 输出带 description 并对蓝牙/虚拟口打标记排序 (真实口在前, 防 agent 首选错口)。
 Add-FwCheck 'com_ports' {
     $comPorts = @()
+    $portDetails = @()
+    $source = 'none'
     $ahil = if ($venvBin) { Join-Path $venvBin 'agentic-hil.exe' } else { $null }
     if ($ahil -and (Test-Path -LiteralPath $ahil)) {
         try {
             $raw = & $ahil com-ports 2>$null | Out-String
             $parsed = $raw | ConvertFrom-Json -ErrorAction SilentlyContinue
             if ($parsed -and $parsed.ports) {
-                $comPorts = @($parsed.ports | ForEach-Object { $_.device } | Where-Object { $_ })
+                $portDetails = @($parsed.ports | ForEach-Object {
+                    [pscustomobject]@{ device = [string]$_.device; description = [string]$_.description }
+                } | Where-Object { $_.device })
+                $comPorts = @($portDetails | ForEach-Object { $_.device })
+                $source = 'agentic-hil'
+            }
+        } catch { }
+    }
+    if ($comPorts.Count -eq 0 -and $python) {
+        try {
+            $pyCode = "import json; from serial.tools.list_ports import comports; print(json.dumps([{'device': p.device, 'description': (p.description or '')} for p in comports()]))"
+            $raw = & $python -c $pyCode 2>$null | Out-String
+            $parsed = $raw | ConvertFrom-Json -ErrorAction SilentlyContinue
+            if ($parsed) {
+                $portDetails = @($parsed | ForEach-Object {
+                    [pscustomobject]@{ device = [string]$_.device; description = [string]$_.description }
+                } | Where-Object { $_.device })
+                $comPorts = @($portDetails | ForEach-Object { $_.device })
+                $source = 'pyserial'
             }
         } catch { }
     }
     if ($comPorts.Count -eq 0) {
         try {
             $comPorts = @((Get-CimInstance Win32_SerialPort -ErrorAction SilentlyContinue | Select-Object -ExpandProperty DeviceID))
+            $source = 'wmi'
         } catch { }
     }
+    # 虚拟/蓝牙口标记 + 真实口优先排序
+    $isVirtual = { param($d) $d -match '(?i)bluetooth|蓝牙|virtual|modem|debug port' }
+    $real = @($portDetails | Where-Object { -not (& $isVirtual $_.description) })
+    $virt = @($portDetails | Where-Object { & $isVirtual $_.description })
+    $ordered = @(@($real | ForEach-Object { $_.device }) + @($virt | ForEach-Object { $_.device }))
+    if ($ordered.Count -gt 0) { $comPorts = $ordered }
+    [pscustomobject]@{
+        status        = if ($comPorts.Count -gt 0) { 'ok' } else { 'none' }
+        source        = $source
+        ports         = $comPorts
+        port_details  = @($portDetails)
+        virtual_ports = @($virt | ForEach-Object { $_.device })
+        note          = '排序: 真实串口在前; 蓝牙/虚拟口仅供参考 (无法访问 DUT)'
+    }
+}
+
+# P1-4: lab.yaml 配置链透明度——枚举全局/项目两层 ndtdbg 段存在性与
+# write_allowed 状态; 任何层 write_allowed: true 输出 WARNING
+# (global 层常驻 true 属危险默认; 项目层 false 不代表安全——合并链会回退全局层)。
+Add-FwCheck 'lab_yaml' {
+    if (-not $python) {
+        return [pscustomobject]@{ status = 'missing'; detail = 'no python' }
+    }
+    $pyCode = @'
+import json, os
+try:
+    import yaml
+except ImportError:
+    yaml = None
+def sec(p):
+    try:
+        with open(p, encoding="utf-8") as fh:
+            d = (yaml.safe_load(fh) if yaml else json.load(fh)) or {}
+    except Exception:
+        return {"parse_error": True}
+    s = d.get("ndtdbg") if isinstance(d, dict) else None
+    return s if isinstance(s, dict) else {}
+out = []
+ad = os.environ.get("APPDATA")
+if ad:
+    p = os.path.join(ad, "FirmwareLoop", "lab.yaml")
+    n = sec(p)
+    out.append({"layer": "global", "path": p, "exists": os.path.isfile(p),
+                "ndtdbg": bool(n), "write_allowed": n.get("write_allowed")})
+pp = os.path.join(os.getcwd(), "lab", "lab.yaml")
+n2 = sec(pp)
+out.append({"layer": "project", "path": pp, "exists": os.path.isfile(pp),
+            "ndtdbg": bool(n2), "write_allowed": n2.get("write_allowed")})
+print(json.dumps(out))
+'@
+    $raw = & $python -c $pyCode 2>$null | Out-String
+    $layers = @($raw | ConvertFrom-Json -ErrorAction SilentlyContinue)
+    $warned = @($layers | Where-Object { $_.write_allowed -eq $true })
     [pscustomobject]@{
-        status = if ($comPorts.Count -gt 0) { 'ok' } else { 'none' }
-        source = if ($ahil -and (Test-Path -LiteralPath $ahil)) { 'agentic-hil' } else { 'wmi' }
-        ports  = $comPorts
+        status = if ($warned.Count -gt 0) { 'warn' } else { 'ok' }
+        detail = if ($warned.Count -gt 0) {
+            ($warned | ForEach-Object {
+                $tip = if ($_.layer -eq 'global') { '常驻 true 属危险默认 (会话级临时态, 用完即关)' } else { '项目层开启须用完即关' }
+                "$($_.layer) 层 write_allowed=true ($tip)"
+            }) -join '; '
+        } else { '任何层均未开启 write_allowed (写保护生效)' }
+        layers = @($layers)
     }
 }
 

{firmwareloop-0.6.0 → firmwareloop-0.6.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.6.0).
+fw_mcp_server.py - FirmwareLoop High-Level Workflow & Device MCP Server (v0.6.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
@@ -329,7 +329,11 @@ def handle_fw_ndtdbg_write_reg(args: Dict[str, Any]) -> Dict[str, Any]:
 
 
 def handle_fw_ndtdbg_flash(args: Dict[str, Any]) -> Dict[str, Any]:
-    """Erase + flash a .bin/.nfw image onto the NdtBox target chip (ChipSea Fxx) over IIC."""
+    """Erase + flash a .bin/.nfw image onto the NdtBox target chip (ChipSea Fxx) over IIC.
+
+    P1-1: retry 参数 (默认 1) —— 命中 "TARGET_MISMATCH @0x0000" (未进 boot 的特征
+    签名: 校验读到旧向量表) 自动重试; BOOT_NOT_ENTERED 不重试 (需人工断电, 直接给指引)。
+    """
     cli_script = os.path.join(REPO_ROOT, "tools", "ndtdbg_cli.py")
     cmd = [PYTHON_EXE, cli_script, "flash-bin", "--file", str(args.get("file_path")),
            "--erase-ms", str(int(args.get("erase_ms", 2000)))]
@@ -337,7 +341,25 @@ def handle_fw_ndtdbg_flash(args: Dict[str, Any]) -> Dict[str, Any]:
         cmd.append("--confirm")
     _ndtdbg_reg_args(args, cmd)
     timeout_s = min(max(int(args.get("timeout_seconds", 300)), 30), 900)
-    return _ndtdbg_run(cmd, timeout_s)
+    retry = max(0, int(args.get("retry", 1)))
+    result: Dict[str, Any] = {}
+    for attempt in range(retry + 1):
+        result = _ndtdbg_run(cmd, timeout_s)
+        data = result.get("data") if isinstance(result.get("data"), dict) else None
+        if not data:
+            return result   # 无 CLI JSON body: 原样返回 (兼容 mock/异常输出)
+        if data.get("ok"):
+            if attempt:
+                data["retry_count"] = attempt
+            return data
+        err_text = f"{data.get('error', '')} {data.get('detail', '')}"
+        err_cls = data.get("error_class")
+        if err_cls == "BOOT_NOT_ENTERED":
+            return data   # 需人工断电重启, 重试无意义
+        if err_cls == "TARGET_MISMATCH" and "@0x0000" in err_text and attempt < retry:
+            continue   # 未进 boot 特征签名: 自动重试
+        return data
+    return result
 
 
 def _stream_cli_cmd(args: Dict[str, Any], out_path: str, duration_cap: float) -> Optional[list]:
@@ -694,36 +716,171 @@ def handle_fw_get_evidence(args: Dict[str, Any]) -> Dict[str, Any]:
     }
 
 
+def _render_fwloop_tools_markdown(indent: str = "  ") -> str:
+    """P1-5: AGENTS.md/SKILL.md 工具清单从 TOOLS_REGISTRY 自动渲染 (消除手写漂移)。
+    渲染条数恒等于注册表条数 (当前 30), 与 tools/list 完全一致。"""
+    lines = []
+    for name, info in TOOLS_REGISTRY.items():
+        desc = (info.get("description") or "").strip()
+        first = desc.split(". ")[0].strip().rstrip(".")
+        lines.append(f"{indent}- `{name}()`: {first}.")
+    return "\n".join(lines)
+
+
+def _detect_hardware() -> Dict[str, Any]:
+    """P1-5: init 硬件探测 (全部 best-effort, 探测不到不猜——fail-closed)。
+
+    - COM 口: pyserial comports (SetupAPI, 带 description, CH341/CP210x/FTDI 全覆盖);
+    - NdtBox USB: hidapi 枚举 WCH(0x1A86) 厂商设备 (agentic-hil 依赖链自带 hidapi);
+    - NdtDebugTool 路径: 常见位置 (用户根/Desktop/Downloads/C:\\/D:\\ 1-2 层)
+      扫描 NdtDebugTool*/lib/USBIOX.DLL, 命中即预填 ndtdbg.dll_dir。
+    """
+    detected: Dict[str, Any] = {"com_ports": [], "ndtbox_hid": None,
+                                "ndtdbg_dll_dir": None, "notes": []}
+    try:
+        from serial.tools.list_ports import comports
+        detected["com_ports"] = [{"device": p.device, "description": (p.description or "")}
+                                 for p in comports()]
+    except Exception as exc:  # noqa: BLE001
+        detected["notes"].append(f"pyserial COM 枚举不可用: {exc}")
+    try:
+        import hid
+        for d in hid.enumerate(vendor_id=0x1A86):   # WCH (CH341) 厂商 ID
+            prod = str(d.get("product") or "")
+            if "CH341" in prod.upper() or "NDT" in prod.upper():
+                detected["ndtbox_hid"] = {"vendor_id": "0x1A86", "product": prod,
+                                          "serial": d.get("serial_number")}
+                break
+    except Exception:  # noqa: BLE001
+        detected["notes"].append("hidapi 不可用, 跳过 NdtBox USB 枚举 (不影响其余探测)")
+    import glob as _glob
+    cands: List[str] = []
+    roots: List[str] = []
+    profile = os.environ.get("USERPROFILE")
+    if profile:
+        roots += [profile, os.path.join(profile, "Desktop"), os.path.join(profile, "Downloads")]
+    roots += ["C:\\", "D:\\"]
+    for root in roots:
+        for pat in (os.path.join(root, "NdtDebugTool*", "lib", "USBIOX.DLL"),
+                    os.path.join(root, "*", "NdtDebugTool*", "lib", "USBIOX.DLL")):
+            try:
+                cands += _glob.glob(pat)
+            except Exception:  # noqa: BLE001
+                pass
+    if cands:
+        detected["ndtdbg_dll_dir"] = os.path.dirname(os.path.abspath(cands[0]))
+    else:
+        detected["notes"].append(
+            "常见位置未发现 NdtDebugTool*/lib/USBIOX.DLL——ndtdbg.dll_dir 需人工提供"
+            " (运行 fwloop ndtdebugtool \"<NdtDebugTool 根目录>\" 写入)")
+    return detected
+
+
+def _build_lab_yaml_from_example(target_dir: str, target_chip: str, build_backend: str,
+                                 detected_dll_dir: Optional[str]) -> str:
+    """P1-5: lab/lab.example.yaml 为唯一模板 (example 加段 init 自动跟上);
+    仅替换 project.name/target_chip/build_backend/source_dir 与 dut.uart.port
+    (留空 + 注释 "用 fw_scan_hardware 探测", 去掉硬编码 COM3);
+    ndtdbg.dll_dir 按探测结果预填, 探测不到保持注释态 + 人工指引。"""
+    example_path = os.path.join(REPO_ROOT, "lab", "lab.example.yaml")
+    with open(example_path, encoding="utf-8") as fh:
+        lines = fh.read().splitlines()
+    out: List[str] = []
+    in_project = False
+    for ln in lines:
+        if ln.startswith("project:"):
+            in_project = True
+            out.append(ln)
+            continue
+        if in_project:
+            if ln.startswith("  "):
+                stripped = ln.lstrip()
+                if stripped.startswith("name:"):
+                    out.append(f'  name: "{os.path.basename(target_dir)}"')
+                    out.append(f'  target_chip: "{target_chip}"')
+                elif stripped.startswith("build_backend:"):
+                    out.append(f'  build_backend: "{build_backend}"')
+                elif stripped.startswith("source_dir:"):
+                    out.append('  source_dir: "."')
+                else:
+                    out.append(ln)
+                continue
+            in_project = False
+        if ln.startswith("    port: COM5"):
+            out.append("    port: null                       # 用 fw_scan_hardware 探测后填入 (勿猜)")
+            continue
+        if ln.startswith('  dll_dir: "C:/path/to/NdtDebugTool/lib"'):
+            if detected_dll_dir:
+                # YAML 双引号标量内反斜杠是转义字符, 统一正斜杠
+                posix = str(detected_dll_dir).replace("\\", "/")
+                out.append(f'  dll_dir: "{posix}"   # init 探测预填, 请核对')
+            else:
+                out.append('  dll_dir: null                    # TODO: 需人工提供 (fwloop ndtdebugtool "<NdtDebugTool 根目录>")')
+            continue
+        out.append(ln)
+    return "\n".join(out) + "\n"
+
+
+def _upgrade_lab_yaml(existing_path: str) -> List[str]:
+    """P1-5 upgrade: 非破坏合并——补齐 example 有而项目缺的顶层段与段内缺失键,
+    已有键一律不动 (治本: Demo_F71_4CH 这类旧项目停在旧形态的问题)。
+    返回新增段/键清单 (无新增返回空表, 文件不动)。"""
+    import yaml as _yaml
+    with open(existing_path, encoding="utf-8") as fh:
+        existing = _yaml.safe_load(fh) or {}
+    example_path = os.path.join(REPO_ROOT, "lab", "lab.example.yaml")
+    with open(example_path, encoding="utf-8") as fh:
+        example = _yaml.safe_load(fh) or {}
+    added: List[str] = []
+    for k, v in example.items():
+        if k not in existing:
+            existing[k] = v
+            added.append(k)
+        elif isinstance(v, dict) and isinstance(existing.get(k), dict):
+            for sk, sv in v.items():
+                if sk not in existing[k]:
+                    existing[k][sk] = sv
+                    added.append(f"{k}.{sk}")
+    if added:
+        body = _yaml.safe_dump(existing, allow_unicode=True, sort_keys=False,
+                               default_flow_style=False)
+        with open(existing_path, "w", encoding="utf-8") as fh:
+            fh.write("# FirmwareLoop lab.yaml (经 fwloop init upgrade 合并: 新增段/键取自\n")
+            fh.write("# lab.example.yaml 模板, 值请人工确认; 既有键保持原值未动)\n")
+            fh.write(body)
+    return added
+
+
 def handle_fw_init_project(args: Dict[str, Any]) -> Dict[str, Any]:
     """Scaffold multi-agent instruction files (AGENTS.md, CLAUDE.md, GEMINI.md), lab.yaml, and .mcp.json."""
     target_dir = args.get("target_dir", ".")
     target_dir = os.path.abspath(target_dir)
     os.makedirs(target_dir, exist_ok=True)
-    target_chip = args.get("target_chip", "STM32F103C8")
+    target_chip = args.get("target_chip")
     build_backend = args.get("build_backend", "keil")
     overwrite = args.get("overwrite", False)
+    upgrade = args.get("upgrade", False)
+    # P1-5: target_chip 必填 (fail-closed), 不再硬编码默认芯片
+    if not target_chip:
+        return {
+            "ok": False,
+            "error_class": "CONFIG_ERROR",
+            "error": "target_chip 必填 (如 STM32F103C8 / CSA37F71)",
+            "detail": "fwloop init <target_chip> 或 MCP fw_init_project(target_chip=...)",
+        }
 
     created_files = []
+    detected = _detect_hardware()
 
     # 1. AGENTS.md
     agents_path = os.path.join(target_dir, "AGENTS.md")
-    agents_content = """# AGENTS.md — Firmware Engineering & Lab Automation Guidelines
+    agents_content = f"""# AGENTS.md — Firmware Engineering & Lab Automation Guidelines
 
 This repository is configured with **FirmwareLoop (`fwloop`)** for AI Agent-driven firmware development, building, flashing, and hardware-in-the-loop (HIL) testing.
 
 ## Dual-Tier MCP Tools Available
-- **Upper-Tier (`fwloop`)**:
-  - `fw_doctor()`: Check compiler, Python, COM ports, and probe connectivity.
-  - `fw_configure_lab(project_name, build_backend, target_chip, uart_port)`: Interactively configure project settings in `lab/lab.yaml`.
-  - `fw_scan_hardware(adopt=false)`: Scan connected ST-LINK / J-Link / CMSIS-DAP probes and COM ports.
-  - `fw_build(backend="auto", configuration="Debug", clean=true)`: Build firmware across Keil5, CMake, Make, IAR, PlatformIO, etc.
-  - `fw_flash(backend="auto", artifact_path)`: Flash compiled firmware image into target MCU via ST-LINK or J-Link.
-  - `fw_reset(backend="auto")`: Hardware/software reset target MCU.
-  - `fw_run_hil_test()`: Run pytest automated hardware-in-the-loop test suite.
-  - `fw_measure(instrument_type, command)`: Safe PyVISA instrument measurement.
-  - `fw_logic_capture(protocol="i2c|spi|uart")` / `fw_logic_decode()`: Logic analyzer protocol capture & decode.
-  - `fw_get_evidence()`: Retrieve audit run artifacts and test evidence.
-  - `fw_init_project()`: Scaffold multi-agent instruction files and lab configurations.
+- **Upper-Tier (`fwloop`, {len(TOOLS_REGISTRY)} tools, auto-generated from MCP registry)**:
+{_render_fwloop_tools_markdown(indent='  ')}
 
 - **Lower-Tier (`agentic-hil`)**:
   - `probe_target()`, `flash_firmware()`, `reset_target()`, `com_session_*()`, `debug_*()`.
@@ -755,29 +912,19 @@ This repository is configured with **FirmwareLoop (`fwloop`)** for AI Agent-driv
             fh.write(gemini_content)
         created_files.append("GEMINI.md")
 
-    # 4. lab/lab.yaml
+    # 4. lab/lab.yaml (P1-5: lab.example.yaml 为唯一模板 + 硬件探测预填 + upgrade 合并)
     lab_dir = os.path.join(target_dir, "lab")
     os.makedirs(lab_dir, exist_ok=True)
     lab_yaml_path = os.path.join(lab_dir, "lab.yaml")
-    lab_yaml_content = f"""# FirmwareLoop Project & Hardware Bench Configuration
-schema: "firmwareloop-lab-config/v1"
-
-project:
-  name: "{os.path.basename(target_dir)}"
-  target_chip: "{target_chip}"
-  build_backend: "{build_backend}"
-  source_dir: "."
-
-hardware:
-  debugger_probe: "stlink"
-  probe_serial: "auto"
-  uart:
-    port: "COM3"
-    baudrate: 115200
-  power_supply:
-    default_voltage: 3.3
-"""
-    if not os.path.exists(lab_yaml_path) or overwrite:
+    lab_upgraded: List[str] = []
+    if os.path.exists(lab_yaml_path):
+        if upgrade:
+            lab_upgraded = _upgrade_lab_yaml(lab_yaml_path)
+            created_files.append("lab/lab.yaml (upgrade)")
+        # 既无 upgrade 也不 overwrite: 保留用户已有配置不动
+    else:
+        lab_yaml_content = _build_lab_yaml_from_example(
+            target_dir, str(target_chip), str(build_backend), detected.get("ndtdbg_dll_dir"))
         with open(lab_yaml_path, "w", encoding="utf-8") as fh:
             fh.write(lab_yaml_content)
         created_files.append("lab/lab.yaml")
@@ -805,7 +952,7 @@ hardware:
     skill_dir = os.path.join(target_dir, "skills", "firmwareloop")
     os.makedirs(skill_dir, exist_ok=True)
     skill_path = os.path.join(skill_dir, "SKILL.md")
-    skill_content = """---
+    skill_content = f"""---
 name: firmwareloop
 description: FirmwareLoop workflow skill for orchestrating firmware builds (Keil/CMake/Make/etc.), probe detection (ST-LINK/J-Link), interactive lab configuration, pytest HIL testing, I2C/SPI logic analyzer captures, PyVISA instrument measurements, and end-to-end hardware acceptance.
 ---
@@ -816,19 +963,8 @@ Use this skill when developing, building, testing, or diagnosing embedded firmwa
 
 ## Capabilities & Tools
 
-### Upper-Tier MCP Tools (`firmwareloop`)
-- `fw_doctor`: Run environmental health check.
-- `fw_configure_lab`: Interactively configure or update project parameters, target chip (e.g. STM32F103C8), build backend (e.g. keil), source directory, COM port, and debugger probe in `lab/lab.yaml`.
-- `fw_scan_hardware`: Scan and identify attached hardware debuggers (ST-LINK, J-Link, CMSIS-DAP) and COM ports.
-- `fw_build`: Compile firmware across 7 backends (Keil, CMake, Make, IAR, PlatformIO, Zephyr, ESP-IDF).
-- `fw_flash`: Flash compiled firmware image into target MCU.
-- `fw_reset`: Hardware or software reset of the target MCU.
-- `fw_run_hil_test`: Run 12-item pytest HIL automated testing.
-- `fw_acceptance_scenario`: Execute end-to-end acceptance scenario.
-- `fw_measure`: Query PyVISA/SCPI instrument readings (frequency, duty cycle, Vpp, voltage, current).
-- `fw_logic_capture` / `fw_logic_decode`: Digital protocol capture and verification (I2C, SPI, UART).
-- `fw_get_evidence`: Retrieve audit run artifacts and reports.
-- `fw_init_project`: Scaffold multi-agent instruction files and lab configurations.
+### Upper-Tier MCP Tools (`firmwareloop`, {len(TOOLS_REGISTRY)} tools, auto-generated from MCP registry)
+{_render_fwloop_tools_markdown(indent='')}
 
 ## Mandatory Rules
 1. **Real-Hardware-First & Zero Fake Data**: Never fake or mock hardware results. When compilers, debuggers, or MCU targets are missing, fail closed immediately and output explicit error diagnostics and user setup guidance.
@@ -994,6 +1130,8 @@ custom_tools:
         "ok": True,
         "target_dir": target_dir,
         "created_files": created_files,
+        "detected": detected,
+        "lab_upgrade_added": lab_upgraded,
         "message": f"Successfully initialized FirmwareLoop multi-agent files in {target_dir}"
     }
 
@@ -1188,7 +1326,9 @@ def handle_fw_serial_send(args: Dict[str, Any]) -> Dict[str, Any]:
 
 def handle_fw_serial_read(args: Dict[str, Any]) -> Dict[str, Any]:
     cmd = [PYTHON_EXE, SERIAL_CLI, "read", "--format", str(args.get("format", "both"))]
-    if args.get("max_bytes"):
+    if args.get("drain"):
+        cmd.append("--drain")
+    elif args.get("max_bytes"):
         cmd.extend(["--max-bytes", str(args["max_bytes"])])
     timeout_ms = int(args.get("timeout_ms", 2000))
     if args.get("expect"):
@@ -1619,6 +1759,11 @@ TOOLS_REGISTRY = {
                     "description": "CLI process timeout; budget ~30s per 64KB image (page writes paced at 30ms)",
                     "default": 300,
                 },
+                "retry": {
+                    "type": "integer",
+                    "description": "Auto-retries on TARGET_MISMATCH @0x0000 signature (target did not enter boot; verify read old vector table). BOOT_NOT_ENTERED never retries (manual power-cycle required). Result carries retry_count when a retry succeeded",
+                    "default": 1,
+                },
                 "dll_dir": {
                     "type": "string",
                     "description": "NdtDebugTool lib directory containing USBIOX.DLL and usb2io.dll; default from lab.yaml ndtdbg.dll_dir",
@@ -1871,7 +2016,7 @@ TOOLS_REGISTRY = {
         "handler": handle_fw_get_evidence,
     },
     "fw_init_project": {
-        "description": "Scaffold multi-agent instruction files (AGENTS.md, CLAUDE.md, GEMINI.md), lab.yaml bench config, and .mcp.json in the current or specified firmware project directory.",
+        "description": "Scaffold multi-agent instruction files (AGENTS.md, CLAUDE.md, GEMINI.md), lab.yaml bench config, and .mcp.json in the current or specified firmware project directory. lab.yaml is generated from lab.example.yaml (single template source) with hardware detection (COM ports / NdtBox HID / NdtDebugTool location) prefilling the ndtdbg section; upgrade=true non-destructively merges missing sections/keys into an existing lab.yaml.",
         "inputSchema": {
             "type": "object",
             "properties": {
@@ -1882,8 +2027,7 @@ TOOLS_REGISTRY = {
                 },
                 "target_chip": {
                     "type": "string",
-                    "description": "Target MCU chip model (e.g. STM32F103C8, STM32F407ZG)",
-                    "default": "STM32F103C8",
+                    "description": "Target MCU chip model (e.g. STM32F103C8, CSA37F71) - REQUIRED, no hardcoded default",
                 },
                 "build_backend": {
                     "type": "string",
@@ -1896,7 +2040,13 @@ TOOLS_REGISTRY = {
                     "description": "Whether to overwrite existing instruction files if present",
                     "default": False,
                 },
+                "upgrade": {
+                    "type": "boolean",
+                    "description": "Non-destructively merge missing sections/keys from lab.example.yaml into an EXISTING lab/lab.yaml (existing keys are never touched; added items come from the template and need manual confirmation)",
+                    "default": False,
+                },
             },
+            "required": ["target_chip"],
             "additionalProperties": False,
         },
         "handler": handle_fw_init_project,
@@ -1981,7 +2131,12 @@ TOOLS_REGISTRY = {
         "inputSchema": {
             "type": "object",
             "properties": {
-                "max_bytes": {"type": "integer", "description": "Max bytes to drain (default 65536)", "default": 65536},
+                "drain": {
+                    "type": "boolean",
+                    "description": "Drain the ENTIRE buffer in one call (>64KB payloads are written to a .hex file and only a summary + tail preview is returned, protecting the agent context from large dumps). Preferred over max_bytes when you just need everything received so far",
+                    "default": False,
+                },
+                "max_bytes": {"type": "integer", "description": "Max bytes to drain (default 65536; ignored when drain=true)", "default": 65536},
                 "expect": {
                     "type": "string",
                     "description": "Wait until this pattern appears in the stream (text; use expect_hex for byte patterns)",
@@ -2081,7 +2236,7 @@ def process_request(req: Dict[str, Any]) -> Optional[Dict[str, Any]]:
                 },
                 "serverInfo": {
                     "name": "firmwareloop",
-                    "version": "0.6.0"
+                    "version": "0.6.1"
                 }
             }
         }
@@ -2216,7 +2371,7 @@ def _settle_stashed_entrypoints(stashed) -> None:
 def handle_cli_update() -> int:
     """Handle `firmwareloop update` command."""
     print("============================================================")
-    print("  FirmwareLoop Auto-Updater (v0.6.0)")
+    print("  FirmwareLoop Auto-Updater (v0.6.1)")
     print("============================================================")
 
     is_git_repo = os.path.exists(os.path.join(REPO_ROOT, ".git"))
@@ -2285,6 +2440,38 @@ def handle_cli_update() -> int:
             return res.returncode
 
 
+def _selftest_protocol_desync() -> tuple:
+    """P0-1 回归检查 (selftest 1.5): echo/r 异构交替 20 次, 断言响应与请求一一对应。
+
+    真机在环时执行实际检查; 无硬件/无桥环境返回 SKIP (不算 FAIL)。
+    返回 (status, detail)。"""
+    try:
+        import types as _types
+        _tools_dir = os.path.join(REPO_ROOT, "tools")
+        if _tools_dir not in sys.path:
+            sys.path.insert(0, _tools_dir)
+        from lib import ndtdbg as _ndbg
+        import ndtdbg_cli as _cli
+        _cfg = _cli.load_config(None)
+        _io = _cli.resolve_io(_types.SimpleNamespace(dll_dir=None, slave_addr="0xA0",
+                                                     speed=1), _cfg)
+        _io.timeout_ms = min(_io.timeout_ms, 5000)
+        _sess = _ndbg.NdtBoxSession(_io)   # open + echo 握手 (失败即 PROTOCOL_DESYNC)
+        _mismatch = 0
+        for _i in range(20):
+            _tok = f"selftest{_i:02d}"
+            _ok, _payload = _sess._txn(f"echo {_tok}")
+            if not _ok or _payload != _tok:
+                _mismatch += 1
+            _sess.read_reg(0x10, 2)   # 异构读 (内容任意, 只验响应行对齐)
+        _sess.close()
+        return (("PASS", f"echo/r 交替 20 次, 回显不匹配 {_mismatch} 次") if _mismatch == 0
+                else ("FAIL", f"echo/r 交替 20 次, 回显不匹配 {_mismatch} 次 (协议错位!)"))
+    except Exception as exc:  # noqa: BLE001
+        _cls = getattr(exc, "error_class", type(exc).__name__)
+        return ("SKIP", f"需硬件在环: {_cls}: {str(exc)[:100]}")
+
+
 def handle_cli_selftest(target: str = "ndtdbg") -> int:
     """`fwloop selftest ndtdbg`: 按 BACKLOG 验收标准自动回归 (需硬件在环)。
 
@@ -2330,6 +2517,12 @@ def handle_cli_selftest(target: str = "ndtdbg") -> int:
     else:
         report("status", "FAIL", (body or {}).get("error_class", f"exit {rc}"))
 
+    # 1.5 协议握手 + echo/r 异构交替 (P0-1 错位回归): 同构纯读流对错位免疫,
+    # 必须含 echo(写型形态) 与 read(读型形态) 交替, 断言响应与请求一一对应。
+    print("[1.5/4] echo/r 异构交替 20 次 (P0-1 错位回归) ...")
+    _st, _detail = _selftest_protocol_desync()
+    report("protocol.desync", _st, _detail)
+
     # 2. stream 冒烟 (100ms x 10s)
     print("[2/4] stream 冒烟 (100ms x 10s, int16 解码) ...")
     rc, body = run_cli("stream", "--regs", "0xEE:8:ch", "--interval-ms", "100",
@@ -2609,7 +2802,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.6.0)")
+    print("  FirmwareLoop Multi-Agent Global Setup Helper (v0.6.1)")
     print("============================================================")
     print("")
 
@@ -2731,31 +2924,43 @@ def handle_cli_setup() -> int:
     return 0
 
 
-def handle_cli_init() -> int:
-    """Handle `firmwareloop init` command."""
+def handle_cli_init(chip: Optional[str] = None, upgrade: bool = False) -> int:
+    """Handle `firmwareloop init [target_chip]` command."""
     print("============================================================")
-    print("  FirmwareLoop Multi-Agent Project Initializer (v0.6.0)")
+    print("  FirmwareLoop Multi-Agent Project Initializer (v0.6.1)")
     print("============================================================")
     cwd = os.getcwd()
     print(f"[*] Initializing multi-agent guidelines & bench config in:\n    {cwd}\n")
-    res = handle_fw_init_project({"target_dir": cwd, "overwrite": False})
+    res = handle_fw_init_project({"target_dir": cwd, "overwrite": False,
+                                  "target_chip": chip, "upgrade": upgrade})
     if res.get("ok"):
         for f in res.get("created_files", []):
             print(f"  [+] Created: {f}")
         if not res.get("created_files"):
             print("  [*] All agent instruction files (AGENTS.md, CLAUDE.md, GEMINI.md, lab.yaml, .mcp.json) already exist.")
+        det = res.get("detected") or {}
+        if det.get("com_ports"):
+            print(f"  [i] Detected COM ports: {', '.join(p['device'] + (' (' + p['description'] + ')' if p.get('description') else '') for p in det['com_ports'])}")
+        if det.get("ndtdbg_dll_dir"):
+            print(f"  [i] NdtDebugTool located: {det['ndtdbg_dll_dir']} (ndtdbg.dll_dir 已预填)")
+        for n in det.get("notes", []):
+            print(f"  [!] {n}")
+        if res.get("lab_upgrade_added"):
+            print(f"  [+] lab.yaml upgrade 补齐: {', '.join(res['lab_upgrade_added'])} (值请人工确认)")
         print("")
         print("============================================================")
         print("[+] Done! All AI Coding Agents (Claude Code, Qoder, Antigravity, CodeBuddy, Cursor) are now ready to operate in this repository.")
         print("============================================================")
         return 0
     else:
-        print(f"[-] Initialization failed: {res.get('message')}")
+        print(f"[-] Initialization failed: {res.get('message') or res.get('error')}")
+        if res.get("detail"):
+            print(f"    {res['detail']}")
         return 1
 
 
 def print_cli_help() -> None:
-    print("""FirmwareLoop (fwloop) — AI Agent Firmware Engineering & Lab Automation Platform (v0.6.0)
+    print("""FirmwareLoop (fwloop) — AI Agent Firmware Engineering & Lab Automation Platform (v0.6.1)
 
 Usage:
   fwloop [command]   (or: firmwareloop [command])
@@ -2781,7 +2986,10 @@ def main() -> None:
     if args:
         cmd = args[0].lower().strip()
         if cmd in ["init", "scaffold"]:
-            sys.exit(handle_cli_init())
+            chip = args[1] if len(args) > 1 else None
+            do_upgrade = any(a in ("-u", "--upgrade") for a in args[1:])
+            chip = next((a for a in args[1:] if not a.startswith("-")), None)
+            sys.exit(handle_cli_init(chip=chip, upgrade=do_upgrade))
         elif cmd in ["update", "upgrade"]:
             sys.exit(handle_cli_update())
         elif cmd in ["doctor", "check"]:
@@ -2798,7 +3006,7 @@ def main() -> None:
                 sys.exit(2)
             sys.exit(handle_cli_ndtdebugtool(args[1]))
         elif cmd in ["version", "-v", "--version"]:
-            print("FirmwareLoop v0.6.0")
+            print("FirmwareLoop v0.6.1")
             sys.exit(0)
         elif cmd in ["help", "-h", "--help"]:
             print_cli_help()

{firmwareloop-0.6.0 → firmwareloop-0.6.1}/tools/lib/ndtdbg.py

@@ -325,7 +325,7 @@ class NdtBoxIo:
     def session(self):
         """持久 serve 会话上下文: 块内的 read_reg/write_reg/raw_write_read/vbrt_reset
         复用同一 32 位桥进程与 USB 会话; 退出自动关闭。"""
-        sess = NdtBoxSession(self)
+        sess = self._get_live_sess()
         self._persistent = sess
         try:
             yield sess
@@ -333,10 +333,23 @@ class NdtBoxIo:
             self._persistent = None
             sess.close()
 
+    def _get_live_sess(self):
+        """P2-2: 取活跃会话; 事务超时失效 (_dead) 的旧会话惰性重建——使 BUS_TIMEOUT
+        文案 "请重试 (将自动重建会话)" 成真 (重建即新 spawn serve 桥, 含 echo 握手)。"""
+        if self._persistent is not None and getattr(self._persistent, "_dead", False):
+            try:
+                self._persistent.close()
+            except Exception:
+                pass
+            self._persistent = None
+        if self._persistent is None:
+            self._persistent = NdtBoxSession(self)
+        return self._persistent
+
     def _with_sess(self, fn):
-        if self._persistent is not None:
-            return fn(self._persistent)
-        sess = NdtBoxSession(self)
+        sess = self._get_live_sess()
+        if self._persistent is sess:
+            return fn(sess)
         try:
             return fn(sess)
         finally:
@@ -596,26 +609,72 @@ class NdtBoxIo:
         read_gap = int(plan.get("read_gap_ms", 10))
         pages = plan.get("writes", [])
         windows = plan.get("windows", [])
+        t_all = time.monotonic()
         with self.session():
             self.vbrt_reset(off_ms)              # 断电复位进 boot (usb2io IO10)
+            reset_ms = round((time.monotonic() - t_all) * 1000)
             time.sleep(0.1)                      # boot ready (UpdateFW Thread.Sleep(100))
+            # P1-1 boot-in 轮询: 读 0x0000 4B (boot ROM 应答; 运行态固件不应答, 读回
+            # 悬空 FF)。未进 boot 时重做一次 vbrt 再轮询; 仍失败立即报 BOOT_NOT_ENTERED
+            # (此前无轮询, 未进 boot 时 333 页写静默空转 ~20s, 最后报误导性的
+            # "校验失败 @0x0000"——实际读到的是旧固件内容; 实战 4 次烧录 3 次首试此败)
+            boot_t0 = time.monotonic()
+            boot_ok = False
+            for round_no in range(2):
+                if round_no:
+                    self.vbrt_reset(off_ms)
+                    time.sleep(0.1)
+                for _ in range(10):
+                    try:
+                        probe = self.raw_write_read(b"\x00\x00", 4)
+                    except NdtBoxError as exc:
+                        if exc.error_class == "BUS_TIMEOUT":
+                            raise   # clock-stretch 挂死: 上抛 (信封已带断电指引)
+                        time.sleep(0.1)
+                        continue
+                    if probe and any(b != 0xFF for b in probe):
+                        boot_ok = True   # 有效应答 (非悬空默认电平)
+                        break
+                    time.sleep(0.1)
+                if boot_ok:
+                    break
+            if not boot_ok:
+                raise NdtBoxError(
+                    "BOOT_NOT_ENTERED",
+                    "断电复位后目标未进入 boot (0x0000 读回悬空/无应答): 运行态固件不响应"
+                    "烧录协议。请仅对目标板断电重启 (勿动 BOX), 然后重新调用 "
+                    "fw_ndtdbg_flash; 若反复出现, 检查 usb2io IO10 供电复位接线")
+            boot_probe_ms = round((time.monotonic() - boot_t0) * 1000)
             # 整片擦除魔数 @0x0000 (EreaseChipCmd AA 55 A5 5A)
+            erase_t0 = time.monotonic()
             try:
                 self.raw_write_read(bytes([0x00, 0x00, 0xAA, 0x55, 0xA5, 0x5A]), 0)
             except NdtBoxError as exc:
                 if exc.error_class == "BUS_TIMEOUT":
-                    # P1-3: boot 等待显式化——把人工确认的搬运工步骤写进错误信封
                     raise NdtBoxError(
                         "BUS_TIMEOUT",
                         "目标未进入 boot (擦除命令超时无应答)。请仅对目标板断电重启 (勿动 BOX), "
                         "然后重新调用 fw_ndtdbg_flash", exc.detail) from exc
                 raise
             time.sleep(erase_ms / 1000.0)
+            # P1-1 擦除金丝雀: 只验 "boot 还活着" (有应答即过——擦除后 0x0000 读回全 FF
+            # 属预期, 内容校验放校验阶段); 把失败从 20s 后的校验提前到擦除后 ~2s
+            try:
+                self.raw_write_read(b"\x00\x00", 4)
+            except NdtBoxError as exc:
+                raise NdtBoxError(
+                    "BOOT_NOT_ENTERED",
+                    f"擦除后 boot 无应答 (金丝雀失败): {exc.message}",
+                    exc.detail) from exc
+            erase_ms_actual = round((time.monotonic() - erase_t0) * 1000)
+            write_t0 = time.monotonic()
             for page_hex in pages:
                 self.raw_write_read(bytes.fromhex(page_hex), 0)   # 页写 (2B 页地址+128B)
                 if page_gap > 0:
                     time.sleep(page_gap / 1000.0)
+            write_ms = round((time.monotonic() - write_t0) * 1000)
             time.sleep(0.2)                      # WriteFw 后至校验前 (Thread.Sleep(200))
+            verify_t0 = time.monotonic()
             for win in windows:
                 off = int(win["off"])
                 rb = self.raw_write_read(off.to_bytes(2, "big"), 256)
@@ -630,11 +689,16 @@ class NdtBoxIo:
                                       f"expect={expect[k:k + 16]} got={got[k:k + 16]}")
                 if read_gap > 0:
                     time.sleep(read_gap / 1000.0)
+            verify_ms = round((time.monotonic() - verify_t0) * 1000)
             # 完成魔数 "PASs" (UpgradeFinishCmd)
             self.raw_write_read(bytes([0x00, 0x00, 0x50, 0x41, 0x53, 0x73]), 0)
             time.sleep(0.01)
             self.vbrt_reset(off_ms)              # 复位加载新固件
-        return {"verify": "pass", "pages_written": len(pages), "read_windows": len(windows)}
+        # P3: 分阶段耗时 (事后分析首试失败率, 无需 job 化即可观测)
+        return {"verify": "pass", "pages_written": len(pages), "read_windows": len(windows),
+                "reset_ms": reset_ms, "boot_probe_ms": boot_probe_ms,
+                "erase_ms": erase_ms_actual, "write_ms": write_ms, "verify_ms": verify_ms,
+                "total_ms": round((time.monotonic() - t_all) * 1000)}
 
     def vbrt_reset(self, off_ms: int = 200) -> dict:
         """模组断电 off_ms 后恢复上电 (usb2io.dll IO10)——复位进入 IIC boot (IOoperation.VBRTOFF)。"""
@@ -642,6 +706,8 @@ class NdtBoxIo:
 
 
 class NdtBoxSession:
+    # 回显握手 token; None=每次随机 (生产)。单测注入固定值以便静态 mock 桥应答。
+    HANDSHAKE_TOKEN: str | None = None
     """serve 桥会话客户端: 32 位薄壳进程长驻 USB 会话, Python 经行协议驱动单事务。
 
     行协议 (全 ASCII): 请求 "open"/"r <reg> <len>"/"w <reg> <data_hex>"/
@@ -687,6 +753,23 @@ class NdtBoxSession:
         if not ok:
             self.close()
             raise self._map_error(payload)
+        # P0-1 回显握手: 桥多发/漏发一行响应会让整条会话永久 +1 错位 (v0.4.0~
+        # v0.6.0 实战暴露——同构纯读流对它免疫, 异构写读流直接腐坏)。open 后立即
+        # 以随机 token 验证"响应与请求一一对应", 把错位显式化为 PROTOCOL_DESYNC。
+        token = type(self).HANDSHAKE_TOKEN or os.urandom(4).hex()
+        try:
+            ok2, payload2 = self._txn(f"echo {token}", timeout_ms=5000)
+        except NdtBoxError as exc:
+            self.close()
+            raise NdtBoxError("PROTOCOL_DESYNC",
+                              f"serve 会话握手失败: {exc.message}", exc.detail) from exc
+        if not ok2 or payload2.strip() != token:
+            self.close()
+            raise NdtBoxError(
+                "PROTOCOL_DESYNC",
+                f"serve 会话握手回显不匹配 (expect {token!r}, got {payload2[:64]!r})——"
+                "桥响应错位或 ndtdbg_bridge.ps1 版本过旧, 请升级 firmwareloop")
+        self._handshaken = True
 
     def _read_loop(self) -> None:
         try:
@@ -787,7 +870,16 @@ class NdtBoxSession:
         ok, payload = self._txn(f"raw {bytes(write).hex()} {read_len}")
         if not ok:
             raise self._map_error(payload, "raw 事务")
-        return bytes.fromhex(payload.replace(" ", "")) if read_len > 0 else None
+        if read_len <= 0:
+            return None
+        try:
+            return bytes.fromhex(payload.replace(" ", ""))
+        except ValueError as exc:
+            # P1-2: 负载解析失败就地转结构化错误 (附负载原文), 不再裸抛 ValueError
+            # 被 CLI 顶层压成一行 UNKNOWN_ERROR (实战定位它花了 20 分钟)
+            raise NdtBoxError("PROTOCOL_ERROR",
+                              f"serve 响应负载非法 hex: {exc}",
+                              f"payload[:80]={payload[:80]!r}") from exc
 
     def vbrt_reset(self, off_ms: int = 200) -> dict:
         ok, payload = self._txn(f"vbrt {int(off_ms)}")

{firmwareloop-0.6.0 → firmwareloop-0.6.1}/tools/ndtdbg_bridge.ps1

@@ -613,12 +613,16 @@ try {
             # 经行协议驱动。 deliberately 无格式化/无业务分支——规避 PS 语法陷阱 (0.2.1/0.2.2 坑)。
             # 行协议 (全 ASCII, 逐行 Flush):
             #   -> open                        <- OK | ERR PROBE
+            #   -> echo <token>                <- OK <token> (回显, 握手防错位)
             #   -> r <reg> <len>               <- OK <hex 空格分隔> | ERR IO
             #   -> w <reg> <data_hex 紧凑>     <- OK | ERR IO
             #   -> raw <write_hex> <read_len>  <- OK <hex|-> | ERR IO
             #   -> vbrt <off_ms>               <- OK | ERR PROBE
             #   -> close                       <- OK (桥退出)
             # 任何未知 op: ERR CONFIG
+            # P0-1: 打开成功后不再主动发 OK (该行无请求对应, 会让整条会话响应
+            # 永久 +1 错位——v0.4.0~v0.6.0 实战暴露); open 的应答由循环分支负责,
+            # 另提供 echo 回显供 Python 侧握手验证响应一一对应。
             [Console]::OutputEncoding = [System.Text.Encoding]::UTF8
             $h = [STDataCollection.Icb]::USBIO_OpenDevice([uint32]0)
             if ($h -le 0) {
@@ -627,8 +631,6 @@ try {
                 exit 1
             }
             [STDataCollection.Icb]::USBIO_SetStream([uint32]0, [uint32](128 + $Speed)) | Out-Null
-            [Console]::WriteLine("OK")
-            [Console]::Out.Flush()
             while ($true) {
                 $line = [Console]::In.ReadLine()
                 if ($null -eq $line) { break }   # stdin EOF
@@ -639,6 +641,8 @@ try {
                 try {
                     if ($op -eq "open") {
                         [Console]::WriteLine("OK")
+                    } elseif ($op -eq "echo") {
+                        [Console]::WriteLine("OK " + $parts[1])
                     } elseif ($op -eq "r") {
                         $reg = [int]$parts[1]; $rlen = [int]$parts[2]
                         $tx = New-Object byte[] 2

{firmwareloop-0.6.0 → firmwareloop-0.6.1}/tools/ndtdbg_cli.py

@@ -40,12 +40,76 @@ def fail(error_class: str, message: str, detail=None) -> None:
 
 def ok(action: str, data: dict, log: str = None) -> None:
     payload = {"schema": "ndtdbg-result/v1", "ok": True, "action": action, "data": data}
+    try:
+        payload["config"] = config_provenance()   # P1-4: 全部 ndtdbg 工具结果附配置溯源
+    except Exception:  # noqa: BLE001
+        pass
     if log:
         payload["log"] = log
     print(json.dumps(payload, ensure_ascii=False))
     sys.exit(0)
 
 
+# --------------------------------------------------------------------------- provenance (P1-4)
+
+def _load_ndtdbg_section(path: str) -> dict | None:
+    """读取单份 lab.yaml 的 ndtdbg 段 (不存在/解析失败返回 None)。"""
+    try:
+        with open(path, encoding="utf-8") as fh:
+            data = (yaml.safe_load(fh) if yaml is not None else json.load(fh)) or {}
+    except Exception:  # noqa: BLE001
+        return None
+    sec = data.get("ndtdbg") if isinstance(data, dict) else None
+    return sec if isinstance(sec, dict) else None
+
+
+def config_provenance() -> dict:
+    """P1-4: lab.yaml 配置链溯源——三级深合并语义不变, 只加透明度。
+
+    - sources: 参与合并的 lab.yaml 路径 (高 -> 低, 复用 _CONFIG_FILES);
+    - ndtdbg_effective_from: ndtdbg 段实际来自的最高优先级文件;
+    - write_allowed_granted_by: write_allowed 授权来源 (write_allowed_source());
+    - overridden_keys: 项目层覆盖了低层取值的 ndtdbg 键;
+    - hint: 项目层缺 ndtdbg 段时的 onboarding 提示 (onboarding, 防止
+      "以为缺配置" 的无效排查——实战中真实问题是 serve 桥错位)。
+    """
+    chain = list(_CONFIG_FILES)   # 高 -> 低
+    proj = os.path.join(os.getcwd(), "lab", "lab.yaml")
+    appdata = os.environ.get("APPDATA")
+    global_cfg = os.path.join(appdata, "FirmwareLoop", "lab.yaml") if appdata else None
+
+    nd_from = None
+    for cand in chain:   # 高 -> 低, 第一份含 ndtdbg 段的即生效来源
+        if _load_ndtdbg_section(cand):
+            nd_from = cand
+            break
+
+    overridden: list = []
+    proj_sec = _load_ndtdbg_section(proj) if os.path.isfile(proj) else None
+    if proj_sec:
+        for cand in chain:
+            if cand == proj:
+                continue
+            lower = _load_ndtdbg_section(cand) or {}
+            for k, v in proj_sec.items():
+                if k in lower and lower[k] != v:
+                    overridden.append(k)
+
+    out: dict = {
+        "sources": chain,
+        "ndtdbg_effective_from": nd_from,
+        "write_allowed_granted_by": write_allowed_source(),
+        "overridden_keys": sorted(set(overridden)),
+    }
+    if nd_from and nd_from != proj:
+        # P1-4 onboarding: ndtdbg 生效来源不是项目层 (项目层缺 ndtdbg 段或文件不存在)
+        example_hint = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))),
+                                    "lab", "lab.example.yaml")
+        out["hint"] = (f"ndtdbg 生效配置来自 {nd_from}; 当前项目层 lab/lab.yaml 未定义 ndtdbg 段。"
+                       f"如需项目级覆盖, 参考 {example_hint} 的 ndtdbg 段")
+    return out
+
+
 # --------------------------------------------------------------------------- config
 
 _CONFIG_FILES: list[str] = []   # 实际加载的 lab.yaml (优先级从高到低), 供错误信息引用
@@ -146,8 +210,11 @@ def cmd_status(io: NdtBoxIo) -> None:
     # 0xFFFF 的 module_connect 同样是悬空默认电平, 不作为总线 OK 证据。
     chip_ok = fw_version not in (None, "v0.0.0.0", "v255.255.255.255") and not bus_hung
     bus_ok = not bus_hung and (chip_ok or (module_connect is not None and module_connect != 0xFFFF))
-    chip_state = "OK" if chip_ok else ("UNKNOWN" if bus_ok else "NO_RESPONSE")
-    bus_state = "HUNG" if bus_hung else ("OK" if bus_ok else "NO_RESPONSE")
+    # P1-3: SILENT 档 (原 NO_RESPONSE) —— 总线可自由收发但无从机应答, 常见于运行态
+    # 固件使用自有协议 (仅 boot ROM 按 0xA0+寄存器语义应答), 属预期而非故障;
+    # 旧文案 "检查接线/上拉/供电" 把 agent 引去查硬件, 浪费一轮排查。
+    chip_state = "OK" if chip_ok else ("UNKNOWN" if bus_ok else "SILENT")
+    bus_state = "HUNG" if bus_hung else ("OK" if bus_ok else "SILENT")
     data = {
         "device": "NdtBox",
         "slave_addr": io.slave_addr,
@@ -165,7 +232,9 @@ def cmd_status(io: NdtBoxIo) -> None:
         data["hint"] = ("从机疑似 clock-stretch 挂死 (常见于目标 HardFault/关中断死循环): "
                         "I2C 读在事务超时内未返回, 区别于返回 FF 的无应答; 请仅对目标板断电重启 (勿动 BOX)")
     elif not bus_ok:
-        data["hint"] = ("疑似 IIC 总线无应答: 检查接线/上拉/供电/从机地址; "
+        data["hint"] = ("iic_bus SILENT: 总线可自由收发但无从机应答——运行态固件通常不响应本工具读协议"
+                        " (仅 boot ROM 应答), 属预期而非故障; 烧录流程会先断电复位进 boot 再通信。"
+                        "若确需排查硬件, 再检查接线/上拉/供电/从机地址; "
                         "0xFF/0xFFFF 读回值是总线悬空的默认电平, 不代表芯片状态")
     ok("status", data, log="Open + ReadFwVersion(0x10) + ReadModuleConnect(0x29)")
 
@@ -508,7 +577,12 @@ def main(argv=None) -> None:
     except NdtBoxError as exc:
         fail(exc.error_class, exc.message, exc.detail)
     except Exception as exc:  # noqa: BLE001
-        fail("UNKNOWN_ERROR", f"ndtdbg_cli 异常: {exc}")
+        # P1-2: 堆栈透出——exc_type + traceback 末 5 行随错误信封返回, agent 无需
+        # 再注入 monkey-patch 脚本定位 (实战定位 ndtdbg.py:790 花了 20 分钟)
+        import traceback
+        tail = "\n".join(traceback.format_exc().strip().splitlines()[-5:])
+        fail("UNKNOWN_ERROR", f"ndtdbg_cli 异常: {exc}",
+             detail=f"exc_type={type(exc).__name__}; traceback_tail:\n{tail}")
 
 
 if __name__ == "__main__":

{firmwareloop-0.6.0 → firmwareloop-0.6.1}/tools/serial_cli.py

@@ -207,9 +207,37 @@ def cmd_read(args: argparse.Namespace) -> None:
         if args.expect is not None:
             result = session.expect(args.expect, args.timeout_ms, is_hex=args.expect_hex)
         else:
-            result = session.read(max_bytes=args.max_bytes)
+            result = session.read(max_bytes=RX_BUFFER_LIMIT if args.drain else args.max_bytes)
     except SerialAssistantError as exc:
         fail(exc.error_class, exc.detail, detail=exc.extra or None)
+
+    if args.drain and not args.expect:
+        # P2-3 (0909 提案): 单次排空整个缓冲; 大 payload 落盘而非进 MCP 响应,
+        # 防止大缓冲 (实战 850KB 刷屏) 撑爆 agent 上下文。返回摘要 + 文件路径。
+        data_hex = result.get("data_hex") or ""
+        n = result.get("bytes", 0)
+        payload: dict = {"drained_bytes": n, "buffer_bytes": result.get("buffer_bytes", 0),
+                         "overflowed": result.get("overflowed"),
+                         "rx_bytes_total": result.get("rx_bytes"),
+                         "tx_bytes_total": result.get("tx_bytes")}
+        if n > 65536:
+            config = ndtdbg_cli.load_config(args.lab_config)
+            out = os.path.join(log_dir(config, args),
+                               f"drain-{time.strftime('%Y%m%d-%H%M%S')}.hex")
+            os.makedirs(os.path.dirname(out), exist_ok=True)
+            with open(out, "w", encoding="utf-8") as fh:
+                fh.write(data_hex)
+            payload["file_path"] = out
+            tail_bytes = bytes.fromhex(data_hex.replace(" ", "")[-1024:] or "")
+            payload["tail_ascii"] = to_ascii(tail_bytes)   # 末 512B 预览
+            payload["note"] = (f"{n}B 全量已落盘 (>64KB 不进 MCP 响应); "
+                               "解析用 fw_serial_parse --source <该文件>")
+        else:
+            payload["data_hex"] = data_hex
+            payload["data_ascii"] = result.get("data_ascii")
+        ok("read", payload, log=f"SerialRead(drain, {n}B)")
+        return
+
     data = {"data_hex": result.get("data_hex"), "data_ascii": result.get("data_ascii"),
             "bytes": result.get("bytes", 0),
             "buffer_bytes": result.get("buffer_bytes"),
@@ -347,6 +375,8 @@ def build_parser() -> argparse.ArgumentParser:
 
     sp = sub.add_parser("read", parents=[common], help="读取会话接收缓冲")
     sp.add_argument("--max-bytes", type=int, default=65536)
+    sp.add_argument("--drain", action="store_true",
+                    help="单次排空整个缓冲 (>64KB 落盘 .hex 返回摘要, 防大 payload 进 MCP 响应)")
     sp.add_argument("--expect", help="等待缓冲出现该文本 (boot_expect 语义)")
     sp.add_argument("--expect-hex", action="store_true", help="expect 按 HEX 解析")
     sp.add_argument("--timeout-ms", type=int, default=2000, help="expect 超时 (默认 2000)")

{firmwareloop-0.6.0 → firmwareloop-0.6.1}/tools/setup-agent-mcp.ps1

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