dsh-quick-toc 0.4.1 → 0.5.1

package/CHANGELOG.en.md

@@ -2,6 +2,47 @@
 
 All notable changes to **dsh-quick-toc** are documented here. Chinese version: [CHANGELOG.md](CHANGELOG.md).
 
+## [0.5.1] - 2026-09-13
+
+### Added
+- **"Back to the newest row" button**: a round button in the outline list's lower-right corner. It fades in whenever the list is not at its bottom and fades out once it is; clicking scrolls the outline back to the newest entry (smooth for a short distance, instant when the list is far up).
+- **Turn stamps carry the day**: the time shown in group headers, search result rows and hover cards is no longer a bare `HH:MM` — yesterday reads `昨天 15:04`, the day before `前天 15:04`, anything older `25-09-11 15:04` (two-digit year; decided by calendar day, not a 24-hour difference).
+- **Failures are reported**: a turn that produced no reply at all (request timeout, upstream error) now shows a `请求失败` row under its group header with the host's own error text; clicking it jumps to that error in the conversation, and the error text is searchable in full-text scope (its result row is tagged 请求失败).
+
+### Changed
+- **The header now holds two buttons per side**: the heading-level filter and the dock toggle on the left, search and collapse on the right, with a spacer pinning the pairs to the two ends; the three-bar identity mark on the left is gone.
+- **The level filter popup is left-aligned with its button** (it used to be right-aligned).
+- **The mount diagnostic is silent by default**: the console no longer prints `[dsh-quick-toc] panel mounted …`. To diagnose, run `localStorage.setItem("dsh-quick-toc.debug", "1")` and reload — the line then reports `turnOutline` and the jump loader's stage-by-stage state, while normal use stays quiet.
+- **Long jumps land instantly**: a jump across a long history no longer "stops halfway" (short jumps still glide smoothly); after landing it re-checks for ~0.6s, which corrects a target that moved while content was mounting.
+
+### Fixed
+- **Failed or aborted turns were mislabelled 未加载**: those turns have no model reply, so they carried neither a time nor headings and were re-listed as unloaded turns. A loaded user message now counts as "this turn is loaded", failures additionally show their error row, and a user-aborted turn simply shows as a heading-less turn.
+- **Scrolling the outline up to load older messages bounced the transcript back to the newest turn**, so paging up never got anywhere: the host force-scrolls to the bottom whenever a scroll is not attributed to the reader while it still believes the reader sits at the bottom, and a page-in triggered from the outline matches exactly that condition. The plugin now lifts the transcript just off the bottom stick zone before clicking the host's "load earlier", so the page-in keeps its place.
+- **A heading-less turn's group header was formatted unlike every other header**: it used to be enlarged (12px / 600 / primary colour), which made it read as a different kind of entry. All group headers now share one style (11px, secondary colour, one row box); a heading-less turn is simply a group with no rows under its header.
+
+## [0.5.0] - 2026-09-12
+
+### Added
+- **Whole-session turn index**: with the host's `turnOutline` projection the outline now covers **every turn of the session**, including turns the paged event window has not loaded. Unloaded turns appear as entries tagged 未加载 with the host's prompt/response previews (host-side budgets: 50 / 120 characters); clicking one pages that turn in through the host's turn-jump loader and scrolls to it. On a host without the projection the panel degrades to loaded turns only.
+- **Row subtitles**: under each heading the panel shows the first sentence of that section's body (skipping blank lines, fenced code, table rules and bare bullet markers), so identically-titled headings can be told apart at a glance.
+- **Hover previews**: hovering a heading or result row opens a card after ~0.26s with the title, turn time, heading path and the section's opening (up to 260 characters); docked right, the card opens to the left; leaving the row fades it out.
+- **Search normalization (always on)**: letter case, full-width/half-width forms and runs of whitespace count as the same match, and the highlight lands on the real characters of the original text.
+- **"Fuzzy" switch**: an independent toggle next to the title/full-text pill. When on, a query also matches text with a little material wedged in between (subsequence matching with a bounded gap); the setting is remembered.
+- **Unloaded turns are searchable too**: full-text scope also searches the previews of unloaded turns, and clicking such a hit loads the turn first, then locates and highlights.
+- **Edge hints**: under the search results, "scroll up to load earlier messages" — dismissed by the first upward scroll. In the outline, reaching the first turn (or scrolling down while already at the last) flashes "已经是最早的消息" / "已经到底了" at the bottom of the panel: fade in, ~2.6s hold, fade out.
+
+### Changed
+- **Auto-follow tracks more tightly**: the artificial delay is gone, the outline positions itself instantly instead of animating after the conversation, and the highlight transition dropped from 0.3s to 0.15s. Following no longer depends on the one scroll container captured at mount — it listens on the document in the capture phase and re-queries the container on every run, with a slow poll as a backstop, so it also keeps working after programmatic jumps (the native turn rail).
+- **The turn being read is marked by a closed blue box** (light fill + outline + left accent bar) that fades in and out; other turns are no longer dimmed into grey (0.6 → 0.85) and the panel's idle opacity went 0.45 → 0.72, which makes the whole list far more readable.
+- **Heading-less turns** promote their time row to body-level size and weight (12px / 600 / primary colour) instead of a grey caption, and they now look the same as headed turns when they are the one being read.
+- Active-state colour collapsed onto a single source: the search button, the level-filter button (including while it animates shut), the title/full-text pill, the fuzzy switch, the level chips and the current result row all use the same tint.
+- The click on the host's "load earlier" is throttled to 900ms while scrolling the outline (one continuous scroll cannot hammer the pager); scrolling the outline still both expands the index and loads older conversation, as in 0.4.x.
+- Every UI string now comes from one table, preparing the zh/en split (the 0.5.0 interface is still Chinese).
+
+### Fixed
+- After jumping with the native turn rail (the tick bar on the right of the conversation), the outline stopped following and no longer lit up the turn being read: the follow listener was bound to the scroll container captured **at mount**, and a jump that repages the window replaces that container, so the listener sat on a discarded node and never saw another scroll event. It now listens on the document in the capture phase and re-queries the current container on every run.
+- A turn without Markdown headings could never become the turn being read (no highlight, no follow): the node→turn map used by the follow only registered messages that carry headings. Every node of the turn (the user message and each model reply) is registered now.
+
 ## [0.4.0] - 2026-09-11
 
 ### Added

package/CHANGELOG.md

@@ -2,6 +2,47 @@
 
 **dsh-quick-toc** 的重要变更都记录在这里。英文版见 [CHANGELOG.en.md](CHANGELOG.en.md)。
 
+## [0.5.1] - 2026-09-13
+
+### 新增
+- **「回到底部」浮动按钮**：大纲列表右下角的圆形按钮。列表不在底部时渐显，滚到底后渐隐；点击把大纲滚回最新一条（近距离平滑滚动，长距离即时到位）。
+- **回合时间带日期**：组头、搜索结果行与悬停卡片里的时间不再只有 `HH:MM`——昨天显示 `昨天 15:04`，前天显示 `前天 15:04`，更早显示 `25-09-11 15:04`（年份取后两位；按自然日判定，不是按 24 小时差）。
+- **失败回合的报错**：请求超时、上游报错这类没有产出任何回复的回合，现在在组头下方显示一行 `请求失败` 与宿主提供的报错原文；点击跳到对话中该报错的位置，报错原文同样能被全文搜索命中（结果行带「请求失败」标记）。
+
+### 变更
+- **标题栏改为一边两个按钮**：左侧「层级筛选 + 停靠切换」，右侧「搜索 + 收起」，中间留白把两组顶到两端；并去掉左侧的三条杠装饰标识。
+- **层级筛选弹层改为左对齐按钮**（此前在按钮右侧对齐）。
+- **挂载诊断日志默认静默**：控制台不再打印 `[dsh-quick-toc] panel mounted …`。需要排查时先执行 `localStorage.setItem("dsh-quick-toc.debug", "1")` 再刷新即可看到该行（`turnOutline` 与跳转加载器的分阶段状态），正常使用不再有噪音。
+- **长距离跳转改为即时定位**：跨越很长历史的跳转不再"滚到一半停下"（近距离仍是平滑滚动），落地后还有约 0.6 秒的校验，用于纠正内容高度在飞行途中变化的情况。
+
+### 修复
+- **失败或中止的回合被误标成「未加载」**：这类回合没有模型回复，既没有时间也没有标题，被当成尚未加载的回合重新列了一遍。现在"该回合的用户消息已加载"本身就是已加载的依据，失败回合另加报错行；被用户中止的回合按普通无标题回合显示。
+- **从大纲往上翻加载更早消息时，对话区会被弹回最新一条**，越翻越回到底部：宿主在"这次滚动不是读者发起、且它仍认为读者停在底部"时会强制滚回底部，而从大纲触发的翻页恰好命中该条件。现在点击宿主的「加载更早」之前会先把对话区抬离贴底区，翻页保持原位。
+- **无标题回合的组头与其它组头格式不一致**：它此前被整体放大（12px / 600 / 正文色），与常规组头并列时像另一种条目。现在所有组头共用同一套样式（11px、次要色、同一行盒），无标题回合只是"组头下面没有行"。
+
+## [0.5.0] - 2026-09-12
+
+### 新增
+- **全量回合索引**：接入宿主的 `turnOutline` 投影后，大纲覆盖**整段会话**的回合，包括分页窗口尚未加载进来的那些。未加载的回合显示为带「未加载」标记的条目，附宿主提供的提问/回答预览（宿主侧上限 50 / 120 字），点击即通过宿主的回合跳转加载器把该回合翻页加载进来再滚过去。宿主没有该投影时退化为只列已加载的回合。
+- **标题行副标题**：每个标题下方显示该节正文的第一句（跳过空行、围栏代码块、表格线与纯项目符号），同名标题一眼可辨。
+- **悬停预览**：悬停标题行或结果行约 0.26 秒后弹出预览卡片，显示标题、回合时间、层级路径与该节开头（最多 260 字）；面板停靠右侧时卡片弹在左侧；移开鼠标渐隐。
+- **搜索归一化（常开）**：大小写、全角/半角、连续空白差异视为同一个匹配，命中高亮落在原文的真实字符上。
+- **「模糊」开关**：搜索框右侧、与「标题/全文」并排的独立开关。开启后允许关键字中间夹少量其他文字（子序列匹配，跨度有上限），开关状态会被记住。
+- **未加载的回合也能被搜到**：「全文」范围同时搜索未加载回合的预览文本，命中行的点击同样是"先加载、再定位并高亮"。
+- **边界提示**：搜索结果下方提示「向上滚动可加载更早的消息」，往上一滚即消失；大纲态滚到第一条、或已在最后一条仍继续下滚时，面板底部浮出「已经是最早的消息」/「已经到底了」，渐显、停留约 2.6 秒后渐隐。
+
+### 变更
+- **自动跟随更跟手**：去掉跟随路径上的人为延时、大纲改为瞬时定位（不再用平滑动画追赶）、高亮过渡由 0.3 秒缩到 0.15 秒。跟随也不再依赖"挂载时抓到的那一个滚动容器"——改为在 document 捕获阶段监听并在每次运行时重新查询容器，另加低频轮询兜底，程序化跳转（原生回合轨道）之后也能继续跟随。
+- **正在阅读的回合改用封闭的蓝色框**标记（浅蓝填充 + 四周描边 + 左侧强调条），出现与消失都是渐显渐隐；其余回合不再压到很暗（0.6 → 0.85），面板静止透明度 0.45 → 0.72，整体可读性提升。
+- **无标题回合的时间行**提升为正文级字号与字重（12px / 600 / 正文色），不再是一行灰色小注；有标题与无标题的回合在成为"正在阅读"时外观一致。
+- 界面激活态配色收敛到单一色源：搜索按钮、层级筛选按钮（含收回动画期间）、「标题/全文」、「模糊」开关、层级芯片、搜索结果当前行统一使用同一个浅蓝。
+- 往上翻大纲时对宿主的「加载更早」点击加了 900ms 节流（连续滚动不会反复触发分页）；大纲态"滚动既展开索引、也加载更早的对话"这一行为与 0.4.x 保持一致。
+- 所有界面文案收敛到一张字符串表，为后续中英双语做准备（0.5.0 的界面文字仍是中文）。
+
+### 修复
+- 用对话右侧的原生回合轨道（刻度条）跳转之后，大纲不再自动跟随、正在阅读的回合也不再点亮：跟随的滚动监听绑在**挂载时抓到的那个滚动容器**上，而跳转重新分页时该容器会被替换，监听器留在被丢弃的节点上，从此收不到任何滚动事件。现在改为在 document 捕获阶段监听，并在每次运行时重新查询当前容器。
+- 没有 Markdown 标题的回合无法成为"正在阅读"的回合（不点亮、不跟随）：跟随用的"节点 → 回合"映射只登记了带标题的消息，无标题回合的节点一个都没登记。现在该回合的所有节点（用户消息与每条模型回复）都会登记。
+
 ## [0.4.0] - 2026-09-11
 
 ### 新增

package/README.en.md

@@ -2,19 +2,27 @@
 
 > **English** | [中文](README.md)
 
-A conversation TOC plugin for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH): it turns the Markdown headings (H1–H6) of AI replies into a navigable outline panel, grouped by conversation turn, with auto-follow highlighting, keyword search and in-chat match highlighting.
+A conversation TOC plugin for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH): it turns the Markdown headings (H1–H6) of AI replies into a navigable outline panel, grouped by conversation turn and covering the whole session (including turns that are not loaded yet), with title/full-text search, hover previews and reading-position auto-follow.
 
 ## Features
 
 - **Turn-grouped outline** — each user message plus its following AI replies form one group; the group header shows the turn's time and a first-line preview, and clicking it jumps to the start of that turn's model reply
-- **Search** — the magnifier in the panel header opens a search box: title / full-text scopes, click any result row to locate and highlight that hit, `n/N` Enter stepping, Esc to close
+- **Whole-session coverage** — turns the conversation window has not loaded are listed too (tagged 未加载, with previews); clicking one loads that turn and jumps to it
+- **Failures are reported** — a turn with no reply at all (request timeout, upstream error) shows `请求失败` plus the host's error text, and clicking it jumps to that error in the conversation
+- **Turn stamps carry the day** — yesterday reads `昨天 15:04`, the day before `前天 15:04`, anything older `25-09-11 15:04`, so times never blur together in a session spanning days
+- **Row subtitles** — under each heading, the first sentence of that section, so identically-titled headings can be told apart
+- **Hover previews** — hovering a heading row shows the section's opening, the turn time and the heading path
+- **Search** — title / full-text scopes; click any result row to locate and highlight that hit, `n/N` Enter stepping, Esc to close
+- **Search tolerance** — case, full-width/half-width and whitespace differences match automatically; the "fuzzy" switch also allows a little material wedged between keywords
 - **In-chat highlighting** — matched keywords are highlighted in the conversation; the current match is highlighted distinctly
 - **Sticky group headers** — while scrolling the outline, the current turn's header stays pinned at the top of the panel
 - **Heading level filter** — the round levels button in the header pops down H1–H6 switches for any combination
-- **Auto-follow** — the turn being read lights up in the outline while you scroll the conversation; the outline loads and follows on its own
+- **Auto-follow** — the turn being read lights up in a closed blue box while you scroll the conversation; the outline follows on its own
 - **Jumping** — click a heading to jump to its position in the conversation
+- **Back to the newest row** — after paging far up, a floating button in the list's lower-right corner returns to the newest entry in one click (it appears when the list is not at its bottom and disappears once it is)
 - **Dockable and resizable** — drag the top bar to move the panel, ◀ / ▶ to dock left or right, drag an edge to resize, and collapse it into an edge handle; position and size are remembered
-- **Paging** — the most recent groups show first; scroll up to load older turns
+- **Paging** — the most recent groups show first; scrolling up both expands the index and loads older conversation
+- **Edge hints** — a brief hint at the bottom of the panel when you keep scrolling past the first or the last entry
 - **Markdown-aware** — inline markup in headings is stripped; `#` lines inside fenced code blocks are not headings
 - **Theme-aware** — adapts to dark and light themes; visible on the chat view only and fades out elsewhere
 - The panel hides itself when the conversation has neither headings nor readable times
@@ -23,12 +31,14 @@ A conversation TOC plugin for [DeepSeek Harness](https://github.com/deepseek-ai/
 
 | Plugin | Supported DSH |
 | --- | --- |
-| **0.4.1** (latest) | 0.1.5-rc.1, 0.1.5-rc.2 |
+| **0.5.1** (latest) | 0.1.5-rc.1, 0.1.5-rc.2 |
+| 0.5.0 | 0.1.5-rc.1, 0.1.5-rc.2 |
+| 0.4.1 | 0.1.5-rc.1, 0.1.5-rc.2 |
 | 0.4.0 | 0.1.5-rc.1, 0.1.5-rc.2 |
 | 0.3.3 | 0.1.5-rc.1 |
 | 0.3.0 – 0.3.2 | ≥ 0.1.2-rc.1 |
 
-`engines.dsh` has a floor of **0.1.5-rc.1** (`>=`): from that release on, the plugin uses the host's session-scoped slot injection. Since 0.4.0 the plugin has been verified against **0.1.5-rc.1 and 0.1.5-rc.2** and declares exactly those; older or newer DSH versions are unverified and therefore not claimed. On an older DSH, the newest usable plugin version is **0.3.2**. On install or update, the DSH market pre-flights host compatibility from `engines.dsh`, `dsh.compatibility.dshReleases` and `peerDependencies` in `package.json`.
+`engines.dsh` has a floor of **0.1.5-rc.1** (`>=`): from that release on, the plugin uses the host's session-scoped slot injection. 0.5.1 was tested on **0.1.5-rc.2**, and the host interfaces it relies on — the `turnOutline` projection, the session-scoped `useProjection`, the client `sessions` service and its `loadThrough` jump loader (since 0.5.0), and the `turn-error` node used for failed turns (since 0.5.1) — were checked one by one against the installed **0.1.5-rc.1** bundles, so both are declared. Older or newer DSH versions are unverified and therefore not claimed; on an older DSH the newest usable plugin version is **0.3.2**. On install or update, the DSH market pre-flights host compatibility from `engines.dsh`, `dsh.compatibility.dshReleases` and `peerDependencies` in `package.json`.
 
 ## Install
 
@@ -54,12 +64,25 @@ After installing, restart DSH and open the Web UI. The panel starts collapsed; c
 
 ## Usage
 
-- **Jumping**: click an outline heading or a group header to jump to it
+- **Jumping**: click an outline heading or a group header to jump to it; entries tagged 未加载 load that turn first, and a failed turn's error row jumps to that error in the conversation
 - **Search**: open the box with the magnifier, click a result to locate and highlight it, Enter to step through matches, Esc to close
+- **Search tolerance**: full-width/half-width, case and whitespace differences match automatically; for looser matching turn on the "fuzzy" switch next to the search box
 - **Level filter**: click the round levels button in the header to pop down the H1–H6 switches
 - **Moving and docking**: drag the top bar to move, ◀ / ▶ to switch sides
 - **Resizing**: drag the right edge, bottom edge or bottom-right corner
-- **Loading older turns**: scroll up inside the outline
+- **Loading older turns**: scroll up inside the outline (it both expands the index and loads older conversation)
+- **Back to the newest row**: after paging far up, click the floating button in the list's lower-right corner
+- **Reading position**: scroll the conversation and the turn you are reading is boxed in blue; the outline follows
+
+## Diagnostics
+
+Mounting the panel prints **nothing** by default. To check the host facilities, run this once in the browser console:
+
+```
+localStorage.setItem("dsh-quick-toc.debug", "1")
+```
+
+then reload: the console shows one line, `[dsh-quick-toc] panel mounted · turnOutline=… · jumpLoader=…`. A missing `turnOutline` means the host has no such projection, and the staged `jumpLoader` wording (`no-sessions-service` / `no-binding-api` / `no-binding-for-session` / `no-loadThrough` / `binding-threw`) pinpoints which link of the jump bridge is broken. Turn it off again with `localStorage.removeItem("dsh-quick-toc.debug")`.
 
 ## Development
 
@@ -67,7 +90,9 @@ After installing, restart DSH and open the Web UI. The panel starts collapsed; c
 - `lib/index.js` — host-side entry (empty; this plugin ships browser-side UI only)
 - `cordis.patch.yml` — loader patch (official DSH bundle format)
 - The panel registers into the session-scoped `conversation.input.overlay` slot so it receives session-scoped hooks (`useChat`, `useSession`, `sessionId`, …), and renders itself through `createPortal` into `document.body` as a fixed floating dock; conversation data comes from `props.useChat` (`ChatSnapshot.order` and `nodes`; node shape: `kind: user/assistant-step`, `location.turn`, `data.blocks`)
-- Changes to `lib/client.js` take effect after restarting DSH
+- The "unloaded turn" capability needs two host facilities: the `turnOutline` projection (the whole-session turn index, each entry carrying its `turn/start` seq) and the turn-jump loader (the client `sessions` service's `binding(sessionId).session.loadThrough(seq)`, reached through the client ctx's declaration-free `ctx.get("sessions")` lookup). Each degrades on its own: without the projection the outline lists loaded turns only, without the loader unloaded entries are shown but not jumped to, and nothing else in the panel is affected.
+- The failure row reads the host's `turn-error` conversation node (published when `turn/end` carries an `error` reason, with `message` and an optional `code`); on a host without that node the row is simply absent and nothing else changes.
+- Changes to `lib/client.js` show up after a page refresh (client modules are served under a content hash and DSH's client HMR pushes reloads); restart DSH only if that does not take
 
 ## License
 

package/README.md

@@ -2,19 +2,27 @@
 
 > [English](README.en.md) | **中文**
 
-**DeepSeek Harness（DSH）对话大纲插件**：把 AI 回复中的 Markdown 标题（H1–H6）提取成可导航的大纲面板，按对话回合分组，自动跟随阅读位置，支持关键字搜索与对话内高亮定位。
+**DeepSeek Harness（DSH）对话大纲插件**：把 AI 回复中的 Markdown 标题（H1–H6）提取成可导航的大纲面板，按对话回合分组、覆盖整段会话（含尚未加载进窗口的回合），支持标题/全文搜索、悬停预览与阅读位置自动跟随。
 
 ## 功能
 
 - **按回合分组** —— 每条用户消息 + 其后续 AI 回复为一组，组头显示回合时间与首行预览，点击跳到该回合模型回答的开头
-- **搜索** —— 标题栏放大镜打开搜索框：标题 / 全文两种范围，结果列表点击任一条定位并高亮，`n/N` 回车逐处跳，Esc 关闭
+- **覆盖整段会话** —— 未加载进对话窗口的回合也在列表里（带「未加载」标记与预览）；点击即加载该回合并跳过去
+- **失败回合的报错** —— 请求超时 / 上游报错这类没有回复的回合显示 `请求失败` 与报错原文，点击跳到对话中的报错位置
+- **回合时间带日期** —— 昨天 `昨天 15:04`、前天 `前天 15:04`、更早 `25-09-11 15:04`，跨天的会话里时间不再重影
+- **标题行副标题** —— 每行标题下方显示该节正文的第一句，同名标题一眼可辨
+- **悬停预览** —— 悬停标题行显示该节开头、回合时间与层级路径
+- **搜索** —— 标题 / 全文两种范围，结果列表点击定位并高亮，`n/N` 回车逐处跳，Esc 关闭
+- **搜索容错** —— 大小写、全角半角、连续空白自动视为同一匹配；「模糊」开关可放宽到关键字中间夹字
 - **对话内高亮** —— 命中的关键字在对话中高亮，当前命中单独标亮
 - **组头吸顶** —— 滚动大纲时，当前回合的组头固定在面板顶部
 - **层级筛选** —— 标题栏的圆形层级按钮弹出 H1–H6 开关，任意组合显示
-- **自动跟随** —— 滚动对话时正在阅读的回合在大纲中自动点亮，其余变暗；大纲自动加载并跟随
+- **自动跟随** —— 滚动对话时正在阅读的回合自动点亮（封闭蓝框），大纲自动跟随
 - **跳转** —— 点击标题跳到对话中该标题的位置；面板与对话双向定位
+- **回到底部** —— 往上翻远之后，列表右下角的浮动按钮一步回到最新一条（不在底部时出现、到底后消失）
 - **可停靠、可缩放** —— 拖顶部横条移动，◀ / ▶ 切换左右停靠，拖边缘调宽高，收起后成为边缘把手；位置与尺寸会被记住
-- **分页** —— 默认显示最近的若干组，向上滚动加载更早的回合
+- **分页** —— 默认显示最近的若干组，向上滚动既展开索引也加载更早的对话
+- **边界提示** —— 滚到最早或最新再继续滚动时，面板底部短暂提示
 - **Markdown 感知** —— 标题中的行内标记会被剥离；围栏代码块里的 `#` 行不算标题
 - **主题适配** —— 深色 / 浅色主题自适应；仅对话视图显示，切到其他视图渐隐
 - 对话中没有标题也没有可识别时间时面板自动隐藏
@@ -23,12 +31,14 @@
 
 | 插件版本 | 支持的 DSH 版本 |
 | --- | --- |
-| **0.4.1**（最新） | 0.1.5-rc.1、0.1.5-rc.2 |
+| **0.5.1**（最新） | 0.1.5-rc.1、0.1.5-rc.2 |
+| 0.5.0 | 0.1.5-rc.1、0.1.5-rc.2 |
+| 0.4.1 | 0.1.5-rc.1、0.1.5-rc.2 |
 | 0.4.0 | 0.1.5-rc.1、0.1.5-rc.2 |
 | 0.3.3 | 0.1.5-rc.1 |
 | 0.3.0 – 0.3.2 | ≥ 0.1.2-rc.1 |
 
-`engines.dsh` 下限为 **0.1.5-rc.1**（`>=`，该版本起插件改用会话级槽位注入的宿主接口）；0.4.0 起在 **0.1.5-rc.1 与 0.1.5-rc.2** 上验证过并声明兼容，更早或更新的 DSH 版本未经验证，不作声明。在更早的 DSH 上，可安装的最新插件版本是 **0.3.2**。安装或更新时，DSH 市场会依据 `package.json` 中的 `engines.dsh`、`dsh.compatibility.dshReleases` 与 `peerDependencies` 做宿主兼容预检。
+`engines.dsh` 下限为 **0.1.5-rc.1**（`>=`，该版本起插件改用会话级槽位注入的宿主接口）。0.5.1 在 **0.1.5-rc.2** 上实测通过；它依赖的宿主接口——`turnOutline` 投影、会话级槽位的 `useProjection`、客户端 `sessions` 服务与 `loadThrough` 跳转加载器（0.5.0 起）、以及失败回合所用的 `turn-error` 节点（0.5.1 起）——已在 **0.1.5-rc.1** 的安装包中逐个核对存在，因此两版都声明兼容。更早或更新的 DSH 版本未经验证，不作声明；在更早的 DSH 上可安装的最新插件版本是 **0.3.2**。安装或更新时，DSH 市场会依据 `package.json` 中的 `engines.dsh`、`dsh.compatibility.dshReleases` 与 `peerDependencies` 做宿主兼容预检。
 
 ## 安装
 
@@ -54,12 +64,25 @@ dsh plugin --profile web add <插件目录路径>
 
 ## 使用
 
-- **跳转**：点击大纲标题或组头跳到对应位置
+- **跳转**：点击大纲标题或组头跳到对应位置；带「未加载」标记的条目会先把该回合加载进来再跳；失败回合点报错行跳到对话中的报错位置
 - **搜索**：放大镜打开搜索框，输入后点结果定位并高亮，回车逐处跳，Esc 关闭
+- **搜索容错**：全角/半角、大小写、空格差异会自动匹配；需要更宽松时点搜索框右侧的「模糊」开关
 - **层级筛选**：点标题栏的圆形层级按钮弹出 H1–H6 开关，选择显示的层级
 - **移动与停靠**：拖顶部横条移动，◀ / ▶ 切换左右停靠
 - **调整大小**：拖右边缘、下边缘或右下角
-- **加载更早**：在大纲中向上滚动
+- **加载更早**：在大纲中向上滚动（既展开索引，也加载更早的对话）
+- **回到底部**：翻远了之后点列表右下角的浮动按钮回到最新一条
+- **阅读位置**：滚动对话，正在阅读的回合会以蓝框标出；大纲会自动跟随
+
+## 诊断
+
+面板挂载时默认**不打印**任何日志。需要排查宿主能力时，在浏览器控制台执行一次：
+
+```
+localStorage.setItem("dsh-quick-toc.debug", "1")
+```
+
+再刷新页面，控制台会出现一行 `[dsh-quick-toc] panel mounted · turnOutline=… · jumpLoader=…`：`turnOutline` 缺失说明宿主没有该投影，`jumpLoader` 的分阶段措辞（`no-sessions-service` / `no-binding-api` / `no-binding-for-session` / `no-loadThrough` / `binding-threw`）可直接定位跳转桥断在哪一环。用完执行 `localStorage.removeItem("dsh-quick-toc.debug")` 关掉。
 
 ## 开发
 
@@ -67,7 +90,9 @@ dsh plugin --profile web add <插件目录路径>
 - `lib/index.js` —— 宿主端入口（空实现；本插件只提供浏览器端 UI）
 - `cordis.patch.yml` —— loader patch（符合官方 bundle 规范）
 - 面板注册进会话级 `conversation.input.overlay` 槽以取得会话级 hook（`useChat`、`useSession`、`sessionId` 等），面板本体通过 `createPortal` 渲染到 `document.body` 成为固定浮层；对话数据来自 `props.useChat`（`ChatSnapshot.order` 与 `nodes`，节点形状：`kind: user/assistant-step`、`location.turn`、`data.blocks`）
-- 修改 `lib/client.js` 后需重启 DSH 生效
+- 「未加载回合」能力依赖宿主的两样东西：`turnOutline` 投影（整段会话的回合索引，每条含 `turn/start` 的 seq）与会话跳转加载器（客户端 `sessions` 服务的 `binding(sessionId).session.loadThrough(seq)`，通过客户端 ctx 的 `ctx.get("sessions")` 免声明查找取得）。两者各自独立降级：没有投影时只列已加载回合，没有加载器时未加载条目只展示、不跳转，面板其余功能不受影响。
+- 失败回合的报错行读的是宿主的 `turn-error` 会话节点（宿主在 `turn/end` 的原因为 `error` 时发布，含 `message` 与可选的 `code`）；宿主不提供该节点时只是不显示这一行，其余功能不受影响。
+- 修改 `lib/client.js` 后刷新页面即可看到变化（客户端模块按内容哈希发版，DSH 的客户端 HMR 也会推送重载）；若未生效再重启 DSH
 
 ## License