dsh-url-router 0.1.1 → 0.1.2

package/README.md

@@ -1,120 +1,114 @@
 # dsh-url-router
 
-One URL for every surface: the address bar names what is on screen, and a link opens
-the surface it names. **Browser half only** — no dependencies, no host route, no telemetry.
+**DSH Web GUI 地址栏路由插件 —— 每个界面都有自己的链接：地址栏写着屏幕上的东西，链接点开就是那个界面。** 给 DeepSeek Harness (dsh) Web GUI 补上"可寻址"：点侧栏会话，地址栏变成 `#/session/<id>`；点插件面板，变成 `#/panel/plugins`；点进某个插件、某个组件、某个任务，地址栏跟着一起走。把这条链接贴到新标签页、或者对着侧栏任意一行右键，就是浏览器自己的行为——无需复制按钮、无需自定义菜单。
 
-```
-#/session/session-2b6e6371-6475-4c44-9f46-a779916a0b56   ← the conversation on screen
-#/panel/plugins                                          ← the Plugins panel
-#/panel/task-board                                       ← the Task Board panel
-```
+它是**地址栏的唯一写者**：只改 URL 的 fragment，路径与查询串（例如启动时的 `?token=…`）原样保留；只用 `replaceState`，浏览面板不会往后退栈里塞历史。**只有浏览器半区**——零依赖、无宿主路由、无遥测。
+
+[中文](#中文) · [English](#english)
+
+---
 
-Click the Plugins row in the sidebar and the address bar becomes `#/panel/plugins`;
-click a conversation and it becomes `#/session/<id>`. Paste either link into another
-tab (same machine, same `DSH_HOME`) and that surface opens.
+## 中文
 
-## Install
+### 安装
 
 ```sh
+# 通过插件管理器（推荐）
 dsh plugin --profile web add dsh-url-router
-# restart `dsh web`, then hard-refresh the browser
+
+# 重启 dsh web，之后硬刷新浏览器
 ```
 
-## Routes
-
-| Route | Surface | Opened by |
-|---|---|---|
-| `#/session/<id>` | the conversation the main view shows | `uiWorkspace.openSession(id)` |
-| `#/panel/<panelId>` | a main-column panel (`plugins`, `task-board`, `skill-explorer`, `ssh`, …) | `layout.selectPanel(id)` |
-| `#/panel/plugins/<package>` | an installed plugin's page | the panel's own list row control |
-| `#/panel/plugins/<item>` | a built-in plugin's page (`shell`, `agent-loop`, `subagent`, `web-search`) | the panel's own list row control |
-| `#/panel/plugins/<package>/<component>` | one component page inside that plugin's page | the panel's own component row control |
-| `#/panel/task-board/task/<taskId>` | one task's detail on the task board | the task board's own `dsh-taskboard-open-task` window event |
-| `#/panel/task-board/new` | the task board's new-task form | the task board's own `dsh-taskboard-new-task` window event |
-
-Route kinds are owned by this plugin; a kind it does not know (`#/settings/…`) is
-**left alone** with a single diagnostic, so another router can own it later.
-
-A panel's inner pages are the panel's own vocabulary, so this plugin never invents one:
-the plugin manager publishes `data-plugin-detail` / `data-plugin-item-detail` /
-`data-plugin-row-detail`, and the task board publishes `data-dsh-taskboard-open-task` /
-`data-dsh-taskboard-new-task` while asking for a task on a window event of the same name.
-
-## Row links
-
-Every conversation row in the sidebar is exposed as a **real link** — a transparent
-`<a href="#/session/<id>" target="_blank">` covering the row, so the browser's own link
-behavior applies with no custom menu:
-
-- **right-click** → the native menu (open link in new tab / copy link / save link as)
-- **middle click, Cmd/Ctrl+click** → a new tab, natively
-- **plain left click** → opens the conversation *here* (`preventDefault` + the official
-  navigation), so the address bar keeps using `replaceState` and no history entry is added
-- the row's own controls (⋯, buttons) are lifted above the overlay and keep working
-
-The same applies to the **main-panel rows** (Plugins, Task Board, …): each becomes
-`#/panel/<id>`. A panel row carries no identity in the DOM, so its id comes from the panel
-registry (`ctx.slots.entries('sidebar.panellist')`), matched by accessible name and aligned
-by registration order; a row that cannot be matched is left untouched.
-
-It supersedes the earlier `dsh-session-url` plugin: install one, not both (both write the
-fragment). The link shape `#/session/<id>` is identical, so existing links keep working.
-
-## Rules it keeps
-
-- **Fragment only.** Path and query string are never touched (a launch `?token=…` survives).
-- **One writer.** This plugin owns the fragment; run it *instead of* any other plugin
-  that writes the address bar (`dsh-session-url` mirrors conversations into the same
-  fragment — the two would overwrite each other).
-- **`replaceState` only**, so browsing panels does not fill the Back stack.
-- **Scopes are declared, not guessed.** A main panel is application-level (it lists this
-  machine's plugins, not a conversation), so its link carries no session id.
-- **A link stays authoritative until it lands** (at most one boot, 8 s): once the named
-  surface is on screen the link stops owning the URL, so walking deeper inside a panel
-  updates the address bar instead of being pulled back to the link.
-- **A link wins for one boot.** Both owners restore their own remembered state while the
-  page loads, so a linked surface stays authoritative for 8 s; after that the view owns
-  the URL again.
-- **Never throws.** Refused navigations and broken services are contained, reported once,
-  and fall back to the view actually on screen — never a blank page.
-
-## Limits
-
-- Depends on the official client faces `ctx.layout.selectPanel` / `ctx.layout.panelInfo`
-  and the session/workspace controllers. If their shape changes, the plugin disables
-  itself with one diagnostic rather than touching official behavior.
-- Row links depend on the official row markup (`div[data-row-key="session:<id>"]`); if
-  that changes the plugin degrades to doing nothing rather than touching official rows.
-- Settings sections are **not** routed yet: the settings package exposes no
-  "open section" seam (they are keyed list slots). Right-hand panes are openable
-  (`ISidebarRight.openTab(kind)`) but not yet routed.
-- An unregistered panel id is refused by the layout by *throwing*; the link is dropped at
-  the end of its window with one diagnostic. A panel that registers within the window is
-  still reached.
+开发时也可以直接挂工作树：
 
----
+```sh
+dsh plugin --profile web add "link:/path/to/dsh-url-router"
+```
+
+### 路由表
+
+| 地址 | 界面 | 由谁打开 |
+| --- | --- | --- |
+| `#/session/<id>` | 主视图里的那个会话 | `uiWorkspace.openSession(id)` |
+| `#/panel/<panelId>` | 主面板（`plugins`、`task-board`、`skill-explorer`、`ssh` …） | `layout.selectPanel(id)` |
+| `#/panel/plugins/<包名>` | 某个已安装插件的页面 | 面板自己的列表行控件 |
+| `#/panel/plugins/<官方项 id>` | 某个官方内置插件的页面（`shell`、`agent-loop`、`subagent`、`web-search`） | 面板自己的列表行控件 |
+| `#/panel/plugins/<包名>/<组件 id>` | 插件页面里的某个组件页 | 面板自己的组件行控件 |
+| `#/panel/task-board/task/<任务 id>` | 任务看板里某个任务的详情 | 任务看板自己的 `dsh-taskboard-open-task` 窗口事件 |
+| `#/panel/task-board/new` | 任务看板的新建任务表单 | 任务看板自己的 `dsh-taskboard-new-task` 窗口事件 |
+
+输入侧宽容：`sessions`/`panels` 复数、百分号编码都接受，一律规范化成上面的形式。**不认识的段位不碰**（例如 `#/settings/…`），只留一条诊断，留给以后的路由器。
+
+面板内部页是**面板自己的词汇表**，本插件不发明：插件管理器发布 `data-plugin-detail` / `data-plugin-item-detail` / `data-plugin-row-detail`，任务看板发布 `data-dsh-taskboard-open-task` / `data-dsh-taskboard-new-task`，并接受同名窗口事件。
+
+### 每一行都是真链接
+
+侧栏的会话行、插件面板的列表行（已安装组与官方组）都是**整行覆盖的透明真锚点**：
 
-# dsh-url-router（中文）
+- **右键** → 浏览器原生菜单（在新标签页中打开 / 复制链接 / 另存为）
+- **中键、Cmd/Ctrl + 单击** → 原生新标签页
+- **左键单击** → 在本页打开（`preventDefault` 后调官方导航，不新增历史记录）
 
-**一个界面，一条链接。** 地址栏永远描述屏幕上的东西，链接打开它命名的界面。
+### 它守的规矩
 
-- 点侧栏「插件」→ 地址栏变成 `#/panel/plugins`；点回某个对话 → 变回 `#/session/<id>`。
-- 把链接粘到另一个标签页（同机、同 `DSH_HOME`）就能直接打开那个界面。
-- 只写 fragment，路径与查询串原样保留；只用 `replaceState`，不往历史里塞垃圾。
-- **它必须是地址栏的唯一写者**：不要和 `dsh-session-url` 同时启用（两者会互相覆盖）。
-- 未知的段位（如 `#/settings/…`）一律**不碰**，只留一条诊断，留给将来的路由器。
-- 目标打不开（未注册的面板、归档的会话）→ 到期丢弃 + 一条诊断 + 回落到屏幕上真实的界面，**绝不白屏、绝不抛错**。
+- **只动 fragment**：路径与查询串从不改写（启动 `?token=…` 能活下来）。
+- **唯一写者**：本插件拥有 fragment，请**不要**和别的写 fragment 的插件同时启用（例如 `dsh-session-url`），两者会互相覆盖。
+- **只用 `replaceState`**：浏览面板不污染后退栈。
+- **作用域由视图决定，不靠猜**：主面板是应用级界面（列的是本机插件，不是某个对话），所以它的链接不带会话 id。
+- **链接落地即交权**：视图一旦变成链接描述的那个界面，链接立刻失去权威——这样你在面板里继续点进去时，地址栏不会被拽回上一层。
+- **绝不抛错**：官方 `selectPanel` 对未注册的面板 id 是抛异常的；所有宿主面调用都被容纳，失败只留一条诊断并回落到屏幕上真实的视图。
 
-## 安装
+### 已知限制
+
+- **设置页分区暂未纳入**：设置包没有"打开某个分区"的接缝（它们是 keyed list slot），只能等它自己发布类似契约。
+- **右栏 pane 与会话内轮次/消息锚点暂未纳入**。
+- **技能中心 / SSH 的内部页**：需要它们各自发布"当前实体 id + 按 id 打开"的契约（任务看板就是这么做的）。
+- 链接**同名不跨机**：会话 id 只在同一台机器、同一个 `DSH_HOME` 下有意义。
+
+### 开发
+
+手写 JS 直接进 `lib/`（无构建步骤），`npm test` 直接跑交付产物（35→45 条用例，`node --test`）。改之前请读 [AGENTS.md](AGENTS.md) 里的路由与行链接契约。
+
+## English
+
+**A URL router for the DSH Web GUI — every surface gets its own link.** Click a conversation and the address bar becomes `#/session/<id>`; click a panel (Plugins, Task Board, …) and it becomes `#/panel/<panelId>`; walk into a plugin, a component, or a task and the bar follows. Paste the link into another tab, or right-click any sidebar row for the browser's own "open in new tab / copy link".
+
+It is the **single writer of the fragment**: path and query string (a launch `?token=…`) are never touched, and it only ever calls `replaceState`. **Browser half only** — no dependencies, no host route, no telemetry.
+
+### Install
 
 ```sh
 dsh plugin --profile web add dsh-url-router
-# 重启 dsh web，之后硬刷新浏览器
+# restart `dsh web`, then hard-refresh the browser
 ```
 
-## 已知限制
+### Routes
+
+| Route | Surface |
+| --- | --- |
+| `#/session/<id>` | the conversation the main view shows |
+| `#/panel/<panelId>` | a main-column panel |
+| `#/panel/plugins/<package>` | an installed plugin's page |
+| `#/panel/plugins/<item>` | a built-in plugin's page (`shell`, `agent-loop`, `subagent`, `web-search`) |
+| `#/panel/plugins/<package>/<component>` | one component page inside that plugin's page |
+| `#/panel/task-board/task/<taskId>` | one task's detail on the task board |
+| `#/panel/task-board/new` | the task board's new-task form |
+
+A kind it does not know (`#/settings/…`) is left alone with a single diagnostic. Panel inner pages are the panel's own vocabulary: the plugin manager publishes `data-plugin-detail` / `data-plugin-item-detail` / `data-plugin-row-detail`, the task board publishes `data-dsh-taskboard-open-task` / `data-dsh-taskboard-new-task`.
+
+### Every row is a real link
+
+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.
+
+### Rules it keeps
+
+- **Fragment only.** Path and query are never rewritten.
+- **One writer.** Do not run another fragment writer (`dsh-session-url`) beside it.
+- **`replaceState` only**, so panels never fill the Back stack.
+- **Scopes are declared, not guessed.** A panel is application-level and carries no session id.
+- **A link stays authoritative until it lands**, then hands the address bar back.
+- **Never throws.** Refused navigations are contained with one diagnostic.
+
+### Limits
 
-- 依赖官方 `ctx.layout.selectPanel` / `panelInfo` 与会话、工作区控制器；形态变了就自我禁用（一条诊断），不改官方行为。
-- **任务看板内部页已纳入**：`#/panel/task-board/task/<任务id>`（任务详情弹层）、`#/panel/task-board/new`（新建任务表单）。这两条靠任务看板自己发布的契约（`data-dsh-taskboard-open-task` / `data-dsh-taskboard-new-task` + 同名窗口事件），本插件不猜它的弹层。
-- **设置页分区暂未纳入**（设置包没有"打开某分区"的接缝；它们是 keyed list slot）。
-- 右栏 pane 能打开（`ISidebarRight.openTab(kind)`），但尚未纳入路由。
+Settings sections (no open seam yet), the right-hand panes, and in-conversation turn anchors are not routed. Skill Center / SSH inner pages need their own "publish the current id + accept an open request" contract, the way the task board did. Session links are meaningful on the same machine and `DSH_HOME` only.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-url-router",
-  "version": "0.1.1",
-  "description": "DSH Web GUI plugin: one URL for every surface — the address bar names what is on screen (a conversation or a main panel) and a link opens it. Single owner of the URL fragment; browser half only, no dependencies, no telemetry.",
+  "version": "0.1.2",
+  "description": "DSH Web GUI 地址栏路由插件：每个界面都有自己的链接（会话 / 主面板 / 插件页与组件页 / 任务看板），整行即真链接，只写 fragment。",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/DDDMUC/dsh-url-router.git"