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

## 安装

### gis-actions（Linux CLI）

```bash
curl -sLO https://packages.mercator.cn/public/gis-actions/latest.deb
sudo dpkg -i latest.deb
```

### gis-actions（Windows CLI）

下载 [latest-windows.zip](https://packages.mercator.cn/public/gis-actions/latest-windows.zip)，解压到 `%LOCALAPPDATA%\\AgentGIS\\gis-actions\\`，加入 `PATH`。

---

## CLI 用法

```bash
# 执行套件（最新版）
agc run <work_dir> --suite-id <suite-id> --input key=value

# 执行指定版本
agc run <work_dir> --suite-id <suite-id> --version 1.0.0 --input key=value

# 直接指定包地址
agc run <work_dir> --package-url <url> --input key=value
```

## API 端点

| 用途 | 端点 |
|------|------|
| 浏览套件 | `GET https://suites.mercator.cn/api/v1/suites` |
| 套件详情 | `GET https://suites.mercator.cn/api/v1/suites/{id}` |
| 指定版本详情 | `GET https://suites.mercator.cn/api/v1/suites/{id}?version=1.0.0` |
| 版本历史 | `GET https://suites.mercator.cn/api/v1/suites/{id}/versions` |
| 发布套件（文件上传） | `POST https://suites.mercator.cn/publish/upload`（需 Gitea Token） |
| 发布套件（Git 仓库） | `POST https://suites.mercator.cn/publish`（需 Gitea Token） |
| API 文档 | `https://suites.mercator.cn/docs` |

## 套件结构

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

### workflow.yaml 格式

```yaml
name: 我的套件
description: 套件描述
version: 1.0.0
author: 作者
platform: all                    # 运行平台: linux / windows / all
slug: my-suite-english-name      # 可选，英文包名。不传则自动转拼音
tags: [标签1, 标签2]
category: 业务分类

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

base_image: gis-base:latest      # 仅 Docker 模式需要

steps:
  - id: step1
    name: 步骤名称
    runtime: python3              # 执行环境: docker / python3 / arcpy
    script_id: run
    params:
      input: $params.input_path
```

### runtime 字段说明

| runtime | 执行方式 | 适用平台 |
|---------|----------|----------|
| docker  | Docker 容器（steps_executor） | Linux |
| python3 | agc 内置 Python（subprocess） | Linux + Windows |
| arcpy   | 系统 arcpy（Python 2.7）    | Windows only |

- 所有步骤 runtime 相同 -> 全部用对应执行器
- 混用 docker 和其他 -> 分步骤各自执行
- 一个套件可以同时包含 docker 和 python3 步骤

## 包命名规则

套件发布到 Gitea Packages 时，包名由套件名称自动生成 slug：

```
例："土地整治竣工结算"  →  land-remediation-settlement
    "Hello World"       →  hello-world
    "Buffer Analysis"   →  buffer-analysis
```

slug 规则：转小写 → 非字母数字替换为连字符 → 合并连续连字符 → 去掉首尾连字符。

## 基础镜像

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

- 镜像名：`gis-base:latest`
- 来源：安装 gis-actions 时自动从 MinIO 下载（`docker load`）

## 知识库

| 文件 | 内容 |
|------|------|
| `knowledge/data-execution-model.md` | 数据执行模型（本地执行设计） |

## 文档

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


## 套件加密发布（v3.2.0+）

套件脚本发布前需进行 AES-256 加密：

```bash
# 设置加密密钥（与 gis-base 镜像版本匹配）
export SUITE_ENCRYPTION_KEY=<hex_key>

# 加密 scripts/ 目录下的所有 .py 文件
python3 -m gis_actions.encrypt encrypt scripts/run.py
# 输出: scripts/run.py.enc（原 file.py 可删除）
```

加密后的套件包结构：
```
suite-package.tgz
├── workflow.yaml
├── scripts/
│   └── run.py.enc           ← AES-256 加密，非明文
├── demo-data/（可选）
└── templates/（可选）
```

解密由 gis-base 镜像内的 decrypt_runner.py 自动完成，套件发布者无需关心容器内解密细节。