From 8dc7b8c04117bab21297d944f9f136ae1755e2e7 Mon Sep 17 00:00:00 2001
From: Ubuntu <ubuntu@localhost.localdomain>
Date: Mon, 13 Jul 2026 11:14:22 +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=88=E5=BC=80=E5=8F=91=E8=80=85?=
 =?UTF-8?q?=20+=20=E4=BD=BF=E7=94=A8=E8=80=85=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 suite-developer/TOOLS.md |  86 +++++++++++++++++++++++------
 suite-user/TOOLS.md      | 113 +++++++++++++++------------------------
 2 files changed, 114 insertions(+), 85 deletions(-)

diff --git a/suite-developer/TOOLS.md b/suite-developer/TOOLS.md
index 1a33eea..dbabdde 100644
--- a/suite-developer/TOOLS.md
+++ b/suite-developer/TOOLS.md
@@ -5,7 +5,8 @@
 ### agentgis-cli（命令行工具）
 
 ```bash
-pip install https://git.mercator.cn/api/packages/SuiteHub/generic/agentgis-cli/0.1.0/agentgis_cli-0.1.0-py3-none-any.whl
+# 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
@@ -20,16 +21,24 @@ agc config set api-key mk_xxxxxxxxxxx
 pip install https://git.mercator.cn/api/packages/SuiteHub/generic/agentgis-sdk/0.1.0/agentgis_sdk-0.1.0-py3-none-any.whl
 ```
 
-### gis-actions（本地执行器，可选）
+### agentgis-worker（本地执行器，`agc run` 必需）
 
-开发者如需本地测试套件执行：
+`agc run` 在 v0.2.0 中改为本地执行，不再调用平台 API。需要安装 worker：
 
 ```bash
-# 安装 gis-actions 软件包
-# Debian/Ubuntu:
+# 安装依赖（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
 ```
 
@@ -39,25 +48,35 @@ sudo systemctl start agentgis-worker
 
 ```bash
 # 🔍 查市场（写代码前先做这个）
-agc suites search <关键词>     # 搜索已有套件
-agc suites list               # 列出所有套件
+agc suites list                        # 列出所有套件
+agc suites list | grep <关键词>         # 搜索已有套件
 
-# 初始化新套件
+# 初始化新套件（脚手架）
 agc init ./my-analysis
 
-# 测试执行
-agc run <suite-id> --inputs '{"expression": "1+1"}'
+# 测试执行（需先安装 agentgis-worker）
+agc run <suite-id> --inputs '{"key": "val"}' --wait --poll 5
 
 # 发布到市场
-agc publish ./my-analysis
+# 方式一：打包后上传
+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/suites` |
-| 执行任务 | `POST https://suites.mercator.cn/api/v1/task` |
+| 发布 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` |
@@ -66,15 +85,45 @@ agc publish ./my-analysis
 
 ```
 my-suite/
-├── workflow.yaml      # 步骤定义（必填）
+├── 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。
+
 ## 知识库
 
 | 文件 | 内容 |
@@ -86,3 +135,10 @@ my-suite/
 ## 文档
 
 公开文档在 `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 未挂载输入文件 + 镜像缺包 | 待修复 |
diff --git a/suite-user/TOOLS.md b/suite-user/TOOLS.md
index 561a476..02c8bd7 100644
--- a/suite-user/TOOLS.md
+++ b/suite-user/TOOLS.md
@@ -4,118 +4,91 @@
 
 https://suites.mercator.cn
 
-浏览套件、查看详情、提交执行任务。
+浏览套件、查看详情。
 
-## CLI（可选）
+## CLI 安装
 
 ```bash
-# 安装 agentgis-cli
-pip install https://git.mercator.cn/api/packages/SuiteHub/generic/agentgis-cli/0.1.0/agentgis_cli-0.1.0-py3-none-any.whl
+# 安装 agentgis-cli 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
 
 # 配置 API Key
 agc config set api-key mk_xxxxxxxxx
 
-# 执行套件（在市场找到 suite-id 后）
-agc run <suite-id> --inputs '{"input_path": "/data/myfile.shp"}'
-
 # 查看套件列表
 agc suites list
-
-# 查看执行状态
-agc status <task-id>
 ```
 
-## gis-actions（本地执行器部署）
+## 本地执行环境
 
-gis-actions 是套件的本地执行引擎，跑在你的机器上。
+所有套件在 **你自己的机器上** 通过 Docker 执行，数据不上云。
 
 ### 前提条件
 
-- **Debian / Ubuntu 系统**
+- **Linux 系统**（Debian / Ubuntu）
 - **Docker**（验证：`docker ps`）
   - `sudo apt install docker.io`
 - 能访问 `registry.mercator.cn`（拉取 gis-base 镜像）
 
-### 安装
+### 安装本地执行器
 
 ```bash
-# 下载并安装 gis-actions
+# 安装 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
 
-# 安装后会自动配置 systemd 服务和 Docker insecure-registry
-```
+# 配置 Docker Registry 认证
+echo "agw_readonly_2026" | docker login registry.mercator.cn -u agentgis-worker --password-stdin
 
-### 配置
-
-编辑 `/etc/agentgis/worker.json`：
-
-```json
-{
-  "worker": {
-    "id": "my-machine-001",
-    "capabilities": ["gis-operations"]
-  },
-  "scheduler": {
-    "url": "https://suites.mercator.cn",
-    "poll_interval": 5,
-    "heartbeat_interval": 30
-  },
-  "auth": {
-    "api_key": "你的 API Key"
-  }
-}
-```
-
-API Key 从 https://auth.mercator.cn 获取。
-
-### 启动
-
-```bash
+# 启动 worker
 sudo systemctl start agentgis-worker
-sudo systemctl status agentgis-worker
 ```
 
-### 验证
+### 执行套件
 
 ```bash
-journalctl -u agentgis-worker -f
-# 应看到：Worker xxx started, polling https://suites.mercator.cn every 5s
+agc run <suite-id> --inputs '{"input_path": "/data/myfile.shp"}' --wait --poll 5
 ```
 
-### 停止
-
-```bash
-sudo systemctl stop agentgis-worker
-```
-
-### 卸载
-
-```bash
-sudo dpkg --purge agentgis-worker
-```
+- `<suite-id>` 从 `agc suites list` 获取
+- 输入文件路径用你的本地绝对路径
+- `--wait` 等待执行完成，`--poll 5` 每 5 秒轮询结果
 
 ### 数据流向
 
 ```
-你本地的 SHP/GeoJSON/TIFF 文件
+你本地的 SHP/GeoJSON/TIFF/XLS 文件
     │
     ▼
-gis-actions（你的机器）
-    │  ← 从调度中心拉取任务
-    │  ← 下载套件脚本包
+worker（你的机器）
+    │  ← 从市场下载套件脚本包
     │  ← docker run gis-base + 套件脚本
     │  → 结果写入 /tmp/output/
     ▼
 结果文件（你的机器）
 ```
 
-## 支持的输入类型
+## 系统服务管理
 
-| 类型 | 说明 | 示例 |
-|------|------|------|
-| `file` | 本地文件路径 | `/data/land_use.shp` |
-| `string` | 文本 | `"缓冲区距离: 500"` |
-| `number` | 数值 | `500.0` |
-| `integer` | 整数 | `100` |
-| `boolean` | 布尔值 | `true` |
+```bash
+# 查看状态
+sudo systemctl status agentgis-worker
+
+# 查看日志
+journalctl -u agentgis-worker -f
+
+# 停止
+sudo systemctl stop agentgis-worker
+
+# 卸载
+sudo dpkg --purge agentgis-worker
+```
+
+## 已知限制
+
+| 问题 | 说明 |
+|------|------|
+| 输入文件挂载 | worker 暂未自动将输入文件挂载到容器内，需等待 Issue #6 修复 |
+| 基础镜像缺包 | gis-base 暂缺 openpyxl/xlrd，Excel 套件运行时会自动 pip install |
+
+详见 https://git.mercator.cn/SuiteHub/agent-profiles/issues/6