carto-arcgis-migration

carto-arcgis-migration

一项技能，可将 ArcGIS Portal / AGOL 端点中的内容迁移到 CARTO。分为三个阶段，按顺序运行，并共用一个事实来源——工作目录中的 MIGRATION_MANIFEST.md：

1. 发现 — 枚举条目、分类并编写清单。参见 references/discover.md。
2. 迁移数据 — Hosted Feature Layers + Hosted Tables → CARTO 表（清单的 Datasets 部分）。参见 references/migrate-data.md。
3. 迁移地图 — Web Maps + 简单的 Dashboard / Web Experience / Web Mapping Application 条目 → CARTO Builder 地图（清单的 Web Maps + Apps 部分）。参见 references/migrate-maps.md。

清单会累积状态——每个阶段都会将条目从 pending 更新为 in-progress，再更新为 done / skipped / failed。重新运行具有幂等性：跳过 done 条目；重试 failed 条目。

访问方式 — 原生 CLI。 迁移是一个批量、脚本化、基于磁盘状态的工作流（磁盘上的清单文件、Python 提取、批量运行 carto）。请在具有真实 shell 的环境中运行（Claude Code、Codex、Antigravity 等）；它无法在仅支持 MCP 的聊天平台（Claude.ai、ChatGPT）上运行，因为这些平台没有文件系统或 Python。它执行的 CARTO 端读取检查——表是否存在的探测、列／几何信息检查、导入——确实有对应的 MCP 工具（execute_query、explore_data describe、import_data），但整体批处理循环、清单台账和 ArcGIS 提取仅支持 CLI，因此该技能会全程使用 carto CLI。有关路由模型，请参见 carto-basics/references/access-paths.md。

前置条件

• carto-skills 插件（此目录）。迁移阶段会将 CARTO 端的具体操作——导入、查询、地图创作——委托给 carto-import-export-data、carto-query-datawarehouse、carto-explore-datawarehouse 和 carto-create-builder-maps。
• 已通过身份验证的 carto CLI（carto auth login），且 carto connections list --json 中至少有一个连接。
• 有权访问 ArcGIS Portal / AGOL 端点，并具备凭据（若 AGOL 完全公开，也可匿名访问）。
• 安装了 geopandas + pyarrow 的 Python，用于数据阶段的 GeoParquet 提取。地图阶段需要 sqlglot 来验证 Arcade 到 SQL 的转换。

路由用户请求

根据用户的请求选择阶段：

用户请求	阶段
“迁移我的 ArcGIS Portal”、“我的 Portal 里有什么”，或只给出 Portal/AGOL URL、未指定条目	发现 (references/discover.md)
“迁移数据集”、“迁移所有数据”，或指定 Hosted Feature Layer / Hosted Table	迁移数据 (references/migrate-data.md)
“迁移地图”、“迁移简单应用”，或指定 Web Map 或简单应用的标题	迁移地图 (references/migrate-maps.md)
“运行完整迁移”	按顺序运行全部三个阶段，并在每个阶段后暂停以供用户审查

如果用户指定了单个条目，请将相关阶段限定为该条目。

顺序很重要

• 任何 migrate- 阶段之前都必须先执行发现。* 清单是事实来源——没有清单时，数据和地图阶段会拒绝启动。
• 先迁移数据，再迁移地图。 Web Maps 和简单应用依赖 Datasets 条目中已解析的 Target FQN。如果 Web Map 的图层引用了尚未迁移的数据集，该 Web Map 会被标记为 failed（Failure: depends-on-unmigrated-data）——地图阶段不会自动调用 migrate-data；用户需要明确了解这一缺口。

始终遵循的规则（适用于整个技能）

• 每次调用 carto 都要传入 --json；每次调用 ArcGIS REST 都要传入 &f=json。
• **发现阶段不要执行迁移。*发现阶段只写入清单。用户审核后，才能运行任何 migrate- 阶段。
• 每次状态转换都要更新清单。批处理中途崩溃时，清单必须反映磁盘上的实际状态。
• 单项失败时绝不终止批次，但 CARTO 认证过期除外（解析 --json 返回的 401/403 → 不处理当前进行中的项目，停止批次，并请用户运行 carto auth login 后重新调用）。
• **保持幂等。**静默跳过状态为 done 的条目。重试状态为 failed 的条目（migrate-data 使用 --overwrite；migrate-maps 先检查标题和标签）。
• 为每个迁移后的地图添加 From ArcGIS 标签，并保留默认隐私设置（私有）。此标签是幂等性预检查和客户侧筛选的唯一依据。
• 随时记录经验教训到 SESSION_LESSONS.md；在批次结束时展示该文件。绝不自动编辑缓存的技能文件——运行时只能读取这些参考文件；由维护者合并上游更改。
• 编写迁移代码前，先查阅相关的 references/*.md。渲染器映射、弹出窗口/Arcade/底图转换、数据集配置要求以及“实战经验教训”都记录在其中；重新发现已有文档记载的特性会浪费用户时间。将 CARTO 平台操作（carto import、carto sql query、carto maps *、carto connections *）交给对应 carto-skill 中经过验证的操作方案，不要猜测参数。