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

package/lib/types/types.d.ts

@@ -0,0 +1,377 @@
+/**
+ * Shared contracts for dsh-data-table: sheet data (agent ↔ renderer)
+ * and the workbook model (agent tools ↔ node half ↔ browser canvas).
+ * @module dsh-data-table/types
+ */
+import type { LineageContext } from '#contracts';
+import type { VersionKind } from '#contracts';
+export type SheetColumnType = 'string' | 'number' | 'boolean' | 'date' | 'currency';
+export interface SheetColumn {
+    /** Unique key (English identifier, mirrors the row field). */
+    key: string;
+    /** Header label (Chinese copy is fine). */
+    label: string;
+    type: SheetColumnType;
+}
+export interface SheetMeta {
+    /** Data source description (e.g. SQL / file path). */
+    source?: string;
+    /** Generating SQL — data lineage. */
+    query?: string;
+    /** ISO timestamp. */
+    generatedAt?: string;
+    /** User-facing notes. */
+    notes?: string;
+    lineage?: LineageContext;
+}
+/** Persisted schema for an Agent-managed sheet. */
+export interface SheetSchema {
+    version: number;
+    columns: SheetColumn[];
+    /** Number of data rows, excluding the header row. */
+    rowCount: number;
+    updatedAt: string;
+}
+export interface SheetData {
+    /** Sheet name (panel title). */
+    name: string;
+    columns: SheetColumn[];
+    rows: Array<Record<string, unknown>>;
+    meta?: SheetMeta;
+}
+/** Row/column caps enforced by the host tool (documented in the tool schema). */
+/** Univer is a UI projection, not an unlimited database. Keep local imports
+ * bounded at 100k rows; larger tables should use a columnar backend. */
+export declare const SHEET_MAX_ROWS = 100000;
+/** Keep one large Agent append from monopolizing one Univer mutation frame. */
+export declare const SHEET_MAX_APPEND_ROWS = 1000;
+/** Physical row indexes include the header row at index 0. */
+export declare const SHEET_MAX_PHYSICAL_ROWS: number;
+export declare const SHEET_MAX_COLUMNS = 50;
+export declare const SHEET_MAX_NAME = 64;
+/** Whether a parsed tool-argument value is a well-formed sheet. */
+export declare function isSheetData(value: unknown): value is SheetData;
+/** Default workbook id (backward compatible with pre-workbook writes). */
+export declare const DEFAULT_WORKBOOK = "main";
+/**
+ * One named workbook: an Univer-compatible snapshot on disk (the whole state,
+ * sheets included). The agent addresses workbooks across sessions by id; the
+ * browser mounts a residency instance from the current snapshot.
+ */
+export interface WorkbookMeta {
+    id: string;
+    name: string;
+    /** Sheet ids in display order (Univer snapshot convention). */
+    sheetOrder: string[];
+    /** ISO timestamp of the last save. */
+    updatedAt: string;
+    /** Monotonically increasing revision of the workbook. */
+    revision?: number;
+    /** Revision represented by the persisted snapshot sidecar. */
+    snapshotRevision?: number;
+    /** Append-only operations used by replay, browser projection and audit UI. */
+    operations?: WorkbookOperation[];
+    /** Durable agent proposals awaiting user confirmation. */
+    proposals?: WorkbookProposal[];
+    /** Last known checkpoints used by rollback. */
+    checkpoints?: WorkbookCheckpoint[];
+    /** Univer workbook snapshot (sheets → cellData etc.). */
+    snapshot: unknown;
+}
+export type WorkbookActor = 'agent' | 'user';
+/**
+ * Lifecycle of a user-visible Version. `temporary` is retained only so old
+ * persisted operation logs can still be read; new writes use `open`.
+ */
+export type WorkbookVersionStatus = 'open' | 'final' | 'restored' | 'superseded' | 'temporary';
+/** Ephemeral collaboration state. Presence is broadcast live but never bumps
+ * the workbook revision or enters the durable operation log. */
+export type WorkbookPresenceKind = 'selection' | 'editing' | 'active-sheet';
+export interface WorkbookPresencePayload {
+    kind: WorkbookPresenceKind;
+    payload: Record<string, unknown>;
+}
+/** Current Univer range plus a bounded value preview for composer context. */
+export interface WorkbookSelectionRange {
+    sheetId: string;
+    sheetName: string;
+    startRow: number;
+    startColumn: number;
+    endRow: number;
+    endColumn: number;
+    values: readonly (readonly unknown[])[];
+}
+/** Coordinates the resident canvas can focus from a bridge reference. */
+export interface WorkbookFocusRange {
+    sheetId: string;
+    startRow: number;
+    startColumn: number;
+    endRow: number;
+    endColumn: number;
+}
+export interface WorkbookPresence {
+    workbookId: string;
+    sessionId: string;
+    actor: WorkbookActor;
+    kind: WorkbookPresenceKind;
+    payload: Record<string, unknown>;
+    timestamp: string;
+}
+/** Isolated review workspace lifecycle. The trunk workbook is never mutated
+ * until a worktree is explicitly merged. */
+export type WorkbookWorktreeStatus = 'draft' | 'ready' | 'merged' | 'discarded';
+export type WorkbookOperationType = 'update_cells' | 'clear_range' | 'delete_cells' | 'insert_rows' | 'delete_rows' | 'insert_columns' | 'delete_columns' | 'create_sheet' | 'delete_sheet' | 'rename_sheet' | 'append_rows' | 'format_cells' | 'merge_cells' | 'unmerge_cells' | 'freeze_panes' | 'set_column_width' | 'set_row_height' | 'sort_range' | 'set_hyperlink' | 'remove_hyperlink'
+/** Legacy-only operation retained so existing persisted histories can replay. */
+ | 'remove_duplicates' | 'batch' | 'snapshot_replace';
+/** How a deleted cell range affects neighboring cells. */
+export type WorkbookCellDeleteShift = 'clear' | 'left' | 'up';
+export type WorkbookCellValue = string | number | boolean | null;
+export interface WorkbookCellUpdate {
+    row: number;
+    column: number;
+    value: WorkbookCellValue;
+    /** Optional Univer formula, without the leading display-only metadata. */
+    formula?: string;
+}
+/** A browser-side edit that can be persisted without serializing the workbook. */
+export interface WorkbookLocalChange {
+    type: 'update_cells';
+    payload: {
+        sheetId: string;
+        cells: WorkbookCellUpdate[];
+    };
+}
+export interface WorkbookRange {
+    startRow: number;
+    startColumn: number;
+    endRow: number;
+    endColumn: number;
+}
+export interface WorkbookOperationPayload {
+    sheetId?: string;
+    sheetName?: string;
+    cells?: WorkbookCellUpdate[];
+    range?: WorkbookRange;
+    count?: number;
+    shift?: WorkbookCellDeleteShift;
+    name?: string;
+    columns?: SheetColumn[];
+    rows?: Array<Record<string, unknown>>;
+    /** Source-backed import is normalized to append_rows before persistence. */
+    sourcePath?: string;
+    sourceFormat?: string;
+    meta?: SheetMeta;
+    schema?: SheetSchema;
+    style?: WorkbookCellStyle;
+    merge?: WorkbookRange;
+    freeze?: {
+        rows?: number;
+        columns?: number;
+    };
+    size?: number;
+    sort?: {
+        column: number;
+        direction?: 'asc' | 'desc';
+    };
+    /** Hyperlink applied to the top-left cell of the range. */
+    url?: string;
+    label?: string;
+    /**
+     * Row that holds the column headers for `append_rows`; data starts on the row
+     * below it. Defaults to 0, which is the only behaviour the tool had before the
+     * field existed, so an omitted value keeps every existing caller intact.
+     * Report sheets keep their title block above the real header row, and this is
+     * what lets them be appended to instead of forcing a rewrite through
+     * `update_cells`.
+     */
+    headerRowIndex?: number;
+    /**
+     * When false, `append_rows` skips comparing existing header labels against the
+     * incoming column labels. Structure still has to be one column per column —
+     * this only relaxes the text match. Defaults to true.
+     */
+    verifyHeader?: boolean;
+    /** Legacy-only remove-duplicates payload fields; no longer exposed as tools/UI. */
+    dedupeColumns?: number[];
+    hasHeader?: boolean;
+    keep?: 'first' | 'last';
+    /** Server-computed original row indexes removed by remove_duplicates. */
+    removedRows?: number[];
+    operations?: Array<{
+        type: WorkbookOperationType;
+        payload: WorkbookOperationPayload;
+    }>;
+    snapshot?: unknown;
+}
+/** A small, JSON-safe subset of Univer cell styles used by Agent tools. */
+export interface WorkbookCellStyle {
+    ff?: string;
+    fs?: number;
+    bl?: boolean;
+    it?: boolean;
+    ul?: boolean;
+    st?: boolean;
+    bg?: string;
+    cl?: string;
+    ht?: number;
+    vt?: number;
+    tr?: number;
+    n?: string;
+}
+/** A durable, replayable mutation shared by Agent and user edits. */
+export interface WorkbookOperation {
+    opId: string;
+    workbookId: string;
+    revision: number;
+    /** Logical parent version. Normally revision - 1; rollback versions point
+     * back to the selected target while retaining their global revision number. */
+    parentRevision?: number;
+    /** Revision observed by the author before this operation was submitted. */
+    baseRevision?: number;
+    /** Stable logical Version id. Multiple physical revisions may fill one
+     * open user Version until it reaches the ten-step target. */
+    versionId?: string;
+    /** Open Versions accept additional user steps; final Versions do not. */
+    versionStatus?: WorkbookVersionStatus;
+    /** User-facing semantic description of this Version, supplied by the Host. */
+    versionSummary?: string;
+    /**
+     * v3 Version tier (PRD §4). Absent on operations written before v3; the
+     * projection then derives it from summary/actor, so old logs still classify.
+     */
+    versionKind?: VersionKind;
+    /** Optional Agent intent retained for audit without changing Step payloads. */
+    versionIntent?: string;
+    /** Correlates multiple semantic Versions emitted by one Agent run. */
+    agentRunId?: string;
+    /** Cross-plugin task/subtask/run lineage for this durable mutation. */
+    lineage?: LineageContext;
+    /** Source revision selected by a restore Version. */
+    restoredFromRevision?: number;
+    actor: WorkbookActor;
+    type: WorkbookOperationType;
+    timestamp: string;
+    payload: WorkbookOperationPayload;
+    /**
+     * Derived, human summary of this Step (v3.1). Set by the server when the
+     * caller's operation is generic — a whole-snapshot save describes itself as
+     * `替换 workbook 快照`, which said nothing about *what* changed.
+     */
+    stepSummary?: string;
+    /** Stable request digest used to detect accidental opId reuse with new data. */
+    requestHash?: string;
+}
+/** One replayable atomic step inside a version. */
+export interface WorkbookHistoryStep {
+    index: number;
+    opId: string;
+    type: WorkbookOperationType;
+    summary: string;
+    /**
+     * The revision this Step left behind — the state *after* it.
+     *
+     * Optional because a Step built from a history entry that predates the field
+     * has no revision of its own; a comparison then falls back to the Version's.
+     * Carrying it is what lets a Step be a comparison baseline and not only a
+     * thing to look at.
+     */
+    revision?: number;
+}
+/** Version-first history entry. Steps are available to the client but can be
+ * collapsed in the default history view. */
+export interface WorkbookHistoryVersion {
+    versionId: string;
+    /** Display number (`V1`, `V2`) assigned in creation order; never reused. */
+    number: number;
+    startRevision: number;
+    revision: number;
+    parentRevision: number;
+    actor: WorkbookActor;
+    timestamp: string;
+    summary: string;
+    /** v3 tier: `named` for a manual save / Agent call / restore, else `auto`. */
+    kind: VersionKind;
+    intent?: string;
+    agentRunId?: string;
+    lineage?: LineageContext;
+    restoredFromRevision?: number;
+    /** Display number of the Version a restore reinstated (v3 origin label). */
+    restoredFromNumber?: number;
+    stepCount: number;
+    steps: WorkbookHistoryStep[];
+    canPreview: boolean;
+    status: WorkbookVersionStatus;
+    branch: 'main' | 'superseded';
+}
+/** Durable isolated workbook workspace used for reviewable changes. */
+export interface WorkbookWorktree {
+    id: string;
+    workbookId: string;
+    /** Opaque browser/agent session that owns this worktree. */
+    ownerSessionId: string;
+    name: string;
+    baseRevision: number;
+    revision: number;
+    status: WorkbookWorktreeStatus;
+    createdAt: string;
+    updatedAt: string;
+    snapshot: unknown;
+    operations: WorkbookOperation[];
+}
+/** Payload-light worktree entry for catalog and UI lists. */
+export interface WorkbookWorktreeSummary {
+    id: string;
+    workbookId: string;
+    ownerSessionId: string;
+    name: string;
+    baseRevision: number;
+    revision: number;
+    status: WorkbookWorktreeStatus;
+    createdAt: string;
+    updatedAt: string;
+}
+export type WorkbookProposalStatus = 'pending' | 'committed' | 'rejected' | 'expired';
+export interface WorkbookProposal {
+    id: string;
+    workbookId: string;
+    actor: WorkbookActor;
+    baseRevision: number;
+    createdAt: string;
+    updatedAt: string;
+    status: WorkbookProposalStatus;
+    summary: string;
+    changes: WorkbookChange[];
+    snapshot: unknown;
+    committedRevision?: number;
+}
+export interface WorkbookChange {
+    kind: 'cell' | 'sheet' | 'structure';
+    sheetId?: string;
+    sheetName?: string;
+    row?: number;
+    column?: number;
+    before?: unknown;
+    after?: unknown;
+    /** The value is unchanged on both sides; only the cell's formatting moved. */
+    styleOnly?: boolean;
+    description?: string;
+}
+export interface WorkbookCheckpoint {
+    revision: number;
+    actor: WorkbookActor;
+    timestamp: string;
+    snapshot: unknown;
+}
+/** Tool result for workbook listing/open. */
+export interface WorkbookSummary {
+    id: string;
+    name: string;
+    sheets: Array<{
+        id: string;
+        name: string;
+        schema?: SheetSchema;
+    }>;
+    updatedAt: string;
+    /** Current trunk revision; lets `workbook_catalog(action=list)` feed `baseRevision` without a second read. */
+    revision?: number;
+}

package/lib/types/types.js

@@ -0,0 +1,34 @@
+/**
+ * Shared contracts for dsh-data-table: sheet data (agent ↔ renderer)
+ * and the workbook model (agent tools ↔ node half ↔ browser canvas).
+ * @module dsh-data-table/types
+ */
+/** Row/column caps enforced by the host tool (documented in the tool schema). */
+/** Univer is a UI projection, not an unlimited database. Keep local imports
+ * bounded at 100k rows; larger tables should use a columnar backend. */
+export const SHEET_MAX_ROWS = 100000;
+/** Keep one large Agent append from monopolizing one Univer mutation frame. */
+export const SHEET_MAX_APPEND_ROWS = 1000;
+/** Physical row indexes include the header row at index 0. */
+export const SHEET_MAX_PHYSICAL_ROWS = SHEET_MAX_ROWS + 1;
+export const SHEET_MAX_COLUMNS = 50;
+export const SHEET_MAX_NAME = 64;
+/** Whether a parsed tool-argument value is a well-formed sheet. */
+export function isSheetData(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const sheet = value;
+    if (typeof sheet.name !== 'string' || sheet.name.length === 0)
+        return false;
+    if (!Array.isArray(sheet.columns) || !Array.isArray(sheet.rows))
+        return false;
+    return sheet.columns.every(column => {
+        if (typeof column !== 'object' || column === null)
+            return false;
+        const c = column;
+        return typeof c.key === 'string' && typeof c.label === 'string'
+            && (c.type === 'string' || c.type === 'number' || c.type === 'boolean' || c.type === 'date' || c.type === 'currency');
+    });
+}
+/** Default workbook id (backward compatible with pre-workbook writes). */
+export const DEFAULT_WORKBOOK = 'main';

package/lib/types/univer/apply-operation.d.ts

@@ -0,0 +1,14 @@
+import type { WorkbookOperation } from '../types.ts';
+import type { SheetsApi, SheetResolver } from './facade.ts';
+/** Default sheet extent (Univer's own default), so data lands on a full-size grid. */
+export interface OperationApplier {
+    apply(operation: WorkbookOperation): Promise<void>;
+    /** True while an operation from elsewhere is being written to the canvas. */
+    isApplyingRemote(): boolean;
+    /** Sheet metadata that only exists in the live canvas (not in the snapshot). */
+    liveSheetMetadata: Map<string, unknown>;
+}
+export declare function createOperationApplier(deps: {
+    sheetsApi: SheetsApi;
+    getSheet: SheetResolver;
+}): OperationApplier;