# TOOLS.md — 套件使用工具

## 市场前端

https://suites.mercator.cn

浏览套件、查看详情。

## CLI 安装

```bash
# 安装 agentgis-cli v0.2.0
pip install https://git.mercator.cn/api/packages/SuiteHub/generic/agentgis-cli/0.2.0/agentgis_cli-0.2.0.tar.gz

# 配置 API Key
agc config set api-key mk_xxxxxxxxx

# 查看套件列表
agc suites list
```

## 本地执行环境

所有套件在 **你自己的机器上** 通过 Docker 执行，数据不上云。

### 前提条件

- **Linux 系统**（Debian / Ubuntu）
- **Docker**（验证：`docker ps`）
  - `sudo apt install docker.io`
- 能访问 `registry.mercator.cn`（拉取 gis-base 镜像）

### 安装本地执行器

```bash
# 安装 gis-actions
curl -OJ https://git.mercator.cn/api/packages/SuiteHub/generic/gis-actions/2.0.8/gis-actions_2.0.8_all.deb
sudo dpkg -i gis-actions_2.0.8_all.deb

# 配置 Docker Registry 认证
echo "agw_readonly_2026" | docker login registry.mercator.cn -u agentgis-worker --password-stdin
```

### 执行套件

```bash
agc run <suite-id> --inputs '{"input_path": "/data/myfile.shp"}' --wait --poll 5
```

- `<suite-id>` 从 `agc suites list` 获取
- 输入文件路径用你的本地绝对路径
- `--wait` 等待执行完成，`--poll 5` 每 5 秒轮询结果

### 数据流向

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

## 系统服务管理

```bash
# 查看状态
sudo systemctl status gis-actions

# 查看日志
journalctl -u gis-actions -f

# 停止
sudo systemctl stop gis-actions

# 卸载
sudo dpkg --purge gis-actions
```

## 已知限制

| 问题 | 说明 |
|------|------|
| 输入文件 | shapefile 需传入目录路径而非单文件路径（因 .dbf/.shx 配套文件） |
| 模板文件 | 含 Excel 模板的套件需确保 templates/ 目录随脚本包一起发布 |

详见 https://git.mercator.cn/SuiteHub/agent-profiles/issues/6