# GIS Actions 本地部署指南

## 架构

GIS Actions 是**本地执行器**，从套件市场下载脚本包并在本地 Docker 中运行：

```
用户 / Agent 指定套件 ID
    → gis-actions（本地）
    → 从 Suite Market 下载脚本包
    → 解析 workflow.yaml
    → docker run gis-base + 脚本
    → 结果写入本地 /tmp/output/
```

## 环境要求

- Python 3.10+
- Docker（用于容器化执行）

## 获取代码

```bash
curl -L -o gis-actions.tar.gz "https://git.mercator.cn/api/packages/AgentGIS/generic/gis-actions/v2.4.0/gis-actions.tar.gz"
tar xzf gis-actions.tar.gz
cd gis-actions
```

## 配置

```bash
# 设置 API Key（从 https://auth.mercator.cn 获取）
export AGENTGIS_API_KEY=mk_xxxxxxxxxxxxx
```

或创建 `worker.json`：

```json
{
  "worker": { "id": "my-machine-001" },
  "scheduler": { "url": "https://suites.mercator.cn" },
  "auth": { "api_key": "***" }
}
```

## 运行套件

```bash
# 通过套件 ID 执行（推荐）
python cli.py run /tmp/workdir --suite-id parcel-analysis --input buffer_distance=0.5

# 或直接指定脚本包地址
python cli.py run /tmp/workdir --package-url https://git.mercator.cn/.../scripts.tar.gz
```

## 目录结构

```
gis-actions/
├── cli.py                  # 命令行入口（支持 --suite-id / --package-url）
├── download_and_run.py     # 下载 + 执行核心逻辑
├── steps_executor.py       # workflow.yaml 步骤执行器
├── workdir/                # 默认工作目录
└── packaging/deb/          # DEB 打包结构（待完善）
```

## 执行流程

1. `cli.py run` 启动
2. 解析套件 ID（调用 Suite Market API 获取 package_url）
3. 下载 scripts.tar.gz → 解压到工作目录
4. 读取 workflow.yaml，按 steps 顺序执行
5. 每个步骤在 Docker 容器中运行（gis-base 镜像）
6. 清理脚本目录（知识产权保护）
7. 结果写入本地输出目录