hive

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Hive - agent 通信基础层

Hive - Agent Communication Base Layer

Hive CLI 是必须的外部依赖。安装方式：

bash

pipx install git+https://github.com/notdp/hive.git
npx skills add https://github.com/notdp/hive -g --all

Hive CLI is a required external dependency. Installation methods:

bash

pipx install git+https://github.com/notdp/hive.git
npx skills add https://github.com/notdp/hive -g --all

升级 CLI：

Upgrade CLI:

pipx upgrade hive

升级全局 skill（从 GitHub 安装的用户用这条）：

Upgrade global skills (for users who installed from GitHub):

npx skills update hive -g

本地 repo checkout 的刷新（skills lock 不跟踪 local source，update 用不了）：

Refresh for local repo checkout (skills lock does not track local sources, update is not available):

npx skills add "$PWD" -g --all


升级 Hive CLI 不会自动刷新已安装的 `hive` skill；当 skill 过期时，在 agent pane 里运行 `hive` 命令会收到 stderr 提醒，也可以显式运行 `hive doctor --skills` 查看详情。

运行 `hive --help` 确认安装成功。

---

你是运行在 Hive 里的 agent。Hive 是你的协作 runtime,不是某个特定 workflow。本 skill 的地图:

- **启动** — `hive init` 一条命令
- **命令速查** — 每天用的 CLI + `hive team` 字段语义
- **消息机制** — 怎么收、怎么发、thread / root 协议 / shell 安全(active-turn fork 和接管 handoff 见 `references/advanced-routing.md`)
- **协作规则** — 什么在 team 内消化,什么升给用户
- **Workflow 加载** — 在 Hive 之上叠更高层流程(如 code-review)
- **排障 + 协议边界** — 见 `references/debug.md`

npx skills add "$PWD" -g --all


Upgrading the Hive CLI will not automatically refresh the installed `hive` skill; when the skill is outdated, running the `hive` command in the agent pane will receive a stderr reminder, or you can explicitly run `hive doctor --skills` to view details.

Run `hive --help` to confirm successful installation.

---

You are an agent running in Hive. Hive is your collaborative runtime, not a specific workflow. The map of this skill:

- **Startup** — One command: `hive init`
- **Command Quick Reference** — Daily-used CLI + `hive team` field semantics
- **Messaging Mechanism** — How to receive, send, thread / root protocol / shell security (active-turn fork and handoff are covered in `references/advanced-routing.md`)
- **Collaboration Rules** — What to resolve within the team, what to escalate to users
- **Workflow Loading** — Stack higher-level processes (such as code-review) on top of Hive
- **Troubleshooting + Protocol Boundaries** — See `references/debug.md`

启动

Startup

加载 hive skill 后第一件事:跑
hive init
,然后按 CLI 输出走。

hive init

幂等,报错会告诉你缺什么 ——

hive team

等它完成之后再跑。

加载 hive skill 就代表你要进入 peer group(和

/gang

的 gang group 并列的基础协作模式;2 个 agent 互相 verify / review / confirm)。

hive init

会自动给你配一个 idle 异族(model-family 不同)的 peer pane —— 优先在同 tmux session 里找现成的,找不到就在当前 window 现场 spawn 一个。两边 pane 都会打上

@hive-group=peer

,在

hive team

里直接可见。

First thing after loading the hive skill: run
hive init
, then follow the CLI output.

hive init

is idempotent; errors will tell you what's missing — run

hive team

only after it completes.

Loading the hive skill means you are entering a peer group (a basic collaboration mode parallel to the

/gang

gang group; two agents verify / review / confirm each other).

hive init

will automatically configure an idle alien (different model-family) peer pane for you — it will first look for an existing one in the same tmux session, and if not found, spawn one on the spot in the current window. Both panes will be tagged with

@hive-group=peer

, which is directly visible in

hive team

命令速查

Command Quick Reference

bash

hive team                            # 成员 + runtime(inputState/busy/turnPhase) + peer + group;`self` 是字符串,指你自己的 member name
hive send dodo "see attachment" --artifact /tmp/file.md   # 已有现成文件时
hive send dodo "see attachment" --artifact - <<'EOF'

bash

hive team                            # Members + runtime(inputState/busy/turnPhase) + peer + group; `self` is a string referring to your own member name
hive send dodo "see attachment" --artifact /tmp/file.md   # When the file already exists
hive send dodo "see attachment" --artifact - <<'EOF'

Findings

item EOF hive reply dodo "ack, looking" # 回复 dodo 最近一条给你的消息(自动 reply-to) hive answer claude "yes" # 回答 agent 的 pending question hive notify "按 Space 和我对话" # 桌面弹通知给当前 pane 的用户

item EOF hive reply dodo "ack, looking" # Reply to dodo's latest message sent to you (auto reply-to) hive answer claude "yes" # Answer an agent's pending question hive notify "Press Space to talk to me" # Send a desktop notification to the user of the current pane

notify 只在你被阻塞、必须用户介入时用;文案结构:发生什么 / 为什么现在需要你 / 按 Space 回来后要做什么

Use notify only when you are blocked and require user intervention; copy structure: what happened / why you are needed now / what to do after pressing Space to return

undefined

undefined

hive team

返回什么

What does

hive team

return?

去

members

里按

self

找自己那行,看完整状态。字段含义:

self
— 字符串 = 你自己的 member name(board/terminal pane 不会有
```
model
```
/
```
sessionId
```
/
```
turnPhase
```
等 runtime 字段,也不会伪造)
group
— 在 member 行上,只有 pane 打了
```
@hive-group
```
标签时才出现(例:peer group 成员
```
group: peer
```
)
inputState=waiting_user
— 对方在等答案,用
```
hive answer
```
回答
busy=true/false
— tmux 输出层的秒级活动布尔,不等于语义上的 busy/idle
turnPhase
— 才是"现在插 new root 是否容易打断对方"的 transcript/JCL 语义层

Find your own entry in

members

self

and check the full status. Field meanings:

self
— String = your own member name (board/terminal panes do not have runtime fields like
```
model
```
/
```
sessionId
```
/
```
turnPhase
```
, nor will they forge them)
group
— Appears on the member line only when the pane is tagged with
```
@hive-group
```
(example: peer group member
```
group: peer
```
)
inputState=waiting_user
— The other party is waiting for an answer; use
```
hive answer
```
to respond
busy=true/false
— A second-level activity boolean at the tmux output layer, not equivalent to semantic busy/idle
turnPhase
— This is the transcript/JCL semantic layer indicating "whether it's easy to interrupt the other party by inserting a new root now"

消息机制

Messaging Mechanism

收消息

Receiving Messages

其他 agent 的消息以

<HIVE from=... to=... msgId=... artifact=<path>>body</HIVE>

block 出现在你 pane 里 —— 这就是主通道。block 本身就带齐你要的所有东西:

短 body(sender 的摘要)在标签之间
详细内容在
```
artifact=<path>
```
指的文件里,用 Read tool 打开那条 path 就是全文

原文永远在
<HIVE>
block 里读。

hive thread <msgId>

和

hive delivery <msgId>

是排障入口(见

references/debug.md

),agent 日常收信用不上。

Messages from other agents appear in your pane as

<HIVE from=... to=... msgId=... artifact=<path>>body</HIVE>

blocks — this is the main channel. The block itself contains everything you need:

The short body (sender's summary) is between the tags
Detailed content is in the file pointed to by
```
artifact=<path>
```
; use the Read tool to open that path for the full text

Always read the original text in the
<HIVE>
block.

hive thread <msgId>

and

hive delivery <msgId>

are troubleshooting entry points (see

references/debug.md

) and are not used by agents for daily message reception.

send vs reply(thread 模型)

send vs reply (thread model)

Hive 的消息组织成 thread。每次发消息前问自己:这是新话题,还是对已有 thread 的延续?

新话题 →
hive send
(新任务 / 新汇报 / 新提问 / 新发现,开新 thread)
对 inbound 的直接回应 →
hive reply
(对方问的答、对方让你做的 ack,续 thread)

判断点是"内容是不是对那条 inbound 的回应",而不是"手头有没有 inbound"。典型陷阱:

dodo 刚给你发"已就位"(inbound 在 inbox)
你现在想派 dodo 新任务"review PR #123"
- 错:
```
hive reply dodo "review PR #123"
```
  → autoReply 挂到"已就位"上,thread 污染
- 对:
```
hive send dodo "review PR #123"
```
  → 新任务开新 thread

Hive's messages are organized into threads. Before sending a message, ask yourself: Is this a new topic, or a continuation of an existing thread?

New topic →
hive send
(new task / new report / new question / new discovery, start a new thread)
Direct response to inbound →
hive reply
(answer to the other party's question, ack for what the other party asked you to do, continue the thread)

The judgment point is "whether the content is a response to that inbound message", not "whether you have an inbound message on hand". Typical pitfalls:

dodo just sent you "Ready" (inbound in inbox)
You now want to assign dodo a new task "review PR #123"
- Wrong:
```
hive reply dodo "review PR #123"
```
  → autoReply is attached to "Ready", polluting the thread
- Correct:
```
hive send dodo "review PR #123"
```
  → start a new thread for the new task

hive send

hive send

开新 thread 的唯一入口,不接受

--reply-to

。body 是短摘要,装不下时用

--artifact

(见下文 root 协议)。即使对方刚给你发过 inbound,只要你现在要说的是新话题,也用

send

。

The only entry point for starting a new thread; does not accept

--reply-to

. The body is a short summary; use

--artifact

when it can't fit (see root protocol below). Even if the other party just sent you an inbound message, use

send

if what you want to say is a new topic.

hive reply

hive reply

续 thread。没传

--reply-to

时 Hive 会挑"最近一条来自该 agent 且你还没回过的入站消息"作 anchor。autoReply 只省找 msgId 的步骤,不判断内容是否真的延续 —— 开新话题还是用

send

。

显式传

--reply-to <msgId>

的场景:

handoff / spawn 时 prompt 直接给了你 anchor msgId(你手头并没有那条 inbound)
你想跨越 autoReply 默认挑的那条,回一条更早的 thread

Hive 把 reply 严格锁在同 thread 内;没有可推断的入站消息且你也没传

--reply-to

时会直接报错。

Continue a thread. If

--reply-to

is not passed, Hive will select "the latest inbound message from that agent that you haven't replied to yet" as the anchor. autoReply only saves the step of finding the msgId, but does not judge whether the content actually continues — still use

send

for new topics.

Scenarios for explicitly passing

--reply-to <msgId>

When prompted during handoff / spawn, you are directly given the anchor msgId (you don't have that inbound message on hand)
You want to bypass the default autoReply selection and reply to an earlier thread

Hive strictly locks replies within the same thread; it will directly report an error if there is no inferable inbound message and you haven't passed

--reply-to

root 协议(send body 约束)

Root Protocol (send body constraints)

root send(没有
```
--reply-to
```
)的
```
body
```
永远是短摘要;详细内容放
```
--artifact
```
```
--artifact
```
不是强制的 —— "ack"、"已就位"、"task done" 这类单行确认可以裸发 root send。信息一多就必须开 artifact
```
body
```
命中下面任一条件会直接 reject,要移进 artifact:
- 超过
```
500
```
  字符
- 一共有
```
3
```
  行或更多
- 含 fenced code:
```
```
```
- 任一非空行以
```
#
```
  、
```
-
```
  、
```
*
```
  开头

首选 heredoc + stdin artifact:

bash

hive send <name> "<message>" --artifact - <<'EOF'
# Findings
- item
EOF

带引号的
```
EOF
```
标签不做 shell 插值,markdown / 代码块 / 引号内容原样传过去

printf '%s\n' ... | hive send ... --artifact -

只当备选,转义坑更多

多行 markdown / 代码走 heredoc +
```
--artifact -
```
;
```
$(cat <<EOF ...)
```
这种命令替换的 shell 转义坑更深,heredoc 是唯一安全路径
```
reply
```
不受这套 root 协议约束,可以只回一句短文本
target 正在 active turn 时,root send 会自动 fork 一个 clone 接管(
```
routingMode=fork_handoff, routingReason=active_turn_fork
```
);不再有
```
deferred
```
状态。详见下文「busy-fork 路由」

The
```
body
```
of a root send (without
```
--reply-to
```
) is always a short summary; detailed content is placed in
```
--artifact
```
```
--artifact
```
is not mandatory — single-line confirmations like "ack", "Ready", "task done" can be sent as root sends without artifact. Use artifact when there is more information
The
```
body
```
will be directly rejected if it meets any of the following conditions, and must be moved to artifact:
- Exceeds
```
500
```
  characters
- Has
```
3
```
  or more lines in total
- Contains fenced code:
```
```
```
- Any non-empty line starts with
```
#
```
  ,
```
-
```
  , or
```
*
```

Preferred method: heredoc + stdin artifact:

bash

hive send <name> "<message>" --artifact - <<'EOF'
# Findings
- item
EOF

Quoted
```
EOF
```
tags do not perform shell interpolation; markdown / code blocks / quoted content are passed as-is
```
printf '%s\n' ... | hive send ... --artifact -
```
is only an alternative, with more escaping pitfalls
Multi-line markdown / code should use heredoc +
```
--artifact -
```
; command substitution like
```
$(cat <<EOF ...)
```
has deeper shell escaping pitfalls, heredoc is the only safe path
```
reply
```
is not subject to this root protocol; you can just reply with a short text
When the target is in active turn, root send will automatically fork a clone to take over (
```
routingMode=fork_handoff, routingReason=active_turn_fork
```
); there is no longer a
```
deferred
```
state. See "busy-fork routing" below for details.

busy-fork 路由(摘要)

Busy-Fork Routing (Summary)

陌生 sender 向 target 发 root send 时,若 target 正在 active turn,消息会自动 fork 到一个 clone pane(

<target>-c1

)接管 —— 这不是 bug,是预期的保护机制。peer 对 和 owner 父子(双向)是 bypass 豁免关系,可直达原 target。

完整 3 条 bypass 判定 + clone pane 行为 + board pane 的文件通道例外 →

references/advanced-routing.md

。

When an unfamiliar sender sends a root send to a target that is in active turn, the message will be automatically forked to a clone pane (

<target>-c1

) to take over — this is not a bug, but an expected protection mechanism. Peer pairs and owner-parent/child (bidirectional) are bypass-exempt and can directly reach the original target.

Complete 3 bypass criteria + clone pane behavior + board pane file channel exceptions →

references/advanced-routing.md

shell 安全

Shell Security

hive send

和

hive reply

的 body 里反引号(```````)会被 zsh/bash 当 command substitution 先执行,消息被悄悄改坏。含 markdown inline code 时走 heredoc +

--artifact -

,或 body 整句改用单引号包裹。

Backticks(```````) in the body of

hive send

and

hive reply

will be executed as command substitution by zsh/bash first, silently corrupting the message. When including markdown inline code, use heredoc +

--artifact -

, or wrap the entire body in single quotes.

接管已有 thread 时的第一条 reply

First Reply When Taking Over an Existing Thread

被 spawn / handoff 到一条不是你自己的 thread 时,接管者要显式
--reply-to <msgId>
;详见

references/advanced-routing.md

。

When spawned / handed off to a thread that is not your own, the taker must explicitly use
--reply-to <msgId>
; see

references/advanced-routing.md

for details.

协作规则

Collaboration Rules

team 内先,user 后

Team First, User Second

协作顺序是固定的:先在 team 内把问题消化完,再对用户汇报。每次想转向用户前,先跑

hive team

看有没有合适的 peer 可以接。

和 peer 讨论时,目标是在 team 内把结论收敛。对用户只给三样:

已收敛的结论
仍未收敛且真正阻断推进的单个问题
你建议的下一步动作

仍在摇摆的 A/B/C、peer 的中间态分歧、你准备回去继续 challenge 的漏洞 —— 都留在 team 内消化完再出。peer 的论证有洞,先回 peer 挑明并收敛,由你自己处理完再对用户汇报(用户明确说要看原始讨论过程的除外)。

以下 4 种情况才升级给用户:

```
hive team
```
看过一遍,没有合适 agent 能接
决策涉及不可逆外部副作用(
```
git push
```
、发 PR comment、删除数据、跑迁移、通知外部系统)
需要用户提供 team 内 agent 都不掌握的信息、授权或偏好
用户明确要求参与这类决策

升级的话术固定是:"已先检查 hive team;这一步仍需你决定,因为 ..." —— 直接给结论和问题。"找谁接手" 是你的判断,不是用户的决策。

The collaboration order is fixed: Resolve the problem within the team first, then report to the user. Before turning to the user, run

hive team

first to see if there is a suitable peer to take over.

When discussing with peers, the goal is to converge the conclusion within the team. Only provide three things to the user:

Converged conclusion
A single blocking issue that has not been converged and truly hinders progress
Your suggested next steps

Oscillating A/B/C options, intermediate disagreements among peers, vulnerabilities you plan to go back and challenge further — all should be resolved within the team before presenting to users. If a peer's argument has flaws, first point it out to the peer and converge, handle it yourself before reporting to the user (unless the user explicitly requests to see the original discussion process).

Only escalate to the user in the following 4 cases:

Checked
```
hive team
```
and no suitable agent can take over
The decision involves irreversible external side effects (
```
git push
```
, sending PR comments, deleting data, running migrations, notifying external systems)
Need the user to provide information, authorization, or preferences that all agents in the team do not have
The user explicitly requests to participate in such decisions

The escalation wording is fixed: "Have checked hive team first; this step still requires your decision because ..." — directly provide the conclusion and problem. "Who to assign to take over" is your judgment, not the user's decision.

采纳谁的方案,谁去实施

Whoever Proposes the Solution Implements It

和 peer 收敛后,最终采纳的方案由提出者实施,另一方 review。

After converging with peers, the final adopted solution is implemented by the proposer, and reviewed by the other party.

默认分工

Default Division of Labor

Claude 偏前端体验、文案收敛和发散式讨论;GPT 偏后端 correctness、约束检查和严谨 review。若项目已有更明确的人选或团队经验,以项目事实为准。

Claude focuses on front-end experience, copy convergence, and divergent discussions; GPT focuses on backend correctness, constraint checking, and rigorous review. If the project has more clear candidates or team experience, follow the project facts.

Workflow 加载

Workflow Loading

更高层流程(如

code-review

)在 Hive 之上加载:

orchestrator 执行
```
hive workflow load <agent> code-review
```

或 spawn 时用

hive spawn <agent> --workflow code-review

workflow 加载后继续用 Hive 命令作为通信与状态底座。

Higher-level processes (such as

code-review

) are loaded on top of Hive:

Orchestrator executes
```
hive workflow load <agent> code-review
```

Or use

hive spawn <agent> --workflow code-review

during spawn

After loading the workflow, continue using Hive commands as the base for communication and status.

排障 + 协议边界

Troubleshooting + Protocol Boundaries

排障命令清单(

hive doctor

delivery

thread

capture

inject

interrupt

kill

exec

)+ 协议硬约束(发送入口、

hive answer

前提、非严格可靠队列语义、

gh

hive

kernel 分工)→

references/debug.md

。日常收发消息不用读这份;主通道见上文「消息机制」。

Troubleshooting command list (

hive doctor

delivery

thread

capture

inject

interrupt

kill

exec

) + protocol hard constraints (sending entry points, prerequisites for

hive answer

, non-strict reliable queue semantics, division of labor between

gh

and

hive

kernels) →

references/debug.md

. No need to read this for daily message sending and receiving; see the "Messaging Mechanism" section above for the main channel.