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

package/lib/types/contract/snapshots.js

@@ -0,0 +1,351 @@
+/**
+ * Snapshot vocabulary: the workbook snapshot shape, the matrix tools, and the
+ * one range reader (docs/issue/0022 P0).
+ *
+ * The readers here are pure functions of their arguments. The two **accessors**
+ * are not, and the distinction is worth stating because the module used to claim
+ * otherwise:
+ *
+ *   - `asWorkbookSnapshot` fills in a missing `sheetOrder` by writing it into the
+ *     object it was handed. That is how a caller's `payload.snapshot` could be
+ *     modified as a side effect of reading it, which is what made a stored
+ *     operation's payload accumulate later revisions. `applyWorkbookOperation`
+ *     now clones before returning, so the write lands on a copy — but this
+ *     function still writes to its argument, and a caller must not assume
+ *     otherwise.
+ *   - `resolveSheet` materializes `cellData` on the sheet it returns. That is
+ *     load-bearing, not incidental: writers mutate the returned sheet and expect
+ *     the change to land in the snapshot, so handing back a copy would silently
+ *     drop every edit.
+ *
+ * `cloneSnapshot` is the point of the move: it existed twice — once in the model
+ * layer and once again inside `client/SheetPanel.tsx` — which is exactly the
+ * drift a contract module exists to prevent.
+ */
+import { SHEET_MAX_COLUMNS, SHEET_MAX_PHYSICAL_ROWS, SHEET_MAX_ROWS, } from "../types.js";
+/**
+ * The snapshot shape. It is declared here rather than in `types.ts` because it
+ * is the *input* of these functions and of nothing else on the wire; the
+ * tool-facing types stay in `types.ts`.
+ */
+/**
+ * The font family a blank sheet is created with.
+ *
+ * It lives in the contract because it is part of the stored snapshot's default
+ * style: the model, the xlsx reader and the engine all have to agree on it.
+ * Before the 0022 refactor it lived in the engine's font module, which made the
+ * model layer import *upward* into the engine (docs/issue/0022 §2).
+ */
+export const DEFAULT_SHEET_FONT_FAMILY = 'PingFang SC';
+/**
+ * The grid a new sheet starts with.
+ *
+ * One constant because *two* layers create sheets — the snapshot mutator and the
+ * Univer canvas — and a sheet's declared extent has to match the grid the user
+ * is looking at. It was written out as `1000` and `26` in seven places across
+ * five files, which is how the two drift apart without anyone editing either
+ * number. It is also a *starting* size, not a read limit: writes grow the sheet
+ * (`SHEET_MAX_ROWS` is the ceiling), and reads take the range they are given.
+ */
+export const DEFAULT_SHEET_ROWS = 1000;
+export const DEFAULT_SHEET_COLUMNS = 26;
+/**
+ * Deterministic JSON, so two equal values serialize identically.
+ *
+ * Object keys are sorted, which `JSON.stringify` does not do: it follows
+ * insertion order, so two snapshots holding the same content in a different
+ * order would compare unequal. Used for content hashes and for deciding whether
+ * a merge actually changed anything.
+ *
+ * It lived in the model layer *and* in the browser's merge code, byte for byte.
+ */
+export function stableJson(value) {
+    if (value === undefined)
+        return 'undefined';
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(stableJson).join(',')}]`;
+    return `{${Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, item]) => `${JSON.stringify(key)}:${stableJson(item)}`).join(',')}}`;
+}
+/** Deep copy through JSON; snapshots are plain JSON by construction. */
+export function cloneSnapshot(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+/**
+ * Narrow `value` to a snapshot, defaulting `sheetOrder` from `sheets`.
+ *
+ * **Writes to its argument** when `sheetOrder` is absent (see the module note).
+ * Every caller here uses the return value, and `applyWorkbookOperation` clones,
+ * but a new caller should not read a snapshot *and* hand the same object
+ * somewhere else without knowing that.
+ */
+export function asWorkbookSnapshot(value) {
+    if (typeof value !== 'object' || value === null)
+        throw new Error('工作簿快照格式无效');
+    const root = value;
+    if (typeof root.sheets !== 'object' || root.sheets === null)
+        throw new Error('工作簿缺少 sheets');
+    if (!Array.isArray(root.sheetOrder))
+        root.sheetOrder = Object.keys(root.sheets);
+    return root;
+}
+export function resolveSheet(root, ref) {
+    const requested = ref?.trim();
+    const sheet = requested === undefined || requested.length === 0
+        ? root.sheets[root.sheetOrder[0] ?? '']
+        : root.sheets[requested] ?? Object.values(root.sheets).find(candidate => candidate.name === requested);
+    if (sheet === undefined)
+        throw new Error(`sheet 不存在：${requested ?? '(第一个 sheet)'}`);
+    sheet.cellData ??= {};
+    return sheet;
+}
+export function validateIndex(value, label) {
+    if (!Number.isInteger(value) || value < 0)
+        throw new Error(`${label} 必须是大于等于 0 的整数`);
+}
+export function validateRange(range) {
+    if (range === undefined)
+        throw new Error('必须提供 range');
+    validateIndex(range.startRow, 'range.startRow');
+    validateIndex(range.startColumn, 'range.startColumn');
+    validateIndex(range.endRow, 'range.endRow');
+    validateIndex(range.endColumn, 'range.endColumn');
+    if (range.endRow < range.startRow || range.endColumn < range.startColumn)
+        throw new Error('range 结束位置不能小于开始位置');
+    if (range.endRow >= SHEET_MAX_PHYSICAL_ROWS)
+        throw new Error(`range 行号超过上限（最多 ${SHEET_MAX_ROWS} 条数据行 + 表头）`);
+    if (range.endColumn >= SHEET_MAX_COLUMNS)
+        throw new Error(`range 列号超过上限（最多 ${SHEET_MAX_COLUMNS} 列）`);
+    // No span check: `startRow`/`startColumn` are non-negative (above) and the end
+    // bounds are already inside the sheet, so the span cannot exceed it. Two
+    // checks that could never fire used to sit here, which is worse than noise —
+    // they read as a rule that something enforces.
+}
+/**
+ * A cell's formula in the one form this repository stores.
+ *
+ * `=SUM(A1:A2)` and `SUM(A1:A2)` are the same formula — the leading `=` is how a
+ * spreadsheet *displays* it, not part of it — and the whitespace around it is not
+ * part of it either. An input that reduces to nothing is not a formula at all.
+ *
+ * Four places wrote cells and each decided this for itself, so they disagreed:
+ * `update_cells` with `formula: '=SUM(A1:A2)'` stored `SUM(A1:A2)` in the
+ * snapshot and drew `=SUM(A1:A2)` on the canvas; `formula: ''` deleted the cell
+ * in the snapshot and left `{v:null,f:''}` on the canvas; `'='` was dropped by
+ * the snapshot and kept by the browser's merge. The snapshot and the canvas are
+ * two views of one workbook, so they cannot disagree about what is in it.
+ */
+export function normalizeCellFormula(formula) {
+    if (typeof formula !== 'string')
+        return undefined;
+    const normalized = formula.trim().replace(/^=/, '');
+    return normalized.length === 0 ? undefined : normalized;
+}
+export function toCellValue(cell) {
+    if (cell === undefined)
+        return null;
+    if (typeof cell.e === 'string')
+        return cell.e;
+    if (cell.v === undefined || cell.v === null)
+        return null;
+    if (typeof cell.v === 'string' || typeof cell.v === 'number' || typeof cell.v === 'boolean')
+        return cell.v;
+    return String(cell.v);
+}
+export function cellType(value) {
+    if (value === null)
+        return 'blank';
+    if (typeof value === 'number')
+        return 'number';
+    if (typeof value === 'boolean')
+        return 'boolean';
+    if (typeof value === 'string' && /^\d{4}-\d{2}-\d{2}(?:T|$)/.test(value))
+        return 'date';
+    return 'string';
+}
+/**
+ * The last row and column that actually carry something, or `-1` when the sheet
+ * is empty.
+ *
+ * A whole-sheet read needs this: the caller asking for "the sheet" must get the
+ * sheet, and the only way to know how big that is, is to look. A hard-coded
+ * window cannot know, and a window that is too small loses data silently.
+ *
+ * A cell that holds only a style is skipped — formatting an empty range writes
+ * style ids into every cell it covers, and those must not stretch a read.
+ */
+export function usedExtent(snapshot, sheetRef) {
+    const sheet = resolveSheet(asWorkbookSnapshot(snapshot), sheetRef);
+    let endRow = -1;
+    let endColumn = -1;
+    for (const [rowKey, line] of Object.entries(sheet.cellData ?? {})) {
+        const row = Number(rowKey);
+        if (!Number.isInteger(row) || row < 0)
+            continue;
+        let rowHasContent = false;
+        for (const [columnKey, cell] of Object.entries(line ?? {})) {
+            const column = Number(columnKey);
+            if (!Number.isInteger(column) || column < 0)
+                continue;
+            const hasValue = toCellValue(cell) !== null;
+            const hasFormula = typeof cell?.f === 'string' && cell.f !== '';
+            if (!hasValue && !hasFormula)
+                continue;
+            endColumn = Math.max(endColumn, column);
+            rowHasContent = true;
+        }
+        if (rowHasContent)
+            endRow = Math.max(endRow, row);
+    }
+    return { endRow, endColumn };
+}
+/**
+ * A style object out of a snapshot, narrowed to a plain record.
+ *
+ * Both storage shapes are real and both are read here: the browser's Univer
+ * residency keeps the object in the workbook's `styles` map and writes only its
+ * id onto the cell, while `format_cells` on the host writes the object inline.
+ * A resolver that knew one shape would silently drop the other's formatting.
+ */
+function styleRecord(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return {};
+    return { ...value };
+}
+/**
+ * The style a cell actually paints with: the sheet's default under the cell's
+ * own, field by field.
+ *
+ * The sheet default is load-bearing, not decoration. `DEFAULT_SHEET_FONT_FAMILY`
+ * lives in every sheet's `defaultStyle` and is the **only** place a font family
+ * is recorded for a cell the user never formatted — a reader that skipped it
+ * would report "no font" for most of a sheet, which is how the Sheet Block
+ * preview could not show the font the workbook is actually set in.
+ *
+ * `null` means there is nothing to paint, so the wire carries a compact matrix
+ * instead of an object per empty cell.
+ */
+export function effectiveCellStyle(root, sheet, cell) {
+    const inline = cell === undefined ? {} : styleRecord(cell.s);
+    const named = typeof cell?.s === 'string' ? styleRecord(root.styles?.[cell.s]) : {};
+    const merged = { ...styleRecord(sheet.defaultStyle), ...named, ...inline };
+    return Object.keys(merged).length === 0 ? null : merged;
+}
+export function readWorkbookRange(snapshot, sheetRef, range, options = {}) {
+    const root = asWorkbookSnapshot(snapshot);
+    const sheet = resolveSheet(root, sheetRef);
+    validateRange(range);
+    const withStyles = options.styles === true;
+    const values = [];
+    const formulas = [];
+    const cells = [];
+    const styles = [];
+    for (let row = range.startRow; row <= range.endRow; row += 1) {
+        const line = [];
+        const formulaLine = [];
+        const cellLine = [];
+        const styleLine = [];
+        for (let column = range.startColumn; column <= range.endColumn; column += 1) {
+            const cell = sheet.cellData[String(row)]?.[String(column)];
+            const value = toCellValue(cell);
+            const formula = typeof cell?.f === 'string' ? cell.f : null;
+            line.push(value);
+            formulaLine.push(formula);
+            cellLine.push({
+                value,
+                formula,
+                type: formula !== null ? 'formula' : cellType(value),
+                ...(formula === null ? {} : { calculation: value === null ? 'unavailable' : 'cached' }),
+                ...(typeof value === 'string' && value.startsWith('#') ? { error: value } : {}),
+            });
+            if (withStyles)
+                styleLine.push(effectiveCellStyle(root, sheet, cell));
+        }
+        values.push(line);
+        formulas.push(formulaLine);
+        cells.push(cellLine);
+        if (withStyles)
+            styles.push(styleLine);
+    }
+    return {
+        sheetId: sheet.id,
+        sheetName: sheet.name,
+        range,
+        values,
+        formulas,
+        cells,
+        ...(withStyles ? { styles } : {}),
+    };
+}
+/**
+ * Return original sheet row indexes that are duplicates within a rectangular
+ * range. This follows Excel's default behavior: compare the selected columns,
+ * keep the first occurrence, and leave the header untouched when requested.
+ */
+export function findDuplicateRows(values, range, columns, hasHeader = false, keep = 'first') {
+    const selectedColumns = columns === undefined || columns.length === 0
+        ? Array.from({ length: range.endColumn - range.startColumn + 1 }, (_value, index) => range.startColumn + index)
+        : [...new Set(columns)];
+    for (const column of selectedColumns) {
+        if (!Number.isInteger(column) || column < range.startColumn || column > range.endColumn) {
+            throw new Error('remove_duplicates 的 columns 必须位于 range 内');
+        }
+    }
+    if (keep !== 'first' && keep !== 'last')
+        throw new Error('remove_duplicates.keep 必须是 first 或 last');
+    const duplicateRows = [];
+    const seen = new Set();
+    const rowIndexes = Array.from({ length: values.length }, (_value, index) => index);
+    if (keep === 'last')
+        rowIndexes.reverse();
+    for (const offset of rowIndexes) {
+        if (hasHeader && offset === 0)
+            continue;
+        const row = values[offset] ?? [];
+        const key = JSON.stringify(selectedColumns.map(column => canonicalValue(row[column - range.startColumn])));
+        if (seen.has(key))
+            duplicateRows.push(range.startRow + offset);
+        else
+            seen.add(key);
+    }
+    return duplicateRows.sort((left, right) => left - right);
+}
+function canonicalValue(value) {
+    if (value === undefined || value === null)
+        return null;
+    if (typeof value === 'number' && Number.isNaN(value))
+        return 'NaN';
+    if (typeof value === 'object')
+        return JSON.stringify(value);
+    return value;
+}
+export function isSheetSchema(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const schema = value;
+    if (!Number.isInteger(schema.version) || !Array.isArray(schema.columns) || schema.columns.length === 0 || schema.columns.length > SHEET_MAX_COLUMNS
+        || !Number.isInteger(schema.rowCount) || schema.rowCount < 0 || schema.rowCount > SHEET_MAX_ROWS
+        || typeof schema.updatedAt !== 'string')
+        return false;
+    const keys = new Set();
+    return schema.columns.every(column => {
+        if (typeof column !== 'object' || column === null)
+            return false;
+        const candidate = column;
+        if (typeof candidate.key !== 'string' || !/^[A-Za-z0-9_]+$/.test(candidate.key) || keys.has(candidate.key)
+            || typeof candidate.label !== 'string' || candidate.label.length === 0
+            || !['string', 'number', 'boolean', 'date', 'currency'].includes(candidate.type ?? ''))
+            return false;
+        keys.add(candidate.key);
+        return true;
+    });
+}
+/** Force a snapshot's `name` field to the workbook's user-facing name.
+ * Both the read and the write path need it, which is why it is vocabulary
+ * rather than a store helper. */
+export function normalizeSnapshotName(snapshot, name) {
+    if (typeof snapshot !== 'object' || snapshot === null)
+        return snapshot;
+    return { ...snapshot, name };
+}

package/lib/types/contract/univer-api-catalog.d.ts

@@ -0,0 +1,29 @@
+/**
+ * JSON-safe metadata for the DSH adapter over Univer's Sheets Facade.
+ *
+ * The catalog is deliberately an allow-list. It gives an Agent discoverable
+ * method names and argument contracts without exposing arbitrary JavaScript or
+ * an Injector instance to the tool protocol. Methods that change workbook
+ * state map to the same durable operations used by the typed tools.
+ */
+import type { WorkbookOperationType } from '../types.ts';
+export type UniverApiMode = 'read' | 'write';
+export type UniverApiAvailability = 'implemented' | 'metadata-only';
+export interface UniverApiArgument {
+    type: 'string' | 'number' | 'boolean' | 'object' | 'array' | 'json';
+    required?: boolean;
+    description: string;
+}
+export interface UniverApiDefinition {
+    api: string;
+    mode: UniverApiMode;
+    availability: UniverApiAvailability;
+    description: string;
+    args: Record<string, UniverApiArgument>;
+    operation?: WorkbookOperationType;
+    notes?: string;
+}
+/** Common Facade methods exposed by the DSH Host adapter. */
+export declare const UNIVER_API_CATALOG: readonly UniverApiDefinition[];
+export declare const UNIVER_API_VERSION = "0.25.1-dsh-1";
+export declare function findUniverApi(api: string): UniverApiDefinition | undefined;

package/lib/types/contract/univer-api-catalog.js

@@ -0,0 +1,264 @@
+/**
+ * JSON-safe metadata for the DSH adapter over Univer's Sheets Facade.
+ *
+ * The catalog is deliberately an allow-list. It gives an Agent discoverable
+ * method names and argument contracts without exposing arbitrary JavaScript or
+ * an Injector instance to the tool protocol. Methods that change workbook
+ * state map to the same durable operations used by the typed tools.
+ */
+const rangeArgs = {
+    sheet: { type: 'string', description: 'sheet id 或名称；也可传 sheetId/sheetName；单 sheet workbook 可省略' },
+    range: { type: 'object', required: true, description: '0-based 矩形范围：{ startRow, startColumn, endRow, endColumn }；也接受 A1:D4' },
+};
+/** Common Facade methods exposed by the DSH Host adapter. */
+export const UNIVER_API_CATALOG = [
+    {
+        api: 'workbook.getSnapshot',
+        mode: 'read',
+        availability: 'implemented',
+        description: '读取当前 workbook 的 Univer snapshot。大表格请优先使用 worksheet.getRangeValues。',
+        args: {},
+    },
+    {
+        api: 'workbook.getWorksheets',
+        mode: 'read',
+        availability: 'implemented',
+        description: '返回 workbook 内所有 worksheet 的 id、名称和顺序。',
+        args: {},
+    },
+    {
+        api: 'worksheet.getRangeValues',
+        mode: 'read',
+        availability: 'implemented',
+        description: '读取 worksheet 的矩形区域值。',
+        args: rangeArgs,
+    },
+    {
+        api: 'worksheet.setValues',
+        mode: 'write',
+        availability: 'implemented',
+        description: '通过 Univer Range.setValues 写入值矩阵；range 可只传起点或省略，Host 会按矩阵尺寸推导。',
+        args: { sheet: rangeArgs.sheet, range: { type: 'object', description: '可选 0-based 范围；也可只传 startRow/startColumn，或使用 A1:D4' }, values: { type: 'array', required: true, description: '二维数组，也接受单行一维数组' } },
+        operation: 'update_cells',
+    },
+    {
+        api: 'worksheet.clearContent',
+        mode: 'write',
+        availability: 'implemented',
+        description: '清除 worksheet range 的内容。',
+        args: rangeArgs,
+        operation: 'clear_range',
+    },
+    {
+        api: 'worksheet.setBackgroundColor',
+        mode: 'write',
+        availability: 'implemented',
+        description: '设置 range 背景色。',
+        args: { ...rangeArgs, color: { type: 'string', required: true, description: 'CSS 颜色' } },
+        operation: 'format_cells',
+    },
+    {
+        api: 'worksheet.setFontColor',
+        mode: 'write',
+        availability: 'implemented',
+        description: '设置 range 字体颜色。',
+        args: { ...rangeArgs, color: { type: 'string', required: true, description: 'CSS 颜色' } },
+        operation: 'format_cells',
+    },
+    {
+        api: 'worksheet.setFontFamily',
+        mode: 'write',
+        availability: 'implemented',
+        description: '设置 range 字体。',
+        args: { ...rangeArgs, family: { type: 'string', required: true, description: '字体 family' } },
+        operation: 'format_cells',
+    },
+    {
+        api: 'worksheet.setFontSize',
+        mode: 'write',
+        availability: 'implemented',
+        description: '设置 range 字号。',
+        args: { ...rangeArgs, size: { type: 'number', required: true, description: '字号，单位 pt' } },
+        operation: 'format_cells',
+    },
+    {
+        api: 'worksheet.setFontWeight',
+        mode: 'write',
+        availability: 'implemented',
+        description: '设置 range 粗体状态。',
+        args: { ...rangeArgs, bold: { type: 'boolean', required: true, description: '是否粗体' } },
+        operation: 'format_cells',
+    },
+    {
+        api: 'worksheet.setFontStyle',
+        mode: 'write',
+        availability: 'implemented',
+        description: '设置 range 斜体状态。',
+        args: { ...rangeArgs, italic: { type: 'boolean', required: true, description: '是否斜体' } },
+        operation: 'format_cells',
+    },
+    {
+        api: 'worksheet.setHorizontalAlignment',
+        mode: 'write',
+        availability: 'implemented',
+        description: '设置 range 水平对齐。',
+        args: { ...rangeArgs, alignment: { type: 'string', required: true, description: 'left、center 或 normal' } },
+        operation: 'format_cells',
+    },
+    {
+        api: 'worksheet.setVerticalAlignment',
+        mode: 'write',
+        availability: 'implemented',
+        description: '设置 range 垂直对齐。',
+        args: { ...rangeArgs, alignment: { type: 'string', required: true, description: 'top、middle 或 bottom' } },
+        operation: 'format_cells',
+    },
+    {
+        api: 'worksheet.merge',
+        mode: 'write',
+        availability: 'implemented',
+        description: '合并 worksheet range。',
+        args: rangeArgs,
+        operation: 'merge_cells',
+    },
+    {
+        api: 'worksheet.breakApart',
+        mode: 'write',
+        availability: 'implemented',
+        description: '取消 worksheet range 的合并。',
+        args: rangeArgs,
+        operation: 'unmerge_cells',
+    },
+    {
+        api: 'worksheet.sort',
+        mode: 'write',
+        availability: 'implemented',
+        description: '对 worksheet range 按列排序。',
+        args: { ...rangeArgs, column: { type: 'number', required: true, description: '0-based 排序列索引' }, direction: { type: 'string', description: 'asc 或 desc，默认 asc' } },
+        operation: 'sort_range',
+    },
+    {
+        api: 'worksheet.setColumnWidth',
+        mode: 'write',
+        availability: 'implemented',
+        description: '设置列宽。',
+        args: { sheet: rangeArgs.sheet, index: { type: 'number', required: true, description: '0-based 列索引' }, size: { type: 'number', required: true, description: '像素宽度' } },
+        operation: 'set_column_width',
+    },
+    {
+        api: 'worksheet.setRowHeight',
+        mode: 'write',
+        availability: 'implemented',
+        description: '设置行高。',
+        args: { sheet: rangeArgs.sheet, index: { type: 'number', required: true, description: '0-based 行索引' }, size: { type: 'number', required: true, description: '像素高度' } },
+        operation: 'set_row_height',
+    },
+    {
+        api: 'worksheet.setHyperLink',
+        mode: 'write',
+        availability: 'implemented',
+        description: '给 range 左上角单元格设置超链接；等价于 workbook_edit 的 set_hyperlink command。',
+        args: { ...rangeArgs, url: { type: 'string', required: true, description: '目标 URL' }, label: { type: 'string', description: '显示文本' } },
+        operation: 'set_hyperlink',
+    },
+    {
+        api: 'worksheet.cancelHyperLink',
+        mode: 'write',
+        availability: 'implemented',
+        description: '移除 range 左上角单元格的超链接。',
+        args: rangeArgs,
+        operation: 'remove_hyperlink',
+    },
+    {
+        api: 'worksheet.setFreeze',
+        mode: 'write',
+        availability: 'implemented',
+        description: '冻结指定行列。',
+        args: { sheet: rangeArgs.sheet, rows: { type: 'number', description: '冻结行数，默认 0' }, columns: { type: 'number', description: '冻结列数，默认 0' } },
+        operation: 'freeze_panes',
+    },
+    {
+        api: 'worksheet.deleteCells',
+        mode: 'write',
+        availability: 'implemented',
+        description: '删除 range 内容，或按 left/up 移动邻近单元格。',
+        args: { ...rangeArgs, shift: { type: 'string', description: 'clear、left 或 up，默认 clear' } },
+        operation: 'delete_cells',
+    },
+    {
+        api: 'worksheet.insertRows',
+        mode: 'write',
+        availability: 'implemented',
+        description: '在指定行位置插入行。',
+        args: { sheet: rangeArgs.sheet, index: { type: 'number', required: true, description: '0-based 行位置' }, count: { type: 'number', description: '行数，默认 1' } },
+        operation: 'insert_rows',
+    },
+    {
+        api: 'worksheet.deleteRows',
+        mode: 'write',
+        availability: 'implemented',
+        description: '删除指定行。',
+        args: { sheet: rangeArgs.sheet, index: { type: 'number', required: true, description: '0-based 行位置' }, count: { type: 'number', description: '行数，默认 1' } },
+        operation: 'delete_rows',
+    },
+    {
+        api: 'worksheet.insertColumns',
+        mode: 'write',
+        availability: 'implemented',
+        description: '在指定列位置插入列。',
+        args: { sheet: rangeArgs.sheet, index: { type: 'number', required: true, description: '0-based 列位置' }, count: { type: 'number', description: '列数，默认 1' } },
+        operation: 'insert_columns',
+    },
+    {
+        api: 'worksheet.deleteColumns',
+        mode: 'write',
+        availability: 'implemented',
+        description: '删除指定列。',
+        args: { sheet: rangeArgs.sheet, index: { type: 'number', required: true, description: '0-based 列位置' }, count: { type: 'number', description: '列数，默认 1' } },
+        operation: 'delete_columns',
+    },
+    {
+        api: 'worksheet.setTextRotation',
+        mode: 'write',
+        availability: 'implemented',
+        description: '设置 range 文字旋转角度。',
+        args: { ...rangeArgs, rotation: { type: 'number', required: true, description: '旋转角度' } },
+        operation: 'format_cells',
+    },
+    {
+        api: 'worksheet.setNumberFormat',
+        mode: 'write',
+        availability: 'implemented',
+        description: '设置 range 数字格式。',
+        args: { ...rangeArgs, format: { type: 'string', required: true, description: 'Univer number format' } },
+        operation: 'format_cells',
+    },
+    {
+        api: 'worksheet.setName',
+        mode: 'write',
+        availability: 'implemented',
+        description: '修改 worksheet 名称。',
+        args: { sheet: rangeArgs.sheet, name: { type: 'string', required: true, description: '新的 sheet 名称' } },
+        operation: 'rename_sheet',
+    },
+    {
+        api: 'workbook.createSheet',
+        mode: 'write',
+        availability: 'implemented',
+        description: '持久化创建 worksheet；可用 sheetId 指定稳定 id。',
+        args: { name: { type: 'string', required: true, description: 'sheet 名称' }, sheetId: { type: 'string', description: '可选稳定 sheet id' } },
+        operation: 'create_sheet',
+    },
+    {
+        api: 'workbook.deleteSheet',
+        mode: 'write',
+        availability: 'implemented',
+        description: '持久化删除 worksheet；工作簿至少保留一个 sheet。',
+        args: { sheet: { type: 'string', description: 'sheet id 或名称；也接受 sheetId/sheetName' } },
+        operation: 'delete_sheet',
+    },
+];
+export const UNIVER_API_VERSION = '0.25.1-dsh-1';
+export function findUniverApi(api) {
+    return UNIVER_API_CATALOG.find(item => item.api === api);
+}

package/lib/types/errors.d.ts

@@ -0,0 +1,8 @@
+/** Shared wire-level errors for the Host API and browser client. */
+export type DataSheetErrorCode = 'VALIDATION_ERROR' | 'WORKBOOK_NOT_FOUND' | 'WORKTREE_NOT_FOUND' | 'SESSION_SCOPE_DENIED' | 'REVISION_CONFLICT' | 'REVISION_UNAVAILABLE' | 'WORKTREE_STATE_INVALID' | 'PAYLOAD_TOO_LARGE' | 'PERSISTENCE_FAILED' | 'COLLABORATION_LIMIT' | 'INTERNAL_ERROR';
+export declare class DataSheetError extends Error {
+    readonly code: DataSheetErrorCode;
+    readonly status: number;
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(code: DataSheetErrorCode, message: string, status?: number, details?: Record<string, unknown> | undefined);
+}

package/lib/types/errors.js

@@ -0,0 +1,12 @@
+export class DataSheetError extends Error {
+    code;
+    status;
+    details;
+    constructor(code, message, status = 400, details) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.details = details;
+        this.name = 'DataSheetError';
+    }
+}

package/lib/types/http/assets-routes.d.ts

@@ -0,0 +1,3 @@
+import type { LegacyRoute } from './routes.ts';
+/** Every static route this plugin serves. */
+export declare function assetRoutes(): LegacyRoute[];