12 KiB
12 KiB
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 中执行 → 返回结果
- 安装方式：一行命令
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 管理 → 创建
- 配置方式：
export AGENTGIS_API_KEY=mk_xxxxxxxxxxxxxxxxxx - 建议写入
~/.bashrc或~/.profile长期生效
第 22 页：执行套件
- 基本命令：
agc run /tmp/output --suite-id <suite-id> --input key=value - 执行流程：
- 从市场查询套件的脚本包地址（package_url）
- 从 Gitea Packages 下载脚本包
- 解压并读取 workflow.yaml
- 按 depends_on 拓扑顺序执行各步骤
- 每步在独立 Docker 容器中运行（docker run --rm gis-base）
- 结果写入本地工作目录的
_step_outputs/下 - 清理下载的脚本包
第 23 页：数据安全
- 数据永不离开本地
- 输入文件始终在用户自己的机器上
- 数据处理在本地 Docker 容器中完成
- 不上传到云端、不经过平台服务器
- 执行完成后脚本包自动清理
- 用户数据和结果文件始终保留在本地
第 24 页：错误处理
- 执行失败怎么办：
- 查看控制台错误信息
- 检查输入文件路径是否正确
- 确认 Docker 是否正常运行（
docker ps） - 确认 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 时自动下载
- 手动下载：
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 实际系统部署验证编写。