# 发布手册

## 发布通道

| 通道 | 分支 | 版本 | npm tag | 内容 |
| --- | --- | --- | --- | --- |
| stable | `main` | `1.x.y` | `latest` | 浏览器-only |
| legacy | `legacy/aihub` | `0.3.x` | `legacy` | AI-HUB 兼容，只接受安全修复 |

`main` 只接受快进合并；已推送的提交和已发布标签不改写、不删除、不强制推送。

## 发布前检查

```bash
pnpm install --frozen-lockfile
pnpm test
node --check lib/client.js
npm pack --dry-run
```

必须确认：

- 工作区干净，当前分支与发布通道一致。
- `package.json.version` 与 `CHANGELOG.md`、`docs/releases/v<version>.md`、README 安装行一致。
- 测试全绿，且 `lib/client.js` 与 `src/client.js` 逐字节一致。
- `npm pack --dry-run` 只包含 `lib/`、assets、`cordis.patch.yml`、LICENSE、README、CHANGELOG、THIRD_PARTY_NOTICES。
- 在干净 DSH profile 安装 tarball，完成一次局域网扫码；公网改动还要完成一次公网扫码和密码校验。

## 发布步骤

1. 合并到 `main` 并确认工作区干净。
2. 运行发布前检查。
3. `git tag -a v<version> -m "dsh-roam <version>"`。
4. `npm publish --access public`；预发布用 `--tag next`，legacy 用 `--tag legacy`。
5. `git push --atomic origin <branch> v<version>`。
6. 创建 GitHub Release，附变更、已知限制和 tarball shasum。

发布失败时只删除本地未推送的标签；远端标签和已发布版本不复用，改用新补丁版本。

## 已知边界

- 1.0 不提供应用层端到端加密；公网 TLS 在隧道或反向代理处终止。
- 浏览器会话 30 天绝对过期，插件重启后需要重新扫码。
- 临时隧道地址每次开启都会变化，固定使用请配置域名。
- iOS / iPadOS Safari 尚未实测。