一、项目文档

1. 项目简介

DDE Shell Dock 硬件监控插件（org.deepin.ds.dock.hwmonitor）是一个运行在 deepin/UOS v25（dde-shell 2.x）任务栏（Dock）上的插件，直接在任务栏中以文字形式实时显示本机硬件信息，左键点击可弹出设置面板进行个性化配置。

代码仓库在GitHub：https://github.com/crazy-zxx/dde-dock-hwmonitor

2. 功能特性

3. 安装方式

方式一：.deb 包（推荐分发）

# 一键打包
./build-deb.sh                    # 生成 dde-dock-hwmonitor_1.0.8_amd64.deb
./build-deb.sh 1.1.0              # 指定版本号

# 安装（对方机器）
sudo apt install ./dde-dock-hwmonitor_1.0.8_amd64.deb

# 卸载
sudo apt remove dde-dock-hwmonitor

deb 包安装内容：插件库、QML 界面、DConfig 元数据、23 种语言翻译、开始菜单 .desktop 入口 + 多尺寸 PNG/SVG 图标、启动脚本 /usr/bin/hwmonitor-launcher。

方式二：源码构建

cmake -B build -G Ninja -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_BUILD_TYPE=Release
cmake --build build
sudo cmake --install build
systemctl --user restart dde-shell@DDE.service

依赖：libdde-shell-dev(≥2.0)、libdtk6core-dev、libdtk6gui-dev、qt6-base-dev、qt6-declarative-dev、qt6-tools-dev、cmake、ninja。

适用范围：Deepin 25 / UOS 25（dde-shell 2.x，amd64）。

4. 使用说明

1. 安装并重启任务栏后，监控文字显示在任务栏（默认左侧、双行，可在设置面板调整）。
2. 左键点击监控文字 → 打开设置面板，可配置：
   • 监控项勾选/排序、单行/双行、左侧/右侧位置
   • 监视网卡、文字字体/大小、文字颜色（亮/暗主题分别设置 + 还原默认）
   • 每个条目的占位字符宽度
   • 「退出程序」按钮
3. 退出程序：点击后关闭设置面板、停止监控、退出进程（任务栏 1 秒后自动恢复），插件保持隐藏。
4. 重新启用：到开始菜单点击「硬件监控」图标（启动脚本带单实例锁：已运行则空操作，已退出则重新启用并刷新任务栏）。

5. 技术架构

数据来源：CPU /proc/stat（两次采样差值）、内存 /proc/meminfo、GPU sysfs gpu_busy_percent 或 nvidia-smi、温度 /sys/class/hwmon/*/temp*_input、网速 /proc/net/dev。

二、开发过程说明（deepin Skills 辅助开发）
1. 技术选型
需求是"任务栏（Dock）上的硬件监控 + 点击弹出设置面板"。通过 dde-shell-development skill 判断：这属于 dde-shell 插件体系（DApplet → Containment → Panel 三层模型），根元素用 AppletItem，插件 ID 规则 org.deepin.ds.dock.*，Plugin.Parent 指向 org.deepin.ds.dock，而不是 dde-tray-loader 的 PluginsItemInterfaceV2 托盘体系。
2. 使用的 deepin Skills 及作用



Skill
作用




dde-shell-development
核心。查插件体系结构、AppletItem QML API、DApplet/DContainment 生命周期、插件元数据、CMake 辅助函数（ds_install_package）、插件发现与加载排查


dtk-development
配合使用。DConfig 配置持久化、DTK 控件（D.SpinBox/D.ComboBox/D.RadioButton）、主题与调色板


dde-tray-development
评估后不适用（托盘插件体系与 dde-shell 体系不同），仅用于排除干扰


dde-control-center-development
不适用（本项目不涉及控制中心模块）



3. 各阶段的 Skill 调用与实现
3.1 插件骨架搭建（dde-shell-development）

读取 skill 的 references/plugin-development.md、references/api/qml-api.md、references/api/core.md：

确认根元素用 AppletItem，附加属性 Applet（id/pluginId/parent/rootObject）
确认 D_APPLET_CLASS(HwMonitorApplet) + #include "xxx.moc" 工厂注册，缺了会导致编译通过但无法加载
确认 Parent 必须是 org.deepin.ds.dock
确认 CMake 用 ds_install_package 安装插件包、DConfig 元数据装到 /usr/share/dsg/configs/org.deepin.dde.shell/


实现 hwmonitorapplet.cpp：构造 → load()（创建 Settings/Backend）→ init()（启动采集、主题联动）。

3.2 硬件数据采集（dtk-development 配合）

MonitorBackend 用 QTimer 定时刷新：CPU /proc/stat 差值、内存 /proc/meminfo、网速 /proc/net/dev（排除 lo）、温度 sysfs、GPU 兼容 amdgpu/nvidia。
踩坑：/proc 虚拟文件 size=0，while(!atEnd()) 一次都不读 → 改用 readAll() 解析，解决"内存/网速一直 0"。

3.3 设置面板（dtk-development：DConfig + DTK 控件）

Settings 封装 DConfig 读写（themeMode/displayMode/dockPosition/netInterface/itemOrder/itemVisible/itemWidth/fontFamily/fontSize/颜色/enabled）。
SettingsPanel.qml 用 D.RadioButton/D.ComboBox/D.SpinBox/D.CheckBox/D.Switch/D.ToolButton/D.Button 实现全部设置项。

3.4 对话中迭代解决的具体问题（按时间线）

内存/网速显示 0 → 修复 /proc 读取方式。
网速一直 0 → 设置面板增加「监视网卡」下拉选择（netInterface）。
显示位置 → 增加 left/right 选项（dockOrder：左 5 / 右 21）。
数值变化导致图标抖动 → 每个条目增加占位字符宽度 width_*，等宽字体 + 左对齐。
文案与排序 → '内存'→'MEM'，默认排序 CPU→GPU→MEM→CPU温度→GPU温度→网速。
面板内容超出看不到 → 加 Flickable + ScrollBar 滚动。
等宽字体 → 提供字体选择（默认 DejaVu Sans Mono）、字号（6~24px）、文字颜色 + 还原默认按钮。
字号 SpinBox 输入回车后上下按钮失效（最难的问题）：

最初尝试 finishEdit()，经查 Qt 6.8 qquickspinbox_p.h 源码确认该方法已被移除，会报 TypeError；
深挖发现根因：DTK SpinBox 获得焦点后上下按钮切换为内部 Button，其 onClicked 调用 increase()/decrease() 只发 valueChanged 不发 valueModified，导致设置不保存；
修复：监听 onValueChanged 写回，并用 initialized 标志防止 C++ componentComplete() 阶段把默认值 0 钳制到 6 时误写配置（曾导致 fontSize 被写成 6）；
同步修复条目宽度 SpinBox 的同类问题。


退出程序按钮 → 需求演进：关闭面板 + 持久化 enabled=false + 停止后端采集 + Qt.quit() 退出进程（利用 dde-shell@DDE.service 的 Restart=always 1 秒自动恢复任务栏）。
开始菜单图标 → deb 装 .desktop + SVG/多尺寸 PNG 图标；排查"图标不显示"发现是 Icon= 名与文件名不匹配；启动脚本 hwmonitor-launcher 加 flock 单实例锁 + 运行状态检查，防止重复点击重复启动。

3.5 构建、打包与测试验证

构建/打包：CMake 源码安装 + build-deb.sh 一键打 deb（含 postinst 自动刷新 DConfig/桌面数据库/图标缓存），本机用 pkexec dpkg -i 纳入 dpkg 管理。
测试验证方法（X11 环境）：

dde-shell --list 确认插件被发现；
journalctl --user 查 [hwmonitor] applet constructed/load/init 与 QML 错误；
ffmpeg x11grab 截屏 + tesseract OCR 定位任务栏/面板控件坐标，用 xdotool 模拟点击/输入做端到端验证（如：输入字号 12+回车→点向上按钮→配置 12→13）；
dde-dconfig get/set 直接读写配置验证持久化与"退出/重新启用"机制。



4. 总结
整个开发以 dde-shell-development skill 为纲（确定插件体系、Applet 生命周期、QML API、打包与加载排查），dtk-development skill 为辅（DConfig 持久化、DTK 控件、主题），从骨架搭建、数据采集、设置面板到打包分发逐步完成。过程中通过"阅读 skill 参考文档 → 定位宿主源码（Qt/dtkdeclarative）→ 截屏 OCR + xdotool 端到端实测"的方式解决了 /proc 读取、SpinBox 聚焦失效、图标命名等实际问题，最终交付了功能完整、可打包分发（deb + 开始菜单入口 + 单实例启动）的 Dock 硬件监控插件。