paseo-peer-zh · git:20261103.ab44e38 · 2026-11-03 · sha256 2abea2e06a933a6a
paseo-peer-zh git:20261103.ab44e38A
Immutable. This exact content never changes and is served at /api/v1/blob/2abea2e06a933a6a.
---
name: paseo-peer-zh
description: 和其他 Paseo 会话协作（本机或另一台机器）：查哪个会话在做某件事、看进度、发消息、回复、在那边新开会话。用户问「哪个会话在做 X / 谁在部署 / 隔壁在干什么」（本机也算），或提到另一台机器、跨机器、让那边的会话做什么，或收到以【跨机器消息】/【跨项目消息】/[Cross-machine message]/[Cross-project message] 开头的消息时使用。
---
# 跨机器协作（paseo-peer-zh）
用户的多台机器都跑 Paseo，各台机器上的会话可以互相查看、发消息。两条通道：
- **Paseo MCP 工具加 `serverId`（首选，Paseo 0.13+）**：用 `paseo-peer link` 把另一台机器登记成本机 daemon 的「连接主机」后，`create_agent`、`send_agent_prompt`、`get_agent_status`、`get_agent_activity`、`list_agents`、`list_workspaces`、`create_workspace` 加上那台机器的 `serverId`，就在那台机器上执行，对方每轮做完**完成通知会回到你的会话**（带对方最后的回复全文）。见下文「在另一台机器上开会话、发消息」。
- **本 skill 目录下的脚本 `scripts/paseo-peer`**（下文写作 `paseo-peer`；没加进 PATH 时用完整路径，如 `~/.claude/skills/paseo-peer-zh/scripts/paseo-peer`）：找会话（`find`/`who`/`mine`）、读日志、归档、改名、配置，以及 MCP 走不通时的兜底（`run`/`tell`）。MCP 的归档、取消、改名等工具不支持 `serverId`，这些一律用脚本。
需要另一个项目配合（联调、打通接口、各自部署）时，流程见 skill `paseo-cross-project-zh`；本 skill 只管跨机器怎么连、怎么发。
机器清单在每台机器的 `~/.paseo/peers.json`（权限 600，含配对链接），`paseo-peer ls` 列出全部机器并标出本机。**配对链接等同远程操控那台机器 agent 的钥匙**：不进任何仓库、不在对话或消息里原样回显、不写进记忆。
示例（两台机器，下文用 `office` 代指另一台）：
| 名字 | 机器 | 上面的项目 |
|---|---|---|
| `office` | 公司的 iMac | 订单服务、支付服务 |
| `home` | 家里的 MacBook | 支付服务、运营后台 |
## 首次配置（用户说「配置 / 初始化 paseo-mesh」或本机还没有 peers.json 时）
只做本机跨项目协作不需要任何配置；跨机器才需要机器清单。按下面的顺序引导用户，每步跑完把结果用一两句话告诉用户：
1. `paseo-peer doctor`：看 Paseo 版本（需 0.12.0+）、PATH、清单状态。
2. 问用户要不要跨机器协作；不要就到此结束。
3. 要的话，问本机的短名（命令里用，如 `office`，小写字母/数字/连字符）和显示名（如「公司的 iMac」），运行 `paseo-peer init --name <短名> --label "<显示名>"`。本机的配对链接脚本自己读取，用户不用提供。
4. 请用户在另一台机器上也装好 skill，把同一段初始化提示词发给那边的 Agent，让它也完成 `init`。
5. 交换加入码（每个方向一次）：在 A 上 `paseo-peer invite`（加入码进剪贴板、不显示）→ 加入码到达 B 的剪贴板后，在 B 上 `paseo-peer join`（连一次验证后才写入，并清空剪贴板）；再反过来做一遍。剪贴板到不了另一台机器时，请用户在那台机器的终端里亲自运行 `paseo-peer join` 粘贴（输入不回显）。
6. 两边都跑 `paseo-peer doctor`，全是 ✓ 才算完成。doctor 提示某台机器「daemon 设了密码」时（Paseo 0.13 起，设了密码的 daemon 走中继也要密码），请用户在本机终端里亲自运行 `paseo-peer password <机器>` 输入那台机器的 daemon 密码（不回显，验证通过才保存进 peers.json）；密码同样不进对话。
7. 两边都是 Paseo 0.13+ 时，两边各跑一次 `paseo-peer link`：把清单里的其他机器登记成本机 daemon 的连接主机（经官方 SDK 添加，配对链接和密码不进命令行参数；首次会按本机 Paseo 版本把 SDK 装到 `~/.paseo/paseo-mesh-sdk`，需要 npm）。之后 doctor 会显示「已是本机的连接主机（在线）」和对方的 serverId。哪台机器要往别的机器派活，就在哪台机器上 link。
**加入码里有配对链接（钥匙）**：绝不让用户把它贴进对话，你也不要用 `invite --print` 把它打到对话里；用户执意要贴时，提醒这会留在会话记录里并发给模型服务。
## 常用命令
```bash
paseo-peer doctor # 体检：版本、权限、每台机器能否连上
paseo-peer password office # 保存那台机器的 daemon 密码（只能由用户在终端里输入）
paseo-peer link # 把其他机器登记成本机的连接主机（0.13+，MCP 工具加 serverId 才能用）
paseo-peer ls # 全部机器，标出本机（本机也可以写 local）
paseo-peer local find 部署 deploy # 哪些会话在做这件事：搜本机全部活跃会话最近的消息和执行的命令（多个关键词任一命中，支持正则；-a 连已关闭和已归档的一起搜；--days N 只搜最近 N 天有活动的；跨机器时 -a 只加最近 --days 天内创建的已归档会话，默认 7 天、最多 50 个）
paseo-peer office who [项目目录名] # 对方机器上做这个项目的会话：状态、最近活动、标题、最近的要求与回复（默认取当前目录名）
paseo-peer office ls -g # 对方全部会话（只有标题、cwd、状态）
paseo-peer office logs <agentId> --tail 40 # 读对方进度（长输出先存文件再看）
paseo-peer office tell <agentId> "消息" # 发消息（首选），不等对方跑完
paseo-peer office wait <agentId> # 等对方跑完这一轮，打印最终状态和最后回复全文（放后台跑，见「要等对方结果」）
paseo-peer office tell <agentId> --file <路径> # 长消息、契约、文件内容：正文从文件读，免转义
paseo-peer whoami # 本会话的来源说明：「项目」项目的会话「会话名」（id 短id）
paseo-peer whoami --header --remote # 用 MCP 往别的机器发消息时的第一行（与 tell 加的来源行相同；同机去掉 --remote）
paseo-peer whoami --labels # 开配合会话要打的标签：--label collab.by=<本机>:<本会话短id> --label collab.from=<项目名>
paseo-peer office mine # 那台机器上本会话开过的配合会话（按标签精确查，含已归档）
```
```bash
paseo-peer office workspace rename <工作区id> "工作区名" # 侧边栏显示的名字
paseo-peer office agent update <agentId> --name "新会话名" # 改已有会话的名字
paseo-peer office agent archive <agentId> # 归档（MCP 的 archive_agent 只管本机）
```
## 在另一台机器上开会话、发消息
对方机器上没有合适的会话、又确实需要它在那边干活时，才新开会话（会占用那台机器的资源）。
**首选 MCP 加 `serverId`**（`paseo-peer doctor` 显示那台机器「已是本机的连接主机（在线）」时可用；serverId 也可用 `list_hosts` 查）：
1. 找工作区：`list_workspaces` 加 `serverId`，按 cwd 找对方项目已有的工作区；没有合适的就 `create_workspace` 加 `serverId`（`isolation: "local"`，`path` 为对方机器上的项目目录）。远端开会话必须指定已有的工作区。
2. 开会话：`create_agent` 加 `serverId` 和 `workspaceId`；`provider` 必须写明 `provider/model`，而且要是**那台机器**装了的（`list_models` 只查本机，那台机器的用 `paseo-peer office provider ls` / `paseo-peer office provider models <provider>` 查）；`labels` 照抄 `paseo-peer whoami --labels` 的取值（如 `{"collab.by": "office:1a2b3c4", "collab.from": "订单服务"}`）；`initialPrompt` 第一行用 `paseo-peer whoami --header --remote` 的输出；`settings.modeId` 填全部放行模式（Claude 是 `bypassPermissions`，Codex 是 `full-access`，其他 provider 用 `paseo-peer office agent mode <agentId> --list` 查），否则对方每遇到一个权限请求就停住，见下文「权限请求」；保持 `notifyOnFinish: true`。开出来的会话自动记成你的子会话（出现在子会话栏）。
3. 后续消息：`send_agent_prompt` 加 `serverId`，第一行同样带来源行；发给那台机器上任何会话（不只是自己开的）都会登记完成通知。对方不是全部放行模式时，同时带上 `sessionMode: "bypassPermissions"`（Codex 为 `full-access`），先切模式再跑这一轮。
4. 看进度：`get_agent_status` / `get_agent_activity` 加 `serverId`。
要对方回报的内容，让它**直接写在那一轮的最后回复里**：完成通知会带上全文，不用再让它 `tell` 回来。
**兜底：脚本**（那台机器还没 link、低于 0.13、或你不在 Paseo 会话里）：
```bash
paseo-peer office workspace ls # 找已有工作区 id
paseo-peer office run --no-wait --workspace <工作区id> --title "会话名" --mode bypassPermissions $(paseo-peer whoami --labels) --cwd <目录> "要做的事"
paseo-peer office tell <agentId> "消息" # 开头自动加来源、末尾附回复命令
```
脚本发起的没有完成通知，靠对方 `tell` 回复（见下文「要等对方结果」）。
本会话自己的 id 在环境变量 `PASEO_AGENT_ID`。目标写本机名字时脚本自动连本机 daemon。
## 找对的会话
- 问「哪个会话在做 X」（谁在部署、谁动了某个文件、谁在跑迁移）先 `find <关键词>` 一次搜遍，本机用 `local`；关键词中英文各给一个（会话的回复多是中文，执行的命令是英文），如 `find 部署 deploy`。会话列表只有标题和状态，看不出在做什么，**不要逐个发消息去问**。
- `find` 默认只搜没关闭的会话（正在跑的和空闲的），够快（几十个会话一两秒）；没搜到、或要找的是以前做过的事，再加 `-a` 连已关闭和已归档的一起搜：本机先 `-a --days 7`，还没有再放宽到 `--days 30`、最后去掉 `--days`（几百个会话十几秒，上千个要一分钟以上，先告诉用户在搜）。**跨机器别指望 `-a` 扫全量**：每个会话都要经中继单独拉一次记录（约 0.6 MB），所以脚本只搜最近 `--days` 天（默认 7）内创建的已归档会话、每次最多 50 个；要找更早的，先 `paseo-peer <机器> ls -a -g` 按标题和目录挑出会话，再对它 `logs <id>`（曾经一次 `-a` 扫了 600 多个已归档会话，5 分钟约 400 MB，触发中继服务器带宽告警）。结果里每个会话带状态和最近活动时间：「谁正在做」看 `running` 和几分钟前，`idle`/`closed`/`archived` 加几小时前多半是做完的事。
- 找自己开过的会话直接 `mine`（靠 `collab.by` 标签，不用猜）；找别人的会话先跑一次 `who`，从「最近」那段（用户最近的要求 + 会话最近的回复）判断谁在做什么、该找谁；不要逐个发消息去问。
- 看不出来时再对候选会话 `logs --tail 40` 细看；仍不确定就问用户，别猜着发。
- 交接链要跟到底：最近回复里写了「交接给 xxx / 由 xxx 接手」的，去找接手的那个会话。
## 会话命名（让对方找得到）
会话标题默认是用户的第一句话，常常看不出在做什么；Paseo 0.12.0 起它还会作为发送者名字显示在同机会话收到的消息上。接手一项工作、或做的事明显换了时，把自己改名为短的任务名（不用加项目名，侧边栏已按项目分组）：
```bash
paseo agent update "$PASEO_AGENT_ID" --name "#123 登录页改版"
```
会话名 ≠ 侧边栏显示的工作区名，要一起改就再 `paseo workspace rename <工作区id> "…"`。
## 发消息的规矩
- **两条通道选哪个**：那台机器已 link（doctor 显示在线）就用 MCP 加 `serverId`（`send_agent_prompt`，第一行 `paseo-peer whoami --header --remote`），能收到完成通知；否则用 `tell`。同一个会话从头到尾只用一条通道：对用 MCP 开过或发过消息的会话不要再 `tell`（它会按回复命令 `tell` 回来，加上完成通知，你会收到两遍）。
- **用脚本时用 `tell`，不用裸 `send`**：`tell` 开头自动写明来源——发往别的机器是「【跨机器消息】来自 <机器> 上「项目」项目的会话「会话名」（id 短id）」，发往本机是「【跨项目消息】来自「项目」项目的会话「会话名」（id 短id）」；末尾附回复命令。项目名取 Paseo 侧边栏的项目名（侧边栏改名即生效，匹配不到退回目录名），会话名取本会话当前名字。回复命令只用 id（不会重名）。
- **对方 `running` 时不用等**：Paseo 0.12.0 起，会话里（有 `PASEO_AGENT_ID`）发出的消息默认「引导」进对方正在跑的这一轮，不打断；`tell` 显式带了 `--behavior steer`。对方的模型不支持引导时 Paseo 会退回打断。确实要打断对方，用裸 `send --behavior interrupt`。
- **要等对方结果**：走 MCP 加 `serverId` 的，对方每轮做完完成通知自动回到你的会话（你空闲时也会被唤醒），不用守着等，也不用挂 heartbeat。本机 daemon 重启不影响：等待中的通知存在磁盘上，重启后自动恢复。对方停在权限请求时也会通知你，正文带 `<permission-request>`（含 `agentId`、`serverId`、`requestId`），按下文「权限请求」处理。处理完后通知会继续等这一轮做完。通知通常很可靠，但**已知有两种情况等不到 `finished` 通知**：
1. **发送时对方是 `closed`**（Paseo 0.14.0 实测，跨机器加 `serverId`；同机未验证）：看 `send_agent_prompt` 返回值里的 `status`，是 `closed`（`deliveryStatus` 为 `queued`）就按「不会有完成通知」处理。几秒内你会收到一条 `event="closed"`、内容为「Agent xxx was closed」的通知，那是唤起对方时补发的过时事件，**不代表对方结束了**，而且它会把这次的完成订阅消耗掉，这一轮真做完时不会再通知。这时派完活在后台运行 `paseo-peer <机器> wait <agentId>`（见下一条），或之后用 `get_agent_status` 加 `serverId` 查状态。
2. **对方机器连续三次连不上**：你会收到「Could not observe child agent … after three failed attempts … This finish subscription has ended」。网络恢复后用 `get_agent_status` 加 `serverId` 查一次，对方还在跑而你又必须等结果，就在后台跑 `wait`（或按下文挂有上限的 heartbeat）。
通知正文只带对方最后回复的前 4000 字，看全文用 `get_agent_activity` 加 `serverId`，或用 `wait`（打印全文）。
- **`wait`：可靠地等对方跑完一轮**（任何通道都能用，包括脚本 `tell` 和上面等不到通知的情况）：`paseo-peer office wait <agentId>` 先等对方进入 `running`（调用时已在跑就直接算开始），再等它离开 `running`，然后打印结束时间、最终状态和这一轮**最后一条回复的全文**（不截断）。派完活就在**后台**运行（Claude Code 用 Bash 的 `run_in_background`），跑完会自动唤醒你；不要在前台阻塞着等。参数：`--timeout <分钟>`（默认 60，最长 120）、`--interval <秒>`（默认 30）、`--start-grace <秒>`（默认 300，这么久还没开始就退出）。退出码：`0` 跑完；`2` 宽限期内没开始（消息可能没送到，`logs` 看一下）；`3` 超时仍在跑（要等就再跑一次）；`4` 停在权限请求（`wait` 只打印请求内容、自己不批；你按下文「权限请求」处理，批完再跑一次 `wait`）；`5` 一直查不到状态（id 不对或连不上）。最终状态是 `error`，或回复明显没说完（如对方遇到 API `ECONNRESET` 断线，会以一条不完整的回复结束这一轮），说明这一轮其实没做完，再发消息催它继续。用了 `wait` 就不必再为同一轮挂 heartbeat。
- **权限请求**：用户交代的任务派给对方做，就等于授权了完成这件事所需的操作，权限请求**直接批**，不转给用户：先看一眼请求内容（通知正文的 `<permission-request>`、`wait` 的输出或 `paseo-peer office permit ls`），在任务范围内就 `paseo-peer office permit allow <agentId> <请求id>`（几条都在范围内可用 `--all`），再 `paseo-peer office agent mode <agentId> bypassPermissions`（Codex 用 `full-access`）切成全部放行，免得一会儿又停住。**超出任务范围**的才拒绝并问用户：删数据或丢数据的迁移、递归删除、推到不相干的仓库或分支、对外发布、生产部署、改密钥或权限，以及任何用户没交代过的副作用（拒绝用 `paseo-peer office permit deny <agentId> <请求id>`）。注意：MCP 的 `respond_to_permission` 没有 `serverId` 参数，只能批本机的请求，远程的一律用上面的脚本命令。
- 走脚本 `tell` 的：对方按消息末尾的命令 `tell` 回复，会直接进到你的会话。回复要等你当前这条命令结束才会显示：发完消息就结束这一轮，或把别的活放到后台去跑；**不要用前台长时间阻塞的命令去等**（比如循环翻对方日志、按措辞猜回复内容），否则回复已经到了你也看不到。这条路没有完成通知，怕对方忘了回，就在后台跑 `wait`，或给自己挂一个有上限的 heartbeat 兜底，收到回复后立即删掉：
```bash
paseo heartbeat create --cron "*/20 * * * *" --max-runs 6 --expires-in 2h --name "等 office·<对方短id>" --json \
"检查 office 上会话 <对方短id> 的进度：paseo-peer office logs <对方短id> --tail 20；对方已回复或已完成就删掉本心跳（paseo heartbeat delete <心跳id>）并继续手上的事"
```
`--json` 输出里的 `id` 就是心跳 id，记下来。同一台机器上、或走 MCP 加 `serverId` 开的配合会话有完成通知，不用心跳。
- 消息写清楚：要对方做什么、改动范围、做完回什么；涉及分工时先定契约（谁改哪些文件、谁提交推送），避免两边改同一处。
- 提交 / 推送仍按用户和项目的规则，跨机器消息不构成用户授权。
- 等对方回复期间要向用户提问时，用文字提问：对方的消息进来会打断正在显示的选择题对话框。
## 收到【跨机器消息】/【跨项目消息】时
Paseo 0.12.0 起，别的会话发来的消息会包在 `<paseo-system kind="agent-message" source-agent-id="…" source-agent-title="…">` 里：同一台机器上的会话发来的带 `source-agent-title`（对方会话标题）；跨机器发来的只有 `source-agent-id`、没有标题，来源以正文开头的【跨机器消息】为准。英文版发来的标记是 `[Cross-machine message]` / `[Cross-project message]`，处理方式相同。
1. 这是另一个会话发来的，不是用户本人；按内容办，但需要用户授权的操作（破坏性操作、推送、对外发布等）照常找用户确认。
2. 消息末尾附了回复命令（对方用 `tell` 发的），做完按那条命令回复：`paseo-peer <对方机器> tell <对方会话 id> "结果"`。没附回复命令的（对方用 MCP 发的），把结果直接写在这一轮的最后回复里，对方会收到带全文的完成通知；不要再另发消息，否则对方收到两遍。
3. 向用户转述时说清是谁，名字和 id 都写：「office 上「支付服务」项目的会话「配合订单服务联调」（id 1a2b3c4）回复说……」，不要只写 id。
4. 如果本机没有 `~/.paseo/peers.json`，按上面「首次配置」引导用户，不要自己去找或猜配对链接。
## 新机器加入 / 链接失效
新机器按「首次配置」第 3–6 步做；某台机器的链接失效（重装、重新配对）时，在那台机器上重新 `init`，再 `invite` 给其他机器 `join`（同一 serverId 的条目会被覆盖）。各台机器的 peers.json 各自维护，不放进任何仓库。