From 6465e27d2238bd04f4f847457b35574a32fb9806 Mon Sep 17 00:00:00 2001 From: Huawei Date: Tue, 21 Jul 2026 02:28:54 +0000 Subject: [PATCH] =?UTF-8?q?[Huawei]=20=E6=B7=BB=E5=8A=A0=20AgentGIS=20Agen?= =?UTF-8?q?t=20=E9=9B=86=E6=88=90=E5=B1=82=E6=9E=B6=E6=9E=84=E8=A7=84?= =?UTF-8?q?=E5=88=92=E4=B8=8E=E8=BF=AD=E4=BB=A3=E8=B7=AF=E7=BA=BF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../agentgis-agent-integration-roadmap.md | 916 ++++++++++++++++++ 1 file changed, 916 insertions(+) create mode 100644 research/agentgis-agent-integration-roadmap.md diff --git a/research/agentgis-agent-integration-roadmap.md b/research/agentgis-agent-integration-roadmap.md new file mode 100644 index 0000000..1452680 --- /dev/null +++ b/research/agentgis-agent-integration-roadmap.md @@ -0,0 +1,916 @@ +# 🏗 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 --suite-id --input k=v + ├── agc config set/get/list + └── agc config set api-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 --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 # 圓前 config set api-key 的改版 +│ ├── token show # 星瀺圓前 API Key掩码 +│ └── token test # 测试 API Key 有效性 +│ +├── suite +│ ├── search # 搜玢套件封装 GET /api/v1/suites/search +│ ├── inspect # 查看套件诊情 +│ ├── run --input k=v # 圓前 run 的粟简版 +│ └── list-status # 查看历史执行状态新增功胜 +│ +├── data +│ ├── list # 列出已连接的数据源远期 +│ ├── import # 富入数据远期 +│ └── export # 富出结果远期 +│ +├── compliance +│ └── check # 觊发合规检测 +│ +├── org +│ └── stats # 组织统计 +│ +├── mcp +│ ├── start # 启劚本地 MCP 代理远期 +│ └── status # 查看 MCP 连接状态 +│ +└── config (现有) + ├── set + ├── get + └── list +``` + +**党局标志** +- `--format json|text` — 控制蟓出栌匏。默讀 `text`人类友奜`json`Agent 友奜 +- `--quiet` — 只蟓出结果数据无 banner/提瀺信息 +- `--timeout ` — 执行超时 + +**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 完成后*