18  第16章 最佳实践

18.1 Workspace 组织策略

18.1.1 核心原则：一个项目一个 Workspace

每个项目使用独立的 Herdr workspace，避免不同项目的 Agent 和文件相互干扰。

# 为新项目创建 workspace
cd ~/projects/new-saas-app
herdr init

# 这会创建 .herdr/ 目录
# .herdr/
# ├── config.toml        # 项目级配置
# ├── workspace.toml     # workspace 定义
# └── agents/            # 项目级 Agent 配置

18.1.2 项目结构建议

~/projects/my-saas-app/
├── .herdr/
│   ├── config.toml           # 项目配置
│   ├── workspace.toml        # workspace 布局
│   └── agents/
│       ├── frontend.toml     # 前端 Agent
│       ├── backend.toml      # 后端 Agent
│       ├── reviewer.toml     # 代码审查 Agent
│       └── tester.toml       # 测试 Agent
├── src/
├── tests/
├── docs/
└── ...

18.1.3 多项目切换

# 不同项目使用不同 session
cd ~/projects/project-a && herdr attach project-a
cd ~/projects/project-b && herdr attach project-b

# 快速切换 session
herdr session switch project-b

Tip

使用 herdr session list 查看所有活跃 session，配合 Ctrl+a s 快速切换。

---

18.2 Tab 布局建议

18.2.1 标准三 Tab 模式

对于大多数开发场景，推荐使用三个 Tab：

flowchart LR
    subgraph Tab1["🎯 Agent Tab"]
        A1[Frontend Agent] --- A2[Backend Agent]
    end
    subgraph Tab2["🧪 测试 Tab"]
        T1[Unit Tests] --- T2[E2E Tests]
    end
    subgraph Tab3["📋 日志 Tab"]
        L1[Dev Server Logs] --- L2[Build Output]
    end

Tab 名称	用途	典型内容
Agent Tab	AI Agent 工作区	2-4 个 Agent 窗格
测试 Tab	运行和监控测试	单元测试、集成测试
日志 Tab	查看运行日志	开发服务器、构建输出

18.2.2 创建标准布局

# .herdr/workspace.toml — 标准三 Tab 布局

[[tabs]]
name = "🤖 Agents"
panes = [
  { agent = "frontend", cwd = "src/frontend" },
  { agent = "backend", cwd = "src/backend" },
]

[[tabs]]
name = "🧪 Tests"
panes = [
  { command = "npm run test:watch", cwd = "." },
  { command = "npm run test:e2e", cwd = "." },
]

[[tabs]]
name = "📋 Logs"
panes = [
  { command = "npm run dev", cwd = "." },
  { command = "tail -f /var/log/app.log", cwd = "." },
]

---

18.3 Agent 命名规范

18.3.1 标准命名方案

采用 角色 + 可选修饰 的命名模式：

Agent 名称	职责	示例命令
frontend	前端开发	UI 组件、样式、路由
backend	后端开发	API、数据库、业务逻辑
reviewer	代码审查	PR 审查、代码质量检查
tester	测试编写	单元测试、集成测试
docs	文档维护	README、API 文档、变更日志
devops	部署运维	CI/CD、Docker、基础设施
frontend-2	第二个前端 Agent	并行开发不同模块

# 启动标准 Agent 团队
herdr agent start frontend  --cwd src/frontend
herdr agent start backend   --cwd src/backend
herdr agent start reviewer  --watch-panes frontend,backend
herdr agent start tester    --watch-panes frontend,backend

18.3.2 多实例命名

当同一角色需要多个实例时：

# 模块名 + 角色
herdr agent start frontend-auth      --cwd src/frontend/auth
herdr agent start frontend-dashboard --cwd src/frontend/dashboard
herdr agent start backend-api        --cwd src/backend/api
herdr agent start backend-worker     --cwd src/backend/worker

Note

Agent 名称建议使用小写字母和连字符（kebab-case），长度控制在 20 个字符以内，便于在侧边栏中完整显示。

---

18.4 多 Agent 任务拆分原则

18.4.1 任务拆分决策树

flowchart TD
    T[任务] --> Q1{单一模块?}
    Q1 -->|是| S1[单个 Agent 处理]
    Q1 -->|否| Q2{模块间有依赖?}
    Q2 -->|否| S2[并行 Agent 处理]
    Q2 -->|是| Q3{依赖关系复杂?}
    Q3 -->|否| S3["串行编排<br/>Agent A → Agent B"]
    Q3 -->|是| S4["编排链<br/>A → B → C → D"]

18.4.2 拆分原则

原则	说明	示例
单一职责	每个 Agent 只负责一个明确任务	frontend 不写后端代码
独立交付	Agent 的产出可以独立验证	tester 产出测试报告
最小依赖	Agent 间依赖尽可能少	backend 不依赖 frontend 的文件
可组合	Agent 编排链可以灵活调整	reviewer 可以审查任意 Agent 的输出

18.4.3 典型编排模式

18.4.3.1 模式一：并行开发

用户请求："实现用户管理功能"
     ├── frontend Agent → 实现用户列表页面
     ├── backend Agent  → 实现 API 接口
     └── tester Agent   → 等待前两者完成后编写测试

18.4.3.2 模式二：代码审查自动化

Agent 完成编码
     ↓
reviewer Agent 自动启动
     ↓
审查结果写入 /tmp/review-report.md
     ↓
如果发现问题 → 创建新 Agent 修复
如果审查通过 → 通知用户

18.4.3.3 模式三：流水线

# 编排链：设计 → 实现 → 测试 → 审查 → 文档
herdr agent chain \
  --step 1:backend  --task "实现数据库模型和 API" \
  --step 2:tester   --task "为 API 编写测试" --after 1 \
  --step 3:reviewer --task "审查 API 实现" --after 1 \
  --step 4:docs     --task "更新 API 文档" --after 3

---

18.5 安全规则与最佳实践

18.5.1 Agent 权限控制

# .herdr/config.toml — 安全配置

[security]
# 限制 Agent 可执行的命令
agent_command_allowlist = [
  "git", "npm", "node", "python", "pytest",
  "eslint", "prettier", "tsc", "vite"
]

# 禁止 Agent 执行的命令
agent_command_blocklist = [
  "rm -rf /", "sudo", "chmod 777", "curl.*|.*sh"
]

# 限制 Agent 的工作目录
restrict_to_workspace = true

# Agent 超时自动终止
agent_timeout = 3600   # 秒（1 小时）

18.5.2 安全清单

检查项	说明	状态
Agent 工作目录限制	仅允许在 workspace 内操作	☐
命令白名单	仅允许安全的开发命令	☐
敏感文件排除	.env、密钥文件不可被 Agent 访问	☐
网络访问控制	按需限制 Agent 的网络访问	☐
超时终止	防止 Agent 长时间运行浪费资源	☐
日志审计	记录 Agent 执行的所有命令	☐

Warning重要安全提示

• 永远不要让 Agent 拥有 sudo 权限
• Agent 不应能修改 .herdr/config.toml（防止自我提权）
• 在生产环境中使用 --dry-run 先预览 Agent 的操作
• 定期审查 Agent 执行的命令日志

---

18.6 团队协作工作流

18.6.1 代码审查自动化

sequenceDiagram
    participant Dev as 开发者
    participant FE as Frontend Agent
    participant Rev as Reviewer Agent
    participant Git as Git 仓库
    
    Dev->>FE: 实现新功能
    FE->>Git: 提交代码
    FE->>Rev: 触发审查（on_done 钩子）
    Rev->>Git: 读取变更
    Rev->>Rev: 分析代码质量
    alt 发现问题
        Rev->>Dev: 报告问题 + 建议修改
    else 审查通过
        Rev->>Dev: ✅ 审查通过
        Rev->>Git: 添加 approved 标签
    end

配置示例：

# .herdr/agents/reviewer.toml
[agent]
name = "reviewer"
command = "claude-code --task code-review"

[agent.hooks]
on_start = "echo '🔍 Reviewer started'"
on_done = "cat /tmp/review-report.md"
on_block = "echo '⚠️ Reviewer needs input'"

[agent.watch]
panes = ["frontend", "backend"]
trigger = "done"    # 当被监控的 Agent 完成时自动启动

18.6.2 并行开发工作流

┌──────────────────────────────────────────────────┐
│                  共享代码仓库                       │
│              (main branch, protected)             │
└──────────────┬───────────────────┬────────────────┘
               │                   │
     ┌─────────┴─────┐    ┌───────┴───────┐
     │  Worktree A   │    │  Worktree B   │
     │  (auth 模块)  │    │ (dashboard)   │
     │               │    │               │
     │  frontend-auth│    │ frontend-dash │
     │  Agent        │    │  Agent        │
     └─────────┬─────┘    └───────┬───────┘
               │                   │
     ┌─────────┴─────┐    ┌───────┴───────┐
     │  Worktree C   │    │  Worktree D   │
     │  (API 模块)   │    │ (worker 模块) │
     │               │    │               │
     │  backend-api  │    │ backend-worker│
     │  Agent        │    │  Agent        │
     └───────────────┘    └───────────────┘

# 并行启动 4 个 Agent，各负责一个模块
herdr agent start frontend-auth \
  --worktree auth \
  --base-branch develop

herdr agent start frontend-dash \
  --worktree dashboard \
  --base-branch develop

herdr agent start backend-api \
  --worktree api \
  --base-branch develop

herdr agent start backend-worker \
  --worktree worker \
  --base-branch develop

18.6.3 CI/CD 集成

#!/bin/bash
# .herdr/scripts/pre-merge-check.sh
# 在 CI 中运行的 Herdr 自动化检查

# 1. 启动 Herdr server（无头模式）
herdr server start --headless

# 2. 创建临时 workspace
herdr init --name ci-check

# 3. 启动 Agent 执行检查
herdr agent start reviewer \
  --task "审查所有变更文件" \
  --output-format json \
  --timeout 300

herdr agent start tester \
  --task "运行完整测试套件" \
  --timeout 600

# 4. 等待所有 Agent 完成
herdr agent wait --all --timeout 900

# 5. 收集结果
REVIEW_RESULT=$(herdr agent result reviewer)
TEST_RESULT=$(herdr agent result tester)

# 6. 根据 Agent 结果决定是否合并
if [[ "$REVIEW_RESULT" == *"approved"* ]] && \
   [[ "$TEST_RESULT" == *"passed"* ]]; then
  echo "✅ 所有检查通过，可以合并"
  exit 0
else
  echo "❌ 检查未通过"
  exit 1
fi

---

18.7 远程开发最佳实践

18.7.1 SSH 连接复用

# ~/.ssh/config — 优化 Herdr 远程连接

Host herdr-dev-server
  HostName dev.example.com
  User developer
  # 连接复用（避免每次新建连接）
  ControlMaster auto
  ControlPath ~/.ssh/cm-%r@%h:%p
  ControlPersist 10m
  # 保持连接
  ServerAliveInterval 60
  ServerAliveCountMax 3
  # 压缩传输
  Compression yes

18.7.2 远程 Workspace 管理

# 在远程服务器创建持久化 workspace
ssh herdr-dev-server "cd ~/projects/api && herdr init --name api-prod"

# 从本地 attach 到远程 workspace
herdr remote attach herdr-dev-server api-prod

# detach 后远程 workspace 继续运行
herdr remote detach herdr-dev-server api-prod

18.7.3 网络断连处理

# 配置自动重连
[remote]
manage_ssh_config = true
auto_reconnect = true
reconnect_interval = 5       # 重连间隔（秒）
reconnect_max_retries = 12   # 最多重试次数

Tip

在网络不稳定的环境中，设置 auto_reconnect = true 可以在断线后自动恢复连接。Agent 会在远程继续运行，不受断线影响。

---

18.8 配置管理：团队共享 vs 个人

18.8.1 分层配置策略

flowchart TD
    G["全局配置<br/>~/.config/herdr/config.toml<br/>个人偏好：shell、主题、字体"]
    P["项目配置<br/>.herdr/config.toml<br/>团队共享：Agent 定义、编排规则"]
    L["本地覆盖<br/>.herdr/config.local.toml<br/>个人覆盖：调试选项、实验功能"]
    
    G --> M[合并]
    P --> M
    L --> M
    M --> F[最终生效配置]

层级	文件	Git 管理	内容
全局	~/.config/herdr/config.toml	dotfiles 仓库	个人偏好（shell、主题）
项目	.herdr/config.toml	项目仓库	团队共享（Agent、布局）
本地覆盖	.herdr/config.local.toml	.gitignore	临时调试、个人定制

# .gitignore 中添加
.herdr/config.local.toml
.herdr/sessions/
.herdr/worktrees/

18.8.2 团队配置模板

# .herdr/config.toml — 团队共享配置

# 统一的 Agent 定义
[agents.frontend]
command = "claude-code"
cwd = "src/frontend"
timeout = 3600

[agents.backend]
command = "claude-code"
cwd = "src/backend"
timeout = 3600

# 统一的编排规则
[orchestration]
auto_review = true
reviewer_agent = "reviewer"
review_trigger = "agent_done"

# 统一的安全策略
[security]
restrict_to_workspace = true
agent_command_allowlist = [
  "git", "npm", "node", "python", "pytest", "eslint"
]

---

18.9 性能优化建议

18.9.1 窗格与 Tab 管理

指标	建议值	说明
每个 Tab 的窗格数	≤ 4	过多会降低可读性和性能
同时活跃的 Tab 数	≤ 5	关闭不使用的 Tab
同时运行的 Agent 数	≤ 6	每个 Agent 消耗 CPU 和内存
窗格最小尺寸	80×24	确保输出可读

18.9.2 输出历史优化

[experimental]
pane_history = true
pane_history_lines = 2000        # 适中即可，过大会消耗内存
detection_interval_ms = 2000     # 检测间隔，增大可降低 CPU
detection_max_panes = 15         # 限制扫描范围

18.9.3 Agent 数量与资源消耗

graph LR
    subgraph 轻量级["轻量级运行 ≤ 3 Agent"]
        L1[CPU: < 5%]
        L2[内存: < 200MB]
        L3[适合日常开发]
    end
    
    subgraph 标准["标准运行 4-6 Agent"]
        N1[CPU: 5-15%]
        N2[内存: 200-500MB]
        N3[适合多模块并行]
    end
    
    subgraph 重度["重度运行 7+ Agent"]
        H1[CPU: 15%+]
        H2[内存: 500MB+]
        H3[需要高性能机器]
    end

---

18.10 从 tmux 迁移的完整路径

18.10.1 迁移步骤

flowchart LR
    T1["Step 1<br/>安装 Herdr"] --> T2["Step 2<br/>导入 tmux 习惯"]
    T2 --> T3["Step 3<br/>配置键绑定"]
    T3 --> T4["Step 4<br/>逐步替换工作流"]
    T4 --> T5["Step 5<br/>利用 Agent 能力"]
    T5 --> T6["Step 6<br/>完全迁移"]

18.10.2 迁移配置对照

# 为 tmux 用户提供的兼容配置

[keys]
# 保持 tmux 风格的前缀键
prefix = "Ctrl+b"        # tmux 默认前缀

[keys.prefix_mode]
# tmux 风格的键绑定
new_pane = "\""          # tmux: 水平分割
new_vpane = "%"          # tmux: 垂直分割
close_pane = "x"         # tmux: 关闭窗格
new_tab = "c"            # tmux: 新建窗口
close_tab = "&"          # tmux: 关闭窗口
detach = "d"             # tmux: detach
list_sessions = "s"      # tmux: session 列表
rename_session = "$"     # tmux: 重命名 session

Tip

详细的 tmux 到 Herdr 迁移对照请参考附录 C《Herdr vs tmux 完整对比》。

---

18.11 检查清单：理想的 Herdr 工作环境

在开始正式使用 Herdr 进行日常开发前，确认以下事项：

• Workspace：每个项目有独立的 .herdr/ 配置
• Tab 布局：配置了 Agent / 测试 / 日志三 Tab
• Agent 命名：使用标准命名规范
• 安全配置：启用了命令白名单和工作目录限制
• 团队配置：项目配置已提交到 Git，本地覆盖已加入 .gitignore
• 远程配置：SSH 连接复用和自动重连已启用
• 性能：Agent 数量在合理范围内
• 日志：日志级别设置为 info，知道如何切换到 debug
• 备份：重要 session 配置已备份

---

18.12 小结

本章总结了使用 Herdr 的最佳实践：

• Workspace：一个项目一个 workspace，配置纳入版本管理
• Tab 布局：标准三 Tab 模式（Agent / 测试 / 日志）
• Agent 命名：角色化命名，支持多实例
• 任务拆分：单一职责、独立交付、最小依赖
• 安全：命令白名单、工作目录限制、超时终止
• 团队协作：代码审查自动化、并行开发、CI/CD 集成
• 远程开发：SSH 连接复用、自动重连、持久化 workspace
• 配置管理：全局（个人）+ 项目（团队）+ 本地覆盖三层架构
• 性能优化：合理控制窗格和 Agent 数量
• tmux 迁移：渐进式替换，先保持习惯再逐步利用 Agent 能力

遵循这些最佳实践，你将能够充分发挥 Herdr 多 Agent 协作的优势，打造高效、安全、可维护的终端工作空间。