@luziyang2026/dsh-question-nav 0.1.0 → 0.3.0

package/src/client/index.ts

@@ -1,16 +1,24 @@
 /**
- * Browser-half entry for the dsh-client-ui-question-nav plugin.
+ * Browser-half entry for the dsh-question-nav plugin.
  *
  * Registers one surface into the frame-wide floating layer (`shell.overlay`):
- * a vertical strip on the right edge of the conversation column listing every
+ * a vertical strip on the LEFT edge of the conversation column listing every
  * user question in the current session as a small button. Clicking a button
- * scrolls the chat to that question (paging older history when needed).
+ * scrolls the chat to that question.
+ *
+ * The strip indexes the WHOLE session history WITHOUT expanding DSH's paged
+ * render window: it pages the raw `session.history` RPC (read-only, no render
+ * cost) and derives each question's chat anchor key from the event. Only when
+ * a dot is clicked does the jump loop call `loadOlder()` to bring that
+ * specific page into the window — so the conversation's memory economy is
+ * preserved.
  *
  * Failure policy: nothing here throws at apply time — an external plugin must
  * never take the GUI down.
  */
 import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
 import type { SessionId } from '@deepseek-ai/dsh-client-connection/client'
+import type { ConnectionHandle } from '@deepseek-ai/dsh-client-connection/client'
 // Type-only: pulls ui-layout's SlotMap merge ('shell.overlay').
 import type {} from '@deepseek-ai/dsh-client-ui-layout/client'
 // Type-only: pulls the locale plugin's Context merge (ctx.locale).
@@ -19,6 +27,7 @@ import { QuestionNavStrip, type QuestionNavInjected } from './QuestionNavStrip.t
 import { en, zh, type QuestionNavKey } from './locales.ts'
 import { extractQuestions } from '../core/nodes.ts'
 import { jumpToQuestion, type JumpFailureCode, type JumpPorts } from '../core/jump.ts'
+import { buildQuestionIndex, type HistoryIndexOptions, type HistoryIndexResult, type RawEventLike } from '../core/history-index.ts'
 
 /** Locale namespace this plugin owns. */
 const NS = 'question-nav'
@@ -31,7 +40,7 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
 }
 
 /** Services required by this plugin. */
-export const inject = ['slots', 'locale', 'sessions']
+export const inject = ['slots', 'locale', 'sessions', 'connection']
 
 /** Single-instance guard: a duplicated client injection must not mount twice. */
 declare global {
@@ -81,6 +90,45 @@ function jumpPortsFor(ctx: ClientContext, sessionId: SessionId): JumpPorts {
   }
 }
 
+/** Resolve the connection handle (shared API client) as other DSH plugins do. */
+function connectionOf(ctx: ClientContext): ConnectionHandle {
+  return ctx.get('connection') as ConnectionHandle
+}
+
+/**
+ * One raw history page, mapped to the pure `buildQuestionIndex` port shape.
+ * `beforeSeq` is exclusive; `undefined` reads the newest page. Returns
+ * undefined when the page is unavailable so the builder stops cleanly. The
+ * SDK's `SessionEvent` is cast to the structural `RawEventLike` at this
+ * boundary (the index reader only touches type/seq/time/surfaceOp/data).
+ */
+async function rawHistoryPage(
+  ctx: ClientContext,
+  sessionId: SessionId,
+  beforeSeq: number | undefined,
+  maxMessages: number,
+): Promise<{ events: readonly { event: RawEventLike }[]; hasMore: boolean } | undefined> {
+  const { api } = connectionOf(ctx)
+  const { result } = await api.sessions.history({ sessionId, beforeSeq, maxMessages })
+  if (!result.ok) return undefined
+  return {
+    events: result.value.events.map((entry) => ({ event: entry.event as unknown as RawEventLike })),
+    hasMore: result.value.hasMore,
+  }
+}
+
+/** Build the full-session question index from the raw history RPC (no render). */
+function buildIndexFor(
+  ctx: ClientContext,
+  sessionId: SessionId,
+  options: HistoryIndexOptions = {},
+): Promise<HistoryIndexResult> {
+  return buildQuestionIndex({
+    history: (beforeSeq, maxMessages) => rawHistoryPage(ctx, sessionId, beforeSeq, maxMessages),
+    now: () => Date.now(),
+  }, options)
+}
+
 function createInject(ctx: ClientContext): QuestionNavInjected {
   return {
     readQuestions: (sessionId) => {
@@ -103,6 +151,7 @@ function createInject(ctx: ClientContext): QuestionNavInjected {
       }
       void jumpToQuestion(ports, key)
     },
+    fetchQuestionIndex: (sessionId, options) => buildIndexFor(ctx, sessionId, options),
   }
 }
 

package/src/client/locales.ts

@@ -4,6 +4,9 @@
  */
 export const zh = {
   'strip.empty': '本会话还没有提问',
+  'strip.loadingAll': '正在加载全部历史…',
+  'strip.loadingSuffix': '…',
+  'strip.loadEarlier': '加载更早的问题',
   'jump.inactive': '聊天视图未激活',
   'jump.hidden': '目标无独立气泡，已定位到邻近内容',
   'jump.notfound': '目标未加载或不存在（可能已压缩）',
@@ -12,6 +15,9 @@ export const zh = {
 
 export const en = {
   'strip.empty': 'No questions in this session yet',
+  'strip.loadingAll': 'Loading full history…',
+  'strip.loadingSuffix': '…',
+  'strip.loadEarlier': 'Load earlier questions',
   'jump.inactive': 'Chat view is not active',
   'jump.hidden': 'No dedicated bubble; landed on nearby content',
   'jump.notfound': 'Target not loaded or missing (maybe compacted)',

package/src/client/question-nav.module.css

@@ -58,6 +58,17 @@
   background: var(--dsw-alias-brand-primary);
 }
 
+/* Dimmed placeholder for unloaded older history (below the count, above the
+   oldest question): click to page in more history. */
+.moreDot {
+  background: transparent;
+  border: 1px dashed var(--dsw-alias-border-l3);
+}
+.moreDot:hover {
+  background: var(--dsw-alias-brand-primary);
+  border-color: var(--dsw-alias-brand-primary);
+}
+
 /* Question count, rendered just above the first dot (sits in the list gap). */
 .count {
   flex: none;
@@ -68,6 +79,19 @@
   user-select: none;
 }
 
+/* Ellipsis shown while the full history is being expanded. */
+.countLoading {
+  margin-left: 2px;
+  font-weight: 400;
+  color: var(--dsw-alias-brand-primary);
+  animation: qnPulse 1.2s ease-in-out infinite;
+}
+
+@keyframes qnPulse {
+  0%, 100% { opacity: 0.4; }
+  50% { opacity: 1; }
+}
+
 /* The centered group: count + dot column, centered together (the list's auto
    margins center it when short; it scrolls as a unit when tall). */
 .dots {

package/src/core/history-index.ts

@@ -0,0 +1,176 @@
+/**
+ * Question-index builder over the raw session history RPC.
+ *
+ * DSH pages the rendered conversation window on purpose (memory economy):
+ * `chat.nodes` only ever holds the loaded window, and force-expanding it
+ * (repeated `loadOlder()`) materializes + renders the whole log — the exact
+ * cost DSH's paging exists to avoid. This module instead builds a lightweight
+ * index of every user question by paging the RAW history RPC (`session.history`
+ * with `beforeSeq`), which reads the host log without touching the render
+ * window at all. Only `{key, seq, time, text}` per question is retained.
+ *
+ * The chat anchor key is derived deterministically from the event — it equals
+ * `conversationContextKey('input-message', String(event.data.id))` — so the
+ * dots can target rows that are not loaded yet, and a click then pages the
+ * window on demand (see `jump.ts`).
+ *
+ * Pure-ish: takes injected ports (one raw history page read, clocks) so it is
+ * unit-testable without a browser or a live session.
+ */
+
+import type { QuestionNode } from './nodes.ts'
+import { messageText } from './nodes.ts'
+
+/** Minimal shape of a raw history event (structural, not SDK-bound). */
+export interface RawEventLike {
+  type: string
+  seq: number
+  time: number
+  surfaceOp?: unknown
+  data?: {
+    id?: unknown
+    source?: { kind?: string; plugin?: string }
+    content?: readonly { type?: string; text?: string }[]
+  }
+}
+
+/** The conversation Definition kind whose key a user question node uses. */
+export const MESSAGE_DEFINITION_KIND = 'input-message'
+
+/**
+ * The engine-owned stable chat key for a user question event — mirrors
+ * `conversationContextKey('input-message', String(id))` from the DSH runtime
+ * (verified against it in the unit test).
+ */
+export function questionKey(id: unknown): string {
+  const kind = MESSAGE_DEFINITION_KIND
+  return `${kind.length}:${kind}${String(id)}`
+}
+
+/**
+ * Whether a raw event is one user question the strip should index.
+ * Mirrors the DSH `messageDefinition` match + `start` classification:
+ * an append-origin `user/message` with a human (`user`) source. Replacement
+ * copies (compaction checkpoints, `source.kind === 'plugin'`) and injected
+ * context (`source.kind !== 'user'`) are excluded.
+ */
+export function isQuestionEvent(event: RawEventLike): boolean {
+  if (event.type !== 'user/message') return false
+  if (event.surfaceOp !== 'append') return false
+  return event.data?.source?.kind === 'user'
+}
+
+/** Map one raw question event to a strip question node, or null when not one. */
+export function questionFromEvent(event: RawEventLike): QuestionNode | null {
+  if (!isQuestionEvent(event)) return null
+  return {
+    key: questionKey(event.data?.id),
+    anchorSeq: event.seq,
+    seq: event.seq,
+    time: event.time,
+    text: messageText(event.data?.content),
+  }
+}
+
+export interface HistoryIndexPorts {
+  /**
+   * Read one raw history page. `beforeSeq` is exclusive (events with seq <
+   * beforeSeq); `undefined` reads the newest page. Resolves undefined when
+   * the page is unavailable (session gone / transport error).
+   */
+  history: (
+    beforeSeq: number | undefined,
+    maxMessages: number,
+  ) => Promise<{ events: readonly { event: RawEventLike }[]; hasMore: boolean } | undefined>
+  /** Monotonic ms clock. */
+  now: () => number
+}
+
+export interface HistoryIndexOptions {
+  /** Raw messages per page (default 100). */
+  maxMessages?: number
+  /** Max pages before giving up (default 200 => 20k messages). */
+  maxPages?: number
+  /** Total wall-clock budget (default 30s). */
+  totalTimeoutMs?: number
+  /** Abort the build; checked every iteration. */
+  signal?: AbortSignal
+  /** Resume from a previous `nextBeforeSeq` instead of the newest page. */
+  startBeforeSeq?: number
+}
+
+export type HistoryIndexCode = 'COMPLETE' | 'BUDGET' | 'TIMEOUT' | 'UNAVAILABLE' | 'CANCELLED'
+
+export interface HistoryIndexResult {
+  ok: boolean
+  code: HistoryIndexCode
+  /** Questions collected so far, ascending by anchorSeq. */
+  questions: QuestionNode[]
+  /** Page count actually read. */
+  pages: number
+  /** Where to continue (exclusive) when stopped early; undefined when COMPLETE. */
+  nextBeforeSeq: number | undefined
+}
+
+const DEFAULTS = {
+  maxMessages: 100,
+  maxPages: 200,
+  totalTimeoutMs: 30_000,
+}
+
+function minSeq(events: readonly { event: RawEventLike }[]): number | undefined {
+  let min: number | undefined
+  for (const { event } of events) {
+    if (min === undefined || event.seq < min) min = event.seq
+  }
+  return min
+}
+
+/**
+ * Page the raw session history backward, collecting every user question into a
+ * lightweight index. Never touches the render window.
+ */
+export async function buildQuestionIndex(
+  ports: HistoryIndexPorts,
+  options: HistoryIndexOptions = {},
+): Promise<HistoryIndexResult> {
+  const cfg = { ...DEFAULTS, ...options }
+  const deadline = ports.now() + cfg.totalTimeoutMs
+  const questions: QuestionNode[] = []
+  let beforeSeq: number | undefined = cfg.startBeforeSeq
+  let pages = 0
+
+  const cancelled = (): boolean => cfg.signal?.aborted === true
+
+  while (true) {
+    if (cancelled()) return { ok: false, code: 'CANCELLED', questions, pages, nextBeforeSeq: beforeSeq }
+    if (ports.now() > deadline) return { ok: false, code: 'TIMEOUT', questions, pages, nextBeforeSeq: beforeSeq }
+    if (pages >= cfg.maxPages) return { ok: false, code: 'BUDGET', questions, pages, nextBeforeSeq: beforeSeq }
+
+    const page = await ports.history(beforeSeq, cfg.maxMessages)
+    if (page === undefined) {
+      // Transient: retry a little, then give up with what we have.
+      if (pages === 0) return { ok: false, code: 'UNAVAILABLE', questions, pages, nextBeforeSeq: beforeSeq }
+      return { ok: true, code: 'COMPLETE', questions, pages, nextBeforeSeq: undefined }
+    }
+
+    for (const { event } of page.events) {
+      const question = questionFromEvent(event)
+      if (question !== null) questions.push(question)
+    }
+
+    if (!page.hasMore) {
+      questions.sort((a, b) => a.anchorSeq - b.anchorSeq)
+      return { ok: true, code: 'COMPLETE', questions, pages, nextBeforeSeq: undefined }
+    }
+
+    const next = minSeq(page.events)
+    if (next === undefined) {
+      // Empty page with hasMore true is anomalous; stop cleanly.
+      questions.sort((a, b) => a.anchorSeq - b.anchorSeq)
+      return { ok: true, code: 'COMPLETE', questions, pages, nextBeforeSeq: undefined }
+    }
+    beforeSeq = next
+    pages += 1
+  }
+}

package/src/core/nodes.ts

@@ -96,3 +96,17 @@ export function nearestRenderable(
   }
   return best
 }
+
+/**
+ * Merge two question sets (full-history index + live loaded window) into one
+ * deduplicated, anchorSeq-ascending list. The window may hold questions that
+ * arrived after the index was built; the index may hold questions the window
+ * has not loaded yet — union on `key`, newest live copy wins per key.
+ */
+export function mergeQuestions(...sources: readonly (readonly QuestionNode[])[]): QuestionNode[] {
+  const byKey = new Map<string, QuestionNode>()
+  for (const source of sources) {
+    for (const node of source) byKey.set(node.key, node)
+  }
+  return [...byKey.values()].sort((a, b) => a.anchorSeq - b.anchorSeq)
+}