reason-machines/reason-network · 上手攻略

• 仓库：reason-machines/reason-network
• 链接：https://github.com/reason-machines/reason-network
• 分类：agent / app（多智能体协作基础设施）
• 作者：spark
• 更新：2026-10-21

0. 三证 checklist

• [x] GitHub URL（已 fetch README.md、DESIGN.md、SECURITY.md 原文）
• [ ] 顶会 venue + 年份 —— 工程仓库，不适用
• [x] README 子模块 anchor：DESIGN.md（架构全文）、SECURITY.md（威胁模型）、tests/e2e/（两机 e2e 脚本）、Cargo.toml / rustfmt.toml 均已引用

⚠️ 诚实声明：本项目是商业产品 Reason 的引擎部分。引擎开源（MIT OR Apache-2.0），但安装它的 Reason CLI 闭源、不在本仓库。仓库卡片标 maturity=research，我读到 README 写 "Milestones: M0 done / M1 done"，描述较新（Reason Network 于 2026-10-16 前后发布），实际生产验证时间有限。

一、是什么

reason-network 是一个跨机器的编码智能体消息层。它解决的问题很具体：

你和同事各自开着 Claude Code / Codex / Cursor，AI 各自在不同的仓库、不同的分支上干活。谁在忙什么、忙完了没、有没有人卡住——人看不到，AI 之间更看不到。

装上之后，团队每个人的每个 agent session 都能：

• 看到全队此刻谁在哪个仓库哪个分支、在忙还是闲着、在做什么；
• 直接给某个具体 session 发消息，而不是往一个公共频道里吼；
• 在对方 agent 卡住、需要人拍板时，通过 notify 弹窗提醒那个人。

支持的 agent：Claude Code、Codex、Cursor、Gemini CLI、Copilot CLI、opencode、pi、Grok Bot、Muse、Reason。

架构上是纯 P2P，中间没有服务器。 每台电脑跑一个小 daemon。

二、解决什么问题

在 AI 辅助编程普及之后，团队协作里冒出了一批新问题：

reason-network 的答案是：把"团队成员"这个概念下沉到 session 粒度。你的 agent 不只是你的 agent，它同时是网络里的一个节点，能被别人找到、被联系。

再加上"没有中心服务器"这一点——它不进你的代码，不托管你的会话内容，团队自托管。

三、快速安装

官方路径（需要 Reason CLI，闭源）：

reason network

CLI 会下载一个锁定版本、校验过 checksum 的构建，装进 ~/.local/bin，把 MCP server 和 hooks 接到本机所有已装的 agent 上，然后起一个后台服务。

首次运行需要初始化并邀请团队成员：

reason-network init      # 建团队
reason-network invite <人>
reason-network join <邀请码>

init / join 内部会跑 setup，它会自动探测本机装了哪些 agent 并逐一接线，改动每个文件前都会先备份。

没有 Reason CLI 的话（本文档写作时仓库没有独立的 release 安装说明，以下为从 Cargo.toml + README "Build" 段推断的自建路径，不确定，需自行验证）：

git clone https://github.com/reason-machines/reason-network
cd reason-network
cargo fmt && cargo clippy --all-targets -- -D warnings && cargo test
cargo build --release

产物是单个静态二进制 reason-network。

四、核心用法

4.1 四个核心子命令

从 DESIGN.md 确认的子命令表：

reason-network daemon    # 每机一个，拥有 iroh endpoint、名册、目录、邮箱(SQLite)
reason-network mcp      # stdio MCP server，由 agent 拉起，是 daemon 的瘦客户端
reason-network hook <ev> # hook 处理器：status / context 注入 / stop-continuation / wake
reason-network who|send|listen|status|init|invite|join|setup|doctor

4.2 看团队

reason-network who

输出全队成员：谁在线、在哪个 repo 哪个 branch、忙还是闲、当前 session 在做什么。

4.3 发消息

reason-network send --to <目标session> "迁移脚本请帮我 review"

send 的发送者身份有三种来源：运行它的那个 shell 所属的 agent session、--from <id> 显式指定、或者从普通终端发出时署名 /terminal。

等待指定地址的下一条消息：

reason-network listen --as <目标session>

4.4 Agent 侧：三个 MCP 工具

agent 拿到的是 MCP server reason-network，暴露三个工具：

• list_team —— 列出团队
• send_message —— 发消息
• check_inbox —— 在无法推送消息的 agent 上轮询收件箱

关键设计：agent 不需要主动汇报任何东西。"这个 session 在干什么"是从它自己的 title 和 todo list 推出来的，不是让它填表。这避免了"为了协作而协作"的仪式感。

4.5 送达行为（按 agent 分档）

4.6 让人参与：notify

reason-network notify <目标> "需要你确认一下这个 PR"

消息会同时在那个人的屏幕上弹窗，用于 agent 自己无法决定的审批或决策。

⚠️ macOS 上弹窗走 Script Editor，需要在系统设置里允许一次通知。

macOS 还有菜单栏图标，显示谁在线、在做什么。

4.7 常驻 agent

reason network serve claude    # 或 grok / codex

在团队里放一个温热的无头 agent，接别人的提问，约两秒回答案。任何有 shell 的 agent 都能跑 reason network to "问题" 去问它并等答案。

4.8 网络层怎么走

同 Wi-Fi：mDNS 直连。 跨公网：iroh（QUIC 按公钥拨号 + 打洞），失败则回落到 HTTPS :443 上的中继——中继只能看到加密后的字节。 状态存在 ~/.reason/network。

4.9 卸载

reason-network leave && reason-network setup --remove && rm -rf ~/.reason/network ~/.local/bin/reason-network
rm -f ~/.local/bin/tincan       # 如果你是从 tincan 迁移来的

Windows PowerShell：

reason-network leave; reason-network setup --remove
Remove-Item -Recurse -Force ~\.reason\network, ~\.local\bin\reason-network\

4.10 端到端测试

python3 tests/e2e/two_machines.py   # 两台机器走 iroh（需要公网）
python3 tests/e2e/hooks.py
python3 tests/e2e/guided.py

五、典型适用场景

• 远程/异步团队：三人以上小队，agent 并行度已经上到"每个人同时开好几个 session"，人脑已经记不住谁在干嘛。
• 跨机器的 agent 分工：让 A 电脑的 Codex 去改前端、B 电脑的 Claude Code 去改后端，并能互相通知。
• 长任务交接："这个任务完成了，提个 PR 收尾吧"——一条消息跨机器送达。
• agent 卡住时找人：agent 遇到需要人授权的步骤，直接弹窗叫对应的人。

六、坑与注意（≥6 条，含三段式）

坑 1：CLI 闭源，"开源了"其实只开了引擎 - 现象：引擎（daemon / MCP / hooks）MIT OR Apache-2.0，但安装器 Reason CLI 不在仓库里，官方也明说 "You don't install it by hand"。 - 影响：想完全脱离商业产品走不通，自建路径无官方文档背书。 - 修复：接受这个边界，或自己 cargo build + 自己写安装流程（无文档，风险自负）。

坑 2：它会改写你所有 agent 的配置文件 - 现象：setup 逐个写入 Claude Code 插件 / claude mcp add、~/.codex/config.toml、~/.cursor/mcp.json、~/.gemini/settings.json、opencode 插件、Copilot mcp-config.json、~/.grok/config.toml 等一长串路径。 - 影响：这些是你的主力工具配置，被改坏很难排查。 - 修复：README 明确写了"改动每个文件前都会备份"，但请先自己 git 化或整目录备份 ~/.claude、~/.codex、~/.cursor 再跑 setup。

坑 3：旧项目名 tincan 会留残留 - 现象：本项目原名 tincan，卸载说明里专门加了一行 rm -f ~/.local/bin/tincan。 - 影响：从 tincan 迁移的用户可能残留旧二进制，PATH 冲突。 - 修复：卸载时照做，或迁移时手动清理。

坑 4：mcp 是单进程多 session 共享的 - 现象：DESIGN.md 明确写了 "Must handle many sessions per process: Codex, opencode and Cursor share one MCP process across threads/tabs." - 影响：任一 session 卡住可能影响同进程内其他 session 的连接。 - 修复：遇到 MCP 工具无响应时，先重启对应 agent，而不是先怀疑网络。

坑 5：消息能否"催醒"取决于 agent 品类 - 现象：Cursor、Gemini、Copilot 只能"下一步送达"，不是即时。 - 影响：指望发一条消息让 Cursor 立刻停下等你审批，会失望。 - 修复：需要人介入的场景一律用 notify 弹窗，而不是指望 agent 消息。

坑 6：公网部署依赖 iroh 打洞，失败率不可控 - 现象：NAT 严格或运营商限制 UDP 时打洞失败，回落到 HTTPS 中继。 - 影响：延迟上升，且多一跳第三方基础设施。 - 修复：延迟敏感的场景尽量让团队机器在同一 LAN；中继可自托管（README 提及）。

坑 7：安全模型靠"签名名册 + 本机身份"，配置错误代价高 - 现象：SECURITY.md 列出四类最要紧的威胁：外人混入团队并读消息、成员冒充他人、本机其他用户/进程与 daemon 对话或伪装成它、消息让 agent 做出用户看不到的动作。 - 影响：第 3 类尤其要注意——本机多用户环境下 daemon 的 socket 权限配置不当就是漏洞。 - 修复：单机个人使用为主；发现漏洞走 GitHub 私密上报（security/advisories/new），不要开公开 issue。

坑 8：数据落盘在 ~/.reason/network，卸载不干净会留状态 - 现象：会话状态、名册、邮箱都在本地 SQLite 里。 - 影响：leave 之外再删目录才干净；误删会导致本地 session 身份丢失需要重新 join。 - 修复：按 4.9 完整执行，重要场景先备份该目录。

坑 9：项目很新，无版本发布节奏可循 - 现象：仓库 42 commits，README 只说 v tag 会构建 macOS/Linux/Windows 归档。 - 影响：API/子命令仍可能变动。 - 修复：待核：本次未确认最新 release tag 与版本号，CLI 侧是 pin 版本安装的，实际用哪个 tag 请查仓库 Releases 与 Reason CLI 输出。

七、与同类对比

核心差异：它把粒度做到了 session，并且是 P2P。绝大多数"agent 协作"方案要么是频道广播（不知道该发给谁），要么必须过中心服务器（要托管你的代码上下文）。

另外它把 notify 做成了一等公民——"agent 找人"这件事被当成一等公民能力，而不是让 agent 打日志等人类去轮询。

八、一句话推荐结论

推荐给：3 人以上、已经重度并行使用多个 coding agent、且成员之间存在明确分工的团队。不推荐给：单人开发者（杀鸡用牛刀）或安全合规严格的组织（P2P 跨公网 + 自动改配置，两条都要过审）。

它的真正贡献不是"造了个消息队列"，而是把 "你的 agent 也是团队成员" 这个隐含事实变成了可寻址、可寻人的一等实体。设计文档里"agent 不需要汇报任何东西，状态从自己的 title 和 todo 推出来"这一条，比技术栈选择更值得抄。

来源：GitHub README.md、DESIGN.md、SECURITY.md 原文（raw.githubusercontent.com/reason-machines/reason-network/main/，2026-10-21 抓取）；官方站点 reasonmachines.com/network；agentools.sh 工具页；日文实测 note.com/masa_wunder/n/n36fbdb8460c5（发布日与安装验证）。待核：具体 release tag/版本号、Reason CLI 闭源部分的能力边界。