fix(bridge): Windows 上中文標籤與 log 亂碼

使用者截圖標籤顯示「撣�」而非「布」。實證：布 的 UTF-8 位元組
e5 b8 83 用 cp950 解碼正好得到「撣�」。

根因是 bridge 的 stdio 綁在系統 ANSI code page（繁中 Windows = cp950），
而非 UTF-8。兩個方向的表現不同：

- Go → Python（stdin）：Go 的 json.Marshal 不 escape 非 ASCII，送出的是
  原始 UTF-8，Python 卻用 cp950 解碼 → 標籤壞掉。這是實際的損壞路徑。
- Python → Go（stdout）：json.dumps 預設 ensure_ascii=True 會轉成 \uXXXX，
  所以碰巧沒事 —— 但那是巧合不是設計。

同一根因也造成 log 的「(source: declared) �X SDK did not report」，那個
�X 是程式碼裡的 em dash 編碼失敗。

修正兩層，各自不可省：

1. kneron_bridge.py 在 module import 時強制 stdio 為 UTF-8（早於任何 I/O，
   import 期間的 traceback 也涵蓋），並在 os.fdopen 明確指定 encoding
   —— 那是 JSON-RPC 回應通道，reconfigure() 碰不到它，目前只靠
   ensure_ascii 巧合存活。errors="replace" 是刻意的：bridge 崩潰會讓裝置
   離線，比一個壞字元嚴重得多。

2. kl720_driver.go 加 PYTHONUTF8=1。實測 PYTHONIOENCODING 只影響 sys.stdin、
   PYTHONUTF8 才管得到 os.fdopen 與 locale.getencoding()，單一層都不夠。

Go 端 stdout scanner 不需改（bufio.Scanner 是 byte-oriented，不做轉碼）。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

local-tool/server/internal/driver/kneron/kl720_driver.go

@@ -123,8 +123,26 @@ func (d *KneronDriver) startPython() error {
 	// On macOS with Apple Silicon, Kneron SDK requires x86_64 (Rosetta 2).
 	// The venv should already contain the correct architecture Python.
 	// Set DYLD_LIBRARY_PATH so libkplus.dylib can be found.
+	// PYTHONUTF8=1 啟用 Python UTF-8 Mode（PEP 540）：讓子行程的 stdio 與
+	// locale.getencoding() 一律視為 UTF-8，不理會系統 ANSI code page。
+	//
+	// 為什麼要在 Go 這端也設一次（bridge 內已有 _force_utf8_stdio()）：
+	// 兩者涵蓋範圍不同，是互補而非重複 ——
+	//
+	//  1. bridge 的 reconfigure() 只能在「直譯器已經啟動、開始執行程式碼」
+	//     之後才生效。若 import 期間（例如 numpy / kp 載入失敗）就拋例外，
+	//     traceback 仍會用舊編碼寫到 stderr，中文路徑會變亂碼而難以診斷。
+	//  2. UTF-8 Mode 一併改變 locale.getencoding()，因此連 open() 這類
+	//     未顯式指定 encoding 的呼叫也會是 UTF-8 —— reconfigure() 對
+	//     sys.std* 以外的檔案物件無能為力。
+	//
+	// 背景：Windows 的 Python 預設把 stdio 綁到系統 ANSI code page，繁中
+	// Windows 為 cp950。而 Go 的 encoding/json 不 escape 非 ASCII，
+	// `{"labels":["布"]}` 在 wire 上是 raw UTF-8，以 cp950 解碼會變成
+	// `撣<>`（U+FFFD），或在嚴格模式下直接讓 bridge 崩潰。
 	cmd.Env = append(os.Environ(),
 		"PYTHONUNBUFFERED=1",
+		"PYTHONUTF8=1",
 	)
 
 	// Add library path for native kp module if lib directory exists.

local-tool/server/scripts/kneron_bridge.py

@@ -19,6 +19,58 @@ import io
 import numpy as np
 
 
+def _force_utf8_stdio():
+    """把 stdin / stdout / stderr 一律綁成 UTF-8，不理會系統預設編碼。
+
+    為什麼需要這支（Windows 中文亂碼根因）：
+
+    Windows 的 Python 把 stdio 綁到「系統 ANSI code page」而非 UTF-8。繁體
+    中文 Windows 的 ANSI code page 是 cp950。而本 bridge 的 JSON-RPC 兩個
+    方向並不對稱：
+
+      Go → Python (stdin)：Go 的 `encoding/json` **不** escape 非 ASCII，
+          `{"labels":["布"]}` 在 wire 上就是 raw UTF-8 位元組 e5 b8 83。
+          以 cp950 解碼會得到 `撣` + U+FFFD（使用者截圖的亂碼），
+          嚴格模式下則直接 UnicodeDecodeError 讓整個 bridge 掛掉。
+
+      Python → Go (stdout)：`json.dumps` 預設 ensure_ascii=True，中文被
+          escape 成 \\uXXXX 純 ASCII，所以這條路「目前」剛好沒壞。但那是
+          隱性依賴 —— 任何人加上 ensure_ascii=False 就會壞。這裡一併綁定，
+          把「stdout 是 UTF-8」變成顯式契約而非巧合。
+
+      stderr：`_log()` 的中文訊息與 em dash（U+2014）等字元現在就會壞
+          （使用者先前看到的 `<EFBFBD>X SDK did not report` 即為此）。
+
+    為什麼用 errors="replace" 而非預設的 "strict"：
+    這是診斷用的 log 通道與協定通道。遇到極端的無效位元組時，我們寧可看到
+    一個 U+FFFD 也不要讓整個 bridge 因為一行 log 而崩潰 —— bridge 掛掉
+    會讓裝置直接失聯，比一個壞字元嚴重得多。stdin 側同理：Go 端送出的一定
+    是合法 UTF-8，replace 只是最後一道防線。
+
+    為什麼在 module import 時就呼叫（而不是在 main() 裡）：
+    必須早於任何 I/O。main() 會 os.dup() stdout、import 期間的例外也會經由
+    stderr 輸出，兩者都得在編碼已經正確之後才發生。
+
+    Python 3.7+ 才有 TextIOWrapper.reconfigure()。專案用的是
+    python-build-standalone 3.12，安全；仍以 hasattr 做防禦，
+    在極舊環境下退化成 no-op 而不是 crash。
+    """
+    for name in ("stdin", "stdout", "stderr"):
+        stream = getattr(sys, name, None)
+        if stream is None:
+            continue  # pythonw / 被重導向到 None 的情境
+        try:
+            if hasattr(stream, "reconfigure"):
+                stream.reconfigure(encoding="utf-8", errors="replace")
+        except (AttributeError, ValueError, OSError):
+            # 已被換成非 TextIOWrapper（例如測試的 StringIO）或已關閉。
+            # 這不是致命錯誤，維持原編碼繼續跑。
+            pass
+
+
+_force_utf8_stdio()
+
+
 def _preload_kneron_dylibs_macos():
     """macOS 專用：用絕對路徑預先 dlopen wheel 內的 libusb + libkplus。
 
@@ -2935,7 +2987,14 @@ def main():
     # writes go to stderr.  Our JSON responses use the duped fd.
     _real_stdout_fd = os.dup(1)          # duplicate fd 1
     os.dup2(2, 1)                        # fd 1 now points to stderr
-    _real_stdout = os.fdopen(_real_stdout_fd, "w")
+    # encoding 必須顯式指定 —— os.fdopen() 不帶 encoding 時會用
+    # locale.getpreferredencoding()，在繁中 Windows 上是 cp950。這個檔案
+    # 物件是 JSON-RPC 的**回應通道**，且它是全新建立的，不受
+    # _force_utf8_stdio() 對 sys.stdout 的 reconfigure 影響，所以必須在
+    # 這裡各自綁一次。errors 理由同 _force_utf8_stdio()：寧可壞一個字元
+    # 也不要讓 bridge 崩潰而導致裝置失聯。
+    _real_stdout = os.fdopen(
+        _real_stdout_fd, "w", encoding="utf-8", errors="replace")
     sys.stdout = sys.stderr              # Python-level redirect too
 
     def _respond(obj):

local-tool/server/scripts/test_kneron_bridge_encoding.py

@@ -0,0 +1,261 @@
+#!/usr/bin/env python3
+"""Unit tests for kneron_bridge stdio encoding (Windows 中文亂碼修正).
+
+背景 —— 為什麼需要這組測試：
+
+Windows 的 Python 預設把 stdin / stdout / stderr 綁到「系統 ANSI code page」
+而非 UTF-8。繁體中文 Windows 的 ANSI code page 是 cp950。JSON-RPC 兩個方向
+的行為並不對稱：
+
+  Go → Python (stdin)：Go 的 `encoding/json` **不** escape 非 ASCII，
+      `{"labels":["布"]}` 在 wire 上是 raw UTF-8 位元組 e5 b8 83。
+      Python 端若以 cp950 解碼會得到 `撣` + U+FFFD —— 這正是使用者截圖
+      看到的亂碼。嚴格模式下則直接 UnicodeDecodeError 讓 bridge 整個掛掉。
+
+  Python → Go (stdout)：`json.dumps` 預設 ensure_ascii=True，中文被 escape
+      成 \\uXXXX 純 ASCII，所以 JSON 回應這條路「目前」不會壞。但這是脆弱的
+      隱性依賴：任何人加上 ensure_ascii=False 就會壞。stderr 上的 `_log()`
+      中文訊息則是現在就會壞（使用者先前看到的 `<EFBFBD>X SDK did not report`
+      就是 em dash U+2014 被非 UTF-8 編碼破壞的結果）。
+
+因此修正必須同時涵蓋 stdin（decode）與 stdout / stderr（encode）。
+
+測試策略 —— 如何在 macOS 上測 Windows-only 的 bug：
+本機 locale 是 UTF-8，直接跑不會重現。改用 `PYTHONIOENCODING` 環境變數強制
+子行程的 stdio 編碼，模擬繁中 Windows 的預設行為。修正正確時，bridge 必須
+忽略這個「錯誤的」預設值、一律以 UTF-8 處理 stdio。
+
+為什麼用 `unknown command` 這條路徑做斷言：
+它是唯一「不需要實體 Kneron dongle、又會把輸入字串原樣 echo 回 stdout」的
+handler，因此能驗證完整的 stdin → 解析 → stdout 往返。真正的 labels 路徑
+（set_inference_options）需要已連線的裝置，在 CI / 本機無法觸及；但兩者共用
+同一個 stdin 解碼器，所以這裡測到的就是同一個根因。
+
+執行方式：
+    cd server/scripts && python3 -m unittest test_kneron_bridge_encoding
+"""
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import unittest
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+BRIDGE = os.path.join(HERE, "kneron_bridge.py")
+
+# 取自使用者實際的 labels.txt。`布` 特別重要：UTF-8 位元組 (e5 b8 83) 以
+# cp950 解碼會得到 `撣` + U+FFFD，正是截圖中的症狀。
+CJK_LABELS = ["剪刀", "石頭", "布"]
+
+# U+FFFD REPLACEMENT CHARACTER —— 解碼失敗的明確指紋。
+REPLACEMENT_CHAR = "<EFBFBD>"
+
+# 模擬非 UTF-8 系統預設編碼的情境。
+#   cp950          —— 繁中 Windows 的 ANSI code page（嚴格模式會拋例外）
+#   cp950:replace  —— 靜默產生 U+FFFD 的最陰險情境（使用者實際看到的）
+#   latin-1        —— 確認修正不是只針對 cp950 硬編
+NON_UTF8_STDIO_ENVS = ["cp950", "cp950:replace", "latin-1"]
+
+
+def _run_bridge(commands, io_encoding=None, timeout=60):
+    """把 commands 逐行餵給 bridge 子行程，回傳 (responses, proc)。
+
+    刻意走真實 subprocess 而非 import：這個 bug 的本質就是「行程啟動時
+    stdio 綁定了什麼編碼」，in-process 測試無法重現。
+
+    以 bytes 模式通訊：測試自己控制編解碼，才能精準模擬 Go 端 json.Marshal
+    送出 raw UTF-8 的行為，不受測試進程自身 locale 影響。
+    """
+    env = os.environ.copy()
+    # 避免使用者環境既有的設定干擾測試前提。
+    env.pop("PYTHONIOENCODING", None)
+    if io_encoding is not None:
+        env["PYTHONIOENCODING"] = io_encoding
+
+    payload = b"".join(
+        json.dumps(c, ensure_ascii=False).encode("utf-8") + b"\n" for c in commands
+    )
+
+    proc = subprocess.run(
+        [sys.executable, BRIDGE],
+        input=payload,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        env=env,
+        timeout=timeout,
+    )
+
+    responses = []
+    for raw in proc.stdout.splitlines():
+        raw = raw.strip()
+        if not raw:
+            continue
+        try:
+            responses.append(json.loads(raw.decode("utf-8")))
+        except (UnicodeDecodeError, json.JSONDecodeError):
+            # 保留原始 bytes，讓失敗訊息看得出是編碼問題而非邏輯問題。
+            responses.append({"_undecodable": raw})
+    return responses, proc
+
+
+class StdinDecodingTest(unittest.TestCase):
+    """stdin 方向：Go 送 raw UTF-8，bridge 必須正確解碼。"""
+
+    def _assert_cjk_roundtrip(self, io_encoding, scenario):
+        # 每個標籤各送一次，確保是逐字驗證而非整包碰運氣。
+        commands = [{"cmd": f"probe_{label}"} for label in CJK_LABELS]
+        responses, proc = _run_bridge(commands, io_encoding)
+
+        stderr_text = proc.stderr.decode("utf-8", "replace")
+
+        self.assertEqual(
+            proc.returncode, 0,
+            msg=(f"[{scenario}] bridge 非正常結束（rc={proc.returncode}）。"
+                 f"多半是 stdin 以非 UTF-8 解碼導致 UnicodeDecodeError。\n"
+                 f"stderr=\n{stderr_text}"),
+        )
+
+        for r in responses:
+            self.assertNotIn(
+                "_undecodable", r,
+                msg=f"[{scenario}] stdout 不是合法 UTF-8 JSON：{r}",
+            )
+
+        errors = [r["error"] for r in responses if isinstance(r.get("error"), str)]
+        self.assertEqual(
+            len(errors), len(CJK_LABELS),
+            msg=(f"[{scenario}] 預期 {len(CJK_LABELS)} 筆 unknown-command 回應，"
+                 f"實得 {len(errors)}。responses={responses}\n"
+                 f"stderr=\n{stderr_text}"),
+        )
+
+        for label, err in zip(CJK_LABELS, errors):
+            self.assertNotIn(
+                REPLACEMENT_CHAR, err,
+                msg=(f"[{scenario}] 回應含 U+FFFD replacement character，"
+                     f"代表 stdin 被以非 UTF-8 解碼：{err!r}"),
+            )
+            self.assertIn(
+                label, err,
+                msg=(f"[{scenario}] 中文字串 round-trip 失敗。"
+                     f"預期回應含 {label!r}，實得 {err!r}"),
+            )
+
+    def test_roundtrip_under_default_locale(self):
+        """基準線：本機預設 locale（macOS / Linux 為 UTF-8）必須正常。
+
+        這條在修正前後都會過 —— 它的作用是證明測試本身沒問題，
+        失敗的是編碼而不是斷言寫錯。
+        """
+        self._assert_cjk_roundtrip(None, "default-locale")
+
+    def test_roundtrip_under_non_utf8_stdio(self):
+        """核心回歸測試：模擬繁中 Windows 的非 UTF-8 預設 stdio。
+
+        修正前：cp950 → UnicodeDecodeError 直接 crash；
+                cp950:replace → 靜默產生 `撣<EFBFBD>`。
+        修正後：bridge 強制 UTF-8，忽略 PYTHONIOENCODING 的錯誤指示。
+        """
+        for io_encoding in NON_UTF8_STDIO_ENVS:
+            with self.subTest(encoding=io_encoding):
+                self._assert_cjk_roundtrip(io_encoding, io_encoding)
+
+
+class StderrEncodingTest(unittest.TestCase):
+    """stderr 方向：_log() 的中文 / 非 ASCII 診斷訊息必須可讀。"""
+
+    def test_stderr_is_valid_utf8_under_non_utf8_stdio(self):
+        """使用者先前看到的 `<60>X SDK did not report` 與 label 亂碼同源。
+
+        stderr 若被綁到 cp950，em dash（U+2014）等非 ASCII 字元會被破壞，
+        讓診斷訊息失去價值。
+        """
+        for io_encoding in NON_UTF8_STDIO_ENVS:
+            with self.subTest(encoding=io_encoding):
+                _, proc = _run_bridge([{"cmd": "probe_布"}], io_encoding)
+                try:
+                    proc.stderr.decode("utf-8")
+                except UnicodeDecodeError as e:
+                    self.fail(
+                        f"[{io_encoding}] stderr 不是合法 UTF-8，"
+                        f"編碼修正未涵蓋 stderr：{e}")
+
+    def test_startup_banner_present(self):
+        """確認 bridge 真的有跑起來（避免上面的測試因空輸出而假綠）。"""
+        _, proc = _run_bridge([{"cmd": "probe_布"}], "cp950:replace")
+        self.assertIn(
+            "[kneron_bridge]", proc.stderr.decode("utf-8", "replace"),
+            msg="bridge 啟動 log 不存在，測試前提不成立")
+
+
+class StdoutEncodingTest(unittest.TestCase):
+    """stdout 方向：JSON 回應必須能以 UTF-8 解碼。"""
+
+    def test_stdout_is_valid_utf8_with_non_ascii_payload(self):
+        """即使未來有人把 json.dumps 改成 ensure_ascii=False 也不能壞。
+
+        目前 ensure_ascii=True 讓中文變成 \\uXXXX 純 ASCII，掩蓋了 stdout
+        的編碼問題。這條測試把「stdout 必須是 UTF-8」釘成顯式契約，
+        而不是依賴 json.dumps 的預設值。
+        """
+        for io_encoding in NON_UTF8_STDIO_ENVS:
+            with self.subTest(encoding=io_encoding):
+                responses, proc = _run_bridge(
+                    [{"cmd": "probe_布"}], io_encoding)
+                for r in responses:
+                    self.assertNotIn(
+                        "_undecodable", r,
+                        msg=(f"[{io_encoding}] stdout 無法以 UTF-8 解碼：{r}"))
+
+
+class RealStdoutFdEncodingTest(unittest.TestCase):
+    """main() 裡 os.fdopen() 建立的 JSON-RPC 回應通道必須顯式綁 UTF-8。
+
+    ⚠️ 這條為什麼是原始碼層級的斷言，而不是行為測試：
+
+    `os.fdopen(fd, "w")` 不帶 encoding 時，編碼取自
+    `locale.getencoding()`（PEP 686 之後 io.text_encoding(None) → "locale"），
+    **不是** `PYTHONIOENCODING`。PYTHONIOENCODING 只影響 sys.std*。
+
+    後果：在 macOS / Linux（locale 為 UTF-8）上，無論怎麼設
+    PYTHONIOENCODING 都無法讓這個檔案物件變成 cp950，因此
+    上面的 subprocess 測試**結構上碰不到這條路徑**（已用 mutation test
+    證實：拿掉 encoding= 參數後那些測試仍然全綠）。
+
+    但在繁中 Windows 上 locale.getencoding() 就是 cp950，這個 fd
+    會真的以 cp950 編碼寫出 JSON 回應。目前 json.dumps 的
+    ensure_ascii=True 讓中文變成純 ASCII 而僥倖沒出事 —— 這是巧合，
+    不是設計。
+
+    唯一能在 macOS 上守住這條的方式，就是把「必須顯式指定 encoding」
+    當成不可回歸的原始碼契約來檢查。
+    """
+
+    def test_fdopen_specifies_utf8_explicitly(self):
+        with open(BRIDGE, encoding="utf-8") as f:
+            source = f.read()
+
+        self.assertIn(
+            "_real_stdout_fd = os.dup(1)", source,
+            msg="main() 的 stdout dup 結構已改變，本測試需同步更新")
+
+        # 找出建立 _real_stdout 的那個 os.fdopen 呼叫（可能跨行）。
+        marker = "_real_stdout = os.fdopen("
+        idx = source.find(marker)
+        self.assertNotEqual(
+            idx, -1, msg="找不到 _real_stdout = os.fdopen(...) 呼叫")
+
+        # 取到該敘述結束（右括號）為止，避免誤抓到後面無關的程式碼。
+        call = source[idx:source.find(")", idx) + 1]
+
+        self.assertIn(
+            'encoding="utf-8"', call,
+            msg=(f"os.fdopen() 未顯式指定 encoding=\"utf-8\"，"
+                 f"在繁中 Windows 上會退回 cp950 編碼 JSON-RPC 回應。"
+                 f"實際呼叫：{call!r}"))
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)