nex_shift/docs/SPECIFICATION.md

11 KiB
Raw Permalink Blame History

Shift 产品行为规范

本文定义 Shift 0.1.11 可观察到的产品行为与验收口径。实现结构见 ARCHITECTURE.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 普通结果

默认写到源文件同目录:

<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 截图

  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. 验收标准

功能改动至少满足:

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 各一次。

若某项无法执行,应明确记录“未验证”,不得根据编译通过推断运行时通过。