11 KiB
11 KiB
Shift 产品行为规范
本文定义 Shift 0.1.11 可观察到的产品行为与验收口径。实现结构见
ARCHITECTURE.md,安全边界见 SECURITY.md。
若本文与代码冲突,以代码和自动化测试为准,并应同步修正本文。
1. 范围
Shift 是一个本地桌面文件工作台,提供:
- 类型感知的格式转换与文件工具;
- 区域/全屏截图与区域录屏;
- 图片标注、只读文本预览、视频播放;
- 英文与简体中文 OCR;
- 局域网设备发现与文件发送;
- 基于 git 通道的应用内更新。
不包含:账号、云端存储、遥测、文件上传、局域网中继、文本就地编辑、 Linux 官方安装包、macOS 公证。
2. 产品不变量
- 源文件只读。 转换、压缩、旋转、裁剪、标注和 OCR 都写出新文件。
- 永不覆盖。 所有输出使用唯一文件名;同名时追加
2、3…… - 本地处理。 转换与 OCR 不发起网络请求;只有更新检查和用户主动发起的 局域网传输会使用网络。
- 界面只展示可执行操作。 格式目录决定扇区;后端没有处理器的动作不得出现。
- 失败必须可见。 用户操作失败时,界面显示可读文案;不允许静默停在空状态。
- 已映射错误本地化。 界面需要稳定识别后端失败时,Rust 返回
err*/share-*等代号,由src/i18n.ts映射为中英文;原始第三方诊断可以原样透传。 - 能力如实申报。 录屏、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 普通结果
默认写到源文件同目录:
<stem><suffix>.<ext>
<stem><suffix> 2.<ext>
<stem><suffix> 3.<ext>
示例:report (compressed).pdf、photo (rotated) 2.png。
设置选择「统一收集到一个文件夹」时,结果写入该目录,但唯一命名规则不变。
4.2 页面文件夹
PDF 转图片和 PDF 拆分写出:
<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 截图
- 截图前检查屏幕录制权限;拒绝时返回可操作错误,不打开黑色遮罩。
- 区域截图为光标所在显示器的冻结画面。
- 全屏截图直接抓取光标所在显示器,不显示遮罩。
- 取消截图恢复先前隐藏的 Shift 窗口。
- 截图成功后显示结果卡片;卡片创建失败时打开编辑器。
6.2 录屏
- macOS:
screencapture -v,可带麦克风。 - Windows/Linux:FFmpeg 系后端,可选择 15/24/30 fps。
- Wayland:区域录屏使用
wf-recorder;X11 使用 FFmpegx11grab。 - 界面只显示后端实现的选项;停止后必须完成文件收尾。
7. 编辑器
7.1 图片
- 以原始像素尺寸加载到画布。
- 标注工具:矩形、箭头、高亮、打码、马赛克、模糊、序号、图章、裁剪、文字。
- 每种工具使用固定颜色和线宽;不提供逐条标注的样式面板。
- 保存和复制都在画布副本上合成;源文件不变。
- 图片编辑器提供 OCR、复制文字、钉图和保存副本。
- 环形菜单的「编辑 / 标注 / 打码 / 加背景」只负责打开图片编辑器;当前不会 预选具体工具,用户需在编辑器工具栏中选择。
7.2 文本
txtmdcsvtsvhtmlhtm以只读<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 传输
- 发送端先写
SHSF、头部长度和 JSON 头。 - 接收端弹出确认卡片,默认 45 秒超时。
- 用户拒绝、关闭卡片或超时:不传文件字节。
- 用户接受:先回 1 字节同意,再传输正文。
- 接收端只写临时
.shift-part,按头部声明字节数收齐后原子重命名。 - 发送端只发送声明大小;源文件变短则失败,源文件变长不会多发送。
- 接收端完整落盘后才回确认;发送端看到确认才报告成功。
多文件批次使用同一批 id,一次确认后在 120 秒窗口内自动接收同批文件。
10.3 用户反馈
- 接收成功显示发送者与文件名。
- 接收过程中断显示
shareReceiveFailed,不再静默。 - 旧版本缺失批次字段时按单文件处理。
11. 更新
11.1 清单
schema必须为 1;缺失、0 或更高版本均拒绝。- 版本使用 semver,预发布版本低于同号正式版。
- 文件不得包含路径分隔符,只允许 ASCII 字母、数字、
.、-、_。 size必须大于 0;SHA256 必须为 64 位十六进制。- 清单响应上限 256 KiB。
11.2 下载与安装
- 下载到临时更新目录。
- 校验文件是普通文件、字节数精确一致、SHA256 匹配。
- 安装前再次运行相同校验;失败删除安装包。
- 只有状态为
ready才允许安装。 - macOS 挂载 DMG 并替换
.app;Windows 运行同一 NSIS 安装器。 - 辅助脚本等待当前进程退出,路径通过进程参数传递。
- 失败时尽量重新打开旧版本,不留下“应用已退出且未安装”的状态。
- 丢弃下载会删除实际安装包并清空更新状态。
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. 验收标准
功能改动至少满足:
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 各一次。
若某项无法执行,应明确记录“未验证”,不得根据编译通过推断运行时通过。