【deepin插件开发活动】专注一刻 FocusFlow — Dock 番茄钟插件

一个嵌入 deepin v25 Dock 的番茄钟 / 专注计时 Applet。
纯 QML、零原生编译依赖，轻量常驻，帮你在一呼一吸间进入深度工作状态。

源码仓库

AtomGit：https://atomgit.com/feidaojun/ds-focusflow
克隆：git clone https://atomgit.com/feidaojun/ds-focusflow.git
协议：GPL-3.0-or-later
独立仓库，可单独构建与安装。

功能介绍

Dock 常驻：进度环 + mm:ss 常驻 Dock，一眼掌握剩余专注时间。
三种模式：专注 25min / 深度 45min / 小憩 5min，一键切换。
完整控制面板：点击图标弹出 PanelPopup，含开始 / 暂停 / 重置与模式预设。
今日专注数：自动累计当天完成的专注轮次。
状态可视化：计时中环呼吸闪烁；结束时提示休息。
背景色可选：弹窗内置「跟随主题 + 米杏 / 薄荷 / 雾蓝 / 樱粉 / 暖紫」六种底色，深浅主题自动取对应变体。

安装方式

# 1. 安装依赖（deepin v25）
sudo apt update
sudo apt install -y libdde-shell-dev cmake qt6-base-dev

# 2. 构建
cd ds-focusflow
cmake -B build -DCMAKE_INSTALL_PREFIX=/usr
cmake --build build -j$(nproc)

# 3. 安装
sudo cmake --install build

# 4. 重启 dde-shell
systemctl --user restart dde-shell@DDE

安装后插件会被 DPluginLoader 扫描到，并作为 org.deepin.ds.dock 的子项出现在 Dock 上。

使用说明

安装重启后，Dock 上出现 专注一刻 进度环图标。
点击图标弹出控制面板。
选择模式，点击开始进入倒计时。
可随时暂停 / 重置；Dock 图标与弹窗同步显示剩余时间。
一轮结束，提示「时间到，喝口水、远眺一下」。

效果截图

空闲态	计时中

控制面板	小憩模式

不同主题适配

开发过程说明

本项目基于 AtomGit linuxdeepin/deepin-skills 仓库的 dde-shell-development Skill 完成。

AI 编程工具（WorkBuddy）加载该 Skill 后，按以下路径辅助开发：

SKILL.md：快速判定适合「纯 QML Applet」路线，宿主选 Dock。
references/design.md：确认 org.deepin.ds.dock 父插件与安装路径。
references/plugin-development.md：得到目录结构、元数据字段、ds_install_package 用法和测试命令。
references/api/qml-api.md：使用 AppletItem 作根、PanelPopup 作弹窗。
references/gotchas.md：自检 Plugin.Id / Parent 一致、弹窗不滥用排除区。
assets/：参考 Package.qml / CMakeLists.txt 模板生成实际文件。

AI 编程工具中调用 deepin Skills 的对话记录截图：

详细模块对照与代码落点见仓库 DEV.md。

实践踩坑与解法

这几处官方文档没有明说，是deepin v25 / dde-shell 2.0.52实测出来的，供后来者参考：

现象	根因	解法
Dock 上完全看不到图标	纯 QML Applet 没有 `.so`，落到基类 `DApplet`，没有 `visible` 属性；`shouldVisible: Applet.visible` 得到 `undefined` 当作 false，被 `DockPartAppletModel` 过滤	`shouldVisible` 直接给 `true`（模型规则是「未定义或 true 即显示」）
装完新版本但图标状态没变	DBus 的 `DockPanel::ReloadPlugins()` 在当前版本是空实现（源码里只有 `// TODO`）	直接重启 `dde-shell`，不要依赖平滑重载
改了 QML 却装回旧文件	`ds_install_package` 在 cmake 配置阶段就复制 `package/`，沿用旧 `build/` 目录会重装旧版本	安装脚本每次强制重新 configure + build
引入 `D.Palette` 后图标消失	分组写法（`normal { common: ... }`）来自上游 master，本机 dtkdeclarative 只支持扁平写法；纯 QML Applet 上也无成功先例	改用 Qt 原生 `SystemPalette`，零 DTK 依赖地跟随深浅色主题
想持久化用户偏好	本机 QML 运行环境没有 `QtQuick.LocalStorage` / `Qt.labs.settings`，dde-shell 插件层也无存储 API	偏好项（如背景色）仅在会话内记忆；新增 import 前务必先在本机验证模块存在