简体中文 · [English](USER_GUIDE_EN.md)
# DSH Remote Web Gateway 用户指南
> **手机远程 DeepSeek Harness，从安装到第一次扫码，这一篇就够了。**
如果你只是第一次使用，不需要先理解 Quick Tunnel、Gateway、Device Session 这些技术名词。
**先把它装起来，用起来。**
遇到问题，再往后找对应章节。
---
# 🤖 不想看文档？把项目链接发给 AI，让它帮你装
这是最推荐给小白的方式。
如果你正在使用：
**DSH、Codex、Claude Code，或者其它可以读取 GitHub 的 Coding Agent**
你甚至不需要从头研究这份指南。
先复制项目地址：
```text
https://github.com/summer1238/dsh-remote-web-gateway
```
然后把下面这段提示词**完整复制给你的 AI**。
## 📋 AI 安装提示词
```text
我要在当前电脑上安装并配置：
DSH Remote Web Gateway
项目地址：
https://github.com/summer1238/dsh-remote-web-gateway
请先阅读这个项目当前最新的：
1. README
2. docs/USER_GUIDE.md
3. docs/TROUBLESHOOTING.md
然后再开始操作。
要求：
1. 不要凭你的历史知识猜安装方式，必须以这个项目当前仓库文档和实际环境为准。
2. 先检查我的 DeepSeek Harness / DSH 是否已经安装、当前版本、Web Profile 和运行状态。
3. 如果我的环境满足要求，再按照项目官方方式安装 DSH Remote Web Gateway。
4. 能安全自动完成的步骤可以直接帮我执行。
5. 需要我本人完成的操作，例如：
- 扫二维码
- 输入配对码
- GitHub 授权
- 点击确认
- 重启 DSH
请停下来明确告诉我应该做什么。
6. 不要修改 DeepSeek Harness Core 源码。
7. 不要为了安装这个插件删除我的 DSH_HOME、配置、会话、项目或其它插件。
8. 不要执行 reset、clean、批量删除、修改系统 PATH、停止不明进程等破坏性操作。
9. 如果安装失败：
- 先读取这个项目的 Troubleshooting
- 再根据真实报错排查
- 不要直接建议重装整个 DSH。
10. 不要在聊天或日志里输出我的 Cookie、Token、GitHub 验证信息、代理密码或其它密钥。
11. 安装结束后请帮我确认：
- 插件已经被 DSH 正确加载
- 设置页出现“远程控制”
- 可以看到“开启远程控制”
12. 到需要手机扫码的步骤时停止，让我本人完成扫码和授权。
请先告诉我你检查到的当前 DSH 环境，然后再开始安装。
```
---
## AI 有终端权限和没有终端权限，有什么区别？
### AI 能操作你的电脑
例如本地 Coding Agent。
它可以协助：
**检查 DSH → 执行安装命令 → 检查插件 → 启动 / 重启 DSH → 排查报错。**
到了扫码、GitHub 授权等需要你本人确认的步骤，再让你接手。
### AI 只是普通聊天
也没关系。
把项目链接发给它，让它先阅读项目文档。
它仍然可以：
**一步一步告诉你复制哪条命令、打开哪个页面、点哪个按钮。**
区别只是：
> 它不能替你操作电脑，你自己照着它的步骤做。
---
# 🚀 不用 AI？自己装也就几步
整个第一次使用流程其实就是：
## **安装插件 → 重启 DSH → 开启远程控制 → 等二维码 → 手机扫码**
下面一步一步来。
---
# 1. 安装前需要什么？
目前正式验证的宿主环境是：
**Windows x64**
插件要求兼容的 DSH 版本从：
```text
0.1.0-rc.5+
```
开始。
当前项目主要开发和真实验收基线是：
```text
DeepSeek Harness 0.1.0-rc.7
```
如果你正在使用更新版本，也建议先确认插件的 Compatibility 文档。
### 📘 [查看兼容性说明](COMPATIBILITY.md)
---
# 2. 一条命令安装
```bash
dsh plugin --profile web add dsh-remote-web-gateway
```
安装完成以后：
## **重启 DSH Web。**
如果你平时本来就知道怎么启动 DSH，按照你原来的方式启动即可。
标准入口是：
```bash
dsh web
```
然后在浏览器打开你的 DSH Web。
默认情况下通常是：
```text
http://127.0.0.1:3080/
```
---
# 3. 找到「远程控制」
打开 DeepSeek Harness。
进入：
## **设置 → 远程控制**
你应该可以看到：
# **开启远程控制**
如果这里完全没有「远程控制」，先不要继续折腾网络。
优先检查：
- 插件是否安装成功；
- 是否安装到了 `web` Profile；
- DSH 是否已经重启；
- 插件是否成功加载。
仍然没有的话直接看：
### 🧰 [故障排查](TROUBLESHOOTING.md)
---
# 4. 点击「开启远程控制」
点击以后，不一定马上出现二维码。
这是正常的。
你可能会依次看到：
> 正在准备安全连接…
> 正在检查 cloudflared…
> 正在创建 Cloudflare Tunnel…
> 正在启动安全连接…
> 正在等待公网地址…
> 正在建立安全连接…
第一次使用时，如果电脑里还没有可用的 `cloudflared`，插件还可能需要先下载。
## **不要看到“正在建立”就急着扫码。**
我们专门做了 Tunnel Ready 检查。
只有确认远程连接已经真正准备好：
# **二维码才会出现。**
也就是说：
> **二维码出现 = 现在才应该扫码。**
---
# 5. 第一次手机扫码
远程控制准备完成以后，电脑设置页会显示：
- 二维码；
- 8 位配对码；
- 剩余有效时间；
- 当前访问地址。
手机直接扫描二维码。
浏览器会打开配对页面。
然后完成第一次设备配对。
配对成功以后，你会看到：
# **设备已成功配对**
电脑设置页原来的 QR、8 位配对码和倒计时会消失。
这是正常的。
不是二维码坏了。
而是：
## **它已经完成了自己的任务。**
---
# 6. 不方便扫码？用 8 位配对码
二维码和 8 位配对码只是两种不同的输入方式。
如果手机摄像头不方便扫码：
1. 在手机浏览器打开电脑设置页显示的当前访问地址；
2. 进入配对页面；
3. 输入电脑上显示的 **8 位配对码**；
4. 完成配对。
二维码和 8 位码属于：
## **同一张一次性配对凭证。**
不是两套权限。
---
# 7. 为什么刚才那个二维码不能再用了？
**这是故意的。**
第一次配对使用的是：
# **一次性 Pairing Ticket**
它默认只有短暂有效时间。
当前默认是：
## **5 分钟。**
二维码和 8 位配对码都属于这一张 Ticket。
其中任何一种成功使用以后：
# **整张 Ticket 立即作废。**
所以：
- QR 成功扫过以后不能再拿去配第二台手机；
- 8 位码成功使用以后也不能再重复输入；
- 刷新电脑设置页也不会自动偷偷给你生成一套新凭证。
**这样设计是为了避免：**
> 一个曾经分享过、截过图、留在聊天记录里的二维码，长期变成进入 DSH 的万能钥匙。
> **注意：尚未使用、仍在有效期内的 QR / 配对码仍然是真正的凭证。**
>
> 不要主动发给别人。
---
# 8. 想连接第二台手机？
很简单。
第一台设备成功配对以后，电脑设置页会显示：
# **生成新的配对码**
点击它。
插件会创建一张新的 Pairing Ticket。
然后第二台设备：
**扫码 / 输入新的 8 位码 → 完成自己的独立授权。**
每台设备都有自己的 Device Session。
不是所有手机共用一把长期万能钥匙。
---
# 9. 已经授权了哪些设备？
在：
## **设置 → 远程控制 → 已授权设备**
可以看到当前已经授权的设备。
设备信息会包含类似：
- 设备名称；
- 浏览器 / User-Agent 信息；
- 最近使用时间。
默认最多支持：
## **20 台已授权设备。**
一般个人使用远远够了。
---
# 10. 手机丢了？马上撤销它
这是远程访问里非常重要的一步。
如果某台手机：
- 丢了；
- 借给别人了；
- 不再使用；
- 你怀疑它不安全；
回到电脑：
## **设置 → 远程控制 → 已授权设备**
找到那台设备。
点击：
# **撤销**
撤销以后：
## **旧设备权限立即失效。**
它原来的授权不能继续使用。
---
# 11. 怀疑不止一台设备？全部撤销
如果你不确定哪台设备出了问题：
点击：
# **撤销全部设备**
系统会要求确认：
> 确定要撤销全部设备吗？所有手机将需要重新配对。
确认以后：
**所有已授权设备都需要重新完成配对。**
---
# 12. 怎么停止远程控制？
暂时不用了？
回到：
## **设置 → 远程控制**
点击：
# **停止远程控制**
正在连接过程中，也可以点击：
# **停止**
停止以后，不要继续使用之前显示的临时访问地址或旧二维码。
下次需要时重新开启远程控制，以设置页当前显示的状态和地址为准。
---
# 13. GitHub 身份验证是什么？必须用吗？
# **不是必须。**
默认的一次性 QR / 8 位码已经可以完成设备首次配对。
GitHub 身份验证属于：
## **可选的身份增强能力。**
如果你希望绑定自己的 GitHub 身份：
进入远程控制设置中的：
# **GitHub 身份认证**
点击：
# **绑定 GitHub**
然后按照页面提示：
1. 打开 GitHub 授权页面；
2. 输入当前页面显示的设备验证码；
3. 使用你自己的 GitHub 账号确认授权；
4. 等待 DSH 完成身份绑定。
---
## ⚠️ GitHub 授权时有一个很重要的安全原则
页面会提醒你：
> **只批准由你本人刚刚在当前设备发起的 GitHub 验证。**
如果有人在聊天里发给你一个 GitHub Device Code，说：
> “帮我输一下。”
不要批准。
**只输入你刚刚自己点击「绑定 GitHub」以后，当前 DSH 页面生成的验证码。**
GitHub 身份验证过程中使用的 Token：
- 不写入项目配置；
- 不保存到浏览器；
- 不写入日志；
- 完成身份确认以后不会作为长期 GitHub Token 保存。
---
# 14. 怎么更新插件？
插件会定期检查新版本。
如果发现更新：
进入：
## **设置 → 远程控制 → 插件更新**
你会看到：
- 当前版本；
- 新版本；
- 更新说明。
确认以后点击：
# **立即更新**
安装结束以后会提示：
> **更新已安装，需要重启 DSH 后生效。**
注意：
# **插件不会偷偷重启你的 DSH。**
正在跑 Agent？
你可以先把工作做完。
然后自己选择合适的时候重启。
如果更新失败：
**当前版本继续运行。**
不会因为更新失败把现有插件直接弄坏。
---
# 15. 为什么第一次启动可能要下载 Cloudflare Tunnel？
DSH Remote Web Gateway 默认使用：
# **Cloudflare Quick Tunnel**
电脑需要一个 `cloudflared` 客户端来建立这个临时安全通道。
如果当前环境没有符合要求的版本：
插件会自动准备它。
所以第一次开启远程控制，有时会比之后慢一点。
你可能会看到：
> 正在下载 Cloudflare Tunnel…
并显示：
- 已下载大小；
- 当前网络方式；
- 当前下载源。
---
# 16. 下载很慢怎么办？
先不用自己到 GitHub 找 exe。
插件已经提供：
## 下载网络
- **自动（推荐）**
- 直连
- 自定义代理
以及：
## 下载源
- **自动（推荐）**
- 仅官方源
- 备用镜像
通常建议先保持：
# **自动（推荐）**
自动模式会根据当前 Windows 网络环境选择可用路径。
如果官方下载连接失败、首包长时间没有到达，或者速度异常：
插件可以尝试经过审核的备用下载路径。
---
## 备用镜像是不是“下载了另一个版本”？
不是。
备用镜像只解决：
> **从哪里把同一个文件下载回来。**
并不会因为走镜像就跳过安全校验。
下载完成以后仍然会做固定版本和完整性验证。
所以：
> **换传输路径 ≠ 降低验证标准。**
---
# 17. 我公司代理需要账号密码怎么办？
当前自定义代理设置里：
**不会保存代理用户名和密码。**
如果你的网络必须使用带凭据的代理，请使用：
```text
HTTPS_PROXY
```
这类环境代理配置。
不要把：
- 用户名；
- 密码；
- Token；
直接写进公开截图、Issue 或聊天记录。
---
# 18. 常见情况
## 点了「开启远程控制」，二维码没有马上出现
先看状态。
如果还是：
> 正在建立安全连接…
**继续等。**
二维码只会在 Tunnel 真正 Ready 以后出现。
---
## 二维码出现以后手机打开 Cloudflare 1033
正常版本里：
**二维码只有在 Tunnel Ready 以后才会出现。**
如果仍然遇到 1033：
1. 不要不断疯狂刷新；
2. 回电脑停止远程控制；
3. 再重新开启一次；
4. 如果仍然复现，把错误页面时间、DSH 日志和问题现象交给 Troubleshooting / AI 排查。
### 🧰 [查看故障排查](TROUBLESHOOTING.md)
---
## 显示「设备已成功配对」，二维码不见了
正常。
Ticket 已被使用。
连接第二台设备：
# **点「生成新的配对码」。**
---
## 显示「配对码已过期」
正常。
一次性配对凭证有有效期。
点击：
# **生成新的配对码**
重新配对。
---
## 被撤销的手机突然 401 / 无法访问
正常。
撤销就是为了：
# **立即收回这台设备的访问权限。**
重新授权需要再次完成配对。
---
## cloudflared 下载失败
先：
1. 检查当前网络；
2. 保持「自动（推荐）」重试；
3. 看是否识别到了系统代理；
4. 必要时尝试自定义代理或备用下载源。
不要为了修这个问题：
- 删除整个 DSH_HOME；
- 重装 Node；
- 改系统 PATH；
- 随便下载一个来历不明的 cloudflared。
---
## 检查更新显示「暂时无法检查更新」
如果 npm registry 当前不可达（或你安装的是未发布到 registry 的本地构建包），可能出现这个提示。
这不会影响：
**当前已经安装版本继续运行。**
---
## 检测到已有 Cloudflare 配置
不要看到这个提示以后直接删除自己的 Cloudflare 配置文件。
如果你的电脑本来就在运行其它 Cloudflare Tunnel：
### 🧰 先查看 [Troubleshooting](TROUBLESHOOTING.md)
确认真实冲突以后再处理。
---
# 🤖 19. 还是没解决？把项目链接 + 报错一起交给 AI
不要只发一句：
> “这个插件坏了，怎么办？”
信息太少，AI 很容易凭经验乱猜。
建议你把：
1. 项目地址；
2. 当前报错；
3. 截图；
4. DSH 版本；
5. 你刚刚做了什么；
一起给它。
然后复制下面这段。
## 📋 AI 排障提示词
```text
我正在使用：
DSH Remote Web Gateway
项目：
https://github.com/summer1238/dsh-remote-web-gateway
我现在遇到的问题是：
【把你的问题写在这里】
报错 / 日志：
【把不含 Token、Cookie、密码等敏感信息的日志贴在这里】
请先阅读项目当前最新的：
1. README
2. docs/USER_GUIDE.md
3. docs/TROUBLESHOOTING.md
然后再分析。
要求：
1. 不要凭历史知识猜当前项目实现。
2. 先判断问题发生在哪一层：
- DSH / 插件加载
- cloudflared 下载
- Quick Tunnel
- Pairing
- Device Session
- GitHub 身份验证
- 更新
- 网络 / 代理
3. 优先使用只读检查确认真实状态。
4. 不要直接删除 DSH_HOME、插件目录、用户配置或会话。
5. 不要执行 git reset / clean、批量删除、修改系统 PATH、结束不明进程等破坏性操作。
6. 如果确实需要修改或删除东西，先告诉我：
- 要改什么
- 为什么
- 风险是什么
- 如何恢复
等我确认后再执行。
7. 不要让我公开：
- Cookie
- Pairing Secret
- GitHub Token
- API Key
- 代理密码
8. 如果截图或日志里可能含敏感信息，请先提醒我脱敏。
9. 如果项目 Troubleshooting 已经有对应问题，优先按照官方文档处理。
10. 最后告诉我：
- 根因
- 你做了什么
- 是否已经修复
- 是否还有风险
现在请先分析，不要先执行破坏性操作。
```
---
# 20. 分享截图 / 求助前，记得先检查敏感信息
尤其不要公开：
- 当前仍然有效的 QR；
- 当前仍然有效的 8 位配对码；
- Pairing Secret；
- Device Cookie；
- GitHub Device Code；
- API Key；
- 代理密码；
- 公司项目路径或源码内容。
如果你必须发截图求助：
# **先停止远程控制，或者等当前 Pairing Ticket 失效，再发图。**
---
# 21. 想了解它为什么这样设计？
普通使用到这里就结束了。
如果你还想知道：
### 🛡️ [威胁模型](THREAT_MODEL.md)
为什么：
**链接不是权限、一次性配对、设备独立授权、管理面不暴露公网。**
### 🏗️ [架构说明](ARCHITECTURE.md)
手机、Quick Tunnel、Remote Web Gateway 和本地 DSH 到底怎么连。
### 🧰 [故障排查](TROUBLESHOOTING.md)
按真实症状查问题。
### 💻 [兼容性](COMPATIBILITY.md)
哪些系统和设备已经真实验证。
### 🔐 [Security Policy](../SECURITY.md)
发现安全漏洞时如何报告。
---
# 最后记住三件事
## **二维码出现再扫。**
因为出现以前，安全连接还在建立。
## **有效期内的配对码不要分享。**
它虽然是一次性的，但在成功使用之前仍然是真实凭证。
## **设备不再可信，就撤销。**
远程权限不是给出去以后就收不回来。
**你始终可以在电脑端管理自己的授权设备。**