docs: record discovery, conversion and macOS packaging regressions
parent
708bb5b0b1
commit
d9bb079ec2
|
|
@ -429,7 +429,8 @@ scripts/ OCR staging, macOS sidecars, Windows installer, release buil
|
|||
public/tesseract/ WASM core + traineddata, generated, not committed
|
||||
assets/ app icon source
|
||||
src-tauri/icons/ generated app icons per platform
|
||||
docs/ Windows build guide, release/update channel, roadmap, mobile plan
|
||||
docs/ Windows build guide, release/update channel, engineering regression
|
||||
ledger, roadmap, mobile plan
|
||||
scripts/linux/ Dockerfile that builds the Linux deb/AppImage off CI
|
||||
.github/workflows/ CI definitions for macOS, Windows and Linux (see Contributing)
|
||||
FileFlipper/ separate companion project, its own repository
|
||||
|
|
@ -453,7 +454,7 @@ The one exception is opt-in by usage: **Send to a device** talks to your local n
|
|||
- Windows recording and media conversion require `ffmpeg` on `PATH`. On Linux media conversion also requires it, area recording needs `wf-recorder` under Wayland and `ffmpeg` under X11, and neither path is exercised by the forge this repository is hosted on, so treat Linux capture as build-verified only.
|
||||
- Linux is a build target, not a shipped product: no deb or AppImage is published, so the update channel carries no `linux` key and a Linux build finds nothing to download. `scripts/linux/Dockerfile` and the `linux` job in CI remain the recipe for anyone who wants one.
|
||||
- Dragging a library row out uses the webview's file-URL drag support. It is the standard `text/uri-list` payload with a `file://` entry plus the plain path, and it needs a gesture-level check on each platform; until then, **Send**, **Reveal** and the row's own buttons are the guaranteed paths for handing a file over.
|
||||
- LAN sharing needs a network that allows peer traffic. Multicast is skipped by some guest and corporate Wi-Fi; those networks still work over the broadcast and unicast fallbacks, but two copies cannot meet across a router that isolates clients.
|
||||
- LAN sharing needs a network that allows peer traffic. Multicast is skipped by some guest and corporate Wi-Fi; those networks still work over the broadcast and unicast fallbacks, but two copies cannot meet across a router that isolates clients. The discovery invariants, permission checks and regression matrix are in `docs/ENGINEERING-NOTES.md`.
|
||||
- On Windows only one Shift copy per machine can hold the discovery port, so extra instances do not appear as peers.
|
||||
- Windows and Linux paths are compile-verified here, and the forge hosting this repository runs no Actions, so nothing is ever built by CI on your behalf. Gesture-level QA needs real Windows and Linux hardware.
|
||||
- Signing identity changes on macOS may require re-approving Screen Recording and Accessibility.
|
||||
|
|
|
|||
|
|
@ -425,7 +425,7 @@ scripts/ OCR 资源准备、macOS 伴生进程、Windows 安装器
|
|||
public/tesseract/ WASM 内核与语言模型,构建生成,不提交
|
||||
assets/ 应用图标源文件
|
||||
src-tauri/icons/ 各平台生成的应用图标
|
||||
docs/ Windows 构建指南、发布与更新通道、路线图、移动端规划
|
||||
docs/ Windows 构建指南、发布与更新通道、工程回归台账、路线图、移动端规划
|
||||
scripts/linux/ 在 CI 之外构建 Linux deb/AppImage 的 Dockerfile
|
||||
.github/workflows/ macOS、Windows、Linux 的 CI 定义(见「参与贡献」)
|
||||
FileFlipper/ 独立姊妹项目,拥有自己的仓库
|
||||
|
|
@ -447,7 +447,7 @@ Shift 对文件做的任何处理都不会发起互联网请求。文件在本
|
|||
- Windows 的录屏与音视频转换要求 `PATH` 中存在 `ffmpeg`。Linux 的音视频转换同样需要它,区域录屏在 Wayland 下需要 `wf-recorder`、在 X11 下需要 `ffmpeg`;本仓库所在的代码托管平台不会执行这些路径,因此 Linux 的截图能力只能算「可编译」而非「已验证」。
|
||||
- Linux 是「可构建」而非「已发布」:不提供 deb 或 AppImage,更新通道里也没有 `linux` 键,因此 Linux 构建检查更新时会得到「没有对应产物」。想要自己动手的人,可照 `scripts/linux/Dockerfile` 或 CI 里的 `linux` 任务来做。
|
||||
- 把历史库的某一行拖出去依赖 Webview 对 file URL 拖拽的支持。载荷使用标准的 `text/uri-list`(内含 `file://` 条目)并附带纯文本路径,仍需在每个平台上做手势级验证;在此之前,**发送**、**在文件夹中显示**以及行内按钮是交付文件的确定路径。
|
||||
- 局域网分享依赖允许点对点流量的网络。部分访客网络与企业 Wi-Fi 会丢弃组播;这些网络仍可经由广播与单播回退路径工作,但若路由器隔离了客户端,两个实例便无法相遇。
|
||||
- 局域网分享依赖允许点对点流量的网络。部分访客网络与企业 Wi-Fi 会丢弃组播;这些网络仍可经由广播与单播回退路径工作,但若路由器隔离了客户端,两个实例便无法相遇。发现机制的不可回退约束、权限排查与回归矩阵见 `docs/ENGINEERING-NOTES.md`。
|
||||
- Windows 上每台电脑只有一个 Shift 实例能占用发现端口,因此额外实例不会出现在设备列表中。
|
||||
- Windows 与 Linux 代码路径在本机通过编译验证,而托管本仓库的平台并不运行 Actions,因此 CI 不会替你构建任何东西;手势层面的验证仍需真实 Windows 与 Linux 设备。
|
||||
- macOS 上签名身份变化后,可能需要重新授予「屏幕录制」与「辅助功能」权限。
|
||||
|
|
|
|||
|
|
@ -1,7 +1,8 @@
|
|||
Shift 0.1.7 - macOS 通用(universal)
|
||||
|
||||
本文件说明 macOS 安装包是怎么打出来的、在其它机器上会遇到什么,以及如何自己校验。
|
||||
完整细节见仓库 docs/RELEASE.md 的「macOS packaging」。
|
||||
完整细节见仓库 docs/RELEASE.md 的「macOS packaging」和 docs/ENGINEERING-NOTES.md
|
||||
的「macOS DMG 打包与跨机器安装」。
|
||||
|
||||
|
||||
关于这个安装包
|
||||
|
|
@ -40,6 +41,14 @@ macOS 权限
|
|||
这类授权绑在这个哈希上,所以一次升级后可能需要重新授权——这与手动重装是同一
|
||||
后果。要彻底消除它,需要 Developer ID 证书加公证(见仓库 docs/ROADMAP.md 的 M5)。
|
||||
|
||||
发布前的硬性回归
|
||||
构建机能够打开自己生成的 DMG,不代表发布包合格。每次发版前必须通过发布源在另
|
||||
一台 Mac(最好从未安装过 Shift)用浏览器下载最终 DMG,以保留真实用户会遇到的
|
||||
quarantine 标记;然后挂载、拖入 Applications、完成首次授权并启动,确认版本号
|
||||
正确。随后打开 Drop,确认能看到另一台 Shift 终端且不会很快消失。若该版本同时
|
||||
提供软件内升级,还要从上一版实际升级一次,确认不会出现 Gatekeeper 提示。任何
|
||||
一项未通过都不得上传 DMG。
|
||||
|
||||
软件内升级
|
||||
设置 → 软件更新 里检查并安装:Shift 自己下载 .dmg,先核对字节数与 SHA256,
|
||||
再由一个独立脚本等本进程退出后挂载镜像、ditto 出新副本、去掉隔离属性、用两次
|
||||
|
|
|
|||
|
|
@ -0,0 +1,290 @@
|
|||
# Shift 工程回归台账
|
||||
|
||||
本文件记录 0.1.2 到 0.1.7 之间已经踩过、并且不应再次引入的工程问题,重点覆盖:
|
||||
|
||||
- Drop / 局域网设备发现
|
||||
- DOCX、Markdown 与图片转换
|
||||
- macOS DMG 打包及在其它机器上的安装
|
||||
|
||||
它记录的是实现约束、故障原因和回归方法,不是用户手册。修改相关代码或打包配置前,
|
||||
先读对应章节;发布后如果得到新的有效结论,也把结论补回这里,并附上提交号。
|
||||
|
||||
## 版本线索
|
||||
|
||||
| 版本 | 本台账相关的已确认事实 |
|
||||
| --- | --- |
|
||||
| 0.1.2 | 当时的 Drop 在两台机器上实测可用;软件内安装升级和重启链路也已打通。 |
|
||||
| 0.1.3 | 最近文件列表迁到应用数据目录,升级后不再随安装包替换而消失。 |
|
||||
| 0.1.4 | 修复带图 DOCX→PDF、带相对图片 Markdown→DOCX/RTF 的丢图问题。 |
|
||||
| 0.1.5 | macOS 改为 ad-hoc 签名并只发布通用 DMG,同时增加本地网络用途声明;但升级后出现 Drop 设备列表为空/只短暂闪现的回归。 |
|
||||
| 0.1.6 | 增加按网卡定向广播,改善过滤组播的网络,但用户实测仍只能短暂看到设备。 |
|
||||
| 0.1.7 | 增加单播扫描、普通信标回应、15 秒过期和 Windows 错误处理;用户实测 Mac 与 Windows 终端的 Drop 发现恢复正常。 |
|
||||
|
||||
历史提交可以这样定位:
|
||||
|
||||
```bash
|
||||
git show --stat 35cca59 # 0.1.6:定向广播
|
||||
git show --stat 708bb5b # 0.1.7:Drop 完整修复
|
||||
git show --stat 19602b7 # 带图 DOCX→PDF
|
||||
git show --stat 9950607 # Markdown 相对图片
|
||||
git show --stat 42d6424 # macOS 改回 ad-hoc 签名
|
||||
git show --stat 58949be # 撤回 pkg,只保留 DMG
|
||||
```
|
||||
|
||||
## Drop / 局域网设备发现
|
||||
|
||||
### 0.1.7 的发现链路
|
||||
|
||||
实现位于 `src-tauri/src/share.rs`。当前链路不是单独依赖组播,而是四层回退:
|
||||
|
||||
1. 每个运行中的 Shift 启动一个常驻 UDP 发现线程,绑定共享端口
|
||||
`47888`。
|
||||
2. 常规信标每 2 秒发往组播组 `239.255.77.88:47888`,同时发往每个活动
|
||||
IPv4 网卡的定向广播地址和受限广播地址。
|
||||
3. 打开 Drop 设备面板时,`share_refresh` 只设置
|
||||
`ShareState.refresh_requested` 原子标记,让常驻线程立刻广播并扫描;它不会再创建
|
||||
第二个同端口 socket。
|
||||
4. 单播扫描覆盖本机所在网段,每 30 秒一次;大网段被限制在包含本机的 `/24`
|
||||
内,最多约 253 个地址,避免全网段泛洪。
|
||||
5. 收到普通信标后,新版本总是回一个带 `reply: true` 的单播信标。回复信标不会再次
|
||||
触发回复,避免两台新版本无限互答。
|
||||
6. 已知设备每 2 秒还会收到一次定向单播,因此即使对端自己的组播和广播都被过滤,
|
||||
只要先通过扫描建立联系,设备就能持续可见。
|
||||
7. 15 秒没有再次收到设备信标才从列表移除。旧版本自己的过期时间是 9 秒,2 秒刷新
|
||||
周期必须在旧版本清除本机后仍来得及再次回应。
|
||||
8. 文件传输使用信标中携带的动态 TCP 端口和 `SHSF` 握手;UDP 源端口不是传输端口。
|
||||
|
||||
### 不能随意改掉的约束
|
||||
|
||||
| 约束 | 原因 |
|
||||
| --- | --- |
|
||||
| `share_refresh` 必须复用常驻发现线程 | Windows 不能可靠地二次绑定 `47888`;Unix 上第二个 socket 可能抢走回复。0.1.7 之前的“只闪一下”就是这条链路失效的表现。 |
|
||||
| 保留 `reply` 标记和 `#[serde(default)]` | 新版本必须能被旧版本解析,也必须能解析旧版本的省略字段;没有该标记,双方会无限互答。 |
|
||||
| 普通信标每次都回复 | 只在“首次发现”时回复会让过滤组播的网络里的设备闪一次后消失。 |
|
||||
| `PEER_TIMEOUT` 保持大于旧版 9 秒过期时间加刷新周期 | 0.1.7 使用 15 秒。缩短会重新制造旧版与新版本交替上线时列表闪烁的问题。 |
|
||||
| 同时保留组播、定向广播、受限广播和单播扫描 | 不同路由器、访客 Wi-Fi 和企业网络会分别过滤其中一种;只改回其中一条路径会导致特定网络回归。 |
|
||||
| 发现线程忽略 Windows 的 `ConnectionReset` / `ConnectionAborted` | 扫描关闭端口会产生排队的 ICMP 失败,这不是发现线程应退出的错误。 |
|
||||
| 每 30 秒重建 socket,但不要退出线程 | 电脑休眠、切换 Wi-Fi 或网络接口变化后,需要重新加入组播;线程退出则再也不会恢复发现。 |
|
||||
| `src-tauri/Info.plist` 保留 `NSLocalNetworkUsageDescription` | macOS 没有用途说明时无法正确发起本地网络访问授权。 |
|
||||
| 发现端口和协议字段保持兼容 | 频道中同时可能有旧版本;新增字段必须可缺省,不能直接改掉现有 beacon 语义。 |
|
||||
|
||||
### 权限与网络排查
|
||||
|
||||
设备列表为空时,先按以下顺序排查,不要直接改发现算法:
|
||||
|
||||
1. **macOS 本地网络权限**:系统设置 → 隐私与安全性 → 本地网络,确认当前安装的
|
||||
`Shift.app` 已打开。ad-hoc 构建每次签名哈希可能变化,因此升级后可能出现新的
|
||||
Shift 条目,旧条目仍保留。
|
||||
2. **Windows 防火墙**:首次运行时应允许 Shift 访问“专用网络”。公共网络配置下,
|
||||
Windows 防火墙通常会阻止入站信标和文件接收。
|
||||
3. **客户端隔离**:访客 Wi-Fi 或企业网络若开启 AP/client isolation,两台设备即使
|
||||
在同一子网也无法直接收发 UDP/TCP。这是网络策略限制,不是端口扫描能绕过的。
|
||||
4. **VPN 和多网卡**:确认两台机器使用的是同一个实际可互通网段;VPN 可能把默认路由
|
||||
和接口顺序带偏。当前扫描只覆盖活动 IPv4 网卡。
|
||||
5. **Windows 单实例限制**:Windows 上每台机器只有一个 Shift 进程能绑定发现端口;
|
||||
验证多机发现时不要在同一台 Windows 上同时运行多个安装副本。
|
||||
6. **ad-hoc 签名变化**:macOS 的本地网络授权绑定签名身份。无法解释的“升级前可见、
|
||||
升级后不可见”应先检查权限条目,再检查代码。
|
||||
|
||||
正常发现时日志中会出现:
|
||||
|
||||
```text
|
||||
Shift share: found <machine> on <ip>
|
||||
```
|
||||
|
||||
### 回归测试
|
||||
|
||||
自动测试在 `src-tauri/src/share.rs` 和 `src-tauri/Cargo.toml`:
|
||||
|
||||
```bash
|
||||
cd src-tauri
|
||||
cargo test --lib share::
|
||||
```
|
||||
|
||||
重点用例:
|
||||
|
||||
- `subnet_scan_skips_this_host_and_broadcast`
|
||||
- `subnet_scan_bounds_a_large_network_to_this_twenty_four`
|
||||
- `reply_beacons_are_distinguished_from_regular_ones`
|
||||
- `peer_timeout_covers_a_legacy_peers_reply_cycle`
|
||||
- `two_copies_on_one_machine_discover_each_other`(默认 ignored,会绑定共享发现端口)
|
||||
|
||||
需要排查真实 socket 和当前网络时运行:
|
||||
|
||||
```bash
|
||||
cd src-tauri
|
||||
cargo test share:: -- --ignored --nocapture
|
||||
```
|
||||
|
||||
每次修改发现、签名或打包配置后,仍要完成真机矩阵:
|
||||
|
||||
| 场景 | 验收标准 |
|
||||
| --- | --- |
|
||||
| macOS ↔ macOS | 打开 Drop 后数秒内出现对端,等待 15 秒以上仍不消失。 |
|
||||
| macOS ↔ Windows x64 | Windows 允许专用网络防火墙后,双方都能发现对方。 |
|
||||
| 升级后 | 旧版本升级到新版本,不需要重启路由器,设备列表能恢复。 |
|
||||
| 切换 Wi-Fi / 休眠唤醒 | 30 秒内重新发现;不得要求退出应用。 |
|
||||
| 权限拒绝再允许 | macOS 本地网络或 Windows 防火墙从拒绝改为允许后,重新打开面板可发现。 |
|
||||
|
||||
0.1.7 的用户验收环境是 Mac 与 Windows 各一台,升级后 Drop 设备发现正常。该结论
|
||||
覆盖真实跨系统发现,但仓库所在平台没有 CI,也没有自动化的双机网络夹具,因此发布前
|
||||
仍需重复上面的手工矩阵。
|
||||
|
||||
## DOCX、Markdown 与图片转换
|
||||
|
||||
### 当前转换路径
|
||||
|
||||
| 输入 → 输出 | 当前实现 | 关键点 |
|
||||
| --- | --- | --- |
|
||||
| 纯图片 DOCX → PDF | `office::document_page_images` 按文档顺序抽取页面图片,再由 `pdf::images_to_pdf_with_progress` 生成 PDF | 保留页数和原始图片内容;这是扫描件路径,不经过 AppKit 文本排版。 |
|
||||
| 含文字和图片 DOCX → PDF | 先用 Pandoc `docx → html5`,通过 `--extract-media` 抽取图片到临时目录,再交给 `native/macos/doc-render.swift` | AppKit 的 OOXML 读取器会静默丢弃内嵌图片,所以这类 DOCX 不能直接交给它。 |
|
||||
| Markdown → PDF | 先由 Pandoc(可用时)或内置 `markdown::to_html` 转成 HTML,再交给 AppKit 渲染器;HTML 的 base URL 指向 Markdown 源目录 | 相对图片路径依赖源目录,不能用临时 HTML 所在目录。 |
|
||||
| Markdown → DOCX / RTF | Pandoc,并传 `--resource-path <源目录>` | Pandoc 的工作目录不是文档目录;缺少该参数会把相对图片替换成 alt 文本。 |
|
||||
| Markdown → HTML | Pandoc,并传 `--resource-path <源目录>` 和 `--self-contained` | 输出必须是可单独移动的单文件,不能引用从未生成的 `media/` 目录。 |
|
||||
| 含图 DOCX → HTML | Pandoc 加 `--self-contained` | 图片以内嵌 data URI 写入 HTML。 |
|
||||
| 任意含宽图的文档 → PDF | `doc-render.swift` 的 `fitAttachments` 把超宽附件按正文栏宽度等比缩放 | 不重采样像素,只修正排版请求的尺寸,避免截图被裁成碎片。 |
|
||||
|
||||
### 不能随意改掉的约束
|
||||
|
||||
1. **不要把含图 DOCX 直接交给 AppKit OOXML 读取器。** 它会返回只有文字、没有附件的
|
||||
attributed string;问题发生在解析阶段,调页边距或打印参数无法找回图片。
|
||||
2. **纯图片 DOCX 的页面抽取要排在通用渲染之前。** 它决定扫描件的真实页数和页面顺序。
|
||||
3. **DOCX→HTML 后必须把 `--extract-media` 的临时目录作为 HTML base directory。**
|
||||
Pandoc 会把图片写成相对路径;base 指向源 DOCX 目录会找不到已抽取媒体。
|
||||
4. **Markdown→PDF 的 HTML base URL 始终是源 Markdown 目录。** 即使 HTML 写在临时目录,
|
||||
也不能改用临时目录。
|
||||
5. **Pandoc 转 DOCX/RTF/HTML 必须保留 `--resource-path`。** 这是相对图片丢失问题的
|
||||
根因修复,不应为了简化命令删掉。
|
||||
6. **HTML 输出必须保留 `--self-contained`。** 否则用户拿到的是一个引用不存在媒体目录
|
||||
的 HTML 文件。
|
||||
7. **宽图适配在 `doc-render.swift` 中完成。** 仅修改 CSS 宽度不会影响 AppKit 对这种
|
||||
HTML `<img>` 单元格的实际 attachment bounds。
|
||||
8. **无 Pandoc 时保留 macOS 的降级路径。** 带图 DOCX 会退回旧的文本渲染,而不是让
|
||||
整个转换直接失败;修改时要明确产品选择,不能无意打破降级。
|
||||
9. **Swift 渲染器改动后重新运行 `pnpm mac:drag-bridge`。** 只改源码不重编伴生进程,
|
||||
打出的 DMG 不会包含修复。
|
||||
|
||||
### 回归测试
|
||||
|
||||
自动测试集中在 `src-tauri/src/files.rs`:
|
||||
|
||||
- `renders_image_only_docx_pages_to_pdf`
|
||||
- `keeps_pictures_when_rendering_a_text_docx_to_pdf`
|
||||
- `fits_a_wide_picture_onto_the_page`
|
||||
- `image_bearing_docx_to_html_embeds_images`
|
||||
- `keeps_markdown_images_when_converting_to_word`
|
||||
|
||||
其中 `keeps_markdown_images_when_converting_to_word` 覆盖 DOCX 和 RTF;
|
||||
`image_bearing_docx_to_html_embeds_images` 检查 HTML 中的图片是 data URI 而不是
|
||||
`media/` 引用。很多用例在缺少 Pandoc 时跳过,因此本机安装 Pandoc 后才能得到完整结果。
|
||||
|
||||
历史验收样例:
|
||||
|
||||
- `平台技术方案(带图测试专用).docx`
|
||||
- `智飞空地一体化低空应用平台技术方案.md`
|
||||
|
||||
这两个样例是手工验收材料,当前没有提交到仓库,不能声称 CI 会自动重跑。每次改动转换
|
||||
路径时,应重新用它们检查标题、表格、正文顺序、相对路径图片和宽图是否同时保留。
|
||||
|
||||
### 当前边界
|
||||
|
||||
- 自动化覆盖的是本地文件和相对路径图片。没有单独的 HTTP/HTTPS 图片下载、缓存、重试
|
||||
与离线回退实现,因此不要声称任意远程图片 URL 都已有自动回归保障。
|
||||
- 含图 DOCX 依赖 Pandoc;没有 Pandoc 时会退回旧文本路径,这是兼容性降级,不等于
|
||||
图片仍被保留。
|
||||
- AppKit 渲染器只在 macOS 构建中可用;Windows/Linux 的文档→PDF 仍走各自的 Pandoc
|
||||
与 PDF 引擎路径。
|
||||
|
||||
## macOS DMG 打包与跨机器安装
|
||||
|
||||
### 当前发布方案
|
||||
|
||||
Shift 的 macOS 产物只有:
|
||||
|
||||
```text
|
||||
Shift-macOS-universal.dmg
|
||||
```
|
||||
|
||||
它是 Apple silicon 与 Intel 通用的应用包,同时用于首次安装和软件内升级。更新清单的
|
||||
`macos` 键必须指向这个 DMG,因为软件内升级脚本会用 `hdiutil` 挂载它再取出应用。
|
||||
不再发布 `.pkg`;`scripts/macos-pkg.sh` 可以保留作历史工具,但不能进入正式发布目录或
|
||||
更新清单。
|
||||
|
||||
当前签名配置是:
|
||||
|
||||
```json
|
||||
"macOS": {
|
||||
"signingIdentity": "-",
|
||||
"hardenedRuntime": false
|
||||
}
|
||||
```
|
||||
|
||||
`"-"` 表示 ad-hoc 签名。项目没有 Apple Developer ID,也不做 notarization,因此新机器
|
||||
第一次打开仍需在 Gatekeeper 中授权一次。
|
||||
|
||||
### 为什么不能用本地自签名证书
|
||||
|
||||
历史上曾使用构建机钥匙串中的 `Shift Local Signing` 证书。它在构建机上看起来完全
|
||||
正常:`codesign` 验证通过,`spctl` 也可能接受,因为证书只存在于那台机器。换到其它
|
||||
Mac 后,证书无法链到受信任根,下载的应用会被系统报告为“已损坏”或恶意软件,而且只
|
||||
提供“移到废纸篓”,没有允许运行的入口。
|
||||
|
||||
因此:
|
||||
|
||||
- **不要重新启用 `Shift Local Signing` 或任何只存在于构建机的证书。**
|
||||
- **不要清空 `signingIdentity` 让它自动选择钥匙串身份。** Tauri 可能挑到本机证书,
|
||||
重新产生同样的跨机器故障。
|
||||
- 保持 ad-hoc,直到项目真正具备 `Developer ID Application` 证书和 notarization。
|
||||
|
||||
### 首次安装与软件内升级
|
||||
|
||||
| 场景 | 预期行为 |
|
||||
| --- | --- |
|
||||
| 其它 Mac 首次下载 DMG | 双击挂载,拖 `Shift.app` 到 `/Applications`。首次启动会提示“身份不明的开发者”;右键 → 打开,或在系统设置 → 隐私与安全性中允许一次。 |
|
||||
| 软件内升级 | 下载 DMG、校验字节数与 SHA256,退出应用后由 helper 挂载、复制、移除 quarantine、替换并重启;不经过浏览器,因此不应出现 Gatekeeper 提示。 |
|
||||
| 构建机本地运行 | 能打开不代表发布包合格;必须从 DMG 转移到另一台机器验证,构建机结论不能替代跨机器验收。 |
|
||||
|
||||
### 每次 macOS 发布前的硬性检查
|
||||
|
||||
1. 运行 `pnpm mac:drag-bridge`,确保拖拽、PDF 与文档渲染三个 Swift 伴生进程都已重新
|
||||
编译为 universal。
|
||||
2. 构建 `pnpm tauri build --target universal-apple-darwin --bundles app,dmg`。
|
||||
3. 对应用执行 `codesign --verify --deep --strict`,并确认
|
||||
`codesign -dv --verbose=2` 显示 `Signature=adhoc`,而不是本地证书名称。
|
||||
4. 对 DMG 执行 `hdiutil verify`;对发布目录执行 `shasum -a 256 -c SHA256SUMS.txt`。
|
||||
5. 确认 `artifacts/` 和 `shift-update.json` 都没有 `.pkg`,`macos` 键指向 DMG。
|
||||
6. **把 DMG 转移到另一台 Mac 验证。** 最好使用没有安装过 Shift 的机器,并通过浏览器从
|
||||
发布源下载最终文件,让 quarantine 标记符合真实用户路径。若用 USB 或 AirDrop 转移,
|
||||
应确认隔离属性仍存在,否则 Gatekeeper 这一项没有被验证。完成拖入 `/Applications`、
|
||||
首次右键打开、启动应用,并检查版本号。
|
||||
7. 在同一台机器打开 Drop,确认本地网络授权正常、能看到另一台 Shift 终端。签名和打包
|
||||
改动最容易同时影响应用启动与局域网权限。
|
||||
8. 如果验证的是升级包,再从旧版本执行一次软件内升级并确认无需 Gatekeeper 提示。
|
||||
|
||||
第 6 步是发布闸门。只在一台机器上生成、签名和打开 DMG 不足以证明“其它机器可安装”。
|
||||
0.1.7 的 DMG 已在其它机器验证可用;后续每次更换签名方式或打包容器时都要重做。
|
||||
|
||||
### 已知边界
|
||||
|
||||
- ad-hoc 构建每次的签名哈希可能变化,macOS 的“屏幕录制”和“本地网络”授权也可能重置。
|
||||
这是当前没有 Developer ID 的代价,不是 Drop 代码回归。
|
||||
- Developer ID + notarization 才能消除首次安装提示,并让权限在升级间稳定。当前项目没有
|
||||
该证书,不能把“已公证”写入发布说明。
|
||||
- 发布前不能只看构建机上的 `spctl` 结果;跨机器安装行为和系统提示类型才是有效证据。
|
||||
|
||||
## 修改这些路径时的统一回归命令
|
||||
|
||||
```bash
|
||||
git diff --check
|
||||
|
||||
cd src-tauri
|
||||
cargo fmt --check
|
||||
cargo test --lib
|
||||
|
||||
cd ..
|
||||
pnpm check
|
||||
pnpm test
|
||||
```
|
||||
|
||||
发布构建还需额外完成本文对应章节的手工矩阵。任何一次修改如果改变了发现协议、转换
|
||||
依赖链或 macOS 签名方式,都应在本文件补一条带日期的结论和提交号。
|
||||
|
|
@ -48,6 +48,12 @@ Publishing an ARM64 Windows build later needs no code change: the ladder already
|
|||
`windows-arm64` and falls back to `windows`, so adding the file to `artifacts/` and
|
||||
re-publishing is enough.
|
||||
|
||||
The incident history, failure signatures and non-negotiable implementation constraints
|
||||
behind the current Drop, conversion and macOS packaging behaviour are recorded in
|
||||
[`ENGINEERING-NOTES.md`](ENGINEERING-NOTES.md). Read the relevant section before changing
|
||||
those paths; this release guide defines the channel, while the engineering ledger explains
|
||||
why the current shape must not be simplified back into an earlier failure.
|
||||
|
||||
Keys are platform, then platform and architecture where they differ. A build picks the
|
||||
first key its own architecture matches and never crosses operating systems:
|
||||
|
||||
|
|
@ -115,6 +121,34 @@ constraint the container had to satisfy, and a DMG satisfies it.
|
|||
`pkgbuild` — is kept in the tree but is no longer part of a release: it built a container
|
||||
with no manifest key, and the DMG covers the first install anyway.
|
||||
|
||||
### macOS release gate
|
||||
|
||||
Every macOS release must pass all of these before it goes into `artifacts/`:
|
||||
|
||||
1. Rebuild the universal Swift sidecars with `pnpm mac:drag-bridge`, then build with
|
||||
`pnpm tauri build --target universal-apple-darwin --bundles app,dmg`.
|
||||
2. Run `codesign --verify --deep --strict` on `Shift.app`, and confirm
|
||||
`codesign -dv --verbose=2` reports `Signature=adhoc`. A local certificate name here is
|
||||
a release blocker, not a stronger signature.
|
||||
3. Run `hdiutil verify Shift-macOS-universal.dmg` and verify `SHA256SUMS.txt` after copying
|
||||
the final artifact into `artifacts/`.
|
||||
4. Confirm the release contains no `.pkg`, and that the manifest's `macos` entry points at
|
||||
the DMG. The in-app helper mounts that exact container with `hdiutil`.
|
||||
5. Transfer the DMG to a different Mac, preferably one that has never installed Shift.
|
||||
Download the final artifact through a browser from the release feed when possible so the
|
||||
quarantine flag matches the real user path; if a USB or AirDrop transfer is used, confirm
|
||||
the quarantine attribute is present, otherwise Gatekeeper was not exercised. Drag
|
||||
`Shift.app` to `/Applications`, approve the first launch once, and verify the version.
|
||||
6. On that same machine, open Drop and confirm another Shift peer appears and stays in the
|
||||
list. A packaging or signing change can invalidate Local Network approval even when the
|
||||
app itself starts correctly.
|
||||
7. For an update release, install the previous version on that machine and run the in-app
|
||||
update once. It must restart on the new version without a Gatekeeper prompt.
|
||||
|
||||
The build host opening its own DMG proves neither cross-machine installation nor the
|
||||
quarantine behaviour. Step 5 is the hard release gate. The full incident record and the
|
||||
manual Drop matrix are in [`ENGINEERING-NOTES.md`](ENGINEERING-NOTES.md).
|
||||
|
||||
Closing this for good means an Apple Developer ID: `Developer ID Application` +
|
||||
`notarytool` + `stapler staple`. Then the DMG opens on double-click with no pane to visit,
|
||||
and the privacy grants keyed to that identity — Screen Recording, and Local Network, which
|
||||
|
|
@ -329,13 +363,13 @@ test, which is the proof that the check is real and not a pass-through.
|
|||
|
||||
Checked against the live `releases` branch of this repository:
|
||||
|
||||
Version **0.1.6**, checked by downloading each artifact back from the raw endpoint rather
|
||||
Version **0.1.7**, checked by downloading each artifact back from the raw endpoint rather
|
||||
than trusting the local copy:
|
||||
|
||||
| Key | Artifact | Verified from the remote |
|
||||
| --- | --- | --- |
|
||||
| `macos` | `Shift-macOS-universal.dmg` (55,539,236 B) | bytes downloaded, SHA256 matches the manifest |
|
||||
| `windows` | `Shift-Setup-0.1.6-win-x64.exe` (24,494,638 B) | bytes downloaded, SHA256 matches the manifest |
|
||||
| `macos` | `Shift-macOS-universal.dmg` (55,585,331 B) | bytes downloaded, SHA256 matches the manifest |
|
||||
| `windows` | `Shift-Setup-0.1.7-win-x64.exe` (24,514,334 B) | bytes downloaded, SHA256 matches the manifest |
|
||||
| `windows-arm64` | not published | by choice — see "Supported release targets" |
|
||||
| `linux` | not published | by choice: Linux is a build target here, not a shipped product |
|
||||
|
||||
|
|
|
|||
|
|
@ -57,6 +57,15 @@ names what is still missing.
|
|||
thread to per-monitor-v2 DPI awareness so a mixed-DPI or multi-monitor desktop cannot
|
||||
shift the image out from under the overlay. PowerShell is nowhere in the capture path; it
|
||||
is used only as the HTTP client for the update download.
|
||||
- LAN Drop discovery is working again in 0.1.7: the shared discovery socket now combines
|
||||
multicast, per-interface directed broadcast, limited broadcast and a bounded `/24`
|
||||
unicast sweep; ordinary beacons receive one marked reply, and peer expiry is long enough
|
||||
for older copies to answer. The user-observed acceptance run covered one Mac and one
|
||||
Windows x64 machine after an upgrade. Unit tests cover the scan bounds, timeout and reply
|
||||
semantics, but the live two-host check is manual because this forge runs no CI and the
|
||||
repository has no second-machine fixture. Client-isolated Wi-Fi remains outside the app's
|
||||
control, and Windows still permits only one listener per machine. The exact invariants
|
||||
and manual matrix are in `docs/ENGINEERING-NOTES.md`.
|
||||
- Windows ARM64: `scripts/build-windows-release.sh` builds both architectures by
|
||||
default, checks each binary's PE machine field (`0x8664` / `0xAA64`) before packaging
|
||||
it, and gates each NSIS installer to the matching machine. The update manifest gained a
|
||||
|
|
@ -112,11 +121,13 @@ names what is still missing.
|
|||
fresh machine (drag to /Applications, one approval on first launch), so the `.pkg` that
|
||||
once accompanied it was dropped rather than kept as a second thing to maintain. The `macos`
|
||||
manifest key has to stay a DMG anyway, because the in-app handoff mounts it with `hdiutil`;
|
||||
see "macOS packaging" in `docs/RELEASE.md`. A Developer ID plus notarization removes the
|
||||
prompt entirely and would also stop Screen Recording and Local Network approval from
|
||||
resetting between builds — both are keyed to the signing identity, so an ad-hoc rebuild
|
||||
loses them, and a lost Local Network grant empties the device list with no message
|
||||
anywhere in the UI.
|
||||
see "macOS packaging" in `docs/RELEASE.md` and the packaging incident record in
|
||||
`docs/ENGINEERING-NOTES.md`. The release gate deliberately requires installation from the
|
||||
transferred DMG on a different Mac; opening the build host's own image is not evidence.
|
||||
A Developer ID plus notarization removes the prompt entirely and would also stop Screen
|
||||
Recording and Local Network approval from resetting between builds — both are keyed to the
|
||||
signing identity, so an ad-hoc rebuild loses them, and a lost Local Network grant empties
|
||||
the device list with no message anywhere in the UI.
|
||||
- Signed Windows installer: pending.
|
||||
- Manifest signing is done. `scripts/release-key.py` mints the release key,
|
||||
`publish-release.sh --key` publishes a detached `shift-update.sig` over the manifest's
|
||||
|
|
|
|||
Loading…
Reference in New Issue