add: Mercator & AgentGIS 培训入门文档
This commit is contained in:
@@ -0,0 +1,203 @@
|
||||
# Mercator 云平台 & AgentGIS 平台 使用入门
|
||||
|
||||
> 📝 本文档面向 **套件使用者**（非技术人员），帮助您快速了解平台全貌和日常使用方式。
|
||||
|
||||
---
|
||||
|
||||
## 一、两个平台的关系
|
||||
|
||||
用一个比喻来理解：
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────────┐
|
||||
│ Mercator 云平台（线上服务） │
|
||||
│ │
|
||||
│ 你在这里： │
|
||||
│ · 登录账号（auth.mercator.cn） │
|
||||
│ · 浏览套件（suites.mercator.cn） │
|
||||
│ · 交流反馈（discussions.mercator.cn） │
|
||||
│ │
|
||||
│ │ │
|
||||
│ ▼ 查询套件、下发任务 │
|
||||
│ │
|
||||
│ ┌──────────────────────────────────────────────────┐ │
|
||||
│ │ AgentGIS 平台（本地工具） │ │
|
||||
│ │ │ │
|
||||
│ │ 在你的电脑上运行： │ │
|
||||
│ │ · GIS Actions（执行引擎） │ │
|
||||
│ │ · GIS Base（地理信息工具箱） │ │
|
||||
│ │ │ │
|
||||
│ │ 📍 数据始终留在你的电脑，不上传云端 │ │
|
||||
│ └──────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
└──────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**一句话：** Mercator 云平台是"超市"，AgentGIS 是"厨房"。你在超市选好菜（套件），在自家厨房（本地电脑）做菜。食材（你的数据）从不出厨房。
|
||||
|
||||
---
|
||||
|
||||
## 二、Mercator 云平台 — 你每天在网页上用的服务
|
||||
|
||||
### 2.1 统一认证中心（auth.mercator.cn）
|
||||
|
||||
**用来做什么：** 登录所有 Mercator 服务的统一入口。
|
||||
|
||||
**你的用法：**
|
||||
1. 打开 https://auth.mercator.cn/login
|
||||
2. 用企业微信扫码，或用账号密码登录
|
||||
3. 登录后自动跳转到对应的服务（套件市场、讨论板等）
|
||||
|
||||
**特别说明：**
|
||||
- 一套账号通吃所有服务
|
||||
- 管理员可以在后台为你创建 API Key（类似"程序密码"），供自动化脚本使用
|
||||
|
||||
### 2.2 专家套件市场（suites.mercator.cn）
|
||||
|
||||
**用来做什么：** 浏览、查找、使用各类 GIS 套件的在线商店。
|
||||
|
||||
**你的用法：**
|
||||
1. 进入首页 → 浏览套件列表
|
||||
2. 按分类筛选（自然资源、土地利用、测绘等）
|
||||
3. 点击套件 → 查看详情、参数说明、版本历史
|
||||
4. 找到需要的套件后，记下套件 ID 或名称
|
||||
5. 在本地通过 `agc` 命令运行它
|
||||
|
||||
**界面预览：**
|
||||
|
||||
| 区域 | 内容 |
|
||||
|------|------|
|
||||
| 顶部导航 | 浏览套件、帮助文档 |
|
||||
| 左侧分类 | 按业务分类筛选 |
|
||||
| 中间列表 | 套件卡片（名称、作者、版本、简介） |
|
||||
| 详情页 | 参数说明、版本日志 |
|
||||
|
||||
### 2.3 Discussions 用户交流平台（discussions.mercator.cn）
|
||||
|
||||
**用来做什么：** 用户之间交流问题、提建议、讨论用法的社区。
|
||||
|
||||
**你的用法：**
|
||||
1. 浏览已有话题 → 看看别人遇到什么问题
|
||||
2. 搜索关键词 → 查找已有的解答
|
||||
3. 创建新话题 → 提问、建议、报 Bug
|
||||
4. 回复参与 → 帮助其他用户
|
||||
|
||||
**话题类型：**
|
||||
|
||||
| 标签 | 说明 |
|
||||
|------|------|
|
||||
| 🐛 bug | 报告平台或套件的问题 |
|
||||
| ✨ feature | 提功能建议 |
|
||||
| ❓ question | 提问求助 |
|
||||
| 💬 discussion | 一般讨论 |
|
||||
| 📢 announcement | 管理员发布的通知 |
|
||||
|
||||
---
|
||||
|
||||
## 三、AgentGIS 平台 — 你电脑上运行的工具
|
||||
|
||||
### 3.1 GIS Actions（本地执行器）
|
||||
|
||||
**是什么：** 一个安装在你电脑上的命令行工具（`agc`），负责执行套件。
|
||||
|
||||
**它做什么：**
|
||||
- 从 Mercator 云平台查询套件信息
|
||||
- 在本地用 Docker 创建一个临时环境
|
||||
- 在该环境中执行套件规定的步骤
|
||||
- 执行完成后自动清理临时文件
|
||||
|
||||
**你的用法：**
|
||||
```bash
|
||||
# 1. 运行一个套件
|
||||
agc run /路径/到/输出目录 --suite-id <套件ID> --input 参数名=值
|
||||
|
||||
# 2. 查看运行状态
|
||||
agc status
|
||||
|
||||
# 3. 列出已安装的套件
|
||||
agc list
|
||||
```
|
||||
|
||||
**数据安全：**
|
||||
- ✅ **你的数据永远留在本地**，不上传云端
|
||||
- ✅ 套件脚本在隔离的 Docker 容器中运行
|
||||
- ✅ 执行完毕后临时文件自动清理
|
||||
- ✅ 只有最终成果文件保留在输出目录
|
||||
|
||||
### 3.2 GIS Base（基础环境）
|
||||
|
||||
**是什么：** 预装了 GIS 工具（GDAL、Python、Shapely、GeoPandas 等）的 Docker 镜像。
|
||||
|
||||
**你不需要直接操作它。** 当你运行 `agc run` 时，GIS Actions 会自动下载或使用本地缓存的基础镜像来执行套件。
|
||||
|
||||
---
|
||||
|
||||
## 四、从零开始：一个任务的全流程
|
||||
|
||||
假设你是一名土地规划人员，需要做"土地整治竣工结算"：
|
||||
|
||||
```
|
||||
第 1 步：打开 auth.mercator.cn → 登录
|
||||
↓
|
||||
第 2 步：打开 suites.mercator.cn → 搜索"土地整治竣工结算"
|
||||
↓
|
||||
第 3 步：查看套件详情 → 了解需要哪些输入参数
|
||||
↓
|
||||
第 4 步：打开终端，运行命令：
|
||||
agc run ./output --suite-id xxxx-xxxx --input range_path=./范围.shp
|
||||
↓
|
||||
第 5 步：GIS Actions 自动执行：
|
||||
├── 下载套件脚本包
|
||||
├── 启动 Docker 容器（含 GIS 工具）
|
||||
├── 运行脚本，处理你的数据
|
||||
└── 生成成果文件到 ./output/ 目录
|
||||
↓
|
||||
第 6 步：在 ./output/ 中拿到结果文件
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 五、常见问题
|
||||
|
||||
### Q: 我需要安装什么软件？
|
||||
**A:** 只需要两样：Docker 和 `agc` 命令行工具。安装步骤见帮助文档。
|
||||
|
||||
### Q: 我的数据安全吗？
|
||||
**A:** 绝对安全。你的数据全程在本地处理，不上传任何文件到云端。只有套件的运行日志回传到服务器（不含原始数据）。
|
||||
|
||||
### Q: 套件不会用怎么办？
|
||||
**A:**
|
||||
- 在套件市场查看套件详情中的参数说明
|
||||
- 在 Discussions 搜索或提问
|
||||
- 在 Discussions 提交功能建议或 Bug 报告
|
||||
|
||||
### Q: 我可以自己发布套件吗？
|
||||
**A:** 可以。需要申请开发者角色，在 Auth Center 后台创建 API Key，然后通过 API 发布。具体步骤见开发指南。
|
||||
|
||||
---
|
||||
|
||||
## 六、快速参考
|
||||
|
||||
### 网址
|
||||
|
||||
| 服务 | 网址 |
|
||||
|------|------|
|
||||
| 登录入口 | https://auth.mercator.cn |
|
||||
| 套件市场 | https://suites.mercator.cn |
|
||||
| 用户交流 | https://www.mercator.cn/discussions/ |
|
||||
| 首页 | https://www.mercator.cn |
|
||||
|
||||
### agc 常用命令
|
||||
|
||||
| 命令 | 说明 |
|
||||
|------|------|
|
||||
| `agc run <输出目录> --suite-id <ID> --input key=val` | 运行套件 |
|
||||
| `agc status` | 查看运行状态 |
|
||||
| `agc list` | 列出可用的套件 |
|
||||
| `agc config set api_key <你的API Key>` | 配置认证 |
|
||||
|
||||
### 推荐工作流
|
||||
|
||||
```
|
||||
登录云平台 → 查找套件 → 本地运行 → 获取结果 → 有疑问去 Discussions
|
||||
```
|
||||
Reference in New Issue
Block a user