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

package/lib/types/contract/mutations.js

@@ -0,0 +1,782 @@
+/**
+ * The snapshot mutator: one DSH operation in, the rewritten snapshot out
+ * (docs/issue/0022 P0/P1).
+ *
+ * Pure and Univer-free — it is the model's own answer to "what does this
+ * operation mean", and `store/read.ts` replays operations through it when a
+ * workbook's snapshot is older than its revision. It lives in `contract/`
+ * rather than in `store/` precisely because it is not about the disk: moving
+ * the read path into the store without it would have made `store/` import
+ * *up* into `workbook-manager`, which the architecture guard forbids.
+ */
+import { SHEET_MAX_COLUMNS, SHEET_MAX_PHYSICAL_ROWS, SHEET_MAX_ROWS, } from "../types.js";
+import { randomUUID } from 'node:crypto';
+import { asWorkbookSnapshot, cloneSnapshot, findDuplicateRows, isSheetSchema, resolveSheet, toCellValue, validateIndex, validateRange, DEFAULT_SHEET_ROWS, DEFAULT_SHEET_COLUMNS, normalizeCellFormula, } from "./snapshots.js";
+import { APPEND_HEADER_MISMATCH } from "./operations.js";
+/** Apply one DSH operation to a Univer-compatible snapshot. */
+export function applyWorkbookOperation(snapshot, operation) {
+    if (operation.type === 'snapshot_replace') {
+        validateSnapshotBounds(operation.payload.snapshot);
+        // A copy, not the payload itself. The replay loop in `store/read.ts` keeps
+        // applying later operations to whatever this returns, so handing back the
+        // caller's object makes the *stored* operation payload accumulate every
+        // later revision — and `store/write.ts` persists `meta.operations` verbatim,
+        // so a rollback or step diff for this revision would show a later state.
+        // The neighbouring branches clone for the same reason; this one did not.
+        return cloneSnapshot(asWorkbookSnapshot(operation.payload.snapshot));
+    }
+    const root = asWorkbookSnapshot(snapshot);
+    const payload = operation.payload;
+    switch (operation.type) {
+        case 'update_cells':
+            updateCells(root, payload.sheetId, payload.cells ?? []);
+            break;
+        case 'clear_range':
+            clearRange(root, payload.sheetId, payload.range);
+            break;
+        case 'delete_cells':
+            deleteCells(root, payload.sheetId, payload.range, payload.shift ?? 'clear');
+            break;
+        case 'insert_rows':
+            insertRows(root, payload.sheetId, payload.range?.startRow ?? 0, payload.count ?? 1);
+            break;
+        case 'delete_rows':
+            deleteRows(root, payload.sheetId, payload.range?.startRow ?? 0, payload.count ?? 1);
+            break;
+        case 'insert_columns':
+            insertColumns(root, payload.sheetId, payload.range?.startColumn ?? 0, payload.count ?? 1);
+            break;
+        case 'delete_columns':
+            deleteColumns(root, payload.sheetId, payload.range?.startColumn ?? 0, payload.count ?? 1);
+            break;
+        case 'create_sheet':
+            createSheet(root, payload.sheetId ?? `sheet-${operation.opId.slice(0, 12)}`, payload.name);
+            break;
+        case 'delete_sheet':
+            deleteSheet(root, payload.sheetId ?? payload.sheetName);
+            break;
+        case 'rename_sheet':
+            renameSheet(root, payload.sheetId, payload.name);
+            break;
+        case 'append_rows':
+            appendRows(root, payload.sheetId ?? payload.sheetName, payload.columns ?? [], payload.rows ?? [], payload.meta, payload.name, payload.headerRowIndex, payload.verifyHeader);
+            break;
+        case 'format_cells':
+            formatCells(root, payload.sheetId ?? payload.sheetName, payload.range, payload.style);
+            break;
+        case 'merge_cells':
+            mergeCells(root, payload.sheetId ?? payload.sheetName, payload.range ?? payload.merge);
+            break;
+        case 'unmerge_cells':
+            unmergeCells(root, payload.sheetId ?? payload.sheetName, payload.range ?? payload.merge);
+            break;
+        case 'freeze_panes':
+            freezePanes(root, payload.sheetId ?? payload.sheetName, payload.freeze);
+            break;
+        case 'set_column_width':
+            setDimension(root, payload.sheetId ?? payload.sheetName, 'columnData', payload.range?.startColumn ?? 0, payload.size);
+            break;
+        case 'set_row_height':
+            setDimension(root, payload.sheetId ?? payload.sheetName, 'rowData', payload.range?.startRow ?? 0, payload.size);
+            break;
+        case 'sort_range':
+            sortRange(root, payload.sheetId ?? payload.sheetName, payload.range, payload.sort);
+            break;
+        case 'set_hyperlink':
+            setHyperlink(root, payload.sheetId ?? payload.sheetName, payload.range, payload.url, payload.label);
+            break;
+        case 'remove_hyperlink':
+            removeHyperlink(root, payload.sheetId ?? payload.sheetName, payload.range);
+            break;
+        case 'remove_duplicates':
+            removeDuplicateRows(root, payload.sheetId ?? payload.sheetName, payload);
+            break;
+        case 'batch':
+            for (const [index, child] of (payload.operations ?? []).entries()) {
+                applyWorkbookOperation(root, {
+                    opId: `${operation.opId}:${index}`,
+                    workbookId: operation.workbookId,
+                    revision: operation.revision,
+                    actor: operation.actor,
+                    timestamp: operation.timestamp,
+                    type: child.type,
+                    payload: child.payload,
+                });
+            }
+            break;
+        default:
+            assertNeverOperation(operation.type);
+    }
+    return root;
+}
+/** Read a rectangular range as a compact 2D value matrix. */
+export function validateSnapshotBounds(value) {
+    const serialized = JSON.stringify(value);
+    if (serialized === undefined || serialized.length > 25 * 1024 * 1024)
+        throw new Error('工作簿快照过大（最大 25 MB）');
+    const root = asWorkbookSnapshot(value);
+    if (root.sheetOrder.length > 100 || Object.keys(root.sheets).length > 100)
+        throw new Error('工作簿 sheet 数量超过上限（最多 100 个）');
+    const seenSheetIds = new Set();
+    for (const sheetId of root.sheetOrder) {
+        if (seenSheetIds.has(sheetId) || root.sheets[sheetId] === undefined)
+            throw new Error('工作簿 sheet 顺序无效');
+        seenSheetIds.add(sheetId);
+    }
+    for (const [sheetId, sheet] of Object.entries(root.sheets)) {
+        if (typeof sheet !== 'object' || sheet === null)
+            throw new Error('工作簿 sheet 格式无效');
+        if (sheet.id !== sheetId || typeof sheet.name !== 'string' || sheet.name.trim().length === 0 || sheet.name.length > 64)
+            throw new Error('工作簿 sheet 元数据无效');
+        if (typeof sheet.cellData !== 'object' || sheet.cellData === null || Array.isArray(sheet.cellData))
+            throw new Error('工作簿 cellData 格式无效');
+        const rowCount = Number(sheet.rowCount);
+        const columnCount = Number(sheet.columnCount);
+        if (!Number.isInteger(rowCount) || rowCount < 1 || rowCount > SHEET_MAX_PHYSICAL_ROWS)
+            throw new Error('工作簿行数超过上限');
+        if (!Number.isInteger(columnCount) || columnCount < 1 || columnCount > SHEET_MAX_COLUMNS)
+            throw new Error('工作簿列数超过上限');
+        for (const [rowKey, row] of Object.entries(sheet.cellData)) {
+            const rowIndex = Number(rowKey);
+            if (!Number.isInteger(rowIndex) || rowIndex < 0 || rowIndex >= SHEET_MAX_PHYSICAL_ROWS)
+                throw new Error('工作簿包含越界行');
+            if (typeof row !== 'object' || row === null || Array.isArray(row))
+                throw new Error('工作簿行数据格式无效');
+            for (const columnKey of Object.keys(row)) {
+                const columnIndex = Number(columnKey);
+                if (!Number.isInteger(columnIndex) || columnIndex < 0 || columnIndex >= SHEET_MAX_COLUMNS)
+                    throw new Error('工作簿包含越界列');
+            }
+        }
+    }
+}
+/** Guard operations whose full Excel semantics are not represented by the
+ * compact Host snapshot mutator. A snapshot fallback remains available for
+ * these workbooks through import/user edits. */
+function assertStructuralOperationSupported(root, sheet, operation) {
+    const hasFormula = Object.values(root.sheets).some(candidate => Object.values(candidate.cellData ?? {}).some(row => Object.values(row).some(cell => typeof cell.f === 'string' && cell.f.length > 0)));
+    const hasAdvancedState = ['mergeData', 'rowData', 'columnData', 'freeze', 'conditionalFormatting', 'dataValidation', 'drawings', 'tables', 'comments'].some(key => {
+        const value = sheet[key];
+        if (value === undefined || value === null)
+            return false;
+        if (Array.isArray(value))
+            return value.length > 0;
+        if (typeof value === 'object')
+            return Object.keys(value).length > 0;
+        return true;
+    });
+    if (hasFormula || hasAdvancedState) {
+        throw new Error(`${operation} 在含公式或高级结构的 sheet 上被拒绝，以避免破坏引用和格式；写更多行请直接用 update_cells 或 import_file（越界会自动扩容 rowCount，不必先 insert_rows），整体替换请改用 snapshot`);
+    }
+}
+function maxCellIndex(cellData, dimension) {
+    let max = -1;
+    if (dimension === 'row') {
+        for (const key of Object.keys(cellData)) {
+            const value = Number(key);
+            if (Number.isInteger(value))
+                max = Math.max(max, value);
+        }
+        return max;
+    }
+    for (const row of Object.values(cellData)) {
+        for (const key of Object.keys(row)) {
+            const value = Number(key);
+            if (Number.isInteger(value))
+                max = Math.max(max, value);
+        }
+    }
+    return max;
+}
+function recomputeDataSheetStats(sheet) {
+    let maxDataRow = 0;
+    let maxDataColumn = 0;
+    for (const [rowKey, row] of Object.entries(sheet.cellData ?? {})) {
+        const rowIndex = Number(rowKey);
+        if (!Number.isInteger(rowIndex))
+            continue;
+        if (rowIndex > 0 && Object.keys(row).length > 0)
+            maxDataRow = Math.max(maxDataRow, rowIndex);
+        for (const columnKey of Object.keys(row)) {
+            const columnIndex = Number(columnKey);
+            if (Number.isInteger(columnIndex))
+                maxDataColumn = Math.max(maxDataColumn, columnIndex + 1);
+        }
+    }
+    // Recompute from the resulting cell map so clearing the last populated cell
+    // cannot leave a stale row/column count in the schema and tool output.
+    sheet.dataSheetStats = { rowCount: maxDataRow, columnCount: maxDataColumn };
+    const schema = isSheetSchema(sheet.dataSheetSchema) ? sheet.dataSheetSchema : undefined;
+    if (schema !== undefined) {
+        sheet.dataSheetSchema = { ...schema, rowCount: maxDataRow, updatedAt: new Date().toISOString() };
+    }
+}
+function updateCells(root, sheetRef, cells) {
+    if (cells.length === 0)
+        throw new Error('cells 不能为空');
+    if (cells.length > SHEET_MAX_ROWS * SHEET_MAX_COLUMNS)
+        throw new Error('一次修改的单元格数量超过上限');
+    const sheet = resolveSheet(root, sheetRef);
+    for (const cell of cells) {
+        validateIndex(cell.row, 'cell.row');
+        validateIndex(cell.column, 'cell.column');
+        if (cell.row >= SHEET_MAX_PHYSICAL_ROWS)
+            throw new Error(`cell.row 超过上限（最多 ${SHEET_MAX_ROWS} 条数据行 + 表头）`);
+        if (cell.column >= SHEET_MAX_COLUMNS)
+            throw new Error(`cell.column 超过上限（最多 ${SHEET_MAX_COLUMNS} 列）`);
+        const row = (sheet.cellData[String(cell.row)] ??= {});
+        const formula = normalizeCellFormula(cell.formula);
+        if (cell.value === null && formula === undefined) {
+            delete row[String(cell.column)];
+            if (Object.keys(row).length === 0)
+                delete sheet.cellData[String(cell.row)];
+            continue;
+        }
+        const current = row[String(cell.column)];
+        row[String(cell.column)] = formula === undefined
+            ? { ...(current ?? {}), v: cell.value, f: undefined }
+            : { ...(current ?? {}), v: cell.value, f: formula };
+        if (formula === undefined)
+            delete row[String(cell.column)].f;
+        sheet.rowCount = Math.max(sheet.rowCount, cell.row + 1);
+        sheet.columnCount = Math.max(sheet.columnCount, cell.column + 1);
+    }
+    recomputeDataSheetStats(sheet);
+}
+function clearRange(root, sheetRef, range) {
+    validateRange(range);
+    const sheet = resolveSheet(root, sheetRef);
+    for (let row = range.startRow; row <= range.endRow; row += 1) {
+        const cells = sheet.cellData[String(row)];
+        if (cells === undefined)
+            continue;
+        for (let column = range.startColumn; column <= range.endColumn; column += 1)
+            delete cells[String(column)];
+        if (Object.keys(cells).length === 0)
+            delete sheet.cellData[String(row)];
+    }
+    recomputeDataSheetStats(sheet);
+}
+function deleteCells(root, sheetRef, range, shift) {
+    validateRange(range);
+    if (shift !== 'clear' && shift !== 'left' && shift !== 'up') {
+        throw new Error(`不支持的单元格删除方式：${String(shift)}`);
+    }
+    if (shift === 'clear') {
+        clearRange(root, sheetRef, range);
+        return;
+    }
+    const sheet = resolveSheet(root, sheetRef);
+    assertStructuralOperationSupported(root, sheet, `delete_cells:${shift}`);
+    const width = range.endColumn - range.startColumn + 1;
+    const height = range.endRow - range.startRow + 1;
+    const nextCellData = {};
+    for (const [rowKey, cells] of Object.entries(sheet.cellData)) {
+        const row = Number(rowKey);
+        if (!Number.isInteger(row))
+            continue;
+        const nextCells = {};
+        for (const [columnKey, cell] of Object.entries(cells)) {
+            const column = Number(columnKey);
+            if (!Number.isInteger(column))
+                continue;
+            if (shift === 'left' && row >= range.startRow && row <= range.endRow) {
+                if (column >= range.startColumn && column <= range.endColumn)
+                    continue;
+                nextCells[String(column > range.endColumn ? column - width : column)] = cell;
+                continue;
+            }
+            if (shift === 'up' && column >= range.startColumn && column <= range.endColumn) {
+                if (row >= range.startRow && row <= range.endRow)
+                    continue;
+                nextCellData[String(row > range.endRow ? row - height : row)] ??= {};
+                nextCellData[String(row > range.endRow ? row - height : row)][columnKey] = cell;
+                continue;
+            }
+            nextCells[columnKey] = cell;
+        }
+        if (Object.keys(nextCells).length > 0) {
+            nextCellData[rowKey] ??= {};
+            Object.assign(nextCellData[rowKey], nextCells);
+        }
+    }
+    sheet.cellData = nextCellData;
+    recomputeDataSheetStats(sheet);
+}
+function insertRows(root, sheetRef, startRow, count) {
+    validateIndex(startRow, 'startRow');
+    validateCount(count);
+    const sheet = resolveSheet(root, sheetRef);
+    if (sheet.rowCount + count > SHEET_MAX_PHYSICAL_ROWS)
+        throw new Error(`插入后行数超过上限（最多 ${SHEET_MAX_ROWS} 条数据行 + 表头）`);
+    assertStructuralOperationSupported(root, sheet, 'insert_rows');
+    if (maxCellIndex(sheet.cellData, 'row') + count >= SHEET_MAX_PHYSICAL_ROWS)
+        throw new Error('插入后单元格超出工作簿行上限');
+    const rows = Object.keys(sheet.cellData).map(Number).filter(Number.isInteger).sort((a, b) => b - a);
+    for (const row of rows) {
+        if (row < startRow)
+            continue;
+        sheet.cellData[String(row + count)] = sheet.cellData[String(row)];
+        delete sheet.cellData[String(row)];
+    }
+    sheet.rowCount += count;
+    recomputeDataSheetStats(sheet);
+}
+function deleteRows(root, sheetRef, startRow, count) {
+    validateIndex(startRow, 'startRow');
+    validateCount(count);
+    if (startRow >= SHEET_MAX_PHYSICAL_ROWS)
+        throw new Error(`startRow 超过上限（最多 ${SHEET_MAX_ROWS} 条数据行 + 表头）`);
+    if (startRow + count > SHEET_MAX_PHYSICAL_ROWS)
+        throw new Error(`删除范围超过上限（最多 ${SHEET_MAX_ROWS} 条数据行 + 表头）`);
+    const sheet = resolveSheet(root, sheetRef);
+    assertStructuralOperationSupported(root, sheet, 'delete_rows');
+    for (let row = startRow; row < startRow + count; row += 1)
+        delete sheet.cellData[String(row)];
+    const rows = Object.keys(sheet.cellData).map(Number).filter(Number.isInteger).sort((a, b) => a - b);
+    for (const row of rows) {
+        if (row < startRow + count)
+            continue;
+        sheet.cellData[String(row - count)] = sheet.cellData[String(row)];
+        delete sheet.cellData[String(row)];
+    }
+    sheet.rowCount = Math.max(1, sheet.rowCount - count);
+    recomputeDataSheetStats(sheet);
+}
+function insertColumns(root, sheetRef, startColumn, count) {
+    validateIndex(startColumn, 'startColumn');
+    validateCount(count);
+    const sheet = resolveSheet(root, sheetRef);
+    if (sheet.columnCount + count > SHEET_MAX_COLUMNS)
+        throw new Error(`插入后列数超过上限（最多 ${SHEET_MAX_COLUMNS} 列）`);
+    assertStructuralOperationSupported(root, sheet, 'insert_columns');
+    if (maxCellIndex(sheet.cellData, 'column') + count >= SHEET_MAX_COLUMNS)
+        throw new Error('插入后单元格超出工作簿列上限');
+    for (const cells of Object.values(sheet.cellData)) {
+        const nextCells = {};
+        for (const [columnKey, cell] of Object.entries(cells)) {
+            const column = Number(columnKey);
+            if (!Number.isInteger(column))
+                continue;
+            nextCells[String(column >= startColumn ? column + count : column)] = cell;
+        }
+        Object.keys(cells).forEach(column => { delete cells[column]; });
+        Object.assign(cells, nextCells);
+    }
+    sheet.columnCount += count;
+    recomputeDataSheetStats(sheet);
+}
+function deleteColumns(root, sheetRef, startColumn, count) {
+    validateIndex(startColumn, 'startColumn');
+    validateCount(count);
+    if (startColumn >= SHEET_MAX_COLUMNS || startColumn + count > SHEET_MAX_COLUMNS) {
+        throw new Error(`删除范围超过上限（最多 ${SHEET_MAX_COLUMNS} 列）`);
+    }
+    const endColumn = startColumn + count;
+    const sheet = resolveSheet(root, sheetRef);
+    assertStructuralOperationSupported(root, sheet, 'delete_columns');
+    for (const cells of Object.values(sheet.cellData)) {
+        const nextCells = {};
+        for (const [columnKey, cell] of Object.entries(cells)) {
+            const column = Number(columnKey);
+            if (!Number.isInteger(column) || (column >= startColumn && column < endColumn))
+                continue;
+            nextCells[String(column >= endColumn ? column - count : column)] = cell;
+        }
+        Object.keys(cells).forEach(column => { delete cells[column]; });
+        Object.assign(cells, nextCells);
+    }
+    sheet.columnCount = Math.max(1, sheet.columnCount - count);
+    recomputeDataSheetStats(sheet);
+}
+function createSheet(root, sheetId, name) {
+    const sheetName = name?.trim();
+    if (sheetName === undefined || sheetName.length === 0)
+        throw new Error('sheet 名称不能为空');
+    if (Object.values(root.sheets).some(sheet => sheet.name === sheetName))
+        throw new Error(`sheet 已存在：${sheetName}`);
+    const id = sheetId?.trim() || `sheet${Date.now().toString(36)}`;
+    if (root.sheets[id] !== undefined)
+        throw new Error(`sheet id 已存在：${id}`);
+    root.sheets[id] = { id, name: sheetName, rowCount: DEFAULT_SHEET_ROWS, columnCount: DEFAULT_SHEET_COLUMNS, cellData: {} };
+    root.sheetOrder.push(id);
+}
+function deleteSheet(root, sheetRef) {
+    if (root.sheetOrder.length <= 1)
+        throw new Error('工作簿至少需要保留一个 sheet，不能删除最后一个 sheet');
+    const sheet = resolveSheet(root, sheetRef);
+    delete root.sheets[sheet.id];
+    root.sheetOrder = root.sheetOrder.filter(id => id !== sheet.id);
+}
+function renameSheet(root, sheetRef, name) {
+    const sheetName = name?.trim();
+    if (sheetName === undefined || sheetName.length === 0)
+        throw new Error('sheet 名称不能为空');
+    const sheet = resolveSheet(root, sheetRef);
+    if (Object.values(root.sheets).some(candidate => candidate.name === sheetName && candidate.id !== sheet.id))
+        throw new Error(`sheet 已存在：${sheetName}`);
+    sheet.name = sheetName;
+}
+/**
+ * Mirrored by the browser projection's `applyAppendRows`, which runs the same
+ * check against live Univer state. The hint names `headerRowIndex` because that
+ * is what unblocks a report sheet whose real header is not row 0.
+ */
+export function formatCells(root, sheetRef, range, style) {
+    validateRange(range);
+    if (style === undefined || typeof style !== 'object')
+        throw new Error('format_cells 必须提供 style');
+    const sheet = resolveSheet(root, sheetRef);
+    for (let row = range.startRow; row <= range.endRow; row += 1) {
+        const cells = (sheet.cellData[String(row)] ??= {});
+        for (let column = range.startColumn; column <= range.endColumn; column += 1) {
+            const current = cells[String(column)] ?? { v: null };
+            cells[String(column)] = { ...current, s: { ...(current.s ?? {}), ...style } };
+        }
+    }
+}
+function mergeCells(root, sheetRef, range) {
+    validateRange(range);
+    const sheet = resolveSheet(root, sheetRef);
+    const merges = Array.isArray(sheet.mergeData) ? sheet.mergeData : [];
+    if (!merges.some(item => JSON.stringify(item) === JSON.stringify(range)))
+        merges.push(range);
+    sheet.mergeData = merges;
+}
+function unmergeCells(root, sheetRef, range) {
+    validateRange(range);
+    const sheet = resolveSheet(root, sheetRef);
+    const merges = Array.isArray(sheet.mergeData) ? sheet.mergeData : [];
+    sheet.mergeData = merges.filter(item => !rangesIntersect(item, range));
+}
+function rangesIntersect(left, right) {
+    return left.startRow <= right.endRow && right.startRow <= left.endRow
+        && left.startColumn <= right.endColumn && right.startColumn <= left.endColumn;
+}
+function freezePanes(root, sheetRef, freeze) {
+    const sheet = resolveSheet(root, sheetRef);
+    if (freeze === undefined || (freeze.rows ?? 0) < 0 || (freeze.columns ?? 0) < 0)
+        throw new Error('freeze_panes 参数无效');
+    sheet.freeze = { rows: Math.floor(freeze.rows ?? 0), columns: Math.floor(freeze.columns ?? 0) };
+}
+function setDimension(root, sheetRef, key, index, size) {
+    validateIndex(index, `${key} index`);
+    if (key === 'columnData' && index >= SHEET_MAX_COLUMNS)
+        throw new Error(`columnData index 超过上限（最多 ${SHEET_MAX_COLUMNS} 列）`);
+    if (key === 'rowData' && index >= SHEET_MAX_PHYSICAL_ROWS)
+        throw new Error(`rowData index 超过上限（最多 ${SHEET_MAX_ROWS} 条数据行 + 表头）`);
+    if (typeof size !== 'number' || !Number.isFinite(size) || size <= 0 || size > 1000)
+        throw new Error('尺寸必须是 0 到 1000 之间的有限数字');
+    const sheet = resolveSheet(root, sheetRef);
+    const data = sheet[key] ?? {};
+    const current = typeof data[String(index)] === 'object' && data[String(index)] !== null ? data[String(index)] : {};
+    const dimension = key === 'columnData' ? 'width' : 'height';
+    const otherDimension = key === 'columnData' ? 'height' : 'width';
+    const next = { ...current, [dimension]: size };
+    delete next[otherDimension];
+    data[String(index)] = next;
+    sheet[key] = data;
+}
+function sortRange(root, sheetRef, range, sort) {
+    validateRange(range);
+    if (sort === undefined || !Number.isInteger(sort.column) || sort.column < range.startColumn || sort.column > range.endColumn)
+        throw new Error('sort_range 的排序列必须位于 range 内');
+    const sheet = resolveSheet(root, sheetRef);
+    const rows = [];
+    for (let row = range.startRow; row <= range.endRow; row += 1) {
+        const selected = {};
+        const source = sheet.cellData[String(row)] ?? {};
+        for (let column = range.startColumn; column <= range.endColumn; column += 1) {
+            if (source[String(column)] !== undefined)
+                selected[String(column)] = source[String(column)];
+        }
+        rows.push({ index: row, cells: selected });
+    }
+    const valueOf = (item) => {
+        const value = toCellValue(item.cells[String(sort.column)]);
+        return typeof value === 'number' ? value : String(value ?? '');
+    };
+    rows.sort((left, right) => {
+        const a = valueOf(left);
+        const b = valueOf(right);
+        const comparison = typeof a === 'number' && typeof b === 'number' ? a - b : String(a).localeCompare(String(b), 'zh-CN');
+        return sort.direction === 'desc' ? -comparison : comparison;
+    });
+    rows.forEach((item, offset) => {
+        const target = range.startRow + offset;
+        const current = sheet.cellData[String(target)] ?? {};
+        for (let column = range.startColumn; column <= range.endColumn; column += 1)
+            delete current[String(column)];
+        Object.assign(current, item.cells);
+        if (Object.keys(current).length > 0)
+            sheet.cellData[String(target)] = current;
+        else
+            delete sheet.cellData[String(target)];
+    });
+}
+function setHyperlink(root, sheetRef, range, url, label) {
+    validateRange(range);
+    const targetUrl = url?.trim();
+    if (targetUrl === undefined || targetUrl.length === 0)
+        throw new Error('set_hyperlink.url 不能为空');
+    if (!isSafeHyperlink(targetUrl))
+        throw new Error('set_hyperlink.url 只支持 http(s)、mailto、file 或 sheet 内部链接');
+    const sheet = resolveSheet(root, sheetRef);
+    const row = (sheet.cellData[String(range.startRow)] ??= {});
+    const current = row[String(range.startColumn)] ?? {};
+    const display = label === undefined || label.trim().length === 0 ? String(toCellValue(current) ?? targetUrl) : label;
+    const document = isRecord(current.p) ? current.p : {};
+    const oldBody = isRecord(document.body) ? document.body : {};
+    const oldRanges = Array.isArray(oldBody.customRanges) ? oldBody.customRanges.filter(item => isRecord(item) && item.rangeType !== 0) : [];
+    const linkId = `dsh-link-${randomUUID()}`;
+    row[String(range.startColumn)] = {
+        ...current,
+        v: display,
+        t: 1,
+        p: {
+            ...document,
+            id: typeof document.id === 'string' ? document.id : `dsh-doc-${randomUUID()}`,
+            documentStyle: isRecord(document.documentStyle) ? document.documentStyle : {},
+            body: {
+                ...oldBody,
+                dataStream: `${display}\r\n`,
+                customRanges: [
+                    ...oldRanges,
+                    { startIndex: 0, endIndex: Math.max(0, display.length - 1), rangeId: linkId, rangeType: 0, properties: { url: targetUrl } },
+                ],
+            },
+        },
+    };
+    sheet.rowCount = Math.max(sheet.rowCount, range.startRow + 1);
+    sheet.columnCount = Math.max(sheet.columnCount, range.startColumn + 1);
+    recomputeDataSheetStats(sheet);
+}
+function removeHyperlink(root, sheetRef, range) {
+    validateRange(range);
+    const sheet = resolveSheet(root, sheetRef);
+    const row = sheet.cellData[String(range.startRow)];
+    const current = row?.[String(range.startColumn)];
+    if (!row || !isRecord(current) || !isRecord(current.p) || !isRecord(current.p.body))
+        return;
+    const body = current.p.body;
+    if (!Array.isArray(body.customRanges))
+        return;
+    const customRanges = body.customRanges.filter(item => !(isRecord(item) && item.rangeType === 0));
+    if (customRanges.length === body.customRanges.length)
+        return;
+    current.p = { ...current.p, body: { ...body, customRanges } };
+    recomputeDataSheetStats(sheet);
+}
+function withResolvedDuplicateRows(snapshot, payload) {
+    validateRange(payload.range);
+    const sheet = resolveSheet(asWorkbookSnapshot(snapshot), payload.sheetId ?? payload.sheetName);
+    const range = payload.range;
+    const values = rangeValues(sheet, range);
+    const removedRows = findDuplicateRows(values, range, payload.dedupeColumns, payload.hasHeader ?? false, payload.keep ?? 'first');
+    return { ...payload, removedRows };
+}
+/** Resolve data-dependent children before an operation is persisted/replayed. */
+export function resolveOperationPayload(snapshot, type, payload) {
+    if (type !== 'batch') {
+        if (type === 'snapshot_replace')
+            validateSnapshotBounds(payload.snapshot);
+        return type === 'remove_duplicates' ? withResolvedDuplicateRows(snapshot, payload) : payload;
+    }
+    if (!Array.isArray(payload.operations) || payload.operations.length === 0 || payload.operations.length > 200) {
+        throw new Error('batch.operations 必须包含 1 到 200 个操作');
+    }
+    // Normal Agent/browser batches contain already validated, replayable
+    // payloads. Only the legacy data-dependent dedupe operation needs a
+    // sequential resolution pass; skipping the clone here is significant for
+    // large append/update batches.
+    if (!payload.operations.some(operation => operationNeedsPayloadResolution(operation)))
+        return payload;
+    let workingSnapshot = cloneSnapshot(snapshot);
+    const operations = (payload.operations ?? []).map((child, index) => {
+        const childPayload = resolveOperationPayload(workingSnapshot, child.type, child.payload);
+        const childOperation = {
+            opId: `resolve:${index}`,
+            workbookId: 'resolve',
+            revision: 0,
+            baseRevision: 0,
+            actor: 'agent',
+            timestamp: new Date(0).toISOString(),
+            type: child.type,
+            payload: childPayload,
+        };
+        workingSnapshot = applyWorkbookOperation(workingSnapshot, childOperation);
+        return { ...child, payload: childPayload };
+    });
+    return { ...payload, operations };
+}
+function operationNeedsPayloadResolution(operation) {
+    return operation.type === 'remove_duplicates'
+        || operation.type === 'batch' && (operation.payload.operations ?? []).some(operationNeedsPayloadResolution);
+}
+function removeDuplicateRows(root, sheetRef, payload) {
+    validateRange(payload.range);
+    const sheet = resolveSheet(root, sheetRef);
+    const rows = payload.removedRows === undefined
+        ? findDuplicateRows(rangeValues(sheet, payload.range), payload.range, payload.dedupeColumns, payload.hasHeader ?? false, payload.keep ?? 'first')
+        : payload.removedRows;
+    if (rows.length === 0)
+        return;
+    for (const row of rows)
+        validateIndex(row, 'removedRows');
+    // Delete from the bottom so indexes remain the original range indexes.
+    let end = rows[rows.length - 1];
+    let start = end;
+    for (let index = rows.length - 2; index >= -1; index -= 1) {
+        const current = index >= 0 ? rows[index] : undefined;
+        if (current !== undefined && current === start - 1) {
+            start = current;
+            continue;
+        }
+        deleteRows(root, sheetRef, start, end - start + 1);
+        if (current !== undefined) {
+            end = current;
+            start = current;
+        }
+    }
+    recomputeDataSheetStats(sheet);
+}
+function rangeValues(sheet, range) {
+    const values = [];
+    for (let row = range.startRow; row <= range.endRow; row += 1) {
+        const source = sheet.cellData[String(row)] ?? {};
+        values.push(Array.from({ length: range.endColumn - range.startColumn + 1 }, (_value, offset) => toCellValue(source[String(range.startColumn + offset)])));
+    }
+    return values;
+}
+function isSafeHyperlink(url) {
+    return /^(?:https?:|mailto:|file:|#)/i.test(url);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function validateCount(count) {
+    if (!Number.isInteger(count) || count < 1 || count > SHEET_MAX_ROWS)
+        throw new Error('count 必须是 1 到上限之间的整数');
+}
+function coerceCellValue(type, value) {
+    if (type === 'number' || type === 'currency') {
+        const numeric = typeof value === 'number' ? value : Number(value);
+        return Number.isFinite(numeric) ? numeric : String(value);
+    }
+    if (type === 'boolean')
+        return typeof value === 'boolean' ? value : String(value) === 'true';
+    if (type === 'date')
+        return value instanceof Date ? value.toISOString().slice(0, 10) : String(value);
+    return String(value);
+}
+function sameSheetColumns(left, right) {
+    return left.length === right.length && left.every((column, index) => {
+        const other = right[index];
+        return other !== undefined && column.key === other.key && column.label === other.label && column.type === other.type;
+    });
+}
+function assertNeverOperation(value) {
+    throw new Error(`不支持的 workbook operation：${String(value)}`);
+}
+/**
+ * Appends schema-typed rows below the header row.
+ *
+ * `headerRowIndex` and `verifyHeader` exist for report sheets whose real header
+ * is not row 0 — previously those sheets could only be written through
+ * `update_cells`, which is what produced the "use update_cells" dead end. Both
+ * default to the old behaviour (header on row 0, labels verified), and the
+ * default path below is left structurally identical so no stored workbook or
+ * existing caller changes meaning.
+ */
+function appendRows(root, sheetRef, columns, rows, meta, sheetName, rawHeaderRowIndex, rawVerifyHeader) {
+    if (columns.length === 0 || columns.length > SHEET_MAX_COLUMNS)
+        throw new Error(`列数必须是 1 到 ${SHEET_MAX_COLUMNS}`);
+    if (rows.length > SHEET_MAX_ROWS)
+        throw new Error(`一次追加最多 ${SHEET_MAX_ROWS} 行`);
+    const headerRowIndex = rawHeaderRowIndex ?? 0;
+    if (!Number.isInteger(headerRowIndex) || headerRowIndex < 0)
+        throw new Error('headerRowIndex 必须是大于等于 0 的整数');
+    if (headerRowIndex >= SHEET_MAX_PHYSICAL_ROWS)
+        throw new Error('headerRowIndex 超出上限（最后一个物理行是 ' + SHEET_MAX_ROWS + '）');
+    // Only an explicit false relaxes the label comparison; it remains the guard
+    // that catches a column reorder before rows are written.
+    const verifyHeader = rawVerifyHeader !== false;
+    let sheet;
+    try {
+        sheet = resolveSheet(root, sheetRef);
+    }
+    catch (error) {
+        if (sheetRef === undefined)
+            throw error;
+        // Use the caller's stable reference as the id when append_rows creates a
+        // sheet. This keeps the Node snapshot, browser projection, and subsequent
+        // commands in the same batch on the exact same sheet.
+        createSheet(root, sheetRef, sheetName ?? sheetRef);
+        sheet = resolveSheet(root, sheetRef);
+    }
+    const headerKey = String(headerRowIndex);
+    const header = sheet.cellData[headerKey];
+    const existingSchema = isSheetSchema(sheet.dataSheetSchema) ? sheet.dataSheetSchema : undefined;
+    if (verifyHeader && existingSchema !== undefined && !sameSheetColumns(existingSchema.columns, columns)) {
+        throw new Error(APPEND_HEADER_MISMATCH);
+    }
+    const existingHeaderIndexes = Object.keys(header ?? {}).map(Number).filter(Number.isInteger);
+    const existingColumnCount = existingHeaderIndexes.length === 0 ? 0 : Math.max(...existingHeaderIndexes) + 1;
+    const existingHeader = header === undefined ? [] : Array.from({ length: existingColumnCount }, (_value, index) => header[String(index)]?.v);
+    if (verifyHeader && existingColumnCount > 0 && (existingColumnCount !== columns.length
+        || columns.some((column, index) => String(existingHeader[index] ?? '') !== column.label))) {
+        throw new Error(APPEND_HEADER_MISMATCH);
+    }
+    if (header === undefined || Object.keys(header).length === 0) {
+        sheet.cellData[headerKey] = Object.fromEntries(columns.map((column, index) => [String(index), { v: column.label }]));
+    }
+    const storedStats = sheet.dataSheetStats;
+    const storedDataRows = typeof storedStats?.rowCount === 'number' && Number.isInteger(storedStats.rowCount) && storedStats.rowCount >= 0
+        ? storedStats.rowCount
+        : -1;
+    const floorRow = headerRowIndex + 1;
+    let existingDataRows = -1;
+    let nextRow = floorRow;
+    if (headerRowIndex === 0 && storedDataRows >= 0) {
+        existingDataRows = storedDataRows;
+        nextRow = Math.max(floorRow, existingDataRows + 1);
+    }
+    else {
+        // A stored counter can only be read against a row-0 header, so a report
+        // sheet is positioned from its real last occupied row instead.
+        for (const key of Object.keys(sheet.cellData)) {
+            const row = Number(key);
+            if (Number.isInteger(row))
+                nextRow = Math.max(nextRow, row + 1);
+        }
+        existingDataRows = Math.max(0, nextRow - 1);
+    }
+    if (nextRow - 1 + rows.length > SHEET_MAX_ROWS)
+        throw new Error(`写入后行数超过上限（最多 ${SHEET_MAX_ROWS} 行）`);
+    for (const [rowIndex, input] of rows.entries()) {
+        const line = {};
+        columns.forEach((column, columnIndex) => {
+            const value = input[column.key];
+            if (value === undefined || value === null)
+                return;
+            line[String(columnIndex)] = { v: coerceCellValue(column.type, value) };
+        });
+        sheet.cellData[String(nextRow + rowIndex)] = line;
+    }
+    sheet.columnCount = Math.max(sheet.columnCount, columns.length);
+    sheet.rowCount = Math.max(sheet.rowCount, nextRow + rows.length);
+    sheet.dataSheetStats = {
+        rowCount: Math.max(existingDataRows, nextRow - 1 + rows.length),
+        columnCount: Math.max(typeof sheet.dataSheetStats?.columnCount === 'number'
+            ? sheet.dataSheetStats.columnCount
+            : 0, columns.length),
+    };
+    if (meta !== undefined)
+        sheet.dataSheetMeta = meta;
+    sheet.dataSheetSchema = {
+        version: existingSchema?.version ?? 1,
+        columns,
+        rowCount: Math.max(existingDataRows, nextRow - 1 + rows.length),
+        updatedAt: new Date().toISOString(),
+    };
+}