diff --git a/RELEASE.md b/RELEASE.md
new file mode 100644
index 0000000..54f8b20
--- /dev/null
+++ b/RELEASE.md
@@ -0,0 +1,65 @@
+# 发布说明
+
+## 前置配置（仅首次）
+
+在 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               ← 本文件
+```