# TOOLS.md — 套件开发工具与资源

## 安装

### gis-actions v3.0.2（CLI + 执行引擎，一个 deb 全包）

```bash
curl -sLO https://git.mercator.cn/api/packages/SuiteHub/generic/gis-actions/3.0.2/gis-actions_3.0.2_all.deb
sudo dpkg -i gis-actions_3.0.2_all.deb
```

安装后直接使用 `agc` 命令。首次安装时 postinst 会自动下载 gis-base 镜像。

### 前提条件

- **Linux 系统**（Debian / Ubuntu）
- **Docker**（`sudo apt-get install -y docker.io`）

### gis-base 基础镜像

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

镜像从 Gitea Packages 加载（无需 registry 账号）：

```bash
curl -sLO https://git.mercator.cn/api/packages/SuiteHub/generic/gis-base/1.0.0/gis-base.tar.gz
docker load -i gis-base.tar.gz
```

> 安装 gis-actions deb 时已自动执行上述步骤，通常无需手动操作。

---

## CLI 用法

`agc` 目前只有一个命令：`run`。

```bash
# 执行套件（唯一命令）
agc run /tmp/output --suite-id <suite-id> --input key=value

# 示例
agc run /tmp/output --suite-id 2c99a1cb-84a5-42dd-9147-1c8e8f7f2941 --input buffer_distance=0.5
```

### 查询市场（通过 curl，agc 暂未内置）

```bash
# 列出所有套件
curl -s https://suites.mercator.cn/api/v1/suites | python3 -m json.tool

# 搜索套件
curl -s "https://suites.mercator.cn/api/v1/suites/search?q=缓冲区"

# 查看套件详情
curl -s https://suites.mercator.cn/api/v1/suites/<suite-id>
```

### 发布套件（通过 API）

```bash
# 打包
tar czf suite.tgz --exclude='.git' --exclude='__pycache__' my-suite/

# 上传发布
curl -X POST https://suites.mercator.cn/api/v1/publish/upload \
  -H "Authorization: Bearer $KEY" \
  -F "file=@suite.tgz"
```

## API 端点

| 用途 | 端点 |
|------|------|
| 发布 Suite（上传） | `POST https://suites.mercator.cn/api/v1/publish/upload` |
| 发布 Suite（Git） | `POST https://suites.mercator.cn/api/v1/publish` |
| 列出套件 | `GET https://suites.mercator.cn/api/v1/suites` |
| 套件详情 | `GET https://suites.mercator.cn/api/v1/suites/{suite_id}` |
| API 文档 | `https://suites.mercator.cn/docs` |

## 套件结构

```
my-suite/
├── workflow.yaml      # 步骤定义（必填）
└── scripts/
    └── run.py         # 执行入口脚本
```

### workflow.yaml 格式规范

使用 `steps` + `$params.xxx` 格式：

```yaml
name: 我的套件
description: 套件描述
version: 1.0.0
author: 作者
tags: [标签1, 标签2]

params:
  input_path:
    type: string
    required: true
    desc: 输入文件路径

nodes:
  - id: start
    type: start

  - id: step1
    name: 步骤名称
    type: python
    script_id: run
    depends_on:
      - start
    params:
      input: "${{inputs.input_path}}"

  - id: end
    type: end
    depends_on:
      - step1
```

> **工作流格式**：使用 `nodes` 定义 DAG，每个节点通过 `depends_on` 指定前驱节点。必须有 `start` 和 `end` 类型节点作为起止。参数用 `${{inputs.xxx}}` 语法引用。

## 基础镜像

所有套件在 gis-base 镜像中执行，包含：Python 3, GDAL, Shapely, GeoPandas, numpy, openpyxl, xlrd

镜像名称：`gis-base:latest`（本地加载，无需 registry）

## 知识库

| 文件 | 内容 |
|------|------|
| `knowledge/script-data-types.md` | 脚本数据类型分类规范 |
| `knowledge/script-dependencies.md` | 脚本依赖管理规范 |
| `knowledge/data-execution-model.md` | 数据执行模型（本地执行设计） |

## 文档

公开文档在 `SuiteHub/agent-profiles` 仓库中。