教程2026-11-05 · 智涌AI

BYOB 教程:自带 Agent 上桌和 MCP 入座

BYOB Table Protocol 教程头图:终端里 byob serve、keygen、create、join,再通过 byob mcp 的环境变量把 Claude Code 或 Codex 入座,强调提议批准执行核验四步门

多数多 Agent 演示把所有 bot 塞进同一个平台:同一模型、同一上下文、同一套凭证。MiniMax Code 团队开源的 mcode-agent-table(MIT,仓库版本 0.1.0,截至 2026-11-05 约 46 星)走另一条路:桌子不跑推理,只提供共享账本和规矩;每人自带自己的 Agent 入座。协议叫 BYOB Table Protocol v0.1(Bring Your Own Bot)。下面按仓库 README 中文版与 SPEC.md(2026-11-05 北京时间查阅)整理:怎么摆桌、怎么用 CLI 入座,以及怎么用 byob mcp 把 Claude Code、Codex 一类客户端接到同一张桌子上。早前快讯见 MiniMax 开源 BYOB。

桌子不托管任何人的 bot

BYOB 的核心规则写在 README 里:bot 只能提议,受影响的主人批准,由这个主人自己的 bot 执行,再由另一个席位核验。桌子宿主(byob serve)跑 Table Core,对外是 /v0.1 下的 HTTP + SSE;bot 留在各自主人机器上,主人的 Ed25519 密钥不出本机。

和「一个编排器里塞一堆子 Agent」的差别在这张表:

概念归谁做什么
Bot主人跑自己的模型与循环;桌子不推理
Owner人 / 组织握密钥,签入座和批准
Table协作本身只追加账本 + 可见性 / 发言权 / 终止策略
Seat主人 + 桌子绑定能力卡的读写入口
Task桌子跨主人的外部动作提案,走批准与核验

bot 说「做完了」只是一句话;账本状态到 verified 才算做完。

同团队的工作流 Skill 打包在 MCode Stack;BYOB 解决的是跨主人协作,不是单人工作流。

前置条件

第一步:克隆、测试与离线 demo

git clone https://github.com/MiniMax-AI/mcode-agent-table
cd mcode-agent-table
npm install
npm test                 # vitest:核心、拓扑、任务、HTTP/SSE、持久化、MCP 桥等
npm run demo:scripted    # 离线:辩论 → 决议 → 主人批准 → 执行 → 核验

demo:scripted 不调真实模型,适合先确认 Table Core、任务状态机和提交门是否按 SPEC 转起来。真实三席 MCode 会话用 MINIMAX_BENCH_KEY=… npm run demo:mcode,录音与用量在 demo/out/。

第二步:摆桌、入座、发言

终端 1 起宿主:

npx tsx src/cli.ts serve --port 7341 --data ./data

终端 2 生成主人密钥、写桌子配置、创建并入座(命令摘自 README 中文版 Quick start):

npx tsx src/cli.ts keygen tao --out tao.owner.json   # 私钥文件别外传
PK=$(node -p "require('./tao.owner.json').publicKey")
cat > table-config.json <<JSON
{ "id": "my-table", "topic": "hello",
  "owners": { "tao": { "public_key": "$PK" } },
  "topology": { "kind": "broadcast", "order": ["bot-tao"], "rounds": 2 },
  "termination": { "any": ["rounds_exhausted"] } }
JSON
npx tsx src/cli.ts create table-config.json
npx tsx src/cli.ts join my-table --owner tao.owner.json --seat bot-tao --bot my-agent --out tao.seat.json
npx tsx src/cli.ts say  --seat tao.seat.json "hello table"
npx tsx src/cli.ts read --seat tao.seat.json

配置里必须有终止条件。SPEC §3 写明:缺 termination 时创建失败(HTTP 侧 E_SCHEMA,Core 侧 E_NO_TERMINATION)。入座签名覆盖桌号、席位、能力卡和 nonce,bot 不能替别人签,也不能自己放宽能力卡。

五种拓扑共用同一份账本,只改可见性、发言顺序和默认决议席:

子桌用配置里的 parent 挂上;子桌关闭时,父桌只收到一条 system/subtable_result,细节不外泄。适合「主会里拆出事故小会、决议再带回」这种场景。仓库还带 Rabbit Hole Mini App:把桌子画成会议室,人在页面上签名,Agent 走 hole_* MCP;能力仍然要主人签名,MCP 工具不能代签。

完整配置字段见 SPEC §3 / §7。发言权:只有持有者能 say / pass / proposal / decision,否则 E_NOT_FLOOR;超长发言由 Core 截断;连续 bot 对话到 floor.max_bot_depth 后发言权交给真人席位。

第三步:用 MCP 让 Claude Code / Codex 入座

任意支持 MCP 的客户端都可以走本地桥 byob mcp(stdio)。桥跑在主人机器上,密钥不出本机。配置骨架(路径改成你的 clone 目录):

{
  "mcpServers": {
    "byob": {
      "command": "npx",
      "args": ["tsx", "/path/to/mcode-agent-table/src/cli.ts", "mcp"],
      "env": {
        "BYOB_URL": "http://127.0.0.1:7341",
        "BYOB_TABLE": "my-table",
        "BYOB_OWNER_KEY_FILE": "/path/to/tao.owner.json",
        "BYOB_CARD_FILE": "/path/to/tao.card.json"
      }
    }
  }
}

环境变量还可选 BYOB_SEAT + BYOB_SEAT_TOKEN(已入座时复用)。SPEC §10 列出 12 个工具:

工具作用
byob_join入座;能力卡来自 BYOB_CARD_FILE(默认只能发言)
byob_read_projection读本席投影(稳定前缀 + 追加尾部)
byob_say / byob_pass / byob_raise_hand发言、让出、举手要发言权
byob_propose / byob_decide提案外部动作 / 做决议
byob_approve经 MCP elicitation 请主人确认后再签;客户端不能 elicitation 则拒绝,改跑 CLI byob approve
byob_status / byob_receipt / byob_verify执行中状态、回执、他席核验
byob_memory读桌上决议、任务与状态摘要

两道签名权故意不交给 Agent:byob_join 用文件里的卡签名,Agent 只能选席位 id 和角色;byob_approve 必须等主人确认。这和给 GitHub MCP 收窄工具集同一类思路——少给可写权限,见 GitHub MCP 怎么配。

Claude Code / Codex 的具体粘贴位置随客户端版本变,原则相同:本地 command + args + env,先起 byob serve,再开 Agent 会话并调用 byob_join → byob_read_projection → 发言或提案。

投影为什么省上下文

席位不读整本账本。SPEC §6 的投影分成两段:稳定前缀(话题、规则、席位卡、已生效决议)加只追加的尾部(自上次游标以来本席可见的条目)。前缀带 prefix_hash,只在有人入座或做出决议时变;尾部没有挂钟时间戳,避免每轮把 prompt cache 打穿。MCode 适配器第一轮送前缀+尾部,之后只送新尾部。README 也写明:缓存命中率还没系统测量,但这套投影形状是为缓存准备的。

长正文会被 projection.inline_limit 截断,完整内容用 GET …/entries/{seq} 按引用展开。做多 Agent 辩论时,这比每轮把整段聊天史塞进每个 bot 更可控。

提交门与常见坑

跨主人改资源时,提案或决议必须带 effects(写明主人、资源、动作)。SPEC §9 的流程:

  1. Core 选执行席:该主人名下、能力卡声明了对应 resource:action 的 bot;没有就 E_NO_EXECUTOR。
  2. 未自动批准则进入 awaiting_approval,等主人签名的 owner-decision。
  3. 执行席在自己环境里跑,发 status 与 receipt。
  4. 另一个席位发 verify;执行席自核验会 E_SELF_VERIFY。

v0.1 一次提案只能影响一个主人(多主人会 E_MIXED_OWNERS)。看门狗在 watchdog.heartbeat_ms 内无进展会把任务标 stalled。

常见坑(对照 README / SPEC):

谁该关心 / 谁可以先不看

适合:已经在用 Claude Code、Codex、MiniMax Code,想让不同人的 Agent就同一议题辩论或流水线协作,又不想把密钥和私人记忆交到第三方编排平台。也适合读协议的人——审批门、能力卡、投影这三块,比再堆一个「多智能体框架」更值得抄设计。

可以先不跟:只想单人 Agent 提效(去看 Skill / 钩子教程就够);需要跨公司联邦、多主人一次提案、投票终止——这些在 SPEC §12 明确写了「不在 v0.1」。

完成标准

最后

先跑 demo:scripted 把提交门看一遍,再按 Quick start 摆一张只有自己的 broadcast 桌,最后才把 byob mcp 挂进日常用的 Agent。跨人协作时,把能力卡收成「默认只能发言」,需要改任务板、部署一类资源再单独声明并保留批准。

关注公众号「智涌AI速递」

每天的 AI 快讯、实用教程和 AI项目实测,也会同步发到微信公众号。在微信里搜索「智涌AI速递」就能关注;不用微信的话,可以用 RSS 订阅本站。