移动端适配包 LUgABeEEE/dsh-adapt-packs

dsh-adapt-packs

DSH 移动端界面的可选适配包。

手机上的第三方插件面板有三个问题，插件在自己组件内部解决不了：拇指够不到的触摸目标、比手机内容区还宽的面板根节点、被浮动组件盖住的行。本仓库就是针对这三个问题的小型修复注册表，以包的形式交付，由 dsh-mobile 通过公开的 extensions/ 目录加载——另外还有一份兼容性列表，逐个记录第三方插件在手机上按原样是否可用、是否需要这些包之一、应该在上游修复，还是根本无法从外部修复。

这里不会 fork 或修改已安装的 DSH 或 dsh-mobile。一个包就是一个目录：

$DSH_HOME/mobile-access/extensions/<id>/
├── extension.json # schemaVersion, id, name, version, description — exactly these five ├── mobile.css # injected by the host ├── mobile.js # optional; window.dshMobile.define({ apiVersion: 1, id, activate }) └── README.md # ignored at runtime

复制进去，宿主两秒内就会加载；移出来，它就消失了。不用重启，不用配置文件，也不用第二套认证模型。

一个插件，多个包

dsh-mobile 永远不会收到属于自己的适配包：完整部署是 dsh-mobile + 本包。宿主只提供它公开的 extensions/ 目录，以及注入 mobile.css / mobile.js 的运行时；决定手机适配什么的一切都在这里——包、catalog.json、兼容性列表、提供一键安装的设置面板，以及命令行。

要装全套，宿主只需要看到一个扩展：

npm run bundle # build/dsh-ui-optimizer/
node tools/install.mjs plugin build/dsh-ui-optimizer --yes

tools/bundle.mjs 把每个包的 define() 改写成收集器，并注册单个 id，这样包仍然是开发和验证的单位，而打包产物是安装的单位。包仍然可以逐个安装（node tools/install.mjs pack <id>），build/ 是生成产物，不是源码。

各部分的位置

部署涉及两个仓库：saya-ch/dsh-mobile 是宿主，只提供它的 mobile-access/extensions/ 运行时，以及包无法提供的能力；本仓库拥有所有包、目录、兼容性列表、面板和工具。边界与变更策略写在 docs/ARCHITECTURE.md 里——简而言之就是「适配内容留在这里，宿主只拿接口」。

包

| 包 | 范围 | 作用 |
| core-panel | 插件面板 | 面板内 44px 的点击下限——0.8.x 上唯一的来源，也是宿主自带下限后会自动退让的兜底（#319）；纯图标按钮宽度；宽度回收 |
| shell-chrome | shell 本身 | 两种抽屉状态：停靠的会话/项目行（role="treeitem"，32/34 → 44px）、侧栏图标按钮和抽屉自己的开关（36×36 / 28×28 → 44×44，含宽度）；「返回会话」栏改成只升不降的地板，绝不压缩宿主自带的 48px |
| floaters | 浮动组件 | 测量右下角固定组件，预留它们的高度，最后几行不再被压在下面 |
| dshmarket-mobile | 插件市场面板 | 给 dshmarket 1.73.x 加 44px 触控地板：按钮、图标按钮和搜索框，作用域限定在 [data-dsh-market-root] |
| dsh-context-mobile | 上下文/费用面板 | 给 dsh-context 0.79.x 加 44px 触控地板，仅限 dsh-mobile 0.8.x（0.8.1+ 自带同样的地板，此时本包自动退让）：粒度按钮、纯图标清除按钮、搜索/选择框和自定义 role=button 行；通过插件自己的 data-lc- 属性定位，用本包的标记限定作用域 |
| host-service-panel-mobile | 宿主可观测性面板 | 给 dsh-host-service-panel 0.7.x 加窄屏布局和 44px 触控地板，作用域限定在 [data-dsh-hsp-root] |

每个包都是实验性的，且默认关闭。catalog.json 逐个记录每个包实际验证了什么、没验证什么——evidence 字段就是让你在信任某个包之前先读的。

兼容清单

不是每个插件都能从外部修好——「这个在手机上没问题」也值得写下来。compat.json 给每个第三方插件记一条结论：

dsh-adapt-packs compat # the whole list
dsh-adapt-packs compat --verdict pack # only entries this repository has a pack for

| 结论 | 含义 |
| native | 原样发布即可在手机上使用 |
| pack | 本仓库有对应的包（pack 字段给出包名） |
| upstream | 能修，但只能由插件作者修 |
| blocked | 无法从外部修（canvas、原生组件、拿不到 DOM） |

每条都带上判定时的版本、手机上的实际表现（尽量给数字）和证据强度——实测、读代码，还是未验证。格式与规则见 docs/兼容清单.md。想补充条目，请开 compat suggestion issue，带数字来，别带形容词。

dsh-adapt-packs status 回答另一个问题——这台机器装了哪些包、哪些被禁用、哪些在目录里但没装。

安装

从 npm 安装

npm install -g dsh-adapt-packs

dsh-adapt-packs list # what is in the catalog
dsh-adapt-packs install core-panel --dry-run # plan only
dsh-adapt-packs install core-panel --yes # write into $DSH_HOMEbash
dsh-adapt-packs uninstall core-panel --yes # move it out (reversible)

发布的 tarball 里带 packs/、catalog.json、docs/ 和工具脚本，还包括 packs/<id>/shots/ 下的证据截图（tarball 约 700 KB）。dsh-adapt-packs check 跑的校验流程和仓库里一样。

在 DSH 里（设置面板）

这个包同时也是一个 DSH bundle：按常规方式安装后，设置里会出现 插件适配 分区，目录、安装状态和兼容性列表都只差一次点击。
bash
dsh plugin add dsh-adapt-packs # or install the tarball from the market

它和命令行共用同一个 lib/store.mjs，所以面板显示的结果不会和 dsh-adapt-packs status 对不上。宿主路由是 /api/adapt-packs/{state,install,uninstall}，除此之外不暴露任何接口。

从本地检出运行 bash
node tools/check-pack.mjs # validate every pack first
node tools/install.mjs pack core-panel --dry-run
node tools/install.mjs pack core-panel --yes
node tools/install.mjs --uninstall core-panel --yes

or install the whole set as one extension

node tools/bundle.mjs
node tools/install.mjs plugin build/dsh-ui-optimizer --yes

install.mjs 默认只做 dry run，会解析 $DSH_HOME（或 ~/.dsh），拒绝覆盖已存在的 pack，并把卸载的 pack 移到 mobile-access-adapt-disabled/，方便以后恢复。

Windows

tools/ 里都是普通 Node 脚本（Node 20+）；这里不假设你用的是 POSIX shell、/tmp 或大小写敏感的路径，命令在 PowerShell 里原样可用。fixture 检查器需要 Playwright 和它的 Chromium 构建： powershell
npm install --no-save --no-package-lock playwright
npx playwright install chromium # downloads into %LOCALAPPDATA%\ms-playwright

check-pack.mjs 按下面的顺序查找 Playwright，失败时会列出它试过的每个路径：DSH_PLAYWRIGHT（一个 playwright/index.js 文件 或 playwright 包目录）→ $DSH_HOME/profiles/{web,desktop,headless}/node_modules/playwright → 本仓库自己的 node_modules → 常规模块解析。缺少 Chromium 时，报错信息会指向 npx playwright install chromium 和预期的浏览器缓存位置（Windows 上是 %LOCALAPPDATA%\ms-playwright）。

设置主目录要用 PowerShell 语法——POSIX 的 export 写法在这里不适用： powershell $env:DSH_HOME = 'C:\Users\you\.dsh' # default when unset: %USERPROFILE%\.dsh

install.mjs 据此推导出 mobile-access\extensions\<id>，并把卸载的 pack 移到 mobile-access-adapt-disabled\<id>。以 ~ 开头的路径会被展开，需要 pack 路径的地方 \ 和 / 都接受。已存在的 pack 目录按大小写不敏感的方式解析（PACKS\CORE-PANEL 就是 packs/core-panel），而 pack id 和 catalog.json 的查找保持小写。支持 CRLF 检出：CI 里的 windows-latest 任务每次 push/PR 都会在 CRLF 工作树上跑完整的 fixture 套件。
正常安装不会走到一条路径：install.mjs 里的 EXDEV 回退（用复制 + 删除代替 rename）。安装源和目标都在同一个 $DSH_HOME 下，所以实际跑的是普通 rename；回退留给挂载方式特殊的 home，只做文档说明，不声称已测试。

定向 fixture

内置 fixture 测的是通用面板，刻意按桌面优先设计。针对某个具体插件的包，可以自带 packs/<id>/fixture.html，里面放该插件自己的 DOM；这时 check-pack 的每一轮（baseline、pack、opt-out、桌面零回归）都改用它来跑。没有这个文件就用内置 fixture，报告会说明跑的是哪个——人类可读输出打印 fixture：内置（回退内置 fixture），--json 里带 fixture.kind。
bash
node tools/check-pack.mjs docs/examples/fixture-pack --desktop # runnable example

约定写在 docs/定向-fixture.md：允许的标记（只有 DOM + 内联样式，不能有脚本、事件处理器、外部引用或 data: 引用，≤ 256 KB）、必须提供的 shell/panel 钩子、target / usesHostMarkers / evidence 如何描述 fixture。docs/examples/fixture-pack/ 是可运行的示例，不是真包：它在 packs/ 之外，不在 catalog.json 里，因此会报一条无害的 catalog 警告。

退出适配 html

每个包都完全停止生效——panel 间距回到自己的值，shell 行回到 shell 的尺寸。这一点由 harness 检查，不靠文字声明。

0.8.1 上要小心： 宿主自己的 panel 下限和它的门控用的是同一个属性（lib/mobile-layout.js:507 里的 :not([data-dsh-adapt="off"])），所以 off 同时会关掉宿主下限——结果可能比完全没有包还糟（t12 实测：Context Insights 最小 44 → 19.8px，<44 0 → 115）。想停用某个包又保留宿主下限，请卸载/停用扩展，不要设这个属性。

已验证的内容

| | 状态 |
| fixture 测量：390×844 粗指针、1280×800 细指针零回归、退出适配 | ✅ 每个包（node tools/check-pack.mjs） |
| Windows 11 + Chromium 上的 fixture 测量（node tools/check-pack.mjs --desktop） | ✅ 每个包（2026-10-31，早先的套件：87 通过 / 0 失败 / 8 跳过；套件此后有变动——windows-latest 上的 CI 跑的是当前版本） |
| dsh-mobile 0.8.0 上的真实运行时 | ✅ 在真实网关上实测（390×844，粗指针，Plugins 面板）——见工作区里的 实测-0.8.0-20261031.md |
| 0.8.1（含 #319） 上的真实运行时 | ⏳ 2026-11-01 发布；宿主写入标记后，我们的门控（:not([data-dsh-panel])）会让高度下限和根宽度钳制退让——用 check-pack 的 host-probe 注入宿主自己的 0.8.1 规则验证过，没有通过真实的 0.8.1 安装重新测量。这台机器现在跑 0.8.1；下面的设备实测仍来自 0.7.1 应用 |
| 0.7.1 上的真实运行时 | ✅ 历史上验证过（2026-10-31 早先一次运行）；122px / 36→44px 这些数字与 0.8.0 相同 |
| 真机 | ✅ Android App 实测（2026-11-01，Redmi K90 Max / Android 17 / dsh-mobile App 0.7.1）：装 core-panel（或整套）后，槽位达到 141/44/0，而无包基线是 141/14/141（只装 dshmarket-mobile 仅修好市场根节点）；真实 env(safe-area-inset-) 为 0，因为这个 App 不是 edge-to-edge；软键盘把视口从 786 缩到 472。见 docs/真机验证.md。iOS、拇指可达手感、edge-to-edge App 仍未验证 |

两条发布线：0.8.0 与 main（#319）

dsh-mobile 在 2026-10-31 合并了 #319（6c50b13），此时 v0.8.0 已发布（2026-10-30），随后在 v0.8.1（2026-11-01）中发布。所以存在两条宿主线——我们的包必须在两边都表现正常：

| | release 0.8.0 | #319 之后的 main |
| 宿主写入 data-dsh-panel | 否（grep：0 命中） | 是，写在 .dshm-main 上 |
| 插件面板控件的 44px 点击下限 | 否（实测 94/94 个控件 < 44px） | 是，宿主提供 |
| 面板根节点宽度钳制 | 否 | 是 |
| 纯图标按钮的 min-width | 否 | 是（0.8.1 同时钳制宽和高） |
| 面板页底部安全区 | 否 | 否 |

因此 core-panel 把高度下限和宽度钳制挂在 .dshm-main:not([data-dsh-panel]) 上：在 0.8.0 上它是唯一来源，在 0.8.1 上（该属性由宿主负责）它让位，而不是重复实现（也从不写宿主的属性——它保留自己的 data-dshm-adapt-panel）。它的 min-width:44 规则保留为 0.8.0 的兜底；0.8.1 提供同样的值，所以在 0.8.1 上它只是同值安全网，而非独有贡献。check-pack 注入宿主自己的 0.8.1 规则来验证这个门控（runtime.hostGate.*）。

这就是这些包停留在 experimental 而非 candidate 的原因。测量是另一个问题，有工具可用：dsh-ui-lab 按真实设备比例打开 DSH 界面，截取面板，并用像素差异对矩阵运行做门控。

无法回避的依赖

这些包直接使用 dsh-mobile 自己的类名——.dshm-shell、.dshm-main、.dshm-mainContent、.dshm-drawer、.dshm-panelNav、[data-slot="sidebar"]。dsh-mobile 不承诺保留它们，其文档也明确排除维护一张以第三方类名为键的通用覆盖表。catalog.json 列出每个包触及的标记（usesHostMarkers 字段），正是为了让破坏可追溯到具体的包，但重新设计仍可能破坏它们。

持久的修复方案是宿主侧的契约：为面板状态、插件自有界面元素、以及退出机制提供稳定属性。在契约出现之前，这个仓库就是一层需要维护的兼容层——不是 dsh-mobile 维护者发布或支持的东西。

贡献新插件包从 packs/_template/ 起步，并且必须通过 node tools/check-pack.mjs packs/<id> 检查。规则写在 docs/收录标准.md 里（中文；检查工具就是这些规则的可执行版本），包括：可以声明哪些能力、插件包必须怎样划定范围、opt-out 是什么意思、插件包不能碰什么。

docs/phone-instance.md 讲的是怎么无头驱动真实手机页面，插件包正是靠这一步在 fixture 之外完成验证。

发布

推送一个与 package.json 匹配的 tag，.github/workflows/publish.yml 会校验目录，然后用 npm provenance 发布。
bash
npm version patch --no-git-tag-version
git commit -am "chore: 0.1.1"
git tag v0.1.1 && git push origin main v0.1.1

这个 job 需要仓库 secret NPM_TOKEN（一个 granular token，对 dsh-adapt-packs 有「Read and write」发布权限）。workflow_dispatch 默认执行 npm publish --dry-run。

License

MIT — 见 LICENSE。