# 发布说明

## 前置配置（仅首次）

在 Gitea 仓库中配置 Actions Secret：

1. 打开 `https://git.addhh.com/willow/mipu-open/-/settings/actions`
2. 点击 **Secrets** → **Add Secret**
3. Name: `GITEA_TOKEN`，Value: （向管理员获取）
4. 保存

## 发布新版本

```bash
# 1. 修改 docs/ 下的文档内容
vim docs/03-01_shopping-search.md

# 2. 提交变更
git add docs/
git commit -m "docs: 更新shopping/search接口说明"

# 3. 打版本 tag
git tag v1.1.0

# 4. 推送代码和 tag
git push && git push --tags
```

推送 tag 后 Gitea Actions 自动执行：

1. 将 `docs/` 目录打包为 `docs.tar.gz`
2. 在 `willow/mipu-open` 仓库创建 Release，附带 `docs.tar.gz`

## 版本号规则

使用语义化版本 `vMAJOR.MINOR.PATCH`：

| 场景 | 示例 |
|------|------|
| 新增接口文档 | v1.1.0 |
| 修正文档错误 | v1.0.1 |
| 文档结构变更/破坏性调整 | v2.0.0 |

## 用户端更新

mipu-api Skill 每次被调用时自动检查：

1. 读取本地 `.version` 获取当前版本
2. 查询 `https://git.addhh.com/api/v1/repos/willow/mipu-open/releases/latest`
3. 版本不一致 → 下载 `docs.tar.gz` → 解压覆盖本地 `docs/`
4. 网络异常 → 静默跳过，使用本地缓存

## 目录结构

```
mipu-open/
├── docs/                    ← 文档源文件（在此维护）
│   ├── 02-01_cache-search.md
│   ├── 03-01_shopping-search.md
│   └── ...
├── .gitea/workflows/
│   └── release-docs.yml     ← CI：tag 触发自动打包发布
├── mipu-api/                ← git submodule (Claude Code Skill)
└── RELEASE.md               ← 本文件
```