📊 ProgressPanel · 桌面悬浮进度面板

Mac 风格的任务进度查看器：常驻屏幕右上角，马卡龙配色、毛玻璃质感， 多事件进度实时展示。前后端分离——任何程序调用一行 API， 任务进度就会实时出现在你的桌面上。

📸 实机截图

折叠展示（默认 4 条）	展开 + 拼音搜索框	拼音过滤结果	手动添加任务

截图取自 Tauri 桌面端的真实窗口渲染（Retina 2x），与交付产物一致。

✨ 功能特性

• 任务进度查看：右上角悬浮面板，多事件进度实时展示，一眼掌握所有任务状态
• 智能折叠：默认展示 4 条，超过自动折叠；展开后超过 6 条面板停在 6 条高度、列表滚动，高度随内容自适应
• 刷新即重绘：点击 ⟳ 刷新，所有进度条从 0 重新生长到当前值，与数字变化同步呈现
• 实时推送：后端 REST API + SSE，外部程序（CI、脚本、服务）一行 curl 即可更新面板，秒级刷新
• 拼音搜索：展开且任务数 > 4 时出现搜索框，支持拼音全拼 / 首字母 / 模糊匹配（标题+副标题，本地匹配，多词空格 AND）
• 手动添加：面板上 + 添加任务，双击卡片拖动滑杆调整进度；后台推送任务只读
• 清理已完成：卡片 × 单个删除，或头部 ✓ 一键清理；任务不自动删除
• 标准系统体验：系统原生标题栏与红绿灯、毛玻璃质感、置顶、跨桌面（Space）显示、托盘驻留（关闭面板后可点托盘图标恢复）
• 拖动优化：拖动不出屏、靠近屏幕边缘自动吸附（留 16px 间距）
• 开箱即用：桌面端内置 Rust 后端（零 Node 依赖），数据 JSON 持久化，重启不丢

🚀 快速开始（开发模式）

npm install              # 安装根依赖（tauri CLI 等）

npm run dev              # 启动开发模式：前端静态服务器 + tauri dev（热更新）
npm run demo             # （另开终端）推送演示事件，看面板实时变化

面板启动后常驻主屏幕右上角：

• 显示/隐藏、复位、退出：点 macOS 菜单栏的 🧁 托盘图标（"复位到主屏幕右上角"可把拖走的面板移回原位；关闭面板后点托盘图标即可恢复）
• 移动面板：按住面板标题栏拖动 —— 面板不会超出屏幕边界，靠近屏幕边缘自动吸附并留 16px 间距
• 搜索：展开且任务数 > 4 时，面板顶部出现搜索框，支持拼音（全拼/首字母）、模糊搜索，匹配标题与副标题（多词空格 AND）
• 置顶：始终显示在所有窗口和全屏应用之上，切换桌面（Space）也不消失
• 添加任务：点面板头部 + 按钮，输入标题/副标题并选一个马卡龙色
• 编辑进度：双击手动添加的任务卡片，拖动滑杆调整进度与状态
• 清理：已完成任务点卡片右上角 × 单个删除，或头部 ✓ 一键清理
• 刷新：点头部 ⟳，数据重新拉取且进度条从 0 重播

📦 打包分发（无需平台签名）

Tauri 2 + Rust 编译为原生 macOS 应用（约 5.7MB，无 Electron 运行时负担）：

npx tauri build          # 产物：
                         #   src-tauri/target/release/bundle/macos/ProgressPanel.app
                         #   src-tauri/target/release/bundle/dmg/ProgressPanel_1.0.0_x64.dmg

双击 ProgressPanel.app 即可运行：面板 + Rust 内置后端一起启动，无需任何其他操作。 未签名应用首次运行需右键 → 打开放行一次。

🏗 目录结构

progress-panel/
├── src-tauri/               # Tauri 2 桌面端（Rust 主进程 + 内置后端）
│   ├── src/
│   │   ├── main.rs          #   入口
│   │   ├── lib.rs           #   悬浮窗 / 托盘 / 拖动 / 高度自适应 / 标题栏适配
│   │   └── server.rs        #   内置后端：REST + SSE（std TcpListener，零 HTTP 依赖）
│   ├── tauri.conf.json      #   窗口与打包配置
│   └── Cargo.toml
├── app/renderer/            # 面板 UI（HTML/CSS/JS，桌面端直接内嵌）
│   ├── index.html
│   ├── styles.css           #   马卡龙配色 · 毛玻璃 · 极简
│   ├── app.js               #   SSE 实时渲染 · 折叠/展开 · 拼音搜索 · 刷新重播
│   ├── bridge.js            #   window.desktop → Tauri invoke 桥
│   └── vendor/              #   pinyin-pro（本地依赖）
├── scripts/
│   ├── demo.js              #   演示脚本：推送一组示例事件
│   ├── dev-server.js        #   开发模式前端静态服务器（no-store）
│   ├── dev.sh               #   一键启动开发模式
│   └── gen-icon.js          #   托盘图标生成器（纯 Node 无依赖）
├── docs/screenshots/        # README 实图
└── package.json

早期 Electron 版本（server/ + app/main.js）保留在仓库历史中，当前版本为 Tauri 重写。

🔌 后端 API

Base URL：http://127.0.0.1:4620（可用环境变量 PORT 修改）。

事件模型

字段	类型	说明
id	string	自动生成，也可自行指定
title	string	必填，事件标题
subtitle	string	可选，副标题/描述
progress	number	0–100，进度百分比
status	string	active / paused / completed / failed
color	string	马卡龙色：pink mint lavender butter sky rose，或任意 hex
source	string	任务来源：api（外部推送，默认）/ manual（面板手动添加）
taskId 等	string	推送方身份关联字段（taskId / rootTaskId / hostId），接收端原样保留用于关联
session_name	string	可选，宿主会话显示名；卡片底部元信息行与详情弹窗展示为会话上下文
todos	array	可选，结构化待办 [{title, status}]；status ∈ pending / running / done / blocked / skipped / failed。非空时在任务卡内嵌待办行展示

任务不会自动删除：completed / failed 后保留，由面板或外部调用清理接口显式删除。 source 决定面板上的编辑权限：手动任务可双击编辑进度，后台推送任务只读。

接口一览

方法	路径	说明
GET	/api/health	健康检查
GET	/api/events	事件列表（?status=active 过滤）
POST	/api/events	创建事件（传 source:'manual' 标记手动任务）
PATCH	/api/events/:id	更新事件（任意字段）
POST	/api/events/:id/progress	快捷更新进度
DELETE	/api/events/:id	删除单个事件
DELETE	/api/events/completed	一键清理所有已完成事件
DELETE	/api/events	清空所有事件
GET	/api/events/stream	SSE 实时推送（snapshot / upsert / delete）

curl 示例

# 创建事件
curl -X POST http://127.0.0.1:4620/api/events \
  -H 'Content-Type: application/json' \
  -d '{"title":"编译 iOS 包","subtitle":"Release · 3 分钟","progress":20,"color":"sky"}'
# => {"event":{"id":"...","title":"编译 iOS 包",...}}

# 更新进度（面板实时刷新）
curl -X PATCH http://127.0.0.1:4620/api/events/<ID> \
  -H 'Content-Type: application/json' -d '{"progress":66}'

# 标记完成（保留展示，不自动删除）
curl -X PATCH http://127.0.0.1:4620/api/events/<ID> \
  -H 'Content-Type: application/json' -d '{"status":"completed"}'

# 手动添加任务（面板上可双击编辑进度）
curl -X POST http://127.0.0.1:4620/api/events \
  -H 'Content-Type: application/json' \
  -d '{"title":"手动任务","source":"manual","color":"lavender"}'

# 一键清理所有已完成任务
curl -X DELETE http://127.0.0.1:4620/api/events/completed

# 实时订阅（SSE）
curl -N http://127.0.0.1:4620/api/events/stream

进度更新到 100 且未显式指定 status 时，会自动变为 completed； completed 状态的任务保留在面板上，可单个删除（卡片 ×）或一键清理（头部 ✓ 按钮）。

⚙️ 配置

环境变量	生效位置	说明
PORT	内置后端	监听端口，默认 4620
DATA_FILE	内置后端	持久化文件路径；设为 none 关闭持久化

🧱 技术栈

层	技术
桌面端	Tauri 2（Rust 主进程 · 系统标题栏/红绿灯 · 托盘 · 原生拖动）
后端	Rust（std TcpListener，REST + SSE，零第三方 HTTP 依赖）
前端	原生 HTML/CSS/JS（WKWebView，复用马卡龙 UI）
实时通信	SSE（Server-Sent Events）
搜索	pinyin-pro（本地拼音全拼/首字母匹配）

🛣 路线图

• 右上角悬浮面板 · 多事件进度 · 超 4 条折叠
• REST + SSE 实时推送 · 外部 API 调用
• 手动添加 / 双击编辑 · 后台任务只读
• 拼音/模糊本地搜索
• 拖动不出屏 · 边缘吸附 · 高度自适应动画
• Tauri 2 原生重写 · 独立 .app / dmg 打包（约 5.7MB）
• 系统标准标题栏与红绿灯 · 刷新进度条重播
• 开机自启 / 多显示器策略配置

🤝 贡献

欢迎 Issue 与 PR！提交前请确保：

npm run demo  # 端到端冒烟验证

📄 开源许可

MIT © Squirt1e