# 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 . 2. 3. ``` 示例:`report (compressed).pdf`、`photo (rotated) 2.png`。 设置选择「统一收集到一个文件夹」时,结果写入该目录,但唯一命名规则不变。 ### 4.2 页面文件夹 PDF 转图片和 PDF 拆分写出: ```text pages/Page 001.png pages/Page 002.png pages 2/Page 001.png ``` 页号至少三位;已存在的页面文件夹不会被复用。 ### 4.3 截图与录屏 - 截图:`Shift-YYYYMMDD-HHMMSS.png`。同一秒内的第二张为 `Shift-YYYYMMDD-HHMMSS 2.png`。 - 录屏:由当前后端决定扩展名,写入录屏输出目录;唯一命名规则相同。 - 共享接收:写入文件输出目录;冲突时使用 ` 2.`。 ## 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` 以只读 `
` 预览。
- 不提供就地编辑;可复制、另存为、打开或显示源文件。
- 文本读取失败时显示错误状态,不留空白预览。

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

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