# TOOLS.md — 套件使用工具

## 市场前端

https://suites.mercator.cn

浏览套件、查看详情。

## 安装

安装 `gis-actions` 包即可获得全部功能（CLI + 执行引擎），一次安装：

```bash
# 下载
curl -sLO https://git.mercator.cn/api/packages/AgentGIS/generic/gis-actions/3.0.5/gis-actions_3.0.5_all.deb

# 安装
sudo dpkg -i gis-actions_3.0.5_all.deb
```

安装后可用 `agc` 命令（已内置在包中）。

## 交流反馈

遇到任何问题或需要帮助，前往 https://discussions.mercator.cn/ 发话题。平台管理员和其他用户会在那里解答。

- **提问** — 使用 `question` 标签
- **报 Bug** — 使用 `bug` 标签
- **提建议** — 使用 `feature` 或 `suggestion` 标签

## 前提条件

- **Linux 系统**（Debian / Ubuntu）
- **Docker**（验证：`docker ps`）
- **API Key** — 登录 https://auth.mercator.cn 获取，后续 `agc config set api_key <你的API Key>` 使用

### gis-base 基础镜像

所有套件运行在 `gis-base` 镜像中（含 Python 3, GDAL, Shapely, GeoPandas, numpy, openpyxl, xlrd）。

首次安装 gis-actions 时会自动下载镜像。也可提前手动准备：

```bash
# 从 Gitea 直接下载镜像包（无需 registry 账号）
curl -sLO https://git.mercator.cn/api/packages/AgentGIS/generic/gis-base/1.0.0/gis-base.tar.gz
docker load -i gis-base.tar.gz
```

## 执行套件

```bash
# 查询市场套件（通过 curl）
curl -s https://suites.mercator.cn/api/v1/suites | python3 -m json.tool

# 执行套件，输入参数用 key=value 格式
agc run /tmp/output --suite-id <suite-id> --input key=value
```

`<suite-id>` 从市场 API 或前端页面获取。

## 数据流向

```
你本地的 SHP/GeoJSON/TIFF/XLS 文件
    │
    ▼
gis-actions（你的机器）
    │  ← 从市场下载套件脚本包
    │  ← docker run gis-base + 套件脚本
    │  → 结果写入 /tmp/output/
    ▼
结果文件（你的机器）
```

## 注意事项

- 输入文件路径使用你的本地绝对路径
- shapefile 需要传入目录路径而非单文件路径（因 .dbf/.shx 配套文件）
- 套件数据不上传云端，全部在你的机器上处理