7  第5章 Agent 体系

7.1 Agent 是什么

在 Herdr 的语境中，Agent 是运行在 Pane 中的 Coding Agent 进程——比如 Claude Code、OMP、Codex 等。Herdr 不是简单的终端复用器，它能够识别这些 Agent 的存在、检测它们的运行状态，并在此基础上提供智能化的工作流管理。

graph TB
    subgraph "Herdr Agent 管理层"
        A[Agent 检测引擎]
        B[状态机]
        C[状态传播]
        D[集成管理器]
    end
    subgraph "Pane 中的 Agent 进程"
        E["Claude Code"]
        F["OMP"]
        G["Codex"]
        H["Kimi Code"]
    end
    A --> E
    A --> F
    A --> G
    A --> H
    A --> B
    B --> C
    D --> A
    style A fill:#4a9eff,color:#fff
    style B fill:#f59e0b,color:#fff
    style C fill:#10b981,color:#fff
    style D fill:#8b5cf6,color:#fff

与普通终端进程不同，Agent 具有以下特征：

• 有状态：Agent 会经历 idle → working → blocked → done 的生命周期
• 需要交互：Agent 可能请求人类审批或输入
• 可标识：Herdr 能通过进程检测或屏幕内容识别 Agent 类型
• 可命名：你可以为 Agent 设置自定义标签，便于区分多个实例

---

7.2 支持的 Agent 完整列表

Herdr 支持主流的 Coding Agent，分为两种检测机制：

7.2.1 生命周期钩子型（Lifecycle Hooks）

这些 Agent 提供了编程接口，Herdr 可以通过钩子精确追踪其状态变化：

Agent	说明	安装命令
Pi	Herdr 内置 Agent	内置
OMP	Open Multi-agent Platform	herdr integration install omp
Claude Code	Anthropic 的 CLI 编码 Agent	herdr integration install claude
Codex	OpenAI 的 CLI 编码 Agent	herdr integration install codex
Kimi Code	Moonshot 的编码 Agent	herdr integration install kimi-code
Hermes	开源编码 Agent	herdr integration install hermes
OpenCode	开源 AI 编码助手	herdr integration install opencode
Kilo Code	轻量级编码 Agent	herdr integration install kilo-code
MastraCode	基于 Mastra 框架的 Agent	herdr integration install mastracode

7.2.2 屏幕清单检测型（Screen Checklist Detection）

这些 Agent 没有公开的生命周期钩子 API，Herdr 通过检测终端屏幕内容（正则匹配、关键词识别）来推断状态：

Agent	说明	检测方式
GitHub Copilot CLI	GitHub 的命令行 Copilot	屏幕清单
Devin CLI	Cognition 的 CLI Agent	屏幕清单
Cursor Agent CLI	Cursor 的命令行模式	屏幕清单
Qoder CLI	Qoder 编码 Agent	屏幕清单
Droid	Factory AI 的 Droid Agent	屏幕清单
Amp	Sourcegraph 的 Amp Agent	屏幕清单
Grok CLI	xAI 的编码 Agent	屏幕清单
Antigravity CLI	Antigravity 编码 Agent	屏幕清单
Kiro CLI	Kiro 编码 Agent	屏幕清单
Maki	Maki 编码 Agent	屏幕清单

Note

两种检测机制的区别： - 生命周期钩子：精确、实时，状态变化由 Agent 主动推送 - 屏幕清单检测：轮询式，通过分析终端输出推断状态，可能有延迟

---

7.3 Agent 状态机

每个 Agent 在运行过程中会经历不同的状态。Herdr 定义了五状态模型：

stateDiagram-v2
    [*] --> idle: Agent 启动
    idle --> working: 用户发送指令
    working --> blocked: 需要审批/决策/输入
    working --> done: 任务完成（后台）
    blocked --> working: 用户响应
    blocked --> idle: 用户取消
    done --> idle: 用户查看 Tab
    working --> idle: 用户中断
    
    note right of idle: 就绪等待输入\ntab 已被查看
    note right of working: 正在执行任务
    note right of blocked: 需要人类介入
    note right of done: 后台完成\n尚未被查看

7.3.1 状态详解

状态	含义	视觉标识	触发条件
idle	就绪等待输入	🟢 绿色	Agent 启动、任务完成后用户已查看
working	正在工作	🔵 蓝色（动画）	Agent 接收到指令正在执行
blocked	需要审批/决策/输入	🟡 黄色 ⚠	Agent 发出提问、请求确认
done	后台完成但尚未查看	🟣 紫色	Agent 在非当前 Tab 完成任务
unknown	无法确定状态	⚪ 灰色	检测失败或 Agent 未响应

Important

done 状态的设计意图：当你在 Tab A 工作时，Tab B 中的 Agent 完成了任务。Herdr 不会直接将其标记为 idle，而是标记为 done，提醒你有新的工作成果需要查看。只有当你切换到该 Tab 查看后，状态才变为 idle。

7.3.2 状态转换示例

用户在 Tab w1:t1（Claude Code）中工作

  时间线：
  t=0    用户输入 "重构 auth 模块"        → working
  t=30s  Claude 请求确认删除旧文件        → blocked ⚠
  t=35s  用户确认 "yes"                   → working
  t=2m   Claude 完成重构                  → done（如果用户在其他 Tab）
  t=2m   用户切回 w1:t1 查看              → idle ✅

---

7.4 状态权限（Status Authority）

不同检测机制对状态判断的权威性不同：

graph TD
    A["生命周期钩子<br/>（Claude Code, OMP, ...）"] -->|"最高权威"| B[精确状态]
    C["屏幕清单检测<br/>（Copilot CLI, Devin, ...）"] -->|"推测状态"| D[推断状态]
    B --> E["可信，可直接用于工作流"]
    D --> F["参考性，可能存在延迟或误判"]
    style A fill:#10b981,color:#fff
    style C fill:#f59e0b,color:#fff

检测方式	精确度	实时性	可信度
生命周期钩子	精确	实时（事件驱动）	⭐⭐⭐⭐⭐
屏幕清单检测	推断	延迟（轮询间隔）	⭐⭐⭐

Warning

使用屏幕检测型 Agent 时注意：状态可能有几秒延迟。如果你的工作流高度依赖状态变化（如自动触发下一步），优先选择生命周期钩子型 Agent。

---

7.5 状态汇总（State Rollup）

Agent 状态不仅影响当前 Pane，还会向上传播到 Tab 和 Workspace 层级：

7.5.1 传播规则

Pane 状态传播优先级：

  blocked > working > done > idle > unknown

graph BT
    P1["Pane w1:p1<br/>idle"] --> T1
    P2["Pane w1:p2<br/>blocked ⚠"] --> T1
    P3["Pane w1:p3<br/>working"] --> T1
    T1["Tab w1:t1<br/>blocked ⚠（最高优先级）"]
    T1 --> W1["Workspace w1<br/>blocked ⚠"]
    W1 --> S1["侧边栏<br/>⚠ 红色图标"]

    P4["Pane w1:p4<br/>done"] --> T2
    P5["Pane w1:p5<br/>idle"] --> T2
    T2["Tab w1:t2<br/>done（未查看）"]
    T2 --> W1

    style P2 fill:#f59e0b,color:#fff
    style T1 fill:#f59e0b,color:#fff
    style W1 fill:#f59e0b,color:#fff
    style S1 fill:#f59e0b,color:#fff
    style P4 fill:#8b5cf6,color:#fff
    style T2 fill:#8b5cf6,color:#fff

7.5.2 传播规则详解

1. Tab 状态 = 其中所有 Pane 状态的最高优先级
2. Workspace 状态 = 其中所有 Tab 状态的最高优先级
3. blocked 优先：只要有一个 Pane 是 blocked，整个 Workspace 在侧边栏显示 ⚠

Tip

为什么 blocked 优先？ 因为 blocked 意味着 Agent 正在等待你的响应。即使其他 Agent 正在工作，你的注意力应该优先分配给被阻塞的 Agent。

---

7.6 Agent 集成安装

7.6.1 安装 Agent 集成

对于生命周期钩子型 Agent，你需要安装对应的集成包：

# 安装 Claude Code 集成
herdr integration install claude

# 安装 OMP 集成
herdr integration install omp

# 安装 Codex 集成
herdr integration install codex

# 输出示例：
# ✅ Integration 'claude' installed successfully
#    - Lifecycle hooks: enabled
#    - State detection: real-time
#    - Default label: "Claude Code"

7.6.2 查看集成状态

# 查看所有已安装的集成
herdr integration status

# 输出示例：
# AGENT          TYPE        STATUS       VERSION
# Claude Code    lifecycle   ✅ active    1.2.0
# OMP            lifecycle   ✅ active    0.9.1
# Codex          lifecycle   ⚠ outdated   1.0.0 → 1.1.0
# Kimi Code      lifecycle   ❌ disabled  —
# Copilot CLI    screen      ✅ built-in  —
# Devin CLI      screen      ✅ built-in  —

7.6.3 更新集成

# 更新单个集成
herdr integration update claude

# 更新所有过期集成
herdr integration update --all

---

7.7 自定义 Agent 标签

7.7.1 重命名 Agent

在多 Agent 工作流中，为每个 Pane 设置有意义的名称非常重要：

# 重命名 Pane 中的 Agent
herdr agent rename w1:p1 "coder"
herdr agent rename w1:p2 "reviewer"
herdr agent rename w1:p3 "test-runner"

重命名后，这些标签会显示在： - Pane 边框标题 - Tab 工具提示 - herdr pane list 输出 - 侧边栏状态详情

7.7.2 自定义状态标签

有时 Agent 的状态不足以描述当前情况。Herdr 允许你手动报告 Agent 状态和元数据：

# 手动报告 Agent 状态
herdr pane report-agent w1:p1 --status blocked --message "等待用户确认数据库迁移方案"

# 报告额外元数据
herdr pane report-metadata w1:p1 \
  --key "task" \
  --value "重构认证模块"

# 清除自定义报告
herdr pane report-agent w1:p1 --clear

Tip

使用场景：当你手动在 Pane 中运行一个长时间脚本（非标准 Agent），或者想要为某个 Pane 添加自定义状态标注时，report-agent 和 report-metadata 非常有用。

---

7.8 Agent 直接附加

7.8.1 attach 命令

你可以直接附加（attach）到指定的 Agent，快速恢复交互：

# 通过标签名附加
herdr agent attach reviewer

# 通过 Pane ID 附加
herdr agent attach w1:p2

attach 操作会： 1. 聚焦到对应的 Pane 2. 将输入焦点设置到 Agent 的提示符 3. 恢复滚动到 Agent 最新输出位置

7.8.2 多 Agent 编排示例

# 1. 创建多 Agent 工作区
herdr workspace create --cwd ~/projects/api --label api

# 2. 设置编码 Agent
herdr pane run w1:p1 "claude"
herdr agent rename w1:p1 "coder"

# 3. 分割并设置审查 Agent
herdr pane split --current --direction right
herdr pane run w1:p2 "omp"
herdr agent rename w1:p2 "reviewer"

# 4. 在编码 Agent 中工作...
# 当 reviewer 有反馈时，快速切换
herdr agent attach reviewer

# 5. 回到编码
herdr agent attach coder

---

7.9 VM/沙箱包装器

在需要隔离的环境中运行 Agent 时，Herdr 支持 VM/沙箱包装器：

7.9.1 基本用法

# 在 VM/sandbox 中运行 Claude Code
HERDR_AGENT=claude fence -- claude

# 使用自定义 VM 配置
HERDR_AGENT=claude fence --vm-config ./vm-config.yaml -- claude --model opus

# 在容器中运行 OMP
HERDR_AGENT=omp fence --docker -- omp serve

7.9.2 工作原理

graph LR
    A[Herdr] -->|"设置环境变量"| B["HERDR_AGENT=claude"]
    B --> C[fence 沙箱包装器]
    C --> D["隔离环境<br/>VM / Docker / 沙箱"]
    D --> E["claude 进程"]
    C -->|"状态钩子"| A
    E -->|"输出"| D
    D -->|"渲染"| A

HERDR_AGENT 环境变量告诉 Herdr 当前要运行的 Agent 类型，fence 命令创建隔离边界。即使 Agent 在沙箱中运行，Herdr 仍然能追踪其状态。

Note

fence 的作用：fence 创建一个隔离边界，确保 Agent 的文件系统访问、网络请求等限制在沙箱范围内，同时保持与 Herdr 的状态通信通道。

7.9.3 支持的沙箱类型

类型	参数	说明
VM	--vm	轻量级虚拟机隔离
Docker	--docker	Docker 容器隔离
沙箱	--sandbox	OS 级沙箱（seatbelt/firejail）
自定义	--vm-config	自定义隔离配置文件

---

7.10 检测清单（Detection Manifests）

7.10.1 什么是检测清单

检测清单是 Herdr 用来识别 Agent 类型及其状态的配置文件。每个 Agent 都有一份清单，定义了：

• 进程识别规则：如何判断一个进程是否为该 Agent
• 状态模式：如何从终端输出中推断当前状态
• 提示符模式：如何识别 Agent 的输入提示符
• 完成条件：如何判断任务已完成

7.10.2 本地覆盖

你可以为特定 Agent 创建本地覆盖清单：

# 创建本地覆盖
herdr agent manifest create --agent claude --output ~/.herdr/manifests/claude.yaml

本地清单示例（~/.herdr/manifests/claude.yaml）：

agent: claude
detection:
  # 进程名匹配
  process:
    - "claude"
    - "claude-code"
  # 命令行参数匹配
  args:
    contains: "--anthropic-api-key"
  
states:
  idle:
    # 匹配空闲状态的屏幕模式
    screen:
      - pattern: "^claude>"
        type: "prompt"
  working:
    screen:
      - pattern: "Thinking..."
        type: "marker"
      - pattern: "Generating..."
        type: "marker"
  blocked:
    screen:
      - pattern: "Do you want to.*\\?"
        type: "question"
      - pattern: "Press ENTER to continue"
        type: "pause"
  done:
    screen:
      - pattern: "Task completed"
        type: "completion"

7.10.3 远程更新

Herdr 会定期从远程仓库拉取最新的检测清单：

# 手动更新检测清单
herdr agent manifest update

# 查看清单版本
herdr agent manifest list --verbose

# 输出示例：
# AGENT         SOURCE     VERSION    UPDATED
# claude        remote     1.2.3      2026-07-28
# omp           remote     0.9.5      2026-07-25
# codex         remote     1.1.0      2026-07-30
# claude        local      custom     (覆盖远程)

Tip

本地覆盖优先级：如果存在同名 Agent 的本地清单，本地清单会与远程清单合并，本地规则优先匹配。这允许你在官方清单更新前临时调整检测规则。

---

7.11 调试工具：agent explain

当 Agent 状态检测不正确时，herdr agent explain 是你的首选调试工具：

7.11.1 基本用法

# 解释当前 Pane 的 Agent 检测结果
herdr agent explain --current

# 解释指定 Pane
herdr agent explain w1:p1

7.11.2 输出示例

━━━ Agent Detection Report for w1:p1 ━━━

📋 Detection Pipeline:
  1. Process scan: ✅ Found "claude" (PID 45231)
  2. Manifest match: ✅ Matched "claude" (remote v1.2.3)
  3. Lifecycle hook: ✅ Connected (websocket :9832)
  4. State determination: ✅ blocked

📊 Current State: blocked
   Source: lifecycle-hook (highest authority)
   Message: "Do you want to proceed with deleting 3 files?"
   Duration: 45s

🖥️ Screen Analysis:
   Last 5 lines matched against patterns:
   Line 47: "Do you want to proceed with deleting 3 files?"
     → matched blocked pattern: "Do you want to.*\\?" (confidence: 0.95)
   
🔍 Manifest Details:
   Manifest: claude (remote v1.2.3)
   Process patterns: ["claude", "claude-code"]
   Hook endpoint: ws://localhost:9832
   Hook status: connected
   
⚙️ Configuration:
   Integration: installed (v1.2.0)
   Custom label: "coder"
   Custom report: none

7.11.3 调试流程

flowchart TD
    A["Agent 状态异常？"] --> B["运行 herdr agent explain"]
    B --> C{检测结果正确？}
    C -- 是 --> D["问题在其他地方<br/>检查网络/权限等"]
    C -- 否 --> E{使用哪种检测？}
    E -- 生命周期钩子 --> F["检查集成版本<br/>herdr integration status"]
    E -- 屏幕清单 --> G["检查终端输出<br/>是否符合清单模式"]
    F --> H{集成过期？}
    H -- 是 --> I["更新集成<br/>herdr integration update"]
    H -- 否 --> J["查看 hook 日志<br/>herdr agent logs"]
    G --> K{模式不匹配？}
    K -- 是 --> L["创建本地覆盖清单"]
    K -- 否 --> M["提交 issue 报告"]
    I --> N["✅ 问题解决"]
    J --> N
    L --> N
    M --> N

7.11.4 常见问题排查

问题	可能原因	解决方案
状态始终显示 unknown	检测清单未安装或不匹配	运行 herdr agent explain，检查 manifest 匹配
状态不更新	生命周期钩子断开	检查 herdr integration status，重启 Agent
blocked 未被检测到	屏幕清单模式过时	创建本地覆盖清单或更新远程清单
Agent 未被识别	进程名不在清单中	检查进程名，添加自定义检测规则

---

7.12 Agent 工作流最佳实践

7.12.1 单 Agent 深度工作

# 一个 Workspace 一个 Agent，专注深度编码
herdr workspace create --cwd ~/project --label main
herdr pane run w1:p1 "claude"

# 辅助 Tab 用于参考
herdr tab create --label "ref"
herdr pane run w1:p2 "tail -f CHANGELOG.md"

7.12.2 多 Agent 流水线

# Tab 1: 编码
herdr tab create --label "code"
herdr pane run w1:p1 "claude"
herdr agent rename w1:p1 "coder"

# Tab 2: 审查
herdr tab create --label "review"
herdr pane run w1:p2 "omp"
herdr agent rename w1:p2 "reviewer"

# Tab 3: 测试
herdr tab create --label "test"
herdr pane run w1:p3 "codex"
herdr agent rename w1:p3 "tester"

状态传播让你随时了解全局：

侧边栏:
  w1 main  ⚠ blocked   ← coder 请求确认
            ✓ done     ← reviewer 已完成审查
            🔵 working  ← tester 正在运行测试

7.12.3 Agent 混合检测策略

当你同时使用钩子型和屏幕检测型 Agent 时：

# 钩子型（高可信）作为主 Agent
herdr pane run w1:p1 "claude"          # lifecycle

# 屏幕检测型（参考性）作为辅助
herdr pane split --current --direction right
herdr pane run w1:p2 "copilot cli"     # screen

Important

注意：屏幕检测型 Agent 的状态仅供参考。在关键工作流（如自动审批、条件触发）中，只依赖钩子型 Agent 的状态。

---

7.13 小结

本章深入解析了 Herdr 的 Agent 体系：

• 19 种 Agent 支持：覆盖主流编码 Agent，分为生命周期钩子和屏幕检测两种机制
• 五状态模型：idle / working / blocked / done / unknown，完整描述 Agent 生命周期
• 状态传播：从 Pane 到 Tab 到 Workspace，blocked 优先确保你不遗漏重要请求
• 集成管理：一键安装、更新、调试 Agent 集成
• 高级特性：VM/沙箱包装器、自定义标签、手动状态报告、检测清单覆盖

掌握了 Agent 体系，你就可以构建高效的多 Agent 协作工作流。下一章我们将学习键盘操作，用快捷键极速操控这一切。