docs: 更新培训文案至 v3.1.2 — 新增命令参考、MCP 集成、包签名

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 <url>`
+- 所有配置保存在 `~/.config/gis-actions/config.toml`
 
 ### 第 22 页：执行套件
 
 - 基本命令：
   ```bash
   agc run /tmp/output --suite-id <suite-id> --input key=value
+  agc run /tmp/output --suite-id <suite-id> --input key=value --watch   # 实时输出
+  agc run /tmp/output --suite-id <suite-id> --input key=value --resume  # 断点续跑
   ```
+- 其他命令：
+  | 命令 | 用途 |
+  |------|------|
+  | `agc search <query>` | 搜索套件 |
+  | `agc info <suite-id>` | 套件详情 |
+  | `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 <file> <sig>`
+
 - 安装 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 <file> <sig>`
+
+---
+
+## 第九部分：各系统关系与生态（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 实际系统部署验证编写。
+