Home

Clippy 技术实现 Wiki

Clippy 是跨平台轻量剪贴板管理器，基于 Tauri v2 + Rust 后端、vanilla HTML/CSS/ES modules 主界面与若干 React/TypeScript 功能岛。

本 Wiki 记录实现方法：每条结论都对应仓库里可查的代码路径、可运行的测试或已记录的实测数字。它不是使用手册，也不重复 README 的安装说明。

阅读顺序

新接手这个项目，建议按下面顺序读前四页，它们覆盖了绝大多数「为什么是这样写的」：

1. 架构总览 — 技术边界、模块职责、所有权划分
2. 剪贴板管线与存储 — 轮询 + 唤醒、单一入库路径、FTS5 事务一致性
3. 截图与冻结帧 — 多显示器冻结帧、覆盖层三态、合成器交互
4. 验证方法论 — 证据分级规则，本项目所有「已完成」的判定标准

全部页面

核心管线

页面	内容
架构总览	前后端边界、IPC 唯一出入口、模块地图
剪贴板管线与存储	500 ms 轮询与写入唤醒、SHA-256 去重、SQLite/FTS5 事务、容量清理
X11 大图传输	有界 INCR 分块发送状态机、写完成屏障、预算与超时
截图与冻结帧	帧获取回退链、覆盖层三态、二进制 IPC 直传 RGBA
长截图拼接	粗筛/精筛两级垂直位移估计、纹理与歧义判据、失败分类
本地 OCR	双引擎结构、结构化流水线、CTC 解码、布局排序、预算与并发

图像与显示

页面	内容
贴图与图像合成	PinManager 生命周期、可编辑 PNG 容器、权威后端合成器
显示缩放与重采样	分数缩放下的缓冲区缩放陷阱、反投影预补偿（实测 43 dB）

支撑体系

页面	内容
翻译与安全边界	provider 分层、敏感内容阻断、私有文件权限
性能基线	criterion 基准数字、内存优化措施、已知瓶颈归因
验证方法论	证据分级、静态与运行时之分、负控制、像素级端到端验收
质量门禁	本地门禁步骤、跳过与通过之分、平台矩阵边界

编码规范

页面	内容
后端编码规范	模块组织、错误处理、数据库、外部工具、日志、运行时不变量清单
前端编码规范	IPC 唯一出口、组件与 DOM 规则、渲染代次、隐藏生命周期、类型安全
工程思维指南	修改前铁律、代码复用判据、跨层数据流清单

三条贯穿全项目的原则

这三条在每一页都会再次出现，它们解释了大部分看起来「过度设计」的地方。

一、单一事实源。 内容类型判定只在 js/preview/classify.js；平台能力只在 platform/；剪贴板入库只有 watcher 一条路径；最终图像合成只在 pin/render_v2.rs。任何「两处都能算」的设计最终都会分叉，项目里已经有多个因分叉而产生的真实缺陷记录。

二、能力探测与实际执行必须指向同一个对象。 例如 OCR 引擎候选必须先通过 --version 才会被用于识别，否则「探测到了」和「实际调用的」可能是两份不同的程序。

三、区分「调用成功」与「业务成功」。 键鼠发送成功不等于操作生效；函数被调用不等于产出正确；进程还活着不等于状态正常。详见验证方法论。