465 lines
16 KiB
Markdown
465 lines
16 KiB
Markdown
# 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**：安装在自己的机器上（deb 包）
|
||
- **Windows**：安装 agc.exe（zip 包）
|
||
- 命令行工具：`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` — 自动升级
|
||
- 职责：从套件市场下载脚本包 → 在本地执行（Linux Docker / Windows 本机）→ 返回结果
|
||
- 安装方式：
|
||
**Linux：**
|
||
```bash
|
||
curl -sLO https://packages.mercator.cn/public/gis-actions/latest.deb
|
||
sudo dpkg -i latest.deb
|
||
```
|
||
**Windows：**
|
||
1. 下载 latest-windows.zip
|
||
2. 解压到 %LOCALAPPDATA%\AgentGIS\gis-actions\
|
||
3. 加入 PATH
|
||
4. 验证：`agc --help`
|
||
|
||
### 第 20 页：环境要求
|
||
|
||
**Linux：**
|
||
- 操作系统：Debian / Ubuntu
|
||
- Docker Engine
|
||
- Python 3.10+
|
||
- 首次运行时自动下载 gis-base 镜像（约 465MB）
|
||
|
||
**Windows：**
|
||
- 操作系统：Windows 10/11
|
||
- ArcMap 10.8（arcpy 步骤需要）
|
||
- 无需 Docker
|
||
|
||
**通用：**
|
||
- 网络：需要能访问 suites.mercator.cn 和 git.mercator.cn
|
||
|
||
### 第 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. 每步按 runtime 执行：
|
||
- runtime: docker → Docker 容器（gis-base 镜像）
|
||
- runtime: python3 → 本地 subprocess
|
||
- runtime: arcpy → 系统 arcpy（Windows only）
|
||
7. 结果写入本地工作目录的 `_step_outputs/` 下
|
||
8. 清理下载的脚本包和临时文件
|
||
|
||
### 第 23 页：数据安全
|
||
|
||
- **数据永不离开本地**
|
||
- 输入文件始终在用户自己的机器上
|
||
- 数据处理在本地完成（Linux Docker 容器 / Windows 本机进程）
|
||
- 不上传到云端、不经过平台服务器
|
||
- 执行完成后脚本包自动清理
|
||
- 用户数据和结果文件始终保留在本地
|
||
|
||
### 第 24 页：错误处理
|
||
|
||
- 执行失败怎么办：
|
||
1. 查看控制台错误信息
|
||
2. 检查输入文件路径是否正确
|
||
3. 运行 `agc doctor` 一键诊断环境：
|
||
- Linux: Docker 是否运行 / Windows: agc.exe 是否在 PATH
|
||
- 镜像是否存在（Linux）
|
||
- API Key 是否有效
|
||
- 能否连通套件市场
|
||
4. 查看失败记录：`agc logs --status failed`
|
||
5. 确认已升级到最新版：`agc self-update`（Linux: deb / Windows: zip 自动解压）
|
||
- 自动报告失败：已配置 API Key 的情况下，执行失败会自动发帖到 Discussions
|
||
- 如果怀疑是套件本身的 Bug：
|
||
- 配置 API Key 后，自动反馈到讨论区
|
||
- 或手动访问 discussions.mercator.cn 发帖
|
||
|
||
---
|
||
|
||
## 第六部分：GIS Base 基础镜像（3 页）
|
||
|
||
### 第 25 页：GIS Base 是什么
|
||
|
||
- **Linux 模式**：所有 Docker 套件的运行基石
|
||
- 预装完整 GIS 工具链的 Linux Docker 镜像
|
||
- 永久存储在用户本地，所有套件共享
|
||
- 镜像名：`gis-base:latest`，约 465MB
|
||
- **Windows 模式**：不需要 gis-base 镜像
|
||
- 使用本地 arcpy / Python 环境
|
||
- 依赖 ArcMap 10.8 的 arcpy 环境
|
||
|
||
### 第 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 下载脚本包 → 执行（Linux Docker / Windows 本机）→ 得到结果
|
||
→ 出问题 → Discussions 反馈 → 开发者收到 → 修复 → 发布新版本
|
||
```
|
||
|
||
### 第 31 页：系统关系图
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────┐
|
||
│ 云端平台 │
|
||
│ │
|
||
│ Auth Center ◄── Suite Market ◄── Discussions │
|
||
│ │ │ │
|
||
│ │ ▼ │
|
||
│ │ Gitea Packages │
|
||
│ │ （脚本包 + 基础镜像） │
|
||
│ └──────────────────│───────────────────────────┘
|
||
│ 下载
|
||
▼
|
||
┌─────────────────────────────────────────────────┐
|
||
│ 本地用户 │
|
||
│ │
|
||
│ gis-actions (agc) │
|
||
│ ├─ Linux: docker run gis-base → 脚本执行 │
|
||
│ └─ Windows: subprocess(arcpy/python3) → 执行 │
|
||
└─────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 第 32 页：总结
|
||
|
||
- **Mercator 云平台**：认证 + 市场 + 讨论区，构成完整生态
|
||
- **AgentGIS**：将 GIS 能力扩展到本地，数据安全有保障
|
||
- **GIS Actions**：一键安装（Linux deb / Windows zip），即装即用
|
||
- **GIS Base**：Linux Docker 模式的 GIS 工具箱 / Windows 使用本地 arcpy
|
||
- **核心价值**：数据不离开本地，算法安全交付，身份贯穿全域
|
||
|
||
---
|
||
|
||
> 本文案基于 SuiteHub/agent-profiles 文档及 2026-07-16 实际系统部署验证编写。
|
||
|