147 lines
4.0 KiB
Markdown
147 lines
4.0 KiB
Markdown
# 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 自动完成，套件发布者无需关心容器内解密细节。
|