Ubuntu
145 lines
4.1 KiB
Markdown
145 lines
4.1 KiB
Markdown
# TOOLS.md — 套件开发工具与资源
|
||
|
||
## 安装
|
||
|
||
### agentgis-cli（命令行工具）
|
||
|
||
```bash
|
||
# v0.2.0（推荐）
|
||
pip install https://git.mercator.cn/api/packages/SuiteHub/generic/agentgis-cli/0.2.0/agentgis_cli-0.2.0.tar.gz
|
||
|
||
# 查看版本
|
||
agc --version
|
||
|
||
# 配置 API Key
|
||
agc config set api-key mk_xxxxxxxxxxx
|
||
```
|
||
|
||
### agentgis-sdk（Python 开发包）
|
||
|
||
```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
|
||
```
|
||
|
||
### agentgis-worker（本地执行器，`agc run` 必需）
|
||
|
||
`agc run` 在 v0.2.0 中改为本地执行，不再调用平台 API。需要安装 worker：
|
||
|
||
```bash
|
||
# 安装依赖（Docker）
|
||
sudo apt-get install -y docker.io
|
||
sudo usermod -aG docker $USER
|
||
# 重新登录或执行 newgrp docker
|
||
|
||
# 安装 worker
|
||
wget -O agentgis-worker.deb https://git.mercator.cn/api/packages/SuiteHub/generic/gis-actions/v2.0.0-alpha/agentgis-worker_2.0.0-alpha_all.deb
|
||
sudo dpkg -i agentgis-worker.deb
|
||
|
||
# 登录 Docker Registry（拉取 gis-base 镜像）
|
||
docker login registry.mercator.cn -u <用户名> --password-stdin
|
||
|
||
# 启动
|
||
sudo systemctl start agentgis-worker
|
||
```
|
||
|
||
---
|
||
|
||
## CLI 用法
|
||
|
||
```bash
|
||
# 🔍 查市场（写代码前先做这个）
|
||
agc suites list # 列出所有套件
|
||
agc suites list | grep <关键词> # 搜索已有套件
|
||
|
||
# 初始化新套件（脚手架）
|
||
agc init ./my-analysis
|
||
|
||
# 测试执行（需先安装 agentgis-worker）
|
||
agc run <suite-id> --inputs '{"key": "val"}' --wait --poll 5
|
||
|
||
# 发布到市场
|
||
# 方式一：打包后上传
|
||
tar czf suite.tgz --exclude='.git' --exclude='__pycache__' --exclude='tests' my-suite/
|
||
agc publish upload suite.tgz
|
||
|
||
# 方式二：通过 Git 发布（需 repo_url）
|
||
curl -X POST https://suites.mercator.cn/api/v1/publish \
|
||
-H "Authorization: Bearer $KEY" \
|
||
-d '{"repo_url": "https://git.mercator.cn/org/my-suite.git"}'
|
||
```
|
||
|
||
## API 端点
|
||
|
||
| 用途 | 端点 |
|
||
|------|------|
|
||
| 发布 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` |
|
||
| API 文档 | `https://suites.mercator.cn/docs` |
|
||
|
||
## 套件结构
|
||
|
||
```
|
||
my-suite/
|
||
├── workflow.yaml # 步骤定义（必填，使用旧版格式）
|
||
└── scripts/
|
||
└── run.py # 执行入口脚本
|
||
```
|
||
|
||
### workflow.yaml 格式规范
|
||
|
||
使用旧版 `steps/script/$params` 格式，**不要**使用 `nodes/script_id/${{inputs}}` 格式：
|
||
|
||
```yaml
|
||
name: 我的套件
|
||
description: 套件描述
|
||
version: 1.0.0
|
||
author: 作者
|
||
tags: [标签1, 标签2]
|
||
|
||
params:
|
||
input_path:
|
||
type: string
|
||
required: true
|
||
desc: 输入文件路径
|
||
|
||
steps:
|
||
- id: step1
|
||
name: 步骤名称
|
||
type: script
|
||
script: scripts/run.py
|
||
params:
|
||
input: $params.input_path
|
||
```
|
||
|
||
## 基础镜像
|
||
|
||
所有套件在 gis-base 镜像中执行，包含：Python 3, GDAL, Shapely, GeoPandas, numpy
|
||
|
||
镜像地址：`registry.mercator.cn/agentgis/gis-base:latest`
|
||
|
||
> ⚠️ 已知限制：gis-base 镜像暂缺 openpyxl / xlrd，涉及 Excel 读写的套件需要在脚本中 pip install。详见 Issue #6。
|
||
|
||
## 知识库
|
||
|
||
| 文件 | 内容 |
|
||
|------|------|
|
||
| `knowledge/script-data-types.md` | 脚本数据类型分类规范 |
|
||
| `knowledge/script-dependencies.md` | 脚本依赖管理规范 |
|
||
| `knowledge/data-execution-model.md` | 数据执行模型（本地执行设计） |
|
||
|
||
## 文档
|
||
|
||
公开文档在 `SuiteHub/agent-profiles` 仓库中。
|
||
|
||
## 已知问题
|
||
|
||
| Issue | 描述 | 状态 |
|
||
|-------|------|------|
|
||
| [#5](https://git.mercator.cn/SuiteHub/agent-profiles/issues/5) | Docker Registry 认证 | 已修复（agentgis-worker/agw_readonly_2026） |
|
||
| [#6](https://git.mercator.cn/SuiteHub/agent-profiles/issues/6) | worker 未挂载输入文件 + 镜像缺包 | 待修复 |
|