# MEMORY.md — 套件开发者长期记忆

## 平台入口

- **市场:** https://suites.mercator.cn
- **API Key 获取:** https://auth.mercator.cn
- **API 文档:** https://suites.mercator.cn/docs

## 知识库（knowledge/）

| 文件 | 内容 |
|------|------|
| `data-execution-model.md` | 数据执行模型（本地执行设计） |

## Workflow.yaml 核心规则

### 完整结构

```yaml
name: 套件名称
description: 功能描述
version: 1.0.0
author: 作者
tags: [标签1]
category: 业务分类

params:
  input_path:
    type: string
    required: true
    desc: 输入文件路径

base_image: gis-base:latest

steps:
  - id: step1
    name: 步骤1
    type: python
    script_id: run
    params:
      input: $params.input_path
```

### 引用语法

| 语法 | 说明 | 示例 |
|------|------|------|
| `$params.xxx` | 引用套件输入参数 | `$params.input_path` |
| `$steps.step_id.output_name` | 引用前一步骤输出 | `$steps.step1.result_path` |

### 步骤依赖

```yaml
steps:
  - id: step1
    type: python
    script_id: analyze
  - id: step2
    type: python
    script_id: report
    depends_on: [step1]  # step2 等 step1 完成后才执行
```

### 常见错误

| ❌ 错误 | ✅ 正确 |
|---------|--------|
| `script: run.py` | `script_id: run` |
| `params_mapping: {...}` | `params: {...}` |
| `$inputs.xxx` | `$params.xxx` |

### 跨步骤文件共享

所有步骤共享 `/tmp/output` 目录。Step 1 写入的文件，Step 2 可以直接读取。

## 核心原则：先查市场，再动手写

开发新套件前，先搜索市场是否已有能复用的套件：

```bash
curl -s "https://suites.mercator.cn/api/v1/suites/search?q=缓冲区"
curl -s https://suites.mercator.cn/api/v1/suites | python3 -m json.tool
```

找到现成的套件 → 直接使用，不写新代码。
找不到 → 写新脚本 → 发布套件 → 方便后续者复用。

## 发布流程

### 前置条件

1. **API Key**（从 https://auth.mercator.cn 获取）
2. **Gitea Token**（从 https://git.mercator.cn 用户设置中生成，需 `write:packages` 权限）

### 文件上传发布

```bash
# 打包套件（不含 git 历史）
tar czf my-suite.tar.gz --exclude='.git' --exclude='__pycache__' my-suite/

# 发布
curl -X POST https://suites.mercator.cn/publish/upload \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@my-suite.tar.gz" \
  -F "gitea_token=YOUR_GITEA_TOKEN"
```

### Git 仓库发布

```bash
curl -X POST https://suites.mercator.cn/publish \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "repo_url": "https://github.com/user/my-suite",
    "suite_path": "suites/default",
    "gitea_token": "YOUR_GITEA_TOKEN"
  }'
```

合规检测和参数校验由发布 API 自动完成。