# 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
```

```bash
```

### 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`

## 知识库

| 文件 | 内容 |
|------|------|
| `knowledge/script-data-types.md` | 脚本数据类型分类规范 |
| `knowledge/script-dependencies.md` | 脚本依赖管理规范 |
| `knowledge/data-execution-model.md` | 数据执行模型（本地执行设计） |

## 文档

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