@tita-agent/dsh-data-table 0.0.0-stage → 0.2.0

package/src/version/diff.ts

@@ -0,0 +1,169 @@
+/**
+ * What changed between two snapshots (docs/issue/0022 P2).
+ *
+ * Pure, and the only place that decides what counts as a change: a cell's
+ * value, a sheet's identity, or the structure around it (merges, freeze,
+ * row/column sizes). The Version list and the comparison bar both read this
+ * shape, so the answer to "what changed" is defined once.
+ *
+ * `scopes` narrows the walk to the sheets and ranges an operation actually
+ * touched; without it the whole workbook is compared.
+ */
+import type { WorkbookChange, WorkbookOperationPayload, WorkbookOperationType, WorkbookRange } from '../types.ts'
+
+/**
+ * How many differences one diff reports.
+ *
+ * A bound is necessary — the list travels in an HTTP response and an Agent
+ * result — but an *unsignalled* bound is not: a caller receiving exactly this
+ * many cannot tell a comparison that found this many from one that stopped
+ * looking, so `describeSnapshotReplace` stated `修改 500 个单元格` for a save that
+ * touched thousands, and the comparison bar showed the same number as though it
+ * were the whole answer. Callers ask {@link diffReachedLimit}.
+ */
+export const DIFF_CHANGE_LIMIT = 500
+
+/** Whether a diff stopped at the limit, so its count is a lower bound. */
+export function diffReachedLimit(changes: readonly WorkbookChange[]): boolean {
+  return changes.length >= DIFF_CHANGE_LIMIT
+}
+import { asWorkbookSnapshot, toCellValue } from '../contract/snapshots.ts'
+
+export interface WorkbookDiffScope {
+  ref: string
+  wholeSheet: boolean
+  ranges: WorkbookRange[]
+}
+
+/** Collect the smallest safe regions touched by a proposal. */
+export function collectDiffScopes(operations: Array<{ type: WorkbookOperationType; payload: WorkbookOperationPayload }>): Map<string, WorkbookDiffScope> {
+  const scopes = new Map<string, WorkbookDiffScope>()
+  const add = (ref: string | undefined, range?: WorkbookRange, wholeSheet = false): void => {
+    if (ref === undefined || ref.trim().length === 0) return
+    const key = ref.trim()
+    const scope = scopes.get(key) ?? { ref: key, wholeSheet: false, ranges: [] }
+    scope.wholeSheet ||= wholeSheet
+    if (range !== undefined) scope.ranges.push(range)
+    scopes.set(key, scope)
+  }
+  for (const operation of operations) {
+    const payload = operation.payload
+    const ref = payload.sheetId ?? payload.sheetName ?? (operation.type === 'create_sheet' ? payload.name : undefined)
+    if (operation.type === 'batch') {
+      for (const child of payload.operations ?? []) {
+        const nested = collectDiffScopes([child])
+        for (const scope of nested.values()) {
+          const target = scopes.get(scope.ref) ?? { ref: scope.ref, wholeSheet: false, ranges: [] }
+          target.wholeSheet ||= scope.wholeSheet
+          target.ranges.push(...scope.ranges)
+          scopes.set(scope.ref, target)
+        }
+      }
+      continue
+    }
+    if (operation.type === 'update_cells') {
+      const cells = payload.cells ?? []
+      if (cells.length > 0) {
+        add(ref, {
+          startRow: Math.min(...cells.map(cell => cell.row)),
+          startColumn: Math.min(...cells.map(cell => cell.column)),
+          endRow: Math.max(...cells.map(cell => cell.row)),
+          endColumn: Math.max(...cells.map(cell => cell.column)),
+        })
+      }
+      continue
+    }
+    if (operation.type === 'clear_range' || operation.type === 'delete_cells' || operation.type === 'format_cells'
+      || operation.type === 'merge_cells' || operation.type === 'unmerge_cells' || operation.type === 'sort_range'
+      || operation.type === 'set_hyperlink' || operation.type === 'remove_hyperlink' || operation.type === 'remove_duplicates') {
+      add(ref, payload.range ?? payload.merge)
+      continue
+    }
+    if (operation.type === 'set_column_width' || operation.type === 'set_row_height' || operation.type === 'freeze_panes'
+      || operation.type === 'append_rows' || operation.type === 'insert_rows' || operation.type === 'delete_rows'
+      || operation.type === 'insert_columns' || operation.type === 'delete_columns') {
+      add(ref, undefined, true)
+      continue
+    }
+    if (operation.type === 'create_sheet' || operation.type === 'delete_sheet' || operation.type === 'rename_sheet') add(ref, undefined, true)
+  }
+  return scopes
+}
+
+/** No value at either end: `toCellValue` answers `null` for a valueless cell. */
+function isBlankValue(value: unknown): boolean {
+  return value === null || value === undefined || String(value) === ''
+}
+
+export function diffWorkbookSnapshots(before: unknown, after: unknown, scopes?: Map<string, WorkbookDiffScope>): WorkbookChange[] {
+  const left = asWorkbookSnapshot(before)
+  const right = asWorkbookSnapshot(after)
+  const changes: WorkbookChange[] = []
+  const sheetIds = new Set([...left.sheetOrder, ...right.sheetOrder])
+  for (const sheetId of sheetIds) {
+    const beforeSheet = left.sheets[sheetId]
+    const afterSheet = right.sheets[sheetId]
+    if (beforeSheet === undefined || afterSheet === undefined) {
+      changes.push({ kind: 'sheet', sheetId, sheetName: afterSheet?.name ?? beforeSheet?.name, description: afterSheet === undefined ? '删除 sheet' : '新增 sheet' })
+      continue
+    }
+    const scope = scopes === undefined || scopes.size === 0
+      ? undefined
+      : [...scopes.values()].find(candidate => candidate.ref === sheetId || candidate.ref === beforeSheet.name || candidate.ref === afterSheet.name)
+    if (scopes !== undefined && scopes.size > 0 && scope === undefined) continue
+    if (beforeSheet.name !== afterSheet.name) changes.push({ kind: 'sheet', sheetId, sheetName: afterSheet.name, before: beforeSheet.name, after: afterSheet.name, description: '重命名 sheet' })
+    for (const key of ['mergeData', 'freeze', 'columnData', 'rowData'] as const) {
+      if (JSON.stringify(beforeSheet[key]) !== JSON.stringify(afterSheet[key])) {
+        changes.push({ kind: 'structure', sheetId, sheetName: afterSheet.name, before: beforeSheet[key], after: afterSheet[key], description: key === 'mergeData' ? '调整合并单元格' : key === 'freeze' ? '调整冻结窗格' : '调整行列尺寸' })
+      }
+    }
+    const rows = scope?.wholeSheet || scope === undefined
+      ? new Set([...Object.keys(beforeSheet.cellData ?? {}), ...Object.keys(afterSheet.cellData ?? {})])
+      : new Set(scope.ranges.flatMap(range => {
+        const result: string[] = []
+        for (let row = range.startRow; row <= range.endRow; row += 1) result.push(String(row))
+        return result
+      }))
+    for (const row of rows) {
+      const columns = scope?.wholeSheet || scope === undefined
+        ? new Set([...Object.keys(beforeSheet.cellData?.[row] ?? {}), ...Object.keys(afterSheet.cellData?.[row] ?? {})])
+        : new Set(scope.ranges.flatMap(range => {
+          const result: string[] = []
+          for (let column = range.startColumn; column <= range.endColumn; column += 1) result.push(String(column))
+          return result
+        }))
+      for (const column of columns) {
+        const beforeCell = beforeSheet.cellData?.[row]?.[column]
+        const afterCell = afterSheet.cellData?.[row]?.[column]
+        if (JSON.stringify(beforeCell) === JSON.stringify(afterCell)) continue
+        const beforeValue = toCellValue(beforeCell)
+        const afterValue = toCellValue(afterCell)
+        // A cell with no value on either side that only gained a style is not a
+        // difference worth reporting. Formatting a range writes a style id into
+        // every cell it covers, empty ones included, and those entries used to
+        // dominate the count: 473 of them against 11 real edits, which made the
+        // comparison bar unreadable (GUI feedback 2026-09-19).
+        //
+        // `toCellValue` answers `null` for a valueless cell, so "blank" here has
+        // to mean null/empty and not just `undefined` — testing for `undefined`
+        // compiles, passes the unit tests, and silently changes nothing.
+        if (isBlankValue(beforeValue) && isBlankValue(afterValue)) continue
+        // Same value, different cell object: the formatting moved, the content
+        // did not. Reported as 样式 rather than as a modification.
+        const styleOnly = beforeValue === afterValue
+        changes.push({
+          kind: 'cell',
+          sheetId,
+          sheetName: afterSheet.name,
+          row: Number(row),
+          column: Number(column),
+          before: beforeValue,
+          after: afterValue,
+          ...(styleOnly ? { styleOnly: true } : {}),
+        })
+        if (changes.length >= DIFF_CHANGE_LIMIT) return changes
+      }
+    }
+  }
+  return changes
+}

package/src/version/grouping.ts

@@ -0,0 +1,96 @@
+/**
+ * Physical revisions → the logical Versions a person sees (docs/issue/0022 P2).
+ *
+ * One user save can fill a single open Version across several requests, and one
+ * Agent semantic batch is a Version with N replayable Steps. This is the only
+ * place that decides where one Version ends and the next begins, so the list,
+ * the comparison bar and the Agent's history tool cannot disagree about it.
+ */
+import { operationSummary, versionKindOfOperations, workbookOperationSteps } from '../contract/operations.ts'
+import { describeSessionSteps } from './summary.ts'
+import type { WorkbookHistoryVersion, WorkbookOperation } from '../types.ts'
+
+export function operationVersionId(operation: WorkbookOperation): string {
+  return operation.versionId ?? `revision:${operation.revision}`
+}
+
+export function historyVersionStatus(status: WorkbookOperation['versionStatus']): WorkbookHistoryVersion['status'] {
+  return status === 'temporary' || status === undefined ? (status === 'temporary' ? 'open' : 'final') : status
+}
+
+/** Group physical revisions into the logical Version shown to users. A user
+ * save can fill one open Version over several requests; an Agent semantic
+ * batch is one Version with N replayable Steps. */
+export function historyVersionsFromOperations(
+  source: WorkbookOperation[],
+  canReplay: (revision: number) => boolean,
+  activeRevisions: Set<number>,
+): WorkbookHistoryVersion[] {
+  const groups = new Map<string, WorkbookOperation[]>()
+  for (const operation of source.slice().sort((left, right) => left.revision - right.revision)) {
+    const id = operationVersionId(operation)
+    const group = groups.get(id)
+    if (group === undefined) groups.set(id, [operation])
+    else group.push(operation)
+  }
+  const entries = [...groups.entries()]
+  const numberByVersionId = new Map(entries.map(([versionId], index) => [versionId, index + 1]))
+  /** Display number of the Version whose revision range covers `revision`. */
+  const numberAtRevision = (revision: number | undefined): number | undefined => {
+    if (revision === undefined) return undefined
+    for (const [versionId, operations] of entries) {
+      const first = operations[0]
+      const last = operations.at(-1)
+      if (first === undefined || last === undefined) continue
+      if (revision >= first.revision && revision <= last.revision) return numberByVersionId.get(versionId)
+    }
+    return undefined
+  }
+  return entries.map(([versionId, operations], index) => {
+    const first = operations[0]
+    const last = operations.at(-1)
+    if (first === undefined || last === undefined) throw new Error('历史版本缺少操作')
+    const steps = operations.flatMap(operation => workbookOperationSteps(operation))
+    const storedSummary = last.versionSummary ?? first.versionSummary ?? (operations.length === 1
+      ? operationSummary(first)
+      : describeSessionSteps(steps))
+    const branch = operations.every(operation => activeRevisions.has(operation.revision)) ? 'main' : 'superseded'
+    const storedStatus = historyVersionStatus(last.versionStatus)
+    const intent = last.versionIntent ?? first.versionIntent
+    const agentRunId = last.agentRunId ?? first.agentRunId
+    const lineage = last.lineage ?? first.lineage
+    const restoredFromRevision = last.restoredFromRevision ?? first.restoredFromRevision
+    const restoredFromNumber = numberAtRevision(restoredFromRevision)
+    // A stored `恢复到 revision 48` predates the v3 wording rule; show the
+    // Version number instead of the internal revision (PRD v3 §7.3).
+    const summary = restoredFromNumber !== undefined && /^恢复到 revision \d+$/.test(storedSummary)
+      ? `恢复到 V${restoredFromNumber}`
+      : storedSummary
+    // v3 tier. Explicit when written; pre-v3 logs are derived from the facts
+    // that already separated a deliberate Version from editing-session churn.
+    const kind = versionKindOfOperations(operations)
+    return {
+      versionId,
+      // Creation order: a restore lands after every existing Version, so its
+      // number is always fresh and old numbers are never reused (PRD §3.2).
+      number: index + 1,
+      startRevision: first.revision,
+      revision: last.revision,
+      parentRevision: first.parentRevision ?? Math.max(0, first.revision - 1),
+      actor: first.actor,
+      timestamp: first.timestamp,
+      summary,
+      kind,
+      ...(intent === undefined ? {} : { intent }),
+      ...(agentRunId === undefined ? {} : { agentRunId }),
+      ...(lineage === undefined ? {} : { lineage }),
+      ...(restoredFromRevision === undefined ? {} : { restoredFromRevision }),
+      ...(restoredFromNumber === undefined ? {} : { restoredFromNumber }),
+      stepCount: steps.length,
+      steps: steps.map((step, index) => ({ index, opId: step.opId, type: step.type, summary: operationSummary(step), ...(step.revision === undefined ? {} : { revision: step.revision }) })),
+      canPreview: canReplay(last.revision),
+      status: branch === 'superseded' ? 'superseded' : storedStatus,
+      branch,
+    }
+  })
+}

package/src/version/records.ts

@@ -0,0 +1,113 @@
+/**
+ * A Version as the wire presents it (docs/issue/0022 P2/P3).
+ *
+ * The history endpoint and the Agent's history tool answer the same question,
+ * so they must produce the same record shape — including the content hash that
+ * lets a client prove it has the right Version without materializing a snapshot.
+ * That is why this is not part of either transport.
+ *
+ * `node:crypto` is deliberate and is pure computation: the hash is of the
+ * Version's *inputs* (its checkpoint plus its ordered Step ids), not of a file.
+ */
+import { createHash } from 'node:crypto'
+import type { VersionRecord } from '#contracts'
+import type { WorkbookCheckpoint, WorkbookHistoryVersion, WorkbookOperation } from '../types.ts'
+
+/** Follow logical parents from the current head. Versions skipped by a
+ * rollback remain in history but are no longer part of the active main line. */
+export function activeHistoryRevisions(currentRevision: number, operations: Map<number, WorkbookOperation>): Set<number> {
+  const active = new Set<number>()
+  let cursor = currentRevision
+  const visited = new Set<number>()
+  while (cursor > 0 && !visited.has(cursor)) {
+    visited.add(cursor)
+    const operation = operations.get(cursor)
+    if (operation === undefined) break
+    active.add(cursor)
+    cursor = operation.parentRevision ?? Math.max(0, cursor - 1)
+  }
+  return active
+}
+
+export function canReplayHistoryRevision(
+  targetRevision: number,
+  currentRevision: number,
+  checkpoints: number[],
+  operations: Map<number, WorkbookOperation>,
+): boolean {
+  if (targetRevision === currentRevision) return true
+  const checkpoint = checkpoints.filter(revision => revision <= targetRevision).at(-1)
+  if (checkpoint === undefined) return false
+  for (let revision = checkpoint + 1; revision <= targetRevision; revision += 1) {
+    const operation = operations.get(revision)
+    if (operation === undefined || (operation.type === 'snapshot_replace' && operation.payload.snapshot === undefined)) return false
+  }
+  return true
+}
+
+/**
+ * Stable content hash for a Version (PRD §3.2): the checkpoint the Version
+ * starts from, plus the ordered opIds applied on top of it. It is a pure
+ * function of the Version's inputs, so the history list never has to
+ * materialise or copy a workbook snapshot into the browser (PRD §11).
+ */
+export function versionContentHash(version: WorkbookHistoryVersion, checkpointHash: (revision: number) => string): string {
+  const chain = version.steps.map(step => step.opId).join(',')
+  return createHash('sha256').update(`${checkpointHash(version.revision)}#${version.startRevision}#${chain}`).digest('hex')
+}
+
+/** Map the Data Sheet history shape onto the shared Version record (PRD §7.1). */
+export function toVersionRecords(
+  versions: WorkbookHistoryVersion[],
+  workbookId: string,
+  checkpointHash: (revision: number) => string,
+): VersionRecord[] {
+  return versions.map(version => {
+    const status: VersionRecord['status'] = version.status === 'final'
+      ? 'committed'
+      : version.status === 'temporary'
+        ? 'open'
+        : version.status
+    return {
+      versionId: version.versionId,
+      artifactKind: 'workbook',
+      artifactId: workbookId,
+      number: version.number,
+      startRevision: version.startRevision,
+      endRevision: version.revision,
+      // The unified record points at the reinstated Version, like other versioned artifacts
+      // record does; `r48` only survives on the legacy history shape.
+      ...(version.restoredFromRevision === undefined
+        ? {}
+        : { restoredFromVersionId: versions.find(candidate => candidate.revision === version.restoredFromRevision)?.versionId ?? `r${version.restoredFromRevision}` }),
+      status,
+      kind: version.kind,
+      actor: version.actor === 'agent' ? 'agent' : 'user',
+      summary: version.summary,
+      ...(version.intent === undefined ? {} : { intent: version.intent }),
+      stepCount: version.stepCount,
+      contentHash: versionContentHash(version, checkpointHash),
+      createdAt: version.timestamp,
+      ...(status === 'committed' || status === 'restored' ? { committedAt: version.timestamp } : {}),
+      ...(version.lineage === undefined ? {} : { lineage: version.lineage }),
+      replayable: version.canPreview,
+    }
+  })
+}
+
+/** Memoized checkpoint hash lookup: hashes each snapshot at most once. */
+export function checkpointHasher(checkpoints: WorkbookCheckpoint[]): (revision: number) => string {
+  const ascending = checkpoints.slice().sort((left, right) => left.revision - right.revision)
+  const cache = new Map<number, string>()
+  const genesis = createHash('sha256').update('genesis').digest('hex')
+  return (revision: number): string => {
+    const cached = cache.get(revision)
+    if (cached !== undefined) return cached
+    const base = ascending.filter(checkpoint => checkpoint.revision <= revision).at(-1)
+    const hash = base === undefined
+      ? genesis
+      : createHash('sha256').update(JSON.stringify(base.snapshot)).digest('hex')
+    cache.set(revision, hash)
+    return hash
+  }
+}

package/src/version/session.ts

@@ -0,0 +1,90 @@
+/**
+ * The editing session: when a Version opens, what closes it, and the shape of
+ * the version fields on the wire (docs/issue/0022 P2).
+ *
+ * Two boundaries close a session (PRD v3.5 D21) — the idle window and the Step
+ * cap — and nothing else does. `settleIdleUserVersions` exists because the write
+ * path can only fork a session when the *next* write arrives: an abandoned tab
+ * left a Version `open` forever, so settling is evaluated lazily at the moment
+ * the user can observe the outcome (reading the version list).
+ */
+import { VERSION_MAX_STEPS, type VersionKind } from '#contracts'
+import { cloneSnapshot } from '../contract/snapshots.ts'
+import { isIdlePast } from '../store/retention.ts'
+import { readWorkbook } from '../store/read.ts'
+import { writeWorkbook } from '../store/write.ts'
+import type { WorkbookMeta, WorkbookVersionStatus } from '../types.ts'
+
+// Safety cap only: idle and semantic boundaries are the primary Version
+// boundary now (PRD §4.1). Shared through data-contracts.
+export const VERSION_STEP_LIMIT = VERSION_MAX_STEPS
+
+/** Old logs use `temporary`; expose it as the clearer `open` lifecycle state. */
+export function normalizeVersionStatus(status: WorkbookVersionStatus | undefined): WorkbookVersionStatus | undefined {
+  return status === 'temporary' ? 'open' : status
+}
+
+/** v3 tier on the wire; unknown values are dropped rather than guessed. */
+export function normalizeVersionKind(kind: VersionKind | undefined): VersionKind | undefined {
+  return kind === 'named' || kind === 'auto' ? kind : undefined
+}
+
+export function isOpenVersionStatus(status: WorkbookVersionStatus | undefined): boolean {
+  return status === 'open' || status === 'temporary'
+}
+
+export function optionalVersionText(value: string | undefined, name: string, maxLength: number): string | undefined {
+  if (value === undefined) return undefined
+  const normalized = value.trim()
+  if (normalized.length === 0 || normalized.length > maxLength) throw new Error(`${name} 必须是 1 到 ${maxLength} 字符的字符串`)
+  return normalized
+}
+
+export function finalizeOpenUserVersions(meta: WorkbookMeta): void {
+  const openVersionIds = new Set((meta.operations ?? [])
+    .filter(operation => operation.actor === 'user' && isOpenVersionStatus(operation.versionStatus) && operation.versionId !== undefined)
+    .map(operation => operation.versionId as string))
+  if (openVersionIds.size === 0) return
+  meta.operations = (meta.operations ?? []).map(operation => openVersionIds.has(operation.versionId ?? '')
+    ? { ...operation, versionStatus: 'final' as const }
+    : operation)
+}
+
+/**
+ * Close every user Version whose last Step is older than the idle window
+ * (PRD v3.3 D21).
+ *
+ * The write path already forks a session when the *next* write arrives after a
+ * pause, but nothing settled a session that was simply abandoned — leaving the
+ * tab open, or closing it, left the Version `open` forever, so "停手 10 分钟"
+ * never actually produced a saved Version. Settling is evaluated lazily when
+ * the version list is read, which is the moment a user can observe the outcome.
+ *
+ * Idempotent: a second call finds nothing open past the window and writes
+ * nothing.
+ */
+export async function settleIdleUserVersions(workbookId: string, nowMs = Date.now()): Promise<number> {
+  const meta = await readWorkbook(workbookId)
+  if (meta === null) return 0
+  const open = (meta.operations ?? []).filter(operation => operation.actor === 'user' && isOpenVersionStatus(operation.versionStatus))
+  if (open.length === 0) return 0
+  const lastAt = new Map<string, string>()
+  for (const operation of open) {
+    const id = operation.versionId ?? `revision:${operation.revision}`
+    const previous = lastAt.get(id)
+    if (previous === undefined || operation.timestamp > previous) lastAt.set(id, operation.timestamp)
+  }
+  const idle = [...lastAt.entries()].filter(([, timestamp]) => isIdlePast(timestamp, nowMs)).map(([id]) => id)
+  if (idle.length === 0) return 0
+  const next = cloneSnapshot(meta) as WorkbookMeta
+  for (const id of idle) finalizeVersion(next, id)
+  await writeWorkbook(next, { persistSnapshot: false, persistCheckpoints: false })
+  return idle.length
+}
+
+/** Finalize exactly one open Version, leaving other Versions untouched. */
+export function finalizeVersion(meta: WorkbookMeta, versionId: string): void {
+  meta.operations = (meta.operations ?? []).map(operation => operation.versionId === versionId && isOpenVersionStatus(operation.versionStatus)
+    ? { ...operation, versionStatus: 'final' as const }
+    : operation)
+}

package/src/version/summary.ts

@@ -0,0 +1,117 @@
+/**
+ * How a Version and its Steps are described in words (docs/issue/0022 P2).
+ *
+ * This is the copy the user reads in the version list, so it is deliberately a
+ * module of its own: PRD 0002 changed it four times, and each of those changes
+ * is a change to *one* file rather than to the repository layer.
+ *
+ * A one-line summary of an *operation* (before it is diffed) lives in
+ * `contract/operations.ts` instead — `store/write.ts` embeds it in the sidecar
+ * index, and a store module may not import upward into `version/`.
+ */
+import { cellAddress, formatCellReference } from '#contracts'
+import { DIFF_CHANGE_LIMIT, diffReachedLimit, diffWorkbookSnapshots } from './diff.ts'
+import type { WorkbookOperation } from '../types.ts'
+
+/**
+ * Describe a whole-snapshot save by what it actually changed (PRD v3.1 §7).
+ * The browser persists most edits this way, and 「替换 workbook 快照」 told the
+ * user nothing; the diff is already computed for Version comparison, so a Step
+ * can say `修改 1 个单元格：Sheet1!C3` — an address the user can paste straight
+ * into the formula bar, unlike the former `Sheet1!R3C2`.
+ */
+export function describeSnapshotReplace(before: unknown, after: unknown): string {
+  const changes = diffWorkbookSnapshots(before, after)
+  if (changes.length === 0) return '保存内容（无变化）'
+  // Content edits are 修改; everything else is 样式. Splitting them is what
+  // makes the sentence true: a cell that only had its formatting touched is not
+  // a modification of anything the reader can see in the grid.
+  const cells = changes.filter(change => change.kind === 'cell' && change.styleOnly !== true)
+  const styled = changes.filter(change => change.kind !== 'cell' || change.styleOnly === true)
+  const sheetOf = (change: { sheetName?: string; sheetId?: string }): string => change.sheetName ?? change.sheetId ?? 'sheet'
+  // One sheet is named once: `发版日志!B27、B28、B29` reads like a spreadsheet
+  // selection, while `发版日志!B27、发版日志!B28` repeats the same word per cell.
+  const head = changes.slice(0, 3)
+  const sheets = new Set(head.map(change => (change.kind === 'cell' ? sheetOf(change) : '')))
+  const labels = head.map(change => change.kind === 'cell'
+    ? (sheets.size === 1
+        ? cellAddress(change.row ?? 0, change.column ?? 0)
+        : formatCellReference({ sheet: sheetOf(change), row: change.row ?? 0, column: change.column ?? 0 }))
+    : (change.description === undefined ? sheetOf(change) : `${sheetOf(change)}·${change.description}`))
+  const scope = sheets.size === 1 && [...sheets][0] !== '' ? `${[...sheets][0]}!` : ''
+  // Three structural changes in one sheet used to print `Sheet1、Sheet1、Sheet1`.
+  const distinct = [...new Set(labels)]
+  // A sheet being merged or frozen — or a cell that only had its formatting
+  // touched — is not a 修改 of anything: nothing about the *content* changed.
+  // The old headline said `修改 4 处结构变化`, which read as though the count
+  // were the verb's object, and it once reported `修改 496 个单元格` when 473 of
+  // those were styled-but-empty cells. Each bucket now carries its own verb.
+  // 结构 / 改变 → 样式 is the user's wording (GUI feedback 2026-09-19): it is
+  // the word they read cell-formatting adjustments as, and it covers the
+  // sheet-level ones too.
+  // `capped` is not the same as `truncated` below: that one is about the *sample*
+  // list being cut short, this one about the counts themselves being a floor.
+  const capped = diffReachedLimit(changes)
+  const headline = [
+    cells.length > 0 ? `修改 ${cells.length}${capped ? '+' : ''} 个单元格` : '',
+    styled.length > 0 ? `样式 ${styled.length}${capped ? '+' : ''} 处` : '',
+  ].filter(part => part !== '').join('、')
+  const truncated = changes.length > 3 || distinct.length < labels.length
+  const limitNote = capped ? `（差异已达 ${DIFF_CHANGE_LIMIT} 条上限，计数为下限）` : ''
+  return `${headline}：${scope}${distinct.join('、')}${truncated ? ' 等' : ''}${limitNote}`
+}
+
+/** One Step's kind → the bucket a session summary counts it in. */
+const SESSION_STEP_BUCKET: Readonly<Record<string, string>> = {
+  update_cells: '修改单元格',
+  append_rows: '追加行',
+  set_hyperlink: '设置超链接',
+  remove_hyperlink: '移除超链接',
+  snapshot_replace: '保存内容',
+  create_sheet: '新增 sheet',
+  delete_sheet: '删除 sheet',
+  rename_sheet: '重命名 sheet',
+}
+
+/**
+ * Fixed bucket order: what was edited first, then what the workbook is made of,
+ * then the presentation of a sheet. Map insertion order would have made the
+ * same session read differently depending on which Step happened to come first.
+ */
+const SESSION_BUCKET_ORDER = [
+  '修改单元格', '追加行', '设置超链接', '移除超链接', '保存内容',
+  '新增 sheet', '删除 sheet', '重命名 sheet',
+] as const
+
+/**
+ * Describe an editing session that was never given a name (PRD v3.3 D21, D22).
+ *
+ * It used to read `编辑会话 · 5 个 Step`, which stated the same count twice: the
+ * row's meta line immediately above it already says `用户 · 5 个 Step`, and the
+ * two lines are read together. A session has no single operation to quote, and
+ * diffing its two ends would mean two snapshot reads plus a diff per Version on
+ * every list request — but the *kinds* of its Steps are already in hand, and
+ * 「改了什么」 is the question the summary line is there to answer; the size of
+ * the session is what the meta line is for.
+ *
+ * An unknown Step type is counted rather than dropped: a summary that silently
+ * omits a kind of change is worse than one that admits it does not know it.
+ */
+export function describeSessionSteps(steps: readonly WorkbookOperation[]): string {
+  const counts = new Map<string, number>()
+  for (const step of steps) {
+    const bucket = SESSION_STEP_BUCKET[step.type] ?? '其他改动'
+    counts.set(bucket, (counts.get(bucket) ?? 0) + 1)
+  }
+  const buckets = [...counts.keys()].sort(
+    (left, right) => bucketRank(left) - bucketRank(right),
+  )
+  if (buckets.length === 0) return '编辑会话'
+  return `编辑会话：${buckets.map(bucket => `${bucket} ${counts.get(bucket) ?? 0} 次`).join('、')}`
+}
+
+/** Position in {@link SESSION_BUCKET_ORDER}; anything unlisted sorts last. */
+function bucketRank(bucket: string): number {
+  const at = SESSION_BUCKET_ORDER.indexOf(bucket as typeof SESSION_BUCKET_ORDER[number])
+  return at === -1 ? SESSION_BUCKET_ORDER.length : at
+}