docs: 更新AGENTS.md文档

- 反映当前C++和QML混合架构
- 添加项目结构和架构说明
- 添加功能特性和C++后端接口说明

AGENTS.md

@@ -6,12 +6,21 @@ Guidance for AI agents working in this repo. Verified against `CMakeLists.txt`,
 
 ## What this is
 
-A **pure-QML dde-shell applet** (deepin desktop shell panel widget). There is no
+A **dde-shell applet** (deepin desktop shell panel widget) for network speed monitoring.
-C++ and no `.so` plugin — the entire applet is `package/main.qml` +
+Uses a C++ backend (`NetworkMonitorApplet` class) for data collection and a QML frontend
-`package/metadata.json`, installed as a data package via dde-shell's CMake macros.
+for the UI. The C++ backend reads `/proc/net/dev` to monitor network traffic.
 
 - Applet ID: `space.jokul.JNetApplet`.
-- Root element of `main.qml` must be `AppletItem` from `import org.deepin.ds 1.0`.
+- Root element of `networkview.qml` must be `AppletItem` from `import org.deepin.ds 1.0`.
+
+## Features
+
+- Real-time download/upload speed monitoring (1-second refresh)
+- Total data transfer statistics
+- Multiple network interface support with interface switching
+- Taskbar icon displays live speed (changes color at high speeds)
+- Hover tooltip shows speed summary
+- Click to open detailed popup
 
 ## Build & install
 
@@ -24,55 +33,86 @@ cmake --build build
 sudo cmake --install build   # -> /usr/share/dde-shell/space.jokul.JNetApplet/
 ```
 
-`cmake --install` needs `sudo` because the default `DDE_SHELL_PACKAGE_INSTALL_DIR`
+Or use the install script:
-is `/usr/share/dde-shell` (a CMake CACHE variable on this system). For a user-local
-install instead:
 
 ```sh
-cmake -B build -DCMAKE_INSTALL_PREFIX=$HOME/.local
+bash install.sh
-cmake --build build && cmake --install build   # -> ~/.local/share/dde-shell/space.jokul.JNetApplet/
+```
+
+`cmake --install` needs `sudo` because the default `DDE_SHELL_PACKAGE_INSTALL_DIR`
+is `/usr/share/dde-shell` (a CMake CACHE variable on this system).
+
+After installation, restart dde-shell:
+
+```sh
+systemctl --user restart dde-shell@DDE
 ```
 
 There is no test, lint, typecheck, or CI target. Verification is manual: install,
 then restart `dde-shell` (it discovers applets by scanning the install dir for
-`metadata.json`). The build also stages a copy at `build/packages/space.jokul.JNetApplet/`
+`metadata.json`).
-for previewing the QML without installing.
+
+## Project structure
+
+```
+├── CMakeLists.txt                 # Build configuration
+├── install.sh                     # Install script
+├── networkmonitorapplet.h         # C++ backend header
+├── networkmonitorapplet.cpp       # C++ backend implementation
+├── package/
+│   ├── metadata.json              # Plugin metadata
+│   └── networkview.qml            # QML UI
+└── AGENTS.md                      # This file
+```
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────┐
+│              DDE Shell Taskbar                   │
+├──────────────────────────────────────────────────┤
+│        space.jokul.JNetApplet                    │
+│  ┌────────────────┐  ┌────────────────────────┐  │
+│  │ C++ Backend    │  │ QML Frontend           │  │
+│  │ NetworkMonitor │  │ networkview.qml        │  │
+│  │ - /proc/net/dev│  │ - Speed display        │  │
+│  │ - Speed calc   │  │ - Popup window         │  │
+│  │ - Interface    │  │ - Interface switcher   │  │
+│  └────────────────┘  └────────────────────────┘  │
+└──────────────────────────────────────────────────┘
+```
+
+## C++ Backend (NetworkMonitorApplet)
+
+Inherits from `DApplet`, provides:
+- `downloadSpeed` / `uploadSpeed`: Current speed in bytes/sec
+- `totalDownload` / `totalUpload`: Total data transferred
+- `networkInterfaces`: List of available interfaces
+- `interfaceStats`: Per-interface statistics
+- `activeInterface`: Currently selected interface
+- `refresh()`: Manually trigger stats update
+- `setActiveInterface(name)`: Switch active interface
 
 ## Identifier correspondence (keep in sync when renaming)
 
 | Where | Field | Value |
 |---|---|---|
-| `CMakeLists.txt` | `ds_install_package(PACKAGE …)` | `space.jokul.JNetApplet` |
+| `CMakeLists.txt` | `add_library(...)` target | `space.jokul.JNetApplet` |
+| `CMakeLists.txt` | `PLUGIN_ID` | `space.jokul.JNetApplet` |
 | `package/metadata.json` | `Plugin.Id` | `space.jokul.JNetApplet` |
 
-The CMake `PACKAGE` becomes the install subdirectory name; `Plugin.Id` is the runtime
+`Plugin.Url` (`networkview.qml`) is a path **relative to `package/`**, not an identifier.
-identifier. They don't technically have to match, but every official dde-shell applet
-keeps them identical — treat them as required to match.
-
-`Plugin.Url` (`main.qml`) is a path **relative to `package/`**, not an identifier.
 Keep it pointing at the entry QML.
 
 ## Required metadata fields (QML applet)
 
-`metadata.json` must contain `Plugin.Version`, `Plugin.Id`, and `Plugin.Url`. The
+`metadata.json` must contain `Plugin.Version`, `Plugin.Id`, `Plugin.Url`, and
-current file is complete — don't drop any. (`Plugin.Url` is omitted only for
+`Plugin.Parent`. The current file is complete — don't drop any.
-widget-based, non-QML plugins.)
-
-## Package layout is fixed by the macro
-
-`ds_install_package` reads `package/` relative to `CMAKE_CURRENT_SOURCE_DIR` by
-default (overridable via `PACKAGE_ROOT_DIR`, not used here). Keep the directory named
-`package/` with `metadata.json` at its root.
-
-## Adding translations (not yet set up)
-
-If i18n is needed, use the `ds_handle_package(PACKAGE <id>)` macro from the same
-DDEShell package. It expects `.ts` files at `translations/<id>_<lang>.ts` and
-installs compiled `.qm` to `${DDE_SHELL_TRANSLATION_INSTALL_DIR}/<id>/translations/`.
-Do not invent a different translation workflow.
 
 ## Conventions
 
 - QML files carry SPDX headers (`SPDX-FileCopyrightText` +
   `SPDX-License-Identifier: LGPL-3.0-or-later`). Preserve on new/edited QML files.
+- C++ files carry SPDX headers (`SPDX-License-Identifier: LGPL-3.0-or-later`).
 - Default branch is `master` (not `main`).
+- QML property types must be QML-compatible (use `double`/`real` instead of `qint64`).