【deepin插件开发活动】dtk-update —— 跨发行版 DTK 系统更新管理托盘插件

参赛方向：方向二（任务栏托盘插件，基于 dde-tray-development）+ 方向三（DTK 创新原生应用，基于 dtk-development）
参赛作品版本：0.0.2（2026-08-20 发布）

一、作品简介

dtk-update 是一个基于 DTK6 的系统更新管理托盘小程序：它在 DDE 任务栏以托盘插件形式常驻，监控系统软件包更新并托管更新、安装、卸载、清理等操作。与一般更新器"绑死某个发行版"不同，dtk-update 把包管理操作放在可插拔后端抽象之下，统一委托给系统包管理器（apt/dpkg、dnf/rpm、pacman、zypper、linyaps/玲珑 等），因此一份代码可以跨 deepin/UOS、Debian、Ubuntu、Fedora、Arch、openSUSE 等多个发行系运行，并天然支持玲珑、snap、flatpak 等跨发行系沙箱应用生态。

项目提供四种形态的入口：deepin/UOS 任务栏托盘插件（PluginsItemInterfaceV2）、不依赖 dde-dock 私有接口的 freedesktop 通用托盘（QSystemTrayIcon）、独立 DTK 主窗口（dtk-update-gui）、以及可选的 D-Bus/systemd 用户守护进程（dtk-update-daemon）。四个入口共用同一份 src/indicator 共享核心与 src/core 纯业务逻辑，保证行为一致。

二、源码仓库

• 仓库地址：https://github.com/taotieren/dtk-update
• 开源协议：GPL-3.0-or-later（OSI 批准，符合活动建议的 GPL/LGPL 要求）
• 独立仓库、可单独构建与安装：GitHub Actions 提供完整 CI，可一键构建 amd64 / arm64 / loong64 三架构 .deb（见下）
• Release 下载页：https://github.com/taotieren/dtk-update/releases

三、功能特性（功能介绍）

3.1 核心能力

• 更新 / 安装 / 卸载 / 清除 / 自动移除 / 清理：完整覆盖日常包管理操作；所有写操作统一经 pkexec/polkit 提权执行，绝不在进程内 sudo，进程级并发锁防止 GUI 与托盘同时触发系统写入。
• 多后端可插拔：PackageBackend 抽象接口 + BackendFactory 自动探测。系统后端按发行系自动匹配（apt→Debian 系、dnf→Fedora 系、pacman→Arch 系、zypper→openSUSE 系）；沙箱后端（linyaps/玲珑、snap、flatpak）与发行系正交、逐个独立探测，0/1/N 个均合法。新增一个发行版只需继承基类、登记注册表两步，无需改动任何 UI。
• 依赖解析：基于后端 dry-run 输出解析（APT ^Inst/ 与 DNF Installing: 格式分流），无结构化输出的后端优雅降级为仅目标包而非失败。
• 预检 / 后检健康检查：内核待重启、服务待重启、配置待审阅（.rpmnew/.rpmsave/.rpmorig、Arch *.pacnew/*.pacsave/*.pacorig）、失败的 systemd 单元——均为只读探测、绝不自动处理；具备容器感知，容器内自动跳过宿主状态检查避免误报。pacman（Arch/Manjaro）与 zypper（openSUSE/SLES）作为系统级后端已实现并完整登记，与 apt/dnf 同属发行系强绑定后端，不进入沙箱后端列表。
• 安全公告聚合：按发行版自动选择上游官方源（Debian DSA / Ubuntu USN / openSUSE / Arch），异步预取并缓存，更新流程内同步合并、绝不阻塞更新；同时聚合 deepin 安全中心 D-Bus 公告，离线时有启发式兜底。
• 发行版最近新闻 / 通知：独立于包名，按发行版从官网/公告服务异步拉取，在托盘/GUI 弹出信息性通知。
• 残留与缓存报告：更新后报告残留包（rc 状态包、孤儿包）与可清理的下载缓存，交由用户显式清理，绝不自动删除。
• 透明配置：DConfig 与用户可编辑的 backend.conf（INI 风格），优先级为用户段 > 全局段 > DConfig > 发行版预设。
• 本地化：简体中文、英语、西班牙语、法语、德语五种语言。

3.2 设计亮点

• 更新确认框默认聚焦「取消」按钮；安全公告与预检结果展示后由用户显式确认才继续——绝不替用户做任何决定。
• src/core 保持与 UI 完全无关、可独立单元测试（GoogleTest，全量 70+ 用例）；包管理命令、输出解析、可用性探测全部下沉到具体后端。
• 托盘插件严格遵循 PluginsItemInterfaceV2（IID com.deepin.dock.PluginsItemInterface_V2），Type_Tray | Attribute_CanSetting，图标使用主题图标，翻译在 init() 内自行加载。

四、技术架构

src/core      纯业务逻辑（与 UI 无关，完整单元测试）
package/      PackageBackend(抽象) · Apt/Dnf/Pacman/Zypper(系统后端)
· Linyaps/Snap/Flatpak(沙箱后端) · BackendFactory · PackageParser
dependency/   DependencyResolver（后端 dry-run 解析）
security/     SecurityAdvisor（deepin 安全中心 D-Bus + 上游公告 + 最近通知）
healthcheck/  PreUpdateCheck / PostUpdateCheck（预检/后检，只读探测）
monitor/      UpdateMonitor（状态机 + 定时调度，聚合沙箱后端）
src/indicator  UpdateIndicator（与桌面环境解耦的共享核心，两个托盘复用）+ UpdateDialogs
src/tray       dde-tray-loader 插件（PluginsItemInterfaceV2，仅 deepin/UOS）
src/tray-generic  跨发行系 freedesktop 托盘（QSystemTrayIcon，无 dde-dock 私有依赖）
src/ui         独立 DTK 主窗口（DMainWindow）
src/daemon     后台 D-Bus 服务（com.dtk.update.Daemon）
tests          core 层 GoogleTest 单元测试

核心设计约束：包管理写操作一律 pkexec 提权；src/core 禁止包含 Dock/Tray/UI 头文件；后端接线集中化（attachSandboxBackends 一行调用接入全部沙箱后端）；一切探测只读、一切写操作先经用户确认。

五、安装方式

5.1 从 Release 安装（推荐，deepin 25 / UOS v25）

从 https://github.com/taotieren/dtk-update/releases 下载对应架构的 .deb（支持 amd64 / arm64 / loong64 三架构），然后：

sudo apt install ./dtk-update_0.0.2_<架构>.deb

安装完成后，deepin 25 任务栏即可在托盘区域看到 dtk-update 图标；dtk-update-gui 主窗口与 dtk-update-tray-generic 通用托盘、dtk-update-daemon 守护进程同步安装。

5.2 从源码构建

编译依赖（Debian/Ubuntu/Deepin/UOS 下，与 debian/control 的 Build-Depends 一致）：

sudo apt-get install -y \
  cmake debhelper-compat pkg-config \
  qt6-base-dev qt6-tools-dev \
  libdtk6core-dev libdtk6gui-dev libdtk6widget-dev libdtk6log-dev \
  libgtest-dev libpolkit-qt6-1-dev libxkbcommon-dev

dde-dock-dev 为可选依赖：仅存在于 deepin/UOS 源（beige 中由 dde-tray-loader-dev 提供）。未安装时 CMake 自动跳过 src/tray 插件，其余目标照常编译；在 deepin 25 上安装它即可编出完整托盘插件。

git clone https://github.com/taotieren/dtk-update.git
cd dtk-update && mkdir build && cd build
cmake ..
make -j$(nproc)
ctest --output-on-failure   # 单元测试
sudo make install

5.3 卸载

sudo apt remove dtk-update

六、使用说明

1. 托盘插件：deepin 25 任务栏托盘区常驻图标。图标状态即系统更新状态（有可用更新、已是最新、后端不可用均有对应提示）；右键菜单提供"立即检查更新""查看可用更新"等入口；左键点击弹出更新确认对话框。
2. 更新流程：点击更新 → 显示可升级包列表与安全公告/预检结果 → 用户显式确认（默认焦点在「取消」）→ 后台异步执行 → 完成后展示后检报告（含待重启提示、残留包、可清理缓存），由用户决定是否处理。
3. 通用托盘（dtk-update-tray-generic）：在非 deepin 发行系（Ubuntu/Fedora/Arch/openSUSE 等）提供同样的更新管理能力，随系统自启；NotShowIn=deepin 避免 deepin 上出现重复托盘。
4. 图形界面（dtk-update-gui）：独立主窗口，展示完整更新状态、包列表、安全公告与配置（--show-config 查看当前配置）。
5. 守护进程（dtk-update-daemon）：可选后台服务，订阅系统唤醒与网络状态变化，恢复联网/唤醒后自动触发检查；systemd 用户服务管理。

七、演示截图（3-5 张）

说明：以下为建议截图清单，正式发帖时在此处插入实际截图。

• 截图 1：deepin 25 任务栏托盘图标状态展示（有可用更新时）
• 截图 2：更新确认对话框（含可升级包列表、安全公告/预检结果、默认聚焦取消按钮）
• 截图 3：dtk-update-gui 主窗口（更新状态 + 包列表 + 配置页）
• 截图 4：通用托盘在非 deepin 发行系（如 Arch/Fedora）上运行效果
• 截图 5：更新完成后的后检报告（待重启提示、残留包与缓存清理建议）

八、开发过程与 deepin Skills 的使用

8.1 使用的 deepin Skills 模块

本作品在开发全程通过 CodeBuddy（AI 编程工具）加载并使用 deepin 官方 Skills，主要包括：

Skill 模块	用途
dde-tray-development	实现 deepin/UOS 任务栏托盘插件：PluginsItemInterfaceV2 接口（IID com.deepin.dock.PluginsItemInterface_V2）、flags（Type_Tray | Attribute_CanSetting）、icon() 主题图标、init() 内加载翻译等托盘插件规范
dtk-development	DTK6 桌面应用/插件开发规范：DApplication、DMainWindow、DConfig、DCI 图标、DLogManager；debian 打包依赖按 DTK 模块映射；兼容 DTK5 自动探测
github-actions-templates	生成 CI 工作流：单元测试流水线（ubuntu:devel）与打包流水线（debootstrap deepin beige chroot + qemu 模拟 loong64，产出三架构 .deb）
codebuddy-md-improver	审计并维护仓库 AGENTS.md 项目指南（架构约束、已知坑、发行纪律）

开发中 deepin Skills 的关键帮助点：

• 托盘插件规范零踩坑：dde-tray-development 直接注入了 V2 接口的 IID 字符串、PluginFlags 用法、消息协议等规范，避免了"插件装不上/不显示"的常见坑。
• DTK6 正确用法：dtk-development 覆盖了 DConfig 配置、DCI 图标资源、polkit 提权（pkexec）集成方式，保证写操作安全合规。
• 文档纪律：codebuddy-md-improver 帮助我们维护 AGENTS.md，把"已踩过的坑"（如 CMake install DESTINATION 与 dh 前缀的错位、Qt6 D-Bus 旧式 SLOT 连接、clang-format 门禁）固化下来，避免团队/AI 重复犯错。

8.2 引用与二次开发说明

项目模块划分思路参考了开源项目 arch-update（预检/后检分离、托盘集成、配置透明化）；包管理实现针对多发行版通过可插拔后端抽象重写，未直接照搬其 Rust 实现。引用部分已在 README 中说明。

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

说明：正式发帖时在此处插入 CodeBuddy 中实际调用 deepin Skills 的对话记录截图。

• 截图 A：加载 dde-tray-development 技能并按其规范实现 PluginsItemInterfaceV2 托盘插件的对话记录
• 截图 B：加载 dtk-development 技能进行 DTK6 主窗口 / DConfig / DCI 图标开发的对话记录
• 截图 C：加载 github-actions-templates 生成多架构 CI 打包流水线的对话记录

九、与活动要求的对照

• 方向契合：方向二（任务栏托盘插件，dde-tray-development）+ 方向三（DTK 原生应用 dtk-update-gui，dtk-development）。
• 必须使用 deepin Skills：是，见 8.1 节表格。
• 必须开源：GPL-3.0-or-later，完整源码在 GitHub 公开。
• 必须可独立构建：独立仓库，debian/control 完整声明 Build-Depends，CI 三架构自动打包验证。
• 环境兼容性：CI 在 deepin beige（deepin 25 底座）chroot 中完成构建与打包；托盘插件基于 dde-tray-loader（deepin 25 任务栏）V2 接口；GUI 基于 DTK6。
• 架构支持：amd64 / arm64 / loong64 三架构 .deb（活动要求至少 amd64，本作品额外覆盖 arm64、loong64）。
• 评审维度预检：功能完整性（六大操作 + 预检后检 + 安全公告）、真实使用价值（日常更新管理刚需）、创新性（跨发行版可插拔后端 + 双托盘双 UI + 守护进程的多入口架构）、UI/UX（DTK 控件、托盘交互、默认聚焦取消的安全交互设计）、代码质量（分层架构、70+ 单元测试、CI 静态门禁）。

十、已知限制

• dde-dock 托盘插件仅在提供 dde-tray-loader-dev 的 deepin 系打包环境中编入 .deb；其他发行系自动跳过该插件，仅发布通用托盘 + GUI + 守护进程。
• 沙箱后端（snap/flatpak/linyaps）依赖各自运行环境健康，未安装或运行时损坏时静默不接入，不影响系统后端聚合。
• 上游公告/通知为可选能力，默认关闭，需用户在配置中显式开启。

十一、版本与维护者信息

11.1 版本

• 当前版本：0.0.2（2026-08-20 发布）
• 仓库：https://github.com/taotieren/dtk-update
• Release 下载页：https://github.com/taotieren/dtk-update/releases
• 协议：GPL-3.0-or-later

11.2 维护者

维护者信息复用仓库 git 配置（git config user.name / git config user.email）：

• 维护者名称：taotieren
• 联系邮箱：admin@taotieren.com
• GitHub 主页：https://github.com/taotieren
• 远程仓库：https://github.com/taotieren/dtk-update（git@github.com:taotieren/dtk-update.git）