---
title: "13 - 疑難排解與術語速查表"
type: note
specialty: Programming
tags: [herdr從0開始使用教學, 13-速查表, troubleshooting, cheatsheet]
created: 2026-08-04
updated: "2026"
modified: 2026-08-04
---

# 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**<br>② sandbox / VM wrapper 遮住了 → 用 `HERDR_AGENT=claude <wrapper> -- claude` |
| 狀態明顯不對 | `herdr agent explain <target> --verbose` 看命中哪條規則、manifest 版本、fallback 理由 |
| agent 在等批准但顯示 `idle` | `blocked` 偵測刻意嚴格；沒命中 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` **現況符合就立刻回傳**（正常行為）<br>② 或者狀態被誤判成 `idle`。**驗收要看檔案，不要看狀態** |
| wait 永遠不回來 | **不給 `--timeout` 就是無限等**。一定要給 |
| `--lines` 加大了還是讀不到完整回應 | agent 跑在終端的 **alternate screen**（Claude Code / OpenCode）。離開 alternate screen 的行**不會進 host scrollback**<br>→ 叫 agent 把完整回應寫成 Markdown、只回檔案路徑，然後直接讀檔 |
| `agent read --lines N` 回 `agent_not_idle` | agent 正在 `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

```bash
HERDR_LOG=herdr=debug herdr
```

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

---

## Part 2：指令 Cheat Sheet

```bash
# ── 啟動與狀態 ───────────────────────────
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 首選** |
| `detection` | agent 偵測用的底部純文字快照 | 除錯偵測 |

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

### Exit code

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

---

## Part 3：術語速查表

| 術語 | 中文 / 白話 |
|---|---|
| **Workspace** | 最上層專案容器。一個 repo / 任務一個。ID `w1` |
| **Tab** | Workspace 裡的一種版面。ID `w1:t1` |
| **Pane** | 一個真實的終端機。ID `w1:p1` |
| **Agent** | Pane 裡被 Herdr 認出來的 coding agent |
| **Session** | 一整個常駐 server 命名空間。有自己的 pane / socket / 狀態 |
| **Client / Server** | Server 擁有 pane 和 process；client 是接上去的終端 UI |
| **Attach / Detach** | 接上 / 離開。**Detach 後 agent 繼續跑** |
| **Prefix** | 保留鍵（預設 `ctrl+b`），按了之後下一鍵送給 Herdr |
| **Prefix mode / Terminal mode / Navigate mode** | 三種輸入模式 |
| **Copy mode** | `prefix+[`，在歷史輸出裡搜尋 / 選取 / 複製 |
| **Rollup** | 狀態往上匯總：agent → pane → tab → workspace |
| **`working`** | Agent 正在跑 |
| **`blocked`** | Herdr **認出了**批准 / 提問 / 權限 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 restore** | Server 重啟後用原生 session id 續接 agent 對話 |
| **Snapshot restore** | Server 重啟後還原**版面形狀**（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=1`** | Agent 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`）

---

## 🔗 相關筆記

- [[00-Index]] — 回到目錄
- [[06-CLI與自動化基礎]] — 指令的完整說明
- [[08-Claude當大腦-Codex當雙手]] — 核心架構
- [[05-Agent偵測與狀態機制]] — 狀態問題的根源
- 官方 troubleshooting：<https://herdr.dev/docs/troubleshooting/>

---

*最後更新：2026-08-04*