deepin-dde-expert

name	deepin-dde-expert
description	Use when developing Deepin/UOS desktop applications with DTK widgets, GVfs file operations, DBus system integration, or Polkit authentication. Qt6/Qt5 dual support.

Deepin/UOS DDE Desktop Application Development Expert

Overview

Deepin/UOS 系统级开发专家，精通 DTK、GVfs、DBus、Polkit，开发符合 DDE 规范的应用。

核心原则:

• DTK 优先于 Qt 原生
• GIO 优先于 QFile（网络协议）
• DBus 事件驱动优先于轮询
• Polkit 鉴权优先于 sudo
• Qt6 优先，V20 回退到 Qt5

When to Use

使用当:

• DTK 控件（DMainWindow、DDialog、DMessageBox）
• GVfs 网络协议（smb://、mtp://、dav://）
• DDE DBus 服务集成
• Polkit 权限控制
• DDE 主题适配

不要用: 通用 Qt 应用、命令行工具、服务端开发

Decision Table

场景	决策	参考文档
显示主窗口	DMainWindow 而非 QMainWindow	DTK Widgets
访问 smb:// 路径	GIO GFile 而非 QFile	GVfs/GIO
获取电池/网络状态	DBus 信号监听而非轮询	DBus
修改 /etc 配置	Polkit + Helper 而非 sudo	Polkit
深色/浅色主题适配	applicationPalette() 而非硬编码	DTK Widgets
大文件 I/O	QtConcurrent 后台线程	GVfs/GIO

Core Rules

Rule 1: DTK Widgets (MANDATORY)

Use	Forbidden
DMainWindow	QMainWindow
DDialog	QDialog
DMessageBox	QMessageBox
DWidget	QWidget

// ✅ CORRECT
#include <DMainWindow>
#include <DMessageBox>
DWIDGET_USE_NAMESPACE

DMainWindow *window = new DMainWindow();
DMessageBox::information(this, "Title", "Message");

// ❌ FORBIDDEN
QMainWindow *window = new QMainWindow();

Theme: Use DGuiApplicationHelper::instance()->applicationPalette(), never hardcode colors.

📖 详情: reference/dtk-widgets-guide.md

Rule 2: GVfs/GIO for Network Protocols

// ✅ CORRECT: smb://, mtp://, dav://
#include <gio/gio.h>
GFile *file = g_file_new_for_uri("smb://server/share/file.pdf");
GFileInputStream *input = g_file_read(file, nullptr, &error);

// ❌ FORBIDDEN
QFile file("smb://server/share/file.pdf"); // Fails

Async I/O: Always use QtConcurrent::run() for file operations.

📖 详情: reference/gvfs-gio-integration.md

Rule 3: DBus Event-Driven

// ✅ CORRECT: Listen to signals
QDBusConnection::systemBus().connect(
    "org.freedesktop.UPower",
    "/org/freedesktop/UPower",
    "org.freedesktop.DBus.Properties",
    "PropertiesChanged",
    this, SLOT(handleEvent(QString, QVariantMap)));

// ❌ FORBIDDEN: Polling
QTimer *timer = new QTimer();
connect(timer, &QTimer::timeout, this, [](){
    QFile::read("/sys/class/power_supply/BAT0/capacity");
});

📖 详情: reference/dbus-service-usage.md

Rule 4: Polkit Authentication

// ✅ CORRECT
PolkitQt1::Authority::instance()->checkAuthorizationSync(
    "org.deepin.dde.policy.authentication",
    PolkitQt1::UnixProcessSubject(QCoreApplication::applicationPid()),
    PolkitQt1::Authority::AllowUserInteraction);

// ❌ FORBIDDEN
sudo ./application  // Security risk

📖 详情: reference/polkit-auth-workflow.md

CMake Configuration

See qt-compatibility-build skill for complete Qt6/Qt5 dual support.

find_package(QT NAMES Qt6 Qt5 REQUIRED COMPONENTS Core)
if(QT_VERSION_MAJOR EQUAL 6)
    set(DTK_VERSION_MAJOR 6)
else()
    set(DTK_VERSION_MAJOR "")
endif()

find_package(Qt${QT_VERSION_MAJOR} REQUIRED COMPONENTS Core Gui Widgets)
find_package(Dtk${DTK_VERSION_MAJOR}Widget REQUIRED)

target_link_libraries(app PRIVATE
    Qt${QT_VERSION_MAJOR}::Widgets
    Dtk${DTK_VERSION_MAJOR}::Widget
)

Debian Control Files

See qt-compatibility-build skill for file convention.

File	Deepin	Qt
debian/control	V25	Qt6
debian/control.1	V20	Qt5

Dependencies (V25/Qt6):

Build-Depends:
 qt6-base-dev | qtbase5-dev,
 libdtk6widget-dev | libdtkwidget-dev,
 libpolkit-qt6-1-dev | libpolkit-qt5-1-dev

Gotchas (常见陷阱)

陷阱	后果	修复
GVfs 挂载点 /run/user/UID/gvfs/	路径随会话变化	→ 使用 GIO URI API
DBus 总线类型错误	连接失败	→ System vs Session
Polkit helper 未验证输入	命令注入风险	→ 严格验证路径
非主线程更新 UI	崩溃	→ 信号槽 (QueuedConnection)
忽略 GError	无法诊断问题	→ 检查 error 参数

Code Review Checklist

📖 完整清单: reference/code-review-checklist.md

快速检查:

# 检查 DTK 控件使用
grep -r "QMainWindow\|QDialog\|QMessageBox" src/

# 检查硬编码颜色
grep -rE "#[0-9a-fA-F]{6}" src/

# 检查 GIO 使用
grep -r "g_file_new_for_uri" src/

Related Skills

• qt-compatibility-build: Qt6/Qt5 dual support, CMake configuration, debian/control convention

Reference Documents

• DTK Widgets Guide - 控件使用、主题适配
• GVfs/GIO Integration - 文件操作、异步 I/O
• DBus Service Usage - 系统服务集成
• Polkit Auth Workflow - 权限控制、Helper 模式
• Code Review Checklist - 审查清单