11 第9章远程开发

11.1 为什么需要远程开发

你的主力开发机器可能不在身边。也许你的 AI Agent 正在办公室的 Mac Studio 上跑一个长任务，而你正在通勤的地铁上用手机想查看进度。也许你的团队有一台高性能的 GPU 服务器，所有 Agent 任务都在上面运行。

Herdr 的远程开发能力让你可以在任何设备上连接到任何 Herdr 实例——手机、iPad、笔记本，甚至另一台台式机。

11.2 三种远程工作模式

Herdr 支持三种远程工作模式，各有适用场景：

模式	命令	Agent 运行位置	显示位置	适用场景
纯本地	`herdr`	本机	本机	日常开发
SSH + 远程运行	`ssh` → `herdr`	远程服务器	远程服务器	服务器管理、GPU 任务
本地客户端 + 远程服务器	`herdr --remote workbox`	远程服务器	本机	最佳体验、移动办公

11.2.1 模式一：纯本地

最简单的模式，所有东西都在你的机器上：

┌─────────────────────┐
│   你的电脑           │
│  ┌───────────────┐  │
│  │  Herdr         │  │
│  │  ┌──────────┐ │  │
│  │  │ Agent    │ │  │
│  │  │ Server   │ │  │
│  │  │ Logs     │ │  │
│  │  └──────────┘ │  │
│  └───────────────┘  │
└─────────────────────┘

适用场景：日常开发，你有你的电脑就够了。

11.2.2 模式二：SSH + 远程运行

通过 SSH 登录到远程服务器，在服务器上运行 Herdr：

# SSH 登录
ssh you@gpu-server

# 在远程服务器上启动 Herdr
herdr

# 现在你看到了 Herdr 的 TUI 界面
# 所有 Agent、文件、进程都在远程服务器上

┌──────────────┐         ┌──────────────────────┐
│  你的电脑     │  SSH    │  远程服务器            │
│              │ ──────> │  ┌────────────────┐  │
│  SSH 客户端   │         │  │  Herdr          │  │
│  (终端)      │ <────── │  │  ┌──────────┐  │  │
│              │         │  │  │ Agent    │  │  │
│              │         │  │  │ Server   │  │  │
│              │         │  │  └──────────┘  │  │
└──────────────┘         │  └────────────────┘  │
                         └──────────────────────┘

适用场景： - GPU 密集型任务（模型训练、推理） - 服务器管理 - 在高性能机器上运行编译任务 - 网络条件好、延迟低

优缺点：

优点	缺点
配置简单	网络断开 → SSH 中断（Herdr 仍运行）
延迟取决于网络	键盘输入有延迟感
所有数据在服务器	需要重新 SSH 连接

11.2.3 模式三：本地客户端 + 远程服务器（推荐）

Herdr 独有的模式。Herdr 客户端在本地运行（提供流畅的 TUI），但所有 Agent 和进程在远程服务器上运行：

# 在本地终端运行
herdr --remote workbox

# Herdr 连接到远程的 Herdr daemon
# 本地显示 TUI，远程执行命令

┌──────────────┐         ┌──────────────────────┐
│  你的电脑     │ Herdr   │  远程服务器 (workbox)  │
│              │ 协议    │                      │
│  ┌────────┐  │ ──────> │  ┌────────────────┐ │
│  │ Herdr  │  │         │  │ Herdr Daemon   │ │
│  │ Client │  │         │  │  ┌──────────┐  │ │
│  │ (TUI)  │  │ <────── │  │  │ Agent    │  │ │
│  └────────┘  │         │  │  │ Server   │  │ │
│              │         │  │  └──────────┘  │ │
│  本地渲染     │         │  └────────────────┘ │
│  远程执行     │         │                      │
└──────────────┘         └──────────────────────┘

适用场景： - 移动办公（手机/iPad 连远程服务器） - 跨平台开发（Windows 机器连 Linux 服务器） - 团队共享开发环境 - 网络不稳定的环境

优缺点：

优点	缺点
本地渲染流畅	需要在远程安装 Herdr daemon
网络断开自动重连	配置稍复杂
支持本地快捷键	某些本地集成需要额外配置
多设备共享同一会话

11.3 选择模式的决策树

graph TD
    A[开始远程开发] --> B{Agent 任务在哪运行？}
    
    B --> |本机| C["模式 1: 纯本地<br/>herdr"]
    B --> |远程服务器| D{你需要什么体验？}
    
    D --> |能接受 SSH 延迟| E["模式 2: SSH + 远程运行<br/>ssh → herdr"]
    D --> |要最佳体验| F{远程已安装 Herdr？}
    
    F --> |是| G["模式 3: 本地客户端 + 远程<br/>herdr --remote workbox"]
    F --> |否| H[先在远程安装 Herdr]
    H --> G
    
    E --> I{网络是否稳定？}
    I --> |是| E
    I --> |否| J["建议切换到模式 3<br/>支持断线重连"]

11.4 手机编程：SSH 客户端 + Herdr

是的，你可以用手机运行 Herdr。在通勤路上检查 Agent 状态、修改 prompt、甚至直接写代码。

11.4.1 iPhone 推荐：moshi

moshi 是目前 iPhone 上最好的终端模拟器之一，完美支持 Herdr 的 TUI 界面。

特性	moshi	系统 SSH	Termius
TUI 渲染	✅ 完美	❌ 有问题	⚠️ 部分
色彩支持	256色 + TrueColor	16色	256色
蓝牙键盘	✅	✅	✅
Mosh 协议	✅	❌	❌
触摸手势	✅ 丰富	❌	⚠️ 基础
价格	付费	免费	免费/付费

11.4.2 手机使用 Herdr 的最佳实践

11.4.2.1 1. 使用 Mosh 协议

地铁里网络不稳定，SSH 会频繁断开。使用 Mosh：

# iPhone 上用 moshi 连接
mosh you@gpu-server

# 然后连接到已有的 Herdr 会话
herdr attach

Mosh 的优势： - 网络切换不中断（WiFi → 4G → WiFi） - 本地回显（打字不卡） - 自动重连

11.4.2.2 2. 使用模式三（本地客户端 + 远程）

# 如果手机上也安装了 Herdr
herdr --remote workbox --session agents

这样手机上渲染 TUI，但所有操作在远程执行。

11.4.2.3 3. 预设常用布局

手机屏幕小，不要在手机上创建复杂布局。提前在电脑上设好，手机只做监控和简单操作：

# 电脑上预设好布局
herdr session save agents-layout

# 手机上直接恢复
herdr session attach agents-layout

11.4.2.4 4. 善用 Agent 状态侧边栏

手机上不需要看完整的 Agent 输出，看侧边栏的状态就够了：

┌──────────────────┐
│  ● agent-1: done │ ← 绿色，完成了
│  ● agent-2: work │ ← 黄色，还在跑
│  ● agent-3: block│ ← 红色，需要你！
└──────────────────┘

红色 = 切过去看看怎么回事。

11.5 远程附加配置

11.5.1 SSH Config 配置

~/.ssh/config 是远程开发的好朋友：

# ~/.ssh/config

Host workbox
    HostName 192.168.1.100
    User developer
    Port 22
    
    # 保持连接
    ServerAliveInterval 60
    ServerAliveCountMax 3
    
    # 压缩传输（提升 TUI 响应速度）
    Compression yes
    
    # 控制套接字（连接复用）
    ControlMaster auto
    ControlPath ~/.ssh/sockets/%r@%h:%p
    ControlPersist 600

Host gpu-server
    HostName gpu.example.com
    User dev
    ServerAliveInterval 30
    Compression yes

创建套接字目录：

mkdir -p ~/.ssh/sockets

11.5.2 SSH Keepalive

防止 SSH 连接因为空闲而断开：

# 方式 1：在 SSH config 中设置（推荐）
ServerAliveInterval 60

# 方式 2：命令行参数
ssh -o ServerAliveInterval=60 you@server

# 方式 3：使用 Mosh（最佳方案）
mosh you@server

11.5.3 SSH Control Socket（连接复用）

第一个 SSH 连接建立后，后续的 SSH 连接复用同一个 socket，大大加快连接速度：

# 第一次连接（正常速度）
ssh workbox

# 不关闭第一个，在本地新开终端
ssh workbox
# ↑ 几乎瞬间连接！

# Herdr 的 --remote 模式也会复用这个 socket
herdr --remote workbox

11.6 Named Sessions：命名会话

Named Sessions 是 Herdr 远程开发的关键功能。给会话起个名字，你就可以随时重连到它。

11.6.1 基本用法

# 启动一个命名会话
herdr --session agents
# 或者
herdr session new agents

# 列出所有会话
herdr session list
# agents    | created: 2026-08-01 14:30 | tabs: 3 | agents: 2
# main      | created: 2026-08-01 09:00 | tabs: 2 | agents: 0

# 连接到指定会话
herdr session attach agents

# 在另一个终端窗口也连接到同一会话（多窗口共享）
herdr session attach agents
# 现在两个终端窗口显示同一个 Herdr 工作空间

11.6.2 远程 Named Sessions

在远程服务器上创建命名会话，从本地连接：

# 在远程服务器上
ssh workbox
herdr session new agents

# 在服务器上启动 Agent（在 agents 会话中）
# ... 启动各种 Agent ...

# 分离
# Ctrl+B, D

# 回到本地
exit  # 退出 SSH

# 从本地直接连接到远程的 agents 会话
herdr --remote workbox --session agents

11.6.3 会话管理

# 查看会话详情
herdr session info agents
# Name: agents
# Created: 2026-08-01 14:30:00
# Tabs: 3 (orchestrator, backend, frontend)
# Agents: 2 (claude-sonnet: working, kimi-k2: idle)
# Size: 12.5 MB (scrollback history)

# 重命名会话
herdr session rename agents project-alpha

# 关闭会话（所有进程会被终止）
herdr session kill agents

# 超时自动关闭
# 在配置中设置
[session]
idle_timeout = 3600  # 1小时无连接后自动关闭

11.7 Terminal Session Observe/Control 模式

有时你想让别人（或另一个工具）观察你的 Herdr 会话，但不给控制权。或者你想把控制权交给别人。

11.7.1 Observe 模式（只读）

# 其他人可以观察你的会话
herdr session observe agents

# 他们能看到你的 TUI 界面
# 但不能输入任何命令

11.7.2 Control 模式（可操作）

# 允许其他人操作你的会话
herdr session share agents --allow-control

# 其他人连接
herdr session attach agents
# 可以看到界面，也可以输入

11.7.3 应用场景

场景	模式	说明
结对编程	Control	两个人同时操作一个工作空间
远程协助	Control	帮同事调试问题
教学演示	Observe	学生观看老师操作
Agent 监控	Observe	用另一个工具监控 Agent 状态
审计	Observe	安全审计，只看不改

11.8 Direct Terminal Attach

除了通过 Herdr 的会话管理外，你还可以直接附加到某个终端进程：

11.8.1 `herdr agent attach`：附加到 Agent

# 查找运行中的 Agent
herdr agent list --all
# agent-001 | claude-sonnet | pid: 12345 | session: agents

# 直接附加到这个 Agent 的终端
herdr agent attach agent-001
# 现在你直接看到了 Claude Code 的界面
# 可以输入消息、查看输出

11.8.2 `herdr terminal attach`：附加到任意终端

# 查找运行中的终端会话
herdr terminal list
# term-001 | bash | pid: 12346 | cwd: ~/projects/my-app
# term-002 | zsh  | pid: 12347 | cwd: ~/projects/api

# 附加到指定终端
herdr terminal attach term-001

这在你想快速查看某个终端的状态、不想通过完整的 Herdr UI 时很有用。

11.9 Single-Process Escape Hatch

有时候你不需要完整的 Herdr 工作空间——只想在一个终端中运行一个命令，但仍然享受 Herdr 的 session 持久化。

# 使用 --no-session 标志
herdr --no-session claude
# 或
herdr --no-session "npm run dev"

# 这个命令会在当前终端中运行
# 但仍然享受 detach/reattach 能力
# 只是没有标签页和分屏

11.9.1 何时使用

场景	是否用 `--no-session`
快速跑一个 Agent 任务	✅ 不需要复杂布局
长时间运行开发服务器	✅ 只需要持久化
多 Agent 协作	❌ 需要完整布局
SSH 中快速检查	✅ 轻量级
日常开发	❌ 用完整 Herdr

--no-session 的本质

它告诉 Herdr：“不要创建工作空间、标签页、分屏，就给我一个进程 + session 持久化。” 适合简单场景和脚本中使用。

11.10 实战案例：从 iPad 远程管理 3 个 Agent

11.10.1 场景

你有一台 iPad Pro + 蓝牙键盘，想远程管理 Mac Studio 上运行的 3 个 Agent。

11.10.2 准备工作

11.10.2.1 在 Mac Studio 上

# 1. 安装并配置 Herdr（一次性）
# 已安装

# 2. 配置 SSH
# 系统设置 → 通用 → 共享 → 远程登录：开启

# 3. 创建 Herdr 配置
cat > ~/.config/herdr/config.toml << 'EOF'
[session]
auto_save = true
auto_save_interval = 60
idle_timeout = 0  # 永不超时

[remote]
listen = true
allow_connections = ["192.168.1.0/24"]  # 只允许局域网
EOF

11.10.2.2 在 iPad 上

使用 Blink Shell（iPad 上最好的终端）或 Termius：

# 方式 1：SSH + Herdr（最简单）
ssh wuzhiguo@mac-studio.local
herdr attach

# 方式 2：Herdr 远程模式（最佳体验）
# 先在 iPad 上安装 Herdr（如果支持）
herdr --remote mac-studio.local --session main

11.10.3 实际工作流

11.10.3.1 早上：启动任务

在 Mac Studio 上（或通过 SSH 远程）：

# 创建命名会话
herdr session new morning-agents

# 启动 3 个 Agent
herdr agent start --model claude-sonnet-4.5 \
  --prompt "重构认证模块" \
  --cwd ~/projects/my-app

herdr agent start --model kimi-k2 \
  --prompt "编写组件测试" \
  --cwd ~/projects/my-app

herdr agent start --model grok-code \
  --prompt "审查最近的 5 个 commit" \
  --cwd ~/projects/my-app

分离会话：

# Ctrl+B, D
# 关闭 SSH
exit

Agent 继续在 Mac Studio 上运行。

11.10.3.2 通勤路上：iPad 检查进度

# iPad 上 SSH 连接
ssh wuzhiguo@mac-studio.local

# 连接到早上的会话
herdr session attach morning-agents

查看状态：

┌────────────────────────────────────┐
│  ● agent-1: done   | 12m | files: 8│
│  ● agent-2: working| 15m | files: 3│
│  ● agent-3: done   | 8m  | files: 0│
└────────────────────────────────────┘

Agent 1 和 3 完成了，Agent 2 还在跑。

快速检查 Agent 3 的审查结果：

herdr agent read agent-3
# "审查了 5 个 commit，发现 2 个潜在问题：
# 1. commit abc123: 密码比较未使用恒定时间函数
# 2. commit def456: SQL 查询未参数化..."

反馈给 Agent 1：

herdr agent prompt agent-1 \
  "code review 发现 authController.js 中密码比较未使用 timingSafeEqual，请修复"

断开 iPad：

# Ctrl+B, D
exit

11.10.3.3 下午：继续监控

# 再次连接
herdr session attach morning-agents

# 所有 Agent 应该都完成了
herdr agent list
# agent-1: done (修复了密码比较问题)
# agent-2: done (测试编写完成)
# agent-3: done

11.10.3.4 晚上：回到 Mac Studio

# 直接在 Mac Studio 上
herdr session attach morning-agents

# 在完整的大屏上检查所有 Agent 的输出
# 提交代码
git add -A && git commit -m "feat: 认证模块重构 + 测试 + code review"

11.10.4 iPad 上的技巧

使用 Blink Shell 的 Mosh 模式：网络切换不中断

# Blink Shell 中
mosh wuzhiguo@mac-studio.local
herdr session attach morning-agents

外接键盘快捷键：iPad + Magic Keyboard 完美支持 Herdr 快捷键

操作	快捷键
切换标签	Ctrl+B, 数字
分屏	Ctrl+B, %
分离	Ctrl+B, D
滚动	Ctrl+B, PageUp

缩小字体看全局：在 iPad 上适当缩小字体，可以一次看到更多信息

# 在 Herdr 中调整字体大小
# Ctrl+B, Ctrl+减号（缩小）
# Ctrl+B, Ctrl+加号（放大）

11.11 远程开发常见问题

11.11.1 Q1：网络断了怎么办？

SSH 模式：SSH 连接断开，但远程 Herdr 继续运行。重新 SSH + herdr attach 即可。

Herdr 远程模式：自动重连。Herdr 客户端会不断尝试重新连接服务器，恢复后 TUI 自动刷新。

11.11.2 Q2：多个设备同时连接？

# 设备 A
herdr --remote workbox --session agents

# 设备 B（同时）
herdr --remote workbox --session agents
# 默认：observe 模式，只能看
# 需要 --allow-control 才能操作

11.11.3 Q3：远程服务器没有 Herdr？

# 在远程服务器上安装
ssh workbox
curl -fsSL https://herdr.dev/install.sh | bash

# 然后启动 daemon
herdr daemon start

11.11.4 Q4：如何安全暴露远程 Herdr？

不要直接暴露 Herdr 端口到公网。使用：

# 方案 1：SSH 隧道（最安全）
ssh -L 7654:localhost:7654 workbox
herdr --remote localhost:7654

# 方案 2：Tailscale / WireGuard VPN
# 在 VPN 网络内直接访问

# 方案 3：Herdr 的 TLS 配置
# ~/.config/herdr/config.toml
[remote]
tls_cert = "/path/to/cert.pem"
tls_key = "/path/to/key.pem"

11.12 最佳实践总结

11.12.1 1. 始终使用 Named Sessions

# ✅ 好习惯
herdr session new my-project

# ❌ 坏习惯（依赖默认会话）
herdr

11.12.2 2. 配置好 SSH Config

把所有常用服务器的配置写在 ~/.ssh/config 中，避免每次输入长命令。

11.12.3 3. 移动设备用 Mosh

# 手机/iPad 上
mosh workbox  # 而不是 ssh workbox

11.12.4 4. 分离前保存

# 重要操作前保存会话
herdr session save

# 配置自动保存
[session]
auto_save = true

11.12.5 5. 安全第一

不在公网暴露 Herdr 端口
使用 SSH 隧道或 VPN
设置 allow_connections 白名单
定期更新 Herdr 版本

11.13 小结

远程开发让 Herdr 的价值真正发挥出来——你的 Agent 在强大的服务器上运行，你在任何设备上监控和操作。本章核心：

三种模式：纯本地、SSH+远程、本地客户端+远程——选择适合你的
Named Sessions：给会话起名字，随时重连
移动办公：手机/iPad + Mosh + Herdr = 随时随地开发
安全配置：SSH 隧道、VPN、白名单
断线不怕：Herdr 的 session 持久化保证 Agent 不中断

下一章，我们将探索 Herdr 的插件系统——如何通过插件扩展 Herdr 的能力。

11.1 为什么需要远程开发

11.2 三种远程工作模式

11.2.1 模式一：纯本地

11.2.2 模式二：SSH + 远程运行

11.2.3 模式三：本地客户端 + 远程服务器（推荐）

11.3 选择模式的决策树

11.4 手机编程：SSH 客户端 + Herdr

11.4.1 iPhone 推荐：moshi

11.4.2 手机使用 Herdr 的最佳实践

11.4.2.1 1. 使用 Mosh 协议

11.4.2.2 2. 使用模式三（本地客户端 + 远程）

11.4.2.3 3. 预设常用布局

11.4.2.4 4. 善用 Agent 状态侧边栏

11.5 远程附加配置

11.5.1 SSH Config 配置

11.5.2 SSH Keepalive

11.5.3 SSH Control Socket（连接复用）

11.6 Named Sessions：命名会话

11.6.1 基本用法

11.6.2 远程 Named Sessions

11.6.3 会话管理

11.7 Terminal Session Observe/Control 模式

11.7.1 Observe 模式（只读）

11.7.2 Control 模式（可操作）

11.7.3 应用场景

11.8 Direct Terminal Attach

11.8.1 herdr agent attach：附加到 Agent

11.8.2 herdr terminal attach：附加到任意终端

11.9 Single-Process Escape Hatch

11.9.1 何时使用

11.10 实战案例：从 iPad 远程管理 3 个 Agent

11.10.1 场景

11.10.2 准备工作

11.10.2.1 在 Mac Studio 上

11.10.2.2 在 iPad 上

11.10.3 实际工作流

11.10.3.1 早上：启动任务

11.10.3.2 通勤路上：iPad 检查进度

11.10.3.3 下午：继续监控

11.10.3.4 晚上：回到 Mac Studio

11.10.4 iPad 上的技巧

11.11 远程开发常见问题

11.11.1 Q1：网络断了怎么办？

11.11.2 Q2：多个设备同时连接？

11.11.3 Q3：远程服务器没有 Herdr？

11.11.4 Q4：如何安全暴露远程 Herdr？

11.12 最佳实践总结

11.12.1 1. 始终使用 Named Sessions

11.12.2 2. 配置好 SSH Config

11.12.3 3. 移动设备用 Mosh

11.12.4 4. 分离前保存

11.12.5 5. 安全第一

11.13 小结

11.8.1 `herdr agent attach`：附加到 Agent

11.8.2 `herdr terminal attach`：附加到任意终端