docs: rewrite TOOLS.md to match v3.0.2 implementation (#8)
This commit is contained in:
+59
-53
@@ -2,63 +2,70 @@
|
||||
|
||||
## 安装
|
||||
|
||||
### gis-actions（CLI + 执行引擎）
|
||||
### 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 --version
|
||||
|
||||
# 配置 API Key
|
||||
agc config set api-key mk_xxxxxxxxxxx
|
||||
```
|
||||
|
||||
安装后直接使用 `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
|
||||
pip install https://git.mercator.cn/api/packages/SuiteHub/generic/agentgis-sdk/0.1.0/agentgis_sdk-0.1.0-py3-none-any.whl
|
||||
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（本地执行器，`agc run` 必需）
|
||||
|
||||
`agc run` 需要 gis-actions 在本地运行：
|
||||
|
||||
```bash
|
||||
# 安装依赖（Docker）
|
||||
sudo apt-get install -y docker.io
|
||||
sudo usermod -aG docker $USER
|
||||
newgrp docker
|
||||
|
||||
# 安装 gis-actions
|
||||
curl -OJ 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
|
||||
|
||||
```
|
||||
> 安装 gis-actions deb 时已自动执行上述步骤，通常无需手动操作。
|
||||
|
||||
---
|
||||
|
||||
## CLI 用法
|
||||
|
||||
`agc` 目前只有一个命令：`run`。
|
||||
|
||||
```bash
|
||||
# 🔍 查市场（写代码前先做这个）
|
||||
agc suites list # 列出所有套件
|
||||
agc suites list | grep <关键词> # 搜索已有套件
|
||||
# 执行套件（唯一命令）
|
||||
agc run /tmp/output --suite-id <suite-id> --input key=value
|
||||
|
||||
# 初始化新套件（脚手架）
|
||||
agc init ./my-analysis
|
||||
# 示例
|
||||
agc run /tmp/output --suite-id 2c99a1cb-84a5-42dd-9147-1c8e8f7f2941 --input buffer_distance=0.5
|
||||
```
|
||||
|
||||
# 测试执行（需先安装 gis-actions）
|
||||
agc run /tmp/output --suite-id <suite-id> --input key=val
|
||||
### 查询市场（通过 curl，agc 暂未内置）
|
||||
|
||||
# 发布到市场
|
||||
# 方式一：打包后上传
|
||||
tar czf suite.tgz --exclude='.git' --exclude='__pycache__' --exclude='tests' my-suite/
|
||||
agc publish upload suite.tgz
|
||||
```bash
|
||||
# 列出所有套件
|
||||
curl -s https://suites.mercator.cn/api/v1/suites | python3 -m json.tool
|
||||
|
||||
# 方式二：通过 Git 发布（需 repo_url）
|
||||
curl -X POST https://suites.mercator.cn/api/v1/publish \
|
||||
# 搜索套件
|
||||
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" \
|
||||
-d '{"repo_url": "https://git.mercator.cn/org/my-suite.git"}'
|
||||
-F "file=@suite.tgz"
|
||||
```
|
||||
|
||||
## API 端点
|
||||
@@ -67,25 +74,22 @@ curl -X POST https://suites.mercator.cn/api/v1/publish \
|
||||
|------|------|
|
||||
| 发布 Suite（上传） | `POST https://suites.mercator.cn/api/v1/publish/upload` |
|
||||
| 发布 Suite（Git） | `POST https://suites.mercator.cn/api/v1/publish` |
|
||||
| 注册脚本 | `POST https://suites.mercator.cn/api/v1/scripts` |
|
||||
| 更新套件版本 | `POST https://suites.mercator.cn/api/v1/suites/{id}/versions` |
|
||||
| 合规检测 | `POST https://suites.mercator.cn/api/v1/compliance/check` |
|
||||
| 数据类型列表 | `GET https://suites.mercator.cn/api/v1/data-types` |
|
||||
| 业务类型列表 | `GET https://suites.mercator.cn/api/v1/business-types` |
|
||||
| 列出套件 | `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 # 步骤定义（必填，使用旧版格式）
|
||||
├── workflow.yaml # 步骤定义（必填）
|
||||
└── scripts/
|
||||
└── run.py # 执行入口脚本
|
||||
```
|
||||
|
||||
### workflow.yaml 格式规范
|
||||
|
||||
使用旧版 `steps/script/$params` 格式，**不要**使用 `nodes/script_id/${{inputs}}` 格式：
|
||||
使用 `steps` + `$params.xxx` 格式：
|
||||
|
||||
```yaml
|
||||
name: 我的套件
|
||||
@@ -95,27 +99,29 @@ author: 作者
|
||||
tags: [标签1, 标签2]
|
||||
|
||||
params:
|
||||
input_path:
|
||||
type: string
|
||||
required: true
|
||||
desc: 输入文件路径
|
||||
type: object
|
||||
required:
|
||||
- input_path
|
||||
properties:
|
||||
input_path:
|
||||
type: string
|
||||
description: 输入文件路径
|
||||
|
||||
steps:
|
||||
- id: step1
|
||||
name: 步骤名称
|
||||
type: script
|
||||
script_id: run
|
||||
script: run
|
||||
params:
|
||||
input: $params.input_path
|
||||
```
|
||||
|
||||
> **注意**：使用 `script: run`（不是 `script_id`，不是 `script: run.py`），参数用 `$params.xxx`（不是 `${{inputs.xxx}}`）。
|
||||
|
||||
## 基础镜像
|
||||
|
||||
所有套件在 gis-base 镜像中执行，包含：Python 3, GDAL, Shapely, GeoPandas, numpy, openpyxl, xlrd
|
||||
|
||||
镜像地址：`registry.mercator.cn/agentgis/gis-base:latest`
|
||||
|
||||
> 当前 digest：`sha256:48c31cb3`（验证含 openpyxl/xlrd）
|
||||
镜像名称：`gis-base:latest`（本地加载，无需 registry）
|
||||
|
||||
## 知识库
|
||||
|
||||
|
||||
Reference in New Issue
Block a user