建议：给常用插件做一批「安卓端适配」，用 dsh-global-todo 当样板 / Proposal: a mobile-adaptation track for popular plugins

[LUgABeEEE]

这是一份流程/协作提案，不涉及对第三方插件仓库的改动。欢迎在回复里直接提名插件或纠偏。
A process and collaboration proposal — it does not change any third-party repository. Plugin nominations and corrections are welcome in the replies.

中文

问题

DSH Mobile 的立场很清楚：移动层负责布局与连接，具体插件在小屏上好不好用，取决于插件自己。这一定位是对的，但留下一个空档：

• 用户会在手机上装一堆常用插件，然后发现面板按钮太小、工具栏挤成一条、弹窗超出屏幕；
• 插件作者多半没有安卓设备，也不知道「手机上该按什么标准改」；
• 目前没有一份可执行的适配清单，也没有一个「已经适配好」的样板可以照抄。

提议

开一条轻量的移动适配线，四步：

1. 提名：由用户/维护者列出 5–10 个高频插件（优先有侧栏面板、列表、表单的；纯后台服务类跳过）。
2. 定标准：给出一份最小适配清单（见下），只要求「不破坏桌面 + 小屏可用」，不要求重做交互。
3. 做样板：拿一个真实插件走完整流程，产出可对照的改动与截图。
4. 验收：每个插件一个 issue，用同一份清单勾选；作者不同意的，就只记录现状，不强行改。

适配清单（草案）

• 断点用面板实测宽度（建议 ≤600px），不要用 UA 或 viewport：同一个面板在桌面窗口变窄时也该受益。
• 触控目标 ≥44px；圆形勾选框可以保持 24px 视觉，只放大命中区。
• 横向排列的 chip/标签条在小屏改为可横向滚动，而不是被裁掉。
• 桌面专属提示（/ 快捷键、kbd 角标）在小屏隐藏。
• 底部留出 env(safe-area-inset-bottom)；列表容器设 overscroll-behavior: contain。
• 正文字号优先跟随外壳的 --dsh-content-font-size，让「移动端字号」设置生效。
• 行内动作（文字按钮）在小屏收成图标，保留 aria-label；不隐藏唯一入口。
• 预览/验收：如果插件自带静态预览 harness，给它加一个 --width=390 档；没有的话，用 390×844 截图加一份手工检查表。

样板：dsh-global-todo

我们把这个流程在自己的插件上走了一遍（0.19.0 的移动档，尚未公开发布），可以作为参照：

• 信号：按面板实测宽度切 data-mobile（≤600px），桌面一字不动；
• 改动：按钮/输入 44px；行内「交给 Agent」收成图标；筛选条横向滑动；隐藏 / 提示；底部让出安全区；字号取 --dsh-content-font-size；设置弹层贴两边而不是固定 360px；
• 结果：390×844 下卡片高度从约 250px 降到约 150px，所有交互目标 ≥44px，桌面截图逐像素不变；
• 可回归：给预览夹具加了 --width=390（让静态 harness 回答面板的宽度测量），把移动分支纳入渲染检查，并生成 390×844 的基线截图。这样下次改样式不需要真机就能发现回归。

边界

• 不替第三方插件仓库强行改代码；适配由作者或经作者同意的 PR 完成。
• 不在移动层按类名注入第三方 CSS：类名一变就碎，而且会同时影响桌面。
• 不承诺「所有插件都能适配」；逐个评估，后台型插件明确不在此列。

征求

• 哪些插件优先？欢迎在回复里提名并说明使用场景；
• 维护者是否愿意让这份清单以 docs/ 指南或置顶讨论的形式存在？
• 插件作者是否接受「先提 issue、再提 PR」的流程？

我们这边可以先出指南初稿、把 dsh-global-todo 的适配整理成可对照的 diff 与截图，并挑 1–2 个插件在作者同意后提适配 PR。

English

The gap

DSH Mobile's position is clear: the mobile layer owns layout and connectivity, and whether a plugin is usable on a small screen is the plugin's own responsibility. That is the right boundary, but it leaves a gap:

• users install common plugins on the phone and find tiny buttons, a toolbar squeezed into one row, dialogs wider than the screen;
• plugin authors usually have no Android device and no clear answer to "what should I change for mobile?";
• there is no executable checklist and no worked example to copy.

Proposal

A lightweight mobile-adaptation track, in four steps:

1. Nominate: users and the maintainer list 5–10 high-frequency plugins (prefer ones with sidebar panels, lists, forms; skip pure background services).
2. Define the bar: a minimal checklist (below) that asks only for "desktop unchanged + usable on a phone", not a redesign.
3. Build one worked example: take a real plugin through the whole flow and publish the diff and screenshots.
4. Verify: one issue per plugin, checked against the same list; if an author declines, record the status and stop there.

Adaptation checklist (draft)

• Switch on the panel's measured width (600px or less suggested), not on a user agent or the viewport: the same panel benefits when a desktop window is narrow.
• Touch targets of at least 44px; a round checkbox may stay visually 24px and grow only its hit area.
• Horizontal chip/tab strips become scrollable sideways on a phone instead of losing their tail.
• Desktop-only affordances (/ shortcut, kbd hints) are hidden on a phone.
• Reserve env(safe-area-inset-bottom); give the list container overscroll-behavior: contain.
• Let body text follow the shell's --dsh-content-font-size so the mobile text-size setting applies.
• Collapse inline text actions to icons with an aria-label, but never hide the only entry point.
• Verification: if the plugin ships a static preview harness, add a --width=390 mode; if not, use 390×844 screenshots plus a manual checklist.

Worked example: dsh-global-todo

We ran this flow on our own plugin (the 0.19.0 mobile layout, not yet published publicly):

• Signal: a data-mobile branch keyed on the panel's measured width (600px or less); desktop untouched.
• Changes: 44px controls and inputs; the inline hand-off collapses to its icon; filter chips scroll sideways; the / hint disappears; the bottom padding yields to the safe area; type follows --dsh-content-font-size; the settings sheet spans both edges instead of a fixed 360px card.
• Result: at 390×844 the card height drops from roughly 250px to roughly 150px, every target is at least 44px, and desktop screenshots are pixel-identical.
• Regression: the preview harness gained a --width=390 mode (a static harness that answers the panel's width measurement), the mobile branch is asserted on every render check, and 390×844 baselines are generated. Style changes can be caught without a device.

Boundaries

• Do not rewrite third-party repositories; the author or an author-approved PR does the adaptation.
• Do not inject third-party CSS from the mobile layer by class name: it breaks the moment a class changes and can hit the desktop at the same time.
• Do not promise that every plugin can be adapted; evaluate case by case, and say plainly that background-only plugins are out of scope.

Asking

• Which plugins should come first? Nominations with a use case are welcome in the replies.
• Would the maintainer accept this checklist as a docs/ guide or a pinned discussion?
• Are plugin authors comfortable with "issue first, PR second"?

We can start with the guide draft, turn the dsh-global-todo work into a reference diff plus screenshots, and approach one or two plugins with an adaptation PR once the author agrees.

[LUgABeEEE]

这是 #279 的指南初稿（中文全文）。英文版会随 docs PR 一起提供，指向同一套清单与验收方式。

范围说明：只要求「桌面不变 + 小屏可用」，不重做交互；文中的 dsh-global-todo 是样板，未公开发布的部分已注明。

---

移动端插件适配指南（初稿）

面向 DSH 插件作者。目标只有一个：桌面不变，小屏可用。
不要求重做交互，不要求安卓真机（但真机验收仍是最后一步）。

英文摘要见文末 English summary。

---

1. 移动页是怎么承载你的插件的

先理解宿主，再改自己的面板。DSH Mobile 在已认证的手机页面上使用专用布局，插件仍然由 DSH 正常加载：

事实	对你的影响
面板注册在 main 槽时，占满手机宽度，上方有一条 56px 的「返回会话」栏	你的面板高度比桌面少 56px；不要假设自己独占整屏
侧栏是 340px 抽屉，不是常驻列	侧栏入口在手机上会被抽屉宽度限制，文字要能收缩
布局提供 [data-pane="conversation"] / [data-pane="sidebar"] 与 .dshm-shell	需要针对性选择器时优先用这些标记，不要猜桌面 CSS 模块类名
外壳对 input/textarea 强制 font-size: max(16px, …)	你的输入框会变大；表单密度要按这个前提设计
外壳只对公共插槽做触摸目标修正	你自己的按钮、行内动作、关闭键要自己保证 ≥44px
插件在小屏是否易用，由插件自己负责（这也是 DSH Mobile 的明确立场）	移动层不会替你重排布局，也不会按类名注入你的样式

---

2. 核心决定：用「实测宽度」，不要用 UA 或 viewport

推荐做法：测量面板自身的宽度，按阈值切换移动档。

// 在面板根节点上过一次测量；ResizeObserver 保证侧栏折叠、窗口变窄也会重新判断
const MOBILE_MAX_WIDTH = 600
const [panelWidth, setPanelWidth] = useState(null)
const isMobile = panelWidth !== null && panelWidth <= MOBILE_MAX_WIDTH

useEffect(() => {
  const element = rootRef.current
  if (element === null) return undefined
  const measure = () => setPanelWidth(element.getBoundingClientRect().width)
  measure()
  window.addEventListener('resize', measure)
  const observer = typeof window.ResizeObserver === 'function' ? new window.ResizeObserver(measure) : null
  observer?.observe(element)
  return () => {
    window.removeEventListener('resize', measure)
    observer?.disconnect()
  }
}, [])

// 根节点带出状态，CSS 只认这一个开关
h('div', { className: 'my-panel', 'data-mobile': isMobile ? '1' : '0' }, …)

为什么不用 @media (max-width: 600px) 或 UA 判断：

• 面板宽度 ≠ 视口宽度。手机页是视口宽，但桌面侧栏里的同一面板可以只有 400px——这时它同样需要移动档；
• 桌面窗口拖窄时，用户期望的是「能用」，不是一个假装自己很宽的布局；
• 实测宽度可以用静态预览夹具喂一个固定值（见第 4 节），从而让适配真正可回归。

阈值选 600px 不是规定。已有的双列断点（例如 ≥960px 开第二列）继续保留，两者互不冲突：data-mobile 管触控与密度，data-wide 管列布局。

---

3. 适配清单

每条都给出「为什么」和「最小做法」。按影响从大到小排列。

3.1 触控目标 ≥44px

为什么：桌面尺寸的 28–32px 按钮在手机上点不中，误触比慢更烦。
做法：按钮、输入、选择器统一 min-height: 44px；图标按钮补 min-width: 44px。圆形勾选框保持 24px 视觉，只放大命中区：

[data-mobile="1"] .check { position: relative; }
[data-mobile="1"] .check::after { content: ''; position: absolute; inset: -10px; }

常见错：把整张卡片都放大。命中区可以扩，视觉尺寸不必跟着变。

3.2 横向 chip / 标签条改为可横滑

为什么：手机上筛选条、分组标签是最先被裁掉的东西，而且被裁的那几个往往正是「只在有数据时才出现」的过滤器。
做法：

[data-mobile="1"] .chips {
  flex-wrap: nowrap; overflow-x: auto; overflow-y: hidden;
  padding: 0; scrollbar-width: none; -webkit-overflow-scrolling: touch;
}
[data-mobile="1"] .chips::-webkit-scrollbar { display: none; }
[data-mobile="1"] .chip { flex: 0 0 auto; min-height: 44px; }

常见错：只给容器 overflow-x:auto，却让分隔条（width:1px 的 divider）跟着换行，于是行尾挂着一根孤零零的竖线。移动档直接隐藏分隔条。

3.3 行内文字动作收成图标

为什么：一行里的「交给 Agent」「编辑」「更多」并排，会吃掉标题的宽度，把正文挤成两三行。
做法：把文字包一层 <span class="btn-label">，移动档隐藏它、保留 aria-label；菜单与详情页继续保留文字入口。

h('button', { className: 'btn', 'aria-label': dispatchLabel }, h(Icon, { name: 'play' }), h('span', { className: 'btn-label' }, dispatchLabel))

[data-mobile="1"] .btn-label { display: none; }
[data-mobile="1"] .btn { min-width: 44px; padding: 0; justify-content: center; }

常见错：连唯一入口一起藏掉。文字可以消失，动作不能消失。

3.4 隐藏桌面专属提示

为什么：/ 聚焦搜索、kbd 角标、快捷键表，在没有键盘的设备上只是噪声，还占宽度。
做法：移动档隐藏 .kbd 一类元素；快捷键说明留在关于/帮助里。

3.5 底部安全区 + 滚动边界

为什么：面板自己是滚动容器时，外壳的顶部安全区管不到列表末尾；惯性滚动还可能把背后页面一起带着走。
做法：

[data-mobile="1"] .inner { padding-bottom: max(28px, calc(14px + env(safe-area-inset-bottom))); }
[data-mobile="1"] .list { overscroll-behavior: contain; }

3.6 字号跟随外壳变量

为什么：DSH Mobile 有「移动端字号」设置，外壳把它放在 --dsh-content-font-size 上（默认 16px）。插件若写死 13px，调大字号时只有输入框变大，比例失真。
做法：

[data-mobile="1"] .panel { font-size: var(--dsh-content-font-size, 15px); }
[data-mobile="1"] .meta { font-size: max(12px, 0.8em); }

桌面没有这个变量，回退值即可，不会影响电脑。

3.7 弹层与表单：贴边、单列

为什么：固定 360px 的设置卡放进 390px 视口会两边被切；两列表单在手机上挤成一条。
做法：设置/详情类弹层在移动档贴两边（left/right: 8px，保留实测 top），表单 grid 收成单列，textarea 至少 96px。

[data-mobile="1"] .settings { width: auto; max-width: none; }
[data-mobile="1"] .form-row { grid-template-columns: minmax(0, 1fr); }
[data-mobile="1"] textarea { min-height: 96px; }

3.8 标题区压缩、列表密度

为什么：手机首屏要留给内容。20px 标题 + 两行副标题 + 三个按钮会占掉四分之一屏。
做法：标题降到 ~1.2em，副标题单行截断；卡片间距收紧，但不要把触控目标一起收紧。

---

4. 验证：让适配可回归

适配最容易烂在「只有真机能看出来」。下面这套做法可以让大部分回归在 CI 里发现。

4.1 给静态预览夹具加 --width

如果你的插件用「服务端渲染 + 静态 HTML 预览」做截图基线，那么面板的宽度测量在这些静态页里不会执行（没有布局引擎），结果永远落到宽屏分支。解决办法：让夹具回答测量。

// tools/preview.mjs（示意）
const viewport = { width: 0, height: 0 }
for (const arg of process.argv.slice(2)) {
  const m = /^--(width|height)=(\d+)$/.exec(arg)
  if (m) viewport[m[1]] = Number(m[2])
}
// 渲染时给每个 ref 一个按目标宽度回答的布局桩
if (typeof type === 'string' && viewport.width > 0 && props?.ref) {
  props.ref.current = {
    getBoundingClientRect: () => ({ width: viewport.width, height: viewport.height, top: 0, left: 0, right: viewport.width, bottom: viewport.height }),
    contains: () => false, focus() {}, blur() {}, scrollIntoView() {},
    querySelectorAll: () => [], addEventListener() {}, removeEventListener() {},
  }
}

这样 --width=390 渲染出的就是真实的窄屏分支，而不是「把桌面页缩小」。

4.2 把结构断言接进渲染检查

至少断言：

• 390px 渲染出现了移动档标记（例如 data-mobile="1"）；
• CSS 里仍然存在 44px、safe-area-inset-bottom、--dsh-content-font-size 这几条规则；
• 被隐藏的提示（kbd）和收起的动作标签，仍然保留可访问名称；
• 桌面渲染与基线逐像素一致（改样式后重拍、对比）。

4.3 截图基线

• 手机档：390×844，至少「列表 / 详情 / 设置」三态；
• 桌面档：改完后重拍，与旧图做像素对比，确认是 0 差异（或只差预期的那几处）。

4.4 静态检查证明不了的事

必须留到真机：软键盘弹出后的可视区、真实 env(safe-area-inset-*) 的值、惯性滚动与回弹、系统字号放大后的换行。文档里把这条写清楚，比假装验过更有用。

---

5. 样板：dsh-global-todo

一个真实插件走完整流程的记录，供对照。

项	值
信号	面板实测宽度 ≤600px → data-mobile="1"；桌面不变
触控	按钮/输入/筛选 44px；圆形勾选框保持 24px 视觉 + 伪元素扩命中区
信息密度	行内「交给 Agent」收成图标（aria-label 保留）；「谁加的」移入详情；meta 从「每条独占一行」回到每行 2–3 条
横向条	筛选 chip 单行横滑，隐藏分隔条；工具栏改单列、搜索满宽
桌面提示	/ 角标与 kbd 隐藏
安全区	底部 max(28px, 14px + env(safe-area-inset-bottom))；列表 overscroll-behavior: contain
字号	正文取 --dsh-content-font-size（回退 15px）
弹层	设置卡贴两边、保留实测 top，不再固定 360px
结果	390×844 卡片高度约 250px → 150px；所有目标 ≥44px；桌面截图逐像素不变
可回归	预览夹具加 --width=390；渲染检查断言移动分支与三条关键规则；生成 390×844 基线

改动只用了三个稳定挂钩：data-mobile（开关）、一个文字标签的包装类（用于收起）、以及一到两个「移动档要隐藏的事实」的类名（例如创建者归属）。没有第二套渲染路径——详情仍然只有一份实现。

---

6. 给插件作者的模板

6.1 Issue 模板

## 插件与小屏
- 插件名/版本：
- 面板位置（侧栏入口 / 主面板 / 其他）：
- 手机与 App（或浏览器）版本：
- 现象（截图/录屏）：
- 期望（只要求「桌面不变 + 小屏可用」）：

## 验收清单
- [ ] 触控目标 ≥44px
- [ ] 横向 chip 可横滑、无被裁的尾部
- [ ] 行内文字动作收成图标且保留可访问名称
- [ ] 桌面专属提示已隐藏
- [ ] 底部安全区与 overscroll 处理
- [ ] 字号跟随 --dsh-content-font-size
- [ ] 弹层/表单在 390px 下不溢出
- [ ] 桌面截图无回归

6.2 PR 检查表

• 只有一份渲染/详情实现，没有为移动复制第二套；
• 断点基于实测宽度，不是 UA/viewport；
• 移动规则全部挂在同一个开关下，桌面选择器未改动；
• 演示用的静态预览可以指定宽度，且窄屏分支真的被执行；
• 渲染检查里新增了结构断言；桌面基线已对比；
• 真机未验的部分在描述里写明（键盘、安全区、惯性滚动）。

---

7. 边界与反模式

• 不要由移动层按类名注入第三方 CSS：类名一变就碎，而且会同时影响桌面。
• 不要为移动端复制一套组件树：两份实现一定会在第一个字段变更时分叉。
• 不要承诺「所有插件都能适配」：后台型、依赖原生窗口的插件不在此列。
• 不要把「能滚动」当成验收通过：还要看首个异常、实际尺寸和焦点顺序。

---

[LUgABeEEE]

指南的中英双文版已整理成 docs PR：#280 （docs/MOBILE_PLUGIN_ADAPTATION.md + .en.md，并从 docs 索引链入）。内容与上一条回复一致，英文不是摘要而是同结构全文。The bilingual guide is in #280 as a docs PR.

[LUgABeEEE]

@saya-ch 打扰一下，想请你看一眼这条提案，顺便把同类诉求一起收拢 🙏

这条提案只要一个决定：要不要让「移动端插件适配」以可执行的清单 + 一个样板的形式成为正式入口（置顶讨论 / issue 模板 / 写进贡献流程，三者选一或组合）。其余都是执行细节。

已经落地的部分（不需要你先投入时间）：

• 指南已合并：docs PR docs(mobile): a mobile adaptation guide for plugin authors #280 今晨已进 main，正文是 docs/MOBILE_PLUGIN_ADAPTATION.md + .en.md，已从 docs 索引链入——所以「先落指南」这一步其实已经完成，现在缺的是把它定为正式入口；
• 样板 dsh-global-todo 的 390×844 截图 + 改动 diff（面板实测宽度切档，桌面逐像素不变）；
• PR fix(mobile): keep the shell chrome opaque under translucent skins #286（今天新提，CI 全绿、可合并）：移动外壳在皮肤把 --dsw-alias-bg-layer-1 / --dsw-alias-bg-base 设为半透明时保持不透明，并补文档说明——模块开关只管客户端模块，插件在服务端注入的壁纸/整页配色不会随勾选消失。这正是适配边界里最容易被误解的一处。

同方向的另两条：#277（讨论区 / 短视频 / 站点入口）、#278（社群与网页）——如果你觉得该并到一条路线里，我可以在那边补一句指向这里，避免三条各聊各的。

想请你定三件事：

1. 清单以什么形式存在最合适：置顶讨论、issue 模板，还是写进 CONTRIBUTING.md？
2. 下一步是先挑 1–2 个插件试跑一遍流程，还是先把提名机制定下来？
3. 「作者提名 → 提 issue → 经同意后提适配 PR」这个流程你接受吗？

你给个方向就行，执行我这边来。

---

@saya-ch a quick ping — this proposal only needs one decision: should mobile plugin adaptation become a formal entry point (pinned discussion, issue template, or contribution-flow text) built on the executable checklist plus one worked example? The guide already landed: #280 merged this morning as docs/MOBILE_PLUGIN_ADAPTATION.md + .en.md. Remaining materials: the dsh-global-todo 390×844 sample with its diff, and PR #286 (green CI, mergeable) which keeps the mobile chrome opaque under translucent skins and documents that the module switch cannot remove page-level styles a plugin injects. #277 and #278 point the same way and can be folded into one track. Three questions: which form should the checklist take; try one or two plugins through the flow next, or define nominations first; and do you accept "nominate → issue → PR with author consent"?

[LUgABeEEE]

关于「正式入口形式」，我们按 docs/ 指南 + 一份可验收的基线 落地了一份具体提案：PR #316

拆分是刻意的：已合并的适配指南答「怎么做」；新的插件移动端基线答「做到什么程度算过」——L1 可点 / L2 顺手 / L3 可回归，附数字出处（Apple HIG 44pt、WCAG 2.2 SC 2.5.5 与 2.5.8、Android 48dp）和一段可直接复制的 [data-mobile="1"] 样式。没有加工具、没有加发布门槛、没有改「插件自负小屏可用」的边界。

如果维护者更希望它以 issue 模板或置顶讨论的形式存在，我可以按那个形式重做，不必保留现在的文件结构。

--- English ---

On the "formal entry point" question, here is a concrete proposal: a docs/ guide plus an acceptance baseline — PR #316.

The split is deliberate: the merged adaptation guide answers how; the new plugin mobile baseline answers how good is good enough — L1 tappable / L2 comfortable / L3 regressible, with the provenance of each number (Apple HIG 44pt, WCAG 2.2 SC 2.5.5 and 2.5.8, Android 48dp) and a copy-paste [data-mobile="1"] stylesheet. No tooling, no release gate, and no change to the boundary that plugins own their small-screen usability.

If you would rather have it as an issue template or a pinned discussion, I can rework it into that form instead of keeping this file layout.

[saya-ch]

感谢这份提案。指南已经通过 #280 落地；我倾向于把移动适配保持为文档建议，不设为正式入口，也不代表 DSH 官方标准。同类议题建议集中在这一个讨论里，避免分散。