# 套件发布指南

## 前置条件

- 一个 API Key（从 https://auth.mercator.cn 获取）
- 套件目录包含 `workflow.yaml` 和 `scripts/`

## 一、通过 Web UI 发布

登录 https://suites.mercator.cn → 进入套件详情页 → 点击「发布」。

系统会自动打包 `workflow.yaml` + `scripts/` + `templates/` 为 `<slug>-<version>.tar.gz` 并上传到 Gitea Packages。

## 二、通过 API 发布

### 1. 直接发布（推荐）

```bash
curl -X POST https://suites.mercator.cn/api/v1/publish \
  -H "Authorization: Bearer mk_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-suite",
    "version": "1.0.0",
    "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 指向包地址
```

## 合规检测

发布时自动检测：

- `workflow.yaml` 格式是否正确
- 参数声明是否完整
- 脚本文件是否存在
- 参数类型是否匹配

不通过则发布失败，返回具体错误信息。