dsh-brief-sidebar 0.9.2 → 0.9.4

package/src/client/summary/ReferenceSection.tsx

@@ -0,0 +1,211 @@
+/**
+ * The references section: 技能与记忆并列成两个可左右切换的页签。
+ *
+ * Why a tab strip instead of three stacked sections: the two lists answer the
+ * same question — "what entered this session's context" — from two different
+ * providers (this plugin's own skill fold, and prime-memory's recall/slots).
+ * Stacked, they pushed the board and the produced files off screen on a narrow
+ * sidebar; side by side, each gets the full width when the reader actually
+ * wants it.
+ *
+ * Two decisions worth knowing when editing this file:
+ *
+ * 1. **The inactive pane stays mounted and is hidden with `display:none`.**
+ *    The recall pane carries real interaction state (selected row, pending
+ *    rating, the expanded history group); unmounting it would silently reset
+ *    what the human just did every time they glanced at the skills tab. The
+ *    cost is that a hidden pane keeps re-rendering on projection frames —
+ *    bounded, because the whole tab still renders nothing while `visible` is
+ *    false (see `SummaryTab`).
+ * 2. **The parent repeats its children's gates.** A section that hides itself
+ *    leaves the tab strip pointing at an empty pane, so the availability
+ *    question is answered here with the SAME readers and resolvers the children
+ *    use. `tests/reference-section.spec.tsx` pins both sides against the same
+ *    fixtures — if a child gate ever drifts from this one, that test goes red
+ *    rather than the UI growing a dead tab.
+ *
+ * Colours come from `--dsw-alias-*` tokens only (skin contract).
+ */
+import { createElement } from 'react'
+import { useCallback, useState } from 'react'
+import type { CSSProperties, KeyboardEvent, ReactNode } from 'react'
+import type { Context } from '@deepseek-ai/cordis'
+import { SKILL_USAGE_KEY } from '../../projection/keys'
+import { useProjectionValue } from '../use-projection'
+import { readSkillUsage } from './skill-usage'
+import { SEARCH_REFS_KEY, readSearchRefs } from './search-refs'
+import { MEMORY_RECALL_KEY, readRecall } from './memory-recall'
+import { MEMORY_SLOTS_KEY, readSlots } from './memory-slots'
+import { resolveShowMemoryRecall, resolveShowMemorySlots } from '../scope-face'
+import { useConfigFlag } from './use-config-flag'
+import { SkillUsageSection } from './SkillUsageSection'
+import { SearchRefSection } from './SearchRefSection'
+import { MemoryRecallSection } from './MemoryRecallSection'
+import { MemorySlotsSection } from './MemorySlotsSection'
+import type { FeedbackFetch } from './recall-feedback'
+
+export interface ReferenceSectionProps {
+  /** The DSH locale lookup, passed down from `apply`. */
+  t: (key: string) => string
+  /** The client root context (the tab body's only way to reach services). */
+  ctx?: Context
+  /** The session this tab is scoped to. */
+  scope?: { readonly sessionId?: string }
+  /** The rating transport, handed straight to the recall pane. */
+  fetchImpl?: FeedbackFetch
+}
+
+/** Which pane is showing. Three values, no fourth tab by design. */
+export type ReferenceTab = 'skills' | 'memory' | 'search'
+
+const SECTION_STYLE: CSSProperties = {
+  flexShrink: 0,
+  borderBottom: '1px solid var(--dsw-alias-border-secondary)',
+}
+
+const HEADER_STYLE: CSSProperties = {
+  padding: '10px 12px 0',
+  color: 'var(--dsw-alias-label-secondary)',
+  fontSize: 12,
+  fontWeight: 600,
+}
+
+/** The tab strip: flush-left, same gutter as section headers. */
+const TABS_STYLE: CSSProperties = {
+  display: 'flex',
+  gap: 4,
+  padding: '6px 12px 0',
+}
+
+/** One tab. Selected gets a hairline of secondary label; never a colour literal. */
+const TAB_STYLE: CSSProperties = {
+  background: 'none',
+  border: 'none',
+  borderBottom: '1px solid transparent',
+  font: 'inherit',
+  fontSize: 12,
+  color: 'var(--dsw-alias-label-tertiary)',
+  cursor: 'pointer',
+  padding: '4px 8px 6px',
+}
+
+const TAB_ACTIVE_STYLE: CSSProperties = {
+  ...TAB_STYLE,
+  borderBottom: '1px solid var(--dsw-alias-label-secondary)',
+  color: 'var(--dsw-alias-label-primary)',
+  fontWeight: 600,
+}
+
+const ORDER: readonly ReferenceTab[] = ['skills', 'memory', 'search']
+
+/**
+ * The references section. All hooks run before any early return, so the tab
+ * strip can disappear (no capability at all) without ever changing hook order.
+ *
+ * @param props - translation, client context, session scope, rating transport.
+ */
+export function ReferenceSection(props: ReferenceSectionProps): ReactNode {
+  const { t, ctx, scope, fetchImpl } = props
+  const [tab, setTab] = useState<ReferenceTab>('skills')
+
+  // The same three reads the children make, used only to decide whether the
+  // strip has anything to point at.
+  const skillsLive = readSkillUsage(useProjectionValue(ctx, scope?.sessionId, SKILL_USAGE_KEY)) !== undefined
+  const searchLive = readSearchRefs(useProjectionValue(ctx, scope?.sessionId, SEARCH_REFS_KEY)) !== undefined
+  const recallFrame = readRecall(useProjectionValue(ctx, scope?.sessionId, MEMORY_RECALL_KEY))
+  const slotsFrame = readSlots(useProjectionValue(ctx, scope?.sessionId, MEMORY_SLOTS_KEY))
+  const recallOn = useConfigFlag(ctx, resolveShowMemoryRecall) !== false
+  const slotsOn = useConfigFlag(ctx, resolveShowMemorySlots) === true
+  const memoryLive = (recallFrame !== undefined && recallOn) || (slotsFrame !== undefined && slotsOn)
+  const live: Record<ReferenceTab, boolean> = { skills: skillsLive, memory: memoryLive, search: searchLive }
+  // 记住的选择可能因能力变化而消失（例如关掉记忆开关）：退到第一个可用页签。
+  const active: ReferenceTab = live[tab] ? tab : ORDER.find(id => live[id]) ?? 'skills'
+
+  const onTabsKeyDown = useCallback((event: KeyboardEvent<HTMLDivElement>): void => {
+    // 左右方向键在“可用页签”里循环：能力缺席的页签不该被键盘走到。
+    if (event.key !== 'ArrowLeft' && event.key !== 'ArrowRight') return
+    event.preventDefault()
+    const shown = ORDER.filter(id => live[id])
+    if (shown.length < 2) return
+    const at = shown.indexOf(active)
+    const step = event.key === 'ArrowRight' ? 1 : shown.length - 1
+    setTab(shown[(at + step) % shown.length])
+  }, [live, active])
+
+  // Nothing to reference — no provider in the composition, or both switched off.
+  if (!skillsLive && !memoryLive && !searchLive) return null
+
+  const tabButton = (id: ReferenceTab, label: string): ReactNode => createElement(
+    'button',
+    {
+      key: id,
+      type: 'button',
+      role: 'tab',
+      id: `dsh-brief-reference-tab-${id}`,
+      'aria-selected': active === id,
+      'aria-controls': `dsh-brief-reference-pane-${id}`,
+      style: active === id ? TAB_ACTIVE_STYLE : TAB_STYLE,
+      'data-dsh-brief-sidebar': `reference-tab-${id}`,
+      onClick: () => { setTab(id) },
+    },
+    label,
+  )
+
+  return createElement(
+    'div',
+    { style: SECTION_STYLE, 'data-dsh-brief-sidebar': 'references-section' },
+    createElement('div', { style: HEADER_STYLE }, t('section.references')),
+    createElement(
+      'div',
+      {
+        role: 'tablist',
+        'aria-label': t('section.references'),
+        style: TABS_STYLE,
+        onKeyDown: onTabsKeyDown,
+        'data-dsh-brief-sidebar': 'reference-tabs',
+      },
+      skillsLive && tabButton('skills', t('references.tabSkills')),
+      // 每个页签各自条件化：只有一侧能力时不该留个点了就空的页签。
+      memoryLive && tabButton('memory', t('references.tabMemory')),
+      searchLive && tabButton('search', t('references.tabSearch')),
+    ),
+    skillsLive && createElement(
+      'div',
+      {
+        role: 'tabpanel',
+        id: 'dsh-brief-reference-pane-skills',
+        'aria-labelledby': 'dsh-brief-reference-tab-skills',
+        hidden: active !== 'skills',
+        style: active === 'skills' ? undefined : { display: 'none' },
+        'data-dsh-brief-sidebar': 'reference-pane-skills',
+      },
+      createElement(SkillUsageSection, { t, ctx, scope, hideHeader: true }),
+    ),
+    memoryLive && createElement(
+      'div',
+      {
+        role: 'tabpanel',
+        id: 'dsh-brief-reference-pane-memory',
+        'aria-labelledby': 'dsh-brief-reference-tab-memory',
+        hidden: active !== 'memory',
+        style: active === 'memory' ? undefined : { display: 'none' },
+        'data-dsh-brief-sidebar': 'reference-pane-memory',
+      },
+      // 两条记忆链各有自己的标题：召回与常驻槽位是不同事实，合成一节会糊掉。
+      createElement(MemoryRecallSection, { t, ctx, scope, fetchImpl }),
+      createElement(MemorySlotsSection, { t, ctx, scope }),
+    ),
+    searchLive && createElement(
+      'div',
+      {
+        role: 'tabpanel',
+        id: 'dsh-brief-reference-pane-search',
+        'aria-labelledby': 'dsh-brief-reference-tab-search',
+        hidden: active !== 'search',
+        style: active === 'search' ? undefined : { display: 'none' },
+        'data-dsh-brief-sidebar': 'reference-pane-search',
+      },
+      createElement(SearchRefSection, { t, ctx, scope, hideHeader: true }),
+    ),
+  )
+}

package/src/client/summary/SearchRefSection.tsx

@@ -0,0 +1,241 @@
+/**
+ * The search-reference section: the `dshSummarySearchRefs` projection drawn as
+ * one tab of the references section.
+ *
+ * It answers "what did this session pull in from outside": the queries it ran
+ * through `advanced_search`, and the sources those searches returned. Two
+ * groups, because they are two different facts — a query says what was asked,
+ * a source says what came back, and an older `dsh-free-search` without
+ * `presentationMeta` produces queries with no sources at all. That degraded
+ * case is stated rather than hidden, because an empty source list would
+ * otherwise read as "the search found nothing".
+ *
+ * Optional on both sides: no registry, or a host half that never registered the
+ * unit, means the client reads capability absence and the section hides.
+ *
+ * Two contracts inherited from the recall section:
+ * - **no native `title` attribute** — the whole text rides the row or is left
+ *   out; an unskinable tooltip would overlap the plugin's own surfaces;
+ * - **colours from `--dsw-alias-*` tokens only** (skin contract).
+ *
+ * Source links are untrusted external data, so only `http`/`https` become
+ * anchors (see `safeHref`) and they open with `rel="noreferrer noopener"`.
+ */
+import { createElement } from 'react'
+import type { CSSProperties, ReactNode } from 'react'
+import type { Context } from '@deepseek-ai/cordis'
+import { SEARCH_REFS_KEY } from '../../projection/keys'
+import { useProjectionValue } from '../use-projection'
+import { GroupHeader } from './FoldToggle'
+import { expandCount, expandTotal } from '../locales'
+import { isLatestSource, readSearchRefs, safeHref } from './search-refs'
+
+export interface SearchRefSectionProps {
+  /** The DSH locale lookup, passed down from `apply`. */
+  t: (key: string) => string
+  /** The client root context (the tab body's only way to reach services). */
+  ctx?: Context
+  /** The session this tab is scoped to. */
+  scope?: { readonly sessionId?: string }
+  /** Drop the section header (the references tab already names it). */
+  hideHeader?: boolean
+}
+
+const SECTION_STYLE: CSSProperties = {
+  flexShrink: 0,
+  borderBottom: '1px solid var(--dsw-alias-border-secondary)',
+}
+
+const HEADER_STYLE: CSSProperties = {
+  padding: '10px 12px 0',
+  color: 'var(--dsw-alias-label-secondary)',
+  fontSize: 12,
+  fontWeight: 600,
+}
+
+const LIST_STYLE: CSSProperties = {
+  listStyle: 'none',
+  margin: 0,
+  padding: '6px 0',
+  display: 'flex',
+  flexDirection: 'column',
+}
+
+const ROW_STYLE: CSSProperties = {
+  display: 'flex',
+  alignItems: 'flex-start',
+  gap: 8,
+  padding: '6px 12px',
+}
+
+const QUERY_STYLE: CSSProperties = {
+  minWidth: 0,
+  flex: '1 1 auto',
+  overflowWrap: 'anywhere',
+  color: 'var(--dsw-alias-label-secondary)',
+}
+
+/** The source title, one line: the host and URL carry the identification. */
+const TITLE_STYLE: CSSProperties = {
+  minWidth: 0,
+  flex: '1 1 auto',
+  display: '-webkit-box',
+  WebkitLineClamp: 2,
+  WebkitBoxOrient: 'vertical',
+  overflow: 'hidden',
+  color: 'var(--dsw-alias-label-secondary)',
+}
+
+const SNIPPET_STYLE: CSSProperties = {
+  margin: 0,
+  minWidth: 0,
+  overflowWrap: 'anywhere',
+  color: 'var(--dsw-alias-label-tertiary)',
+  fontSize: 11,
+  lineHeight: '16px',
+}
+
+const META_STYLE: CSSProperties = {
+  flexShrink: 0,
+  color: 'var(--dsw-alias-label-tertiary)',
+  fontSize: 11,
+  lineHeight: '18px',
+  whiteSpace: 'nowrap',
+}
+
+/** The "本轮" pill: same form as the skill tag, tertiary emphasis. */
+const TAG_STYLE: CSSProperties = {
+  flexShrink: 0,
+  color: 'var(--dsw-alias-label-tertiary)',
+  border: '1px solid var(--dsw-alias-label-tertiary)',
+  borderRadius: 999,
+  padding: '0 6px',
+  fontSize: 11,
+  lineHeight: '16px',
+  whiteSpace: 'nowrap',
+}
+
+const FOOTER_STYLE: CSSProperties = {
+  padding: '0 12px 10px',
+  color: 'var(--dsw-alias-label-tertiary)',
+  fontSize: 11,
+}
+
+const EMPTY_STYLE: CSSProperties = {
+  margin: '0 auto',
+  padding: 24,
+  maxWidth: 460,
+  textAlign: 'center',
+  color: 'var(--dsw-alias-label-tertiary)',
+  lineHeight: 1.7,
+  fontSize: 12,
+}
+
+/**
+ * The search-reference section. The subscription is unconditional (a plain
+ * listener, not IO); the view decides whether anything is drawn.
+ *
+ * @param props - translation, client context, session scope, header switch.
+ */
+export function SearchRefSection(props: SearchRefSectionProps): ReactNode {
+  const { t, ctx, scope, hideHeader = false } = props
+
+  const view = readSearchRefs(useProjectionValue(ctx, scope?.sessionId, SEARCH_REFS_KEY))
+
+  // Capability absent — the optional unit never registered. Hide, don't nag.
+  if (view === undefined) return null
+
+  if (view.queries.length === 0 && view.sources.length === 0) {
+    return createElement(
+      'div',
+      { style: SECTION_STYLE, 'data-dsh-brief-sidebar': 'search-refs-section' },
+      !hideHeader && createElement('div', { style: HEADER_STYLE }, t('section.searchRefs')),
+      createElement(
+        'div',
+        { style: EMPTY_STYLE },
+        createElement('div', { style: { marginBottom: 6, color: 'var(--dsw-alias-label-secondary)' } }, t('searchRefs.empty')),
+        createElement('div', null, t('searchRefs.emptyHint')),
+      ),
+    )
+  }
+
+  const body: ReactNode[] = []
+
+  if (view.queries.length > 0) {
+    body.push(createElement(GroupHeader, {
+      key: 'qh',
+      text: expandCount(t('searchRefs.queryGroup'), view.queries.length),
+      marker: 'search-refs-query-group',
+    }))
+    body.push(createElement(
+      'ul',
+      { key: 'ql', style: LIST_STYLE },
+      view.queries.map(row => createElement(
+        'li',
+        { key: `${row.turn}:${row.query}`, style: ROW_STYLE, 'data-dsh-brief-sidebar': 'search-refs-query' },
+        createElement('span', { style: QUERY_STYLE }, row.query),
+        createElement('span', { style: META_STYLE }, expandCount(t('searchRefs.hits'), row.hits)),
+      )),
+    ))
+  }
+
+  if (view.sources.length > 0) {
+    body.push(createElement(GroupHeader, {
+      key: 'sh',
+      text: expandCount(t('searchRefs.sourceGroup'), view.sources.length),
+      marker: 'search-refs-source-group',
+    }))
+    body.push(createElement(
+      'ul',
+      { key: 'sl', style: LIST_STYLE },
+      view.sources.map(item => {
+        const href = safeHref(item.url)
+        const label = item.title ?? item.url
+        const link = href === undefined
+          // A non-web scheme (or a malformed URL) from a provider stays text:
+          // it must not become a clickable thing in the user's sidebar.
+          ? createElement('span', { style: TITLE_STYLE }, label)
+          : createElement(
+            'a',
+            { style: TITLE_STYLE, href, target: '_blank', rel: 'noreferrer noopener' },
+            label,
+          )
+        return createElement(
+          'li',
+          { key: item.url, style: ROW_STYLE, 'data-dsh-brief-sidebar': 'search-refs-source' },
+          createElement(
+            'div',
+            { style: { minWidth: 0, flex: '1 1 auto', display: 'flex', flexDirection: 'column', gap: 2 } },
+            link,
+            createElement('span', { style: META_STYLE }, item.host),
+            item.snippet !== undefined && createElement('p', { style: SNIPPET_STYLE }, item.snippet),
+          ),
+          isLatestSource(view, item.url) && createElement('span', { style: TAG_STYLE }, t('searchRefs.latestTag')),
+        )
+      }),
+    ))
+  } else {
+    // 有查询无来源：老版 dsh-free-search 不发 meta。说清楚，别让人以为搜了没结果。
+    body.push(createElement(
+      'div',
+      { key: 'ns', style: FOOTER_STYLE, 'data-dsh-brief-sidebar': 'search-refs-no-sources' },
+      t('searchRefs.noSourcesHint'),
+    ))
+  }
+
+  // 列表有上限，页脚说真数：只有真数超过列表长度时才出现，免得两个数字打架。
+  if (view.queryTotal > view.queries.length || view.sourceTotal > view.sources.length) {
+    body.push(createElement(
+      'div',
+      { key: 'cap', style: FOOTER_STYLE, 'data-dsh-brief-sidebar': 'search-refs-capped' },
+      expandTotal(t('searchRefs.capped'), Math.max(view.queryTotal, view.sourceTotal)),
+    ))
+  }
+
+  return createElement(
+    'div',
+    { style: SECTION_STYLE, 'data-dsh-brief-sidebar': 'search-refs-section' },
+    !hideHeader && createElement('div', { style: HEADER_STYLE }, t('section.searchRefs')),
+    ...body,
+  )
+}

package/src/client/summary/SkillUsageSection.tsx

@@ -43,6 +43,12 @@ export interface SkillUsageSectionProps {
   ctx?: Context
   /** The session this tab is scoped to. */
   scope?: { readonly sessionId?: string }
+  /**
+   * Drop the section header. The references tab already says “技能”, so
+   * repeating it as a heading inside the pane is noise; standalone renders
+   * (and every existing test) keep the default `false`.
+   */
+  hideHeader?: boolean
 }
 
 const SECTION_STYLE: CSSProperties = {
@@ -121,7 +127,7 @@ const EMPTY_STYLE: CSSProperties = {
  * @param props - translation, client context, session scope.
  */
 export function SkillUsageSection(props: SkillUsageSectionProps): ReactNode {
-  const { t, ctx, scope } = props
+  const { t, ctx, scope, hideHeader = false } = props
   const [availableOpen, setAvailableOpen] = useState(false)
 
   const view = readSkillUsage(useProjectionValue(ctx, scope?.sessionId, SKILL_USAGE_KEY))
@@ -137,7 +143,7 @@ export function SkillUsageSection(props: SkillUsageSectionProps): ReactNode {
   return createElement(
     'div',
     { style: SECTION_STYLE, 'data-dsh-brief-sidebar': 'skill-usage-section' },
-    createElement('div', { style: HEADER_STYLE }, t('section.skillUsage')),
+    !hideHeader && createElement('div', { style: HEADER_STYLE }, t('section.skillUsage')),
     view.session.length === 0 && createElement(
       'div',
       { style: EMPTY_STYLE },

package/src/client/summary/search-refs.ts

@@ -0,0 +1,116 @@
+/**
+ * The `dshSummarySearchRefs` projection — reading it.
+ *
+ * The unit is registered by THIS plugin's host half (key `dshSummarySearchRefs`):
+ * the queries this session ran through `advanced_search`, and the sources those
+ * searches brought back. It answers "what did the session pull in from outside"
+ * — where the skill tab says which instruction packs were loaded and the memory
+ * tab says which of the user's own knowledge was injected.
+ *
+ * Reading discipline, same as every other brief section:
+ * - `undefined` = the capability is ABSENT (no projection registry, or a frame
+ *   drifted past repair) → the tab hides;
+ * - empty lists = the honest empty state (the session has not searched yet);
+ * - a malformed row is dropped, never thrown.
+ *
+ * The module is deliberately PURE — no React, no context, no IO.
+ */
+import { SEARCH_REFS_KEY } from '../../projection/keys'
+import type { SearchRefItemView, SearchRefView, SearchQueryView } from '../../projection/keys'
+import { urlKey } from '../../projection/search-ref-fold'
+
+/** The key this plugin's client half subscribes to (re-exported for callers). */
+export { SEARCH_REFS_KEY }
+
+/** Whether a value is a non-negative safe integer (the view's counters). */
+function isCounter(value: unknown): value is number {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0
+}
+
+/** Narrow one source row; `undefined` = malformed, dropped. */
+function readItem(value: unknown): SearchRefItemView | undefined {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return undefined
+  const raw = value as Record<string, unknown>
+  if (typeof raw['url'] !== 'string' || raw['url'].length === 0) return undefined
+  if (typeof raw['host'] !== 'string') return undefined
+  if (typeof raw['query'] !== 'string') return undefined
+  if (!isCounter(raw['count']) || !isCounter(raw['lastTurn'])) return undefined
+  const item: { -readonly [K in keyof SearchRefItemView]: SearchRefItemView[K] } = {
+    url: raw['url'],
+    host: raw['host'],
+    query: raw['query'],
+    count: raw['count'],
+    lastTurn: raw['lastTurn'],
+  }
+  if (typeof raw['title'] === 'string' && raw['title'].length > 0) item.title = raw['title']
+  if (typeof raw['snippet'] === 'string' && raw['snippet'].length > 0) item.snippet = raw['snippet']
+  return item
+}
+
+/** Narrow one query row; `undefined` = malformed, dropped. */
+function readQuery(value: unknown): SearchQueryView | undefined {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return undefined
+  const raw = value as Record<string, unknown>
+  if (typeof raw['query'] !== 'string' || raw['query'].length === 0) return undefined
+  if (!isCounter(raw['turn']) || !isCounter(raw['hits'])) return undefined
+  return { query: raw['query'], turn: raw['turn'], hits: raw['hits'] }
+}
+
+/** The latest-turn key set, or `null` when absent OR drifted (only a tag rides it). */
+function readLatest(value: unknown): SearchRefView['latest'] {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return null
+  const raw = value as Record<string, unknown>
+  if (!isCounter(raw['turn']) || !Array.isArray(raw['urls'])) return null
+  return { turn: raw['turn'], urls: raw['urls'].filter((u): u is string => typeof u === 'string' && u.length > 0) }
+}
+
+/**
+ * Narrow a raw projection value into a search-reference view.
+ *
+ * @param value - the raw `unknown` snapshot of the `dshSummarySearchRefs` face.
+ * @returns the validated view, or `undefined` when the capability is absent.
+ */
+export function readSearchRefs(value: unknown): SearchRefView | undefined {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return undefined
+  const raw = value as Record<string, unknown>
+  if (!Array.isArray(raw['queries']) || !Array.isArray(raw['sources'])) return undefined
+  if (!isCounter(raw['queryTotal']) || !isCounter(raw['sourceTotal'])) return undefined
+  const queries: SearchQueryView[] = []
+  for (const entry of raw['queries']) {
+    const narrowed = readQuery(entry)
+    if (narrowed !== undefined) queries.push(narrowed)
+  }
+  const sources: SearchRefItemView[] = []
+  for (const entry of raw['sources']) {
+    const narrowed = readItem(entry)
+    if (narrowed !== undefined) sources.push(narrowed)
+  }
+  return {
+    latest: readLatest(raw['latest']),
+    queries,
+    sources,
+    queryTotal: raw['queryTotal'],
+    sourceTotal: raw['sourceTotal'],
+  }
+}
+
+/** Whether one source row was surfaced by the latest turn's searches. */
+export function isLatestSource(view: SearchRefView, url: string): boolean {
+  return view.latest?.urls.includes(urlKey(url)) === true
+}
+
+/**
+ * The href to render for a source URL, or `undefined` when it must not be a link.
+ *
+ * Search results are untrusted external data: a `javascript:` or `data:` URL in
+ * a provider response would otherwise become a clickable footgun in the user's
+ * own sidebar. Only web schemes get an anchor; everything else renders as text.
+ */
+export function safeHref(url: string): string | undefined {
+  try {
+    const parsed = new URL(url)
+    return parsed.protocol === 'https:' || parsed.protocol === 'http:' ? parsed.href : undefined
+  } catch {
+    return undefined
+  }
+}

package/src/index.ts

@@ -37,7 +37,7 @@
  */
 import type { Context } from '@deepseek-ai/cordis'
 import z from '@deepseek-ai/schemastery'
-import { registerDeliverablesProjection, registerSkillUsageProjection } from './projection/register'
+import { registerDeliverablesProjection, registerSearchRefProjection, registerSkillUsageProjection } from './projection/register'
 
 /** Profile row identity. */
 export const name = 'dsh-brief-sidebar'
@@ -68,4 +68,7 @@ export const Config = z.object({
 export function apply(ctx: Context): void {
   registerDeliverablesProjection(ctx)
   registerSkillUsageProjection(ctx)
+  // 搜索引用：本会话用 `advanced_search` 查了什么、取回了哪些来源。与技能一样
+  // 是可选贡献：没有 sessionProjections 服务的组合不注册也不影响本行加载。
+  registerSearchRefProjection(ctx)
 }

package/src/projection/keys.ts

@@ -22,6 +22,13 @@ export const DELIVERABLES_KEY = 'dshSummaryDeliverables'
  */
 export const SKILL_USAGE_KEY = 'dshSummarySkillUsage'
 
+/**
+ * The search-reference key (queries and returned sources of this session's
+ * `advanced_search` calls). Same rule as above: the name is ours, so no other
+ * host-side unit can answer for it by accident.
+ */
+export const SEARCH_REFS_KEY = 'dshSummarySearchRefs'
+
 /** Client view of the produced-file fold (JSON-safe). */
 export interface DeliverablesView {
   /** Paths produced in the latest turn, first-seen order (capped). */
@@ -63,3 +70,39 @@ export interface SkillUsageView {
   /** How many entries that frame published — may exceed `available.length`. */
   readonly availableCount: number
 }
+
+/** One external source a search brought back (wire view). */
+export interface SearchRefItemView {
+  /** The URL as published (host case and trailing slash normalised). */
+  readonly url: string
+  readonly host: string
+  readonly title?: string
+  /** Provider snippet, capped by the fold. */
+  readonly snippet?: string
+  /** The query that most recently surfaced it. */
+  readonly query: string
+  /** Settled searches that surfaced this source. */
+  readonly count: number
+  readonly lastTurn: number
+}
+
+/** One query the session ran, with how many sources it returned. */
+export interface SearchQueryView {
+  readonly query: string
+  readonly turn: number
+  readonly hits: number
+}
+
+/** Client view of the search-reference fold (JSON-safe). */
+export interface SearchRefView {
+  /** Normalised URL keys surfaced in the latest turn; `null` before the first turn. */
+  readonly latest: { readonly turn: number; readonly urls: readonly string[] } | null
+  /** Distinct queries, most recent first (capped). */
+  readonly queries: readonly SearchQueryView[]
+  /** Distinct sources, most recent first (capped). */
+  readonly sources: readonly SearchRefItemView[]
+  /** Distinct queries session-wide — may exceed `queries.length`. */
+  readonly queryTotal: number
+  /** Distinct sources session-wide — may exceed `sources.length`. */
+  readonly sourceTotal: number
+}