From 17b6624a348a0b02a55faa0316af8aea73351cda Mon Sep 17 00:00:00 2001
From: butubb <1422726308@qq.com>
Date: Sun, 13 Sep 2026 16:30:48 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E5=A5=91=E7=BA=A6=E8=A1=A5=20'?=
 =?UTF-8?q?=E8=AF=B7=E5=B9=B3=E5=8F=B0=E9=9D=99=E9=BB=98=E8=A3=85'=20?=
 =?UTF-8?q?=E6=8E=A5=E5=8F=A3=EF=BC=88=C2=A73.4=EF=BC=89=E2=80=94=E2=80=94?=
 =?UTF-8?q?=E8=AE=BE=E5=A4=87=E7=AB=AF=E5=8F=AF=E9=80=89=E5=AE=9E=E7=8E=B0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

设备端自己调系统安装器在 MIUI 上要过好几步确认，而平台走 adb 装是静默的
（实测升级 2.7s、全新安装 7.9s）。接口已实现，写进两个仓库共享的契约：
受理后平台异步安装、设备端轮询版本变化判断结果；平台装不了时返回 ok=false，
设备端退回本机安装。
---
 doc/DEVICE_AGENT.md | 23 ++++++++++++++++++++++-
 1 file changed, 22 insertions(+), 1 deletion(-)

diff --git a/doc/DEVICE_AGENT.md b/doc/DEVICE_AGENT.md
index d4471bf..734c6bf 100644
--- a/doc/DEVICE_AGENT.md
+++ b/doc/DEVICE_AGENT.md
@@ -120,7 +120,28 @@
 - `404`：id 不存在或平台侧文件已删（**注意与"未启用"的 404 区分：看响应体**，
   未启用时是 JSON `{"ok":false,...}`，文件缺失时也是 JSON —— 设备端拿到非 `application/...` 的响应就视为失败）
 
-### 3.4 `POST /api/device/agent/report`
+### 3.4 `POST /api/device/agent/install`（可选：让平台帮你静默装）
+
+**背景**：设备上的 App 自己调系统安装器，MIUI 上要过「继续 → 勾选未经安全检测 →
+继续更新」甚至 ICP 备案检查好几步；而**平台用 adb 装是静默的**（实测升级 2.7s、
+全新安装 7.9s、336MB 大包都没弹过一次框）。
+
+所以"安装/更新"按钮**建议走这个接口**：用户在手机上选（商店体验），平台用 adb 落地（静默）。
+
+**请求体**：`{"apk_id": "56b114aa"}`
+
+**响应**：
+```json
+{"ok": true, "msg": "开始安装 X 到 1 台设备", "serial": "192.168.20.100:5555"}
+```
+
+- 受理后平台**异步**安装，设备端应轮询本机该包的 versionCode 变化来判断结果
+  （装上后按 §3.5 上报 `install_ok`）
+- 平台装不了（比如 MIUI 拦了 adb 安装、设备不在池里）→ `ok=false` + `error`，
+  **设备端应退回本机安装**（`ACTION_VIEW` + FileProvider，会弹系统确认框，但至少能装）
+- `409` = 这台设备还没登记进平台设备池（平台不认识它，不能替它装）
+
+### 3.5 `POST /api/device/agent/report`
 
 回报下载/安装结果，平台侧留档（面板可见）。