---
title: "03 - 核心概念：Workspace / Tab / Pane / Agent"
type: note
specialty: Programming
tags: [herdr從0開始使用教學, 03-核心概念, workspace, pane]
created: 2026-08-04
updated: "2026"
modified: 2026-08-04
---

# 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 往上匯總**——所以你掃一眼左側就知道「哪個專案在等我」。

```bash
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 都拿得到：

```bash
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`。

```bash
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 之後保住它**。

```bash
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：

```bash
printf '%s\n' "$HERDR_WORKSPACE_ID" "$HERDR_TAB_ID" "$HERDR_PANE_ID"
```

所以在 pane 裡跑的腳本（**或 agent**）要指自己時，用 `--current`：

```bash
herdr pane split --current --direction right --cwd "$PWD" --no-focus
```

> ⚠️ **不要省略目標**。省略時 Herdr 會用「UI 目前 focus 的 pane」——那可能是使用者剛好切過去的、或是另一個 client 的。這是多 agent 編排最容易出的意外。

### split 的方向要看形狀

官方給的幾何規則：**寬的 pane 往右切，窄或高的 pane 往下切**，並且避免連續同方向切出無法使用的細長條。要知道形狀就先問：

```bash
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 命名

```bash
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**。

```bash
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*