多 Agent 会话架构研究

本文比较 Kero、Orca、herdrm 和 Sheprd 的终端托管、Agent 适配与多端交互实现，并据此提出统一会话架构。

研究依据为官方文档及检查时的源码，未构建或进行运行时兼容测试。产品能力属于研究时点的记录；设计建议与已确认实现分开描述，未确认的发布渠道和行为明确标注。

1. 核心结论

统一抽象应建立在 Agent 会话 上，而不是 PTY、终端窗口或某一种 Agent 协议上。

• 运行托管与界面分离：后台管理进程和终端，GUI、手机、CLI 可以断开再连接。
• 观察与控制分离：画面、hooks、日志和协议事件提供不同质量的信息，不能据此推导相同的控制能力。
• 终端与协议并存：已有原生 TUI 通过 Runtime 接入；新建结构化会话可由常驻会话程序统一连接 Agent。
• 多端共享会话控制者：各界面访问同一份快照、事件和命令接口，避免分别启动 Agent 或竞争审批。

Sheprd 的 sheprd-acp 最接近这一方案：在后台托管的窗格中运行会话程序，由它连接 Agent，同时提供聊天 TUI 和原生 GUI 接口。herdrm 则展示了如何保留已有 Agent TUI，通过 Herdr API、单窗格 attach 和日志读取增加图形界面。

2. 基础概念：PTY、终端与生命周期

2.1 PTY 负责终端交互

PTY 是操作系统的虚拟终端接口，可以理解为带终端行为的双向连接。后台持有 master 端，CLI 通过 slave 端连接标准输入、输出和错误输出。

后台写入按键或文本，CLI 读取输入；CLI 输出文本与控制序列，后台读取输出。PTY 还涉及尺寸、回显、终端模式和信号处理。例如 Ctrl+C 在普通模式下可产生中断信号，在原始模式下也可能作为字节交给应用。

PTY 不是网络协议，也不是 Agent 语义协议。 它不天然理解模型回复、工具调用或审批请求。

2.2 终端数据有不同表示

终端前端不必直接读取 Agent 的 PTY，也不必统一使用 libghostty。关键是双方约定输出表示、初始快照及后续增量。

2.3 哪些连接需要保持

最后一个 PTY master 关闭通常会导致终端挂断，CLI 可能收到 SIGHUP 或读写错误并退出。PTY 不能当作可随意断开、重连原进程的普通网络连接。

“退出后仍运行”必须说明退出的是 GUI、连接客户端、会话程序还是 daemon。恢复对话与保留原执行进程也应分开描述。

3. 四种实现总览

平台支持不等于功能完全一致。例如检查时 Sheprd 的 Windows 文档说明 saved SSH hosts 不可用，桌面 herdr-core 路径也有本机限制。

4. Kero：独立终端服务与 Agent 集成

4.1 GUI 与 kerod

kerod 管理进程、PTY、终端状态和滚动内容。GUI 使用 libghostty 显示终端，并提供项目分组、分屏、通知、状态和变更查看。

关闭 GUI 不结束后台任务。kerod 重启后可重建会话；完成集成的 Claude Code、Codex、Pi、OMP、OpenCode 可通过自身 resume 能力恢复对话。

4.2 通信协议

GUI 和 kero CLI 共用自定义协议，检查到的本机连接使用 Unix domain socket。

远程外层使用 yamux 多路复用承载 control、attach 子流，支持协商 deflate 压缩与心跳。

• SSH：执行远端 kero __bridge，启动或连接 kerod，通过 SSH 字节流桥接。
• WSL：通过 wsl.exe 运行桥接。
• 网络监听：通过 /kero/mux WebSocket 接入，可结合 Tailscale 或 Tailscale Serve。

control 属于自定义 RPC 风格协议，不能仅因使用 JSON 就称为标准 JSON-RPC。

4.3 各 Agent 的适配

屏幕规则借鉴 Herdr，官方列出的支持包括 Claude Code、Codex、Gemini、OpenCode、Amp、Cursor、Droid、Qwen、Copilot、Kiro、Cline、Kimi、Pi 等。屏幕识别、hooks、恢复各自有支持范围。

kero report 通过 OSC 7501 Program Status Protocol 上报工作、阻塞、完成、失败、进度和子任务。这是状态语义，不是完整聊天或工具审批协议。

Kero 的优势是终端托管和脚本控制直接、通用；独立 daemon 本身不能证明所有场景下的管理能力或稳定性更优。

5. Orca：终端与结构化开发环境

5.1 两条交互路径

终端模式在工作区中启动原生 CLI，通过 PTY 交互，结合 OSC 标题和 hooks 等识别状态。结构化模式启动协议进程，把消息、工具、审批、问题和选项映射为界面元素。

官方结构化支持包括 Claude、Codex、Grok、OpenCode、Pi、OMP、Antigravity，仍取决于运行位置。本机、配对服务器、SSH、WSL 的能力与生命周期不能一概而论。

Orca 还整合 worktree、编辑器、Diff、Git、浏览器、任务和 CLI 编排。优势是结构化交互与完整工作流，代价是维护多种协议和执行路径。

5.2 手机协议与 Agent 协议分层

iOS/Android 客户端可查看状态、终端和聊天，发送回复、回答问题并进行部分工作区操作。Agent 仍在配对主机执行。

配对使用一次性码，建立手机设备 token。支持 LAN/Tailscale 等直达路径和 Orca Relay；直接地址支持 ws://、wss://，移动协议有版本检查。

Agent 侧 ACP 与手机传输是不同层。不能概括为“全部经 ACP 解析再 P2P 传输”，也不能由直连推断 WebRTC 打洞。Relay 包含服务器中继，桌面关闭后的行为需按运行路径判断。

6. Herdr 接入与 attach

6.1 嵌套完整 TUI 与后端集成不同

在 Kero/Orca 中运行完整 Herdr 客户端时，外层持有客户端 PTY，内部 Agent 的 PTY 仍归 Herdr daemon。外层看到整体画面，不天然获得内部各窗格的独立身份、输出和状态；隐藏窗格无法仅靠当前画面识别。

研究中未找到 Kero/Orca 直接导入 Herdr 运行会话的官方集成。这是缺少适配，不足以证明 Herdr API 能力不足；herdrm 和 Sheprd 已给出实际接法。

6.2 单窗格 attach 与 takeover

根据本机 Herdr 源码，herdr agent attach <pane> --takeover 先将目标解析成 terminal_id，握手后发送 AttachTerminal 请求，连接到指定终端。

接入时重置画面同步基线，按新客户端行列和像素尺寸调整终端，设置直接 attach 尺寸锁。普通 Herdr 整体界面客户端不会因此全部断开。

接管的是单终端 attach 客户端位置与尺寸控制，PTY 和 Agent 进程仍归 daemon。 它不转移 PTY master，也不重启 Agent。

6.3 两种 attach 不是一回事

私有会话 attach 是额外的语义通道，不释放 Herdr 的 PTY，也不要求 Herdr 退出。

7. herdrm：复用 attach，增强已有 TUI

7.1 控制与终端通道

herdrm 使用 SwiftUI，HerdrKit 提供独立领域和传输层，Herdr daemon 保持托管权。

SocketRPC 使用按行 JSON，普通请求每次新建连接，事件订阅保持连接。TerminalProcess 通过 forkpty 启动 attach 或 SSH，独立读写队列泵送字节，libghostty-spm 显示终端。

flowchart TB
    subgraph UI["herdrm 客户端"]
        LIST["会话列表与状态"]
        VIEW["Ghostty 终端视图"]
        ATTACH["指定窗格 attach 客户端"]
        VIEW <-->|"外层 PTY 输入输出"| ATTACH
    end
    LIST <-->|"Herdr RPC 与事件"| H["Herdr daemon"]
    ATTACH <-->|"单终端 attach 协议"| H
    H <-->|"持有原始 PTY"| A["原生 Agent TUI"]

外层 PTY 承载指定窗格 attach，不是完整多窗格 TUI，因此能独立展示已有 Agent。

7.2 日志聊天与终端辅助审批

手机 MobileAgentChat 支持 Claude/Codex：

1. 验证 Herdr agent_session 来源，取得会话 ID。
2. 聊天可见时通过 SSH 短命令按偏移读取 transcript，约每 1.5 秒轮询一次。
3. 需要检查阻塞等状态时，通过 pane.read 解析可见问题或权限提示。
4. 操作前重读画面并核对 fingerprint，通过 pane.send_input 发按键；普通消息走 agent.prompt。
5. 观察提示和状态变化确认结果。

它不是带请求 ID 的协议审批。重检画面可以降低误输入，但检查与发送不原子，TUI 改版会影响解析。日志视图还依赖文件格式、会话关联、访问权限和落盘时机。研究未发现 ACP、app-server 或 Agent SDK 的主动会话控制路径。

7.3 远程与手机连接

桌面 SSH 通常用 ssh -L 转发 Unix socket，ssh -tt 执行 attach；Windows 远端另有 remote-api bridge。手机直接 SSH 使用 stream-local 访问 Herdr socket，使用 SSH PTY 执行 attach。

Relay 路径中，手机和 Mac 分别主动连接 WebSocket 中继，在其上建立 Noise 加密会话，内部再跑 SSH，连接 Mac 本机 sshd。

• Noise：Noise_IKpsk2_25519_ChaChaPoly_SHA256。
• 二维码携带 Mac 静态公钥及一次性 PSK，配对码十分钟过期。
• 手机公钥写入 authorized_keys 并限制回环来源，需要系统 Remote Login。
• 可优先尝试直接地址，校验经加密通道获得的 SSH host key。
• Relay 服务端为私有项目，本研究没有对其审计。

Tailcat 是另一条 socket 桥接路径，不提供任意 shell；独立 shell、日志读取和手机终端支持需分别判断。

7.4 版本与维护

检查提交：437b5f2b7a247d1ff36ac50825e051bc1560a3f0。当时最新 Release 为 v0.7.1，仅确认 macOS 附件；iOS 源码和配对实现存在，公开获取渠道未确认，未找到 Android target。

README 声明因 Herdr 推出官方 GUI，herdrm 可能停止维护。

8. Sheprd：常驻会话程序与多前端

8.1 两种终端后端

Sheprd 使用 Rust/GPUI。Herdr 1 路径连接 herdr-client.sock，直接接收 cells、surface 和 patch，原生绘制；不必启动完整 TUI，也不依赖 Ghostty。

sheprd-protocol 使用 4 字节小端长度加 bincode 2 standard；patch 校验 boot_id、projection_revision、base_surface_revision 等，拒绝不匹配更新。

herdr-core 路径接收原始输出，经 sheprd-terminal 模拟后复用绘制。Release 附带固定版本 core，旧会话不自动迁移。观察者与 driver 分离，使只看画面不必改尺寸或输入。

8.2 sheprd-acp 自己提供聊天 TUI

Herdr 托管终端，Sheprd 将结构化对话放进普通窗格中的常驻 sheprd-acp。它是 Agent 的唯一协议客户端，同时维护对话、绘制聊天 TUI，并向其他前端开放会话接口。

flowchart TB
    subgraph HOST["Agent 所在主机"]
        H["Herdr daemon：持有 PTY master"]
        B["sheprd-acp 常驻进程<br/>维护对话并自绘 TUI"]
        A["Agent 子进程：协议模式"]
        E["私有会话 endpoint"]
        R["remote-control 服务"]
        H <-->|"PTY：按键与聊天 TUI 输出"| B
        B <-->|"stdio：ACP 或原生协议转换"| A
        B <-->|"快照、增量、消息、审批"| E
        R <--> E
    end
    G["GUI 原生聊天"] <-->|"私有会话协议，本机或 SSH 桥接"| E
    T["终端视图"] <-->|"Herdr 画面与输入"| H
    P["手机或 PWA"] <-->|"HTTPS / WebSocket"| R

endpoint 是会话程序的逻辑接口，不是独立 Agent 或 PTY 托管进程。图中只展示聊天路径，手机普通终端访问另有通道。

ACP 是协议，TUI 是 sheprd-acp 额外实现的界面。 协议聊天模式没有同时运行 Agent 自带的原生 TUI；关闭 GUI 不结束后台窗格中的会话程序。

8.3 原生协议归一化

harness.rs 的 Reach、Translator 隔离原生协议，Session 层处理 ACP 语义。Claude、Codex、Pi 可改用外部 adapter。

内部统一 ACP 不表示所有 Agent 原生支持 ACP，也不表示能力无损等价。Claude 部分控制消息跟随 SDK 行为，并非公开接口，存在兼容维护成本。

8.4 对外会话协议与发现

sheprd-chat-protocol 与 Agent 侧 ACP 分开：

序号支持同步校验，不代表无限保留历史；恢复仍受缓存策略限制。

8.5 视图切换与模式转换

Linux 的 render_existing/observe 验证会话 ID、PID 和起始时间，原进程结束或身份变化时退出；手工 mirror 读取明确指定的 Claude/Codex JSONL，提供只读 endpoint。

观察路径不启动或恢复 Agent，不写日志，不把历史工具记录还原成实时审批。读取窗口、条目、文本和图片有上限，格式支持属于尽力兼容。

8.6 手机与独立远程服务

sheprd-remote-control 是独立用户服务，GUI 退出后可以继续运行，聚合 Herdr 会话、已有 core 终端及协议聊天，自身不启动或升级 Herdr daemon。

手机使用 HTTPS/WebSocket，原生端固定主机指纹并使用签名会话认证；PWA 使用同一服务。优先 Tailscale，其次 LAN，默认端口 7443，跨网络需要可达路径。远程主机可经 SSH 部署服务，手机分别连接各主机。

这与 herdrm 的 Noise 会话内再跑 SSH 的 Relay 不同，也不能推断为 WebRTC P2P。推送与会话数据连接是不同通道。

检查提交：72b49b1bd4be6930e3cbdc3c191dda1a0cf41fa4。项目与 Herdr 官方无隶属关系；旧名 herdr-gpui 仍出现在兼容标识。官方提供 iPhone/iPad TestFlight 和 PWA，原生项目以 iOS 26 为目标，未找到 Android 原生发布说明。

9. 统一会话架构建议

本节是设计建议，不代表四个项目已经采用相同模型。

9.1 对象与职责

Session、进程、终端和窗格分别编号。进程重启或移动窗格不必创建新对话；恢复关联需有明确会话 ID 和实际恢复结果，不能只靠目录或时间猜测。

9.2 一个 API，两种执行路径

flowchart TB
    V["GUI / 手机 / CLI"] <-->|"能力、快照、事件、命令"| S["统一 Session API"]
    S <-->|"原生 TUI 会话"| X["终端与观察适配"]
    S <-->|"结构化会话"| B["常驻 Session Broker"]
    X <-->|"画面与输入"| R["Runtime：Herdr / 本机 / 远程"]
    X <-->|"只读历史"| L["TranscriptSource"]
    R <-->|"托管与终端连接"| T["原生 Agent TUI"]
    B <-->|"唯一主动协议通道"| A["Agent Adapter"]
    A <-->|"ACP / SDK / app-server"| P["协议模式 Agent"]
    R -.->|"托管 Broker 生命周期"| B

两条分支表示不同会话执行模式，不要求同一个 Agent 同时支持原生 TUI 与协议控制。若后续支持模式交接，应作为经过验证的独立能力。

9.3 按能力提供操作

Session 返回 capabilities，不能用一个“支持聊天”布尔值概括全部能力。

屏幕发现“等待审批”不代表具备协议审批能力；日志显示工具历史，也不代表能取消或批准当前工具。

9.4 信息来源与同步

终端、协议、transcript 是三类信息来源，hooks 可作为额外状态输入，不应当作等价的实时事实。

• 终端通道声明原始字节、镜像或 cells/patch，各自定义基线及增量。
• 语义事件统一消息、工具、审批、问题和轮次生命周期，事件名可采用 message.delta、tool.started、approval.requested 等。
• 事件包含 Session ID、来源、epoch、序号；有依据时附轮次、工具和审批 ID。
• 日志保留记录身份或偏移，重读去重，历史重载不重复触发通知或审批。
• 连接、执行、待用户操作分别建模；离线意味着不可观测，不等于空闲或完成。
• 结构化事件在明确覆盖的范围内优先，画面与 hooks 补充时记录有效期，避免陈旧状态覆盖新事实。

9.5 输入协调与资源边界

1. 每个执行会话由一个协调器管理主动输入。多客户端共享视图，驱动权和命令按明确规则协调。
2. 协议审批绑定请求 ID，原子校验是否仍待处理；终端辅助操作即使重检画面，仍须承认检查到发送之间的竞态。
3. 重连结合带游标快照与有序增量；处理快照和订阅竞态，epoch 变化或序号缺口时重新同步。
4. 限制缓存、日志、订阅、在途请求，慢客户端不阻塞 PTY 读取；恢复窗口耗尽则回退快照。
5. 区分关闭视图、断开连接、取消轮次、停止 Agent、关闭终端、停止 daemon。
6. 不支持两种模式并行控制时，先确认原进程退出，再调用受支持的 resume，处理未确认输入与恢复失败。

9.6 实施顺序

1. 定义 Session 身份、能力、事件与生命周期，明确观察和控制边界。
2. 实现 Herdr Runtime：枚举、事件、单窗格 attach、输入、重连，先接已有 Agent。
3. 加入 hooks 和只读 transcript，验证会话关联、去重和状态时效。
4. 为一个 Agent 实现常驻 Broker 与协议 Adapter，同时提供聊天 TUI 和 GUI 接口。
5. 验证多端审批、断线同步、退出行为，再扩展 Agent 与远程服务。

10. 名称与读法

herdr、sheprd 都不是标准英文单词的常规拼写。本次未找到官方明确发音或命名来源说明，以下按拼写与产品比喻解释。

可理解为“照看一群 Agent”的品牌比喻，按完整单词读，无须按删减后的辅音硬拼。

11. 参考资料

Kero

• 平台、会话恢复、Agent 集成、状态识别。
• 本机协议、终端帧、远程协议、远程传输。

Orca

• 仓库、会话、结构化聊天、手机。
• Claude 进程、Codex app-server、ACP。

Herdr 与 herdrm

• Herdr API。attach 另核对本机 src/cli/agent.rs、src/server/headless.rs，未记录固定提交。
• herdrm 仓库与维护状态。以下固定在研究提交：
• HerdrService、SocketRPC、PTY。
• 手机聊天、传输、Relay。

Sheprd

• 仓库。以下固定在研究提交：
• 桌面、会话程序与观察、Translator。
• 会话协议、终端协议、远程服务、iOS。

发音

• shepherd 标准发音。