本文件是 fleet 的设计与边界说明;协议语义以仓库根
SEALING_CN.md为准, 策略推导不变量以src/sync/POLICY-INVARIANTS.md为准。 fleet 不改 core 语义,只消费@mebular/core的公共 API。发布版本:Fleet 任务编排随 Mebular 0.3.2 发布。当前实现基线为
feat/fleet-orchestration@b4ef1e8: executor/adapters、DSH/OpenCode/Claude Code adapter、plan owner guard、agent readiness 与 executable routing 已落地; 0.3.2 证据见docs/quality/0.3.2-fleet-orchestration.md。 P0–P7 的 0.3.0 周期证据保留原名与历史结论,不因版本标签改写 (见docs/quality/0.3.0-fleet-orchestration-e2e.md)。
把「任务」当作一类记忆:发起端把任务写进共享分区(如 tasks),目标设备上的 Agent 拾取、执行、写回状态;跨设备靠已有的记忆同步(写入即推 + anti-entropy + 变更订阅)传递,无中心协调。
- 不在 core 引入任务/调度/agent 语义;fleet 只
import { ... } from '@mebular/core',不得深路径src/**。反向依赖由tests/fleet/boundary.test.ts强制。 - 墙钟不进一致性判定:
expiresAt只是本机任务板的软约定(展示/排队提示),跨端权威生命周期只由显式状态事件驱动。 - 禁中心化:无注册服务、无全局账本;配额 = 每设备对自己发出的量本地记账(本地拒绝/排队)。
- 不改
SEALING_CN.md的协议语义(R-a..R-d / 水位 / 一致性口径 / 线格式)。若要动 → 停下报告。
- 分区:任务记录落在共享
namespace(默认tasks),复用 core 的图上记忆与选择性同步(订阅供给)。 - 显式状态机:
queued → claimed → running → done | failed;状态迁移是显式事件,确定性、可收敛(状态单调秩 + 终态平局裁决;见protocol/state-machine.json)。 expiresAt软约定:仅影响本机展示与本地排队;不触发跨端状态迁移,也不参与权威判定。- 因果链:
trace.causedBy/trace.chain记录派生关系(如子任务由父任务触发)。
- 域(namespace)= 记忆数据通道:订阅 = 数据义务(收 + 及时同步本地新记忆);不含派发语义。
- 任务 = 树/DAG:root = 派发者(发起 Agent);子任务由执行者派生(
trace.causedBy/chain,禁环);任务事件存放在某个域里,域只是运输与存储。 - 派发权限三层:L1 传输(双方订阅交集)→ L2 任务树(创建者即派发者:子任务由执行者创建,预算随树递减)→ L3 执行(本地:
to.device/to.agent过滤、执行器、并发/准入)。
- 树预算:root 声明
budget {maxDepth≤8, maxChildren≤16, maxTasks≤256}(dispatch默认children-ok,可root-only);子任务预算 ≤ 父剩余(maxDepth/maxTasks每层减一)。 - 无效事件:越预算/越链长/root-only 派生 = 无效
created→ 入口拒收(传输入口 +states()权威视图剔除,纯函数collab/tree.ts,全端一致)。 - 公平准入(本地、确定性、无墙钟):收件按
(from.device, 逻辑序)轮转;有其它待处理发送方时单一发送方份额 ≤50%;(来源设备,目标 Agent)配额;每 Agent 并发默认 2;超额本地排队/拒绝——本地记账、无全局账本。 - 确定性摊派:等价目标间
hash(taskId) mod N(deterministicTarget;无偏好/热点)。
- 目录(普通记忆域,默认
agents):每设备一条签名记录{device, agents:[{name,kind,capabilities?,executable?,executionMode?,concurrency,capacity?}], updatedAt, version};task_targets = 订阅任务域的对端 ∩ 其目录 (device,agent);capacity/load为建议性,不参与授权/一致性。远端 Agent 口径:adapter 在执行设备本地;目录只发布执行能力投影kind + capabilities + executable(boolean) + executionMode(cli|http|json-rpc|in-process;concurrency/capacity仅作建议性负载提示),command/env/token 永不过网。health不是目录字段;能力卡可携带可选{status,checkedAt?,latencyMs?,detail?},task_targets会合并进目标,属 advisory。 - 能力卡(P1)(同
agents域,internal 记忆节点):metadata.internal=true+internalObject.kind="agent_capability_card";由 config 的 optionalcapabilities、ExecutorRegistry、运行环境编译,设备签名、版本单调、agent 移除发 tombstone。卡片只含标签/限制/工具名,不含 command/env/凭据/原始对话。默认记忆列表、域计数、搜索、图遍历与 fleet SSE 都不返回能力卡;task_targets只额外返回cards摘要,旧targets字段与顺序不变。 - CR-002(P1,已批准 / P6 硬化 / P7 CR-003)daemon 发布:生产
store:"daemon"下 fleet 无本地 Mebular 句柄。CR-003 批准的内部 app 端点白名单为/app/nodes(optional metadata,拒绝 card/role/plan 通用写入)、/app/capability-cards、/app/plans、/app/role-cards、/app/peers;默认 loopback;非 loopback 仅 TLS+bearer/scope 且需显式部署;internal metadata,不新增公共 MCP/UI/TaskEvent。最小内部 app 扩展:POST /app/nodes接受 optionalmetadata,GET /app/nodes返回 optionalmetadata;新增内部POST /app/capability-cards(draft 无 signature),由守护身份app.identity.getDeviceKey(deviceId)签名并写agents域 internal 节点,身份不可用返回 409,不伪造。签名/canonical/schema 仍只复用 fleetcards.ts;fleet 侧用DaemonAgentBackend走既有 app 面。读取信任:node.createdBy === card.device+ 签名验证(本机 identity / 远端已认证公钥)。P6 新增内部GET /app/peers:只返回 sync 握手登记的在线 peer{device, publicKeyHex}(默认 loopback,memory.read;非 loopback 仅 TLS+bearer;不回退config.peers地址簿);DaemonAgentBackend用它验证远端卡片,旧守护无该端点或 peer 离线时远端候选 fail-closed。/app/nodes是 raw debug 面,拒绝 card/role/plan 内部对象写入;能力卡只能走专用端点。旧 daemon 配置启动期幂等补齐agents同步域。embedded 路径仍用本地 Mebular。公开 MCP 方法、人类 UI、TaskEvent线格式均不变。 - 角色卡(P5):
agent_role_cardinternal 节点(agents域,metadata.internal=true+internalObject.kind="agent_role_card";(device, agent, kind)版本单调、tombstone、最新版本/author 绑定解析)。本机 runtime job 从任务历史聚合 intent/成败/样本量/最近性,可选只读 memory runtime internal compact/checkpoint 摘要(RoleSummaryProvider,只取 ID/意图,不复制原文);confidence 由样本量/成功率/一致性/最近性计算,<0.5低置信度。隐私硬化:strengths/preferredIntents/avoid只允许固定安全标签白名单(如 code/test/docs/review),未知 intent/短 token/原文一律忽略;写路径(生成器、appendAgentRoleCard、daemon/app/role-cards)统一由服务端从agent + sampleSize + preferredIntents重建summary,客户端 raw summary 一律丢弃;P6 读路径(embedded、daemon、远端旧卡)同样重建 summary,agent与provenance.source/generator只接受安全 token。evidenceRefs只允许task/summary/checkpoint/session_summary/compact,task 只接受真实 fleet/plan ID(含~cN派生子任务),summary/checkpoint 只接受内容哈希/ULID/UUID,schema 与 daemon 端点同时拒绝任意文本。graphRoleSummaryProvider要求摘要带 device/agent 并按目标过滤。默认shadow=true:派发行为与无卡一致(why.roleCard="shadow-ignored")。只有配置显式roleCards.enabled=true、shadow=false且confidence>=0.5时才作为 P3 软排序最后一项(why.roleCard="used-soft"),永不参与授权/硬过滤/容量。daemon 模式新增内部/app/role-cardsPOST/GET(loopback + memory.write/read,author=本机,拒绝/app/nodes伪造/读取角色卡原文),不新增公共 MCP 方法或人类 UI;无原始对话/command/env/凭据落盘。 - 工具面(MCP 与 CLI 能力完全一致):任务工具经统一 MCP 入口暴露(
mebular mcp/ HTTP/mcp,与记忆面同一入口;fleet mcp已删除)+ 等价子命令fleet task_*/mebular task_*;对照见下表。
| MCP 工具 | CLI 子命令 |
|---|---|
task_submit |
fleet task_submit |
task_submit_batch |
fleet task_submit_batch |
task_cancel |
fleet task_cancel |
task_retry |
fleet task_retry |
task_status |
fleet task_status |
task_list |
fleet task_list |
task_history |
fleet task_history |
task_children |
fleet task_children |
task_summarize |
fleet task_summarize |
task_subscribe |
fleet task_subscribe |
task_negotiate |
fleet task_negotiate |
chatter_send |
fleet chatter_send |
chatter_inbox |
fleet chatter_inbox |
task_quota |
fleet task_quota |
task_targets |
fleet task_targets |
board_create |
fleet board_create |
CLI 通用形参:--input '<json>'(字段与 MCP arguments 一致)+ --dir/--namespace/--agent;输出为同一结构化 JSON。
先区分两个角色:
- 派发方(dispatcher):提交/查询/取消任务、持有 plan、看
task_status的调用方。任何能连上 MCP/CLI 的 Console 客户端或 Agent 都可以是派发方;派发方不等于能执行本机任务。 - 执行方(executor):执行设备上真正把
intent跑出结果的 Agent/适配器。适配器只装在执行设备本地;远端目录只发布kind + capabilities + executable(boolean) + executionMode,不发布 command/env/token。
| Agent / 宿主 | 执行能力 | 接入方式与现状 |
|---|---|---|
| Hermes | 已实现 | 内置 HermesAgent(kind=hermes):hermes [-p P] [-t T] [-m M] [--in DIR] -z <prompt> --usage-file <tmp>;health() 探测 --version |
| OpenChamber | 已实现(runner 启用时) | 通过公开 runner(@mebular/opencode-plugin/fleet-runner)的 POST /v1/run-once 执行(kind=openchamber + OpenChamberRunnerAgent);runner 默认关闭,需宿主显式启用并发布 <MEBULAR_HOME>/openchamber-runner.json;discovery 缺失/陈旧 → ADAPTER_UNAVAILABLE;health() 探测 /health;每次新 session |
| DSH v1 | 已实现 | DshHeadlessAgent(kind=dsh):`dsh [baseArgs] --profile headless [prompt |
| OpenCode | 已实现 | OpenCodeAgent(kind=opencode):`opencode [baseArgs] run [prompt |
| Claude Code | 已实现 | ClaudeCodeAgent(kind=claude-code):`claude [baseArgs] -p [prompt |
| Cursor | 不可执行 | 0.3.2 没有 cursor kind/adapter;dispatch-only。将来接入需先实机验证非交互、exit code、stdout、超时与取消 |
| Claude Desktop | 不可执行 | 只能 dispatch-only(没有本地命令执行接缝) |
echo / board |
仅 demo/测试 | echo 是确定性 fake executor;board 是任务板占位。二者不作为生产 plan owner/MR,也不代表真实执行能力 |
自动探测(fleet quickstart / fleet join):
- PATH 顺序固定:
hermes→dsh→opencode→claude(kind=claude-code);存在即声明对应 agent。 - OpenChamber 不探 PATH;仅当本机已有
<MEBULAR_HOME>/openchamber-runner.json(公开 runner 已启用并发布 discovery)时追加openchamber,否则由用户显式配置。 - 都没有时回退
echo(demo);Cursor/Claude Desktop 不在自动探测内,始终 dispatch-only。 - 探测只表示“本机声明存在该 CLI”,不代表 task E2E;
health()需要单独调用,fleet doctor不逐 agent 跑--version。
plan readiness(提交前检查,已实现):
plan.owner.device必须是提交者设备,plan.owner.agent必须是提交者 Agent;跨设备代提交不在本期 scope。planAgent(ctx.agent ?? config.defaultAgent ?? config.agents[0]?.name ?? "board")必须属于本机config.agents[].name;否则返回PLAN_POLICY+PLAN_OWNER_UNEXECUTABLE,不创建 plan/root(fail closed)。- 生产 plan 的 owner 必须是真实可执行 Agent:
isPlanOwnerExecutableAgent显式拒绝board/echo(含kind=echo)以及没有command的command;hermes/openchamber/dsh/opencode/claude-code按 kind 视为可执行。测试可用echo作确定性 fake executor,但不得据此宣称生产可执行。 - root plan 的 MR 目标固定为
plan.owner的{device,agent},dispatch="root-only"。 - 每个 ready step 仍须通过 route 硬过滤(L1 授权、policy、executable、health、能力、payload、在线、容量);无候选 →
NO_TARGET/blocked,不建 task。 fleet doctor的plan owner 就绪检查同一 readiness:有可执行 agent 为 PASS(占位 agent 会列出),只有占位/空 agents 为 WARN(不伪造真实 agent);defaultAgent指向不可执行 agent 为 FAIL。
executable / health 语义:
executable由 config 静态推导:echo/board为 false,command必须有command,其余已实现 kind 为 true。它不代表 CLI 已安装。- 目录/能力卡把
executable=false发布出去;route 见到显式 false 直接ADAPTER_UNAVAILABLE。旧目录/旧卡缺字段按“未知”兼容。 health是可选 advisory:CLI adapter 的health()用<command> --version;OpenChamber runner 用GET /health。route 只在显式health.status="unavailable"时硬拒绝;degraded/未知不拒绝。fleet doctor不做逐 agent health 探测,也不会因 health 失败自动撤销卡片;不要把它写成“目录说能跑就一定跑得起来”。
入口:task_submit.plan 提交、task_status.plan 查看进度与 why/blockedBy、fleet doctor 做设备/订阅/身份/readiness 自检。Console 不加 Fleet UI;没有新的导航、页面、设置项或任务面板。
拓扑:一台机器 = 一个节点 = 一个守护(mebular serve),守护是 记忆/身份/网络/信任的唯一持有者;fleet 与各 Agent(MCP/skill)都是本机客户端,共用守护的身份与存储,数据分域。
- 身份模式:
root(持有用户主密钥私钥,首台设备)|delegated(仅委派证书链 + 设备钥,无主私钥——T2 令牌加入的设备)。mebular status|doctor显示identityMode。 - 同机互信:设备级身份,同机 Agent 之间默认可信(不做加密隔离);跨机仍走"链到主密钥"的证书链 + 订阅供给。
- 存储模式(fleet):
daemon(默认于统一上车;fleet 只走守护本机 app 接口,不监听 libp2p、不托管 join)|embedded(仅测试/CI,本地 Mebular)。 - 本机 app 接口(loopback HTTP + bearer,非回环 fail-closed):
createNode/listNodes/namespaces+policy/{subscription,subscriptions,namespace}+join/invite+peers(P6:已认证在线 peer 公钥,供 daemon 验证远端能力卡);单写者(守护持 store 锁,第二写者MCP_STORAGE_LOCKED)。 - 统一 home:
~/.mebular(MEBULAR_HOME覆盖)——守护config.json与 fleetfleet.config.json同目录。 - join 归守护:invite/join/委派签发由守护提供;fleet 仅作客户端。embedded 模式保留 fleet 自托管 join(
packages/fleet/src/jointoken.ts+fleet node --join-serve),仅测试/CI(test-only),生产不用。
- 审查 DAG:任务派生为有向无环图(计划 → 分派 → 审查 → 汇总);
trace.chain表达父子,避免环。 - 有限协商:任务可回写「需要澄清/反提案」,但步数有上限(有限协商),超限转
failed并附原因。 - 配额制闲聊:Agent 间低频信息交换,受每设备本地配额约束(超额本地拒绝/排队),不对全网协调。
- 每个设备维护
egress(x)计数(对自己发出的任务/消息计数),超额本地拒绝或排队。 - 无全局账本、无跨端对账;不同设备的配额互不影响(可接受的不一致,换取去中心化)。
状态:M0–M4 已交付;三种协作形态已接 live 通道(1d);verify:fleet:local/remote/agents/collab 与 verify:wan:l2 均入 CI。双机操作见 RUNBOOK.md。
- M0(本阶段):骨架 + 边界测试 + CI 接线 + 设计/协议夹具先行。
- M1:协议与模型(envelope / 状态机 / 配额语义)+
PROTOCOL-INVARIANTS.md矩阵 + 随机化 harness(含 oracle-free 扰动检查)。 - M2:单机双进程最小可用(A 派活 → B 执行 → 结果回传)+
scripts/verify-fleet-local.mjs。 - M3:真跨设备(真实 libp2p 传输,loopback 先验证)+ 订阅负例 + 时延统计 + 双机 runbook。
- M4(已交付):三种协作形态扩展 + 真实执行器适配(Hermes / OpenChamber)。0.3.2 追加 DSH headless / OpenCode / Claude Code adapter;Cursor/Claude Desktop 仍 dispatch-only。完整矩阵与真实 smoke 边界见 §2.5.3。
语言无关的 JSON 夹具放在 packages/fleet/protocol/:先固定线格式与状态迁移表,再由 TS 实现与测试去匹配,
避免「实现先行」导致线格式漂移。M0 起:envelope.example.json、state-machine.json 及其往返/一致性测试。
- fleet 产线格式(envelope)版本由
FLEET_PROTOCOL_VERSION钉住;改动 = 破坏性,需全端同版本。 - 状态收敛只依赖显式事件与单调秩;终态不可逆(
done/failed不再迁移),重试以新任务/新事件表达。 - 时延、配额、协作形态的实测数据在 M2/M3 报告;本阶段不宣称性能。