282 lines
11 KiB
Markdown
282 lines
11 KiB
Markdown
|
|
# Shift 产品行为规范
|
|||
|
|
|
|||
|
|
本文定义 Shift 0.1.11 可观察到的产品行为与验收口径。实现结构见
|
|||
|
|
[`ARCHITECTURE.md`](ARCHITECTURE.md),安全边界见 [`SECURITY.md`](SECURITY.md)。
|
|||
|
|
若本文与代码冲突,以代码和自动化测试为准,并应同步修正本文。
|
|||
|
|
|
|||
|
|
## 1. 范围
|
|||
|
|
|
|||
|
|
Shift 是一个本地桌面文件工作台,提供:
|
|||
|
|
|
|||
|
|
- 类型感知的格式转换与文件工具;
|
|||
|
|
- 区域/全屏截图与区域录屏;
|
|||
|
|
- 图片标注、只读文本预览、视频播放;
|
|||
|
|
- 英文与简体中文 OCR;
|
|||
|
|
- 局域网设备发现与文件发送;
|
|||
|
|
- 基于 git 通道的应用内更新。
|
|||
|
|
|
|||
|
|
不包含:账号、云端存储、遥测、文件上传、局域网中继、文本就地编辑、
|
|||
|
|
Linux 官方安装包、macOS 公证。
|
|||
|
|
|
|||
|
|
## 2. 产品不变量
|
|||
|
|
|
|||
|
|
1. **源文件只读。** 转换、压缩、旋转、裁剪、标注和 OCR 都写出新文件。
|
|||
|
|
2. **永不覆盖。** 所有输出使用唯一文件名;同名时追加 ` 2`、` 3`……
|
|||
|
|
3. **本地处理。** 转换与 OCR 不发起网络请求;只有更新检查和用户主动发起的
|
|||
|
|
局域网传输会使用网络。
|
|||
|
|
4. **界面只展示可执行操作。** 格式目录决定扇区;后端没有处理器的动作不得出现。
|
|||
|
|
5. **失败必须可见。** 用户操作失败时,界面显示可读文案;不允许静默停在空状态。
|
|||
|
|
6. **已映射错误本地化。** 界面需要稳定识别后端失败时,Rust 返回 `err*` /
|
|||
|
|
`share-*` 等代号,由 `src/i18n.ts` 映射为中英文;原始第三方诊断可以原样透传。
|
|||
|
|
7. **能力如实申报。** 录屏、OCR、转换和平台权限只显示当前后端真正支持的选项。
|
|||
|
|
|
|||
|
|
## 3. 文件识别
|
|||
|
|
|
|||
|
|
识别以扩展名、而非 MIME 或文件内容为准,扩展名不区分大小写。
|
|||
|
|
|
|||
|
|
| 类型 `kind` | 扩展名 |
|
|||
|
|
| --- | --- |
|
|||
|
|
| `image` | `png` `jpg` `jpeg` `webp` `tiff` `tif` `bmp` `gif` `heic` `heif` `avif` |
|
|||
|
|
| `video` | `mp4` `mov` `m4v` `avi` `mkv` `webm` |
|
|||
|
|
| `audio` | `mp3` `wav` `m4a` `aiff` `aif` `caf` `flac` `ogg` |
|
|||
|
|
| `pdf` | `pdf` |
|
|||
|
|
| `document` | `docx` `doc` `rtf` `odt` `txt` `md` `html` `htm` `pages` |
|
|||
|
|
| `presentation` | `pptx` `ppt` `key` |
|
|||
|
|
| `spreadsheet` | `xlsx` `xls` `xlsb` `ods` `csv` `tsv` `numbers` |
|
|||
|
|
| `other` | 其他扩展名 |
|
|||
|
|
|
|||
|
|
被识别但当前不解析:`.doc`、`.pages`、`.ppt`、`.key`、`.numbers`。这些文件
|
|||
|
|
只提供编辑/打开/显示,不提供格式扇区。
|
|||
|
|
|
|||
|
|
## 4. 输出命名与位置
|
|||
|
|
|
|||
|
|
### 4.1 普通结果
|
|||
|
|
|
|||
|
|
默认写到源文件同目录:
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
<stem><suffix>.<ext>
|
|||
|
|
<stem><suffix> 2.<ext>
|
|||
|
|
<stem><suffix> 3.<ext>
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
示例:`report (compressed).pdf`、`photo (rotated) 2.png`。
|
|||
|
|
|
|||
|
|
设置选择「统一收集到一个文件夹」时,结果写入该目录,但唯一命名规则不变。
|
|||
|
|
|
|||
|
|
### 4.2 页面文件夹
|
|||
|
|
|
|||
|
|
PDF 转图片和 PDF 拆分写出:
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
<stem> pages/Page 001.png
|
|||
|
|
<stem> pages/Page 002.png
|
|||
|
|
<stem> pages 2/Page 001.png
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
页号至少三位;已存在的页面文件夹不会被复用。
|
|||
|
|
|
|||
|
|
### 4.3 截图与录屏
|
|||
|
|
|
|||
|
|
- 截图:`Shift-YYYYMMDD-HHMMSS.png`。同一秒内的第二张为
|
|||
|
|
`Shift-YYYYMMDD-HHMMSS 2.png`。
|
|||
|
|
- 录屏:由当前后端决定扩展名,写入录屏输出目录;唯一命名规则相同。
|
|||
|
|
- 共享接收:写入文件输出目录;冲突时使用 `<stem> 2.<ext>`。
|
|||
|
|
|
|||
|
|
## 5. 转换与工具
|
|||
|
|
|
|||
|
|
### 5.1 格式转换
|
|||
|
|
|
|||
|
|
可见目标必须同时满足:
|
|||
|
|
|
|||
|
|
- 文件类型支持该目标;
|
|||
|
|
- 目标不等于源格式;
|
|||
|
|
- 后端存在处理器。
|
|||
|
|
|
|||
|
|
当前转换目标与引擎以 README 的「Conversions / 格式转换」表为准。缺少外部
|
|||
|
|
依赖时,动作返回可操作错误,说明缺少哪个工具;界面不得提前展示一个明知
|
|||
|
|
不会工作的扇区。
|
|||
|
|
|
|||
|
|
### 5.2 工具
|
|||
|
|
|
|||
|
|
工具包含压缩、移除元数据、旋转、翻转、黑白、50%、裁剪、抠图、合并、拆分、
|
|||
|
|
提取文字、720p、静音、截帧、提取音频、单声道、纯文本和 OCR。
|
|||
|
|
|
|||
|
|
批量规则:
|
|||
|
|
|
|||
|
|
- 2 张以上图片可选择合并为 PDF;
|
|||
|
|
- 2 个以上 PDF 可选择合并为一个 PDF;
|
|||
|
|
- 其他工具逐文件执行。
|
|||
|
|
|
|||
|
|
### 5.3 取消与失败
|
|||
|
|
|
|||
|
|
- 在圆环中心或环外松手不执行动作。
|
|||
|
|
- 一个批次中的失败必须报告;不得把失败结果计入成功数量。
|
|||
|
|
- 转换成功后的结果写入历史库。
|
|||
|
|
|
|||
|
|
## 6. 截图与录屏
|
|||
|
|
|
|||
|
|
### 6.1 截图
|
|||
|
|
|
|||
|
|
1. 截图前检查屏幕录制权限;拒绝时返回可操作错误,不打开黑色遮罩。
|
|||
|
|
2. 区域截图为光标所在显示器的冻结画面。
|
|||
|
|
3. 全屏截图直接抓取光标所在显示器,不显示遮罩。
|
|||
|
|
4. 取消截图恢复先前隐藏的 Shift 窗口。
|
|||
|
|
5. 截图成功后显示结果卡片;卡片创建失败时打开编辑器。
|
|||
|
|
|
|||
|
|
### 6.2 录屏
|
|||
|
|
|
|||
|
|
- macOS:`screencapture -v`,可带麦克风。
|
|||
|
|
- Windows/Linux:FFmpeg 系后端,可选择 15/24/30 fps。
|
|||
|
|
- Wayland:区域录屏使用 `wf-recorder`;X11 使用 FFmpeg `x11grab`。
|
|||
|
|
- 界面只显示后端实现的选项;停止后必须完成文件收尾。
|
|||
|
|
|
|||
|
|
## 7. 编辑器
|
|||
|
|
|
|||
|
|
### 7.1 图片
|
|||
|
|
|
|||
|
|
- 以原始像素尺寸加载到画布。
|
|||
|
|
- 标注工具:矩形、箭头、高亮、打码、马赛克、模糊、序号、图章、裁剪、文字。
|
|||
|
|
- 每种工具使用固定颜色和线宽;不提供逐条标注的样式面板。
|
|||
|
|
- 保存和复制都在画布副本上合成;源文件不变。
|
|||
|
|
- 图片编辑器提供 OCR、复制文字、钉图和保存副本。
|
|||
|
|
- 环形菜单的「编辑 / 标注 / 打码 / 加背景」只负责打开图片编辑器;当前不会
|
|||
|
|
预选具体工具,用户需在编辑器工具栏中选择。
|
|||
|
|
|
|||
|
|
### 7.2 文本
|
|||
|
|
|
|||
|
|
- `txt` `md` `csv` `tsv` `html` `htm` 以只读 `<pre>` 预览。
|
|||
|
|
- 不提供就地编辑;可复制、另存为、打开或显示源文件。
|
|||
|
|
- 文本读取失败时显示错误状态,不留空白预览。
|
|||
|
|
|
|||
|
|
### 7.3 视频与其他文件
|
|||
|
|
|
|||
|
|
- 视频使用 webview 播放器。
|
|||
|
|
- 其他可识别文件显示文件图标和打开入口。
|
|||
|
|
|
|||
|
|
### 7.4 编辑器资源上限
|
|||
|
|
|
|||
|
|
| 数据 | 上限 | 超限行为 |
|
|||
|
|
| --- | --- | --- |
|
|||
|
|
| 非普通文件路径 | — | `errNotAFile` |
|
|||
|
|
| 文本预览 | 8 MiB | `errTextTooLarge` |
|
|||
|
|
| 图片文件 | 64 MiB | `errImageTooLarge` |
|
|||
|
|
| 图片像素 | 40,000,000 | `errImageTooLarge` |
|
|||
|
|
| 编辑后 data URL | 128 MiB | `errEditDataTooLarge` |
|
|||
|
|
| OCR 结果写文本 | 8 MiB | `errTextTooLarge` |
|
|||
|
|
|
|||
|
|
列表预览在图片超限时省略缩略图,但文件本身仍可被识别和操作。
|
|||
|
|
|
|||
|
|
## 8. 历史库
|
|||
|
|
|
|||
|
|
- 由 Rust 写入 `app_data_dir/history.json`。
|
|||
|
|
- 容量上限 300 条;置顶条目不因容量或清理被移除。
|
|||
|
|
- 不存在的未置顶文件在整理时被丢弃。
|
|||
|
|
- 截图、转换结果和收到的文件都进入同一历史库。
|
|||
|
|
- 新条目通过 `history://changed` 与 `app://file-result` 广播。
|
|||
|
|
- 清除历史不删除磁盘上的文件。
|
|||
|
|
|
|||
|
|
## 9. OCR
|
|||
|
|
|
|||
|
|
- 图片:单张识别,实时显示进度,结果可复制或写入编辑器。
|
|||
|
|
- PDF:逐页渲染后识别,合并文本写出 `(OCR).txt`;临时页面目录随后删除。
|
|||
|
|
- 语言:英文与简体中文,使用本地 Tesseract WASM 和模型。
|
|||
|
|
- OCR 过程中不得下载语言包。
|
|||
|
|
|
|||
|
|
## 10. 局域网发送
|
|||
|
|
|
|||
|
|
### 10.1 发现
|
|||
|
|
|
|||
|
|
- UDP 组播:`239.255.77.88:47888`。
|
|||
|
|
- 另外使用定向广播、受限广播和受限 `/24` 单播扫描。
|
|||
|
|
- 信标包含实例 id、机器名、平台和 TCP 接收端口。
|
|||
|
|
- 15 秒未刷新即过期。
|
|||
|
|
- 可见 peer 上限 256;达到上限时先清理过期 peer,仍满则拒绝新 id。
|
|||
|
|
|
|||
|
|
### 10.2 传输
|
|||
|
|
|
|||
|
|
1. 发送端先写 `SHSF`、头部长度和 JSON 头。
|
|||
|
|
2. 接收端弹出确认卡片,默认 45 秒超时。
|
|||
|
|
3. 用户拒绝、关闭卡片或超时:不传文件字节。
|
|||
|
|
4. 用户接受:先回 1 字节同意,再传输正文。
|
|||
|
|
5. 接收端只写临时 `.shift-part`,按头部声明字节数收齐后原子重命名。
|
|||
|
|
6. 发送端只发送声明大小;源文件变短则失败,源文件变长不会多发送。
|
|||
|
|
7. 接收端完整落盘后才回确认;发送端看到确认才报告成功。
|
|||
|
|
|
|||
|
|
多文件批次使用同一批 id,一次确认后在 120 秒窗口内自动接收同批文件。
|
|||
|
|
|
|||
|
|
### 10.3 用户反馈
|
|||
|
|
|
|||
|
|
- 接收成功显示发送者与文件名。
|
|||
|
|
- 接收过程中断显示 `shareReceiveFailed`,不再静默。
|
|||
|
|
- 旧版本缺失批次字段时按单文件处理。
|
|||
|
|
|
|||
|
|
## 11. 更新
|
|||
|
|
|
|||
|
|
### 11.1 清单
|
|||
|
|
|
|||
|
|
- `schema` 必须为 1;缺失、0 或更高版本均拒绝。
|
|||
|
|
- 版本使用 semver,预发布版本低于同号正式版。
|
|||
|
|
- 文件不得包含路径分隔符,只允许 ASCII 字母、数字、`.`、`-`、`_`。
|
|||
|
|
- `size` 必须大于 0;SHA256 必须为 64 位十六进制。
|
|||
|
|
- 清单响应上限 256 KiB。
|
|||
|
|
|
|||
|
|
### 11.2 下载与安装
|
|||
|
|
|
|||
|
|
1. 下载到临时更新目录。
|
|||
|
|
2. 校验文件是普通文件、字节数精确一致、SHA256 匹配。
|
|||
|
|
3. 安装前再次运行相同校验;失败删除安装包。
|
|||
|
|
4. 只有状态为 `ready` 才允许安装。
|
|||
|
|
5. macOS 挂载 DMG 并替换 `.app`;Windows 运行同一 NSIS 安装器。
|
|||
|
|
6. 辅助脚本等待当前进程退出,路径通过进程参数传递。
|
|||
|
|
7. 失败时尽量重新打开旧版本,不留下“应用已退出且未安装”的状态。
|
|||
|
|
8. 丢弃下载会删除实际安装包并清空更新状态。
|
|||
|
|
|
|||
|
|
## 12. 错误与国际化
|
|||
|
|
|
|||
|
|
- 界面需要稳定识别的后端失败以代号返回;新增代号必须同时提供 `en` 与 `zh`。
|
|||
|
|
无法稳定映射的第三方诊断原样显示。
|
|||
|
|
- `translate()` 查不到 key 时原样显示,保留第三方工具诊断信息。
|
|||
|
|
- 单次注册的监听器使用 `tLive()`,避免切换语言后仍显示旧语言。
|
|||
|
|
- 不可用控件使用 disabled 状态和视觉禁用态,不伪装成可点击。
|
|||
|
|
|
|||
|
|
## 13. 平台能力
|
|||
|
|
|
|||
|
|
| 能力 | macOS | Windows | Linux |
|
|||
|
|
| --- | --- | --- | --- |
|
|||
|
|
| 发布安装包 | 通用 DMG | x64 NSIS | 无 |
|
|||
|
|
| 全局拖拽唤起圆环 | AppKit 桥 | Win32 轮询 + 原生拖放 | 无;仅主窗口选择 |
|
|||
|
|
| 截图/录屏 | 原生 | GDI + FFmpeg | `grim` / `wf-recorder` / FFmpeg |
|
|||
|
|
| 文档渲染 | AppKit/PDFKit | Pandoc + Poppler | Pandoc + Poppler |
|
|||
|
|
| 局域网分享 | 支持 | 支持(单实例监听) | 支持 |
|
|||
|
|
| 更新 | 支持 | 支持 | 能检查,但通道无产物 |
|
|||
|
|
|
|||
|
|
Linux 是构建目标,不是已发布产品。
|
|||
|
|
|
|||
|
|
## 14. 验收标准
|
|||
|
|
|
|||
|
|
功能改动至少满足:
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
pnpm check
|
|||
|
|
pnpm test
|
|||
|
|
pnpm build
|
|||
|
|
cd src-tauri
|
|||
|
|
cargo fmt --check
|
|||
|
|
cargo test --lib
|
|||
|
|
cargo clippy --all-targets -- -D warnings
|
|||
|
|
cd ..
|
|||
|
|
git diff --check
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
涉及以下行为时还需手工验收:
|
|||
|
|
|
|||
|
|
- 跨机器发现与接收:两台真实设备,允许本地网络/防火墙;
|
|||
|
|
- 截图/录屏权限:macOS 屏幕录制、麦克风、本地网络;
|
|||
|
|
- Windows 拖拽与安装器:真实 Windows,不以交叉编译代替;
|
|||
|
|
- 更新:安装上一版本,执行一次应用内升级;
|
|||
|
|
- Linux 截图/录屏:Wayland 与 X11 各一次。
|
|||
|
|
|
|||
|
|
若某项无法执行,应明确记录“未验证”,不得根据编译通过推断运行时通过。
|
|||
|
|
|