fleet

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Fleet

Fleet

A fleet is a folder that Syncthing keeps in step across machines. Agents coordinate through it with plain files: each agent keeps a card in
agents/
, receives messages in
inbox/<name>/
, and shares anything long as a file in
context/
. The folder is the whole system.
Fleets live side by side under one synced root, one subfolder per project or topic (
<root>/<topic>
). The root is
$FLEET_ROOT
if set, otherwise
~/fleet
. The root itself is not a fleet; it only holds the fleets and the Syncthing files.
fleet.mjs
(Node ≥ 18, no dependencies) does the file work.
init
copies it and
PROTOCOL.md
into the fleet folder, and the copy finds the fleet from its own location: run
node <fleet>/fleet.mjs <command>
(
help
lists every command and option).
Fleet 是由 Syncthing 在多台机器之间保持同步的文件夹。Agent 通过普通文件进行协调:每个 Agent 在
agents/
中保留一张卡片,在
inbox/<name>/
中接收消息,并将所有较长内容作为文件共享到
context/
中。整个系统就是这个文件夹。
多个 Fleet 并列存放在同一个同步 root 下,每个项目或主题对应一个子文件夹(
<root>/<topic>
)。如果设置了
$FLEET_ROOT
,则使用该路径作为 root,否则使用
~/fleet
。root 本身不是 Fleet;它只用于存放各个 Fleet 和 Syncthing 文件。
fleet.mjs
(Node ≥ 18,无依赖)负责所有文件操作。
init
会将它和
PROTOCOL.md
复制到 Fleet 文件夹中,复制后的脚本会根据自身所在位置找到 Fleet:运行
node <fleet>/fleet.mjs <command>
(
help
会列出所有命令和选项)。

Join

加入

  1. Locate the fleet. The user gives a full path or a topic name (
    <root>/<topic>
    ). If you can't tell which topic they mean, list the root's subfolders and ask. A new topic gets a lowercase, hyphenated name. If
    <fleet>/PROTOCOL.md
    doesn't exist, create the fleet:
    node <this-skill-dir>/fleet.mjs init <fleet>
    (safe to repeat, safe when two agents race). If the fleet still has a
    spawn.mjs
    , or
    node <fleet>/fleet.mjs help
    has no
    brief
    command, its scripts predate this skill: run the same
    init
    to refresh them (it removes
    spawn.mjs
    ). Cards, inboxes and context are left alone.
  2. Read
    <fleet>/PROTOCOL.md
    in full.
    It has the layout, the one-writer-per-file rule, the message and handoff formats, and the gotchas. Every agent in the fleet works from it, including agents without this skill, so it is the authority when this file and it differ.
  3. Join under a name: the one the user gives, otherwise role + machine (
    orch
    ,
    api-laptop
    ).
    node <fleet>/fleet.mjs join --as <name> --role "<one line>" --tool <claude-code|codex|...>
    . Tell the user the name you took. Done when
    who
    lists you.
If you created the fleet, you are its orchestrator. Join as
orch
unless the user names you otherwise, add
--orchestrator
(a fleet has one;
join
refuses a second), and read references/orchestrating.md before you plan any work. It covers splitting work, starting sessions with T3 Code's own thread tools (the fleet is only the communication protocol), waking idle workers, and switching a session between Claude and Codex without losing its context, and working with another project's orchestrator through a shared bridge fleet (it has no orchestrator: join it as a peer). Workers don't need it.
  1. 定位 Fleet。 用户会提供完整路径或主题名称(
    <root>/<topic>
    )。如果无法确定用户指的是哪个主题,则列出 root 下的子文件夹并询问用户。新主题使用小写、连字符分隔的名称。如果
    <fleet>/PROTOCOL.md
    不存在,则创建 Fleet:
    node <this-skill-dir>/fleet.mjs init <fleet>
    (可以重复执行,也适用于两个 Agent 同时执行的情况)。如果 Fleet 中仍然存在
    spawn.mjs
    ,或者
    node <fleet>/fleet.mjs help
    中没有
    brief
    命令,说明其脚本早于当前 skill:运行相同的
    init
    来刷新脚本(这会移除
    spawn.mjs
    )。卡片、收件箱和上下文不会受到影响。
  2. 完整阅读
    <fleet>/PROTOCOL.md
    。
    其中包含目录结构、单文件单写入者规则、消息和移交格式以及注意事项。Fleet 中的每个 Agent 都以该文件为准,包括没有安装此 skill 的 Agent。因此,如果本说明与该文件不一致,应以
    PROTOCOL.md
    为准。
  3. 使用名称加入: 使用用户指定的名称,否则使用角色与机器名组合,例如
    orch
    或
    api-laptop
    。运行
    node <fleet>/fleet.mjs join --as <name> --role "<one line>" --tool <claude-code|codex|...>
    。告知用户你使用的名称。当
    who
    命令列出你时,即完成加入。
如果你创建了 Fleet,你就是它的 orchestrator。 除非用户另有指定,否则使用
orch
名称加入,并添加
--orchestrator
(每个 Fleet 只有一个 orchestrator;
join
会拒绝第二个)。在规划任何工作之前,请阅读 references/orchestrating.md。其中介绍了拆分工作、使用 T3 Code 自带的线程工具启动会话(Fleet 只是通信协议)、唤醒空闲 worker、在不丢失上下文的情况下在 Claude 和 Codex 之间切换会话,以及通过共享的 bridge Fleet 与另一个项目的 orchestrator 协作(bridge Fleet 没有 orchestrator,应作为 peer 加入)。worker 不需要阅读该文档。

Every turn once joined

加入后的每个回合

  • Read your inbox first, before the user's request:
    inbox --as <name>
    . It's the only way messages reach you.
  • Handle each message, then mark it
    done
    .
    Answer asks with
    send --reply-to <id>
    , so the sender can match answers to asks.
  • Keep your card true:
    status --as <name> busy --task "…"
    while working;
    idle
    when done,
    blocked
    when waiting on someone,
    offline
    when the user ends the session. Other agents plan around your card, so a stale
    busy
    stalls them.
  • Long material goes in a file. Write
    context/<name>--<topic>.md
    , then send a short message naming it. On PowerShell, pass a body with quotes or line breaks via
    --body-file <temp file outside the fleet>
    (PowerShell 5.1 mangles embedded quotes).
  • Never start sessions yourself unless you are the orchestrator. Need another worker? Ask it.
  • 先读取收件箱,且要在处理用户请求之前执行:
    inbox --as <name>
    。这是消息到达你的唯一方式。
  • 处理完每条消息后将其标记为
    done
    。
    使用
    send --reply-to <id>
    回答 ask,以便发送方将答案与 ask 对应起来。
  • 保持卡片状态准确: 工作时运行
    status --as <name> busy --task "…"
    ;完成后设为
    idle
    ;等待他人时设为
    blocked
    ;用户结束会话时设为
    offline
    。其他 Agent 会根据你的卡片安排工作,因此过期的
    busy
    状态会拖住它们。
  • 较长内容应写入文件。 写入
    context/<name>--<topic>.md
    ,然后发送一条提及该文件名的简短消息。在 PowerShell 上,如需通过
    --body-file <temp file outside the fleet>
    传递带引号或换行的正文,请使用此方式(PowerShell 5.1 会破坏嵌入的引号)。
  • 除非你是 orchestrator,否则绝不要自行启动会话。 需要其他 worker 时,应向其发出请求。

Waiting for messages

等待消息

A session whose turn has ended reads nothing until something wakes it.
watch --once
is the wake-up: it exits 0 as soon as your inbox holds an unread message, 2 on timeout. It fires on any unread message, so mark handled ones
done
before re-arming, or it exits immediately. One command does both:
done --as <name> <id> && watch --as <name> --once --timeout <sec>
.
Pick the form that fits your harness:
  • Harness re-invokes you when a background command exits (Claude Code background Bash): run
    watch --as <name> --once
    in the background, end your turn, run
    inbox
    when it fires. Give the background call its longest timeout (2 h = 7,200,000 ms) and
    watch --timeout
    a bit under it (
    7000
    ). If the harness kills it anyway, nothing is lost: check
    inbox
    and re-arm.
  • Harness streams a long-running command's output (Claude Code Monitor):
    watch --as <name>
    prints one line per new message.
  • Neither (Codex, or a sub-agent that must finish in one go): run
    watch --as <name> --once --timeout 540
    in the foreground while the user wants you to wait, and again after each exit 2. Between turns the orchestrator wakes you by posting into your session ("Orch: new message in your inbox (<id>)"): read your inbox then.
一个回合结束后,会话在被唤醒之前不会读取任何内容。
watch --once
用于唤醒会话:一旦收件箱中有未读消息就以状态码 0 退出,超时则以状态码 2 退出。只要出现任何未读消息,它都会触发,因此重新等待前应将已处理的消息标记为
done
,否则它会立即退出。可以使用一条命令完成这两个操作:
done --as <name> <id> && watch --as <name> --once --timeout <sec>
。
根据你的运行环境选择合适的方式:
  • 当后台命令退出时,环境会再次调用你(Claude Code 后台 Bash):在后台运行
    watch --as <name> --once
    ,结束当前回合,并在它触发时运行
    inbox
    。为后台调用设置最长超时时间(2 小时 = 7,200,000 毫秒),并将
    watch --timeout
    设置为略低于该值(
    7000
    )。即使环境仍然将其终止,也不会丢失消息:检查
    inbox
    并重新等待即可。
  • 当环境会持续输出长时间运行命令的结果时(Claude Code Monitor):
    watch --as <name>
    会为每条新消息输出一行。
  • 两者都不支持时(Codex,或必须一次性完成的 sub-agent):在用户需要等待期间,在前台运行
    watch --as <name> --once --timeout 540
    ,并在每次以状态码 2 退出后再次运行。回合之间,orchestrator 会通过向你的会话发送消息来唤醒你("Orch: new message in your inbox (<id>)"):届时读取收件箱即可。

Long-lived processes

长时间运行的进程

A server or training run you start is a child of T3 Code, and a T3 Code restart or reboot kills it. Run anything that must outlive the session detached (an OS service, or on Windows a logon scheduled task), and note how to restart it in a context file. For long jobs, keep a short
STATUS
note there too, so a restarted session can resume.
你启动的服务器或训练任务都是 T3 Code 的子进程,重启 T3 Code 或机器都会将其终止。对于必须比当前会话存续更久的任务,应使其脱离会话独立运行(使用操作系统服务,或在 Windows 上使用登录计划任务),并在 context 文件中记录重新启动方式。对于长时间运行的任务,还应在其中保留一份简短的
STATUS
说明,以便重启后的会话继续执行。