diff --git a/suites-help/培训文档/培训文案.md b/suites-help/培训文档/培训文案.md index 307d5cb..17b0065 100644 --- a/suites-help/培训文档/培训文案.md +++ b/suites-help/培训文档/培训文案.md @@ -1,7 +1,7 @@ # Mercator 云平台 & AgentGIS 培训文案 > 基于 SuiteHub/agent-profiles 文档及 2026-07-16 实际系统验证。 -> 预计 30 页,每页标题 + 要点 = 一张 PPT。 +> 预计 32 页,每页标题 + 要点 = 一张 PPT。 --- @@ -206,6 +206,14 @@ - 本地执行器,安装在自己的 Linux 机器上 - 命令行工具:`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` — 自动升级 - 职责:从套件市场下载脚本包 → 在本地 Docker 中执行 → 返回结果 - 安装方式:一行命令 ```bash @@ -227,24 +235,37 @@ - 获取方式:登录 auth.mercator.cn → API Key 管理 → 创建 - 配置方式: ```bash - export AGENTGIS_API_KEY=mk_xxxxxxxxxxxxxxxxxx + agc config set api-key mk_xxxxxxxxxxxxxxxxxxxx ``` -- 建议写入 `~/.bashrc` 或 `~/.profile` 长期生效 +- 查看配置:`agc config list` +- 切换市场地址:`agc config set market-url ` +- 所有配置保存在 `~/.config/gis-actions/config.toml` ### 第 22 页:执行套件 - 基本命令: ```bash agc run /tmp/output --suite-id --input key=value + agc run /tmp/output --suite-id --input key=value --watch # 实时输出 + agc run /tmp/output --suite-id --input key=value --resume # 断点续跑 ``` +- 其他命令: + | 命令 | 用途 | + |------|------| + | `agc search ` | 搜索套件 | + | `agc info ` | 套件详情 | + | `agc logs` | 历史记录 | + | `agc cache list / clean` | 缓存管理 | + | `agc mcp` | AI Agent 集成(MCP 协议) | - 执行流程: 1. 从市场查询套件的脚本包地址(package_url) - 2. 从 Gitea Packages 下载脚本包 - 3. 解压并读取 workflow.yaml - 4. 按 depends_on 拓扑顺序执行各步骤 - 5. 每步在独立 Docker 容器中运行(docker run --rm gis-base) - 6. 结果写入本地工作目录的 `_step_outputs/` 下 - 7. 清理下载的脚本包 + 2. 检查本地缓存,命中则跳过下载 + 3. 从 Gitea Packages 下载脚本包(自动缓存) + 4. 解压并读取 workflow.yaml + 5. 按 depends_on 拓扑顺序执行各步骤 + 6. 每步在独立 Docker 容器中运行(docker run --rm gis-base) + 7. 结果写入本地工作目录的 `_step_outputs/` 下 + 8. 清理下载的脚本包 ### 第 23 页:数据安全 @@ -260,8 +281,14 @@ - 执行失败怎么办: 1. 查看控制台错误信息 2. 检查输入文件路径是否正确 - 3. 确认 Docker 是否正常运行(`docker ps`) - 4. 确认 gis-actions 版本(`dpkg -l gis-actions`) + 3. 运行 `agc doctor` 一键诊断环境: + - Docker 是否运行 + - gis-base 镜像是否存在 + - API Key 是否有效 + - 能否连通套件市场 + 4. 查看失败记录:`agc logs --status failed` + 5. 确认已升级到最新版:`agc self-update` +- 自动报告失败:已配置 API Key 的情况下,执行失败会自动发帖到 Discussions - 如果怀疑是套件本身的 Bug: - 配置 API Key 后,自动反馈到讨论区 - 或手动访问 discussions.mercator.cn 发帖 @@ -294,6 +321,37 @@ ### 第 27 页:获取方式 +- 安装 gis-actions 时自动下载 +- 也可手动拉取: + ```bash + docker pull registry.mercator.cn/library/gis-base:latest + ``` +- 离线环境:在可联网机器上导出镜像 + ```bash + docker save gis-base:latest | gzip > gis-base.tar.gz + ``` + 然后在目标机器 + ```bash + 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 工具 +- 启动方式: + ```bash + agc mcp # stdio 模式(默认) + agc mcp --transport sse --port 8080 # SSE 模式(HTTP) + ``` +- AI Agent 无需关心 Docker、镜像、套件包——只需调用工具名和参数 + +### 第 29 页:包签名与安全 + +- 套件包发布时使用 Ed25519 签名 +- 下载后自动验证签名,防止篡改 +- 手动验签:`python3 -m gis_actions.signing verify ` + - 安装 gis-actions 时自动下载 - 手动下载: ```bash @@ -305,9 +363,34 @@ --- -## 第七部分:各系统关系与生态(3 页) +## 第八部分:AI Agent 集成与安全(2 页) -### 第 28 页:端到端工作流程 +> 新增:MCP 协议适配 + 包签名验证 + +--- + +### 第 28 页:AI Agent 集成(MCP 协议) + +- GIS Actions v3.1 起支持 MCP(Model Context Protocol) +- AI Agent(Claude / DeepSeek / 本地 Agent)可自动发现和调用 GIS 工具 +- 启动方式: + ```bash + agc mcp # stdio 模式(默认) + agc mcp --transport sse --port 8080 # SSE 模式(HTTP) + ``` +- AI Agent 无需关心 Docker、镜像、套件包——只需调用工具名和参数 + +### 第 29 页:包签名与安全 + +- 套件包发布时使用 Ed25519 签名 +- 下载后自动验证签名,防止篡改 +- 手动验签:`python3 -m gis_actions.signing verify ` + +--- + +## 第九部分:各系统关系与生态(3 页) + +### 第 30 页:端到端工作流程 ``` 用户 → Auth Center 登录/获取 API Key @@ -317,7 +400,7 @@ → 出问题 → Discussions 反馈 → 开发者收到 → 修复 → 发布新版本 ``` -### 第 29 页:系统关系图 +### 第 31 页:系统关系图 ``` ┌─────────────────────────────────────────────────┐ @@ -341,7 +424,7 @@ └─────────────────────────────────────────────────┘ ``` -### 第 30 页:总结 +### 第 32 页:总结 - **Mercator 云平台**:认证 + 市场 + 讨论区,构成完整生态 - **AgentGIS**:将 GIS 能力扩展到本地,数据安全有保障 @@ -352,3 +435,4 @@ --- > 本文案基于 SuiteHub/agent-profiles 文档及 2026-07-16 实际系统部署验证编写。 +