Tailscale 远程访问 kjx-talesofai/dsh-plugin-tailscale-remote

dsh-plugin-tailscale-remote

在手机上打开 DeepSeek Harness 桌面端 Web UI，走的是你自己的 Tailscale tailnet。打开一个开关，就建好一条仅限 tailnet 的 HTTPS 映射，给出二维码，手机随即接入——不用端口转发，不用反向代理，也不暴露到公网。

= 0.2.0-rc.1">

dsh-plugin-tailscale-remote — 一个开关，把桌面端的 DSH 从你自己的手机打开

中文说明（点开） —— 用 Tailscale 把桌面端 DSH 开到手机上，只在你自己的网络里

它是什么：DSH 桌面端插件。打开侧栏里的「Tailscale 远程访问」开关，它就为你在 tailnet 上建一条 HTTPS 映射（https://<你的设备名>.<你的 tailnet>.ts.net/ → 本机 127.0.0.1:<DSH 端口>），面板给出配对二维码；手机扫码、点一下「进入 DSH」，就进去了。之后这台手机直接访问那个域名即可。

为什么做：DSH 的 Web UI 只监听回环地址（127.0.0.1），这是对的——但它意味着手机天然连不上。Tailscale 已经把两台设备放进同一张虚拟网，缺的只是把 GUI 安全地桥过去：不开放公网、不做端口转发、服务端也不用改成监听 0.0.0.0。这个插件就是那座桥，加上一个开关、一个二维码和状态灯。

和 DeepSeek Harness Mobile 的分工：那是社区自研的安卓客户端——想给手机一个原生 App 的人应该用那个，体验是专门为手机做的。这个插件走的是相反的、也故意更窄的路：手机侧不装任何东西（就是一个浏览器标签页），不用注册账号、不经过任何中继，也不引入另一套会话管理；代价是必须有一台开着的、能跑 DSH 的桌面机，且它与手机在同一个 tailnet 里。它不是客户端，只是一座接入现有桌面实例的桥。

怎么装（在 DSH「添加插件」里填，不需要 npm 账号、也无需发布）：

| 填入 | 形式 |
| GitHub | github:kjx-talesofai/dsh-plugin-tailscale-remote#v0.2.5（当前可用） |
| 本地目录 | 绝对路径，例如 /path/to/dsh-plugin-tailscale-remote |

装完重启桌面端（host 半边只在启动时加载）。没有别的步骤：hostname 由插件启动时自己探测并注册进 harness 的信任栅栏。

中英文：侧栏名、面板、帮助文案都跟随 DSH 界面语言（设置 → 通用 → 语言）实时切换，不用重启；配对页按手机浏览器的 Accept-Language 选语言；插件在插件列表里的名字/描述也分中英文。

怎么用：侧栏「Tailscale 远程访问」→ 打开开关 → 手机相机扫二维码 → 在打开的页面点一下「进入 DSH」。此后这台手机直接开 https://<域名>/ 即可（会话 cookie 保留 30 天）。开关关掉 = 撤销那条映射。

Tailscale 组网（三步，别人的 agent 照着做就行）：

1. Mac 与手机都安装 Tailscale 客户端，用同一个账号登录（同一 tailnet）；
2. 打开 Tailscale 管理台 的 DNS 页，启用 MagicDNS 与 HTTPS Certificates；
3. 验证：tailscale status 能看到两台设备，tailscale ip -4 给出 100.x 地址。

插件会在打开开关时预检这三项（含证书是否已签发），缺哪一项都会在面板上用红字说清楚，不会出现"绿灯但连不上"。这也是本插件唯一的前置依赖——它不含、也不能替代组网本身。

注意事项：

- 只用 Serve，绝不用 Funnel：映射只在 tailnet 内可达，不暴露到公网；
- DSH 始终只监听 127.0.0.1，插件不会改它的绑定；
- 撤销传输 ≠ 撤销会话：关开关只撤销入口，手机已签发的会话 cookie 在 30 天内仍有效；
- Mac 睡眠或合盖时隧道断开，手机就连不上；Tailscale 客户端必须保持运行；
- 配对码一次性、10 分钟有效，用过会自动换新。

卸载：在 DSH「插件」列表里卸载 dsh-plugin-tailscale-remote → 重启。想连入口一起清掉，先在面板里关掉开关（它会撤销自己建立的那条 tailscale serve 映射）。

老实说（实测范围）：只在 macOS（Apple Silicon）+ DSH 0.2.0-rc.2 + Tailscale CLI 1.102.4 上端到端跑过（真实手机扫码登录成功）；桌面端升到 0.2.1-rc.2 后重核了依赖面（平台模块版本、cordis / schemastery 版本、客户端 slot 契约），但没有重新拿手机走一遍。Windows / Linux 未测；DSH 升级后上游契约可能变化，见下方 Compatibility。

为什么做这个

DSH 的 Web UI 只绑定回环地址，这个默认值是对的——也意味着你的手机永远连不上它。Tailscale 已经把设备放进同一个虚拟网络，所以缺的那块很小、很具体：把回环上的这个端口桥接到仅限 tailnet 的 HTTPS 源，带真实证书，并且做成一个能关掉的开关。

这个插件就只做这件事。它刻意做得很窄：

- 不新增监听，不碰 0.0.0.0。 框架继续绑定回环；tailscale serve 终止 TLS 并代理过去。
- 不要账号，不要中继，不要遥测。 流量留在你的 tailnet 内（WireGuard）。插件从不向任何地方发送数据。
- 不留持久 token。 启动链接携带一个按进程生成的 token，从不写入磁盘；面板只在已认证的 UI 里显示它。

和原生客户端是什么关系

社区做了一个 Android 应用 DeepSeek Harness Mobile，给想在手机上用真正客户端的人：它是专门做的 App，有自己的生命周期和会话处理。你要的是原生手机体验，就用它。

这个插件刻意走了另一条路。手机上除了一个浏览器标签页什么都不用装，没有账号，没有中继，也没有第二份会话存储——但它只在运行 DSH 的桌面端醒着、且处于同一 tailnet 时可用。它不是客户端，而是通往你已经在跑的实例的一座薄桥。

安装

在 DSH 的插件安装对话框里点 Add plugin，填下面任意一种，然后重启桌面应用：

github:kjx-talesofai/dsh-plugin-tailscale-remote#v0.2.5 # GitHub, pinned to this release
/absolute/path/to/dsh-plugin-tailscale-remote # local checkout (dev)

这个插件没有发布到 npm registry，也不需要——上面两种写法就是 DSH 要求的全部。在本地检出里跑 npm pack 会生成一个 .tgz，可以发给别人，也可以在对话框里用 file:/absolute/path.tgz 指向它。

命令行等价写法：

dsh plugin --profile desktop add github:kjx-talesofai/dsh-plugin-tailscale-remote#v0.2.5

跟机器相关的部分都在运行时自动发现。从本地检出（或从已安装的包）安装是同一条命令——它会调用插件管理器，所以配置档布局变了也照样正确：

node ~/.dsh/profiles/desktop/node_modules/dsh-plugin-tailscale-remote/scripts/install.mjs --profile desktop
--spec <spec> 安装的不是本包自己的 release，--revert 把它再删掉，--dry-run 只打印命令、不执行。脚本默认安装 github:<owner>/<repo>#v<its own version>，版本号取自它的 package.json，所以它永远装不了跟自己出厂时不同的 tag。

要求 DSH Desktop ≥ 0.2.0-rc.1，< 0.3.0 —— 声明在 engines.dsh 里，harness 导入插件前会检查 —— 并且两台设备都要装 Tailscale（见下文）。

Tailscale，三步搞定

给你自己看 —— 或者给在另一台机器上配置的智能体看：

1. 加入同一个 tailnet。 在桌面端和手机上安装 Tailscale，登录同一个账号。
2. 打开两个开关，在 admin DNS 页面：MagicDNS 和 HTTPS Certificates。
3. 验证： tailscale status 列出两台设备；tailscale ip -4 打印一个 100.x 地址。

插件的预检就查这三件事（包括你的节点名对应的证书是否真的签发了），缺哪项就用大白话报哪项。它不替你配置 —— 网络的事还是 Tailscale 管。

用法

1. 侧边栏 → Tailscale Remote Access → 打开开关。面板显示状态、一个二维码，还有备用链接。
2. 手机相机 → 扫码 → 配对页打开 → 点 Enter DSH。
3. 这个浏览器从此有了会话（30 天）。之后直接打开 https://<node>.<tailnet>.ts.net/ 就行。

关掉开关就移除映射。自定义 servePort 时 URL 带端口（https://<node>.<tailnet>.ts.net:8443/）；面板上也会显示。

语言

侧边栏标签、面板、四步帮助文本都走 harness 自己的 locale 服务，所以跟随 Settings → General → Language，原地切换 —— 不用刷新，不用重启，也没有单独的语言设置要同步。客户端加载之前看到的那两个页面（配对、验证码过期）用不了这个服务，所以它们跟随手机浏览器的 Accept-Language；插件列表里插件自己的名称和描述，通过 locale/en.json + locale/zh.json 本地化。

工作原理

phone ──HTTPS──▶ Tailscale Serve ──▶ 127.0.0.1:<DSH port> (harness Web UI)
tailnet-only + real cert loopback only, unchanged
▲ ▲
└── pairing page hands the session cookie │ plugin registers the tailnet
to the browser from a same-site page │ authority with the /api trust fence

| 映射 | tailscale serve --bg --https=<servePort> <local port> |
| 信任围栏 | 插件在运行时注册自己的 tailnet 授权源（不用改配置档） |
| 配对 | 一次性验证码（10 分钟，单次使用，同站 + 限流），因为 Chromium 拒绝存储应用发起的重定向过程中设置的 SameSite=Strict cookie |
| 远程设置 | 一行 index-tap 引导声明 ownsHost 传输，因此在手机上打开的配置表单会持久化到主机，而不是留在页面内存里 |
| 语言 | 面板和侧边栏标签向 harness 的 locale 服务注册 zh/en 字典；主机侧失败以语言中立的 detailCode 传递，客户端之前的配对页面读取 Accept-Language |
| 诊断 | 插件配置里的 debug: true 会注册一条需主动开启的诊断路由，以及一条由标记控制的扫描路径回显 |

安全

- 仅限 tailnet。 用 tailscale serve，绝不用 tailscale funnel。
- 主机监听回环地址。 harness 始终监听 127.0.0.1；插件从不重新绑定它。
- token 不持久化。 每个进程的启动 token 只存在内存里，且仅通过已认证的面板展示；真正留存下来的是保存的会话 cookie。
- 受护栏保护的路由。 /api/tailscale-remote. 复用 harness 自带的 Host/Origin 护栏和会话门禁；门禁不可用时，插件按关闭处理（503）。
- 传输可逆。 关掉开关会移除插件创建的映射——且只移除那一条（tailscale serve 是机器级全局的，所以外来映射保持不动）。
- 已认证远程页面使用主机侧设置。 除非页面走回环，或其传输声明了归属，否则 DSH 会把页面的配置表单放在页面内存里。因此插件向提供的 index 注入一行传输引导（放在 __DSH_BOOT__ 之前）。它只声明归属——会话门禁和 Host/Origin 护栏依然生效，shell 已提供的传输保持不动。
- 不可逆：会话。 撤销传输并不会撤销已签发的 cookie；需要的话，轮换 ~/.dsh/.credentials.yaml 里的 client-connection/browser-session。

兼容性

已在 macOS（Apple Silicon）· DSH Desktop 0.2.0-rc.2 · Tailscale 1.102.4 上端到端验证，同一 tailnet 内用真机手机测试。对照 0.2.1-rc.2 包，同样的依赖读数为：dsh-client-connection、dsh-client-locale、dsh-host-frontend-static 均为 0.2.1-rc.2，@deepseek-ai/dsh-client-ui-primitives 为 0.2.1-rc.2（由 web 应用的模块映射提供，不来自 dsh/node_modules），@deepseek-ai/cordis 4.0.5，@deepseek-ai/schemastery 3.18.5 —— 全部仍在本包接受的范围内。

浏览器侧注入 slots 和 locale，在两个插槽注册上都声明 locale: tailscale-remote，并注册该命名空间的 zh/en 字典。这三者都是随 web 应用一起提供的服务（@deepseek-ai/dsh-client-locale 以 immediately 挂载），所以不涉及额外安装步骤——但若某个组合去掉了 locale 插件，本插件的 UI 也会随之消失。
未测试：Windows、Linux，以及 0.2.0-rc.2 之外的 DSH 版本（在 0.2.1-rc.2 上，除 tailnet 往返之外的部分都重新检查过）。插件依赖上游行为（/api 信任围栏、易变的插件配置、客户端插槽约定、locale 服务、tailscale serve status --json）；下面的测试套件锁定了它依赖的这些行为，所以 DSH 升级后请先跑 npm test。

开发

下面的 npm 就是 Node 自带的命令行，不需要账号，也不发布任何东西。

npm install # esbuild + runtime deps
npm run build # src/ → lib/ (the client half is inlined into the harness's lazy-CJS wrapper)
npm test # 4 suites: preflight table · artifact/reference integrity · client render/lifecycle · host routes + fence

客户端和宿主测试套件支持环境变量覆盖，可以针对已安装的副本运行，而不是工作树——这是唯一能证明用户磁盘上实际那份代码行为与测试一致的办法：

CLIENT_BUNDLE=~/.dsh/profiles/desktop/node_modules/dsh-plugin-tailscale-remote/lib/client.js node tests/client.test.mjs
HOST_BUNDLE=~/.dsh/profiles/desktop/node_modules/dsh-plugin-tailscale-remote/lib/index.js node tests/host.test.mjs

仓库结构——源码与产物：

| 路径 | 是什么 | 是否随包发给用户 |
| src/index.js | 宿主部分（源码） | ✗（lib/ 才是构建产物） |
| src/client.jsx | 浏览器部分（源码） | ✗ |
| src/locales.js | 客户端注册的 zh/en 词典，以及未挂载渲染时的回退文案 | ✗ |
| lib/index.js、lib/client.js | 构建产物，已提交，这样 github: 安装无需构建步骤即可工作 | ✓ |
| cordis.patch.yml | bundle 层：插入本插件的配置行 | ✓ |
| assets/icon.svg | DSH 插件管理器中显示的插件图标 | ✓ |
| locale/en.json、locale/zh.json | 插件列表中本插件自己的名称/描述，由 dsh-app-boot 解析 | ✓ |
| scripts/build.mjs | 构建（esbuild 包装 + 契约检查） | ✗ |
| scripts/install.mjs | 安装到 DSH 配置档——对 dsh plugin add/remove 的包装（--spec、--revert、--dry-run） | ✓ |
| tests/artifacts.test.mjs | 路径/引用漂移守卫：正是它让下一个坏掉的 bundle/… 式导入无法发布 | ✗ |
| tests/.test.mjs | 预检表 · 产物完整性 · 客户端冒烟（真实 bundle 跑在桩 DOM 里，两种语言） · 宿主冒烟（桩 cordis + 假 tailscale） | ✗ |
| dist/ | npm pack 输出（已被 git 忽略） | ✗ |

卸载

在 DSH 插件列表里移除插件，然后重启。在此之前，先在面板里把开关关掉，撤销 tailscale serve 映射。

许可证

MIT © 2026 Jiaxin Kou

由 Jiaxin Kou 构建 · GitHub