SuiteHub/agent-profiles
4
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
bfbadface44865e4b0344ccdf671ccf18bf51d0a
agent-profiles/research/agentgis-agent-integration-roadmap.md
T

39 KiB
Raw Blame History

🏗️ AgentGIS Cloud Platform — Agent 集成层架构规划与迭代路线

编制: Huawei | 日期: 2026-07-21 基于: CARTO for Agents 架构研究 + AgentGIS 平台现状 定位: 平台下一阶段架构升级的决策参考

目录

  1. 现状快照
  2. 目标架构蓝图
  3. 差距分析
  4. 迭代路线
  5. Phase 1 详设：Skill 目录 + CLI 扩展
  6. Phase 2 详设：MCP Server
  7. Phase 3 详设：Suite as Tool
  8. 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
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
MCP Server 托管式，OAuth/Token 认证 无 🔴 严重 Phase 2
Workflow as Tool 一键 MCP publish 无 🔴 严重 Phase 3
平台工具（内置） 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
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 可程序化解析：

# Skill: <名称>

> 层级: utility | platform | use-case
> 触发词: keyword1, keyword2, keyword3
> 依赖: [utility/install-and-auth, ...]

## 适用场景

（用自然语言描述什么情况下 Agent 应该加载这个 skill）

## 前置条件

（需要在加载这个 skill 之前已满足的条件）

## 步骤

### 步骤 1：xxxx

```bash
agc <command> <args> --format 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：

{
  "status": "ok" | "error",
  "data": { ... },
  "error": { "code": "ERROR_CODE", "message": "Human readable" }
}

5.5 审计埋点设计

新表 agent_action_log（suite_market_db）：

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

{
  "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

{
  "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

{
  "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

{
  "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
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"]

# 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 表新增字段：

# 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 动态注册逻辑

# 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 扩展空间语义：

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：

## 标题
[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 完成后

Reference in New Issue View Git Blame Copy Permalink