# 🏗️ CARTO for Agents — 架构研究笔记 > **分析日期**: 2026-07-21 > **研究者**: Huawei > **目的**: 提取 CARTO for Agents 架构思路，对照 AgentGIS Cloud Platform，发现可借鉴的方向 --- ## 一、总体架构图 ``` ┌────────────────────────────────────────────────────────────────────┐ │ CARTO for Agents 三层能力 │ ├────────────────────────────────────────────────────────────────────┤ │ │ │ 🧑 人机界面层 │ │ ┌──────────────────────────────────────────────────────────────┐ │ │ │ Claude.ai │ ChatGPT │ Gemini │ Claude Desktop │ MCP Inspector│ │ │ └──────────────┬───────────────────────────┬──────────────────┘ │ │ │ │ │ │ ┌──────────────▼──────────────┐ ┌──────────▼──────────────┐ │ │ │ CARTO MCP Server │ │ CARTO Agent Skills │ │ │ │ (托管 MCP Server) │ │ (本地技能 playbook) │ │ │ │ │ │ │ │ │ │ - Platform tools │ │ Utility Tier │ │ │ │ - Interactive tools │ │ Platform Tier │ │ │ │ - Workflows as MCP Tools │ │ Use-case Pattern Tier │ │ │ └──────────────┬──────────────┘ └──────────┬──────────────┘ │ │ │ │ │ │ └──────────┬────────────────┘ │ │ │ 调用 │ │ ┌──────────▼──────────────┐ │ │ │ CARTO CLI │ │ │ │ (@carto/carto-cli) │ │ │ │ npm install -g │ │ │ └──────────┬──────────────┘ │ │ │ │ └────────────────────────────┼──────────────────────────────────────┘ │ ┌──────────────┴──────────────┐ │ 数据/计算层 │ │ BigQuery / Snowflake / │ │ Redshift / Databricks / │ │ Oracle（数据永不离开） │ └─────────────────────────────┘ ``` --- ## 二、三大组件的精要分析 ### 2.1 CARTO CLI —— 平台能力的"API 化" **不是普通的 CLI。** 它是一个**完整覆盖 CARTO 平台操作的命令集合**，设计上同时面向人类和 Agent。 关键设计点： | 设计特征 | 说明 | 对我们的启发 | |----------|------|-------------| | **一人一 Agent 通用** | 同一个 `carto` 命令，人类在终端用，Agent 在 shell 调用 | ✅ `agc` CLI 已经走在这条路上 | | **输出可编程** | JSON 输出，Agent 直接解析 | ✅ 我们的 `agc` 应统一输出格式 | | **连接管理** | `carto credentials create token/spa/m2m` — Agent 自动创建作用域精细的令牌 | ⚠️ 我们现在 API Key 是手动管理 | | **无状态** | 每次调用通过本地 profile 认证，不维护与 Agent 的持久会话 | ✅ 符合我们的设计 | **核心洞察：** CLI 是 Agent 访问平台能力的最小公约数接口。Agent 不需要理解 REST API 的路径、认证头、分页逻辑——只需 `carto `。 ### 2.2 CARTO MCP Server —— 标准化协议接入 MCP（Model Context Protocol）是 Anthropic 提出、逐渐成为事实标准的 AI <-> 工具协议。CARTO 建了一个托管 MCP Server，把平台能力暴露给任何兼容 MCP 的客户端。 **三类工具设计：** ``` Platform tools Interactive tools Workflows tools ┌──────────────────────┐ ┌──────────────────────┐ ┌──────────────────────┐ │ list_connections │ │ view_map │ │ run_workflow │ │ browse_tables │ │ load_builder_map │ │ get_workflow_status │ │ describe_table │ │ │ │ get_workflow_results │ │ search_maps │ │ 返回交互式地图嵌入 │ │ │ │ │ │ 仅 MCP Apps 客户端 │ │ 同步/异步模式 │ │ 返回 JSON → Agent 推理 │ │ 支持内联渲染 │ │ │ └──────────────────────┘ └──────────────────────┘ └──────────────────────┘ ``` **关键设计决策：** - 用 OAuth（U2M/M2M）作为主要认证方式，API Token 为辅 - SSO 企业用户通过独立 URL 入口 - 支持**把已发布的工作流暴露为 MCP Tool**（这是精髓——见下文 4.1 节） ### 2.3 CARTO Agent Skills —— 专家知识的封装 这是最值得我们借鉴的模块。不是给 Agent 喂一堆文档让它自己悟，而是把**领域的专业知识编码成可加载的 playbook**。 **三层架构设计：** ``` Use-case Pattern Tier ← 用户自然语言触发（"做个热点分析"） ├── carto-hotspot-analysis ├── carto-spatial-autocorrelation ├── carto-site-selection ├── carto-trade-area-analysis ├── carto-gwr ├── carto-composite-scoring ├── carto-spatial-enrichment ├── carto-routing-od-analysis ├── carto-territory-planning ├── carto-geocoding └── carto-arcgis-migration ← 甚至覆盖了从 Esri 迁移这个复杂场景 ↑ 依赖 Platform Tier ← 按产品面组织 ├── carto-create-workflow ├── carto-manage-builder-maps ├── carto-import-export-data ├── carto-data-observatory ├── carto-develop-app ← vibe coding 完整空间应用 ↑ 依赖 Utility Tier ← 基础原语 ├── install & auth ├── sql query ├── explore data └── (被其他技能作为依赖加载) ``` **每个 skill 的触发方式不是硬编码的**，而是通过**关键词匹配 + 用户意图自动路由**。Agent 从用户请求中识别"hotspot"→ 自动加载 `carto-hotspot-analysis`。 这就是把分析师多年的经验编码成 Agent 能直接遵守的 playbook，省去了每次从头探索 API 的试错成本。 --- ## 三、对我们 AgentGIS 平台的架构启发 ### 🔑 启发一：把平台能力包装成 CLI + Skill 双接口 **现状：** 我们已经有 `agc` CLI，但 Agent 集成主要靠 API Key 直接调 suite-market API。 **建议方向：** ``` AI Agent (Claude Code / Codex / 自研) │ ├── 直接调 API → 能力完整但 Agent 需要"学习"REST 语义 │ └── agc → Agent 只需要记一组 CLI 命令 │ └── Agent Skill playbook → 告诉 Agent "做 xx 分析时，先用哪个命令，再做什么" ``` 具体来说： 1. **`agc` CLI 补全**：目前只跑套件。可以扩展为： - `agc auth login|token` — 认证管理 - `agc suite search|inspect|run` — 套件操作 - `agc data import|export|list` — 数据管理 - `agc compliance check` — 合规检查 - `agc org stats` — 组织统计 2. **Skill 目录**：在 `SuiteHub/agent-profiles` 下建 `agent-skills/` 目录，写一套针对我们平台的 skill playbook。 --- ### ⚡ 启发二：MCP Server 暴露平台能力给外部 Agent **现状：** Agent 集成方式单一（API Key → suite-market API），且没有标准化协议。 **建议方向：** 1. 搭建一个 **MCP Server** 暴露 AgentGIS 核心能力： - `list_suites` — 搜索可用套件 - `inspect_suite` — 查看套件详情（参数说明、版本） - `run_suite` — 触发本地执行（返回执行 ID） - `check_compliance` — 对给定脚本做合规检测 - `query_suite_results` — 查询历史执行结果 2. 这样 Claude / ChatGPT / 自研 Agent 都能通过标准协议接入 3. 认证用现有 API Key 体系即可（MCP Server 支持 API Token 方式） --- ### 🧠 启发三：Agent Skill 三层架构 —— 把领域知识编码为 Playbook **这是最核心的启发。** 我们的平台生态天然适合三层 Skill 架构： ``` ┌─ Use-case Tier（分析模式）─────────────────────────────────────┐ │ 分析套件（Analysis Suite） │ │ • 地理围栏分析（当用户说"做个围栏分析"） │ │ • POI 叠加分析 │ │ • 空间统计（莫兰 I、热点分析） │ │ • 数据质量报告 │ │ │ │ 迁移套件（Migration Suite） │ │ • 从某 GIS 平台迁移到 AgentGIS（参考 carto-arcgis-migration） │ └────────────────────────────────────────────────────────────────┘ ↑ 依赖 ┌─ Platform Tier（产品操作）──────────────────────────────────────┐ │ • 套件搜索与运行 │ │ • 合规检测流程 │ │ • 数据导入导出 │ │ • 发布流程 │ │ • 平台管理（查看健康状态、审计日志） │ └────────────────────────────────────────────────────────────────┘ ↑ 依赖 ┌─ Utility Tier（基础原语）───────────────────────────────────────┐ │ • 安装 & 认证 │ │ • agc CLI 基础命令用法 │ │ • 基础镜像操作（docker run 隔离执行理解） │ │ • Gitea Packages 下载模式 │ └────────────────────────────────────────────────────────────────┘ ``` **每个 Skill 文件包含：** - `triggers`：触发关键词（Agent 据此自动加载） - `dependencies`：依赖的底层 skill - `steps`：操作步骤，每一步引用具体 CLI 命令 - `examples`：示例输入输出 --- ### 🔐 启发四：Workflow → MCP Tool —— 固化合规的分析流程 **这是最惊艳的设计。** CARTO 允许你把一个 Workflow（分析流程）**一键发布为 MCP Tool**。效果： 1. 分析师（人）在 Workflows 里搭建、审核、固化分析流程 2. 一键发布为 MCP Tool → 分析流程变成了一个可调用函数 3. Agent 只需要提供输入参数，不需要再推导分析逻辑 **对应到我们平台：** 一个套件（Suite）本质上就是一个固化的分析流程（workflow.yaml + scripts/）。那我们就可以： - 允许平台管理员**把经过合规检测的套件标记为"可 MCP 调用"** - 暴露到 MCP Server 上，Agent 直接 `run_suite(suite_id, inputs)` - Agent 不需要知道套件内部怎么运行——只需要知道："我想做围栏分析，传入中心点坐标和半径" 这就解决了 Agent 系统里最核心的张力：**概率性推理 ↔ 确定性执行**。 - 不确定性（Agent 推理）→ 决定"做什么" - 确定性（已审阅的套件）→ 决定"怎么做" --- ### 📋 启发五：语义模型（Sematic Model）—— 告诉 Agent 数据长什么样 CARTO 基于 [Apache Ossie](https://ossie.apache.org/) 开放标准定义语义模型，扩展了空间字段描述： ```yaml # 语义模型核心结构 version: "0.1.1" semantic_model: - name: "数据集描述" datasets: - name: "table_name" fields: - name: "geom" description: "空间字段业务含义" custom_extensions: - vendor_name: CARTO data: '{"spatial_data": {"type": "polygon", "srid": 4326}}' relationships: - name: "数据集间关系" from/to/ai_context metrics: - name: "可复用计算指标" expression/description ``` **对我们的意义：** 如果我们想实现"Agent 根据自然语言描述自动选择合适的套件并填参执行"，语义模型是关键。但目前这个阶段，我们还没有 Agent 直接跟数据仓库交互的需求（套件是封闭的），可以列为**中期规划**。 --- ### 🔄 启发六：ARC → AgentGIS 迁移技能 CARTO 做了 `carto-arcgis-migration`，处理从 Esri 迁移到 CARTO 的全流程。我们平台未来也可能面临类似场景——从其他 GIS 平台迁移到 AgentGIS。 如果将来有需求，可以参照同样的三阶段设计： 1. **Discover** — 盘点源平台资产，生成迁移计划供审批 2. **Migrate data** — 迁移数据到目标仓库 3. **Migrate config** — 迁移配置/脚本到套件格式 --- ## 四、三个最值得立即动手的方向 按投入产出比排序： ### 方向 1（高优先级）：ACl "agc" CLI 扩展 + Skill 目录 > 预计投入：低。Skill 是 markdown 文件，CLI 扩展是增量开发。 - 在 `SuiteHub/agent-profiles` 下建 `agent-skills/` 目录 - 先写 1-2 个 Utility skill（安装认证、基础操作） - 再写 1 个 Use-case skill（"做一个围栏分析"的完整引导） - 扩展 `agc` CLI 添加几个 Agent 友好子命令 ### 方向 2（中-高优先级）：MCP Server > 预计投入：中。需要搭一个轻量 MCP Server 容器。 - 在阿里云 ECS 部署 `agentgis-mcp-server` 容器 - 先用 `mk_` API Key 认证 - 暴露 3-5 个核心工具（list_suites, inspect_suite, run_suite, check_compliance） - 对接 Claude Code / ChatGPT 测试 ### 方向 3（中长期）：Workflow as Tool / Suite as Tool > 预计投入：较高。需要修改发布流程 + 合规检测 + MCP 集成。 - 在套件模型中增加 `mcp_enabled: bool` 字段 - 合规检测通过后可标记为 MCP 可调用 - MCP Server 读取可调用套件列表，暴露为 tools - Agent 传入参数 -> MCP Server -> 触发 `agc run` -> 返回结果 --- ## 五、与 ArcGIS 迁移的类比思考（长期） CARTO 的迁移故事核心论点： 1. **架构差异** — ArcGIS 拷贝数据到封闭存储 vs CARTO 在数据仓库原生执行 2. **成本结构** — 按席位 vs 按用量 3. **Agent 化** — 迁移本身就是 Agent 驱动的 我们的平台从第一天就是"数据不离开本地"模式，没有历史包袱。但如果将来需要吸引从传统 GIS 平台迁移的用户，可以借鉴他们的三阶段迁移模式和 readiness assessment 流程。 --- ## 六、总结 | 维度 | CARTO for Agents | AgentGIS Cloud Platform | 可借鉴程度 | |------|------------------|------------------------|-----------| | CLI 覆盖度 | 全平台操作 | 仅 `agc run` | ⭐⭐⭐ 扩展 CLI | | MCP 协议 | 原生支持 | 无 | ⭐⭐⭐ 新建 MCP Server | | Agent Skill 目录 | 3 层 15+ skill | 无 | ⭐⭐⭐ 建 skill 目录 | | Workflow → Tool | 一键发布为 MCP Tool | 概念匹配（套件 = 流程） | ⭐⭐⭐ 中期实现 | | 语义模型 | Apache Ossie + 空间扩展 | 无 | ⭐⭐ 远期规划 | | 迁移工具 | 三阶段 Agent 驱动 | 无 | ⭐ 按需 | | In-product AI Agent | Builder 内嵌聊天 | 暂不考虑 | ⭐ 排除 | **一句话总结：** CARTO for Agents 的三个设计——**CLI 全平台覆盖、MCP 标准化协议接入、Skill playbook 编码领域知识**——都是我们 AgentGIS 平台在 Agent 集成层可以（也应该）做的事情。Skill 架构和 Workflow as Tool 是最契合我们现状、投入产出比最高的方向。 --- *笔记归档：research/carto-for-agents-architecture-notes.md*