carto-create-builder-maps

carto-create-builder-maps

CARTO Builder 是一款制图工具，可根据 JSON 地图配置渲染交互式地图。本技能涵盖完整的编写流程：通过自然语言创建、编辑数据集／图层／小组件／弹出窗口／隐私设置、发布快照供共享查看者使用、离线验证，以及管理地图资产。它还涵盖跨配置文件复制（dev → prod 晋级、通过 carto maps copy 按客户隔离的组织交付）——请参阅下方的 跨组织晋级／复制 参考资料。

访问路径选择。 下方的各个阶段、制图规则和配置指南与访问路径无关——无论采用哪种方式，编写的 JSON 都相同。只有传输方式不同：

操作	MCP（已连接时优先使用，OAuth）	CLI
列出／获取／搜索地图	read_maps (list | get)	carto maps list / get
创建／编辑／发布	create_map、update_map (update | update_dataset | publish)	carto maps create / update / publish / datasets update
离线验证	validate_map (validate)	carto maps validate
在数据仓库中进行预检（SQL 试运行、渲染、Agent）	validate_map (verify)	carto maps verify-remote
Bundle 架构（字段／枚举／调色板目录）	validate_map (schema)	carto maps schema
AI Agent 状态／模型／工作流 MCP 工具	admin_carto (agents_status | list_agent_models)、read_workflows (list_mcp_tools)	carto maps agents status / models / mcp-tools
删除	delete (kind=map)	carto maps delete
内联预览（仅限 MCP-Apps 宿主）	view_map (mapId) — 参阅 carto-preview-builder-map	—（CLI 无法内联渲染；可使用 screenshot 生成 PNG）
检查数据集	explore_data (describe)	carto connections describe
SQL 探查	execute_query	carto sql query
先导入文件	import_data (submit | status)	carto import

仅 CLI 支持——MCP 无对应功能： carto maps agents core-tools、carto maps screenshot（PNG 渲染）、carto maps copy（跨配置文件晋级和同一组织内复制）。这些操作、脚本化／批量编写，以及服务器未连接时，请使用 CLI。

令牌与 OAuth。 使用 API 令牌时，MCP 会话仅开放读取／发现功能子集（仍可使用 validate_map、view_map、explore_data、execute_query；create_map / update_map / delete 不可用）——请通过 CLI 编写内容，或重新使用 OAuth 连接。在沙盒化聊天宿主（Claude.ai、ChatGPT）上，CLI 完全无法运行——MCP 是唯一可用的实时路径。检测信号：carto-basics/references/access-paths.md。

如需临时探索空间 SQL，请使用 carto-query-datawarehouse。

字段结构、枚举值、调色板目录和 AI 工具目录由 validate_map (schema) / carto maps schema [section]（JSON Schema，由 Tier-1 验证使用的同一套 Zod 定义生成）、admin_carto (list_agent_models) / read_workflows (list_mcp_tools) / carto maps agents models / mcp-tools / core-tools（AI 接口），以及 explore_data describe / carto connections describe <conn> <table>（数据集元数据）提供——切勿硬编码或自行假定。本文档与 CLI／架构不一致时，以架构为准。

参考文档

决策与方向——请先阅读

• references/cartography.md — 样式设计前的制图决策：配色方案类型、比例尺类型、底图搭配、多图层色相区分、反模式。涉及样式设计时，编写 JSON 前必须阅读。
• references/configuration-shape.md — 带注释的 JSON 框架。keplerMapConfig 顶层结构、datasets[] 条目（表 / 查询 / 瓦片集 / 栅格）以及 mapSettings 规则。
• references/examples.md — 经实际组织验证可用的模板：最简地图、H3 聚合、SQL 参数、组件库。需要 JSON 模板作为起点时加载。

按组件查阅——编写时按需参考

• references/layers.md — 各图层类型的编写方法：tileset（点 / 线 / 多边形 / 3D）、h3、quadbin、heatmapTile、clusterTile、raster。还包括颜色范围（调色板 / 比例尺 / /stats）、描边样式（lineStyle 实线 / 虚线 / 点线）、多边形填充图案（fillPatternEnabled + fillPattern）以及适配底图的对比度。
• references/widgets.md — 分析界面：formula、category、pie、histogram、range、timeseries、table。排序、可折叠默认设置、跨数据集交叉筛选。
• references/interactions.md — Builder 的交互面板：popupSettings 涵盖工具提示弹窗（悬停 / 点击）、信息面板（停靠侧栏，仅点击）以及点击筛选（featureFilterScope）。悬停最多支持 5 个字段（Builder 编辑器限制，未经过验证），包含内联 CSS 的自定义 HTML 模板，以及渲染器会清除的内容。
• references/formatting.md — 数字格式：组件 formatter 的预设 ID、弹窗字段和表格列的 d3 格式代码，以及双向映射各选项的表格。
• references/sql-parameters.md — Category、DateRange、Numeric、NumericRange。{{paramName}} 占位符编写方式及提供方原生方言转换。
• references/basemap.md — 将 basemapConfig.styleId 和 mapStyle.styleType 都设为相同的值（截图引擎和查看器 SSR 目前仍读取 mapStyle）。CARTO 底图 / Google Maps / 自定义底图库。
• references/agent-config.md — 地图上的 Agent（选择启用）。组织状态检查、模型选择、MCP / 核心工具目录、由功能驱动的启用方式。

操作 / 排除故障

• references/updates.md — CRUD 生命周期：配方、keplerMapConfig 的局部更新与整体替换规则（最常见的破坏性陷阱）、--datasets-mode、发布串联、验证手段。
• references/troubleshooting.md — 症状 → 修复对照表、应避免生成的反模式、遇到阻碍时的应急方法，以及通过 carto maps screenshot 进行视觉验证。

推广 / 跨组织复制——在配置文件之间迁移地图时阅读

• references/cross-profile-copy.md — maps copy 的工作机制、连接映射（--connection-mapping / --connection）、--skip-source-validation，以及哪些内容会转移、哪些不会。
• references/agent-migration-caveats.md — 将含有 AI Agent 的地图复制后出现的 UNAVAILABLE_MODEL / UNAVAILABLE_TOOL 问题、CLI 无法自动修复的原因，以及 Builder 中的手动操作步骤。
• references/post-copy-validation.md — 确认目标地图是否正确渲染：数据集、连接、Agent 问题以及目标 URL 的构建。

编写流程

每次收到“创建地图”请求时，都要按顺序完成以下阶段。跳过某个阶段是导致*“地图在 Builder 中显示异常”*的最常见原因。为方便说明，命令以 carto … 的形式展示；连接 MCP 服务后，请使用上述路由表中的对应工具（create_map / update_map / validate_map / read_maps、explore_data、execute_query、import_data）——JSON 负载相同。

阶段 1 — 收集上下文（准入关卡）

这一阶段是必经关卡，而非建议。但顺序很重要：只有数据才能限定哪些问题有答案。在了解表中有什么之前询问用户的抽象偏好（受众、模式、组件、共享方式），会产生通常不适用的泛泛问题，还会让用户替 Agent 完成将需求映射到列的工作。

顺序

1. 目标 — 一句话。 “这张地图的主题是什么？要传达什么结论？” 没有答案就不要继续；如果 X 足够具体，“就做一张关于 X 的地图” 也可以。

2. 数据提示 — 一句话。 “数据在哪里——你已有的表、演示数据集，还是要导入的文件？” 继续之前，先确定具体的表 FQN。演示数据：按主题搜索 carto-demo-data.demo_tables。文件：先运行 import_data（MCP）/ carto import（CLI）。

3. 静默检查数据。 在询问其他问题之前：

   • explore_data describe / carto connections describe <conn> <table> → 架构、行数、几何类型（point / line / polygon / h3 / quadbin / raster）。
   • 对以下内容运行 execute_query / carto sql query：候选 colorField 列的 NULL 占比；与目标相关的数值列的 min/max/p50/p95/p99；候选分类列的 COUNT(DISTINCT ...)，以发现基数陷阱；时间列的日期范围。
   • 检查最多执行一到两个查询。 不要审查每一列，只检查与用户目标相关的内容。

4. 现在，基于数据提问。 只询问数据能给出答案的问题。以下是基于数据的好问题与过早提出的抽象问题示例：

   不好（抽象，问得太早）	好（检查数据后再问，基于数据）
   “想要组件吗？”	“我看到 capacity_repd_mwp（总和约为 13 GW）和 repd_status（5 个类别）——要不要添加容量总计和状态细分组件？”
   “要分析型还是制图型？”	“该表有 23 列，包括投运日期、区域和容量，适合做分析型地图——建议添加容量直方图，还是保持简单？”
   “公开还是私有？”	（共享方式与数据无关；相关时再清楚地询问——绝不要在第一轮就问）
   “要哪种配色？”	“有 26.5 万个设施，点会严重重叠——建议降低不透明度并使用统一颜色，还是按容量着色（长尾分布 → 对数刻度）？”

   如果数据本身就能回答某个问题，就不要问——直接决定：

   • 几何类型 → 静默决定图层类型：polygon / line / point → tileset；已建立索引的 h3 / quadbin → 直接使用 h3 / quadbin；raster → raster。
   • 视口 → 使用数据的边界框。
   • 候选 colorField 的 NULL 占比 > 25% → 静默切换列，或使用 WHERE col IS NOT NULL 进行筛选。参见 cartography.md §4.5a。

5. 共享 / 受众 / Agent — 仅在出现触发信号时询问。 不要将这些问题设为首次渲染地图的前置条件。默认设为 private。当用户说*“与团队共享”、“发给我的 CEO”、“添加 AI Agent”*时，再提出相关问题。

技术前提（静默处理——仅在未满足时说明）

• 访问已就绪。 在 MCP 中，确认工具列表里有地图工具（如果只显示 validate_map / view_map，则会话通过令牌进行身份验证——请通过 CLI 编写，或通过 OAuth 重新连接）。在 CLI 中，运行 carto auth status；如果未通过身份验证，则使用 carto auth login --no-launch-browser 并停止。参见 carto-basics/references/access-paths.md。
• 组织 AI 状态（仅当用户提到地图上的 Agent 时）。admin_carto（agents_status）/ carto maps agents status——如果 enabled: false，则放弃 Agent 方案并告知用户。

时间预算

首版目标： 从用户说“开始”到生成可用 URL，耗时约 30 秒。若用户只提供目标和数据提示，Agent 静默检查，即可达成。首张地图仍须美观——cartography.md 中的制图默认设置（配色系列、比例尺、底图搭配、多图层色相区分）从第一版起就适用；自定义范围、替换配色、调整组件等完善工作将在后续轮次中进行，让用户查看结果后再调整。

阶段 2 — 制定制图决策

如果涉及样式设置，请在编写 JSON 前阅读 references/cartography.md。输出配置前，明确说明以下选择：

• 图层类型，根据数据特征选择（点 / 线 / 多边形 / h3 / quadbin / 热力图 / 聚类 / 栅格）。
• 配色系列（定性 / 顺序 / 发散）——根据叙述重点和底图选择，不要凭惯性选择。
• 比例尺类型——根据数据形态和含义选择，不要凭惯性选择。默认选择路径：具有语义标记的有界值（0–100 分数、%、比率）→ quantize，或在自然标记上使用 custom + colorRange.colorMap（不接受 colorDomain）；跨越多个数量级的重尾数据 → custom + uiCustomScaleType: "logarithmic"；偏斜且无界、查看者关注排名而非量级的数据 → quantile（这是适用场景，不是稳妥的默认值）；看似类别的整数 → 转换为 STRING + ordinal。参见 references/cartography.md §3.2——quantile 并非通用的稳妥默认值；在 ENERGY STAR、年龄、% 等有界值上凭惯性选择它，是最常见的比例尺选择错误。
• 底图（默认使用浅色 positron / dark-matter / voyager / Google 变体 / 自定义）。
• 多图层色相区分，有多个图层时使用（每个图层选用不同配色系列，而非使用同一色带的不同色阶）。

仅在纯结构性工作（重命名、替换数据集、更改隐私设置、编辑 Agent 配置、调整 mapSettings）时，才可跳过提前进行的制图设计。

阶段 3 — 编写配置

参照 references/configuration-shape.md 中的框架。填写以下内容：

• datasets[] — 连接、来源、geoColumn、类型、格式。对于 h3 / quadbin 图层，请参照数据源选择标准（动态分箱与预构建 tileset）。
• keplerMapConfig.config.visState.layers[] — 类型 + visualChannels + visConfig（参见 layers.md）。
• 如果用于分析，则填写 keplerMapConfig.config.widgets[]（参见 widgets.md）。
• 对于可识别要素的数据集，默认填写 keplerMapConfig.config.popupSettings.layers（参见 interactions.md）。
• 如果支持筛选，则填写 keplerMapConfig.config.sqlParameters[]（参见 sql-parameters.md）。
• keplerMapConfig.config.basemapConfig + mapStyle — 两者都要填写，并设为相同的值（参见 basemap.md）。
• 仅当用户明确提出要求且组织已启用 AI 时，才填写 agent 块（参见 agent-config.md）。

第 4 阶段 — 离线验证

validate_map（MCP）/ carto maps validate map.json（CLI）。Tier-1 会检查结构、类型、枚举值、交叉引用、Agent 字段、aggregationExp 一致性、隐私强制转换，以及十余条跨字段规则（规范的 visualChannels 路径、自定义标记配对、弹窗结构等），全程无需调用后端。反复调整，直到验证通过。

第 5 阶段 — 创建并验证

create_map（MCP）/ carto maps create < map.json（CLI）。两者都会运行 Tier-1 检查，并在 POST /maps 之前，针对每个数据集执行 SELECT … WHERE 1=0 数据源可访问性探测，因此损坏的数据源不会创建孤立地图：Tier-1 问题、带有 detail 的 SOURCE_INACCESSIBLE / COLUMN_NOT_FOUND 警告，以及针对新数据集的瓦片服务器 4xx 错误，都会导致写入被拒绝。探测会自动排除合成的 _carto_* 列，以及从 aggregationExp 中解析出的聚合后别名，因此使用 h3 / quadbin / heatmapTile / clusterTile 进行合理创作不会触发此检查。创建后，进行视觉验证：在 MCP-Apps 主机上，view_map <id> 可内联预览；在 shell 中，carto maps screenshot <id> 可渲染 PNG — 决策标准请参阅始终生效规则中的 “视觉验证”。

第 6 阶段 — 发布（准备好让查看者查看时）

创建操作会生成私有草稿。要让地图对用户预期的受众可见：

• 设置 privacy，优先使用 policies（{type:"organization"}、{type:"public"}、{type:"user"|"group", id}；public 还需要 organization）；旧版 privacy + sharingScope 形式仍然有效。两种形式择一发送，不要同时发送。
• 首次分享会发布地图；再次将其设为私有则会取消发布。后续编辑后，发布以刷新共享查看者 / 公开查看者看到的快照：使用 update_map（method=publish）/ carto maps publish <id>，或使用串联编辑和发布的命令 carto maps update <id> --publish。

成功发布后，告诉用户 “查看者现在可以看到地图了”；否则，请明确说明这些编辑只有用户自己可见。

---

始终生效的规则

这些规则适用于每项任务，而不仅仅是创建流程。

先了解意图 — 隐去实现细节

在第 1 阶段收集信息时（以及之后的每一轮跟进中），始终使用通俗语言。第一轮不要提及 dataId、geoColumn、tilejson、keplerMapConfig、connectionId、FQN 语法或图层类型分类 — 这些内容读起来像规格说明，会让用户替你完成工作。用用户熟悉的说法来组织每个问题：“地图是关于什么的”、“谁会查看”、“查看者是否应该能够筛选”、“应该如何分享”。在脑中将这些内容转换为 JSON；不要让用户来转换。

悄悄处理，不要询问

• 访问权限 — 在执行第一个会调用 API 的命令之前，确认 MCP 地图工具可用（或在 CLI 中运行 carto auth status）。
• 连接 UUID + FQN 语法 — 用户说出表名后，通过 explore_data（list_connections / describe）或 carto connections list / describe 进行解析。不要让用户手动输入 project.dataset.table。
• 导入——用户提供的是文件而非表时 — 如果用户提供了地理空间文件的路径 / URL（CSV / GeoJSON / GeoPackage / GeoParquet / KML / KMZ / Shapefile-zip，≤ 1GB），先通过 import_data（MCP）/ carto import --file <path>（或 --url <url>）--connection <name> --destination <fqn>（CLI）将其导入为数据仓库表，然后再基于导入的表构建地图。默认做法：选择一个连接（如果存在用户的主要 CARTO Data Warehouse，优先选择它），并选择一个能反映文件基名的合适目标 FQN。默认等待导入完成；只有多 GB 的加载才在后台运行（--async / 通过 import_data 轮询状态）。不要让用户转换格式——导入器支持全部 7 种格式。
• 图层类型 — 根据数据集的结构推断：
  • 线 / 面源数据 → tileset。
  • 点源数据，稀疏 / 要素级（查找某家门店、点击缩放）→ tileset。
  • 点源数据，密集 / 大型（典型的聚合场景）→ 聚合为 h3 或 quadbin（h3 = 六边形视觉效果，quadbin = 正方形 + 随缩放级别自适应的单元格大小）。对于大型点表上“X 集中在哪里？”/“Y 的密度”这类问题，这是合适的默认选项——便于定量解读，可在不同视口间比较，且不会受到逐行渲染预算的限制。
  • 预先索引的 h3 / quadbin 源数据 → 直接使用 h3 / quadbin。仍需在数据集上设置 aggregationExp：只有 dataset.type: "tileset" 无需设置，而预先索引的 table / query 不在此列。参见 configuration-shape.md “空间索引（H3、quadbin）”。
  • 按波段存储的栅格 → raster。
  • heatmapTile 和 clusterTile 并非默认选项——仅当用户明确要求“热力图”/“聚类点”，或者叙述明确要求展示不含数值的模式（heatmapTile），或展示可缩放至单个点的数字气泡（clusterTile）时，才选择它们。对于其他密集点数据，默认聚合为 h3 / quadbin——它们能保留定量解读，而热力图会模糊数据，聚类则会将其转化为气泡计数。 只有当用户确实难以在要素级（tileset）和聚合（h3 / quadbin）之间做出选择时才询问，例如："单个商店的位置，还是整个城市的密度？"。
• 视口 — 以数据的边界框为中心（CLI 会在创建时计算）；不要询问纬度／经度／缩放级别。
• 图例和分类域 — CLI 会获取 /stats 并自动填充图例。
• colorField 数据形状探测 — 将数值列绑定到 colorField（或 sizeField / radiusField / heightField）之前，使用单行 execute_query / carto sql query 探测 NULL 比例（SELECT COUNT(*), COUNT(col) FROM source）。如果超过 25% 的行是 NULL，地图在渲染时会以灰色为主——这与分类基数陷阱属于同一类问题。可采用两种修复方式（无需询问用户）：在源 SQL 中添加 WHERE col IS NOT NULL 进行过滤，或选择数据更完整的列。详见 references/cartography.md §4.5a 中的完整示例。对于现有地图的往返修改（用户已选择该列）以及小型数据集（< 1k 行——该陷阱不会明显显现），跳过探测。
• 弹出窗口 — 默认生成，前提是数据集包含可识别要素的列（name / id / address / owner / timestamp）。最终用户无法查阅源表——弹出窗口（或次选的 table 小组件）是他们读取每个要素属性的唯一方式。没有弹出窗口和 table 小组件的地图只会向用户显示颜色和位置；要素的其他信息对他们都不可见。悬停时添加 2–4 个标识列，点击时显示其余列。仅在纯模式地图中跳过（热力图、密度 h3 / quadbin，其中读取的是聚合数据，而非单个要素）。
• 小组件 — 分析型地图默认建议添加，数量按使用场景确定（而非固定数量）：
  • 纯制图地图：0 个小组件。
  • 运营／“查找此要素”地图：1–2 个（主要是 table）。
  • 探索型分析地图：3–6 个（公式 + 类别／饼图 + 直方图 + 时间序列 + 范围 + 表格）。
  • 仪表板地图：6–8 个。超过约 8 个后，面板会显得拥挤。
• SQL 参数 — 源数据存在自然筛选维度时建议添加（日期范围、区域、类别）。连接 {{paramName}} 占位符、一个 sqlParameters[] 条目以及 mapSettings.sqlParameterControls: true。源数据静态时跳过。
• 描述的位置。 描述会与小组件显示在同一个右侧面板中，因此其位置由 widgetsPanelLayout.placement 决定：浮动在地图上的卡片，或停靠的栏列。简短描述适合浮动显示；较长描述或包含表格的描述更适合停靠显示。若在加载时打开描述，设置 uiState.descriptionPreview: true，让查看者看到渲染后的内容，而非编辑器。
• 描述 — 面向查看者的 Markdown，可选。 空描述或省略描述时，查看者完全看不到描述（描述为空时，右侧栏的信息按钮会隐藏）；对于参考地图或没有故事可讲的地图，留空即可。如果确实要生成描述，就写得丰富些——右侧栏的纵向空间充足，精心编写的描述读起来就像地图的小型落地页。完整模板见 references/cartography.md §6.4（可选主图 → ## 标题 → 引言段落 → 可选的 ### 背景、### 当前所见、### 试试看），以及其中关于不使用表格／不添加 ### 来源 的规则和 NYC PLUTO 完整示例。不要将描述用于编写备注、Agent 推理或变更历史。若选择不生成描述，设置 description: ""（空字符串，绝不能为 null——null 会显示占位文本）；maps create 会自动填入 ""，而 maps update 必须显式设置 "" 才能清除描述。

仅在用户明确提出要求时才输出的可选区块

不要主动提供，也不要在 “我还能做些什么？” 中列出，除非用户明显在探索：

区块	仅在以下情况下输出……
agent	用户要求在地图上添加 Agent。先运行 admin_carto（agents_status）/ carto maps agents status；如果已禁用，则不添加。
privacy（非私有）	用户要求共享。默认保持私有。
tags / description	用户提供了这些内容，或地图正在对外发布。
collaborative	用户要求组织中的其他成员也能编辑，而不只是查看。
自定义调色板 / 3D / 自定义标记	用户要求特定样式，或默认样式不合适。

图层堆叠顺序是反向的——存在 layerGrouping 时由它控制

visState.layers[0] 会渲染在最上层，这与标准 deck.gl 相反。按前景优先的顺序编写几何图形：点和线位于多边形之上，多边形位于 h3 / quadbin / heatmapTile / clusterTile 单元之上，单元位于栅格之上。最常见的问题是背景多边形遮住下方的要素，导致地图看起来是空的，尽管所有数据集都已正常加载。

堆叠顺序的设置方式取决于地图：

• 存在 config.layerGrouping（每张从 Builder 保存的地图都有此项）：树的顺序就是渲染顺序，第一项位于最上层。单独调整 visState.layers 不会改变屏幕上的显示效果；树中缺少的图层会追加到最底层。调整树的顺序，并将新图层的条目插入到正确的堆叠位置。
• 不存在 layerGrouping（新建的 bundle）：visState.layers 的顺序就是渲染顺序。

让 visState.layers 与树保持相同顺序，确保两者显示一致。不要输出 visState.layerOrder。 只有不存在树时，Builder 才会将其视为图层索引（而不是 ID）读取；它的存在还会关闭 CLI 的写入前堆叠警告。该警告只识别特定的几何图形组合，也不会检查 layerGrouping——请正确编排顺序，不要等着被纠正。完整规则见：references/layers.md（图层堆叠顺序，第一节）和 references/cartography.md §1.8。

写入前进行验证

组装好地图配置后，如果想在调用 API 前进行离线检查，可以运行 carto maps validate <map.json>。它执行与 create 相同的 Tier-1 检查，但不会调用后端。反复迭代或将 JSON 交给用户时很有用。

写入后重新加载 Builder

每次写入都会在服务端接受更改后立即返回。Builder 只会将地图加载到内存中的客户端状态一次，且不会订阅服务端事件，因此已打开的 https://<org>/builder/<id> 标签页会继续显示过期状态，直到重新加载。对于远程 / 外部 Agent（claude.ai 上的 Claude、ChatGPT、MCP 客户端，以及任何无法访问本地浏览器的工具）：请告知用户：“地图已更新。重新加载 Builder 标签页（Cmd/Ctrl+R）以查看更改。”

视觉验证——根据地图形态决定（无需询问）

验证实际渲染效果——第 1 层级和源代码／渲染检查无法发现配色对比度、图层遮挡或标签碰撞问题。有两种方式：

• MCP-Apps 宿主（Claude.ai、Claude Desktop、ChatGPT）：view_map <id> 会在对话中内嵌预览地图——无需使用 shell。优先使用此方式。
• Shell（编码环境）：carto maps screenshot <id> 会渲染 PNG；将其内嵌展示，让用户看到最终效果。light 引擎（默认，约 8 秒，仅渲染 deck 图层和底图）与 full（--render-engine full，约 20 秒，另外渲染组件和图例）。完整标志参数说明见 references/troubleshooting.md。

不要问“要截图吗？”——用户无法判断延迟。根据地图形态决定，然后直接运行。

**需要验证的情况：**Agent 创建了非简单地图（3 层或更多图层、自定义配色／标记、复杂组件、3D、自定义底图）；用户反馈地图空白／有误；公开发布前。**可以跳过的情况：**仅编辑元数据；对已验证地图进行小幅调整；用户在已打开的 Builder 标签页中快速迭代。

**引擎选择（截图）：**优先使用速度更快的 light；验证组件或图例时使用 full（它们不会在 light 中渲染）。弹出窗口（悬停／点击／信息面板／自定义 HTML）两种引擎都不会渲染——请在 Builder 中验证，而不是查看截图。

keplerMapConfig 是整体替换，而非部分合并

更新时，大多数顶层字段都支持部分补丁：title、description、tags、collaborative、agent、datasets。但 keplerMapConfig 不支持。privacy 也不适合进行部分补丁：任何隐私设置块都会重写地图的共享设置；{"policies": []} 或 {"privacy": "private"} 会撤销所有共享并取消地图发布（参见 updates.md）。将 {keplerMapConfig: {config: {basemapConfig: {...}}}} 作为“部分更新”发送，会清除图层／组件／sqlParameters／视口。要更改 keplerMapConfig 内的任何内容，请使用读取－修改－写入流程：读取完整配置（read_maps get / carto maps get <id> --json），进行编辑，然后发回（update_map / carto maps update <id>）。这两种路径都会在执行前拒绝可能导致清除数据的部分更新；完整合并矩阵见 updates.md。

不要根据标题臆造地图 ID

如果用户用名称／标题而不是 UUID 指代地图：

1. read_maps（使用提示词筛选列表）／carto maps list --mine --search "<hint>"——缩小范围，仅显示与提示词匹配且属于用户自己的地图。
2. 恰好匹配一个 → 使用其 id，并在写入前确认。
3. 匹配多个 → 列出它们的 ID 和标题，询问用户要选哪一个。
4. 没有匹配项 → 询问用户是否要创建新地图。

未经用户确认，绝不要选中某个匹配项并写入；也绝不要仅根据标题编造 UUID。

用户要求时再查阅规范

如果用户说 “给我看看 JSON”／“我自己来写”／“模式是什么”，请打开 carto maps schema 和 configuration-shape.md。否则，围绕用户的地图展开对话，而不是我们的地图。

---

速查表

要做的事几乎总是以下三种之一（MCP 工具 / CLI 命令）：

我想要……	执行此操作
根据自然语言请求创建地图（最常见的路径）	收集所需输入（阶段 1），仅使用这些输入生成配置 → create_map / carto maps create < map.json
编辑现有地图——添加数据集、更新图层样式、更改隐私设置、重命名或更换底图	update_map / carto maps update <id> < partial.json（部分 PATCH；未提及的字段会保留，但 keplerMapConfig 会被整体替换）
复制现有地图	读取配置（read_maps get / carto maps get <id> --json），编辑后重新创建

每次创建 / 更新时，都会自动运行渲染、数据源和 Agent 检查。大多数问题会显示为警告，但若数据源检查失败并返回 detail，或瓦片服务拒绝新数据集，就会阻止写入——无需单独执行“验证能否渲染”步骤。

最常用的命令（CLI；MCP 对应项见顶部的路由表）

carto maps list --mine                            # browse (MCP: read_maps list)
carto maps get <id> --json                         # read a config (MCP: read_maps get)
carto maps validate [map.json]                     # Tier-1 sanity check (MCP: validate_map)
carto maps create [map.json]                       # new map (MCP: create_map)
carto maps update <id> [patch.json] [--publish]    # partial update / publish (MCP: update_map)
carto maps publish <id>                            # freeze a snapshot (MCP: update_map method=publish)
carto maps schema [section]                        # JSON Schema reference (MCP: validate_map method=schema)
carto maps agents status                           # is CARTO AI enabled? (MCP: admin_carto method=agents_status)
carto maps screenshot <id>                         # PNG render (CLI-only; MCP-Apps: view_map)

内联示例

复制现有地图——这是生成可用地图最可靠的方法；数据源配置本来就是 Builder 格式，因此不会遇到部分图层陷阱。

carto maps get <source-map-id> --json \
  | jq '.title = "My copy" | del(.id, .privacy)' \
  > new-map.json
carto maps create < new-map.json

仅更新标题（部分 PATCH）：

echo '{"title":"Better title"}' | carto maps update <map-id> --json

向现有地图添加一个数据集（合并模式会保留现有数据集）：

carto maps get <map-id> --json > current.json
jq '.datasets += [{"$ref":"extra","type":"table","source":"proj.ds.new_table","connectionId":"<conn-id>","geoColumn":"geom","columns":["geom"],"format":"tilejson","label":"New source"}]' current.json > updated.json
carto maps update <map-id> --json < updated.json

替换所有数据集（具有破坏性——输入中未包含的数据集会被删除）：

carto maps update <map-id> --datasets-mode replace --json < map.json

更新单个数据集的源 SQL（不会有清除 keplerMapConfig 的风险）：

carto maps datasets update <map-id> <dataset-id> --source "SELECT geom, revenue FROM stores WHERE country = 'ES'"

更多示例（完整 JSON 配置包），请参阅 references/examples.md。

---

不确定时

• 字段未知 / 可疑？ validate_map（架构） / carto maps schema [section] 会返回权威 JSON Schema。
• 地图显示空白 / 异常？ 请参阅 references/troubleshooting.md 中的症状→修复对照表。
• 需要直观检查？ 在支持 MCP-Apps 的主机上内联使用 view_map <id>，或在 shell 中使用 carto maps screenshot <id>（PNG）。
• AI Agent 界面？ 在 MCP 上使用 admin_carto（agents_status | list_agent_models）和 read_workflows（list_mcp_tools）；在 CLI 上使用 carto maps agents status / models / mcp-tools / core-tools（core-tools 仅限 CLI）。
• 写入后卡住了？ 告诉用户重新加载 Builder 标签页——Builder 不会订阅服务端事件。