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

package/lib/types/tools/render.js

@@ -0,0 +1,290 @@
+/**
+ * How a tool result reaches the model (docs/issue/0022 P3b).
+ *
+ * A tool answers with text blocks, and a large value is spilled to disk with a
+ * pointer instead of being inlined into the conversation. Both decisions are
+ * about *presentation*, so they sit together and neither tool owns them.
+ */
+import { randomUUID } from 'node:crypto';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { formatCellReference } from '#contracts';
+import { operationSummary } from "../contract/operations.js";
+import { toolOutputRoot } from "../store/paths.js";
+import { pruneToolOutput } from "../store/retention.js";
+export function textBlock(text) {
+    return { type: 'text', text };
+}
+export function asRecordOrUndefined(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value) ? value : undefined;
+}
+export function renderSummaryAndValue(summary, value) {
+    const detailPath = asRecordOrUndefined(value)?.detailPath;
+    const json = JSON.stringify(value, null, 2);
+    const header = summary.trim().length === 0 ? '' : `${summary}\n\n`;
+    if (json.length <= TOOL_RESULT_INLINE_LIMIT)
+        return [textBlock(`${header}${json}`)];
+    const preview = json.slice(0, TOOL_RESULT_INLINE_LIMIT);
+    const tail = typeof detailPath === 'string'
+        ? `\n…（结果过大，已截断）\n完整结果：${detailPath}（用 read 工具读取完整 JSON）`
+        : '\n…（结果过大，已截断）';
+    return [textBlock(`${header}${preview}${tail}`)];
+}
+/**
+ * Model-facing tool output.
+ *
+ * DSH treats `output.render` as the only content the model sees
+ * (harness `createSuccessResult`), so a constant string silently drops the
+ * whole workbook payload. These helpers keep a readable summary plus the real
+ * JSON inline, and oversized results are spilled to
+ * `<storage root>/tool-output/*.json` during `execute` and reported as
+ * `detailPath` instead of being truncated away.
+ */
+export const TOOL_RESULT_INLINE_LIMIT = 24_000;
+/** Spill an oversized canonical value so the model can still page through it. */
+export async function spillLargeToolResult(toolName, value) {
+    const record = asRecordOrUndefined(value) ?? { value };
+    if (JSON.stringify(record).length <= TOOL_RESULT_INLINE_LIMIT)
+        return record;
+    const directory = toolOutputRoot();
+    const detailPath = join(directory, `${toolName}-${Date.now().toString(36)}-${randomUUID().slice(0, 8)}.json`);
+    await mkdir(directory, { recursive: true });
+    await writeFile(detailPath, JSON.stringify(value, null, 2), 'utf8');
+    // Keep the directory bounded. Nothing used to, so these accumulated for the
+    // life of the installation.
+    await pruneToolOutput();
+    return { ...record, detailPath };
+}
+/** Keep large write payloads out of the model/tool transcript. */
+export function compactToolValue(value) {
+    if (Array.isArray(value))
+        return value.map(compactToolValue);
+    if (typeof value !== 'object' || value === null)
+        return value;
+    const record = value;
+    const result = {};
+    for (const [key, item] of Object.entries(record)) {
+        if (key === 'operation' && isOperationRecord(item))
+            result[key] = operationReceipt(item);
+        else if ((key === 'operations' || key === 'rebasedOperations') && Array.isArray(item)) {
+            result[key] = item.map(candidate => isOperationRecord(candidate) ? operationReceipt(candidate) : compactToolValue(candidate));
+        }
+        else
+            result[key] = compactToolValue(item);
+    }
+    return result;
+}
+export function asJsonValue(value) {
+    const serialized = JSON.stringify(compactToolValue(value));
+    if (serialized === undefined)
+        throw new Error('工具结果无法序列化');
+    return JSON.parse(serialized);
+}
+export function isOperationRecord(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const operation = value;
+    return typeof operation.opId === 'string' && typeof operation.workbookId === 'string'
+        && typeof operation.revision === 'number' && typeof operation.type === 'string'
+        && typeof operation.timestamp === 'string' && typeof operation.payload === 'object'
+        && operation.payload !== null;
+}
+export function operationReceipt(operation) {
+    const payload = operation.payload;
+    const cells = Array.isArray(payload.cells) ? payload.cells : [];
+    const range = payload.range ?? payload.merge;
+    const sheetRef = payload.sheetId ?? payload.sheetName;
+    const payloads = operation.type === 'batch' ? (payload.operations ?? []).map(step => step.payload) : [payload];
+    const sheetIds = [...new Set(payloads.map(item => item.sheetId ?? item.sheetName).filter((value) => typeof value === 'string'))];
+    const totalCellCount = operation.type === 'batch'
+        ? payloads.reduce((total, item) => total + (Array.isArray(item.cells) ? item.cells.length : 0), 0)
+        : cells.length;
+    const totalRowCount = operation.type === 'batch'
+        ? payloads.reduce((total, item) => total + (Array.isArray(item.rows) ? item.rows.length : 0), 0)
+        : Array.isArray(payload.rows) ? payload.rows.length : 0;
+    return {
+        opId: operation.opId,
+        workbookId: operation.workbookId,
+        revision: operation.revision,
+        parentRevision: operation.parentRevision ?? Math.max(0, operation.revision - 1),
+        ...(operation.versionId === undefined ? {} : { versionId: operation.versionId }),
+        ...(operation.versionStatus === undefined ? {} : { versionStatus: operation.versionStatus }),
+        ...(operation.versionSummary === undefined ? {} : { versionSummary: operation.versionSummary }),
+        ...(operation.versionIntent === undefined ? {} : { versionIntent: operation.versionIntent }),
+        ...(operation.agentRunId === undefined ? {} : { agentRunId: operation.agentRunId }),
+        ...(operation.lineage === undefined ? {} : { lineage: operation.lineage }),
+        ...(operation.restoredFromRevision === undefined ? {} : { restoredFromRevision: operation.restoredFromRevision }),
+        actor: operation.actor,
+        type: operation.type,
+        timestamp: operation.timestamp,
+        summary: operationSummary(operation),
+        ...(sheetRef === undefined ? {} : { sheetId: sheetRef }),
+        ...(sheetIds.length > 0 && operation.type === 'batch' ? { sheetIds } : {}),
+        ...(totalCellCount > 0 ? { cellCount: totalCellCount } : {}),
+        ...(totalRowCount > 0 ? { rowCount: totalRowCount } : {}),
+        ...(range === undefined ? {} : { range }),
+    };
+}
+export function isNonEmptyCell(cell) {
+    const record = asRecordOrUndefined(cell);
+    if (record === undefined)
+        return false;
+    if (typeof record.f === 'string' && record.f.length > 0)
+        return true;
+    return record.v !== undefined && record.v !== null && record.v !== '';
+}
+/** Compact per-sheet map (`name ↔ id` + size) that Agent callers use to address sheets. */
+export function sheetOverviews(snapshot) {
+    const root = asRecordOrUndefined(snapshot) ?? {};
+    const sheets = asRecordOrUndefined(root.sheets) ?? {};
+    const order = Array.isArray(root.sheetOrder)
+        ? root.sheetOrder.filter((item) => typeof item === 'string')
+        : Object.keys(sheets);
+    const result = [];
+    for (const id of order) {
+        const sheet = asRecordOrUndefined(sheets[id]);
+        if (sheet === undefined)
+            continue;
+        let maxRow = -1;
+        let maxColumn = -1;
+        let nonEmptyCells = 0;
+        const cellData = asRecordOrUndefined(sheet.cellData);
+        if (cellData !== undefined) {
+            for (const [rowKey, line] of Object.entries(cellData)) {
+                const row = Number(rowKey);
+                const cells = asRecordOrUndefined(line);
+                if (!Number.isInteger(row) || cells === undefined)
+                    continue;
+                for (const [columnKey, cell] of Object.entries(cells)) {
+                    const column = Number(columnKey);
+                    if (!Number.isInteger(column))
+                        continue;
+                    maxRow = Math.max(maxRow, row);
+                    maxColumn = Math.max(maxColumn, column);
+                    if (isNonEmptyCell(cell))
+                        nonEmptyCells += 1;
+                }
+            }
+        }
+        result.push({
+            id,
+            name: typeof sheet.name === 'string' ? sheet.name : id,
+            rowCount: typeof sheet.rowCount === 'number' ? sheet.rowCount : 0,
+            columnCount: typeof sheet.columnCount === 'number' ? sheet.columnCount : 0,
+            maxRow: maxRow < 0 ? null : maxRow,
+            maxColumn: maxColumn < 0 ? null : maxColumn,
+            nonEmptyCells,
+        });
+    }
+    return result;
+}
+export function sheetMapSummary(sheets) {
+    if (sheets.length === 0)
+        return '当前工作簿没有 sheet。';
+    return sheets.map(sheet => {
+        // `== null` on purpose: callers that summarise a sheet without reading its
+        // cells leave these absent rather than null, and `workbook_catalog` was
+        // printing `rows 0-undefined × cols 0-undefined` because of it.
+        const extent = sheet.maxRow == null || sheet.maxColumn == null
+            ? '暂无数据'
+            : `数据 rows 0-${sheet.maxRow} × cols 0-${sheet.maxColumn}`;
+        return `- ${sheet.name} ↔ ${sheet.id}（${extent}，非空 ${sheet.nonEmptyCells}）`;
+    }).join('\n');
+}
+/** Inline `名称（id）` list used by self-healing error messages. */
+export function sheetReferenceList(snapshot) {
+    const sheets = sheetOverviews(snapshot);
+    if (sheets.length === 0)
+        return '（当前工作簿没有 sheet）';
+    return sheets.map(sheet => `${sheet.name}（${sheet.id}）`).join(' / ');
+}
+export function renderCatalogResult(value) {
+    const record = asRecordOrUndefined(value) ?? {};
+    const action = typeof record.action === 'string' ? record.action : 'list';
+    if (Array.isArray(record.workbooks)) {
+        const workbooks = record.workbooks;
+        const lines = workbooks.map(item => `- ${String(item.id)}（${String(item.name)}）revision=${String(item.revision ?? 0)} sheets=${String(item.sheetCount ?? 0)} updatedAt=${String(item.updatedAt ?? '')}`);
+        return renderSummaryAndValue(workbooks.length === 0 ? '没有工作簿；请用 workbook_catalog(action=create) 创建。' : `共 ${workbooks.length} 个工作簿：\n${lines.join('\n')}`, value);
+    }
+    const workbook = asRecordOrUndefined(record.workbook);
+    if (workbook !== undefined) {
+        const sheets = Array.isArray(workbook.sheets) ? workbook.sheets : [];
+        return renderSummaryAndValue(`工作簿已就绪：${String(workbook.id)}（${String(workbook.name)}）revision=${String(workbook.revision ?? 0)}\n${sheetMapSummary(sheets)}`, value);
+    }
+    return renderSummaryAndValue(`工作簿目录操作已完成：action=${action}`, value);
+}
+export function renderReadResult(value) {
+    const record = asRecordOrUndefined(value) ?? {};
+    const parts = [`workbookId: ${String(record.workbookId ?? '')}，revision: ${String(record.revision ?? 0)}`];
+    const workbook = asRecordOrUndefined(record.workbook);
+    if (workbook !== undefined) {
+        const sheets = Array.isArray(workbook.sheets) ? workbook.sheets : [];
+        parts.push(`工作簿：${String(workbook.name ?? '')}，sheet 数：${sheets.length}`);
+        parts.push(sheetMapSummary(sheets));
+    }
+    const sheet = asRecordOrUndefined(record.sheet);
+    if (sheet !== undefined)
+        parts.push(`sheet：${String(sheet.name ?? '')} ↔ ${String(sheet.id ?? '')}`);
+    const range = asRecordOrUndefined(record.range);
+    if (range !== undefined && typeof range.startRow === 'number') {
+        parts.push(`range：rows ${range.startRow}-${range.endRow} × cols ${range.startColumn}-${range.endColumn}（0-based，end inclusive）`);
+    }
+    if (Array.isArray(record.values)) {
+        const first = record.values[0];
+        parts.push(`values：${record.values.length} 行 × ${Array.isArray(first) ? first.length : 0} 列`);
+    }
+    else if (Array.isArray(record.cells)) {
+        parts.push(`cells：${record.cells.length} 个`);
+    }
+    if (typeof record.detailPath === 'string')
+        parts.push(`完整结果：${record.detailPath}`);
+    return renderSummaryAndValue(parts.join('\n'), value);
+}
+export function renderFindResult(value) {
+    const record = asRecordOrUndefined(value) ?? {};
+    const results = Array.isArray(record.results) ? record.results : [];
+    const lines = results.slice(0, 20).map(item => `- ${formatCellReference({
+        sheet: typeof item.sheetName === 'string' ? item.sheetName : typeof item.sheetId === 'string' ? item.sheetId : '',
+        row: typeof item.row === 'number' ? item.row : 0,
+        column: typeof item.column === 'number' ? item.column : 0,
+    })} = ${JSON.stringify(item.value ?? null)}`);
+    const summary = `匹配 ${results.length} 处${record.truncated === true ? '（已截断，请缩小范围或提高 limit）' : ''}（query=${String(record.query ?? '')}，scope=${String(record.scope ?? '')}）`;
+    return renderSummaryAndValue(lines.length === 0 ? summary : `${summary}\n${lines.join('\n')}`, value);
+}
+export function renderHistoryResult(value) {
+    const record = asRecordOrUndefined(value) ?? {};
+    if (Array.isArray(record.versions)) {
+        const versions = record.versions;
+        const lines = versions.map(item => `- revision=${String(item.revision)} status=${String(item.status ?? '')} steps=${String(item.stepCount ?? '')} ${String(item.summary ?? '')}`);
+        return renderSummaryAndValue(`workbookId: ${String(record.workbookId ?? '')}，revision: ${String(record.revision ?? 0)}，Version ${versions.length} 个\n${lines.join('\n')}`, value);
+    }
+    return renderSummaryAndValue(`历史查询已完成：action=${String(record.action ?? '')}，workbookId=${String(record.workbookId ?? '')}`, value);
+}
+export function renderEditResult(value) {
+    const record = asRecordOrUndefined(value) ?? {};
+    const dryRun = record.dryRun === true;
+    const lines = [
+        dryRun
+            ? `编辑预检通过，尚未写入（revision 保持 ${String(record.revision ?? record.revisionBefore ?? 0)}）。`
+            : `工作簿编辑已提交（revision ${String(record.revisionBefore ?? '?')} → ${String(record.revisionAfter ?? record.revision ?? '?')}）。`,
+        `workbookId: ${String(record.workbookId ?? '')}`,
+        `Version ${String(record.versionCount ?? 0)} 个 / 命令 ${String(record.commandCount ?? 0)} 条，影响 sheet：${Array.isArray(record.affectedSheets) && record.affectedSheets.length > 0 ? record.affectedSheets.join('、') : '（无）'}，单元格 ${String(record.affectedCellCount ?? 0)} 个`,
+    ];
+    if (record.replayed === true)
+        lines.push('该 opId 之前已提交，本次为幂等重放。');
+    if (record.transformed === true) {
+        const rebased = Array.isArray(record.rebasedOperations) ? record.rebasedOperations.length : 0;
+        lines.push(`提交前检测到 ${rebased} 个并发编辑（均为单元格写入），已自动变基到最新 revision 后提交；行/列结构未变化，本计划的坐标仍然有效。`);
+    }
+    if (Array.isArray(record.warnings) && record.warnings.length > 0) {
+        lines.push('warnings：');
+        for (const warning of record.warnings)
+            lines.push(`- ${String(warning)}`);
+    }
+    if (dryRun && Array.isArray(record.versions)) {
+        for (const version of record.versions) {
+            lines.push(`- ${String(version.summary ?? '')}：${String(version.stepCount ?? 0)} 个 step`);
+        }
+    }
+    return renderSummaryAndValue(lines.join('\n'), value);
+}

package/lib/types/tools/univer-api.d.ts

@@ -0,0 +1,18 @@
+import type { LineageContext } from '#contracts';
+/** Sheet column types a modelled table may declare. */
+export declare function parseUniverApiAction(value: unknown): 'catalog' | 'search' | 'invoke';
+export type ApiArguments = Record<string, unknown>;
+export declare function asApiArguments(value: unknown): ApiArguments;
+/** Execute one cataloged Facade method through the durable DSH adapter. */
+export declare function executeUniverApi(args: {
+    workbookId: string;
+    api: string;
+    arguments: ApiArguments;
+    expectedRevision?: number;
+    opId?: string;
+    lineage?: LineageContext;
+}): Promise<unknown>;
+export declare function parseBoolean(value: unknown, label: string): boolean;
+export declare function parseColor(value: unknown, label: string): string;
+export declare function parseHorizontalAlignment(value: unknown): number;
+export declare function parseVerticalAlignment(value: unknown): number;

package/lib/types/tools/univer-api.js

@@ -0,0 +1,198 @@
+import { findUniverApi } from "../contract/univer-api-catalog.js";
+import { mutateWorkbook, readWorkbook, readWorkbookRange, summarize } from "../workbook-manager.js";
+import { normalizeValueMatrix, parseIndex, parseRange } from "../request-params.js";
+import { parseCellDeleteShift, parseCount, parseNonEmptyString, sheetRefFromArguments, sheetRefForSnapshot, } from "./arguments.js";
+import { dimensionRange, parseApiValues, parseFiniteNumber, parseFreeze, parseHyperlink, parseHyperlinkLabel, parseSort, parseValueRange, } from "./cells.js";
+/** Sheet column types a modelled table may declare. */
+const COLUMN_TYPES = ['string', 'number', 'boolean', 'date', 'currency'];
+/** Sheet column types a modelled table may declare. */
+export function parseUniverApiAction(value) {
+    if (value === 'catalog' || value === 'search' || value === 'invoke')
+        return value;
+    throw new Error('action 必须是 catalog、search 或 invoke');
+}
+export function asApiArguments(value) {
+    if (value === undefined || value === null)
+        return {};
+    if (typeof value !== 'object' || Array.isArray(value))
+        throw new Error('arguments 必须是对象');
+    return value;
+}
+/** Execute one cataloged Facade method through the durable DSH adapter. */
+export async function executeUniverApi(args) {
+    const definition = findUniverApi(args.api);
+    if (definition === undefined)
+        throw new Error(`未知 Univer API：${args.api}；请先调用 univer_api(action=catalog)`);
+    if (definition.availability !== 'implemented') {
+        throw new Error(`${args.api} 仅作为浏览器 Facade 元数据提供；持久化 workbook 请使用 workbook_edit 或已注册的 Adapter`);
+    }
+    const meta = await readWorkbook(args.workbookId);
+    if (meta === null)
+        throw new Error(`工作簿不存在：${args.workbookId}`);
+    const input = args.arguments;
+    if (definition.mode === 'read') {
+        switch (args.api) {
+            case 'workbook.getSnapshot':
+                return { ok: true, workbookId: args.workbookId, revision: meta.revision ?? 0, snapshot: meta.snapshot };
+            case 'workbook.getWorksheets': {
+                const sheets = summarize(meta).sheets;
+                return { ok: true, workbookId: args.workbookId, revision: meta.revision ?? 0, sheets, worksheets: sheets, sheetCount: sheets.length };
+            }
+            case 'worksheet.getRangeValues': {
+                const range = parseRange(input.range);
+                const sheet = sheetRefForSnapshot(meta.snapshot, input, 'arguments.sheet');
+                return { ok: true, workbookId: args.workbookId, revision: meta.revision ?? 0, ...readWorkbookRange(meta.snapshot, sheet, range) };
+            }
+            default:
+                throw new Error(`读取 API 尚未实现：${args.api}`);
+        }
+    }
+    let type = definition.operation;
+    let payload;
+    const sheet = args.api === 'workbook.createSheet'
+        ? sheetRefFromArguments(input, 'arguments.sheet')
+        : sheetRefForSnapshot(meta.snapshot, input, 'arguments.sheet');
+    switch (args.api) {
+        case 'worksheet.setValues': {
+            const matrix = input.values ?? input.data ?? input.matrix;
+            const valueMatrix = normalizeValueMatrix(matrix);
+            const range = parseValueRange(input.range, valueMatrix, 'arguments');
+            payload = { sheetId: sheet, cells: parseApiValues(valueMatrix, range) };
+            break;
+        }
+        case 'worksheet.clearContent':
+            payload = { sheetId: sheet, range: parseRange(input.range) };
+            break;
+        case 'worksheet.setBackgroundColor':
+            payload = { sheetId: sheet, range: parseRange(input.range), style: { bg: parseColor(input.color, 'color') } };
+            break;
+        case 'worksheet.setFontColor':
+            payload = { sheetId: sheet, range: parseRange(input.range), style: { cl: parseColor(input.color, 'color') } };
+            break;
+        case 'worksheet.setFontFamily':
+            payload = { sheetId: sheet, range: parseRange(input.range), style: { ff: parseNonEmptyString(input.family, 'family') } };
+            break;
+        case 'worksheet.setFontSize': {
+            const size = parseFiniteNumber(input.size, 'size');
+            if (size <= 0)
+                throw new Error('size 必须大于 0');
+            payload = { sheetId: sheet, range: parseRange(input.range), style: { fs: size } };
+            break;
+        }
+        case 'worksheet.setFontWeight':
+            payload = { sheetId: sheet, range: parseRange(input.range), style: { bl: parseBoolean(input.bold, 'bold') } };
+            break;
+        case 'worksheet.setFontStyle':
+            payload = { sheetId: sheet, range: parseRange(input.range), style: { it: parseBoolean(input.italic, 'italic') } };
+            break;
+        case 'worksheet.setHorizontalAlignment':
+            payload = { sheetId: sheet, range: parseRange(input.range), style: { ht: parseHorizontalAlignment(input.alignment) } };
+            break;
+        case 'worksheet.setVerticalAlignment':
+            payload = { sheetId: sheet, range: parseRange(input.range), style: { vt: parseVerticalAlignment(input.alignment) } };
+            break;
+        case 'worksheet.merge':
+            payload = { sheetId: sheet, range: parseRange(input.range) };
+            break;
+        case 'worksheet.breakApart':
+            payload = { sheetId: sheet, range: parseRange(input.range) };
+            break;
+        case 'worksheet.deleteCells':
+            payload = { sheetId: sheet, range: parseRange(input.range), shift: parseCellDeleteShift(input.shift) };
+            break;
+        case 'worksheet.insertRows':
+            payload = { sheetId: sheet, range: dimensionRange(parseIndex(input.index, 'index'), 'row'), count: input.count === undefined ? 1 : parseCount(input.count) };
+            break;
+        case 'worksheet.deleteRows':
+            payload = { sheetId: sheet, range: dimensionRange(parseIndex(input.index, 'index'), 'row'), count: input.count === undefined ? 1 : parseCount(input.count) };
+            break;
+        case 'worksheet.insertColumns':
+            payload = { sheetId: sheet, range: dimensionRange(parseIndex(input.index, 'index'), 'column'), count: input.count === undefined ? 1 : parseCount(input.count) };
+            break;
+        case 'worksheet.deleteColumns':
+            payload = { sheetId: sheet, range: dimensionRange(parseIndex(input.index, 'index'), 'column'), count: input.count === undefined ? 1 : parseCount(input.count) };
+            break;
+        case 'worksheet.setTextRotation':
+            payload = { sheetId: sheet, range: parseRange(input.range), style: { tr: parseFiniteNumber(input.rotation, 'rotation') } };
+            break;
+        case 'worksheet.setNumberFormat':
+            payload = { sheetId: sheet, range: parseRange(input.range), style: { n: parseNonEmptyString(input.format, 'format') } };
+            break;
+        case 'worksheet.setName':
+            payload = { sheetId: sheet, name: parseNonEmptyString(input.name, 'name') };
+            break;
+        case 'workbook.createSheet':
+            payload = { sheetId: sheet, name: parseNonEmptyString(input.name, 'name') };
+            break;
+        case 'workbook.deleteSheet':
+            payload = { sheetId: sheet };
+            break;
+        case 'worksheet.sort':
+            payload = { sheetId: sheet, range: parseRange(input.range), sort: parseSort({ column: input.column, direction: input.direction }) };
+            break;
+        case 'worksheet.setColumnWidth':
+            payload = { sheetId: sheet, range: dimensionRange(parseIndex(input.index, 'index'), 'column'), size: parseFiniteNumber(input.size, 'size') };
+            break;
+        case 'worksheet.setRowHeight':
+            payload = { sheetId: sheet, range: dimensionRange(parseIndex(input.index, 'index'), 'row'), size: parseFiniteNumber(input.size, 'size') };
+            break;
+        case 'worksheet.setHyperLink':
+            payload = { sheetId: sheet, range: parseRange(input.range), url: parseHyperlink(input.url), label: input.label === undefined ? undefined : parseHyperlinkLabel(input.label) };
+            break;
+        case 'worksheet.cancelHyperLink':
+            payload = { sheetId: sheet, range: parseRange(input.range) };
+            break;
+        case 'worksheet.setFreeze':
+            payload = { sheetId: sheet, freeze: parseFreeze({ rows: input.rows, columns: input.columns }) };
+            break;
+        default:
+            type = undefined;
+            throw new Error(`写入 API 尚未实现：${args.api}`);
+    }
+    if (type === undefined)
+        throw new Error(`API ${args.api} 没有持久化 operation 映射`);
+    const result = await mutateWorkbook({
+        workbookId: args.workbookId,
+        actor: 'agent',
+        type,
+        payload,
+        expectedRevision: args.expectedRevision,
+        opId: args.opId,
+        versionKind: 'named',
+        lineage: args.lineage,
+    });
+    return {
+        ok: true,
+        workbookId: args.workbookId,
+        revision: result.meta.revision ?? 0,
+        operation: result.operation,
+        ...(args.lineage === undefined ? {} : { lineage: args.lineage }),
+        ...(result.rebasedOperations === undefined ? {} : { rebasedOperations: result.rebasedOperations }),
+    };
+}
+export function parseBoolean(value, label) {
+    if (typeof value !== 'boolean')
+        throw new Error(`${label} 必须是 boolean`);
+    return value;
+}
+export function parseColor(value, label) {
+    return parseNonEmptyString(value, label);
+}
+export function parseHorizontalAlignment(value) {
+    if (value === 'left')
+        return 1;
+    if (value === 'center')
+        return 2;
+    if (value === 'normal')
+        return 0;
+    throw new Error('alignment 必须是 left、center 或 normal');
+}
+export function parseVerticalAlignment(value) {
+    if (value === 'top')
+        return 1;
+    if (value === 'middle')
+        return 2;
+    if (value === 'bottom')
+        return 0;
+    throw new Error('alignment 必须是 top、middle 或 bottom');
+}

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

@@ -0,0 +1,3 @@
+import { type ToolArguments } from './arguments.ts';
+export declare function parseCatalogAction(value: unknown): 'list' | 'create' | 'rename' | 'delete';
+export declare function executeWorkbookCatalog(args: ToolArguments): Promise<unknown>;

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

@@ -0,0 +1,83 @@
+/**
+ * `workbook_catalog`: the directory and lifecycle of workbooks (docs/issue/0022 P3b).
+ *
+ * Creation also names the file. A workbook's id *is* its file name under
+ * `<project>/storages/data-table/`, so the naming rule lives at this one entry
+ * point: `yyyymmdd-中文名含义` (see `storageNameOf`). Before it, a Chinese display
+ * name was slugged by an ASCII-only rule and became `_wb` — a directory nobody
+ * could read.
+ */
+import { blankSnapshot, deleteWorkbook, listWorkbookSummaries, readWorkbook, renameWorkbook, summarize, workbookExists, writeWorkbook, } from "../workbook-manager.js";
+import { storageNameOf } from '#contracts';
+import { normalizeWorkbookId } from "../contract/ids.js";
+import { now, parseNonEmptyString, workbookIdOf } from "./arguments.js";
+export function parseCatalogAction(value) {
+    if (value === 'list' || value === 'create' || value === 'rename' || value === 'delete')
+        return value;
+    throw new Error('action 必须是 list、create、rename 或 delete');
+}
+export async function executeWorkbookCatalog(args) {
+    const action = parseCatalogAction(args.action);
+    if (action === 'list') {
+        const summaries = await listWorkbookSummaries();
+        // 响应按 wire 契约标注，字段变化会在编译期被发现。
+        const response = {
+            ok: true,
+            workbooks: summaries.map(summary => ({
+                id: summary.id,
+                name: summary.name,
+                revision: summary.revision ?? 0,
+                sheets: summary.sheets,
+                sheetCount: summary.sheets.length,
+                updatedAt: summary.updatedAt,
+            })),
+        };
+        return response;
+    }
+    if (action === 'create') {
+        const name = parseNonEmptyString(args.name, 'name');
+        const requestedId = typeof args.workbookId === 'string' && args.workbookId.trim().length > 0 ? args.workbookId : undefined;
+        if (args.workbookId !== undefined && requestedId === undefined) {
+            throw new Error('workbookId 必须是非空字符串');
+        }
+        // Both halves of the name rule meet here:
+        //
+        //  · no id given — the display name *becomes* the file name's meaning, so the
+        //    directory says what each workbook is: `20261002-销售汇总.json`;
+        //  · an id given — it is the caller's own name for this workbook, and it is
+        //    used as written (character set aside). It is deliberately **not**
+        //    re-dated: a workbook named `20261001-销售汇总` yesterday must still be
+        //    addressable by the id its creator used, today.
+        const baseId = requestedId === undefined
+            ? storageNameOf(name, { fallback: '未命名工作簿' })
+            : normalizeWorkbookId(requestedId);
+        let workbookId = baseId;
+        if (requestedId !== undefined && await workbookExists(workbookId)) {
+            throw new Error('工作簿 id 已存在：' + workbookId);
+        }
+        for (let suffix = 2; requestedId === undefined && await workbookExists(workbookId); suffix += 1) {
+            workbookId = baseId + '-' + suffix;
+        }
+        await writeWorkbook({
+            id: workbookId,
+            name,
+            sheetOrder: ['sheet1'],
+            updatedAt: now(),
+            revision: 0,
+            operations: [],
+            snapshot: blankSnapshot(name),
+        });
+        return { ok: true, action, workbook: { id: workbookId, name, sheets: summarize((await readWorkbook(workbookId))).sheets, revision: 0 } };
+    }
+    const workbookId = workbookIdOf(args.workbookId);
+    if (action === 'rename') {
+        const meta = await renameWorkbook(workbookId, parseNonEmptyString(args.name, 'name'));
+        return { ok: true, action, workbook: { id: meta.id, name: meta.name, sheets: summarize(meta).sheets, revision: meta.revision ?? 0 } };
+    }
+    if (args.confirm !== true)
+        throw new Error('删除工作簿必须显式传 confirm: true');
+    if (!await workbookExists(workbookId))
+        throw new Error('工作簿不存在：' + workbookId);
+    await deleteWorkbook(workbookId);
+    return { ok: true, action, workbookId };
+}