03 - 核心概念：Workspace / Tab / Pane / Agent
← 02-安裝與環境選擇 | 00-Index | 下一篇 → 04-日常操作-滑鼠與鍵盤
四層模型（背下來就通了）
Session（一整個常駐 server 命名空間）
└── Workspace w1 專案 / 任務 / 調查 ← 一個 repo 一個
└── Tab w1:t1 這個專案裡的一種版面 ← agents / logs / server / review
└── Pane w1:p1 一個真實的終端機 ← 可以 split
└── Agent pane 裡被認出來的 coding agent
ID 是不透明的穩定 handle，格式固定：
| 層級 | ID 範例 | 說明 |
|---|---|---|
| workspace | w1 | |
| tab | w1:t1 | 帶 workspace 前綴 |
| pane | w1:p1 | 帶 workspace 前綴 |
⚠️ 關掉的 tab / pane，ID 不會被回收再用。這點在寫腳本時很重要——不能假設
w1:p2一定是「第二個 pane」。永遠從 JSON 回應裡讀 ID，不要自己推算。
Workspace（工作區）
最上層的專案容器。一個 repo、一個任務、或一次調查用一個 workspace。
它擁有底下的 tab 和 pane。最重要的性質是：sidebar 的狀態會從底下的 agent 往上匯總——所以你掃一眼左側就知道「哪個專案在等我」。
herdr workspace list
herdr workspace create --cwd ~/project --label api --no-focus
herdr workspace focus w1
herdr workspace rename w1 "刷題網站"
herdr workspace close w1建立 workspace 會連帶建立它的第一個 tab 和 root pane，回應裡三個 ID 都拿得到：
created=$(herdr workspace create --cwd ~/Obsidian-med-note --label vault --no-focus)
ws=$(printf '%s\n' "$created" | jq -r '.result.workspace.workspace_id')
tab=$(printf '%s\n' "$created" | jq -r '.result.tab.tab_id')
pane=$(printf '%s\n' "$created" | jq -r '.result.root_pane.pane_id')給本站作者的 workspace 規劃建議
| Workspace | cwd | 用途 |
|---|---|---|
vault | ~/Obsidian-med-note | 醫學筆記庫日常維護 |
board | ~/Taiwan_IM_board | 刷題網站 |
詳解-114 | worktree checkout | 一次詳解量產 batch（做完就關） |
Tab（分頁 / 版面）
Workspace 裡的一種版面配置。官方建議的用法是照「視角」分：agents、logs、server、review。
herdr tab list --workspace w1
herdr tab create --workspace w1 --label logs --no-focus
herdr tab focus w1:t2
herdr tab rename w1:t2 review
herdr tab close w1:t2- 不給
--workspace時，tab create用目前 active 的 workspace；沒有的話會失敗。 - 建 tab 一樣會建它的 root pane（
.result.root_pane.pane_id）。 - ⚠️ 關掉 workspace 的最後一個 tab，會連 workspace 一起關掉。
Pane（面板 = 一個真實終端機）
Pane 就是一個真的終端機。Herdr 負責畫出它的輸出、把輸入送回 process、並且在 client detach 之後保住它。
herdr pane list --workspace w1
herdr pane get w1:p1
herdr pane split w1:p1 --direction right --cwd "$PWD" --no-focus
herdr pane zoom w1:p1 --toggle
herdr pane rename w1:p1 "詳解-心臟"
herdr pane close w1:p2--current 是給「在 pane 裡跑的東西」用的
Herdr 會把呼叫者的 context 注入每個受管理的 pane：
printf '%s\n' "$HERDR_WORKSPACE_ID" "$HERDR_TAB_ID" "$HERDR_PANE_ID"所以在 pane 裡跑的腳本（或 agent）要指自己時，用 --current：
herdr pane split --current --direction right --cwd "$PWD" --no-focus⚠️ 不要省略目標。省略時 Herdr 會用「UI 目前 focus 的 pane」——那可能是使用者剛好切過去的、或是另一個 client 的。這是多 agent 編排最容易出的意外。
split 的方向要看形狀
官方給的幾何規則：寬的 pane 往右切，窄或高的 pane 往下切，並且避免連續同方向切出無法使用的細長條。要知道形狀就先問：
herdr pane layout --pane "$HERDR_PANE_ID"幾個容易忽略的參數
| 參數 | 意思 |
|---|---|
--no-focus | 背景建立，不搶使用者的焦點（編排時幾乎永遠要加） |
--cwd PATH | 新終端的工作目錄；不給則照 terminal.new_cwd 政策（預設跟隨來源 pane） |
--env KEY=VALUE | 在新 shell 加/換一個環境變數 |
--ratio FLOAT | 分割比例 |
pane move 會換 ID ⚠️
把 pane 移到別的 workspace，它的 workspace-qualified pane ID 會變：
- 移動後用
.result.move_result.pane.pane_id - 舊值留在
.result.move_result.previous_pane_id - 正在跑的 process 保留啟動時的
HERDR_PANE_ID，所以它自己用--current仍然安全 - 但已經在等待中的
agent wait會以agent_not_running結束
Agent（被認出來的 coding agent）
Pane 不一定有 agent；agent 是「目前佔用這個 pane 的、被 Herdr 認出來的 process」。
這個區分決定你該用哪套指令：
| 你要做的事 | 用哪套 |
|---|---|
| 跑 shell、測試、server、CI watcher、任何普通指令 | pane 指令 |
| Herdr 需要知道「這是哪個 agent」「它現在什麼狀態」 | agent 指令 |
🔑 關鍵規則：
agent start需要一個「已經存在、而且停在互動 shell prompt」的 pane。它不會幫你建立、分割或搬動版面。要先pane split，再agent start。
Agent 的五種狀態
| 狀態 | 意思 |
|---|---|
blocked | 需要你輸入、批准、或做決定 |
working | 正在跑 |
done | 做完了，而且你還沒看過 |
idle | 做完或在等待，而且你已經看過了 |
unknown | Herdr 無法有信心地分類 |
done 和 idle 底層是同一個狀態，差別只在「這個 tab 有沒有在 focus 的 Herdr UI 裡被看到過」：
- focus 那個 tab、或用
pane focus/agent focus指它 → 標記為看過 →done變idle - 用 CLI 讀它（
agent read）不算看過
⚠️
unknown不代表成功完成。它只代表「有 agent 在，但 Herdr 分不清楚」。腳本裡若把unknown當成功會出事。
Agent 命名
herdr agent list
herdr agent get w1:p2
herdr agent rename w1:p2 reviewer
herdr agent rename reviewer --clear- 名字規則：
[a-z][a-z0-9_-]{0,31}，且在存活中的 agent 之間唯一。 - 名字是「目前佔用這個 pane 的 agent」的別名，agent 結束 / 被釋放 / 被取代時就會清掉。它不是永久重新命名 pane。
- agent 指令的 target 只接受 唯一的存活名稱 或 目前承載該 agent 的 pane ID。不接受 terminal ID，也不接受
codex這種光是 kind 的標籤。
Session（常駐命名空間）
一個 session = 一個獨立的 Herdr server 命名空間。直接跑 herdr 是接上 default session。
herdr session list
herdr session attach work
herdr session attach side-project
herdr session stop work
herdr session delete side-project命名 session 有自己的 pane、tab、workspace、socket、runtime state，但共用同一個全域設定檔。
👉 先用 workspace，不要濫用 named session。 只有在你真的需要完全隔離的 pane / socket / 持久狀態時才開新 session（例如做實驗、怕搞壞主要工作環境時）。
Client 與 Server
預設架構是「背景 server + 一個或多個 attach 上去的 client」：
- Server 擁有 pane 和 process 狀態。
- Client 是接上那個 server 的終端 UI。
ctrl+b q → detach client。server 和所有 agent 繼續跑。
herdr → 重新 attach。
herdr server stop → 真的結束 session，並停掉所有 pane process。
這就是「關掉終端機 agent 照跑」的原理，也是手機能接回來的原理。
三種模式
| 模式 | 說明 |
|---|---|
| Terminal mode | 按鍵送給 focus 的 pane（平常狀態） |
| Prefix mode | 按下 prefix 鍵後，等一個 Herdr 動作鍵 |
| Navigate mode | 常駐的 workspace 導覽介面 |
預設 prefix 是 ctrl+b。按 prefix+c 開新 tab、prefix+w 進 workspace 導覽。細節見 04-日常操作-滑鼠與鍵盤。
一張圖總結：一次詳解量產的結構
Session: default
└── Workspace w1 "刷題網站" cwd=~/Taiwan_IM_board
├── Tab w1:t1 "agents"
│ ├── Pane w1:p1 ← claude（大腦，跑編排腳本）
│ ├── Pane w1:p2 ← codex "writer-a" 114 年 心臟 001-012
│ ├── Pane w1:p3 ← codex "writer-b" 114 年 心臟 013-024
│ └── Pane w1:p4 ← codex "writer-c" 114 年 腎臟 001-012
└── Tab w1:t2 "validate"
└── Pane w1:p5 ← shell，跑 python3 tools/validate.py
Claude 在 w1:p1 建出 p2–p5、丟任務、等它們、讀結果、跑驗證、最後統一 commit。完整腳本見 08-Claude當大腦-Codex當雙手。
🔗 相關筆記
- 02-安裝與環境選擇 — 上一步
- 04-日常操作-滑鼠與鍵盤 — 下一步：實際操作
- 05-Agent偵測與狀態機制 — 五種狀態是怎麼判斷出來的
- 06-CLI與自動化基礎 — 把這些概念變成指令
最後更新：2026-08-04