docs: 更新培训文案至 v3.1.2 — 新增命令参考、MCP 集成、包签名
This commit is contained in:
+99
-15
@@ -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 实际系统部署验证编写。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user