From 3753bdfe19a363fb76f8243dedf5dc035fc831ae Mon Sep 17 00:00:00 2001 From: Huawei Date: Tue, 21 Jul 2026 08:24:00 +0000 Subject: [PATCH] =?UTF-8?q?[Huawei]=20=E8=BF=81=E7=A7=BB=E5=88=B0=20AgentG?= =?UTF-8?q?IS/platform=20=E4=BB=93=E5=BA=93?= 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 deletions(-) delete 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 deleted file mode 100644 index 628964a..0000000 --- a/research/carto-for-agents-architecture-notes.md +++ /dev/null @@ -1,336 +0,0 @@ -# 🏗️ 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*