From e601a50e95325b5cfa8ab088f23035f910ab2409 Mon Sep 17 00:00:00 2001 From: Huawei Date: Tue, 14 Jul 2026 12:34:17 +0000 Subject: [PATCH] =?UTF-8?q?add:=20Mercator=20&=20AgentGIS=20=E5=9F=B9?= =?UTF-8?q?=E8=AE=AD=E5=85=A5=E9=97=A8=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- suites-help/培训文档/入门指南.md | 203 +++++++++++++++++++++++++++++++ 1 file changed, 203 insertions(+) create mode 100644 suites-help/培训文档/入门指南.md diff --git a/suites-help/培训文档/入门指南.md b/suites-help/培训文档/入门指南.md new file mode 100644 index 0000000..b2e5b89 --- /dev/null +++ b/suites-help/培训文档/入门指南.md @@ -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 --input key=val` | 运行套件 | +| `agc status` | 查看运行状态 | +| `agc list` | 列出可用的套件 | +| `agc config set api_key <你的API Key>` | 配置认证 | + +### 推荐工作流 + +``` +登录云平台 → 查找套件 → 本地运行 → 获取结果 → 有疑问去 Discussions +```