docs: rewrite TOOLS.md to match v3.0.2 implementation (#8)

suite-developer/TOOLS.md

@@ -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` 必需）
+> 安装 gis-actions deb 时已自动执行上述步骤，通常无需手动操作。
-
-`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
-
-```
 
 ---
 
 ## CLI 用法
 
+`agc` 目前只有一个命令：`run`。
+
 ```bash
-# 🔍 查市场（写代码前先做这个）
+# 执行套件（唯一命令）
-agc suites list                        # 列出所有套件
+agc run /tmp/output --suite-id <suite-id> --input key=value
-agc suites list | grep <关键词>         # 搜索已有套件
 
-# 初始化新套件（脚手架）
+# 示例
-agc init ./my-analysis
+agc run /tmp/output --suite-id 2c99a1cb-84a5-42dd-9147-1c8e8f7f2941 --input buffer_distance=0.5
+```
 
-# 测试执行（需先安装 gis-actions）
+### 查询市场（通过 curl，agc 暂未内置）
-agc run /tmp/output --suite-id <suite-id> --input key=val
 
-# 发布到市场
+```bash
-# 方式一：打包后上传
+# 列出所有套件
-tar czf suite.tgz --exclude='.git' --exclude='__pycache__' --exclude='tests' my-suite/
+curl -s https://suites.mercator.cn/api/v1/suites | python3 -m json.tool
-agc publish upload suite.tgz
 
-# 方式二：通过 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` |
+| 列出套件 | `GET https://suites.mercator.cn/api/v1/suites` |
-| 更新套件版本 | `POST https://suites.mercator.cn/api/v1/suites/{id}/versions` |
+| 套件详情 | `GET https://suites.mercator.cn/api/v1/suites/{suite_id}` |
-| 合规检测 | `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      # 步骤定义（必填，使用旧版格式）
+├── 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: object
-    type: string
+  required:
-    required: true
+    - input_path
-    desc: 输入文件路径
+  properties:
+    input_path:
+      type: string
+      description: 输入文件路径
 
 steps:
   - id: step1
     name: 步骤名称
-    type: script
+    script: run
-    script_id: 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`
+镜像名称：`gis-base:latest`（本地加载，无需 registry）
-
-> 当前 digest：`sha256:48c31cb3`（验证含 openpyxl/xlrd）
 
 ## 知识库