docs: add training PPT outline for Mercator Cloud Platform & AgentGIS

2026-07-16 08:58:54 +00:00
parent 7abeb8f4ac
commit d546fc7027
1 changed files with 354 additions and 0 deletions
@@ -0,0 +1,354 @@
+# Mercator 云平台 & AgentGIS 培训文案
+
+> 基于 SuiteHub/agent-profiles 文档及 2026-07-16 实际系统验证。
+> 预计 30 页，每页标题 + 要点 = 一张 PPT。
+
+---
+
+## 第一部分：平台概述（2 页）
+
+### 第 1 页：Mercator 云平台是什么
+
+- 企业级智能自动化云平台
+- 核心定位：**AI 调度 + 本地执行 + 全链路安全**
+- 三个核心子系统：
+  - **统一认证中心**（auth.mercator.cn）— 你是谁
+  - **专家套件市场**（suites.mercator.cn）— 你能做什么
+  - **用户交流中心**（discussions.mercator.cn）— 怎么反馈
+- AgentGIS = GIS 能力扩展层，面向地理空间数据处理
+
+### 第 2 页：平台总体架构
+
+- 云端 + 本地两层架构
+- **云端**：认证、市场、讨论区、代码托管、脚本包分发
+- **本地**：GIS Actions 执行引擎，下载脚本包后在本地 Docker 中运行
+- **核心原则：数据永不离开本地**
+- 用户数据始终在自己的机器上处理，不上传云端
+- 云端只做管理、分发、协作
+
+---
+
+## 第二部分：统一认证中心（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/ 目录
+- 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 → 注册到数据库
+
+### 第 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`
+- 职责：从套件市场下载脚本包 → 在本地 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
+  export AGENTGIS_API_KEY=mk_xxxxxxxxxxxxxxxxxx
+  ```
+- 建议写入 `~/.bashrc` 或 `~/.profile` 长期生效
+
+### 第 22 页：执行套件
+
+- 基本命令：
+  ```bash
+  agc run /tmp/output --suite-id <suite-id> --input key=value
+  ```
+- 执行流程：
+  1. 从市场查询套件的脚本包地址（package_url）
+  2. 从 Gitea Packages 下载脚本包
+  3. 解压并读取 workflow.yaml
+  4. 按 depends_on 拓扑顺序执行各步骤
+  5. 每步在独立 Docker 容器中运行（docker run --rm gis-base）
+  6. 结果写入本地工作目录的 `_step_outputs/` 下
+  7. 清理下载的脚本包
+
+### 第 23 页：数据安全
+
+- **数据永不离开本地**
+- 输入文件始终在用户自己的机器上
+- 数据处理在本地 Docker 容器中完成
+- 不上传到云端、不经过平台服务器
+- 执行完成后脚本包自动清理
+- 用户数据和结果文件始终保留在本地
+
+### 第 24 页：错误处理
+
+- 执行失败怎么办：
+  1. 查看控制台错误信息
+  2. 检查输入文件路径是否正确
+  3. 确认 Docker 是否正常运行（`docker ps`）
+  4. 确认 gis-actions 版本（`dpkg -l gis-actions`）
+- 如果怀疑是套件本身的 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
+  curl -sLO https://packages.mercator.cn/public/gis-base/latest.tar.gz
+  docker load -i latest.tar.gz
+  ```
+- 镜像存储在 MinIO 公共存储上
+- 所有套件脚本在此镜像中隔离执行
+
+---
+
+## 第七部分：各系统关系与生态（3 页）
+
+### 第 28 页：端到端工作流程
+
+```
+用户 → Auth Center 登录/获取 API Key
+    → 浏览 Suite Market → 选择合适的套件
+    → 复制 agc run 命令 → 在本地终端执行
+    → GIS Actions 下载脚本包 → Docker 运行 → 得到结果
+    → 出问题 → Discussions 反馈 → 开发者收到 → 修复 → 发布新版本
+```
+
+### 第 29 页：系统关系图
+
+```
+┌─────────────────────────────────────────────────┐
+│                  云端平台                         │
+│                                                   │
+│  Auth Center ◄── Suite Market ◄── Discussions    │
+│     │                  │                           │
+│     │                  ▼                           │
+│     │          Gitea Packages                      │
+│     │        （脚本包 + 基础镜像）                  │
+│     └──────────────────│───────────────────────────┘
+                        │ 下载
+                        ▼
+┌─────────────────────────────────────────────────┐
+│                  本地用户                         │
+│                                                   │
+│  gis-actions (agc) ── docker run ── 脚本执行     │
+│                          │                        │
+│                     gis-base 镜像                  │
+│                    （本地 + 只读）                  │
+└─────────────────────────────────────────────────┘
+```
+
+### 第 30 页：总结
+
+- **Mercator 云平台**：认证 + 市场 + 讨论区，构成完整生态
+- **AgentGIS**：将 GIS 能力扩展到本地，数据安全有保障
+- **GIS Actions**：一键安装，即装即用
+- **GIS Base**：开箱即用的 GIS 工具箱
+- **核心价值**：数据不离开本地，算法安全交付，身份贯穿全域
+
+---
+
+> 本文案基于 SuiteHub/agent-profiles 文档及 2026-07-16 实际系统部署验证编写。