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

package/lib/types/tools/workbook-edit.js

@@ -0,0 +1,912 @@
+/**
+ * `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.js";
+import { createHash, randomUUID } from 'node:crypto';
+import { statSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { extname, 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, } from "../types.js";
+import { DataSheetError } from "../errors.js";
+import { applyWorkbookOperation } from "../contract/mutations.js";
+import { workbookOperationSteps } from "../contract/operations.js";
+import { mutateWorkbookPlan, readWorkbook } from "../workbook-manager.js";
+import { isOperationType, normalizeValueMatrix, parseIndex, parseRange } from "../request-params.js";
+import { asToolArguments, commandIndex, commandPayload, commandSheet, optionalAuditText, optionalIntent, parseCellDeleteShift, parseCount, parseHeaderVerification, parseNonEmptyString, sheetRefForSnapshot, } from "./arguments.js";
+import { chunkRows, dimensionCommandRange, dimensionRange, parseApiValues, parseCells, parseFiniteNumber, parseFreeze, parseHyperlink, parseHyperlinkLabel, parseSort, parseValueRange, resolveCellFileValues, validateSheet, } from "./cells.js";
+import { operationReceipt, sheetOverviews, sheetReferenceList } from "./render.js";
+import { snapshotSheet } from "./workbook-read.js";
+/**
+ * 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, index, targetWorkbookId, warnings = []) {
+    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 = [{ type: 'create_sheet', payload: { sheetId: newSheetId, name } }];
+    const cells = [];
+    const cellData = sheet.cellData;
+    if (typeof cellData === 'object' && cellData !== null) {
+        for (const [rowKey, line] of Object.entries(cellData)) {
+            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, ...(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)) {
+            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, warnings = [], targetWorkbookId = 'workbook') {
+    if (!Array.isArray(value) || value.length === 0 || value.length > 100)
+        throw new Error('commands 必须是 1 到 100 项的数组');
+    const aliases = {
+        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();
+    const fileCellExpansions = new Map();
+    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.valueFromFile !== undefined
+                && cell.valueFromFile !== null));
+            if (needsFile) {
+                fileCellExpansions.set(index, parseCells(await resolveCellFileValues(raw.cells, `commands[${index}]`)));
+            }
+        }
+    }));
+    const result = [];
+    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 = aliasedType === 'import_file' || aliasedType === 'duplicate_sheet'
+            ? aliasedType
+            : aliasedType;
+        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;
+}
+/**
+ * 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, label) {
+    const rows = imported.rows;
+    if (rows.length === 0)
+        throw new Error(`${label}.sourcePath 没有可导入的数据行`);
+    if (rows.every(row => Array.isArray(row)))
+        return normalizeValueMatrix(rows);
+    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.map(row => table.columns.map(column => row[column.key] ?? null));
+    }
+    const keys = [];
+    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' })),
+        rows,
+    });
+    if (table.columns.length !== keys.length)
+        throw new Error(`${label}.sourcePath 列推断失败`);
+    return rows.map(row => keys.map(key => row[key] ?? null));
+}
+/** Stable content digest so an import receipt can prove what was written. */
+export function hashValueMatrix(matrix) {
+    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) {
+    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) {
+    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, rawFormat) {
+    const sourcePath = resolve(parseNonEmptyString(rawPath, 'sourcePath'));
+    let info;
+    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);
+                }
+                catch {
+                    throw new Error(`sourcePath JSONL 第 ${index + 1} 行不是有效 JSON`);
+                }
+            })
+            : (() => { try {
+                return JSON.parse(text);
+            }
+            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;
+            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 }) };
+}
+/**
+ * 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, rawCommands, defaultIntent, warnings = [], targetWorkbookId = 'workbook') {
+    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) {
+    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, groups, workbookId = 'workbook') {
+    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 = {
+                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, name, groupIndex, commandIndex) {
+    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, warnings) {
+    const firstWrite = new Map();
+    const reported = new Set();
+    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, explicit, label, allowMissing) {
+    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, sheetRef, rawRows, label) {
+    if (!Array.isArray(rawRows))
+        throw new Error(`${label}.rows 必须是对象数组`);
+    const rows = rawRows;
+    let existing;
+    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
+        : undefined;
+    if (Array.isArray(schemaRecord?.columns) && schemaRecord.columns.length > 0) {
+        const columns = schemaRecord.columns;
+        return { columns, rows: projectRowsToColumns(rows, columns) };
+    }
+    const keys = [];
+    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['0']
+        : undefined;
+    const headerValues = headerRow !== null && typeof headerRow === 'object' && headerRow !== undefined && !Array.isArray(headerRow)
+        ? headerRow
+        : {};
+    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)].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, columns) {
+    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, key) {
+    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, args) {
+    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.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) {
+    const warnings = [];
+    let parsedVersions;
+    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',
+            // 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',
+            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) }),
+    };
+}
+export function collectImportFileSteps(versions) {
+    const steps = [];
+    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;
+}
+/**
+ * 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, context) {
+    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 = [];
+    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, sheetRef) {
+    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, snapshot) {
+    const names = new Map(sheetOverviews(snapshot).map(sheet => [sheet.id, sheet.name]));
+    const labels = new Set();
+    const refs = new Map();
+    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, opId) {
+    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) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        throw new Error('style 必须是对象');
+    const raw = value;
+    const style = {};
+    for (const key of ['ff', 'bg', 'cl', 'n']) {
+        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']) {
+        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']) {
+        if (raw[key] !== undefined) {
+            if (typeof raw[key] !== 'boolean')
+                throw new Error(`style.${key} 必须是布尔值`);
+            style[key] = raw[key];
+        }
+    }
+    return style;
+}
+export function parseSheetMeta(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'object' || Array.isArray(value))
+        throw new Error('meta 必须是对象');
+    const raw = value;
+    const meta = {};
+    for (const key of ['source', 'query', 'generatedAt', 'notes']) {
+        if (raw[key] !== undefined) {
+            if (typeof raw[key] !== 'string')
+                throw new Error(`meta.${key} 必须是字符串`);
+            meta[key] = raw[key];
+        }
+    }
+    return meta;
+}