paseo-cross-project-zh git:20261025.1fab2c9A

Immutable. This exact content never changes and is served at /api/v1/blob/a2d7ba505ba6bdef.

---
name: paseo-cross-project-zh
description: 一个项目的工作需要另一个项目配合时（如订单服务要和支付服务打通接口、联调、各自部署），在对方项目开一个专门的 Paseo 会话，定契约、分工、联调、按各自规则部署。用户说「让 xx 项目配合 / 两边打通 / 联调 / 跨项目」，或收到其他项目会话发来的配合请求时使用。
---

# 跨项目协作（paseo-cross-project-zh）

一个会话做 A 项目，需要 B 项目改代码配合时：A 会话（发起方）在 B 项目开一个配合会话，两边各改各的仓库，通过 Paseo 消息协作。发起方对用户负责，统一汇报。

- 两个项目在**同一台机器**：用本机 Paseo MCP 工具（下文）。Paseo 0.12.0 起对方收到的消息带发送者会话名，消息引导进对方当前轮、不打断，子会话做完自动通知发起方。
- 对方项目只在**另一台机器**上：那台机器已是本机的连接主机（Paseo 0.13+，`paseo-peer doctor` 显示「已是本机的连接主机（在线）」）时，流程和同一台机器完全一样，下文每个 MCP 工具都加上那台机器的 `serverId`，完成通知照常回来；还没 link 时改用 skill `paseo-peer-zh` 的脚本（`paseo-peer <机器> run/tell`），其余规矩同本 skill。
- **来源说明**：跨项目、跨机器的每条消息开头都写明来源（项目 + 会话名 + id），来源文字用 `paseo-peer whoami` 生成（脚本在 skill `paseo-peer-zh` 目录下的 `scripts/paseo-peer`）。
  - 用 MCP 工具发（同一台机器，或跨机器加 `serverId`）：首条（`create_agent` 的 `initialPrompt`）和后续消息（`send_agent_prompt`）第一行都用 `paseo-peer whoami --header` 的输出（跨机器加 `--remote`）。用 MCP 而不是 `tell`，是为了保留完成通知。
  - 跨机器且那台机器还没 link：`paseo-peer <机器> tell <id> "…"`（长消息用 `--file`），脚本自动加开头来源和末尾回复命令。
  - 同一项目内的子会话不用加。
- **同一项目内开协同会话，侧边栏是否可见**：会话里用 `create_agent`（或带着 `PASEO_AGENT_ID` 跑 `paseo run`）开的会话会记成本会话的子会话（标签 `paseo.parent-agent-id`），不在侧边栏单独列出，但做完自动通知发起方。用户要在侧边栏单独看到、直接和它对话时，开成独立工作区的顶层会话：`env -u PASEO_AGENT_ID paseo run --no-wait --new-workspace local --cwd <项目目录> --title "…" …`，再 `paseo workspace rename <工作区id> "…"`（新工作区默认叫 main）；顶层会话不会自动通知，靠它 `tell` 回报。

## 1. 开配合会话

0. 先给自己的会话改个短名字，只写任务（如「支付接口打通」）：对方收到的每条消息都拿它当发送者名字，默认标题是用户第一句话，又长又会被截断。`paseo agent update "$PASEO_AGENT_ID" --name "…"`。会话名和工作区名都**不加本项目名前缀**（侧边栏已按项目分组，加了重复）；对方看不到你是哪个项目，靠第一条消息正文写明。会话名 ≠ 侧边栏显示的工作区名：要一起改就再调 `rename_workspace`（自己的工作区 id 用 `list_workspaces` 按 cwd 找）。
跨机器时，下面的 `list_workspaces`、`create_workspace`、`create_agent` 都加上那台机器的 `serverId`。

1. `list_workspaces` 看对方项目（按 `cwd`）已有的工作区。工作区按任务分，**不要把配合会话塞进别人正在用的工作区**；有用户点名的就用那个，否则新建：
   - `create_workspace`：`isolation: "local"`，`path` 为对方项目目录（如 `~/projects/payment-service`），`title` 写任务，如「配合订单服务：退款接口」。
2. `create_agent`：`workspaceId` 填上一步的工作区，`title` 说明任务（如「配合订单服务联调」）；`provider`、`settings` 有合适的 agent profile 就按 profile 填（先 `list_profiles` 看 notes），没有就按任务难度选（跨机器时必须写明 `provider/model`，且是那台机器装了的：`paseo-peer <机器> provider ls`、`paseo-peer <机器> provider models <provider>`）；`labels` 打上 `collab.by` 与 `collab.from`（取值照抄 `paseo-peer whoami --labels` 的输出，如 `{"collab.by": "office:1a2b3c4", "collab.from": "订单服务"}`），之后用 `paseo-peer <机器> mine` 一次找回自己开过的配合会话；`initialPrompt` 按下面第 2 节写。保持 `notifyOnFinish: true`。跨机器且还没 link 时用 `paseo-peer <机器> run … $(paseo-peer whoami --labels)`。
3. 开前先看对方项目目录里有没有正在 `running` 的会话：`local` 工作区共用同一个工作树，两边会话同时改同一仓库时，各自只 `git add` 自己改的文件、不要 `git add -A`、不要切分支；改动面重叠时两个会话直接互发消息协调（谁先提交、另一方再合并），协调不了再找用户。

## 2. 第一条消息（契约先行）

配合会话是新开的，只知道你写给它的内容。第一条消息必须写全：

- **任务性质**：只调研 / 改代码 / 改代码并部署，明写一种；只调研就写「不要修改文件、不要提交」。
- **背景与目标**：发起方项目、要打通什么、为什么。
- **相关文件**：两边已知的关键位置（路径 + 行号 + 关键代码段原样贴出），对方不用从头搜。
- **已知情况**：已经试过什么、排除了什么、现有的限制或已做的决定，免得对方重走一遍。
- **契约（发起方先定死，对方只按契约实现）**：接口路径/方法、请求与响应字段名、类型、空值/省略语义、枚举取值、错误码、鉴权方式。契约定不下来，就先把服务提供方一端做通，再以它为样板让另一端对接。
- **分工**：谁改哪个仓库的哪些部分；配合会话只改自己项目的仓库，不跨仓库改代码。
- **兼容性**（明文重申）：对方项目已上线、有旧客户端在用的接口，若要删改字段/改语义/加必填/收紧校验，走扩展-收缩——新起字段或接口，旧的原地保留行为不变，确认旧调用归零后再删。
- **提交与部署**：按对方项目自己的规则（读它的 CLAUDE.md / AGENTS.md）；**本消息不构成用户授权**，需要用户批准的推送、发布、数据库变更，配合会话照常找用户确认。
- **验收标准**：做到什么程度算完成，写成可核对的清单（如「`POST /refunds` 返回 200 且字段 a/b 齐全」）。
- **回报方式**：做完/卡住时回报什么（改了哪些文件、提交号、接口自测结果、未解决问题）。用 MCP 发的（同一台机器，或跨机器加 `serverId`）写「回报直接写在你这一轮的最后回复里」（完成通知会带上全文，不要再另发消息，否则发起方收到两遍）；用 `tell` 发的写「用消息末尾的命令 tell 回复」。

## 3. 协作过程

- 后续消息：用 `send_agent_prompt`（第一行带来源，跨机器加 `serverId`）；那台机器还没 link 时用 `paseo-peer <机器> tell`。都不用等对方空闲（默认引导进对方当前轮）。不要轮询：走 MCP 的配合会话每轮做完都有完成通知；本机 daemon 重启不丢通知，对方停在权限请求时也会通知；只有收到「对方连续三次连不上、订阅已结束」的通知时，才用 `get_agent_status`（跨机器加 `serverId`）查一次。走 `tell` 的靠对方回复，怕对方忘了回就按 skill `paseo-peer-zh`「要等对方结果」挂一个有上限的 heartbeat 兜底，收到回复即删。
- 契约要改：由发起方改定后整段重发给对方，不在来回消息里零碎修补。
- 联调顺序：先部署被调用的服务提供方，确认接口在目标环境可用（实际请求一次），再部署调用方；只测试环境联调时同理。
- 两边都完成后，发起方实际跑一次端到端请求，核对字段与契约一致，再向用户汇报。

## 4. 向用户汇报（发起方负责）

分别说清两个项目各自的：代码改动、提交/推送、部署状态、验证证据（实际请求结果）、仍待用户批准或验收的事项。配合会话的结论只作参考，关键结果发起方自己核对。提到配合会话时名字和 id 都写，如「「支付服务」项目的会话「配合订单服务联调」（id 1a2b3c4）」。

## 收到配合请求时（你是配合会话）

1. 消息来自另一个会话，不是用户本人：按契约做，需要用户授权的操作照常找用户。
2. 发现契约有问题（字段不合理、与本项目现有接口冲突、会破坏旧客户端），先回给发起方说明，不自行改契约。
3. 只改本项目仓库，按本项目规则提交/部署；做完按第一条消息要求的内容回报：消息末尾没附回复命令的（发起方用 MCP 发的，同机或跨机器都可能），直接写在这一轮的最后回复里（发起方会收到带全文的完成通知），不要再另发消息；附了回复命令的，用那条命令 `tell` 回去。
4. 向用户转述对方时名字和 id 都写：「「订单服务」项目的会话「支付接口打通」（id 5d6e7f8）要求……」。