# Mercator 云平台 & AgentGIS 培训文案

> 基于 SuiteHub/agent-profiles 文档及 2026-07-16 实际系统验证。
> 预计 32 页，每页标题 + 要点 = 一张 PPT。

---

## 第一部分：平台概述（2 页）

### 第 1 页：Mercator 云平台是什么

- 企业级智能自动化云平台
- 核心定位：**AI 调度 + 本地执行 + 全链路安全**
- 三个核心子系统：
  - **统一认证中心**（auth.mercator.cn）— 你是谁
  - **专家套件市场**（suites.mercator.cn）— 你能做什么
  - **用户交流中心**（discussions.mercator.cn）— 怎么反馈
- AgentGIS = GIS 能力扩展层，面向地理空间数据处理

### 第 2 页：平台总体架构

- 云端 + 本地两层架构
- **云端**：认证、市场、讨论区、代码托管、脚本包分发
- **本地**：GIS Actions 执行引擎，下载脚本包后在本地运行（Linux Docker / Windows 本机进程）
- **核心原则：数据永不离开本地**
- 用户数据始终在自己的机器上处理，不上传云端
- Linux：Docker 容器隔离执行 / Windows：本机进程执行
- 云端只做管理、分发、协作

---

## 第二部分：统一认证中心（5 页）

### 第 3 页：Auth Center 是什么

- 域名：auth.mercator.cn
- 职责：统一身份认证，所有子系统的入口
- 一句话：**一次登录，通行全平台**
- 支持三种登录方式：
  - 密码登录
  - 企业微信扫码登录
  - 忘记密码 → 邮箱重置

### 第 4 页：登录与注册

- **密码登录**：输入用户名/邮箱 + 密码
- **企业微信扫码**：首次扫码自动创建账户，绑定企业微信身份
- **注册**：自助注册，需企业邮箱验证（@mercator.cn）
- **忘记密码**：通过绑定邮箱发送重置链接
- 支持 MFA（多因素认证）：TOTP 动态码

### 第 5 页：API Key 管理

- 什么场景用：AI Agent（如 OpenClaw）调用平台 API
- API Key 格式：`mk_` 开头，46 位字符
- 获取方式：登录 Auth Center → API Key 管理 → 创建
- 可设置过期时间（1-365 天，默认 90 天）
- 可随时吊销
- **安全提醒**：API Key 创建后只显示一次，请立即保存

### 第 6 页：OAuth2 / OIDC 服务端

- Auth Center 内置完整的 OAuth2 和 OpenID Connect 服务端
- 支持授权码流程（Authorization Code）+ PKCE
- 支持 Refresh Token 自动续期
- RS256 签名，JWKS 公开密钥
- 企业微信为 OIDC 身份源
- 可注册第三方 OAuth Client，实现 SSO

### 第 7 页：个人信息管理

- 个人资料：修改昵称、邮箱、手机号、地址
- 头像上传：支持 JPG/PNG/WebP/GIF，最大 500KB
- 会话管理：查看当前登录设备，可远程登出
- 修改密码

---

## 第三部分：专家套件市场（8 页）

### 第 8 页：Suite Market 是什么

- 域名：suites.mercator.cn
- 职责：GIS 套件的发现、发布、版本管理
- 面向两类用户：
  - **套件使用者**：浏览、选择、执行套件
  - **套件开发者**：开发、测试、发布套件
- 公开可访问，认证只约束操作（创建/执行/发布）

### 第 9 页：浏览与搜索套件

- **套件列表**：展示所有已发布套件
  - 名称、描述、分类、版本号、作者
- **搜索栏**：关键词搜索名称和描述
- **分类筛选**：按业务分类过滤（如土地整治、数据转换等）
- **状态筛选**：按发布状态筛选

### 第 10 页：套件详情

- 点击套件名称进入详情页
- 展示内容：
  - **详细描述**：套件的完整功能说明
  - **输入参数**：需要用户提供的参数列表（名称、类型、是否必填、默认值）
  - **输出结果**：执行完成后能获取的结果说明
  - **版本选择**：可选择指定版本执行
- 快速执行命令：一键复制 `agc run` 命令

### 第 11 页：选择套件的方法

- 看用途：描述是否匹配你的需求？
- 看输入：需要提供的文件或参数是否容易获取？
- 看输出：结果是否符合预期？
- 看不明白的套件就不选，换一个
- 先查市场，再动手——避免重复造轮子

### 第 12 页：套件的结构

- 一个套件 = workflow.yaml + scripts/ 目录 + [可选] demo-data/ 目录
  - workflow.yaml：工作流定义
  - scripts/：Python 脚本文件
  - demo-data/（可选）：Playground 在线演示用的样例数据
    - 有 demo-data/ 的套件可在 agentgis.cn Playground 中在线试用
    - 没有 demo-data/ 的套件只能通过 agc run 本地执行
- workflow.yaml 定义了：
  - **name**：套件名称
  - **description**：功能描述
  - **version**：版本号
  - **slug**：英文包名（可选）
  - **params**：输入参数声明
  - **base_image**：运行镜像（默认 gis-base:latest）
  - **steps**：执行步骤列表
- scripts/：包含实际的 Python 脚本文件

### 第 13 页：工作流（Workflow）机制

- Steps 定义执行流水线
- 引用语法：
  - `$params.xxx`：引用用户输入的参数
  - `$steps.step_id.output_name`：引用前一步骤的输出
- 步骤依赖：`depends_on` 定义执行顺序
- 所有步骤共享 `/tmp/output` 工作目录
- 示例：三步流水线
  ```
  Step 1: 空间分析（flow_dir.py）→ 输出流向栅格
  Step 2: 汇流累积（accumulation.py）→ 依赖 Step 1
  Step 3: 河网提取（stream_extract.py）→ 依赖 Step 2
  ```

### 第 14 页：发布套件（面向开发者）

- 前置条件：
  - API Key（auth.mercator.cn 获取）
  - Gitea Token（git.mercator.cn 获取，需 write:packages 权限）
- 发布方式：
  - **文件上传**：`POST /publish/upload`，上传 tar.gz/zip
  - **Git 仓库**：`POST /publish`，从 Git 仓库拉取
- 发布流程自动完成：
  - 合规检测 → 参数校验 → 打包脚本 → 上传 Gitea Packages → 注册到数据库
  - 包含 demo-data/ 目录的套件自动支持 Playground 在线演示

### 第 15 页：版本管理

- 每次发布自动保存历史版本快照
- 版本记录包含：version、workflow 定义、package_url、description、category、tags
- 用户可通过 `--version x.x.x` 指定执行历史版本
- API 支持：`GET /api/v1/suites/{id}?version=1.0.0`
- 包命名规则：中文自动转拼音，或通过 slug 字段手动指定英文名

---

## 第四部分：用户交流中心（3 页）

### 第 16 页：Discussions 是什么

- 域名：discussions.mercator.cn
- 职责：用户交流、反馈、问题讨论
- 功能：
  - 创建话题
  - 评论互动
  - 标签分类
  - 话题关闭/重开

### 第 17 页：话题与标签

- 预置标签体系：
  - **bug**（红色）：缺陷报告
  - **feature**（绿色）：功能请求
  - **question**（蓝色）：使用疑问
  - **discussion**（紫色）：一般讨论
  - **announcement**（橙色）：公告
  - **suggestion**（青色）：改进建议
  - **auto-report**（灰色）：系统自动生成的报告
- 标签帮助快速筛选和分类话题

### 第 18 页：错误反馈机制

- gis-actions 执行失败时，会自动发话题到 Discussions（需配置 API Key）
- 自动生成的话题包含：
  - 套件名称和版本号
  - 错误摘要
  - 脱敏后的日志
  - 标签：bug + auto-report
- 好处：
  - 开发者第一时间知道套件出问题
  - 其他用户可能遇到相同问题可以找到解决方案
  - 可关闭话题表示已修复

---

## 第五部分：GIS Actions 本地执行引擎（6 页）

### 第 19 页：GIS Actions 是什么

- 本地执行器，安装在自己的 Linux 机器上
- 命令行工具：`agc`
- 完整命令集：
  - `agc config` — 配置 API Key 和市场地址
  - `agc run` — 执行套件（支持 `--watch` 实时输出、`--resume` 续跑）
  - `agc search / info` — 搜索和查看套件
  - `agc doctor` — 环境诊断
  - `agc logs / cache` — 运行历史和缓存管理
  - `agc mcp` — AI Agent 集成入口（MCP 协议）
  - `agc self-update` — 自动升级
- 职责：从套件市场下载脚本包 → 在本地 Docker 中执行 → 返回结果
- 安装方式：一行命令
  ```bash
  curl -sLO https://packages.mercator.cn/public/gis-actions/latest.deb
  sudo dpkg -i latest.deb
  ```

### 第 20 页：环境要求

- 操作系统：Linux（Debian / Ubuntu 推荐）
- Docker：需要安装 Docker Engine
- Python 3.10+（已随 deb 包安装）
- 网络：需要能访问 suites.mercator.cn（查询套件）和 git.mercator.cn（下载脚本包）
- 首次运行时自动下载 gis-base 镜像（约 465MB）

### 第 21 页：配置 API Key

- 为什么需要 API Key：用于认证身份、调取套件信息和下载脚本包
- 获取方式：登录 auth.mercator.cn → API Key 管理 → 创建
- 配置方式：
  ```bash
  agc config set api-key mk_xxxxxxxxxxxxxxxxxxxx
  ```
- 查看配置：`agc config list`
- 切换市场地址：`agc config set market-url <url>`
- 所有配置保存在 `~/.config/gis-actions/config.toml`

### 第 22 页：执行套件

- 基本命令：
  ```bash
  agc run /tmp/output --suite-id <suite-id> --input key=value
  agc run /tmp/output --suite-id <suite-id> --input key=value --watch   # 实时输出
  agc run /tmp/output --suite-id <suite-id> --input key=value --resume  # 断点续跑
  ```
- 其他命令：
  | 命令 | 用途 |
  |------|------|
  | `agc search <query>` | 搜索套件 |
  | `agc info <suite-id>` | 套件详情 |
  | `agc logs` | 历史记录 |
  | `agc cache list / clean` | 缓存管理 |
  | `agc mcp` | AI Agent 集成（MCP 协议） |
- 执行流程：
  1. 从市场查询套件的脚本包地址（package_url）
  2. 检查本地缓存，命中则跳过下载
  3. 从 Gitea Packages 下载脚本包（自动缓存）
  4. 解压并读取 workflow.yaml
  5. 按 depends_on 拓扑顺序执行各步骤
  6. 每步在独立 Docker 容器中运行（docker run --rm gis-base）
  7. 结果写入本地工作目录的 `_step_outputs/` 下
  8. 清理下载的脚本包

### 第 23 页：数据安全

- **数据永不离开本地**
- 输入文件始终在用户自己的机器上
- 数据处理在本地 Docker 容器中完成
- 不上传到云端、不经过平台服务器
- 执行完成后脚本包自动清理
- 用户数据和结果文件始终保留在本地

### 第 24 页：错误处理

- 执行失败怎么办：
  1. 查看控制台错误信息
  2. 检查输入文件路径是否正确
  3. 运行 `agc doctor` 一键诊断环境：
     - Docker 是否运行
     - gis-base 镜像是否存在
     - API Key 是否有效
     - 能否连通套件市场
  4. 查看失败记录：`agc logs --status failed`
  5. 确认已升级到最新版：`agc self-update`
- 自动报告失败：已配置 API Key 的情况下，执行失败会自动发帖到 Discussions
- 如果怀疑是套件本身的 Bug：
  - 配置 API Key 后，自动反馈到讨论区
  - 或手动访问 discussions.mercator.cn 发帖

---

## 第六部分：GIS Base 基础镜像（3 页）

### 第 25 页：GIS Base 是什么

- 所有套件运行的基石
- 预装完整 GIS 工具链的 Linux Docker 镜像
- 永久存储在用户本地，所有套件共享
- 镜像名：`gis-base:latest`
- 大小：约 465MB
- 基底：Debian slim（bookworm）

### 第 26 页：预装环境

- 系统级：
  - GDAL 命令行工具
  - mdbtools（Access 数据库读取）
  - libgeos、libproj 等 GIS 底层库
- Python 3.11：
  - 核心 GIS：numpy、shapely、pyproj、fiona、rasterio、geopandas
  - 数据处理：pandas、scipy、openpyxl、xlrd、xlsxwriter
  - 可视化：matplotlib
  - 文档生成：python-docx、reportlab
  - 工具库：Pillow、requests、Jinja2

### 第 27 页：获取方式

- 安装 gis-actions 时自动下载
- 也可手动拉取：
  ```bash
  docker pull registry.mercator.cn/library/gis-base:latest
  ```
- 离线环境：在可联网机器上导出镜像
  ```bash
  docker save gis-base:latest | gzip > gis-base.tar.gz
  ```
  然后在目标机器
  ```bash
  docker load -i gis-base.tar.gz
  ```

### 第 28 页：AI Agent 集成（MCP 协议）

- GIS Actions v3.1 起支持 MCP（Model Context Protocol）
- AI Agent（Claude / DeepSeek / 本地 Agent）可自动发现和调用 GIS 工具
- 启动方式：
  ```bash
  agc mcp                            # stdio 模式（默认）
  agc mcp --transport sse --port 8080  # SSE 模式（HTTP）
  ```
- AI Agent 无需关心 Docker、镜像、套件包——只需调用工具名和参数

### 第 29 页：包签名与安全

- 套件包发布时使用 Ed25519 签名
- 下载后自动验证签名，防止篡改
- 手动验签：`python3 -m gis_actions.signing verify <file> <sig>`

- 安装 gis-actions 时自动下载
- 手动下载：
  ```bash
  curl -sLO https://packages.mercator.cn/public/gis-base/latest.tar.gz
  docker load -i latest.tar.gz
  ```
- 镜像存储在 MinIO 公共存储上
- 所有套件脚本在此镜像中隔离执行

---

## 第八部分：AI Agent 集成与安全（2 页）

> 新增：MCP 协议适配 + 包签名验证

---

### 第 28 页：AI Agent 集成（MCP 协议）

- GIS Actions v3.1 起支持 MCP（Model Context Protocol）
- AI Agent（Claude / DeepSeek / 本地 Agent）可自动发现和调用 GIS 工具
- 启动方式：
  ```bash
  agc mcp                            # stdio 模式（默认）
  agc mcp --transport sse --port 8080  # SSE 模式（HTTP）
  ```
- AI Agent 无需关心 Docker、镜像、套件包——只需调用工具名和参数

### 第 29 页：包签名与安全

- 套件包发布时使用 Ed25519 签名
- 下载后自动验证签名，防止篡改
- 手动验签：`python3 -m gis_actions.signing verify <file> <sig>`

---

## 第九部分：各系统关系与生态（3 页）

### 第 30 页：端到端工作流程

```
用户 → Auth Center 登录/获取 API Key
    → 浏览 Suite Market → 选择合适的套件
    → 复制 agc run 命令 → 在本地终端执行
    → GIS Actions 下载脚本包 → Docker 运行 → 得到结果
    → 出问题 → Discussions 反馈 → 开发者收到 → 修复 → 发布新版本
```

### 第 31 页：系统关系图

```
┌─────────────────────────────────────────────────┐
│                  云端平台                         │
│                                                   │
│  Auth Center ◄── Suite Market ◄── Discussions    │
│     │                  │                           │
│     │                  ▼                           │
│     │          Gitea Packages                      │
│     │        （脚本包 + 基础镜像）                  │
│     └──────────────────│───────────────────────────┘
                        │ 下载
                        ▼
┌─────────────────────────────────────────────────┐
│                  本地用户                         │
│                                                   │
│  gis-actions (agc) ── docker run ── 脚本执行     │
│                          │                        │
│                     gis-base 镜像                  │
│                    （本地 + 只读）                  │
└─────────────────────────────────────────────────┘
```

### 第 32 页：总结

- **Mercator 云平台**：认证 + 市场 + 讨论区，构成完整生态
- **AgentGIS**：将 GIS 能力扩展到本地，数据安全有保障
- **GIS Actions**：一键安装，即装即用
- **GIS Base**：开箱即用的 GIS 工具箱
- **核心价值**：数据不离开本地，算法安全交付，身份贯穿全域

---

> 本文案基于 SuiteHub/agent-profiles 文档及 2026-07-16 实际系统部署验证编写。