提交qiming-mcp-proxy

qiming-mcp-proxy/RELEASE.md

@@ -0,0 +1,220 @@
+# mcp-proxy 发布指南
+
+本文档说明如何使用 cargo-dist 进行多平台发布。
+
+## 📦 支持的项目
+
+当前使用 cargo-dist 发布以下二进制文件：
+- `mcp-stdio-proxy` (mcp-proxy)
+- `document-parser`
+- `voice-cli`
+
+## 🚀 发布流程
+
+### 1. 更新版本号
+
+更新对应子项目的 `Cargo.toml` 中的版本号：
+
+```bash
+# 更新 mcp-proxy
+cd mcp-proxy
+# 编辑 Cargo.toml 中的 version 字段
+
+# 更新 document-parser
+cd document-parser
+# 编辑 Cargo.toml 中的 version 字段
+
+# 更新 voice-cli
+cd voice-cli
+# 编辑 Cargo.toml 中的 version 字段
+```
+
+### 2. 测试本地构建
+
+在发布前，可以测试本地构建是否正常：
+
+```bash
+# 生成发布计划
+~/.cargo/bin/dist plan --tag=v0.2.0
+
+# 构建（测试）
+~/.cargo/bin/dist build --tag=v0.2.0
+```
+
+### 3. 提交并打标签
+
+```bash
+# 提交更改
+git add .
+git commit -m "release: v0.2.0"
+
+# 创建标签
+git tag v0.2.0
+
+# 推送到远程仓库
+git push
+git push --tags
+```
+
+### 4. GitHub Actions 自动发布
+
+推送标签后，GitHub Actions 会自动：
+- ✅ 构建所有目标平台的二进制文件
+- ✅ 生成安装脚本（shell 和 powershell）
+- ✅ 生成校验和（SHA256）
+- ✅ 创建 GitHub Release
+- ✅ 上传所有构建产物
+
+## 📦 支持的平台
+
+- Linux x86_64 (`x86_64-unknown-linux-gnu`)
+- Linux ARM64 (`aarch64-unknown-linux-gnu`)
+- macOS Intel (`x86_64-apple-darwin`)
+- macOS Apple Silicon (`aarch64-apple-darwin`)
+- Windows x86_64 (`x86_64-pc-windows-msvc`)
+
+## 📥 用户安装方式
+
+### 方式 1: 使用安装脚本（推荐）
+
+**Linux/macOS:**
+```bash
+# 安装 mcp-proxy
+curl --proto '=https' --tlsv1.2 -sSf https://github.com/nuwax-ai/mcp-proxy/releases/latest/download/mcp-stdio-proxy-installer.sh | sh
+
+# 安装 document-parser
+curl --proto '=https' --tlsv1.2 -sSf https://github.com/nuwax-ai/mcp-proxy/releases/latest/download/document-parser-installer.sh | sh
+
+# 安装 voice-cli
+curl --proto '=https' --tlsv1.2 -sSf https://github.com/nuwax-ai/mcp-proxy/releases/latest/download/voice-cli-installer.sh | sh
+```
+
+**Windows (PowerShell):**
+```powershell
+# 安装 mcp-proxy
+irm https://github.com/nuwax-ai/mcp-proxy/releases/latest/download/mcp-stdio-proxy-installer.ps1 | iex
+
+# 安装 document-parser
+irm https://github.com/nuwax-ai/mcp-proxy/releases/latest/download/document-parser-installer.ps1 | iex
+
+# 安装 voice-cli
+irm https://github.com/nuwax-ai/mcp-proxy/releases/latest/download/voice-cli-installer.ps1 | iex
+```
+
+### 方式 2: 直接下载二进制
+
+从 [GitHub Releases](https://github.com/nuwax-ai/mcp-proxy/releases) 下载对应平台的压缩包。
+
+**Linux/macOS:**
+```bash
+# 下载并解压
+curl -L https://github.com/nuwax-ai/mcp-proxy/releases/latest/download/mcp-stdio-proxy-x86_64-unknown-linux-gnu.tar.xz | tar xJ
+
+# 安装
+sudo mv mcp-stdio-proxy /usr/local/bin/
+```
+
+**Windows:**
+下载 `.zip` 文件并解压，将 `.exe` 文件放到 PATH 目录中。
+
+### 方式 3: 使用 cargo install
+
+```bash
+cargo install mcp-stdio-proxy
+```
+
+### 方式 4: 使用 cargo-binstall
+
+```bash
+# 如果已安装 cargo-binstall
+cargo binstall mcp-stdio-proxy
+
+# 或从 crates.io 直接安装
+cargo install cargo-binstall
+cargo binstall mcp-stdio-proxy
+```
+
+## 🔐 校验和验证
+
+每个发布都会包含 `sha256.sum` 文件，用于验证下载的文件完整性：
+
+```bash
+# 下载校验和文件
+curl -L -O https://github.com/nuwax-ai/mcp-proxy/releases/latest/download/sha256.sum
+
+# 验证下载的文件
+sha256sum -c sha256.sum
+```
+
+## 📋 发布检查清单
+
+在发布前，请确认：
+
+- [ ] 所有子项目的版本号已更新
+- [ ] `Cargo.toml` 中的 `repository` 字段正确
+- [ ] CHANGELOG.md 已更新（如有）
+- [ ] 本地测试构建成功
+- [ ] Git tag 格式正确（如 `v0.2.0`）
+- [ ] 推送 tag 到远程仓库
+
+## 🛠️ 配置文件
+
+### `dist-workspace.toml`
+
+配置 cargo-dist 的行为：
+
+```toml
+[dist]
+# CI 后端
+ci = "github"
+
+# 安装脚本类型
+installers = ["shell", "powershell"]
+
+# 构建目标平台
+targets = [
+    "aarch64-apple-darwin",
+    "aarch64-unknown-linux-gnu",
+    "x86_64-apple-darwin",
+    "x86_64-unknown-linux-gnu",
+    "x86_64-pc-windows-msvc"
+]
+```
+
+### `.github/workflows/release.yml`
+
+自动生成的 GitHub Actions 工作流，处理：
+- 构建计划
+- 多平台编译
+- 生成安装脚本和校验和
+- 创建 GitHub Release
+
+## 📞 故障排查
+
+### 构建失败
+
+如果 GitHub Actions 构建失败，检查：
+1. 所有子项目的 `Cargo.toml` 都有 `repository` 字段
+2. 版本号格式正确（遵循 SemVer）
+3. 所有依赖项兼容
+
+### 本地测试
+
+在本地测试发布流程：
+
+```bash
+# 查看发布计划
+dist plan --tag=v0.2.0
+
+# 构建产物
+dist build --tag=v0.2.0
+
+# 查看构建结果
+ls -la target/distrib/
+```
+
+## 📚 相关资源
+
+- [cargo-dist 官方文档](https://axodotdev.github.io/cargo-dist/)
+- [GitHub Releases](https://github.com/nuwax-ai/mcp-proxy/releases)
+- [项目仓库](https://github.com/nuwax-ai/mcp-proxy)