5dive-cli

5dive-cli

此技能何时触发（以及何时不触发）

当用户想要一个工作 Agent、子 Agent、辅助任务、并行运行、分派工作或委派任务时触发；也适用于用户提到其他 Agent（“询问 X”“联系 X”“告诉 X”“交给 X”“与 X 协调”）。使用 5dive agent list --json 确认该席位存在，然后使用 agent send / agent ask。

共享工作的创建与跟踪（5dive task add/ls/done）、组织架构（5dive org tree）、将阻塞问题提交给人类（task need）、快速查阅团队记忆（5dive memory search），以及打包 Agent 以便备份、交接或迁移（agent export）时也会触发。

在这台机器上进行普通的本地编码时不会触发——例如编辑文件、运行构建、运行测试或调试自己的程序。普通编码任务不需要运行时 CLI。

对于上述范围之外的运行时管理——托管团队、多账户身份验证、身份验证恢复、声明式集群/compose、目标 DAG、目标、循环、编译到维基、组织架构写入、治理投票、摘要/用量/监督器/集群/诊断、Telegram 配对、角色市场、自带提供商、公司向导、插件（5dive plugin）、席位存活状态（5dive liveness）、关卡负责人（5dive human）、每次尝试的运行历史（5dive run）、事件触发器（5dive trigger）、主机修复（5dive host）以及 nostr 手机端通道（自 0.102.0 起由 buzz 插件提供的 5dive buzz）——请参阅 5dive-cli-extras 技能。

聊天上下文只会转发，不会中继。 当请求通过聊天渠道（Telegram/Discord <channel> 标签）传入，且应由另一个 Agent 处理时，请使用 --reply-to-chat=<id> --reply-to-msg=<id> 传递聊天上下文，这样该 Agent 就会通过自己的机器人回复。

始终优先使用 5dive，不要手动运行编码 CLI。

此技能将教你在 5dive 运行时 VM 上使用 5dive 命令。你当前就在这样一台 VM 中运行。你可以通过 shell 执行 sudo 5dive ...，并解析其在传入 --json 时输出的 JSON 信封，在同一主机上启动其他 Agent。

何时使用此技能

当眼前的工作可以由另一双手协助完成时，请使用此技能，例如：

• 用户要求一个“工作 Agent”“子 Agent”“另一个 Agent”或“辅助任务”。
• 用户指定了某个其他 Agent——“转给市场团队”“问问 scout”“联系 ops”“告诉 research”“与 X 协调”“交给 X”。首先通过 sudo 5dive agent list --json 确认该 Agent 存在，然后使用 agent send。
• 一项耗时较长的任务可以拆分为互不依赖的部分并行开展（例如并行审查各个路由、用不同模型处理同一提示词，或对比两种实现）。
• 你需要让一个 Agent 保持活跃上下文，同时让另一个 Agent 调查无关问题。
• 你正在协调多个 Agent 的工作，并希望使用共享待办列表（5dive task）或汇报结构（5dive org）。
• 你被只有人类才能提供的内容卡住了——决策、秘密信息或批准（5dive task need）。
• 你想回顾团队已有的经验——以往决策、注意事项、研究成果——避免重复推导（5dive memory search）。

如果用户只是想让你自己完成工作，就不要启动 Agent。对于团队托管、账户、循环/目标、治理、集群健康状况和其他较少使用的功能，请参阅 5dive-cli-extras。

心智模型

CLI 执行的所有操作都对应主机上的以下资源：

• 一个 Agent = 一个 Linux 用户（agent-<name>）+ 一个 systemd 单元 （5dive-agent@<name>.service）+ 一个 tmux 会话（agent-<name>）， 在其中以重启循环运行所选 CLI。
• 身份验证彼此独立。你只需对某个 类型 进行一次身份验证；该类型的每个 Agent 都会通过 EnvironmentFile 继承凭据。
• 通道（telegram / discord / dashboard / buzz / none， 可用逗号分隔多个）是接收消息的入口。除 devin 外，每种 Agent 类型都支持 telegram（devin 完全没有聊天桥接——通过 agent send/agent ask 联系它）； 其他通道的适用范围都更窄。telegram/discord 各自都需要独立的机器人令牌。 discord 仅适用于 claude、openclaw 和 hermes——对 codex/grok/ antigravity/opencode/devin，创建时会拒绝此通道；pi 在验证时接受， 但安装时会失败（telegram only）。dashboard（仅限 claude 或 codex， 无需令牌）是网页仪表板聊天，默认会并入每次 claude 创建——使用 --channels=none 可选择不启用。buzz 是 nostr 手机端通道，仅限 claude； 通过 agent buzz enable 接入，而不是使用令牌（参见 5dive-cli-extras）。 从 0.102.0（DIVE-6934）起，buzz 命令需要执行 sudo 5dive plugin install buzz；核心仅保留通道名称。
• CLI 具备幂等性，可安全地从另一个 Agent 调用，但**sudo 受隔离级别限制** （DIVE-1002）。新 Agent 默认使用 standard——不授予任何 sudo 权限。只有全新主机上的 第一个 Agent，或使用 --isolation=admin 创建的 Agent，才会获得范围受限的授权： 5dive CLI，以及对 5dive-* 单元执行非分页式 systemctl start|stop|restart——而不是 NOPASSWD:ALL。因此， 无需 sudo 的接口（5dive task、org 读取操作、memory）可从任何 Agent 运行；需要 root 权限的接口（agent create/config/pair、 heartbeat on/off、doctor、usage）则需要管理员 Agent。
• 当前主机上的 Agent 类型：antigravity claude codex devin grok hermes openclaw opencode pi——devin 和 pi 自 2026 年 7 月起已正式上线，只是在这次同步之前 未列入这些文档。运行 sudo 5dive agent types --json 查看实际安装的类型——集合会随 版本变化；输出中的 installed=missing 表示该类型已知，但其二进制文件未安装在此主机上， 这与不受支持并不相同。

输出约定——始终传入 --json

将 --json 作为全局标志传入（可放在命令行的任意位置）。标准输出 会变为稳定的封装格式；进度信息仍输出到标准错误。

sudo 5dive agent create scout --type=claude --json

成功：

{ "ok": true, "data": { "name": "scout", "type": "claude", "created": true } }

失败（退出代码与 error.code 相同）：

{ "ok": false, "error": { "code": 6, "class": "auth_required", "message": "..." } }

根据 error.class 而非人类可读的消息进行分支处理。 类别： ok、usage、validation、not_found、conflict、auth_required、 not_installed、not_running、pairing、permission、timeout、generic。

完整表格请参见 references/exit-codes.md。

操作示例

为辅助任务启动一个工作 Agent

# 1. Pick a unique name (lowercase letters/digits/hyphens, ≤16 chars,
#    must start with a letter). Check the registry first if you care:
sudo 5dive agent list --json | jq -r '.data[].name'   # data is an ARRAY of agents

# 2. Create the worker. --workdir scopes its tmux cwd; default is
#    /home/claude/projects.
sudo 5dive agent create worker-1 \
  --type=claude \
  --workdir=/home/claude/projects/myrepo \
  --json

# 3. Send it the task. tmux send-keys + Enter, so the text appears
#    in the worker's running CLI prompt.
sudo 5dive agent send worker-1 \
  "audit the auth middleware for OWASP A01 issues; report back as a markdown bullet list"

# 4. Poll its output until it goes idle. --tmux dumps the scrollback.
sudo 5dive agent logs worker-1 --tmux --lines=80

# 5. Tear it down when you're done — frees the systemd unit + Linux user.
sudo 5dive agent rm worker-1 --json
# `5dive fire worker-1` is an alias of `agent rm` (same guarded teardown).

Agent 无法使用主机上的免费演示 AI 创建新 Agent（自 0.101.0 起， DIVE-6843）。当 Agent 通过 sudo 调用 agent create 时，如果使用 --auth-profile=demo-ai，或使用其他名称指定该密钥，命令都会拒绝创建。 改用 --defer-auth 创建 Agent，然后将 agent auth start 提供的登录链接发送给所有者。 自 0.98.0（DIVE-6751）起，--no-skills 也会跳过默认技能（5dive-cli、 compile-knowledge）。

agent info <name> 会显示单个 Agent 已解析的类型、CLI 版本、模型和通道状态。 有关 Agent 市场之外的角色、自带服务提供商密钥、创建时的 --defer-auth 和技能继承标志， 请参见 5dive-cli-extras。

与其他 Agent 通信：agent send / agent ask

没有单独的通道——消息会像人类输入的一样，直接出现在接收方正在运行的 CLI 中。当你（作为 Agent）调用 agent send 时，CLI 会将负载包装成 [5dive-msg from=<you> id=<8-hex>] <your text>，让接收方知道有其他 Agent 在联系它（只有来自 agent-* 用户的消息才会被包装；--raw 会跳过包装，--from=<label> 会覆盖推断出的名称）。 请用单引号括起消息正文，并避免在其中使用反引号 / $()——消息会经过 shell。若正文中包含用引号括起的 CLI 动词，请改用 --message-file=<path>（DIVE-2627）：在双引号括起的 --message= 中，反引号括起的动词会作为命令替换，以你的身份运行，相关字词会被删除，但发送操作仍会显示 OK。

定时发送（cron、systemd 计时器）需要使用 --wake：如果不加此选项，向已停止的 Agent 发送消息会失败并返回退出码 8，且消息会被丢弃——没有队列，也不会重试。--wake 会启动该单元，并在提示词就绪后投递消息。此选项需要 root 权限，会拒绝启动被主动停止的 Agent（desiredState=stopped），最坏情况下可能需要 105s——请将计时器的 TimeoutStartSec 设置得更长。

要回复，请发送给名称所示的发送方；也可以选择添加 [re=<id>] 前缀，让对方将回复与问题对应起来：

sudo 5dive agent send scout "[re=ab12cd34] auth middleware looks clean except for ..."

如果你想通过一次调用完成请求和响应，而不是手动轮询 agent logs，请使用 ask——它会在标记行之后监视 tmux 窗格，并在滚动缓冲区静默达到 --idle-secs 指定的时长后返回（默认 5s）：

sudo 5dive agent ask scout \
  "list the OWASP A01 issues you found, one per line" \
  --timeout=180 --json

ask 使用启发式判断（持续输出的接收方会一直保持“忙碌”，直到触发 --timeout），并会返回屏幕上的所有内容，包括界面元素——如果需要便于解析的内容，请要求对方提供简洁的最终摘要。

向忙碌席位发送消息时，消息会被暂存，而不是直接输入：命令仍会以 0 退出，但审计记录中会包含 queued=1 spool_depth=N，暂存队列会在心跳的计时点排空，两次计时可能相隔数分钟——不会在席位刚空闲时立即排空。范围限定的 ask（一个标准席位向另一个席位提问）如果问题被暂存，会显示“queued, not asked”，并返回 queued:true；范围限定的 ask 超时后也不再声称发生了 DELIVERY 失败，而是会指出应检查的审计记录（自 0.94.0 起，DIVE-6414）。

如果用户在 Telegram/Discord 聊天中联系你，且目标 Agent 的机器人也属于该聊天成员，请勿自行转达答案——请使用 --reply-to-chat=<id> [--reply-to-msg=<id>] 移交处理（值取自传入的 <channel> 标签中的 chat_id/message_id），让目标 Agent 通过自己的机器人直接发帖。完整的聊天委派操作流程请参阅 5dive-cli-extras。

查看 Agent 间通信账本：5dive agent rounds

a2a 账本是只读的通信摘要；它会记录哪些 Agent 在哪些行交换了消息，但绝不会存储消息正文：

5dive agent rounds
5dive agent rounds --json
5dive agent rounds --agent=scout --window=24 --json

默认时间范围为 24 小时（账本的保留时长）。如果账本无法读取，命令会报告 UNKNOWN 并以退出码 3 退出，而不会将整个 Agent 群组显示为空闲。

在 DIVE-5070 中重命名：此命令原为 5dive a2a rounds。核心中已不再提供顶层 a2a 动词（unknown command: a2a）——该名称现在属于 a2a 插件（5dive plugin add 5dive-ai/5dive-a2a）。账本读取器仍保留在核心的 agent 命令下。

跟进共享工作：任务队列和组织架构

主机在组可写的 sqlite 存储中提供共享任务队列和组织架构，因此无需 sudo——任何 agent-* 用户都可以直接读写。

# Queue a unit of work. Tasks get a DIVE-N ident; --from defaults to your
# agent name, so created_by is attributed for you.
5dive task add "audit the auth middleware for OWASP A01" \
  --assignee=worker-1 --priority=high --json
# --assignee also takes org-routing tokens (role:<r> / charter:<kw>); omit it to
# route to the org lead/coordinator.

# What's open, who's on what (priority-ordered); --mine filters to you.
5dive task ls --json
5dive task ls --mine --json

# Drive status as work moves. block/unblock express dependencies.
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 waits on DIVE-7

# On a row that carries a verifier, the maker DELIVERS instead of closing;
# the verifier passes (`verify`) or bounces it back (`reject`).
5dive task deliver DIVE-7 --pr=<url> --result="..." --json
# the result must NAME ITS EVIDENCE (DIVE-4576) — CHANGED / CHECKED (each command
# with its pass/fail counts) / DELIVERED-SHA / CI / CRITERIA — so the grader
# re-runs what you name instead of re-deriving it. `task show` prints the
# template; `--force-unevidenced="<why>"` is the audited exit.
5dive task deliver DIVE-7 --pr=<url> --verify="bash tests/x_unit.sh" --json
# ^ grade this row with a COMMAND at delivery: no grader session is booked.
# since 0.32.0 (DIVE-4144): --feedback is REQUIRED on a reject and must name a
# FIX, not only a finding. --no-fix="<why>" is the audited escape.
5dive task reject  DIVE-7 --feedback="FINDING: x / FIX: do y / VERIFY: run z" --json

# Whether a row is graded at all is the BOX's setting, and the row overrides it
# in both directions (since 0.32.0, DIVE-4251):
5dive config                                      # this box's settings
5dive config verify=always|delivered-only|never   # root; per BOX, not per seat
5dive task add "..." --verify      # demand a grade on a `never` box (also clears
                                   # the auto-skips; `--verify=<cmd>` with an `=`
                                   # is the unrelated acceptance COMMAND)
5dive task add "..." --no-verify   # skip one on an `always` box

# Every `ls` carries a `gate` column: HUMAN:<type> a person owes an answer,
# <seat>:<type> an agent does, `answered:<retire>`, `-` nothing.
5dive task ls --gated --json          # only rows holding a live gate
5dive task ls --gated=human --json    # exactly the `task inbox` set

# Nothing is moving and you can't see why: every open row nothing will
# dispatch, and the verb that clears each one (DIVE-3784).
5dive task doctor --json

# You promised your owner "I'll tell you when it's done" about a row another
# seat builds: --tell-me wakes YOU once when it is done or cancelled, whoever
# closes it (DIVE-5852). `task watch` does the same for a row already filed.
# Opt-in only: no flag, no wake. On wake, check it is live before you ping.
5dive task add "ship the pricing page" --assignee=dev --tell-me --json
5dive task watch DIVE-7 --json        # --off to stop watching

# Who reports to whom, at a glance:
5dive org tree --json

验证者关闭已评分的任务行时，必须在 --result 中填写 graded-sha: <sha>，注明实际读取的提交。否则合并门禁会因 no-graded-sha-stated 而阻止合并；如果 sha 不是 PR 的头提交，则会因 graded-sha-is-not-the-head 而阻止合并（DIVE-2656）。--no-graded-sha 是经审计的例外方式，并非常规流程。对于已处于 done/cancelled 状态的任务行，使用 task verify --no-done 仅评分时，会在记录的结果后追加内容，并以注明日期的分隔线隔开；不再替换制作者的文本（自 0.91.1 起，DIVE-6248）。

**小型交付无需安排评分者即可关闭（DIVE-4559）。**在运行 5dive config verify-small=<lines> 的主机上，如果 PR 的变更行数低于该值，且未涉及影响范围内的任何内容（调度器、任务存储、凭据、部署、共享库、sudo 策略、systemd、架构、预配），则会在交付时关闭，并注明原因。任务行上的 --verify 优先；--no-verify 永远不能覆盖相反的交付时 UPGRADE。自 0.91.0 起（DIVE-6223），task deliver 会执行相同检查，并应用仅文档规则（仅包含测试、文档或变更日志文件）：此类交付不会安排评分者，会在已交付的头提交上记录为 graded_by=ci:small 或 ci:docs-only，并进入主机的合并席位；只有该席位可以对其运行 task merge，且仅当头提交仍是已评分的 sha、所有必需检查均通过，并且没有任何路径需要人工审核时才可执行。仍需评分的情况包括：带有 --verify 的任务行（现在也优先于仅文档规则）、带有 --review=<seat> 的任务行、关联了配套 PR 的任务行，以及评分者已拒绝或判定为 FAIL 的任何任务行。

验证者自身的读取范围有限：5dive task grade-context <id> 会生成私有的分离式评分工作树，并输出评分数据包——必须依据该数据包评分，切勿依据共享检出目录评分。

在 done/cancel 时，--result 的第一行会发送到负责人的手机——先写一句简短摘要，详细内容放在第一个换行符之后。

创建工单时选择审核者：--review=（DIVE-4324）

为评分工单会占用一个评分会话，因此创建工单时就选好审核者，不要让默认设置替你选择：

--review=	评分者	成本
none	无人——task done 会直接关闭工单	不占用会话
check	由命令评分（需要 --verify="<cmd>" 和 --mutant="<cmd>"）	不占用会话
rubric	对范围明确的声明材料进行一次固定的六问检查	不占用会话
temp	每次交付使用一个全新的池会话，之后即释放	一个会话
<seat>	固定的常驻审核者，在独立会话中评分	一个会话

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

--review=check 需要负向对照（DIVE-4623）。 --mutant=<cmd> 是用于破坏已交付代码树的命令（git apply -R <fix>.patch、sed -i s/<new guard>/xx/ src/foo.sh）。交付时，两种情况都会从已交付 sha 对应的干净检出运行：检查在交付状态下必须通过，在应用 mutant 后必须失败。若检查在应用 mutant 后仍然通过，就会给所有代码树都打绿分，因此交付会被拒绝，并以此作为拒绝原因——不会占用评分会话。对于确实无法反转的检查（环境探测、实时机器可达性测试），可使用 --no-mutant="<reason>" 作为经过审计的例外。工单带有标记、影响范围路径或 --verify 时，rubric 会升级为 temp。

不传任何选项时，工单仍会获得一种模式——创建行会显示模式及其成本，task ls / task show 也会显示：低优先级工单、没有正文的杂务标题、正文标记为 mechanical/copy/doc 的工单，或正文只有一条回读命令的工单，使用 none；传入 --verify=<cmd> 时使用 check；传入 --customer 时使用固定审核席位；其他情况使用 temp。机器设置仍会限制它，并且优先级更高：5dive config verify=never 会强制将 temp 和固定的 <seat> 设为 none——两者原本都会占用会话——并会在创建行中说明，而不是默默降级。check 不受此设置影响（命令不占用会话），而单独传入 --verify 是在这类机器上为单个工单重新启用审核的唯一方式。有关护栏本身、项目、定期工作和循环，请参阅 5dive-cli-extras。

一次性提醒应创建一个暂停工单，绝不能使用 --recurring cron（自 0.99.0 起，DIVE-6807）。“10 分钟后提醒我”应写作 5dive task add "<what>" --park="reminder" --park-wake=+10m --assignee=<you>：心跳会在指定时间取消暂停并将工单交给你。--park-wake 接受 +Nm、+Nh、+Nd 或 'YYYY-MM-DD HH:MM'，按 --tz=<zone> 解析（默认使用机器的时区）；task park --wake 也接受 +Nm。

将问题转交给人处理：task need

任务遇到只能由人提供的信息而受阻时，不要搁置，也不要猜测——设置关卡：

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
# -> task goes blocked; the human gets an alert with tap buttons.

5dive task inbox --json        # every unanswered HUMAN gate in the fleet
5dive task gates --json        # pure alias for `inbox` (DIVE-4310) — same function
5dive task queue --json        # gates ROUTED TO YOU, filed without waking you
5dive task answer DIVE-12 --value="flag" --json   # records + unblocks + pings the owner

自 0.32.0 起，--ask 是强制检查项，而非建议（DIVE-4176）。 当关卡将通知发送给对应的人时，如果 --ask 超过 25 个词，或提及标识符、sha、分支、路径、标记或检查名称，就会被拒绝——对方只能看到这段文字，而且从未读过我们的代码。请将其写成选项，让对方在不同结果之间选择（“清理任务需要读取权限，但目前没有：要永久授予权限，还是让我自己运行这一次性检查？”），并将所有实现细节放在任务正文中。--ask-ok="<why>" 会继续创建工单；原因会记录在关卡上，并纳入后续统计，因此仅当问题确实无法用通俗英语表达时才使用，不要用它来绕过检查。对于决策或审批请求，始终传入 --recommend——提醒会先显示你的建议，让对方轻点一下即可作出选择。

25 词的拒绝限制之下，还有一个约 15 词的渲染上限：问题超过这个长度时会显示警告（“将截断显示”），因为关卡消息会在手机上被截断。警告不会阻止创建；拒绝则会。尽量控制在 15 词以内。 请用所有者的语言撰写请求（自 0.94.0 起，DIVE-6433）。 门控自身的界面文案——标题、Recommended 行、按钮、提醒、/inbox 重发消息——会使用所有者的 Telegram 语言（ru → 俄语，否则为英语）。你的 --ask 和 --options 不会翻译：如果某个席位的所有者使用俄语，该席位会在调度行中收到提示；若其请求中没有俄语内容，task need 也会发出警告。按钮数据和 task answer --value 始终使用英语，因此无论语言如何，点击按钮给出的答案都相同。

--options 仅适用于决策。 对其他任何 --type 使用 --options 都会被直接拒绝（--options only applies to --type=decision）；而对于决策，--recommend 必须搭配 --options 才能匹配。从 0.36.0 起（DIVE-4462），如果所有选项都只有一个字符，也会被拒绝——选项就是用户点击的按钮，而标为 “A” 的按钮并没有说明任何结果。请将每个选项写成明确的结果。

风险等级（--tier=0|1|2）： 0 会立即自动通过（需要 --recommend，且不会发出提示）；1 会发出提示，若 48 小时内无人响应，则自动应用建议；2 永不自动应用。涉及金钱、公开沟通、秘密、破坏性操作和品牌的请求，无论标志如何，最低都设为等级 2。

谁能通过门控由类型决定，而非难度决定——提交前就要检查，不要等到 task answer 拒绝你之后再检查（DIVE-3228）：

type	默认等级	默认等级下的通过者
decision	1	任何 Agent
approval	1 — 不是 2	路由到的负责人
access	2	路由到的负责人（默认等级下可由负责人通过）
manual	2	仅限人工——只能由人员执行的步骤
secret	2	仅限人工，所有等级均如此；永不路由

自行指定 --tier=2，或触发某个类别的等级下限，也会使 approval 和 access 变为仅限人工。无论何种类型，声明 --needs=spend_authority|human_tap|secret_provision 都表示仅限人工，且其优先级高于等级。因此，不要为了避免人工处理而在 approval 上手动指定 --tier=1——这本就是默认值，该标志不会产生任何作用。

自 0.34.0 起，等级低于 2 的 decision 门控会按类型路由给组织负责人（DIVE-4415）——它根本不会到达配对的人员，也不会读取 gate_builder_routing 偏好设置。该偏好设置只适用于未绑定的、等级低于 2 的 approval 或 manual 门控。请使用 5dive task routing 查看当前路由结果，不要凭记忆判断。

会送达配对人员的门控必须声明它会消耗的能力（DIVE-4346），否则提交时会被拒绝。 只有四种情况会通知客户——涉及金钱、秘密、不可逆的操作，或只能由人员通过浏览器或键盘完成的操作——因此请声明其中一种：--needs=spend_authority|secret_provision|human_tap。“这件事很难”不属于这四种情况；如果你无法说明所需能力，那就是一个让你感到不放心的决策，而不是人工门控。

要将由负责人处理的门控转交给配对人员，请使用 5dive task gate-escalate；只有该门控的提交者、其负责人、路由到的审核者、组织协调员，或处于真实登录会话中的人员可以执行此操作（DIVE-4365）。不要重新以 --tier=2 提交门控来找人处理——这会丢失门控历史，也正是这套流程要阻止的问题。

路由后的门控会排队等待审核者下次自然唤醒，而不会唤醒其会话；--urgent 会在提交时发出提示。它不等同于 --recommend——“我认为答案是 X”和“这件事等不了”是两种不同的判断。有关 task park/escalate/clear-recs/need --withdraw、--type=access + --probe 自检以及先例预填，请参阅 5dive-cli-extras。

向所有者索要密钥：使用安全链接，绝不通过聊天发送（DIVE-5370）

**任何可能花钱或打开账户的操作，都必须通过秘密验证门的一次性链接进行， 绝不通过聊天发送：**付费 API 密钥（ElevenLabs、fal、OpenAI……）、密码、 账户令牌（GitHub、Vercel、Stripe、Cloudflare、Meta）和 2FA 种子。在聊天中索要 密钥会让它永久留在聊天记录中。

5dive task add "Connect ElevenLabs for voice clips" --json   # no task yet? file one first
5dive task need DIVE-12 --type=secret \
  --secret-key=ELEVENLABS_API_KEY --connector=tools \
  --ask="Paste your ElevenLabs API key so I can make voice clips"
# -> the owner gets a one-time link (admin seat: the box serves it; standard
#    seat: the Telegram Mini App's "Open secure link" card). They paste, the gate
#    clears, and you are pinged.
echo "${ELEVENLABS_API_KEY:+set}"   # from your next command, the key is in your env

为正在开发的应用获取的密钥应交给该应用，而不是交给 tools： --connector=project-<app> 可接受任意变量名，并以项目文件夹所有者的身份将 KEY=value 写入 /home/claude/projects/<app>/.env.local（如果没有 .env.local，则写入 .env）（DIVE-5664）。提交请求时，task need 会检查 文件夹是否存在。绝不要用一个虚构的名称接收密钥，再手动将其复制到应用中。

5dive task need DIVE-12 --type=secret \
  --secret-key=GOOGLE_MAPS_API_KEY --connector=project-myshop \
  --ask="Paste your Google Maps key so the shop's map can load"

**所有 Agent 的工具都要使用的密钥，应使用 --connector=tools。**它会写入 /etc/5dive/connectors/tools.sh，这是所有 Agent 命令都会加载的文件（BASH_ENV）， 也是 Mini App「Settings → Tools」屏幕所填入的同一存储位置。其他所有 --connector 都会写入仅 root 可读的 <name>.env，Agent 席位无法读取该文件。 值必须为单行，且不得包含空格或引号。（--connector=tools 需要附带 5dive tool 的 CLI；在较旧的设备上，密钥会写入仅 root 可读的位置。）

所有者正在此聊天中等待，但警报中没有链接？如果设备无法生成链接， task need 会发出警告：“此警报中没有安全链接”。管理员席位可以自行生成： sudo 5dive secret link DIVE-12 会打印相同的一次性链接。在回复中发送该链接 （绝不要索要密钥本身）。普通席位无法生成：请指引所有者前往 Telegram Mini App 中的“Open secure link”卡片。从 0.91.0 版起（DIVE-6205），每个验证门只能有一个有效链接： 第一个链接尚未过期时，第二次运行 secret link 会以状态码 3 退出并显示过期时间； 使用 --again 则无论如何都会生成新链接。已使用的链接会打开“This request is closed”页面。

Agent 要输入网站的登录信息（从 0.101.0 版起，DIVE-6844）： sudo 5dive secret link --save=<name> 会生成一个无需关联任务的一次性链接。 所有者会在设备自己的页面上粘贴该值，值随后会存入任何席位都无法读取的 仅 root 可读存储中。sudo 5dive secret saved ls 会列出名称，但绝不显示值； secret saved rm <name> 会删除指定项。浏览器在 5dive browser act 步骤中 通过 "saved":"<name>" 输入该值。名称只能包含小写字母、数字和连字符；值必须为单行。

**一次性密钥可以通过聊天发送：**免费套餐或测试密钥、所有者表示可丢弃的密钥， 或非机密值。不确定时，请使用链接。无论哪种方式，都绝不要回显、记录或提交密钥。

备份、移交或迁移 Agent：agent export

有人让你“打包自己”、备份、克隆或迁移 Agent？不要手动打包文件。 一个命令即可完成，分两步进行（这是一个审核流程）：

sudo 5dive agent export <name> --memory=raw --audience=self
#   -> writes a memory DRAFT and prints its dir. Nothing is packed yet.
sudo 5dive agent export <name> --memory=raw --audience=self \
     --approve-memory=<draft dir> -o <name>.tar.gz
#   -> the pack. Attach this file. Keep the two flags on step 2: the
#      SEAL hint step 1 prints leaves them out, and without them the
#      seal keeps only reference/project facts.

包含内容：CLAUDE.md、角色设定、配置（模型、工作量、插件、钩子）、 技能正文和整个记忆文件夹。出于安全考虑，不包含：会话日志（其中有私人聊天记录） 以及 Agent 自己的令牌和登录信息（新席位会在 agent import 时获取自己的信息）。 不会静默清理任何内容：看起来像密钥的内容会按文件和行号列出，移除后才能打包。

• 不带记忆标志 = 仅包含配置和角色设定。
• --with-memory 生成的是可发布包，而非备份：仅包含参考资料和项目事实， 不包含私人信息；默认的 --audience=publish 会拒绝包含主机路径、名称或 ID 的内容。
• 没有 --audience=self 时，--memory=raw 会拒绝执行。自用包属于私人内容： 绝不要发布。
• --format=agents-md 会写入一个 AGENTS.md 文件，而不是 tarball。

使用 sudo 5dive agent import <file> --as=<new name> 还原。

在重新推导前搜索团队记忆

5dive memory search "hetzner capacity gotchas" --json

只读，无需 sudo，按 BM25 排序的片段附有文件和标题出处。在重新推导过往决策或调试队友已经遇到的问题之前，先查这里。

对于大型存储，优先采用两阶段召回（DIVE-3821）——相比片段，它能让每个 token 带来更多候选结果：

5dive memory search "hetzner capacity" --index   # stage 1: slug + one-liner + score, no bodies
5dive memory get <slug> [<slug>...]              # stage 2: full bodies, only what you chose

第一阶段结果为空，说明相关内容可能不存在；索引较短则不能说明这一点。搜索时使用 FACT 会采用的词，而不是任务中的用词。关于写入路径（memory add，编译到共享 wiki）、memory router、memory check 和卫生检查，请参阅 5dive-cli-extras。

确认自己的身份，或以正确身份运行 gh

5dive whoami --json     # actor, authority (root|sudo:<who>|self) and tier — with the SOURCE of each

如果门禁拒绝或权限错误令人费解，就查这里——它会说明 CLI 实际将你识别为哪个 uid/Agent/层级，而不是你以为的身份。如果无法确认执行者身份，会以退出码 6（auth_required）退出，而不是打印 unknown，因此也可用于脚本化的可测量性检查。

如果任务涉及以 Agent 身份打开 PR 或 issue，或对其发表评论，优先使用 5dive gh <gh args...>，而不是直接调用 gh 二进制文件：写入操作（pr create、pr merge、issue comment 等）会路由到 5dive-bot 机器账号，使 GitHub 执行者字段能够明确区分 Agent 操作和人工操作（DIVE-2448）；读取和管理员级调用则会自动使用你自己的凭据。5dive gh --explain <args> 可预览路由决策，而不执行任何操作。

行为准则

1. 始终传入 --json。 解析信封。不要 grep stderr。
2. 一个名称对应一个 Agent。 名称只能包含小写字母、数字和连字符，必须以字母开头，最多 16 个字符。只有在运行 agent rm 后才能重复使用名称。
3. 不要共享机器人令牌。 同一机器人上的两个 Telegram 频道 Agent 会在 getUpdates 上相互争抢。每个 Agent 都需要自己的机器人。
4. 关闭你启动的服务。 泄漏的 worker-N Agent 会在重启后继续运行——它是一个真实的 systemd 单元，不是线程。任务完成后，调用 5dive agent rm <name>。
5. 不要直接调用底层 CLI 二进制文件。 绕过 5dive 会跳过 systemd 单元、审计日志和环境变量注入——Agent 将因身份验证失效而运行，并且没有重启循环。
6. 如果某个标志被判定为未知，请阅读 5dive --help。 主机上的二进制文件可能比此技能中的版本更新或更旧。帮助输出具有权威性。
7. 需要人工处理时，用门禁阻止任务。 使用 task need 并附上建议，不要猜测，也不要让任务悄无声息地搁置。
8. 委派聊天请求时，不要转述——通过 agent send --reply-to-chat=<id> --reply-to-msg=<id> 移交上下文。

参考

• references/commands.md — 每个子命令和标志，可直接复制粘贴。 还包括上文未重述、使用频率较低的顶层动词：5dive deploy （委派生产部署，INST-5）、5dive bug（向 5dive 提交诊断报告，仅在所有者同意后发送）、 constitution（机器强制执行的防护措施入口）、5dive acp （通过标准输入/输出使用 ACP，让 Buzz/Zed 之类的客户端可以选择 5dive 作为 编码 Agent 运行时——由客户端启动，而非直接运行，DIVE-3017）、 liveness（检查席位针对其自行写入的制品是否存活，DIVE-3778）、 plugin（安装/启用/回滚插件和市场）、human （可以放行关卡的人员，DIVE-3342）、run（一个 Agent 对一个任务进行的一次尝试—— 是 trace 的下一级单位）、trigger（经签名的外部事件转化为普通任务）以及 host（在 CLI-root 授权下修复加固的 unit/journal/cron，以及 host timezone）。 标准席位无需 root 权限即可使用的动词——5dive route（通过端口发布应用）、 5dive pkg install（安装 apt 软件包，仅限安装）、5dive tool（工具密钥）、 5dive hire-link（为你的人类提供一键聘用链接，或使用 --create 创建目录中没有合适人选时所需的自定义 Agent）以及在合作伙伴主机上使用的 5dive partner hire——还有 5dive machine add|rm|ls（添加任何 Agent 都可通过 ssh <name> 访问的机器，DIVE-5622； add --note="<what it is for>" 会将备注写入每个 Claude 席位的 CLAUDE.md 对应行，DIVE-6143）， 以及所有者界面 5dive telegram-app link（Mini App 登录）和 5dive disk sweep|alarm|tick（安全清理缓存
  • 磁盘空间不足警报），详见 5dive-cli-extras。
• Web UI 已从核心移出，现在是插件。 5dive plugin add 5dive-ai/5dive-ui 会安装它，之后 5dive ui 的用法与之前相同。核心中保留的是视图渲染所用的读取契约： 5dive board [--json] 会将此主机的组织/队列/关卡/流程/触发器作为 一份带版本号的 JSON 文档输出，因此使用方无需打开核心的私有 sqlite 存储（DIVE-4779）。5dive board --contract-version 完全不读取存储， 可用于与尚未有 board 的主机协商契约版本。
• references/exit-codes.md — 退出码和错误类别。
• references/paths.md — 磁盘上的状态布局（仅用于调试）。
• 5dive-cli-extras 技能 — 团队托管、账户、身份验证恢复、compose/ 团队模板、目标 DAG、目标、循环、记忆写入/维基、组织架构写入、 治理投票、摘要/用量/主管/机群/诊断、Telegram 配对详情、人物市场、自带服务提供商，以及公司向导。

深入了解

完整参考手册请访问 https://5dive.com/docs。如果此技能中的标志 与正在运行的二进制文件接受的内容冲突，请以二进制文件为准——直接运行 sudo 5dive --help 或 sudo 5dive agent <sub> --help 并遵循其说明。

已与 5dive CLI 0.102.2（提交 46c65af9，2026-10-26）同步。某个主机的 二进制文件可能比 main 最多落后一天（nightly 更新渠道）——如有差异，请以 5dive --help 为准。