docs: 通用用法 GENERAL_USAGE + README/ubuntu-desktop 强调通用、用户最少步骤

README.md

@@ -21,7 +21,8 @@ tags:
 
 HuggingRun 是面向 Hugging Face Spaces 的**通用部署接口**：用同一套工具解决 HF 上的持久化、单端口、网络等限制，让任意 Docker 应用都能一键部署、重启后状态保留。
 
-- **通用工具优先**：主要维护的是通用层（持久化同步、单入口、可配置端口）。示例仅演示“最少配置”用法。
+- **通用用法（用户最少步骤）**：[docs/GENERAL_USAGE.md](docs/GENERAL_USAGE.md) — 不按其他云容器收费或复杂配置，所有能力围绕通用工具展开。
+- **通用工具优先**：主要维护的是通用层（持久化同步、单入口、可配置端口）。示例仅演示“最少配置”用法，不在核心脚本中为任何案例写死逻辑。
 - **HF 限制与应对**：见 [docs/HF_LIMITATIONS.md](docs/HF_LIMITATIONS.md)（持久化、单端口、出站网络、DNS 等）。
 
 ## 通用接口：你只需做两件事
@@ -65,7 +66,8 @@ HuggingRun 是面向 Hugging Face Spaces 的**通用部署接口**：用同一
 
 ### Ubuntu 桌面（noVNC）
 
-见 [ubuntu-desktop/](ubuntu-desktop/)：使用同一套通用脚本（同步 + entrypoint），仅 `RUN_CMD` 改为启动 XFCE + noVNC。作为“用通用工具跑复杂应用”的示例，不做额外封装。
+**仅作为通用工具示例**：使用同一套 `scripts/`（同步 + entrypoint），仅通过不同 Dockerfile 设置 `RUN_CMD=/opt/start-desktop.sh`。  
+用法：Duplicate 本 Space 后，用 [ubuntu-desktop/Dockerfile](ubuntu-desktop/Dockerfile) 的内容**替换**仓库根目录的 `Dockerfile`，保存后构建即可；无需改通用脚本。详见 [ubuntu-desktop/README.md](ubuntu-desktop/README.md)。
 
 ## 环境变量速查
 

docs/GENERAL_USAGE.md

@@ -0,0 +1,69 @@
+# HuggingRun 通用用法
+
+本文档说明**通用工具**的用法。所有能力都围绕这一套工具展开；示例（含 Ubuntu 桌面）只是「同一条通用流水线 + 不同 RUN_CMD 或不同 Dockerfile」的用法，不做单独定制。
+
+---
+
+## 设计原则
+
+- **用户尽量少做事**：不要求像其他云容器那样做复杂配置或付费才能持久化。
+- **零额外成本**：HF 免费额度（2 vCPU、16GB、50GB 临时盘）即可用；持久化用 HF Dataset（免费私有仓库），无需买持久盘。
+- **通用优先**：维护的是一套通用入口 + 持久化 + 环境变量；任何「跑什么」都由 `RUN_CMD` 或由不同 Dockerfile 决定，不在核心脚本里为某一案例写死逻辑。
+
+---
+
+## 通用流水线（所有用法共用）
+
+1. **入口**：`/scripts/entrypoint.sh` → 调用 `sync_hf.py`。
+2. **sync_hf.py**：  
+   - 若配置了 `HF_TOKEN` 与 Dataset 仓库，则把 `PERSIST_PATH`（默认 `/data`）从 HF Dataset 拉回 → 再启动应用；  
+   - 后台按 `SYNC_INTERVAL` 把 `PERSIST_PATH` 同步回 Dataset；  
+   - 最后执行 `RUN_CMD`（或默认 demo）。  
+3. **应用**：唯一要求是监听 `APP_PORT`（默认 7860）。需要持久化的数据放在 `PERSIST_PATH` 下即可。
+
+没有任何「仅针对某一种容器」的步骤；换应用只换 `RUN_CMD` 或换一个使用同一套 `scripts/` 的 Dockerfile。
+
+---
+
+## 用户最少步骤（通用用法）
+
+### 场景 A：跑默认 demo 或自定义命令
+
+1. 在 HF 上 **Duplicate 本 Space**（或新建 Space 并克隆本仓库）。
+2. 可选：在 Settings → Secrets 里配置  
+   - `HF_TOKEN`（要持久化时必填）  
+   - `RUN_CMD`（要跑的进程，不设则跑内置 demo）
+3. 打开 Space 链接即可。  
+无需改代码、无需付费、无需像其他云容器那样单独买持久盘或做复杂配置。
+
+### 场景 B：跑「另一种镜像」示例（例如 Ubuntu 桌面）
+
+- 仍用**同一套通用工具**：只是把「要跑的东西」换成 Ubuntu 桌面。
+- 操作：Duplicate 本 Space 后，用 **ubuntu-desktop 示例的 Dockerfile** 替换仓库根目录的 `Dockerfile` 内容（仓库里已有 `scripts/` 和 `ubuntu-desktop/start-desktop.sh`，构建上下文不变）。
+- 之后同样只需在 Settings 里配 Secrets（如 `HF_TOKEN`），无需在通用脚本里加任何 Ubuntu 专用逻辑。
+
+**Ubuntu 桌面示例步骤**：见 [ubuntu-desktop/README.md](../ubuntu-desktop/README.md)。方式一：用 `ubuntu-desktop/Dockerfile` 的内容替换根目录 `Dockerfile` 后推送。方式二：新建一个 Space，将本仓库的 **deploy-ubuntu-desktop** 分支推送到该 Space 的 main（该分支根目录已是桌面 Dockerfile，仍使用同一套 `scripts/`）。
+
+---
+
+## 环境变量（通用）
+
+| 变量 | 默认 | 说明 |
+|------|------|------|
+| `RUN_CMD` | 默认 demo | 要执行的命令 |
+| `PERSIST_PATH` | `/data` | 与 HF Dataset 同步的目录 |
+| `HF_TOKEN` | — | 持久化用 Token |
+| `HF_DATASET_REPO` | `{SPACE_ID}-data` | Dataset 仓库 |
+| `AUTO_CREATE_DATASET` | `false` | 是否自动创建 Dataset |
+| `SYNC_INTERVAL` | `60` | 同步间隔（秒） |
+| `PORT` / `APP_PORT` | `7860` | 应用监听端口（HF 只暴露此端口） |
+
+所有行为都由这些变量与同一套脚本决定；不增加「仅某案例」的变量。
+
+---
+
+## 和「其他云容器」的对比
+
+- **其它云**：往往要选机型、买持久盘、配网络/密钥等，步骤多、有持续费用。
+- **HuggingRun**：Duplicate Space → 按需设 `HF_TOKEN` / `RUN_CMD`（或换示例 Dockerfile），即可跑任意兼容 Docker 的应用，持久化用 HF Dataset，不额外付费。  
+所有修改都围绕这套**通用工具**展开；示例（包括 Ubuntu 桌面）只演示用法，不扩展通用层为「专用逻辑」。

ubuntu-desktop/README.md

@@ -1,14 +1,15 @@
 # Ubuntu 桌面示例
 
-本目录是 **HuggingRun 通用工具** 的一个示例：在 HF 上跑 Ubuntu + XFCE + noVNC，使用与主仓库相同的持久化与 entrypoint，仅 `RUN_CMD` 不同。
+本目录是 **HuggingRun 通用工具** 的一个示例：在 HF 上跑 Ubuntu + XFCE + noVNC，使用与主仓库**完全相同的** `scripts/`（entrypoint + sync），**不修改任何通用逻辑**；仅通过本目录的 Dockerfile 设置 `RUN_CMD=/opt/start-desktop.sh`。
 
-- **通用工具**：根目录的 `scripts/sync_hf.py`、`scripts/entrypoint.sh` 和主 Dockerfile 的 entrypoint。
+- **通用用法**：见 [docs/GENERAL_USAGE.md](docs/GENERAL_USAGE.md)。
 - **本示例**：`Dockerfile` 在此目录，构建时从仓库根 COPY `scripts/`，并设置 `RUN_CMD=/opt/start-desktop.sh`；`start-desktop.sh` 启动 Xvfb + XFCE + x11vnc + noVNC（监听 7860），桌面 HOME 放在 `PERSIST_PATH/desktop-home`，由通用同步脚本持久化。
 
-## 最小用法
+## 最小用法（用户只做两件事）
 
-1. 新建 Space 或 Duplicate HuggingRun，将 **Dockerfile** 换成本目录的 `Dockerfile` 内容（或从仓库根构建：`docker build -f ubuntu-desktop/Dockerfile .`）。
-2. 设置 Secrets：`HF_TOKEN`、可选 `AUTO_CREATE_DATASET=true`。
-3. 构建并运行，浏览器打开 Space 即可看到 noVNC 桌面；重启后状态由通用持久化保留。
+1. **Duplicate HuggingRun Space** 后，用本目录的 **Dockerfile 内容替换**仓库根目录的 `Dockerfile`（不增删通用脚本）。
+2. 在 Settings → Secrets 中设置 `HF_TOKEN`，可选 `AUTO_CREATE_DATASET=true`。
+3. 推送后等待构建，浏览器打开 Space 即可看到 noVNC 桌面；重启后状态由通用持久化保留。
 
-维护重点在通用层；本示例仅做最小封装。
+从仓库根构建（例如本地）：`docker build -f ubuntu-desktop/Dockerfile .`  
+维护重点在通用层；本示例仅做最小封装，不向 core 增加任何案例专用逻辑。