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

package/src/tools/workbook-edit.ts

@@ -0,0 +1,987 @@
+/**
+ * `workbook_edit`: one plan, many semantic Versions (docs/issue/0022 P3b).
+ *
+ * The largest tool surface by far: it parses command lists and version groups,
+ * expands `duplicate_sheet` and `valueFromFile`, resolves a table's columns from
+ * the sheet it will land on, and reports a receipt per imported file. It is one
+ * file because those steps are one transaction — a plan either commits whole or
+ * is rejected whole (PRD 0002 §5).
+ */
+import { cloneSnapshot } from '../contract/snapshots.ts'
+import { createHash, randomUUID } from 'node:crypto'
+import { statSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { extname, join, resolve } from 'node:path'
+import * as XLSX from 'xlsx'
+import { cellAddress } from '#contracts'
+import {
+  SHEET_MAX_APPEND_ROWS,
+  SHEET_MAX_COLUMNS,
+  SHEET_MAX_PHYSICAL_ROWS,
+  SHEET_MAX_ROWS,
+  type SheetColumn,
+  type SheetColumnType,
+  type WorkbookCellUpdate,
+  type WorkbookOperationPayload,
+  type WorkbookOperationType,
+  type WorkbookRange,
+} from '../types.ts'
+import { DataSheetError } from '../errors.ts'
+
+import { applyWorkbookOperation } from '../contract/mutations.ts'
+import { workbookOperationSteps } from '../contract/operations.ts'
+import type { LineageContext } from '#contracts'
+import { mutateWorkbookPlan, readWorkbook } from '../workbook-manager.ts'
+import { isOperationType, normalizeValueMatrix, parseIndex, parseRange } from '../request-params.ts'
+import {
+  asToolArguments,
+  commandIndex,
+  commandPayload,
+  commandSheet,
+  now,
+  optionalAuditText,
+  optionalIntent,
+  parseCellDeleteShift,
+  parseCount,
+  parseHeaderVerification,
+  parseNonEmptyString,
+  sheetRefForSnapshot,
+  type ToolArguments,
+} from './arguments.ts'
+import {
+  chunkRows,
+  dimensionCommandRange,
+  dimensionRange,
+  parseApiValues,
+  parseCells,
+  parseFiniteNumber,
+  parseFreeze,
+  parseHyperlink,
+  parseHyperlinkLabel,
+  parseSort,
+  parseValueRange,
+  resolveCellFileValues,
+  validateSheet,
+} from './cells.ts'
+import { operationReceipt, sheetOverviews, sheetReferenceList } from './render.ts'
+import { snapshotSheet } from './workbook-read.ts'
+
+/** Agent-facing receipt seed for one `import_file` step. It is stripped before
+ * the command is persisted, so the Version/Step payload keeps its existing
+ * shape and replay model. */
+export interface ImportFileMeta {
+  sourcePath: string
+  range: WorkbookRange
+  rowsWritten: number
+  cellsWritten: number
+  sourceRowCount: number
+  truncated: boolean
+  verifyCapacity: boolean
+  firstRow: unknown[]
+  lastRow: unknown[]
+  valuesHash: string
+}
+
+/** One parsed command plus non-persisted Agent-facing metadata. */
+export interface ParsedCommand {
+  type: WorkbookOperationType
+  payload: WorkbookOperationPayload
+  importFile?: ImportFileMeta
+}
+
+/**
+ * Copy a sheet's cell content and column widths into a new sheet of the target
+ * workbook (docs/issue/0011 I2 / T7).
+ *
+ * Expanded into the existing `create_sheet` / `update_cells` /
+ * `set_column_width` commands rather than becoming a new persisted operation:
+ * the Version/Step model is untouched and the browser projection needs no new
+ * branch. The source is read from storage, so it has to exist before the batch
+ * starts — a sheet created earlier in the same batch is not visible here.
+ *
+ * What is copied is the content that was tedious to retype (title block, header
+ * row, long SQL text) plus column widths. Styles, merges, freeze panes and data
+ * validation are deliberately not copied; they stay with the source sheet.
+ */
+export async function expandDuplicateSheet(raw: ToolArguments, index: number, targetWorkbookId: string, warnings: string[] = []): Promise<ParsedCommand[]> {
+  const label = `commands[${index}]`
+  const sourceWorkbookId = raw.fromWorkbookId === undefined || raw.fromWorkbookId === null
+    ? targetWorkbookId
+    : parseNonEmptyString(raw.fromWorkbookId, `${label}.fromWorkbookId`)
+  const name = parseNonEmptyString(raw.name, `${label}.name`)
+  const explicitId = raw.sheetId === undefined || raw.sheetId === null
+    ? undefined
+    : parseNonEmptyString(raw.sheetId, `${label}.sheetId`)
+  const source = await readWorkbook(sourceWorkbookId)
+  if (source === null) throw new Error(`${label}.fromWorkbookId 工作簿不存在：${sourceWorkbookId}`)
+  const root = asToolArguments(source.snapshot, 'workbook snapshot')
+  const order = Array.isArray(root.sheetOrder) ? root.sheetOrder.map(String) : Object.keys(asToolArguments(root.sheets, 'workbook snapshot.sheets'))
+  const requested = raw.sheet === undefined || raw.sheet === null
+    ? order[0]
+    : parseNonEmptyString(raw.sheet, `${label}.sheet`)
+  if (requested === undefined) throw new Error(`${label} 源工作簿没有可复制的 sheet`)
+  const sheet = snapshotSheet(source.snapshot, requested)
+  const newSheetId = explicitId ?? stableCreateSheetId(targetWorkbookId, name, 0, index)
+
+  const commands: ParsedCommand[] = [{ type: 'create_sheet', payload: { sheetId: newSheetId, name } }]
+  const cells: WorkbookCellUpdate[] = []
+  const cellData = sheet.cellData
+  if (typeof cellData === 'object' && cellData !== null) {
+    for (const [rowKey, line] of Object.entries(cellData as Record<string, Record<string, { v?: unknown; f?: unknown }>>)) {
+      const row = Number(rowKey)
+      if (!Number.isInteger(row) || row < 0) continue
+      for (const [columnKey, cell] of Object.entries(line ?? {})) {
+        const column = Number(columnKey)
+        if (!Number.isInteger(column) || column < 0) continue
+        if (cell === null || typeof cell !== 'object') continue
+        const value = cell.v === undefined ? null : cell.v
+        const formula = typeof cell.f === 'string' ? cell.f : undefined
+        // An empty cell carries nothing to reproduce.
+        if (value === null && formula === undefined) continue
+        cells.push({ row, column, value: value as WorkbookCellUpdate['value'], ...(formula === undefined ? {} : { formula }) })
+      }
+    }
+  }
+  if (cells.length === 0) {
+    warnings.push(`${label} 源 sheet「${requested}」没有可复制的内容，只创建了空 sheet`)
+  } else {
+    commands.push({ type: 'update_cells', payload: { sheetId: newSheetId, cells } })
+  }
+  const columnData = sheet.columnData
+  if (typeof columnData === 'object' && columnData !== null) {
+    for (const [key, entry] of Object.entries(columnData as Record<string, { width?: unknown }>)) {
+      const column = Number(key)
+      const width = entry?.width
+      if (!Number.isInteger(column) || typeof width !== 'number' || !(width > 0) || width > 1000) continue
+      commands.push({
+        type: 'set_column_width',
+        payload: { sheetId: newSheetId, range: { startRow: 0, endRow: 0, startColumn: column, endColumn: column }, size: width },
+      })
+    }
+  }
+  return commands
+}
+
+export async function parseEditCommands(value: unknown, warnings: string[] = [], targetWorkbookId = 'workbook'): Promise<ParsedCommand[]> {
+  if (!Array.isArray(value) || value.length === 0 || value.length > 100) throw new Error('commands 必须是 1 到 100 项的数组')
+  const aliases: Record<string, WorkbookOperationType> = {
+    set_values: 'update_cells',
+    clear: 'clear_range',
+    format: 'format_cells',
+    merge: 'merge_cells',
+    unmerge: 'unmerge_cells',
+    freeze: 'freeze_panes',
+    sort: 'sort_range',
+  }
+  const importedTables = await Promise.all(value.map(async (candidate, index) => {
+    const raw = commandPayload(asToolArguments(candidate, 'commands[' + index + ']'))
+    const rawType = raw.type
+    const type = typeof rawType === 'string' && aliases[rawType] !== undefined ? aliases[rawType] : rawType
+    if (raw.sourcePath === undefined) return undefined
+    // `update_cells` prefers a literal matrix or `cells` payload; reading a file
+    // the command will ignore would fail the whole plan when that path is
+    // missing and would waste I/O on a file that is never used.
+    const usesImport = type === 'import_file' || type === 'append_rows'
+      || (type === 'update_cells' && raw.cells === undefined && literalValueMatrix(raw) === undefined)
+    return usesImport ? readTabularSource(raw.sourcePath, raw.sourceFormat) : undefined
+  }))
+  // `duplicate_sheet` has to read its source workbook from storage, so it is
+  // the one command whose expansion cannot happen inside the synchronous loop
+  // below (which uses `return` to end each case). Resolve those expansions up
+  // front and inject them in place, so command order — and therefore the
+  // name-to-id binding in `bindEditVersionGroups` — is unchanged.
+  const duplicateExpansions = new Map<number, ParsedCommand[]>()
+  const fileCellExpansions = new Map<number, WorkbookCellUpdate[]>()
+  await Promise.all(value.map(async (candidate, index) => {
+    const raw = commandPayload(asToolArguments(candidate, 'commands[' + index + ']'))
+    if (raw.type === 'duplicate_sheet') {
+      duplicateExpansions.set(index, await expandDuplicateSheet(raw, index, targetWorkbookId, warnings))
+      return
+    }
+    // `cells[].valueFromFile` needs storage too, and `parseCells` is synchronous.
+    if (raw.type === 'update_cells' && Array.isArray(raw.cells)) {
+      const needsFile = raw.cells.some(cell => (
+        typeof cell === 'object' && cell !== null && !Array.isArray(cell)
+        && (cell as Record<string, unknown>).valueFromFile !== undefined
+        && (cell as Record<string, unknown>).valueFromFile !== null
+      ))
+      if (needsFile) {
+        fileCellExpansions.set(index, parseCells(await resolveCellFileValues(raw.cells, `commands[${index}]`)))
+      }
+    }
+  }))
+  const result: ParsedCommand[] = []
+  value.forEach((candidate, index) => {
+    const raw = commandPayload(asToolArguments(candidate, 'commands[' + index + ']'))
+    if (raw.scope !== undefined && raw.scope !== 'workbook' && raw.scope !== 'sheet' && raw.scope !== 'cell') {
+      throw new Error('commands[' + index + '].scope 必须是 workbook、sheet 或 cell')
+    }
+    const rawType = raw.type
+    const aliasedType = typeof rawType === 'string' && aliases[rawType] !== undefined ? aliases[rawType] : rawType
+    // `import_file` and `duplicate_sheet` are Agent-facing conveniences that are
+    // expanded below into the durable command set, so neither ever reaches the
+    // Version/Step model as a type of its own.
+    const type: WorkbookOperationType | 'import_file' | 'duplicate_sheet' =
+      aliasedType === 'import_file' || aliasedType === 'duplicate_sheet'
+        ? aliasedType
+        : aliasedType as WorkbookOperationType
+    if (type !== 'import_file' && type !== 'duplicate_sheet'
+      && (!isOperationType(type) || type === 'batch' || type === 'snapshot_replace' || type === 'remove_duplicates')) {
+      throw new Error('commands[' + index + '].type 不支持')
+    }
+    const sheet = commandSheet(raw, index, type === 'create_sheet' || type === 'append_rows')
+    switch (type) {
+      case 'update_cells': {
+        // A literal matrix wins. `sourcePath` is the bulk alternative, so a
+        // large result never has to be spelled out inside the tool call.
+        const imported = importedTables[index]
+        const matrix = literalValueMatrix(raw)
+          ?? (imported === undefined ? undefined : importedValueMatrix(imported, `commands[${index}]`))
+        const cells = fileCellExpansions.get(index) ?? (raw.cells === undefined
+          ? (() => {
+            const valueMatrix = normalizeValueMatrix(matrix)
+            return parseApiValues(valueMatrix, parseValueRange(valueCommandRange(raw), valueMatrix, `commands[${index}]`, warnings))
+          })()
+          : parseCells(raw.cells))
+        result.push({ type, payload: { sheetId: commandSheet(raw, index), cells } })
+        return
+      }
+      case 'clear_range':
+        result.push({ type, payload: { sheetId: commandSheet(raw, index), range: parseRange(raw.range) } })
+        return
+      case 'delete_cells':
+        result.push({ type, payload: { sheetId: commandSheet(raw, index), range: parseRange(raw.range), shift: parseCellDeleteShift(raw.shift) } })
+        return
+      case 'insert_rows':
+      case 'delete_rows': {
+        const range = dimensionCommandRange(raw, index, 'row')
+        result.push({ type, payload: { sheetId: commandSheet(raw, index), range, count: raw.count === undefined ? range.endRow - range.startRow + 1 : parseCount(raw.count) } })
+        return
+      }
+      case 'insert_columns':
+      case 'delete_columns': {
+        const range = dimensionCommandRange(raw, index, 'column')
+        result.push({ type, payload: { sheetId: commandSheet(raw, index), range, count: raw.count === undefined ? range.endColumn - range.startColumn + 1 : parseCount(raw.count) } })
+        return
+      }
+      case 'create_sheet':
+        result.push({ type, payload: { sheetId: sheet, name: parseNonEmptyString(raw.name, 'commands[' + index + '].name') } })
+        return
+      case 'delete_sheet':
+        result.push({ type, payload: { sheetId: commandSheet(raw, index) } })
+        return
+      case 'rename_sheet':
+        result.push({ type, payload: { sheetId: commandSheet(raw, index), name: parseNonEmptyString(raw.name, 'commands[' + index + '].name') } })
+        return
+      case 'append_rows': {
+        const label = `commands[${index}]`
+        const imported = importedTables[index]
+        const table = validateSheet({
+          name: raw.name ?? sheet ?? imported?.name ?? 'Sheet',
+          columns: raw.columns ?? imported?.columns,
+          rows: raw.rows ?? raw.data ?? raw.records ?? imported?.rows,
+        })
+        // Report sheets keep a title block above the real header row, so the
+        // header is addressable instead of being pinned to row 0.
+        const headerRowIndex = parseIndex(raw.headerRowIndex ?? 0, `${label}.headerRowIndex`)
+        if (headerRowIndex >= SHEET_MAX_PHYSICAL_ROWS) {
+          throw new Error(`${label}.headerRowIndex=${headerRowIndex} 超出上限（最后一个物理行是 ${SHEET_MAX_ROWS}）`)
+        }
+        const verifyHeader = parseHeaderVerification(raw.verifyHeader, `${label}.verifyHeader`)
+        const chunks = table.rows.length === 0 ? [[]] : chunkRows(table.rows, SHEET_MAX_APPEND_ROWS)
+        for (const rows of chunks) {
+          result.push({ type, payload: { sheetId: sheet, name: table.name, columns: table.columns, rows, meta: parseSheetMeta(raw.meta), headerRowIndex, verifyHeader } })
+        }
+        return
+      }
+      case 'import_file': {
+        // A first-class "one command + one file path" bulk import for report
+        // sheets: the origin is explicit, row 0 never has to be a header, and
+        // the result carries a self-verifying receipt. It is normalized into
+        // the existing update_cells write path before persistence.
+        const label = `commands[${index}]`
+        const imported = importedTables[index]
+        if (imported === undefined) throw new Error(`${label}.sourcePath 是 import_file 的必填参数（支持 CSV/JSON/JSONL/XLSX/XLS）`)
+        const origin = raw.range === undefined || raw.range === null ? undefined : asToolArguments(raw.range, `${label}.range`)
+        const startValue = raw.startRow ?? origin?.startRow
+        if (startValue === undefined) throw new Error(`${label}.startRow 是 import_file 的必填参数（0-based 写入起点）；也可用 range.startRow 给出`)
+        const startRow = parseIndex(startValue, `${label}.startRow`)
+        const startColumn = parseIndex(raw.startColumn ?? origin?.startColumn ?? 0, `${label}.startColumn`)
+        const source = importedValueMatrix(imported, label)
+        const available = SHEET_MAX_PHYSICAL_ROWS - startRow
+        if (available < 1) {
+          throw new Error(`${label}.startRow=${startRow} 超出上限（最多 ${SHEET_MAX_ROWS} 条数据行 + 表头，最后一个物理行是 ${SHEET_MAX_ROWS}）`)
+        }
+        // A partial bulk write is a silent data-loss trap, so it must be asked
+        // for explicitly instead of being reported as a successful import.
+        if (source.length > available && raw.allowTruncate !== true) {
+          throw new Error(`${label} 源文件 ${source.length} 行超出可写区间：从第 ${startRow + 1} 行起最多还能写 ${available} 行（上限 ${SHEET_MAX_ROWS} 条数据行 + 表头）。请减少源文件行数、下移起点，或显式传 allowTruncate: true 只导入前 ${available} 行`)
+        }
+        const rows = source.length > available ? source.slice(0, available) : source
+        if (rows.length === 0) throw new Error(`${label}.startRow=${startRow} 没有可写入的行`)
+        const truncated = rows.length < source.length
+        const range = parseRange({ startRow, startColumn, endRow: startRow + rows.length - 1, endColumn: startColumn + (rows[0]?.length ?? 1) - 1 })
+        const cells = parseApiValues(rows, range)
+        result.push({
+          type: 'update_cells',
+          payload: { sheetId: commandSheet(raw, index), cells },
+          importFile: {
+            sourcePath: imported.path,
+            range,
+            rowsWritten: rows.length,
+            cellsWritten: cells.length,
+            sourceRowCount: source.length,
+            truncated,
+            verifyCapacity: raw.verifyCapacity !== false,
+            firstRow: rows[0] ?? [],
+            lastRow: rows[rows.length - 1] ?? [],
+            valuesHash: hashValueMatrix(rows),
+          },
+        })
+        return
+      }
+      case 'format_cells':
+        result.push({ type, payload: { sheetId: commandSheet(raw, index), range: parseRange(raw.range), style: parseStyle(raw.style) } })
+        return
+      case 'merge_cells':
+      case 'unmerge_cells':
+        result.push({ type, payload: { sheetId: commandSheet(raw, index), range: parseRange(raw.range) } })
+        return
+      case 'freeze_panes':
+        result.push({ type, payload: { sheetId: commandSheet(raw, index), freeze: parseFreeze(raw.freeze) } })
+        return
+      case 'set_column_width':
+        result.push({ type, payload: { sheetId: commandSheet(raw, index), range: dimensionRange(commandIndex(raw, index, 'index'), 'column'), size: parseFiniteNumber(raw.size, 'commands[' + index + '].size') } })
+        return
+      case 'set_row_height':
+        result.push({ type, payload: { sheetId: commandSheet(raw, index), range: dimensionRange(commandIndex(raw, index, 'index'), 'row'), size: parseFiniteNumber(raw.size, 'commands[' + index + '].size') } })
+        return
+      case 'sort_range':
+        result.push({ type, payload: { sheetId: commandSheet(raw, index), range: parseRange(raw.range), sort: parseSort(raw.sort) } })
+        return
+      case 'set_hyperlink':
+        result.push({ type, payload: { sheetId: commandSheet(raw, index), range: parseRange(raw.range), url: parseHyperlink(raw.url), label: raw.label === undefined ? undefined : parseHyperlinkLabel(raw.label) } })
+        return
+      case 'remove_hyperlink':
+        result.push({ type, payload: { sheetId: commandSheet(raw, index), range: parseRange(raw.range) } })
+        return
+      case 'duplicate_sheet':
+        result.push(...(duplicateExpansions.get(index) ?? []))
+        return
+      default:
+        assertNeverEditCommand(type)
+    }
+  })
+  return result
+}
+
+export interface ImportedTable {
+  /** Resolved absolute path of the source file. */
+  path: string
+  name?: string
+  columns?: unknown
+  rows: unknown[]
+}
+
+/**
+ * Expand a tabular import (`{ columns?, rows }`) into the rectangular value
+ * matrix the `update_cells` write path consumes. CSV/XLSX/JSONL produce row
+ * objects, so the column order is inferred from the row keys — the same rule
+ * `append_rows` uses — while `validateSheet` keeps the caps and error wording
+ * for both shapes. Ragged array rows are padded by `normalizeValueMatrix`.
+ */
+export function importedValueMatrix(imported: ImportedTable, label: string): unknown[][] {
+  const rows = imported.rows
+  if (rows.length === 0) throw new Error(`${label}.sourcePath 没有可导入的数据行`)
+  if (rows.every(row => Array.isArray(row))) return normalizeValueMatrix(rows as unknown[][])
+  if (imported.columns !== undefined && !Array.isArray(imported.columns)) throw new Error(`${label}.sourcePath columns 必须是数组`)
+  const declared = Array.isArray(imported.columns) ? imported.columns : undefined
+  if (declared !== undefined && declared.length > 0) {
+    const table = validateSheet({ name: undefined, columns: declared, rows })
+    return (table.rows as Array<Record<string, unknown>>).map(row => table.columns.map(column => row[column.key] ?? null))
+  }
+  const keys: string[] = []
+  rows.forEach((row, index) => {
+    if (typeof row !== 'object' || row === null || Array.isArray(row)) throw new Error(`${label}.sourcePath 第 ${index + 1} 行不是对象`)
+    for (const key of Object.keys(row)) if (!keys.includes(key)) keys.push(key)
+  })
+  if (keys.length === 0) throw new Error(`${label}.sourcePath 无法从数据行推断列，请改用 CSV/XLSX 或显式提供 values`)
+  if (keys.length > SHEET_MAX_COLUMNS) throw new Error(`${label}.sourcePath 列数超过上限（最多 ${SHEET_MAX_COLUMNS} 列）`)
+  // The validator's sanitized keys are only metadata here: values are projected
+  // positionally by the original key order, exactly like `inferAppendTable`.
+  const table = validateSheet({
+    name: undefined,
+    columns: keys.map((key, index) => ({ key: /^[A-Za-z0-9_]+$/.test(key) ? key : `column_${index + 1}`, label: key, type: 'string' as SheetColumnType })),
+    rows,
+  })
+  if (table.columns.length !== keys.length) throw new Error(`${label}.sourcePath 列推断失败`)
+  return rows.map(row => keys.map(key => (row as Record<string, unknown>)[key] ?? null))
+}
+
+/** Stable content digest so an import receipt can prove what was written. */
+export function hashValueMatrix(matrix: readonly unknown[][]): string {
+  return createHash('sha256').update(JSON.stringify(matrix)).digest('hex')
+}
+
+/**
+ * The literal value matrix of an `update_cells` command, if it carries one.
+ * Shared by the import pre-read and the command branch so both agree on when a
+ * `sourcePath` is actually consulted.
+ */
+export function literalValueMatrix(raw: ToolArguments): unknown {
+  return raw.values ?? raw.data ?? raw.matrix
+    ?? (Array.isArray(raw.rows) && raw.rows.some(item => Array.isArray(item)) ? raw.rows : undefined)
+}
+
+/**
+ * `update_cells` anchors at `range`, or at the top-level `startRow` /
+ * `startColumn` pair. A missing anchor keeps the historical default (row 1,
+ * column 0) — the P1-2 origin change is intentionally out of scope here.
+ */
+export function valueCommandRange(raw: ToolArguments): unknown {
+  if (raw.range !== undefined && raw.range !== null) return raw.range
+  if (raw.startRow === undefined && raw.startColumn === undefined) return undefined
+  return { startRow: raw.startRow, startColumn: raw.startColumn }
+}
+
+/** Read a local tabular file for bulk Agent imports. The file is converted to
+ * the same append_rows/update_cells contract before it reaches the durable
+ * mutator, so a failed parse never creates a partial workbook revision. */
+export async function readTabularSource(rawPath: unknown, rawFormat: unknown): Promise<ImportedTable> {
+  const sourcePath = resolve(parseNonEmptyString(rawPath, 'sourcePath'))
+  let info: { size: number }
+  try { info = statSync(sourcePath) } catch { throw new Error(`sourcePath 文件不存在：${sourcePath}`) }
+  if (!Number.isInteger(info.size) || info.size < 0 || info.size > 128 * 1024 * 1024) throw new Error('sourcePath 文件必须不超过 128 MiB')
+  const extension = typeof rawFormat === 'string' && rawFormat.trim() !== '' ? `.${rawFormat.trim().replace(/^\./, '').toLowerCase()}` : extname(sourcePath).toLowerCase()
+  if (!['.csv', '.json', '.jsonl', '.xlsx', '.xls'].includes(extension)) throw new Error('sourcePath 仅支持 CSV、JSON、JSONL、XLSX、XLS')
+  const bytes = await readFile(sourcePath)
+  if (extension === '.json' || extension === '.jsonl') {
+    const text = bytes.toString('utf8').replace(/^\uFEFF/, '')
+    const value = extension === '.jsonl'
+      ? text.split(/\r?\n/).map(line => line.trim()).filter(Boolean).map((line, index) => {
+        try { return JSON.parse(line) as unknown } catch { throw new Error(`sourcePath JSONL 第 ${index + 1} 行不是有效 JSON`) }
+      })
+      : (() => { try { return JSON.parse(text) as unknown } catch { throw new Error('sourcePath JSON 不是有效 JSON') } })()
+    if (Array.isArray(value)) return { path: sourcePath, rows: value }
+    if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+      const record = value as Record<string, unknown>
+      const rows = record.rows ?? record.data ?? record.records
+      if (Array.isArray(rows)) return { path: sourcePath, name: typeof record.name === 'string' ? record.name : undefined, columns: record.columns, rows }
+    }
+    throw new Error('sourcePath JSON 须是数组，或包含 rows/data/records 数组的对象')
+  }
+  // CSV is text: decode UTF-8 explicitly so quoted commas/newlines parse
+  // correctly and CJK values do not come back as latin1 mojibake.
+  const workbook = XLSX.read(extension === '.csv' ? bytes.toString('utf8').replace(/^\uFEFF/, '') : bytes, extension === '.csv' ? { type: 'string' } : { type: 'buffer' })
+  const firstName = workbook.SheetNames[0]
+  if (firstName === undefined) throw new Error('sourcePath 工作簿没有 sheet')
+  const first = workbook.Sheets[firstName]
+  if (first === undefined) throw new Error('sourcePath 第一个 sheet 不存在')
+  return { path: sourcePath, name: firstName, rows: XLSX.utils.sheet_to_json(first, { defval: null }) as unknown[] }
+}
+
+export interface ParsedEditVersion {
+  summary: string
+  intent?: string
+  commands: ParsedCommand[]
+}
+
+/**
+ * Convert the tool protocol into the aggregate's two durable levels:
+ * semantic Version groups, each containing replayable command Steps. The
+ * shorthand keeps older callers working while making their whole request one
+ * coherent Version instead of one Version per command.
+ */
+export async function parseEditVersionGroups(rawVersions: unknown, rawCommands: unknown, defaultIntent?: string, warnings: string[] = [], targetWorkbookId = 'workbook'): Promise<ParsedEditVersion[]> {
+  if (rawVersions !== undefined && rawVersions !== null) {
+    if (rawCommands !== undefined && rawCommands !== null) throw new Error('versions 与 commands 只能提供其中之一')
+    if (!Array.isArray(rawVersions) || rawVersions.length === 0 || rawVersions.length > 20) throw new Error('versions 必须是 1 到 20 项的数组')
+    const groups = await Promise.all(rawVersions.map(async (candidate, index) => {
+      const raw = asToolArguments(candidate, `versions[${index}]`)
+      const summary = optionalIntent(raw.summary, `versions[${index}].summary`)
+      if (summary === undefined) throw new Error(`versions[${index}].summary 必须是 1 到 280 字符的字符串`)
+      return {
+        summary,
+        intent: optionalAuditText(raw.intent, `versions[${index}].intent`, 1000) ?? defaultIntent,
+        commands: await parseEditCommands(raw.commands, warnings, targetWorkbookId),
+      }
+    }))
+    const commandCount = groups.reduce((total, group) => total + group.commands.length, 0)
+    if (commandCount > 100) throw new Error('versions 中 commands 总数最多 100 条')
+    return groups
+  }
+  const commands = await parseEditCommands(rawCommands, warnings, targetWorkbookId)
+  return [{
+    summary: defaultIntent ?? `Agent 编辑（${commands.length} 个 step）`,
+    intent: defaultIntent,
+    commands,
+  }]
+}
+
+export function assertNeverEditCommand(value: never): never {
+  throw new Error('不支持的编辑命令：' + String(value))
+}
+
+/**
+ * Bind the forgiving Agent wire format to the durable workbook format. This
+ * runs after the workbook has been loaded, so a single-sheet workbook can
+ * safely omit `sheet`, sheet names can be converted to ids, and commands that
+ * create a sheet can be followed by commands targeting that new sheet.
+ */
+export function bindEditVersionGroups(snapshot: unknown, groups: ParsedEditVersion[], workbookId = 'workbook'): ParsedEditVersion[] {
+  let working = cloneSnapshot(snapshot)
+  return groups.map((group, groupIndex) => {
+    const commands = group.commands.map((command, commandIndex) => {
+      const label = `versions[${groupIndex}].commands[${commandIndex}]`
+      const payload = { ...command.payload }
+      if (command.type === 'create_sheet') {
+        // A missing id used to fall back to `sheet-${opId.slice(0,12)}`, which
+        // differs between the bind probe and the real commit and stranded
+        // later commands in the same batch on a stale id.
+        const explicit = payload.sheetId ?? payload.sheetName
+        payload.sheetId = explicit === undefined || String(explicit).trim() === ''
+          ? stableCreateSheetId(workbookId, payload.name, groupIndex, commandIndex)
+          : parseNonEmptyString(explicit, `${label}.sheet`)
+        delete payload.sheetName
+      } else {
+        const explicitRef = payload.sheetId ?? payload.sheetName
+        const ref = resolveCommandSheetRef(working, explicitRef, `${label}.sheet`, command.type === 'append_rows')
+        if (ref !== undefined) {
+          payload.sheetId = ref
+          delete payload.sheetName
+        }
+      }
+      if (command.type === 'append_rows' && (payload.columns === undefined || payload.columns.length === 0)) {
+        const inferred = inferAppendTable(working, payload.sheetId ?? payload.sheetName, payload.rows ?? [], label)
+        payload.columns = inferred.columns
+        payload.rows = inferred.rows
+      }
+      const bound: ParsedCommand = {
+        type: command.type,
+        payload,
+        ...(command.importFile === undefined ? {} : { importFile: command.importFile }),
+      }
+      working = applyWorkbookOperation(working, {
+        opId: `bind:${groupIndex}:${commandIndex}`,
+        workbookId: 'bind',
+        revision: 0,
+        actor: 'agent',
+        timestamp: new Date(0).toISOString(),
+        type: bound.type,
+        payload: bound.payload,
+      })
+      return bound
+    })
+    return { ...group, commands }
+  })
+}
+
+/** Deterministic create_sheet id so preview and commit address the same sheet. */
+export function stableCreateSheetId(workbookId: string, name: unknown, groupIndex: number, commandIndex: number): string {
+  const seed = `${workbookId}#${groupIndex}#${commandIndex}#${String(name ?? 'sheet')}`
+  return `sheet-${createHash('sha256').update(seed).digest('hex').slice(0, 12)}`
+}
+
+/**
+ * Warn when one edit plan writes the same cell more than once. The later
+ * command wins, which is easy to do by accident in a 15-command batch.
+ */
+export function collectDuplicateCellWrites(versions: readonly ParsedEditVersion[], warnings: string[]): void {
+  const firstWrite = new Map<string, string>()
+  const reported = new Set<string>()
+  let suppressed = 0
+  versions.forEach((version, groupIndex) => {
+    version.commands.forEach((command, commandIndex) => {
+      if (command.type !== 'update_cells') return
+      const sheetId = String(command.payload.sheetId ?? command.payload.sheetName ?? '')
+      const label = `versions[${groupIndex}].commands[${commandIndex}]`
+      for (const cell of command.payload.cells ?? []) {
+        const key = `${sheetId}:${cell.row}:${cell.column}`
+        const previous = firstWrite.get(key)
+        if (previous === undefined) {
+          firstWrite.set(key, label)
+          continue
+        }
+        if (reported.has(key)) continue
+        reported.add(key)
+        if (reported.size > 20) { suppressed += 1; continue }
+        warnings.push(`cells ${cellAddress(cell.row, cell.column)} 被 ${previous} 与 ${label} 依次覆盖；后写入的命令生效`)
+      }
+    })
+  })
+  if (suppressed > 0) warnings.push(`另有 ${suppressed} 个 cell 被重复写入，已省略`)
+}
+
+export function resolveCommandSheetRef(snapshot: unknown, explicit: unknown, label: string, allowMissing: boolean): string | undefined {
+  if (explicit === undefined || explicit === null || explicit === '') return sheetRefForSnapshot(snapshot, {}, label)
+  const ref = parseNonEmptyString(explicit, label)
+  try {
+    const sheet = snapshotSheet(snapshot, ref)
+    return typeof sheet.id === 'string' && sheet.id.length > 0 ? sheet.id : ref
+  } catch (error) {
+    if (allowMissing) return ref
+    throw new Error(`${label} 指向不存在的 sheet：${ref}。当前工作簿 sheet：${sheetReferenceList(snapshot)}。若该 sheet 由本批次 create_sheet 新建，请把 create_sheet 放在引用它的命令之前（同一个 version 内按顺序执行），或先单独提交 create_sheet`)
+  }
+}
+
+export function inferAppendTable(snapshot: unknown, sheetRef: unknown, rawRows: unknown, label: string): { columns: SheetColumn[]; rows: Array<Record<string, unknown>> } {
+  if (!Array.isArray(rawRows)) throw new Error(`${label}.rows 必须是对象数组`)
+  const rows = rawRows as Array<Record<string, unknown>>
+  let existing: Record<string, unknown> | undefined
+  if (sheetRef !== undefined) {
+    try { existing = snapshotSheet(snapshot, String(sheetRef)) } catch { /* append_rows may create a new sheet */ }
+  }
+  const schema = existing?.dataSheetSchema
+  const schemaRecord = typeof schema === 'object' && schema !== null && !Array.isArray(schema)
+    ? schema as Record<string, unknown>
+    : undefined
+  if (Array.isArray(schemaRecord?.columns) && schemaRecord.columns.length > 0) {
+    const columns = schemaRecord.columns as SheetColumn[]
+    return { columns, rows: projectRowsToColumns(rows, columns) }
+  }
+  const keys: string[] = []
+  for (const row of rows) {
+    for (const key of Object.keys(row)) if (!keys.includes(key)) keys.push(key)
+  }
+  if (keys.length === 0) throw new Error(`${label} 缺少 columns，且无法从 rows 推断列`)
+  if (keys.length > SHEET_MAX_COLUMNS) throw new Error(`推断列数超过上限（最多 ${SHEET_MAX_COLUMNS} 列）`)
+  const header = existing?.cellData
+  const headerRow = header !== undefined && typeof header === 'object' && header !== null && !Array.isArray(header)
+    ? (header as Record<string, unknown>)['0']
+    : undefined
+  const headerValues = headerRow !== null && typeof headerRow === 'object' && headerRow !== undefined && !Array.isArray(headerRow)
+    ? headerRow as Record<string, unknown>
+    : {}
+  const columns = keys.map((sourceKey, index) => {
+    const key = /^[A-Za-z0-9_]+$/.test(sourceKey) ? sourceKey : `column_${index + 1}`
+    const labelValue = headerValues[String(index)] && typeof headerValues[String(index)] === 'object'
+      ? (headerValues[String(index)] as Record<string, unknown>).v
+      : undefined
+    return { key, label: typeof labelValue === 'string' && labelValue.length > 0 ? labelValue : sourceKey, type: inferredColumnType(rows, sourceKey) }
+  })
+  const normalizedRows = rows.map(row => Object.fromEntries(columns.map((column, index) => [column.key, row[keys[index]]])))
+  return { columns, rows: normalizedRows }
+}
+
+export function projectRowsToColumns(rows: Array<Record<string, unknown>>, columns: SheetColumn[]): Array<Record<string, unknown>> {
+  return rows.map(row => Object.fromEntries(columns.map(column => {
+    if (Object.hasOwn(row, column.key)) return [column.key, row[column.key]]
+    if (Object.hasOwn(row, column.label)) return [column.key, row[column.label]]
+    return [column.key, undefined]
+  })))
+}
+
+export function inferredColumnType(rows: Array<Record<string, unknown>>, key: string): SheetColumnType {
+  const values = rows.map(row => row[key]).filter(value => value !== undefined && value !== null)
+  if (values.length > 0 && values.every(value => typeof value === 'boolean')) return 'boolean'
+  if (values.length > 0 && values.every(value => typeof value === 'number' && Number.isFinite(value))) return 'number'
+  return 'string'
+}
+
+/**
+ * A rejected edit plan used to come back as a bare message, so the caller had
+ * to replay the whole payload just to discover what it had sent (docs/issue/0011
+ * I8 / T7). Every validation failure now names the shape that was received and
+ * says that only the offending command has to change; `details` carries the
+ * same facts as data for callers that can read them.
+ */
+export function withEditRetryContext(error: unknown, args: { workbookId: string; versions?: unknown; commands?: unknown }): DataSheetError {
+  if (error instanceof DataSheetError) return error
+  const message = error instanceof Error ? error.message : String(error)
+  const commandList = Array.isArray(args.commands) ? args.commands : []
+  const versionList = Array.isArray(args.versions) ? args.versions : []
+  const types = commandList.map(entry => (
+    typeof entry === 'object' && entry !== null ? String((entry as Record<string, unknown>).type ?? '?') : '?'
+  ))
+  const shape = versionList.length > 0
+    ? `${versionList.length} 个 version 分组`
+    : `${commandList.length} 条命令${types.length === 0 ? '' : `（${[...new Set(types)].join('、')}）`}`
+  return new DataSheetError(
+    'VALIDATION_ERROR',
+    `${message}；已收参数：workbookId=${args.workbookId}，${shape}。修正出错的那条命令后重试即可，不必重发整份 payload。`,
+    400,
+    {
+      workbookId: args.workbookId,
+      versionCount: versionList.length,
+      commandCount: commandList.length,
+      commandTypes: [...new Set(types)],
+    },
+  )
+}
+
+export async function executeWorkbookEdit(args: {
+  workbookId: string
+  versions: unknown
+  commands: unknown
+  baseRevision?: number
+  opId?: string
+  intent?: string
+  agentRunId?: string
+  lineage?: LineageContext
+  dryRun: boolean
+}): Promise<unknown> {
+  const warnings: string[] = []
+  let parsedVersions: ParsedEditVersion[]
+  try {
+    parsedVersions = await parseEditVersionGroups(args.versions, args.commands, args.intent, warnings, args.workbookId)
+  } catch (error) {
+    throw withEditRetryContext(error, args)
+  }
+  const meta = await readWorkbook(args.workbookId)
+  if (meta === null) throw new Error('工作簿不存在：' + args.workbookId)
+  const versions = bindEditVersionGroups(meta.snapshot, parsedVersions, args.workbookId)
+  collectDuplicateCellWrites(versions, warnings)
+  const commands = versions.flatMap(version => version.commands)
+  const importSteps = collectImportFileSteps(versions)
+  const currentRevision = meta.revision ?? 0
+  const steps = versions.map((version, index) => {
+    const operationId = args.opId === undefined ? undefined : versions.length === 1 ? args.opId : args.opId + ':version:' + (index + 1)
+    return {
+      type: 'batch' as const,
+      // Only the durable { type, payload } shape is persisted: the Agent-facing
+      // import receipt metadata must not change the Version/Step model or the
+      // request hash (and therefore opId idempotency).
+      payload: { operations: version.commands.map(command => ({ type: command.type, payload: command.payload })) },
+      opId: operationId,
+      versionId: newAgentVersionId(args.workbookId, operationId),
+      versionSummary: version.summary,
+      // One Agent tool call is a deliberate Version, not session churn (§4.2).
+      versionKind: 'named' as const,
+      versionIntent: version.intent,
+      agentRunId: args.agentRunId,
+      lineage: args.lineage,
+    }
+  })
+  // dryRun shares this exact call: the same opId checks, payload resolution,
+  // `applyWorkbookOperation` validation and revision accounting run before the
+  // manager decides whether to persist.
+  const plan = await mutateWorkbookPlan({
+    workbookId: args.workbookId,
+    actor: 'agent',
+    steps,
+    expectedRevision: args.baseRevision,
+    ...(args.dryRun ? { dryRun: true } : {}),
+  })
+  const committedVersions = plan.operations
+  const revisionAfter = plan.meta.revision ?? currentRevision
+  const last = committedVersions.at(-1)
+  const affected = summarizeAffectedSheets(versions, plan.meta.snapshot)
+  // A replayed plan wrote nothing this turn, so no receipt may be fabricated:
+  // the file on disk may have changed since the original write and the sheet
+  // still holds the earlier content. `replayed: true` tells the caller to read
+  // the workbook instead of trusting a proof from this turn.
+  const imports = plan.replayed === true ? [] : importSteps.map(step => importFileReceipt(step, {
+    workbookId: args.workbookId,
+    revisionBefore: currentRevision,
+    revisionAfter,
+    snapshotBefore: meta.snapshot,
+    snapshotAfter: plan.meta.snapshot,
+  }))
+  for (const receipt of imports) for (const warning of receipt.warnings) warnings.push(warning)
+  return {
+    ok: true,
+    ...(args.dryRun ? { dryRun: true } : {}),
+    workbookId: args.workbookId,
+    revision: args.dryRun ? currentRevision : revisionAfter,
+    revisionBefore: currentRevision,
+    revisionAfter,
+    versionCount: committedVersions.length,
+    commandCount: commands.length,
+    affectedSheets: affected.sheets,
+    sheetRefs: affected.refs,
+    affectedCellCount: affected.cellCount,
+    ...(imports.length === 0 ? {} : { imports }),
+    ...(warnings.length === 0 ? {} : { warnings }),
+    ...(plan.replayed === true ? { replayed: true } : {}),
+    ...(plan.transformed === true
+      ? { transformed: true, rebasedOperations: plan.rebasedOperations ?? [] }
+      : {}),
+    ...(args.intent === undefined ? {} : { intent: args.intent }),
+    ...(args.agentRunId === undefined ? {} : { agentRunId: args.agentRunId }),
+    ...(args.lineage === undefined ? {} : { lineage: args.lineage }),
+    versions: committedVersions.map((operation, index) => ({
+      ...operationReceipt(operation),
+      summary: versions[index]?.summary ?? operation.versionSummary ?? '',
+      ...(versions[index]?.intent === undefined ? {} : { intent: versions[index]?.intent }),
+      stepCount: versions[index]?.commands.length ?? workbookOperationSteps(operation).length,
+      commands: (versions[index]?.commands ?? []).map(command => ({ type: command.type, sheet: command.payload.sheetId ?? command.payload.sheetName ?? null })),
+    })),
+    ...(last === undefined ? {} : { operation: operationReceipt(last) }),
+  }
+}
+
+/**
+ * One `import_file` step after binding (its sheet reference is resolved). The
+ * command itself is already normalized to a durable `update_cells` payload.
+ */
+export interface ImportFileStep {
+  type: WorkbookOperationType
+  payload: WorkbookOperationPayload
+  importFile: ImportFileMeta
+}
+
+export function collectImportFileSteps(versions: readonly ParsedEditVersion[]): ImportFileStep[] {
+  const steps: ImportFileStep[] = []
+  for (const version of versions) {
+    for (const command of version.commands) {
+      if (command.importFile === undefined) continue
+      steps.push({ type: command.type, payload: command.payload, importFile: command.importFile })
+    }
+  }
+  return steps
+}
+
+/** One Agent-facing import receipt for a single `import_file` command. */
+export interface ImportFileReceipt {
+  workbookId: string
+  revisionBefore: number
+  revisionAfter: number
+  sheetId: string | null
+  range: WorkbookRange
+  rowsWritten: number
+  cellsWritten: number
+  sourceRowCount: number
+  truncated: boolean
+  sourcePath: string
+  rowCountBefore: number | null
+  rowCountAfter: number | null
+  capacityExpanded: boolean
+  firstRow: unknown[]
+  lastRow: unknown[]
+  valuesHash: string
+  warnings: string[]
+}
+
+/**
+ * Self-verifying import receipt: range/row/cell counts, source size, a content
+ * digest plus first/last row samples, and the auto-expansion result so the
+ * Agent never has to reread the whole range to prove the write landed.
+ */
+export function importFileReceipt(step: ImportFileStep, context: {
+  workbookId: string
+  revisionBefore: number
+  revisionAfter: number
+  snapshotBefore: unknown
+  snapshotAfter: unknown
+}): ImportFileReceipt {
+  const meta = step.importFile
+  const sheetId = step.payload.sheetId ?? null
+  const rowCountBefore = snapshotRowCapacity(context.snapshotBefore, sheetId)
+  const rowCountAfter = snapshotRowCapacity(context.snapshotAfter, sheetId)
+  const capacityExpanded = rowCountBefore !== null && rowCountAfter !== null && rowCountAfter > rowCountBefore
+  const receiptWarnings: string[] = []
+  if (capacityExpanded && meta.verifyCapacity) {
+    receiptWarnings.push(`import_file 自动扩容：${sheetId ?? '(Host 推断的 sheet)'} rowCount ${rowCountBefore} → ${rowCountAfter}（写入到第 ${meta.range.endRow + 1} 行），无需 insert_rows`)
+  }
+  if (meta.truncated) {
+    receiptWarnings.push(`import_file 按 allowTruncate 只导入了源文件 ${meta.sourceRowCount} 行中的前 ${meta.rowsWritten} 行，其余未写入`)
+  }
+  return {
+    workbookId: context.workbookId,
+    revisionBefore: context.revisionBefore,
+    revisionAfter: context.revisionAfter,
+    sheetId,
+    range: meta.range,
+    rowsWritten: meta.rowsWritten,
+    cellsWritten: meta.cellsWritten,
+    sourceRowCount: meta.sourceRowCount,
+    truncated: meta.truncated,
+    sourcePath: meta.sourcePath,
+    rowCountBefore,
+    rowCountAfter,
+    capacityExpanded,
+    firstRow: meta.firstRow,
+    lastRow: meta.lastRow,
+    valuesHash: meta.valuesHash,
+    warnings: receiptWarnings,
+  }
+}
+
+/** Physical row capacity (`rowCount`) of one sheet in a snapshot. */
+export function snapshotRowCapacity(snapshot: unknown, sheetRef: string | null): number | null {
+  if (sheetRef === null) return null
+  try {
+    const sheet = snapshotSheet(snapshot, sheetRef)
+    return typeof sheet.rowCount === 'number' ? sheet.rowCount : null
+  } catch {
+    return null
+  }
+}
+
+/** Receipt data that lets an Agent prove what a write touched without rereading storage. */
+export function summarizeAffectedSheets(versions: readonly ParsedEditVersion[], snapshot: unknown): { sheets: string[]; refs: Array<{ name: string; sheetId: string }>; cellCount: number } {
+  const names = new Map(sheetOverviews(snapshot).map(sheet => [sheet.id, sheet.name]))
+  const labels = new Set<string>()
+  const refs = new Map<string, { name: string; sheetId: string }>()
+  let cellCount = 0
+  for (const version of versions) {
+    for (const command of version.commands) {
+      const sheetId = command.payload.sheetId ?? command.payload.sheetName
+      const label = typeof sheetId === 'string' && sheetId.length > 0
+        ? `${names.get(sheetId) ?? sheetId}(${sheetId})`
+        : '(由 Host 推断)'
+      labels.add(label)
+      // The readable mapping is also published as data: sheet ids are hashes,
+      // and a caller that just created a sheet needs the id without parsing the
+      // "name(id)" label back out (docs/issue/0011 I6 / T7).
+      if (typeof sheetId === 'string' && sheetId.length > 0) {
+        refs.set(sheetId, { name: names.get(sheetId) ?? sheetId, sheetId })
+      }
+      const payload = command.payload
+      if (Array.isArray(payload.cells)) cellCount += payload.cells.length
+      else if (Array.isArray(payload.rows)) cellCount += payload.rows.length * (Array.isArray(payload.columns) ? payload.columns.length : 0)
+      else if (payload.range !== undefined) {
+        cellCount += (payload.range.endRow - payload.range.startRow + 1) * (payload.range.endColumn - payload.range.startColumn + 1)
+      }
+    }
+  }
+  return { sheets: [...labels], refs: [...refs.values()], cellCount }
+}
+
+export function newAgentVersionId(workbookId: string, opId?: string): string {
+  const suffix = opId === undefined
+    ? randomUUID().slice(0, 12)
+    : createHash('sha256').update(opId).digest('hex').slice(0, 16)
+  return `agent-version:${workbookId}:${suffix}`
+}
+
+export function parseStyle(value: unknown): NonNullable<WorkbookOperationPayload['style']> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) throw new Error('style 必须是对象')
+  const raw = value as Record<string, unknown>
+  const style: NonNullable<WorkbookOperationPayload['style']> = {}
+  for (const key of ['ff', 'bg', 'cl', 'n'] as const) {
+    if (raw[key] !== undefined) {
+      if (typeof raw[key] !== 'string') throw new Error(`style.${key} 必须是字符串`)
+      style[key] = raw[key]
+    }
+  }
+  for (const key of ['fs', 'ht', 'vt', 'tr'] as const) {
+    if (raw[key] !== undefined) {
+      if (typeof raw[key] !== 'number' || !Number.isFinite(raw[key])) throw new Error(`style.${key} 必须是有限数字`)
+      style[key] = raw[key]
+    }
+  }
+  for (const key of ['bl', 'it', 'ul', 'st'] as const) {
+    if (raw[key] !== undefined) {
+      if (typeof raw[key] !== 'boolean') throw new Error(`style.${key} 必须是布尔值`)
+      style[key] = raw[key]
+    }
+  }
+  return style
+}
+
+
+
+export function parseSheetMeta(value: unknown): { source?: string; query?: string; generatedAt?: string; notes?: string } | undefined {
+  if (value === undefined || value === null) return undefined
+  if (typeof value !== 'object' || Array.isArray(value)) throw new Error('meta 必须是对象')
+  const raw = value as Record<string, unknown>
+  const meta: { source?: string; query?: string; generatedAt?: string; notes?: string } = {}
+  for (const key of ['source', 'query', 'generatedAt', 'notes'] as const) {
+    if (raw[key] !== undefined) {
+      if (typeof raw[key] !== 'string') throw new Error(`meta.${key} 必须是字符串`)
+      meta[key] = raw[key]
+    }
+  }
+  return meta
+}