917 lines
39 KiB
Markdown
917 lines
39 KiB
Markdown
# 🏗️ AgentGIS Cloud Platform — Agent 集成层架构规划与迭代路线
|
||
|
||
> **编制**: Huawei | **日期**: 2026-07-21
|
||
> **基于**: CARTO for Agents 架构研究 + AgentGIS 平台现状
|
||
> **定位**: 平台下一阶段架构升级的决策参考
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
1. [现状快照](#一现状快照)
|
||
2. [目标架构蓝图](#二目标架构蓝图)
|
||
3. [差距分析](#三差距分析)
|
||
4. [迭代路线](#四迭代路线)
|
||
5. [Phase 1 详设：Skill 目录 + CLI 扩展](#五phase-1-详设skill-目录--cli-扩展)
|
||
6. [Phase 2 详设：MCP Server](#六phase-2-详设mcp-server)
|
||
7. [Phase 3 详设：Suite as Tool](#七phase-3-详设suite-as-tool)
|
||
8. [Phase 4 展望：语义模型与 Agent 自动化](#八phase-4-展望语义模型与-agent-自动化)
|
||
9. [附录](#九附录)
|
||
|
||
---
|
||
|
||
## 一、现状快照
|
||
|
||
### 1.1 我们有什么
|
||
|
||
```
|
||
用户 / AI Agent
|
||
│
|
||
├── mk_ API Key → suites.mercator.cn REST API ← 当前主要 Agent 接入方式
|
||
│
|
||
└── agc CLI（仅 run + config 子命令）
|
||
│
|
||
├── agc run <dir> --suite-id <id> --input k=v
|
||
├── agc config set/get/list
|
||
└── agc config set api-key <key>
|
||
```
|
||
|
||
**平台核心：**
|
||
|
||
| 组件 | 状态 | 说明 |
|
||
|------|------|------|
|
||
| `auth-center` | ✅ 运行中 | 认证 + API Key + OIDC + OAuth2/OIDC 服务端 |
|
||
| `suite-market` | ✅ 运行中 | 套件 CRUD、发布、合规检测、搜索 |
|
||
| `discussions` | ✅ 运行中 | 社区讨论、故障自动报告 |
|
||
| `gis-actions` (`agc`) | ✅ 运行中 | CLI 本地执行器，当前只有 `run` 和 `config` |
|
||
| `Agent Profiles` | ✅ 运行中 | SuiteHub/agent-profiles 仓库，多角色认知文件 |
|
||
| 合规检测 | ✅ 有 | `POST /api/v1/compliance/check` |
|
||
| 参数校验 | ✅ 有 | `POST /api/v1/parameters/validate` |
|
||
|
||
### 1.2 我们缺什么
|
||
|
||
| 能力 | 状态 | 差距 |
|
||
|------|------|------|
|
||
| **CLI 全平台覆盖** | ❌ 仅 `run` + `config` | 无搜索、无认证管理、无数据操作、无查看健康状态 |
|
||
| **CLI JSON 输出** | ❌ | 当前输出是自由文本，Agent 无法可靠解析 |
|
||
| **Agent Skill 目录** | ❌ 无 | Agent Profiles 是静态认知文件，不是可加载的 playbook |
|
||
| **MCP Server** | ❌ 无 | Agent 接入面窄，只有 REST API |
|
||
| **Workflow as Tool** | ❌ 无 | 套件 = 流程，但不可被 Agent 直接调用 |
|
||
| **语义模型** | ❌ 无 | Agent 不理解数据含义，依赖人填参数 |
|
||
| **Agent 审计追踪** | ❌ 无 | 无法追踪"哪个 Agent 做了什么操作" |
|
||
|
||
---
|
||
|
||
## 二、目标架构蓝图
|
||
|
||
### 2.1 两层架构 → 四层架构
|
||
|
||
```
|
||
当前（两层） 目标（四层）
|
||
|
||
Agent ──REST──→ suite-market Agent ──MCP──→ MCP Server
|
||
│
|
||
CLI ├── Platform Tools（内置）
|
||
│ ├── Interactive Tools（未来）
|
||
│ └── Suite Tools（动态注册）
|
||
agc ──→ 本地执行
|
||
Agent Skill 目录
|
||
│
|
||
Utility → Platform → Use-case
|
||
│
|
||
agc CLI（扩展）
|
||
│
|
||
suite-market REST API（不变）
|
||
|
||
```
|
||
|
||
### 2.2 目标架构总图
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────────────────────┐
|
||
│ Agent 集成层（新建/扩展） │
|
||
├──────────────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ ┌─────────────────────────────────────────┐ ┌────────────────────────┐ │
|
||
│ │ MCP Server（新建） │ │ Agent Skills（新建） │ │
|
||
│ │ agentgis-mcp-server:8100 │ │ │ │
|
||
│ │ │ │ Use-case Tier │ │
|
||
│ │ Platform Tools（内置）： │ │ ├─ 围栏分析 │ │
|
||
│ │ ├─ list_suites │ │ ├─ POI 叠加 │ │
|
||
│ │ ├─ inspect_suite │ │ ├─ 热点分析 │ │
|
||
│ │ ├─ run_suite │ │ ├─ 数据质量报告 │ │
|
||
│ │ ├─ run_suite_async │ │ └─ arcgis-迁移（远期） │ │
|
||
│ │ ├─ get_run_status │ │ ↑ 依赖 │ │
|
||
│ │ ├─ get_run_results │ │ Platform Tier │ │
|
||
│ │ ├─ check_compliance │ │ ├─ 套件搜索与运行 │ │
|
||
│ │ ├─ search_data │ │ ├─ 合规检测流程 │ │
|
||
│ │ └─ get_org_stats │ │ ├─ 数据导入导出 │ │
|
||
│ │ │ │ └─ 平台健康检查 │ │
|
||
│ │ Suite Tools（动态注册）： │ │ ↑ 依赖 │ │
|
||
│ │ 每个标记为 mcp_enabled=True 的套件 │ │ Utility Tier │ │
|
||
│ │ 自动注册为一个 tool │ │ ├─ 安装与认证 │ │
|
||
│ │ │ │ ├─ agc 基础命令 │ │
|
||
│ │ 认证：API Key / OAuth（未来） │ │ ├─ Docker 执行模型 │ │
|
||
│ └─────────────────────────────────────────┘ │ └─ Gitea 包下载 │ │
|
||
│ └────────────────────────┘ │
|
||
│ │
|
||
│ ┌──────────────────────────────────────────────────────────────────────┐ │
|
||
│ │ agc CLI（扩展） 人类 + Agent 通用 │ │
|
||
│ │ agc auth login|token|logout │ │
|
||
│ │ agc suite search|inspect|run|list-status │ │
|
||
│ │ agc data import|export|list │ │
|
||
│ │ agc compliance check │ │
|
||
│ │ agc org stats │ │
|
||
│ │ agc mcp start|stop|status ← 新增：MCP 本地代理 │ │
|
||
│ └──────────────────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
└──────────────────────────────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌──────────────────────────────────────────────────────────────────────────┐
|
||
│ 平台服务层（现有，小幅修改） │
|
||
├──────────────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ suite-market（+ mcp_enabled 字段 + 审计 API） │
|
||
│ auth-center（+ M2M OAuth 支持，远期） │
|
||
│ discussions（+ Agent 操作审计话题） │
|
||
│ │
|
||
└──────────────────────────────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌──────────────────────────────────────────────────────────────────────────┐
|
||
│ 本地执行层（不变） │
|
||
├──────────────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ agc run → 下载 → 解压 → 拓扑序执行 → 结果保留本地 │
|
||
│ │
|
||
└──────────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 2.3 Agent 交互流程（目标态）
|
||
|
||
```
|
||
场景 A：人类在终端用
|
||
用户 → agc suite search --keyword 围栏 → JSON 结果
|
||
|
||
场景 B：Claude Code 通过 CLI 操作
|
||
Claude Code → shell: agc suite search --keyword 围栏 --format json
|
||
→ 解析 JSON → 决定调用哪个套件
|
||
→ shell: agc suite run --suite-id geofence --input center=POINT(116 40)
|
||
|
||
场景 C：ChatGPT 通过 MCP 操作
|
||
ChatGPT → MCP list_suites(keyword="围栏")
|
||
→ MCP run_suite(suite_id="geofence", inputs={"center": "POINT(116 40)"})
|
||
→ MCP Server → 调用 suite-market API → 触发 agc run（本地或返回执行指令）
|
||
|
||
场景 D：自研 Agent 通过 Skill Playbook 操作
|
||
Agent 收到请求：{"type": "geofence", "params": {...}}
|
||
→ 匹配 trigger 关键词 → 加载 geofence-analysis skill
|
||
→ 按 skill steps 执行：agc suite search → agc suite run → agc suite list-status
|
||
```
|
||
|
||
---
|
||
|
||
## 三、差距分析
|
||
|
||
### 3.1 能力对照矩阵
|
||
|
||
| 能力 | CARTO | AgentGIS 现状 | 差距等级 | 参考实现 |
|
||
|------|-------|--------------|---------|---------|
|
||
| **CLI 安装** | `npm install -g @carto/carto-cli` | `pip install gis-actions` | 等效 | 无需改动 |
|
||
| **CLI 命令覆盖** | 30+ 子命令（auth/credentials/maps/workflows/import/export/org） | 2 子命令（run/config） | 🔴 严重 | [Phase 1](#五phase-1-详设skill-目录--cli-扩展) |
|
||
| **CLI JSON 输出** | 默认 JSON | 文本格式，需解析 | 🟡 中等 | `--format json` 全局参数 |
|
||
| **CLI 认证集成** | `carto auth login` OAuth 交互式 | `agc config set api-key` 手动配 | 🟡 中等 | `agc auth login` + OAuth 设备码流 |
|
||
| **Agent Skills** | 三层 15+ skill，GitHub 公开仓库 | 无 | 🔴 严重 | [Phase 1](#五phase-1-详设skill-目录--cli-扩展) |
|
||
| **MCP Server** | 托管式，OAuth/Token 认证 | 无 | 🔴 严重 | [Phase 2](#六phase-2-详设mcp-server) |
|
||
| **Workflow as Tool** | 一键 MCP publish | 无 | 🔴 严重 | [Phase 3](#七phase-3-详设suite-as-tool) |
|
||
| **平台工具（内置）** | list_connections, browse_tables, describe_table... | 无 | 🔴 严重 | Phase 2 内置 |
|
||
| **交互式地图** | view_map（MCP Apps 内联渲染） | 不需要 | 不适用 | 无计划 |
|
||
| **语义模型** | Apache Ossie + CARTO 空间扩展 | 无 | 🟡 中等 | Phase 4 |
|
||
| **Agent 审计** | CARTO AI Analytics 面板 | 无 | 🟡 中等 | Phase 3+ |
|
||
| **迁移工具** | carto-arcgis-migration | 无 | 🟢 低 | 按需 |
|
||
| **In-product Agent** | Builder 内嵌聊天 | 暂不考虑 | 不适用 | 排除 |
|
||
|
||
### 3.2 技术债评估
|
||
|
||
| 项目 | 影响 | 建议 |
|
||
|------|------|------|
|
||
| `agc` 无统一输出格式 | Agent 无法可靠解析 | 加全局 `--format json|text` |
|
||
| suite-market 无 MCP 相关 API | 无法注册和查询 mcp_enabled 套件 | 后端加字段 + API |
|
||
| 无 Agent 操作审计 | 无法追踪谁做了什么 | PostgreSQL + Redis 写审计流 |
|
||
| 无隔离的 MCP Server 容器 | 需要新容器 | Docker + NPM 反代 |
|
||
| Agent Profiles 是静态文件 | 不能程序化加载 | 独立出 skills 目录结构 |
|
||
|
||
---
|
||
|
||
## 四、迭代路线
|
||
|
||
### 总览
|
||
|
||
```
|
||
Phase 1 Phase 2 Phase 3 Phase 4
|
||
2026-07-21 2026-08-01 2026-09-01 2026-Q4
|
||
───────── ───────── ───────── ────────
|
||
|
||
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
||
│ Skill 目录 │ │ MCP Server │ │ Suite as Tool │ │ 语义模型 │
|
||
│ CLI 扩展 │ ───► │ (基础版) │ ───► │ (动态注册) │ ───► │ Agent 自决 │
|
||
│ 审计埋点 │ │ Claude 对接 │ │ AI Analytics │ │ 策 + 优化 │
|
||
└──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘
|
||
│
|
||
2-3 周 3-4 周 3-4 周 远期持续
|
||
```
|
||
|
||
### Phase 1：地基（2026-07-21 起，预计 2-3 周）
|
||
|
||
**目标：让 AI 编码 Agent 能正确操作 AgentGIS 平台**
|
||
|
||
| 工作项 | 交付物 | 负责人 |
|
||
|--------|--------|--------|
|
||
| **1a. 设计 Skill 目录结构** | `agent-skills/` 目录 + 仓库 | Huawei（开 Issue） |
|
||
| **1b. 编写 Utility Skill（3 个）** | install-auth.md, basic-commands.md, execution-model.md | Huawei（开 Issue） |
|
||
| **1c. 编写 Platform Skill（2 个）** | suite-search-run.md, compliance-check.md | Huawei（开 Issue） |
|
||
| **1d. 编写 Use-case Skill（1 个）** | geofence-analysis.md | Huawei（开 Issue） |
|
||
| **1e. 扩展 `agc` CLI** | 添加 auth/search/list-status/stats 子命令 + `--format json` | Admin（编码） |
|
||
| **1f. 审计埋点** | `suite-market` 后端添加 `agent_action` 审计表 | Admin（编码） |
|
||
|
||
**验收标准：**
|
||
- ✅ Claude Code 通过 skill 引导，能用 `agc` CLI 完成"搜索套件→查看详情→运行"
|
||
- ✅ `agc suite search --format json` 返回可解析 JSON
|
||
- ✅ 所有 Agent 操作写入审计日志
|
||
|
||
### Phase 2：标准协议接入（2026-08-01 起，预计 3-4 周）
|
||
|
||
**目标：让任意 MCP 兼容的 AI 客户端能直接调用 AgentGIS 平台**
|
||
|
||
| 工作项 | 交付物 | 负责人 |
|
||
|--------|--------|--------|
|
||
| **2a. 搭建 MCP Server 容器** | Docker 镜像 + NPM 反代 (mcp.mercator.cn) | Huawei（运维） |
|
||
| **2b. 实现核心 Platform Tools** | list_suites, inspect_suite, run_suite, run_suite_async, get_run_status, get_run_results, check_compliance | Admin（编码） |
|
||
| **2c. API Key 认证集成** | MCP Server 验证 `mk_` 前缀 API Key | Admin（编码） |
|
||
| **2d. 对接 Claude Desktop 测试** | 配置 MCP Server URL，端到端验证 | Huawei（测试） |
|
||
| **2e. 对接 ChatGPT 测试** | ChatGPT 自定义 MCP 测试 | Huawei（测试） |
|
||
| **2f. 编写 MCP 使用文档** | 开发者指南 + 用户指南 | Huawei（文档） |
|
||
|
||
**验收标准：**
|
||
- ✅ ChatGPT 直接聊天：搜索套件→查看详情→运行→查状态→获取结果
|
||
- ✅ Claude Desktop 同样可用
|
||
- ✅ 认证正确，非法 API Key 被拒绝
|
||
- ✅ `mcp.mercator.cn` 稳定运行
|
||
|
||
### Phase 3：动态套件工具（2026-09-01 起，预计 3-4 周）
|
||
|
||
**目标：经合规检测的套件自动变为可 MCP 调用的工具**
|
||
|
||
| 工作项 | 交付物 | 负责人 |
|
||
|--------|--------|--------|
|
||
| **3a. suite-market 增加 mcp_enabled 字段** | 模型迁移 + API 更新 + 前端 UI | Admin（编码） |
|
||
| **3b. 合规通过后自动标记** | 合规检测流程末尾增加自动标记逻辑 | Admin（编码） |
|
||
| **3c. MCP Server 动态注册** | MCP Server 读取可调用套件列表，自动注入 tools | Admin（编码） |
|
||
| **3d. 异步执行支持强化** | 执行状态回调 / 轮询 + 超时机制 | Admin（编码） |
|
||
| **3e. AI Analytics 面板** | 审计数据 → 可视化面板（操作排行、成功/失败率） | Admin（编码） |
|
||
| **3f. 完善 Use-case Skill 目录** | 再写 3 个 Use-case skill | Huawei（文档） |
|
||
|
||
**验收标准：**
|
||
- ✅ 发布一个合规套件 → 自动在 MCP Server 上出现为可调用 tool
|
||
- ✅ Agent 直接调 `run_geofence_analysis(inputs={...})` → 执行 → 返回结果
|
||
- ✅ 管理员看到 Agent 操作统计面板
|
||
- ✅ Skill 目录达到 5+ 个 Use-case skill
|
||
|
||
### Phase 4：智能 Agent 层（2026-Q4，远期）
|
||
|
||
**目标：Agent 能理解数据含义，自动选择并填充参数执行套件**
|
||
|
||
| 工作项 | 说明 |
|
||
|--------|------|
|
||
| 4a. **语义模型设计** | 基于 Apache Ossie 标准，定义数据集、字段、关系、指标 |
|
||
| 4b. **语义模型存储** | suite-market 扩展，支持套件关联语义模型 |
|
||
| 4c. **Agent 自决策** | Agent 根据用户自然语言描述 + 语义模型，自动匹配套件并填充参数 |
|
||
| 4d. **M2M OAuth** | 为微服务和自动化 Agent 提供机器间认证 |
|
||
| 4e. **迁移工具（按需）** | 如出现迁移需求，实现 agentgis-arcgis-migration skill |
|
||
|
||
---
|
||
|
||
## 五、Phase 1 详设：Skill 目录 + CLI 扩展
|
||
|
||
### 5.1 Skill 目录结构
|
||
|
||
**仓库位置：** `SuiteHub/agent-profiles`（已有仓库，新增 `agent-skills/` 目录）
|
||
|
||
```
|
||
SuiteHub/agent-profiles/agent-skills/
|
||
│
|
||
├── catalog.json ← 技能清单（供 Agent 程序化加载）
|
||
├── ARCHITECTURE.md ← 架构说明 + 加载规则
|
||
│
|
||
├── utility/
|
||
│ ├── install-and-auth.md ← 安装 agc + 配置 API Key
|
||
│ ├── basic-commands.md ← agc 基础命令参考
|
||
│ ├── execution-model.md ← Docker 隔离执行模型说明
|
||
│ └── gitea-packages.md ← Gitea Packages 下载模式
|
||
│
|
||
├── platform/
|
||
│ ├── suite-search-and-run.md ← 搜索套件 + 查看详情 + 运行
|
||
│ ├── compliance-check.md ← 合规检测流程
|
||
│ ├── data-import-export.md ← 数据导入导出（配合 CLI）
|
||
│ └── platform-health.md ← 平台健康检查
|
||
│
|
||
└── use-case/
|
||
├── geofence-analysis.md ← 地理围栏分析
|
||
├── poi-overlay-analysis.md ← POI 叠加分析（Phase 3+）
|
||
├── spatial-statistics.md ← 空间统计（Phase 3+）
|
||
└── data-quality-report.md ← 数据质量报告（Phase 3+）
|
||
```
|
||
|
||
### 5.2 Skill 文件模板
|
||
|
||
每个 `.md` 文件遵循统一格式，Agent 可程序化解析：
|
||
|
||
```markdown
|
||
# Skill: <名称>
|
||
|
||
> 层级: utility | platform | use-case
|
||
> 触发词: keyword1, keyword2, keyword3
|
||
> 依赖: [utility/install-and-auth, ...]
|
||
|
||
## 适用场景
|
||
|
||
（用自然语言描述什么情况下 Agent 应该加载这个 skill）
|
||
|
||
## 前置条件
|
||
|
||
（需要在加载这个 skill 之前已满足的条件）
|
||
|
||
## 步骤
|
||
|
||
### 步骤 1：xxxx
|
||
|
||
```bash
|
||
agc <command> <args> --format json
|
||
```
|
||
|
||
输出示例：
|
||
```json
|
||
{...}
|
||
```
|
||
|
||
解析指引：Agent 应该关注哪个字段、如何判断下一步...
|
||
|
||
### 步骤 2：xxxx
|
||
|
||
...
|
||
|
||
## 完整示例
|
||
|
||
一个端到端的对话或脚本示例
|
||
|
||
## 常见错误
|
||
|
||
（Agent 可能遇到的错误及处理方法）
|
||
```
|
||
|
||
### 5.3 Skill 加载规则（`catalog.json`）
|
||
|
||
```json
|
||
{
|
||
"version": "1.0",
|
||
"skills": [
|
||
{
|
||
"id": "install-and-auth",
|
||
"tier": "utility",
|
||
"triggers": ["install", "setup", "auth", "api key", "login"],
|
||
"dependencies": [],
|
||
"file": "utility/install-and-auth.md"
|
||
},
|
||
{
|
||
"id": "basic-commands",
|
||
"tier": "utility",
|
||
"triggers": ["agc", "cli", "command"],
|
||
"dependencies": ["install-and-auth"],
|
||
"file": "utility/basic-commands.md"
|
||
},
|
||
{
|
||
"id": "suite-search-and-run",
|
||
"tier": "platform",
|
||
"triggers": ["search suite", "run suite", "execute", "find suite"],
|
||
"dependencies": ["install-and-auth", "basic-commands"],
|
||
"file": "platform/suite-search-and-run.md"
|
||
},
|
||
{
|
||
"id": "geofence-analysis",
|
||
"tier": "use-case",
|
||
"triggers": ["geofence", "fence", "buffer", "围栏", "缓冲区"],
|
||
"dependencies": ["suite-search-and-run", "execution-model"],
|
||
"file": "use-case/geofence-analysis.md"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
**Agent 加载逻辑：**
|
||
1. 解析用户请求 → 提取关键词
|
||
2. 匹配 `catalog.json` 中 skills[].triggers → 收集匹配的 skill ID
|
||
3. 去重、按 tier 排序（utility → platform → use-case）
|
||
4. 递归加载 dependencies
|
||
5. 按加载顺序读取所有 `.md` 文件注入 Agent 上下文
|
||
|
||
### 5.4 `agc` CLI 扩展设计
|
||
|
||
**新增子命令：**
|
||
|
||
```
|
||
agc
|
||
├── auth
|
||
│ ├── login # OAuth 设备码流（远期）
|
||
│ ├── token set <key> # 当前 config set api-key 的改版
|
||
│ ├── token show # 显示当前 API Key（掩码）
|
||
│ └── token test # 测试 API Key 有效性
|
||
│
|
||
├── suite
|
||
│ ├── search <keyword> # 搜索套件（封装 GET /api/v1/suites/search）
|
||
│ ├── inspect <suite-id> # 查看套件详情
|
||
│ ├── run <suite-id> --input k=v # 当前 run 的精简版
|
||
│ └── list-status # 查看历史执行状态（新增功能）
|
||
│
|
||
├── data
|
||
│ ├── list # 列出已连接的数据源（远期）
|
||
│ ├── import <file> # 导入数据（远期）
|
||
│ └── export <suite-id> <fmt> # 导出结果（远期）
|
||
│
|
||
├── compliance
|
||
│ └── check <suite-id> # 触发合规检测
|
||
│
|
||
├── org
|
||
│ └── stats # 组织统计
|
||
│
|
||
├── mcp
|
||
│ ├── start # 启动本地 MCP 代理（远期）
|
||
│ └── status # 查看 MCP 连接状态
|
||
│
|
||
└── config (现有)
|
||
├── set <key> <value>
|
||
├── get <key>
|
||
└── list
|
||
```
|
||
|
||
**全局标志：**
|
||
- `--format json|text` — 控制输出格式。默认 `text`（人类友好），`json`（Agent 友好）
|
||
- `--quiet` — 只输出结果数据，无 banner/提示信息
|
||
- `--timeout <seconds>` — 执行超时
|
||
|
||
**JSON 输出格式约定：**
|
||
|
||
所有返回 JSON 的子命令遵循统一 schema：
|
||
|
||
```json
|
||
{
|
||
"status": "ok" | "error",
|
||
"data": { ... },
|
||
"error": { "code": "ERROR_CODE", "message": "Human readable" }
|
||
}
|
||
```
|
||
|
||
### 5.5 审计埋点设计
|
||
|
||
**新表 `agent_action_log`（`suite_market_db`）：**
|
||
|
||
```sql
|
||
CREATE TABLE agent_action_log (
|
||
id BIGSERIAL PRIMARY KEY,
|
||
api_key_id VARCHAR(64) NOT NULL, -- 哪个 API Key 执行的操作
|
||
agent_name VARCHAR(128) DEFAULT '', -- Agent 标识（如 "claude-code"）
|
||
action VARCHAR(64) NOT NULL, -- 操作类型
|
||
target_type VARCHAR(32), -- 操作对象类型（suite/data/...）
|
||
target_id VARCHAR(128), -- 操作对象 ID
|
||
request JSONB, -- 请求参数
|
||
response_summary VARCHAR(256), -- 响应摘要
|
||
status VARCHAR(16) DEFAULT 'success', -- success/failure
|
||
duration_ms INTEGER, -- 耗时
|
||
ip_address INET,
|
||
created_at TIMESTAMP DEFAULT NOW()
|
||
);
|
||
|
||
CREATE INDEX idx_agent_action_log_api_key ON agent_action_log(api_key_id);
|
||
CREATE INDEX idx_agent_action_log_created ON agent_action_log(created_at);
|
||
```
|
||
|
||
**采集点：**
|
||
- 所有 REST API 入口（通过 FastAPI middleware）
|
||
- `agc` CLI 所有子命令（通过请求头 `X-Agent-Name`）
|
||
- 未来 MCP Server 所有调用
|
||
|
||
---
|
||
|
||
## 六、Phase 2 详设：MCP Server
|
||
|
||
### 6.1 架构
|
||
|
||
```
|
||
Claude.ai / ChatGPT / 自研 Agent
|
||
│
|
||
│ MCP Protocol (SSE / Streamable HTTP)
|
||
▼
|
||
┌──────────────────────────────────────┐
|
||
│ agentgis-mcp-server:8100 │
|
||
│ │
|
||
│ Python (FastAPI) + mcp-python-sdk │
|
||
│ │
|
||
│ Auth Middleware: 验证 mk_ API Key │
|
||
│ │
|
||
│ ┌────────────────────────────────┐ │
|
||
│ │ Tool Registry │ │
|
||
│ │ ├── Built-in Tools (静态) │ │
|
||
│ │ │ ├── list_suites │ │
|
||
│ │ │ ├── inspect_suite │ │
|
||
│ │ │ ├── run_suite │ │
|
||
│ │ │ ├── run_suite_async │ │
|
||
│ │ │ ├── get_run_status │ │
|
||
│ │ │ ├── get_run_results │ │
|
||
│ │ │ ├── check_compliance │ │
|
||
│ │ │ ├── search_data │ │
|
||
│ │ │ └── get_org_stats │ │
|
||
│ │ └── Suite Tools (动态) │ │
|
||
│ │ └── Phase 3 启用 │ │
|
||
│ └────────────────────────────────┘ │
|
||
│ │
|
||
│ Backend Calls: │
|
||
│ └─→ suites.mercator.cn REST API │
|
||
│ └─→ auth.mercator.cn 验证 API Key │
|
||
└──────────────────────────────────────┘
|
||
│
|
||
▼
|
||
Nginx Proxy Manager
|
||
mcp.mercator.cn → agentgis-mcp-server:8100
|
||
```
|
||
|
||
### 6.2 核心 Tool 定义
|
||
|
||
每个 tool 用 JSON Schema 定义参数和返回：
|
||
|
||
#### `list_suites`
|
||
|
||
```json
|
||
{
|
||
"name": "list_suites",
|
||
"description": "搜索可用套件。从关键词搜索或按分类浏览所有已发布套件。",
|
||
"inputSchema": {
|
||
"type": "object",
|
||
"properties": {
|
||
"keyword": { "type": "string", "description": "搜索关键词，支持模糊匹配" },
|
||
"category": { "type": "string", "description": "分类过滤" },
|
||
"page": { "type": "integer", "description": "页码，默认 1" },
|
||
"page_size": { "type": "integer", "description": "每页数量，默认 10" }
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### `inspect_suite`
|
||
|
||
```json
|
||
{
|
||
"name": "inspect_suite",
|
||
"description": "查看套件的详细信息，包括参数说明、版本历史、使用说明。Agent 在决定运行前应该先 inspect。",
|
||
"inputSchema": {
|
||
"type": "object",
|
||
"properties": {
|
||
"suite_id": { "type": "string", "description": "套件 ID" },
|
||
"version": { "type": "string", "description": "可选，指定版本" }
|
||
},
|
||
"required": ["suite_id"]
|
||
}
|
||
}
|
||
```
|
||
|
||
#### `run_suite`
|
||
|
||
```json
|
||
{
|
||
"name": "run_suite",
|
||
"description": "运行套件。参数必须匹配 inspect_suite 返回的 parameter_schema。同步执行，等待结果返回。",
|
||
"inputSchema": {
|
||
"type": "object",
|
||
"properties": {
|
||
"suite_id": { "type": "string", "description": "套件 ID" },
|
||
"version": { "type": "string", "description": "可选，指定版本" },
|
||
"inputs": {
|
||
"type": "object",
|
||
"description": "参数键值对，格式由套件的 parameter_schema 定义",
|
||
"additionalProperties": { "type": "string" }
|
||
}
|
||
},
|
||
"required": ["suite_id", "inputs"]
|
||
}
|
||
}
|
||
```
|
||
|
||
#### `run_suite_async`
|
||
|
||
与 `run_suite` 相同参数，但立即返回 `run_id`，Agent 用 `get_run_status` / `get_run_results` 轮询。
|
||
|
||
#### `check_compliance`
|
||
|
||
```json
|
||
{
|
||
"name": "check_compliance",
|
||
"description": "对套件的脚本内容触发合规检测。返回合规评分和检测报告。",
|
||
"inputSchema": {
|
||
"type": "object",
|
||
"properties": {
|
||
"suite_id": { "type": "string", "description": "套件 ID" },
|
||
"version": { "type": "string", "description": "可选，指定版本" }
|
||
},
|
||
"required": ["suite_id"]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 6.3 认证实现
|
||
|
||
```
|
||
Client Request Header:
|
||
Authorization: Bearer mk_8e8oJPtslcrwWMdbveIYF6JTj2DdVWmip1YuXDywQsY
|
||
|
||
MCP Server:
|
||
1. 提取 Bearer Token
|
||
2. 调 auth.mercator.cn/api/v1/apikeys/verify
|
||
POST { "api_key": "mk_..." }
|
||
← { "valid": true, "user_id": "...", "scopes": ["suite:read", "suite:run"] }
|
||
3. 缓存验证结果（5 分钟 TTL，Redis）
|
||
4. 在 tool 执行时检查 scope 是否匹配
|
||
```
|
||
|
||
### 6.4 部署配置
|
||
|
||
```dockerfile
|
||
# Dockerfile
|
||
FROM python:3.11-slim
|
||
|
||
WORKDIR /app
|
||
COPY requirements.txt .
|
||
RUN pip install -r requirements.txt
|
||
|
||
COPY src/ ./src/
|
||
ENV PYTHONPATH=/app/src
|
||
|
||
EXPOSE 8100
|
||
CMD ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8100"]
|
||
```
|
||
|
||
```yaml
|
||
# docker-compose 新增服务
|
||
agentgis-mcp-server:
|
||
build: ./agentgis-mcp-server
|
||
container_name: agentgis-mcp-server
|
||
networks:
|
||
- mercator-net
|
||
environment:
|
||
- SUITE_MARKET_URL=http://suite-market-backend:8001
|
||
- AUTH_CENTER_URL=http://auth-center-backend:8000
|
||
- REDIS_URL=redis://mercator-redis:6379/1
|
||
- MCP_SERVER_PORT=8100
|
||
- LOG_LEVEL=info
|
||
restart: unless-stopped
|
||
```
|
||
|
||
```
|
||
NPM 配置：
|
||
Domain: mcp.mercator.cn
|
||
Forward: http://agentgis-mcp-server:8100
|
||
SSL: Let's Encrypt
|
||
WebSocket Support: ✅ On（MCP 需要 SSE）
|
||
```
|
||
|
||
### 6.5 测试清单
|
||
|
||
| 测试项 | 方法 | 预期 |
|
||
|--------|------|------|
|
||
| API Key 正确 | curl -H "Authorization: Bearer mk_..." | 返回正常结果 |
|
||
| API Key 错误 | curl -H "Authorization: Bearer mk_wrong" | 401 Unauthorized |
|
||
| API Key 过期 | 使用已过期 Key | 401 |
|
||
| 无 API Key | curl 无 Authorization | 401 |
|
||
| MCP Inspector 连接 | npm install -g @modelcontextprotocol/inspector | 列出的 tools 正确 |
|
||
| Claude Desktop 连接 | claude_desktop_config.json 配置 | 工具正常调用 |
|
||
| run_suite 同步 | 短套件 | 等待完成后返回结果 |
|
||
| run_suite_async | 长套件 | 立即返回 run_id，轮询获取结果 |
|
||
| 并发调用 | 同时 5 个请求 | 各请求独立处理 |
|
||
|
||
---
|
||
|
||
## 七、Phase 3 详设：Suite as Tool
|
||
|
||
### 7.1 数据库模型变更
|
||
|
||
`suite_suites` 表新增字段：
|
||
|
||
```python
|
||
# suite_market 模型
|
||
class Suite(Base):
|
||
__tablename__ = "suite_suites"
|
||
|
||
# 现有字段...
|
||
id: str
|
||
name: str
|
||
# ...
|
||
|
||
# Phase 3 新增
|
||
mcp_enabled: bool = False # 是否可作为 MCP Tool 调用
|
||
mcp_tool_name: str | None = None # 自定义 tool 名，默认用 suite_id
|
||
mcp_description: str | None = None # 自定义 tool 描述，默认用 suite description
|
||
mcp_approved_at: datetime | None # 批准时间
|
||
mcp_approved_by: str | None # 批准人
|
||
mcp_call_count: int = 0 # 累计 MCP 调用次数
|
||
```
|
||
|
||
### 7.2 发布流程变更
|
||
|
||
```
|
||
开发者打包 workflow.yaml + scripts/ → .tar.gz
|
||
→ POST /publish/upload（需 API Key + Gitea Token）
|
||
→ 合规检测
|
||
→ 参数校验
|
||
→ 上传脚本包到 Gitea Packages
|
||
→ 写入 suite_suites
|
||
→ [新增] 如果合规通过 → mcp_enabled = True
|
||
→ [新增] MCP Server 重新加载 tool 列表
|
||
```
|
||
|
||
### 7.3 MCP Server 动态注册逻辑
|
||
|
||
```python
|
||
# mcp-server 启动时 + 定时刷新（每 5 分钟）
|
||
async def refresh_suite_tools():
|
||
"""从 suite-market 拉取所有 mcp_enabled=True 的套件，注册为 tool"""
|
||
async with httpx.AsyncClient() as client:
|
||
resp = await client.get(
|
||
f"{SUITE_MARKET_URL}/api/v1/suites",
|
||
params={"mcp_enabled": True},
|
||
headers={"Authorization": f"Bearer {INTERNAL_TOKEN}"}
|
||
)
|
||
suites = resp.json()
|
||
|
||
# 清空旧的 suite tools
|
||
suite_tools.clear()
|
||
|
||
for suite in suites:
|
||
# 生成 tool schema
|
||
tool_def = {
|
||
"name": suite.get("mcp_tool_name") or slugify(suite["id"]),
|
||
"description": suite.get("mcp_description") or suite.get("description", ""),
|
||
"inputSchema": {
|
||
"type": "object",
|
||
"properties": {},
|
||
"required": []
|
||
}
|
||
}
|
||
|
||
# 从 parameter_schema 转换参数定义
|
||
for param in suite.get("parameter_schema", []):
|
||
tool_def["inputSchema"]["properties"][param["name"]] = {
|
||
"type": param.get("json_type", "string"),
|
||
"description": param.get("description", "")
|
||
}
|
||
if param.get("required"):
|
||
tool_def["inputSchema"]["required"].append(param["name"])
|
||
|
||
suite_tools[suite["id"]] = tool_def
|
||
```
|
||
|
||
### 7.4 AI Analytics 面板
|
||
|
||
**数据源：** `agent_action_log` 表
|
||
|
||
**面板内容（可以用简单 K/V 展示或选型 Grafana）：**
|
||
|
||
| 指标 | SQL |
|
||
|------|-----|
|
||
| 今日活跃 Agent 数 | `SELECT COUNT(DISTINCT api_key_id) FROM agent_action_log WHERE created_at > today()` |
|
||
| 操作 Top 5 | `SELECT action, COUNT(*) FROM agent_action_log GROUP BY action ORDER BY 2 DESC LIMIT 5` |
|
||
| 成功/失败率 | `SELECT status, COUNT(*) FROM agent_action_log GROUP BY status` |
|
||
| 最活跃套件 Top 5 | `SELECT target_id, COUNT(*) FROM agent_action_log WHERE target_type='suite' GROUP BY target_id` |
|
||
| 操作趋势（最近 7 天） | `SELECT DATE(created_at), COUNT(*) FROM agent_action_log WHERE created_at > 7days GROUP BY 1` |
|
||
|
||
**前端集成：** suite-market 前端 Settings → AI Analytics 页
|
||
|
||
---
|
||
|
||
## 八、Phase 4 展望：语义模型与 Agent 自动化
|
||
|
||
> 这部分是远期方向，写在这里作为技术储备，不纳入近期迭代。
|
||
|
||
### 8.1 语义模型适配
|
||
|
||
基于 Apache Ossie 扩展空间语义：
|
||
|
||
```yaml
|
||
version: "0.1.1"
|
||
semantic_model:
|
||
- name: "土地利用分析套件"
|
||
description: "基于遥感影像的土地利用分类与分析"
|
||
datasets:
|
||
- name: "land_use_parcels"
|
||
fields:
|
||
- name: "geom"
|
||
description: "地块边界（Polygon, EPSG:4326）"
|
||
custom_extensions:
|
||
- vendor_name: AgentGIS
|
||
data: '{"spatial_data": {"type": "polygon", "srid": 4326}}'
|
||
- name: "land_type"
|
||
description: "土地利用类型编码"
|
||
- name: "area_sqkm"
|
||
description: "面积（平方公里）"
|
||
metrics:
|
||
- name: "各类型占比"
|
||
expression: "COUNT(*) * 1.0 / SUM(COUNT(*)) OVER()"
|
||
```
|
||
|
||
### 8.2 Agent 自决策流程
|
||
|
||
```
|
||
用户输入： "帮我分析北京五环内的商业用地分布"
|
||
│
|
||
├── (Phase 4) Agent 读取语义模型 → 匹配到 land_use_parcels
|
||
├── (Phase 4) Agent 自动选择"围栏 + 分类统计"套件组合
|
||
├── (Phase 4) 自动填充参数：center=北京市中心, radius=五环半径
|
||
│
|
||
├── (Phase 3) MCP Server → run_suite("geofence-analysis", inputs={...})
|
||
│
|
||
└── (Phase 2) 执行 → 返回结果 → Agent 解读输出
|
||
```
|
||
|
||
---
|
||
|
||
## 九、附录
|
||
|
||
### A. 工作量估算汇总
|
||
|
||
| Phase | 工作项 | 类型 | 估计人天 | 优先 |
|
||
|-------|--------|------|---------|------|
|
||
| P1 | Skill 目录结构搭建 | 文档 | 0.5 | 🔴 |
|
||
| P1 | Utility Skill × 3 | 文档 | 1 | 🔴 |
|
||
| P1 | Platform Skill × 2 | 文档 | 1 | 🔴 |
|
||
| P1 | Use-case Skill × 1 | 文档 | 1 | 🔴 |
|
||
| P1 | CLI 扩展（auth/suite/search/stats） | 编码 | 3 | 🔴 |
|
||
| P1 | CLI JSON 输出格式化 | 编码 | 1 | 🔴 |
|
||
| P1 | 审计表 + middleware | 编码 | 2 | 🟡 |
|
||
| **P1 小计** | | | **9.5** | |
|
||
| P2 | MCP Server 容器搭建 + 部署 | 运维 | 1 | 🔴 |
|
||
| P2 | 5 个核心 tool 实现 | 编码 | 4 | 🔴 |
|
||
| P2 | API Key 认证中间件 | 编码 | 1 | 🔴 |
|
||
| P2 | 测试对接 + 调试 | 测试 | 2 | 🔴 |
|
||
| P2 | MCP 使用文档 | 文档 | 1 | 🟡 |
|
||
| **P2 小计** | | | **9** | |
|
||
| P3 | suite-market 模型变更 | 编码 | 1 | 🔴 |
|
||
| P3 | 发布流程修改 | 编码 | 2 | 🔴 |
|
||
| P3 | MCP 动态注册 | 编码 | 2 | 🔴 |
|
||
| P3 | 异步执行增强 | 编码 | 2 | 🟡 |
|
||
| P3 | Analytics 面板前端 | 编码 | 3 | 🟡 |
|
||
| P3 | Use-case Skill × 3 | 文档 | 2 | 🟡 |
|
||
| **P3 小计** | | | **12** | |
|
||
|
||
**总计：约 30 人天**（分 3 个阶段执行）
|
||
|
||
### B. Issue 创建模板
|
||
|
||
Boss 批准后，按以下模板开 Issue：
|
||
|
||
```markdown
|
||
## 标题
|
||
[Agent集成] Phase X: <工作项名称>
|
||
|
||
## 背景
|
||
（为什么做、参考了 CARTO for Agents 的什么设计）
|
||
|
||
## 需求描述
|
||
（具体做什么，验收条件）
|
||
|
||
## 技术参考
|
||
- 架构文档: research/carto-for-agents-architecture-notes.md
|
||
- 相关 API: （如有）
|
||
- 需要修改的仓库: suite-market / gis-actions / agent-profiles
|
||
|
||
## 验收条件
|
||
- [ ] 条件 1
|
||
- [ ] 条件 2
|
||
|
||
## 指派
|
||
@Admin
|
||
```
|
||
|
||
### C. 决策记录
|
||
|
||
| 决策 | 选择 | 理由 |
|
||
|------|------|------|
|
||
| MCP 协议版本 | 2025-06-18（最新稳定版） | 客户端支持最广 |
|
||
| MCP Server 语言 | Python (FastAPI) | 与现有技术栈一致，mcp-python-sdk 成熟 |
|
||
| MCP 传输方式 | SSE（Server-Sent Events） | 兼容性最好，NPM 支持 WebSocket |
|
||
| Agent Skill 格式 | Markdown + JSON catalog | 人类可读，Agent 可解析，无需新工具 |
|
||
| CLI JSON 输出 | 全局 --format 参数 | 不影响现有 text 输出兼容性 |
|
||
| 审计存储 | PostgreSQL（suite_market_db） | 与现有数据库一致，避免引入新存储 |
|
||
| 容器网络 | 加入现有 mercator-net | 统一网络管理 |
|
||
|
||
---
|
||
|
||
*文档版本: v1.0*
|
||
*下次评审: Phase 1 完成后*
|