diff --git a/README.md b/README.md
index ea911a4..057fa4d 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,58 @@
 # dsh-worktable 🖥️
 
+> ## 📦 本仓库是内部补丁分发仓，不是上游源码仓
+>
+> 上游：<https://github.com/Aisland-SJL/dsh-worktable> ｜ 本仓 = 上游 **v0.5.1** + 桌面端状态持久化补丁（`0.5.2-local.1`）。
+> 下面从「Screenshots」开始的全部内容是上游 README 原文；本次改动说明见 [PATCH.md](PATCH.md)。
+
+### 要不要装
+
+| 你的环境 | 要不要装 | 原因 |
+| --- | --- | --- |
+| **Slark 桌面端** | 要装 | 宿主每次启动都用随机端口（启动参数 `--port 0`），页面来源跟着变；工作台把项目存在 localStorage，浏览器按来源隔离 → 换端口就是空库，**新建的工作台重启就没了** |
+| 浏览器里跑的 `dsh web`（端口固定） | 不用装 | 端口不变、来源不变，本来就不会丢 |
+
+打这个补丁只治「重启丢数据」，不改变工作台的其他行为。
+
+### 安装
+
+当前版本 **v0.5.2-local.1**：
+
+```bash
+dsh plugin --profile web add "https://gitea.ququclean.com/xiaoqu/dsh-worktable/releases/download/v0.5.2-local.1/dsh-worktable.tgz"
+```
+
+- **桌面端：先完全退出 Slark，再执行命令**，装完手动重开；不要在宿主运行时安装。
+- `--profile web` 按你自己的 profile 名字改。
+- 资产 `dsh-worktable.tgz`，477878 字节，sha256：
+  `6abbdd3d87598f5ce0a216921cf9d43d7c62d8e0becb55f7177a9435b4067a0a`
+  （下载后可 `Get-FileHash dsh-worktable.tgz -Algorithm SHA256` 核对）
+
+### 装完怎么确认生效
+
+1. 重启后侧边栏能看到「工作台」；
+2. 新建一个项目/窗口，等两秒；
+3. 检查状态文件出现：`<DSH_HOME>\worktable-state.json`；
+4. 再完全退出重开 —— 项目还在，即生效。
+
+`<DSH_HOME>` 一般是 `%LOCALAPPDATA%\Slark\DSH\environments\<环境id>\profiles\<profile-id>`。
+
+### 覆盖范围（重要）
+
+- **覆盖**：项目、布局、绑定、项目文件夹、视图与外观设置 → 镜像到 `<DSH_HOME>/worktable-state.json`
+- **不覆盖**：图库媒体（照片仍存在 IndexedDB），换端口照样丢
+- 状态文件是宿主侧的，跨重启、跨端口稳定；localStorage 仍保留为第一落点
+
+### 升级与回退
+
+- 装上 `0.5.2-local.1` 后，插件不会提示升级到 0.5.1。
+- 上游发布 0.5.2 及以上时插件会提示升级；**一旦升级就回到没有补丁的状态**，重启又会丢数据。新版本需要把补丁重新合并（改动只有三处，见 [PATCH.md](PATCH.md)）。
+- 回退官方版：
+  ```bash
+  dsh plugin --profile web add "https://github.com/Aisland-SJL/dsh-worktable/releases/latest/download/dsh-worktable.tgz"
+  ```
+  同样要先完全退出宿主、装完手动重开。
+
 <p align="center"><b>English</b> · <a href="README.zh.md">简体中文</a></p>
 
 **An agent-project workbench for DeepSeek Harness** — a sidebar app drawer that turns every project into dockable windows, plus a built-in control room that watches them all in real time.