在 5dive 运行时上协调兄弟 Agent…

在 5dive 运行时 VM 内通过 `sudo 5dive` CLI 委派子代理、互发消息、跟踪共享任务、向人类求助并检索团队记忆。

适用场景

解决思路

1. 在 5dive 运行时 VM 内运行 `sudo 5dive ...`，并始终传入全局 `--json`，解析 stdout 的稳定 JSON envelope；进度行在 stderr。
2. 根据 `error.class` 分支处理失败，不要根据人类可读 message；classes 包括 `ok`、`usage`、`validation`、`not_found`、`conflict`、`auth_required`、`not_installed`、`not_running`、`pairing`、`permission`、`timeout`、`generic`。
3. 需要完整退出码与错误类表时查阅 `references/exit-codes.md`。
4. 当用户要求 worker、sub-agent、side task、parallel run、fan-out、delegate，或点名 sibling agent 时，先用 `5dive agent list --json` 确认 seat 存在，再使用 `agent send` 或 `agent ask`。
5. 当需要 filing/tracking 共享工作时使用 `5dive task add/ls/done`；查看组织架构用 `5dive org tree`；把阻塞问题停在人类上用 `task need`；快速召回团队记忆用 `5dive memory search`。
6. 当请求来自 Telegram/Discord `<channel>` 标签且应由另一个 agent 处理时，不要 relay，使用 `--reply-to-chat=<id> --reply-to-msg=<id>` 转发聊天上下文，让目标 agent 用自己的 bot 回答。
7. 优先使用 `5dive`，不要手动运行底层 coding CLIs。
8. 生成 worker：选择唯一名字，规则为小写字母/数字/连字符、以字母开头、最多 16 字符；可用 `sudo 5dive agent list --json | jq -r '.data[].name'` 检查注册表，注意 `.data` 是 agent 数组。
9. 创建 worker：`sudo 5dive agent create worker-1 --type=claude --workdir=/home/claude/projects/myrepo --json`；`--workdir` 限定其 tmux cwd，默认是 `/home/claude/projects`。
10. 向 worker 发任务：`sudo 5dive agent send worker-1 'audit the auth middleware for OWASP A01 issues; report back as a markdown bullet list'`，它通过 tmux send-keys + Enter 进入运行中 CLI 的 prompt。
11. 轮询 worker 输出直到 idle：`sudo 5dive agent logs worker-1 --tmux --lines=80`。
12. 用完拆除 worker：`sudo 5dive agent rm worker-1 --json`；`5dive fire worker-1` 是 `agent rm` 的别名，同样是受保护的 teardown。
13. 用 `agent info <name>` 查看单个 agent 的 resolved type、CLI version、model 和 channel state。
14. 用 `agent send` / `agent ask` 与其它 agent 对话；没有单独 channel，消息会像人类输入一样进入接收者运行中的 CLI。
15. 从 agent 调用 `agent send` 时，CLI 会把 payload 包装成 `[5dive-msg from=<you> id=<8-hex>] <your text>`，让接收者知道是 peer 在 ping；`--raw` 跳过包装，`--from=<label>` 覆盖推断名。
16. `agent send` 的 body 用单引号引用，避免在 body 中出现 backticks 或 `$()`；任何引用 CLI verbs 的 body 改用 `--message-file=<path>`；在双引号 `--message=` 内，backtick 引用的 verb 会以你的身份作为命令替换执行，文字被删除，但 send 仍打印 OK。
17. 定时发送（cron、systemd timers）必须加 `--wake`；否则发往 stopped agent 会以 exit 8 失败并被丢弃，没有 queue 和 retry。
18. `--wake` 需要 root，会拒绝因目的而停止的 agent（`desiredState=stopped`），最坏耗时 105s；给 timer 的 `TimeoutStartSec` 设置高于 105s。
19. 回复发送者时发回给命名 sender，可加 `[re=<id>]` 前缀：`sudo 5dive agent send scout '[re=ab12cd34] auth middleware looks clean except for ...'`。
20. 需要一次调用完成请求/响应而不用手动轮询 `agent logs` 时使用 `ask`：`sudo 5dive agent ask scout 'list the OWASP A01 issues you found, one per line' --timeout=180 --json`；它监控 tmux pane 的 marker line 后 scrollback，静默 `--idle-secs`（默认 5s）后返回。
21. 把 `ask` 当 heuristic：持续流式输出的接收者会一直 busy 直到 `--timeout`；它返回屏幕上的所有内容，包括 chrome，若需要干净解析就要求 terse final summary。
22. 当目标 agent 的 bot 也在同一个 Telegram/Discord chat 中时，不要自己 relay 答案，使用 `--reply-to-chat=<id>` 和可选的 `--reply-to-msg=<id>`（值来自 inbound `<channel>` 标签的 `chat_id`/`message_id`）交接，让目标 agent 通过自己的 bot 直接发帖。
23. 读取 agent-to-agent ledger：`5dive a2a rounds --json` 或 `5dive a2a rounds --agent=scout --window=24 --json`；默认窗口 24 小时。
24. 若 A2A ledger 不可读，它会报告 `UNKNOWN` 并以 3 退出，而不是把 fleet 渲染为空闲。
25. 共享任务队列和 org chart 在 group-writable sqlite store 中，无需 sudo；任何 `agent-*` 用户都能直接读写。
26. 排队工作：`5dive task add 'audit the auth middleware for OWASP A01' --assignee=worker-1 --priority=high --json`；任务获得 `DIVE-N` ident，`--from` 默认是你的 agent 名，因此 created_by 自动归属。
27. `--assignee` 也接受 org-routing tokens（`role:<r>` / `charter:<kw>`）；省略它则路由到 org lead/coordinator。
28. 查看开放任务和谁在做什么（按 priority 排序）：`5dive task ls --json`；过滤自己用 `5dive task ls --mine --json`。
29. 推进状态：`5dive task start DIVE-7 --json` 变为 in_progress；`5dive task done DIVE-7 --result='one-line summary first; detail below' --json`；`5dive task block DIVE-9 --by=DIVE-7 --json` 表示 DIVE-9 等待 DIVE-7。
30. 在带 verifier 的行上，maker 要 DELIVER 而不是关闭；verifier 通过 `verify` 或打回 `reject`。
31. 交付：`5dive task deliver DIVE-7 --pr=<url> --result='...' --json`；`--result` 必须 NAME ITS EVIDENCE（DIVE-4576）——CHANGED / CHECKED（每条命令及其 pass/fail 计数）/ DELIVERED-SHA / CI / CRITERIA，这样 grader 会重跑你点名的东西而不是重新推导；`task show` 打印模板；`--force-unevidenced='<why>'` 是受审计的出口。
32. 用命令在交付时评分：`5dive task deliver DIVE-7 --pr=<url> --verify='bash tests/x_unit.sh' --json`，不会预定 grader session。
33. reject 时使用 `5dive task reject DIVE-7 --feedback='FINDING: x / FIX: do y / VERIFY: run z' --json`；自 0.32.0（DIVE-4144）起 `--feedback` 在 reject 时是 REQUIRED，且必须点名 FIX 而不只是 finding；`--no-fix='<why>'` 是受审计的 escape。
34. 行是否被评分由 BOX 设置决定，行可双向覆盖：查看 `5dive config`；设置 `5dive config verify=always|delivered-only|never`（root，按 BOX 而非按 seat）；`5dive task add '...' --verify` 在 `never` box 上要求评分（也清除 auto-skips）；带 `=` 的 `--verify=<cmd>` 是另一回事，表示 acceptance COMMAND；`5dive task add '...' --no-verify` 在 `always` box 上跳过单行。
35. 每个 `ls` 都带 `gate` 列：`HUMAN:<type>` 表示人欠一个回答，`<seat>:<type>` 表示 agent 欠一个回答，`answered:<retire>` 表示已答，`-` 表示无 gate；用 `5dive task ls --gated --json` 只看持有 live gate 的行，用 `5dive task ls --gated=human --json` 精确看 `task inbox` 集合。
36. 当没有东西推进且看不出原因时运行 `5dive task doctor --json`，列出每个不会被 dispatch 的开放行以及清除每行的 verb（DIVE-3784）。
37. 查看谁向谁汇报：`5dive org tree --json`。
38. verifier 关闭 graded row 时必须在 `--result` 中写 `graded-sha: <sha>`，点名它实际读取的 commit；否则 merge gate 停在 `no-graded-sha-stated`；sha 不是 PR head 则停在 `graded-sha-is-not-the-head`（DIVE-2656）；`--no-graded-sha` 是受审计的 escape，不是正常路径。
39. 在运行 `5dive config verify-small=<lines>` 的 box 上，小于该 changed lines 且不触及 blast radius（scheduler、task store、credentials、deploy、shared libs、sudo policy、systemd、schema、provisioning）的 PR 可在 delivery 时直接关闭并说明；行上的 `--verify` 胜过它；`--no-verify` 从不胜过相反的 delivery-time UPGRADE。
40. verifier 自己的读取是受限的：用 `5dive task grade-context <id>` 物化私有 detached grading worktree 并打印 grading packet；从那里评分，绝不要从 shared checkout 评分。
41. 在 `done`/`cancel` 时，`--result` 的第一行会被 ping 到 owner 的手机；第一行要放一行简短总结，细节放在第一个换行之后。
42. 在 filing 行时用 `--review=` 选择 reviewer：`none` 无人评分，`task done` 直接关闭，不花 session；`check` 由命令评分，需要 `--verify='<cmd>'` 和 `--mutant='<cmd>'`，不花 session；`rubric` 对 bounded claim packet 做一次固定六问 pass，不花 session；`temp` 每次 delivery 用一个 fresh pool session，然后消失，花一个 session；`<seat>` 是 pinned standing reviewer，在它自己的 session 中评分，花一个 session。
43. `--review=` 示例：`5dive task add 'bump the pinned version in three manifests' --review=none`；`5dive task add 'add the retry arm' --review=check --verify='bash tests/retry_unit.sh' --mutant='git apply -R fix.patch'`；`5dive task add 'rework the claim path' --review=temp`；`5dive task add 'new pricing tile' --review=quinn --customer`。
44. `--review=check` 必须提供 negative control（DIVE-4623）：`--mutant=<cmd>` 是 BREAK the delivered tree 的命令（如 `git apply -R <fix>.patch`、`sed -i s/<new guard>/xx/ src/foo.sh`）；delivery 时两个 arm 都从 delivered sha 的 clean checkout 运行，check 必须在 delivered 时 PASS 且在 mutant 后 FAIL；若 check 在 mutant 后仍存活，delivery 会以该 finding 被 REFUSED 且不预定 grader session；对确实无法 invert 的 check（环境探针、live-box reachability test）用 `--no-mutant='<reason>'` 作为受审计 escape；`rubric` 在行带 flag、blast-radius path 或 `--verify` 时升级为 `temp`。
45. 什么都不传时行仍会得到 mode，并打印在 `created DIVE-N` 行、由 `task ls` / `task show` 显示：低优先级行、无 body 的 chore title、body 标记为 `mechanical`/`copy`/`doc` 或 body 只是一条 read-back command 时为 `none`；给了 `--verify=<cmd>` 时为 `check`；传了 `--customer` 时为 pinned seat；否则为 `temp`。
46. box 设置仍然封顶且会赢：`5dive config verify=never` 会在 `temp` 和 pinned `<seat>` 上强制 `none`（二者都会预定 session）并在 created line 说明，而不是静默降级；`check` 豁免（命令不花钱）；裸 `--verify` 是在这种 box 上为单行买回评分的唯一方式。
47. 把问题停在人类上：`5dive task need DIVE-12 --type=decision --ask='Ship behind a flag or straight to prod?' --options='flag|prod' --recommend='flag' --tier=1 --json`；`--type` 可选 `decision | secret | approval | manual | access`；任务变为 blocked，人类收到带 tap buttons 的 alert。
48. 查看所有未回答 HUMAN gate：`5dive task inbox --json`；`5dive task gates --json` 是 `inbox` 的纯别名（DIVE-4310）；`5dive task queue --json` 看向你路由的 gate（不唤醒你而 filing）；`5dive task answer DIVE-12 --value='flag' --json` 记录答案、解除阻塞并 ping owner。
49. 自 0.32.0 起 `--ask` 被 ENFORCED 而非建议（DIVE-4176）：到达 paired human 的 gate 若 `--ask` 超过 25 words，或点名 ident、sha、branch、path、flag、check name，会被拒绝；人类只看到这段文字且从未读过代码，要写成 OUTCOMES 之间的选择，把所有机制放进 task BODY；`--ask-ok='<why>'` 可照常 filing，但会记录在 gate 上并计数，只在确实无法用 plain English 写 ask 时使用。
50. 始终为 decision/approval 传 `--recommend`；alert 会以你的 recommendation 开头，让人类可一键处理。
51. 在 25-word 拒绝之下还有约 15-word render budget：超过约 15 words 会 WARN（will render cut），因为 gate message 在手机上会截断；警告会 filing，拒绝不会；目标瞄准 15。
52. `--options` 仅用于 decision；在任何其它 `--type` 上用 `--options` 会被直接拒绝（`--options only applies to --type=decision`）；decision 上的 `--recommend` 需要 `--options` 可匹配；自 0.36.0（DIVE-4462）起，全部为单字符的 options 也会被拒绝，因为 options 就是人点击的按钮，按钮写 `A` 不点名任何 outcome；每个选项写成 plain outcome。
53. 使用 risk tiers `--tier=0|1|2`：`0` 立即 auto-clear（需要 `--recommend`，不 ping）；`1` ping 但 48h 未回答则 auto-apply recommendation；`2` 永不 auto-apply；money、public comms、secrets、destructive、brand asks 无论 flag 如何都 floored 到 tier 2。
54. 谁能清除 gate 由 TYPE 而非难度决定，filing 前就检查，不要等 `task answer` 拒绝（DIVE-3228）：`decision` 默认 tier 1，任何 agent 可清；`approval` 默认 tier 1（不是 2），routed lead 可清；`access` 默认 tier 2，routed lead 在默认下可清；`manual` 默认 tier 2，仅 human；`secret` 默认 tier 2，在每一 tier 都仅 human，且从不 routed。
55. 自己 pin `--tier=2` 或触发 category floor 会让 `approval` 和 `access` 也变成 human-only；任何 type 上 `--needs=spend_authority|human_tap|secret_provision` 都按声明成为 human-only 并压过 tier；不要把 approval 手传 `--tier=1` 来让它避开人类，因为那已是默认且该 flag 是 no-op。
56. 自 0.34.0 起，tier<2 的 `decision` gate 会按 kind 路由到 ORG LEAD（DIVE-4415），根本不到 paired human，也不读 `gate_builder_routing` preference；该 preference 只管辖 unbound tier<2 的 `approval` 或 `manual` gate；用 `5dive task routing` 读 live answer，不要凭记忆。
57. 确实到达 paired human 的 gate 必须点名它消耗的 capability（DIVE-4346），否则 filing 时被拒绝：customer 只为四件事被 tap——money、a secret、something irreversible、something only a person at a browser or keyboard can do；用 `--needs=spend_authority|secret_provision|human_tap` 声明其一；如果无法点名 capability，那是你不舒服的 decision，不是 human gate。
58. 把 lead-held gate 向上转发给 paired human 用 `5dive task gate-escalate`；只有 gate filer、其 lead、routed reviewer、org coordinator 或真实登录 session 的人类可做（DIVE-4365）；不要为了触达人而把 gate 重新 filed 成 `--tier=2`，那会丢失 gate history，也是该 rail 要阻止的失败。
59. routed gate 会 QUEUE 到 reviewer 下一次自然 wake，而不是唤醒其 session；`--urgent` 在 file 时 ping；它不同于 `--recommend`，`I think the answer is X` 和 `this cannot wait` 是两个独立声明。
60. 在重新推导前搜索团队记忆：`5dive memory search 'hetzner capacity gotchas' --json`；只读、无需 sudo、BM25-ranked snippets 带 file+heading provenance。
61. 大 store 上用两阶段 recall（DIVE-3821）：`5dive memory search 'hetzner capacity' --index` 作为 stage 1 返回 slug + one-liner + score，无 body；`5dive memory get <slug> [<slug>...]` 作为 stage 2 只取你选中的完整 body。
62. stage-1 空结果才是 absence 的证据，短 index 不是；用 FACT 会使用的词搜索，而不是任务使用的词。
63. 检查自己的身份：`5dive whoami --json` 显示 actor、authority（`root|sudo:<who>|self`）和 tier，以及每项的 SOURCE；当 gate 拒绝或权限错误不合理时用它，它点名 CLI 实际看到的 uid/agent/tier；无法测量 actor 时以 exit 6（`auth_required`）退出，可兼作可测量性检查。
64. 任务涉及以 agent 身份打开/评论 PR 或 issue 时，优先用 `5dive gh <gh args...>` 而不是直接调用 `gh` binary：写操作（`pr create`、`pr merge`、`issue comment` 等）路由到 `5dive-bot` machine account，使 GitHub actor 字段能区分 agent 与人类（DIVE-2448）；读和管理类调用自动留在自己的 credential 上；`5dive gh --explain <args>` 预览路由决定而不运行。
65. 始终传 `--json`，解析 envelope，不要 grep stderr。
66. 一个名字对应一个 agent；名字为小写字母/数字/连字符、以字母开头、最多 16 字符；只有在 `agent rm` 后才可复用名字。
67. 不要共享 bot token；同一 bot 上的两个 Telegram-channel agent 会在 `getUpdates` 上互相竞争；每个 agent 需要自己的 token。
68. 拆除自己 spin up 的东西；泄漏的 `worker-N` agent 会跨 reboot 继续运行，因为它是真实 systemd unit 而不是 thread；任务完成时调用 `5dive agent rm <name>`。
69. 不要直接 shell out 到底层 CLI binary；绕过 `5dive` 会跳过 systemd unit、audit log 和 env injection，agent 会以 broken auth 运行且没有 restart loop。
70. 如果某个 flag 被以 unknown 拒绝，读 `5dive --help`；host 上的 binary 可能比本 skill 新或旧，help 输出是权威。
71. 被人类阻塞时，用带 recommendation 的 `task need` gate 它，而不是猜或让任务静默腐烂。
72. 委派聊天请求时，不要 relay，使用 `agent send --reply-to-chat=<id> --reply-to-msg=<id>` 交接上下文。
73. 需要每个子命令和 flag 的可复制内容时看 `references/commands.md`；它还包括较少用的顶层 verbs：`5dive deploy`（delegated production deploy，INST-5）、`5dive bug`（diagnostic issue filing）、`constitution`（machine-enforced guardrails 的前门）、`5dive ui`（本地只读 web UI：org chart/queue/gates，DIVE-2655）、`5dive acp`（通过 stdio 说 ACP，让 Buzz/Zed 等 client 选 5dive 为 coding-agent runtime，由 client spawn 而非直接运行，DIVE-3017）、`liveness`（seat 是否对它 WRITTEN 的 artifact 存活，DIVE-3778）、`plugin`（安装/启用/回滚 plugins + marketplaces）、`human`（能 CLEAR gate 的人，DIVE-3342）、`run`（一个 agent 对一个 task 的一次 attempt，是 `trace` 下的单位）、`trigger`（签名外部事件变成普通 tasks）和 `host`（CLI-root grant 下的 hardened unit/journal/cron remediation）。
74. 运行时管理超出本技能范围（crew hosting、multi-account auth、auth recovery、declarative fleets/compose、goal DAGs、objectives、loops、compiling into wiki、org-chart writes、governance votes、digest/usage/supervisor/fleet/diagnose、Telegram pairing、persona market、BYO providers、company wizard、`5dive plugin`、`5dive liveness`、`5dive human`、`5dive run`、`5dive trigger`、`5dive host`、nostr handset rail `5dive buzz`）时看 `5dive-cli-extras` skill。
75. 理解资源映射：一个 agent = 一个 Linux user（`agent-<name>`）+ 一个 systemd unit（`5dive-agent@<name>.service`）+ 一个 tmux session（`agent-<name>`），在其中以 restart loop 运行选定的 CLI。
76. 认证与 agent 解耦：认证一个 type 一次，该 type 的每个 agent 通过 `EnvironmentFile` 继承 credentials。
77. 选择 channel：`telegram`/`discord`/`dashboard`/`buzz`/`none`，可逗号列表；除 `devin` 外每种 agent type 都支持 `telegram`（`devin` 完全没有 chat bridge，只能通过 `agent send`/`agent ask` 触达）；其它 channel 每个都更窄。
78. `telegram`/`discord` 各自需要自己的 bot token；`discord` 只在 `claude`、`openclaw`、`hermes` 上工作，create 时对 `codex`/`grok`/`antigravity`/`opencode`/`devin` 会拒绝，`pi` 在校验时接受但 install 时死亡（`telegram only`）。
79. `dashboard` 只在 claude 或 codex，且 token-free，是 web-dashboard chat，默认折入每个 claude create；`--channels=none` 选择退出。
80. `buzz` 是 nostr handset rail，且 claude-only；它由 `agent buzz enable` 接线，而不是 token（详见 `5dive-cli-extras`）。
81. CLI 是幂等的，可从另一个 agent 安全调用，但 `sudo` 受 isolation tier 限制（DIVE-1002）：新 agent 默认 `standard` 零 sudo；只有 fresh box 上第一个 agent 或 `--isolation=admin` 创建的 agent 获得 scoped grant——`5dive` CLI 加上对 `5dive-*` units 的非分页 `systemctl start|stop|restart`，不是 `NOPASSWD:ALL`。
82. 因此无 sudo surfaces（`5dive task`、`org` reads、`memory`）可从任何 agent 运行；root surfaces（`agent create`/`config`/`pair`、`heartbeat on/off`、`doctor`、`usage`）需要 admin agent。
83. 当前 host 上 agent types 为 `antigravity claude codex devin grok hermes openclaw opencode pi`；`devin` 和 `pi` 自 Jul 2026 起 live；运行 `sudo 5dive agent types --json` 查看实际安装；输出中的 `installed=missing` 表示 type KNOWN 但 binary 不在本机，不等于 unsupported。
84. 完整参考手册在 <https://5dive.com/docs>；若本 skill 的 flag 与运行中的 binary 冲突，信任 binary，直接运行 `sudo 5dive --help` 或 `sudo 5dive agent <sub> --help` 并遵循。
85. 本 skill 同步到 5dive CLI 0.47.0（commit `4704e3ad`，2026-09-21）；给定 box 的 binary 可能比 main 滞后最多一天（nightly update channel），不同时信任 `5dive --help`。

适用边界 · 注意事项

• 普通本地编码任务（编辑文件、运行 build、运行 tests、调试自己的程序）不适用；这些不需要 runtime CLI。
• 超出上述协调/任务队列/记忆搜索的运行时管理不适用；应使用 `5dive-cli-extras`。
• 用户只是要你自己完成工作时，不要 spawn agent。