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

多数多 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 解决的是跨主人协作,不是单人工作流。
前置条件
- Node.js ≥ 22.19(
package.json的engines)。 - 能 clone GitHub 仓库并
npm install。 - 要用 MCP 入座时:已会在 Claude Code / Codex 里加本地 stdio MCP(背景见 MCP 是什么与怎么接)。
- 跑三席真实 MCode 辩论 demo 时:本机
mcode≥ 0.6.3,并准备 MiniMax API key(README 的demo:mcode)。本教程只按文档讲配置与门禁,不要求先跑真实模型。
第一步:克隆、测试与离线 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 不能替别人签,也不能自己放宽能力卡。
五种拓扑共用同一份账本,只改可见性、发言顺序和默认决议席:
broadcast:按order轮转,大家互相看见。debate:正反轮流,法官默认只看双方的say。pipeline:按阶段传递,后一阶段主要看前一阶段输出。hub_spoke/delegation:中心或汇报树控制发言权回流。
子桌用配置里的 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 的流程:
- Core 选执行席:该主人名下、能力卡声明了对应
resource:action的 bot;没有就E_NO_EXECUTOR。 - 未自动批准则进入
awaiting_approval,等主人签名的owner-decision。 - 执行席在自己环境里跑,发
status与receipt。 - 另一个席位发
verify;执行席自核验会E_SELF_VERIFY。
v0.1 一次提案只能影响一个主人(多主人会 E_MIXED_OWNERS)。看门狗在 watchdog.heartbeat_ms 内无进展会把任务标 stalled。
常见坑(对照 README / SPEC):
- 忘写 termination:桌子创建直接被拒。
- 没发言权就 say:返回
E_NOT_FLOOR,应先raise_hand或等轮到自己。 - 把主人密钥交给 Agent 或塞进仓库:协议假设密钥只在主人侧;MCP 桥也不把签名权交给模型。
- 指望联邦或多主机:v0.1 单宿主,无主机间联邦;WebSocket / A2A 桥也未实现。
- 把「说完了」当完成:只认账本
verified。
谁该关心 / 谁可以先不看
适合:已经在用 Claude Code、Codex、MiniMax Code,想让不同人的 Agent就同一议题辩论或流水线协作,又不想把密钥和私人记忆交到第三方编排平台。也适合读协议的人——审批门、能力卡、投影这三块,比再堆一个「多智能体框架」更值得抄设计。
可以先不跟:只想单人 Agent 提效(去看 Skill / 钩子教程就够);需要跨公司联邦、多主人一次提案、投票终止——这些在 SPEC §12 明确写了「不在 v0.1」。
完成标准
npm test与npm run demo:scripted按官方说明能跑通。- 本地宿主在 7341(或你选的端口)起来,
create+join+say+read能看到投影前缀与尾部。 - MCP 客户端列表里出现 byob 的 12 个工具;能力卡来自文件而不是对话临时编造。
- 读过 SPEC §9 / §12:清楚单主人提案、无联邦、帖子目前靠 seat token 认证(入座与批准才主人签名)这些边界。
最后
先跑 demo:scripted 把提交门看一遍,再按 Quick start 摆一张只有自己的 broadcast 桌,最后才把 byob mcp 挂进日常用的 Agent。跨人协作时,把能力卡收成「默认只能发言」,需要改任务板、部署一类资源再单独声明并保留批准。