From c4743dde125c73672304affa83ce19b0a96e4cb2 Mon Sep 17 00:00:00 2001 From: jokul Date: Tue, 14 Jul 2026 00:25:43 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=20AGENTS.md=20?= =?UTF-8?q?=E6=8C=87=E5=AF=BC=E6=96=87=E4=BB=B6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 包含构建安装、deb打包、架构说明、数据采集方式、翻译注意事项、 QML约定等高价值上下文，帮助后续开发会话快速上手 --- AGENTS.md | 84 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..870d257 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,84 @@ +# AGENTS.md + +## Build & Install + +```bash +# Quick build + install (requires sudo password in terminal) +bash install.sh + +# Or manual: +cmake -Bbuild && cmake --build build +sudo cmake --install build +systemctl --user restart dde-shell@DDE +``` + +- `sudo` requires a real TTY — agent bash tool cannot provide passwords. Tell the user to run install commands in their terminal. +- `install.sh` order: build → remove old → install → restart. If build fails, old plugin is NOT removed (set -e). +- **Never declare a Q_INVOKABLE method or Q_PROPERTY without implementing it before building.** The .so will load but dde-shell will crash with `undefined symbol`, taking down the entire taskbar. + +## Deb Packaging + +```bash +bash build-deb.sh # output to release/ +bash build-deb.sh --install # build + install + restart +``` + +- `dpkg-buildpackage` outputs to `../`, `build-deb.sh` moves artifacts to `release/`. +- `debian/compat` must NOT exist — compat level is declared in `debian/control` via `debhelper-compat (= 13)`. + +## Architecture + +DDE Shell taskbar plugin. C++ backend (`graphicsdriverapplet.cpp`) + QML frontend (`package/driverview.qml`). + +- Root element: `AppletItem` with `import org.deepin.ds.dock 1.0` +- Plugin ID: `org.deepin.ds.graphics-driver`, parent: `org.deepin.ds.dock` +- `dockOrder: 21` = right side of taskbar (20-30 range) +- C++ exposes properties via `Q_PROPERTY` + `Q_INVOKABLE`, QML accesses via `applet` (the `Applet` attached object) +- `PanelPopup` for click popup, `PanelToolTip` for hover tooltip +- `DockPanelPositioner.bounding` must be set before calling `open()` on popup/tooltip + +## LSP False Positives + +The LSP reports errors like `'applet.h' file not found` and `Unknown type name 'DS_BEGIN_NAMESPACE'`. These are **pre-existing and expected** — the dde-shell headers are in `/usr/include/dde-shell/` which LSP doesn't index. Do NOT attempt to fix them. Verify with `cmake --build build` instead. + +## Data Collection (no D-Bus) + +All GPU data is collected directly from sysfs/command-line tools (no D-Bus service): + +| Data | NVIDIA | AMD/Intel | +|------|--------|-----------| +| GPU detect | `lspci -mm` | `lspci -mm` | +| Driver name | `/sys/bus/pci/devices/0000:XX:XX.X/driver` symlink → `symLinkTarget().section('/', -1)` | same | +| Driver version | `/proc/driver/nvidia/version` (regex `Kernel Module\s+(\d+\.\d+\.\d+)`) | `/proc/sys/kernel/osrelease` (prefixed "Linux ") | +| Temperature | `nvidia-smi --query-gpu=...` | `/sys/class/hwmon/hwmonN/temp1_input` (÷1000) | +| GPU usage | `nvidia-smi` | `/sys/class/drm/cardN/device/gpu_busy_percent` | +| VRAM | `nvidia-smi` | `/sys/class/drm/cardN/device/mem_info_vram_*` (bytes → MB) | +| Primary GPU | `/sys/bus/pci/devices/.../boot_vga` = `1` | same | +| GPU mode | Check `/usr/share/X11/xorg.conf.d/nvidia-drm-outputclass.conf` existence → PRIME | — | + +- PCI→DRM card mapping: scan `/sys/bus/pci/devices/0000:XX:XX.X/drm/` for `cardN` entries (regex `^card(\d+)$`). +- `gpuStats` property format: QStringList, one line per GPU: `"temp|gpuUsage|memUsage|memUsed|memTotal"` (-1 = unavailable). +- `nvidia-smi` query: `--query-gpu=pci.bus_id,temperature.gpu,utilization.gpu,utilization.memory,memory.total,memory.used --format=csv,noheader,nounits`. Match by PCI bus ID (last two segments). + +## Translations + +- `.ts` files in `translations/`, compiled to `.qm` at build time via `lrelease`. +- `lrelease` path: `/usr/lib/qt6/bin/lrelease` +- Manual `lupdate` target: `cmake --build build --target update_translations` +- For simple string additions, edit `.ts` files directly (add `` blocks). +- **Watch for Unicode dashes**: previous edits introduced em-dash (U+2014) where ASCII hyphen was intended. The `edit` tool may fail to match strings containing these. Use Python `re.sub` as fallback. + +## QML Conventions + +- Colors derived from `DockPalette.iconTextPalette` (basePalette): `primaryText`, `secondaryText`, `tertiaryText`, `cardBackground`, `cardBorder`, `accentBlue`, `accentBlueLight`. +- Existing JS helper functions in driverview.qml: `parseGpuName()`, `parseDriverInfo()`, `parseDriverName()`, `parseDriverVersion()`, `parseGpuVendorShort()`, `buildToolTipText()`. +- `deviceInfo` format: each line = `"GPU Name (driver version)"`. Parsed by splitting on `(` and `)`. +- Timer pattern: `statsRefreshTimer` (2s interval) starts on popup open AND tooltip hover, stops on close/leave. + +## No Tests + +No test suite exists. Verify changes by building + installing + visually checking the taskbar. + +## Reference Plugin + +`/home/Jokul/Downloads/dde-weather/` — another dde-shell plugin using the same `AppletItem`/`PanelPopup` pattern. Useful reference for UI structure.