Use serialwrap broker + MCP for multi-agent UART access with single-writer arbitration, RAW logging, and session-safe command execution. Trigger when tasks involve UART command execution, UART state collection, multi-agent UART coordination, or UART evidence export.
定義 Agent 在 UART 任務中使用 serialwrap/serialwrap-mcp 的觸發條件、操作順序與安全邊界，避免直接碰觸實體 UART 造成資料失真或衝突。
serialwrapd 必須啟動。READY。session bind + session attach 至少完成一次）。serialwrap_get_health 或 CLI serialwrap daemon status。serialwrap_list_sessions、serialwrap_list_devices，或 CLI session list / device list。serialwrap_get_session_state(selector)，必要時先做 serialwrap_self_test。serialwrap_bind_session / serialwrap_attach_session / serialwrap_recover_session。serialwrap_submit_command，必填 source 與 selector。line 前景命令：用 serialwrap_get_command 或 CLI cmd status --cmd-id ... 直接讀 stdout。background 命令：用 serialwrap_tail_command_result 或 CLI cmd result-tail --cmd-id ... 增量取回 chunk。interactive 任務：用 interactive-open/send/status/close，不要拿 cmd submit 硬跑全螢幕互動程式。log tail-raw / wal export。serialwrap_get_health -> health.statusserialwrap_list_devices -> device.listserialwrap_list_sessions -> session.listserialwrap_get_session_state -> session.get_stateserialwrap_bind_session -> session.bindserialwrap_attach_session -> session.attachserialwrap_self_test -> session.self_testserialwrap_recover_session -> session.recoverserialwrap_submit_command -> command.submitserialwrap_get_command -> command.getserialwrap_tail_command_result -> command.result_tailserialwrap_clear_session -> session.clearserialwrap_attach_console -> session.console_attachserialwrap_detach_console -> session.console_detachserialwrap_list_consoles -> session.console_listserialwrap_open_interactive -> session.interactive_openserialwrap_send_interactive_keys -> session.interactive_sendserialwrap_get_interactive_status -> session.interactive_statusserialwrap_close_interactive -> session.interactive_closeserialwrap_tail_results -> result.tail（deprecated alias）serialwrap_submit_command
selector, cmdsource="agent:<name>", mode="line|background|interactive", timeout_s, priorityserialwrap_get_command
cmd_idserialwrap_tail_command_result
cmd_idfrom_chunk, limitserialwrap_get_session_state
selector（session_id | COMx | alias）serialwrap list 已移除，現在改用：
serialwrap daemon statusserialwrap device listserialwrap session listserialwrap session self-test --selector COM2serialwrap cmd submit --selector COM2 --cmd 'pwd' --source agent:diag --mode line --cmd-timeout 10serialwrap cmd status --cmd-id <cmd_id>serialwrap cmd result-tail --cmd-id <cmd_id> --from-chunk 0 --limit 100line 命令不要用 cmd result-tail 讀結果；它是給 background capture 用的。line 請直接看 cmd status / command.get.stdout。ob sync, 套件升級, 韌體操作）要給足 cmd-timeout。timeout 太短時 broker 可能以 CTRL_C 回收，target 端會留下半完成狀態。Another ... already running，先檢查 target 端是否真的還有活著的 process；若沒有，再做最小清理，例如移除空的 stale lock 目錄。cmd status 若仍是 running，不要盲目重送相同命令，先確認 target 端是否仍在執行。source，不可省略，確保追蹤性。/dev/ttyUSB* 或 /dev/ttyACM*。logread -f, tcpdump, kernel debug）優先用 mode=background；若必須前景執行，必須明確設定較長 timeout。serialwrap_self_test，再決定是否 serialwrap_recover_session。/home/paul_chen/.paul_tools/serialwrap daemon status
/home/paul_chen/.paul_tools/serialwrap session self-test --selector COM2
/home/paul_chen/.paul_tools/serialwrap cmd submit --selector COM2 --cmd 'ob sync --path ~/notes' --source agent:diag --mode line --cmd-timeout 300
/home/paul_chen/.paul_tools/serialwrap cmd status --cmd-id <cmd_id>
/home/paul_chen/prj_pri/ser-dep/skills.md/home/paul_chen/prj_pri/ser-dep/docs/serialwrap-spec.md