From bb0df9f7a9d3c0b5b30b2960868e0fe49fb55ce0 Mon Sep 17 00:00:00 2001
From: admin <admin@mercator.cn>
Date: Mon, 13 Jul 2026 09:32:41 +0000
Subject: [PATCH] =?UTF-8?q?fix(#8):=20=E9=87=8D=E5=86=99=E5=8F=91=E5=B8=83?=
 =?UTF-8?q?=E6=8C=87=E5=8D=97=EF=BC=8C=E5=AF=B9=E9=BD=90=20publish=20API?=
 =?UTF-8?q?=20=E5=AE=9E=E9=99=85=E7=AB=AF=E7=82=B9?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 suites-help/开发者指南/套件发布指南.md | 82 +++++++++++++++-----------
 1 file changed, 46 insertions(+), 36 deletions(-)

diff --git a/suites-help/开发者指南/套件发布指南.md b/suites-help/开发者指南/套件发布指南.md
index 338dd2c..f1e4d22 100644
--- a/suites-help/开发者指南/套件发布指南.md
+++ b/suites-help/开发者指南/套件发布指南.md
@@ -5,52 +5,62 @@
 - 一个 API Key（从 https://auth.mercator.cn 获取）
 - 套件目录包含 `workflow.yaml` 和 `scripts/`
 
-## 一、使用 CLI 发布（推荐）
+## 一、通过 Web UI 发布
+
+登录 https://suites.mercator.cn → 进入套件详情页 → 点击「发布」。
+
+系统会自动打包 `workflow.yaml` + `scripts/` + `templates/` 为 `<slug>-<version>.tar.gz` 并上传到 Gitea Packages。
+
+## 二、通过 API 发布
+
+### 1. 直接发布（推荐）
 
 ```bash
-# 安装 CLI
-# gis-actions 安装后自带 agc 命令（见 TOOLS.md）
-
-# 配置 API Key
-# agc config set api-key mk_xxxxxxxxxxxxx（当前 CLI 暂不支持此命令）
-
-# 发布
-# agc publish ./my-suite（当前 CLI 暂不支持，见下文 API 方式）
-```
-
-## 二、手动发布
-
-### 1. 打包
-
-```bash
-cd my-suite
-tar czf scripts.tar.gz workflow.yaml scripts/
-```
-
-### 2. 上传到包存储
-
-```bash
-curl -X PUT \
-  -H "Authorization: Bearer mk_xxxx" \
-  -F "file=@scripts.tar.gz" \
-  https://suites.mercator.cn/api/v1/publish/upload
-```
-
-### 3. 注册套件
-
-```bash
-curl -X POST https://suites.mercator.cn/api/v1/suites \
+curl -X POST https://suites.mercator.cn/api/v1/publish \
   -H "Authorization: Bearer mk_xxxx" \
   -H "Content-Type: application/json" \
   -d '{
     "name": "my-suite",
-    "description": "我的套件",
     "version": "1.0.0",
-    "workflow": { ... },
-    "package_url": "https://..."
+    "description": "我的套件",
+    "workflow_yaml": "name: my-suite\nversion: 1.0.0\nsteps: ...",
+    "scripts": {"run.py": "#!/usr/bin/env python3\n..."}
   }'
 ```
 
+### 2. 上传包文件发布
+
+先手动打包：
+
+```bash
+cd my-suite
+# 打包为 <slug>-<version>.tar.gz（slug 为套件名的 ASCII 转换）
+tar czf my-suite-1.0.0.tar.gz workflow.yaml scripts/
+```
+
+上传：
+
+```bash
+curl -X POST https://suites.mercator.cn/api/v1/publish/upload \
+  -H "Authorization: Bearer mk_xxxx" \
+  -F "file=@my-suite-1.0.0.tar.gz" \
+  -F "name=my-suite" \
+  -F "version=1.0.0"
+```
+
+## 三、发布流程说明
+
+```
+1. 提交 workflow.yaml + scripts/ 内容
+2. 系统自动校验：
+   - workflow.yaml 格式是否正确
+   - 参数声明是否完整
+   - 脚本文件是否存在
+   - 参数类型是否匹配
+3. 校验通过 → 打包为 <slug>-<version>.tar.gz → 上传到 Gitea Packages
+4. 在数据库中注册套件记录，package_url 指向包地址
+```
+
 ## 合规检测
 
 发布时自动检测：