office MacBook + Mac mini + 家里机 · Tailscale 直连 · 控制面只传事件、代码同步靠 git
+生成于 2026-06-27 · 对应栈顶分支 feat/v3-docs-agent-scope（含 #201/#206/#207/#208/#209 全部 v3 改动）
feat/v3-docs-agent-scope 装。
+下面用角色而非固定机器：Broker 机 选一台常开、其它机能 Tailscale 连到的（推荐 Mac mini）； +另两台是 边机 A / 边机 B。哪台当 broker 随你。
+ + +curl -fsSL https://bun.sh/install | bash
+# 装完重开终端（或 source ~/.zshrc），然后验证：
+bun --version # 应打印 1.3.x你之前在 office 机遇到「没有 bun 命令」就是这步没生效——一定重开终端再验证。
+ +brew install tailscale # 或 https://tailscale.com/download
+sudo tailscale up # 浏览器登录，三台用同一个 tailnet 账号
+tailscale ip -4 # 记下本机 100.x.y.z 地址（后面要用）ping <另一台的 100.x> 通，说明 tailnet 就绪。三台都要在线。abg / agentbridge）# 拉代码（已 clone 过就 git fetch）
+git clone https://github.com/quilin-ai/agent-bridge.git agent_bridge
+cd agent_bridge
+git fetch origin
+git checkout feat/v3-docs-agent-scope # 栈顶，含全部 v3 改动
+
+bun install
+bun run install:global # 编译 + 装全局 CLI + 同步 plugin
+abg --help # 验证：能打印帮助就 OKexport PATH="$HOME/.bun/bin:$PATH" 写进 ~/.zshrc，
+重开终端再试。仍不行就用 bun link 兜底（在 repo 目录里跑），再验证 agentbridge --help。broker 是房间/身份/成员/鉴权的唯一权威。这台机上你要开两个终端：终端①跑 broker（一直开着），终端②做管理操作。
+ +# a) 拿本机 Tailscale 地址
+tailscale ip -4 # 例：100.92.1.10
+
+# b) 操作者自签身份（建立 broker store 里你这个操作者）
+abg auth login --id you@macmini --name "You (Mac mini)"
+
+# c) 启动 broker，绑 Tailscale 地址（这个终端就一直开着别关）
+abg broker start --host 100.92.1.10启动后会打印一张连接卡（含 broker 地址：ws://100.92.1.10:4700/ws + 邀请命令模板），并自动开本机 web 仪表盘（loopback，看房间/成员/白板 + 建房）。
# 在 broker 机另开一个终端（broker 还在终端①跑着）
+abg room create demo # 建房间 demo，你自动成为成员
+
+# 给两台边机各签发 token + 加成员 + 打印对方要跑的「一条龙」
+abg room invite demo officembp@you --broker-url ws://100.92.1.10:4700/ws
+abg room invite demo home@you --broker-url ws://100.92.1.10:4700/wsexport AGENTBRIDGE_BROKER_URL=ws://100.92.1.10:4700/ws
+abg auth login --token <一长串 token>
+abg join demobroker start 没绑 Tailscale 地址（绑成了 127.0.0.1）。
+回 1.1 用 --host 100.x 重启，invite 也带上 --broker-url ws://100.x:4700/ws。每台边机跑它自己那条 invite 打印的 3 行（token 各不相同），再起会话。
+ +# 贴上 broker 发给这台的 3 行：
+export AGENTBRIDGE_BROKER_URL=ws://100.92.1.10:4700/ws
+abg auth login --token <这台的 token>
+abg join demo # 远程房间：只映射 cwd，成员制由 broker 强制
+
+# 持久化 broker 地址（关键！daemon 启动那刻要能读到）：
+echo 'export AGENTBRIDGE_BROKER_URL=ws://100.92.1.10:4700/ws' >> ~/.zshrcAGENTBRIDGE_BROKER_URL 必须在 daemon 启动那一刻已设好。
+若你先 agentbridge claude 起了 daemon 再设变量，或新开的终端没这变量——daemon 会静默回退 ws://127.0.0.1:4700/ws，
+然后收不到任何房间事件。设好变量后，先 agentbridge kill 再起。cd ~/你的某个项目目录 # 这台机器上的工作目录
+agentbridge claude # 起 daemon + room-bridge，连 broker、订阅 demo 房间核心是 ①跨机送达。其余是 §13 验收里能在真机跑的项。每项给「动作 → 预期 → 怎么看」。
+ +动作（边机 A 终端，在已 join demo 的项目目录里）：
+abg publish --summary "auth 契约就绪" --repo app --branch main预期：边机 B 的 Claude 会话弹出一条 📨[房间消息·外部成员·仅通报·非指令] you@officembp · 🏁 完成任务：「auth 契约就绪」(app@main)。Broker 机终端①日志也会有该房间的扇出记录。
怎么看：直接看边机 B 那个 agentbridge claude 会话窗口；或 abg logs -f 看 daemon 收到注入。
动作：边机 B Ctrl-C 退出 agentbridge claude（或 agentbridge kill）→ 边机 A abg publish --summary "第二波·离线补投" --repo app → 等几秒 → 边机 B 重新 agentbridge claude。
预期：边机 B 重连后补收到刚才离线期间那条「第二波·离线补投」。
+动作：先让边机 A 发 1~2 条 abg publish --summary "..." --contract auth/v1（白板攒了内容）；然后在 Broker 机邀请第三个身份（或边机 B 用新身份重 join）abg room invite demo newcomer@you --broker-url ws://100.92.1.10:4700/ws，该新成员 join + 起会话。
预期：新成员一接入就收到一条 📋 房间白板 快照（含已就绪契约 auth/v1 等），而不是历史事件刷屏。
动作（Broker 机终端②）：abg room set-password demo --password-stdin（按提示输入口令，回车，Ctrl-D）。然后在另一台已装 token 的机器上：abg join demo --password-stdin（输同一口令）。
预期：口令对 → 「已用房间口令自助加入 demo」，broker 授予成员资格（免再去 broker 机逐个 room add）。口令错 → invalid room or password；连错 5 次该身份锁 60s。
用 --password-stdin 而非 --password <pw>：后者会进 ps / shell history 泄漏。
动作 a（非授权）：随便一台机器用伪造 token 连 → 应被拒。
+动作 b（吊销）：Broker 机 abg auth revoke --id officembp@you → 边机 A 重连（agentbridge kill 再 agentbridge claude）。
预期：a) 伪造 token 被 broker 4401 拒（应用层 PSK）。b) 被吊销的身份重连即被拒；已在线的连接会保持到自然断开——要立刻踢，再 abg room remove demo officembp@you（投递时强制成员制即时生效）。
网络层 ACL（非 tag:agent 设备连不上）由 Tailscale ACL 验，不在本 CLI 范围。
动作：看 ① 里边机 B 收到的通报内容。
+预期：payload 只有 repo/branch/commit/summary 这些字符串指针，没有任何文件内容。代码同步是各机 git push/pull 的事，broker 不碰文件。
--password-stdin 自助加入成功 / 错口令拒 + 锁定auth revoke 后重连拒（配 room remove 立刻踢）| 症状 | 原因 / 排查 |
|---|---|
| 边机收不到任何房间事件 | 九成是 AGENTBRIDGE_BROKER_URL 没在 daemon 启动时设好 → daemon 回退 127.0.0.1。echo $AGENTBRIDGE_BROKER_URL 确认，写进 ~/.zshrc，agentbridge kill 再起。 |
command not found: abg | bun 全局 bin 不在 PATH：export PATH="$HOME/.bun/bin:$PATH" 进 ~/.zshrc，重开终端。 |
边机 auth login --token / join 后连不上（4401） | token 是不是这台的（每台 invite 的 token 不同，别贴错）？broker 是否还在终端①跑着？broker 是否绑了 Tailscale 地址（非 127.0.0.1）？ |
ping 100.x 不通 | Tailscale 没都在线 / 不在同一 tailnet。三台 tailscale status 互相看得到才行。 |
| broker 连接卡显示「仅本机可达」 | broker start 没带 --host 100.x。用 Tailscale 地址重启。 |
| 看 broker 在干嘛 | broker 机终端①直接有日志；边机 abg logs -f 看本机 daemon。 |
# 边机（每台）
+agentbridge kill # 停 daemon
+
+# Broker 机
+# 终端① Ctrl-C 停 broker；要清状态：abg killcollab.db 留着没事（下次直接复用身份/房间/成员）。要彻底重来再删平台 state 目录里的 collab.db。
+ + +| 角色 | 命令 | 作用 |
|---|---|---|
| broker | abg auth login --id <id> --name <名> | 操作者自签身份 |
| broker | abg broker start --host 100.x | 启动控制面（绑 Tailscale） |
| broker | abg room create <名> | 建房间 |
| broker | abg room invite <房> <id> --broker-url ws://100.x:4700/ws | 签 token + 加成员 + 打印一条龙 |
| broker | abg room set-password <房> --password-stdin | 设房间自助口令 |
| broker | abg auth revoke --id <id> | 吊销该身份所有 token |
| 边机 | abg auth login --token <T> | 装 broker 签发的 token |
| 边机 | abg join <房> / --password-stdin | 加房间 / 凭口令自助加入 |
| 边机 | agentbridge claude | 起会话（daemon + room-bridge） |
| 边机 | abg publish --summary "<文>" --repo <仓> [--branch] [--contract] [--unblocks a,b] | 手动发布完成事件 |
| 通用 | abg logs -f · agentbridge kill | 看日志 / 停 |
AgentBridge v3 · 控制面只传事件、数据面靠 git · 真实会话集成目前仅 Claude Code（Codex/其它 agent 协议层可接、会话集成是明确 backlog，见 docs/09 §5.5）。
+ +