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

package/lib/types/http/trunk.js

@@ -0,0 +1,322 @@
+import { DataSheetError } from "../errors.js";
+import { lineageOfValue } from "../audit.js";
+import { deleteWorkbook, readWorkbook, readWorkbookIndex, commitWorkbookProposal, rejectWorkbookProposal, rollbackWorkbook, mutateWorkbook, } from "../workbook-manager.js";
+import { parseIndex, parseRange, isOperationType, asOperationPayload, optionalRevision } from "../request-params.js";
+import { readWorkbookRange, workbookExists } from "../workbook-manager.js";
+import { usedExtent } from "../contract/snapshots.js";
+import { parseRevision } from "./routes.js";
+import { standaloneWorkbookHtml } from "./standalone.js";
+import { readJsonBody, requireDataSheetSession, writeOperationError } from "./routes.js";
+export async function handleTrunkRoute(route, req, res, url) {
+    const id = route.id;
+    if (route.kind === 'view' && req.method === 'GET') {
+        const id = route.id;
+        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 = {};
+        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;
+        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 = {
+                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 = {};
+        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;
+        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;
+        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;
+        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' : 'named',
+                ...(requestedVersionStatus === undefined ? {} : { versionStatus: requestedVersionStatus }),
+                ...(versionSummary === undefined ? {} : { versionSummary, versionStatus: requestedVersionStatus ?? 'final' }),
+            });
+            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/lib/types/http/worktree.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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 { type WorkbookRoute } from './routes.ts';
+export declare function handleWorktreeRoute(route: WorkbookRoute, req: IncomingMessage, res: ServerResponse, url: URL): Promise<boolean>;

package/lib/types/http/worktree.js

@@ -0,0 +1,145 @@
+import { DataSheetError } from "../errors.js";
+import { diffReachedLimit, diffWorkbookSnapshots } from "../version/diff.js";
+import { createWorkbookWorktree, listWorkbookWorktrees, mergeWorkbookWorktree, mutateWorkbookWorktree, readWorkbookAtRevision, readWorkbookWorktree, setWorkbookWorktreeStatus, } from "../workbook-manager.js";
+import { isOperationType, asOperationPayload, optionalRevision } from "../request-params.js";
+import { readJsonBody, requireDataSheetSession, writeOperationError } from "./routes.js";
+export async function handleWorktreeRoute(route, req, res, url) {
+    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;
+            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);
+        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;
+        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,
+                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 = {};
+        try {
+            body = await readJsonBody(req);
+        }
+        catch { /* empty action body is valid */ }
+        const worktreeId = route.worktreeId;
+        const action = route.action;
+        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);
+        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/lib/types/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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';
+export declare const name = "dsh-data-table";
+export declare const inject: readonly ["tools", "connection", "sessions"];
+/**
+ * Plugin body: chunk route + workbook/sheet tools.
+ * @param ctx - registrant context.
+ */
+export declare function apply(ctx: Context): void;

package/lib/types/index.js

@@ -0,0 +1,156 @@
+import { setLineageScope } from "./audit.js";
+import { UNIVER_API_CATALOG, UNIVER_API_VERSION } from "./contract/univer-api-catalog.js";
+import { listWorkbookSummaries } from "./workbook-manager.js";
+import { assetRoutes } from "./http/assets-routes.js";
+import { handleCollaborationRoute } from "./http/collaboration.js";
+import { handleHistoryRoute } from "./http/history.js";
+import { handleTrunkRoute } from "./http/trunk.js";
+import { handleWorktreeRoute } from "./http/worktree.js";
+import { guardDataSheetRequest, matchWorkbookRoute, readJsonBody, registerConnectionRoutes, writeOperationError, } from "./http/routes.js";
+import { projectFor, runForProject, sessionIdOf } from "./http/project-scope.js";
+import { projectFileRoutes } from "./http/project-files.js";
+import { registerWorkbookTools } from "./tools/index.js";
+import { executeWorkbookCatalog } from "./tools/workbook-catalog.js";
+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'];
+/**
+ * Plugin body: chunk route + workbook/sheet tools.
+ * @param ctx - registrant context.
+ */
+export function apply(ctx) {
+    setLineageScope(ctx);
+    const routes = [...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;
+                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;
+                    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/lib/types/invariant.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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 declare const manifest = "dsh-data-table";
+export declare const invariant: {
+    manifest: string;
+    reason: string;
+};