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

package/src/http/trunk.ts

@@ -0,0 +1,322 @@
+/**
+ * The workbook's own routes (docs/issue/0022 P3).
+ *
+ * Snapshot read/write, the incremental `changes` cursor, one bounded range read,
+ * the operation append, proposals and rollback — everything a browser or another
+ * plugin uses to read and write the trunk workbook.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import { DataSheetError } from '../errors.ts'
+import { lineageOfValue } from '../audit.ts'
+import {
+  deleteWorkbook,
+  readWorkbook,
+  readWorkbookIndex,
+  commitWorkbookProposal,
+  rejectWorkbookProposal,
+  rollbackWorkbook,
+  mutateWorkbook,
+} from '../workbook-manager.ts'
+import { parseIndex, parseRange, isOperationType, asOperationPayload, optionalRevision } from '../request-params.ts'
+import { readWorkbookRange, workbookExists } from '../workbook-manager.ts'
+import { usedExtent } from '../contract/snapshots.ts'
+import { parseRevision } from './routes.ts'
+import { standaloneWorkbookHtml } from './standalone.ts'
+import { readJsonBody, requireDataSheetSession, writeOperationError, type WorkbookRoute } from './routes.ts'
+import type { SheetRangeResponse } from '#contracts'
+
+export async function handleTrunkRoute(route: WorkbookRoute, req: IncomingMessage, res: ServerResponse, url: URL): Promise<boolean> {
+  const id = route.id
+
+  if (route.kind === 'view' && req.method === 'GET') {
+    const id = route.id as string
+    const meta = await readWorkbook(id)
+    const title = meta?.name ?? id
+    res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-cache' })
+    res.end(standaloneWorkbookHtml(title))
+    return true
+  }
+
+  if (route.kind === 'snapshot' && (req.method === 'DELETE' || req.method === 'POST' && url.searchParams.get('action') === 'delete')) {
+    let body: Record<string, unknown> = {}
+    try { body = await readJsonBody(req) } catch { /* confirmation is checked below */ }
+    if (body.confirm !== true) {
+      res.writeHead(400, { 'content-type': 'application/json; charset=utf-8' })
+      res.end(JSON.stringify({ ok: false, error: '删除工作簿必须显式传入 confirm: true' }))
+      return true
+    }
+    try {
+      if (!await workbookExists(id)) {
+        res.writeHead(404, { 'content-type': 'application/json; charset=utf-8' })
+        res.end(JSON.stringify({ ok: false, error: `工作簿不存在：${id}` }))
+        return true
+      }
+      await deleteWorkbook(id)
+      res.writeHead(200, { 'content-type': 'application/json; charset=utf-8' })
+      res.end(JSON.stringify({ ok: true, workbookId: id }))
+    } catch (error) {
+      writeOperationError(res, error)
+    }
+    return true
+  }
+
+  if (route.kind === 'range') {
+    const sessionId = requireDataSheetSession(req, res, url)
+    if (sessionId === null) return true
+    if (req.method !== 'GET') { res.writeHead(405); res.end(); return true }
+    const id = route.id as string
+    try {
+      const meta = await readWorkbook(id)
+      if (meta === null) { writeOperationError(res, new DataSheetError('WORKBOOK_NOT_FOUND', '工作簿不存在', 404)); return true }
+      const sheetRef = url.searchParams.get('sheet') ?? ''
+      const rangeParam = url.searchParams.get('range') ?? ''
+      // A bounded, read-only snapshot of one range: this is how another
+      // plugin materializes a Sheet as its own data source (§8.6).
+      // No range asked for means *the sheet*, so the extent is measured rather
+      // than assumed. This used to default to `A1:Z1000` — rows 0–999 and columns
+      // A–Z — which silently handed back a prefix of any larger sheet, and the
+      // `truncated` flag below could not say so because it compared a value with
+      // itself (`values.length - 1 < endRow - startRow` is `n < n`). Data
+      // were being dropped before the loader ever saw them.
+      const requested = rangeParam.trim() === '' ? undefined : parseRange(rangeParam)
+      const extent = usedExtent(meta.snapshot, sheetRef)
+      const range = requested ?? { startRow: 0, startColumn: 0, endRow: extent.endRow, endColumn: extent.endColumn }
+      // this range twice — as a SQL relation (values only) and as the Sheet
+      // Block's read-only preview, which has to draw the range the way the sheet
+      // draws it. Making it opt-in keeps the relation path from paying for a
+      // matrix it never reads.
+      const withStyles = url.searchParams.get('styles') === '1'
+      const result = readWorkbookRange(meta.snapshot, sheetRef, range, withStyles ? { styles: true } : {})
+      const header = result.values[0] ?? []
+      const body = result.values.slice(1)
+      // An empty sheet reads as no columns rather than one unnamed one.
+      const columns = header.every(value => value === null)
+        ? []
+        : header.map((value, index) => typeof value === 'string' && value.trim() !== '' ? value.trim() : `column_${index + 1}`)
+      // 响应按 wire 契约标注，字段变化会在编译期被发现。
+      const payload: SheetRangeResponse = {
+        ok: true,
+        workbookId: id,
+        workbookName: meta.name,
+        revision: meta.revision ?? 0,
+        sheetId: result.sheetId,
+        sheetName: result.sheetName,
+        range: result.range,
+        columns,
+        rows: body,
+        // The style matrix spans the **whole** requested range, header row
+        // included, so it indexes exactly like `result.values` — the preview
+        // pairs `styles[row][column]` with the value it just drew rather than
+        // re-deriving which row is the header.
+        ...(result.styles === undefined ? {} : { styles: result.styles }),
+        // Only a narrow request can be short of the sheet: that is the single
+        // case where more data exists than was returned, and saying so is what
+        // lets the reader ask for the rest.
+        truncated: requested !== undefined && (extent.endRow > requested.endRow || extent.endColumn > requested.endColumn),
+      }
+      res.writeHead(200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-cache' })
+      res.end(JSON.stringify(payload))
+    } catch (error) {
+      writeOperationError(res, error instanceof DataSheetError ? error : new DataSheetError('VALIDATION_ERROR', error instanceof Error ? error.message : String(error), 400))
+    }
+    return true
+  }
+
+  if (route.kind === 'proposals' && req.method === 'GET') {
+    const index = await readWorkbookIndex(id)
+    const meta = index === null ? await readWorkbook(id) : null
+    if (index === null && meta === null) {
+      res.writeHead(404)
+      res.end()
+      return true
+    }
+    const proposals = (index?.proposals ?? meta?.proposals ?? []).filter(proposal => proposal.status === 'pending').map(proposal => ({
+      id: proposal.id,
+      summary: proposal.summary,
+      baseRevision: proposal.baseRevision,
+      createdAt: proposal.createdAt,
+      changes: proposal.changes,
+    }))
+    res.writeHead(200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-cache' })
+    res.end(JSON.stringify({ ok: true, workbookId: id, revision: index?.revision ?? meta?.revision ?? 0, proposals }))
+    return true
+  }
+
+  if (route.kind === 'proposal-action' && req.method === 'POST') {
+    let body: Record<string, unknown> = {}
+    try { body = await readJsonBody(req) } catch { /* reject does not need a body */ }
+    try {
+      const proposalId = route.proposalId
+      if (route.action === 'commit') {
+        const result = await commitWorkbookProposal({ workbookId: id, proposalId, actor: 'user', expectedRevision: optionalRevision(body.baseRevision) })
+        res.writeHead(200, { 'content-type': 'application/json; charset=utf-8' })
+        res.end(JSON.stringify({ ok: true, revision: result.meta.revision ?? 0, operation: result.operation }))
+      } else {
+        const meta = await rejectWorkbookProposal(id, proposalId)
+        res.writeHead(200, { 'content-type': 'application/json; charset=utf-8' })
+        res.end(JSON.stringify({ ok: true, revision: meta.revision ?? 0, proposalId }))
+      }
+    } catch (error) {
+      writeOperationError(res, error)
+    }
+    return true
+  }
+
+  if (route.kind === 'rollback' && req.method === 'POST') {
+    let body: Record<string, unknown>
+    try { body = await readJsonBody(req) } catch { writeOperationError(res, new DataSheetError('VALIDATION_ERROR', 'bad json')); return true }
+    try {
+      const result = await rollbackWorkbook({
+        workbookId: id,
+        targetRevision: parseIndex(body.targetRevision, 'targetRevision'),
+        expectedRevision: optionalRevision(body.baseRevision),
+        actor: 'user',
+        // The browser names the Version (`恢复到 V3`) because only it knows
+        // the display number; the manager falls back to the revision.
+        ...(typeof body.summary === 'string' && body.summary.trim() !== '' ? { summary: body.summary.trim() } : {}),
+        lineage: lineageOfValue(body.lineage),
+      })
+      res.writeHead(200, { 'content-type': 'application/json; charset=utf-8' })
+      res.end(JSON.stringify({
+        ok: true,
+        revision: result.meta.revision ?? 0,
+        operation: result.operation,
+      }))
+    } catch (error) {
+      writeOperationError(res, error)
+    }
+    return true
+  }
+
+  if (route.kind === 'changes' && req.method === 'GET') {
+    const meta = await readWorkbook(id)
+    if (meta === null) {
+      res.writeHead(404)
+      res.end()
+      return true
+    }
+    const after = parseRevision(url.searchParams.get('after'))
+    const operations = (meta.operations ?? []).filter(operation => operation.revision > after)
+    const currentRevision = meta.revision ?? 0
+    const oldestRevision = operations[0]?.revision ?? currentRevision
+    const requiresSnapshot = after < oldestRevision - 1
+    res.writeHead(200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-cache' })
+    res.end(JSON.stringify({
+      ok: true,
+      workbookId: id,
+      revision: currentRevision,
+      operations,
+      requiresSnapshot,
+      snapshot: requiresSnapshot ? meta?.snapshot : undefined,
+    }))
+    return true
+  }
+
+  if (route.kind === 'snapshot' && req.method === 'GET') {
+    const meta = await readWorkbook(id)
+    if (meta === null) {
+      res.writeHead(404)
+      res.end()
+      return true
+    }
+    res.writeHead(200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-cache' })
+    res.end(JSON.stringify({
+      ok: true,
+      workbookId: meta.id,
+      revision: meta.revision ?? 0,
+      updatedAt: meta.updatedAt,
+      snapshot: meta.snapshot,
+    }))
+    return true
+  }
+
+  if (route.kind === 'operation' && req.method === 'POST') {
+    let body: Record<string, unknown>
+    try {
+      body = await readJsonBody(req)
+    } catch {
+      writeOperationError(res, new DataSheetError('VALIDATION_ERROR', 'bad json'))
+      return true
+    }
+    const type = body.type
+    if (!isOperationType(type)) {
+      writeOperationError(res, new DataSheetError('VALIDATION_ERROR', 'invalid operation type'))
+      return true
+    }
+    try {
+      const result = await mutateWorkbook({
+        workbookId: id,
+        // Browser HTTP routes are always user-originated. Agent writes use
+        // the tool host directly and cannot spoof this audit field.
+        actor: 'user',
+        type,
+        payload: asOperationPayload(body.payload),
+        expectedRevision: optionalRevision(body.baseRevision),
+        opId: typeof body.opId === 'string' ? body.opId : undefined,
+        versionId: typeof body.versionId === 'string' ? body.versionId : undefined,
+        // `temporary` remains accepted for browser bundles that have not
+        // been upgraded yet; the mutation authority normalizes it to
+        // the clearer durable `open` status.
+        versionStatus: body.versionStatus === 'open' || body.versionStatus === 'temporary' || body.versionStatus === 'final' ? body.versionStatus : undefined,
+        // Browser routes are always user-originated, and a user edit
+        // session is an auto checkpoint (PRD v3 §4).
+        versionKind: 'auto',
+        lineage: lineageOfValue(body.lineage),
+      })
+      res.writeHead(200, { 'content-type': 'application/json; charset=utf-8' })
+      res.end(JSON.stringify({
+        ok: true,
+        revision: result.meta.revision ?? 0,
+        operation: result.operation,
+        ...(result.rebasedOperations === undefined ? {} : { rebasedOperations: result.rebasedOperations }),
+        ...(result.transformed === undefined ? {} : { transformed: result.transformed }),
+      }))
+    } catch (error) {
+      writeOperationError(res, error)
+    }
+    return true
+  }
+
+  if (route.kind === 'snapshot' && req.method === 'POST') {
+    let body: Record<string, unknown>
+    try {
+      body = await readJsonBody(req)
+    } catch {
+      writeOperationError(res, new DataSheetError('VALIDATION_ERROR', 'bad json'))
+      return true
+    }
+    if (!Object.prototype.hasOwnProperty.call(body, 'snapshot')) {
+      writeOperationError(res, new DataSheetError('VALIDATION_ERROR', 'snapshot is required'))
+      return true
+    }
+    const snapshot = body.snapshot
+    try {
+      const versionSummary = typeof body.versionSummary === 'string' && body.versionSummary.trim() !== '' ? body.versionSummary.trim() : undefined
+      const versionId = typeof body.versionId === 'string' && body.versionId.trim() !== '' ? body.versionId.trim() : undefined
+      const requestedVersionStatus = body.versionStatus === 'open' || body.versionStatus === 'final' ? body.versionStatus : undefined
+      const result = await mutateWorkbook({
+        workbookId: id,
+        actor: 'user',
+        type: 'snapshot_replace',
+        payload: { snapshot },
+        expectedRevision: optionalRevision(body.baseRevision),
+        opId: typeof body.opId === 'string' ? body.opId : undefined,
+        lineage: lineageOfValue(body.lineage),
+        ...(versionId === undefined ? {} : { versionId }),
+        // A named checkpoint is an explicit, self-contained Version even
+        // when the content did not change (PRD §8); a plain snapshot flush
+        // is one Step of the editing session instead (PRD v3.1 §4).
+        versionKind: versionSummary === undefined ? 'auto' as const : 'named' as const,
+        ...(requestedVersionStatus === undefined ? {} : { versionStatus: requestedVersionStatus }),
+        ...(versionSummary === undefined ? {} : { versionSummary, versionStatus: requestedVersionStatus ?? 'final' as const }),
+      })
+      res.writeHead(200, { 'content-type': 'application/json; charset=utf-8' })
+      res.end(JSON.stringify({ ok: true, revision: result.meta.revision ?? 0, operation: result.operation }))
+    } catch (error) {
+      writeOperationError(res, error)
+    }
+    return true
+  }
+
+  return false
+}

package/src/http/worktree.ts

@@ -0,0 +1,119 @@
+/**
+ * Isolated review worktrees over HTTP (docs/issue/0022 P3).
+ *
+ * Draft copies are session-scoped, which is why every handler here resolves the
+ * session first and checks the owner before touching a worktree.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import { DataSheetError } from '../errors.ts'
+import { diffReachedLimit, diffWorkbookSnapshots } from '../version/diff.ts'
+import {
+  createWorkbookWorktree,
+  listWorkbookWorktrees,
+  mergeWorkbookWorktree,
+  mutateWorkbookWorktree,
+  readWorkbookAtRevision,
+  readWorkbookWorktree,
+  setWorkbookWorktreeStatus,
+} from '../workbook-manager.ts'
+import { isOperationType, asOperationPayload, optionalRevision } from '../request-params.ts'
+import { readJsonBody, requireDataSheetSession, writeOperationError, type WorkbookRoute } from './routes.ts'
+
+export async function handleWorktreeRoute(route: WorkbookRoute, req: IncomingMessage, res: ServerResponse, url: URL): Promise<boolean> {
+  const id = route.id
+
+  if (route.kind === 'worktrees') {
+    const sessionId = requireDataSheetSession(req, res, url)
+    if (sessionId === null) return true
+    if (req.method === 'GET') {
+      const worktrees = await listWorkbookWorktrees(id, sessionId)
+      res.writeHead(200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-cache' })
+      res.end(JSON.stringify({ ok: true, workbookId: id, worktrees }))
+      return true
+    }
+    if (req.method === 'POST') {
+      let body: Record<string, unknown>
+      try { body = await readJsonBody(req) } catch (error) { writeOperationError(res, error); return true }
+      try {
+        const worktree = await createWorkbookWorktree({ workbookId: id, ownerSessionId: sessionId, name: typeof body.name === 'string' ? body.name : undefined, worktreeId: typeof body.worktreeId === 'string' ? body.worktreeId : undefined })
+        res.writeHead(201, { 'content-type': 'application/json; charset=utf-8' })
+        res.end(JSON.stringify({ ok: true, workbookId: id, worktree }))
+      } catch (error) { writeOperationError(res, error) }
+      return true
+    }
+    res.writeHead(405)
+    res.end()
+    return true
+  }
+
+  if (route.kind === 'worktree' && req.method === 'GET') {
+    const sessionId = requireDataSheetSession(req, res, url)
+    if (sessionId === null) return true
+    const worktree = await readWorkbookWorktree(id, route.worktreeId as string)
+    if (worktree === null) { writeOperationError(res, new DataSheetError('WORKTREE_NOT_FOUND', 'worktree 不存在', 404)); return true }
+    if (worktree.ownerSessionId !== sessionId) { writeOperationError(res, new DataSheetError('SESSION_SCOPE_DENIED', '当前 session 无权访问该 worktree', 403)); return true }
+    res.writeHead(200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-cache' })
+    res.end(JSON.stringify({ ok: true, workbookId: id, worktree }))
+    return true
+  }
+
+  if (route.kind === 'worktree-operations' && req.method === 'POST') {
+    const sessionId = requireDataSheetSession(req, res, url)
+    if (sessionId === null) return true
+    let body: Record<string, unknown>
+    try { body = await readJsonBody(req) } catch (error) { writeOperationError(res, error); return true }
+    if (!isOperationType(body.type)) { writeOperationError(res, new DataSheetError('VALIDATION_ERROR', 'invalid operation type')); return true }
+    try {
+      const result = await mutateWorkbookWorktree({
+        workbookId: id,
+        worktreeId: route.worktreeId as string,
+        ownerSessionId: sessionId,
+        actor: 'user',
+        type: body.type,
+        payload: asOperationPayload(body.payload),
+        expectedRevision: optionalRevision(body.baseRevision),
+        opId: typeof body.opId === 'string' ? body.opId : undefined,
+      })
+      res.writeHead(200, { 'content-type': 'application/json; charset=utf-8' })
+      res.end(JSON.stringify({ ok: true, workbookId: id, worktree: result.worktree, revision: result.worktree.revision, operation: result.operation }))
+    } catch (error) { writeOperationError(res, error) }
+    return true
+  }
+
+  if (route.kind === 'worktree-action' && req.method === 'POST') {
+    const sessionId = requireDataSheetSession(req, res, url)
+    if (sessionId === null) return true
+    let body: Record<string, unknown> = {}
+    try { body = await readJsonBody(req) } catch { /* empty action body is valid */ }
+    const worktreeId = route.worktreeId as string
+    const action = route.action as 'ready' | 'reopen' | 'merge' | 'discard'
+    try {
+      if (action === 'merge') {
+        const result = await mergeWorkbookWorktree({ workbookId: id, worktreeId, ownerSessionId: sessionId, actor: 'user', expectedRevision: optionalRevision(body.baseRevision) })
+        res.writeHead(200, { 'content-type': 'application/json; charset=utf-8' })
+        res.end(JSON.stringify({ ok: true, workbookId: id, worktree: result.worktree, revision: result.mutation.meta.revision ?? 0, operation: result.mutation.operation }))
+      } else {
+        const worktree = await setWorkbookWorktreeStatus({ workbookId: id, worktreeId, ownerSessionId: sessionId, status: action === 'discard' ? 'discarded' : action })
+        res.writeHead(200, { 'content-type': 'application/json; charset=utf-8' })
+        res.end(JSON.stringify({ ok: true, workbookId: id, worktree }))
+      }
+    } catch (error) { writeOperationError(res, error) }
+    return true
+  }
+
+  if (route.kind === 'worktree-diff' && req.method === 'GET') {
+    const sessionId = requireDataSheetSession(req, res, url)
+    if (sessionId === null) return true
+    const worktree = await readWorkbookWorktree(id, route.worktreeId as string)
+    if (worktree === null) { writeOperationError(res, new DataSheetError('WORKTREE_NOT_FOUND', 'worktree 不存在', 404)); return true }
+    if (worktree.ownerSessionId !== sessionId) { writeOperationError(res, new DataSheetError('SESSION_SCOPE_DENIED', '当前 session 无权访问该 worktree', 403)); return true }
+    const base = await readWorkbookAtRevision(id, worktree.baseRevision)
+    if (base === null) { writeOperationError(res, new DataSheetError('REVISION_UNAVAILABLE', 'worktree 基线 revision 已被压缩或无法重放', 409)); return true }
+    res.writeHead(200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-cache' })
+    const changes = diffWorkbookSnapshots(base.snapshot, worktree.snapshot)
+    res.end(JSON.stringify({ ok: true, workbookId: id, worktreeId: worktree.id, from: worktree.baseRevision, to: worktree.revision, changes, truncated: diffReachedLimit(changes) }))
+    return true
+  }
+
+  return false
+}

package/src/index.ts

@@ -0,0 +1,165 @@
+/**
+ * Node half of dsh-data-table: the plugin body.
+ *
+ * It does two things: assemble the HTTP routes (the asset routes plus one
+ * prefix route whose sub-paths are matched in `http/routes.ts`) and register the
+ * Agent tool surface. Everything it hands to either transport lives in a module
+ * beside it, so this file is the list of what the plugin offers — not how any of
+ * it works (docs/issue/0022 P3b).
+ * @module dsh-data-table
+ */
+import type { Context } from '@deepseek-ai/cordis'
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import type {} from '@deepseek-ai/dsh-tools'
+import type {} from '@deepseek-ai/dsh-client-connection'
+import { setLineageScope } from './audit.ts'
+import { UNIVER_API_CATALOG, UNIVER_API_VERSION } from './contract/univer-api-catalog.ts'
+import { listWorkbookSummaries } from './workbook-manager.ts'
+import { assetRoutes } from './http/assets-routes.ts'
+import { handleCollaborationRoute } from './http/collaboration.ts'
+import { handleHistoryRoute } from './http/history.ts'
+import { handleTrunkRoute } from './http/trunk.ts'
+import { handleWorktreeRoute } from './http/worktree.ts'
+import {
+  guardDataSheetRequest,
+  matchWorkbookRoute,
+  readJsonBody,
+  registerConnectionRoutes,
+  writeOperationError,
+  type LegacyRoute,
+} from './http/routes.ts'
+import { projectFor, runForProject, sessionIdOf } from './http/project-scope.ts'
+import { projectFileRoutes } from './http/project-files.ts'
+import { registerWorkbookTools } from './tools/index.ts'
+import { executeWorkbookCatalog } from './tools/workbook-catalog.ts'
+
+export const name = 'dsh-data-table'
+// `sessions` is read to turn a Session id into that Session's project directory,
+// in both transports: a browser request names its id in a header, and a tool call
+// names the same id through its Agent. Cordis throws on undeclared service access,
+// and the throw lands inside a request handler whose exception the web server
+// reports as a bodyless 400 — so a missing declaration looked exactly like a
+// malformed request (2026-09-25).
+//
+// `sandboxPolicy` is deliberately *not* declared: it is not reachable from a plugin context in
+// the web deployment (`cannot get property "sandboxPolicy" without inject` in
+// `~/.dsh/logs/dsh-web-3080.log`, 77 times), so reading it as a fallback turned every workbook
+// list into a 400. A Session's own header is the answer, and a caller that names no Session
+// keeps the pre-project store instead of a project guessed from a policy.
+export const inject = ['tools', 'connection', 'sessions'] as const
+
+/**
+ * Plugin body: chunk route + workbook/sheet tools.
+ * @param ctx - registrant context.
+ */
+export function apply(ctx: Context): void {
+  setLineageScope(ctx)
+  const routes: LegacyRoute[] = [...assetRoutes(), {
+    // A prefix route: everything under `/data-sheet/workbook/` is one entry
+    // point, and `matchWorkbookRoute` decides which domain handles it.
+    kind: 'prefix',
+    // Workbook projection and operation endpoints.
+    // Paths:
+    //   GET  /data-sheet/workbook/<id>.json
+    //   POST /data-sheet/workbook/<id>.json              (legacy snapshot checkpoint)
+    //   GET  /data-sheet/workbook/<id>/changes?after=N
+    //   GET  /data-sheet/workbook/<id>/collaboration     (live SSE session)
+    //   GET  /data-sheet/workbook/<id>/history[?revision=N]
+    //   POST /data-sheet/workbook/<id>/operations        (fine-grained mutation)
+    // NOTE: prefix route paths must NOT end with a trailing slash — the host
+    // matcher appends its own "/" (startsWith(`${prefix}/`)), so a trailing
+    // slash makes subpaths unmatchable.
+    path: '/data-sheet/workbook',
+    handler: async (req, res) => {
+      if (!guardDataSheetRequest(req, res)) return
+      // Writes must be JSON: a form-encoded body would be parsed as an empty
+      // object and silently drop the payload.
+      if (req.method !== 'GET' && req.method !== 'HEAD') {
+        const contentType = String(req.headers['content-type'] ?? '').toLowerCase()
+        if (!contentType.startsWith('application/json')) {
+          res.writeHead(415, { 'content-type': 'application/json; charset=utf-8' })
+          res.end(JSON.stringify({ ok: false, code: 'VALIDATION_ERROR', error: '写请求必须使用 application/json' }))
+          return
+        }
+      }
+      const url = new URL(req.url ?? '/', 'http://x')
+      // `decodeURIComponent` throws on a malformed escape (`/x/%E0%A4%A`), and
+      // that would escape the handler as an unhandled URIError. A path we cannot
+      // decode is simply not one of our routes.
+      let pathname: string
+      try {
+        pathname = decodeURIComponent(url.pathname)
+      } catch {
+        res.writeHead(400)
+        res.end()
+        return
+      }
+      const route = matchWorkbookRoute(pathname)
+      if (route === null) {
+        res.writeHead(404)
+        res.end()
+        return
+      }
+      // Worktrees are session-scoped draft copies and are handled first, so a
+      // draft can never be mistaken for a normal workbook mutation. The live
+      // stream is next because it holds the response open.
+      // Every workbook path resolves inside the requesting Session's project, so
+      // the store root it writes to is that project's `storages/data-table`.
+      const project = projectFor(ctx, sessionIdOf(req.headers, url))
+      const dispatched = await runForProject(project, async () => {
+        if (await handleWorktreeRoute(route, req, res, url)) return true
+        if (await handleCollaborationRoute(route, req, res, url)) return true
+        if (await handleHistoryRoute(route, req, res, url)) return true
+        if (await handleTrunkRoute(route, req, res, url)) return true
+        return false
+      })
+      if (dispatched) return
+      res.writeHead(405)
+      res.end()
+    },
+  }, {
+    kind: 'exact',
+    path: '/data-sheet/workbooks.json',
+    handler: async (_req, res) => {
+      if (!guardDataSheetRequest(_req, res)) return
+      const project = projectFor(ctx, sessionIdOf(_req.headers, new URL(_req.url ?? '/', 'http://x')))
+      // POST routes to the Agent's catalog implementation so the browser and the
+      // model share one create/rename/delete path.
+      if (_req.method === 'POST') {
+        let body: Record<string, unknown>
+        try { body = await readJsonBody(_req) } catch (error) { writeOperationError(res, error); return }
+        try {
+          const result = await runForProject(project, async () => executeWorkbookCatalog({ ...body, action: body.action }))
+          res.writeHead(body.action === 'create' ? 201 : 200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-cache' })
+          res.end(JSON.stringify(result))
+        } catch (error) {
+          writeOperationError(res, error)
+        }
+        return
+      }
+      if (_req.method !== 'GET' && _req.method !== 'HEAD') {
+        res.writeHead(405, { 'content-type': 'application/json; charset=utf-8' })
+        res.end(JSON.stringify({ ok: false, error: 'method not allowed' }))
+        return
+      }
+      const workbooks = await runForProject(project, async () => listWorkbookSummaries())
+      res.writeHead(200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-cache' })
+      res.end(JSON.stringify({ ok: true, workbooks }))
+    },
+  }, {
+    // Agent-facing metadata endpoint. It is deliberately separate from the
+    // mutation routes so a client can discover the safe Univer surface without
+    // receiving a browser-only Injector or executing arbitrary JavaScript.
+    kind: 'exact',
+    path: '/data-sheet/univer-api.json',
+    handler: async (_req, res) => {
+      if (!guardDataSheetRequest(_req, res)) return
+      res.writeHead(200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-cache' })
+      res.end(JSON.stringify({ ok: true, version: UNIVER_API_VERSION, catalog: UNIVER_API_CATALOG }))
+    },
+  }, ...projectFileRoutes(ctx)]
+
+  registerConnectionRoutes(ctx, routes, '/data-sheet')
+  registerWorkbookTools(ctx)
+}
+

package/src/invariant.ts

@@ -0,0 +1,17 @@
+/**
+ * Package-owned invariant companion for dsh-data-table.
+ *
+ * Runtime invariant: the browser half can only render a sheet that the host
+ * tool admitted, because the renderer parses the durable tool-call arguments
+ * through {@link isSheetData} — the same shape the tool validated. A renderer
+ * reaching an unvalidated sheet is a build-level type violation, not a runtime
+ * state, so the companion registers the manifest name only.
+ * @module dsh-data-table/invariant
+ */
+
+export const manifest = 'dsh-data-table'
+
+export const invariant = {
+  manifest,
+  reason: 'renderer input is the host-validated tool-call arguments (isSheetData); no runtime event/data relation to check',
+}