6  第4章 工作区、标签与窗格

6.1 三层架构模型

Herdr 的界面组织遵循一个清晰的三层模型：Workspace → Tab → Pane。理解这三层之间的关系，是高效使用 Herdr 的基础。

graph TD
    subgraph "Workspace w1 (api-server)"
        T1["Tab w1:t1 — Agents"]
        T2["Tab w1:t2 — Logs"]
        T3["Tab w1:t3 — Server"]
        T1 --> P1["Pane w1:p1<br/>Claude Code"]
        T1 --> P2["Pane w1:p2<br/>OMP"]
        T2 --> P3["Pane w1:p3<br/>tail -f app.log"]
        T3 --> P4["Pane w1:p4<br/>npm run dev"]
        T3 --> P5["Pane w1:p5<br/>redis-cli"]
    end
    subgraph "Workspace w2 (frontend)"
        T4["Tab w2:t1 — Main"]
        T4 --> P6["Pane w2:p1<br/>Cursor Agent"]
    end
    style T1 fill:#4a9eff,color:#fff
    style T2 fill:#4a9eff,color:#fff
    style T3 fill:#4a9eff,color:#fff
    style T4 fill:#4a9eff,color:#fff

每一层的职责如下：

层级	概念	职责	类比
Workspace	项目级容器	绑定一个 Git 仓库，管理该项目所有终端会话	浏览器窗口
Tab	视图分区	在同一工作区内分离不同关注点（Agent、日志、服务器等）	浏览器标签页
Pane	真实终端	渲染输出、发送输入，每个 pane 对应一个 PTY	tmux 窗格

Note

核心原则：Workspace 是项目的边界，Tab 是注意力的分区，Pane 是执行的单元。三层各司其职，互不干扰。

---

6.2 Workspace：项目级容器

6.2.1 什么是 Workspace

Workspace 是 Herdr 的顶层组织单元。每个 Workspace 通常绑定一个 Git 仓库（或 Git Worktree），将该项目相关的所有终端活动收纳在同一个空间内。

与 tmux 的 session 不同，Herdr 的 Workspace 具有项目感知能力：

• 自动关联 Git 仓库：创建时绑定当前工作目录的 repo
• 侧边栏状态汇总：在侧边栏显示所有 Tab 和 Pane 的聚合状态
• 跨工作区切换：通过侧边栏或快捷键快速切换项目

6.2.2 创建 Workspace

# 基本创建：绑定当前目录的 Git 仓库
herdr workspace create --cwd ~/projects/api-server --label api

# 创建后自动获得 ID（如 w1）
# label 是人类可读的别名，用于侧边栏显示

创建 Workspace 时，Herdr 会：

1. 扫描 --cwd 指定目录的 Git 信息（分支、远程地址等）
2. 初始化第一个 Tab（w1:t1）和一个 Pane（w1:p1）
3. 将该 Workspace 添加到侧边栏
4. 自动聚焦到新创建的 Workspace

Tip

推荐实践：为每个活跃项目创建一个 Workspace。使用有意义的 --label，如 api、frontend、infra，方便在侧边栏快速识别。

6.2.3 列出 Workspace

# 列出所有 Workspace
herdr workspace list

# 输出示例：
# ID    LABEL       CWD                         BRANCH       TABS  PANES
# w1    api         ~/projects/api-server       main         3     5
# w2    frontend    ~/projects/web-client       feat/auth    2     3
# w3    infra       ~/projects/infrastructure   main         1     2

侧边栏也提供了可视化的 Workspace 列表，显示每个工作区的标签、活跃 Tab 数量和状态汇总。

6.2.4 聚焦 Workspace

# 通过 ID 聚焦
herdr workspace focus w1

# 通过 label 聚焦
herdr workspace focus api

聚焦操作会将选定的 Workspace 提到前台，并恢复上次活跃的 Tab 和 Pane。

6.2.5 重命名 Workspace

# 重命名
herdr workspace rename w1 --label "API Server v2"

重命名只修改 label（显示名称），不影响 ID 和内部结构。

6.2.6 关闭 Workspace

# 关闭（终止所有 Pane 中的进程）
herdr workspace close w1

# 关闭时确认
herdr workspace close w1 --confirm

Warning

注意：关闭 Workspace 会终止其中所有 Pane 的进程。如果有未保存的工作，请先在 Agent 中保存。

6.2.7 侧边栏状态汇总

侧边栏是 Workspace 的可视化控制中心。每个 Workspace 条目显示：

• Label 和 Git 分支：快速识别项目和当前分支
• Tab 数量：当前有多少个标签页
• 状态汇总图标：聚合所有 Tab/Pane 的状态

状态汇总遵循传播规则：

Pane 状态 → Tab 状态 → Workspace 状态 → 侧边栏图标

示例：
Pane w1:p1 = blocked  ─┐
Pane w1:p2 = working   ─┤→ Tab w1:t1 = blocked
Pane w1:p3 = working   ─┘
                        ↓
               Workspace w1 = blocked（侧边栏显示红色 ⚠）

Important

关键传播规则：只要有一个 Pane 处于 blocked 状态，其所在的 Tab 和 Workspace 都会显示 blocked。这确保你不会错过任何需要关注的 Agent 请求。

---

6.3 Tab：工作区内的视图分区

6.3.1 什么是 Tab

Tab 是 Workspace 内部的布局分区。当你需要在同一个项目中切换不同上下文时，Tab 提供了干净的分离：

• Agent Tab：运行 Claude Code、OMP 等 Coding Agent
• 日志 Tab：tail -f 实时查看应用日志
• 服务器 Tab：运行开发服务器、数据库等基础设施
• 审查 Tab：代码审查、diff 查看

每个 Tab 拥有独立的 Pane 布局，切换 Tab 时不会丢失各 Pane 的状态。

6.3.2 创建 Tab

# 创建新 Tab
herdr tab create --label logs

# 创建 Tab 并聚焦到它
herdr tab create --label "Code Review" --focus

# 在指定 Workspace 中创建
herdr tab create --workspace w1 --label server

新 Tab 创建时自动包含一个全屏 Pane。

6.3.3 列出 Tab

# 列出当前 Workspace 的所有 Tab
herdr tab list

# 输出示例：
# ID      LABEL          PANES  STATUS
# w1:t1   Agents         2      blocked
# w1:t2   Logs           1      idle
# w1:t3   Server         2      working

6.3.4 聚焦 Tab

# 通过 ID 聚焦
herdr tab focus w1:t2

# 相对切换
herdr tab next        # 下一个 Tab
herdr tab prev        # 上一个 Tab

6.3.5 重命名 Tab

herdr tab rename w1:t2 --label "Application Logs"

6.3.6 关闭 Tab

# 关闭 Tab（终止其中所有 Pane）
herdr tab close w1:t2

---

6.4 Pane：真实终端

6.4.1 什么是 Pane

Pane 是 Herdr 架构的最底层——一个真实的终端实例。每个 Pane 对应一个 PTY（伪终端），可以渲染输出和接收输入。

Pane 的核心能力：

能力	说明	命令
渲染输出	实时显示终端输出，支持滚动	herdr pane read
发送输入	向终端发送文本或按键	herdr pane send-text
执行命令	直接在 Pane 中运行命令	herdr pane run
状态检测	识别 Agent 状态	herdr pane report-agent
布局控制	分割、调整大小、缩放	herdr pane split

6.4.2 分割 Pane

# 向右分割（在当前 Pane 右侧创建新 Pane）
herdr pane split --current --direction right --no-focus

# 向下分割（在当前 Pane 下方创建新 Pane）
herdr pane split --current --direction down

# 指定比例分割
herdr pane split --current --direction right --percentage 30

6.4.3 分割策略指南

选择正确的分割方向对于可读性至关重要：

flowchart TD
    A[准备分割 Pane] --> B{窗口宽度 > 高度?}
    B -- 是（宽窗口） --> C[向右分割 →]
    B -- 否（窄/高窗口） --> D[向下分割 ↓]
    C --> E{已有右分割?}
    E -- 是 --> F["考虑新建 Tab<br/>避免过度水平分割"]
    E -- 否 --> G[执行 right split]
    D --> H{已有下分割?}
    H -- 是 --> I["考虑新建 Tab<br/>避免过度垂直分割"]
    H -- 否 --> J[执行 down split]
    F --> K[✅ 良好布局]
    G --> K
    I --> K
    J --> K

Tip

黄金法则： - 宽窗口（16:9 屏幕）→ 向右分割，并排查看 - 窄/高窗口（竖屏或半屏）→ 向下分割，上下堆叠 - 避免同方向连续分割：如果已经右分割了两次，再分割会让每个 Pane 太窄。此时应该新建 Tab。

6.4.4 布局检测

# 检测当前 Tab 的布局
herdr pane layout --current

# 输出示例：
# Tab: w1:t1
# Layout: horizontal
# Panes:
#   w1:p1 (50%) [Claude Code] — blocked
#   w1:p2 (50%) [OMP] — working

6.4.5 读取 Pane 输出

# 读取最近 120 行输出（不换行截断）
herdr pane read w1:p1 --source recent-unwrapped --lines 120

# 读取全部可见输出
herdr pane read w1:p1 --source visible

# 读取自上次检查以来的新输出
herdr pane read w1:p1 --source since-last-read

--source 参数说明：

Source	说明	适用场景
recent	最近 N 行（自动换行）	快速查看输出尾部
recent-unwrapped	最近 N 行（不截断长行）	查看完整长行输出（如编译错误）
visible	当前可见区域	截取当前屏幕
since-last-read	自上次读取以来的增量	只看新增输出，适合轮询

6.4.6 发送输入

Herdr 提供三种向 Pane 发送输入的方式：

6.4.6.1 send-text：发送文本

# 发送文本（不按回车）
herdr pane send-text w1:p1 "npm test"

# 发送文本并回车
herdr pane send-text w1:p1 "npm test" --enter

# 从文件发送
herdr pane send-text w1:p1 --file ./commands.sh

6.4.6.2 send-keys：发送特殊按键

# 发送 Ctrl+C
herdr pane send-keys w1:p1 C-c

# 发送 Tab 键（自动补全）
herdr pane send-keys w1:p1 Tab

# 发送方向键
herdr pane send-keys w1:p1 Up
herdr pane send-keys w1:p1 Down

6.4.6.3 run：直接执行命令

# 在指定 Pane 中执行命令
herdr pane run w1:p1 "git status"

# 执行并等待输出
herdr pane run w1:p1 "npm test" --timeout 30000

6.4.7 关闭 Pane

# 关闭单个 Pane
herdr pane close w1:p2

# 强制关闭（发送 SIGKILL）
herdr pane close w1:p2 --force

6.4.8 重命名 Pane

# 给 Pane 设置有意义的名称
herdr pane rename w1:p1 "Reviewer Agent"
herdr pane rename w1:p2 "Test Runner"

6.4.9 缩放 Pane

# 将 Pane 缩放到全屏（类似 tmux zoom）
herdr pane zoom w1:p1

# 再次执行恢复原始布局
herdr pane zoom w1:p1

---

6.5 ID 体系

Herdr 使用层级化的 ID 体系来唯一标识每个元素：

w1              ← Workspace（工作区）
├── w1:t1       ← Tab（标签页）
│   ├── w1:p1   ← Pane（窗格）
│   └── w1:p2   ← Pane
└── w1:t2       ← Tab
    └── w1:p3   ← Pane

6.5.1 ID 规则

元素	格式	示例	说明
Workspace	w{N}	w1, w2	全局递增编号
Tab	w{N}:t{M}	w1:t1, w1:t2	Workspace 内递增
Pane	w{N}:p{M}	w1:p1, w1:p2	Workspace 内全局递增（非 Tab 内）

Important

注意 Pane 编号：Pane ID 在 Workspace 内全局递增，而不是在 Tab 内重新计数。即 w1:p3 属于 w1:t2，而不是 w1:t2 的第 3 个 Pane。这样设计是因为 Pane 可以在 Tab 之间移动。

6.5.2 简写与别名

在大多数命令中，你可以使用简写：

# 完整 ID
herdr pane read w1:p1

# 如果当前已聚焦 w1，可省略 workspace 前缀
herdr pane read :p1

# 如果当前已聚焦 w1:t1 中的唯一 pane
herdr pane read --current

---

6.6 窗格分割实战

6.6.1 场景一：Agent + 日志监控

# 1. 创建 Workspace
herdr workspace create --cwd ~/projects/api-server --label api

# 2. 在第一个 Tab 中启动 Claude Code
# （w1:p1 已自动创建）

# 3. 向右分割一个 Pane 用于日志
herdr pane split --current --direction right

# 4. 在新 Pane 中启动日志监控
herdr pane run w1:p2 "tail -f /var/log/api-server.log"

# 5. 聚焦回左侧的 Agent Pane
herdr pane focus w1:p1

结果布局：

┌─────────────────┬─────────────────┐
│   w1:p1         │   w1:p2         │
│   Claude Code   │   tail -f log   │
│   (Agent)       │   (Monitoring)  │
└─────────────────┴─────────────────┘

6.6.2 场景二：多 Agent 协作

# 创建专门的 Agent Tab
herdr tab create --label "Agents"

# 分割为两个并排 Pane
herdr pane split --current --direction right

# 左侧运行 Claude Code（编码）
herdr pane run w1:p1 "claude"

# 右侧运行 OMP（审查）
herdr pane run w1:p2 "omp"

# 重命名以便区分
herdr agent rename w1:p1 "coder"
herdr agent rename w1:p2 "reviewer"

6.6.3 场景三：全栈开发环境

# Tab 1: Frontend
herdr tab create --label "Frontend"
herdr pane run w1:p1 "cd frontend && npm run dev"

# Tab 2: Backend
herdr tab create --label "Backend"
herdr pane run w1:p1 "cd backend && python manage.py runserver"

# Tab 3: Database
herdr tab create --label "Database"
herdr pane run w1:p1 "psql -d myapp"

# Tab 4: Agents
herdr tab create --label "Agents"
herdr pane run w1:p1 "claude"

---

6.7 Git Worktree 集成

6.7.1 从侧边栏创建 Worktree

Herdr 支持与 Git Worktree 深度集成。你可以直接从侧边栏创建 Worktree，Herdr 会自动为每个 Worktree 创建关联的 Workspace：

# 创建 Worktree 并关联 Workspace
herdr workspace create --cwd ~/projects/api-server \
  --label "feature-auth" \
  --worktree feat/authentication

这条命令会：

1. 在 ~/projects/api-server 中创建 Git Worktree（分支 feat/authentication）
2. 创建关联的 Workspace，--cwd 指向 Worktree 目录
3. 在侧边栏中显示新 Workspace

6.7.2 Worktree 的优势

传统方式	Herdr Worktree 集成
切换分支打断当前工作	每个 Worktree 独立 Workspace，互不干扰
git stash 管理混乱	不需要 stash，各分支独立运行
无法同时运行两个分支的 Agent	不同 Workspace 的 Agent 完全并行

graph LR
    subgraph "主仓库 ~/projects/api-server"
        W1["w1: main<br/>（主线开发）"]
    end
    subgraph "Worktree ~/projects/api-server-feat-auth"
        W2["w2: feat/auth<br/>（功能开发）"]
    end
    subgraph "Worktree ~/projects/api-server-hotfix"
        W3["w3: hotfix/v1.2<br/>（紧急修复）"]
    end
    W1 -.->|"herdr workspace create<br/>--worktree"| W2
    W1 -.->|"herdr workspace create<br/>--worktree"| W3

Tip

实战推荐：当你需要在不打断当前 Agent 工作的情况下处理紧急修复或开始新功能时，使用 Worktree + Workspace 组合。这比 git stash + git checkout 的传统流程高效得多。

---

6.8 小结

本章介绍了 Herdr 的核心三层架构：

• Workspace 绑定项目，提供隔离的工作环境
• Tab 分区注意力，将不同类型的终端活动组织在不同标签页
• Pane 执行命令，是真实终端的最小单元

掌握了这三层模型，你就可以高效地组织多项目、多 Agent、多任务的终端工作流。下一章我们将深入 Agent 体系，了解 Herdr 如何识别和管理各种 Coding Agent。