Parcels-Go 使用手册：从环境准备到故障排查

在一台电脑上跑 AI Agent，人一合上电脑任务就断了；家里那台性能更强的台式机却整夜闲置。Parcels-Go 要解决的就是这个问题：它把本地正在运行的 Agent 会话连同代码一起搬到远端机器，放进 tmux 里继续执行，你随时可以查看输出、拉回改动。它是命令行原版 parcels 的图形化 Go 实现，本手册把每个界面、每个字段、每个按钮逐一讲清楚。

一、准备工作：两台机器先打通

Parcels 依赖 Tailscale 让笔记本和台式机互通。两台机器都安装 Tailscale 并用同一账号登录：

# macOS
brew install tailscale
# Linux
curl -fsSL https://tailscale.com/install.sh | sh

# 两台机器分别执行登录
tailscale up

# 在笔记本上验证互通
tailscale status
ssh <台式机别名> echo ok

然后 SSH 到远端机器装必备依赖：tmux、rsync、git，以及生成交接文档要用的 python3；再装你要用的 agent，比如 npm install -g @anthropic-ai/claude-code，并执行 claude login 完成登录。agent 支持 claude、codex、pi、droid 四种，装哪个用哪个。首次打开 parcels-go 应用时界面是空的，先去「目标」Tab 把远端机器加上。

二、发送 Tab：把任务搬过去

发送 Tab 是最常用的界面，负责把当前在跑的 AI Agent 任务搬到远端。各字段填法：

九成场景只需要填 Repo 路径、目标机器、Agent 三项，其他留空，点发送即可。

发送的七个步骤

发送时会看到七步日志，每步对应背后的一个操作：

哪一步红了就看报错信息，多数情况是体检没过，去体检 Tab 跑一遍诊断即可。发送成功后界面会给出 attach 命令，复制到终端就能实时看 agent 在干什么；按 Ctrl+B 再按 D 可以脱离会话但不杀进程。

Worktree 多任务并行

填了 Worktree 标签后，Parcels 会用 git worktree 给这条任务建独立工作环境：每个任务有独立目录、独立分支、独立 tmux 会话。比如标签为 docs 的任务会落在 .parcels-worktrees/docs 目录、parcel/docs 分支、parcel-myproject-docs 会话里；主线仓库完全不受影响，你可以继续在主仓库改代码。agent 跑完后到同步 Tab 拉回该 worktree 的改动，再 git merge 合并、git worktree remove 清理。

这是 Cursor Background Agents、Devin 这类「一个任务一个沙箱」产品做不到的：Parcels 是一个仓库同时跑多条 agent 线，互不踩踏。它适合同时推进写文档、重构、写测试这类相互独立的子任务，或者并行探索多个方案。

三、活动 Tab：自动盯进度

发送成功后，任务自动出现在活动 Tab。后台 Monitor 每 30 秒巡检一次，列表每 10 秒自动刷新。任务有三种状态：运行中（agent 还在干活）、空闲（超过 180 秒没新输出，可能卡住或接近完成）、已完成（检测到完成信号）。

Monitor 用三种信号判断任务跑完没有：tmux 会话消失，说明 agent 进程退出了；输出末尾出现 Task completed、All done 这类完成关键词或回到 shell 提示符，也算完成；180 秒空闲超时是兜底信号。活动卡片上有「看输出」按钮，能抓取 tmux 最近 40 行，方便看 agent 干到哪了；关闭按钮只是把任务移出跟踪列表，不会杀远端进程。

任务完成后，卡片会列出远端改动摘要（几个文件修改、几个新增），并提示你该去同步 Tab 把改动拿回来。

四、同步 Tab：把改动安全拿回来

agent 在远端改完代码后，同步 Tab 提供四个动作。

预览改动：用 rsync dry-run 对比远端和本地，不实际改动任何文件，列出修改和新增清单，每个文件可以单独看 diff。零副作用，最常用。

拉取（覆盖）：确认后 rsync 把远端改动直接拉回，但会覆盖本地未提交改动，拉之前强烈建议先 git stash 或 commit。

安全拉取（建分支）：日常最推荐的方式。点击后自动新建形如 parcel/pull-20260706-063815 的分支，把远端改动 rsync 拉回、git add -A 提交，然后切回原分支。原分支的未提交改动完全不受影响，改动被隔离在新分支里，复核之后再决定要不要合并，永不丢代码。

补缺到远端：用 rsync --ignore-existing 只补远端缺的文件，不覆盖 agent 改过的内容，适合把本地新建的文件送过去给远端 agent 用。

推荐工作流：先预览改动，逐个看 diff 审查质量，然后安全拉取建分支，最后本地复核再合并提交。

五、模板、历史与状态

模板 Tab：经常用同样配置发任务的话，可以存成模板，字段包括名字、描述、目标机器、Agent、Repo 匹配、默认 Prompt、是否仅同步。界面里点编辑即可把模板载入发送表单；也可以直接对 AI 说「用某个模板把某个项目发过去」，由它调用 parcels_send_by_template 完成。

历史 Tab：自动记录每次发送，成功记录带 attach 命令和耗时，失败记录带错误信息，顶部统计总次数、成功数、失败数、总耗时。「重发」按钮会用这条历史的参数（仓库、目标、agent、会话）直接再发一次，适合上次跑挂了想重试，或者相同任务再跑一遍的场景。

状态 Tab：实时快照，点刷新才更新，查询远端 tmux 里所有 parcel 开头的会话，并显示每个会话最近 12 行输出。它和活动 Tab 的分工是：状态 Tab 手动刷新看即时输出，活动 Tab 自动监控、检测完成并发通知。

六、目标 Tab 与体检 Tab

目标 Tab 管理远端机器，添加时填四项：名字（下拉框标识）、Host（Tailscale 别名，即 SSH 主机名）、远端目录（相对 HOME 的存代码目录）、默认 Agent。保存后在 ~/.parcels/targets/ 下生成 toml 配置。如果之前用过 bash 原版 parcels，已有的 .conf 配置也能被识别，两个版本可以共存。

体检 Tab 在发送前确认远端环境没问题，第一次配好新机器后强烈建议先跑一遍。它检查三类内容：一是工具是否装齐，tmux、rsync、git、jq、python3 加各家 agent 命令，红色就是没装，去远端用 brew 或 apt 装上；二是鉴权是否就绪，claude 查凭证文件或环境变量，codex、pi、droid 各查对应的 auth 文件，其中 droid 是机器绑定的，要在远端跑一次；三是远端环境信息，包括 SSH 用户和 HOME 路径。出现红色项按提示修，比如 agent 鉴权缺失就 SSH 到远端重新登录。

七、托盘、通知与 MCP 集成

关闭主窗口后 Parcels 缩到系统托盘，后台继续跑。托盘菜单可以重开主窗口、刷新远端状态或真正退出，顶部会显示当前有几个会话在运行，每 30 秒自动刷新。

任务完成或失败会自动通知：在 ~/.parcels/notify.toml 里可以配通用 Webhook 和飞书自定义机器人，macOS 系统通知始终开启、无需配置。发送成功不通知，agent 跑完发成功通知加改动摘要，失败则发失败通知加错误信息。

把构建出的 parcels-mcp 二进制配进 Claude Desktop 或 Cursor 的 MCP 配置后，AI 就能直接调度 Parcels，共 11 个工具，覆盖列出目标机器、发送任务、按模板发送、查状态、体检、查活动、看输出、查历史、列模板、预览同步、拉取同步。你不用记命令，直接说「把这个仓库发到 desktop」「远端改了啥」「拉回来」，AI 自己会调对应的工具。

八、故障排查

提示 tmux session did not survive：agent 启动后立刻崩了。先去体检 Tab 跑诊断，再 SSH 到远端手动执行 agent 命令看报什么错。最常见原因是 agent 没登录，重新执行登录命令即可；其次是会话 ID 不对，在本地先开 agent 跑一会儿再发送。

同步报 rsync 错误：先检查 Tailscale 通不通，再查远端目录权限，网络慢就稍后重试。

通知没收到：系统通知检查 macOS 通知设置里是否放行 Parcels；飞书通知检查 webhook 地址与机器人开关；还可以查 ~/.parcels/parcels.db 的 activities 表有没有记录。

活动一直是运行中：说明 Monitor 没检测到完成信号，可能是输出里没有完成关键词（等 180 秒空闲超时即可）、tmux 会话名不匹配，或者远端 SSH 不通导致巡检失败。

所有数据集中存放：目标配置在 ~/.parcels/targets/，通知配置在 notify.toml，历史、模板、活动数据在 parcels.db（SQLite），HANDOFF.md 在每个仓库根目录。想完全重置，删掉 ~/.parcels 目录，下次启动会自动重建。

如果你也有一台整夜闲着的家用电脑，不妨照着这份手册把它变成自己的 Agent 工位。