graph TD
A[Herdr Session 持久化] --> B["Live Persistence<br/>分离保持运行"]
A --> C["Snapshot Restore<br/>重启后恢复布局"]
A --> D["Pane Screen History<br/>终端回放"]
A --> E["Native Agent Session<br/>Agent 会话恢复"]
A --> F["Live Handoff<br/>实验性热更新"]
B --> B1[detach → 进程继续]
B --> B2[reattach → UI 恢复]
C --> C1[保存布局快照]
C --> C2[重启后加载快照]
D --> D1[保存终端输出历史]
D --> D2[scrollback 完整保留]
E --> E1[Claude Code 自身的 session]
E --> E2[恢复 Agent 对话上下文]
F --> F1[运行中更新 Herdr 版本]
F --> F2[不中断 Agent]
9 第7章 单 Agent 工作流
9.1 场景概述：一个开发者 + 一个 Agent 的日常
在 AI 辅助编程的时代，最常见的开发模式不是多 Agent 协作，而是一个开发者配合一个 Coding Agent。你有一个 Herdr 工作空间，一个 Agent 标签页，一个 Claude Code 实例——这就是 80% 开发者的日常。
听起来简单，但魔鬼藏在细节里：
- Agent 跑到一半你要去开会，怎么办？
- 下班了，Agent 还在跑长任务，能关机吗？
- 第二天回来，怎么恢复昨天的工作上下文？
- 怎么同时看 Agent 输出、测试日志和本地服务器？
Herdr 的设计哲学是：让单 Agent 工作流像呼吸一样自然。你不需要学习复杂的命令，只需要理解一个核心概念——Session 持久化。
9.2 在 Herdr 中运行 Claude Code
9.2.1 启动你的第一个 Agent
打开终端，输入：
herdrHerdr 会创建一个默认工作空间。按 c 新建一个标签页，命名为 agent：
┌─────────────────────────────────────────────────┐
│ [main] [agent] [server] [logs] │
├─────────────────────────────────────────────────┤
│ │
│ $ claude │
│ ╭──────────────────────────────────────╮ │
│ │ Claude Code v2.0.1 │ │
│ │ Model: claude-sonnet-4.5 │ │
│ │ Repo: ~/projects/my-app │ │
│ ╰──────────────────────────────────────╯ │
│ │
│ > │
│ │
├─────────────────────────────────────────────────┤
│ ● agent: idle │ main: bash │ 23:41 │
└─────────────────────────────────────────────────┘在 Agent 标签页中启动 Claude Code：
cd ~/projects/my-app
claude此时 Herdr 会自动识别这是一个 Coding Agent，侧边栏会显示 Agent 状态。
9.2.2 Agent 状态监控
Herdr 的侧边栏（Sidebar）会实时显示 Agent 的状态：
| 状态 | 颜色 | 含义 |
|---|---|---|
idle |
🟢 绿色 | Agent 空闲，等待输入 |
working |
🟡 黄色 | Agent 正在执行任务 |
blocked |
🔴 红色 | Agent 遇到阻塞，需要人工介入 |
error |
⚫ 灰色 | Agent 进程异常退出 |
waiting |
🔵 蓝色 | Agent 等待用户确认 |
当 Agent 进入 blocked 状态时，Herdr 会在状态栏闪烁提醒。你不需要一直盯着 Agent 的输出——切到其他标签页做自己的事，等 Agent 需要你的时候再切回来。
Note为什么状态监控如此重要？
传统的终端中，Claude Code 如果需要你确认（比如 “是否执行这个命令？”），你不去看就不知道。在 Herdr 中，即使你在另一个标签页写代码，侧边栏的红色 blocked 标记也会提醒你：该回去看看了。
9.3 多标签工作流
单 Agent 不意味着只有一个标签页。一个高效的单 Agent 工作流通常是这样布局的：
┌──────────────────────────────────────────────────────────┐
│ [code:main] [agent] [server] [logs] [docs] │
├──────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ Tab: agent │ │
│ │ ┌────────────────────┬─────────────────────┐ │ │
│ │ │ │ │ │ │
│ │ │ Claude Code │ Agent Log │ │ │
│ │ │ (主交互) │ (自动滚动) │ │ │
│ │ │ │ │ │ │
│ │ └────────────────────┴─────────────────────┘ │ │
│ └──────────────────────────────────────────────────┘ │
│ │
├──────────────────────────────────────────────────────────┤
│ ● agent: working │ server: running │ 23:41 │
└──────────────────────────────────────────────────────────┘9.3.1 标签页分工
| 标签页 | 用途 | 示例命令 |
|---|---|---|
code:main |
你手动写代码的地方 | vim src/index.ts |
agent |
Claude Code 运行环境 | claude |
server |
开发服务器 | npm run dev |
logs |
实时日志 | tail -f logs/app.log |
docs |
API 文档参考 | open api-docs.html |
9.3.2 快速创建标签布局
你可以用 Herdr 的布局命令快速创建这套结构：
# 在 Herdr 中，按 c 创建标签页
# 标签 1: code:main (默认)
# 标签 2: agent → 启动 claude
# 标签 3: server → npm run dev
# 标签 4: logs → tail -f logs/app.log或者使用 Herdr 的 layout 配置文件：
# .herdr/layout.toml
[[tabs]]
name = "code"
panes = [{ command = "nvim", size = 1.0 }]
[[tabs]]
name = "agent"
panes = [{ command = "claude", size = 1.0 }]
[[tabs]]
name = "server"
panes = [{ command = "npm run dev", size = 1.0 }]
[[tabs]]
name = "logs"
panes = [{ command = "tail -f logs/app.log", size = 1.0 }]启动时直接加载：
herdr --layout .herdr/layout.toml
Tip布局即代码
把你的常用布局保存为 .herdr/layout.toml，提交到 Git 仓库。这样团队成员 clone 仓库后，一条命令就能恢复完整的工作环境。
9.4 分离与重连：Session 持久化
这是 Herdr 最核心的能力，也是它区别于普通终端模拟器的关键。
9.4.1 问题：终端关闭 = 进程消失
在传统的终端中，如果你关闭终端窗口（或 SSH 连接断开），里面运行的所有进程都会被杀死。Claude Code 跑了一小时的任务，网络一闪——没了。
9.4.2 解决方案：Herdr Session
Herdr 维护了一个持久的会话层。当你”分离”（detach）时：
- Herdr 进程继续在后台运行
- 所有标签页和其中的进程（包括 Claude Code）继续执行
- 终端 UI 断开，但后端活着
当你”重连”（reattach）时：
- Herdr 恢复终端 UI
- 所有标签页恢复到分离时的状态
- Agent 的输出历史完整保留
# 分离（不关闭 Herdr）
# 按 Ctrl+B, D
# 或者直接关闭终端窗口（Herdr 会自动 detach）
# 重连
herdr attach
# 或者如果有多个 session
herdr session list
herdr session attach main9.4.3 Session 持久化的五个层次
Herdr 的持久化不是一个简单的功能，而是五个层次的系统：
9.4.3.1 1. Live Persistence（分离保持运行）
最基础的持久化。当你 detach 后，所有进程继续运行：
# 启动 Herdr，开始一个长任务
herdr
# 在 Agent 标签页让 Claude Code 跑一个重构任务
# 分离（Agent 继续跑！）
# Ctrl+B, D
# 你可以关掉终端、锁屏、去喝咖啡
# 甚至断开 SSH 连接
# 回来后重连
herdr attach
# Claude Code 的输出完整保留，任务可能已经完成了原理：Herdr 使用 PTY（伪终端）层来管理进程。detach 只是断开了前端渲染，后端的 PTY 和进程管理器仍在运行。
9.4.3.2 2. Snapshot Restore（重启后恢复布局）
如果你的电脑重启了（或者 Herdr 进程被手动杀死），Live Persistence 就失效了。但 Herdr 还能恢复你的工作空间布局：
# Herdr 会定期保存布局快照
# 保存位置：~/.local/share/herdr/snapshots/
# 重启后，Herdr 会提示恢复
herdr
# > 检测到上次会话快照（2小时前），是否恢复？ [Y/n]快照内容包括：
- 标签页名称和顺序
- 每个标签页的 pane 布局
- 每个 pane 的工作目录
- 每个 pane 的启动命令（如果能推断）
Warning快照的限制
快照恢复的是布局，不是进程状态。比如你的开发服务器不会自动重启，你需要手动重新运行。但 Agent 标签页会尝试恢复 Claude Code 的 session（见下文）。
9.4.3.3 3. Pane Screen History Replay
每个 pane 的终端输出历史（scrollback）会被持久化保存。即使重启后，你也能回看 Agent 之前的输出：
# 重连后，在 Agent 标签页
# 按 PageUp 进入 scrollback 模式
# 可以看到分离期间 Agent 的所有输出这在实际使用中极其有用——你下班时让 Agent 跑一个任务，第二天回来不仅能看到结果，还能看到 Agent 的完整推理过程。
9.4.3.4 4. Native Agent Session Restore
Claude Code 自身也有 session 持久化能力。当 Herdr 恢复 Agent 标签页时，会尝试恢复 Claude Code 的对话上下文：
# Claude Code 的 session 保存在 ~/.claude/sessions/
# Herdr 重连时会检查并尝试恢复
# 如果 Claude Code 支持 --resume 参数
herdr 会自动执行: claude --resume <session-id>
Note双层持久化
Herdr 的持久化 + Claude Code 自身的持久化 = 双重保险。即使 Herdr 重启了，Claude Code 的对话历史也不会丢失。
9.4.3.5 5. Live Handoff（实验性）
这是 Herdr 最前沿的特性：在不中断运行进程的情况下，热更新 Herdr 自身。
# 场景：Herdr 有新版本了，但你的 Agent 正在跑重要任务
# 传统方式：关闭 Herdr → 更新 → 重启（任务中断）
# Live Handoff：运行中的进程不中断，只替换 Herdr 的管理层
herdr upgrade --live
# > 正在执行 live handoff...
# > Agent 进程保留中...
# > Herdr 核心已更新到 v1.5.0
# > Handoff 完成，无中断
Warning实验性功能
Live Handoff 目前还是实验性功能，在某些复杂布局下可能不稳定。建议在非关键任务中先测试。
9.4.4 一张图理解完整流程
sequenceDiagram
participant U as 用户
participant T as 终端
participant H as Herdr 后端
participant A as Agent (Claude Code)
participant F as 文件系统
U->>T: herdr
T->>H: 创建 session
H->>A: 启动 Claude Code
U->>A: "重构这个模块"
A-->>U: 开始执行...
U->>T: detach (Ctrl+B, D)
T-->>U: 终端 UI 关闭
Note over H,A:"后端继续运行！<br/>Agent 继续执行任务"
U->>T: (去吃晚饭)
A->>F: 修改文件
A->>H: 更新状态为 done
U->>T: herdr attach
T->>H: 恢复 UI
H-->>U: 显示完整输出历史
Note over U,A:"任务已完成，<br/>输出历史完整保留"
9.5 Agent 直接附加模式
除了在 Herdr 的标签页中启动 Agent 外，你还可以用 herdr agent attach 直接将 Agent 附加到现有终端：
# 在普通终端中启动 Claude Code
cd ~/projects/my-app
claude
# 在另一个终端中，将这个 Agent 纳入 Herdr 管理
herdr agent attach
# Herdr 会检测到当前终端的 Agent 进程
# 并将其纳入 Herdr 的状态管理这在你已经有一个运行中的 Agent、但想用 Herdr 管理它时非常有用。
9.5.1 agent attach vs 标签页启动
| 特性 | 标签页启动 | agent attach |
|---|---|---|
| Agent 自动识别 | ✅ | ✅ |
| 状态监控 | ✅ | ✅ |
| Session 持久化 | ✅ | ✅ |
| 布局恢复 | ✅ | ❌（依赖外部终端） |
| 适用场景 | 全新工作流 | 已有运行中 Agent |
| 多 Agent 管理 | ✅ | ✅ |
9.6 Worktree 工作流：Git 分支管理
当 Agent 在修改代码时，你可能想同时在另一个分支上工作。Herdr 集成了 Git Worktree 支持：
9.6.1 从侧边栏创建 Worktree
# 在 Herdr 侧边栏的 Git 面板中
# 按 w 打开 Worktree 菜单
┌─────────────────────────────┐
│ Git Worktree │
├─────────────────────────────┤
│ > main (当前) │
│ feature/auth │
│ feature/api-refactor │
│ + 新建 worktree... │
└─────────────────────────────┘选择 “新建 worktree”，输入分支名：
┌─────────────────────────────┐
│ 新分支名: feature/login │
│ 路径: ../my-app-login │
│ [创建] [取消] │
└─────────────────────────────┘Herdr 会在新标签页中打开这个 worktree：
# 自动执行
cd ~/projects/my-app-login
# 这是一个独立的 worktree，在 feature/login 分支上9.6.2 为什么 Worktree + Agent 是绝配？
graph LR
R[Git 仓库] --> WT1["Worktree: main<br/>你的手动工作"]
R --> WT2["Worktree: feature/auth<br/>Agent A 工作"]
R --> WT3["Worktree: feature/api<br/>Agent B 工作"]
WT1 --> |互不干扰| WT2
WT2 --> |互不干扰| WT3
Tip避免 Agent 互相踩踏
如果你有多个 Agent 同时修改代码（即使是单 Agent 工作流，你也会手动改代码），Worktree 确保每个工作区操作不同的分支，互不干扰。
9.7 实战案例：用 Herdr + Claude Code 开发 Express API
让我们用一个完整的实战案例来串联本章的所有知识点。
9.7.1 需求
开发一个 Express.js REST API，包含用户注册、登录、CRUD 文章功能。
9.7.2 第一步：初始化项目
# 启动 Herdr
herdr
# 在 main 标签页
mkdir express-api && cd express-api
npm init -y
npm install express bcrypt jsonwebtoken mongoose
git init9.7.3 第二步：设置多标签布局
# Ctrl+B, C 创建标签页
# 标签 1: code (手动编辑)
# 标签 2: agent (Claude Code)
# 标签 3: server (开发服务器)
# 标签 4: logs (日志)
# 标签 5: mongo (MongoDB shell)或者使用布局配置：
# .herdr/layout.toml
[[tabs]]
name = "code"
panes = [{ command = "nvim .", size = 1.0 }]
[[tabs]]
name = "agent"
panes = [{ command = "claude", size = 1.0 }]
[[tabs]]
name = "server"
panes = [{ command = "npm run dev", size = 1.0 }]
[[tabs]]
name = "mongo"
panes = [{ command = "mongosh", size = 1.0 }]9.7.4 第三步：让 Agent 搭建项目骨架
切到 agent 标签页，给 Claude Code 下达指令：
> 请帮我搭建一个 Express.js REST API 项目骨架：
> 1. 使用 MVC 目录结构（models, controllers, routes, middleware）
> 2. 配置 MongoDB 连接
> 3. 实现用户注册和登录（JWT 认证）
> 4. 实现文章的 CRUD 操作
> 5. 添加输入验证和错误处理中间件Agent 开始工作。你切到 code 标签页做自己的事情——比如写 README 或者调整 package.json。
9.7.5 第四步：监控 Agent 状态
在 Agent 工作期间，侧边栏显示：
┌──────────────────────┐
│ 状态面板 │
├──────────────────────┤
│ ● agent: working │
│ ⏱ 运行时间: 5m 23s │
│ 📁 修改文件: 8 │
│ ✅ 完成步骤: 3/5 │
├──────────────────────┤
│ server: stopped │
│ mongo: idle │
└──────────────────────┘当 Agent 完成 package.json 的修改后，你可以在 server 标签页启动开发服务器，开始测试已完成的路由。
9.7.6 第五步：分离与恢复
下班时间到了，但 Agent 还在跑：
# Ctrl+B, D 分离
# 关闭终端，安心下班
# 第二天早上
herdr attach重连后你看到：
# Agent 标签页显示：
> ✅ 所有任务已完成！
>
> 创建的文件：
> - src/models/User.js
> - src/models/Article.js
> - src/controllers/authController.js
> - src/controllers/articleController.js
> - src/routes/index.js
> - src/middleware/auth.js
> - src/middleware/errorHandler.js
> - src/app.js
> - src/server.js
>
> 修改的文件：
> - package.json (添加了 dev script)
> - .env.example (添加了环境变量模板)9.7.7 第六步：测试和调试
切到 server 标签页启动服务器：
npm run dev
# Server running on port 3000
# MongoDB connected切到 logs 标签页查看实时日志，使用 mongo 标签页检查数据库状态。
如果发现 bug，切回 agent 标签页：
> 注册接口返回 500 错误，日志显示 "ValidationError"
> 请检查 User model 的必填字段验证Agent 开始排查和修复。
9.7.8 第七步：提交代码
在 code 标签页：
git add -A
git commit -m "feat: 完成用户认证和文章 CRUD API"
git push origin main9.8 最佳实践总结
9.8.1 1. 永远在 Agent 开始工作前保存布局
# 手动保存当前布局
herdr session save
# 或者设置自动保存
# ~/.config/herdr/config.toml
[session]
auto_save = true
auto_save_interval = 60 # 秒9.8.2 2. 给标签页起有意义的名字
# 好的命名
[auth-agent] [api-server] [mongo] [logs]
# 不好的命名
[tab1] [tab2] [tab3] [tab4]9.8.3 3. 利用 detach 实现异步工作
# 下班前，给 Agent 一个长任务
# detach，关电脑（如果是远程服务器的话）
# 第二天 attach 检查结果9.8.4 4. Scrollback 是你的朋友
Agent 跑完任务后，不要急着清屏。用 PageUp 回顾 Agent 的完整输出：
- 检查 Agent 是否走了弯路
- 理解 Agent 的修改逻辑
- 学习你不知道的库或 API 用法
9.8.5 5. 一个标签页一个 Agent
虽然一个标签页可以有多个 pane，但在 pane 中只放一个 Agent。Agent 的输出通常很长，需要完整的终端宽度。
┌──────────────────────────────────┐
│ Tab: agent (整页 Claude Code) │
│ │
│ > claude │
│ (Claude Code 占满整个标签页) │
│ │
└──────────────────────────────────┘9.9 小结
单 Agent 工作流看似简单，但要做到高效需要：
- 合理的标签页布局——将 Agent、服务器、日志、数据库分标签管理
- 充分利用状态监控——不要盯着 Agent 看，去做你自己的事
- 拥抱 Session 持久化——detach/reattach 让你和 Agent 都能异步工作
- 善用 Worktree——你和 Agent 操作不同分支，互不干扰
- 保存你的布局——好的布局可以复用和分享
掌握这些，你就已经比 90% 的 AI 辅助开发者更高效了。下一章，我们将进入更激动人心的领域——多 Agent 协作。