883 lines
69 KiB
Markdown
883 lines
69 KiB
Markdown
# Shift 工程回归台账
|
||
|
||
本文件记录 0.1.2 到 0.1.13 之间已经踩过、并且不应再次引入的工程问题,重点覆盖:
|
||
|
||
- Drop / 局域网设备发现
|
||
- DOCX、Markdown 与图片转换
|
||
- 设置面板与「运行组件」的显示口径,以及 Windows 上的一键安装组件
|
||
- 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 发现恢复正常。 |
|
||
| 0.1.8 | 最近文件改为收藏并移除拖回主操作按钮的交互;Windows 增加单实例保护;macOS DOCX→PDF 改用 Quick Look 源,保留页眉、页脚与装订版式。 |
|
||
| 0.1.9 | 重新支持把「最近使用」拖回三个主操作按钮,并且**按钮是唯一落点**——松开在面板其他位置不执行任何操作(见「『最近使用』拖回主面板的三个按钮」);设置面板字号统一到 `--text-*` 阶梯;取消「截图后」行为选项,固定为结果卡片;修复 macOS「运行组件」把 AppKit 文档渲染器报成 Pandoc 缺失且没有安装入口的回归。 |
|
||
| 0.1.10 | 拖放反馈收束到按钮:面板自身不再做拖拽动画,松开在非按钮处彻底静默(去掉 0.1.9 的提示浮层);「文字识别」对非图片直接拒绝,不再退回格式环;托盘「识别图片文字…」改为「文字识别」。 |
|
||
| 0.1.11 | Windows 实测「最近使用」拖到三个按钮全部完不成:页内文件拖拽在 WebView2 上 DOM 与原生两条投递路径都可能不上报,改由 `dragEnd` 兜底;开始拖动时先让闲置圆环让开,它无边框且始终置顶,正压在按钮上(两节都在「『最近使用』拖回主面板的三个按钮」里)。三个按钮的可用性判定收进 `src/lib/dropCapabilities.ts`,两种语言、两条投递路径共用一条"能处理就处理,不能处理就禁止"的规则。同一节里另有两处:内部拖拽被原生 `enter` 报成"没有文件"、从而三个按钮全部点亮(`dragPathsKnown()` 改为合并),以及禁止态定为**按钮禁用+光标禁止符号**——光标原本由 wry 固定回报 Copy、页面改不动,现在由 `src-tauri/src/drop_cursor.rs` 在运行时接管那两条回报方法,把页面的判定翻译成原生拖放的拒绝(同一节也记了这条路上"被拒绝的手势没有收尾事件"这个坑)。局域网接收的文件从此也受「完成后在访达中显示」控制,一批只在最后一个落地时显示一次;「运行组件」缺失多项时可以一次装完。 |
|
||
| 0.1.13 | Windows 实测「运行组件」一键安装失败:`winget` 把“已经装过”报成非零退出码,界面就照着说安装失败(见「Windows 一键安装运行组件」)。同一节还记了 `--source` 未钉住导致的静默挂死、机器级组件必须提权、以及装完之后进程内 PATH 仍是旧值这三处。另有三处与系统资源相关的约束:托盘改用自绘的黑白模板图(`scripts/build-icons.py` 重建,应用图标同一份几何,`icon_as_template` 只在 macOS 生效);钉图窗口的放大尺寸与位置必须按 work area 与 DPI 换算后夹取,见「钉图窗口的放大与还原」;闲置时的取样节奏——伴生进程 `native/macos/drag-bridge.swift` 无按压时 10Hz、Windows 手势监视 `monitor_pause` 在圆环关闭时 250ms、发现线程静默时 1.6s——都要在“关掉了就别一直占 CPU”和“还听得见、还能过期”之间取平衡。另有两条:主面板顶部的升级提示与托盘那一行共用同一份状态,而这份状态必须落到磁盘上,否则探测一天只跑一次,用户在探测当天之后就再也看不到提示——包括升级重启后的那一次启动;落盘的提示在恢复时要重新判定它是否还算数,见「升级提示跨启动存活」。Windows 应用内更新随后实测失败:`cmd.exe /C` 从带空格的 `%TEMP%\Shift Updates` 路径上剥掉了首尾引号,辅助脚本从未启动;静默安装还会被没人能点的 WebView2 提示框永久卡住。现在脚本路径经环境变量传入并保留外层引号,静默模式不弹 WebView2 提示,安装器在 `taskkill` 后也会等进程真正释放 EXE。 |
|
||
|
||
历史提交可以这样定位:
|
||
|
||
```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 workflow 能验证协议单元测试,但没有双机网络夹具,因此发布前
|
||
仍需重复上面的手工矩阵。
|
||
|
||
## DOCX、Markdown 与图片转换
|
||
|
||
### 当前转换路径
|
||
|
||
| 输入 → 输出 | 当前实现 | 关键点 |
|
||
| --- | --- | --- |
|
||
| 纯图片 DOCX → PDF | `office::document_page_images` 按文档顺序抽取页面图片,再由 `pdf::images_to_pdf_with_progress` 生成 PDF | 保留页数和原始图片内容;这是扫描件路径,不经过 AppKit 文本排版。 |
|
||
| 普通 DOCX → PDF | 先用 `/usr/bin/qlmanage -p` 生成系统的 Quick Look `Preview.html`,再由 `native/macos/doc-render.swift` 用 WebKit 渲染并按 A4 切片 | AppKit 的 OOXML 读取器只保留正文;把 Quick Look HTML 再转成 attributed string 还会重排表格并制造空白页。`qlmanage` 有 30 秒超时,且必须确认 `Preview.html` 存在。 |
|
||
| Quick Look 不可用且含图 DOCX → PDF | 用 Pandoc `docx → html5`,通过 `--extract-media` 抽取图片到临时目录,再交给 `doc-render` | 保留图片的降级路径;Quick Look 失败或超时后才进入。 |
|
||
| Markdown → PDF | 先由 Pandoc(可用时)或内置 `markdown::to_html` 转成 HTML,再交给 WebKit 渲染器;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 | HTML 在 WebKit 测量前把超宽 `<img>` 等比缩到页面宽度;非 HTML 文档仍由 `fitAttachments` 调整 attachment bounds | 不重采样像素,只修正排版请求的尺寸,避免截图被裁成碎片。 |
|
||
|
||
### 不能随意改掉的约束
|
||
|
||
1. **普通 DOCX 不能直接交给 AppKit OOXML 读取器。** 它只保留正文,页眉页脚会消失;
|
||
含图文档还会返回只有文字、没有附件的 attributed string。必须先走 Quick Look,
|
||
失败后才允许回退。
|
||
2. **HTML 必须交给 WebKit,不能再转成 NSAttributedString。** 后者会重新排版 Quick
|
||
Look 的定位内容,把原本同页的页脚推到新页,并把 7 页内容拉成 9 页。
|
||
3. **纯图片 DOCX 的页面抽取要排在通用渲染之前。** 它决定扫描件的真实页数和页面顺序。
|
||
4. **DOCX→HTML 后必须把 `--extract-media` 的临时目录作为 HTML base directory。**
|
||
Pandoc 会把图片写成相对路径;base 指向源 DOCX 目录会找不到已抽取媒体。
|
||
5. **Markdown→PDF 的 HTML base URL 始终是源 Markdown 目录。** 即使 HTML 写在临时目录,
|
||
也不能改用临时目录。
|
||
6. **Pandoc 转 DOCX/RTF/HTML 必须保留 `--resource-path`。** 这是相对图片丢失问题的
|
||
根因修复,不应为了简化命令删掉。
|
||
7. **HTML 输出必须保留 `--self-contained`。** 否则用户拿到的是一个引用不存在媒体目录
|
||
的 HTML 文件。
|
||
8. **宽图适配在 `doc-render.swift` 中完成。** HTML 必须在测量前缩放宽图;非 HTML
|
||
文档的 AppKit `<img>` 单元格不会服从 CSS width,仍需调整 attachment bounds。
|
||
9. **无 Pandoc 时保留 macOS 的降级路径。** 带图 DOCX 会退回旧的文本渲染,而不是让
|
||
整个转换直接失败;修改时要明确产品选择,不能无意打破降级。
|
||
10. **Swift 渲染器改动后重新运行 `pnpm mac:drag-bridge`。** 只改源码不重编伴生进程,
|
||
打出的 DMG 不会包含修复。
|
||
11. **Quick Look 临时目录必须在所有成功和失败路径清理。** 输出先写到临时目录,确认
|
||
PDF 有效后再改名;不能把半成品留在用户的输出目录。
|
||
|
||
### 回归测试
|
||
|
||
自动测试集中在 `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`
|
||
- `keeps_docx_headers_and_footers_when_converting_to_pdf`
|
||
- `image_bearing_docx_to_html_embeds_images`
|
||
- `keeps_markdown_images_when_converting_to_word`
|
||
|
||
## 升级后的单实例
|
||
|
||
Windows 安装器重启应用时可能留下旧进程,再启动新进程就会有两个托盘实例和两套窗口。
|
||
`tauri-plugin-single-instance` 必须在 `tauri::Builder` 中**最先注册**:第二个进程在
|
||
其余插件和窗口初始化前就把参数交给第一实例并退出,第一实例收到回调后显示主窗口。
|
||
|
||
macOS 的 `hotkeys::acquire_instance` 文件锁仍保留为热键所有权的额外保护,不能因为加入
|
||
单实例插件而删除;但它不是 Windows 的解决方案,非 Unix 分支本身不会持有跨进程锁。
|
||
|
||
其中 `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` 已从仓库删除,任何 `.pkg` 都不能进入
|
||
正式发布目录或更新清单。
|
||
|
||
当前签名配置是:
|
||
|
||
```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` 结果;跨机器安装行为和系统提示类型才是有效证据。
|
||
|
||
## 截图、录制与圆环的键盘焦点
|
||
|
||
### 症状与真实原因
|
||
|
||
区域截图、区域录制时按 `ESC` 无法取消,拖动文件后出现的圆环按 `ESC` 也无反应。前端确实
|
||
监听了 `keydown`,但事件根本没有到达页面。
|
||
|
||
在运行中的 Shift 上用 `lldb` 取证可以看到:
|
||
|
||
```text
|
||
keyWindow = <TaoWindow "Shift Capture"> isKeyWindow = YES
|
||
firstResponder = <TaoView> ← 页面在 contentView 的 subview 里,不在这里
|
||
contentView = <TaoView> subviews = [<WryWebView>]
|
||
```
|
||
|
||
窗口是 key window,但 AppKit 的键盘事件投递给的是窗口的 first responder,而 first
|
||
responder 停在 tao 自己的 `TaoView` 上,所以页面收不到任何按键。链路上有两个成因:
|
||
|
||
- `WebviewWindow::set_focus()` 只做 `makeKeyAndOrderFront` 加激活应用
|
||
(tao `platform_impl/macos/window.rs` 的 `set_focus`),不会动 first responder。
|
||
- wry 在创建 webview 时调用过一次 `makeFirstResponder(webview)`,但之后每次
|
||
`set_simple_fullscreen` 都会经 `toggle_style_mask` 再调
|
||
`makeFirstResponder(ns_view)`(tao `util/mod.rs`)把它抢回去;窗口重新显示同样会丢。
|
||
|
||
因此**只要窗口被显示过一次,就必须再显式把键盘交给页面**。等价验证:在真实进程里执行
|
||
`makeFirstResponder(WryWebView)` 之后,同一个 `ESC` 立刻被页面收到。
|
||
|
||
### 不能随意改掉的约束
|
||
|
||
| 约束 | 原因 |
|
||
| --- | --- |
|
||
| 显示 overlay / 圆环后必须调用 `crate::focus_page` | 只有 `Webview::set_focus`(`makeFirstResponder`)能让页面收到 `ESC`/`Enter`;`WebviewWindow::set_focus` 不够。 |
|
||
| 采集前记住哪些 Shift 窗口是可见的,结束时按名单恢复 | 之前无条件 `show` 主窗口:面板开着会被截图吃掉,面板本来关着又会被凭空打开。 |
|
||
| 录制期间不能恢复面板,`recording::stop` 才恢复 | 恢复出来的窗口会出现在被录制的区域里。 |
|
||
| `restore_windows` 用 recorder HUD 判断是否在录制,不能去锁 `state.recording` | `recording::stop` 全程持有该 Mutex,从这条路再锁一次会自死锁。 |
|
||
| 已有 overlay 或正在录制时,新一轮采集不得覆盖待恢复名单 | 否则后一次(面板不可见)会把“面板开着”的记录擦掉。 |
|
||
|
||
### 回归测试
|
||
|
||
`src-tauri/src/lib.rs` 中的源码断言守住调用点:
|
||
|
||
```bash
|
||
cd src-tauri
|
||
cargo test --lib capture
|
||
```
|
||
|
||
键盘投递本身只能实测,最小矩阵(每步都要看窗口是否真的消失/回来):
|
||
|
||
1. 面板开着 → `Alt+Shift+2` → 直接按 `ESC` → overlay 消失且面板回来。
|
||
2. 面板开着 → `Alt+Shift+3` → 直接按 `ESC` → 同上。
|
||
3. 面板关着 → `Alt+Shift+2` → `ESC` → 不要凭空出现面板。
|
||
4. 面板开着 → 选区录制 → 录制中面板保持隐藏 → 停止后面板回来,`.mov` 有效。
|
||
5. 录制中再截一张图 → `ESC` 只关 overlay,录制与 HUD 不受影响。
|
||
6. 圆环(拖文件到面板,或「文件转换」选文件后)→ `ESC` 收起圆环。
|
||
7. `Enter` 仍能确认选区并保存截图。
|
||
|
||
## 「运行组件」的显示口径
|
||
|
||
### 0.1.9 的 macOS 回归
|
||
|
||
macOS 的设置 → 运行组件里,文档转 PDF 那一行显示 **“Pandoc PDF pipeline / 缺失”**,
|
||
而且**没有安装按钮**。两件事都是同一个错误造成的。
|
||
|
||
`document_pdf_component()` 原本在 `if let Some(renderer) = files::doc_render_bridge()`
|
||
里 `return` 掉内置的 AppKit 渲染器;`df35111`(准备 0.1.8)把 `return` 改成了裸表达式,
|
||
于是构造出的组件被丢弃、继续往下走到 Pandoc 分支。后果是:
|
||
|
||
- 名字变成 `Pandoc PDF pipeline`,可用条件变成 `pandoc.is_some() && pdf_engine.is_some()`;
|
||
macOS 这条链路根本不需要 LaTeX/Typst 引擎(pandoc 只负责把带图 DOCX 转成 HTML 交给
|
||
渲染器),所以只要机器上没装 xelatex/typst 之类就永远显示缺失。
|
||
- 面板对 `external` 且缺失的行只给安装按钮,而 `install_target("document-pdf")` 在
|
||
macOS 没有条目(只有 `pandoc`、`media`),于是既报缺失又无处可装。
|
||
|
||
**修法不是补一个安装入口,而是恢复「macOS 由内置渲染器作答」这件事。** 现在两个平台各自
|
||
拥有独立的 `document_pdf_component()`(`#[cfg(target_os = "macos")]` /
|
||
`#[cfg(not(target_os = "macos"))]`),与同文件里 `pdf_page_component`、
|
||
`image_backend_component` 的写法一致:在 macOS 上想再次落到 Pandoc 分支会变成编译错误,
|
||
而不再是一次静默的行为回归。
|
||
|
||
### 不能随意改掉的约束
|
||
|
||
| 约束 | 原因 |
|
||
| --- | --- |
|
||
| macOS 的 `document-pdf` 必须是 `source = "bundled"` 且以 `doc_render_bridge()` 为准 | 这条转换在 macOS 上就是 Quick Look / AppKit 渲染器;改成 external 会重新引入"缺失但装不了"。 |
|
||
| 带图 DOCX 仍需要 Pandoc,但那是 `pandoc` 那一行的职责 | `pandoc` 行有自己的安装目标(`brew install pandoc`);不要把依赖合并进 `document-pdf`。 |
|
||
| `external` + 缺失的行必须有安装目标 | 否则面板等于告诉用户坏了、却不给出口,就是本次回归的表现。 |
|
||
|
||
### 回归测试
|
||
|
||
`src-tauri/src/runtime.rs` 的 `tests` 模块:
|
||
|
||
```bash
|
||
cd src-tauri
|
||
cargo test --lib runtime
|
||
```
|
||
|
||
- `macos_document_pdf_is_the_bundled_renderer_not_a_pandoc_pipeline`:钉住 macOS 的
|
||
`source` 与 `name`。
|
||
- `a_missing_component_always_offers_a_way_forward`:任何标记为缺失的行都必须要么可安装、
|
||
要么本来就不是 external。
|
||
|
||
## 「运行组件」可以一次装多个缺失项
|
||
|
||
面板原先一次只能装一个组件:`runtimeInstalling` 是一个 `string | null`,`install` 命令
|
||
只接受一个 `component_id`,任何一个按钮在忙时就把整片按钮全部禁用。缺失 Pandoc 与 FFmpeg
|
||
时用户要点两次、等两轮重新检测。
|
||
|
||
现在前端把缺失且可安装的组件收成一个列表,标题栏在**缺失不止一项**时给出「一键安装
|
||
N 个组件」,行内的单个安装按钮保持原样,两种入口调用同一个 `install_runtime_components`。
|
||
|
||
| 约束 | 原因 |
|
||
| --- | --- |
|
||
| 后端逐个串行安装,不能并发 | `brew` 与 `winget` 同一时刻只允许一个安装,并发只会互相锁住并报错。 |
|
||
| 同一个 `package_id` 只装一次 | Windows 上 `pdf-render` 与 `pdf-to-word` 都指向 Poppler,按行安装会重复下载同一个包。 |
|
||
| 只有“包管理器本身坏了”才中止整批 | 没装 brew / winget、没有源、网络不通、winget 不回应:剩下的行只会把同一个错误重复 N 遍、各等一次超时。但**单个包**的失败(用户关掉 UAC、某一个安装程序自己拒绝)必须继续往下装,否则「一键安装 N 个组件」会因为一个组件被拒绝而放弃其余四个。判定收在 `ends_the_batch()`,有测试钉住。 |
|
||
| 无论成功失败都 `refreshRuntime()` | 中止的批次里先前的安装可能已经落盘,面板必须重新检测才能显示真实状态,不能相信这一个回复。 |
|
||
| 安装结果的名字由界面措辞 | `install_runtime_components` 返回 `()`:按既有约定,后端只报代号,`runtimeInstallComplete` / `runtimeInstallManyComplete` 两种数量由界面选择。 |
|
||
|
||
## Windows 一键安装运行组件
|
||
|
||
### 0.1.13 之前实测必然失败
|
||
|
||
用户在 Windows 机器上点「一键安装组件」报失败。原先的实现是一条
|
||
`winget install --id X --exact --silent --accept-package-agreements --accept-source-agreements`,
|
||
非零就报错,然后用 `resolve_tool()` 验证二进制在不在。四个独立原因都藏在这十行里:
|
||
|
||
1. **`winget` 把"已经装过"报成非零退出码。** `0x8A15002B`(PACKAGE_ALREADY_INSTALLED)与
|
||
`0x8A150016`(没有可升级版本)都是成功语义,但 `ExitStatus::success()` 一律当真失败。
|
||
机器上已经有 Pandoc 的用户,越"没问题"越必然看到"安装失败"。
|
||
2. **不钉 `--source`。** 同时挂了 msstore 源的机器上,未钉源的 `winget` 可能停在一条
|
||
`--silent` 永远不会回答的源协议上;表现就是"卡住不动",最后由 15 分钟超时收成失败。
|
||
3. **机器级组件必然要提权。** Poppler / FFmpeg / ImageMagick / Typst 默认装到
|
||
Program Files,需要管理员;Shift 自身是免管理员的 GUI 进程,`--silent` 拿不到 UAC 就
|
||
直接失败。原先没有任何提权路径。
|
||
4. **装完之后再验证也找不到。** 进程只持有启动时的环境块:`winget` 写进注册表的
|
||
`%LOCALAPPDATA%\Microsoft\WinGet\Links` 不会回流到运行中的 Shift,`which` 于是仍按旧
|
||
PATH 回答,`winget-install-missing-binary` 把一次真正成功的安装报成失败。
|
||
|
||
### 不能随意改掉的约束
|
||
|
||
| 约束 | 原因 |
|
||
| --- | --- |
|
||
| 退出码先判,代码表认不出来时才看 `winget` 的措辞 | 退出码是精确信号;措辞只用来分家两件码里分不开的事(用户关掉了 UAC、源没有接受协议)。反过来让措辞压过码,一句无用的日志就能把成功改成重试。 |
|
||
| 只按完整码匹配,不按低 16 位 | Win32 的 `0x8007_xxxx` 与 WinGet 的 `0x8A15_xxxx` 会撞低 16 位;只看尾巴会把普通的访问被拒读成"需要提权"。 |
|
||
| 每条命令都带 `--source winget` | 去掉它就会在挂了 msstore 的机器上静默挂死到超时——而那看起来就是"安装失败"。 |
|
||
| 阶梯:不指定 scope → `--scope user` → 提权 `--scope machine` | 第一档就是历来发出去的那条命令,默认装到用户目录的包行为完全不变;`--scope user` 是"不弹 UAC 也能装机器级包"的出口,且 WinGet 在选安装器阶段就会拒绝不支持的 scope,所以这一档只花一次握手而不是整包下载;UAC 是最后一招,因为一个本该是开关的操作弹出授权框,正是"看起来坏了"的来源。 |
|
||
| 提权走 `powershell Start-Process -Verb RunAs -Wait -PassThru` | 无控制台的 GUI 进程自己弹不出 UAC;提权后的 `winget` 写在自己的控制台里,但**宿主** shell 的输出仍在我们手上,而"用户取消"只在这里以文字出现(1223 只是旁证)。 |
|
||
| 成功与否最终由磁盘上有没有那个可执行文件决定 | 装完先 `refresh_process_path()` + `reset_tool_cache()` 再找。`RegGetValueW` 不加 `RRF_NOEXPAND`,注册表里的 `REG_EXPAND_SZ` 会像系统构造进程环境那样展开。找不到才说"没装上",并且说成"重启 Shift 后重新检测",而不是"安装失败"。 |
|
||
| 单个包失败不许放弃整批 | 见上一节;判定在 `ends_the_batch()`。 |
|
||
|
||
`src-tauri/src/process.rs` 里 `output_hidden_with_timeout()` 是这套逻辑唯一的输出通道:
|
||
它同时保留 `CREATE_NO_WINDOW`(GUI 进程不闪控制台)与持续排空管道(否则子进程写满管道会
|
||
一直堵到超时)。超时消息统一含 `TIMEOUT_MARKER`,调用方据此区分"没回答"与"回答不要"。
|
||
|
||
### 回归测试
|
||
|
||
```bash
|
||
cd src-tauri
|
||
cargo test --lib runtime
|
||
```
|
||
|
||
- `an_already_installed_package_is_not_a_failure`:钉住原因 1,也就是这次实测失败的主因。
|
||
- `exit_codes_are_separated_by_who_can_fix_them`:谁能修就分给谁,并钉住低 16 位撞车。
|
||
- `every_winget_attempt_pins_the_community_source`:三档命令都必须带 `--source winget`。
|
||
- `the_ladder_escalates_scope_only_when_it_must`:未提权的两档都不许要求 machine scope。
|
||
- `the_installer_own_words_break_a_tie` / `a_closed_prompt_reads_as_a_refusal`:措辞只在码
|
||
认不出来时生效,且"网络断了"不能被读成"用户说了不要"。
|
||
- `only_a_broken_package_manager_ends_the_batch`:整批中止的判定。
|
||
|
||
## 钉图窗口的放大与还原
|
||
|
||
钉图窗口原先只有「复制」和「关闭」,用户要的「放大」按钮并不存在——不是坏了,是没有。
|
||
现在一颗按钮管两个方向:放大到屏幕,或退回钉住时的大小。
|
||
|
||
| 约束 | 原因 |
|
||
| --- | --- |
|
||
| 尺寸按 work area,不按整块屏幕 | `monitor.size()` 含菜单栏与 Dock。按整屏算出来的钉图会有一部分永远压在菜单栏底下,而无边框窗口拖不回自己身上。 |
|
||
| 逻辑像素给 `set_size`,物理像素给 `set_position` | 两者单位不同。混用后在 2x 屏上放大就是两倍大、位置偏一半——这台机器上验得出来,在 1x 外接屏上看不出来,所以由 `PinArea::logical_size()` 显式换算并命名。 |
|
||
| 先 `set_size` 再 `set_position` | 混合 DPI 的桌面上,改尺寸可能把窗口挪到另一块屏,此时窗口自己的 scale factor 已经变了;顺序反过来位置就按旧的 scale 算。 |
|
||
| 放大幅度封顶 3 倍 | 预览最长边本来就是 1040 px(`PIN_PREVIEW_EDGE`)。再往上只是把锯齿摊开,用户看到的是糊成一片的马赛克,不是更大的字。 |
|
||
| 放大以窗口中心为锚点,并夹在 work area 内 | 以左上角为锚点读起来像"窗口被搬走了";不夹取的话,贴着屏幕右缘钉住的图一放大就整张跑到屏幕外。 |
|
||
| 每次重新钉都回到小图 | 窗口是复用而不是重建(`PIN_ENLARGED` 是唯一的记录)。否则上一次放到最大的用户,接下来每一张钉图都糊满全屏。 |
|
||
| 读不到显示器就答小图,不猜 | `pin_window_size(.., None, true)` 走的是小图那一支。按一块幻影屏幕算出来的尺寸,是把图放到用户够不着的地方。 |
|
||
|
||
按钮的文案(放大 / 恢复原大小)跟的是页面自己那份 `enlarged`,而真实尺寸只有 Rust 知道;
|
||
`zoom_pin` 把翻转后的状态返回给页面,两边才不会各说各话。
|
||
|
||
### 回归测试
|
||
|
||
```bash
|
||
cd src-tauri && cargo test --lib editor
|
||
```
|
||
|
||
`a_fresh_pin_never_exceeds_its_own_picture_or_520_px`、`enlarging_fills_the_screen_but_stays_inside_it`、
|
||
`a_small_picture_is_not_blown_up_to_the_ceiling`、`an_enlarged_pin_grows_from_its_centre`、
|
||
`a_pin_against_a_screen_edge_grows_inward_not_off_screen`。后两条钉的是"从中心放大"和
|
||
"贴边时向内长",因为它们在 1x 的单屏开发机上看起来永远是对的。
|
||
|
||
## 闲置时的取样节奏
|
||
|
||
Shift 绝大部分时间是停在菜单栏里没人碰的。这一节的每条节奏都是从实测里挑出来的,
|
||
目的是把"关掉了就别一直占 CPU"和"还听得见、还能过期"同时满足。
|
||
|
||
### 实测的 A/B
|
||
|
||
在装有 0.1.11 的机器上,两个版本各自空转 60 秒,按进程分别读 `ps -o time=`:
|
||
|
||
| 进程(60 秒空转) | 0.1.11 | 0.1.13 | 变化 |
|
||
| --- | --- | --- | --- |
|
||
| `drag-bridge` 伴生进程 | 140 ms | 40 ms | **−71%** |
|
||
| `shift` 主进程 | 100 ms | 60 ms | −40% |
|
||
| 合计 | 240 ms | 100 ms | **−58%** |
|
||
|
||
只有伴生进程那一行可以直接归因:它没有窗口,所以不受"主窗口有没有开着"影响,
|
||
而其余三处改动都发生在那两个数字里。主进程那一行不能当成"发现线程省了 40%"来读——
|
||
同一个构建重复测量的摆动就有 ±40ms,和差值同量级。发布前若要再引用一次,
|
||
请重新测,不要抄这张表。
|
||
|
||
|
||
| 位置 | 节奏 | 原因 |
|
||
| --- | --- | --- |
|
||
| `native/macos/drag-bridge.swift` | 无按压 10Hz,按住切 30Hz | 伴生进程是**另一个被跟踪的进程**,原先永远 30Hz,而且每跳都分配一个 CGEvent 去读一个没人要的鼠标位置。它是这一节里唯一能被干净归因的改动:伴生进程没有窗口,所以它的 CPU 与「主窗口是否开着」无关。`NSTimer` 不能改自己的间隔,所以是换掉计时器而不是调它。 |
|
||
| `src-tauri/src/drag_bridge.rs` `monitor_pause`(Windows) | 圆环开着 33ms,关了 250ms | 圆环开着时必须 33ms:这条循环要靠观察到"按下"才能从按下点量起拖拽阈值,放慢不是"晚一点发现",而是**根本记不住按下**,于是快速拖动的用户从此开不了环。只有关掉圆环时才敢放慢,那时要等的只有开关本身。 |
|
||
| `src-tauri/src/share.rs` 发现线程 | 信标 2s / 扫段 30s 不动;静默时收包等待 400ms→1.6s,无 peer 时账目检查 600ms→2.4s | **关掉 ShiftDrop 不等于变聋**:字段注释写的是"不主动播报",`recv_from` 从来不受 `enabled` 约束,所以一台关掉的机器仍然听得见、仍然能被别人选来发送;`expire()` 也必须继续跑,否则一小时前的 peer 会永远挂在列表里冒充在线。所以省的是唤醒次数,不是探测能力。播报与扫段的频率一点没动,peer 被发现的速度因此不变。 |
|
||
| `src/components/MainWindow.tsx` 30 秒时钟 | 页面可见才跑 | 主窗口一生大部分时间是隐藏的;隐藏的页面里每 30 秒重绘一次没人看的列表,正是 nex_squid `useSystemSnapshot` 用 `visibilitychange` 停掉的那类开销。空列表连 `setNowTick` 都省了——重新计时的是不存在的行。 |
|
||
| 最近列表缩略图 | `IntersectionObserver` 只保留在视线内的图片 | `loading="lazy"` 只**推迟**解码,从不**释放**。在 WKWebView 里用 250 张真实截图量过:静止时 13 张解码,滚到底单调涨到 136 张再也不降;观察者接管后同样的滚动稳定在约 20 张。root 必须是列表本身而不是视口——行的裁剪来自列表的 `overflow-y`。 |
|
||
|
||
托盘图标也在这一节,因为它省的是同一个东西:`src-tauri/icons/tray-template.png` 是
|
||
`scripts/build-icons.py` 画的纯 alpha 黑白标记(中性灰只在 Windows 上当底色用,
|
||
macOS 完全忽略颜色),`icon_as_template(cfg!(target_os = "macos"))` 只在 macOS 生效——
|
||
Windows 没有可以请求的着色。**别把它换回 `app.default_window_icon()`**:那是彩色转盘,
|
||
`tray-icon` 会把它按 18pt 高等比缩放,在菜单栏里就是一团色块,这正是"系统图标该是
|
||
黑白"这条反馈的来由。
|
||
|
||
## 升级提示跨启动存活
|
||
|
||
主面板顶部要显示升级信息,点一下跳到「设置 → 软件更新」。界面这一半很直接:
|
||
`useUpdateFlow` 在 MainWindow 里再挂一份,它只**读** Rust 记着的状态并订阅
|
||
`update://status`,不会自己发探测请求,所以两处视图不会各自查网络,也不会给出
|
||
对方已经做完的动作。
|
||
|
||
难的是另一半:探测**一天只允许跑一次**(`update_check_due` 看 `last_update_check_day`),
|
||
而原先 `UpdateState` 是纯内存的。两者一叠,"发现新版本"只会在真正跑探测的那一天出现,
|
||
之后就再也见不到——**尤其是升级装完、应用重启的那一次启动**,恰恰是用户最该看到的时候。
|
||
实测就是这么撞上的:第一次启动看不到横幅,把时间戳改老才出现。
|
||
|
||
| 约束 | 原因 |
|
||
| --- | --- |
|
||
| 提示要落盘,存在 `app_data_dir/update-notice.json` | 和 `history.json` 同一目录、同样在安装包之外,因此升级和重装都还在。只有 `available`/`ready` 值得留;其他结果一律**删掉**文件,于是一次失败的检查不会把旧结论留在面板上冒充新闻。 |
|
||
| 恢复时重新判定它还算不算数 | 版本已经不领先就整条丢掉——用户已经装上那个版本了,留着就是横幅 forever 地推荐他正在跑的版本;这也是清理的唯一时机,`revive_notice` 返回 `None` 时顺手删文件。 |
|
||
| `ready` 只有在安装包文件真在磁盘上才保留 | "已下载并校验"承诺的是临时目录里的一个文件,系统完全可以在 Shift 关着的时候清掉它。文件没了就降级成 `available`:这句话仍然为真,只是要重新下载一次。 |
|
||
| 恢复发生在 `setup_tray` **之前** | 托盘那一行(`update::tray_title`)读的是同一份状态。放在后面,横幅回来了而托盘行没有,两个入口自相矛盾。 |
|
||
| 关掉"每天检查更新"就不恢复 | 这个开关的语义是"别告诉我"。留着提示等于用磁盘缓存绕过用户刚刚做的决定。 |
|
||
| 用户点"忽略"要连磁盘那份一起删 | 否则"忽略"只有效到下次启动,横幅天天回来。 |
|
||
|
||
### 回归测试
|
||
|
||
```bash
|
||
cd src-tauri && cargo test --lib update::
|
||
```
|
||
|
||
`a_notice_for_a_release_still_ahead_survives_the_launch`(并且钉住恢复出来的
|
||
`current_version` 必须是**现在**在跑的版本,不是当初问的那个)、
|
||
`an_installed_release_stops_being_announced`、
|
||
`a_ready_notice_without_its_installer_downgrades_rather_than_lying`。
|
||
|
||
## 所有图标共用一份几何
|
||
|
||
同一句反馈的后半段是"应用图标要和当前的单色图标保持一致设计"。这句话的重点在**设计**,
|
||
不在**单色**:托盘那张必须是黑白的,因为它由系统着色;应用图标该是彩色的,因为 Dock
|
||
瓦片背后没有任何东西给它着色。真正让两张图标成为同一个作品的,是几何和填充规则,不是
|
||
颜色。
|
||
|
||
第一次改错了方向:为了“和单色标记一致”,把应用图标做成**深咖啡底 + 暖色图**,
|
||
等于把橙底白图整个翻转。深浅两种桌面都验过、对比度也算过,所以不是没检查,而是检查错了
|
||
对象——一致性有两条轴(几何 / 明暗关系),当时只对齐了几何那条,而用户认得的是“橙色底”。
|
||
所以两者由 `scripts/build-icons.py` 里的同一组常数画出来
|
||
(`OUTER`/`INNER`/`HUB`/`GAP`/`PLUS_ARM`/`PLUS_BAR`),只有背后允许出现的东西不同。
|
||
|
||
| 约束 | 原因 |
|
||
| --- | --- |
|
||
| 一致性来自几何与**平涂**,不来自配色 | 六块扇形、同样的扇区间隙角、同样的内外环与 hub 半径、加号同样是从 hub 里**挖**出来的负空间,以及同样一律平涂。旧图标之所以像另一个产品,不是因为它有颜色,而是因为它是一整块橙紫渐变底 + 径向高光 + 投影 + 六块扇形各配一种奶油色——那是另一套视觉语言。 |
|
||
| **橙底白图**,只有两色,且不得出现渐变/高光/投影/逐扇形配色 | 这条就是反馈最初的原话:“我之前是橙底、白线的风格”。底色 `#FF6B35` 取自本项目自己的母版,图色 `#FFF4EA` 取自界面的面板奶油色;加号是挖出来的洞、透出底色,而不是第三色。这样应用图标与托盘标记是**同一张图**,只是各自换了底色。 |
|
||
| 环形几何只在 `scripts/build-icons.py` 定义一次 | 托盘那张 PNG 是用它逐字节重绘出来的(改完脚本跑一遍,产物与仓库里的文件 `cmp` 相同)。几何分两处写就会漂移,而漂移只在 16px 下看得出来。 |
|
||
| SVG 母版里的瓦片是**内缩**的(820/1024) | `tauri icon` 只会等比缩放母版,**不会**加边距。母版画成满幅,产出的 `icon.png` 就是满幅方块,而仓库里原有的整组图标是 410/512=0.801 的圆角瓦片。 |
|
||
| 轮盘直径取瓦片的 0.795 | 被替换的那版母版是 r=326 画在 820 的瓦片里(0.795)。照抄这个比例,新图标在 Dock 里的视觉重量和旧的一致,不会突然变大。 |
|
||
| 加号用瓦片的颜色画,不真的打穿成透明 | 在 Dock 上两种做法看起来完全一样;但 `tauri icon` 合成 iOS/Android 图层时,真的洞会被平台背景填掉。 |
|
||
| 用 `--tauri` 重生成整组,而不是手搓 | 实测 `tauri icon` 产出的 `icon.icns` 条目(ic07…ic14 + is32/il32/s8mk/l8mk)与 `icon.ico` 尺寸梯(16/24/32/48/64/256)跟仓库里已有的**完全一致**,且它不会碰 `tray-template.png`。 |
|
||
|
||
验收看 16px:16px 时轮盘只有约 10px,六条扇区间隙约 0.46px、加号约 0.38px,都已经是
|
||
亚像素——被替换的那版在 16px 的加号也只有 0.72px,所以这不是退步,而是这套几何在小尺寸
|
||
下的固有结果。真正必须在 16px 还读得出来的是**外环的扇形分割**和瓦片轮廓,深浅两种桌面
|
||
下都验过。换成两色之后,不存在“某个颜色要到某个尺寸才出现”的问题了。
|
||
|
||
`public/shift-icon.png` 是 `icon.png` 的副本,不是另一张图:它在主窗口与编辑器标题栏里以
|
||
26 CSS px 显示(Retina 上 52 设备 px),那个尺寸下渐变版的中心已经糊成一团,而平涂版的
|
||
扇形分割和 hub 还分得开。
|
||
|
||
## 「最近使用」拖回主面板的三个按钮
|
||
|
||
0.1.8 曾经把这条交互关掉:一行拖出去是文件,拖回来却什么都不是,用户只能重新选一次文件。
|
||
现在拖到「文件转换 / 文件工具 / 文字识别」上就执行该按钮的动作。
|
||
|
||
**按钮是唯一的落点,也是唯一会响应拖放的东西。** 这条规则分两步收紧:
|
||
|
||
- 0.1.9 去掉了"落在面板空白处就打开操作环"的兜底,改成不执行操作、弹一条提示。
|
||
- 0.1.10 连提示也去掉:既然不执行任何操作,解释"为什么没执行"的浮层只是在用户没有松手的位置
|
||
制造动静,落在面板其他位置现在是彻底静默。
|
||
|
||
「文字识别」的拒绝方式在同一步收紧里改成了**事前可见**:0.1.10 用提示说明"这个格式识别不了",
|
||
但那仍是让用户先做错、再由浮层告知。现在拖拽一开始就按携带的文件判定,识别不了的按钮直接进入
|
||
不可用态,松手时什么都不发生,也不再有任何提示。
|
||
|
||
**不可用态写成"禁用 + 光标禁止符号",不额外画一层符号。** 拒绝要落在光标上:鼠标底下那个
|
||
复制角标本来就是 AppKit 对"这个落点要不要这个文件"的回答,能服务就画 +,不能服务就画禁止,
|
||
用户不需要先学会读按钮的配色。0.1.11 中途曾把拒绝画成按钮上层的禁止符号,理由是**页内拖拽改得动
|
||
`dropEffect`,外部文件却改不动光标**:外部文件走原生拖放通道,而 **macOS 下 wry 的
|
||
`draggingEntered:` / `draggingUpdated:` 固定回报 `NSDragOperation::Copy`**
|
||
(`wry/src/wkwebview/drag_drop.rs`,它甚至会把 super 返回的 `None` 改写成 `Copy`)。
|
||
现在的结论是:这条路能接管,于是拒绝交还给光标,按钮只保留 `disabled` 与配色弱化,不再叠一层符号。
|
||
|
||
**`src-tauri/src/drop_cursor.rs` 只改"回答",不改"投递"。** 页面是唯一知道"拖的是什么、
|
||
指针停在哪个按钮上"的东西,所以它把判定用 `set_drop_refusal` 命令交下来;原生侧在运行时替换 wry
|
||
那个私有类的两条回报方法(类名由 `wry::wkwebview::class::wry_web_view::WryWebView` 前缀扫描得到,
|
||
因为真名带 crate 版本,写死会在升级时静默失效),拒绝时把 `Copy` 收窄成 `NSDragOperationNone`。
|
||
**两次都必须先调用 wry 自己的实现再改它的返回值**:那次调用正是 `over` / `dragover` 的投递入口,
|
||
拒绝分支若直接 `return`,页面就再也收不到指针移动,一次拒绝会粘到整次手势结束——从不能服务的按钮
|
||
拖到能服务的按钮也不会亮。Windows 不需要这套:OLE 每次移动都会来问本进程,回报跟随页面设的
|
||
`dropEffect`,光标本来就会是禁止。
|
||
|
||
**被拒绝的手势没有收尾事件,所以盯鼠标松开。** 落点回报 `None` 时 AppKit 既不发
|
||
`performDragOperation:` 也不发 `draggingExited:`,按钮会一直停在禁用态、面板看起来卡住了。
|
||
`drop_cursor.rs` 因此在拒绝生效期间起一个线程轮询 `CGEventSourceButtonState`,松手时向主窗口
|
||
发 `drop://cancelled`,页面用它收起 `dragging` / `dropAction` / `dragPaths`。
|
||
|
||
**每次手势只报一次判定,起点必须是"欢迎"。** `draggingEntered:` 会把判定复位成不拒绝——文件还
|
||
没认全就拒绝会废掉一次本来能用的拖拽。而页面是在 `enter` 之后才回答的,所以 `useEffect` 的依赖里
|
||
必须带上一个"第几次拖拽"的计数器(`dragSession`),否则状态没变化的第二次拖拽不会重新上报,
|
||
上一次留下的判定会一直生效。
|
||
|
||
**按钮变暗用自身配色,不用全应用的 `opacity: var(--dimmed)`。** 不用 `opacity` 最早是为了
|
||
保住画在按钮之上的禁止符号——符号不能跟着被调淡。符号换成光标之后这条理由已经不在了,配色
|
||
没有再动:整颗按钮调淡会和"还在加载"混在一起,而改用 `color` / `background` 弱化读起来就是
|
||
"这颗关掉了"。留着它也省下一次已经验收过的观感改动。
|
||
|
||
**`is-drop-unavailable` 必须 `pointer-events: none`。** 落点由坐标命中(`actionAtPoint`)而不是
|
||
由"哪个元素回答了事件"决定;禁用按钮若仍占住命中区,`disabled` 后的按钮不再回应拖拽事件,
|
||
手势会停在最后一个应答过的按钮上。把它让开,命中判定与视觉状态才可能一致,顺带让 hover 反馈
|
||
彻底无从发生。
|
||
|
||
`dragPaths` 是判定唯一依据:原生路径在 `enter` 拿到 `paths`,内部路径在 `dragstart` 写入这一行
|
||
——`over` 事件不带路径,`dataTransfer` 在 `dragover` 里也读不到,所以两条路都必须在开始时登记。
|
||
|
||
### 内部拖拽会被原生 `enter` 报成"没有文件"
|
||
|
||
0.1.11 实测最隐蔽的一个 bug:把「最近使用」的一行拖到按钮上,**三个按钮全部点亮为可处理**,
|
||
松手却什么都不做——正是用户描述的"反馈为可处理文件,但又不给出操作"。原因是 macOS 上一次内部
|
||
拖拽会被**两条通道同时上报**,而原生 `enter` 的载荷里没有文件名:wry 的 `collect_paths` 只读
|
||
`NSFilenamesPboardType`,页内拖拽携带的是 `text/uri-list`,于是回报 `paths: []`。这个空数组把
|
||
`dragstart` 已经登记的 `[行路径]` 覆盖掉,而 `actionCanServe` 按既定规则必须把"文件未知"当作
|
||
不禁止,三个按钮就全成了候选落点。
|
||
|
||
修法是合并而不是覆盖:`dragPathsKnown(known, reported)`(`src/lib/dropCapabilities.ts`)——
|
||
报告非空时以报告为准,报告为空时保留已知的那一份。**不能反过来"信任最新一条"**:两条通道谁先到
|
||
因平台与 WebView 版本而异,覆盖语义必然在其中一种顺序下失效。也**不能把空数组直接判成"全禁用"**:
|
||
那是 0.1.10 之前 Windows 拖拽整片灰掉的成因(见下条 `actionCanServe`)。
|
||
|
||
外部拖入和内部拖拽始终遵循同一条规则,`dropFiles` 因此接受 `DropAction | null`,`null` 直接
|
||
原样返回——它不是"未知动作",而是"没有动作",两条投递路径共用这一个判断。
|
||
|
||
同理,拖拽反馈只加在按钮上:进行中三个按钮同时点亮为候选落点(原生拖拽用 `dragging`,内部
|
||
拖拽用 `rowDragging`),而 `.home-drop` 面板本身不再缩放、变色或换描边——`is-dragging` 类、
|
||
对应的两条 CSS 规则、以及随之失效的 `transition` 都已删除,标题也不再改文案。从外部拖入和从
|
||
列表拖起现在是同一种观感,之前只有外部拖入会让整块面板动起来。实现上有一条约束容易在重构时
|
||
丢掉:
|
||
|
||
**一次内部拖拽可能被报告两次。** 历史行使用 `dragOutPayload`,也就是 `text/uri-list` 里的
|
||
`file://` 加纯文本路径,因此它对外就是一个文件拖拽。同一次手势有两种投递路径:
|
||
|
||
- DOM:`onDragOver` / `onDrop`(挂在 `.home` 根节点,用 `clientX/clientY` 命中按钮);
|
||
- 原生:`getCurrentWebview().onDragDropEvent` 的 `drop`(坐标要先经 `toWindowPoint` 换算)。
|
||
|
||
哪个先、是否都会到,取决于 WebView 版本与平台,所以两条路都必须武装,再由
|
||
`recentDrag.current = { path, landed }` 的 `landed` 标记只放行第一个。去掉这个标记,
|
||
圆环会被打开两次;只保留 DOM,Windows 的原生投递会让拖拽失效。
|
||
|
||
另外两条约束:
|
||
|
||
| 约束 | 原因 |
|
||
| --- | --- |
|
||
| `onDragEnd` 不能立即清空 `recentDrag`,要延迟 500 ms | 部分引擎在按钮抬起之后才发出原生 `drop`,提前清空会让这一次手势变成"落回面板的空拖拽"。 |
|
||
| 两条投递路径都必须把"没命中按钮"当作同一种结果处理 | 内部拖拽与外部拖入的语义必须一致;只在 DOM 路径静默、原生路径仍兜底开环或弹提示,就会出现同一个动作两种结果。 |
|
||
| 点亮候选按钮的开关有两个来源 | 外部拖拽靠原生 `enter` 设置的 `dragging`,内部拖拽原生事件不一定到,必须另有 `rowDragging`,否则从列表拖起时按钮毫无反应。 |
|
||
| 面板不要用 `is-dragging` 自己做拖放反馈 | 内部拖拽拿不到原生事件,只有外部拖拽会点亮面板,两种拖法观感不同;把反馈收在按钮上,两条路径共用同一套 `has-drop-target`。 |
|
||
| 三个按钮共用 `src/lib/dropCapabilities.ts` 一条规则 | 判定原先只写在「文字识别」上,另外两个按钮照旧执行,于是"能处理就处理、不能处理就禁止"在同一个面板里有两种口径。视觉状态(`spent()`)、`dropFiles` 的实际执行、`aimedAction` 的点亮,三处必须问同一个函数,否则会出现"看着能按、按下去什么都不做"或者反过来。 |
|
||
| 「处理不了」不接受兜底,也不解释拒绝 | 按钮说做什么就做什么:既不能转交别的圆环,也不能弹一条"为什么不行"——那等于让用户先做错再被纠正。按钮禁用加光标禁止符号就是全部答复。 |
|
||
| 拒绝交给光标,按钮侧不再叠符号;为此必须接管原生回报 | 光标上的复制角标本来就是"这个落点要不要文件"的答复,两条投递路径都能改到它,观感天然一致;代价是 macOS 要在 `drop_cursor.rs` 里改掉 wry 固定回报的 `NSDragOperation::Copy`。页内拖拽仍走 `dropEffectFor()`,Chromium 会照它画禁止光标。 |
|
||
| 禁用按钮要 `pointer-events: none` | 落点靠坐标命中,不靠元素应答;禁用后按钮若仍占命中区,拖拽事件不再回到它身上,`dropAction` 会停在上一个应答的按钮上。 |
|
||
| 内部拖拽的原生 `enter` 不带文件名,要合并不要覆盖 | `collect_paths` 只读文件列表,页内拖拽带的是 `text/uri-list`,于是回报空数组;直接写入会把 `dragstart` 登记的行路径冲掉,三个按钮全点亮、松手又静默。`dragPathsKnown()` 保留已知的那一份。 |
|
||
| `actionCanServe` 在"文件未知"时必须返回 true | Windows 的拖拽在载荷可读之前可能报告 0 个文件;按空列表判定会把三个按钮全部禁掉,一次本来能用的手势就废了。只有"知道文件、且知道处理不了"才禁止。 |
|
||
| 「文件工具」永不禁止 | 它的环以打开 / 在文件夹中显示 / 发送收尾,任何存在的文件都能执行;把"其他"类型判成处理不了会让面板出现三个灰按钮。 |
|
||
| 拖出的行落在窗口之外时不能命中按钮 | `dragend` 的坐标也要经过 `actionAtPoint`,而命中判定四周有 `SLACK_X/SLACK_Y` 余量;不先判窗口边界,拖去资源管理器的一行会被当成落在按钮上。 |
|
||
| 拖拽结束时三处都要清空 `dragPaths` | 原生 `leave`、原生 `drop`、行的 `dragEnd` 都要清;`landRecentRow` 也清一次,因为部分引擎在落点已确定后才补 `dragEnd`,只靠它会让按钮在下一笔拖拽前一直显示为不可用。 |
|
||
|
||
### Windows:一次内部拖拽可能一次都不报告
|
||
|
||
0.1.10 用户实测:Windows 上把「最近使用」的行拖到三个按钮,**每一个都完不成**。台账
|
||
里"只保留 DOM,Windows 的原生投递会让拖拽失效"写反了方向——在 Windows 上两条路都可能不到:
|
||
|
||
1. **DOM 路径**:历史行是 `draggable` 的文件式拖拽,WebView2 在自己的窗口上注册了 OLE
|
||
`IDropTarget`(`wry/src/webview2/drag_drop.rs`),页面内的 drop 被它接管。
|
||
2. **原生路径**:那个 `IDropTarget::DragEnter` 只读 `CF_HDROP`;页内拖拽不带这个格式,
|
||
于是 `enter_is_valid` 保持 false,`DragOver` / `Drop` / `DragLeave` 一律不上报。
|
||
|
||
两条都静默,松手就没有任何事件,于是"什么都会发生"被用户读成"拒绝"。修法是让 `dragend`
|
||
成为兜底:它总会上报,且带 `clientX/clientY`,足够命中按钮;`landed` 标记保证它只在两条
|
||
投递路径都没到过的时候执行一次。
|
||
|
||
**0.1.11 第一次修错了方向。** 那版把兜底写在 `dragEnd` 里立刻执行,而 macOS 的原生
|
||
`drop` 是在按钮抬起**之后**才到的:兜底先用 `dragend` 自己的坐标判定(Chromium 在这里报
|
||
的是 (0, 0),不是松手位置),把 `landed` 置真,随后真正的那次 drop 被当作"这一笔已经完了"
|
||
丢掉——结果从"偶尔不响应"变成"三个按钮全部无反馈"。现在兜底满足两条:
|
||
|
||
| 约束 | 原因 |
|
||
| --- | --- |
|
||
| 兜底必须延迟到真正 drop 之后(260 ms),且只由 `landed` 决定谁执行 | 谁先谁是正确答案因引擎而异;macOS 是 drop 在后,页内拖拽在 Chromium 是只有 `dragend`。 |
|
||
| 兜底只在**命中按钮**时才落地 | 没命中时它给不出任何 0.1.10 给不了的东西,却可能抢在真正的 drop 之前把这一笔标记完成,把它吃掉。 |
|
||
| `dragend` 坐标为 (0, 0) 时改用在途最后一次 `dragover` 的位置 | (0, 0) 是"没报告"而不是"在左上角松手";Chromium 就是这样。 |
|
||
| 不要改成"记住离开窗口时就丢掉该位置" | Chromium 在 `dragenter` / `dragleave` 上把 `relatedTarget` 固定为 null,按它清位会让 Windows 的兜底永远拿不到落点——又回到不响应。剩下的误判只剩"从按钮上拖出去"这一种路径,代价远小于什么都不做。 |
|
||
|
||
### 拖动时的图像是文件,不是那一行
|
||
|
||
不加 `setDragImage` 时,引擎拍的是指针下的元素本身:缩略图 + 文件名 + 时间 + 目录 + 五个悬停
|
||
按钮,看上去像在拖整个列表。`src/lib/dragImage.ts` 造一个和圆环拖拽示意同款的"一个文件 +
|
||
名字"的图(图片行复用列表里已经解码好的缩略图,其他行显示扩展名)。它挂在 body 外、屏幕外,
|
||
250 ms 后自删:两个引擎拍照的时机不同帧,删早了就拍不到。
|
||
|
||
### Windows:闲置的圆环会压在按钮上
|
||
|
||
圆环窗口无边框、`always_on_top`,用完不关就停在原地等点击,而它可能正压在面板的按钮上。
|
||
开始拖动一行时先调用 `stand_down_radial` 让它让开;`radial_dragging` 为真说明这次圆环属于
|
||
一个正在进行的 Shift 拖拽手势,那时不能收——结束手势的松手才有权处置它。
|
||
|
||
注意不要把它改成"圆环在 `enter` 时自行让开":往打开的圆环上直接放文件、由落点扇区执行该
|
||
动作,是 Windows 现有的一条可用路径,被闲置判定挡掉就是功能倒退。
|
||
|
||
### 回归测试
|
||
|
||
`src/lib/dropTargets.test.ts` 覆盖命中区域与坐标换算,`src/lib/dropCapabilities.test.ts`
|
||
覆盖"谁能服务这次拖拽"这条规则(含类型表与后端一致、PDF 不落到 OCR、载荷未知时不禁止);
|
||
拖拽本身用浏览器实测(Chromium 与 WKWebView 两条路径都要走一遍):
|
||
|
||
1. 「最近使用」某行 → 拖到「文件转换」→ 只弹出一个格式环,且文件是这一行。
|
||
2. 同一行 → 拖到「文件工具」→ 只弹出工具环。
|
||
3. 图片行 → 拖到「文字识别」→ 按钮正常点亮,光标带 +,打开编辑器并自动开始识别;非图片行 → 「文字识别」拖拽全程为禁用态、**光标为禁止符号**、不会点亮,**hover 完全无反馈**,松手后不打开编辑器、不开环、**不出现任何提示**,另外两个按钮仍可正常落点。**同一条非图片行还要从访达再拖一次**:两条通道的光标观感必须一致(这是 0.1.11 的主要回归点)。
|
||
3b. `.key` / `.zip` 这类没有可转换目标的行 → 「文件转换」同样全程禁用+光标禁止、松手不执行;「文件工具」始终可用并正常弹出工具环。
|
||
3c. **Windows 必须单独跑一遍 1–3**:这一平台两条投递路径都可能不上报,兜底只在 `dragEnd` 里,macOS 通过不代表 Windows 通过。
|
||
3d. 先用「文件转换」弹出一个圆环、再拖一行到按钮上 → 圆环不能吃掉这次拖放(Windows 尤其要看这一条)。
|
||
3e. 拒绝之后把文件拖到**能服务的按钮**上 → 光标必须重新变成 +、按钮重新点亮、松手正常执行。原生侧一旦在拒绝时提前返回而跳过 wry 的实现,页面就收不到指针移动,整段手势都会停在拒绝上。
|
||
3f. 连续拖两次同一批文件 → 第二次不能残留第一次的判定(`dragSession` 就是为了让每次手势都重新上报一次)。
|
||
4. 同一行 → 拖到面板空白处 / 标题栏 / 列表本身 → 不开环、不执行、**不出现任何提示浮层**。
|
||
5. 从访达拖文件到面板空白处 → 同样不执行、不提示;拖到任一按钮 → 执行该按钮的动作。
|
||
6. 行拖出到访达/聊天窗口 → 仍是文件本体,没有被 Shift 自己吃掉。
|
||
7. 两种拖法各拖一次 → 面板(`.home-drop`)在拖拽全程不缩放、不变色,标题文案不变;只有三个按钮在拖拽开始时同时亮起虚线候选态、松开后熄灭。
|
||
8. 松手之后(无论落在哪里)→ 按钮立刻恢复正常亮度,下一次拖拽不会残留不可用态。
|
||
|
||
## 「完成后在访达中显示」管到的两条落地路径
|
||
|
||
`auto_reveal` 这个开关原本只有转换完成时会读:`perform_file_action` 结束前判断一次,
|
||
弹出第一个输出。局域网收到的文件走的是 `share.rs::receive_file`,它自己 `emit`
|
||
`app://file-result` 并写入历史,从来不经过那条判断,所以「接收完就弹一个访达窗口」
|
||
不受任何设置控制。
|
||
|
||
现在两条落地路径共用同一条规则:**文件落地之后是否把文件管理器带到前台,由
|
||
`settings::auto_reveal` 决定**。批量接收沿用批处理的既有语义——一批只在最后一个文件
|
||
落地时显示一次(`reveals_on_landing`),而不是每个文件弹一次窗口,与一次转换十个文件
|
||
只弹一个输出的行为对齐。
|
||
|
||
| 约束 | 原因 |
|
||
| --- | --- |
|
||
| 接收路径必须读 `auto_reveal`,不能自己决定弹窗 | 同一件事有两种行为,用户只能理解为开关坏了;转换那侧已经是这个口径。 |
|
||
| 一批文件只按最后一个文件显示一次 | 显示的是文件管理器窗口,十个文件弹十次等于抢占前台十次。 |
|
||
| 批内序号必须在 `emit_transfer` 之前读 | 那条事件会把 `header.peer_name` 移出,之后再借用就是编译错误;先算成一个 `bool` 才能既保住顺序又保住借用检查。 |
|
||
| 缺字段的旧版本信标必须仍然显示 | `batch_index` / `batch_total` 都取默认 0 时,`index + 1 >= total` 成立,`saturating_add` 防的是 0 - 1 下溢。 |
|
||
|
||
### 回归测试
|
||
|
||
`cargo test --lib share` 的 `only_the_last_file_of_a_batch_reveals`:钉住单文件、批次中间、
|
||
批次末尾与旧版本信标四种头部的判定。
|
||
|
||
## 提示语由界面措辞,后端只报代号
|
||
|
||
同一件事在两个地方各说一遍,就一定会说成两样。0.1.10 之前正是这样:`perform_action` 直接返回
|
||
`"Saved 1 file."` 这类英文句子,界面在中文环境里也就照原样显示,而同一个环里别的结果用的是
|
||
`t("saved")`;写目录被拒的提示同样由 Rust 拼成英文长句,macOS 首次运行必然看到它。
|
||
|
||
现在约定只有一条:**后端说"是哪件事",界面说"这句话怎么说"。**
|
||
|
||
- 结果:`ActionOutcome.message` 只能是 `outcome*` 代号,由 `src/lib/feedback.ts` 的
|
||
`outcomeMessage()` 措辞;数量取自 `outputs.length`,不再把数字写进句子再让人解析。
|
||
- 失败:`Err("…")` 用 `err*` 或 `share-*` / `homebrew-*` 这类既有小写代号;显示前统一走
|
||
`t(messageFrom(error))`。`translate()` 查不到 key 时原样返回,所以第三方库抛出的原始句子
|
||
(`ffmpeg exited with status 137`)仍会照实显示,不会被压成一句无信息的话。
|
||
- 措辞查不到就不要显示代号:`outcomeMessage()` 对未知 `outcome*` 回落到 `saved`。
|
||
|
||
`src/lib/feedback.test.ts` 会扫过 `src-tauri/src/*.rs`,要求每一个 `err*` / `outcome*` 代号在
|
||
两种语言里都有措辞,且 `outcome*` 必须被 `feedback.ts` 认识。新增代号时不必改测试——它会自己发现漏掉的
|
||
那一个;删掉一个还在用的代号同样会红。
|
||
|
||
另一条容易踩的约束:**一次性注册的监听器不要闭包捕获 `t`。** 挂载时注册的回调拿到的是首帧的 `t`,
|
||
之后切换语言,它弹出的消息仍是启动时的语言;`app://error` 与两条落点失败的回调因此用
|
||
`tLive()`(按当前存储的语言即时翻译),而不是 `t`。
|
||
|
||
反馈的时长收在 `FEEDBACK` 一处(`done` / `hint` / `notice` / `error` / `running` / `hold`),
|
||
`hold` 专用于进度会持续刷新、中途不能过期的长任务;`src/lib/utils.ts` 的 `messageFrom()` 是
|
||
把 unknown 变成文案的唯一途径。不可用控件统一用 `--dimmed` 与 `cursor: default`,
|
||
`:hover` 一律带 `:not(:disabled)`。
|
||
|
||
## 更新、分享与读取边界
|
||
|
||
2026-11 的全面评审补了一组不应被简化掉的约束。它们共同处理的是同一类问题:
|
||
**一个被声明为“已校验”的对象,在真正使用前仍可能变化,或声明值本身可能不可信。**
|
||
|
||
### 更新链路
|
||
|
||
| 约束 | 原因 |
|
||
| --- | --- |
|
||
| 清单里的文件名必须直接位于发布目录 | 路径分隔符、`..`、空格和 shell 元字符不能进入下载路径或交接参数;发布脚本产出的文件名只含 ASCII 字母、数字、`.`、`-`、`_` |
|
||
| 清单下载后限制 256 KiB | 清单是小型 JSON;损坏或被替换的 feed 不应无限占用内存 |
|
||
| 下载后校验是普通文件、精确字节数和 SHA256 | 只比较哈希仍会接受声明尺寸与实际尺寸不一致的输入 |
|
||
| 安装前再次执行同一组校验 | 下载文件位于可写的临时目录,下载完成到用户点击安装之间存在 TOCTOU 窗口;失败时必须删除文件 |
|
||
| macOS/Windows 辅助脚本使用固定脚本常量,路径经进程参数或环境变量传入 | 文件夹名不能改变 helper 的脚本文本;Windows 启动器必须保留 `cmd.exe /C` 的外层引号,否则含空格路径会被静默截断 |
|
||
| `Discard` 删除实际下载物 | 只清状态会留下可被误用的旧安装包 |
|
||
|
||
回归测试:`artifact_names_stay_inside_the_release_directory`、
|
||
`an_installer_changed_after_download_is_refused`,以及两个 handoff 脚本的参数化
|
||
检查。真实 Windows 交接仍需在 Windows 机器上验收。
|
||
|
||
### 分享链路
|
||
|
||
| 约束 | 原因 |
|
||
| --- | --- |
|
||
| peer 表最多 256 项,满时先清理过期项 | 未认证信标可伪造无限 id;可见列表不能无限增长 |
|
||
| 发送端按 header 声明大小精确复制 | 源文件在 metadata 之后变长时,多出的字节会被接收端误当成 ack |
|
||
| 源文件比声明短时立即失败 | 不允许用半截文件换取成功状态;接收端删除 `.shift-part` |
|
||
| 只有用户已接受后的接收失败才弹错误 | 任意 TCP 扫描或坏握手不应产生用户可见的 toast |
|
||
| 接收错误事件带文件名与 peer 名 | 失败要可定位,而不是只有一句泛化提示 |
|
||
|
||
回归测试:`the_peer_table_stops_accepting_new_ids_at_its_limit`、
|
||
`bytes_after_the_declared_size_never_cross_the_wire`、
|
||
`a_source_that_shrinks_is_refused_without_a_partial_file`。
|
||
|
||
分享协议本身仍无认证、无加密;这里修的是拒绝自动落盘、路径安全、字节边界和可见
|
||
失败,不是身份认证。安全边界见 `docs/SECURITY.md`。
|
||
|
||
### 编辑器读取
|
||
|
||
| 数据 | 上限 | 测试 |
|
||
| --- | --- | --- |
|
||
| 文本预览 | 8 MiB | `editor_reads_are_bounded_before_they_allocate` |
|
||
| 图片文件 | 64 MiB | 同上 |
|
||
| 图片像素 | 4000 万 | 与钉图上限一致 |
|
||
| 编辑后 data URL | 128 MiB | 解码前检查 |
|
||
|
||
文本与图片在 Rust 读盘前检查路径是否为普通文件并执行上限;UI 只负责把返回的
|
||
`errNotAFile` / `errTextTooLarge` / `errImageTooLarge` / `errEditDataTooLarge`
|
||
翻译成文案。不要在只读预览里静默吞掉读取错误。
|
||
|
||
## 修改这些路径时的统一回归命令
|
||
|
||
```bash
|
||
git diff --check
|
||
|
||
cd src-tauri
|
||
cargo fmt --check
|
||
cargo test --lib
|
||
cargo clippy --all-targets -- -D warnings
|
||
|
||
cd ..
|
||
pnpm check
|
||
pnpm test
|
||
pnpm build
|
||
```
|
||
|
||
发布构建还需额外完成本文对应章节的手工矩阵。任何一次修改如果改变了发现协议、转换
|
||
依赖链或 macOS 签名方式,都应在本文件补一条带日期的结论和提交号。
|