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

package/lib/types/tools/workbook-find.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `workbook_find`: locate a value across sheets, cells or formulas
+ * (docs/issue/0022 P3b).
+ */
+import type { WorkbookRange } from '../types.ts';
+import { type ToolArguments } from './arguments.ts';
+export declare function parseFindScope(value: unknown): 'sheets' | 'cells' | 'formulas';
+export declare function parseFindMatch(value: unknown): 'contains' | 'exact' | 'regex';
+export declare function textMatcher(query: string, match: 'contains' | 'exact' | 'regex'): (value: unknown) => boolean;
+export declare function inRange(row: number, column: number, range: WorkbookRange | undefined): boolean;
+export declare function findWorkbookContent(workbookId: string, args: ToolArguments): Promise<unknown>;

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

@@ -0,0 +1,89 @@
+import { readWorkbook } from "../workbook-manager.js";
+import { parseRange } from "../request-params.js";
+import { asToolArguments, parseCount, parseNonEmptyString, sheetRefFromArguments } from "./arguments.js";
+export function parseFindScope(value) {
+    if (value === undefined || value === null)
+        return 'cells';
+    if (value === 'sheets' || value === 'cells' || value === 'formulas')
+        return value;
+    throw new Error('scope 必须是 sheets、cells 或 formulas');
+}
+export function parseFindMatch(value) {
+    if (value === undefined || value === null)
+        return 'contains';
+    if (value === 'contains' || value === 'exact' || value === 'regex')
+        return value;
+    throw new Error('match 必须是 contains、exact 或 regex');
+}
+export function textMatcher(query, match) {
+    if (match === 'regex') {
+        let expression;
+        try {
+            expression = new RegExp(query, 'i');
+        }
+        catch {
+            throw new Error('query 不是有效的正则表达式');
+        }
+        return value => expression.test(String(value ?? ''));
+    }
+    const needle = query.toLocaleLowerCase();
+    return value => {
+        const text = String(value ?? '').toLocaleLowerCase();
+        return match === 'exact' ? text === needle : text.includes(needle);
+    };
+}
+export function inRange(row, column, range) {
+    return range === undefined || row >= range.startRow && row <= range.endRow && column >= range.startColumn && column <= range.endColumn;
+}
+export async function findWorkbookContent(workbookId, args) {
+    const meta = await readWorkbook(workbookId);
+    if (meta === null)
+        throw new Error('工作簿不存在：' + workbookId);
+    const query = parseNonEmptyString(args.query, 'query');
+    const scope = parseFindScope(args.scope);
+    const match = parseFindMatch(args.match);
+    const matches = textMatcher(query, match);
+    const limit = args.limit === undefined ? 100 : Math.min(500, parseCount(args.limit));
+    const selectedSheet = sheetRefFromArguments(args, 'sheet');
+    const range = args.range === undefined ? undefined : parseRange(args.range);
+    const root = asToolArguments(meta.snapshot, 'workbook snapshot');
+    const sheets = asToolArguments(root.sheets, 'workbook snapshot.sheets');
+    const results = [];
+    for (const [sheetId, sheet] of Object.entries(sheets)) {
+        const sheetName = typeof sheet.name === 'string' ? sheet.name : sheetId;
+        if (selectedSheet !== undefined && selectedSheet !== sheetId && selectedSheet !== sheetName)
+            continue;
+        if (scope === 'sheets') {
+            if (matches(sheetName))
+                results.push({ sheetId, sheetName });
+            if (results.length >= limit)
+                break;
+            continue;
+        }
+        const cellData = sheet.cellData;
+        if (typeof cellData !== 'object' || cellData === null || Array.isArray(cellData))
+            continue;
+        for (const [rowKey, line] of Object.entries(cellData)) {
+            const row = Number(rowKey);
+            if (!Number.isInteger(row) || typeof line !== 'object' || line === null || Array.isArray(line))
+                continue;
+            for (const [columnKey, rawCell] of Object.entries(line)) {
+                const column = Number(columnKey);
+                if (!Number.isInteger(column) || !inRange(row, column, range))
+                    continue;
+                const cell = typeof rawCell === 'object' && rawCell !== null && !Array.isArray(rawCell) ? rawCell : {};
+                const candidate = scope === 'formulas' ? cell.f : cell.v;
+                if (!matches(candidate))
+                    continue;
+                results.push({ sheetId, sheetName, row, column, value: cell.v ?? null, formula: typeof cell.f === 'string' ? cell.f : null });
+                if (results.length >= limit)
+                    break;
+            }
+            if (results.length >= limit)
+                break;
+        }
+        if (results.length >= limit)
+            break;
+    }
+    return { ok: true, workbookId, revision: meta.revision ?? 0, query, scope, match, results, truncated: results.length >= limit };
+}

package/lib/types/tools/workbook-history.d.ts

@@ -0,0 +1,2 @@
+import { type ToolArguments } from './arguments.ts';
+export declare function executeHistoryQuery(workbookId: string, args: ToolArguments): Promise<unknown>;

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

@@ -0,0 +1,59 @@
+import { readWorkbook, readWorkbookAtRevision, readWorkbookAtStep } from "../workbook-manager.js";
+import { diffWorkbookSnapshots } from "../version/diff.js";
+import { historyVersionsFromOperations } from "../version/grouping.js";
+import { activeHistoryRevisions, canReplayHistoryRevision, checkpointHasher, toVersionRecords } from "../version/records.js";
+import { parseIndex } from "../request-params.js";
+import { parseCount } from "./arguments.js";
+export async function executeHistoryQuery(workbookId, args) {
+    const action = args.action === undefined || args.action === null ? 'list' : args.action;
+    if (action !== 'list' && action !== 'diff' && action !== 'replay')
+        throw new Error('action 必须是 list、diff 或 replay');
+    if (action === 'diff') {
+        const fromRevision = parseIndex(args.fromRevision, 'fromRevision');
+        const toRevision = parseIndex(args.toRevision, 'toRevision');
+        if (fromRevision > toRevision)
+            throw new Error('fromRevision 不得大于 toRevision');
+        const left = await readWorkbookAtRevision(workbookId, fromRevision);
+        const right = await readWorkbookAtRevision(workbookId, toRevision);
+        if (left === null || right === null)
+            throw new Error('指定 revision 已被压缩或无法重放');
+        return { ok: true, action, workbookId, fromRevision, toRevision, changes: diffWorkbookSnapshots(left.snapshot, right.snapshot) };
+    }
+    if (action === 'replay') {
+        const rawRevision = args.revision ?? args.toRevision;
+        const revision = parseIndex(rawRevision, 'revision');
+        if (args.step !== undefined && args.step !== null) {
+            const step = parseIndex(args.step, 'step');
+            const replay = await readWorkbookAtStep(workbookId, revision, step);
+            if (replay === null)
+                throw new Error('指定 revision/step 已被压缩或无法重放');
+            return { ok: true, action, workbookId, ...replay };
+        }
+        const replay = await readWorkbookAtRevision(workbookId, revision);
+        if (replay === null)
+            throw new Error('指定 revision 已被压缩或无法重放');
+        return { ok: true, action, workbookId, ...replay };
+    }
+    const meta = await readWorkbook(workbookId, { includeCheckpoints: true });
+    if (meta === null)
+        throw new Error('工作簿不存在：' + workbookId);
+    const limit = args.limit === undefined ? 20 : Math.min(100, Math.max(1, parseCount(args.limit)));
+    const allOperations = (meta.operations ?? []).slice().sort((left, right) => left.revision - right.revision);
+    const currentRevision = meta.revision ?? 0;
+    const byRevision = new Map(allOperations.map(operation => [operation.revision, operation]));
+    const active = activeHistoryRevisions(currentRevision, byRevision);
+    const checkpoints = (meta.checkpoints ?? []).map(checkpoint => checkpoint.revision).sort((left, right) => left - right);
+    const canReplay = (revision) => canReplayHistoryRevision(revision, currentRevision, checkpoints, byRevision);
+    const fullVersions = historyVersionsFromOperations(allOperations, canReplay, active).slice(-limit);
+    const versions = fullVersions.map(({ steps: _steps, ...version }) => version);
+    return {
+        ok: true,
+        action,
+        workbookId,
+        revision: currentRevision,
+        versions,
+        // Unified cross-plugin model (PRD §7.1). `versions` stays for compatibility.
+        versionRecords: toVersionRecords(fullVersions, workbookId, checkpointHasher(meta.checkpoints ?? [])),
+        checkpoints,
+    };
+}

package/lib/types/tools/workbook-read.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `workbook_read`: one bounded look at a sheet, a range or a single cell
+ * (docs/issue/0022 P3b).
+ */
+import type { WorkbookRange } from '../types.ts';
+export declare function parseReadIncludes(value: unknown): Set<string>;
+export declare function snapshotSheet(snapshot: unknown, sheetRef: string): Record<string, unknown>;
+export declare function snapshotCell(snapshot: unknown, sheetRef: string, row: number, column: number): Record<string, unknown> | undefined;
+export declare function styleMatrix(snapshot: unknown, sheetRef: string, range: WorkbookRange): unknown[][];
+/**
+ * Per-sheet backfill status for `workbook_read(kind: 'workbook')`
+ * (docs/issue/0011 I5 / T7).
+ *
+ * The agent kept a prose table of "which sheet still needs what" because the
+ * read surface could only show scale. This reports the four things that table
+ * tracked — data area, run provenance, run time and a conclusion block — so a
+ * workbook's completeness is visible without opening every sheet. `complete` is
+ * deliberately conservative: it is a hint, not a gate.
+ */
+export declare function sheetBackfillStatus(sheet: Record<string, unknown>): Record<string, unknown>;
+export declare function readWorkbookTarget(workbookId: string, rawTarget: unknown, rawInclude: unknown): Promise<unknown>;

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

@@ -0,0 +1,204 @@
+import { readWorkbook, readWorkbookRange, summarize } from "../workbook-manager.js";
+import { parseIndex, parseRange } from "../request-params.js";
+import { asToolArguments, sheetRefForSnapshot } from "./arguments.js";
+import { sheetOverviews } from "./render.js";
+export function parseReadIncludes(value) {
+    if (value === undefined || value === null)
+        return new Set();
+    if (!Array.isArray(value))
+        throw new Error('include 必须是字符串数组');
+    const allowed = new Set(['values', 'formulas', 'cells', 'styles', 'snapshot', 'backfill']);
+    const result = new Set();
+    for (const item of value) {
+        if (typeof item !== 'string' || !allowed.has(item))
+            throw new Error('include 仅支持 values、formulas、cells、styles、snapshot、backfill');
+        result.add(item);
+    }
+    return result;
+}
+export function snapshotSheet(snapshot, sheetRef) {
+    const root = asToolArguments(snapshot, 'workbook snapshot');
+    const sheets = asToolArguments(root.sheets, 'workbook snapshot.sheets');
+    const direct = sheets[sheetRef];
+    if (direct !== undefined)
+        return direct;
+    const byName = Object.values(sheets).find(sheet => sheet.name === sheetRef);
+    if (byName === undefined)
+        throw new Error('sheet 不存在：' + sheetRef);
+    return byName;
+}
+export function snapshotCell(snapshot, sheetRef, row, column) {
+    const sheet = snapshotSheet(snapshot, sheetRef);
+    const cellData = sheet.cellData;
+    if (typeof cellData !== 'object' || cellData === null || Array.isArray(cellData))
+        return undefined;
+    const line = cellData[String(row)];
+    if (typeof line !== 'object' || line === null || Array.isArray(line))
+        return undefined;
+    const cell = line[String(column)];
+    return typeof cell === 'object' && cell !== null && !Array.isArray(cell) ? cell : undefined;
+}
+export function styleMatrix(snapshot, sheetRef, range) {
+    const result = [];
+    for (let row = range.startRow; row <= range.endRow; row += 1) {
+        const line = [];
+        for (let column = range.startColumn; column <= range.endColumn; column += 1) {
+            line.push(snapshotCell(snapshot, sheetRef, row, column)?.s ?? null);
+        }
+        result.push(line);
+    }
+    return result;
+}
+/**
+ * Per-sheet backfill status for `workbook_read(kind: 'workbook')`
+ * (docs/issue/0011 I5 / T7).
+ *
+ * The agent kept a prose table of "which sheet still needs what" because the
+ * read surface could only show scale. This reports the four things that table
+ * tracked — data area, run provenance, run time and a conclusion block — so a
+ * workbook's completeness is visible without opening every sheet. `complete` is
+ * deliberately conservative: it is a hint, not a gate.
+ */
+export function sheetBackfillStatus(sheet) {
+    const asRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value) ? value : undefined;
+    const stats = asRecord(sheet.dataSheetStats);
+    const meta = asRecord(sheet.dataSheetMeta);
+    const schema = asRecord(sheet.dataSheetSchema);
+    const dataRows = typeof stats?.rowCount === 'number' && stats.rowCount >= 0 ? stats.rowCount : 0;
+    const cellData = asRecord(sheet.cellData) ?? {};
+    // A conclusion block is not tracked anywhere in the snapshot: any write
+    // recomputes the row counts, so the counter cannot separate data from prose.
+    // What it can do is spot rows that do not span the data schema, which is the
+    // shape a conclusion row takes in these report sheets (row 0 is the header).
+    const schemaColumns = Array.isArray(schema?.columns) ? schema.columns.length : 0;
+    let conclusionRows = 0;
+    for (const [key, line] of Object.entries(cellData)) {
+        const row = Number(key);
+        if (!Number.isInteger(row) || row <= 0)
+            continue;
+        const cells = asRecord(line);
+        if (cells === undefined)
+            continue;
+        const filled = Object.values(cells).filter(cell => {
+            const value = asRecord(cell)?.v;
+            return value !== undefined && value !== null && String(value).length > 0;
+        }).length;
+        if (filled === 0)
+            continue;
+        if (schemaColumns > 0 && filled >= schemaColumns)
+            continue;
+        conclusionRows += 1;
+    }
+    const provenance = meta === undefined
+        ? null
+        : { source: meta.source ?? null, query: meta.query ?? null, notes: meta.notes ?? null };
+    return {
+        /** Highest row index holding content. Every write recomputes it, so it
+         * covers a conclusion block as well as the data — it is a bound, not a
+         * count of data rows. */
+        lastOccupiedRow: typeof stats?.rowCount === 'number' && stats.rowCount >= 0 ? stats.rowCount : 0,
+        columnCount: typeof stats?.columnCount === 'number' ? stats.columnCount : 0,
+        conclusionRows,
+        runAt: typeof meta?.generatedAt === 'string' ? meta.generatedAt : null,
+        provenance,
+        schemaUpdatedAt: typeof schema?.updatedAt === 'string' ? schema.updatedAt : null,
+        complete: (typeof stats?.rowCount === 'number' ? stats.rowCount : 0) > 0 && provenance !== null,
+    };
+}
+export async function readWorkbookTarget(workbookId, rawTarget, rawInclude) {
+    const meta = await readWorkbook(workbookId);
+    if (meta === null)
+        throw new Error('工作簿不存在：' + workbookId);
+    const target = asToolArguments(rawTarget, 'target');
+    const kind = target.kind;
+    if (kind !== 'workbook' && kind !== 'sheet' && kind !== 'range' && kind !== 'cells') {
+        throw new Error('target.kind 必须是 workbook、sheet、range 或 cells');
+    }
+    const include = parseReadIncludes(rawInclude);
+    const summary = summarize(meta);
+    const base = { ok: true, workbookId, revision: meta.revision ?? 0 };
+    if (kind === 'workbook') {
+        const sheets = sheetOverviews(meta.snapshot);
+        return {
+            ...base,
+            workbook: { id: summary.id, name: summary.name, sheets, sheetCount: sheets.length, updatedAt: summary.updatedAt },
+            ...(include.has('snapshot') ? { snapshot: meta.snapshot } : {}),
+            ...(include.has('backfill')
+                ? {
+                    backfill: sheets.map(overview => ({
+                        sheetId: overview.id,
+                        name: overview.name,
+                        ...sheetBackfillStatus(snapshotSheet(meta.snapshot, overview.id)),
+                    })),
+                }
+                : {}),
+        };
+    }
+    const sheetRef = sheetRefForSnapshot(meta.snapshot, target, 'target.sheet');
+    const sheet = snapshotSheet(meta.snapshot, sheetRef);
+    const sheetSummary = summary.sheets.find(candidate => candidate.id === sheetRef || candidate.name === sheetRef);
+    const resolvedSheetRef = {
+        workbookId,
+        sheetId: sheetSummary?.id ?? String(sheet.id ?? sheetRef),
+        sheetName: sheetSummary?.name ?? String(sheet.name ?? sheetRef),
+    };
+    if (kind === 'sheet') {
+        const overview = sheetOverviews(meta.snapshot).find(candidate => candidate.id === resolvedSheetRef.sheetId);
+        return {
+            ...base,
+            sheetRef: resolvedSheetRef,
+            sheet: {
+                id: resolvedSheetRef.sheetId,
+                name: resolvedSheetRef.sheetName,
+                rowCount: overview?.rowCount ?? sheet.rowCount ?? 0,
+                columnCount: overview?.columnCount ?? sheet.columnCount ?? 0,
+                maxRow: overview?.maxRow ?? null,
+                maxColumn: overview?.maxColumn ?? null,
+                nonEmptyCells: overview?.nonEmptyCells ?? 0,
+            },
+            ...(include.has('snapshot') ? { snapshot: sheet } : {}),
+        };
+    }
+    if (kind === 'range') {
+        const range = parseRange(target.range);
+        const result = readWorkbookRange(meta.snapshot, sheetRef, range);
+        // `readWorkbookRange` materializes values, formulas and cells together, but
+        // returning all three inline spent the result budget three times over
+        // (docs/issue/0011 I1 / T5). Only `values` is unconditional; the heavier views
+        // have to be asked for.
+        return {
+            ...base,
+            sheetRef: { ...resolvedSheetRef, range: `${range.startRow}:${range.startColumn}-${range.endRow}:${range.endColumn}` },
+            sheetId: result.sheetId,
+            sheetName: result.sheetName,
+            range: result.range,
+            values: result.values,
+            ...(include.has('formulas') ? { formulas: result.formulas } : {}),
+            ...(include.has('cells') ? { cells: result.cells } : {}),
+            ...(include.has('styles') ? { styles: styleMatrix(meta.snapshot, result.sheetId, range) } : {}),
+        };
+    }
+    if (!Array.isArray(target.cells) || target.cells.length === 0 || target.cells.length > 500) {
+        throw new Error('target.cells 必须是 1 到 500 项的单元格坐标数组');
+    }
+    const cells = target.cells.map((rawCell, index) => {
+        const coordinate = asToolArguments(rawCell, 'target.cells[' + index + ']');
+        const row = parseIndex(coordinate.row, 'target.cells[' + index + '].row');
+        const column = parseIndex(coordinate.column, 'target.cells[' + index + '].column');
+        const cell = snapshotCell(meta.snapshot, sheetRef, row, column);
+        const value = cell?.v;
+        return {
+            row,
+            column,
+            value: value === undefined ? null : value,
+            formula: typeof cell?.f === 'string' ? cell.f : null,
+            ...(include.has('styles') ? { style: cell?.s ?? null } : {}),
+        };
+    });
+    return {
+        ...base,
+        sheetRef: resolvedSheetRef,
+        sheet: { id: resolvedSheetRef.sheetId, name: resolvedSheetRef.sheetName },
+        cells,
+    };
+}