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

package/src/tools/workbook-find.ts

@@ -0,0 +1,80 @@
+/**
+ * `workbook_find`: locate a value across sheets, cells or formulas
+ * (docs/issue/0022 P3b).
+ */
+import type { WorkbookRange } from '../types.ts'
+import { readWorkbook } from '../workbook-manager.ts'
+
+import { parseRange } from '../request-params.ts'
+import { asToolArguments, parseCount, parseNonEmptyString, sheetRefFromArguments, type ToolArguments } from './arguments.ts'
+
+export function parseFindScope(value: unknown): 'sheets' | 'cells' | 'formulas' {
+  if (value === undefined || value === null) return 'cells'
+  if (value === 'sheets' || value === 'cells' || value === 'formulas') return value
+  throw new Error('scope 必须是 sheets、cells 或 formulas')
+}
+
+export function parseFindMatch(value: unknown): 'contains' | 'exact' | 'regex' {
+  if (value === undefined || value === null) return 'contains'
+  if (value === 'contains' || value === 'exact' || value === 'regex') return value
+  throw new Error('match 必须是 contains、exact 或 regex')
+}
+
+export function textMatcher(query: string, match: 'contains' | 'exact' | 'regex'): (value: unknown) => boolean {
+  if (match === 'regex') {
+    let expression: RegExp
+    try { expression = new RegExp(query, 'i') } catch { throw new Error('query 不是有效的正则表达式') }
+    return value => expression.test(String(value ?? ''))
+  }
+  const needle = query.toLocaleLowerCase()
+  return value => {
+    const text = String(value ?? '').toLocaleLowerCase()
+    return match === 'exact' ? text === needle : text.includes(needle)
+  }
+}
+
+export function inRange(row: number, column: number, range: WorkbookRange | undefined): boolean {
+  return range === undefined || row >= range.startRow && row <= range.endRow && column >= range.startColumn && column <= range.endColumn
+}
+
+export async function findWorkbookContent(workbookId: string, args: ToolArguments): Promise<unknown> {
+  const meta = await readWorkbook(workbookId)
+  if (meta === null) throw new Error('工作簿不存在：' + workbookId)
+  const query = parseNonEmptyString(args.query, 'query')
+  const scope = parseFindScope(args.scope)
+  const match = parseFindMatch(args.match)
+  const matches = textMatcher(query, match)
+  const limit = args.limit === undefined ? 100 : Math.min(500, parseCount(args.limit))
+  const selectedSheet = sheetRefFromArguments(args, 'sheet')
+  const range = args.range === undefined ? undefined : parseRange(args.range)
+  const root = asToolArguments(meta.snapshot, 'workbook snapshot')
+  const sheets = asToolArguments(root.sheets, 'workbook snapshot.sheets') as Record<string, Record<string, unknown>>
+  const results: Array<Record<string, unknown>> = []
+  for (const [sheetId, sheet] of Object.entries(sheets)) {
+    const sheetName = typeof sheet.name === 'string' ? sheet.name : sheetId
+    if (selectedSheet !== undefined && selectedSheet !== sheetId && selectedSheet !== sheetName) continue
+    if (scope === 'sheets') {
+      if (matches(sheetName)) results.push({ sheetId, sheetName })
+      if (results.length >= limit) break
+      continue
+    }
+    const cellData = sheet.cellData
+    if (typeof cellData !== 'object' || cellData === null || Array.isArray(cellData)) continue
+    for (const [rowKey, line] of Object.entries(cellData as Record<string, unknown>)) {
+      const row = Number(rowKey)
+      if (!Number.isInteger(row) || typeof line !== 'object' || line === null || Array.isArray(line)) continue
+      for (const [columnKey, rawCell] of Object.entries(line as Record<string, unknown>)) {
+        const column = Number(columnKey)
+        if (!Number.isInteger(column) || !inRange(row, column, range)) continue
+        const cell = typeof rawCell === 'object' && rawCell !== null && !Array.isArray(rawCell) ? rawCell as Record<string, unknown> : {}
+        const candidate = scope === 'formulas' ? cell.f : cell.v
+        if (!matches(candidate)) continue
+        results.push({ sheetId, sheetName, row, column, value: cell.v ?? null, formula: typeof cell.f === 'string' ? cell.f : null })
+        if (results.length >= limit) break
+      }
+      if (results.length >= limit) break
+    }
+    if (results.length >= limit) break
+  }
+  return { ok: true, workbookId, revision: meta.revision ?? 0, query, scope, match, results, truncated: results.length >= limit }
+}

package/src/tools/workbook-history.ts

@@ -0,0 +1,63 @@
+/**
+ * `workbook_history`: the version list, one version, one Step, and a diff
+ * (docs/issue/0022 P3b). It answers with the same record shape the HTTP history
+ * endpoint returns, which is why `version/records.ts` owns that shape.
+ */
+import type { WorkbookOperation } from '../types.ts'
+import { readWorkbook, readWorkbookAtRevision, readWorkbookAtStep } from '../workbook-manager.ts'
+import { diffWorkbookSnapshots } from '../version/diff.ts'
+import { historyVersionsFromOperations } from '../version/grouping.ts'
+
+import { activeHistoryRevisions, canReplayHistoryRevision, checkpointHasher, toVersionRecords } from '../version/records.ts'
+import { parseIndex } from '../request-params.ts'
+import { parseCount, type ToolArguments } from './arguments.ts'
+
+
+export async function executeHistoryQuery(workbookId: string, args: ToolArguments): Promise<unknown> {
+  const action = args.action === undefined || args.action === null ? 'list' : args.action
+  if (action !== 'list' && action !== 'diff' && action !== 'replay') throw new Error('action 必须是 list、diff 或 replay')
+  if (action === 'diff') {
+    const fromRevision = parseIndex(args.fromRevision, 'fromRevision')
+    const toRevision = parseIndex(args.toRevision, 'toRevision')
+    if (fromRevision > toRevision) throw new Error('fromRevision 不得大于 toRevision')
+    const left = await readWorkbookAtRevision(workbookId, fromRevision)
+    const right = await readWorkbookAtRevision(workbookId, toRevision)
+    if (left === null || right === null) throw new Error('指定 revision 已被压缩或无法重放')
+    return { ok: true, action, workbookId, fromRevision, toRevision, changes: diffWorkbookSnapshots(left.snapshot, right.snapshot) }
+  }
+  if (action === 'replay') {
+    const rawRevision = args.revision ?? args.toRevision
+    const revision = parseIndex(rawRevision, 'revision')
+    if (args.step !== undefined && args.step !== null) {
+      const step = parseIndex(args.step, 'step')
+      const replay = await readWorkbookAtStep(workbookId, revision, step)
+      if (replay === null) throw new Error('指定 revision/step 已被压缩或无法重放')
+      return { ok: true, action, workbookId, ...replay }
+    }
+    const replay = await readWorkbookAtRevision(workbookId, revision)
+    if (replay === null) throw new Error('指定 revision 已被压缩或无法重放')
+    return { ok: true, action, workbookId, ...replay }
+  }
+
+  const meta = await readWorkbook(workbookId, { includeCheckpoints: true })
+  if (meta === null) throw new Error('工作簿不存在：' + workbookId)
+  const limit = args.limit === undefined ? 20 : Math.min(100, Math.max(1, parseCount(args.limit)))
+  const allOperations = (meta.operations ?? []).slice().sort((left, right) => left.revision - right.revision)
+  const currentRevision = meta.revision ?? 0
+  const byRevision = new Map(allOperations.map(operation => [operation.revision, operation]))
+  const active = activeHistoryRevisions(currentRevision, byRevision)
+  const checkpoints = (meta.checkpoints ?? []).map(checkpoint => checkpoint.revision).sort((left, right) => left - right)
+  const canReplay = (revision: number): boolean => canReplayHistoryRevision(revision, currentRevision, checkpoints, byRevision)
+  const fullVersions = historyVersionsFromOperations(allOperations, canReplay, active).slice(-limit)
+  const versions = fullVersions.map(({ steps: _steps, ...version }) => version)
+  return {
+    ok: true,
+    action,
+    workbookId,
+    revision: currentRevision,
+    versions,
+    // Unified cross-plugin model (PRD §7.1). `versions` stays for compatibility.
+    versionRecords: toVersionRecords(fullVersions, workbookId, checkpointHasher(meta.checkpoints ?? [])),
+    checkpoints,
+  }
+}

package/src/tools/workbook-read.ts

@@ -0,0 +1,210 @@
+/**
+ * `workbook_read`: one bounded look at a sheet, a range or a single cell
+ * (docs/issue/0022 P3b).
+ */
+import type { WorkbookRange } from '../types.ts'
+import type { SheetRef } from '#contracts'
+
+import { readWorkbook, readWorkbookRange, summarize } from '../workbook-manager.ts'
+import { parseIndex, parseRange } from '../request-params.ts'
+import { asToolArguments, sheetRefForSnapshot } from './arguments.ts'
+import { sheetOverviews } from './render.ts'
+
+export function parseReadIncludes(value: unknown): Set<string> {
+  if (value === undefined || value === null) return new Set()
+  if (!Array.isArray(value)) throw new Error('include 必须是字符串数组')
+  const allowed = new Set(['values', 'formulas', 'cells', 'styles', 'snapshot', 'backfill'])
+  const result = new Set<string>()
+  for (const item of value) {
+    if (typeof item !== 'string' || !allowed.has(item)) throw new Error('include 仅支持 values、formulas、cells、styles、snapshot、backfill')
+    result.add(item)
+  }
+  return result
+}
+
+export function snapshotSheet(snapshot: unknown, sheetRef: string): Record<string, unknown> {
+  const root = asToolArguments(snapshot, 'workbook snapshot')
+  const sheets = asToolArguments(root.sheets, 'workbook snapshot.sheets') as Record<string, Record<string, unknown>>
+  const direct = sheets[sheetRef]
+  if (direct !== undefined) return direct
+  const byName = Object.values(sheets).find(sheet => sheet.name === sheetRef)
+  if (byName === undefined) throw new Error('sheet 不存在：' + sheetRef)
+  return byName
+}
+
+export function snapshotCell(snapshot: unknown, sheetRef: string, row: number, column: number): Record<string, unknown> | undefined {
+  const sheet = snapshotSheet(snapshot, sheetRef)
+  const cellData = sheet.cellData
+  if (typeof cellData !== 'object' || cellData === null || Array.isArray(cellData)) return undefined
+  const line = (cellData as Record<string, unknown>)[String(row)]
+  if (typeof line !== 'object' || line === null || Array.isArray(line)) return undefined
+  const cell = (line as Record<string, unknown>)[String(column)]
+  return typeof cell === 'object' && cell !== null && !Array.isArray(cell) ? cell as Record<string, unknown> : undefined
+}
+
+export function styleMatrix(snapshot: unknown, sheetRef: string, range: WorkbookRange): unknown[][] {
+  const result: unknown[][] = []
+  for (let row = range.startRow; row <= range.endRow; row += 1) {
+    const line: unknown[] = []
+    for (let column = range.startColumn; column <= range.endColumn; column += 1) {
+      line.push(snapshotCell(snapshot, sheetRef, row, column)?.s ?? null)
+    }
+    result.push(line)
+  }
+  return result
+}
+
+/**
+ * Per-sheet backfill status for `workbook_read(kind: 'workbook')`
+ * (docs/issue/0011 I5 / T7).
+ *
+ * The agent kept a prose table of "which sheet still needs what" because the
+ * read surface could only show scale. This reports the four things that table
+ * tracked — data area, run provenance, run time and a conclusion block — so a
+ * workbook's completeness is visible without opening every sheet. `complete` is
+ * deliberately conservative: it is a hint, not a gate.
+ */
+export function sheetBackfillStatus(sheet: Record<string, unknown>): Record<string, unknown> {
+  const asRecord = (value: unknown): Record<string, unknown> | undefined =>
+    typeof value === 'object' && value !== null && !Array.isArray(value) ? value as Record<string, unknown> : undefined
+  const stats = asRecord(sheet.dataSheetStats)
+  const meta = asRecord(sheet.dataSheetMeta)
+  const schema = asRecord(sheet.dataSheetSchema)
+  const dataRows = typeof stats?.rowCount === 'number' && stats.rowCount >= 0 ? stats.rowCount : 0
+  const cellData = asRecord(sheet.cellData) ?? {}
+  // A conclusion block is not tracked anywhere in the snapshot: any write
+  // recomputes the row counts, so the counter cannot separate data from prose.
+  // What it can do is spot rows that do not span the data schema, which is the
+  // shape a conclusion row takes in these report sheets (row 0 is the header).
+  const schemaColumns = Array.isArray(schema?.columns) ? schema.columns.length : 0
+  let conclusionRows = 0
+  for (const [key, line] of Object.entries(cellData)) {
+    const row = Number(key)
+    if (!Number.isInteger(row) || row <= 0) continue
+    const cells = asRecord(line)
+    if (cells === undefined) continue
+    const filled = Object.values(cells).filter(cell => {
+      const value = asRecord(cell)?.v
+      return value !== undefined && value !== null && String(value).length > 0
+    }).length
+    if (filled === 0) continue
+    if (schemaColumns > 0 && filled >= schemaColumns) continue
+    conclusionRows += 1
+  }
+  const provenance = meta === undefined
+    ? null
+    : { source: meta.source ?? null, query: meta.query ?? null, notes: meta.notes ?? null }
+  return {
+    /** Highest row index holding content. Every write recomputes it, so it
+     * covers a conclusion block as well as the data — it is a bound, not a
+     * count of data rows. */
+    lastOccupiedRow: typeof stats?.rowCount === 'number' && stats.rowCount >= 0 ? stats.rowCount : 0,
+    columnCount: typeof stats?.columnCount === 'number' ? stats.columnCount : 0,
+    conclusionRows,
+    runAt: typeof meta?.generatedAt === 'string' ? meta.generatedAt : null,
+    provenance,
+    schemaUpdatedAt: typeof schema?.updatedAt === 'string' ? schema.updatedAt : null,
+    complete: (typeof stats?.rowCount === 'number' ? stats.rowCount : 0) > 0 && provenance !== null,
+  }
+}
+
+export async function readWorkbookTarget(workbookId: string, rawTarget: unknown, rawInclude: unknown): Promise<unknown> {
+  const meta = await readWorkbook(workbookId)
+  if (meta === null) throw new Error('工作簿不存在：' + workbookId)
+  const target = asToolArguments(rawTarget, 'target')
+  const kind = target.kind
+  if (kind !== 'workbook' && kind !== 'sheet' && kind !== 'range' && kind !== 'cells') {
+    throw new Error('target.kind 必须是 workbook、sheet、range 或 cells')
+  }
+  const include = parseReadIncludes(rawInclude)
+  const summary = summarize(meta)
+  const base = { ok: true, workbookId, revision: meta.revision ?? 0 }
+
+  if (kind === 'workbook') {
+    const sheets = sheetOverviews(meta.snapshot)
+    return {
+      ...base,
+      workbook: { id: summary.id, name: summary.name, sheets, sheetCount: sheets.length, updatedAt: summary.updatedAt },
+      ...(include.has('snapshot') ? { snapshot: meta.snapshot } : {}),
+      ...(include.has('backfill')
+        ? {
+            backfill: sheets.map(overview => ({
+              sheetId: overview.id,
+              name: overview.name,
+              ...sheetBackfillStatus(snapshotSheet(meta.snapshot, overview.id)),
+            })),
+          }
+        : {}),
+    }
+  }
+
+  const sheetRef = sheetRefForSnapshot(meta.snapshot, target, 'target.sheet')
+  const sheet = snapshotSheet(meta.snapshot, sheetRef)
+  const sheetSummary = summary.sheets.find(candidate => candidate.id === sheetRef || candidate.name === sheetRef)
+  const resolvedSheetRef: SheetRef = {
+    workbookId,
+    sheetId: sheetSummary?.id ?? String(sheet.id ?? sheetRef),
+    sheetName: sheetSummary?.name ?? String(sheet.name ?? sheetRef),
+  }
+  if (kind === 'sheet') {
+    const overview = sheetOverviews(meta.snapshot).find(candidate => candidate.id === resolvedSheetRef.sheetId)
+    return {
+      ...base,
+      sheetRef: resolvedSheetRef,
+      sheet: {
+        id: resolvedSheetRef.sheetId,
+        name: resolvedSheetRef.sheetName,
+        rowCount: overview?.rowCount ?? sheet.rowCount ?? 0,
+        columnCount: overview?.columnCount ?? sheet.columnCount ?? 0,
+        maxRow: overview?.maxRow ?? null,
+        maxColumn: overview?.maxColumn ?? null,
+        nonEmptyCells: overview?.nonEmptyCells ?? 0,
+      },
+      ...(include.has('snapshot') ? { snapshot: sheet } : {}),
+    }
+  }
+
+  if (kind === 'range') {
+    const range = parseRange(target.range)
+    const result = readWorkbookRange(meta.snapshot, sheetRef, range)
+    // `readWorkbookRange` materializes values, formulas and cells together, but
+    // returning all three inline spent the result budget three times over
+    // (docs/issue/0011 I1 / T5). Only `values` is unconditional; the heavier views
+    // have to be asked for.
+    return {
+      ...base,
+      sheetRef: { ...resolvedSheetRef, range: `${range.startRow}:${range.startColumn}-${range.endRow}:${range.endColumn}` },
+      sheetId: result.sheetId,
+      sheetName: result.sheetName,
+      range: result.range,
+      values: result.values,
+      ...(include.has('formulas') ? { formulas: result.formulas } : {}),
+      ...(include.has('cells') ? { cells: result.cells } : {}),
+      ...(include.has('styles') ? { styles: styleMatrix(meta.snapshot, result.sheetId, range) } : {}),
+    }
+  }
+
+  if (!Array.isArray(target.cells) || target.cells.length === 0 || target.cells.length > 500) {
+    throw new Error('target.cells 必须是 1 到 500 项的单元格坐标数组')
+  }
+  const cells = target.cells.map((rawCell, index) => {
+    const coordinate = asToolArguments(rawCell, 'target.cells[' + index + ']')
+    const row = parseIndex(coordinate.row, 'target.cells[' + index + '].row')
+    const column = parseIndex(coordinate.column, 'target.cells[' + index + '].column')
+    const cell = snapshotCell(meta.snapshot, sheetRef, row, column)
+    const value = cell?.v
+    return {
+      row,
+      column,
+      value: value === undefined ? null : value,
+      formula: typeof cell?.f === 'string' ? cell.f : null,
+      ...(include.has('styles') ? { style: cell?.s ?? null } : {}),
+    }
+  })
+  return {
+    ...base,
+    sheetRef: resolvedSheetRef,
+    sheet: { id: resolvedSheetRef.sheetId, name: resolvedSheetRef.sheetName },
+    cells,
+  }
+}