Ubuntu
145 lines
3.5 KiB
Markdown
145 lines
3.5 KiB
Markdown
# 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` 仓库中。
|