现在很多人会同时使用多个 coding agent：让一个 agent 调查问题，让另一个实现代码，再让第三个运行测试或做审查。
但只要 agent 数量一多，问题就来了：
- 这些 agent 到底跑在哪里？
- 怎么知道某个 agent 是完成了、卡住了，还是正在等待确认？
- 一个 agent 的调查结果，怎么交给另一个 agent？
- 如果当前会话关掉了，下次还能不能接着做？
Herdr 和 session-share 都能用于多 agent 协作，但它们解决的不是同一个问题。
简单地说：
Herdr 负责让多个 agent 同时工作，session-share 负责让不同会话之间共享持久化的协作记录。
Herdr：管理正在运行的 agent
Herdr 可以理解成一个专门为 coding agent 设计的终端运行时。
它把不同 agent 放进独立的 pane 中。每个 pane 都有自己的终端、进程、工作目录和输出缓冲区：
flowchart LR
C[协调者] --> API[Herdr CLI / API]
API --> S[Herdr server runtime]
S --> PA[Pane A / PTY<br/>researcher]
S --> PB[Pane B / PTY<br/>implementer]
S --> PC[Pane C / PTY<br/>reviewer]
PA --> OA[终端输出与状态]
PB --> OB[终端输出与状态]
PC --> OC[终端输出与状态]
OA --> C
OB --> C
OC --> C这些 agent 可以是 Codex、Claude CLI，或者其他 Herdr 能识别的 coding agent。
Herdr 关注的是实时运行状态：
- agent 是否正在工作
- 是否已经空闲
- 是否等待用户批准
- 是否完成了后台任务
- 当前终端输出是什么
- 是否需要继续发送输入
因此，Herdr 不只是“开几个终端窗口”。它还会观察 agent 的终端状态，并通过 CLI 或 API 进行控制。
比如，可以先在一个 pane 中启动 agent，再让它调查问题：
herdr agent prompt researcher \
"调查这个测试失败的原因，完成后总结复现步骤和根因。" \
--wait然后读取它的输出：
herdr agent read researcher \
--source recent-unwrapped \
--lines 120如果另一个 agent 负责实现修复，就可以把调查结论继续传给它：
herdr agent prompt implementer \
"根据 researcher 的调查结果实现修复：……" \
--wait这里的通信路径很直接：
协调者
→ Herdr CLI/API
→ 目标 agent 的 PTY
→ 读取目标 agent 的终端输出所以，Herdr 更像是一个实时控制平面。它可以管理 agent 进程、发送输入、读取输出、等待状态变化，也可以处理 agent 卡在权限确认或问题选择界面的情况。
session-share：保存 agent 之间的上下文
session-share 关注的不是某个 agent 当前的终端画面，而是不同 agent 会话之间的信息传递。
它更像一个项目级的协作记录层。消息和任务会以持久化记录的形式保存到项目目录下的 .session-share/ 中。它不是实时消息总线，也不保证另一个正在运行的会话已经收到消息；agent 或协调者需要主动写入和读取这些记录。
一个 agent 调查完问题之后，可以留下这样的交接信息：
任务：调查 Windows 下的配置解析失败
结论：
- 问题出现在路径解析阶段
- 反斜杠被当作转义字符处理
- Linux 环境下无法复现
- 相关文件：src/config/path.rs
- 建议增加 Windows 路径测试也可以通过 CLI 创建任务和发送交接消息。具体参数应以本机 session-share --help 为准，例如：
session-share task "调查配置解析失败" \
--from coordinator \
--assign researcher \
--project "$PWD"
session-share message "已定位到路径解析问题，相关文件是 src/config/path.rs" \
--from researcher \
--to implementer \
--project "$PWD"之后，另一个 agent，甚至另一个时间点启动的 agent，就可以读取这份记录，结合当前代码和测试结果继续完成实现或验证。
这解决的是另一类问题：
- 上一个 agent 做到哪里了？
- 调查结论是什么？
- 哪些文件已经改过？
- 测试是否通过？
- 还有哪些风险没有处理？
- 这个问题以前是否已经调查过？
即使原来的 Herdr pane 已经关闭，只要项目目录中的 session-share 记录仍然存在，后续会话就可以找到这些交接内容。
它更适合表达“工作语义”，而不是“终端状态”。
两者最核心的差别
可以用两个问题来区分它们：
Herdr 回答：“这个 agent 现在怎么样？我能不能给它发命令？”
session-share 回答：“之前的 agent 做了什么？下一个 agent 应该从哪里接着做？”
看几个实际例子。
Agent 正在等待权限确认
Herdr 可以识别这个 agent 处于 blocked 状态，并读取终端上的确认界面。必要时，还可以通过 send-keys 发送按键。
session-share 可以记录“这个任务被权限确认阻塞”，但它本身通常不负责操作那个终端界面。
Agent 已经退出，任务下周继续
Herdr 依赖当前的 session、pane 和进程。进程退出后，它就不再是一个实时控制对象。
session-share 仍然可以保存：
- 任务目标
- 已经完成的调查
- 修改过的文件
- 测试结果
- 未解决的问题
- 下一步建议
下一个 agent 可以先从交接记录了解背景，再结合当前代码和测试结果继续工作。
三个 agent 并行工作
Herdr 负责把三个 agent 真正运行起来：
Herdr
├── researcher：调查问题
├── implementer：编写修复
└── reviewer：检查修改session-share 则负责记录它们之间的交接：
researcher → 调查结论
implementer → 修改说明和测试结果
reviewer → 审查意见和剩余风险Herdr 中的通信，通常是“经过协调者”
Herdr 可以让一个协调者读取 agent A 的输出，再把其中的结论发送给 agent B：
Agent A
→ Herdr 读取输出
→ 协调者提炼结论
→ Herdr 向 Agent B 发送任务这是一种间接通信。
Agent A 和 Agent B 并不是天然拥有一个自由对话的消息通道。它们通常通过以下方式协作：
- 共享 Git 仓库
- 共享文件
- 共享测试结果
- 由协调 agent 转述信息
- 通过 Herdr CLI 控制彼此所在的 pane
这种方式的优点是过程清楚、终端证据完整，也容易观察每一步发生了什么。
但它也有一个明显限制：如果只依赖终端输出，协调者需要自己从大量文本中提炼结论。终端输出适合实时观察，却不一定适合长期保存和检索。
这正是 session-share 发挥作用的地方。
session-share 更适合做“交接”和“记忆”
一个比较完整的流程可以是：
flowchart TD
T[创建任务或记录背景] --> SS[session-share 项目记录<br/>.session-share/]
SS --> R[researcher 会话读取任务]
R --> F[调查问题并形成结论]
F --> M[写入消息或更新任务]
M --> I[implementer 会话读取交接记录]
I --> W[结合当前代码实现并运行测试]
W --> U[写入修改说明、测试结果和剩余风险]
U --> V[reviewer 会话读取最新记录并审查]例如：
- 在 session-share 中建立一个调查任务。
- 用 Herdr 启动 researcher。
- researcher 在自己的 pane 中复现问题。
- 协调者通过 Herdr 读取 researcher 的结论。
- 把结论写入 session-share。
- 用 Herdr 启动 implementer。
- implementer 读取交接记录，结合当前代码修改实现。
- 把修改内容和测试结果再次保存到 session-share。
- reviewer 读取这些信息，完成审查。
在这个流程里，Herdr 负责“现场”，session-share 负责“档案”。
什么时候该用 Herdr，什么时候该用 session-share？
如果目标是控制当前正在运行的 agent，优先使用 Herdr：
- 启动或停止 agent
- 为 agent 分配独立 pane
- 向 agent 发送 prompt
- 读取终端输出
- 等待 agent 完成
- 处理权限确认和交互输入
- 观察 agent 的实时生命周期
如果目标是跨会话共享信息，优先使用 session-share：
- 创建和派发任务
- 保存调查结果
- 记录实现和测试结论
- 给下一个 agent 写交接说明
- 回忆上次会话做到哪里
- 在 Codex、Claude、Pi 等不同 agent 之间传递上下文
它们不是替代关系
把 Herdr 和 session-share 放在一起时，最自然的分工是：
Herdr = 运行时和控制
session-share = 协作记录和持久记忆或者换一个更生活化的比喻：
- Herdr 像一个管理多个工作台的调度中心。你可以看到每个人是否在工作，也可以直接交代事情。
- session-share 像团队的项目日志。它记录谁调查了什么、得出了什么结论，以及下一步应该做什么。
只有 Herdr 时，多个 agent 可以并行运行，但交接主要依赖实时终端输出和共享文件。
只有 session-share 时，多个会话可以交换任务和结论，但它本身不负责启动 agent，也不负责操作某个具体的终端进程。
两者结合之后，协作链路会完整得多：
Herdr 让 agent 在同一个运行环境里并行工作；session-share 让这些工作的结果能够跨会话沉淀和流转。
这也是两者最重要的区别：Herdr 面向“活着的进程”，session-share 面向“持续的协作上下文”。