From ab1a5227fae3b6d6329c98b6f25b4a64a22e5f58 Mon Sep 17 00:00:00 2001
From: Jokul <wangshengshan011@163.com>
Date: Sat, 18 Jul 2026 19:48:31 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=20README=20=E4=B8=8E?=
 =?UTF-8?q?=20AGENTS=20=E8=AF=B4=E6=98=8E=EF=BC=8C=E8=A1=A5=E5=85=85=20deb?=
 =?UTF-8?q?=20=E6=89=93=E5=8C=85=E4=B8=8E=E6=9C=80=E6=96=B0=E5=8A=9F?=
 =?UTF-8?q?=E8=83=BD?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 AGENTS.md | 13 ++++++++++
 README.md | 74 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 87 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index aaadd1f..f2ede0b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -21,6 +21,8 @@ for the UI. The C++ backend reads `/proc/net/dev` to monitor network traffic.
 - Taskbar icon displays live speed (changes color at high speeds)
 - Hover tooltip shows speed summary
 - Click to open detailed popup
+- Popup shows active interface IP address, per-interface speed comparison and stats
+- One-click plugin uninstall from the popup
 
 ## Build & install
 
@@ -42,6 +44,14 @@ bash install.sh
 `cmake --install` needs `sudo` because the default `DDE_SHELL_PACKAGE_INSTALL_DIR`
 is `/usr/share/dde-shell` (a CMake CACHE variable on this system).
 
+### Deb packaging
+
+`build-deb.sh` builds a `.deb` from the version declared in `CMakeLists.txt`:
+
+```sh
+bash build-deb.sh   # -> jnetapplet_<version>_<arch>.deb
+```
+
 After installation, restart dde-shell:
 
 ```sh
@@ -57,11 +67,13 @@ then restart `dde-shell` (it discovers applets by scanning the install dir for
 ```
 ├── CMakeLists.txt                 # Build configuration
 ├── install.sh                     # Install script
+├── build-deb.sh                   # Deb packaging script
 ├── networkmonitorapplet.h         # C++ backend header
 ├── networkmonitorapplet.cpp       # C++ backend implementation
 ├── package/
 │   ├── metadata.json              # Plugin metadata
 │   └── networkview.qml            # QML UI
+├── docs/                          # Design docs and implementation plans
 └── AGENTS.md                      # This file
 ```
 
@@ -90,6 +102,7 @@ Inherits from `DApplet`, provides:
 - `networkInterfaces`: List of available interfaces
 - `interfaceStats`: Per-interface statistics
 - `activeInterface`: Currently selected interface
+- `ipAddress`: IP address of the active interface
 - `refresh()`: Manually trigger stats update
 - `setActiveInterface(name)`: Switch active interface
 
diff --git a/README.md b/README.md
index 20713d5..91d7490 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,76 @@
 # JNetApplet
 
+基于 dde-shell 的**深度系统任务栏网络速率监控插件**，使用 C++ 后端采集数据、
+QML 前端渲染界面，实时显示当前网卡的上行/下行速率与累计流量。
+
+- 插件 ID：`space.jokul.JNetApplet`
+- 适用环境：deepin 桌面环境（dde-shell 面板）
+- 数据源：读取 `/proc/net/dev` 计算网络流量
+
+## 功能特性
+
+- 实时上行/下行速率监控（1 秒刷新）
+- 累计上传/下载流量统计
+- 多网卡支持，可在弹窗中切换活动网卡
+- 任务栏图标实时显示速率，高速时变色提示
+- 悬停显示速率摘要，点击展开详情弹窗
+- 详情弹窗展示活动网卡 IP 地址、各网卡速率对比与统计图表
+- 支持从弹窗一键卸载插件
+
+## 构建与安装
+
+需要配置期存在 `DDEShell` CMake 包（来自 `dde-shell` 开发包）。
+
+### 方式一：从源码安装
+
+```sh
+cmake -B build
+cmake --build build
+sudo cmake --install build   # -> /usr/share/dde-shell/space.jokul.JNetApplet/
+```
+
+或使用安装脚本：
+
+```sh
+bash install.sh
+```
+
+`cmake --install` 需要 `sudo`，因为默认 `DDE_SHELL_PACKAGE_INSTALL_DIR`
+为 `/usr/share/dde-shell`（本机 CMake CACHE 变量）。
+
+安装后重启 dde-shell 使插件生效：
+
+```sh
+systemctl --user restart dde-shell@DDE
+```
+
+### 方式二：打包为 deb 安装
+
+仓库提供 `build-deb.sh` 一键打包脚本，会从 `CMakeLists.txt` 读取版本号并构建 deb 包：
+
+```sh
+bash build-deb.sh
+```
+
+产物为 `jnetapplet_<version>_<arch>.deb`，可直接用 `dpkg -i` 安装。
+
+## 验证
+
+项目无测试 / lint / typecheck / CI 流程，验证方式为手动：安装后重启 `dde-shell`
+（其通过扫描安装目录中的 `metadata.json` 发现插件）。
+
+## 项目结构
+
+```
+├── CMakeLists.txt                          # 构建配置
+├── install.sh                              # 安装脚本
+├── build-deb.sh                            # deb 一键打包脚本
+├── networkmonitorapplet.h                  # C++ 后端头文件
+├── networkmonitorapplet.cpp                # C++ 后端实现
+├── package/
+│   ├── metadata.json                       # 插件元数据
+│   └── networkview.qml                     # QML 界面
+├── docs/                                   # 设计文档与实现计划
+├── README.md                               # 本文件
+└── AGENTS.md                               # AI 代理工作指引
+```