dsh-turn-outline 0.2.5 → 0.2.7

package/README.en.md

@@ -9,6 +9,14 @@
 
 [中文](README.md)
 
+## Preview
+
+<p align="center">
+  <img src="docs/assets/turn-outline-panel.png" alt="Turn Outline tab: the session folded into per-user turns of input, tool steps and output" width="420" />
+</p>
+
+> Real-session screenshot: the whole session folds into turns 1-5, each = user input + tool steps + final output; the tool filter chips at the top (All / bash / read / edit / More) aggregate by semantic dot, and clicking any row jumps back to its place in the conversation.
+
 ## Overview
 
 **Who it is for**: users of DeepSeek Harness (Web / Desktop profile) with long sessions who want to quickly revisit "what happened at step N" — at zero cost, without adding an LLM or touching the DSH core.
@@ -29,24 +37,24 @@
 
 ### Option 1: one-liner from npm (recommended)
 
-Install better-sidebar first (stable line pinned to 0.17.x), then this plugin:
+Install better-sidebar first, then this plugin:
 
 ```sh
-npx @deepseek-ai/dsh plugin --profile desktop add dsh-better-sidebar@0.17.1
+npx @deepseek-ai/dsh plugin --profile desktop add dsh-better-sidebar
 npx @deepseek-ai/dsh plugin --profile desktop add dsh-turn-outline
 ```
 
 > Using the Web profile? Swap `--profile desktop` for `--profile web`.
 >
-> ⚠️ **Version-line note**: this plugin is currently validated on **better-sidebar 0.17.x + DSH 0.1.1-rc.x (stable)**. The npm `latest` better-sidebar 0.18.0 supports only DSH 0.1.2-rc.1+ and has not been co-tested with this plugin — until a 0.18-adapted release, pin `dsh-better-sidebar@0.17.1` before upgrading your host.
+> ℹ️ **Version-line note**: this plugin declares the peer range `dsh-better-sidebar@^0.17.0 || ^0.18.0`, and both lines are co-tested — **better-sidebar 0.18.0 + DSH 0.1.2-rc.1** (validated since 0.2.7) and **better-sidebar 0.17.1 + DSH 0.1.1-rc.x (stable)**. Note that better-sidebar 0.18.0 supports only DSH 0.1.2-rc.1+: on an older stable host (0.1.0-rc.8 ~ 0.1.1-rc.2), pin `dsh-better-sidebar@0.17.1`.
 
 ### Option 2: install from source (development / offline)
 
 ```sh
 git clone https://github.com/Andor-Z/dsh-turn-outline
 cd dsh-turn-outline
-pnpm install && pnpm build && pnpm pack     # produces dsh-turn-outline-0.2.5.tgz
-npx @deepseek-ai/dsh plugin --profile desktop add "file:$(pwd)/dsh-turn-outline-0.2.5.tgz"
+pnpm install && pnpm build && pnpm pack     # produces dsh-turn-outline-0.2.6.tgz
+npx @deepseek-ai/dsh plugin --profile desktop add "file:$(pwd)/dsh-turn-outline-0.2.6.tgz"
 ```
 
 ### Restart & enable
@@ -70,7 +78,7 @@ npx @deepseek-ai/dsh plugin --profile desktop remove dsh-turn-outline
 
 ```
 host (Node)      inject: ['webServer','sessionQuery','sessions']
-  POST /turntrail/api/events { sessionId, afterSeq }
+  POST /turn-outline/api/events { sessionId, afterSeq }
   → live sessions: borrow the frozen snapshot of the live store (O(1) probe + O(delta) projection, zero deep clones)
   → cold sessions: sessionQuery persisted log + lastSeq cache (LRU + byte cap)
   → paged responses (PAGE_SIZE events per page, hasMore semantics) + field trimming (no full tool-result payloads)
@@ -91,7 +99,7 @@ client (browser) inject: ['sessions','betterSidebar'] (betterSidebar is an optio
 
 ## Permissions & data
 
-- **Session logs**: one read-only host route `POST /turntrail/api/events`, browser same-origin + Host-header trust fence; read-only, never writes or mutates the session.
+- **Session logs**: one read-only host route `POST /turn-outline/api/events`, browser same-origin + Host-header trust fence; read-only, never writes or mutates the session.
 - **Zero LLM calls**: nothing is sent to any model; no token consumption.
 - **No credential access**: no other network/file access besides session events; no user config, no persistent storage (tab state follows better-sidebar's layout persistence).
 
@@ -102,14 +110,14 @@ client (browser) inject: ['sessions','betterSidebar'] (betterSidebar is an optio
 | Platform | DSH 0.1.1-rc.x (stable line; web/desktop profile) |
 | Dependencies | dsh-better-sidebar (optional peer; inert when absent), react (injected by the DSH client seed) |
 | Build | TypeScript + esbuild, no runtime npm dependencies |
-| Tests | vitest, 77 cases (fold / folder / jump / tab / host) |
+| Tests | vitest, 80 cases (fold / folder / jump / tab / host) |
 
 ## Development
 
 ```sh
 pnpm install          # if pnpm 10+ blocks build scripts, allow esbuild as prompted (see pnpm-workspace.yaml)
 pnpm typecheck        # tsc --noEmit
-pnpm test             # vitest run (77 cases)
+pnpm test             # vitest run (80 cases)
 pnpm build            # esbuild → lib/index.js + lib/client.js (includes bundle-contract self check)
 pnpm pack             # produces dsh-turn-outline-<version>.tgz (prepack rebuilds automatically)
 ```

package/README.md

@@ -9,6 +9,14 @@
 
 [English](README.en.md)
 
+## 样式预览
+
+<p align="center">
+  <img src="docs/assets/turn-outline-panel.png" alt="轮次轨迹 tab：会话按用户轮次折叠成「输入 → 工具步骤 → 输出」的结构化轨迹" width="420" />
+</p>
+
+> 真实会话截图：整条会话折叠为「轮次 1-5」，每轮 = 用户输入 + 工具步骤 + 最终输出；顶部工具筛选 chips（全部 / bash / read / edit / 更多）按语义色点聚合，点击任意行可定位回对话原位。
+
 ## 概览
 
 **适合谁**：使用 DeepSeek Harness（Web / Desktop profile）、会话很长、想快速回看某一步「当时做了什么」的用户——希望零成本、不引入 LLM 也不改动核心。
@@ -29,24 +37,24 @@
 
 ### 方式一：npm 一行命令（推荐）
 
-先装 better-sidebar（stable 线钉 0.17.x），再装本插件：
+先装 better-sidebar，再装本插件：
 
 ```sh
-npx @deepseek-ai/dsh plugin --profile desktop add dsh-better-sidebar@0.17.1
+npx @deepseek-ai/dsh plugin --profile desktop add dsh-better-sidebar
 npx @deepseek-ai/dsh plugin --profile desktop add dsh-turn-outline
 ```
 
 > 使用 Web profile 时把 `--profile desktop` 换成 `--profile web`。
 >
-> ⚠️ **版本线说明**：本插件当前验证于 **better-sidebar 0.17.x + DSH 0.1.1-rc.x（stable）**。npm `latest` 的 better-sidebar 0.18.0 仅支持 DSH 0.1.2-rc.1+，尚未与本插件联调——在 0.18 适配版发布前，升级宿主请先固定 `dsh-better-sidebar@0.17.1`。
+> ℹ️ **版本线说明**：本插件 peer 声明 `dsh-better-sidebar@^0.17.0 || ^0.18.0`，双线均已联调——**better-sidebar 0.18.0 + DSH 0.1.2-rc.1**（0.2.7 起验证）与 **better-sidebar 0.17.1 + DSH 0.1.1-rc.x（stable）**。注意 better-sidebar 0.18.0 仅支持 DSH 0.1.2-rc.1+：旧 stable 宿主（0.1.0-rc.8 ~ 0.1.1-rc.2）请固定安装 `dsh-better-sidebar@0.17.1`。
 
 ### 方式二：源码本地安装（开发 / 离线）
 
 ```sh
 git clone https://github.com/Andor-Z/dsh-turn-outline
 cd dsh-turn-outline
-pnpm install && pnpm build && pnpm pack     # 产出 dsh-turn-outline-0.2.5.tgz
-npx @deepseek-ai/dsh plugin --profile desktop add "file:$(pwd)/dsh-turn-outline-0.2.5.tgz"
+pnpm install && pnpm build && pnpm pack     # 产出 dsh-turn-outline-0.2.6.tgz
+npx @deepseek-ai/dsh plugin --profile desktop add "file:$(pwd)/dsh-turn-outline-0.2.6.tgz"
 ```
 
 ### 重启与启用
@@ -70,7 +78,7 @@ npx @deepseek-ai/dsh plugin --profile desktop remove dsh-turn-outline
 
 ```
 host（Node）  inject: ['webServer','sessionQuery','sessions']
-  POST /turntrail/api/events { sessionId, afterSeq }
+  POST /turn-outline/api/events { sessionId, afterSeq }
   → 活跃会话：直接借用 live store 冻结快照（O(1) 探测 + O(delta) 投影，零深拷贝）
   → 冷会话：sessionQuery 持久化日志 + lastSeq 缓存（LRU + 字节上限）
   → 响应逐页（每页 PAGE_SIZE 事件，hasMore 语义）+ 字段裁剪（不发 tool 结果全文）
@@ -91,7 +99,7 @@ client（浏览器）  inject: ['sessions','betterSidebar']（betterSidebar 可
 
 ## 权限与数据
 
-- **会话日志**：host 只读路由 `POST /turntrail/api/events`，浏览器同源 + Host 头信任围栏；只读不回写、不改动会话。
+- **会话日志**：host 只读路由 `POST /turn-outline/api/events`，浏览器同源 + Host 头信任围栏；只读不回写、不改动会话。
 - **零 LLM 调用**：不向任何模型发送内容，无 token 消耗。
 - **不读取凭据**：除会话事件外无其他网络 / 文件访问；无用户配置、无持久化存储（tab 状态随 better-sidebar 布局持久化）。
 
@@ -102,14 +110,14 @@ client（浏览器）  inject: ['sessions','betterSidebar']（betterSidebar 可
 | 平台 | DSH 0.1.1-rc.x（stable 线；web/desktop profile） |
 | 依赖 | dsh-better-sidebar（可选 peer；未装则 inert）、react（DSH client 种子注入） |
 | 构建 | TypeScript + esbuild，无运行时 npm 依赖 |
-| 测试 | vitest 77 用例（fold / folder / jump / tab / host） |
+| 测试 | vitest 80 用例（fold / folder / jump / tab / host） |
 
 ## 开发
 
 ```sh
 pnpm install          # pnpm 10+ 拦截构建脚本时按提示允许 esbuild（见 pnpm-workspace.yaml）
 pnpm typecheck        # tsc --noEmit
-pnpm test             # vitest run（77 用例）
+pnpm test             # vitest run（80 用例）
 pnpm build            # esbuild → lib/index.js + lib/client.js（含 bundle 契约自检）
 pnpm pack             # 产出 dsh-turn-outline-<version>.tgz（prepack 自动重新构建）
 ```

package/lib/client.js

@@ -1107,7 +1107,7 @@ function t(lang, key) {
 var React = __toESM(require("react"), 1);
 var MAX_PULL_PAGES = 64;
 function fetchTrailEvents(sessionId, afterSeq, base) {
-  const url = new URL("/turntrail/api/events", base ?? window.location.origin);
+  const url = new URL("/turn-outline/api/events", base ?? window.location.origin);
   return fetch(url.toString(), {
     method: "POST",
     headers: { "content-type": "application/json", accept: "application/json" },
@@ -1134,15 +1134,23 @@ function useTrail(sessionId, visible, fetchEvents, sessionsService) {
   const requestGen = React.useRef(0);
   const lastPullAt = React.useRef(0);
   const throttleTimer = React.useRef(null);
+  const visibleRef = React.useRef(visible);
+  const schedulePullRef = React.useRef(null);
   React.useEffect(() => {
     fetchRef.current = fetchEvents;
   }, [fetchEvents]);
+  React.useEffect(() => {
+    visibleRef.current = visible;
+  }, [visible]);
   React.useEffect(() => () => {
     if (throttleTimer.current !== null) window.clearTimeout(throttleTimer.current);
+    schedulePullRef.current = null;
   }, []);
   const pull = React.useCallback(async () => {
     const generation = ++requestGen.current;
     const sid = sessionIdRef.current;
+    const seqBefore = seqRef.current;
+    let drainCapped = false;
     try {
       for (let page = 0; page < MAX_PULL_PAGES; page += 1) {
         const { events, hasMore } = await fetchRef.current(sid, seqRef.current);
@@ -1163,10 +1171,17 @@ function useTrail(sessionId, visible, fetchEvents, sessionsService) {
             setStats(folder.stats());
           }
         }
-        if (hasMore !== true || events.length === 0) break;
+        if (hasMore !== true || events.length === 0) {
+          drainCapped = false;
+          break;
+        }
+        drainCapped = page === MAX_PULL_PAGES - 1;
       }
       setError(null);
       setStatus("ready");
+      if (drainCapped && seqRef.current !== seqBefore && generation === requestGen.current && sid === sessionIdRef.current && visibleRef.current && schedulePullRef.current !== null) {
+        schedulePullRef.current();
+      }
     } catch (reason) {
       if (generation !== requestGen.current) return;
       setError(reason instanceof Error ? reason.message : String(reason));
@@ -1192,6 +1207,9 @@ function useTrail(sessionId, visible, fetchEvents, sessionsService) {
       void pull();
     }, MIN_GAP - since);
   }, [pull]);
+  React.useEffect(() => {
+    schedulePullRef.current = schedulePull;
+  }, [schedulePull]);
   React.useEffect(() => {
     sessionIdRef.current = sessionId;
     folderRef.current = null;
@@ -1809,28 +1827,27 @@ function targetIcon() {
 }
 
 // src/client/index.tsx
-var primitives = (() => {
-  try {
-    return require("@deepseek-ai/dsh-client-ui-primitives");
-  } catch {
-    return null;
-  }
-})();
-function listIcon() {
-  const path = React3.createElement("path", {
-    d: "M3 3.5h10M3 8h10M3 12.5h6",
-    fill: "none",
-    stroke: "currentColor",
-    strokeWidth: "1.5",
-    strokeLinecap: "round",
-    strokeLinejoin: "round"
-  });
-  return React3.createElement("svg", { viewBox: "0 0 16 16", width: "14", height: "14", "aria-hidden": true }, path);
-}
-function tabIcon(size) {
-  const IconList = primitives !== null && typeof primitives.IconBranchOutline16 === "function" ? primitives.IconBranchOutline16 : null;
-  if (IconList !== null) return React3.createElement(IconList, { size });
-  return listIcon();
+function routeIcon(size) {
+  const children = [
+    React3.createElement("circle", { key: "a", cx: 6, cy: 19, r: 3 }),
+    React3.createElement("path", { key: "p", d: "M9 19h8.5a3.5 3.5 0 0 0 0-7h-11a3.5 3.5 0 0 1 0-7H15" }),
+    React3.createElement("circle", { key: "b", cx: 18, cy: 5, r: 3 })
+  ];
+  return React3.createElement(
+    "svg",
+    {
+      viewBox: "0 0 24 24",
+      width: size,
+      height: size,
+      fill: "none",
+      stroke: "currentColor",
+      strokeWidth: 2,
+      strokeLinecap: "round",
+      strokeLinejoin: "round",
+      "aria-hidden": true
+    },
+    children
+  );
 }
 var inject = ["sessions", "betterSidebar"];
 function apply(ctx) {
@@ -1846,7 +1863,7 @@ function apply(ctx) {
   ctx.effect(() => betterSidebar.registerTab({
     id: "turn-outline",
     title: () => typeof navigator !== "undefined" && navigator.language.toLowerCase().startsWith("zh") ? "\u8F6E\u6B21\u8F68\u8FF9" : "Turn Outline",
-    icon: (size) => tabIcon(size),
+    icon: (size) => routeIcon(size),
     order: 46,
     single: true,
     component: (props) => React3.createElement(TrailTab, {