From c6758a430802c8e17ff83f9184766c3d70b94c0c Mon Sep 17 00:00:00 2001
From: Ubuntu <ubuntu@localhost.localdomain>
Date: Mon, 13 Jul 2026 09:51:53 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=20TOOLS.md=20?=
 =?UTF-8?q?=E9=80=82=E9=85=8D=20v0.2.0=EF=BC=88worker=20=E5=AE=89=E8=A3=85?=
 =?UTF-8?q?=E3=80=81=E6=96=B0=E7=89=88=E6=9C=AC=E5=8F=B7=E3=80=81workflow?=
 =?UTF-8?q?=20=E6=A0=BC=E5=BC=8F=E8=A7=84=E8=8C=83=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/TOOLS.md | 135 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 135 insertions(+)
 create mode 100644 docs/TOOLS.md

diff --git a/docs/TOOLS.md b/docs/TOOLS.md
new file mode 100644
index 0000000..4db3549
--- /dev/null
+++ b/docs/TOOLS.md
@@ -0,0 +1,135 @@
+# 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`
+
+## 知识库
+
+| 文件 | 内容 |
+|------|------|
+| `knowledge/script-data-types.md` | 脚本数据类型分类规范 |
+| `knowledge/script-dependencies.md` | 脚本依赖管理规范 |
+| `knowledge/data-execution-model.md` | 数据执行模型（本地执行设计） |
+
+## 文档
+
+公开文档在 `SuiteHub/agent-profiles` 仓库中。