gavinguo521/paseo-mesh / skills/paseo-peer-zh
paseo-peer-zh
Verified和其他 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 时)
只做本机跨项目协作不需要任何配置;跨机器才需要机器清单。按下面的顺序引导用户,每步跑完把结果用一两句话告诉用户:
paseo-peer doctor:看 Paseo 版本(需 0.12.0+)、PATH、清单状态。- 问用户要不要跨机器协作;不要就到此结束。
- 要的话,问本机的短名(命令里用,如
office,小写字母/数字/连字符)和显示名(如「公司的 iMac」),运行paseo-peer init --name <短名> --label "<显示名>"。本机的配对链接脚本自己读取,用户不用提供。 - 请用户在另一台机器上也装好 skill,把同一段初始化提示词发给那边的 Agent,让它也完成
init。 - 交换加入码(每个方向一次):在 A 上
paseo-peer invite(加入码进剪贴板、不显示)→ 加入码到达 B 的剪贴板后,在 B 上paseo-peer join(连一次验证后才写入,并清空剪贴板);再反过来做一遍。剪贴板到不了另一台机器时,请用户在那台机器的终端里亲自运行paseo-peer join粘贴(输入不回显)。 - 两边都跑
paseo-peer doctor,全是 ✓ 才算完成。doctor 提示某台机器「daemon 设了密码」时(Paseo 0.13 起,设了密码的 daemon 走中继也要密码),请用户在本机终端里亲自运行paseo-peer password <机器>输入那台机器的 daemon 密码(不回显,验证通过才保存进 peers.json);密码同样不进对话。 - 两边都是 Paseo 0.13+ 时,两边各跑一次
paseo-peer link:把清单里的其他机器登记成本机 daemon 的连接主机(经官方 SDK 添加,配对链接和密码不进命令行参数;首次会按本机 Paseo 版本把 SDK 装到~/.paseo/paseo-mesh-sdk,需要 npm)。之后 doctor 会显示「已是本机的连接主机(在线)」和对方的 serverId。哪台机器要往别的机器派活,就在哪台机器上 link。
加入码里有配对链接(钥匙):绝不让用户把它贴进对话,你也不要用 invite --print 把它打到对话里;用户执意要贴时,提醒这会留在会话记录里并发给模型服务。
常用命令
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 # 那台机器上本会话开过的配合会话(按标签精确查,含已归档)
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 查):
- 找工作区:
list_workspaces加serverId,按 cwd 找对方项目已有的工作区;没有合适的就create_workspace加serverId(isolation: "local",path为对方机器上的项目目录)。远端开会话必须指定已有的工作区。 - 开会话:
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。开出来的会话自动记成你的子会话(出现在子会话栏)。 - 后续消息:
send_agent_prompt加serverId,第一行同样带来源行;发给那台机器上任何会话(不只是自己开的)都会登记完成通知。对方不是全部放行模式时,同时带上sessionMode: "bypassPermissions"(Codex 为full-access),先切模式再跑这一轮。 - 看进度:
get_agent_status/get_agent_activity加serverId。
要对方回报的内容,让它直接写在那一轮的最后回复里:完成通知会带上全文,不用再让它 tell 回来。
兜底:脚本(那台机器还没 link、低于 0.13、或你不在 Paseo 会话里):
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 起它还会作为发送者名字显示在同机会话收到的消息上。接手一项工作、或做的事明显换了时,把自己改名为短的任务名(不用加项目名,侧边栏已按项目分组):
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通知:- 发送时对方是
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查状态。 - 对方机器连续三次连不上:你会收到「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,或回复明显没说完(如对方遇到 APIECONNRESET断线,会以一条不完整的回复结束这一轮),说明这一轮其实没做完,再发消息催它继续。用了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 兜底,收到回复后立即删掉: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],处理方式相同。
- 这是另一个会话发来的,不是用户本人;按内容办,但需要用户授权的操作(破坏性操作、推送、对外发布等)照常找用户确认。
- 消息末尾附了回复命令(对方用
tell发的),做完按那条命令回复:paseo-peer <对方机器> tell <对方会话 id> "结果"。没附回复命令的(对方用 MCP 发的),把结果直接写在这一轮的最后回复里,对方会收到带全文的完成通知;不要再另发消息,否则对方收到两遍。 - 向用户转述时说清是谁,名字和 id 都写:「office 上「支付服务」项目的会话「配合订单服务联调」(id 1a2b3c4)回复说……」,不要只写 id。
- 如果本机没有
~/.paseo/peers.json,按上面「首次配置」引导用户,不要自己去找或猜配对链接。
新机器加入 / 链接失效
新机器按「首次配置」第 3–6 步做;某台机器的链接失效(重装、重新配对)时,在那台机器上重新 init,再 invite 给其他机器 join(同一 serverId 的条目会被覆盖)。各台机器的 peers.json 各自维护,不放进任何仓库。
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |