# Deepin Dde Expert

> Use when developing Deepin/UOS desktop applications with DTK widgets, GVfs file operations, DBus system integration, or Polkit authentication. Qt6/Qt5 dual support.

- Skill: `re2zero/deepin-dde-expert` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add re2zero/deepin-dde-expert`
- Raw SKILL.md: https://api.skillmd.com/api/skills/re2zero/deepin-dde-expert/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: re2zero (https://skillmd.com/u/re2zero)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/re2zero/deepin-dde-expert

---


# 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](reference/dtk-widgets-guide.md) |
| 访问 `smb://` 路径 | GIO `GFile` 而非 `QFile` | [GVfs/GIO](reference/gvfs-gio-integration.md) |
| 获取电池/网络状态 | DBus 信号监听而非轮询 | [DBus](reference/dbus-service-usage.md) |
| 修改 `/etc` 配置 | Polkit + Helper 而非 sudo | [Polkit](reference/polkit-auth-workflow.md) |
| 深色/浅色主题适配 | `applicationPalette()` 而非硬编码 | [DTK Widgets](reference/dtk-widgets-guide.md) |
| 大文件 I/O | QtConcurrent 后台线程 | [GVfs/GIO](reference/gvfs-gio-integration.md) |

## Core Rules

### Rule 1: DTK Widgets (MANDATORY)

| Use | Forbidden |
|-----|-----------|
| `DMainWindow` | `QMainWindow` |
| `DDialog` | `QDialog` |
| `DMessageBox` | `QMessageBox` |
| `DWidget` | `QWidget` |

```cpp
// ✅ 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](reference/dtk-widgets-guide.md)

### Rule 2: GVfs/GIO for Network Protocols

```cpp
// ✅ 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](reference/gvfs-gio-integration.md)

### Rule 3: DBus Event-Driven

```cpp
// ✅ 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](reference/dbus-service-usage.md)

### Rule 4: Polkit Authentication

```cpp
// ✅ 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](reference/polkit-auth-workflow.md)

## CMake Configuration

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

```cmake
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](reference/code-review-checklist.md)

**快速检查**:
```bash
# 检查 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](reference/dtk-widgets-guide.md) - 控件使用、主题适配
- [GVfs/GIO Integration](reference/gvfs-gio-integration.md) - 文件操作、异步 I/O
- [DBus Service Usage](reference/dbus-service-usage.md) - 系统服务集成
- [Polkit Auth Workflow](reference/polkit-auth-workflow.md) - 权限控制、Helper 模式
- [Code Review Checklist](reference/code-review-checklist.md) - 审查清单