dsh-brief-sidebar 0.9.0 → 0.9.2

package/src/client/summary/FoldToggle.tsx

@@ -0,0 +1,114 @@
+/**
+ * The two group chrome pieces the summary sections share: a counted group
+ * title, and the toggle that folds a group away.
+ *
+ * Extracted because the deliverables section (本回合 / 更早改动) and the recall
+ * section (活跃召回 / 其余历史召回) now fold a history group the same way. Two
+ * private copies of the same button would drift the first time either section
+ * touches padding — and the whole point of the split is that a reader can tell
+ * "what is live now" from "what the session also contains" without learning a
+ * different layout per section.
+ *
+ * Colours come from `--dsw-alias-*` tokens only (skin contract, enforced by
+ * `tests/purity.spec.ts`).
+ */
+import { createElement } from 'react'
+import type { CSSProperties, ReactNode } from 'react'
+
+/** Section-level title under the section header: quieter, same left gutter. */
+const GROUP_HEADER_STYLE: CSSProperties = {
+  padding: '8px 12px 0',
+  color: 'var(--dsw-alias-label-tertiary)',
+  fontSize: 11,
+  fontWeight: 600,
+}
+
+/** The fold switch: full-width hit area, tertiary text, chevron at the end. */
+const TOGGLE_STYLE: CSSProperties = {
+  background: 'none',
+  border: 'none',
+  font: 'inherit',
+  fontSize: 12,
+  color: 'var(--dsw-alias-label-tertiary)',
+  cursor: 'pointer',
+  display: 'flex',
+  alignItems: 'center',
+  gap: 4,
+  padding: '6px 12px',
+  textAlign: 'left',
+  width: 'calc(100% - 24px)',
+}
+
+/** The note beside a folded group (e.g. how many the capped list left out). */
+const CAPTION_STYLE: CSSProperties = {
+  padding: '0 12px 6px',
+  color: 'var(--dsw-alias-label-tertiary)',
+  fontSize: 11,
+  lineHeight: '16px',
+}
+
+const CHEVRON_STYLE = (open: boolean): CSSProperties => ({
+  flexShrink: 0,
+  transition: 'transform 0.16s',
+  transform: open ? 'rotate(180deg)' : 'none',
+})
+
+/**
+ * A counted group title. Renders nothing when the group is empty — an empty
+ * "活跃召回 · 0" line would ask the reader to explain a heading rather than read
+ * a fact.
+ * @param props - already-interpolated text, plus an optional DOM marker.
+ */
+export function GroupHeader(props: { text: string; marker?: string }): ReactNode {
+  if (props.text.length === 0) return null
+  return createElement(
+    'div',
+    {
+      style: GROUP_HEADER_STYLE,
+      'data-dsh-brief-sidebar': props.marker ?? 'group-header',
+    },
+    props.text,
+  )
+}
+
+/**
+ * The fold switch. `marker` is what tests (and the browser probe) click, so it
+ * belongs to the component rather than to either caller's markup.
+ * @param props - label, current state, DOM marker, click handler.
+ */
+export function FoldToggle(props: {
+  label: string
+  open: boolean
+  marker: string
+  onToggle(): void
+}): ReactNode {
+  const { label, open, marker } = props
+  return createElement(
+    'button',
+    {
+      type: 'button',
+      'aria-expanded': open,
+      style: TOGGLE_STYLE,
+      'data-dsh-brief-sidebar': marker,
+      onClick: () => { props.onToggle() },
+    },
+    label,
+    createElement(
+      'svg',
+      { width: 10, height: 10, viewBox: '0 0 16 16', 'aria-hidden': true, style: CHEVRON_STYLE(open) },
+      createElement('path', {
+        d: 'M4 6l4 4 4-4',
+        fill: 'none',
+        stroke: 'currentColor',
+        strokeWidth: 1.5,
+        strokeLinecap: 'round',
+        strokeLinejoin: 'round',
+      }),
+    ),
+  )
+}
+
+/** A quiet caption under a group, used for the "the list is capped" note. */
+export function GroupCaption(props: { text: string; marker: string }): ReactNode {
+  return createElement('div', { style: CAPTION_STYLE, 'data-dsh-brief-sidebar': props.marker }, props.text)
+}

package/src/client/summary/MemoryRecallSection.tsx

@@ -53,6 +53,7 @@ import { resolveShowMemoryRecall } from '../scope-face'
 import { useConfigFlag } from './use-config-flag'
 import { useProjectionValue } from '../use-projection'
 import { expandCount } from '../locales'
+import { FoldToggle, GroupHeader } from './FoldToggle'
 
 export interface MemoryRecallSectionProps {
   /** The DSH locale lookup, passed down from `apply`. */
@@ -309,6 +310,7 @@ function RecallRow(props: {
   item: MemoryRecallItem
   selected: boolean
   stale: boolean
+  wasSuperseded: boolean
   pending: boolean
   armed: boolean
   mark: number | undefined
@@ -320,7 +322,7 @@ function RecallRow(props: {
   onEnter(el: HTMLElement): void
   onLeave(): void
 }): ReactNode {
-  const { item, selected, stale, mark, error, t } = props
+  const { item, selected, stale, wasSuperseded, mark, error, t } = props
   const scenario = item.scenario === undefined ? undefined : item.scenario.join(' · ')
   const markText = mark === undefined
     ? undefined
@@ -361,6 +363,13 @@ function RecallRow(props: {
         scenario,
       ),
       staleText !== undefined && createElement('span', { style: MARK_STYLE }, staleText),
+      // “正文已被摘要取代”是行自己的事实，得写在行上：否则展开历史组后，
+      // 读者只能靠位置猜哪一行不在上下文里。
+      wasSuperseded && createElement(
+        'span',
+        { style: TYPE_STYLE, 'data-dsh-brief-sidebar': 'recall-superseded-tag' },
+        t('recall.supersededTag'),
+      ),
       markText !== undefined && createElement('span', { style: MARK_STYLE }, markText),
       error !== undefined && createElement(
         'span',
@@ -408,6 +417,8 @@ export function MemoryRecallSection(props: MemoryRecallSectionProps): ReactNode
   // Flipped once by a 404: the composition's prime-memory cannot take marks,
   // so the section goes back to being the plain read-only list it was.
   const [writeAbsent, setWriteAbsent] = useState(false)
+  // 历史召回组默认折叠：它们已不在上下文里，但仍属于“本会话见过什么”的一部分。
+  const [historyOpen, setHistoryOpen] = useState(false)
 
   const show = useConfigFlag(ctx, resolveShowMemoryRecall)
   const view: MemoryRecallView | undefined = readRecall(
@@ -493,8 +504,11 @@ export function MemoryRecallSection(props: MemoryRecallSectionProps): ReactNode
   // A `superseded` row is different — its text is no longer in context — so it is
   // hidden, and the footer reports the count so nothing disappears silently.
   const isStale = (item: MemoryRecallItem): boolean => item.retired === true || staleIds.includes(item.id)
+  // 两组按“正文还在不在上下文”分：活跃 = 未取代（或被退场的例外，裁决凭证必须留下）；
+  // 其余历史 = 被摘要取代且未被裁决退场的，它们收进开关后面而不是只报个计数。
   const rows = view.items.filter(item => item.superseded !== true || item.retired === true)
-  const hidden = view.items.length - rows.length
+  const historyRows = view.items.filter(item => item.superseded === true && item.retired !== true)
+  const hidden = historyRows.length
 
   if (rows.length === 0) {
     return createElement(
@@ -510,6 +524,34 @@ export function MemoryRecallSection(props: MemoryRecallSectionProps): ReactNode
         },
         hidden > 0 ? expandCount(t('recall.supersededHidden'), hidden) : t('recall.empty'),
       ),
+      // 空态下历史组仍要能展开：否则“全都被取代”的会话永远读不到自己召回过什么。
+      historyRows.length > 0 && createElement(FoldToggle, {
+        label: expandCount(t('recall.historyGroup'), historyRows.length),
+        open: historyOpen,
+        marker: 'recall-history-toggle',
+        onToggle: () => { setHistoryOpen(current => !current) },
+      }),
+      historyOpen && createElement(
+        'ul',
+        { style: LIST_STYLE },
+        historyRows.map(item => createElement(RecallRow, {
+          key: item.id,
+          item,
+          selected: false,
+          stale: isStale(item),
+          wasSuperseded: true,
+          pending: false,
+          armed: false,
+          mark: undefined,
+          error: undefined,
+          rating: false,
+          t,
+          onSelect: () => {},
+          onScore: () => {},
+          onEnter: () => {},
+          onLeave: () => {},
+        })),
+      ),
     )
   }
 
@@ -518,6 +560,11 @@ export function MemoryRecallSection(props: MemoryRecallSectionProps): ReactNode
     { style: SECTION_STYLE, 'data-dsh-brief-sidebar': 'memory-recall-section' },
     createElement('div', { style: HEADER_STYLE }, t('section.memoryRecall')),
     rating && createElement('div', { style: HINT_STYLE }, `${t('recall.rateHint')}${t('recall.strikeHint')}`),
+    // 活跃组计数只说“仍在上下文”的那些，注入总数归页脚，两个数各说各的。
+    rows.length > 0 && createElement(GroupHeader, {
+      text: expandCount(t('recall.activeGroup'), rows.length),
+      marker: 'recall-active-group',
+    }),
     createElement(
       'ul',
       { style: LIST_STYLE },
@@ -526,6 +573,7 @@ export function MemoryRecallSection(props: MemoryRecallSectionProps): ReactNode
         item,
         selected: selectedId === item.id,
         stale: isStale(item),
+        wasSuperseded: item.superseded === true,
         pending: pendingId === item.id,
         armed: armed && selectedId === item.id,
         mark: marks[item.id] ?? item.rating,
@@ -538,6 +586,35 @@ export function MemoryRecallSection(props: MemoryRecallSectionProps): ReactNode
         onLeave,
       })),
     ),
+    historyRows.length > 0 && createElement(FoldToggle, {
+      label: expandCount(t('recall.historyGroup'), historyRows.length),
+      open: historyOpen,
+      marker: 'recall-history-toggle',
+      onToggle: () => { setHistoryOpen(current => !current) },
+    }),
+    historyOpen && createElement(
+      'ul',
+      { style: LIST_STYLE },
+      historyRows.map(item => createElement(RecallRow, {
+        key: item.id,
+        item,
+        // 历史行不开评分：退场与相关度都是对“还在上下文里的那条”的裁决，
+        // 正文已被取代的行再标一次也不会回到上下文，只会让人以为还能救。
+        selected: false,
+        stale: isStale(item),
+        wasSuperseded: true,
+        pending: false,
+        armed: false,
+        mark: undefined,
+        error: undefined,
+        rating: false,
+        t,
+        onSelect: () => {},
+        onScore: () => {},
+        onEnter: () => {},
+        onLeave: () => {},
+      })),
+    ),
     createElement(
       'div',
       { style: FOOTER_STYLE },

package/src/client/summary/SkillUsageSection.tsx

@@ -3,15 +3,23 @@
  * part of the summary tab.
  *
  * Where `MemoryRecallSection` answers "what memories did the model see", this
- * answers "which instruction packs did it pull" — the skills this session
- * loaded through the host's `skill` tool, with how often and when.
+ * answers "which instruction packs entered the context, and which ones were on
+ * the menu". Two groups, deliberately not merged:
+ *
+ * - **已引用** — the skill's instructions reached the conversation, either
+ *   because the model called the `skill` tool or because the user invoked it
+ *   directly (the host then injects `<skill_content>` and tells the model not
+ *   to call the tool — reading only the tool would miss over half of those
+ *   sessions, measured on 250 real ones).
+ * - **本会话可用** — the session's current catalog. Available is NOT used: the
+ *   model may never touch any of these, so it is collapsed behind a counted
+ *   toggle and never mixed into the reference rows.
  *
  * Like the deliverables section this is an OPTIONAL capability on both sides:
  * no projection registry (or a host half that never registered the unit) means
  * the client reads capability absence and the section hides. No settings switch
  * gates it either — the list is a read-only fact about the session, not a
- * preference, and a section that only ever shows what already happened costs
- * nothing to leave on.
+ * preference.
  *
  * Two contracts this row honours, both learned on the recall section:
  * - **no native `title` attribute** — it paints an unskinable tooltip that
@@ -19,11 +27,14 @@
  * - **colours from `--dsw-alias-*` tokens only** (skin contract).
  */
 import { createElement } from 'react'
+import { useState } from 'react'
 import type { CSSProperties, ReactNode } from 'react'
 import type { Context } from '@deepseek-ai/cordis'
 import { SKILL_USAGE_KEY } from '../../projection/keys'
 import { useProjectionValue } from '../use-projection'
-import { expandPair, readSkillUsage } from './skill-usage'
+import { availableExcept, expandPair, readSkillUsage } from './skill-usage'
+import { GroupCaption, GroupHeader, FoldToggle } from './FoldToggle'
+import { expandCount } from '../locales'
 
 export interface SkillUsageSectionProps {
   /** The DSH locale lookup, passed down from `apply`. */
@@ -111,32 +122,32 @@ const EMPTY_STYLE: CSSProperties = {
  */
 export function SkillUsageSection(props: SkillUsageSectionProps): ReactNode {
   const { t, ctx, scope } = props
+  const [availableOpen, setAvailableOpen] = useState(false)
 
   const view = readSkillUsage(useProjectionValue(ctx, scope?.sessionId, SKILL_USAGE_KEY))
 
   // Capability absent — the optional unit never registered. Hide, don't nag.
   if (view === undefined) return null
 
-  if (view.session.length === 0) {
-    return createElement(
-      'div',
-      { style: SECTION_STYLE, 'data-dsh-brief-sidebar': 'skill-usage-section' },
-      createElement('div', { style: HEADER_STYLE }, t('section.skillUsage')),
-      createElement(
-        'div',
-        { style: EMPTY_STYLE },
-        createElement('div', { style: { marginBottom: 6, color: 'var(--dsw-alias-label-secondary)' } }, t('skillUsage.empty')),
-        createElement('div', null, t('skillUsage.emptyHint')),
-      ),
-    )
-  }
-
+  const referenced = view.session.map(entry => entry.name)
+  // 可用组只列未被引用的那些：同一个技能不该占两行。
+  const rest = availableExcept(view.available, referenced)
   const latestNames = view.latest?.names ?? []
 
   return createElement(
     'div',
     { style: SECTION_STYLE, 'data-dsh-brief-sidebar': 'skill-usage-section' },
     createElement('div', { style: HEADER_STYLE }, t('section.skillUsage')),
+    view.session.length === 0 && createElement(
+      'div',
+      { style: EMPTY_STYLE },
+      createElement('div', { style: { marginBottom: 6, color: 'var(--dsw-alias-label-secondary)' } }, t('skillUsage.empty')),
+      createElement('div', null, t('skillUsage.emptyHint')),
+    ),
+    view.session.length > 0 && createElement(GroupHeader, {
+      text: expandCount(t('skillUsage.invokedGroup'), view.session.length),
+      marker: 'skill-usage-invoked-group',
+    }),
     createElement(
       'ul',
       { style: LIST_STYLE },
@@ -148,7 +159,27 @@ export function SkillUsageSection(props: SkillUsageSectionProps): ReactNode {
         latestNames.includes(entry.name) && createElement('span', { style: TAG_STYLE }, t('skillUsage.latestTag')),
       )),
     ),
+    rest.length > 0 && createElement(FoldToggle, {
+      label: expandCount(t('skillUsage.availableGroup'), rest.length),
+      open: availableOpen,
+      marker: 'skill-usage-available-toggle',
+      onToggle: () => { setAvailableOpen(current => !current) },
+    }),
+    // 清单有上限：开关行说收了多少个名字，附注说这一帧真发了多少。
+    rest.length > 0 && view.availableCount > view.available.length && createElement(GroupCaption, {
+      text: expandCount(t('skillUsage.availableCapped'), view.availableCount),
+      marker: 'skill-usage-available-capped',
+    }),
+    availableOpen && createElement(
+      'ul',
+      { style: LIST_STYLE },
+      rest.map(name => createElement(
+        'li',
+        { key: name, style: ROW_STYLE, 'data-dsh-brief-sidebar': 'skill-usage-available-row' },
+        createElement('span', { style: NAME_STYLE }, name),
+      )),
+    ),
     // 列表有上限，页脚说真数：加载次数与去重后的技能数各归各。
-    createElement('div', { style: FOOTER_STYLE }, expandPair(t('skillUsage.count'), view.callTotal, view.sessionTotal)),
+    view.session.length > 0 && createElement('div', { style: FOOTER_STYLE }, expandPair(t('skillUsage.count'), view.callTotal, view.sessionTotal)),
   )
 }

package/src/client/summary/skill-usage.ts

@@ -49,6 +49,19 @@ function readLatest(value: unknown): SkillUsageView['latest'] {
   return { turn: raw['turn'], names: raw['names'].filter((n): n is string => typeof n === 'string' && n.length > 0) }
 }
 
+/**
+ * The available-skill list of a frame, or `[]` when the frame carries none.
+ *
+ * Absent-by-age is the important case: a host half older than this reader
+ * publishes no `available` field at all, and that must NOT void the whole view
+ * — the session's references are still true. Only a drifted (non-array) value
+ * reads as "nothing known", never as "nothing available".
+ */
+function readAvailable(value: unknown): readonly string[] {
+  if (!Array.isArray(value)) return []
+  return value.filter((n): n is string => typeof n === 'string' && n.length > 0)
+}
+
 /**
  * Narrow a raw projection value into a skill-usage view.
  *
@@ -67,7 +80,33 @@ export function readSkillUsage(value: unknown): SkillUsageView | undefined {
     const narrowed = readEntry(entry)
     if (narrowed !== undefined) session.push(narrowed)
   }
-  return { latest: readLatest(raw['latest']), session, sessionTotal: raw['sessionTotal'], callTotal: raw['callTotal'] }
+  const available = readAvailable(raw['available'])
+  // The count rides with the list; without a list there is no count to trust.
+  const availableCount = available.length === 0 ? 0 : (isCounter(raw['availableCount']) ? raw['availableCount'] : available.length)
+  return {
+    latest: readLatest(raw['latest']),
+    session,
+    sessionTotal: raw['sessionTotal'],
+    callTotal: raw['callTotal'],
+    available,
+    availableCount,
+  }
+}
+
+/**
+ * The available list minus the names already shown as referenced.
+ *
+ * One skill must not occupy a row in both groups: the reference row is the
+ * stronger fact, and a duplicate under "available" would read as "the model
+ * had a choice it didn't make".
+ *
+ * @param available - the session's current catalog names, in catalog order.
+ * @param referenced - names the fold counted as loaded or invoked.
+ * @returns the remaining catalog names, order preserved.
+ */
+export function availableExcept(available: readonly string[], referenced: readonly string[]): string[] {
+  const seen = new Set(referenced)
+  return available.filter(name => !seen.has(name))
 }
 
 /**

package/src/projection/keys.ts

@@ -47,12 +47,19 @@ export interface SkillUsageEntryView {
 
 /** Client view of the skill-usage fold (JSON-safe). */
 export interface SkillUsageView {
-  /** Skills loaded in the latest turn; `null` before the first `turn/start`. */
+  /** Skills referenced in the latest turn; `null` before the first `turn/start`. */
   readonly latest: { readonly turn: number; readonly names: readonly string[] } | null
-  /** Distinct loaded skills, most recently used first (capped). */
+  /** Distinct referenced skills, most recently used first (capped). */
   readonly session: readonly SkillUsageEntryView[]
-  /** Distinct loaded skills session-wide — may exceed `session.length`. */
+  /** Distinct referenced skills session-wide — may exceed `session.length`. */
   readonly sessionTotal: number
-  /** Successful skill loads session-wide. */
+  /** Successful references session-wide, both channels included. */
   readonly callTotal: number
+  /**
+   * The skills this session was OFFERED, per its latest catalog frame (capped).
+   * Available is not referenced: the model may never use any of these.
+   */
+  readonly available: readonly string[]
+  /** How many entries that frame published — may exceed `available.length`. */
+  readonly availableCount: number
 }

package/src/projection/register.ts

@@ -110,6 +110,11 @@ const skillStateSchema = z.object({
   items: z.array(z.object({ name: z.string(), count: z.number(), lastTurn: z.number() })),
   sessionTotal: z.number(),
   callTotal: z.number(),
+  // Defaults, not requirements: a state persisted by the pre-0.9.2 shape has no
+  // catalog fields, and replaying it must not fail (the session's references
+  // are still true; only the "available" knowledge starts empty).
+  catalog: z.array(z.string()).default([]),
+  catalogCount: z.number().default(0),
 })
 
 /** Zod schema of the skill-usage wire view. */
@@ -118,6 +123,8 @@ const skillViewSchema = z.object({
   session: z.array(z.object({ name: z.string(), count: z.number(), lastTurn: z.number() })),
   sessionTotal: z.number(),
   callTotal: z.number(),
+  available: z.array(z.string()),
+  availableCount: z.number(),
 })
 
 /** Same reference-stability memo as above, for the skill-usage unit. */
@@ -134,6 +141,8 @@ function skillView(state: SkillUsageState): SkillUsageView {
     session: state.items.slice(0, SKILL_CAPS.view),
     sessionTotal: state.sessionTotal,
     callTotal: state.callTotal,
+    available: state.catalog.slice(0, SKILL_CAPS.available),
+    availableCount: state.catalogCount,
   }
   skillViewMemo.set(state, next)
   return next
@@ -155,8 +164,9 @@ export function registerSkillUsageProjection(ctx: Context): void {
       init: () => initSkillUsageState(),
       apply: applySkillUsageEvent,
       wire: { viewSchema: skillViewSchema, view: skillView },
-      // 0 = the first published shape of this key.
-      stateVersion: 0,
+      // 1 = the shape gained the catalog fields (`catalog`/`catalogCount`); the
+      // state schema defaults them so a version-0 state still replays.
+      stateVersion: 1,
     })
   })
 }