# 已知限制

[← 返回 README](../README.md)

这些都是**已知且接受**的取舍，不是待修的 bug；写在这里是为了让你在遇到时知道「这是预期行为」
而不是「装坏了」。

---

## 会话跳转

- **前端不支持 `?session=` 深链**，而且鉴权的 token 换取会 `303` 丢掉查询参数。所以会话跳转是
  **由本插件的客户端半部**调 `sessions.open()` 完成的——这也是为什么这个插件必须带客户端半部。
  细节见 [点击回跳与点击延迟](./click-focus.md#4-打开正确会话--宿主记住--客户端索取)。
- **待跳转会话有 90 秒有效期**（`focusTtlMs`）：超过这个时间再点旧通知，就只回到 dsh 页面、
  不再强行切会话。
- 同一条通知被点开后，若走的是**新开标签页**那条路，新页面会先落回上次选中的会话、约 1 秒后才
  切到目标会话（因为 URL 参数在鉴权重定向时被丢弃，只能由页面加载后主动索取）。实测日志可见这
  一跳转。

## 聚焦

- **聚焦 = 窗口标题 + UI Automation**：先在顶层窗口标题里找 marker + tag；找不到时用 UI Automation
  选中对应的浏览器**标签页**（Chromium 与 Firefox 会把每个标签暴露成 `TabItem`），所以 dsh 标签
  不在前台时点击也能真正回到 dsh。只有当 UIA 不可用（组策略禁用、或非 Chromium/Firefox 的浏览器）
  时，才退化为「只把上次命中的窗口提到前台」，此时需要手动点一下 dsh 标签。
- **`titleTag` 会改写标签页标题**：这是多实例精确聚焦的代价（`… — DeepSeek Harness [dsh:3081]`）。
  不喜欢可以设 `titleTag: false`，代价是多个实例并存时会认错窗口。
- **批量匹配是字面包含，不是模糊匹配**：`focusWindowMarker` 与 tag 都按 `OrdinalIgnoreCase` 的
  字面 `IndexOf` 匹配（不能用 `-like`，方括号会被当成字符集）。所以 marker 写错一个字符就完全
  匹配不上，会退化为「新开标签页」。

## 通知

- **持久通知依赖 `scenario="reminder"` + 一个按钮**：Windows 会忽略**没有按钮**的 reminder 场景
  （退化成普通通知，几秒后被收走）。插件因此在持久化时总会带上按钮。另外 `reminder` 通知不会被
  Focus Assist / 勿扰静默掉，这是系统行为。
- **`appName` 没有接线**（声明了但无处读取），改它不会有效果；要区分通知来源请改 `appId`。
- 普通 Linux 桌面依赖 `notify-send`（多数发行版需自行安装 `libnotify-bin`）；WSL 下不需要，
  直接走 Windows Toast。Linux 上持久化用 `notify-send -u critical -t 0` 近似，但**撤回通知没有
  通用通道**，`dismissOnReturn` 在 Linux 上不生效。
- **撤回只在 Windows/WSL 可用**：走的是 `History.Remove(tag, group, appId)` 按 tag 精确删除。

## 进程与资源

- **焦点助手是个常驻 PowerShell 进程**（约 50-70MB），这是把点击端到端从 2.1s 降到 ~0.1-0.2s 的
  代价，见[点击延迟](./click-focus.md#3-点击延迟为什么要有一个常驻助手进程)。
- **助手互斥量按 spool 目录区分**：共用同一个 spool 的多个实例（Windows 原生 + WSL 指向同一份
  检出，默认如此）**共享**一个助手；配了不同 `spoolDir` 的实例各自有一个。共用 spool 的实例之间
  仍会互相影响——一方卸载/重载会把共享的助手带走，另一方下一次点击退化为冷启动（~1.4s），之后由
  `enqueue-focus.vbs` 的心跳自愈恢复。
- **助手重载期间可能有一次慢点击**：插件 HMR 重载时旧助手收到 `stop` 退出、新助手可能因互斥量
  抢先失败而退出，于是下一次点击要等心跳过期后重新拉起。只影响一次。
- **跨版本升级可能残留一个旧助手进程**（旧版本用的是全局固定互斥量名），见
  [升级提醒](./windows.md#2-升级提醒可能残留一个旧版焦点助手进程)。

## 框架行为

- **在场状态的 TTL 是 45 秒**（`presenceTtlMs`）。这是「不做静音黑洞」的代价与保障：标签页崩溃、
  浏览器被关掉之后，45 秒内插件仍可能认为你在看那条会话。
- presence 端点的注册清理绑定在 connection 服务的 fiber 上（框架语义），HMR 重载插件时端点可能
  不会随之注销，但重复注册是覆盖语义，不会报错。
- 多标签页同时打开时，每个标签页都会独立上报（这是设计如此，多标签都能各自被抑制），因此切换
  标签页时日志会有较多上报记录。
- **打开浏览器 DevTools 会让页面失焦**（`document.hasFocus()` 变 false），插件会判为「离开」。
  这是预期行为，不是故障；控制台里查到的 `mode` 可能是 `away`。

## 开发相关

- **测试用注入的假 spawn，不产生真实副作用**。这不是洁癖：Windows 无法用 shell 脚本冒充
  `powershell.exe`（只认 PE 映像，不认 shebang）。约定见
  [实现说明 - 测试约定](./implementation-notes.md#5-测试约定)。