Team Resurrection —— 团队打包 / 搬家 / 分身工具

> 触发： 用户说「我要搬家」「换电脑了」「帮我分身一个团队」「备份团队」等。
>
> 核心理念： 搬家·分身·备份，三合一。
>
> ⚠️ 权限说明：本 skill 会修改 openclaw.json、创建 cron 任务、重启 Gateway。所有敏感操作前自动展示内容供用户确认，确认后全自动执行。allowAgents 使用最小白名单（仅实际成员ID），不使用通配符 ["*"]。
>
> 🔐 安全提示：
> - 搬家包含敏感信息 — pack.py 会打包 MEMORY.md（含个人记忆/偏好）、TOOLS.md（含 API keys、账号、服务器地址）等文件。不要公开分享搬家包，传输时使用加密介质。
> - 务必先 --dry-run — 在新环境运行前，先用 python3 migrate.py 搬家包.zip --dry-run 审查 diff，确认无误后再正式执行。
> - 敏感操作可跳过 — 使用 --no-cron 跳过 cron 创建、--no-restart 跳过 Gateway 重启，逐步验证。
> - 检查 cron payload — 执行前检查 cron_tasks.json 中的 payload 字段，确认不会触发意外操作。
> - 确认备份存在 — 操作前确认 ~/.qclaw/backup/ 下有备份目录，如需回滚可恢复。
> - 低信任环境 — 如对搬家包来源不确定，先逐行审计 pack.py/migrate.py/clone.py，或在隔离环境中测试。
>
> 三大场景：
> - 🚚 搬家 — 换电脑、重装系统，一键把整个团队迁到新环境
> - 👯 分身 — 同环境快速复制一支团队，跑实验、做测试、开新项目
> - 📦 打包 — 备份团队快照，随时可还原

零、快速开始

场景一：搬家（跨环境迁移）

用户（旧环境）：我要搬家
Agent：好的，开始打包...
       [执行 pack.py]
       打包完成：~/一键搬家包/Agent搬家包_YYYYMMDD.zip
       请把搬家包复制到新环境

用户（新环境）：[把搬家包丢给agent] 这是一键搬家包，帮我搬家
Agent：[执行 migrate.py]
       🔒 备份 → 🔧 Main Agent 配置 → 复制身份/成员/skills → 合并配置 → 重启
       ✅ 搬家完成！

场景二：分身（同环境复制）

用户：帮我分身一个团队，后缀用"测试"
Agent：[执行 clone.py]
       检测到 10 人团队 → 备份配置 → 复制 workspace（加后缀）→ 追加配置 → 重启

       原团队：毒舌 / 小策 / 老墨 / ...
       分身：  毒舌-测试 / 小策-测试 / 老墨-测试 / ...
       ✅ 分身完成！

场景三：备份

用户：帮我打一个搬家包
Agent：[执行 pack.py]
       ✅ 打包完成：~/一键搬家包/xxx.zip

一、核心概念

1.1 团队激活三要素

子代理要正确激活，必须同时满足三个条件：

关键发现：
- agentId 控制人格，不控制 workspace
- cwd 才控制 workspace 隔离
- 不设 cwd → 所有子代理读父代理的 workspace

1.2 三大功能对比

1.3 备份与回滚

所有操作前自动备份：
- 目标：~/.qclaw/backup/
- 搬家备份：搬家备份_YYYYMMDD_HHMMSS/
- 分身备份：clone备份_YYYYMMDD_HHMMSS/

回滚方法：

# 搬家回滚
cp -r ~/.qclaw/backup/搬家备份_xxx/* ~/.qclaw/

# 分身回滚（只需还原配置）
cp ~/.qclaw/backup/clone备份_xxx/openclaw.json ~/.qclaw/openclaw.json
openclaw gateway restart

1.4 配置合并策略

核心原则：不覆盖现有配置。

• 搬家（migrate.py）：deep merge（agents/hooks 字段级合并，其他保留）
• 分身（clone.py）：追加新 agent（不触碰原有 agent 条目）
• hooks.allowedAgentIds：取并集

二、脚本说明

2.1 脚本清单

2.2 pack.py（打包脚本）

功能： 自动检测当前 workspace，收集所有资料，生成搬家包

执行方式：

cd skills/team-resurrection
python3 pack.py

输出： ~/一键搬家包/{Agent名称}搬家包_YYYYMMDD_HHMMSS.zip

v2.0 改进：
- ✅ 不再硬编码 workspace 路径，自动检测 active workspace
- ✅ 自动推断 agent 名称（从 SOUL.md/IDENTITY.md）
- ✅ README.md 根据实际内容动态生成

2.3 migrate.py（搬家脚本）

功能： 完整的一键搬家流程

执行方式：

# 基本用法：传入搬家包路径
python3 migrate.py /path/to/搬家包.zip

# 审查模式：只看不做
python3 migrate.py /path/to/搬家包.zip --dry-run

# 跳过危险操作
python3 migrate.py /path/to/搬家包.zip --no-cron --no-restart

# 交互式（在搬家包目录内运行）
unzip 搬家包.zip && cd 搬家包 && python3 migrate.py

参数说明：

执行步骤：

Main Agent 选项：

选项 1：指向现有 agent → 把当前 agent 指向新 workspace
选项 2：新建 main agent 实例 → 创建新目录 + 配置
选项 3：覆盖现有 main agent → ⚠️ 需二次确认

2.4 clone.py（分身脚本）🆕

功能： 在同一环境下复制整个团队，所有 ID/路径加后缀避免冲突

执行方式：

# 交互式（会询问后缀）
cd skills/team-resurrection
python3 clone.py

# 指定后缀
python3 clone.py --suffix "测试"

执行步骤：

分身命名示例：

后缀: 测试

原团队：                    分身：
  毒舌 (agent-ba01c6a8)       毒舌-测试 (agent-ba01c6a8-测试)
  小策 (xiaoce)               小策-测试 (xiaoce-测试)
  老墨 (laomo)                老墨-测试 (laomo-测试)
  ...

workspace:
  ~/.qclaw/workspace-agent-ba01c6a8/
  → ~/.qclaw/workspace-agent-ba01c6a8-测试/

  ~/.qclaw/workspace-agent-ba01c6a8/xiaoce/
  → ~/.qclaw/workspace-agent-ba01c6a8-测试/xiaoce-测试/

冲突检测： 执行前自动检查目标路径是否已存在，冲突则中止（不覆盖）。

三、搬家包结构

搬家包/
├── README.md                    ← 动态生成（含团队成员列表）
├── migrate.py                   ← 一键执行脚本
│
├── 身份层/                      ← Main Agent
│   ├── SOUL.md / MEMORY.md / TOOLS.md / AGENTS.md / IDENTITY.md / USER.md
│   └── memory/
│
├── 团队成员层/                  ← 子代理（自动检测，有则包含）
│   ├── 成员A/SOUL.md
│   └── ...
│
├── skills/                      ← Skills
├── openclaw-agents.json         ← Agent 配置片段
├── cron_tasks.json              ← Cron 任务清单
└── 工作目录说明.md             ← git 工作目录提示

通用化

四、配置文件说明

4.1 openclaw.json 核心配置

{
  "agents": {
    "list": [
      { "id": "main", "name": "Main Agent" },
      {
        "id": "member-a",
        "name": "成员A",
        "workspace": "/Users/xxx/.qclaw/workspace-xxx/member-a",
        "agentDir": "/Users/xxx/.qclaw/agents/member-a/agent"
      }
    ],
    "defaults": {
      "model": { "primary": "qclaw/modelroute" },
      "maxConcurrent": 10,
      "subagents": { "allowAgents": ["*"] }
    }
  },
  "hooks": { "allowedAgentIds": ["member-a", "member-b"] }
}

4.2 关键配置项

五、常见问题排查

问题1：agentId is not allowed

原因： openclaw.json 缺少 allowAgents 白名单

解决： migrate.py / clone.py 执行时自动补上最小白名单（仅实际成员ID），如需通配符请手动修改

问题2：子代理读错 SOUL.md

原因： spawn 时没传 cwd 参数

解决： 必须同时传 agentId + cwd：

sessions_spawn({
  agentId: "member-a",
  cwd: "/Users/xxx/.qclaw/workspace-xxx/member-a",
  mode: "run",
  task: "..."
})

问题3：Gateway 重启后 spawn 报错 unknown channel

原因： Gateway 重启时 channel 注册需要几秒

解决： 重启后等 5-10 秒再 spawn

问题4：分身后 ID 冲突

现象： clone.py 报"目标 workspace 已存在"

解决： 换一个后缀，或手动删除旧分身：

rm -rf ~/.qclaw/workspace-xxx-旧后缀
# 然后从 openclaw.json 中删除对应 agent 条目

问题5：搬家后配置丢失

原因： v1.0 用 config replace

解决： v2.0+ 已修复（deep merge）。回滚：cp -r ~/.qclaw/backup/搬家备份_xxx/* ~/.qclaw/

六、验证清单

搬家验证

• [ ] openclaw gateway status 显示 running
• [ ] ls ~/.qclaw/workspace-*/SOUL.md 找到 SOUL.md
• [ ] openclaw.json 包含所有 agent 配置
• [ ] agents.defaults.subagents.allowAgents 已设置（最小白名单，仅实际成员ID）
• [ ] 测试 spawn 至少 2 个 agent，确认人格正确

分身验证

• [ ] openclaw.json 中同时存在原团队和分身团队
• [ ] 分身 workspace 路径带后缀
• [ ] 分身 agent ID 带后缀
• [ ] 用分身 ID spawn，确认读的是分身 workspace 的 SOUL.md
• [ ] 原团队 spawn 不受影响

七、维护建议

1. 定期打包：重大变更后重新 pack.py
2. 备份保留：至少保留最近 3 次备份
3. 分身清理：实验完成后删除分身 workspace + 从 openclaw.json 移除条目
4. 日志记录：所有配置变更记录到 memory/YYYY-MM-DD.md