diff --git a/suites-help/培训文档/培训文案.md b/suites-help/培训文档/培训文案.md new file mode 100644 index 0000000..307d5cb --- /dev/null +++ b/suites-help/培训文档/培训文案.md @@ -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 --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 实际系统部署验证编写。