From 522a040128bf0265185aa47bc4fa79347cf05514 Mon Sep 17 00:00:00 2001 From: Huawei Date: Mon, 20 Jul 2026 09:15:05 +0000 Subject: [PATCH] docs: add dual-platform throughout training doc --- suites-help/培训文档/培训文案.md | 73 ++++++++++++++++++++------------ 1 file changed, 46 insertions(+), 27 deletions(-) diff --git a/suites-help/培训文档/培训文案.md b/suites-help/培训文档/培训文案.md index b0cd96c..ef33b4f 100644 --- a/suites-help/培训文档/培训文案.md +++ b/suites-help/培训文档/培训文案.md @@ -211,7 +211,9 @@ ### 第 19 页：GIS Actions 是什么 -- 本地执行器，安装在自己的 Linux 机器上 +- 本地执行器 + - **Linux**：安装在自己的机器上（deb 包） + - **Windows**：安装 agc.exe（zip 包） - 命令行工具：`agc` - 完整命令集： - `agc config` — 配置 API Key 和市场地址 @@ -221,21 +223,35 @@ - `agc logs / cache` — 运行历史和缓存管理 - `agc mcp` — AI Agent 集成入口（MCP 协议） - `agc self-update` — 自动升级 -- 职责：从套件市场下载脚本包 → 在本地 Docker 中执行 → 返回结果 -- 安装方式：一行命令 +- 职责：从套件市场下载脚本包 → 在本地执行（Linux Docker / Windows 本机）→ 返回结果 +- 安装方式： + **Linux：** ```bash 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：需要安装 Docker Engine -- Python 3.10+（已随 deb 包安装） -- 网络：需要能访问 suites.mercator.cn（查询套件）和 git.mercator.cn（下载脚本包） +**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：用于认证身份、调取套件信息和下载脚本包 @@ -270,15 +286,18 @@ 3. 从 Gitea Packages 下载脚本包（自动缓存） 4. 解压并读取 workflow.yaml 5. 按 depends_on 拓扑顺序执行各步骤 - 6. 每步在独立 Docker 容器中运行（docker run --rm gis-base） + 6. 每步按 runtime 执行： + - runtime: docker → Docker 容器（gis-base 镜像） + - runtime: python3 → 本地 subprocess + - runtime: arcpy → 系统 arcpy（Windows only） 7. 结果写入本地工作目录的 `_step_outputs/` 下 - 8. 清理下载的脚本包 + 8. 清理下载的脚本包和临时文件 ### 第 23 页：数据安全 - **数据永不离开本地** - 输入文件始终在用户自己的机器上 -- 数据处理在本地 Docker 容器中完成 +- 数据处理在本地完成（Linux Docker 容器 / Windows 本机进程） - 不上传到云端、不经过平台服务器 - 执行完成后脚本包自动清理 - 用户数据和结果文件始终保留在本地 @@ -289,12 +308,12 @@ 1. 查看控制台错误信息 2. 检查输入文件路径是否正确 3. 运行 `agc doctor` 一键诊断环境： - - Docker 是否运行 - - gis-base 镜像是否存在 + - Linux: Docker 是否运行 / Windows: agc.exe 是否在 PATH + - 镜像是否存在（Linux） - API Key 是否有效 - 能否连通套件市场 4. 查看失败记录：`agc logs --status failed` - 5. 确认已升级到最新版：`agc self-update` + 5. 确认已升级到最新版：`agc self-update`（Linux: deb / Windows: zip 自动解压） - 自动报告失败：已配置 API Key 的情况下，执行失败会自动发帖到 Discussions - 如果怀疑是套件本身的 Bug： - 配置 API Key 后，自动反馈到讨论区 @@ -306,12 +325,13 @@ ### 第 25 页：GIS Base 是什么 -- 所有套件运行的基石 -- 预装完整 GIS 工具链的 Linux Docker 镜像 -- 永久存储在用户本地，所有套件共享 -- 镜像名：`gis-base:latest` -- 大小：约 465MB -- 基底：Debian slim（bookworm） +- **Linux 模式**：所有 Docker 套件的运行基石 + - 预装完整 GIS 工具链的 Linux Docker 镜像 + - 永久存储在用户本地，所有套件共享 + - 镜像名：`gis-base:latest`，约 465MB +- **Windows 模式**：不需要 gis-base 镜像 + - 使用本地 arcpy / Python 环境 + - 依赖 ArcMap 10.8 的 arcpy 环境 ### 第 26 页：预装环境 @@ -401,9 +421,9 @@ ``` 用户 → Auth Center 登录/获取 API Key - → 浏览 Suite Market → 选择合适的套件 + → 浏览 Suite Market → 选择合适的套件（关注平台标签） → 复制 agc run 命令 → 在本地终端执行 - → GIS Actions 下载脚本包 → Docker 运行 → 得到结果 + → GIS Actions 下载脚本包 → 执行（Linux Docker / Windows 本机）→ 得到结果 → 出问题 → Discussions 反馈 → 开发者收到 → 修复 → 发布新版本 ``` @@ -424,10 +444,9 @@ ┌─────────────────────────────────────────────────┐ │ 本地用户 │ │ │ -│ gis-actions (agc) ── docker run ── 脚本执行 │ -│ │ │ -│ gis-base 镜像 │ -│ （本地 + 只读） │ +│ gis-actions (agc) │ +│ ├─ Linux: docker run gis-base → 脚本执行 │ +│ └─ Windows: subprocess(arcpy/python3) → 执行 │ └─────────────────────────────────────────────────┘ ``` @@ -435,8 +454,8 @@ - **Mercator 云平台**：认证 + 市场 + 讨论区，构成完整生态 - **AgentGIS**：将 GIS 能力扩展到本地，数据安全有保障 -- **GIS Actions**：一键安装，即装即用 -- **GIS Base**：开箱即用的 GIS 工具箱 +- **GIS Actions**：一键安装（Linux deb / Windows zip），即装即用 +- **GIS Base**：Linux Docker 模式的 GIS 工具箱 / Windows 使用本地 arcpy - **核心价值**：数据不离开本地，算法安全交付，身份贯穿全域 ---