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

package/src/tools/univer-api.ts

@@ -0,0 +1,243 @@
+/**
+ * `univer_api`: the safe Univer adapter registry (docs/issue/0022 P3b).
+ *
+ * `catalog` and `search` describe what may be called; `invoke` turns one adapter
+ * call into a normal workbook operation, so it lands in version history like any
+ * other edit. It is not an escape hatch to arbitrary JavaScript or a raw
+ * Injector: the catalogue is the whole surface.
+ */
+import {
+  type SheetColumnType,
+  type WorkbookOperationPayload,
+} from '../types.ts'
+import type { LineageContext } from '#contracts'
+
+import { findUniverApi } from '../contract/univer-api-catalog.ts'
+import { mutateWorkbook, readWorkbook, readWorkbookRange, summarize } from '../workbook-manager.ts'
+import { normalizeValueMatrix, parseIndex, parseRange } from '../request-params.ts'
+import {
+  parseCellDeleteShift,
+  parseCount,
+  parseNonEmptyString,
+  sheetRefFromArguments,
+  sheetRefForSnapshot,
+} from './arguments.ts'
+import {
+  dimensionRange,
+  parseApiValues,
+  parseFiniteNumber,
+  parseFreeze,
+  parseHyperlink,
+  parseHyperlinkLabel,
+  parseSort,
+  parseValueRange,
+} from './cells.ts'
+
+
+/** Sheet column types a modelled table may declare. */
+const COLUMN_TYPES: readonly SheetColumnType[] = ['string', 'number', 'boolean', 'date', 'currency']
+
+/** Sheet column types a modelled table may declare. */
+export function parseUniverApiAction(value: unknown): 'catalog' | 'search' | 'invoke' {
+  if (value === 'catalog' || value === 'search' || value === 'invoke') return value
+  throw new Error('action 必须是 catalog、search 或 invoke')
+}
+
+
+
+
+
+export type ApiArguments = Record<string, unknown>
+
+export function asApiArguments(value: unknown): ApiArguments {
+  if (value === undefined || value === null) return {}
+  if (typeof value !== 'object' || Array.isArray(value)) throw new Error('arguments 必须是对象')
+  return value as ApiArguments
+}
+
+/** Execute one cataloged Facade method through the durable DSH adapter. */
+export async function executeUniverApi(args: {
+  workbookId: string
+  api: string
+  arguments: ApiArguments
+  expectedRevision?: number
+  opId?: string
+  lineage?: LineageContext
+}): Promise<unknown> {
+  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: WorkbookOperationPayload
+  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: unknown, label: string): boolean {
+  if (typeof value !== 'boolean') throw new Error(`${label} 必须是 boolean`)
+  return value
+}
+
+export function parseColor(value: unknown, label: string): string {
+  return parseNonEmptyString(value, label)
+}
+
+export function parseHorizontalAlignment(value: unknown): number {
+  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: unknown): number {
+  if (value === 'top') return 1
+  if (value === 'middle') return 2
+  if (value === 'bottom') return 0
+  throw new Error('alignment 必须是 top、middle 或 bottom')
+}
+
+
+
+

package/src/tools/workbook-catalog.ts

@@ -0,0 +1,94 @@
+/**
+ * `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.ts'
+import { storageNameOf } from '#contracts'
+import { normalizeWorkbookId } from '../contract/ids.ts'
+import { now, parseNonEmptyString, workbookIdOf, type ToolArguments } from './arguments.ts'
+import type { WorkbookCatalogResponse } from '#contracts'
+
+export function parseCatalogAction(value: unknown): 'list' | 'create' | 'rename' | 'delete' {
+  if (value === 'list' || value === 'create' || value === 'rename' || value === 'delete') return value
+  throw new Error('action 必须是 list、create、rename 或 delete')
+}
+
+export async function executeWorkbookCatalog(args: ToolArguments): Promise<unknown> {
+  const action = parseCatalogAction(args.action)
+  if (action === 'list') {
+    const summaries = await listWorkbookSummaries()
+    // 响应按 wire 契约标注，字段变化会在编译期被发现。
+    const response: WorkbookCatalogResponse = {
+      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),
+    } as never)
+    return { ok: true, action, workbook: { id: workbookId, name, sheets: summarize((await readWorkbook(workbookId)) as never).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 }
+}