# dsh-plugin-mobile-ui · 项目说明

> **完整项目说明**：背景与约束、加载原理、功能全表、模块参考、设计 token、验证体系、上游缺陷反制、维护手册、历史结论。
> 只想上手看根目录 [README.md](../README.md)；日常使用与维护看 [MOBILE-UI-GUIDE.md](MOBILE-UI-GUIDE.md)。
> 本文随代码更新；与代码冲突时以代码为准。每条关键结论都注明**实测**或**代码出处**。

| 元信息 | 值 |
|---|---|
| 包名 / 版本 | `dsh-plugin-mobile-ui` / `0.1.0`（MIT） |
| 远端 | https://github.com/loeissu/dsh-plugin-mobile-ui |
| 代码基线 | `src/client` 18 个模块 / 5649 行；最大 `DrawerOverlay.tsx` 1672 行 |

---

## 0. 一页速览

| 项 | 说明 |
|---|---|
| 一句话 | 把 DeepSeek Harness 的 Web 界面改造成**手机能用**的界面 |
| 交付形态 | 官方 **slot 客户端插件**：单个 IIFE，经 `window.__ModuleLoader__.load({ id, factory })` 注册，导出 `apply` / `inject` |
| 目标设备 | 手机（竖屏 320–430px、横屏 915×412）；桌面鼠标环境**行为不变** |
| 连接能力 | **不提供**。手机连电脑是 [dsh-plugin-tether](https://github.com/zexadev/dsh-tether) 的职责 |
| 表面 | `shell.overlay` ×2（启动页、抽屉）、`settings.section`、`tool.call.toolview` ×5；另加 8 层宿主 chrome 打磨（不注册插槽） |
| 验证 | 离线契约检查 + **33 个 CDP 断言套件**（全部通过）；3 个已放弃设计的脚本归档在 `tools/retired/` |
| 硬约束 | 不 fork dsh-tether、不改 DSH 源码、不替换 `sidebar` 插槽、不提升 tether 内置 DSH 运行时 |
| 许可 | MIT；与 DeepSeek 官方无关，不含任何品牌资产 |

---

## 1. 背景与边界

### 1.1 分层：谁负责什么

```
手机 App（cc.zexa.dshtether，tether 的 Android 客户端）
  └─ 应用内回环代理 http://127.0.0.1:<port>        ← 手机上页面的 origin（实机错误页可见）
       └─ P2P 隧道（NAT 打洞）→ 电脑上的 dsh web
            └─ DSH Web 客户端（React + Cordis DI）
                 ├─ dsh-plugin-tether    ：把界面送到手机（连接、配对、隧道）
                 └─ dsh-plugin-mobile-ui ：让界面在手机上**好用**（本项目）
```

DSH 的界面是**桌面优先**的：控件尺寸、间距、密度、悬浮交互都按鼠标设计。到了手机上集中表现为三类问题：**命中区过小**、**窄屏排版互相挤压**、**触摸设备没有 hover** 带来的一系列副作用（残留提示、`pointerleave` 缺失、粘滞 hover 样式）。本项目只解决这些，不重新实现界面。

### 1.2 硬约束（写代码前先读）

| 约束 | 原因 |
|---|---|
| 不 fork `dsh-tether` | 连接/配对/隧道是它的职责；fork 会把两个项目的升级耦合在一起 |
| 不修改 DSH 源码 | 升级 DSH 不应有合并成本；一切通过公开插槽与运行时 DOM 完成 |
| 不注册 `sidebar` 插槽（默认关闭） | 它是 `single`/`root`：接管会连带屏蔽 ui-sidebar 声明的 6 个座位，且"一个 key 只能有一个声明者"无法用优先级解决 → **全局失败**（`Failed to load plugins`）。见 [drawer-takeover.md](drawer-takeover.md) |
| 不提升 tether 内置的 DSH 运行时 | 那是 tether 的发布物（`0.1.5` 的 per-session 写锁依赖 `flock`，在 Android 上硬抛异常）；本项目只记录影响面 |
| 每步先在隔离环境/模拟器验证 | 真机截图是最终裁判，但每步都要有可复现的实测 |

**可无损回退是设计目标**：拔掉本项目，DSH 在手机上仍然能用，只是难用。

---

## 2. 交付形态与加载原理

### 2.1 loader 契约

产物是**一个自包含的 IIFE**，不打包 React（宿主提供，产物只声明 `externals`）：

```js
__ModuleLoader__.load({ id: 'dsh-plugin-mobile-ui', factory: () => ({ apply, inject }) })
```

`npm run verify` 用模拟 loader 执行产物并打印：

```
loader calls: 1
id: dsh-plugin-mobile-ui
factory: function
externals requested: react, react-dom, react/jsx-runtime
exports: apply, inject
inject: ["slots","layout","uiWorkspace","connection"]
slots injected: ["settings.section","shell.overlay","shell.overlay","tool.call.toolview"×5]
registered -> name=… id=… order=… priority=…
rendered -> … ok
```

- 四个服务是**必需依赖**：任一缺失，插件整体不 apply（不是局部失效）。
- 三类错误会被拦住：产物自带 React、缺少 `__ModuleLoader__.load` 外壳、缺少 `apply`/`inject`。
- 另有**陈旧产物守卫**：任何 `src/**.ts(x)` 比 `lib/client.js` 新即 exit 2 —— 防止"对着旧产物验证"。

### 2.2 插槽注册表

| 插槽 | 形式 | 内容 | 开关 |
|---|---|---|---|
| `shell.overlay` | list（追加） | 启动页 | `splash` |
| `shell.overlay` | list（追加） | 抽屉（「导航」入口 + 面板） | `drawerOverlay` |
| `settings.section` | list（追加） | 设置页「移动端」分区 | `settings` |
| `tool.call.toolview` | keyed ×5 | 工具卡（`pwsh/read/grep/edit/write`，`priority: -100`） | `toolCards` |
| `sidebar` | single（替换） | 接管式抽屉，**默认关闭且违反硬约束** | `replaceSidebar: false` |

- keyed 槽位**一个 key 一个优先级只能有一条**：以更低优先级注册即"遮蔽"宿主原卡；同优先级注册会抛错 → 全局 `Failed to load plugins`。`verify-bundle.mjs` 断言每个 keyed 注册都是负优先级。
- `inject` 包裹 `register` 是**强制写法**：未声明的 slot，`inject` 只是待命不报错；裸 `register` 会抛 `slot "X" is not declared`。

### 2.3 宿主 chrome 打磨（不注册插槽）

对宿主自带界面的改动走"**带标记的样式表 + 少量运行时测量**"：

- 每张表注入为 `<style data-plugin="dsh-plugin-mobile-ui" data-plugin-css="dsh-mobile-ui/<id>">`；当前 8 张启用（`splash` / `drawer` / `tool-card` / `viewport-fit` / `tether-compat` / `typography` / `settings-chrome` / `conversation-chrome`），另有未启用的 `drawer-takeover`。
- **选择器纪律**：只用宿主公开的 `data-slot="…"` 锚点与 CSS-Module 本地名的**后缀**（如 `[class*="_navCell"]`）；哈希前缀每次构建都变，绝不用。
- `!important` 只出现在"覆盖宿主"的表里，且作用域收窄到锚点之下。
- 运行时测量只做**宿主给不出答案**的部分：`导航` 在宿主 tab 条里的让位宽度（取决于语言与字体）、列表溢出与让位等。
- `injectStyles` 以**文档**判定归属（不信任模块内 Set），因此外部删表后重装能补回。

### 2.4 构建与两道闸门

```sh
npm run bundle     # prebundle lint（CSS 模板串禁止裸反引号）→ tsdown 打包
npm run verify     # 离线 loader 契约 + 陈旧产物守卫
```

`lib/` 不入版本库；DSH 的 Loader 直接读磁盘上的 `lib/client.js`、并把它发布到 `/plugins/dsh-plugin-mobile-ui/client.js`。**没有构建过的克隆装上去完全不生效，且不报错。**

---

## 3. 安装、更新与卸载

```sh
git clone https://github.com/loeissu/dsh-plugin-mobile-ui.git
cd dsh-plugin-mobile-ui
npm install
npm run bundle                       # 必须
npm run verify                       # 可选
dsh plugin --profile web add .       # 装进 Web GUI 所在 profile
```

- **安装后必须重启 `dsh web`**（插件在启动时被扫描；不重启不生效也不报错）。
- **改完代码**：`npm run bundle` 后**刷新页面**即可 —— 产物变更由 `dsh-client-hmr` 轮询后推送给客户端；若 profile 未启用该插件，则需重启服务。
- 确认安装：`dsh plugin --profile web list` 能看到 `dsh-plugin-mobile-ui`。
- 卸载：`dsh plugin --profile web remove dsh-plugin-mobile-ui`，然后重启。

---

## 4. 手机端功能全表

### 4.1 操作

| 想做什么 | 怎么做 |
|---|---|
| 打开导航 | 点顶栏最左的文字 **「导航」**（取代 ☰；绘制 26×25，命中 45×44） |
| 关闭导航 | 点遮罩 / 面板内**左滑 >72px** / 右上 × / Esc |
| 换工作区、开会话 | 抽屉分组列表（**刚刚 / 今天 / 昨天 / 更早**，按日历日切分） |
| 新建会话 | 抽屉底部 **＋** |
| 打开主机设置 | 抽屉底部 **设置**；设置页内**左右滑动**换分区 |
| 手动恢复连接 | 抽屉底部 **刷新连接**（换 mux socket）；假活时按钮变 **重试**，每 4s（一分钟后 15s）自动重试 |
| 看连接状态 | 抽屉底部状态点（四态见 4.2） |
| 看工具输出 | 工具卡默认折叠；**失败卡自动展开**；输出截断到 20k 字符 |
| 复制回答 | 消息下方 **复制**（见 §8.3：WebView 里 async 剪贴板被拒，本项目接通宿主兜底） |
| 横屏 | 与竖屏同一套界面（抽屉、命中区、设置页密度都在） |

### 4.2 连接状态四态

| 状态 | 依据 | 状态点 | 按钮 |
|---|---|---|---|
| 已连接 | `ctx.connection.state === 'connected'` | 蓝填充 | 刷新连接 |
| 连接中 | `connecting` | 蓝脉冲（reduced-motion 下变圆环） | — |
| 未连接 | `disconnected` | 灰填充 | 刷新连接 |
| **链路已断** | 本插件**探针**判定（§8.1） | 深色圆环 + 读屏文案「链路已断」 | **重试**（自动轮询、不导航） |

### 4.3 提示与命中区（实测值）

| 控件 | 绘制 | 命中 | 方式 |
|---|---|---|---|
| 「导航」标签 | 26×25 | **45×44** | 伪元素 `inset: -10px` |
| 消息操作（复制/反馈） | 28×28 | **35×43** | 伪元素（横向到相邻节距为止） |
| composer 按钮 | 28×28 | **39×37** | 受下方指标 dock 限制 |
| 宿主 `对话`/`轨迹` tab | 26×25 | **43×36** | `::before`（`::after` 被宿主的激活下划线占用） |
| 抽屉关闭 / ＋ | 36×36 | **45×45** | 伪元素 `inset: -5px` |
| 设置弹层关闭 | 32×32 / 28×28 | **45** | 伪元素 `inset: -9px` |
| 设置页分区 tab | 32px 高 | **44** | 伪元素 `inset: -6px -2px` |
| 插件自己的「重放」 | 36px 高 | **44** | 伪元素 `inset: -4px -2px` |

---

## 5. 模块参考

`src/index.ts`（5 行）只声明入口元数据；`src/client/index.tsx` 是 `apply()`：注册表面、按开关装配模块。

| 模块 | 行 | 职责与关键决策 |
|---|---:|---|
| `index.tsx` | 269 | `apply()`：插槽注册 + 模块装配；所有安装在能力自检之后，缺能力静默 no-op（激活期抛错=全局失败） |
| `config.ts` | 417 | `FEATURES` 开关 + 全部用户可见文案（zh/en 双字典，53 键**完全对齐**，脚本核查） |
| `theme.ts` | 308 | 设计 token（全部取 DSH `--dsw-alias-*`）、`PHONE_MEDIA`、`injectStyles`、`isDarkTheme`/`observeTheme` |
| `DrawerOverlay.tsx` | 1672 | 抽屉主体：工作区/会话列表、新建、设置入口、刷新连接 + **链路探针**、状态点、左滑关闭、跑马灯标题、让位测量。**拖拽走 CSS 变量而非 React state**（实测：一次滑动曾有 105 次样式重算 / 42 次布局） |
| `Splash.tsx` | 322 | 启动页与冷/热启动时长（冷 700ms / 热 120ms，上限 4s）；重放实例可点击关闭 |
| `Settings.tsx` | 266 | 设置页「移动端」分区（版本、主题跟随、工具卡数量、重放启动页） |
| `ToolCard.tsx` | 456 | 工具卡：折叠/展开、失败自动展开、输出截断、`contentText` 记忆化；对未知 block 形状不抛错 |
| `Drawer.tsx` | 240 | 接管式抽屉（`sidebar` 插槽）——**默认关闭且违反硬约束**，仅作历史保留 |
| `viewport.ts` | 383 | 软键盘遮挡：`visualViewport` + `interactive-widget=resizes-visual`；延迟回调池按 timeout/frame 分开取消；dispose 恢复 `<meta viewport>` |
| `conversation-chrome.ts` | 229 | 宿主会话控件：命中层（横竖屏都生效）＋标题让位/底部指标行（**仅窄屏**）——改命中区与隐藏内容必须用不同断点 |
| `settings-chrome.ts` | 228 | 宿主设置弹层：窄屏密度 ＋ 标题行高度修正（`min-height: 44px`）＋两种朝向的触控层 |
| `settings-swipe.ts` | 138 | 设置页左右滑动换分区（点相邻 nav 单元；不抢垂直滚动；到头不回绕；仅手机） |
| `clipboard-fallback.ts` | 135 | WebView 里接通宿主自己的复制兜底（只在 async 剪贴板被拒时；仅手机） |
| `tooltip-dismiss.ts` | 122 | 触摸没有 `pointerleave`，补发宿主已在监听的离开事件，避免 hover 提示永久残留；仅手机 |
| `connection-recovery.ts` | 91 | 回到前台且状态为 `disconnected` 时重连（2.5s 防抖） |
| `typography.ts` | 65 | 窄屏字阶/字重基线（含 CJK 行高与 tabular-nums） |
| `tether-compat.ts` | 182 | 反制 tether 注入样式的两处事故（队列行 `_row` 规则、确认弹层模态框规则） |
| `keyboard-debug.ts` | 128 | 诊断浮层（`keyboardDebug`，默认关闭） |

### 5.1 特征开关（`FEATURES`）

| 开关 | 默认 | 作用 |
|---|---|---|
| `splash` | `true` | 启动页 |
| `drawerOverlay` | `true` | 浮层抽屉（唯一导航入口） |
| `settings` | `true` | 设置页「移动端」分区 **+** 宿主设置弹层的手机排版 |
| `keyboardFit` | `true` | 软键盘遮挡 |
| `tetherCompat` | `true` | tether 反制层 |
| `resumeReconnect` | `true` | 回前台自动重连 |
| `typography` | `true` | 窄屏排版基线 |
| `conversationChrome` | `true` | 宿主会话控件命中层与标题让位 |
| `settingsSwipe` | `true` | 设置页左右滑动换分区 |
| `clipboardFallback` | `true` | 复制兜底（WebView） |
| `tooltipDismiss` | `true` | hover 提示收尾（手机） |
| `toolCards` | `['pwsh','read','grep','edit','write']` | 工具卡（替换式，见 §9） |
| `keyboardDebug` | `false` | 诊断浮层 |
| `replaceSidebar` | `false` | 接管 `sidebar`（**违反硬约束，勿开**） |
| 启动页时长 | `minVisibleMs 700` / `minVisibleWarmMs 120` / `fadeMs 200` / `maxVisibleMs 4000` / `maxVisibleWarmMs 900` | 冷/热启动节拍与封顶 |

---

## 6. 设计系统

### 6.1 颜色

**全部来自运行中的 DSH**：`theme.ts` 只声明 `--dsw-alias-*` 语义 token 的引用（`TOKEN`/`V`），没有任何字面色值，因此浅色/深色/品牌色变化都自动跟随宿主。少数必须自绘的层次（遮罩 `rgba(0,0,0,.45)`、面板阴影）保持中性。已知坑：`--dsw-alias-brand-primary` **不是**蓝色；等宽字体是 `--ds-font-family-code`。

### 6.2 字阶（`TYPE` / `TYPE_LH`）

| 名称 | 字号 | 行高 | 用途 |
|---|---|---|---|
| `micro` | 11px | 16px | 分组标签、路径、计数 |
| `caption` | 12px | 18px | 元信息、说明、指标 |
| `bodySm` | 13px | 18px | 次级行、工具标题、设置控件、「导航」标签 |
| `body` | 14px | 21px | 主体 |
| `bodyLg` | 15px | 22px | 抽屉标题、弹层标题 |
| `display` | 19px | 28px | 启动页产品名（字距收紧） |
| — | — | `code` 20px | 等宽块 |

### 6.3 圆角 / 间距 / 动效 / 层级

```
R      xs 5 · sm 9 · md 12 · lg 14 · xl 16 · panel 30 · pill 999
SPACE  xs 4 · sm 6 · md 8 · lg 12 · xl 16 · xxl 20 · rowY 11   （rowY 把 21px 行高变成 44px 目标）
MOTION base 200ms · sheet 220ms · expand 200ms · spin 900ms · pulse 1200ms
       ease cubic-bezier(.4, 0, .2, 1)
Z      splash 2147483000 · sheet 2147482000 · debug 2147481000 · local 2 · sticky 1
```

**实测层级清单**（避免互相压盖）：浮层根 `2147482000` → 宿主设置弹层 `1000`（**被关在停靠侧栏列的层叠上下文里**，所以该列自身必须带 `z-index: 40`）→ 停靠侧栏列 `40` → 应用顶栏 tab 条 `1`。层级冲突是本项目踩过两次的坑（§8.5）。

### 6.4 「手机」的判定：`PHONE_MEDIA`

```css
(max-width: 768px), (max-height: 520px) and (pointer: coarse)
```

- 纯宽度判定在**横屏**失效：915×412 的手机比 768px 更宽，会整套掉回桌面布局（抽屉、命中层、设置密度同时消失）。
- 粗指针守卫保证 1600×500 的桌面窗**不**被误判为手机。
- 用途分工：**改命中区/纯增量的层**用 `PHONE_MEDIA`；**隐藏内容或重构布局的层**仍用纯宽度（横屏那行有空间，没必要删信息）。

---

## 7. 验证体系

### 7.1 三层

1. **离线契约**：`npm run prebundle` + `npm run verify`（无需浏览器）。
2. **CDP 断言套件**：`tools/verify-*.mjs`（33 个），驱动真实 Chrome，逐条断言，退出码即结果。
3. **真机截图**：最终裁判；本项目多数根因都由真机截图揭出。

```sh
node tools/verify-render.mjs "http://127.0.0.1:3080/?token=<TOKEN>"
```

### 7.2 套件分组

| 分组 | 套件 |
|---|---|
| 启动页 | `verify-render` `verify-splash-warm` |
| 抽屉骨架/共存 | `verify-drawer-overlay` `verify-coexistence` |
| 入口与让位 | `verify-drawer-open` `verify-nav-tab-locale` |
| 面板交互 | `verify-drawer-swipe` `verify-touch-scroll` `verify-drawer-list` `verify-drawer-new-session` `verify-drawer-settings` `verify-drawer-refresh` `verify-drawer-windowing` `verify-conn-dot` |
| 连接诚实性 | `verify-refresh-honesty` `verify-link-retry-cadence` |
| 剪贴板与提示 | `verify-clipboard-fallback` `verify-tooltip-dismiss` |
| 命中区 | `verify-tap-targets` `verify-conversation-touch` |
| 宿主会话 chrome | `verify-conversation-chrome` |
| 宿主设置弹层 | `verify-settings-chrome` |
| 滑动与横屏 | `verify-swipe-and-landscape` |
| 键盘/输入法 | `verify-keyboard-fit` `verify-ime-refocus` `verify-keyboard-focus-poll` |
| 上游缺陷反制 | `verify-risk-dialog` `verify-tether-compat` `verify-tether-queue` |
| 工具卡 | `verify-toolcards` `verify-toolcard-fail-open` |
| 其它 | `verify-title-marquee` `verify-resume-reconnect` |

### 7.3 方法论纪律（写新套件照做）

- **驱动真实浏览器**，不用 jsdom 假装；触摸必须用 `Input.dispatchTouchEvent` **并开** `setTouchEmulationEnabled`，否则原生滚动/指针语义不成立。
- **窗口隐藏时触摸事件不会被确认**：`document.hidden === true` 的页面**永远不 ack** `Input.dispatchTouchEvent`（实测：页面本身 1ms 响应、零异常，但每次派发都超时；`Page.bringToFront` 无效）。解法是 `Emulation.setFocusEmulationEnabled({ enabled: true })` —— 它把 `document.hidden` 翻成 false，同一次派发 **10ms** 内确认。四个派发触摸的套件都带这一行。此外窗口不可见时**绘制/焦点类断言也不可靠**（`elementFromPoint`、focus 事件、IME 轮询会假失败），跑全套请用可见窗口或 `--headless=new`。
- **套件依赖"已打开一个会话"**：`对话`/`轨迹` tablist、命中区、标题空间等都在会话里才有。新 profile 首跑请先开一个会话，否则会得到"元素不存在"的假失败。
- **状态相关的量不要写成固定阈值**：会话标题宽度随打开的会话变化（实测同一份代码 226px 与 76px 都出现过）。正确做法是**同一时刻 A/B**：量一次 → 摘掉本插件样式 → 再量 → 断言"绝不更差"。
- **归因先证伪**：怀疑样式表时**只摘我们自己的**（宿主也用 `data-plugin-css` 标记，全删会把宿主一起删）。
- **测真东西**：剪贴板断言读**真剪贴板**（CDP 授权 `clipboardReadWrite`），不是读桩。
- **桩要装对侧**：测试"包装器是否生效"时，桩必须在 App 启动**之前**注入，否则桩会覆盖包装器，测的是桩。
- 失败信息带**实测值与阈值**，便于区分回归与环境漂移。

### 7.4 已归档（`tools/retired/`）

`verify-drawer`（接管 `sidebar`）、`verify-drawer-push`（推挤式布局）、`verify-drawer-edge`（左缘滑动打开）——三者断言的是**已放弃的设计**，原因见 `tools/retired/README.md`。

---

## 8. 上游缺陷与反制清单

本项目相当一部分代码是"替上游擦地"。每条：现象 → 根因 → 处理 → 验证。

### 8.1 链路假活：socket 连着但到不了电脑

- **现象**：App 切后台再回来，界面还在、状态点也蓝着，但数据不同步；点「刷新连接」没用。
- **根因**：手机页面的 origin 是 tether 应用内的**回环代理**，app socket 的对端是**手机本机代理**而不是电脑。真正断的是代理背后的 P2P 隧道；`reconnect()` 换一条到本机代理的 socket **必然瞬间成功**（实测 120ms 回到 `connected`）。客户端**检测不到**：连接层没有心跳（只有 15s 首代就绪计时），tether 注入脚本也没有任何连接恢复。
- **处理**：刷新后跑**链路探针**——`fetch(location.href, {cache:'no-store'})` 要求响应含宿主注入的 `__DSH_BOOT__` **或**体量达到壳的规模（≥8KB；标记是内部字串、非契约，改名不该把健康链路判死）。探针失败 → 第三态。
- **验证**：`verify-refresh-honesty`（16 项）。

### 8.2 恢复方式：**绝不自动导航**

- **现象**：第三态最初做 `location.reload()`，实机直接落到 Chrome 错误页 `net::ERR_SOCKET_NOT_CONNECTED`，App 卡死只能杀掉重开（实机截图）。
- **根因**：代理不在时重载连文档都取不到——自动导航在根因场景下**必然失败**。
- **处理**：第三态按钮改为**重试**：只重新探测，第三态期间每 4s（一分钟后 15s）自动重试，恢复即自动重连；**从不离开页面**。
- **验证**：`verify-refresh-honesty`（含"点它不导航"的哨兵断言与"恢复自愈"断言）。

### 8.3 复制失效：宿主的兜底不可达

- **现象**：点「复制」毫无反应（无提示、无内容）。
- **根因**（宿主 `dsh-web-frontend` 源码）：

  ```js
  if (navigator.clipboard?.writeText) { try { await writeText(t); return true } catch { return false } }
  // 只有 async API *不存在* 时才走 textarea + execCommand('copy') 兜底
  ```

  Android WebView 里 async 剪贴板通常**存在但被拒**，于是 `return false`，**自己的兜底永远走不到**；调用方 `if (!ok) return` 静默返回。实测复现：`writeText` 1 次、`execCommand` **0 次**。
- **处理**：包一层 `navigator.clipboard.writeText`，**只在被拒时**走宿主本就写好的 legacy 路径（离屏 readonly textarea + `execCommand`，并恢复用户原有选区）。真 API 先试、文案仍由宿主决定、两条都失败时 promise 依旧 reject；仅手机。
- **验证**：`verify-clipboard-fallback`（9 项，读**真剪贴板**：健康 1434 字符入板 / WebView 情形兜底写入相同文本 / 桌面不兜底且剪贴板不变）。

### 8.4 hover 提示残留

- **现象**：复制成功后一个深色「复制成功」气泡永久停在输入框上方。
- **根因**：触摸点击合成 `pointerenter` 但**永不产生 `pointerleave`**，宿主的 hover-intent 打开气泡后再也收不到"指针离开"。实测：8s 仍在；blur / 焦点移走 / 合成 `pointerdown` 均无效；**对锚点派发 `pointerout/pointerleave` 有效**。不是我们的样式造成的（全摘掉照样残留）；桌面下鼠标移开即消失。
- **处理**：触摸交互后 1.2s 对可见 tooltip 的锚点补发宿主已在监听的离开事件；不隐藏、不伪造状态；仅手机。
- **验证**：`verify-tooltip-dismiss`（4 项，含"期间确实出现过"防空跑与桌面不干预）。

### 8.5 窄屏断点与层叠：两次"只有某个朝向才暴露"

- **断点**：所有按宽度开关的移动表面在横屏手机（915×412）全部失效 → `PHONE_MEDIA`（§6.4）。
- **层叠**：`position: fixed` **会创建层叠上下文**，把宿主设置弹层自身的 `z-index: 1000` 关在停靠侧栏列里。竖屏没事是因为 tether 给该列 `z-index: 30`；横屏 tether 的 ≤640 规则不生效 → 应用顶栏（`z-index: 1`）反过来盖住弹层顶部，关闭按钮点不到（实测 `elementFromPoint` 返回顶栏 tab 条）。处理：停靠规则自带 `z-index: 40`，不依赖另一个插件是否生效。

### 8.6 tether 注入样式的两处事故

| 事故 | 根因 | 处理 |
|---|---|---|
| 队列行被压扁 | tether 用 `[class*="_row"]:not([class*="rowText"])` 命中过宽，给队列行加了 `flex-wrap: wrap` | 同断点下计数器规则收回 |
| 确认弹层标题压正文、按钮被裁 | tether 把模态框改成全屏 + 绝对定位 header + 对 content-box 元素用 `width:100%` | 只对**没有 nav 的** `role="dialog"` 恢复紧凑卡片（`max-width: 640px`、`border-box`） |

### 8.7 其它反制

| 项 | 处理 |
|---|---|
| 会话标题被挤 | 隐藏装饰性 `/` 与重复模式标签、子代理 chip 折叠成图标（**回收 132px**，A/B 实测 226px vs 94px） |
| 底部指标行裁字 | 行内边距 32→8px、标签降到 12px；<380px 允许换行 |
| 设置弹层标题行压 tab 条 | 标题行只有 22px 高却装 32px 关闭按钮 → 给行 `min-height: 44px`（不改小控件） |
| 设置页五个 tab 需横滚 | 只回收间距；≤408px 隐藏图标，让五格在 320px 屏也放得下 |
| 命中区普遍偏小 | 一律用伪元素扩大**命中区**而非改绘制尺寸（见 §4.3） |
| 标题密文泄露 | 抽屉展示的会话标题会**脱敏** `ghp_*`/`github_pat_*` 形态串（只影响显示） |

---

## 9. 已知限制与取舍

| 项 | 说明 |
|---|---|
| **工具卡替换 4 张官方卡** | `read/grep/edit/write` 是替换式注册，会失去官方的「在轨迹中查看」与点开文件（`openFile` 未被调用）。想全部保留：`toolCards: []`（`pwsh` 是新增，不替换任何东西） |
| 键盘/输入法 | `viewport.ts` 依据 `visualViewport`，是 CDP 推断，**未在真机实测**；长按选择、IME 形态差异仍可能出入 |
| `layoutRef` 复位 | 高水位只在**宽度**变化时复位；纯高度变化的极端场景可能让框架保持偏矮（开放项） |
| 设置入口解析失败无反馈 | 依赖 `sidebar.settings` 座位或文案匹配；宿主改座位或第三种语言时会表现为"点了没反应" |
| 标题空间 | 带交付物/计划/队列 chip 的会话仍可能把标题压到 ~76px（其余占用者没有"可无损隐藏"的依据） |
| `:has()` 依赖 | 两处规则用 `:has()`（WebView < 105 整条丢弃，无降级），需要较新的 Android WebView |
| HMR 卸载残留 | 卸载/禁用而不刷新页面时，注入的样式表不会自动移除（`<meta viewport>` 已在 dispose 恢复；样式表按设计交由宿主/HMR 处理） |
| 无单元测试 / 无 CI | 验证 = 离线契约 + 33 个 CDP 套件 |
| 原生启动页 | [android-native-splash.md](android-native-splash.md) 的改动集完整但**未应用**（需 Android 构建环境） |
| 真机 vs 模拟 | 多数结论来自 CDP 触摸模拟 + 真机截图；具体每条有标注 |

---

## 10. 维护手册

### 10.1 改代码的流程

```sh
# 1. 改 src/
npm run bundle        # 必须看退出码：prebundle lint 会拦 CSS 模板里的裸反引号
npm run verify        # 必须看退出码：产物比源码旧会 exit 2（守卫，不是构建失败）
# 2. 刷新手机页面（产物变更由 dsh-client-hmr 推送）
# 3. 跑相关套件 + 一次全量
```

**两道闸门的价值**：`check-css-backticks.mjs` 在打包前就指出 `文件:行`（本项目先后 8 次在 CSS 注释里写反引号）；`verify-bundle.mjs` 的陈旧产物守卫拦住"对着旧产物验证"。

### 10.2 常见故障排查

| 症状 | 先查 |
|---|---|
| 装了完全没变化 | 构建过吗（`lib/client.js` 存在且比源码新）？重启 `dsh web` 了吗？`dsh plugin --profile web list` 里有吗？ |
| 改完没变化 | `npm run bundle` 的退出码；页面刷新了吗；profile 里有 `dsh-client-hmr` 吗 |
| 白屏 + `Failed to load plugins` | 激活期抛错：模块缺能力判断；keyed 槽位优先级撞车（同 key 同 priority）；`inject` 的服务缺失 |
| 桌面被影响 | 该规则是否误用 `PHONE_MEDIA`（粗指针/矮窗会命中）；是否漏了宽度断点 |
| 抽屉打不开 / 点不到 | 浮层根是否 `display:none`（宽视口正常）；`pointer-events` 是否被停靠层吃掉；宿主 tab 条是否被别的东西盖住（层级，见 §8.5） |
| 手机上"点了没反应" | 命中区（用 `verify-tap-targets` 量）；是否是 hover 型交互（触摸没有 hover）；是否需要读屏文案 |

### 10.3 加东西的步骤

- **加一个表面**：`ctx.slots.inject(key, () => ctx.slots.register(spec, Component))`；若目标是**替换**宿主表面，必须用负优先级并先确认 keyed 语义；补一个 `verify-*.mjs` 断言它渲染。
- **加一层宿主 chrome 打磨**：新建 `xxx-chrome.ts` → `injectStyles('<id>', CSS)`；选择器只用 `data-slot` 与本地名后缀；决定断点用 `PHONE_MEDIA` 还是纯宽度；套件里断言"宿主原样 vs 我们"的 A/B。
- **加一个套件**：见 §7.3 纪律；`tools/retired/` 不收新脚本。

### 10.4 升级 DSH / tether

影响面与清单见 [2026-09-12-upgrade-and-maintenance.md](2026-09-12-upgrade-and-maintenance.md)。要点：

- 耦合按脆弱度排序：**keyed 槽位优先级撞车**（可致全局失败）> 宿主服务缺失（整体不 apply）> 宿主 `data-slot`/本地名变化（局部失效）> 另一个插件的注入样式变化（tether）。
- tether 升级重点验证：注入样式是否仍在 `@media (max-width: 640px)` 内、停靠规则是否仍给侧栏列 `z-index`、窄屏断点是否变化。
- **不要**提升 tether 内置的 DSH 运行时（见 [03-tether-0.1.5-bump-report.md](03-tether-0.1.5-bump-report.md)）。

---

## 11. 约定与纪律

1. **可无损回退**：拔掉插件，DSH 必须仍然能用。任何"替换"都必须显式开关 + 默认关闭。
2. **激活期绝不抛错**：缺服务、缺 DOM、缺 API 都要静默降级（`typeof` 能力判断 + early return）。
3. **选择器只用锚点与后缀**：`data-slot` / `role` / 本地名后缀；不用哈希前缀，不用裸标签名。
4. **`!important` 只在覆盖宿主的表里**，并收窄作用域到锚点之下。
5. **能测就不要猜**：宽度、命中区、层级、时序都要有实测数字；注释写清是实测还是推断。
6. **区分"我们的"与"上游的"**：反制上游缺陷时，注释写明根因出处（源码/日志）与验证方式。
7. **每个修复配一个套件**；状态相关的量用 A/B 而不是固定阈值。
8. **不提交 `lib/`**（产物）与临时探针；探针放仓库外的暂存目录。

---

## 12. 目录结构

```
src/index.ts                  插件入口声明（5 行）
src/client/                   18 个模块（见 §5）
verify-bundle.mjs             离线 loader 契约 + 陈旧产物守卫
check-css-backticks.mjs       prebundle 预检：CSS 模板串禁止裸反引号
tsdown.config.ts              构建配置（lib/index.js + lib/client.js + sourcemap）
cordis.patch.yml              profile 补丁声明：`insert` 一行 `id: mobile-ui`；没有它 Loader 只把包当普通依赖装进来，插件永不激活
package.json                  scripts: prebundle / bundle / verify
tools/                        33 个 verify-*.mjs + 36 个 probe-*.mjs + 抓图/诊断脚本
tools/retired/                3 个已放弃设计的脚本（见其 README）
docs/                         21 篇 Markdown + docs/tools/slot-diff.ps1（索引见 docs/README.md）
lib/                          构建产物（不入 git）
README.md / README.en.md      上手文档（中/英）
STATUS.md                     2026-09-11 状态快照——**已过期**，只作历史与踩坑记录
```

---

## 13. 文档地图

- [README.md](../README.md) / [README.en.md](../README.en.md) —— 上手：是什么、怎么装、怎么用、怎么验证。
- [MOBILE-UI-GUIDE.md](MOBILE-UI-GUIDE.md) —— 使用与维护主文档（能力表、token、开关、验证清单、键盘、横屏、复制与提示两节）。
- [2026-09-12-upgrade-and-maintenance.md](2026-09-12-upgrade-and-maintenance.md) —— 升级影响面与检查清单。
- [docs/README.md](README.md) —— 全部 22 篇的分类（现行 / 计划 / 历史）；**历史文档不要当操作说明**。
- 缺陷记录：[2026-09-12-ui-audit.md](2026-09-12-ui-audit.md)（§5b–5h 是各批次实施记录与实测数据）。

---

## 14. 被推翻或已放弃的结论（避免重复调查）

| 曾经的做法/结论 | 现状与原因 |
|---|---|
| 接管 `sidebar` 插槽做抽屉 | **已放弃**：座位重复声明 + `single` 语义导致全局失败；改为浮层抽屉（`drawer-takeover.md` 仅作记录） |
| 推挤式抽屉（padding 让位） | **已放弃**：412px 屏上把会话区挤得太窄；改为覆盖 + 遮罩 |
| 左缘滑动打开抽屉 | **已移除**：Android 10+ 手势导航占用了左缘，WebView 收不到 |
| 「抽屉不能滚动」 | **已推翻**：是探针方法问题（控制组停在滚动底部 + 未开触摸模拟）；实测抽屉正常滚动（0→208） |
| 恢复用 `location.reload()` | **已推翻**（真机）：代理缺失时重载连文档都取不到，落到错误页；改为只重试、不导航 |
| 刷新连接只做 `reconnect()` | **已推翻**：对端是本机代理，必然瞬间"成功"；补链路探针后才诚实 |
| 窄屏只按宽度判断 | **已推翻**：横屏手机比 768px 更宽，整套移动表面失效；改为 `PHONE_MEDIA` |
| 会话标题空间用固定下限断言 | **已推翻**：量的是"当时打开的是哪个会话"；改为同一时刻 A/B |
| CSS 模板里写反引号 | **已被 lint 拦住**（8 次）；构建前即报 `文件:行` |

---

## 15. 许可与声明

MIT。与 DeepSeek 官方无关，不使用其名称、标识或品牌资源。界面配色全部取自运行中 DSH 暴露的 `--dsw-alias-*` 语义 token，自身不带设计资产。本项目只往官方插槽里追加内容，并对宿主自带界面做**限定范围**的排版与命中区打磨；不修改 DSH 源码，不 fork [dsh-tether](https://github.com/zexadev/dsh-tether)。