# 发版清单(Release Checklist)

> v0.4.0 起适用。前置:CI 已接入(推送 main 自动 typecheck/test/build + 打包产物);
> 自动更新已接线(electron-updater 读 GitHub Releases 的 `latest.yml`)。

## 标准发版流程

1. **版本号**:`package.json` bump(如 0.4.0 → 0.5.0),MCP serverInfo 自动跟随(`app.getVersion()`)
2. **本地验证**:`npm run typecheck && npm test && npm run dist`(需 `ELECTRON_MIRROR` / `ELECTRON_BUILDER_BINARIES_MIRROR`,见 AGENTS.md)
3. **烟测**:`./dist/win-unpacked/MemorySQL.exe` 启动 → `curl http://127.0.0.1:8642/health` → 任一语义查询验证 `·语义` 召回
4. **提交 + 推送**:
   ```bash
   git add -A && git commit -m "chore: release vX.Y.Z"
   git tag vX.Y.Z && git push origin main --tags
   ```
5. **创建 GitHub Release**(装了 gh CLI 时):
   ```bash
   gh release create vX.Y.Z dist/MemorySQL-Setup-X.Y.Z.exe dist/MemorySQL-Setup-X.Y.Z.exe.blockmap dist/latest.yml \
     --title "MemorySQL vX.Y.Z" --notes "..."
   ```
   必传三件:**exe + .exe.blockmap(差分更新用)+ latest.yml(updater 索引)**;win-unpacked 可选打包 zip 给免安装用户。

   三个平台各自的必传件(`scripts/publish-release.mjs` 已按此上传,缺哪件 updater 就对哪个平台失效):

   | 平台 | 安装包 | 更新载荷 | updater 索引 |
   |---|---|---|---|
   | Windows | `MemorySQL-Setup-X.Y.Z.exe` | `.exe.blockmap` | `latest.yml` |
   | Linux | `.AppImage` / `.deb` | — | `latest-linux.yml` |
   | macOS | `MemorySQL-X.Y.Z-{arm64,x64}.dmg` | `MemorySQL-X.Y.Z-{arm64,x64}.zip` | `latest-mac.yml`(**两个架构合并后的一份**,见下) |
6. **验收自动更新**:已安装旧版的机器启动应用 → 应静默下载新版本并提示;或在设置里手动触发(后续可加)。

## macOS 发布注意事项

- **未签名**:目前没有 Apple Developer ID,`electron-builder.yml` 里 `mac.identity: null`。
  首次启动 Gatekeeper 会拦,用户需「右键 → 打开」或执行
  `xattr -dr com.apple.quarantine /Applications/MemorySQL.app`。README 顶部已写明。
- **dmg 与 zip 缺一不可**:dmg 给人装,**zip 才是 electron-updater 替换用的载荷**。
  只发 dmg 的话 mac 用户装上之后再也收不到自动更新,且**没有任何报错**。
- **两个架构分别出包**:`macos-14`(arm64)与 `macos-13`(x64)各出一个,不做 universal。
  原因是原生模块按架构分发(`sqlite-vec-darwin-{arm64,x64}`),universal 要合并两套。
- **`latest-mac.yml` 必须合并,不能各传各的 ⚠️ 这是最容易发出去一个坏更新的地方**

  两个 CI job **各自都会产出一份叫 `latest-mac.yml` 的清单**,而一个 release 只能有一个同名文件,
  后上传的覆盖先上传的。而 electron-updater 读的是**这一份**清单,再从里面的 `files:` 列表
  按架构过滤(`MacUpdater.filterFilesForArch`,`node_modules/electron-updater/out/MacUpdater.js:30`)。
  实测行为:

  | 清单里只有 | Apple Silicon 装到 | Intel 装到 |
  |---|---|---|
  | arm64 条目 | ✅ arm64 | 空 → `ERR_UPDATER_ZIP_FILE_NOT_FOUND` |
  | x64 条目 | ⚠️ **Intel 版** | ✅ x64 |

  第二行是要命的:**Apple Silicon 会下载并安装 Intel 版**,而 `sqlite-vec` / `onnxruntime`
  都是按架构编译的原生模块,换架构即损坏 —— 而且不报任何错,直到用到那个功能才崩。

  所以发版时**先下载两个架构的清单、合并、再传**:

  ```bash
  gh run download <run-id> -n MemorySQL-macOS-arm64-<sha>  -D mac/arm64
  gh run download <run-id> -n MemorySQL-macOS-x64-<sha>    -D mac/x64
  # 两个目录里各有一份 latest-mac.yml,重名 —— 先改名
  mv mac/arm64/latest-mac.yml mac/arm64.yml
  mv mac/x64/latest-mac.yml   mac/x64.yml
  node scripts/merge-mac-manifest.mjs mac/latest-mac.yml mac/arm64.yml mac/x64.yml
  gh release upload <tag> mac/latest-mac.yml --clobber
  ```

  合并脚本会用 **electron-updater 自己的函数**校验「两个架构都能解析到 zip」,
  校验不过就拒绝输出 —— 所以拼错不会发出去,只会在发版时立刻失败。
  (两个架构的 zip/dmg 本来就是不同文件,直接原样上传即可,只有清单需要合并。)

  `scripts/publish-release.mjs` 目前按各平台逐个上传,**mac 的清单要走上面这几步**。
  Intel runner 排不到队时,可以先只发 arm64 —— 但**此时不要把 x64 的清单传上去**,
  那会覆盖成只有 x64 条目,正好是最危险的方向。

- **blockmap 缺失不影响正确性**:mac 产物里没有 `.blockmap`,只是退回全量下载
  (differential download 失效),`latest-mac.yml` 里的 `sha512` 仍然校验下载完整性。
- **本地无法验证 mac 构建**:electron-builder 硬性要求在 macOS 上构建,
  在 Windows 上跑 `--mac` 直接报 "supported only on macOS"。
  **唯一验证途径是 CI** —— 推 main 后看 package job 的两个 mac runner 是否绿。
- **要转正式签名 + 公证**:需 Apple Developer Program(US$99/年),然后
  1. 仓库 Settings → Secrets 配 `CSC_LINK`(Developer ID Application 导出的 .p12,base64)、
     `CSC_KEY_PASSWORD`、`APPLE_ID`、`APPLE_APP_SPECIFIC_PASSWORD`、`APPLE_TEAM_ID`
  2. `electron-builder.yml` 删掉 `identity: null`,补 `notarize: true` 与 `hardenedRuntime: true`
  3. CI 里去掉 `CSC_IDENTITY_AUTO_DISCOVERY: 'false'`

  转完后 mac 用户双击即开,不再有 Gatekeeper 提示。

## winget 提交(首次发版后)
- ✅ **v0.4.0 已提交**:PR https://github.com/microsoft/winget-pkgs/pull/426778
  (fork `Logic647/winget-pkgs` 分支 `winget-memorysql-0.4.0`,路径 `manifests/l/Logic647/MemorySQL/0.4.0/` 三件套,
  通过 GitHub Contents API 上传——本机无法 clone 大仓库也能提交)
- **后续版本更新流程**:同一分支模式,改 3 个 yaml 的版本号/URL/SHA256 后往同一 PR 追加,或按 winget-pkgs 惯例每个版本一个 PR
- **bot 反馈迭代**:validation pipeline 结果直接评论在 PR 上;如报 manifest 错误,改 `/tmp/winget/*.yaml` 后用同样的 Contents API PUT 到分支即可
- 本机直连 github.com:443 被墙时的完整提交路径见 DEVLOG 2026-08-31 条目(fork/branch/contents 全走 api.github.com)
- manifest 内容模板见 git 历史(本文件不保留副本,以 PR 分支为准)

## scoop 提交(可选,更轻)

- 建一个个人 bucket 仓库(如 `Logic647/scoop-bucket`),放 JSON manifest:

```json
{
  "version": "0.4.0",
  "url": "https://github.com/Logic647/MemorySQL/releases/download/v0.4.0/MemorySQL-Setup-0.4.0.exe",
  "hash": "<Get-FileHash SHA256>",
  "installer": { "script": "Start-Process \"$dir\\$fname\" /S | Wait-Process" },
  "bin": "MemorySQL.exe",
  "shortcuts": [["MemorySQL.exe", "MemorySQL"]],
  "checkver": "github",
  "autoupdate": { "url": "https://github.com/Logic647/MemorySQL/releases/download/v{$version}/MemorySQL-Setup-{$version}.exe" }
}
```
- 用户侧:`scoop bucket add logic647 https://github.com/Logic647/scoop-bucket && scoop install memorysql`

## MCP 生态登记(发布后)

- [PulseMCP](https://www.pulsemcp.com/submit) / [MCP Servers 目录](https://github.com/modelcontextprotocol/servers) PR:登记 `memory_get_context` 等 7 工具与 stdio 桥用法
- 中文社区发布素材:README 首屏截图 + 60 秒 demo 脚本(Codex 干到一半 → 换 Hermes → `memory_get_context` 无缝续接)