移动端视口加固 PrblyElect/dsh-web-mobile

dsh-web-mobile

为 DeepSeek Harness（DSH）web GUI 做移动端体验加固。

web GUI 面向桌面端。在手机浏览器里，页面可以随意双指缩放；在 Safari 里，只要点一下聊天输入框，它就会自动放大。这个插件借助 DSH 自己的首页渲染接缝（webServer.tapIndex）改写服务端返回的 index 页面，因此：

- 不用改 node_modules 里已安装的前端；
- 上游 Harness/前端的改动照样能进来；
- 注销插件后，页面恢复原样。

仓库名是 dsh-web-mobile；包本身的名字是 dsh-web-mobile-hardening，因为短名字已被 npm registry 上一个无关的包占用，安装那个名字会解析到别人的代码。

这个包没有发布到 npm registry。 可以从本地检出安装，从 tarball（npm pack）安装，或走插件管理器的 git 通道——三种方式下面都会讲。这里没有任何一步需要 registry 按名字解析这个插件。

注入了什么

原版页面本来就带 viewport meta。这个插件不是补一个缺失的 viewport meta：它替换原版指令，换成更严格的一条，所以服务端返回的页面里仍然只有一个 viewport meta。

- 锁定视口缩放 —— 在原版 width=device-width, initial-scale=1 上追加 maximum-scale=1 和 user-scalable=no。它做了什么、没做什么：
- 在遵守 user-scalable=no 的浏览器里，压掉双指/双击缩放；
- 在遵守该指令的 WebView 里，压掉 iOS 聚焦自动放大；
- 在出于无障碍原因忽略 user-scalable=no 的浏览器里（iOS 10+ 和 Chrome 55+ 都会忽略），它拦不住双指缩放，页面在那里仍可缩放——而这正是本插件面向的大多数浏览器，也是缩放锁定只能算尽力而为的提示、而非保证的原因。
- 粗指针下表单字段 16px 下限 —— 在 @media (pointer: coarse) 内，input、textarea、select 拿到 font-size: 16px !important。!important 是关键：前端用 CSS module 类规则给字段设样式，那条规则设的是 font 简写，而简写会直接把 font-size 重置掉。类规则在优先级上也压过更早的元素选择器，且在层叠中更靠后。普通声明两边都赢不了，所以下限必须标 important。媒体查询按指针能力判断，不按宽度，所以窄桌面窗口不受影响。按前端构建版本看，这个下限带来什么：
- 在前端的 next 线（0.2.1-rc.5，latest harness 发布的构建）上，上游字段规则在任何宽度下都是 13px，所以下限既必要又有效；
- 在 alpha 线（0.2.2-alpha.2）上，字段规则一样——同一条类规则，仍是 font 简写，仍在样式表顶层，仍不在媒体查询里。alpha 自己的样式表里没有针对该输入框、限定触摸范围的 font-size 规则（它仅有的 16px 声明落在字标和标题上），所以那里也需要这个下限。

这个下限只是保底，并不覆盖应用本身的设计：它只在检测到粗指针时生效，并且只把小于 16px 的输入框调大。
- touch-action: manipulation 加在按钮、链接、输入框和 [role="button"] 上，去掉双击缩放的延迟。
- 透明点击高亮 —— 每个元素上都加 -webkit-tap-highlight-color: transparent。

未交付的内容

- 没有侧边栏行为。 插件不会折叠、隐藏或以任何方式触碰侧边栏。已发布的前端构建没有为此暴露稳定的钩子：侧边栏守卫需要定位的那些带哈希的构建产物类名，在这些构建里并不存在，也没有 aria-label、title 或 data- 属性给侧边栏命名。针对这些选择器写的守卫永远不会触发，所以插件完全不注入 JavaScript。
- 没有安全区处理。 没有设置 viewport-fit=cover，因为插件和前端都不消费 env(safe-area-inset-)：这些内边距会作用不到任何东西。页面因此保留浏览器默认的安全区行为，而不去声称支持刘海屏布局。

范围说明 —— 刻意不做滚动或框架覆盖

插件不注入任何滚动或框架覆盖。聊天的垂直滚动和自动跟随尾部行为完全交给应用。以下尝试都试过并放弃了：冻结框架（100dvh、吸收 overflow:hidden、body padding）、用 JS 守卫对抗应用的跟随尾部自动滚动、让软键盘覆盖内容（通过 visualViewport 抬高输入区）—— 它们没有帮助，而且全局框架冻结破坏了桌面布局。如果你 fork 了本项目想重试，请把这类覆盖限定在粗指针查询（@media (pointer: coarse)）下，而不是只按宽度判断，这样窄的桌面窗口永远不会受影响。

安装

本地检出

dsh plugin --profile web add /path/to/dsh-web-mobile

本包声明了 bundle 补丁（package.json 里的 dsh.bundle.patch），所以插件管理器会自动把它注册为配置档层：不需要手写配置档补丁条目。之后重启 dsh web。

从本地检出打包成 tarball

npm pack

生成的 .tgz 是普通 npm 包：把它作为 file: 条目加到 web 配置档的依赖里，再按下文所述注册插件行。解析它不会从 registry 拉取任何东西。

Git 方式

dsh plugin add "github:PrblyElect/dsh-web-mobile#<commit>"

把 <commit> 换成该仓库真实已发布的提交 —— 占位符原样无法解析。如果 web 配置档是这样选择的，加上 --profile web 标志。

git 安装可能需要 allowBuilds 批准，针对某个包
声明安装脚本：pnpm 11 默认会拦截这类脚本，管理器会把它们列在 pendingBuilds 下，等你批准后才执行。这个包没有声明安装脚本，只有 test 脚本，所以这里没有需要批准的东西；只有确实需要时，这个键才需要写进配置档的 pnpm-workspace.yaml。

插件索引条目指向同一个东西，要求也一样：

{
"type": "git",
"commit": "<sha>",
"path": "..."
}

commit 字段必须是真实已发布的提交。生态自己发布的索引条目带有 type 和 commit；这个包的 package.json 位于仓库根目录，所以 path 字段（如果所用的 schema 有这个字段）应该是 "."。

手动安装

把包加进 web 配置档 package.json 的依赖里（file: 路径或 file: tarball 都行），然后在配置档补丁里注册插件（$DSH_HOME/profiles/web/cordis.patch.yml，在补丁列表里创建 insert 条目）：

- insert:
- id: web-mobile
name: 'dsh-web-mobile-hardening'

这里的 name: 是加载器解析的包标识符，它针对你刚在本地安装的包来解析——file: 依赖让 node_modules 里有了一个叫 dsh-web-mobile-hardening 的包，名字正好对上。这不是去注册表查询，没有上面那步依赖安装就不会生效。

然后重启 dsh web。要移除它，删掉 insert 条目（以及那条依赖）再重启——原生页面就回来了。

各安装路径分别校验什么

这里涉及两个包管理器，它们的做法并不一致。 dsh plugin 用 pnpm 安装；下面 npm 那几行，是你自己用 npm 安装 tarball 时的情况。

用 npm 时：

| 路径 | 是否校验 peer 范围 | 是否锁定版本 |
| file: 目录路径 | 否 | 否 |
| 来自 npm pack 的 file: tarball | 是——peer 超出范围会以 ERESOLVE 失败 | 由 lockfile 锁定 |

没有「npm 注册表，按名称」这一行：这个包没有发布到注册表，所以这条路径对它不存在。上面每条安装路径都在本地解析插件。

目录依赖是链接而非解析，所以 npm 从不对它校验声明的 peer 范围：走 npm 这条路，范围写错也看不出来。真正能抓到它的是下面 harness 自己的校验。

用 pnpm 时——也就是 dsh plugin 跑的那套——情况不一样：pnpm 把超出范围的 peer 报成警告，然后照样装完，每条路径都如此，包括 tarball 那条。DSH 自己的配置档没有打开 pnpm 的 strict-peer-dependencies，所以默认情况下 peer 范围只是被报告，并不强制执行。想强制的话，安装时加 --strict-peer-dependencies，或者装完检查 lockfile。pnpm peers check 可以按需报告不匹配。

harness 在 pnpm 之上还有自己的校验。 pnpm 的宽松只针对 peer 范围。DSH 的要求——engines.dsh——由插件管理器会在 pnpm 运行之前强制执行检查：本地路径或 registry 规格会对照包声明的 engines 和 peerDependencies 检查，DSH 要求不满足就拒绝操作，因此不会下载任何内容，也不会运行构建脚本。git 或 tarball 规格必须先拉取才能判断，所以改为在安装之后判断。无论哪种情况，拒绝时都会指出未满足的要求，并打印授予豁免的 allow-version 命令。

兼容性

兼容性门禁

package.json 声明：

{
"engines": {
"node": ">=24.9.0",
"dsh": ">=0.2.0-rc.1 <0.3.0-0 || >=0.2.1-a <0.3.0-0 || >=0.2.2-a <0.3.0-0"
}
}

自 0.2.1-rc.1 harness 版本起，第三方插件声明了 engines.dsh 时，兼容性优先看它，因此 dsh 范围决定 harness 是否接受插件；下面的 peerDependencies 范围是依赖解析范围，故意设得更宽。

dsh 范围为什么写成这样。 harness 评估这个范围时包含预发布版本——它用 includePrerelease 打开的方式，拿运行时版本与范围比较——所以单个 >=0.2.0-rc.1 <0.3.0-0 就已经能接受 0.2.1-rc.5 和 0.2.2-alpha.2，也就是插件验证过的两个预发布构建。

尽管如此，声明的范围还是为每个已发布的 major.minor.patch 元组写了一个比较器，原因是 npm 自己的 semver——读者很可能拿同一字符串套用它：npm 只有在范围指名了同一元组的预发布版本时，才认为预发布版本满足范围，所以按这种更严格的读法，单比较器形式会拒绝这个插件支持的版本。因此按元组逐个写是防御性的，并非 harness 要求——它在两种读法下都能接受预期版本集合，只有 harness 发布了 0.2.3 预发布版本并且读者使用 npm 更严格的语义时，才需要新增比较器。

DSH 线。 DeepSeek Harness 的 0.2.x 发布线——即 next 通道——也就是 engines.dsh 门禁接受的版本。注意两个通道不是一回事：harness 包的 latest 和 next 都指向 0.2.1-rc.5，但 peer 的 latest 标签仍是 0.0.1-rc.1，这个插件不支持它——请把 peer 装在 next，或装显式版本。tapIndex 接缝和提供的 标记贯穿 0.2.x 线；viewport 替换已对照前端的 next（0.2.1-rc.5）和 alpha（0.2.2-alpha.2）构建验证过。转换本身不匹配任何上游类名、id 或属性，所以前端重新构建不会破坏它。

Peer。 @deepseek-ai/dsh-host-webserver——拥有 webServer 服务及其 tapIndex 转换的包，也是这个插件唯一调用的 API。运行时不再导入 Harness 的其他任何东西。
运行时。 Node >=24.9.0，包管理器 pnpm@11.7.0。Node 版本下限与 harness 自身的 alpha 线一致，后者已把最低版本提高到 Node 24.9。官方 @deepseek-ai/ 包没有声明 engines，也没有声明自己的 packageManager 字段，所以里面没有可用来对照的东西。

peer 范围，以及为什么这样写

声明的范围是十个比较符，用 || 连接——peer 每发布一个预发布元组，就对应一个比较符：

| 预发布元组 | 比较符 |
| 0.1.0 | ^0.1.0-rc.6 |
| 0.1.1 | >=0.1.1-rc.0 <0.2.0 |
| 0.1.2 | >=0.1.2-a <0.2.0 |
| 0.1.3 | >=0.1.3-a <0.2.0 |
| 0.1.5 | >=0.1.5-a <0.2.0 |
| 0.1.6 | >=0.1.6-a <0.2.0 |
| 0.1.7 | >=0.1.7-a <0.2.0 |
| 0.2.0 | >=0.2.0-rc.1 <0.3.0-0 |
| 0.2.1 | >=0.2.1-a <0.3.0-0 |
| 0.2.2 | >=0.2.2-a <0.3.0-0 |

npm 的 semver 有一条规则，对任何覆盖预发布线的范围都起决定作用：预发布版本要满足某个范围，前提是这个范围本身点名了同一个 major.minor.patch 元组的预发布版本。 显而易见的 >=0.1.0-rc.6 <0.3.0 只为 0.1.0 点名了预发布版本，所以它放行 0.1.0-rc.6 … 0.1.0-rc.8，却拒绝之后每一条预发布线——包括 0.2.0-rc.2 和 0.2.1-rc.5，而这两个版本正是本插件验证时用的版本。没有任何一对比较符能表达「从 0.1.0 到 0.3.0 的每一个预发布版本」；只能每个预发布元组配一个比较符。

上面十个比较符覆盖了从 0.1.0 到 0.2.2 的每一个已发布预发布元组，同时仍然拒绝 0.3.0-rc.1 以及所有比 0.1.0-rc.6 更旧的版本（0.0.1-rc.1、0.0.1-rc.2、0.0.1-rc.3、0.0.1-rc.5、0.1.0-rc.2 和 0.1.0-rc.3 这些构建）。不要把它合并成单个 >=/< 对：那样会悄悄把插件自己验证过的版本踢出范围，也会丢掉更旧线上的读者可能所在的 0.1.x 元组。

范围放行的每个版本都带有插件需要的那一个 API——ctx.webServer.tapIndex——这一点是解包已发布的 tarball 核对出来的，不是读 changelog 得出的。

文件

- index.js — DSH 插件（name、inject: ["webServer"]、apply）。
- cordis.patch.yml — 插入插件行的 bundle 补丁。
- package.json — ESM 包元数据；仅声明（无运行时导入）。
- test/index.test.mjs — index 转换的零依赖测试。

本插件是纯宿主端：只带一个 dsh.bundle.patch，别的什么都没有。没有 dsh.client 块，因为没有客户端那一半——加固内容是注入到所服务页面里的标记，不是在 DSH 客户端内运行的 bundle。同时声明了客户端那一半的插件看起来会不一样；这个差异是有意为之。

验证

插件附带一个零依赖测试，跑在 Node 内置的测试运行器上：

node --test "test//.test.mjs"

或者在包目录下：

npm test
测试文件要逐个写明文件名，因为只给一个目录参数并不算数：在当前的 Node 版本上，node --test test/ 会把这个参数当成模块路径来解析，而不是扫描目录，结果在任何测试运行之前就失败了。在包目录下直接执行 node --test 也可以。

测试通过伪造的 ctx.webServer.tapIndex 驱动真实的转换逻辑，并断言注入行为：原有的 viewport meta 会被替换，而不是重复添加；最终只保留一个 viewport meta；即使原有 meta 的 name= 属性不在首位，也仍能匹配；页面没有原有 meta 时会注入一个；存在多个原有 meta 时会合并成恰好一个。测试还断言样式块注入在应用的样式表之前——这个顺序是约定的一部分，因为上游的字段规则是一条类规则，它设置 font 简写属性，并且在层叠中排在后面——还断言 16px 规则存在，且作用域限定在 coarse-pointer 查询内，以及插件不注入任何 JavaScript，也不注入 safe-area 指令。

测试套件还会检查 engines.dsh 版本范围的行为：它必须接受插件经过验证的那些版本，并拒绝这些版本两侧的版本线，既要按 harness 的比较方式（包含预发布版本），也要按 npm 更严格的比较方式。这项检查需要 semver 求值器，所以包内自带了一个小型实现，放在 test/semver-lite.mjs，而不是引入依赖；它的行为已针对本包用到的版本范围和版本号，与 node-semver 做了交叉核对。

License

MIT — 见 LICENSE。