dsh-conversation-overview 1.4.0 → 1.4.2

package/README.md

@@ -38,7 +38,7 @@ CLI 安装后重启 `dsh` 生效（方式一/二安装后刷新浏览器页面
 
 安装后在「设置 → 会话概览」或插件行内配置中调整选项；对话页刷新即可看到「概览」标签页与右侧边栏入口。
 
-> 注意：若此前安装过开发版 `@local/dsh-conversation-overview`，请先移除它再安装本包——两者使用相同的插件行 id（`conversation-overview`）与插槽 key，不应同时启用。
+> 注意：若此前用 `link:` 装过本地开发副本（同名包指向你的工作目录），请先移除再安装本包——两者使用相同的插件行 id（`conversation-overview`）与插槽 key，不应同时启用。判断方法：`grep dsh-conversation-overview ~/.dsh/profiles/web/package.json`，出现 `link:/…` 即为开发版。
 
 **插件更新**：
 
@@ -78,14 +78,69 @@ CLI 安装后重启 `dsh` 生效（方式一/二安装后刷新浏览器页面
 
 ## 开发与测试
 
-包内无构建步骤：`index.js`（Host 侧，schemastery Config + 资源定位）与 `client.js`（浏览器侧，`window.__ModuleLoader__` 工厂格式）均为源文件直发。
+### 代码结构
 
-离线测试用真实会话日志（`session.v4.jsonl.zstd`）驱动折叠逻辑与设置表单断言：
+包内**没有构建步骤**，两个源文件直接就是发布物：
+
+| 文件 | 运行位置 | 职责 |
+| --- | --- | --- |
+| `index.js` | Host（Node） | schemastery 配置字段定义、`dsh-resource://` 资源定位与 Host 侧数据接口 |
+| `client.js` | 浏览器（Web UI） | 概览页/侧边栏 UI、会话事件折叠、标签页注册，以 `window.__ModuleLoader__` 工厂函数形式被加载 |
+
+改完文件后：Host 侧（`index.js`、`cordis.patch.yml` 的配置项）需要**重启 DSH** 才生效；纯客户端（`client.js`）**刷新页面**即可。
+
+### 本地调试安装
+
+```bash
+# 让 profile 直接引用本地目录（改完刷新即生效，不必反复装包）
+dsh plugin --profile web add link:/absolute/path/to/dsh-conversation-overview
+
+# 确认装的是开发版而不是 npm 版
+grep dsh-conversation-overview ~/.dsh/profiles/web/package.json   # 应看到 link:/…
+```
+
+### 运行测试
+
+测试脚本随包发布，无需构建、无需联网。它会在 Node 里用桩（stub）替代浏览器环境——`window`、`localStorage`、`React`——然后加载 `client.js`，对**真实会话日志**做一遍完整折叠并断言结果。
 
 ```bash
-node .scratch/test.mjs <path/to/session-a.jsonl.zstd> <path/to/session-b.jsonl.zstd>
+# 默认自动取本机最近的 2 个会话日志
+npm test
+
+# 或指定任意日志（可传多个，跨会话、跨工作区都行）
+node .scratch/test.mjs ~/.dsh/sessions/<workspace>/<session-id>/session.v4.jsonl.zstd \
+                       ~/.dsh/sessions/<workspace>/<other-session-id>/session.v4.jsonl.zstd
 ```
 
+- 依赖 **Node ≥ 20** 与 **`zstdcat`**（日志是 zstd 压缩的；macOS：`brew install zstd`）。
+- 会话日志位置：`~/.dsh/sessions/<工作区>/<session-id>/session.v4.jsonl.zstd`，每一轮对话都在里面。
+- 全部通过时输出 `ALL TESTS PASSED`，并列出实际检查了哪几个日志；任一断言失败会直接给出断言信息与所在行号。
+
+### 测试覆盖范围
+
+共 16 组、约 460 条断言，全部离线运行：
+
+| # | 覆盖内容 |
+| --- | --- |
+| 1 | `zh`/`en` 词典键完全对齐（少一个键就失败，避免界面出现原始 key） |
+| 2 | `apply()` 在 mock `ctx` 上注册了哪些标签页/插槽，以及每个配置开关的显隐效果 |
+| 3 | 用真实日志跑完整折叠：待办、关键步骤、产物、引用、统计、里程碑 |
+| 4 | 地址解析、助手提及、变更事件等纯函数 |
+| 5 | 文件类型分类与工作区变更聚合 |
+| 6 | OpenViking 预览与 Markdown 渲染 |
+| 7 | frontmatter、面包屑、引用排序 |
+| 8 | 按轮次折叠（`latest` / `all` 两种范围）与上下文快照 |
+| 9 | 全量引用识别（正文里出现过的资源是否都被收集） |
+| 10 | 关键步骤流与轮次导航轨的联动刻度 |
+| 11 | 「新标签打开」确实落到宿主自己的 Markdown 文档页 |
+| 12 | 「本轮结论」只在该轮结束后出现 |
+| 13 | 结论自动打开：只在观察到该轮实际运行后打开一次（刷新不会重开） |
+| 14 | 子代理相关界面只在真有子代理工作时出现（压缩里程碑不算） |
+| 15 | 文档标签刷新后仍能恢复正文（结论/计划快照镜像到 `localStorage`） |
+| 16 | 代理身份判定：`origin: "subagent"` 才是子代理，分叉/续聊会话算主会话 |
+
+> 这些断言同时充当回归护栏：改动 `client.js` 的折叠或显隐逻辑后先跑 `npm test`，比在浏览器里逐个点要快得多。
+
 ## License
 
 MIT © 2026

package/client.js

@@ -1565,20 +1565,23 @@ window.__ModuleLoader__.load({
     function openArtifact(binding, artifact, stats) {
       const sessionId = binding ? binding.sessionId : undefined;
       if (artifact.kind === "conclusion") {
+        /* The plugin's own tab is restorable: its body is mirrored into localStorage,
+           while the host's plan-review page keeps its payload in tab params only and
+           turns into the expired "计划" page after a reload. */
+        if (typeof artifact.previewKey === "string" && artifact.previewKey !== "" && openContextPreview(artifact.previewKey)) return;
         const entry = typeof artifact.previewKey === "string" ? readContextPreview(artifact.previewKey) : null;
         const docKey = `conclusion:${typeof artifact.turn === "number" ? artifact.turn : artifact.previewKey}`;
-        if (openNativeDocument(sessionId, docKey, artifact.title, entry === null ? undefined : entry.text)) return;
-        if (typeof artifact.previewKey === "string" && artifact.previewKey !== "") openContextPreview(artifact.previewKey);
+        openNativeDocument(sessionId, docKey, artifact.title, entry === null ? undefined : entry.text);
         return;
       }
       if (artifact.plan === true) {
         if (openNativePlan(sessionId, artifact.planCallId)) return;
         /* host plan viewer unavailable (plugin disabled, no sidebar): the document
            page over the same snapshot, then the plugin's own tab */
+        if (typeof artifact.previewKey === "string" && artifact.previewKey !== "" && openContextPreview(artifact.previewKey)) return;
         const entry = typeof artifact.previewKey === "string" ? readContextPreview(artifact.previewKey) : null;
         const docKey = `plan:${typeof artifact.planCallId === "string" && artifact.planCallId !== "" ? artifact.planCallId : artifact.previewKey}`;
-        if (openNativeDocument(sessionId, docKey, entry !== null ? entry.title : artifact.planTitle, entry === null ? undefined : entry.text)) return;
-        if (typeof artifact.previewKey === "string" && artifact.previewKey !== "") openContextPreview(artifact.previewKey);
+        openNativeDocument(sessionId, docKey, entry !== null ? entry.title : artifact.planTitle, entry === null ? undefined : entry.text);
         return;
       }
       if (typeof artifact.path === "string" && artifact.path.startsWith("viking://")) {
@@ -1852,7 +1855,12 @@ window.__ModuleLoader__.load({
     function rememberContextPreview(sessionId, refKey, title, text, kind) {
       if (typeof sessionId !== "string" || sessionId === "" || typeof text !== "string" || text === "") return undefined;
       const globalKey = `${sessionId}|${refKey}`;
-      contextPreviews.set(globalKey, { title: typeof title === "string" && title !== "" ? title : refKey, text: text.length > CONTEXT_TEXT_LIMIT ? `${text.slice(0, CONTEXT_TEXT_LIMIT)}\n…` : text, ...(typeof kind === "string" && kind !== "" ? { kind } : {}) });
+      const entry = { title: typeof title === "string" && title !== "" ? title : refKey, text: text.length > CONTEXT_TEXT_LIMIT ? `${text.slice(0, CONTEXT_TEXT_LIMIT)}\n…` : text, ...(typeof kind === "string" && kind !== "" ? { kind } : {}) };
+      contextPreviews.set(globalKey, entry);
+      /* Documents (turn conclusion, plan snapshot) open as tabs the host restores
+         after a reload, and their body lives only here — mirror them into
+         localStorage so a refreshed tab does not render the "unavailable" state. */
+      if (entry.kind === "conclusion" || entry.kind === "plan") persistDocPreview(globalKey, entry);
       while (contextPreviews.size > CONTEXT_PREVIEW_LIMIT) {
         const oldest = contextPreviews.keys().next();
         if (oldest.done === true) break;
@@ -1861,9 +1869,43 @@ window.__ModuleLoader__.load({
       return globalKey;
     }
 
+    const DOC_PREVIEW_STORE_KEY = "dsh.conversationOverview.docPreviews";
+    const DOC_PREVIEW_STORE_LIMIT = 8;
+    const DOC_PREVIEW_TEXT_LIMIT = 20000;
+
+    function readDocPreviewStore() {
+      try {
+        const raw = window.localStorage.getItem(DOC_PREVIEW_STORE_KEY);
+        const parsed = typeof raw === "string" ? JSON.parse(raw) : null;
+        if (!Array.isArray(parsed)) return [];
+        return parsed.filter((item) => Array.isArray(item) && typeof item[0] === "string" && isRecord(item[1]));
+      } catch {
+        return [];
+      }
+    }
+
+    function persistDocPreview(globalKey, entry) {
+      try {
+        const kept = readDocPreviewStore().filter((item) => item[0] !== globalKey);
+        const text = entry.text.length > DOC_PREVIEW_TEXT_LIMIT ? `${entry.text.slice(0, DOC_PREVIEW_TEXT_LIMIT)}\n…` : entry.text;
+        kept.push([globalKey, { title: entry.title, text, kind: entry.kind }]);
+        window.localStorage.setItem(DOC_PREVIEW_STORE_KEY, JSON.stringify(kept.slice(-DOC_PREVIEW_STORE_LIMIT)));
+      } catch {
+        /* storage full or unavailable: the in-memory copy still serves this page */
+      }
+    }
+
     function readContextPreview(globalKey) {
       const entry = contextPreviews.get(globalKey);
-      return entry === undefined ? null : entry;
+      if (entry !== undefined) return entry;
+      /* a tab restored after a reload finds its body here */
+      const stored = readDocPreviewStore().find((item) => item[0] === globalKey);
+      if (stored === undefined) return null;
+      const revived = isRecord(stored[1]) && typeof stored[1].text === "string" ? stored[1] : null;
+      if (revived === null || revived.text === "") return null;
+      const restored = { title: typeof revived.title === "string" && revived.title !== "" ? revived.title : globalKey, text: revived.text, ...(typeof revived.kind === "string" && revived.kind !== "" ? { kind: revived.kind } : {}) };
+      contextPreviews.set(globalKey, restored);
+      return restored;
     }
 
     const CONTEXT_ADDRESS_PREFIX = "dsh-resource://overview-context/";
@@ -1895,8 +1937,13 @@ window.__ModuleLoader__.load({
     function openContextPreview(globalKey) {
       const sidebar = contextSidebar();
       if (sidebar === null) return false;
-      sidebar.openResource(contextPreviewAddress(globalKey));
-      return true;
+      try {
+        sidebar.openResource(contextPreviewAddress(globalKey));
+        return true;
+      } catch (_unavailable) {
+        /* no tab type claims our address (plugin half not mounted): caller falls back */
+        return false;
+      }
     }
 
     /* An overview can be mounted twice (inline card + sidebar tab); only the first
@@ -1910,6 +1957,27 @@ window.__ModuleLoader__.load({
       return true;
     }
 
+    /* Auto-open decision for the turn-conclusion tab. Guard shape:
+       { ready, opened:Set, sawRunning }. A conclusion only earns a tab when this
+       overview watched the session run at some point after mounting — history that
+       is replayed on mount/refresh (even when it arrives in several flushes, after
+       the first paint) must never pop a tab. Returns the key to open, else null. */
+    function conclusionAutoOpenKey(guard, conclusion, sessionId, sawRunning) {
+      if (!isRecord(guard) || !(guard.opened instanceof Set)) return null;
+      const record = isRecord(conclusion) ? conclusion : null;
+      const key = `${sessionId}|${record === null ? "" : record.turn}`;
+      if (guard.ready !== true) {
+        /* first paint: whatever already exists is history, never re-opened */
+        guard.ready = true;
+        if (record !== null) guard.opened.add(key);
+        return null;
+      }
+      if (record === null || record.ended !== true || guard.opened.has(key)) return null;
+      guard.opened.add(key);
+      if (sawRunning !== true) return null;
+      return key;
+    }
+
     /* Quick-nav linkage: a click on the built-in turn rail broadcasts a scope request
        that every mounted overview follows (module-level, cross-instance). */
     const navScopeStore = { rev: 0, selection: null, listeners: new Set() };
@@ -2038,6 +2106,26 @@ window.__ModuleLoader__.load({
       return React.useSyncExternalStore(subscribe, read);
     }
 
+    /** True while the session is actively producing a turn (running flag of sessionStatus). */
+    function useSessionRunning(sessionId) {
+      const source = readSessionStatusSource();
+      const subscribe = React.useCallback(
+        (onChange) => (source !== undefined && typeof source.subscribe === "function" ? source.subscribe(onChange) : () => {}),
+        [source]
+      );
+      const read = React.useCallback(() => {
+        if (source === undefined || typeof source.getSnapshot !== "function" || typeof sessionId !== "string") return false;
+        try {
+          const snapshot = source.getSnapshot();
+          const status = snapshot !== null && snapshot !== undefined && typeof snapshot.get === "function" ? snapshot.get(sessionId) : undefined;
+          return status !== null && status !== undefined && status.running === true;
+        } catch {
+          return false;
+        }
+      }, [source, sessionId]);
+      return React.useSyncExternalStore(subscribe, read);
+    }
+
     function touch(folder) {
       folder.changed = true;
     }
@@ -5788,25 +5876,34 @@ function FileTypeIcon(props) {
       }
       const byId = isRecord(snapshot) && isRecord(snapshot.byId) ? snapshot.byId : {};
       const self = isRecord(byId[sessionId]) ? byId[sessionId] : null;
-      const parentId =
-        isRecord(address) && typeof address.parentSessionId === "string" && address.parentSessionId !== ""
-          ? address.parentSessionId
-          : self !== null && typeof self.parentId === "string" && self.parentId !== ""
-          ? self.parentId
+      const entryTitle = (entry, fallback) =>
+        entry !== null && typeof entry.title === "string" && entry.title !== ""
+          ? entry.title
+          : entry !== null && typeof entry.displayTitle === "string" && entry.displayTitle !== ""
+          ? entry.displayTitle
+          : fallback;
+      const entryParent = (entry) =>
+        typeof entry.parentSessionId === "string" && entry.parentSessionId !== ""
+          ? entry.parentSessionId
+          : typeof entry.parentId === "string" && entry.parentId !== ""
+          ? entry.parentId
           : null;
+      /* `origin: "subagent"` is the durable marker. A branched/forked conversation
+         also carries a parentSessionId (and the host even hands out a subagent
+         address for it), but it is a main session with lineage — not a subagent. */
+      const isSubagent = self !== null && self.origin === "subagent";
+      const parentId = isSubagent
+        ? (isRecord(address) && typeof address.parentSessionId === "string" && address.parentSessionId !== "" ? address.parentSessionId : entryParent(self))
+        : null;
       const parent = parentId !== null && isRecord(byId[parentId]) ? byId[parentId] : null;
       const ids = isRecord(snapshot) && Array.isArray(snapshot.ids) ? snapshot.ids : [];
       const children = [];
       const seen = new Set();
       for (const id of ids) {
         const entry = isRecord(byId[id]) ? byId[id] : null;
-        if (entry === null || entry.parentId !== sessionId) continue;
+        if (entry === null || entry.origin !== "subagent" || entryParent(entry) !== sessionId) continue;
         seen.add(id);
-        children.push({
-          id,
-          title: typeof entry.displayTitle === "string" && entry.displayTitle !== "" ? entry.displayTitle : id,
-          running: entry.running === true,
-        });
+        children.push({ id, title: entryTitle(entry, id), running: entry.running === true });
       }
       /* A child can exist in the parent's catalog projection before the list is
          projected; the catalog is the same metadata the host itself reads. */
@@ -5834,7 +5931,7 @@ function FileTypeIcon(props) {
       return {
         kind: "sub",
         parentId,
-        parentTitle: parent !== null && typeof parent.displayTitle === "string" ? parent.displayTitle : "",
+        parentTitle: parent !== null ? entryTitle(parent, "") : "",
         mode: isRecord(address) && typeof address.mode === "string" ? address.mode : "",
         children,
       };
@@ -5864,6 +5961,22 @@ function FileTypeIcon(props) {
       }
     }
 
+    /* Whether this session's visible scope actually involved subagents: agent-team
+       members, subagent-catalog records, or real subagent/spawn tool calls. A
+       context-compaction milestone also carries a teamKey, so teamKey alone is not
+       evidence (that used to announce a subagent in single-agent conversations). */
+    function subagentWorkInScope(summary) {
+      const team = isRecord(summary) && isRecord(summary.team) ? summary.team : null;
+      if (team !== null && Array.isArray(team.members) && team.members.length > 0) return true;
+      if (team !== null && Array.isArray(team.subagents) && team.subagents.length > 0) return true;
+      const steps = isRecord(summary) && Array.isArray(summary.stepsAll) ? summary.stepsAll : [];
+      return steps.some(
+        (step) =>
+          isRecord(step) &&
+          (step.name === "subagent" || step.name === "subagent_fork" || step.name === "spawn_teammate" || step.name === "team_task_create")
+      );
+    }
+
     /** One compact line that says whether this overview belongs to the main agent or to
         a subagent, and offers to switch to the other side of that lineage. */
     function SessionRoleBar({ t, sessionId, hasWork }) {
@@ -5928,6 +6041,8 @@ function FileTypeIcon(props) {
       }
       /* A plain main session with no subagents in this scope has no identity to
          announce: the badge, the child list, and the parent link are all noise. */
+      /* A finished child session from an older turn is lineage, not status: only an
+         actually running subagent (or subagent work in the visible scope) is announced. */
       if (role.children.length === 0 || hasWork === false) return null;
       return h("div", { className: "dsov-role", "data-kind": "main" }, h("span", { className: "dsov-roleBadge" }, t("role.main")), children, list);
     }
@@ -5959,22 +6074,20 @@ function FileTypeIcon(props) {
       const stats = useArtifactStats(binding, summary.changeTurns);
       const cfg = useConfig();
       const sessionId = binding ? binding.sessionId : undefined;
-      /* 本轮结论 as a document: a turn that finishes while this overview is open pops
-         its closing reply into a tab once. A turn that had already finished before the
-         overview mounted is never re-opened (no tab storm on refresh or scope switch). */
-      const conclusionGuard = React.useRef({ ready: false, opened: new Set() });
+      /* 本轮结论 as a document: only a turn this overview actually watched finish
+         pops its closing reply into a tab, once. A conclusion replayed from history
+         on mount/refresh — even when it arrives in a late flush after the first
+         paint — is never opened. */
+      const sessionRunning = useSessionRunning(binding ? binding.sessionId : undefined);
+      const conclusionGuard = React.useRef({ ready: false, opened: new Set(), sawRunning: false });
+      React.useEffect(() => {
+        if (sessionRunning === true) conclusionGuard.current.sawRunning = true;
+      }, [sessionRunning]);
       React.useEffect(() => {
         const conclusion = isRecord(summary.conclusion) ? summary.conclusion : null;
-        const key = `${sessionId}|${conclusion === null ? "" : conclusion.turn}`;
         const guard = conclusionGuard.current;
-        if (guard.ready !== true) {
-          /* first paint: a turn that had already finished is never re-opened */
-          guard.ready = true;
-          if (conclusion !== null && conclusion.ended === true) guard.opened.add(key);
-          return;
-        }
-        if (conclusion === null || conclusion.ended !== true || guard.opened.has(key)) return;
-        guard.opened.add(key);
+        const key = conclusionAutoOpenKey(guard, conclusion, sessionId, guard.sawRunning);
+        if (key === null) return;
         if (cfg.conclusionTab !== true) return;
         if (typeof conclusion.previewKey !== "string" || conclusion.previewKey === "") return;
         if (contextSidebar() === null) return;
@@ -5982,22 +6095,12 @@ function FileTypeIcon(props) {
         /* a failed open must not eat the claim: another instance may still show the tab */
         const entry = readContextPreview(conclusion.previewKey);
         const docKey = `conclusion:${typeof conclusion.turn === "number" ? conclusion.turn : conclusion.previewKey}`;
-        const opened = openNativeDocument(sessionId, docKey, conclusion.title, entry === null ? undefined : entry.text) || openContextPreview(conclusion.previewKey);
+        const opened = openContextPreview(conclusion.previewKey) || openNativeDocument(sessionId, docKey, conclusion.title, entry === null ? undefined : entry.text);
         if (!opened) conclusionAutoOpened.delete(key);
-      }, [summary, cfg.conclusionTab, sessionId]);
+      }, [summary, cfg.conclusionTab, sessionId, sessionRunning]);
       /* Agent identity only earns its row when a subagent actually took part in the
-         visible scope — otherwise the overview is a single-agent conversation. */
-      const roleWork = React.useMemo(() => {
-        const team = isRecord(summary.team) ? summary.team : null;
-        if (team !== null && (Array.isArray(team.subagents) && team.subagents.length > 0)) return true;
-        if (team !== null && (Array.isArray(team.members) && team.members.length > 0)) return true;
-        const steps = Array.isArray(summary.stepsAll) ? summary.stepsAll : [];
-        return steps.some(
-          (step) =>
-            isRecord(step) &&
-            (step.name === "subagent" || step.name === "subagent_fork" || step.name === "spawn_teammate" || step.name === "team_task_create" || typeof step.teamKey === "string")
-        );
-      }, [summary]);
+         visible scope (see subagentWorkInScope). */
+      const roleWork = React.useMemo(() => subagentWorkInScope(summary), [summary]);
       const rootClass = variant === "panel" ? "dsov-panel" : "dsov-view";
       const rootRef = React.useRef(null);
       const scope = summary.scope === selection || selection === "latest" ? summary.scope : selection;
@@ -7721,6 +7824,11 @@ html[data-dsov-quicknav="off"] nav:has(button[data-index][aria-label]),html[data
       changesReviewAddress,
       absPath,
       normalizeConfig,
+      conclusionAutoOpenKey,
+      subagentWorkInScope,
+      persistDocPreview,
+      readDocPreviewStore,
+      DOC_PREVIEW_STORE_KEY,
       setFormConfig,
       setOverlayConfig,
       clearOverlayConfig,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-conversation-overview",
-  "version": "1.4.0",
+  "version": "1.4.2",
   "type": "module",
   "description": "DeepSeek Harness (DSH) plugin: an Overview tab beside Chat/Trajectory plus a right-sidebar page summarizing session progress (goal, todos, key steps), artifacts, and references, with per-turn scoping, OpenViking memory preview, and quick-nav linkage.",
   "keywords": [
@@ -40,8 +40,12 @@
     "icon.svg",
     "README.md",
     "LICENSE",
-    "assets/overview.png"
+    "assets/overview.png",
+    ".scratch/test.mjs"
   ],
+  "scripts": {
+    "test": "node .scratch/test.mjs"
+  },
   "engines": {
     "dsh": ">=0.2.1-rc.2",
     "node": ">=20"