--- name: zt-multi-machine-sync description: "Use when 跨机 agent 协作与数据同步 (Mac↔Windows研究机)。" --- # 跨机 Agent 协作（zt 项目） 研究侧(Windows)与实操侧(Mac)两个 Hermes agent 的协作基础设施。**目标：让人不再当传话筒**。 ## 架构 - **Mac 实操机**（本机）：实操闭环 + 看板。Tailscale IP `100.82.83.42`（设备名 xpressomac-mini） - **Windows 研究机**：策略研究。Tailscale IP `100.76.168.126`（DESKTOP-8E2HEQS / research-wsl） - 两台**不在同一局域网** → **Tailscale** 组网（同账号 maobuyibox@，RTT ~500ms） ## 三层协调机制 1. **peer 通道**（实时消息）— `hermes peer`，gateway-to-gateway 直连，无需 Desktop 在环 2. **git 共享事实源**（文件/变更）— Mac 上的 bare repo，双方 push/pull 3. **人**（兜底转达） peer 传**消息**、git 传**文件**，互补，缺一不可。 ## 配置清单（2026-09-12 打通） ### 两端 api_server（各自的 `~/.hermes/.env`） ``` API_SERVER_ENABLED=true API_SERVER_KEY=<强随机，两端各自不同> API_SERVER_HOST=0.0.0.0 API_SERVER_PORT=8642 ``` ### Mac 侧 - `hermes peer add research --url http://100.76.168.126:8642 --key <研究侧key>`（key 存 `HERMES_PEER_RESEARCH_KEY`） - bare repo `~/zt_sync.git`；工作区 `~/zt_app` 的 remote origin 指向它 - Remote Login 已开；研究侧 ed25519 公钥在 `~/.ssh/authorized_keys` - **默认模型必须是未被 guardrail 屏蔽的**（见坑 2） ### 研究侧 - `hermes peer add mac --url http://100.82.83.42:8642 --key `（存 `HERMES_PEER_MAC_KEY`） - `git clone ssh://xpresso@100.82.83.42/Users/xpresso/zt_sync.git` - Hermes 需 **≥ v0.21.0**（`hermes peer` 在此版本起可用；旧版先 `hermes update`） ## 常用命令 ```bash hermes peer list hermes peer dm research "..." # 短消息，同步等回复（慢） hermes peer run research --idempotency-key < task.txt # 长任务，返回 run_id hermes peer status research hermes peer stop research cd ~/zt_app && git add -A && git commit -m "..." && git push # 推送变更 git pull # 拉对端变更 git log --oneline -10 # 看双方历史 ``` ## 协调工作流 - 研究侧定稿策略/数据 → `git push` + `peer dm mac "改了 X，请拉取"` - Mac 实操发现问题（如博敏 t0）→ `git push` + `peer dm research "发现 Y"` - 注册 peer 后，每个 Bot 的 messaging protocol 自动带 peer roster，agent 可 **自主** 用 `message_agent(target="research", …)` 联系，不需人转发 ## 坑（全部踩过） 1. **端口冲突**：gateway 重启时旧 api_server 未释放 8642 → `address already in use`。**再 restart 一次**（旧进程退出后端口即空）即可。 2. **默认模型被 guardrail 屏蔽**：Mac 曾用 `moonshotai/kimi-k3` → OpenRouter workspace hk 的 guardrail 屏蔽 19 个端点 → **api_server 调 agent 直接失败**（peer 表现为对端报错）。修：`hermes config set model.default deepseek/deepseek-v4.1-flash`（已验证可用）。排查：直接 curl OpenRouter 测该模型。 3. **WSL 端口不通**：研究侧 Hermes 在 WSL、Tailscale 在 Windows 时，WSL2 端口**不自动暴露**。症状：研究侧本地 `127.0.0.1:8642` 通（报 HTTP 200），但从 Mac 看 `Connection refused`。修：Windows 加 `netsh interface portproxy add v4tov4 listenport=8642 listenaddress=0.0.0.0 connectport=8642 connectaddress=`，或把 Tailscale 装进 WSL。 4. **Clash/代理拦截**：必须让 `100.64.0.0/10` 走 DIRECT，否则 Tailscale 流量被代理拦死。 5. **NAT 单向**：跨 gateway 是直连；内网可拨公网，反向无入站路由 → 用 Tailscale/VPN 兜底。 6. **peer dm 慢**：同步持一个 HTTP 连接直到对端 turn 结束，只适合短消息；重活走 `peer run`。 7. **peer 不传文件**：消息≠文件，文件永远走 git。 8. **终端无 `timeout` 命令**：macOS 无 GNU timeout，用 `gtimeout`（brew coreutils）或工具自带超时。 ## 验证清单 ```bash nc -z -w5 100.76.168.126 8642 && echo 端口可达 # 网络层 curl -s -o /dev/null -w "%{http_code}\n" --max-time 15 \ http://100.76.168.126:8642/v1/models \ -H "Authorization: Bearer $KEY" # 应为 200 hermes peer dm research "test" # 应返回对端回复 ``` ## 注意 - 本 skill 不记录明文密钥；密钥在 `~/.hermes/.env`（`HERMES_PEER_*_KEY`、`API_SERVER_KEY`） - 研究机若也要此 skill，需在其 `~/.hermes/skills/` 单独安装（经 git 同步即可）