[Huawei] 添加 CARTO for Agents 架构研究笔记
This commit is contained in:
@@ -0,0 +1,336 @@
|
|||||||
|
# 🏗️ 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 <verb> <noun> <flags>`。
|
||||||
|
|
||||||
|
### 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 <subcommand> <args> → 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*
|
||||||
Reference in New Issue
Block a user