diff --git a/AGENTS.md b/AGENTS.md
index f2ede0b..3649ec9 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,7 +1,7 @@
 # AGENTS.md
 
 Guidance for AI agents working in this repo. Verified against `CMakeLists.txt`,
-`package/metadata.json`, and the installed macro file at
+`package/metadata.json.in`, and the installed macro file at
 `/usr/lib/x86_64-linux-gnu/cmake/DDEShell/DDEShellPackageMacros.cmake`.
 
 ## What this is
@@ -71,7 +71,7 @@ then restart `dde-shell` (it discovers applets by scanning the install dir for
 ├── networkmonitorapplet.h         # C++ backend header
 ├── networkmonitorapplet.cpp       # C++ backend implementation
 ├── package/
-│   ├── metadata.json              # Plugin metadata
+│   ├── metadata.json.in           # Plugin metadata 模板（由 CMake 生成 metadata.json）
 │   └── networkview.qml            # QML UI
 ├── docs/                          # Design docs and implementation plans
 └── AGENTS.md                      # This file
@@ -112,15 +112,26 @@ Inherits from `DApplet`, provides:
 |---|---|---|
 | `CMakeLists.txt` | `add_library(...)` target | `space.jokul.JNetApplet` |
 | `CMakeLists.txt` | `PLUGIN_ID` | `space.jokul.JNetApplet` |
-| `package/metadata.json` | `Plugin.Id` | `space.jokul.JNetApplet` |
+| `package/metadata.json.in` | `Plugin.Id` | `space.jokul.JNetApplet` |
 
 `Plugin.Url` (`networkview.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`, `Plugin.Url`, and
-`Plugin.Parent`. The current file is complete — don't drop any.
+`package/metadata.json.in` is the template; CMake's `configure_file()` generates the
+final `metadata.json` in the build directory at configure time. The template must
+contain `Plugin.Version`, `Plugin.Id`, `Plugin.Url`, and `Plugin.Parent`. Don't drop any.
+
+## Version management
+
+**Single source of truth**: `CMakeLists.txt` line 3 `project(JNetApplet VERSION x.y.z)`.
+
+- `package/metadata.json.in` uses `@PROJECT_VERSION@` placeholder, substituted at
+  configure time -> installed `metadata.json` always matches.
+- `build-deb.sh` extracts the version directly from `CMakeLists.txt` via grep.
+- **To bump the version**: edit only the `project(... VERSION ...)` line in
+  `CMakeLists.txt`. All downstream consumers (install, deb) pick it up automatically.
 
 ## Conventions
 
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 375fb00..84a879d 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -36,5 +36,10 @@ target_link_libraries(space.jokul.JNetApplet PRIVATE
 
 # 安装到dde-shell插件目录
 install(TARGETS space.jokul.JNetApplet DESTINATION /usr/lib/x86_64-linux-gnu/dde-shell)
-install(FILES package/metadata.json DESTINATION /usr/share/dde-shell/${PLUGIN_ID})
+
+# 由模板生成 metadata.json，版本号从 project() 取，避免多处手动维护
+# 设计原因：版本号唯一源为 CMakeLists.txt 顶部的 project(... VERSION)，
+# configure_file 在构建目录生成最终 metadata.json，install 安装生成文件
+configure_file(package/metadata.json.in ${CMAKE_CURRENT_BINARY_DIR}/metadata.json @ONLY)
+install(FILES ${CMAKE_CURRENT_BINARY_DIR}/metadata.json DESTINATION /usr/share/dde-shell/${PLUGIN_ID})
 install(FILES package/networkview.qml DESTINATION /usr/share/dde-shell/${PLUGIN_ID})
\ No newline at end of file
diff --git a/README.md b/README.md
index 91d7490..f327aae 100644
--- a/README.md
+++ b/README.md
@@ -68,7 +68,7 @@ bash build-deb.sh
 ├── networkmonitorapplet.h                  # C++ 后端头文件
 ├── networkmonitorapplet.cpp                # C++ 后端实现
 ├── package/
-│   ├── metadata.json                       # 插件元数据
+│   ├── metadata.json.in                   # 插件元数据模板（由 CMake 生成 metadata.json）
 │   └── networkview.qml                     # QML 界面
 ├── docs/                                   # 设计文档与实现计划
 ├── README.md                               # 本文件
diff --git a/package/metadata.json b/package/metadata.json.in
similarity index 89%
rename from package/metadata.json
rename to package/metadata.json.in
index cd5e40b..6795f9d 100644
--- a/package/metadata.json
+++ b/package/metadata.json.in
@@ -1,6 +1,6 @@
 {
   "Plugin": {
-    "Version": "1.0",
+    "Version": "@PROJECT_VERSION@",
     "Id": "space.jokul.JNetApplet",
     "Url": "networkview.qml",
     "Parent": "org.deepin.ds.dock",