# fluxpin-copy

**Repository Path**: jane-far/fluxpin

## Basic Information

- **Project Name**: fluxpin-copy
- **Description**: Fluxpin（拾流）是一款键盘优先、本地优先、隐私友好的跨端剪贴板工具。它能够自动保存文本、图片和文件，通过全局快捷键快速唤起历史记录，让你随时找回并再次使用复制过的内容。Fluxpin 面向 macOS、Windows、Linux 与 Android 设计，支持离线使用、安全同步和敏感内容保护，让重要信息在设备之间自然流动，同时始终由你掌控。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-08
- **Last Updated**: 2026-08-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FluxPin 跨端剪贴板

<img src="assets/brand/fluxpin-app-icon-transparent.png" width="96" alt="FluxPin 图标" />

面向 macOS、Windows、Linux 与 Android 的跨端剪贴板历史工具。产品原则:**本地优先、云端增量同步(E2EE 加密)、默认不覆盖远端系统剪贴板**。

**当前状态:桌面端本地 MVP 已在 macOS 上验证并打包;加密云同步(M2)核心已入库,待联调。**
UI 为 Apple HIG 风格:横向卡片网格 + 不透明抽屉 + Spotlight 式右侧预览区。

## 功能

### 剪贴板捕获
- 文本(Unicode/多行/代码/网址)、图片(保存原图 + 256px 缩略图)、文件列表(路径/名称/大小/MIME)
- 同设备连续相同内容去重(哈希比对,只更新时间并置顶)
- 来源应用名记录;应用黑名单(按名忽略,不记录)
- 暂停监听:15 分钟 / 1 小时 / 直到手动恢复
- 敏感内容启发式:纯数字验证码、PEM/OpenSSH 私钥、凭据参数 → 标记"敏感"不上传候选

### 历史管理
- 横向卡片网格(固定两行,高度自适应窗口)+ 右侧预览区(文本全文 / 图片大图 / 文件信息)
- 类型筛选:全部 / 文本 / 图片 / 文件 / 收藏;FTS5 即时搜索(10,000 条下 <100ms)
- 完整键盘操作:↑↓←→ 网格导航、Enter 复制并关闭、⇧Enter 仅复制、⌘1~9 快速选择、
  ⌘D 收藏、⌫ 删除(5 秒撤销)、Esc 关闭、`/` 聚焦搜索
- 保留策略:文本 30 天、图片/文件 7 天、最多 10,000 条、磁盘 2GB(均可配置)

### 底部抽屉(macOS)
- 全局快捷键 `⌘⇧V`(可在设置中修改);托盘左键也可切换
- 鼠标所在屏唤起;矩形严格位于工作区内:距左右 16px、底部 8px,宽度 = 工作区宽 - 32px,
  高度固定 320px,恰好容纳两行卡片(无需配置);完整支持全屏空间
- 打开 240ms / 关闭 180ms 动效,支持"减少动态效果"(80ms 淡入淡出)
- 无 Dock 图标,仅菜单栏入口;失焦自动隐藏;关闭后恢复唤起前的前台应用焦点

### 设置窗口
- 通用:主题(跟随系统/浅色/深色)、开机启动、启动时隐藏、全局快捷键
- 记录:类型开关、去重开关、应用黑名单、保留天数/条数
- 隐私:敏感规则开关、清除本机历史、导出 JSON、立即清理
- 关于:版本、设备名、统计、数据目录

## 加密云同步(M2,核心已入库)

端到端加密设计见 [ADR 0004](docs/adr/0004-e2ee-sync.md),已在仓库中实现的组件:

- `crates/clip-crypto`:密钥层级(ARK/ADK/CEK)、XChaCha20-Poly1305、X25519/Ed25519
  设备身份、macOS Keychain 设备密钥、分块加密(1 MiB)与跨语言测试向量
- `crates/clip-sync`:加密事件日志、游标、确定性 LWW 合并与重试状态机
- `apps/sync-server`:Axum 服务端(设备注册、密钥封装包、事件批次、分块上传与配额)

服务端即使被完全读取,也拿不到剪贴板正文、文件内容或敏感元数据(明文只存在于用户设备)。

## 快速开始(macOS)

```bash
# 依赖:Node 20+、pnpm、Rust(含 Xcode Command Line Tools)

cd apps/desktop
pnpm install

# 开发模式(热更新)
pnpm tauri dev

# 生产构建(app + dmg)
pnpm build && pnpm tauri build
```

调试模式(自动化验证用,启动即唤起抽屉):

```bash
FLUXPIN_DEBUG=1 ./apps/desktop/src-tauri/target/debug/fluxpin
```

应用图标源文件:`assets/brand/fluxpin-app-icon-transparent.png`(重新生成图标集:`pnpm tauri icon <该文件>`)。

## 测试

```bash
cargo test                      # 全部 Rust 测试(81 项:领域/存储/加密/几何/剪贴板回环/性能)
cd apps/desktop && pnpm build   # 前端构建(含 tsc 类型检查)
```

测试覆盖:去重与规范化、敏感识别、保留策略、设置、迁移/CRUD/FTS 搜索、加密往返与
篡改检测、冻结测试向量、抽屉几何(多屏/DPI)、对象文件原子写与标记-清扫、
真实剪贴板读写回环、10,000 条搜索性能(<100ms)。

## 数据位置

- 数据库:`~/Library/Application Support/com.fluxpin.app/fluxpin.db`(SQLite + WAL + FTS5)
- 图片对象:`.../objects/`(内容寻址,先写临时文件再原子改名)
- 日志:`~/Library/Logs/FluxPin/fluxpin.log`(字段白名单,不含剪贴板正文)

> 更名提示:旧版(ClipFlow)数据在 `~/Library/Application Support/com.clipflow.app/`,
> 不随新版本自动迁移,可按需手动复制。

## 目录结构

```
crates/
  clip-domain   领域模型与业务规则(去重、敏感识别、保留策略、设置)
  clip-store    本地 SQLite 持久化(迁移、CRUD、FTS 搜索与清理)
  clip-crypto   端到端加密(密钥层级、AEAD、设备身份、分块加密)
  clip-sync     同步协议(加密事件日志、游标、LWW 合并)
apps/
  desktop       Tauri 2 + React 桌面端(macOS)
  sync-server   Axum 同步服务端
docs/           产品需求、技术规划、ADR、测试报告
```

## 已知限制与后续(见 docs/adr/)

- 本地库暂为明文 SQLite(系统 FileVault 兜底),SQLCipher 随 M2 同步里程碑接入(ADR 0002)
- 富文本 HTML/RTF、自动粘贴、拖出、来源图标、右键菜单 → P1
- Windows/Linux 适配器未实现(接口已预留,ADR 0003)
- 云同步联调(客户端 ↔ sync-server)、Android 客户端 → M2/M3
- 恢复密钥/账号体系 → M2

## 文档

- [产品需求说明](docs/产品需求说明.md)
- [技术规划](docs/技术规划.md)
- [架构决策记录](docs/adr/)
- [黑盒测试报告](docs/黑盒测试报告.md)
- [真机测试指引](docs/真机测试指引.md)
- [抽屉截图(验证证据)](docs/验证-抽屉截图.png)

## 验证记录(2026-08-12,macOS 15.7 arm64)

| 项目 | 结果 |
| --- | --- |
| cargo test(全部 crate) | 81 项通过 |
| 文本捕获 → 入库 | 通过(含哈希/来源应用) |
| 连续复制去重 | 通过(1 条记录,updated_at 置顶) |
| 图片捕获 → 原图 + 缩略图 | 通过(对象库内容寻址) |
| 文件捕获 → 元数据 | 通过(path/name/size/mime) |
| 写回(应用复制 → 剪贴板) | 通过(真实剪贴板回环) |
| 抽屉几何 | 1920×1080 屏:X=16,宽=1888,高=320,底部避让 Dock |
| 托盘图标 / 全局快捷键注册 | 通过(菜单栏可见、注册日志成功) |
| 10,000 条搜索/列表性能 | <100ms 目标达成 |
| 加密往返 / 篡改检测 / 冻结向量 | 通过(26 项,含官方 IETF 向量) |