---
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 天有活动的，仅本机）
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 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` 的输出；保持 `notifyOnFinish: true`。开出来的会话自动记成你的子会话（出现在子会话栏）。
3. 后续消息：`send_agent_prompt` 加 `serverId`，第一行同样带来源行；发给那台机器上任何会话（不只是自己开的）都会登记完成通知。
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 "会话名" $(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`（几百个会话十几秒，上千个要一分钟以上，先告诉用户在搜）。结果里每个会话带状态和最近活动时间：「谁正在做」看 `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`），默认把请求内容转述给用户、由用户决定；只有用户事先明确授权过这类操作时，才自己用 `respond_to_permission` 加这几个参数远程批准或拒绝。处理完后通知会继续等这一轮做完。唯一会结束的情况：对方机器连续三次连不上，你会收到「Could not observe child agent … after three failed attempts … This finish subscription has ended」，这时用 `get_agent_status` 加 `serverId` 查一次对方状态（连不上就等网络恢复后再查），对方还在跑而你又必须等结果时，才按下一条挂有上限的 heartbeat。通知正文只带对方最后回复的前 4000 字，看全文用 `get_agent_activity` 加 `serverId`。
- 走脚本 `tell` 的：对方按消息末尾的命令 `tell` 回复，会直接进到你的会话。回复要等你当前这条命令结束才会显示：发完消息就结束这一轮，或把别的活放到后台去跑；**不要用前台长时间阻塞的命令去等**（比如循环翻对方日志、按措辞猜回复内容），否则回复已经到了你也看不到。这条路没有完成通知，怕对方忘了回，就给自己挂一个有上限的 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 各自维护，不放进任何仓库。