carto-develop-app

carto-develop-app

根据提示词生成可运行的 CARTO + deck.gl 应用。确定四项选择——应用类型、框架、认证模式、数据形态——然后组装图层、组件、筛选器、输入项、图例，以及（可选的）嵌入式地图 Agent。

应用遵循 CartoDB/deck.gl-examples 蓝图。图层来自 @deck.gl/carto；数据源、组件、筛选器、fetchMap、query() 来自 @carto/api-client（数据源在 v0.4.0 中已从 @deck.gl/carto 移出——不要从那里导入）。

访问方式。 这是 CLI 路径技能：搭建和运行应用需要真实的 shell 和开发环境（npm、Vite），而且没有 MCP 工具可以生成应用，因此无法在沙盒聊天主机（Claude.ai、ChatGPT）上运行。只有凭证和发现步骤有对应的 MCP 工具：通过 OAuth MCP 会话，使用 manage_api_access_tokens 创建令牌，使用 manage_oauth_clients 创建 OAuth/M2M 客户端，并使用 read_maps / read_workflows 发现地图/工作流 ID。其他所有操作都需要 shell。路径检测：carto-basics/references/access-paths.md。

何时使用

• “deck.gl 应用”“CARTO 应用”“地图应用”“空间仪表板”——使用此技能。
• 已提供 Builder 地图 ID → fetchmap.md。
• Storymap / 滚动叙事 / 叙事地图 / 引导式导览 → storymap.md（基于下方的 React 脚手架进行组合）。
• 地图对话 / 嵌入式 AI Agent → agentic-variant.md。
• 在 Builder 中创作地图 → carto-create-builder-maps。跨组织/配置文件迁移 Builder 地图 → cross-profile-copy.md。

运行模式——默认自主运行

通过 CARTO CLI 生成环境变量。不要向用户提问。 传入 --json 并解析。

运行，然后写入 .env：

carto auth status --json                  # → tenant_id (region) → apiBaseUrl
carto connections list --json             # → connectionName (default: carto_dw)

# One token, ONE grant per source — repeat --connection alongside every --source.
carto credentials create token --json \
  --connection <connectionName> --source <fully.qualified.table.A> \
  --connection <connectionName> --source <fully.qualified.table.B> \
  --apis sql,maps \
  --referers 'http://localhost:5173*,<production-origin>*'

一个令牌，多个授权——而不是每张表一个令牌。--connection 和 --source 按位置配对，因此每个 --source 都要重复指定 --connection。使用 --referers（复数 CSV）；重复使用 --referer（单数）会覆盖之前的值。Referer 会与浏览器的完整页面 URL 进行通配符匹配，因此每个模式都要以 * 结尾（仅写 http://localhost:5173 将无法匹配浏览器实际发送的 http://localhost:5173/）。--apis 和授权彼此独立：maps 覆盖数据源/图层，sql 覆盖 query()，而 *QuerySource 需要在授权中包含其查询——请参阅 auth-public-token.md。

私有应用需要将令牌命令替换为 carto credentials create spa --json（OAuth）或 carto credentials create m2m --json（M2M）。托管应用无需任何凭证：跳过令牌步骤，并按 auth-hosted.md 操作。

如果 carto 不在 PATH 中，或 auth status 失败：说明一次后就停止——输出缺少的命令。不要改为提问。假设 CLI 可正常工作（carto-basics）。

只询问 CLI 无法回答的问题：表名（如果不明显）以及下方含糊不清的应用形态选项。

决策流程——仅在确实存在歧义时提问

1. 是否提供了 Builder map ID？ 是 → fetchmap.md。完成。 1b. 是否为 Storymap 形态？ 线索：“story map”、“scrollytelling”、“guided tour”、“scenes/chapters/slides”、“fly through”。→ storymap.md。仍需从下方选择 React 脚手架及数据源/图层；storymap 是叠加其上的状态模式，而非单独的脚手架。
2. 演示还是生产环境？ 默认使用 vanilla TS + Vite + MapLibre（scaffold-vanilla.md），除非提示中提到“production”、“auth”、“deploy”、“team”或“multi-screen” → React（scaffold-react.md）。仅在明确指定时使用 Vue / Angular（scaffold-vue-angular.md）。
3. 认证模型？ 根据提示线索选择；仅在线索冲突时提问。
   • “public” / “share” / “embed” / 无需登录 → API 访问令牌（auth-public-token.md）
   • “private” / “users log in” / “CARTO login” → OAuth SPA（auth-private-oauth.md）
   • “SSO” / “Okta” / “Azure AD” / “corporate IdP” → OAuth + SSO（auth-private-sso.md）
   • “backend” / “ETL” / “CI” / “scheduled” → M2M（auth-m2m.md）
   • “hosted on CARTO” / “internal tool” / “for my team” / “no infrastructure” / carto app deploy → CARTO 托管，运行时使用 viewer token（auth-hosted.md）。需要启用 Hosted Apps 标记；不适用于匿名访问。
4. 数据形态？ 从 data-sources.md + layers.md 中选择数据源/图层组合：点/线/多边形 → vector；H3 → H3；quadbin → quadbin；曲面 → raster。通过 basemap-and-view.md 配置底图和视图状态同步。

然后仅添加用户要求的内容：组件、筛选器、输入项、图例、SQL/工作流、Agent 对话。示例见 recipes/。

5. 视觉风格？ 没有风格线索 → 默认采用 Meridian 风格（简洁、专业、原生 CARTO 风格）。有任何风格线索（“futuristic”、“corporate”或指定的设计系统）→ 定制主题以符合用户描述。无论哪种情况，都应用 UX 布局原则。参见 design-and-theming.md。

始终遵循的指导原则

• apiBaseUrl 是 https://<tenant_id>.api.carto.com，其中 tenant_id（区域，例如 gcp-us-east1）来自 carto auth status --json。tenant_domain 是组织自己的域名（例如 clausa.app.carto.com），不包含区域。https://<tenant_domain>/config.yaml 中的 apis.baseUrl 是权威配置（包括可自托管的情况）。切勿硬编码。
• connectionName 默认为 carto_dw；请通过 carto connections list --json 确认。
• 公共令牌必须始终传入 --source，并将 --apis 限定为 sql,maps。公共资源包中绝不能包含 imports / lds。
• 复杂分析属于工作流，而不是应用 SQL。 预测收入、计算综合评分／适宜性评分、细分、多步联接等，都应使用 carto-create-workflow 构建；然后，应用通过 Workflows API 读取其输出表或 CALL 其存储过程（或者，由嵌入式 Agent 驱动时，将其作为已发布的 MCP 工具调用）。繁重的逻辑留在服务端；应用负责传递参数。参见 workflows-and-sql.md。
• 一个 filters 对象由数据源辅助函数和组件方法共享。修改它会触发两者重新获取数据。
• 图层的 z 顺序由 layers 数组决定，最后一个位于最上方，而不是 CSS z-index。 通过调整数组位置并传入一个全新的数组来重新排序（切勿原地修改）；z-index 用于排列 DOM 面板，不会影响共享画布上的图层。参见 layers.md。（不透明填充遮挡底图标签是另一个问题，应从底图侧处理，参见 basemap-and-view.md。）
• 在 onViewStateChange 上对视口空间筛选进行约 300 ms 的防抖。
• 设计——除非用户指定其他美学风格，否则采用受 Meridian 启发的默认主题。UX 布局原则（以地图为主角、规范面板布局、渐进式展示）始终适用。参见 design-and-theming.md。
• 切勿虚构徽标。 只有在用户提供经过验证的 PNG / JPG / SVG 素材或指向官方来源时，才渲染徽标（CARTO、客户、合作伙伴或第三方品牌）。没有经过验证的素材时，应询问用户，或使用文字字标／完全省略徽标。不得生成 SVG 标志、从未经验证的 URL 获取素材，也不得用相似品牌替代。即使是知名品牌也适用。
• 最后运行应用。 运行 npm install && npm run dev 并报告 URL。