---
name: cloud-migration-assistant
description: 云迁移助手。一句话完成跨云迁移全流程：扫描源云资源、智能选型对比、生成迁移报告、自动采购腾讯云 CVM。触发词：云迁移助手、一键换云、帮我换云、换到腾讯云、迁移到腾讯云、阿里云迁腾讯云、从阿里云迁移、AWS迁移腾讯云、Azure迁移、华为云迁移、IDC上云、机房迁移上云、跨云迁移、多云迁移、迁移评估、云迁移评估、迁移方案、上云规划、迁移对比、迁移上云、迁移成本分析、帮我开机、一键迁移、自动采购、直接购买、迁移报告、可视化对比、migration dashboard、cloud migration、migrate to tencent cloud、迁移看板
description_zh: 云迁移助手：联动 MigraQ 技能扫描源云资源并智能选型，生成交互式迁移报告，通过 tccli 一键购买腾讯云 CVM 实例。支持阿里云、AWS、Azure、华为云等多云来源，无需手动操作控制台
description_en: Cloud Migration Assistant — scans source cloud resources (Alibaba, AWS, Azure, Huawei, on-prem) via MigraQ, generates an interactive migration report, and provisions Tencent Cloud CVM instances via tccli (RunInstances) without manual console steps
version: "0.5"
allowed-tools:
  - Bash
  - Read
  - Write
metadata:
  openclaw:
    emoji: 🔄
    requires:
      bins:
        - python3
    permissions:
      - fs:/tmp/
    security:
      data_handling: 本 Skill 不处理任何云凭证，不在本地持久化存储任何用户数据
    os:
      - linux
      - darwin
      - windows
  lightclaw:
    emoji: 🔄
    requires:
      bins:
        - python3
    requires_optional:
      - id: pip-tccli
        kind: pip
        package: tccli
        bins:
          - tccli
        label: "腾讯云 CLI（阶段四 CVM 采购时需要，仅查看迁移报告无需此依赖）"
---

# 云迁移助手

**定位**：云迁移助手，Orchestra 模式，端到端协调三个层次：

```
用户 ↔ Claude (cloud-migration-assistant)
              │
              ├─→ MigraQ SSE API           （阶段一：获取迁移分析）
              │       └─→ JSON export       （阶段二：结构化导出）
              │
              ├─→ generate_dashboard.py     （阶段三：生成迁移报告）
              │
              └─→ provision_cvm.py          （阶段四：CVM 采购编排）
                      ├─→ tccli cvm DescribeImages
                      ├─→ tccli vpc DescribeVpcs / DescribeSubnets
                      ├─→ tccli cvm DescribeSecurityGroups
                      └─→ tccli cvm RunInstances
```

**核心价值**：用户只需一句话（"帮我把阿里云换到腾讯云"/"AWS 迁移评估"/"IDC 机房上云规划"），即可完成从资源扫描、费用对比、迁移报告，到自动开机的全流程——真正的一键换云。

---

## 🎯 何时使用此技能

**触发关键词**：云迁移助手、一键换云、帮我换云、换到腾讯云、迁移到腾讯云、阿里云迁腾讯云、从阿里云迁移、AWS迁移腾讯云、Azure迁移、华为云迁移、IDC上云、机房迁移上云、跨云迁移、多云迁移、迁移评估、云迁移评估、迁移方案、上云规划、迁移成本分析、迁移对比、迁移上云、帮我开机、一键迁移、自动采购、直接购买、迁移报告、可视化对比、migration dashboard、cloud migration、migrate to tencent cloud、迁移看板

**四种使用场景**：
1. **全链路**：扫描 + 报告 + 自动购买（用户说"帮我换云"/"帮我开机"/"一键迁移"）
2. **迁移评估**：扫描 + 报告，不购买（用户说"评估一下我的云迁移成本"/"出个迁移方案"）
3. **报告 + 购买**：已有数据，需要可视化并购买（用户提供 JSON 文件）
4. **仅查看报告**：只需可视化，不购买（演示模式或离线查看）

---

## 🚀 工作流（五阶段全程驱动）

本技能自己负责完整五阶段流程，用户一句话触发。

---

### 阶段零 A：定位并验证 MigraQ

**Step 1：定位 MigraQ 路径**

```bash
MIGRAQ_PATH=$(python3 {baseDir}/scripts/check_env.py --locate-migraq)
```

若退出码非 0，报错：提示用户安装 MigraQ 技能，或设置 `$MIGRAQ_SKILL_PATH` 环境变量指向 MigraQ 目录。

**MigraQ 路径解析顺序**（check_env.py 内置逻辑）：
1. `$MIGRAQ_SKILL_PATH` 环境变量（最高优先级）
2. `~/.lightclaw/workspace/skills/MigraQ`
3. `~/.lightclaw/skills/MigraQ`
4. `~/.workbuddy/skills/MigraQ`
5. `~/.codebuddy/skills/MigraQ`
6. `~/.agents/skills/MigraQ`

**Step 2：调用 MigraQ 自身的环境检测（版本 + AK/SK + 网络）**

```bash
python3 "$MIGRAQ_PATH/scripts/check_env.py"
```

根据退出码处理：详见下方"错误处理"章节。

---

### 阶段零 B：检查 tccli（仅在用户有购买意图时执行）

若用户的描述包含购买意图（"帮我开机"/"直接购买"/"自动采购"/"一键迁移"等），在阶段一之前检查 tccli：

```bash
python3 {baseDir}/scripts/check_env.py --check-tccli
```

| 退出码 | 含义 | 处理 |
|--------|------|------|
| 0 | tccli 已安装且凭证有效 | 继续 |
| 2 | 凭证未配置（auth_error） | 引导用户执行 `tccli configure set` 或完成 OAuth 登录（参考 tencentcloud-infra 技能），用户完成后继续 |
| 3 | tccli 未安装 | 提示 `pip install tccli` 并安装；若用户只想看迁移报告不购买，可跳过此步骤继续 |

**若用户只想查看迁移报告**（无购买意图），跳过阶段零 B，跳过阶段四，完成阶段一至三后即结束。

---

### 阶段一：调用 MigraQ 获取迁移分析

将用户原话原样转发给 MigraQ（**转发铁律：不改写**）：

```bash
python3 "$MIGRAQ_PATH/scripts/migrateq_sse_api.py" '<用户原话>'
```

- 获取 `session_id`（后续阶段必须复用）
- 将 `data.content`（Markdown 分析报告）**完整展示给用户**

---

### 阶段二：同 session 追问 JSON 导出

在**同一 session** 中请求结构化导出：

```bash
python3 "$MIGRAQ_PATH/scripts/migrateq_sse_api.py" '<JSON_EXPORT_PROMPT>' '<session_id>'
```

**JSON 导出 Prompt（固定模板，必须逐字使用，不得改写）**:

```
请将上述选型推荐和TCO分析结果，按照以下 JSON schema 完整导出。只输出纯 JSON，不要包含任何说明文字或 markdown 代码块标记：

{"meta":{"source_cloud":"源云名称","target_cloud":"腾讯云","analysis_date":"YYYY-MM-DD","total_source_cost":0.0,"total_target_cost":0.0,"total_savings":0.0,"savings_pct":0.0},"resources":[{"id":1,"product":"ECS|MySQL|Redis|CDB","source_spec":"规格标识","source_cpu":4,"source_mem":16,"source_region":"地域","source_billing":"包年包月|按量付费","source_cost":0.0,"target_spec":"腾讯云规格或—","target_cpu":4,"target_mem":16,"target_region":"地域","target_cost":0.0,"tier":"A|A'|B1|B2|C|D","confidence":0.98,"match_reason":"匹配原因","status":"ok|partial|error"}]}
```

**JSON 提取规则**：
- MigraQ 返回的 `data.content` 可能包裹在 ` ```json ... ``` ` 代码块中
- 提取时**移除代码块标记**，取纯 JSON 字符串
- 用 `json.loads()` 验证合法性
- 写入 `/tmp/migraq_export_<session_id前8位>.json`

---

### 阶段三：生成迁移报告

```bash
python3 {baseDir}/scripts/generate_dashboard.py \
  --input /tmp/migraq_export_<session_id前8位>.json \
  --output /tmp/migration-dashboard.html
```

- 告知用户 HTML 文件路径，提示用浏览器打开
- 使用**静态模式**（而非 `--serve`），以便 Claude 继续引导阶段四

迁移报告生成后主动询问用户（仅当阶段零 B 已通过，即有购买意图时）：

> "✅ 迁移报告已生成：`/tmp/migration-dashboard.html`
> 共 **N** 台资源推荐迁移，总月费节省 ¥XXX。**是否直接购买这些腾讯云实例？**"

---

### 阶段四：CVM 编排购买（全自动）

#### Step 1：生成购买计划（自动查询镜像/VPC/SG）

```bash
python3 {baseDir}/scripts/provision_cvm.py \
  --plan \
  --input /tmp/migraq_export_<session_id前8位>.json \
  --platform ubuntu
```

脚本自动：
- 筛选 tier in (A, A', B1, B2) 且 status in (ok, partial) 的资源
- 按地域查询公共镜像（默认 Ubuntu 最新版）
- 查询默认 VPC + 子网 + 安全组
- 将计划写入 `/tmp/provision_plan_<hash>.json`

Claude 将计划格式化展示给用户确认：

```
将创建以下实例（共 N 台）：
  ① SA5.XLARGE16  4C16G  上海  包年包月1个月
     镜像: Ubuntu 22.04 LTS
     VPC: vpc-xxx (默认) / subnet-xxx (上海一区)
     安全组: sg-xxx (default)
     月费: ¥216.53
  ② ...
  ③ ...（D 级或 error 状态资源已跳过，共跳过 M 台）

总费用: ¥XXX/月
确认购买？（是/否）
```

#### Step 2：用户确认后执行购买

收到用户确认后，执行：

```bash
python3 {baseDir}/scripts/provision_cvm.py \
  --execute \
  --plan-file /tmp/provision_plan_<hash>.json
```

Claude 汇报结果：
```
购买完成！共创建 N 台实例：
  ✅ ins-abc123  SA5.XLARGE16  上海（¥216.53/月）
  ✅ ins-def456  S5.LARGE8     北京（¥89.00/月）
  ❌ 实例 #3 创建失败: InsufficientBalance（余额不足，请充值后重试）
```

#### `--dry-run` 预览模式

若用户希望先预览命令不实际购买：

```bash
python3 {baseDir}/scripts/provision_cvm.py \
  --execute \
  --plan-file /tmp/provision_plan_<hash>.json \
  --dry-run
```

输出每台实例的 `tccli cvm RunInstances` 命令预览。

---

## 🔧 其他使用模式

### 静态 HTML 迁移报告（单文件 JSON 输入）

```bash
python3 {baseDir}/scripts/generate_dashboard.py --input <file.json>
```

### 动态服务器模式（支持浏览器内一键换云向导）

```bash
# 启动本地服务器，自动打开浏览器
python3 {baseDir}/scripts/generate_dashboard.py --input <file.json> --serve
python3 {baseDir}/scripts/generate_dashboard.py --input <file.json> --serve --port 9090
```

- 浏览器访问 `http://localhost:8080`
- 资源卡片显示 **"🔄 一键换云"** 按钮，提供三步向导（选镜像 → 选 VPC/子网 → 选安全组）
- 需要 `tccli` 已安装并配置凭证

> **注意**：`--serve` 模式会阻塞 Claude 继续对话。主流程（阶段三）使用静态模式，`--serve` 作为可选的独立查看方式。

### 多目标云对比（多份 MigraQ JSON 合并）

```bash
python3 {baseDir}/scripts/generate_dashboard.py \
  --input tencent.json aws.json azure.json \
  --output /tmp/multi-cloud-dashboard.html
```

合并规则：相同 `(source_cloud, product, source_spec, source_billing, source_region)` 的条目自动合并，最低费用目标云标注 🥇。

### 多源云对比

```bash
python3 {baseDir}/scripts/generate_dashboard.py \
  --input from-aliyun.json from-aws.json \
  --output /tmp/multi-source-dashboard.html
```

### CSV 输入

```bash
python3 {baseDir}/scripts/generate_dashboard.py --input <file.csv> --format csv
```

CSV 格式（首行为列头）：
```csv
product,source_spec,source_cpu,source_mem,source_region,source_billing,source_cost,target_spec,target_cpu,target_mem,target_region,target_cost,tier,confidence,match_reason,status
ECS,ecs.g8a.xlarge,4,16,上海,包年包月,468.00,SA5.XLARGE16,4,16,上海,216.53,A,0.98,精确匹配,ok
```

### 演示模式（内置测试数据，无需 MigraQ）

```bash
python3 {baseDir}/scripts/generate_dashboard.py --demo
```

---

## 📊 迁移报告包含的可视化组件

### 1. 顶部仪表盘
- 总资源数 / 匹配成功率 / 总费用节省比例
- 源端月费 vs 目标端月费

### 2. 左右对照卡片（核心）
- 左侧：源端资源（云厂商、规格、CPU/内存、地域、月费）
- 右侧：腾讯云推荐（规格、CPU/内存、地域、月费）
- 中间：匹配等级标签（A/A'/B/C/D）+ 节省金额
- 颜色编码：A 绿色 / B 黄色 / C 橙色 / D 红色

### 3. 费用对比柱状图
- 每种规格的源端/目标端费用并排柱状图（同规格自动合并）

### 4. 匹配等级分布饼图
- 展示 A/B1/B2/C/D 各等级占比

---

## ⚠️ 错误处理

| 场景 | 处理方式 |
|------|---------|
| MigraQ 未安装 | 报错：提示用户安装 MigraQ 技能，或设置 `$MIGRAQ_SKILL_PATH` 环境变量 |
| MigraQ check_env 退出码 2（AK/SK 未配置） | 报错：提示配置 `TENCENTCLOUD_SECRET_ID` / `TENCENTCLOUD_SECRET_KEY` 并 source ~/.zshrc |
| MigraQ check_env 退出码 3（网络不通） | 报错：提示检查网络，确保可达 `https://cmg.ai.tencentcloudapi.com` |
| MigraQ check_env 退出码 4（版本过旧） | 报错：提示前往 SkillHub 更新 MigraQ 后重试 |
| MigraQ check_env 含 `update_available: true` | 透传提示："💡 MigraQ 有新版本可用，可前往 SkillHub 更新"，不阻断流程 |
| MigraQ 调用失败（AuthError/NetworkError） | 透传 MigraQ 错误，提示检查 AK/SK 和网络 |
| JSON 提取失败（非合法 JSON） | 报错：建议重新发起分析或手动提供 JSON 文件 |
| `generate_dashboard.py` 失败 | 报错：显示 Python 脚本错误信息 |
| tccli 未安装（check-tccli 退出码 3） | 提示 `pip install tccli`；若用户不购买则跳过 |
| tccli 凭证未配置（check-tccli 退出码 2） | 引导执行 `tccli configure set` 或 OAuth 登录（参考 tencentcloud-infra 技能） |
| provision_cvm.py auth_error | 透传给用户，引导配置凭证后重试 |
| RunInstances 失败（余额不足等） | 在结果中标记 ❌，提示错误原因，其他成功实例正常汇报 |
| `--serve` 模式端口冲突 | Python 报错：Address already in use，可用 `--port` 指定其他端口 |

---

## 🤝 技能协作关系

### 与 MigraQ 的关系
- **MigraQ**：数据层——远端 Agent 调用、资源扫描、选型推荐、TCO 询价
- **本 Skill**：编排层——可视化展示 + 自动化采购

**互调方式（脚本直调）**：

1. `check_env.py --locate-migraq` 动态找到 MigraQ 路径
2. `$MIGRAQ_PATH/scripts/check_env.py` 自我验证就绪
3. `$MIGRAQ_PATH/scripts/migrateq_sse_api.py` 发起 API 请求

调用 MigraQ 时**必须遵守转发铁律**：用户原话原样传入，不得改写。

### 与 tencentcloud-infra 的关系
- **tencentcloud-infra**：通用腾讯云 CLI 技能，提供 OAuth 登录、全 API 覆盖
- **本 Skill**：内置 `provision_cvm.py`，专门封装 CVM 购买所需的 5 个 API；遇到 auth 错误时引导用户参考 tencentcloud-infra 的 OAuth 流程

### 与 cvm-ai-doctor 的关系
- **cvm-ai-doctor**：单机系统诊断
- **本 Skill**：云迁移编排
- 未来计划：cvm-cluster-doctor 整合两者，提供集群级健康 + 迁移态势感知

---

## 🗂️ 脚本文件说明

| 脚本 | 职责 |
|------|------|
| `scripts/check_env.py` | 环境预检：Python 版本、MigraQ 路径定位（`--locate-migraq`）、tccli 凭证检查（`--check-tccli`） |
| `scripts/generate_dashboard.py` | 迁移报告生成：JSON/CSV → HTML；支持静态（`--output`）和动态（`--serve`）模式 |
| `scripts/provision_cvm.py` | CVM 采购编排：封装 tccli API 调用，生成购买计划（`--plan`）并执行（`--execute`） |

---

**最后更新**: 2026-05-18
**版本**: 0.5
**兼容性**: Linux / macOS / Windows（需要 Python 3.7+）
