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

package/lib/contract-wire.d.ts

@@ -0,0 +1,147 @@
+/**
+ * 跨插件 HTTP 线协议（wire）。
+ *
+ * ## 为什么单独一层
+ *
+ * 契约库里原本放的是「每个插件各自都要用的通用件」——版本模型、磁盘布局、结果信封。
+ * HTTP 消费方需要与 table 的目录项、范围响应和单元格样式三个形状保持一致。
+ *
+ * 手抄的代价不是丑，是**漂移时不报错**：
+ *
+ * - 消费方写的是防御式解析（`typeof style.ff === 'string'`）。生产者把 `ff` 改名，
+ *   消费方不会崩，只是**静默不再画字体**。
+ * - 目录响应同理：字段改名后 `Array.isArray(body.workbooks)` 仍然为真，只是每一项
+ *   都过不了字段检查，于是**静默显示空列表**。
+ *
+ * 所以这里把形状定义一次，并且**同时提供类型与校验器**：生产者用它标注返回值（改名 →
+ * 编译不过），消费方用它做校验（改名 → 运行时明确报错，而不是降级）。
+ *
+ * ## 目前的范围
+ *
+ * Table 提供两条只读工作簿查询路由，供集成调用方读取：
+ *
+ * ```
+ * GET /data-sheet/workbooks.json
+ * GET /data-sheet/workbook/{workbookId}/range?sheet=&session=&range=&styles=
+ * ```
+ *
+ * 两条都由 table 生产。
+ *
+ * ## 不在这一层的东西
+ *
+ * 统一信封（`./envelope` 的 `Envelope<T,E>`）**没有**覆盖这两条路由，因为它的载荷放在
+ * `data` 下，而 table 的响应把载荷放在顶层。把 table 迁到信封等于重写它每一条响应的形状
+ * 和它自己的浏览器客户端（`workbookApi.ts`、独立工作簿页），是独立工程。
+ * `spec/contracts/envelope.json` 里的「尚未遵守」指的正是这件事，这里不假装它已解决。
+ */
+/** 单元格格式。字段名是 Univer 的短码，与 table 的存储格式一致。 */
+export interface SheetCellStyle {
+    /** 字体族 */
+    ff?: string;
+    /** 字号（磅） */
+    fs?: number;
+    /** 加粗 */
+    bl?: boolean;
+    /** 斜体 */
+    it?: boolean;
+    /** 下划线 */
+    ul?: boolean;
+    /** 删除线 */
+    st?: boolean;
+    /** 背景色，`#rrggbb` */
+    bg?: string;
+    /** 前景色，`#rrggbb` */
+    cl?: string;
+    /** 水平对齐 */
+    ht?: number;
+    /** 垂直对齐 */
+    vt?: number;
+    /** 文字旋转 */
+    tr?: number;
+    /** 数字格式 */
+    n?: string;
+}
+/** 一个 0-based、两端 inclusive 的矩形范围。 */
+export interface SheetRangeBounds {
+    startRow: number;
+    startColumn: number;
+    endRow: number;
+    endColumn: number;
+}
+/** `GET /data-sheet/workbook/{id}/range` 的 200 响应体。 */
+export interface SheetRangeResponse {
+    ok: true;
+    workbookId: string;
+    workbookName: string;
+    /** 读取时的主干修订号；消费方可用来判断是否落后。 */
+    revision: number;
+    sheetId: string;
+    sheetName: string;
+    /** 实际返回的范围。请求未指定时是这张表的已用范围。 */
+    range: SheetRangeBounds;
+    /** 表头行；空表返回空数组而不是一个无名列。 */
+    columns: string[];
+    /** 数据行（不含表头）。 */
+    rows: unknown[][];
+    /**
+     * 覆盖**整个** `range`（含表头行）的格式矩阵，下标与 `rows` 对齐（`rows[0]` 对应
+     * `range.startRow + 1`）。只有请求带 `styles=1` 时才出现。
+     */
+    styles?: Array<Array<SheetCellStyle | null>>;
+    /** 请求的范围窄于已用范围时为 `true`，消费方据此继续取剩余部分。 */
+    truncated: boolean;
+}
+/** 目录里一张表的结构摘要。生产者可能带更多字段，消费方只应依赖这些。 */
+export interface WorkbookSheetSchema {
+    /** 列定义；对消费方是不透明的，只保证是数组。 */
+    columns?: unknown[];
+    /** 数据行数，不含表头行。 */
+    rowCount?: number;
+}
+/** 目录里的一张表。 */
+export interface WorkbookCatalogSheet {
+    id: string;
+    name: string;
+    schema?: WorkbookSheetSchema;
+}
+/** 目录里的一个工作簿。 */
+export interface WorkbookCatalogEntry {
+    id: string;
+    name: string;
+    /** 主干修订号；消费方可用作乐观并发基线。 */
+    revision: number;
+    /**
+     * 表数量，等于 `sheets.length`。生产者顺手给的冗余字段，消费方不必依赖它。
+     * 保留在契约里是因为它**确实在线上**，不写就等于契约漏了一半。
+     */
+    sheetCount: number;
+    /** 最后一次写入时间（ISO 8601）。 */
+    updatedAt: string;
+    sheets: WorkbookCatalogSheet[];
+}
+/** `GET /data-sheet/workbooks.json` 的 200 响应体。 */
+export interface WorkbookCatalogResponse {
+    ok: true;
+    workbooks: WorkbookCatalogEntry[];
+}
+/**
+ * table 的错误响应体。
+ *
+ * `code` 只在生产者能给出稳定错误码时出现（例如 `REVISION_CONFLICT`、
+ * `VALIDATION_ERROR`）；`error` 是给人看的一句话，消费方**不要**用它做判断。
+ * 冲突响应还会额外带 `expectedRevision` / `revision` / `conflict`。
+ */
+export interface WireErrorBody {
+    ok: false;
+    code?: string;
+    error: string;
+    expectedRevision?: number;
+    revision?: number;
+    conflict?: unknown;
+}
+/** `{ ok: false, error: string }`，忽略额外字段。 */
+export declare function isWireErrorBody(value: unknown): value is WireErrorBody;
+/** 严格校验一个目录响应：任何一项不合格就整体拒绝，而不是悄悄过滤掉。 */
+export declare function isWorkbookCatalogResponse(value: unknown): value is WorkbookCatalogResponse;
+/** 严格校验一个范围响应。 */
+export declare function isSheetRangeResponse(value: unknown): value is SheetRangeResponse;

package/lib/contract-wire.js

@@ -0,0 +1,99 @@
+/**
+ * 跨插件 HTTP 线协议（wire）。
+ *
+ * ## 为什么单独一层
+ *
+ * 契约库里原本放的是「每个插件各自都要用的通用件」——版本模型、磁盘布局、结果信封。
+ * HTTP 消费方需要与 table 的目录项、范围响应和单元格样式三个形状保持一致。
+ *
+ * 手抄的代价不是丑，是**漂移时不报错**：
+ *
+ * - 消费方写的是防御式解析（`typeof style.ff === 'string'`）。生产者把 `ff` 改名，
+ *   消费方不会崩，只是**静默不再画字体**。
+ * - 目录响应同理：字段改名后 `Array.isArray(body.workbooks)` 仍然为真，只是每一项
+ *   都过不了字段检查，于是**静默显示空列表**。
+ *
+ * 所以这里把形状定义一次，并且**同时提供类型与校验器**：生产者用它标注返回值（改名 →
+ * 编译不过），消费方用它做校验（改名 → 运行时明确报错，而不是降级）。
+ *
+ * ## 目前的范围
+ *
+ * Table 提供两条只读工作簿查询路由，供集成调用方读取：
+ *
+ * ```
+ * GET /data-sheet/workbooks.json
+ * GET /data-sheet/workbook/{workbookId}/range?sheet=&session=&range=&styles=
+ * ```
+ *
+ * 两条都由 table 生产。
+ *
+ * ## 不在这一层的东西
+ *
+ * 统一信封（`./envelope` 的 `Envelope<T,E>`）**没有**覆盖这两条路由，因为它的载荷放在
+ * `data` 下，而 table 的响应把载荷放在顶层。把 table 迁到信封等于重写它每一条响应的形状
+ * 和它自己的浏览器客户端（`workbookApi.ts`、独立工作簿页），是独立工程。
+ * `spec/contracts/envelope.json` 里的「尚未遵守」指的正是这件事，这里不假装它已解决。
+ */
+/** 是否为「不是对象」以外的任意值——所有校验器的第一道门。 */
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** `{ ok: false, error: string }`，忽略额外字段。 */
+export function isWireErrorBody(value) {
+    return isObject(value) && value.ok === false && typeof value.error === 'string';
+}
+/** 严格校验一个目录响应：任何一项不合格就整体拒绝，而不是悄悄过滤掉。 */
+export function isWorkbookCatalogResponse(value) {
+    if (!isObject(value) || value.ok !== true || !Array.isArray(value.workbooks))
+        return false;
+    return value.workbooks.every(entry => {
+        if (!isObject(entry))
+            return false;
+        if (typeof entry.id !== 'string' || typeof entry.name !== 'string')
+            return false;
+        if (typeof entry.revision !== 'number' || typeof entry.sheetCount !== 'number')
+            return false;
+        if (typeof entry.updatedAt !== 'string' || !Array.isArray(entry.sheets))
+            return false;
+        return entry.sheets.every(sheet => {
+            if (!isObject(sheet))
+                return false;
+            if (typeof sheet.id !== 'string' || typeof sheet.name !== 'string')
+                return false;
+            if (sheet.schema === undefined)
+                return true;
+            const schema = sheet.schema;
+            if (!isObject(schema))
+                return false;
+            if (schema.columns !== undefined && !Array.isArray(schema.columns))
+                return false;
+            return schema.rowCount === undefined || typeof schema.rowCount === 'number';
+        });
+    });
+}
+/** 严格校验一个范围响应。 */
+export function isSheetRangeResponse(value) {
+    if (!isObject(value) || value.ok !== true)
+        return false;
+    if (typeof value.workbookId !== 'string' || typeof value.sheetName !== 'string')
+        return false;
+    if (!Array.isArray(value.columns) || !value.columns.every(column => typeof column === 'string'))
+        return false;
+    if (!Array.isArray(value.rows))
+        return false;
+    if (typeof value.truncated !== 'boolean')
+        return false;
+    if (value.styles !== undefined) {
+        if (!Array.isArray(value.styles))
+            return false;
+        if (!value.styles.every(row => Array.isArray(row)))
+            return false;
+    }
+    if (value.range === undefined)
+        return false;
+    const range = value.range;
+    if (!isObject(range))
+        return false;
+    // 先取出局部常量再进闭包：TS 不会把 `value.range` 的收窄带进回调。
+    return ['startRow', 'startColumn', 'endRow', 'endColumn'].every(key => typeof range[key] === 'number');
+}

package/lib/contracts.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Shared wire contracts and pure protocol helpers.
+ *
+ * This source lives in the existing private UI workspace package so DSH plugins
+ * can type-check against one canonical module. Client and host builds bundle the
+ * imported code into their plugin output; it is not a published runtime package.
+ */
+export * from './contract-envelope.js';
+export * from './contract-refs.js';
+export * from './contract-version.js';
+export * from './contract-layout.js';
+export * from './contract-wire.js';

package/lib/contracts.js

@@ -0,0 +1,12 @@
+/**
+ * Shared wire contracts and pure protocol helpers.
+ *
+ * This source lives in the existing private UI workspace package so DSH plugins
+ * can type-check against one canonical module. Client and host builds bundle the
+ * imported code into their plugin output; it is not a published runtime package.
+ */
+export * from './contract-envelope.js';
+export * from './contract-refs.js';
+export * from './contract-version.js';
+export * from './contract-layout.js';
+export * from './contract-wire.js';

package/lib/types/audit.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Audit lineage (docs/issue/0022 P3).
+ *
+ * Workbook writes carry who asked for them: the ids the model passed, filled in
+ * from the active intent recorder when it is installed. Both transports need
+ * this — the browser sends them in a request body, the Agent receives them in
+ * tool arguments — so it is neither one's private concern.
+ */
+import type { LineageContext } from '#contracts';
+export declare function lineageOfValue(value: unknown): LineageContext | undefined;
+/**
+ * Active-recorder lineage supplied by `dsh-data-domain-knowledge`'s intent
+ * service (`titaDataAgentIntent`; the module was its own package until 0020).
+ * Optional: without the recorder plugin, workbook writes keep carrying only the
+ * lineage the model passed explicitly.
+ */
+export interface LineageProvider {
+    activeLineage(sessionKey: string): {
+        lineage: Partial<LineageContext>;
+        committed: boolean;
+    } | undefined;
+}
+/**
+ * The scope the intent recorder is resolved from. `apply()` sets it once; it is
+ * module state because the recorder is a host service rather than an argument.
+ */
+export declare let lineageScope: {
+    get(name: string, strict?: boolean): unknown;
+} | undefined;
+export declare function setLineageScope(scope: {
+    get(name: string, strict?: boolean): unknown;
+} | undefined): void;
+export declare function lineageProvider(): LineageProvider | undefined;
+export declare function lineageOfArgs(args: Record<string, unknown>, exec?: {
+    agent?: {
+        session?: {
+            header?: {
+                id?: string;
+            };
+        };
+    };
+}): LineageContext | undefined;

package/lib/types/audit.js

@@ -0,0 +1,39 @@
+export function lineageOfValue(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return undefined;
+    const args = value;
+    const lineage = {};
+    const fields = [
+        ['sessionId', 'sessionId'], ['turnId', 'turnId'], ['intentId', 'intentId'],
+        ['taskId', 'taskId'], ['subtaskId', 'subtaskId'], ['parentSubtaskId', 'parentSubtaskId'], ['runId', 'runId'],
+        ['traceId', 'traceId'], ['domain', 'domain'],
+    ];
+    for (const [target, source] of fields)
+        if (typeof args[source] === 'string' && args[source].trim())
+            lineage[target] = args[source].trim().slice(0, 160);
+    return Object.keys(lineage).length > 0 ? lineage : undefined;
+}
+/**
+ * The scope the intent recorder is resolved from. `apply()` sets it once; it is
+ * module state because the recorder is a host service rather than an argument.
+ */
+export let lineageScope;
+export function setLineageScope(scope) {
+    lineageScope = scope;
+}
+export function lineageProvider() {
+    const scope = lineageScope;
+    // Test harnesses pass a minimal context; only a real cordis scope can resolve services.
+    if (typeof scope?.get !== 'function')
+        return undefined;
+    return scope.get('titaDataAgentIntent', false);
+}
+export function lineageOfArgs(args, exec) {
+    const lineage = lineageOfValue(args);
+    const sessionId = lineage?.sessionId ?? exec?.agent?.session?.header?.id;
+    if (!sessionId)
+        return lineage;
+    // Explicit arguments win; the recorder only fills the ids a call omitted.
+    const inherited = lineageProvider()?.activeLineage(sessionId)?.lineage;
+    return { sessionId, ...inherited, ...lineage };
+}

package/lib/types/client/ProjectImportMenu.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The workbook import menu, and the chooser behind it.
+ *
+ * Import used to start and end in the operating system's file dialog. It now
+ * starts in the project: the menu opens a listing of `<project>/storages` with
+ * each file's creation and modification time, because a project that keeps its
+ * data beside itself should offer its own files first.
+ *
+ * It is still not a wall. Containment says where a project's files live, not
+ * what a user may open, so the chooser's footer keeps "从项目外导入…" — the same
+ * OS dialog as before, one click away rather than two.
+ *
+ * The bytes of a chosen file are read by the Host (a browser cannot open a path),
+ * and from there the pipeline is the one that already existed: the buffer goes
+ * back as `data-sheet:import-bytes` and `univer/plugins/export.ts` parses it.
+ *
+ * @module dsh-data-table/client/ProjectImportMenu
+ */
+import { type ReactElement } from 'react';
+export interface ProjectImportMenuProps {
+    /** True while no workbook is open: importing has nowhere to land. */
+    disabled: boolean;
+}
+/**
+ * The 导入 menu plus the project file chooser it opens.
+ *
+ * @param props - See {@link ProjectImportMenuProps}.
+ * @returns the menu and, when open, the chooser.
+ */
+export declare function ProjectImportMenu({ disabled }: ProjectImportMenuProps): ReactElement;

package/lib/types/client/ProjectImportMenu.js

@@ -0,0 +1,70 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * The workbook import menu, and the chooser behind it.
+ *
+ * Import used to start and end in the operating system's file dialog. It now
+ * starts in the project: the menu opens a listing of `<project>/storages` with
+ * each file's creation and modification time, because a project that keeps its
+ * data beside itself should offer its own files first.
+ *
+ * It is still not a wall. Containment says where a project's files live, not
+ * what a user may open, so the chooser's footer keeps "从项目外导入…" — the same
+ * OS dialog as before, one click away rather than two.
+ *
+ * The bytes of a chosen file are read by the Host (a browser cannot open a path),
+ * and from there the pipeline is the one that already existed: the buffer goes
+ * back as `data-sheet:import-bytes` and `univer/plugins/export.ts` parses it.
+ *
+ * @module dsh-data-table/client/ProjectImportMenu
+ */
+import { useState } from 'react';
+import { FilePickerDialog, ToolbarMenu } from '@tita-agent/ui';
+import { FileSpreadsheet, FileText, Upload } from '@tita-agent/ui/icons';
+import { fetchProjectFiles, readProjectFile } from "./transport/workbookApi.js";
+/** Extensions each format accepts, as the chooser's filter. */
+const ACCEPT = { xlsx: ['.xlsx', '.xls'], csv: ['.csv'] };
+/** Copy for each format, used in the menu hint and the dialog's title. */
+const FORMAT_LABEL = { xlsx: 'Excel', csv: 'CSV' };
+/**
+ * The 导入 menu plus the project file chooser it opens.
+ *
+ * @param props - See {@link ProjectImportMenuProps}.
+ * @returns the menu and, when open, the chooser.
+ */
+export function ProjectImportMenu({ disabled }) {
+    const [format, setFormat] = useState(null);
+    /** Hand a chosen file's bytes to the import pipeline. */
+    const readAndImport = (entry, chosen) => {
+        setFormat(null);
+        void readProjectFile(entry.path)
+            .then(file => {
+            window.dispatchEvent(new CustomEvent('data-sheet:import-bytes', {
+                detail: { data: file.data, name: file.name, format: chosen },
+            }));
+        })
+            .catch((error) => {
+            // The panel already listens for this event, so a failure to read the
+            // file reports itself the same way a failure to parse it does.
+            window.dispatchEvent(new CustomEvent('data-sheet:import-error', {
+                detail: { message: error instanceof Error ? error.message : String(error) },
+            }));
+        });
+    };
+    return (_jsxs(_Fragment, { children: [_jsx(ToolbarMenu, { label: "\u5BFC\u5165", icon: _jsx(Upload, { size: 14, "aria-hidden": "true" }), disabled: disabled, groups: [{
+                        items: [
+                            { id: 'xlsx', label: '导入 Excel', hint: '从项目 storages/ 选择文件', icon: _jsx(FileSpreadsheet, { size: 15, "aria-hidden": "true" }), onSelect: () => { setFormat('xlsx'); } },
+                            { id: 'csv', label: '导入 CSV', hint: '从项目 storages/ 选择文件', icon: _jsx(FileText, { size: 15, "aria-hidden": "true" }), onSelect: () => { setFormat('csv'); } },
+                        ],
+                    }] }), format !== null && (_jsx(FilePickerDialog, { open: true, onOpenChange: next => { if (!next)
+                    setFormat(null); }, title: `导入 ${FORMAT_LABEL[format]} 文件`, description: `选择项目 storages/ 下的文件；内容读入当前工作簿，原文件不会被移动或改动。`, accept: ACCEPT[format], load: fetchProjectFiles, onPick: entry => { readAndImport(entry, format); }, onImportOutside: () => {
+                    const outside = format;
+                    setFormat(null);
+                    // Literal event names rather than a template: the Univer bridge is
+                    // looked up by these exact strings, and a name assembled at runtime
+                    // is a bridge nobody can grep for.
+                    if (outside === 'csv')
+                        window.dispatchEvent(new CustomEvent('data-sheet:request-import-csv'));
+                    else
+                        window.dispatchEvent(new CustomEvent('data-sheet:request-import-xlsx'));
+                } }))] }));
+}

package/lib/types/client/SheetPanel.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Right-column workbook canvas. Univer owns the editing experience; this
+ * component owns the browser projection of the DSH workbook service:
+ * snapshot bootstrap, incremental user operations, and Agent-operation sync.
+ * @module dsh-data-table/client/SheetPanel
+ */
+import type { PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+import type { SurfaceBridgeService } from '@tita-agent/dsh-surface-bridge';
+import '@tita-agent/ui/styles.css';
+type PanelProps = PropsRuntime<'details'>;
+export interface WorkbookWorkspaceProps {
+    /** Whether the workspace is live. The embedded pane keeps this true even while parked. */
+    open: boolean;
+    /**
+     * Whether the workspace is on screen. Defaults to `open`.
+     *
+     * The resident workspace outlives the pane, so `open` cannot answer this; the
+     * few behaviours that must follow real visibility (the window-level save
+     * shortcut) read this instead.
+     */
+    visible?: boolean;
+    /** Standalone mode removes the in-panel affordances that only make sense in DSH. */
+    standalone?: boolean;
+    /** Optional workbook to load first; embedded mode otherwise requires explicit selection. */
+    initialWorkbookId?: string;
+    /** Shared DSH composer context bridge; absent in standalone pages. */
+    bridge?: SurfaceBridgeService;
+}
+/** Shared workbook workspace used by both the DSH details panel and the standalone page. */
+export declare function WorkbookWorkspace({ open, visible, standalone, initialWorkbookId, bridge }: WorkbookWorkspaceProps): import("react").JSX.Element;
+/** Right-column adapter: the DSH layout owns the open/close state. */
+export declare function SheetPanel(_: PanelProps): import("react").JSX.Element;
+export {};