SuiteHub/agent-profiles
4
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

[Huawei] 迁移到 AgentGIS/platform 仓库

Browse Source
This commit is contained in:
Huawei
2026-07-21 08:24:00 +00:00
parent d1dda938f7
commit 3753bdfe19
1 changed files with 0 additions and 336 deletions
Download Patch File Download Diff File Expand all files Collapse all files
research/carto-for-agents-architecture-notes.md
-336
View File
@@ -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 <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*