agents

用途

agents 是 bro 工具链中的一个技能，用于监管由 bro 管理的智能体（agent）。当需要重新拉起丢失的 worker、停止某个智能体，或跨编排连接器查看智能体面板时使用。该技能本身仅承载策略，所有具体机制都由 bro CLI 实现。

前置条件

• bro 需在 PATH 中，或使用 npx -y @broject/bro@0（锁定主版本）。
• 需要 bd：up <step> 通过共享 beads 存储声明（claim）并渲染提示词。

主要能力

bro fleet agents 是覆盖各编排连接器（native 分离进程、gascity、tmux、docker 等）的监管面。git common dir 中的 agentId 注册表使智能体身份在其进程结束后仍能延续：重新生成（respawn）会复用已死智能体的 id、worktree 和已存储的提示词。

• docker 连接器：每个 worker 在容器中运行，镜像来自 agents.docker.image 或仓库的 devcontainer。worktree、git common dir 和 beads 存储以宿主机路径挂载，因此注册表、声明、退出约定保持一致；docker daemon 不可达时只会降低视图质量，不会误判为“丢失”。
• copilot 连接器：派发 GitHub Copilot 编码智能体任务，即会提交 pull request 的托管远程 worker。派发前步骤会先声明进共享 beads 存储（远程执行器无法访问它），注册表记录 {taskId, pr}，down 会尽力取消底层 Actions 运行；存活的会话会被报告而非隐藏。agents.copilot.maxSessions/maxWorkers 通过缓存计数统计远程活动任务，缓存过期时按 fail closed 处理。

命令

• bro fleet agents status [<id|step>] [--json] [--connector <name>]：跨所有后端的智能体面板；带参数时打印单个智能体详情。降级的后端仅告警，不会导致整个视图硬失败；但针对性的查询若遇后端降级则以非零码退出（只有在健康读取时才判定为 gone）。
• bro fleet agents up [<step>] [--connector <name>]：无参数时执行后端的 supervisor up（supervisor 为 none 的后端如 native 会报告为空操作）；带 <step> 时生成该步骤的智能体——丢失或已退出的智能体会在同一 agentId 上重新生成（beads 声明重新绑定），存活的智能体则返回 SpawnError。
• bro agents run [<prompt>…] [--prompt-file <f>] [--for <bead>]：临时生成，创建一个 phantom adhoc-<hex> 步骤，经由与 up 相同的注册表/worktree/配额路径发送提示词，并可用生成的 id 查询 status/log/down。--for <bead> 则把生成本绑定到该 bead 的声明上（存在活动智能体或外部声明时拒绝；无提示词则使用 bead 自身文本）。无论哪种方式，若本仓库存在提示词高度相似的活动智能体/会话，会输出 stderr 警告，仅为提示，生成仍会执行。
• bro fleet agents down [<id|step>] [--connector <name>]：无参数时 supervisor down；带目标时停止该智能体——在健康读取下 gone 的智能体以 0 退出（输出 stopped <id>）；在后端降级时未找到会报告 unverified（退出 1），而非 gone；若 worker 抗住停止信号（抗 TERM）或后端无法确认其死亡，也退出 1 且从不输出 stopped。
• bro fleet agents log <id|step> [--follow] [--lines <N>]：跟踪智能体记录的 .log，用于判断“它是否真的在工作”；status 会打印路径，log 读取该路径。--follow 相当于 tail -F：janitor 截断以及 remove/respawn 重开都会被报告，不会静默跳过。stdout 只输出日志字节，上下文头走 stderr。

--connector <name> 将上述子命令限定到某个后端。up 上的常用标志：--worktree <path>（覆盖记录值/约定的 <repo>--<step> 查找）、--prompt-file <file>（覆盖已存储提示词/bead 文本）、--beads-dir <dir>。若无 worktree 可解析，up 会在 spawn 转换中于分支 work/<step> 上创建约定的同级目录——进入、声明和生成在注册表锁下作为一步完成，因此拒绝时不会留下半进入的目录树（仅远程的 copilot 后端跳过此步骤）。

策略要点

• 面板优先，智能体其次：bro fleet 是只读视图，“lost — respawn?” 行是决策入口，bro fleet agents up <step> 是对应动作。
• 重新生成保留身份：相同 agentId、相同 worktree、相同已存储提示词，重新生成的 fixer 保留其自定义指令。共享 beads 存储中的声明会转移到重新生成的操作者。
• 声明是协调平面：被活动智能体声明的步骤拒绝二次生成；由其他角色（或无智能体）持有的声明拒绝重绑定——应先释放陈旧声明，不要强行覆盖。
• 两个上限，不同维度：fleet.maxConcurrent 统计 bro 自有注册表智能体；agents.<kind>.maxSessions 通过注册的会话平面限制全主机会话——agents.devin.maxSessions 统计活动 devin CLI 会话（其 session_locks，按 pid 去重），包含交互式会话，因此面板看似空闲时生成仍可能被拒。agents.<kind>.maxWorkers 拆分计数：只有生成的 worker 计入（devin 以 BRO_AGENT_ID 环境标记或非终端 stdin 判定），交互式 TTY 不再挤占。当已注册平面检测到解析命令的 CLI 或后端设置了 agents.<backend>.sessionKind 时，生成计入某 kind；声明了 kind 却无注册平面会明确拒绝。Devin 的主机本地计数不包含云侧 devin_session_create 会话——平面只报告主机可验证的内容。

适用场景与限制

适用于需要跨多种后端监管智能体、恢复丢失 worker、协调声明与并发配额的多智能体开发流程。限制包括：依赖 bro CLI 与 bd，需配置 PATH 或使用 npx；部分计数值仅限主机可验证范围（如 Devin 云侧会话不在主机本地计数中）；后端降级时部分判定为 unverified 而非确定结论。