dsh-url-router 0.3.1 → 0.4.0

package/AGENTS.md

@@ -2,6 +2,16 @@
 
 本仓是一个独立的 DeepSeek Harness Web GUI 插件仓（**只有浏览器半区**）。
 
+## 社区插件索引登记（重要）
+
+- 索引仓库：<https://github.com/zhu1090093659/dsh-community-plugins> ✓（`community.json` 是 DSH Workshop 商店与 dsh-market.com 清单的**唯一数据源** ✓）。
+- 本插件条目 `dsh-url-router`（`ui/panel`）**已登记** ✓（PR <https://github.com/zhu1090093659/dsh-community-plugins/pull/30> 已合并 ✓，上游 `community.json` 现为 136 条 ✓）。
+- 我对那个仓库**只有读权限** ✓ → 流程是 **fork（`DDDMUC/dsh-community-plugins` ✓）→ 对齐上游 main → 追加条目 → 跑门禁 → 强推自己的 fork → 开 PR** ✓。
+- 那个仓库的规矩（与我们自己的不同 ✗）：**`community.json` 只追加、一个条目一个提交** ✓；必填 `id/name/nameEn/author/repo`，但发布面要求连 `description/descriptionEn/npm/category/subcategory` 一起填 ✓；`repo` 必须匹配 `^https://[A-Za-z0-9._~/-]+$` ✓（市场会把它变成 shell 命令 ✗，禁空白与元字符 ✓）；`npm` 必须匹配 `^(@[a-z0-9][a-z0-9._-]*/)?[a-z0-9][a-z0-9._-]*$` ✓；`category` 限 `ui/agent/tools/knowledge/integration/security/utility` ✓，`subcategory` 必须属于该 category 的白名单 ✓（`ui` 只接受 `terminal/chat/render/panel` ✓）。
+- 提交前必跑：`node scripts/community-index.cjs --check` ✓ 与 `node --test scripts/community-index.test.mjs` ✓。
+- ** Conventional Commits，且那个仓库全文禁 emoji** ✓（连对勾叉号都别用 ✗ —— 我们自己仓库的 ✓/✗ 风格不能带过去 ✗）。
+- **发新版后要做的事** ✓：`description` 是给所有用户看的商店文案 ✓，**功能变了就得同步条目** ✓（上游有先例：`fix(community-plugins): sync …` 这类 PR ✓）—— 发 0.4.x 时回来核对一遍描述与当前行为 ✓。
+
 ## 形态约束
 
 - **手写 JS，直接进 `lib/`**：没有构建步骤，`lib/index.js`（宿主半区，空操作）与 `lib/client.js`（浏览器半区，交付产物）既是源也是产物。
@@ -20,6 +30,12 @@
 - **工作区路线**：`#/workspace/<工作区名>/session/<会话id>`（侧栏形状 ✓）。工作区行是 `data-row-key="workspace:<uuid>"` ✓、**行文本就是工作区名** ✓（无 `data-workspace-*` ✗，实测 ✓）；会话所属工作区 = 树里**它之前最近的那个 workspace 行** ✓（`workspaceNameOf()` ✓，行锚点与反映共用 ✓）。名字是**装饰** ✓：`sameRoute` 对 workspace 路线只比**会话 id** ✓（名字过期也能落地 ✓）；读不到工作区行就退回 `#/session/<id>` ✓（不猜 ✓）。
 - **行锚点的 href 也要带工作区** ✓（右键"复制链接"直接给出带归属的链接 ✓）。
 - **作用域由视图决定，不靠猜**：主面板是应用级界面（列的是本机插件，不是某个对话），所以它的链接**不带**会话 id；只有会话级视图才写会话。
+- **`data-dsh-surface` 从来不是官方标记** ✓（2026-10-24 实测订正，**上一轮"官方把设置标记改名了"的结论作废** ✗）：官方设置浮层根元素是 `role="dialog" aria-modal="true" data-shortcut-modal="settings"` ✓（`dsh-client-ui-settings-general/lib/client.js`，`dsh-client-ui-shortcuts` 与 `dsh-web-frontend/dist` 同名 ✓），里面 `<nav>` 的按钮仍是 `aria-current="true"` ✓。那个老名字是**第三方「皮肤中心」`@linxin666/dsh-client-ui-skin-center` 用 compat 适配器给官方 DOM 补打的** ✓（它自己的契约文档 `contracts/semantic-attrs-v1.md` 写明了 owner 是 skin-center、"非永久公共契约"、上游主题缝落地后进入删除评估 ✓）。
+  ⇒ 症状按 profile 分裂，**不是"两边一样"** ✓：装了皮肤中心的 web profile 里地址栏一直正常反映设置 ✓（我 3080 实测：开浮层 → `#/settings/账号与余额` ✓，两个标记同时在场 ✓）；桌面 home 没装它 ✗ → 只有那边"地址栏不反映设置"。**粘 `#/settings` 开不出来**同理 ✓（驱动也读同一个标记）。
+  ⇒ 现在的做法：`settingsOverlayOf()` **官方标记优先、皮肤中心标记兜底** ✓。**别把顺序改回去** ✗，也**别拿兜底那条当证据** —— 用户哪天关掉皮肤中心它就没了 ✓，官方那条永远在 ✓。
+  **教训**：`data-dsh-*` 这类语义属性**先问是谁打的**再决定能不能当契约 ✗（扫官方包 0 命中是真的，错在当年把它当成官方契约写进路由）。判断依据是**真机 DOM** ✓，不是 grep ✓。
+- **会话链接必须先把挡在前面的主面板让开** ✓（2026-10-24 修）：主面板选中时 `canonical` 就是面板 ✓，直接 `openSession` 会让地址栏立刻被写回面板路由 ✗（桌面版地址栏实测：面板 → 对话「没反应」✓）。驱动会话 / 工作区 / 轮次 / 行这些路由前，先 `host.beginNavigation()` + `host.selectPanel(null)` ✓，落地后由 `canonical` 归位 ✓。用例：`a conversation link takes the main column back from an open panel` ✓。
+- **设置浮层挡的是一整列，不止面板** ✓（2026-10-24 桌面实测）：浮层在屏时 `canonical` 读到的就是 `#/settings/<分区>` ✓，所以**任何**非设置链接在它后面都落不了地，8 秒后按"视图没动"过期 ✗ —— 会话其实已经在浮层**背后**打开了 ✓，用户只看到"打不开"✗（截图：浮层停在「通用设置」✓，粘 `#/workspace/默认工作区/session/…` ✓，地址栏仍是 `#/settings/通用设置` ✓）。做法：`host.closeSettings()` 派发一次 document 级 `keydown` `Escape` ✓ —— 官方模态层注册的就是这个监听（bundle 实测 `document.addEventListener('keydown', h, true)` 且 `key === 'Escape'` 时关最上层 ✓），而 `closeTopModal` 走的那个模态栈注册表是 bundle 私有的 ✗ 外部拿不到 ⇒ **合成 Escape 是浏览器半侧唯一可用的关闭路径** ✓，也正是用户按 Esc 走的那条 ✓。**一条链接只按一次** ✓（`overlayDismissed` 随新链接复位 ✓）：每次 DOM 通知都派发会打扰正在操作页面的用户 ✓，代价只是"没关掉就得再粘一次" ✓。设置自己的链接**不关** ✓。用例：`a conversation link takes the settings overlay out of the way` ✓。
 - **一个 boot 的权威窗口（8 秒）**：链接在窗口内压过两边各自的 localStorage 恢复，窗口过后视图重新拥有地址栏。
 - **绝不抛错**：官方 `selectPanel` 对未注册的面板 id 是**抛异常**的，所有宿主面调用都必须被容纳（`attempt`/`guard`），失败只留一条诊断并回落到屏幕上真实的视图。
 - 只用 `replaceState`；路径与查询串原样保留。
@@ -31,13 +47,20 @@
 - 锚点 href 必须用本插件自己的编码函数 `routeHash('session', id)`，不要另写一套。
 - **找不到 DOM / 行属性不匹配一律静默 no-op**，绝不改官方行、绝不抛错；锚点点击里的导航也要 `try/catch`（官方导航可能抛）。
 - 行选择器或属性一旦改动，必须同步改 `test/client.test.js` 里的假 DOM 用例（假 DOM 已包含 `fakeDom`/`openWithDom`）。
+- **侧栏扫描有预算（2026-10-18 起，别改回去）**：
+  - 观察者是**每帧一次** ✓：一帧内到达的多个 mutation 批次合并成一次 `scan()` ✓（`requestAnimationFrame` ✓；没有 rAF 的最小 DOM / 假 DOM 走**同步**扫描 ✗ 不排队 ✓，否则测试与无帧环境会丢链接 ✓）。
+  - 批次**先过滤** ✓：只有可能带来行的节点才触发扫描 ✓（元素自身或子树里有 `[data-row-key^="session:"]` / `[data-plugin-item]` / `[data-plugin-package]` / panel slot ✓）；**纯文本批次直接跳过** ✓（流式回答、hover、工具输出整天在改 DOM ✗ 但它们永远不带行 ✓）。批次为空（拿不到记录：假 DOM、非标准 DOM）**按"要扫"处理** ✓ —— 宁可多扫一次也绝不漏行 ✓。
+  - 工作区归属**一趟遍历** ✓（`workspaceNamesOfRows()` 建 Map ✓），不是每行走一遍 `[data-row-key]` ✗（旧实现是 O(N²) ✓）。`workspaceNameOf(row)` 保留给单行调用（反映侧 ✓）。
+  - 已经挂着锚的行**跳过重挂** ✓，但判据是**行内 `querySelector` 找到锚** ✓，不是行上的 `data-dsh-url-router-host` ✗ —— 视图重渲染可能把锚点丢掉而属性还在 ✓，用属性判会**永久失去修复机会** ✓（有回归用例覆盖 ✓）。
+  - `panelRows()` 走 **`[data-slot="sidebar.panellist"]` 属性查询 + `closest('button')`** ✓，不再遍历全文档按钮再逐个查子树 ✗。
+  - 卸载时**取消排队的那一帧** ✓（`cancelAnimationFrame` ✓）。
 
 - **面板内部页是多段的**：`#/panel/plugins/<包>/<组件>`（每段单独 `encodeURIComponent`，所以原生的 `/` 一定是层级分隔）。钩子分**两组**，不要以为一套通吃：**已安装组** `li[data-plugin-package]` → `[data-plugin-detail]` → `li[data-plugin-row="<kind>:<rowId>"]` → `[data-plugin-row-detail="<包>#<rowId>"]`；**官方组** `li[data-plugin-item="<id>"]` → `[data-plugin-item-detail="<id>"]`（实测：官方项页面**没有** `data-plugin-detail`）。驱动一个段位时先找包行、再找官方行。**钩子有两种拼写**（`#` 与 `:`），解析统一走 `splitRowHook()`，别自己 `split`。
 - **任务看板走它自己的契约**（由用户单仓 `dsh-task-board` 发布）：`#/panel/task-board/task/<任务id>` 与 `#/panel/task-board/new`。反映读 `data-dsh-taskboard-open-task` / `data-dsh-taskboard-new-task`；驱动派发同名窗口事件；**表单优先于任务详情**。
 - **观察者的 `attributeFilter` 必须列全所有已发布的页面钩子**：只列 `data-plugin-detail` 曾让任务看板的重试通知饿死（历史 bug，别删名单项）。
 - **未落地的链接要有定时重试**（`LINK_RETRY_MS` = 500ms）：只靠 DOM 通知不够，启动后界面会安静下来，一次被吞掉的重试就永远不来了。
 - **切换主面板前先 `beginNavigation()`**（`ctx.layout` 的配套动作，可选面，缺失即跳过）。
-- **设置面板是覆盖层**：`#/settings` ✓（裸段位 ✓，`ROUTE_PATTERN` 支持 `#/<kind>` ✓）与 `#/settings/<分区>` ✓。反映读 `[data-dsh-surface="settings"]` ✓；驱动点 `[data-slot="sidebar.settings"]` 的入口 ✓（兜底按可访问名 ✓）。
+- **设置面板是覆盖层**：`#/settings` ✓（裸段位 ✓，`ROUTE_PATTERN` 支持 `#/<kind>` ✓）与 `#/settings/<分区>` ✓。反映读 `settingsOverlayOf()` ✓（**官方 `data-shortcut-modal="settings"` 优先** ✓，见上条 ✓）；驱动点 `[data-slot="sidebar.settings"]` 的入口 ✓（兜底按可访问名 ✓）。
 - **设置分区的身份 = 显示名**（实测无稳定 id ✗：导航项只有 `aria-current="true"` ✓，无 `id`/`data-*`/`aria-controls` ✗，右侧内容区无 `data-*` ✗）。反映：在覆盖层里找 `aria-current="true"` **且 `closest('nav') !== null`** 的按钮 ✓，取它的标签文字 ✓；驱动：按标签（先精确、再忽略大小写）点 ✓。**换语言/改文案会让旧分区链接失效** ✗（重新点一次即写出新链接 ✓）。
 - **设置分区里的页签同理，再深一层** ✓：`#/settings/<分区>/<页签>`。契约是标准 ARIA ✓：`[role="tab"][aria-selected="true"]` ✓（实测 `dsh-usage` 的用量/个人套餐/Token 银行就是 `role="tab"` ✓），身份同样是**标签文字** ✓；驱动=先点分区、再点标签匹配的页签 ✓（同一次调用里做完 ✓，因为分区一点开，页签就在同一个覆盖层里 ✓）。
 - **`aria-selected` 也必须观察** ✓（与 `aria-current` 同理：切换页签只改它 ✓）。
@@ -57,6 +80,17 @@
 - **面板行同样是链接**：`data-slot="sidebar.panellist"` 所在的那个 `<button>`（官方侧栏渲染的面板行）会挂上 `href="#/panel/<id>"` 的锚点。**行里没有 id**，id 只能从注册表取：`ctx.slots.entries('sidebar.panellist')` 的 `options.id` / `options.order` / `options.label`；label 可能是**函数**（按语言解析），所以优先按可访问名匹配、数量一致时按 order 对齐，匹配不上一律不碰。
 - **`slots` 必须留在 `inject` 里**：cordis 下读未声明的服务会抛错，而插件激活期的抛错会让整个插件 `failed`（真机事故：面板链接那次就是这么挂的——假 ctx 无条件给服务，单测抓不到，只有真机能抓）。其余可选面（如 `ctx.layout`）一律 `try/catch` 读取。
 
+## 桌面地址栏契约（2026-10-24 起，改之前先读）
+
+- **形态**：Windows 桌面版的标题栏是**页面里画的** ✓ —— preload（`app.asar` 的 `lib/preload-app.cjs`）跑 `syncWindowsAppearance()`：给 `<html>` 打 `data-windows-titlebar`、设 `--dsh-windows-titlebar-height: 40px`，并用 shadow DOM 画菜单条（宿主 `[data-windows-menu]`，`position:fixed; top:0; left:var(--dsh-windows-menu-start,48px); z-index:1100; -webkit-app-region:no-drag`）。⇒ 那条 strip 是**页面空间** ✓，插件可以往里画 ✓。
+- **门控**：只有 `documentElement.getAttribute('data-windows-titlebar') !== null` 时才画 ✓；Web 版与 macOS 上**一行都不执行** ✓（"并进 url-router 但不影响其它平台"的全部机制就是这个 ✓）。
+- **定位**：`left = 48 + 菜单宿主宽度 + 8` ✓（宽度用宿主 `getBoundingClientRect()` 量 ✓，**不要**读 shadow 内部 ✗）；`right = TITLEBAR_CAPTION_WIDTH = 138px` 是 Windows 窗口按钮宽度常量 ✓（改缩放/换系统可能要调 ✓）；高度一律走 CSS 变量 ✓，不要写死 40 ✓。
+- **交互**：`-webkit-app-region: no-drag` 必须留 ✓ —— strip 本身是拖拽区 ✗，去掉它输入框点不动 ✗。
+- **落地只写 hash** ✓：`window.location.hash = fragment` ✓，绝不自己调路由内部 ✗ —— 浏览器触发 `hashchange` ✓，落地就是"粘贴链接"那条已验证的路 ✓。
+- **反映靠 feed** ✓：`reflect()` 写完地址栏后 `publishRoute(wantedHash)` ✓，桌面栏 `subscribeRoute(show)` ✓。**别改成监听 `hashchange`** ✗ —— 本插件用 `replaceState` 写地址栏 ✗、**不触发** hashchange ✗，改了就变成"框里永远是旧的" ✗。
+- **假 DOM 不支持 `#id` 选择器** ✗ → 地址栏带 `data-dsh-part="url-router-address-bar"` ✓，测试用属性选择器 ✓（行锚点当年同理 ✓）。
+- **验收**：布局可在 Web 版上用 `document.documentElement.setAttribute('data-windows-titlebar','')` + 那个 CSS 变量预演 ✓（同一套 CSS ✓），但 `dsh-app://` 下的 `replaceState` / `hashchange` 行为**只能真机确认** ✓。
+
 ## 跨机开发日志
 
 改动记录在私有库 [DDDMUC/repo-devlogs](https://github.com/DDDMUC/repo-devlogs) 的 **`dsh-url-router/`** 文件夹（`HANDOFF.md` 最新一轮在最上面；macOS 端写 `WORKLOG-macos.md`，条目以 `[macOS]` 开头）。按该库规矩，每条先写 `**运行环境**`（设备 / 应用 / 服务商与模型），再写做了什么、动了哪些文件、怎么验证、遗留问题。

package/README.md

@@ -1,6 +1,6 @@
 # dsh-url-router
 
-**DSH Web GUI 地址栏路由插件 —— 每个界面都有自己的链接：地址栏写着屏幕上的东西，链接点开就是那个界面。** 给 DeepSeek Harness (dsh) Web GUI 补上"可寻址"：点侧栏会话，地址栏变成 `#/session/<id>`；点插件面板，变成 `#/panel/plugins`；点进某个插件、某个组件、某个任务，地址栏跟着一起走。把这条链接贴到新标签页、或者对着侧栏任意一行右键，就是浏览器自己的行为——无需复制按钮、无需自定义菜单。
+**DSH 地址栏路由插件（Web 与 Windows 桌面版）—— 每个界面都有自己的链接：地址栏写着屏幕上的东西，链接点开就是那个界面。** 给 DeepSeek Harness (dsh) 补上"可寻址"：点侧栏会话，地址栏变成 `#/session/<id>`；点插件面板，变成 `#/panel/plugins`；点进某个插件、某个组件、某个任务，地址栏跟着一起走。把这条链接贴到新标签页、或者对着侧栏任意一行右键，就是浏览器自己的行为——无需复制按钮、无需自定义菜单。桌面版（Windows）自己没有地址栏，本插件就把它画在标题栏那条空白里。
 
 它是**地址栏的唯一写者**：只改 URL 的 fragment，路径与查询串（例如启动时的 `?token=…`）原样保留；只用 `replaceState`，浏览面板不会往后退栈里塞历史。**只有浏览器半区**——零依赖、无宿主路由、无遥测。
 
@@ -25,6 +25,8 @@ dsh plugin --profile web add dsh-url-router
 dsh plugin --profile web add "link:/path/to/dsh-url-router"
 ```
 
+**已登记进社区插件索引** ✓ —— [zhu1090093659/dsh-community-plugins](https://github.com/zhu1090093659/dsh-community-plugins) 的 `community.json` 是本插件在 DSH Workshop 商店与 dsh-market.com 清单里的唯一数据源 ✓（登记条目 `dsh-url-router`，`ui/panel` ✓）。
+
 ### 路由表
 
 | 地址 | 界面 | 由谁打开 |
@@ -49,11 +51,21 @@ dsh plugin --profile web add "link:/path/to/dsh-url-router"
 - **中键、Cmd/Ctrl + 单击** → 原生新标签页
 - **左键单击** → 在本页打开（`preventDefault` 后调官方导航，不新增历史记录）
 
+### 桌面版的地址栏
+
+DSH 桌面版（Windows）的标题栏是**画在网页里的**：preload 给 `<html>` 打上 `data-windows-titlebar`、给出 `--dsh-windows-titlebar-height`，菜单条本身是页面里的一个 shadow DOM 固定元素（`[data-windows-menu]`）。那条 strip 里的空白是**页面空间**，而桌面版**自己没有地址栏** —— 于是本插件把地址栏放在那儿：
+
+- 只在 `html[data-windows-titlebar]` 存在时出现 ✓（Web 版与 macOS 上什么都不画 ✓）。
+- 位置：紧跟 shell 自己的菜单条右侧 ✓、右端避开窗口按钮 ✓；高度取 `--dsh-windows-titlebar-height` ✓；`-webkit-app-region: no-drag` 保证能点 ✓。
+- 输入什么 ✓：任何 `#/…` 路由（会话 / 工作区 / 视图 / 轮次 / 行 / 面板 / 设置三层 / 右栏 pane）、**裸会话 id**、或**整条链接**（只取它的 fragment）✓；回车写 hash → 浏览器触发 `hashchange` → 落地走的就是"粘贴链接"那条已验证的路 ✓。
+- 它同时是**反映** ✓：本插件每次写地址栏都会同步进这个框 ✓，所以它显示的就是"现在在哪" ✓。Escape 还原 ✓；认不出的文本不动地址栏 ✓。
+
 ### 它守的规矩
 
 - **只动 fragment**：路径与查询串从不改写（启动 `?token=…` 能活下来）。
 - **唯一写者**：本插件拥有 fragment，请**不要**和别的写 fragment 的插件同时启用（例如 `dsh-session-url`），两者会互相覆盖。
 - **只用 `replaceState`**：浏览面板不污染后退栈。
+- **链接落地前，挡在前面的表面先让开** ✓：主面板选中时地址栏读到的就是面板 ✓，设置浮层在屏时读到的就是 `#/settings/<分区>` ✓ —— 这两种情况下会话**其实已经在背后打开了** ✗，屏幕上却像"没反应" ✓。所以驱动任何非设置链接之前 ✓，先 `beginNavigation()` + `selectPanel(null)` 让面板退场 ✓，再用**官方自己那条 document 级 Escape** 把设置浮层请走 ✓（模态栈是官方内部的私有注册表 ✗ 外部拿不到 ⇒ Escape 是浏览器侧唯一可用的官方关闭路径 ✓，也就是你按 Esc 走的那条 ✓）。**一条链接只按一次** ✓：不会在你正在操作页面时乱按键 ✓，代价只是万一那次没关掉、你再粘一次 ✓。设置自己的链接**不动**浮层 ✓。
 - **轮次信息：能证明才写** ✓。助手行自己的身份里就带轮次（`row/assistant/80/32` = 第 80 轮第 32 项 ✓）；**工具行不带** ✗（只有调用 id ✓）→ 于是我从视图的**轮次边界** `[data-turn-start]` 反推 ✓，**但只在行夹在两个已渲染边界之间时才写** ✓（`turn/82/row/tool/call/…` ✓）。视图是虚拟化的 ✓，边界可能只渲染了一侧 ✗ → 那时**宁可不写轮次** ✓，也绝不猜一个错的轮次 ✗。
 - **轨迹里的每一行都有自己的链接** ✓：`#/session/<id>/row/<类>/<作用域>/<id>`（例：`row/tool/call/call_ce3a…`、`row/assistant/80/32` = 第 80 轮第 32 项 ✓；有工作区时跟在会话 id 之后 ✓）。身份来自视图自己发的 **`data-trajectory-row-key`** ✓（值是 `<类>%00<作用域>%00<id>` ✓，我把它拆成可读路径 ✓）；你家 Trajectory Plus 发的是 **`data-dshts-turn`**（轮号 ✓）→ 那种行按轮次写（`turn/<n>` ✓）。点一行就反映进地址栏 ✓（**纯被动**：不 preventDefault ✓）。粘贴行链接会打开那个对话并**尽力滚到那一行** ✓ —— 视图是虚拟化的 ✓，**没渲染出来的行不会被假装滚到** ✗（不会骗你 ✓）。
 - **会话视图（对话 / 轨迹 / 轨迹plus …）也进地址栏** ✓：`#/session/<id>/view/<viewId>`（有工作区时是 `#/workspace/<名>/session/<id>/view/<viewId>` ✓）。**视图 id 是真的 id** ✓（来自槽位 `conversation.view` 的 `id` 字段 ✓，按 `order` 排序后与头部页签一一对应 ✓）：实测本机是 `chat` / `trajectory` / **`surface`**（Trajectory Plus ✓）/ **`plus2`**（Trajectory Plus 2 ✓）。默认视图（第一个 ✓）**不写进链接** ✓，所以普通对话链接保持短 ✓。**粘贴视图链接会真的切过去** ✓（与其它覆盖层不同：这是链接存在的意义 ✓）。
@@ -61,13 +73,14 @@ dsh plugin --profile web add "link:/path/to/dsh-url-router"
 - **作用域由视图决定，不靠猜**：主面板是应用级界面（列的是本机插件，不是某个对话），所以它的链接不带会话 id。
 - **链接落地即交权**：视图一旦变成链接描述的那个界面，链接立刻失去权威——这样你在面板里继续点进去时，地址栏不会被拽回上一层。
 - **绝不抛错**：官方 `selectPanel` 对未注册的面板 id 是抛异常的；所有宿主面调用都被容纳，失败只留一条诊断并回落到屏幕上真实的视图。
+- **侧栏扫描有预算** ✓：一帧内的多次 DOM 变更合并成**一次**扫描 ✓；只带文本/普通元素的批次**直接跳过** ✓（流式输出不会一帧扫一次 ✓）；工作区归属**一趟遍历**解决 ✓（不是每行走一遍树 ✗）；已挂锚的行不再重挂 ✓，锚点被视图丢掉时下一趟自动补回 ✓。
 
 ### 已知限制
 
 - **轮次链接是"位置"，而且现在真能跳** ✓：点某一轮，地址栏记下 `#/session/<id>/turn/<n>` ✓；**粘贴它会打开那个对话、把历史翻页回那一轮、再滚到它** ✓（真机实测：贴 `/turn/118` → 窗口变成 118→121、目标在视口 true、最顶可见正是 118 ✓）。用的是**官方已有公开契约** ✓：`sessions.retainScope(id, source)` 拿到会话控制器 ✓ → `session.projections.faceOf('turnOutline')` 读到那一轮的 `seq` ✓ → `session.loadThrough(seq)` 翻页回去 ✓（完事 `reference.release()` ✓）→ 再按官方视口同款选择器 `[data-chat-turn]:not([hidden])` 滚到它 ✓。座位高度/相交都读不到时**不算到位** ✓，宁可继续重试也不假报 ✗。
 - **右栏 pane 已闭环** ✓：`#/session/<id>/pane/<kind>` 与 `#/panel/<面板>/pane/<kind>` ✓（真机验证：贴链接开出对应页签 ✓、地址栏跟着切换 ✓）。页签种类由右栏自己注册 ✓（实测 7 种：`guide` / `subagentchat` / `changes-review` / `plan` / `files` / `text` / `terminal` ✓）。
 - **设置面板已纳入**：`#/settings` ✓、**`#/settings/<分区>`** ✓、**`#/settings/<分区>/<页签>`** ✓（页签靠标准 `role="tab"` + `aria-selected` ✓，分区内任何页签都吃这一套 ✓）。分区**没有稳定 id** ✗（实测：导航项上只有 `aria-current="true"` ✓，父链是 `nav` ✓，右侧内容区一个 `data-*` 都没有 ✗；官方内部的 `openSection(id)` 也不对外 ✗）→ 所以**分区的身份就是它的显示名** ✓：反映读「`aria-current="true"` 且属于 `nav`」的那个按钮的**标签文字** ✓，驱动按标签点 ✓。含义：**换语言或官方改文案后，旧的分区链接会失效** ✗（但你重新点一次，地址栏就会写出新链接 ✓ —— 自洽、不过期 ✓）。裸 `#/settings` 只要面板开着就算落地 ✓，随后地址栏自动升级为具体分区 ✓。
-- **设置页分区暂未纳入（旧描述）**：设置包没有"打开某个分区"的接缝（它们是 keyed list slot），只能等它自己发布类似契约。
+- **设置页分区的身份只有显示名**（上一条的含义，别当成 bug 去找官方要 id ✗）：官方那个 `openSection(id)` 里的 id **不对外** ✗，DOM 上也没有任何 `data-*` ✓ —— 所以链接里写的就是用户读到的那行字 ✓，官方改文案或换语言后旧链接失效是**设计如此** ✓。
 - **会话内的轮次与行锚点已纳入** ✓：`#/session/<id>/turn/<n>` ✓（**反映 + 翻页 + 滚动 ✓ 全链路已闭环**）、`#/session/<id>/row/<类>/<作用域>/<id>` ✓（反映 + 尽力滚动 ✓，含可证明时的轮次归属 ✓）。轮次跳转用的是官方公开 API ✓，**没有等待任何新接缝** ✓（`uiChat.scrollToTurn` 那条请求已降级为锦上添花 ✓，讨论见 <https://github.com/deepseek-ai/deepseek-harness/discussions/9339> ✓）。
 - **技能中心 / SSH 的内部页**：需要它们各自发布"当前实体 id + 按 id 打开"的契约（任务看板就是这么做的）。
 - **和别的 fragment 写者互斥**（例如写 `#msg=` 的"跳到消息"插件）：一个 URL 只有一个 fragment ✓，两个写者只能轮流拥有 ✗。本插件**不假装合并** ✓ —— 它认出外来 fragment ✓、**绝不覆盖** ✓，并明确说"只能启用一个写者" ✓（而不是互相静默擦掉对方的链接 ✗）。
@@ -94,6 +107,7 @@ dsh plugin --profile web add dsh-url-router
 # restart `dsh web`, then hard-refresh the browser
 ```
 
+Listed in the community plugin index: [zhu1090093659/dsh-community-plugins](https://github.com/zhu1090093659/dsh-community-plugins) keeps `community.json`, the single source for the DSH Workshop store catalog and the dsh-market.com manifest (entry `dsh-url-router`, `ui/panel`).
 ### Routes
 
 | Route | Surface |
@@ -112,6 +126,15 @@ A kind it does not know is left alone with a single diagnostic (a fragment has e
 
 Conversation rows and both plugin-list groups carry a transparent full-row anchor: right-click gives the native menu, middle/Cmd-click opens a native new tab, and a plain left click navigates in place without adding a history entry.
 
+### The desktop address bar
+
+The Windows desktop window draws its own title bar **inside the page**: the preload marks `<html data-windows-titlebar>` and publishes `--dsh-windows-titlebar-height`, and its menu is a fixed shadow-DOM element in the page (`[data-windows-menu]`). That strip is page space, and the desktop window has **no address bar of its own** — so this plugin puts one there:
+
+- Drawn only when `html[data-windows-titlebar]` is present (nothing at all on the web app or macOS).
+- Placed right after the shell's own menu and before the window buttons, at `--dsh-windows-titlebar-height`, with `-webkit-app-region: no-drag` so it stays clickable.
+- Accepts any `#/…` route, a bare conversation id, or a whole link (only its fragment is used); Enter writes the hash, the browser fires `hashchange`, and the link lands through the very same path a pasted link takes.
+- It also **reflects**: every write this plugin makes to the address bar is mirrored into the box, so it always names what is on screen. Escape restores it; text that names no route is refused.
+
 ### Rules it keeps
 
 - **Fragment only.** Path and query are never rewritten.

package/lib/client.js

@@ -66,6 +66,14 @@ window.__ModuleLoader__.load({
 		const ROUTE_ALIASES = { session: 'session', sessions: 'session', panel: 'panel', panels: 'panel', settings: 'settings', workspace: 'workspace', workspaces: 'workspace' }
 		/** Attribute the settings overlay puts on its root element. */
 		const SETTINGS_SURFACE_ATTRIBUTE = 'data-dsh-surface'
+		/**
+		 * The marker the official build puts on the settings overlay. `data-dsh-surface` was never
+		 * official: the third-party skin centre stamps it through its own compat adapter, and that
+		 * contract says out loud it is not public and may be removed. Any profile without that
+		 * plugin — the desktop window is one — has only this marker, so a router that knows only
+		 * the other name silently stops naming the overlay.
+		 */
+		const SETTINGS_MODAL_ATTRIBUTE = 'data-shortcut-modal'
 		/** Value of that attribute for the settings overlay. */
 		const SETTINGS_SURFACE_VALUE = 'settings'
 		/** Slot the settings entry is rendered into (its button opens the overlay). */
@@ -123,10 +131,75 @@ window.__ModuleLoader__.load({
 		 * The router's own version, for the report a human files. A test keeps it equal to the
 		 * package version, so a release cannot forget to bump it.
 		 */
-		const ROUTER_VERSION = '0.3.1'
+		const ROUTER_VERSION = '0.4.0'
+		/**
+		 * Hand-maintained build marker, reported alongside the version. A working copy that is
+		 * linked into a profile serves this file straight from disk, so the package version
+		 * cannot say *which* copy a live window loaded — this can, and `report().build` is how a
+		 * real-machine check answers that. Bump it whenever a live window must be told apart.
+		 */
+		const ROUTER_BUILD = 'desktop-bar+settings-marker+modal-dismiss'
 
 		const TAG = '[url-router]'
 
+		/** Marks the Windows desktop title bar the shell draws inside the page. */
+		const WINDOWS_TITLEBAR_ATTRIBUTE = 'data-windows-titlebar'
+		/** The shell's own menu host inside that strip; the address bar starts after it. */
+		const WINDOWS_MENU_ATTRIBUTE = 'data-windows-menu'
+		/** The shell's own left inset for that menu, matching its fallback. */
+		const WINDOWS_MENU_START = 48
+		/** Id of the desktop address bar and of its stylesheet. */
+		const TITLEBAR_BAR_ID = 'dsh-url-router-titlebar'
+		/** The bar's structural hook, the way the row anchors carry theirs. */
+		const TITLEBAR_PART = 'url-router-address-bar'
+		const TITLEBAR_STYLE_ID = 'dsh-url-router-titlebar-style'
+		/** Width the window's caption buttons take at the right end of the strip. */
+		const TITLEBAR_CAPTION_WIDTH = 138
+		/** Gap between the shell's menu and the bar. */
+		const TITLEBAR_GAP = 8
+		/** How long the bar waits for a handed-over link to land before it says it did not. */
+		const TITLEBAR_SETTLE_MS = 900
+		/** What the address bar accepts, said in its placeholder. */
+		const TITLEBAR_PLACEHOLDER = '#/session/… · #/panel/… · #/settings · 会话 id · 链接'
+		/** The strip belongs to the shell, so only the bar itself is styled. */
+		const TITLEBAR_STYLE_TEXT = [
+			`#${TITLEBAR_BAR_ID}{position:fixed;top:0;height:var(--dsh-windows-titlebar-height,40px);display:flex;align-items:center;z-index:1200;-webkit-app-region:no-drag}`,
+			`#${TITLEBAR_BAR_ID} input{height:26px;width:100%;box-sizing:border-box;border:1px solid transparent;border-radius:6px;padding:0 8px;font:inherit;font-size:12px;color:inherit;background:var(--dsw-specific-sidebar-fill,rgba(127,127,127,.14));outline:none;-webkit-app-region:no-drag}`,
+			`#${TITLEBAR_BAR_ID} input:focus{border-color:var(--dsw-alias-brand-primary,rgba(79,124,255,.9))}`,
+			`#${TITLEBAR_BAR_ID}[data-dsh-url-router-state="refused"] input{border-color:rgba(214,69,69,.85);color:rgba(214,69,69,1)}`,
+		].join('')
+		/** Listeners told the fragment this router just wrote; the desktop bar reads it. */
+		const routeFeed = new Set()
+		/**
+		 * Tell the feed what the address bar now says.
+		 * @param {string} hash - the fragment just written.
+		 */
+		function publishRoute(hash) {
+			for (const listener of [...routeFeed]) {
+				try {
+					listener(hash)
+				} catch {
+					// A reader must never break a write.
+				}
+			}
+		}
+		/**
+		 * Read every fragment this router writes.
+		 * @param {Function} listener - called with the fragment.
+		 * @returns {() => void} the unsubscribe.
+		 */
+		function subscribeRoute(listener) {
+			routeFeed.add(listener)
+			return () => routeFeed.delete(listener)
+		}
+		/**
+		 * How the desktop address bar hands a typed fragment over. The routing state machine
+		 * installs it (it owns the adoption path) and leaves it a no-op until then, so a bar
+		 * drawn before the machine is live cannot navigate anything.
+		 * @param {string} fragment - the fragment to adopt.
+		 */
+		let driveTypedFragment = () => {}
+
 		/**
 		 * The conversation view ids the registry publishes, in registration order — the same order
 		 * the header renders its tabs in, which is what lets a tab position map back to an id.
@@ -164,6 +237,29 @@ window.__ModuleLoader__.load({
 			}
 		}
 
+		/**
+		 * Resolve the workspace name for every row in one pass over the tree, instead of
+		 * walking the tree again for every row that needs a name.
+		 * @param {object} document - the document the tree lives in.
+		 * @returns {Map<object, string|undefined>} row -> its workspace display name.
+		 */
+		function workspaceNamesOfRows(document) {
+			const names = new Map()
+			const rows = document?.querySelectorAll?.('[data-row-key]')
+			if (rows === undefined || rows === null) return names
+			let name
+			for (const candidate of rows) {
+				const key = typeof candidate.getAttribute === 'function' ? candidate.getAttribute('data-row-key') : null
+				if (typeof key !== 'string') continue
+				if (key.startsWith(WORKSPACE_ROW_PREFIX)) {
+					name = (candidate.textContent ?? '').trim()
+					continue
+				}
+				names.set(candidate, name === undefined || name === '' ? undefined : name)
+			}
+			return names
+		}
+
 		/**
 		 * The workspace a sidebar row belongs to: the nearest workspace row before it, read from the
 		 * row text. Returns undefined when the tree says nothing, so no caller has to guess.
@@ -567,6 +663,8 @@ window.__ModuleLoader__.load({
 			let panelAttempts = 0
 			/** How many times a panel link's inner page was requested (bounded, see below). */
 			let innerAttempts = 0
+			/** Whether the current link already asked for a modal standing in front of it to go away. */
+			let overlayDismissed = false
 			/** The view state observed on the previous notification. */
 			let seen = 'none'
 			let cancelTimer
@@ -593,7 +691,7 @@ window.__ModuleLoader__.load({
 			const canonical = () => {
 				// The settings overlay covers the main column, so while it is up it is what is on
 				// screen; when it closes the ordinary surface takes the address bar back.
-				if (window.document?.querySelector?.(`[${SETTINGS_SURFACE_ATTRIBUTE}="${SETTINGS_SURFACE_VALUE}"]`) != null) {
+				if (settingsOverlayOf(window.document) !== undefined) {
 					const section = host.activeSettingsSection() ?? ''
 					const tab = section === '' ? undefined : host.activeSettingsTab()
 					return tab === undefined ? { kind: 'settings', id: section } : { kind: 'settings', id: section, inner: [tab] }
@@ -755,6 +853,7 @@ window.__ModuleLoader__.load({
 				// (this also leaves a foreign fragment alone, which the caller never reaches).
 				if (route === undefined && hash === '') return
 				host.replaceUrl(routeUrl(pathname, search, route))
+				publishRoute(wantedHash)
 			}
 			/**
 			 * Re-read the view state and move towards the state the address bar describes.
@@ -801,6 +900,29 @@ window.__ModuleLoader__.load({
 					reflect(canonical())
 					return
 				}
+				// Anything that names a conversation — session, workspace, turn, row, view — has to
+				// take the main column back from a panel standing in front of it. Without this the
+				// panel stays selected, the canonical form stays the panel's, and the link reads as
+				// "nothing happened" (measured on the desktop address bar: the workspace-shaped link
+				// returns through its own branch below, so closing the panel in one branch only was
+				// not enough). A settings overlay standing in front is dealt with right below.
+				if (link.kind !== 'panel' && link.kind !== 'settings') {
+					const panelInFront = host.activePanelId()
+					if (panelInFront !== undefined && panelInFront !== null) {
+						host.beginNavigation()
+						host.selectPanel(null)
+					}
+				}
+				// The settings overlay covers the main column too, and while it is up it *is* what the
+				// address bar names — so a link behind it can never land and expires as "the view did
+				// not move" (measured on the desktop: overlay on 通用设置, a pasted workspace link
+				// opened its conversation out of sight and the bar stayed on `#/settings/通用设置`).
+				// Dismiss it once per link: Escape on every notification would fire on a page the user
+				// is working in, and a link that misses simply has to be pasted again.
+				if (link.kind !== 'settings' && !overlayDismissed) {
+					overlayDismissed = true
+					host.closeSettings()
+				}
 				// A conversation link may name which view it wants, on either route shape; the view is
 				// driven before the plain conversation/workspace branches, or they would swallow it.
 				const rowParts = innerPath(link.inner)
@@ -995,6 +1117,7 @@ window.__ModuleLoader__.load({
 					claimed = false
 					panelAttempts = 0
 					innerAttempts = 0
+					overlayDismissed = false
 					seen = 'none'
 				}
 				dropTimer()
@@ -1042,6 +1165,18 @@ window.__ModuleLoader__.load({
 				retryTimer = undefined
 			}
 			const safeReadLink = () => guard(readLink)
+			// The desktop address bar hands its fragment over here instead of relying on the
+			// browser: a programmatic hash write fires `hashchange` in a browser, but a hash
+			// equal to the current one fires nothing at all, and the desktop shell serves the
+			// page over its own scheme. Adopting through the same guarded entry the hashchange
+			// listener uses makes the bar work in both cases. The hash is still written, so the
+			// address bar, Back/Forward and copied links all agree with what is on screen.
+			driveTypedFragment = fragment => {
+				attemptValue(() => {
+					window.location.hash = fragment
+				})
+				safeReadLink()
+			}
 			const offPanel = host.onPanelChange(() => safeReconcile('panel'))
 			const offCatalog = host.onCatalogChange(() => safeReconcile('catalog'))
 			const offDom = host.onDomChange(() => safeReconcile('dom'))
@@ -1110,6 +1245,7 @@ window.__ModuleLoader__.load({
 				const count = selector => attemptValue(() => document?.querySelectorAll?.(selector)?.length) ?? '\u2014'
 				return {
 					version: ROUTER_VERSION,
+					build: ROUTER_BUILD,
 					hash: attemptValue(() => host.readLocation().hash) ?? '',
 					canonical: current === undefined ? null : { kind: current.kind, id: current.id, inner: innerPath(current.inner) },
 					link: linked === undefined ? null : { hash: routeHash(linked.kind, linked.id, linked.inner), attempts: { panel: panelAttempts, inner: innerAttempts } },
@@ -1123,7 +1259,7 @@ window.__ModuleLoader__.load({
 						turnBoundaries: count(`[${TRAJECTORY_TURN_START_ATTRIBUTE}]`),
 						pluginPackages: count('[data-plugin-package]'),
 						officialItems: count('[data-plugin-item]'),
-						settingsOverlay: count(`[${SETTINGS_SURFACE_ATTRIBUTE}="${SETTINGS_SURFACE_VALUE}"]`),
+						settingsOverlay: settingsOverlayOf(document) === undefined ? 0 : 1,
 						settingsSection: attemptValue(() => host.activeSettingsSection()) ?? null,
 						taskBoardOpen: count(`[${TASK_BOARD_OPEN_ATTRIBUTE}]`),
 						taskBoardNew: count(`[${TASK_BOARD_NEW_ATTRIBUTE}]`),
@@ -1137,7 +1273,7 @@ window.__ModuleLoader__.load({
 				}
 			}
 			guard(() => {
-				window.__dshUrlRouter = { version: ROUTER_VERSION, report, when: host.now() }
+				window.__dshUrlRouter = { version: ROUTER_VERSION, build: ROUTER_BUILD, report, when: host.now() }
 			})
 
 			return () => {
@@ -1322,8 +1458,12 @@ window.__ModuleLoader__.load({
 		function panelRows(document) {
 			const rows = []
 			try {
-				for (const button of document.querySelectorAll('button')) {
-					if (typeof button.querySelector === 'function' && button.querySelector(`[data-slot="${PANEL_LIST_SLOT}"]`) !== null) rows.push(button)
+				// One attribute query beats walking every button in the document and
+				// querying each button's subtree: the panel list publishes its slot on
+				// exactly one element per row, so the slot itself is the index.
+				for (const slot of document.querySelectorAll(`[data-slot="${PANEL_LIST_SLOT}"]`)) {
+					const host = typeof slot.closest === 'function' ? slot.closest('button') : null
+					if (host !== null && !rows.includes(host)) rows.push(host)
 				}
 			} catch {
 				return []
@@ -1338,12 +1478,14 @@ window.__ModuleLoader__.load({
 		 * @param {Function} openSession - navigation for a plain left click.
 		 * @returns {boolean} whether the row now carries an anchor.
 		 */
-		function enhanceRow(document, row, openSession) {
+		function enhanceRow(document, row, openSession, knownWorkspaceName) {
 			const id = sessionIdOfRow(row)
 			if (id === undefined) return false
 			// The workspace the row sits under leads the link, so a copied link says where the
 			// conversation lives. No workspace row in the tree means no guess: the plain route.
-			const workspaceName = workspaceNameOf(row, document)
+			// A caller that already resolved the tree hands the name in, so N rows cost one
+			// pass over the tree instead of N.
+			const workspaceName = arguments.length > 3 ? knownWorkspaceName : workspaceNameOf(row, document)
 			const href = workspaceName === undefined
 				? routeHash('session', id)
 				: routeHash('workspace', workspaceName, innerPath([WORKSPACE_SESSION_SEGMENT, id]))
@@ -1384,7 +1526,18 @@ window.__ModuleLoader__.load({
 			const scan = () => {
 				let linked = 0
 				try {
-					for (const row of document.querySelectorAll(ROW_SELECTOR)) if (enhanceRow(document, row, openSession)) linked += 1
+					const rows = document.querySelectorAll(ROW_SELECTOR)
+					let names
+					for (const row of rows) {
+						// Already a link, and the anchor is still in the row: remounting it
+						// costs a computed style and a tree walk and buys nothing. The check is a
+						// query inside one row (a handful of nodes), never a sweep of the document,
+						// so a rescan stays proportional to the rows that need one — and a row whose
+						// anchor a re-render dropped is healed on the next pass.
+						if (typeof row.querySelector === 'function' && row.querySelector(`[data-dsh-part="${ANCHOR_PART}"]`) !== null) continue
+						names ??= workspaceNamesOfRows(document)
+						if (enhanceRow(document, row, openSession, names.get(row))) linked += 1
+					}
 				} catch {
 					// A DOM that cannot be scanned is left untouched: the address-bar sync
 					// is the plugin's contract, the row links are an addition to it.
@@ -1444,10 +1597,64 @@ window.__ModuleLoader__.load({
 				style = undefined
 			}
 			let observer
+			let frame
+			let queued = false
+			const runScan = () => {
+				queued = false
+				frame = undefined
+				scan()
+			}
+			/**
+			 * Coalesce mutation batches into one scan per frame: a streaming answer mutates
+			 * the transcript many times per frame, and every batch used to buy a whole-document
+			 * scan. Without animation frames the scan runs straight away, so a minimal DOM
+			 * never waits on a frame that will not come.
+			 */
+			const scheduleScan = () => {
+				if (queued) return
+				if (typeof window.requestAnimationFrame !== 'function') {
+					scan()
+					return
+				}
+				queued = true
+				frame = window.requestAnimationFrame(runScan)
+			}
+			/**
+			 * Only a mutation batch that can introduce a row is worth a scan. Text nodes and
+			 * ordinary elements arrive constantly (streaming, hover, tool output) and never
+			 * carry a row.
+			 * @param {object[]} mutations - the batch the observer delivered.
+			 * @returns {boolean} whether a scan is warranted.
+			 */
+			const rowMayHaveArrived = mutations => {
+				// A batch delivered empty says nothing about what changed: scan rather than guess.
+				if (!Array.isArray(mutations) || mutations.length === 0) return true
+				for (const mutation of mutations) {
+					if (mutation === null || mutation === undefined) continue
+					if (mutation.type !== 'childList') continue
+					const added = mutation.addedNodes ?? []
+					for (const node of added) {
+						// Skip only what is provably not an element: a text or comment node can never
+						// carry a row, while a DOM without nodeType still gets looked at.
+						if (node === null || node === undefined) continue
+						if (node.nodeType !== undefined && node.nodeType !== 1) continue
+						if (typeof node.matches !== 'function') return true
+						if (node.matches(ROW_SELECTOR) || node.matches('[data-plugin-item],[data-plugin-package]')) return true
+						if (node.matches(`[data-slot="${PANEL_LIST_SLOT}"]`)) return true
+						if (typeof node.querySelector === 'function') {
+							if (node.querySelector(ROW_SELECTOR) !== null) return true
+							if (node.querySelector('[data-plugin-item],[data-plugin-package]') !== null) return true
+						}
+					}
+				}
+				return false
+			}
 			try {
 				const root = document.body ?? document.documentElement
 				if (root !== undefined && root !== null && typeof window.MutationObserver === 'function') {
-					observer = new window.MutationObserver(scan)
+					observer = new window.MutationObserver(mutations => {
+						if (rowMayHaveArrived(mutations)) scheduleScan()
+					})
 					observer.observe(root, { childList: true, subtree: true })
 				}
 			} catch {
@@ -1459,6 +1666,9 @@ window.__ModuleLoader__.load({
 			return () => {
 				try {
 					observer?.disconnect()
+					if (queued && typeof window.cancelAnimationFrame === 'function' && frame !== undefined) window.cancelAnimationFrame(frame)
+					queued = false
+					frame = undefined
 					style?.remove()
 					for (const row of [...document.querySelectorAll(ROW_SELECTOR), ...panelRows(document)]) {
 						row.querySelector(`[data-dsh-part="${ANCHOR_PART}"]`)?.remove()
@@ -1841,7 +2051,7 @@ window.__ModuleLoader__.load({
 				// One selector at a time (a comma list is beyond a small DOM stub) and the `nav`
 				// ancestor check keeps unrelated aria-current controls out of it.
 				activeSettingsSection: () => {
-					const overlay = window.document?.querySelector?.(`[${SETTINGS_SURFACE_ATTRIBUTE}="${SETTINGS_SURFACE_VALUE}"]`)
+					const overlay = settingsOverlayOf(window.document)
 					if (overlay === null || overlay === undefined || typeof overlay.querySelectorAll !== 'function') return undefined
 					for (const candidate of overlay.querySelectorAll('button')) {
 						if (typeof candidate.getAttribute !== 'function') continue
@@ -1854,7 +2064,7 @@ window.__ModuleLoader__.load({
 				},
 				// The tab a settings section is showing: the same ARIA contract one level deeper.
 				activeSettingsTab: () => {
-					const overlay = window.document?.querySelector?.(`[${SETTINGS_SURFACE_ATTRIBUTE}="${SETTINGS_SURFACE_VALUE}"]`)
+					const overlay = settingsOverlayOf(window.document)
 					if (overlay === null || overlay === undefined || typeof overlay.querySelectorAll !== 'function') return undefined
 					for (const candidate of overlay.querySelectorAll('[role="tab"]')) {
 						if (typeof candidate.getAttribute !== 'function') continue
@@ -1864,10 +2074,23 @@ window.__ModuleLoader__.load({
 					}
 					return undefined
 				},
+				// The overlay is a modal, and the platform's own dismiss path is a document-level
+				// Escape: the shipped modal layer registers `document.addEventListener('keydown',
+				// handler, true)` gated on `key === 'Escape'` and closes the topmost modal there.
+				// The registry that official `closeTopModal` walks is module-private to the bundle,
+				// so this key event is the only dismiss route a browser-half plugin has — and it is
+				// the same path the user's Esc key takes.
+				closeSettings: () => {
+					if (settingsOverlayOf(window.document) === undefined) return
+					attempt(() => {
+						const event = new window.KeyboardEvent('keydown', { key: 'Escape', bubbles: true, cancelable: true })
+						window.document?.dispatchEvent?.(event)
+					})
+				},
 				openSettings: (section, tab) => {
 					if (typeof section === 'string' && section !== '') {
 						// A section is named by the label the user reads, so the request is a label match.
-						const overlay = window.document?.querySelector?.(`[${SETTINGS_SURFACE_ATTRIBUTE}="${SETTINGS_SURFACE_VALUE}"]`)
+						const overlay = settingsOverlayOf(window.document)
 						const scope = overlay ?? window.document
 						if (typeof scope?.querySelectorAll === 'function') {
 							const candidates = [...scope.querySelectorAll('button')].filter(candidate => {
@@ -2053,6 +2276,259 @@ window.__ModuleLoader__.load({
 		 * Register the URL routing on the running GUI.
 		 * @param {object} ctx - client root context.
 		 */
+		// ---------------------------------------------------------------------
+		// desktop address bar: the DSH desktop window has no address bar of its own.
+		//
+		// The Windows shell draws its own 40px title bar inside the page — the preload
+		// marks `<html data-windows-titlebar>` and publishes
+		// `--dsh-windows-titlebar-height` — and leaves the strip between its menu and
+		// the window buttons empty. That strip is page space, so this router can put
+		// its own address bar in it: one input that names a route and opens it, which
+		// is the only way a link reaches the desktop window. Everywhere else (the web
+		// app, macOS) the marker is absent and this draws nothing at all.
+		// ---------------------------------------------------------------------
+		/**
+		 * Normalise what was typed into the address bar into a fragment this router owns.
+		 * @param {string} raw - the text in the bar.
+		 * @returns {string|undefined} the fragment to open, or undefined when nothing can be named.
+		 */
+		function titlebarFragmentOf(raw) {
+			const text = String(raw ?? '').trim()
+			if (text === '') return undefined
+			// A whole link: only its fragment is this router's to open.
+			if (/^[a-z][a-z0-9+.-]*:\/\//i.test(text)) {
+				const at = text.indexOf('#')
+				return at === -1 ? undefined : titlebarFragmentOf(text.slice(at))
+			}
+			// A bare id names that conversation, the way the shell's own menu copies it.
+			if (/^session-[0-9a-z-]{8,}$/i.test(text)) return routeHash('session', text)
+			const fragment = text.startsWith('#') ? text : `#${text.startsWith('/') ? '' : '/'}${text}`
+			return ROUTE_PATTERN.test(fragment) ? fragment : undefined
+		}
+
+		/**
+		 * The settings overlay element, when one is on screen. The official marker is tried first;
+		 * the other name is only ever present because a third-party theming plugin stamps it, so it
+		 * stays a fallback and nothing may depend on it being there.
+		 * @param {object} document - the document to look in.
+		 * @returns {object|undefined} the overlay element.
+		 */
+		function settingsOverlayOf(document) {
+			for (const attribute of [SETTINGS_MODAL_ATTRIBUTE, SETTINGS_SURFACE_ATTRIBUTE]) {
+				const found = attemptValue(() => document?.querySelector?.(`[${attribute}="${SETTINGS_SURFACE_VALUE}"]`))
+				if (found !== null && found !== undefined) return found
+			}
+			return undefined
+		}
+
+		/**
+		 * The fragment a reader can read: percent escapes decoded, or the raw text when the
+		 * escapes are malformed. Display only — the router still writes the encoded form.
+		 * @param {string} hash - the fragment.
+		 * @returns {string} the readable fragment.
+		 */
+		function readableFragment(hash) {
+			const text = String(hash ?? '')
+			try {
+				return decodeURIComponent(text)
+			} catch {
+				return text
+			}
+		}
+
+		/**
+		 * The conversation a route names, whichever shape it is written in.
+		 * @param {string} hash - the fragment.
+		 * @returns {string|undefined} the session id, when the route names one.
+		 */
+		function targetSessionOf(hash) {
+			const route = parseRoute(String(hash ?? ''))
+			if (route === undefined || route.unknown !== undefined) return undefined
+			if (route.kind === 'session') return route.id
+			if (route.kind !== 'workspace') return undefined
+			const parts = innerPath(route.inner)
+			const at = parts.indexOf(WORKSPACE_SESSION_SEGMENT)
+			return at >= 0 && at + 1 < parts.length ? parts[at + 1] : undefined
+		}
+
+		/**
+		 * Whether a route names the conversation another route names. A workspace prefix is
+		 * decoration, so the same conversation reached in either shape counts as arrived.
+		 * @param {string} wanted - the fragment handed over.
+		 * @param {string} now - the fragment to compare.
+		 * @returns {boolean} whether they name the same thing.
+		 */
+		function landedFragment(wanted, now) {
+			if (String(wanted) === String(now)) return true
+			const target = targetSessionOf(wanted)
+			return target !== undefined && target === targetSessionOf(now)
+		}
+
+		/**
+		 * Why a handed-over link did not land, in the few words the bar can show. The router's
+		 * own report is the source — it knows what is on screen and what it refused — so the
+		 * line stays factual instead of guessing a cause.
+		 * @param {string} wanted - the fragment handed over.
+		 * @returns {string} the line to show in the bar.
+		 */
+		function refusalReason(wanted) {
+			const report = attemptValue(() => window.__dshUrlRouter?.report?.())
+			const target = targetSessionOf(wanted)
+			const name = target === undefined ? String(wanted) : target.slice(0, 18)
+			const canonical = report?.canonical
+			const shown = canonical === undefined || canonical === null
+				? '无'
+				: `${canonical.kind}:${String(canonical.id).slice(0, 8)}`
+			const rows = report?.surfaces?.conversationRows ?? '?'
+			return `打不开 ${name}（当前 ${shown}，侧栏 ${rows} 行）`
+		}
+
+		/**
+		 * Draw the address bar into the desktop window's title bar strip.
+		 * @param {object} document - the document to draw into.
+		 * @param {Function} subscribe - registers a listener for every canonical write.
+		 * @returns {() => void} the disposer.
+		 */
+		function startTitlebarAddress(document, subscribe) {
+			if (document === undefined || document === null) return () => {}
+			const root = document.documentElement
+			// The marker is the shell's own statement that this page has a title bar drawn
+			// inside it. Without it there is no strip, and nothing is drawn.
+			if (typeof root?.getAttribute !== 'function' || root.getAttribute(WINDOWS_TITLEBAR_ATTRIBUTE) === null) return () => {}
+			if (typeof document.createElement !== 'function' || typeof document.body?.appendChild !== 'function') return () => {}
+			let style
+			try {
+				style = document.createElement('style')
+				style.id = TITLEBAR_STYLE_ID
+				style.textContent = TITLEBAR_STYLE_TEXT
+				const parent = document.head ?? document.body
+				if (parent !== undefined && parent !== null && typeof parent.appendChild === 'function') parent.appendChild(style)
+			} catch {
+				style = undefined
+			}
+			const bar = document.createElement('div')
+			bar.id = TITLEBAR_BAR_ID
+			if (typeof bar.setAttribute === 'function') bar.setAttribute('data-dsh-part', TITLEBAR_PART)
+			const input = document.createElement('input')
+			input.type = 'text'
+			input.spellcheck = false
+			input.placeholder = TITLEBAR_PLACEHOLDER
+			if (typeof input.setAttribute === 'function') input.setAttribute('aria-label', '地址栏 / address bar')
+			bar.appendChild(input)
+			/** Start after the shell's menu, stop before its window buttons. */
+			const place = () => {
+				let menuWidth = 0
+				try {
+					const menu = typeof document.querySelector === 'function' ? document.querySelector(`[${WINDOWS_MENU_ATTRIBUTE}]`) : null
+					if (menu !== null && menu !== undefined && typeof menu.getBoundingClientRect === 'function') menuWidth = menu.getBoundingClientRect().width || 0
+				} catch {
+					menuWidth = 0
+				}
+				bar.style.left = `${WINDOWS_MENU_START + menuWidth + TITLEBAR_GAP}px`
+				bar.style.right = `${TITLEBAR_CAPTION_WIDTH}px`
+			}
+			place()
+			/** How the bar looks right now: idle, waiting for a link to land, or refused. */
+			const mark = (state, hint) => {
+				if (typeof bar.setAttribute === 'function') bar.setAttribute('data-dsh-url-router-state', state)
+				if (typeof input.setAttribute === 'function' && typeof input.removeAttribute === 'function') {
+					if (hint === undefined) input.removeAttribute('title')
+					else input.setAttribute('title', hint)
+				}
+			}
+			/** Show the current fragment, unless the reader is in the middle of typing. */
+			const show = hash => {
+				if (document.activeElement === input) return
+				mark('idle', undefined)
+				input.value = readableFragment(hash)
+			}
+			show(window.location?.hash)
+			/** Whether the view has arrived where the link asked, judged by what is on screen. */
+			const arrived = wanted => {
+				const report = attemptValue(() => window.__dshUrlRouter?.report?.())
+				const canonical = report?.canonical
+				if (canonical === undefined || canonical === null) return false
+				return landedFragment(wanted, routeHash(canonical.kind, canonical.id, canonical.inner))
+			}
+			let settleTimer
+			const stopSettle = () => {
+				if (settleTimer !== undefined) attemptValue(() => window.clearTimeout(settleTimer))
+				settleTimer = undefined
+			}
+			/**
+			 * A link that never lands has to say so: this window has no console and no address
+			 * bar of its own, so a refused link would otherwise look like a dead input.
+			 * @param {string} wanted - the fragment handed over.
+			 * @param {boolean} retried - whether the plain hash write has been tried as well.
+			 */
+			const settle = (wanted, retried) => {
+				stopSettle()
+				settleTimer = attemptValue(() => window.setTimeout(() => {
+					settleTimer = undefined
+					if (arrived(wanted)) {
+						// Landed: the bar goes back to naming what is on screen, which is the
+						// canonical form of the route the reader typed.
+						mark('idle', undefined)
+						input.value = readableFragment(window.location?.hash)
+						return
+					}
+					// The direct adoption did nothing. Try the plain hash write once — that is the
+					// path a pasted link takes in a browser — and only then report a refusal.
+					if (!retried) {
+						attemptValue(() => {
+							window.location.hash = wanted
+						})
+						settle(wanted, true)
+						return
+					}
+					const why = refusalReason(wanted)
+					mark('refused', why)
+					input.value = why
+				}, TITLEBAR_SETTLE_MS))
+			}
+			const onKeyDown = event => {
+				if (event?.key === 'Escape') {
+					stopSettle()
+					mark('idle', undefined)
+					input.value = readableFragment(window.location?.hash)
+					return
+				}
+				if (event?.key !== 'Enter') return
+				const fragment = titlebarFragmentOf(input.value)
+				if (fragment === undefined) {
+					// Nothing here names a route: leave the address bar saying what is on screen.
+					stopSettle()
+					mark('idle', undefined)
+					input.value = readableFragment(window.location?.hash)
+					return
+				}
+				mark('pending', undefined)
+				// Handed over directly rather than by writing the hash and hoping for a
+				// `hashchange`: that event never fires when the hash already says this, and the
+				// desktop window is not the browser's own page. The router writes the hash itself.
+				driveTypedFragment(fragment)
+				settle(fragment, false)
+			}
+			input.addEventListener('keydown', onKeyDown)
+			document.body.appendChild(bar)
+			const offRoute = subscribe(show)
+			let onResize
+			try {
+				onResize = () => place()
+				window.addEventListener('resize', onResize)
+			} catch {
+				onResize = undefined
+			}
+			return () => {
+				offRoute?.()
+				stopSettle()
+				input.removeEventListener?.('keydown', onKeyDown)
+				if (onResize !== undefined) window.removeEventListener?.('resize', onResize)
+				bar.remove?.()
+				style?.remove?.()
+			}
+		}
+
 		function apply(ctx) {
 			// Fragment routing: the address bar names the view, and a link opens it.
 			ctx.effect(() => {
@@ -2101,6 +2577,12 @@ window.__ModuleLoader__.load({
 				const slots = probed.faces.slots
 				return startRowLinks(window.document, openSession, slots, selectPanel)
 			}, 'url-router: row links')
+			// Desktop address bar: only the Windows shell draws a title bar inside the page,
+			// and that strip is page space. No marker, no bar.
+			ctx.effect(() => {
+				if (typeof window === 'undefined' || window.document === undefined) return () => {}
+				return startTitlebarAddress(window.document, subscribeRoute)
+			}, 'url-router: desktop address bar')
 		}
 
 		exports.apply = apply

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-url-router",
-  "version": "0.3.1",
-  "description": "DSH Web GUI 地址栏路由插件：每个界面都有自己的链接（会话 / 主面板 / 插件页与组件页 / 任务看板），整行即真链接，只写 fragment。",
+  "version": "0.4.0",
+  "description": "DSH 地址栏路由插件：每个界面都有自己的链接（会话 / 主面板 / 插件页与组件页 / 任务看板 / 设置），整行即真链接，只写 fragment；Windows 桌面版把地址栏画在标题栏里。",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/DDDMUC/dsh-url-router.git"