docs: 添加 AGENTS.md 指导文件
包含构建安装、deb打包、架构说明、数据采集方式、翻译注意事项、 QML约定等高价值上下文，帮助后续开发会话快速上手
This commit is contained in:
@@ -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 `<message>` 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.
|
||||
Reference in New Issue
Block a user