SuiteHub/agent-profiles

Fork 0

Files

T

Huawei 522a040128 docs: add dual-platform throughout training doc

2026-07-20 09:15:05 +00:00

16 KiB

Raw Blame History

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：
```
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 管理 → 创建

配置方式：

agc config set api-key mk_xxxxxxxxxxxxxxxxxxxx

查看配置：agc config list
切换市场地址：agc config set market-url <url>
所有配置保存在 ~/.config/gis-actions/config.toml

第 22 页：执行套件

基本命令：

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. 清理下载的脚本包和临时文件

命令	用途
`agc search <query>`	搜索套件
`agc info <suite-id>`	套件详情
`agc logs`	历史记录
`agc cache list / clean`	缓存管理
`agc mcp`	AI Agent 集成（MCP 协议）

第 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 时自动下载

也可手动拉取：

docker pull registry.mercator.cn/library/gis-base:latest

离线环境：在可联网机器上导出镜像

docker save gis-base:latest | gzip > gis-base.tar.gz

然后在目标机器

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 工具

启动方式：

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 时自动下载

手动下载：

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 工具

启动方式：

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 实际系统部署验证编写。

16 KiB Raw Blame History Unescape Escape

Mercator 云平台 & AgentGIS 培训文案

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

第 1 页：Mercator 云平台是什么

第 2 页：平台总体架构

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

第 3 页：Auth Center 是什么

第 4 页：登录与注册

第 5 页：API Key 管理

第 6 页：OAuth2 / OIDC 服务端

第 7 页：个人信息管理

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

第 8 页：Suite Market 是什么

第 9 页：浏览与搜索套件

第 10 页：套件详情

第 11 页：选择套件的方法

第 12 页：套件的结构

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

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

第 15 页：版本管理

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

第 16 页：Discussions 是什么

第 17 页：话题与标签

第 18 页：错误反馈机制

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

第 19 页：GIS Actions 是什么

第 20 页：环境要求

第 21 页：配置 API Key

第 22 页：执行套件

第 23 页：数据安全

第 24 页：错误处理

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

第 25 页：GIS Base 是什么

第 26 页：预装环境

第 27 页：获取方式

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

第 29 页：包签名与安全

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

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

第 29 页：包签名与安全

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

第 30 页：端到端工作流程

第 31 页：系统关系图

第 32 页：总结

16 KiB

Raw Blame History