Andrew的筆記園地

閱讀時間約 12 分鐘

⬇ MD

13 - 疑難排解與術語速查表

← 12-設定檔-通知-Plugins-SocketAPI | 00-Index

Part 1：症狀 → 對策

安裝與啟動

症狀原因 / 對策
herdr 指令找不到重開終端機，或檢查安裝目錄有沒有在 PATH 上
更新完了但 session 還是舊版舊 server 還在跑。herdr server stop 再 herdr；具名 session 用 herdr session stop <name> 再 attach
Windows 上 herdr channel set stable 被拒正常。Windows beta 只有 preview channel，等 stable Windows release
Homebrew / mise / Nix 裝的跑 herdr update 沒反應這些安裝要用各自的套件管理器更新，herdr update 在上面是停用的

鍵盤與輸入

症狀原因 / 對策
直接和弦（免 prefix）沒反應你的終端機或桌面環境在 Herdr 之前就吃掉了。兩邊擇一改
Enter / Tab / Backspace 觸發兩次見官方 troubleshooting「Enter, Tab, or Backspace fires twice」
Option+←/→ 冒出 ;3D / ;3C見官方 troubleshooting 對應段落
Windows 上 shift+enter 沒作用只有外層終端機把它回報成「獨立的修飾 Enter」才有效。否則 Herdr 只能轉送普通 Enter
中文輸入法候選框位置跑掉（Windows / WSL）預設 host_cursor = "auto" 畫的是格子游標，沒有原生 IME 錨點。改 [ui] host_cursor = "native"（代價：游標可能閃爍）
copy 模式裡 ctrl+b 不是翻頁prefix 在 copy 模式仍保有原意。換 prefix，或直接用滑鼠拖選（不用進 copy 模式）

Agent 偵測與狀態

症狀原因 / 對策
pane 裡明明跑著 agent 卻沒被認出來① shell framework 自動進了 tmux → Herdr 只看到 tmux。在 Herdr pane 裡不要自動進 tmux
② sandbox / VM wrapper 遮住了 → 用 HERDR_AGENT=claude <wrapper> -- claude
狀態明顯不對herdr agent explain <target> --verbose 看命中哪條規則、manifest 版本、fallback 理由
agent 在等批准但顯示 idleblocked 偵測刻意嚴格；沒命中 manifest 規則會 fallback 到 idle（explain 裡標 default_known_agent_idle_fallback）。改用 agent read --source visible 確認
explain 的結果跟預期不符，剛升級過 Herdr即時 explain 由正在跑的 server 評估。升級後要重啟或 handoff 到新 server
受限 Linux runtime 完全偵測不到server 端設 HERDR_PROCESS_DETECTION=child-groups（opt-in、best effort，需重啟 server，要設在遠端 server 環境而不是 client）
想強制更新偵測規則herdr server update-agent-manifests；改過本機覆寫則 herdr server reload-agent-manifests

編排與腳本

症狀原因 / 對策
agent start 失敗pane 必須停在互動 shell prompt（shell 自己擁有前景，沒有前景指令 / 編輯器 / agent 在跑）。先讓 pane 回到 prompt
agent_prompt_stalled--wait 從非 working 狀態送出，五秒內沒觀察到 lifecycle 變化。用 agent get / agent explain / agent read --source visible 診斷
agent wait 立刻回來但什麼都沒做① agent wait 現況符合就立刻回傳（正常行為）
② 或者狀態被誤判成 idle。驗收要看檔案，不要看狀態
wait 永遠不回來不給 --timeout 就是無限等。一定要給
--lines 加大了還是讀不到完整回應agent 跑在終端的 alternate screen（Claude Code / OpenCode）。離開 alternate screen 的行不會進 host scrollback
→ 叫 agent 把完整回應寫成 Markdown、只回檔案路徑，然後直接讀檔
agent read --lines N 回 agent_not_idleagent 正在 working / blocked / unknown。等它 idle 再讀，或改 --source visible
pane move 之後指令找不到 pane跨 workspace 移動會換 pane ID。用 .result.move_result.pane.pane_id。已在等待中的 agent wait 會以 agent_not_running 結束
腳本抓到錯的 pane省略目標會用 UI 目前 focus 的 pane。一律用 --current / 明確 pane ID / 唯一 agent 名稱
pane 被切成無法使用的細長條先 herdr pane layout 看形狀；寬的往右切、窄或高的往下切。超過 3–4 個 worker 改用一個 tab / workspace
多個 worker 改到同一個檔案用 herdr worktree create 給每人一個獨立 checkout

遠端

症狀原因 / 對策
herdr --remote 在 Windows 不能用原生 Windows 不支援。改成 ssh you@server 再跑 herdr
遠端 attach 認證失敗先確認純 ssh workbox 通不通；passphrase key 在無法提示的環境要先 ssh-add
改了本機 keybinding 但遠端 attach 沒變本機 keybinding 是 attach 當下的快照。detach 再 attach
本機剪貼簿貼圖到遠端沒作用只有 herdr --remote（本機薄客戶端）才有橋接。先 SSH 再跑 herdr 是整個跑在 server 上，讀不到本機剪貼簿

找 log

HERDR_LOG=herdr=debug herdr

官方 troubleshooting 的「Find diagnostic logs」一節有 log 位置說明。

Part 2：指令 Cheat Sheet

# ── 啟動與狀態 ───────────────────────────
herdr                                  # 啟動 / attach 預設 session
herdr --session work                   # 具名 session
herdr --skill                          # 印出 agent skill 檔
herdr --default-config                 # 印出預設設定
herdr status | herdr status server
herdr --version
 
# ── Server ──────────────────────────────
herdr server stop
herdr server reload-config
herdr server agent-manifests
herdr server update-agent-manifests
herdr server reload-agent-manifests
 
# ── Session ─────────────────────────────
herdr session list --json
herdr session attach work
herdr session stop work
 
# ── Workspace ───────────────────────────
herdr workspace list
herdr workspace create --cwd ~/proj --label api --no-focus
herdr workspace rename w1 "刷題網站"
herdr workspace close w1
 
# ── Tab ─────────────────────────────────
herdr tab list --workspace w1
herdr tab create --workspace w1 --label ops --no-focus
herdr tab focus w1:t2
 
# ── Pane ────────────────────────────────
herdr pane list --workspace w1
herdr pane layout --pane "$HERDR_PANE_ID"
herdr pane split --current --direction right --cwd "$PWD" --no-focus
herdr pane run w1:p3 "python3 tools/validate.py"
herdr pane read w1:p3 --source recent-unwrapped --lines 120
herdr pane wait-output w1:p3 --regex "PASS|FAIL" --timeout 300000
herdr pane send-keys w1:p3 ctrl+c
herdr pane zoom w1:p1 --toggle
herdr pane close w1:p3
 
# ── Agent ───────────────────────────────
herdr agent list
herdr agent start writer-a --kind codex --pane w1:p2
herdr agent start writer-a --kind codex --pane w1:p2 -- <agent-args>
herdr agent prompt writer-a "任務內容" --wait --timeout 900000
herdr agent wait writer-a --until idle --until done --timeout 1800000
herdr agent read writer-a --source recent-unwrapped --lines 200
herdr agent send-keys writer-a esc
herdr agent get writer-a
herdr agent explain writer-a --verbose
herdr agent rename w1:p2 writer-a
herdr agent focus writer-a
herdr agent attach writer-a            # Unix only
 
# ── Worktree ────────────────────────────
herdr worktree list --cwd .
herdr worktree create --cwd . --branch codex/task-a --no-focus
herdr worktree open --cwd . --branch codex/task-a
herdr worktree remove --workspace w2 --force
 
# ── Metadata / 通知 ─────────────────────
herdr pane report-metadata w1:p2 --source user:x \
  --display-agent "Codex: 心臟" --token summary="114-001~012" --ttl-ms 3600000
herdr notification show "完成" --body "24 題已產出" --sound done
 
# ── Integration ─────────────────────────
herdr integration install claude
herdr integration install codex
herdr integration status
 
# ── 其他 ────────────────────────────────
herdr api schema --json
herdr completion zsh > ~/.zfunc/_herdr
herdr update
herdr channel show

Read source 對照

Source意思適合
visible目前渲染的畫面UI 回饋迴圈
recent近期輸出（含折行）一般
recent-unwrapped近期輸出（折行接回）log / transcript 首選
detectionagent 偵測用的底部純文字快照除錯偵測

pane wait-output 例外：recent 和 recent-unwrapped 都搜尋 unwrapped 的近期快照；recent 是預設拼法。

Exit code

Code意思
0成功
1server 錯誤或 timeout（JSON 印到 stderr）
2CLI 語法錯誤

Part 3：術語速查表

術語中文 / 白話
Workspace最上層專案容器。一個 repo / 任務一個。ID w1
TabWorkspace 裡的一種版面。ID w1:t1
Pane一個真實的終端機。ID w1:p1
AgentPane 裡被 Herdr 認出來的 coding agent
Session一整個常駐 server 命名空間。有自己的 pane / socket / 狀態
Client / ServerServer 擁有 pane 和 process；client 是接上去的終端 UI
Attach / Detach接上 / 離開。Detach 後 agent 繼續跑
Prefix保留鍵（預設 ctrl+b），按了之後下一鍵送給 Herdr
Prefix mode / Terminal mode / Navigate mode三種輸入模式
Copy modeprefix+[，在歷史輸出裡搜尋 / 選取 / 複製
Rollup狀態往上匯總：agent → pane → tab → workspace
workingAgent 正在跑
blockedHerdr 認出了批准 / 提問 / 權限 UI
done背景工作完成、你還沒看過
idle準備好接收輸入、已經被看過
unknown有 agent 但分不清楚 ← 不代表完成
Status authority每個 pane 只有一個狀態權威來源
Lifecycle 權威Integration 的 hook 事件直接決定狀態（Pi / OMP / Kimi / OpenCode / Kilo / MastraCode）
Screen manifest讀畫面快照比對 TOML 規則來判斷狀態（Claude Code / Codex 走這條）
Session identity integration只回報原生 session id 供重啟後續接，不決定狀態（Claude / Codex 屬於這型）
Detection snapshot緩衝區底部的即時畫面（不受你捲動影響）
Native agent session restoreServer 重啟後用原生 session id 續接 agent 對話
Snapshot restoreServer 重啟後還原版面形狀（process 不會回來）
Pane screen history還原近期終端內容（預設關閉，會存到磁碟，有隱私風險）
Live handoff更新 / 遠端 attach 時把活的 pane 移交給新 server（實驗性、Unix only）
Alternate screen全螢幕程式（Claude Code / OpenCode）畫 transcript 的地方，離開後不進 host scrollback
Bracketed paste讓多行貼上被當成「一次貼上」而不是每行各自送出
agent start在已存在且停在 shell prompt 的 pane 啟動 agent（不建立版面）
agent prompt --wait原子送出文字+Enter，等 lifecycle 狀態 settle（不追單一 turn）
pane wait-output等終端輸出符合字串 / regex（完全不解讀 agent lifecycle）
--no-focus背景建立，不搶使用者焦點
--current目標指向「呼叫這個指令的那個 pane」
Metadata token純顯示用的 sidebar 資訊，不影響 wait / 通知 / rollup
Worktree帶 git checkout 來歷的 Herdr workspace，用來隔離平行工作
Plugin可執行的工作流套件；整個 Herdr CLI 就是它的 API
HERDR_ENV=1Agent skill 的守門條件：代表「我跑在 Herdr 管理的 pane 裡」

Part 4：三張「別忘記」小抄

編排三鐵律

  1. ID 從 JSON 讀，不要猜（jq -r '.result.pane.pane_id'）
  2. 明確指定目標（--current / pane ID / agent 名稱），永遠加 --no-focus 和 --cwd "$PWD"
  3. 驗收看檔案，不看狀態

Claude / Codex 分工線

Codex 可以做Codex 不可以做
格式套用、批次改寫醫學事實判斷
機械性檔案操作PMID / trial 數據查證
圖片處理、資料轉換決定「哪個 guideline 比較新」
產出草稿git commit / push

離開電腦前

  • 派完工了？
  • 沒有 pane 卡在等你？
  • [ui.toast] delivery = "terminal"？
  • prefix+q detach（不是 herdr server stop）

🔗 相關筆記

最後更新：2026-08-04

關係圖譜

反向連結