From a1c8935cbd2046a8231407734064e9207e065b78 Mon Sep 17 00:00:00 2001 From: Huawei Date: Tue, 21 Jul 2026 02:28:51 +0000 Subject: [PATCH] =?UTF-8?q?[Huawei]=20=E6=B7=BB=E5=8A=A0=20CARTO=20for=20A?= =?UTF-8?q?gents=20=E6=9E=B6=E6=9E=84=E7=A0=94=E7=A9=B6=E7=AC=94=E8=AE=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../carto-for-agents-architecture-notes.md | 336 ++++++++++++++++++ 1 file changed, 336 insertions(+) create mode 100644 research/carto-for-agents-architecture-notes.md diff --git a/research/carto-for-agents-architecture-notes.md b/research/carto-for-agents-architecture-notes.md new file mode 100644 index 0000000..628964a --- /dev/null +++ b/research/carto-for-agents-architecture-notes.md @@ -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 `。 + +### 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*