From 35f9080ee4bbe4ec31c86dd2e73673c5caa8d074 Mon Sep 17 00:00:00 2001
From: pikastech <liang6516@outlook.com>
Date: Sun, 19 Jul 2026 19:21:57 +0200
Subject: [PATCH] =?UTF-8?q?docs(provider):=20=E6=9B=B4=E6=96=B0=20Windows?=
 =?UTF-8?q?=20=E5=AE=89=E8=A3=85=E4=B8=8E=E8=BF=90=E8=A1=8C=E6=97=B6?=
 =?UTF-8?q?=E5=90=88=E5=90=8C?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/reference/provider-gateway.md | 33 +++++++++++++++++++++---------
 1 file changed, 23 insertions(+), 10 deletions(-)

diff --git a/docs/reference/provider-gateway.md b/docs/reference/provider-gateway.md
index 21ed2ff7..d3a05138 100644
--- a/docs/reference/provider-gateway.md
+++ b/docs/reference/provider-gateway.md
@@ -7,7 +7,8 @@ Provider Gateway 是计算节点侧容器。它只主动连出到主 server 暴
 `src/components/unideskcprovider` 是独立的纯 Windows provider 形态：
 
 - 运行时：
-  - 直接使用 Windows Python 3.11、Tkinter 和 PyYAML；
+  - Windows 7 使用 Python 3.8，Windows 10/11 使用 Python 3.11；
+  - 运行时必须包含 Tkinter 和 PyYAML；
   - 不依赖 Docker、WSL、bash、入站 SSH 服务或 Linux 文件系统；
   - WSL 只可作为安装文件传输或外部验收通道，不参与 provider 运行。
 - 本地界面：
@@ -23,9 +24,10 @@ Provider Gateway 是计算节点侧容器。它只主动连出到主 server 暴
   - Windows route 的二进制下载直接使用 PowerShell 标准输出流，不映射 `/mnt/<drive>`，也不要求同机存在 WSL；
   - Docker、远程升级、微服务代理和出站代理暂不支持，并返回结构化 unsupported。
 - 启动入口：
-  - 目标机需要 Python 3.11、Tkinter 和 PyYAML；
-  - 双击 `start.cmd` 或直接运行 `pythonw.exe unideskcprovider.py`；
-  - 启动命令不接受配置参数或环境变量。
+  - Apps L1 提供 Windows 7/10/11 共用的零参数 CMD installer；
+  - installer 优先复用满足版本和 Tkinter 要求的运行时，
+    必要时在 `%USERPROFILE%\.unidesk\runtime` 安装专有 Python；
+  - 双击本地 CMD 或直接运行一行 CMD 命令，均不接受配置参数或环境变量。
 
 唯一用户配置固定为 `%USERPROFILE%\.unidesk\provider.yaml`：
 
@@ -33,6 +35,7 @@ Provider Gateway 是计算节点侧容器。它只主动连出到主 server 暴
 id: G14-win
 server: ws://152.53.229.148:18082/ws/provider
 credentialFile: provider.token
+pythonRuntime: auto
 autoStart: true
 ```
 
@@ -42,7 +45,13 @@ autoStart: true
 - TCP 数据通道默认从 provider WebSocket 端口按既有协议推导；
 - 只有部署拓扑不能使用既有端口映射时才增加 `data: tcp://host:port`；
 - `autoStart` 省略时默认关闭，修改后由面板写回；
-- 日志固定写入 `%USERPROFILE%\.unidesk\logs\unideskcprovider.log`，达到 2 MiB 后轮转并保留 3 份。
+- `pythonRuntime` 默认 `auto`：
+  - `auto` 先查找系统 Python，再复用已有专有 Python，最后按需安装专有 Python；
+  - `system` 只接受系统 Python，不满足时失败并提示选择 `private`；
+  - `private` 只复用或安装专有 Python，不扫描系统 Python；
+  - 明确选择 `system` 或 `private` 后禁止切换到另一类运行时；
+- 日志固定写入 `%USERPROFILE%\.unidesk\logs\unideskcprovider.log`，
+  按本机自然日轮转并保留有限历史。
 
 升级检查默认启用，稳定频道每 300 秒检查一次。只有需要覆盖默认策略时才增加：
 
@@ -76,13 +85,17 @@ Provider Apps 下载服务使用独立 L1 运行面：
 
 同一 Apps L1 还提供 Windows 快速部署入口：
 
-- 人类工具页目标入口：`https://app.hwlod.com/`；
-- 当前可解析别名：`https://app.hwpod.com/`；
+- 人类工具页唯一入口：`https://apps.hwpod.com/`；
 - Agent 安装合同：`/v1/unideskcprovider/install.json`；
-- Node bootstrap：`/v1/unideskcprovider/install.cjs`；
-- 页面生成的一行 Node 命令只包含 provider id、服务器地址、凭据文件名和自动启动策略；
+- 通用 CMD：`/win.cmd`；
+- Python bootstrap：`/v1/unideskcprovider/install-bootstrap.py`；
+- 页面把 provider id、服务器地址、凭据文件名、Python 环境策略和自动启动策略写入短 YAML；
 - token 必须预先通过受控渠道写入 `%USERPROFILE%\.unidesk`，网页和命令不得携带 token；
-- bootstrap 负责原子写入短 `provider.yaml`、下载并校验 Python 发布件、检查 Tkinter/PyYAML 和启动 `pythonw.exe`。
+- CMD 只读取已有 `provider.yaml`，探测系统与专有 Python、选择低延迟可达下载源，
+  并逐秒显示下载速度、已耗时和预计剩余秒数；
+- bootstrap 下载并校验 Provider 发布件、检查 PyYAML，并启动 Windows Python 进程；
+- 运行中安装通过 WMI 托管的独立交接进程停止旧 PID 和启动新版本，
+  禁止在当前 Provider 命令树内先终止旧实例。
 
 同机 Windows 与 WSL provider 必须使用不同 id，例如 `G14-win` 与 `G14-WSL`。停止其中一个不得影响另一个。