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

package/src/store/write.ts

@@ -0,0 +1,230 @@
+/**
+ * The only module that replaces a workbook's bytes (docs/issue/0022 P1).
+ *
+ * Every commit is a write-ahead journal plus temp-file renames, so an
+ * interrupted save is finished by the next read rather than leaving half a
+ * workbook on disk. It takes the journal lock from `store/read.ts` so a commit
+ * can never interleave with the recovery of another.
+ */
+import { mkdir, rename, rm, unlink, writeFile } from 'node:fs/promises'
+import { randomUUID } from 'node:crypto'
+import { DEFAULT_WORKBOOK, type WorkbookMeta, type WorkbookWorktree } from '../types.ts'
+import { normalizeWorkbookId, normalizeWorktreeId } from '../contract/ids.ts'
+import { PROPOSAL_LOG_LIMIT, operationSummary } from '../contract/operations.ts'
+import { validateSnapshotBounds } from '../contract/mutations.ts'
+import { cloneSnapshot, normalizeSnapshotName } from '../contract/snapshots.ts'
+import {
+  workbookCheckpointsPath,
+  workbookIndexPath,
+  workbookOperationsPath,
+  workbookPath,
+  workbookProposalsPath,
+  workbookRoot,
+  workbookSnapshotPath,
+  workbookTransactionPath,
+  workbookWorktreeDirectory,
+  workbookWorktreePath,
+} from './paths.ts'
+import {
+  fileExists,
+  readWorkbook,
+  recoverWorkbookTransactionNow,
+  summarize,
+  withWorkbookTransactionQueue,
+  workbookCache,
+  type StoredWorkbookTransaction,
+  type WorkbookIndex,
+  type WorkbookTransactionFile,
+} from './read.ts'
+
+/** Write one workbook meta atomically (creates the repo root on demand). */
+export async function writeWorkbook(meta: WorkbookMeta, options: { persistSnapshot?: boolean; persistCheckpoints?: boolean } = {}): Promise<void> {
+  const normalizedId = normalizeWorkbookId(meta.id)
+  await withWorkbookTransactionQueue(normalizedId, async () => {
+    await mkdir(workbookRoot(), { recursive: true })
+    await recoverWorkbookTransactionNow(normalizedId)
+    // The DSH metadata name is the user-facing workbook name. Keep the Univer
+    // snapshot name aligned so exports and other consumers use the same name.
+    const normalizedMeta = { ...meta, id: normalizedId, snapshot: normalizeSnapshotName(meta.snapshot, meta.name) }
+    validateSnapshotBounds(normalizedMeta.snapshot)
+    const operationLog = normalizedMeta.operations ?? []
+    const proposalLog = normalizedMeta.proposals ?? []
+    // Versions are the durable audit trail. Keep the append-only operation log
+    // instead of truncating it to a recent tail so old versions can be replayed.
+    normalizedMeta.operations = operationLog
+    // The single place this bound is applied, since every write comes through here.
+    normalizedMeta.proposals = proposalLog.slice(-PROPOSAL_LOG_LIMIT)
+    const snapshotExists = await fileExists(workbookSnapshotPath(normalizedId))
+    const persistSnapshot = options.persistSnapshot === true || !snapshotExists
+    const checkpointsExist = await fileExists(workbookCheckpointsPath(normalizedId))
+    const snapshotRevision = persistSnapshot
+      ? normalizedMeta.revision ?? 0
+      : (typeof normalizedMeta.snapshotRevision === 'number' ? normalizedMeta.snapshotRevision : 0)
+    const {
+      snapshot: _snapshot,
+      checkpoints: _checkpoints,
+      operations: _operations,
+      proposals: _proposals,
+      ...metadata
+    } = normalizedMeta
+    const metadataWithSnapshotRevision = { ...metadata, snapshotRevision }
+    const files: WorkbookTransactionFile[] = [
+      { target: workbookOperationsPath(normalizedId), value: normalizedMeta.operations ?? [] },
+      { target: workbookProposalsPath(normalizedId), value: normalizedMeta.proposals ?? [] },
+      { target: workbookPath(normalizedId), value: metadataWithSnapshotRevision },
+      { target: workbookIndexPath(normalizedId), value: buildWorkbookIndex(normalizedMeta) },
+    ]
+    if (persistSnapshot) files.unshift({ target: workbookSnapshotPath(normalizedId), value: { revision: normalizedMeta.revision ?? 0, snapshot: normalizedMeta.snapshot } })
+    if (options.persistCheckpoints === true || !checkpointsExist) files.splice(persistSnapshot ? 1 : 0, 0, { target: workbookCheckpointsPath(normalizedId), value: { checkpoints: normalizedMeta.checkpoints ?? [] } })
+    await commitWorkbookTransaction(normalizedId, files, normalizedMeta.revision ?? 0)
+    workbookCache.set(normalizedId, {
+      meta: { ...normalizedMeta, snapshotRevision, checkpoints: normalizedMeta.checkpoints ?? [] },
+      checkpointsLoaded: options.persistCheckpoints === true || !checkpointsExist,
+    })
+  })
+}
+
+export async function writeJsonAtomically(path: string, value: unknown): Promise<void> {
+  const tempPath = `${path}.${process.pid}.${randomUUID()}.tmp`
+  try {
+    await writeFile(tempPath, JSON.stringify(value, null, 2), 'utf8')
+    await rename(tempPath, path)
+  } finally {
+    try { await unlink(tempPath) } catch { /* rename already removed it */ }
+  }
+}
+
+export async function commitWorkbookTransaction(id: string, files: WorkbookTransactionFile[], revision: number): Promise<void> {
+  const transactionId = randomUUID()
+  const journalPath = workbookTransactionPath(id)
+  const prepared = files.map(file => ({ target: file.target, temp: `${file.target}.${transactionId}.tmp` }))
+  let journalWritten = false
+  try {
+    for (const [index, file] of files.entries()) {
+      await writeFile(prepared[index]!.temp, JSON.stringify(file.value, null, 2), 'utf8')
+    }
+    await writeJsonAtomically(journalPath, { revision, files: prepared } satisfies StoredWorkbookTransaction)
+    journalWritten = true
+    for (const file of prepared) await rename(file.temp, file.target)
+    await unlink(journalPath)
+  } catch (error) {
+    // Once the journal exists, its prepared files are intentionally retained
+    // so the next read can complete the commit. Before that point cleanup is
+    // safe because no target has been replaced.
+    if (!journalWritten) {
+      await Promise.all(prepared.map(file => unlink(file.temp).catch(() => undefined)))
+    }
+    throw error
+  }
+}
+
+export async function writeWorktree(worktree: WorkbookWorktree): Promise<void> {
+  await mkdir(workbookWorktreeDirectory(worktree.workbookId), { recursive: true })
+  await writeJsonAtomically(workbookWorktreePath(worktree.workbookId, worktree.id), worktree)
+}
+
+export function buildWorkbookIndex(meta: WorkbookMeta): WorkbookIndex {
+  const summary = summarize(meta)
+  return {
+    id: summary.id,
+    name: summary.name,
+    sheetOrder: summary.sheets.map(sheet => sheet.id),
+    sheets: summary.sheets,
+    updatedAt: summary.updatedAt,
+    revision: meta.revision ?? 0,
+    operations: (meta.operations ?? []).map(operation => ({
+      opId: operation.opId,
+      workbookId: operation.workbookId,
+      revision: operation.revision,
+      actor: operation.actor,
+      type: operation.type,
+      timestamp: operation.timestamp,
+      summary: operationSummary(operation),
+    })),
+    proposals: (meta.proposals ?? []).map(({ snapshot: _snapshot, ...proposal }) => proposal),
+  }
+}
+
+/**
+ * Delete a workbook and all of its Datasheet sidecars. `main` is the stable
+ * default workbook and is intentionally protected from accidental deletion.
+ * The queue makes deletion serialize with an in-flight save for the same id.
+ */
+export async function deleteWorkbook(id: string): Promise<void> {
+  const normalizedId = normalizeWorkbookId(id)
+  if (normalizedId === DEFAULT_WORKBOOK) throw new Error('默认工作簿 main 不能删除')
+  await withWorkbookQueue(normalizedId, async () => {
+    workbookCache.delete(normalizedId)
+    const paths = [
+      workbookPath(normalizedId),
+      workbookIndexPath(normalizedId),
+      workbookSnapshotPath(normalizedId),
+      workbookCheckpointsPath(normalizedId),
+      workbookOperationsPath(normalizedId),
+      workbookProposalsPath(normalizedId),
+      workbookTransactionPath(normalizedId),
+    ]
+    for (const path of paths) {
+      try { await unlink(path) } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+      }
+    }
+    await rm(workbookWorktreeDirectory(normalizedId), { recursive: true, force: true })
+  })
+}
+
+/** Rename the user-facing workbook label without changing its stable id or
+ * history. The snapshot name is kept in sync by `writeWorkbook`. */
+export async function renameWorkbook(id: string, name: string): Promise<WorkbookMeta> {
+  const normalizedId = normalizeWorkbookId(id)
+  const normalizedName = name.trim()
+  if (normalizedName.length === 0) throw new Error('工作簿名称不能为空')
+  return withWorkbookQueue(normalizedId, async () => {
+    const existing = await readWorkbook(normalizedId)
+    if (existing === null) throw new Error(`工作簿不存在：${id}`)
+    const meta = cloneSnapshot(existing) as WorkbookMeta
+    meta.name = normalizedName
+    meta.updatedAt = new Date().toISOString()
+    await writeWorkbook(meta)
+    return meta
+  })
+}
+
+/** Serialize mutations (and worktree writes) per id.
+ * `deleteWorkbook` and `renameWorkbook` take the same lock as `mutateWorkbook`,
+ * so a delete can never interleave with an in-flight save. The manager imports
+ * them from here rather than owning them, because the store must not depend on
+ * its callers. */
+
+const mutationQueues = new Map<string, Promise<void>>()
+
+const worktreeQueues = new Map<string, Promise<void>>()
+
+export async function withWorkbookQueue<T>(id: string, task: () => Promise<T>): Promise<T> {
+  const previous = mutationQueues.get(id) ?? Promise.resolve()
+  let release!: () => void
+  const current = new Promise<void>(resolveRelease => { release = resolveRelease })
+  mutationQueues.set(id, current)
+  await previous
+  try {
+    return await task()
+  } finally {
+    release()
+    if (mutationQueues.get(id) === current) mutationQueues.delete(id)
+  }
+}
+
+export async function withWorktreeQueue<T>(workbookId: string, worktreeId: string, task: () => Promise<T>): Promise<T> {
+  const key = `${normalizeWorkbookId(workbookId)}:${normalizeWorktreeId(worktreeId)}`
+  const previous = worktreeQueues.get(key) ?? Promise.resolve()
+  let release!: () => void
+  const current = new Promise<void>(resolveRelease => { release = resolveRelease })
+  worktreeQueues.set(key, current)
+  await previous
+  try {
+    return await task()
+  } finally {
+    release()
+    if (worktreeQueues.get(key) === current) worktreeQueues.delete(key)
+  }
+}

package/src/tools/arguments.ts

@@ -0,0 +1,128 @@
+/**
+ * Reading tool arguments (docs/issue/0022 P3b).
+ *
+ * The Agent hands a tool an untyped record; every field has to be validated
+ * before it can become part of an operation. These are the conversions several
+ * tools share — the ones only one tool needs live in that tool.
+ */
+import { SHEET_MAX_ROWS, type WorkbookCellDeleteShift } from '../types.ts'
+import { normalizeWorkbookId } from '../contract/ids.ts'
+import { parseIndex } from '../request-params.ts'
+
+export type ToolArguments = Record<string, unknown>
+
+export function asToolArguments(value: unknown, label = '参数'): ToolArguments {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) throw new Error(label + '必须是对象')
+  return value as ToolArguments
+}
+
+/** Validate and normalize a workbook id argument. There is no implicit
+ * `main`: every Agent call must identify the workbook it intends to change. */
+export function workbookIdOf(raw: unknown): string {
+  if (typeof raw !== 'string' || raw.trim().length === 0) {
+    throw new Error('必须明确指定 workbookId；请先调用 workbook_catalog(action=list) 获取工作簿 id')
+  }
+  return normalizeWorkbookId(raw)
+}
+
+/** ISO timestamp helper. */
+export function now(): string {
+  return new Date().toISOString()
+}
+
+export function optionalIntent(value: unknown, name = 'intent'): string | undefined {
+  if (value === undefined || value === null) return undefined
+  if (typeof value !== 'string' || value.trim().length === 0 || value.trim().length > 280) throw new Error(`${name} 必须是 1 到 280 字符的字符串`)
+  return value.trim()
+}
+
+export function optionalAuditText(value: unknown, name: string, maxLength: number): string | undefined {
+  if (value === undefined || value === null) return undefined
+  if (typeof value !== 'string' || value.trim().length === 0 || value.trim().length > maxLength) throw new Error(`${name} 必须是 1 到 ${maxLength} 字符的字符串`)
+  return value.trim()
+}
+
+export function optionalString(value: unknown): string | undefined {
+  if (value === undefined || value === null) return undefined
+  if (typeof value !== 'string' || value.trim().length === 0) throw new Error('opId 必须是非空字符串')
+  return value.trim()
+}
+
+export function parseCount(value: unknown): number {
+  const count = parseIndex(value, 'count')
+  if (count < 1 || count > SHEET_MAX_ROWS) throw new Error(`count 必须是 1 到 ${SHEET_MAX_ROWS} 之间的整数`)
+  return count
+}
+
+/**
+ * `verifyHeader` defaults to true because comparing header labels is the only
+ * guard that catches a column order or rename mistake before rows are written.
+ * Only an explicit `false` relaxes it.
+ */
+export function parseHeaderVerification(value: unknown, label: string): boolean {
+  if (value === undefined || value === null) return true
+  if (typeof value !== 'boolean') throw new Error(`${label} 必须是布尔值`)
+  return value
+}
+
+export function parseCellDeleteShift(value: unknown): WorkbookCellDeleteShift {
+  if (value === undefined || value === null || value === '') return 'clear'
+  if (value === 'clear' || value === 'left' || value === 'up') return value
+  throw new Error('shift 必须是 clear、left 或 up')
+}
+
+export function commandPayload(raw: ToolArguments): ToolArguments {
+  const nested = raw.payload
+  if (nested === undefined || nested === null) return raw
+  if (typeof nested !== 'object' || Array.isArray(nested)) throw new Error('command.payload 必须是对象')
+  // Permit callers to send the durable { type, payload } shape while keeping
+  // the documented flat command shape. Explicit top-level fields win.
+  return { ...(nested as ToolArguments), ...raw }
+}
+
+/**
+ * Accept the vocabulary used by both the public Agent tool and the Univer
+ * facade. Older callers use `sheet`, while generated calls often use the
+ * persisted field name `sheetId` or the human-facing `sheetName`.
+ */
+export function sheetRefFromArguments(raw: ToolArguments, label = 'sheet'): string | undefined {
+  const candidates = ['sheet', 'sheetId', 'sheetName', 'sheet_id', 'sheet_name']
+    .filter(key => raw[key] !== undefined && raw[key] !== null && raw[key] !== '')
+  if (candidates.length === 0) return undefined
+  const refs = candidates.map(key => parseNonEmptyString(raw[key], `${label}.${key}`))
+  const first = refs[0] as string
+  if (refs.some(ref => ref !== first)) throw new Error(`${label}、sheetId、sheetName 只能指定同一个 sheet`)
+  return first
+}
+
+/** Resolve an optional Agent sheet reference. A missing reference is safe only
+ * when the workbook has one sheet; otherwise returning the first sheet would
+ * make a write silently target the wrong tab. */
+export function sheetRefForSnapshot(snapshot: unknown, raw: ToolArguments, label: string): string {
+  const explicit = sheetRefFromArguments(raw, label)
+  if (explicit !== undefined) return explicit
+  const root = asToolArguments(snapshot, 'workbook snapshot')
+  const order = Array.isArray(root.sheetOrder) ? root.sheetOrder.filter(item => typeof item === 'string') as string[] : []
+  if (order.length === 1 && order[0] !== undefined) return order[0]
+  const sheets = typeof root.sheets === 'object' && root.sheets !== null && !Array.isArray(root.sheets)
+    ? Object.entries(root.sheets as Record<string, unknown>).map(([id, value]) => {
+      const sheet = value !== null && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : {}
+      return `${id}${typeof sheet.name === 'string' ? `（${sheet.name}）` : ''}`
+    })
+    : []
+  throw new Error(`${label} 缺少 sheet；当前工作簿有多个 sheet，请使用 sheetId 或 sheetName：${sheets.join('、')}`)
+}
+
+export function commandSheet(raw: ToolArguments, index: number, _optional = false): string | undefined {
+  return sheetRefFromArguments(raw, 'commands[' + index + '].sheet')
+}
+
+export function commandIndex(raw: ToolArguments, index: number, field: 'index' | 'startRow' | 'startColumn'): number {
+  const value = raw[field] ?? (field === 'startRow' ? raw.index : field === 'startColumn' ? raw.index : undefined)
+  return parseIndex(value, 'commands[' + index + '].' + field)
+}
+
+export function parseNonEmptyString(value: unknown, label: string): string {
+  if (typeof value !== 'string' || value.trim().length === 0) throw new Error(`${label} 必须是非空字符串`)
+  return value.trim()
+}

package/src/tools/cells.ts

@@ -0,0 +1,298 @@
+/**
+ * Payload vocabulary shared by the two tools that write to a workbook
+ * (docs/issue/0022 P3b).
+ *
+ * `workbook_edit` and `univer_api` both accept a value matrix plus a range, both
+ * accept cells whose value comes from a file, both declare a table's columns, and
+ * both size a row or column. That translation lives here rather than in either
+ * tool: a tool importing the other tool is exactly the coupling this phase
+ * exists to prevent, and every helper here is about building a payload, not about
+ * which endpoint received it.
+ */
+import { statSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { resolve } from 'node:path'
+import {
+  SHEET_MAX_COLUMNS,
+  SHEET_MAX_NAME,
+  SHEET_MAX_ROWS,
+  type SheetColumn,
+  type SheetColumnType,
+  type WorkbookCellUpdate,
+  type WorkbookOperationPayload,
+  type WorkbookRange,
+} from '../types.ts'
+import { parseA1Range, parseIndex, parseRange } from '../request-params.ts'
+import { asToolArguments, parseNonEmptyString, type ToolArguments } from './arguments.ts'
+
+
+/** Sheet column types a modelled table may declare. */
+const COLUMN_TYPES: readonly SheetColumnType[] = ['string', 'number', 'boolean', 'date', 'currency']
+
+export function parseCells(value: unknown): WorkbookCellUpdate[] {
+  if (!Array.isArray(value) || value.length === 0) throw new Error('cells 必须是非空数组')
+  if (value.length > SHEET_MAX_ROWS * SHEET_MAX_COLUMNS) throw new Error('一次修改的单元格数量超过上限')
+  return value.map((item, index) => {
+    if (typeof item !== 'object' || item === null || Array.isArray(item)) throw new Error(`第 ${index + 1} 个 cell 不是对象`)
+    const raw = item as Record<string, unknown>
+    const cellValue = raw.value
+    if (cellValue !== null && typeof cellValue !== 'string' && typeof cellValue !== 'number' && typeof cellValue !== 'boolean') {
+      throw new Error(`第 ${index + 1} 个 cell 的 value 必须是 string/number/boolean/null`)
+    }
+    if (typeof cellValue === 'number' && !Number.isFinite(cellValue)) throw new Error(`第 ${index + 1} 个 cell 的 value 不是有限数字`)
+    if (raw.formula !== undefined && typeof raw.formula !== 'string') throw new Error(`第 ${index + 1} 个 cell 的 formula 必须是字符串`)
+    return {
+      row: parseIndex(raw.row, `cells[${index}].row`),
+      column: parseIndex(raw.column, `cells[${index}].column`),
+      value: cellValue as WorkbookCellUpdate['value'],
+      ...(raw.formula === undefined ? {} : { formula: raw.formula }),
+    }
+  })
+}
+
+/**
+ * Resolve `cells[].valueFromFile` into a literal value (docs/issue/0011 I4 / T7).
+ *
+ * Long text had to be inlined into the tool call, and the same SQL was retyped
+ * into every workbook that needed it. A cell may now name a local text file
+ * instead. The content is read here and handed to the ordinary `parseCells`
+ * validation, so nothing bypasses the existing cell limits.
+ */
+export async function resolveCellFileValues(value: unknown[], label: string): Promise<unknown[]> {
+  return Promise.all(value.map(async (item, index) => {
+    if (typeof item !== 'object' || item === null || Array.isArray(item)) return item
+    const raw = item as Record<string, unknown>
+    if (raw.valueFromFile === undefined || raw.valueFromFile === null) return item
+    const path = resolve(parseNonEmptyString(raw.valueFromFile, `${label}.cells[${index}].valueFromFile`))
+    let info: { size: number; isFile(): boolean }
+    try { info = statSync(path) } catch { throw new Error(`${label}.cells[${index}].valueFromFile 文件不存在：${path}`) }
+    if (!info.isFile()) throw new Error(`${label}.cells[${index}].valueFromFile 不是文件：${path}`)
+    if (info.size > TEXT_CELL_MAX_BYTES) {
+      throw new Error(`${label}.cells[${index}].valueFromFile 文件过大（${info.size} 字节，上限 ${TEXT_CELL_MAX_BYTES}）`)
+    }
+    const content = await readFile(path, 'utf8')
+    const { valueFromFile: _consumed, ...rest } = raw
+    // An explicit `value` still wins, so the field is a fallback rather than an
+    // override that could silently disagree with the caller.
+    return raw.value === undefined ? { ...rest, value: content } : rest
+  }))
+}
+
+/**
+ * Resolve the target range of a value matrix.
+ *
+ * The matrix size is unambiguous, so it is the authority: `range` only needs
+ * to anchor the write, and a `range` whose declared end disagrees with
+ * `values` is corrected and reported as a warning instead of failing a large
+ * batch. End coordinates are inclusive, which the tool description now states.
+ */
+export function parseValueRange(value: unknown, matrix: unknown[][], label: string, warnings: string[] = []): WorkbookRange {
+  const rowCount = matrix.length
+  const columnCount = matrix[0]?.length ?? 0
+  const derived = (startRow: number, startColumn: number): WorkbookRange =>
+    parseRange({ startRow, startColumn, endRow: startRow + rowCount - 1, endColumn: startColumn + columnCount - 1 })
+  if (value === undefined || value === null) return derived(1, 0)
+
+  let startRow: number
+  let startColumn: number
+  let declaredEndRow: number | undefined
+  let declaredEndColumn: number | undefined
+  if (typeof value === 'string') {
+    const parsed = parseA1Range(value)
+    startRow = parsed.startRow
+    startColumn = parsed.startColumn
+    declaredEndRow = parsed.endRow
+    declaredEndColumn = parsed.endColumn
+  } else {
+    const raw = asToolArguments(value, label + '.range')
+    startRow = raw.startRow === undefined ? 1 : parseIndex(raw.startRow, label + '.range.startRow')
+    startColumn = raw.startColumn === undefined ? 0 : parseIndex(raw.startColumn, label + '.range.startColumn')
+    declaredEndRow = raw.endRow === undefined ? undefined : parseIndex(raw.endRow, label + '.range.endRow')
+    declaredEndColumn = raw.endColumn === undefined ? undefined : parseIndex(raw.endColumn, label + '.range.endColumn')
+  }
+
+  const target = derived(startRow, startColumn)
+  if (declaredEndRow === undefined && declaredEndColumn === undefined) return target
+  if (declaredEndRow === target.endRow && declaredEndColumn === target.endColumn) return target
+  // Supplying only the range origin is enough. A declared end that disagrees
+  // is downgraded to a warning: the values matrix already fixes the extent.
+  const declared = { endRow: declaredEndRow ?? target.endRow, endColumn: declaredEndColumn ?? target.endColumn }
+  if (declared.endRow < target.startRow || declared.endColumn < target.startColumn) {
+    throw new Error(`${label}.range 结束位置不能小于开始位置：range 为 rows ${startRow}-${declared.endRow} × cols ${startColumn}-${declared.endColumn}`)
+  }
+  const declaredRows = declared.endRow - target.startRow + 1
+  const declaredColumns = declared.endColumn - target.startColumn + 1
+  warnings.push(
+    `${label}.range 与 values 尺寸不一致：range 为 ${declaredRows}×${declaredColumns}（rows ${startRow}-${declared.endRow} × cols ${startColumn}-${declared.endColumn}），values 为 ${rowCount}×${columnCount}；已按 values 落位为 rows ${target.startRow}-${target.endRow} × cols ${target.startColumn}-${target.endColumn}（end 坐标 inclusive）`,
+  )
+  return target
+}
+
+export function parseApiValues(matrix: unknown[][], range: WorkbookRange): WorkbookCellUpdate[] {
+  const rowCount = range.endRow - range.startRow + 1
+  const columnCount = range.endColumn - range.startColumn + 1
+  if (matrix.length !== rowCount) throw new Error(`values 行数必须为 ${rowCount}`)
+  const cells: WorkbookCellUpdate[] = []
+  for (const [rowOffset, line] of matrix.entries()) {
+    if (line.length !== columnCount) throw new Error(`values[${rowOffset}] 列数必须为 ${columnCount}`)
+    for (const [columnOffset, cell] of line.entries()) {
+      if (cell !== null && typeof cell !== 'string' && typeof cell !== 'number' && typeof cell !== 'boolean') {
+        throw new Error(`values[${rowOffset}][${columnOffset}] 必须是 string/number/boolean/null`)
+      }
+      if (typeof cell === 'number' && !Number.isFinite(cell)) throw new Error('values 不能包含非有限数字')
+      cells.push({ row: range.startRow + rowOffset, column: range.startColumn + columnOffset, value: cell as WorkbookCellUpdate['value'] })
+    }
+  }
+  return cells
+}
+
+/** A single cell of long text (typically a SQL body) read from a local file. */
+export const TEXT_CELL_MAX_BYTES = 1024 * 1024
+
+export function parseFreeze(value: unknown): NonNullable<WorkbookOperationPayload['freeze']> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) throw new Error('freeze 必须是对象')
+  const raw = value as Record<string, unknown>
+  const rows = raw.rows === undefined ? 0 : parseIndex(raw.rows, 'freeze.rows')
+  const columns = raw.columns === undefined ? 0 : parseIndex(raw.columns, 'freeze.columns')
+  return { rows, columns }
+}
+
+export function parseSort(value: unknown): NonNullable<WorkbookOperationPayload['sort']> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) throw new Error('sort 必须是对象')
+  const raw = value as Record<string, unknown>
+  const direction = raw.direction === undefined ? 'asc' : raw.direction
+  if (direction !== 'asc' && direction !== 'desc') throw new Error('sort.direction 必须是 asc 或 desc')
+  return { column: parseIndex(raw.column, 'sort.column'), direction }
+}
+
+export interface ValidatedSheet {
+  name?: string
+  columns: SheetColumn[]
+  rows: Array<Record<string, unknown>>
+}
+
+export function cellValue(type: SheetColumnType, value: unknown): number | string | boolean {
+  switch (type) {
+    case 'number':
+    case 'currency': {
+      const numeric = typeof value === 'number' ? value : Number(value)
+      return Number.isFinite(numeric) ? numeric : String(value)
+    }
+    case 'boolean':
+      return typeof value === 'boolean' ? value : String(value) === 'true'
+    case 'date':
+      return value instanceof Date ? value.toISOString().slice(0, 10) : String(value)
+    default:
+      return String(value)
+  }
+}
+
+/** Validate one sheet argument; throws a model-facing message on bad input. */
+export function validateSheet(args: { name: unknown; columns?: unknown; rows: unknown }): ValidatedSheet {
+  const name = args.name === undefined || args.name === null ? undefined : parseNonEmptyString(args.name, 'name')
+  if (name !== undefined && name.length > SHEET_MAX_NAME) throw new Error(`表格名称过长（最多 ${SHEET_MAX_NAME} 字符）`)
+  if (args.columns !== undefined && !Array.isArray(args.columns)) throw new Error('columns 必须是数组；已有 sheet 可省略，Host 会从表头推断')
+  const rawColumns = Array.isArray(args.columns) ? args.columns : []
+  if (rawColumns.length === 0 && !Array.isArray(args.rows)) throw new Error('至少需要一列')
+  if (rawColumns.length > SHEET_MAX_COLUMNS) throw new Error(`列数超过上限（最多 ${SHEET_MAX_COLUMNS} 列）`)
+  const keys = new Set<string>()
+  const columns: SheetColumn[] = rawColumns.map((column, index) => {
+    // Column-definition errors have to state the accepted structure and echo
+    // what arrived: "列定义必须是对象" alone cost a debugging round in the
+    // original session (docs/issue/0011 I7 / T6).
+    if (typeof column !== 'object' || column === null || Array.isArray(column)) {
+      throw new Error(`列定义必须是对象：columns[${index}] 期望 { key, label, type }，实际收到 ${JSON.stringify(column) ?? String(column)}`)
+    }
+    const raw = column as Record<string, unknown>
+    if (typeof raw.key !== 'string' || !/^[A-Za-z0-9_]+$/.test(raw.key)) {
+      throw new Error(`列 key 必须是仅含字母、数字、下划线的非空字符串：columns[${index}] 期望 { key, label, type }，实际收到 ${JSON.stringify(raw)}`)
+    }
+    if (keys.has(raw.key)) throw new Error(`列 key 重复：${raw.key}（columns[${index}]）`)
+    keys.add(raw.key)
+    if (typeof raw.label !== 'string' || raw.label.length === 0) {
+      throw new Error(`列 ${raw.key} 缺少 label：期望 { key: ${JSON.stringify(raw.key)}, label: string, type: string }，实际收到 ${JSON.stringify(raw)}`)
+    }
+    if (!COLUMN_TYPES.includes(raw.type as SheetColumnType)) {
+      throw new Error(`列 ${raw.key} 类型未知：${String(raw.type)}；type 只能是 ${COLUMN_TYPES.join('、')}`)
+    }
+    return { key: raw.key, label: raw.label, type: raw.type as SheetColumnType }
+  })
+  if (!Array.isArray(args.rows)) throw new Error('rows 必须是数组')
+  if (args.rows.length > SHEET_MAX_ROWS) {
+    throw new Error(`行数超过上限（最多 ${SHEET_MAX_ROWS} 行）；请使用分页查询或拆成多个 workbook`)
+  }
+  const rows = args.rows.every(row => Array.isArray(row))
+    ? args.rows.map((row, index) => {
+      if (columns.length === 0) throw new Error('rows 使用二维数组时必须同时提供 columns')
+      const values = row as unknown[]
+      if (values.length > columns.length) throw new Error(`第 ${index + 1} 行列数超过 columns 定义`)
+      return Object.fromEntries(columns.map((column, columnIndex) => [column.key, values[columnIndex] ?? null]))
+    })
+    : args.rows.map((row, index) => {
+    if (typeof row !== 'object' || row === null || Array.isArray(row)) {
+      throw new Error(`第 ${index + 1} 行不是对象`)
+    }
+    return row as Record<string, unknown>
+  })
+  return { name, columns, rows }
+}
+
+export function chunkRows(rows: Array<Record<string, unknown>>, size: number): Array<Array<Record<string, unknown>>> {
+  const chunks: Array<Array<Record<string, unknown>>> = []
+  for (let start = 0; start < rows.length; start += size) chunks.push(rows.slice(start, start + size))
+  return chunks
+}
+
+export function dimensionRange(index: number, dimension: 'row' | 'column'): WorkbookRange {
+  return dimension === 'column'
+    ? { startRow: 0, startColumn: index, endRow: 0, endColumn: index }
+    : { startRow: index, startColumn: 0, endRow: index, endColumn: 0 }
+}
+
+/**
+ * Row/column structural commands accept either an explicit `range` (matching
+ * the documented command vocabulary) or the older `index`/`startRow` +
+ * `count` pair. Missing position arguments report the full accepted contract
+ * instead of the single `startRow` field the old implementation demanded.
+ */
+export function dimensionCommandRange(raw: ToolArguments, index: number, dimension: 'row' | 'column'): WorkbookRange {
+  const label = `commands[${index}]`
+  const positionField = dimension === 'row' ? 'startRow' : 'startColumn'
+  const endField = dimension === 'row' ? 'endRow' : 'endColumn'
+  const explicit = raw.range
+  if (typeof explicit === 'string') {
+    const parsed = parseA1Range(explicit)
+    return dimension === 'row'
+      ? { startRow: parsed.startRow, startColumn: 0, endRow: parsed.endRow, endColumn: 0 }
+      : { startRow: 0, startColumn: parsed.startColumn, endRow: 0, endColumn: parsed.endColumn }
+  }
+  const range = explicit === undefined || explicit === null ? undefined : asToolArguments(explicit, `${label}.range`)
+  const startValue = range?.[positionField] ?? raw[positionField] ?? raw.index
+  if (startValue === undefined || startValue === null) {
+    throw new Error(`${label} 缺少${dimension === 'row' ? '行' : '列'}位置：请传 ${label}.range:{${positionField},${endField}}（0-based，结束坐标 inclusive），或传 ${label}.index / ${label}.${positionField} 搭配 count`)
+  }
+  const start = parseIndex(startValue, `${label}.${positionField}`)
+  const rawEnd = range?.[endField]
+  const end = rawEnd === undefined || rawEnd === null ? start : parseIndex(rawEnd, `${label}.${endField}`)
+  if (end < start) throw new Error(`${label}.range 结束位置不能小于开始位置（${start} > ${end}）`)
+  return dimension === 'row'
+    ? { startRow: start, startColumn: 0, endRow: end, endColumn: 0 }
+    : { startRow: 0, startColumn: start, endRow: 0, endColumn: end }
+}
+
+export function parseFiniteNumber(value: unknown, label: string): number {
+  if (typeof value !== 'number' || !Number.isFinite(value)) throw new Error(`${label} 必须是有限数字`)
+  return value
+}
+
+export function parseHyperlink(value: unknown): string {
+  if (typeof value !== 'string' || value.trim().length === 0) throw new Error('url 必须是非空字符串')
+  const url = value.trim()
+  if (!/^(?:https?:|mailto:|file:|#)/i.test(url)) throw new Error('url 只支持 http(s)、mailto、file 或 sheet 内部链接')
+  return url
+}
+
+export function parseHyperlinkLabel(value: unknown): string {
+  if (typeof value !== 'string') throw new Error('label 必须是字符串')
+  return value
+}