dsh-quick-toc 0.3.2 → 0.4.0

package/CHANGELOG.en.md

@@ -0,0 +1,104 @@
+# Changelog
+
+All notable changes to **dsh-quick-toc** are documented here. Chinese version: [CHANGELOG.md](CHANGELOG.md).
+
+## [0.4.0] - 2026-09-11
+
+### Added
+- **Sticky group headers**: while scrolling the outline, the header of the turn you are inside stays pinned to the top of the panel, flush against the toolbar above it.
+- **Collapsible level-filter row**: the **层级 (levels)** button at the left of the magnifier hides/shows the `1`–`6` row (the choice is remembered; the filter keeps applying while it is hidden).
+- **Position breadcrumb**: the top of the panel shows the path of the section you are reading; click it to jump there. The rule is "the deepest heading above the viewport's middle line" — the section that fills most of the screen — and since a jump also lands above that line, the breadcrumb still shows the same heading after you click it.
+- **Heading level filter**: the `1`–`6` chips at the top of the panel are independent switches, so any combination works (e.g. H1 and H3 with H2 hidden) and the choice is remembered; switching off the last remaining level restores all six.
+- **Search result list**: while a query is present the outline becomes a result list — one row per match, showing the matched heading or message with the keyword highlighted, its heading path, the turn time and a repeat count (plus a context snippet in full-text scope). Rows are chronological with the **newest hit at the bottom**, a fresh search starts at the newest hit and you scroll up to reach earlier ones; **clicking a row** makes that hit current, i.e. the same path as Enter stepping — it highlights the keyword in the conversation and scrolls there. `n/N` Enter-stepping is kept.
+
+### Changed
+- **Compatibility**: verified against and declared for DSH **0.1.5-rc.1 and 0.1.5-rc.2** (`engines.dsh` keeps its floor of `>=0.1.5-rc.1`). The host interface is identical in both — the session-scoped slot `conversation.input.overlay`, the `useChat` hook from `dsh-client-ui-chat` and the client-module seed table were all checked against the installed bundles.
+- **Performance**: heading parsing and text extraction are now cached per node, so a streaming update only re-processes the node that changed instead of the whole history; the cache drops nodes that left the conversation, keeping it bounded.
+- `countOccurrences` now guards an empty needle (an empty query made `indexOf` spin in place — an infinite loop; every current call site is guarded, so this is hardening).
+
+### Fixed
+- The outline did not jump to the newest turn when content first appeared: that effect's dependency array was written above the `groups` declaration, so it always evaluated to `0` during render and the effect only ever ran on mount. The effect now sits below `groups` and depends on `groups.length`.
+- Result rows always reported a repeat count of 1 (the `×N` badge never appeared), which also made the "row holding the current match" highlight land on the next row when one heading matched twice. Each row now records its real occurrence count.
+- Dragging the top bar to move the panel persisted the position from **before** the drag (the closure kept the value captured at pointer-down), so the panel jumped back to its old spot after a reload. It now stores the position the drag ended at.
+- In full-text scope, clicking a row whose hit was in a message body only scrolled and never highlighted anything (the click used the jump-only path while highlighting only happened while Enter-stepping). Clicking a result row now shares the stepping path: highlight that hit, scroll to it, and update both `n/N` and the highlighted row.
+- When the same keyword occurred more than once inside one text node, the in-chat highlight wrapped only the FIRST occurrence there, so the later one was neither tinted nor eligible to be marked as the current hit — stepping to it found no current mark and degraded to a plain scroll with no distinct highlight. Every occurrence inside each text node is now wrapped in order, so the in-conversation hit order lines up with `n/N`.
+- Breadcrumb and jump were inconsistent: detection used "the last heading above the viewport top" while a jump puts the heading 20 px below the top, so clicking the breadcrumb switched it to the previous heading. Both now use the viewport's **middle line**, which both reflects the section filling most of the screen and stays consistent with every jump target.
+- The level filter used to be a "show up to level N" prefix that could not skip an intermediate level; it is now a per-level switch.
+- The turn header (the time row) jumped to the turn's **user message**; it now jumps to the **start of that turn's model reply**, and turns without any headings — which have only this row in the panel — are clickable too.
+- `# comment` / `## example` lines inside a ``` fenced code block were treated as headings and leaked into the outline: they have no element to jump to, and they shifted the index of the real headings after them so those jumped to the wrong place. Heading parsing now skips fenced blocks (``` and ~~~, info strings, longer closing fences, up to 3 spaces of indentation).
+- There was a gap between the pinned group header and the toolbar above it: the scroll container's 6 px top padding is a wall a sticky row cannot pass. The top padding is gone, so the header butts against the toolbar; spacing between groups comes from the divider.
+
+## [0.3.3] - 2026-09-10
+
+### Added
+- The panel and its collapsed edge handle fade out while the center column shows another view (trajectory, context, plugin views) and fade back in on the chat view. The check polls lightly (120 ms) and falls back to visible whenever the active view cannot be determined.
+
+### Changed
+- Compatibility is declared for DSH `0.1.5-rc.1` only (`engines.dsh`, `dsh.compatibility.dshReleases` and `peerDependencies`), which is the version this plugin is verified against.
+- READMEs updated: the feature list and the usage section now cover search, search-scope switching, in-chat highlighting and turn jumping, and the compatibility table lists the supported DSH version of the last two releases.
+- GitHub release bodies now default to the Chinese CHANGELOG section with the English section folded below it, and the changelog is split into `CHANGELOG.md` (Chinese, default) and `CHANGELOG.en.md` (English).
+
+## [0.3.2] - 2026-09-08
+
+### Changed
+- Documentation pass: the compatibility matrix and feature list in the READMEs are refreshed, and the npm package description now mentions keyword search and in-chat highlighting.
+
+## [0.3.1] - 2026-09-08
+
+### Fixed
+- Panel and collapsed edge handle no longer float above DSH modals: the base z-index is now 500 (above app popovers at z 100 and the transcript width handles at z 8, but below DSH's modal layer at z 1000), so opening Settings covers the outline instead of the outline sitting on top of it.
+- Circular controls are true circles again on DSH 0.1.5-rc.1: the theme applies `corner-shape: superellipse(1.5)` to every element, which turned `border-radius: 50%` into a squircle. The icon buttons, search-scope toggle, top drag bar and edge handle now declare `corner-shape: round`.
+
+### Changed
+- Compatibility declaration also lists DSH `0.1.5-rc.1` (verified compatible; `engines.dsh` stays `>=0.1.2-rc.1`).
+
+## [0.3.0] - 2026-08-24
+
+### Fixed
+- Compatibility with the then-current DSH 0.1.2-rc.1: the removed `@deepseek-ai/dsh-client-runtime` package no longer breaks plugin loading (externals drift). Runtime hooks now arrive as session-scope slot props.
+- Conversation data access moved from `useSession(s => s.chat.*)` to the session-scope `useChat` hook (`ChatSnapshot.order` + `nodes` map, contributed by `dsh-client-ui-chat`). Node shape unchanged (`kind: user/assistant-step`, `location.turn`, `data.blocks`), so grouping / search / highlight / jump logic is untouched.
+- Panel mount moved into the session-scoped `conversation.input.overlay` slot. In that DSH version session-scoped hooks only reach a declared *session* slot; a frame-floating `shell.overlay` occupant's `SessionProvider` binds to the root binding (no session id) and rendered the panel slot empty. The panel still draws its own fixed, frame-floating dock (position: fixed), so the overlay seat is only the hook source.
+
+### Changed
+- `dsh.client.inject` now lists `dsh-client-ui-chat` / `dsh-client-ui-conversation` / `dsh-client-ui-layout` instead of the removed runtime package.
+- Dropped the unused `sessions` service from the client inject list.
+
+### Added
+- Version guard: `dsh.compatibility.dshReleases` declares `0.1.2-rc.1: compatible` and `engines.dsh: ">=0.1.2-rc.1"` (dshmarket install-time host-compat preflight); peerDependencies pin `dsh-client-ui-chat` / `dsh-client-ui-conversation` `>=0.1.2-rc.1`. The panel degrades gracefully with a console warning when the `chat` hook is unavailable (older hosts).
+
+## [0.2.2] - 2026-08-24
+
+### Added
+- Keyword search: header magnifier button opens a search box; Enter cycles through matches (n/N counter); Escape or the magnifier toggles it closed
+- Search scope toggle: 标题 (heading titles only) or 全文 (also user messages and AI reply texts)
+- In-chat match highlighting: matched keywords are highlighted in the conversation; the current match gets a distinct highlight and is scrolled to the upper-middle of the viewport
+- Every occurrence counts toward n/N (multiple hits in one message = multiple matches)
+- Heading-less turns get a standalone time entry; all group headers show the turn's first-line preview next to the time (click to jump)
+
+### Changed
+- Panel collapse animation unified for both docks: clip-path hides the panel at the sidebar/screen edge (shadow removed to avoid clipping artifacts)
+- Inactive outline groups dimmed to 0.6 opacity
+
+## [0.1.1] - 2026-08-17
+
+### Changed
+- Release workflow also uploads a stable-named tarball (`dsh-quick-toc.tgz`) so `/releases/latest/download/` always resolves to the newest release
+
+## [0.1.0] - 2026-08-17
+
+### Added
+- Turn-grouped outline: each user message + its AI replies form one group, with the group's end time as the header
+- Auto-follow highlight: turns visible in the conversation viewport light up in the outline (multiple at once); the outline auto-loads and scrolls to keep them visible
+- Smooth jump: clicking a heading glides to the exact heading position in the conversation (with a small top offset)
+- Dock left/right with a draggable top bar, resizable from the edges/corner, collapsible into an edge handle (click it to expand)
+- Scrollbar follows the dock side (left when docked left, right when docked right)
+- Paged rendering: latest groups first; scrolling the outline to the top loads older groups
+- Auto "load older": when the outline reaches the top with everything loaded, it clicks the conversation's own load-more button
+- Header time jump: clicking a group's time label jumps to that turn's start
+- Markdown-aware titles: `**bold**`, `*italic*`, `` `code` ``, `[links](url)`, `~~strike~~` stripped from heading text
+- Persisted panel state (dock side, position, size) with automatic migration from older key names
+- Auto-hides when the conversation has no headings; light/dark theme support
+
+### Published
+- npm: `dsh-quick-toc@0.1.0`
+- GitHub: `LyaxZ/dsh-quick-toc` with auto-release workflow (tag push -> npm pack -> release asset)

package/CHANGELOG.md

@@ -1,68 +1,104 @@
-# Changelog
-
-All notable changes to **dsh-quick-toc** are documented here.
+# 更新日志
+
+**dsh-quick-toc** 的重要变更都记录在这里。英文版见 [CHANGELOG.en.md](CHANGELOG.en.md)。
+
+## [0.4.0] - 2026-09-11
+
+### 新增
+- **组头吸顶**：滚动大纲时，当前所在回合的组头固定在面板顶部，并与上方工具条紧贴
+- **层级筛选行可收起**：标题栏放大镜左边的 **层级** 按钮收起/展开 `1`–`6` 那一行（选择会记住；收起后筛选设置仍然生效）
+- **位置面包屑**：面板顶部显示你正在读的章节路径，点击可跳到该标题。判定规则是"视口中线之上最深的标题"（画面里占得最多的那一节）；跳转落点也在中线之上，所以点完后面包屑显示的仍是同一个标题
+- **标题层级筛选**：面板顶部 `1`–`6` 芯片是各自独立的开关，可任意组合（例如只留 H1 与 H3、关掉中间的 H2），选择会记住；把最后一个亮着的层级也关掉时自动恢复显示全部六级
+- **搜索结果列表**：有搜索词时大纲切换为结果列表，逐条列出命中（标题关键字高亮、层级路径、回合时间、重复次数，全文模式附上下文片段）。列表按时间排列、**最新的命中在底部**，开始搜索时自动定位到最新命中，向上滚回看更早的命中；点击任一行会把该命中设为当前命中——和回车逐处跳同一条路径，会在对话里高亮并滚过去；`n/N` 回车逐处跳保留
+
+### 变更
+- **兼容性**：在 DSH **0.1.5-rc.1 与 0.1.5-rc.2** 上验证并声明兼容（`engines.dsh` 下限仍为 `>=0.1.5-rc.1`）。两版的宿主接口一致——会话级槽位 `conversation.input.overlay`、`dsh-client-ui-chat` 的 `useChat` hook 与客户端模块 seed 表都经实测核对相同。
+- **性能**：标题解析与文本提取改为按节点缓存——流式更新只重算真正变化的节点，不再每次重算整段历史；缓存会清理已离开会话的节点，保持有界
+- `countOccurrences` 增加空查询守卫（空查询会让 `indexOf` 原地打转导致死循环；现有调用点都有守卫，此举为加固）
+
+### 修复
+- 大纲首次载入内容时没有自动定位到最新回合：该副作用的依赖数组写在 `groups` 声明之前，渲染时读到的永远是 `0`，导致副作用只在挂载时执行一次。已把副作用移到 `groups` 之后并直接依赖 `groups.length`。
+- 搜索结果行的重复次数恒为 1（`×N` 从不显示），并连带使"当前命中所属行"在重复命中时定位到下一行。现在每行记录真实的出现次数。
+- 拖动顶部横条调整面板垂直位置后，记录的仍是**拖动前**的位置（写入的是拖动开始时闭包里的旧值），刷新后面板跳回原位。现在写入拖动结束时的实际位置。
+- 全文搜索时，正文命中行点击后只滚动、不高亮（点击走的是"仅跳转"路径，而高亮只在回车逐处跳里做）。现在点击结果行与回车逐处跳共用同一条路径：先高亮该处，再滚过去，同时更新 `n/N` 与当前行高亮。
+- 同一段文本里同一关键字出现多次时，对话内高亮只包住**该文本节点里的第一处**：第二处既不染色，也无法被标成"当前命中"，于是跳到第二处时找不到当前标记，退化成"只滚动、没有高亮"。现在每个文本节点内的所有出现都会依次包住，对话内命中序号与 `n/N` 完全对齐。
+- 面包屑与跳转错位：判定用"视口顶部之上最后一个标题"，而跳转把标题放在"顶部 +20px"，于是点完面包屑就会换成上一个标题。现在统一以**视口中线**为基准（既反映画面里占得最多的那一节，又与所有跳转落点自洽）。
+- 层级筛选原本是"显示到第 N 级"的前缀语义，无法跳过中间层级；现在改为逐级开关。
+- 回合组头（时间那一行）原本跳到该回合的**用户消息**位置；现在跳到**该回合模型回答的开头**，并且没有标题的回合（面板里只剩时间行）也能点。
+- ``` 围栏代码块里的 `# 注释` / `## 示例` 会被当成标题混进大纲（既没有可跳转的目标，又会让它后面那些真标题的序号错位、跳到错误位置）。现在解析标题时会跳过围栏代码块（支持 ``` 与 ~~~、带 info string 的开栏、更长的闭栏、最多 3 空格缩进）。
+- 吸顶的组头上边缘与上方工具条之间有一道空隙：滚动容器的上内边距（6px）把粘性行"顶"不下去。现在去掉该上内边距，组头紧贴工具条，组与组之间的间距由分隔线提供。
+
+## [0.3.3] - 2026-09-10
+
+### 新增
+- 中间列切到其他视图（轨迹、上下文、插件视图）时，大纲面板与收起后的边缘把手会渐隐，切回对话视图时渐显。检测为轻量轮询（120ms）；无法判断当前视图时按"可见"处理。
+
+### 变更
+- 兼容性只声明 DSH `0.1.5-rc.1`（`engines.dsh`、`dsh.compatibility.dshReleases` 与 `peerDependencies`），即本插件验证过的版本。
+- README 更新：功能列表与「使用」章节补齐搜索、搜索范围切换、对话内高亮与回合跳转；兼容表列出最近两个版本各自支持的 DSH 版本。
+- GitHub Release 的描述默认取中文 CHANGELOG 段落，英文段落折叠在其下方可展开；CHANGELOG 拆分为 `CHANGELOG.md`（中文，默认）与 `CHANGELOG.en.md`（英文）。
 
 ## [0.3.2] - 2026-09-08
 
-### Changed
-- Documentation pass: the compatibility matrix and feature list in the READMEs are refreshed, and the npm package description now mentions keyword search and in-chat highlighting.
+### 变更
+- 文档整理：README 的兼容表与功能列表更新，npm 包描述补充了关键字搜索与对话内高亮。
 
 ## [0.3.1] - 2026-09-08
 
-### Fixed
-- Panel and collapsed edge handle no longer float above DSH modals: the base z-index is now 500 (above app popovers at z 100 and the transcript width handles at z 8, but below DSH's modal layer at z 1000), so opening Settings covers the outline instead of the outline sitting on top of it.
-- Circular controls are true circles again on DSH 0.1.5-rc.1: the theme applies `corner-shape: superellipse(1.5)` to every element, which turned `border-radius: 50%` into a squircle. The icon buttons, search-scope toggle, top drag bar and edge handle now declare `corner-shape: round`.
+### 修复
+- 面板与收起把手不再浮在 DSH 弹层之上：基础 z-index 改为 500（高于应用弹出层 z100 与对话宽度手柄 z8，低于 DSH 弹层 z1000），打开设置时设置面板会盖住大纲。
+- 圆形控件在 DSH 0.1.5-rc.1 上恢复为正圆：主题对所有元素应用了 `corner-shape: superellipse(1.5)`，会把 `border-radius: 50%` 变成方圆角；图标按钮、搜索范围切换、顶部拖条与边缘把手现声明 `corner-shape: round`。
 
-### Changed
-- Compatibility declaration also lists DSH `0.1.5-rc.1` (verified compatible; `engines.dsh` stays `>=0.1.2-rc.1`).
+### 变更
+- 兼容声明加入 DSH `0.1.5-rc.1`（当时 `engines.dsh` 仍为 `>=0.1.2-rc.1`）。
 
 ## [0.3.0] - 2026-08-24
 
-### Fixed
-- **DSH 0.1.2-rc.1 compatibility**: the removed `@deepseek-ai/dsh-client-runtime` package no longer breaks plugin loading (externals drift). Runtime hooks now arrive as session-scope slot props.
-- Conversation data access moved from `useSession(s => s.chat.*)` to the session-scope `useChat` hook (`ChatSnapshot.order` + `nodes` map, contributed by `dsh-client-ui-chat`). Node shape unchanged (`kind: user/assistant-step`, `location.turn`, `data.blocks`), so grouping / search / highlight / jump logic is untouched.
-- Panel mount moved into the session-scoped `conversation.input.overlay` slot. In 0.1.2-rc.1 session-scoped hooks only reach a declared *session* slot; a frame-floating `shell.overlay` occupant's `SessionProvider` binds to the root binding (no session id) and rendered the panel slot empty. The panel still draws its own fixed, frame-floating dock (position: fixed), so the overlay seat is only the hook source.
+### 修复
+- 适配当时的目标版本 DSH 0.1.2-rc.1：已被移除的 `@deepseek-ai/dsh-client-runtime` 不再导致插件加载失败（externals drift），运行时 hook 改为由会话作用域槽位的 props 注入。
+- 对话数据访问由 `useSession(s => s.chat.*)` 改为会话作用域的 `useChat`（`ChatSnapshot.order` + `nodes`，由 `dsh-client-ui-chat` 贡献）；节点形状未变（`kind: user/assistant-step`、`location.turn`、`data.blocks`），因此分组、搜索、高亮与跳转逻辑未受影响。
+- 面板挂载改到会话作用域的 `conversation.input.overlay` 槽：该版本中会话级 hook 只到达已声明的会话槽，而 root 作用域 `shell.overlay` 里的 `SessionProvider` 绑定的是无 sessionId 的 root binding，导致子槽始终空渲染。面板本体仍以 `position: fixed` 自绘浮层，挂载槽只作为 hook 来源。
 
-### Changed
-- `dsh.client.inject` now lists `dsh-client-ui-chat` / `dsh-client-ui-conversation` / `dsh-client-ui-layout` instead of the removed runtime package.
-- Dropped the unused `sessions` service from the client inject list.
+### 变更
+- `dsh.client.inject` 改为列出 `dsh-client-ui-chat` / `dsh-client-ui-conversation` / `dsh-client-ui-layout`，替代已移除的运行时包。
+- 从客户端 inject 列表中移除未使用的 `sessions` 服务。
 
-### Added
-- Version guard: `dsh.compatibility.dshReleases` declares `0.1.2-rc.1: compatible` and `engines.dsh: ">=0.1.2-rc.1"` (dshmarket install-time host-compat preflight); peerDependencies pin `dsh-client-ui-chat` / `dsh-client-ui-conversation` `>=0.1.2-rc.1`. The panel degrades gracefully with a console warning when the `chat` hook is unavailable (older hosts).
+### 新增
+- 版本守卫：`dsh.compatibility.dshReleases` 与 `engines.dsh` 声明（供 dshmarket 安装时做宿主兼容预检），并以 peerDependencies 约束相关 DSH 包版本；`chat` hook 不可用时，面板以控制台警告优雅降级。
 
 ## [0.2.2] - 2026-08-24
 
-### Added
-- Keyword search: header magnifier button opens a search box; Enter cycles through matches (n/N counter); Escape or the magnifier toggles it closed
-- Search scope toggle: 标题 (heading titles only) or 全文 (also user messages and AI reply texts)
-- In-chat match highlighting: matched keywords are highlighted in the conversation; the current match gets a distinct highlight and is scrolled to the upper-middle of the viewport
-- Every occurrence counts toward n/N (multiple hits in one message = multiple matches)
-- Heading-less turns get a standalone time entry; all group headers show the turn's first-line preview next to the time (click to jump)
+### 新增
+- 关键字搜索：标题栏放大镜打开搜索框，回车逐处跳转（`n/N` 计数），Esc 或再次点击放大镜关闭
+- 搜索范围切换：仅标题，或同时搜索用户消息与 AI 回复正文
+- 对话内高亮：命中的关键字在对话中高亮，当前命中单独标亮并滚动到视口中上部
+- 同一条消息内的多次命中都计入 `n/N`
+- 无标题的回合也有独立的时间条目；所有组头在时间旁显示该回合首行预览（点击跳转）
 
-### Changed
-- Panel collapse animation unified for both docks: clip-path hides the panel at the sidebar/screen edge (shadow removed to avoid clipping artifacts)
-- Inactive outline groups dimmed to 0.6 opacity
+### 变更
+- 两种停靠的面板收起动画统一：由 clip-path 在侧栏/屏幕边缘裁切（移除阴影，避免裁切残影）
+- 非激活的大纲组降到 0.6 不透明度
 
 ## [0.1.1] - 2026-08-17
 
-### Changed
-- Release workflow also uploads a stable-named tarball (`dsh-quick-toc.tgz`) so `/releases/latest/download/` always resolves to the newest release
+### 变更
+- 发布流程额外上传稳定命名的 tarball（`dsh-quick-toc.tgz`），使 `/releases/latest/download/` 始终解析到最新版本
 
 ## [0.1.0] - 2026-08-17
 
-### Added
-- Turn-grouped outline: each user message + its AI replies form one group, with the group's end time as the header
-- Auto-follow highlight: turns visible in the conversation viewport light up in the outline (multiple at once); the outline auto-loads and scrolls to keep them visible
-- Smooth jump: clicking a heading glides to the exact heading position in the conversation (with a small top offset)
-- Dock left/right with a draggable top bar, resizable from the edges/corner, collapsible into a draggable edge handle
-- Scrollbar follows the dock side (left when docked left, right when docked right)
-- Paged rendering: latest groups first; scrolling the outline to the top loads older groups
-- Auto "load older": when the outline reaches the top with everything loaded, it clicks the conversation's own load-more button
-- Header time jump: clicking a group's time label jumps to that turn's start
-- Markdown-aware titles: `**bold**`, `*italic*`, `` `code` ``, `[links](url)`, `~~strike~~` stripped from heading text
-- Persisted panel state (dock side, position, size) with automatic migration from older key names
-- Auto-hides when the conversation has no headings; light/dark theme support
-
-### Published
-- npm: `dsh-quick-toc@0.1.0`
-- GitHub: `LyaxZ/dsh-quick-toc` with auto-release workflow (tag push -> npm pack -> release asset)
+### 新增
+- 按回合分组的大纲：每条用户消息与其后续 AI 回复为一组，组头显示该组的结束时间
+- 自动跟随高亮：对话视口内可见的回合在大纲中点亮（可同时多组）；大纲自动加载并滚动，使其保持可见
+- 平滑跳转：点击标题平滑滚动到对话中该标题的位置（带少量顶部偏移）
+- 左右停靠（拖顶部横条移动）、从边缘/角部调整大小、收起为边缘把手（点击展开）
+- 滚动条随停靠方向（停靠左侧时在左，停靠右侧时在右）
+- 分页渲染：默认显示最新的若干组；在大纲中滚到顶部加载更早的组
+- 自动「加载更早」：大纲到达顶部且已全部加载时，会点击对话自身的「加载更多」按钮
+- 组头时间跳转：点击组的时间标签跳到该回合开头
+- Markdown 感知标题：剥离 `**加粗**`、`*斜体*`、`` `代码` ``、`[链接](url)`、`~~删除线~~`
+- 面板状态持久化（停靠边、位置、尺寸），并从旧键名自动迁移
+- 对话无标题时自动隐藏；支持亮/暗主题
+
+### 发布
+- npm：`dsh-quick-toc@0.1.0`
+- GitHub：`LyaxZ/dsh-quick-toc`，带自动发布流程（推送标签 → npm pack → release 资产）

package/README.en.md

@@ -2,66 +2,75 @@
 
 > **English** | [中文](README.md)
 
-A quick conversation TOC plugin for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH): extracts Markdown headings (H1–H6) from 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, with auto-follow highlighting, keyword search and in-chat match highlighting.
 
 ## Features
 
-- **Turn-grouped outline** — each user message + its AI replies form one group, with the group's end time as the header (plus the turn's first-line preview; click it to jump to the turn start)
-- **Keyword search** — a magnifier in the header opens the search box; Enter cycles matches (n/N counter), Esc closes; toggle between **title / full-text** scope
-- **In-chat highlighting** — matched keywords are highlighted in the conversation; the current match gets a distinct highlight and is scrolled to the upper-middle of the viewport; every occurrence counts toward n/N
-- **Auto-follow highlight** — as you scroll the conversation, the turns visible in the viewport light up in the outline (multiple at once); the outline auto-loads and scrolls to keep them visible
-- **Smooth jump** — click a heading to glide to the exact heading position in the conversation
-- **Dockable & resizable** — dock left or right (drag the top bar), resize from the edges/corner, collapse to a draggable edge handle; panel size/position remembered
-- **Paged rendering** — shows the latest groups first; scrolling to the top of the outline loads older ones
-- **Markdown-aware titles** — inline `**bold**`, *italic*, `` `code` ``, `[links](url)`, `~~strike~~` are stripped from heading text
-- Auto-hides when the conversation has no headings; works in light/dark themes; the inner-shadow card look adapts to the theme (white bevel in dark)
+- **Turn-grouped outline** — each user message plus its following AI replies form one group; the group header shows the turn's end time and a first-line preview, and clicking it jumps to the **start of that turn's model reply** (a turn with no headings has only this row and is still clickable)
+- **Keyword search** — the magnifier in the panel header opens a search box; press **Enter** to jump to the next match (wrapping), **Esc** to close, with an `n/N` match counter
+- **Search result list** — once a query is present the outline becomes a result list: each row is a matched heading or message (keyword highlighted) showing its heading path, the turn time and a repeat count, plus a context snippet in full-text scope. Rows run in chronological order (**newest hit at the bottom**) and a fresh search starts at the newest hit — scroll up to walk back through earlier ones; **clicking a row** makes that hit the current one, i.e. exactly what Enter stepping does: it highlights the keyword in the conversation and scrolls there
+- **Search scope toggle** — the **title / full-text** button in the search box switches between searching heading titles only and also searching user messages plus AI reply text
+- **In-chat highlighting** — matched keywords are highlighted in the conversation; the current match is highlighted distinctly and scrolled into the upper part of the viewport; every occurrence inside a message counts toward `n/N`
+- **Sticky group headers** — while scrolling the outline, the header of the turn you are inside stays pinned to the top of the panel, flush against the toolbar above it
+- **Position breadcrumb** — the top of the panel shows the path of the section you are reading (e.g. `Deploy › Docker`). The rule is "the deepest heading above the viewport's middle line", i.e. the section that fills most of the screen; clicking it keeps showing that same heading afterwards, because a jump also lands above the middle line. When you do not want that row, the **位置 (position)** button just left of the magnifier collapses it (the choice is remembered)
+- **Heading level filter** — the `1`–`6` chips in the panel header are **independent switches**, so any combination is possible (e.g. H1 and H3 with H2 hidden); the choice is remembered. Switching off the last remaining level restores all six, so the panel is never empty. That row itself can be collapsed: the **层级 (levels)** button at the left of the magnifier hides/shows it (the choice is remembered), and the filter keeps applying while it is hidden
+- **Code blocks are not headings** — `# comment` / `## example` lines inside a ``` fenced code block never become outline entries (they used to leak into the outline and made the real headings after them jump to the wrong place)
+- **Auto-follow highlighting** — while scrolling the conversation, the turns visible in the viewport light up in the outline (several at once) and the rest dim; the outline loads and scrolls so the group being read stays visible
+- **Jumping** — click a heading to jump to its position in the conversation, or click a group header's time/preview to jump to the **start of that turn's model reply**
+- **Dockable and resizable** — drag the top bar to move the panel, use ◀ / ▶ to dock it left or right, drag an edge or corner to resize, and collapse it into an edge handle (click it to expand); the panel's position and size are remembered
+- **Paging and loading older** — the most recent groups show first; scrolling up inside the outline loads older groups
+- **Markdown-aware titles** — inline markup in headings (`**bold**`, `*italic*`, `` `code` ``, `[links](url)`, `~~strike~~`) is stripped before display
+- **Chat view only** — when the center column switches to another view (trajectory, context, …), the panel and its edge handle fade out
+- When the conversation has no headings at all, the outline lists clickable turn-time entries only; it hides itself when not even a time can be read. It adapts to the dark and light themes (the inner-shadow card follows the theme)
 
 ## Compatibility
 
-| Plugin | DSH |
+| Plugin | Supported DSH |
 | --- | --- |
-| **0.3.2** (latest) | **≥ 0.1.2-rc.1** (verified on 0.1.2-rc.1 / 0.1.5-rc.1) |
-| 0.3.0 – 0.3.1 | same |
-| 0.2.2 | DSH versions before 0.1.2-rc.1 (install as `dsh-quick-toc@legacy`) |
+| **0.4.0** (latest) | 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 |
 
-0.3.0 re-targeted the host integration (new slot architecture + `useChat` session data) and **only supports DSH 0.1.2-rc.1 and above**; for older DSH builds install 0.2.2. On install/update the DSH market pre-flights host compatibility from `dsh.compatibility.dshReleases` and `peerDependencies` in package.json and warns on a mismatch.
+`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.4.0 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`.
 
 ## Install
 
-With the DSH CLI (published on npm — name only):
+With the DSH CLI:
 
 ```
 dsh plugin --profile web add dsh-quick-toc
 ```
 
-or from GitHub:
+Or from GitHub:
 
 ```
 dsh plugin --profile web add github:LyaxZ/dsh-quick-toc
 ```
 
-or, for a local checkout:
+Or from a local folder:
 
 ```
-dsh plugin --profile web add <path-to-this-folder>
+dsh plugin --profile web add <path-to-the-plugin-folder>
 ```
 
-Restart DSH (double-click `restart-dsh.bat` on Windows) and open the Web UI. The outline is collapsed by default — click the small edge handle on the left side of the conversation to expand it.
+After installing, restart DSH and open the Web UI. The panel starts collapsed; click the edge handle next to the conversation to expand it.
 
 ## Usage
 
-- Click a heading in the outline to jump to that heading in the conversation
-- Drag the top bar to move the panel; use the **◀ / ▶** button to dock left/right
-- Drag the right edge (width), bottom edge (height) or the bottom-right corner (both) to resize
-- Scroll the outline to the top to load older groups
+- **Jumping**: click a heading in the outline to jump to its position; click a group header's time or first-line preview to jump to the **start of that turn's model reply**; click the breadcrumb at the top to jump to the heading you are inside
+- **Search**: click the magnifier in the header to open the search box; once you type a keyword the outline becomes a result list — click any row to locate and highlight that hit, or press Enter to step through the matches (`n/N` shows the current position and the total, and the row holding the current match is highlighted); press Esc or the magnifier again to close and return to the outline; use the **title / full-text** button to change the search scope
+- **Level filter**: the `1`–`6` chips are independent switches, so any combination works; the **层级 (levels)** button in the header collapses or expands that row
+- **Moving and docking**: drag the top bar to move the panel; use ◀ / ▶ to switch between left and right docking
+- **Resizing**: drag the right edge for width, the bottom edge for height, or the bottom-right corner for both
+- **Loading older turns**: scroll up inside the outline to load older groups; when the conversation itself offers a "load older messages" button, the outline also triggers it on reaching the top
 
 ## Development
 
 - `lib/client.js` — all UI logic (browser side)
-- `lib/index.js` — host-side no-op entry (extend with a version gate if needed)
+- `lib/index.js` — host-side entry (empty; this plugin ships browser-side UI only)
 - `cordis.patch.yml` — loader patch (official DSH bundle format)
-- **Since 0.3.0 the plugin targets the new plugin model**: the panel registers into the session-scoped `conversation.input.overlay` slot (session hooks are contributed via `ctx.uiSession.provide`, `useChat` by ui-chat), and the panel body `createPortal`s to `document.body` as a fixed floating dock; data comes from `props.useChat` (`ChatSnapshot.order` + `nodes`; node shape: `kind: user/assistant-step`, `location.turn`, `data.blocks`)
-- Client changes need a DSH restart (boot rev is content-based)
+- 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
 
 ## License
 

package/README.md

@@ -6,62 +6,71 @@
 
 ## 功能
 
-- **按回合分组** —— 每条用户消息 + 其后续 AI 回复为一组，组头显示该组最后一条消息的结束时间（附带该回合首行预览，点击可跳到回合开头）
-- **关键字搜索** —— 标题栏放大镜打开搜索框，回车逐个定位（n/N 计数），Esc 关闭；支持 **标题 / 全文** 范围切换
-- **对话内高亮** —— 命中关键字在对话中高亮，当前命中单独标亮并滚动到视口上方约 1/3 处；同一条消息内的多次命中都计入 n/N
-- **自动跟随高亮** —— 滚动对话框时，视口内可见的回合在大纲中自动点亮（多组可同时点亮）；大纲自动加载并滚动，保证正在读的组始终可见
-- **平滑跳转** —— 点击标题平滑滚动到对话中该标题的准确位置
-- **可停靠、可缩放** —— 左右停靠（拖顶部横条移动）、边缘/角部拖拽调整大小、收起成可拖动的边缘把手；大小与位置自动记忆
-- **分页渲染** —— 默认显示最近几组，大纲滚动到顶部自动加载更早的组
-- **Markdown 清理** —— 标题中的 `**加粗**`、*斜体*、`` `代码` ``、`[链接](url)`、`~~删除线~~` 等行内标记自动剥离
-- 对话无标题时自动隐藏；适配深色 / 浅色主题；内阴影卡片质感随主题切换（深色为白色高光）
+- **按回合分组** —— 每条用户消息 + 其后续 AI 回复为一组；组头显示该组最后一条消息的结束时间，并附带该回合首行预览，点击跳到**该回合模型回答的开头**（没有标题的回合只剩这一行，同样可点）
+- **关键字搜索** —— 标题栏放大镜打开搜索框；输入后按 **回车** 跳到下一处命中（循环），按 **Esc** 关闭；命中计数以 `n/N` 显示
+- **搜索结果列表** —— 输入关键字后，大纲切换为结果列表：每行是命中的标题或消息（关键字高亮），并显示层级路径、回合时间与重复次数（全文搜索时附上下文片段）。列表按时间顺序排（**最新的命中在底部**），开始搜索时自动定位到最新命中，向上滚即可回看更早的命中；**点击任一行**把该命中设为当前命中——与回车逐处跳走同一条路径，会在对话里高亮并滚动过去
+- **搜索范围切换** —— 搜索框内的 **标题 / 全文** 按钮切换范围：仅标题，或同时搜索用户消息与 AI 回复正文
+- **对话内高亮** —— 命中的关键字在对话中高亮，当前命中单独标亮并滚动到视口上部；同一条消息中的多次命中都会计入 `n/N`
+- **组头吸顶** —— 滚动大纲时，当前所在回合的组头固定在面板顶部（与上方工具条紧贴，中间不留空隙），始终知道自己在看哪一轮
+- **位置提示（面包屑）** —— 面板顶部显示你正在读的章节路径（如 `部署 › Docker`）。判定规则是"**视口中线之上最深的那个标题**"，也就是画面里占得最多的那一节；点击它跳过去后仍显示同一个标题（跳转落点也在中线之上，规则自洽）
+- **层级筛选** —— 面板顶部的 `1`–`6` 芯片是**各自独立的开关**，可任意组合（例如只留 H1 和 H3、关掉中间的 H2）；选择会被记住。把最后一个还亮着的层级也关掉时，会自动恢复显示全部六级（面板不会变空）。这一行本身也能收起：标题栏里放大镜左边的 **层级** 按钮收起/展开它（选择会记住），收起后筛选设置仍然生效
+- **代码块不算标题** —— ``` 围栏代码块里的 `# 注释`、`## 示例` 不会被当成大纲标题（以前会混进大纲，还会让它后面那些真标题跳错位置）
+- **自动跟随高亮** —— 滚动对话时，视口内可见的回合在大纲中自动点亮（可同时点亮多组），其余组变暗；大纲自动加载并滚动，使正在阅读的组保持可见
+- **跳转** —— 点击标题跳到对话中该标题所在位置；点击组头的时间或预览跳到该回合开头
+- **可停靠、可缩放** —— 拖顶部横条移动，按 ◀ / ▶ 切换左右停靠，拖边缘或角部调整宽高，收起后成为边缘把手（点击展开）；面板位置与尺寸会被记住
+- **分页与加载更早** —— 默认显示最近的若干组；在大纲中向上滚动（或滚动到顶部）会加载更早的组
+- **Markdown 清理** —— 标题中的行内标记（`**加粗**`、`*斜体*`、`` `代码` ``、`[链接](url)`、`~~删除线~~`）会被剥离后显示
+- **仅对话视图显示** —— 中间列切到轨迹、上下文等其他视图时，面板与边缘把手渐隐
+- 对话中没有任何标题时，大纲只列出可点击跳转的回合时间条目；连时间也识别不到时面板自动隐藏。适配深色与浅色主题（内阴影质感随主题切换）
 
 ## 兼容性
 
-| 插件版本 | DSH 版本 |
+| 插件版本 | 支持的 DSH 版本 |
 | --- | --- |
-| **0.3.2**（最新） | **≥ 0.1.2-rc.1**（已在 0.1.2-rc.1 / 0.1.5-rc.1 验证） |
-| 0.3.0 – 0.3.1 | 同上 |
-| 0.2.2 | 0.1.2-rc.1 之前的旧版 DSH（npm 上 `dsh-quick-toc@legacy`） |
+| **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 |
 
-0.3.0 重写了与宿主的对接（新版 slot 架构 + `useChat` 会话数据），**只支持 DSH 0.1.2-rc.1 及以上**；旧版 DSH 请安装 0.2.2。安装/更新时 DSH 市场会根据 package.json 的 `dsh.compatibility.dshReleases` 与 `peerDependencies` 做 host 兼容预检，版本不符会给出提示。
+`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` 做宿主兼容预检。
 
 ## 安装
 
-通过 DSH CLI 安装（已发布 npm，只要名字）：
+通过 DSH CLI 安装：
 
 ```
 dsh plugin --profile web add dsh-quick-toc
 ```
 
-或从 GitHub 安装：
+也可以从 GitHub 安装：
 
 ```
 dsh plugin --profile web add github:LyaxZ/dsh-quick-toc
 ```
 
-或本地目录安装：
+或以本地目录安装：
 
 ```
-dsh plugin --profile web add <本目录路径>
+dsh plugin --profile web add <插件目录路径>
 ```
 
-重启 DSH（Windows 上双击 `restart-dsh.bat`）后打开 Web UI。大纲默认收起——点击对话区左侧边缘的小把手展开。
+安装后重启 DSH 并打开 Web UI。面板默认收起，点击对话区边缘的把手即可展开。
 
 ## 使用
 
-- 点击大纲标题跳转到对话中对应位置
-- 拖动顶部横条移动面板；点 **◀ / ▶** 按钮切换左右停靠
-- 拖右边缘调宽度、下边缘调高度、右下角同时调
-- 大纲滚动到顶部可加载更早的组
+- **跳转**：点击大纲标题跳到该标题所在位置；点击组头的时间或首行预览跳到**该回合模型回答的开头**；点击顶部的面包屑跳到当前所在标题
+- **搜索**：点击标题栏的放大镜展开搜索框，输入关键字后大纲切换为结果列表——直接点某一条定位并高亮，或按回车逐处循环（`n/N` 显示当前位置与命中总数，当前命中所属行会高亮）；按 Esc 或再次点击放大镜关闭并回到大纲；用 **标题 / 全文** 按钮切换搜索范围
+- **层级筛选**：`1`–`6` 芯片是各自独立的开关，可任意组合；点标题栏的 **层级** 按钮收起/展开这一行
+- **移动与停靠**：拖顶部横条移动面板，按 ◀ / ▶ 在左右之间切换停靠
+- **调整大小**：拖右边缘调宽度、拖下边缘调高度、拖右下角同时调整
+- **加载更早**：在大纲中向上滚动即可加载更早的回合；对话本身有"加载更早消息"按钮时，大纲滚到顶部也会触发它
 
 ## 开发
 
 - `lib/client.js` —— 全部 UI 逻辑（浏览器端）
-- `lib/index.js` —— 宿主端空入口（版本守卫可在此扩展）
+- `lib/index.js` —— 宿主端入口（空实现；本插件只提供浏览器端 UI）
 - `cordis.patch.yml` —— loader patch（符合官方 bundle 规范）
-- **0.3.0 起对接新版插件模型**：面板注册进会话级 `conversation.input.overlay` 槽（会话级 hook 由 `ctx.uiSession.provide` 贡献，`useChat` 由 ui-chat 贡献），面板本体 `createPortal` 到 `document.body` 渲染成固定浮层；数据入口为 `props.useChat`（`ChatSnapshot.order` + `nodes`，节点形状：`kind: user/assistant-step`、`location.turn`、`data.blocks`）
-- 改 client.js 后需重启 DSH（boot rev 按内容算）
+- 面板注册进会话级 `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 生效
 
 ## License