Skip to content

Latest commit

 

History

History
158 lines (118 loc) · 19.1 KB

DESIGN.md

File metadata and controls

158 lines (118 loc) · 19.1 KB

@mebular/fleet 设计(跨设备多 Agent 协作 · 任务=记忆)

本文件是 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)。

0. 一句话

把「任务」当作一类记忆:发起端把任务写进共享分区(如 tasks),目标设备上的 Agent 拾取、执行、写回状态;跨设备靠已有的记忆同步(写入即推 + anti-entropy + 变更订阅)传递,无中心协调。

1. 红线(不可越界)

  1. 不在 core 引入任务/调度/agent 语义;fleet 只 import { ... } from '@mebular/core',不得深路径 src/**。反向依赖由 tests/fleet/boundary.test.ts 强制。
  2. 墙钟不进一致性判定:expiresAt 只是本机任务板的软约定(展示/排队提示),跨端权威生命周期只由显式状态事件驱动。
  3. 禁中心化:无注册服务、无全局账本;配额 = 每设备对自己发出的量本地记账(本地拒绝/排队)。
  4. 不改 SEALING_CN.md 的协议语义(R-a..R-d / 水位 / 一致性口径 / 线格式)。若要动 → 停下报告。

2. 任务 = 记忆

  • 分区:任务记录落在共享 namespace(默认 tasks),复用 core 的图上记忆与选择性同步(订阅供给)。
  • 显式状态机:queued → claimed → running → done | failed;状态迁移是显式事件,确定性、可收敛(状态单调秩 + 终态平局裁决;见 protocol/state-machine.json)。
  • expiresAt 软约定:仅影响本机展示与本地排队;不触发跨端状态迁移,也不参与权威判定。
  • 因果链:trace.causedBy / trace.chain 记录派生关系(如子任务由父任务触发)。

2.5 域 vs 任务(W1 语义钉住)

  • 域(namespace)= 记忆数据通道:订阅 = 数据义务(收 + 及时同步本地新记忆);不含派发语义。
  • 任务 = 树/DAG:root = 派发者(发起 Agent);子任务由执行者派生(trace.causedBy/chain,禁环);任务事件存放在某个域里,域只是运输与存储。
  • 派发权限三层:L1 传输(双方订阅交集)→ L2 任务树(创建者即派发者:子任务由执行者创建,预算随树递减)→ L3 执行(本地:to.device/to.agent 过滤、执行器、并发/准入)。

2.5.1 反滥用(预算 + 公平准入)

  • 树预算: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;无偏好/热点)。

2.5.2 每设备 Agent 目录 + 工具面

  • 目录(普通记忆域,默认 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 的 optional capabilities、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 接受 optional metadata,GET /app/nodes 返回 optional metadata;新增内部 POST /app/capability-cards(draft 无 signature),由守护身份 app.identity.getDeviceKey(deviceId) 签名并写 agents 域 internal 节点,身份不可用返回 409,不伪造。签名/canonical/schema 仍只复用 fleet cards.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_card internal 节点(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-cards POST/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。

2.5.3 派发方 vs 执行方(Agent 支持口径)

先区分两个角色:

  • 派发方(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):

  1. PATH 顺序固定:hermes → dsh → opencode → claude(kind=claude-code);存在即声明对应 agent。
  2. OpenChamber 不探 PATH;仅当本机已有 <MEBULAR_HOME>/openchamber-runner.json(公开 runner 已启用并发布 discovery)时追加 openchamber,否则由用户显式配置。
  3. 都没有时回退 echo(demo);Cursor/Claude Desktop 不在自动探测内,始终 dispatch-only。
  4. 探测只表示“本机声明存在该 CLI”,不代表 task E2E;health() 需要单独调用,fleet doctor 不逐 agent 跑 --version。

plan readiness(提交前检查,已实现):

  1. plan.owner.device 必须是提交者设备,plan.owner.agent 必须是提交者 Agent;跨设备代提交不在本期 scope。
  2. planAgent(ctx.agent ?? config.defaultAgent ?? config.agents[0]?.name ?? "board")必须属于本机 config.agents[].name;否则返回 PLAN_POLICY + PLAN_OWNER_UNEXECUTABLE,不创建 plan/root(fail closed)。
  3. 生产 plan 的 owner 必须是真实可执行 Agent:isPlanOwnerExecutableAgent 显式拒绝 board/echo(含 kind=echo)以及没有 command 的 command;hermes/openchamber/dsh/opencode/claude-code 按 kind 视为可执行。测试可用 echo 作确定性 fake executor,但不得据此宣称生产可执行。
  4. root plan 的 MR 目标固定为 plan.owner 的 {device,agent},dispatch="root-only"。
  5. 每个 ready step 仍须通过 route 硬过滤(L1 授权、policy、executable、health、能力、payload、在线、容量);无候选 → NO_TARGET/blocked,不建 task。
  6. 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;没有新的导航、页面、设置项或任务面板。

2.6 一机一节点(W2):统一守护 + fleet 客户端化

拓扑:一台机器 = 一个节点 = 一个守护(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 与 fleet fleet.config.json 同目录。
  • join 归守护:invite/join/委派签发由守护提供;fleet 仅作客户端。embedded 模式保留 fleet 自托管 join(packages/fleet/src/jointoken.ts + fleet node --join-serve),仅测试/CI(test-only),生产不用。

3. 三种协作形态(已接 live:1d,含用法/限制)

  • 审查 DAG:任务派生为有向无环图(计划 → 分派 → 审查 → 汇总);trace.chain 表达父子,避免环。
  • 有限协商:任务可回写「需要澄清/反提案」,但步数有上限(有限协商),超限转 failed 并附原因。
  • 配额制闲聊:Agent 间低频信息交换,受每设备本地配额约束(超额本地拒绝/排队),不对全网协调。

4. 配额(本地记账)

  • 每个设备维护 egress(x) 计数(对自己发出的任务/消息计数),超额本地拒绝或排队。
  • 无全局账本、无跨端对账;不同设备的配额互不影响(可接受的不一致,换取去中心化)。

5. 路线(M0→M4)

状态: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。

6. 夹具先行(fixture-first)

语言无关的 JSON 夹具放在 packages/fleet/protocol/:先固定线格式与状态迁移表,再由 TS 实现与测试去匹配, 避免「实现先行」导致线格式漂移。M0 起:envelope.example.json、state-machine.json 及其往返/一致性测试。

7. 边界与已知取舍(M0 起)

  • fleet 产线格式(envelope)版本由 FLEET_PROTOCOL_VERSION 钉住;改动 = 破坏性,需全端同版本。
  • 状态收敛只依赖显式事件与单调秩;终态不可逆(done/failed 不再迁移),重试以新任务/新事件表达。
  • 时延、配额、协作形态的实测数据在 M2/M3 报告;本阶段不宣称性能。