agent-mesh

Agent Mesh — meshfleet.app

面向 OpenCode 的可审计多 Agent 协作。 将并行 Agent 作为独立的操作系统进程启动。将工作分配给专业 Agent。让 Agent 进行点对点协作——并通过见证回执和法定人数批准，让你能够回答：谁看到了这件事，谁批准了这件事，拿出证据来。 核心部分采用 MIT 许可证，且免费。

网站：meshfleet.app · 源代码版本：0.22.0 · npm · CI

维护情况：当前源代码和 Git 标签可在代码库中查看；标签代表发布意向，而注册表是已发布内容的唯一记录 · 48 小时内回复问题 · 不搞下载量噱头。

项目状态——有意保持在 1.0 之前，且积极维护。 发布有意保持低频（只有值得发布时才会推出版本，不按日历安排）；代码库每月都会进行维护，问题会在 48 小时内得到首次回复。

边界，亦是一项承诺：机制免费且永远免费——协作、回执、委员会、提供方中立的咨询接口，以及运行验证的能力，均采用 MIT 许可证，永久如此。加密签名和审计员级别的证明属于单独的付费层 （meshfleet-pro）。特定账户的提供方操作和托管策略也不属于此核心。核心中的现有机制不会转为付费功能。核心既不持有，也不独立控制提供方账户凭据、余额、重置策略、支出权限或外部发布权限。

**主机可移植性：**这是一个 Agent 审计跟踪，优先支持 OpenCode——但并非只适用于 OpenCode。核心是一个标准 MCP 服务；对更多主机的支持将根据实际需求推进。

为什么选择 Meshfleet？

OpenCode 是一个单 Agent 运行时。你与它交谈，它就会执行任务。一旦你需要多个专家并行工作——先探索，再审查，然后实现——就会遇到后台任务 30 分钟超时的问题。

Meshfleet 补上了缺失的一层：由多个 Agent 组成的集群，可以并行运行、彼此通信、交接工作并自主协作。它们是独立的操作系统进程，而不是后台任务。没有人为设置的上限。

以下是一个由源代码／运维人员配置的示例，并不表示当前 npm 包中包含所示的所有运行时：

const { fleet_id } = await callTool("spawn_fleet", {
  agents: [
    { role: "Explorer",   prompt: "Map the auth layer",    agent: "codebase-onboarding-engineer" },
    { role: "Analyst",    prompt: "Review the architecture", agent: "oracle" },
    { role: "Engineer",   prompt: "Implement JWT refresh",  agent: "backend-architect", model: "opencode-go/minimax-m3" },
    { role: "Reviewer",   prompt: "Review the resulting diff", runtime: "claude-cli", workspace_binding: "review-worktree" },
  ],
});

四位专家。四个独立进程。它们交接工作、提出问题，并在遇到问题时发出提醒。你来查看结果。

每个 OpenCode Agent 都可以接受可选的 model（provider/model）选择器。设置后，Meshfleet 会将其作为不可变请求（Agent.requested_model）持久化，并为该 Agent 启动 opencode run --model <value>；检测到的运行时横幅会写入 Agent.runtime_model，如果状态为 complete 的 Agent 缺少横幅或横幅与请求不符，则会失败关闭。不指定 model 时，旧的 argv 保持不变。选择器是数据，不是 shell 文本；横幅是检测到的证据，不代表身份验证、计费、提供商可用性或证明。

spawn_fleet 还接受可选的、针对每个 Agent 的 runtime。默认值仍为 opencode-cli；只有运维人员进行配置后，才能使用非默认运行时。claude-cli 要求使用绝对路径命令、已配置的版本标签，以及经运维人员准入的不透明工作区绑定。调用方必须通过 workspace_binding 重复提供该绑定，并省略 OpenCode 专用的 agent 和 model 选择器。minimax-cli 和 grok-cli 是单独的、仅可显式启用的文本通道。每个通道都要求使用各自的绝对路径 MESHFLEET_<VENDOR>_COMMAND 和已配置的 MESHFLEET_<VENDOR>_VERSION；不接受模型／Agent 选择器、工作区权限或产物预期；通过结构化的最终文本信封声明结果；不公开原始诊断信息；也绝不会成为自动故障转移目标。Grok 适配器还会强制配置的包装器遵守不读取来源的纯文本边界。每个包装器负责自己的身份验证；Meshfleet 会传递经清理的环境，绝不会读取或序列化凭据，也不会声明账户、凭据、有效模型、配额或可用性。此出站工作器适配器与离线静态 Grok 配置转换彼此独立；后者不会启动任何运行时。有关确切的权限和证据限制，请参阅适配器契约。针对任何账户进行的本地冒烟测试都仅限于本地环境。单独的纯 recommend_route 建议功能可以选择启用由调用方提供证据、用于近重置情况的平局判定，但它绝不会轮询账户、授予提供商权限或执行付费服务。

当某个 Agent 的操作至关重要时，Meshfleet 可以证明发生了什么。每条消息都会为每个接收者写入回执（已送达、已查看、已确认）。决策可以通过委员会进行——基于法定人数的批准流程，要求获得签署，并记录在同一账本上。这种设计移植自一个曾在生产环境中运行 40 天、处理 18,404 条消息的总线，支持由法定人数批准的决策。

---

30 秒内完成安装

通过 npm 安装（包名为 meshfleet；agent-mesh 这个 npm 名称已被占位包抢注）：

npm install -g meshfleet

或者从源代码安装：

git clone https://github.com/johnmwhitman/agent-mesh.git \
  ~/.config/opencode/mcp-servers/agent-mesh
cd ~/.config/opencode/mcp-servers/agent-mesh
npm install && npm run build

将以下内容添加到 ~/.config/opencode/opencode.jsonc（npm 安装）：

{
  "mcp": {
    "meshfleet": {
      "type": "local",
      "enabled": true,
      "command": ["npx", "-y", "meshfleet"]
    }
  }
}

对于非规范的、仅供开发使用的源码检出用法（不推荐用于发布配置）：

{
  "mcp": {
    "meshfleet": {
      "type": "local",
      "enabled": true,
      "command": ["node", "~/.config/opencode/mcp-servers/agent-mesh/dist/index.js"]
    }
  }
}

重启 OpenCode。启动一个 Agent 集群。将其接入你的客户端 →

从已发布的软件包开始

已发布的 meshfleet 软件包提供的免密钥引导演示，是一个脚本化的账本演示：它证明软件包和检查器可以运行，但不能证明由模型驱动的工作进程完成了实际任务。

npx -y --package=meshfleet -- agent-mesh demo

该已发布的引导演示完全基于一个临时账本运行（不会触及 ~/.config/opencode 下的任何内容），并打印演示审计记录，然后提供一条后续检查器命令。稍后若要检查自己配置的 MCP 账本，请显式绑定该软件包——通过 npx 运行 agent-mesh 可执行文件时，如果没有 --package=meshfleet，解析到的会是 npm 上另一个无关的保留软件包 [email protected]，而不是这个软件包：

npx -y --package=meshfleet -- agent-mesh inspect --verify

如果该命令（或 MCP 服务本身）因 CRASH ... unsupported newer storage schema version 退出，说明它在默认路径 （~/.config/opencode/agent-mesh.db）找到了一个已有账本，该账本由比你当前运行版本更新的 meshfleet 构建写入——这在已经运行过 OpenCode/meshfleet 的开发机器上很常见，在全新安装中则不会出现。将 MESHFLEET_DB_FILE=/path/to/other.db 指向另一个账本文件（MCP 客户端配置也可以设置同一个变量），这样就不会触及现有文件。

仅源码中的确定性运行时

本页介绍的较新源码检出版本包含一个 local-demo 运行时——由当前 Node 可执行文件运行的确定性工作进程。它不在已发布的软件包中。构建此源码检出版本后，让 MCP 宿主使用它启动：

spawn_fleet with agents [{ role: "scout", prompt: "Count the receipts.", runtime: "local-demo" }]

启动、生命周期事件、回执和 collect_results 都是真实的；只有工作进程是模拟的，而且它会在输出中明确说明（"model": null，不会捏造文本）。local-demo 绝不会用于自动故障转移——真实 Agent 失败时，绝不会被静默替换为回显程序。

尝试一项真实的只读任务

前提：你已安装 OpenCode，并已配置好有权使用的账户。Meshfleet 不会创建凭据、选择计费范围或调用提供商，除非你要求它启动工作进程。通过你的 MCP 宿主：

1. 调用 spawn_fleet，并传入 agents: [{ role: "explorer", prompt: "Read this repository's README and list its three main sections. Do not edit files." }]。 省略 runtime，以使用已发布的默认 opencode-cli 适配器。
2. 将返回的 fleet_id 传给 collect_results，然后使用 npx -y --package=meshfleet -- agent-mesh inspect --verify 检查本地证据。
3. 将 complete 和本地一致性报告视为记录下来的声明，而不是答案或代码正确的证明。请自行审核工作进程的结果。

然后分享自愿的首次使用反馈，说明这条路径是有用、没用还是受阻，并指出你卡住的第一个步骤。请勿上传源代码、提示词、凭据、机密信息或原始账本文件。如果它有帮助，可以改天在另一项有意义的任务上尝试相同的证据检查；重新运行脚本化演示不算再次使用。

---

将其接入你的客户端

Meshfleet 是一个标准的 stdio MCP 服务。调用方式始终相同——npx -y meshfleet （package.json 中的 meshfleet 可执行文件指向服务 dist/index.js）——只有外层配置文件会因客户端而异。

说明标签。“已测试”表示可以直接从本仓库验证。以下针对特定客户端的配置格式遵循各客户端文档——我们尚未为每个编辑器接入 CI，因此会标注“参见 <client> 文档——欢迎验证”。

任意 MCP 客户端（通用 stdio）——已测试：本仓库随附的 mcp.json 中正是此配置

{
  "mcpServers": {
    "meshfleet": {
      "command": "npx",
      "args": ["-y", "meshfleet"]
    }
  }
}

OpenCode——主要宿主；规范的 meshfleet 服务标识

~/.config/opencode/opencode.jsonc：

{
  "mcp": {
    "meshfleet": {
      "type": "local",
      "enabled": true,
      "command": ["npx", "-y", "meshfleet"]
    }
  }
}

Claude Code——参见 Claude Code 文档——欢迎验证

CLI 形式：

claude mcp add meshfleet -- npx -y meshfleet

或者在仓库根目录使用项目级 .mcp.json：

{
  "mcpServers": {
    "meshfleet": {
      "command": "npx",
      "args": ["-y", "meshfleet"]
    }
  }
}

Codex — 同一主机无关的 stdio 服务

使用相同的命令和参数配置 Codex 的 MCP 服务条目：

{
  "mcpServers": {
    "meshfleet": {
      "command": "npx",
      "args": ["-y", "meshfleet"]
    }
  }
}

这些 Claude Code、Codex、OpenCode 和通用 MCP 配置都会调用同一个入站 stdio 服务。这仅证明 MCP 边界上的客户端互操作性。工作进程默认使用 OpenCode 的 opencode run；操作员也可以单独注册非默认运行时，例如 claude-cli。subscribe_inbox SSE 端点是可选的加速方式；兼容性并不依赖它，客户端也可以通过轮询 get_inbox 获取消息。

如果上面的任何配置块无法在你的客户端中运行，请提交 issue——配置过时是一个 bug。

本地 A2A 兼容接口

本地父进程还提供一个仅限环回地址的 A2A 兼容适配器，供仪表板和集成自测使用：

GET  /.well-known/agent-card.json
POST /a2a/tasks
GET  /a2a/tasks/:task_id

Agent Card 仅声明本地任务提交和状态查询功能。任务 ID 会持久保存在本地 SQLite 账本中（local_a2a_tasks 表），因此在同一账本中，即使进程退出并重启，任务 ID 也会保留。该适配器受 MESHFLEET_SSE_TOKEN 保护（并支持现有的 SSE 身份验证别名），始终绑定到环回地址，且不提供公共 A2A 入站接口、远程中继、签名身份或推送通知。现在，本地适配器提供持久化的本地任务状态。MCP stdio 仍是主要控制接口。

---

CLI

安装 Meshfleet 后，agent-mesh CLI（来自 meshfleet npm 包——npm 上的裸 agent-mesh 会解析到另一个已保留的占位包）可让你在终端中查看正在运行的 Fleet，而 agent-mesh-dashboard 则提供实时 TUI。下方每条命令都通过 --package=meshfleet 显式选择 meshfleet 包，以避开被抢注的名称。

$ npx -y --package=meshfleet -- agent-mesh inspect
3 fleets:

bc34d339-935c-4…  complete  3 agents, 3 done (34.8m)
37ae1cf2-5ce8-4…  complete  1 agents, 1 done (28.2m)
d648beb0-cfb2-4…  failed    2 agents, 2 done (27.3s)

$ npx -y --package=meshfleet -- agent-mesh inspect --metrics
Total fleets:       7
  completed:        3
  failed:           4
Total agents:       16
Success rate:       42.9%
Avg duration:       1.34s

$ npx -y --package=meshfleet -- agent-mesh inspect --events 5
TIMESTAMP            EVENT              DETAIL
──────────────────────────────────────────────────────────────────────
2026-07-02 12:40:12  agent_spawned       fleet=f-1 agent=a-1
2026-07-02 12:40:12  agent_spawned       fleet=f-1 agent=a-2
2026-07-02 12:40:12  fleet_created       fleet=f-1

$ npx -y --package=meshfleet -- agent-mesh inspect timeline f-1 --from 2026-07-02T12:40:00Z --to 2026-07-02T12:45:00Z
Local ledger timestamps in [1782996000000,1782996300000) · not authenticity, completeness, tamper evidence, authenticated provenance, or external time
TIMESTAMP            KIND                SUMMARY
──────────────────────────────────────────────────────────────────────
2026-07-02 12:40:13  message             handoff agent-a→agent-b
2026-07-02 12:40:18  receipt             ack by agent-b on 3f9c1a2b

$ npx -y --package=meshfleet -- agent-mesh inspect --follow            # or -f; add --fleet <id> to scope to one fleet
ledger: ~/.config/opencode/agent-mesh.db  · poll 400ms  · ctrl-c to stop
watching… no messages yet  (spawn a fleet or send_message from MCP)
2026-07-22 09:14:03  handoff  agent-a → agent-b  msg=3f9c1a2b  {"task":"review PR #42"}

时间线范围可选，支持仅包含数字的 epoch 毫秒值、ISO 日期（YYYY-MM-DD）或带时区的 ISO 日期时间（YYYY-MM-DDTHH:mm:ss[.fraction](Z|±HH:mm)）。小数精度会规范化为 epoch 毫秒值。范围会根据本地账本中存储的时间戳，选择半开区间 [from,to)。添加 --json 可获取附加的 timeline_window 检查信封。不带范围的 inspect timeline [fleet] 保持原有的文本和 JSON 结构。这只是对本地记录的只读选择，并不能证明其真实性、完整性、未被篡改、来源经过身份验证或时间来自外部。

---

MCP 工具

默认的 stdio tools/list 仍提供兼容的 40 工具目录。设置 MESHFLEET_COMPACT_CATALOG=1 可启用包含 36 个工具的紧凑目录，其中省略了三个建议性路由工具（compile_route_candidates、recommend_route、plan_speculative_backlog）和已弃用的 verify_ledger_v2。在紧凑模式下，MESHFLEET_ROUTE_ADVISOR=1 会恢复这三个建议性工具，使目录包含 39 个工具。对于新的集成，建议使用 verify_ledger 和 verify_ledger_v3。

Fleet

工具	功能
spawn_fleet	将 N 个并行 Agent 作为独立 OS 进程启动；每个 Agent 可以选择已注册的 runtime 及其必需的不透明 workspace_binding，也可以使用默认的 OpenCode 运行时和可选的 model（provider/model）选择器
spawn_from_template	根据已保存的模板启动一个 Fleet
save_fleet_template / list_fleet_templates	可复用、有版本管理的 Fleet 配置
list_fleets / fleet_status	查看所有 Fleet，或单个 Fleet 的完整状态
collect_results	一次调用即可收集每个 Agent 的最终输出
set_fleet_timeout	设置单个 Fleet 的超时覆盖值（以 ms 为单位）
attach_agent	将预先创建的 Agent 动态附加到正在运行的 Fleet；该 Agent 可设置相同的可选 model（provider/model）选择器

消息与回执

工具	功能
send_message	P2P 消息（5 种类型）——或将 to_agent_id: "*" 设为向整个集群广播
send_messages	批量发送，每个批次作为一个原子事务（最多 1000 条消息；更大的批次会被拒绝）
get_inbox / ack_message	轮询并确认；每次确认都会写入一条针对收件人的回执
subscribe_inbox	通过 SSE 推送消息，而非轮询（可选认证令牌）
subscribe_events	统一的全集群 SSE 事件流；可选 fleet_id 筛选条件；每种账本事件都会在追加时发出（可选认证令牌）
receipt / get_receipts	写入并查询可验证送达账本：谁在何时看到了什么
verify_ledger	审计整个账本的内部一致性——错误意味着账本断言了自身记录无法支持的内容
verify_ledger_v2	围绕未更改的验证器报告构建带版本的未签名快照一致性封装；报告来自专用只读文件快照；处理程序不会写入账本
verify_ledger_v3	可选启用的分离式验证器封装，仅提供由严重程度推导出的本地一致性标签；不代表来源或置信度；处理程序使用专用只读文件快照，且不会写入账本
get_build_identity	正在运行的安装包的完整 BuildIdentityReport——包名称/版本、source_commit、entrypoint_count、各入口点的 SHA-256 映射，以及 entrypoints_match_runtime 标志。用于验证特定路径的哈希值是否与已发布清单匹配的专用诊断名称。与不带 verbosity 参数的 get_health() 提供相同信息。

理事会（法定人数批准）

工具	功能
open_ratification	向集群提交一项决策：法定人数、截止时间、必需的签署，以及可选的每位投票者权重
cast_vote	Agent 以留档方式投票——重新投票会更改有效投票，但不会改写历史记录
tally_ratification / sweep_ratifications	确定结果；使超过截止时间的投票过期

路由与运维

工具	功能
register_capability	自行描述角色和技能，以便进行路由
route_work	根据关键词和角色匹配度，将任务分配给最合适的 Agent
recommend_route	对调用方提供的 Agent/运行时/模型候选项进行建议性排序，并应用严格的隐私/能力筛选条件和可选择启用的近重置平局判定
plan_speculative_backlog	对调用方批准的推测性工作进行纯投影，保留路由门槛，并明确不对容量建模
compile_route_candidates	对经过清理的清单/观测快照进行纯离线投影；不会排序、持久化、执行、授权、唤醒或联系服务提供方
record_routing_outcome	反馈结果以改进路由
list_agents	发现 100 多种预置的 Agent 个性
get_health / ping	集群健康状态和存活状态。get_health 接受可选的 verbosity 参数——"full"（默认值，完整的 BuildIdentityReport，包括各入口点的 SHA-256 映射）或 "summary"（省略入口点映射，以缩小常规探测的负载）。验证特定路径的哈希值是否与已发布清单匹配时，请使用专用诊断工具 get_build_identity。

讨论（有界的双 Agent 协商）

工具	功能
ask_peer	发起有界讨论：发送根问题，可选择预留一次对等方尝试，并等待答案确定
wake_agent	唯一的通用讨论运行触发器——以原子方式预留并启动一次有界尝试
reply_discussion	提交当前唤醒尝试获准生成的唯一回复；绝不会启动 Agent
get_discussion	只读：根据持久化消息和回执推导对话记录、尝试次数、预算及故障关闭状态

请参阅 docs/discussions.md，了解完整的快速入门指南、工具参考和终态优先级。 默认的 tools/list 仍为 40，以保持兼容性。设置 MESHFLEET_COMPACT_CATALOG=1 可启用包含 36 个工具的紧凑配置文件。在紧凑模式下，设置 MESHFLEET_ROUTE_ADVISOR=1 可恢复三个建议型路由工具；仍可通过准确名称调用 verify_ledger_v2，但它不会出现在紧凑发现结果中。

RoutePlane 目录发现是独立的软件包库和 CLI，并非 MCP 工具：它会获取 RoutePlane 固定的本地回环模型目录，并将调用方拥有的策略投射为建议候选项。其软件包库 API recommendRoutePlaneCatalog() 会组合已获取的快照；选择启用的 fetchAndRecommendRoutePlaneCatalog() 会先获取一次该固定的本地回环目录，再进行相同的组合。它们的 evaluated 和 no_compiled_candidates 状态会将目录诊断与任务排除项分开保留，并且始终仅提供建议，所有效果标志均为 false。这两个 API 都不会部署、发布、选择提供商、执行模型、联系该显式本地回环目录获取操作之外的提供商、轮询预算遥测数据，也不会根据提供商标签推断权限。 RoutePlane 目录边界 → docs/ROUTEPLANE-CATALOG.md

Fleetbudget 导入和观测投射是独立的软件包接口，并非 MCP 工具。新的 meshfleet/fleetbudget-sanitizer 库和 meshfleet-fleetbudget-sanitize 标准输入 CLI，会根据调用方拥有的采集时间间隔，严格验证当前未版本化的 fleetbudget --json 字节格式。它们仅将 lane 保留为不透明的证据标识符，以及保留 measured、used、total 和 unit；routes、state、utilization、note 和 detail 则会经过验证后删除。CLI 从标准输入读取数据，绝不会调用 Fleetbudget、其他提供商进程或路由命令。

经过清理的原始通道不会包含类型化配额窗口，因此即使原始上限已完整或耗尽，也仍然只能用于诊断：它会产生 WINDOW_MISSING，不生成观测数据，也不提供可用性、耗尽、分配、排名或路由权限。存在真实的类型化配额窗口时，compileFleetBudgetObservations() 仍接受带有显式候选项绑定的调用方提供的版本化快照。多个候选项可以共享一个通道 ID，作为复制且未拆分的证据；编译器会返回观测数据或诊断信息、规范来源哈希，以及全部为 false 的效果标志。任何一个接口都不会求和、分配、预留、同步、执行或授权。经过验证的窗口边界会传递给路由候选项编译器，但不包含其通道/窗口 ID。显式的 prefer_near_reset 建议只能在现有最终评分之后，将这些边界用作平分时的决胜依据；没有默认的账户优化策略。 在原始测量预算可用于实际操作之前，必须先实现结构化采集器版本控制、由生产方负责的观测时间记录，以及类型化配额窗口。安全的主机采集与确切边界 → docs/FLEETBUDGET-OBSERVATIONS.md plan_speculative_backlog 是一种独立的纯队列投影，仅处理调用方提供的封闭输入。只有当调用方包含不透明的 state: "approved" 证据时，才会提出任务；这并不代表 MeshFleet 授权。它组合现有的 recommend_route 硬性门槛，并可选择为每项任务启用已落地的近重置平局判定，但绝不会将重置紧迫性视为全局队列优先级。候选质量标签仅声明资格，不代表质量测量。资产和视频候选项必须具备纯文本或经调用方证明的权利材料、经过私下审核，并要求由人工发布。结果仅包含作为重放证据的规范化输入哈希，所有影响均为 false，并明确说明共享候选容量尚未建模：它不会执行、安排、轮询、读取凭据、推断提供方、绑定资源池、预留容量、消耗预算、发送、发布，也不会确立新鲜度、来源、批准状态、提供方状态、回执或执行承诺。proposed 和 blocked 数组按优先级降序、任务 ID 升序排列；每个条目都包含其在该全局顺序中的从零开始的 queue_index。 咨询式路由 → docs/ADVISORY-ROUTING.md

经过净化的集群封装器用法可通过独立的纯 meshfleet/wrapper-usage-observations 包接口使用。它仅接受封闭且已解码的 fleet.wrapper-usage-summary/v1 对象，并返回 accepted/groups 状态封装，其中所有影响和权限均为 false。它会原样保留 routeplane-unattributed，并复制源拒绝项和聚合计数，不包含提示词、原始事件 ID、提供方或配额推断、派生速率、持久化、执行、安排、路由、日志激活或 MeshFleet 健康状态变更。它不是 MCP 工具，在结构上也不能与路由候选观察数据互换。 封装器用量状态边界 → docs/WRAPPER-USAGE-OBSERVATIONS.md

咨询式路由 → docs/ADVISORY-ROUTING.md · Fleetbudget 观察数据 → docs/FLEETBUDGET-OBSERVATIONS.md · 架构概览 → AGENT-MESH-SPEC.md · P2P/回执 → SPEC-P2P.md · 委员会 → SPEC-COUNCILS.md

---

5 种消息类型

类型	用途
handoff	将上下文传递给流水线中的下一个 Agent
question	提出澄清问题（可选使用 correlation_id）
result	报告最终结果
alert	向所有集群对等方广播问题
request_help	遇到阻碍时请求升级处理（向具备相关技能的特定对等方发出请求）

负载上限为 64 KB。默认编码为 JSON，但负载是字符串——可发送任意内容。广播（to_agent_id: "*"）会发送给所有集群对等方，每位接收者都会独立确认——回执账本会准确显示哪些人已收到。

---

4 种协作模式

• 流水线交接：A → B → C。每位专家都将上下文交给下一位，无需协调器介入。
• 辩论达成共识：A 和 B 审查同一份产物，通过提问展开讨论，并在报告前达成一致。
• 故障恢复：C 遇到阻碍后广播 alert，具备相关技能的对等方会提供修复方案。
• 批准的决策：委员会对高风险操作进行投票——包括法定人数、截止时间和必需的签署；结果（包括哪些人未作回应）都会记录在账本中。

了解更多回执切入点 →

---

验证器能捕获什么——以及它无法捕获什么

“证明它”是一个关于检测能力的主张，因此它附带了证据： test/fixtures/corpus/ 是一个包含 85 个故意伪造账本的语料库，每个账本都是一个干净的基线，加上一项声明的变更。结果分为三个独立类别报告，绝不合并成单一覆盖率数字：

类别	N	含义
caught	60	过度声明——账本声称的内容不受其自身记录支持。会引发错误并使账本验证失败。
anomaly	15	令人意外，但声明没有超出记录所支持的范围。仅发出警告，并且刻意不计为已捕获。
undetectable	10	未签名的本地核心在结构上无法看到这些情况。不产生任何发现。

**第三类是有意公开的。**核心负责检查内部一致性；它无法检查来源、内容绑定、完整性或绝对时间。因此，理事会批准后被替换的载荷、为合法持有席位的 Agent 铸造的选票、拥有连贯历史的幽灵 Agent，以及整体时钟偏移，都能通过验证——每种情况都作为一个明确断言这一点的测试样例提交。这让免费核心的边界变成了可以实际运行的内容，而不只是我们声称的内容。这也正是 Meshfleet Pro 所处的边界另一侧：签名能让这些攻击向量变得可检测，而本核心不包含签名。

caught 和 anomaly 向量共同列出了验证器在 discussion.* 系列之外可能发出的所有检查项；每次运行都会从源代码重新推导这份清单——因此，新增检查却没有测试样例就会导致构建失败。

已实现的版本化证据范围

verify_ledger_v2 是已实现的 MCP 验证器接口。它仍位于兼容的默认目录中，但当 MESHFLEET_COMPACT_CATALOG=1 时，会从精简的 tools/list 中隐藏并标记为弃用；此版本中其处理程序仍可调用。建议使用 verify_ledger 和 verify_ledger_v3。现有的 verify_ledger、VerifyReport、VerifyFinding、agent-mesh inspect --verify 和 meshfleet.inspect/v1 均保持不变。

在工具分发时，其处理程序会通过专用的只读文件快照读取配置的账本，且不会写入账本。在正常的父进程模式下，服务启动时的恢复或迁移操作可能会在任何工具分发之前初始化或更改配置的账本；v2 不会改变这些分发前的影响，且这些影响不在此处理程序的边界内。

MCP 工具会返回以下信封。与之对应的选择启用模式 agent-mesh inspect --verify-v2 [file] CLI 已实现：它通过同一个专用的只读文件快照审计指定文件或配置的账本。使用 --json 时会输出同一个对象；否则会先输出一条证据范围标题，然后输出未变更的旧版验证器文本：

{
  "schema": "meshfleet.verify/v2",
  "evidence_scope": {
    "profile": "unsigned_snapshot_consistency/v1",
    "ok_means": "no_detected_internal_consistency_contradiction",
    "assurance_ceiling": "internal_consistency_of_the_unsigned_snapshot_read",
    "not_established": [
      "authorship_and_authenticated_provenance",
      "pre_read_snapshot_integrity_and_tamper_evidence",
      "content_binding",
      "completeness_and_deletion",
      "external_delivery_and_execution",
      "external_time"
    ]
  },
  "report": "the unchanged VerifyReport"
}

report.ok 保留其当前的确切含义：在读取的未签名快照中没有检测到内部一致性矛盾（report.errors === 0）。它不能证明作者身份或经过身份验证的来源、读取前快照的完整性或篡改证据、内容绑定、完整性或未发生删除、外部传递或执行，或外部时间。范围由验证器生成的输出决定，而非调用方或账本输入；它是报告所能证明内容的上限，而非置信度评分、完整性判定或晋级。

已实现可选启用的 verifier v3 本地一致性分级

verify_ledger_v3 和 agent-mesh inspect --verify-v3 [file] 是彼此独立、 可选启用的 verifier 接口。它们保留相同的六项 unsigned_snapshot_consistency/v1 evidence_scope，但返回一个全新的、恰好包含 四个键的封装，其中带有一份未更改的 VerifyReport 的分离副本：

{
  "schema": "meshfleet.verify/v3",
  "evidence_scope": {
    "profile": "unsigned_snapshot_consistency/v1",
    "ok_means": "no_detected_internal_consistency_contradiction",
    "assurance_ceiling": "internal_consistency_of_the_unsigned_snapshot_read",
    "not_established": [
      "authorship_and_authenticated_provenance",
      "pre_read_snapshot_integrity_and_tamper_evidence",
      "content_binding",
      "completeness_and_deletion",
      "external_delivery_and_execution",
      "external_time"
    ]
  },
  "report": {
    "ok": true,
    "scope": {
      "covers": "internal consistency — every receipt, flag, inbox entry, and ratification tally is supported by the ledger's own records",
      "excludes": "authenticity — there is no hash chain or signature here, so an edit that rewrites the ledger consistently is indistinguishable from honest history"
    },
    "errors": 0,
    "warnings": 0,
    "counts": { "fleets": 0, "agents": 0, "messages": 0, "receipts": 0, "ratifications": 0 },
    "findings": []
  },
  "finding_local_bands": []
}

每个报告发现项恰好对应一个本地分级，并按报告中原有的顺序排列：error 会变为 local_consistency_error，warning 会变为 local_consistency_warning。映射不会对发现项排序、去重、检查检查项名称，也不会为发现项打分。严重性未知或缺失时会默认拒绝。 没有发现项时不会生成分级；也不会生成 undetectable 发现项。

报告副本和分级数组仅为防止调用方别名问题而冻结。 它们不提供防篡改证据。这些标签仅是根据严重性得出的本地一致性标签，不代表来源或置信度；没有标签既不表示真实性，也不表示完整性。与 v2 一样，处理程序通过专用的只读文件快照读取，不会写入账本。verify_ledger、verify_ledger_v2、 VerifyReport、现有的 inspect JSON、 文本输出、退出状态、账本行为和边车文件均保持不变。

---

这能证明你的 Agent 什么——又不能证明什么

上一节讨论的是账本说谎。这一节讨论的是Agent说谎，而任何协调记录都无法排除这种情况。Meshfleet 在本地、未签名的 SQLite 账本中记录集群协调信息：一份结构化、可查询的历史记录，记录了谁被启动、谁给谁发了消息、谁投了票，以及每个 Agent 对自身结果作了什么声明。它不是加密日志系统，不提供第三方证明，也无法让大模型的声明变成事实。

账本可以告诉你	账本无法告诉你
记录的历史中，内部协调规则（法定人数阈值、投票集合、回执密钥）是否成立。	Agent 报告的发现、退出代码或测试通过情况是否属实。
协调事件的记录顺序和时间线。	具有本地写入权限的进程是否在账本外改写了行（参见上面的 undetectable 分类）。
哪些 Agent 参与、投票、确认，以及每个 Agent 声明了什么结果。	向第三方证明执行情况或陈述属实——此核心中没有签名。

运行原则：线索，而非凭据。 集群输出是线索，绝非凭据——在你亲自重新运行之前，任何内容都不应写入报告。编排器处于自主执行与你的决策之间，因此必须明确说明其责任的边界：Meshfleet 会强制执行协议规则并提供候选产物；验证工作仍由你的工具和审核来完成。

已知限制及各项进展

• 完成状态由 Agent 声明，而非经验证。 曾观察到 Agent 在解释失败的内容上记录了 complete。已交付的结果契约要求每次派生都在结果信封中声明 done / refused / blocked， 并将其作为 result_contract 记录在 Agent 行中，且由 collect_results 返回。只有 ok 可以记录为 complete；refused、blocked、artifact_missing、invalid 或缺失的结果都会记录为 failed。有效的信封仍然只是一个 声明——它不能验证内容是否为伪造、付出了多少努力或质量如何。
• Agent 指标造假。 Agent 可以报告虚构的测试数量，或编造“VERIFIED”声明，而账本只会记录它 声称了这些内容。问题仍然存在，目前只能部分检测；强制使用结果信封也无法解决。
• 崩溃期间 Agent 丢失。 collect_results 会明确报告丢失情况（名称为 lost_agents，并且只有发生丢失时 才会出现 warning）。服务崩溃时会留下一条持久化日志，下一次健康启动时会读取该日志： 在能够如实归因时，中断的行会带有 stopped_reason（server_crash | process_lost）。如果失败行有 有效的结果契约，且包含输出或声明的产物，则会改列在 degraded_agents 中：结果已报告，但运行时 状态不正常。这是交付证据，不是执行情况或真实性的证明。均已交付。
• 内部规则执行。 已投入运行：审计器每次运行都会从源代码重新推导规则；若账本声称的内容超出 自身记录所能支持的范围——例如没有投票却有批准记录，或没有消息却有回执——验证就会失败 （即上文的 caught 分类）。

---

对比

工具	最适合	权衡
OpenCode task()	单任务工作	超时 30 分钟，不支持 P2P
LangGraph	Python 图应用	仅支持 Python，优先托管部署
CrewAI	基于角色的 Python Agent	仅支持 Python，托管部署
AutoGen	研究项目	体量大，仅支持 Python
手写 cron	特定的一次性工作流	没有共享抽象
Meshfleet	OpenCode + 多 Agent、本地优先、可审计	目前仅支持 TypeScript

它们都无法回答“谁看到了这件事、谁批准了，拿出证据”。这正是我们的定位。

常见问题 →

---

架构

src/
├── db.ts                # The withLedger transaction seam over SQLite (the write boundary)
├── core.ts              # Data layer: ledger, messages, receipts, capabilities, events
├── migrate.ts           # One-shot JSON→SQLite migration (runs once at startup)
├── ratify.ts            # Councils: quorum ratification over the receipts substrate
├── templates.ts         # Versioned fleet templates
├── routing-feedback.ts  # Outcome-informed work routing
├── health.ts            # Fleet health scoring
├── realtime.ts          # SSE push delivery (subscribe_inbox)
├── inspector.ts         # Pure formatters for CLI output
├── index.ts             # MCP server: transport + tool handlers
└── bin/
    ├── inspect.ts       # CLI: npx -y --package=meshfleet -- agent-mesh inspect
    └── dashboard.ts     # Live TUI: npx -y --package=meshfleet -- agent-mesh-dashboard

所有写入都通过一个函数完成——db.ts 中的 withLedger(mutator)，它会在单个 SQLite BEGIN IMMEDIATE 事务中执行变更。Agent 是真正的操作系统进程，每个进程都会在同一账本上启动各自的 agent-mesh 实例，因此写入确实会并发发生；SQLite（WAL + busy_timeout）负责跨进程写入互斥，因此此代码库无需自建锁定协议，也不会发生丢失更新。（早期的 JSON 读写改存储方案在双进程测试中悄悄丢失了 120 条回执中的 57 条；SQLite 方案通过了相同测试，成绩为 200/200。）读取方使用无锁的 readLedger()。纯格式化函数位于 inspector.ts 中，易于测试且不涉及 I/O。

账本位于 ~/.config/opencode/agent-mesh.db（SQLite）；事件日志位于 ~/.config/opencode/agent-mesh.events.log（NDJSON）。使用 MESHFLEET_DB_FILE=/path/to/file.db 覆盖账本路径——适用于第二次安装、测试账本，或默认路径上现有文件由较新或不兼容的构建版本写入的情况。随时可以使用 npx -y --package=meshfleet -- agent-mesh inspect --export 将账本导出为便于阅读的 JSON。从 JSON 账本升级后的首次运行时，服务会迁移该账本一次（经过验证，并保留 .migrated.<ts> 备份）。

架构概览 → · P2P 消息规范 →

---

要求

• Node.js >= 20
• $PATH 中有 OpenCode CLI（支持 OpenCode 的任何模型提供方）
• 仅此而已

---

背景

背景：Human Out of the Loop 是本项目组合背后的书籍。

---

许可证

核心部分采用 MIT 许可证——可自由使用、分叉，并集成到你的产品中。除许可证文件外，无需注明出处。（商业保障层 Meshfleet Pro 位于单独的代码仓库中，不会改变此处的内容。）

---

参与贡献

请参阅 CONTRIBUTING.md。漏洞 → 问题。安全问题 → SECURITY.md。路线图 → ROADMAP.md。