@sparkelf/dsh-dataops-managed 0.3.24 → 0.3.25

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

@@ -0,0 +1,26 @@
+/**
+ * The custom `dataops-resources` sidebar tab.
+ *
+ * It renders the DataOps embed page in a same-origin iframe. The iframe is deliberately not
+ * a generic URL tab: the generic tab sandbox is an opaque origin and cannot use the portal's
+ * sessionStorage. The only parent-child messages are navigation and "add to conversation";
+ * every authorization decision still happens in DataOps.
+ *
+ * @module client/DataOpsResourcesTab
+ */
+/** Minimal view of the tab record carried by Better Sidebar. */
+export interface ResourceTabRecord {
+    meta?: unknown;
+    title?: string;
+}
+/** Props Better Sidebar passes to a tab component (the fields this tab needs). */
+export interface DataOpsResourcesTabProps {
+    ctx: unknown;
+    scope?: {
+        sessionId?: string;
+    };
+    tab: ResourceTabRecord;
+    visible?: boolean;
+}
+/** Render the embedded DataOps resource page and translate its parent messages. */
+export declare function DataOpsResourcesTab({ ctx, tab }: DataOpsResourcesTabProps): import("react").JSX.Element;

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

@@ -0,0 +1,34 @@
+/**
+ * Always-mounted host→client bridge for the resource tab.
+ *
+ * The Host tool cannot call the browser's tab API. It broadcasts one SSE event; this
+ * component translates that event into `betterSidebar.openTab` plus `updateTab` so a
+ * second import focuses the existing tab and refreshes its target resource.
+ *
+ * @module client/OpenResourceBridge
+ */
+/** The part of Better Sidebar's service this bridge uses. */
+export interface ResourceTabService {
+    openTab(seed: {
+        type: string;
+        id?: string;
+        title?: string;
+        meta?: unknown;
+    }, scope?: {
+        sessionId?: string;
+    }): void;
+    updateTab?(tabId: string, patch: {
+        title?: string;
+        path?: string;
+        meta?: unknown;
+    }, sessionId?: string): void;
+}
+/** Tab id shared with the client registration. */
+export declare const RESOURCE_TAB_TYPE = "dataops-resources";
+/** Invisible bridge component; renders nothing. */
+export declare function OpenResourceBridge({ service, scope }: {
+    service: ResourceTabService;
+    scope?: {
+        sessionId?: string;
+    };
+}): null;

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

@@ -14,7 +14,7 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
         'settings.dataops-managed': ManagedDataOpsKey;
     }
 }
-/** Required client services for the managed DataOps Settings section. */
+/** Required client services for the managed DataOps Settings section and the resource tab bridge. */
 export declare const inject: string[];
 /**
  * Register the managed DataOps surfaces and the sign-in prompt.

package/lib/types/collect-api.d.ts

@@ -0,0 +1,99 @@
+/**
+ * DataOps spreadsheet-import transport for the collection skill.
+ *
+ * The host reads a workspace attachment, uploads it as multipart, asks DataOps for a
+ * create-table or existing-table plan, and only executes when the model calls the
+ * execute tool after the user's plan confirmation. Nothing here creates a table on
+ * preview/plan; execution is the single mutating call.
+ *
+ * @module collect-api
+ */
+import type { ReviewApi } from './review-api.ts';
+/** Largest spreadsheet the DataOps importer accepts. */
+export declare const COLLECT_FILE_MAX_BYTES: number;
+/** One importable DataOps database destination. */
+export interface CollectDataSource {
+    urn: string;
+    name: string;
+    dbType: string | null;
+    databaseName: string | null;
+}
+/** The preview payload DataOps returns for one uploaded workbook. */
+export interface CollectPreview {
+    sessionId: string;
+    file?: {
+        name?: string;
+        sheetName?: string;
+        rowCount?: number;
+        columnCount?: number;
+    };
+    sheetName?: string;
+    rowCount?: number;
+    columnCount?: number;
+    columns?: Array<Record<string, unknown>>;
+    [key: string]: unknown;
+}
+/** A create-table or field-mapping plan plus its session context. */
+export interface CollectPlanResult {
+    session?: Record<string, unknown>;
+    model?: Record<string, unknown>;
+    plan?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/** The execute result; `resource` is the row DataOps upserted. */
+export interface CollectExecuteResult {
+    success?: boolean;
+    mode?: string;
+    targetTable?: {
+        schema?: string;
+        table?: string;
+    };
+    totalRows?: number;
+    importedRows?: number;
+    skippedRows?: number;
+    errors?: unknown[];
+    resource?: {
+        id: number;
+        urn: string;
+        chineseName?: string | null;
+        accessLevel?: string;
+        aiVisible?: boolean;
+        created?: boolean;
+    };
+    [key: string]: unknown;
+}
+/** One resource row returned by the DataOps catalog. */
+export interface CollectResourceRow {
+    id: number;
+    urn: string;
+    chineseName?: string | null;
+    sourceTable?: string | null;
+    resourceType?: string;
+    rowCount?: number | null;
+    accessLevel?: string;
+    aiVisible?: boolean | null;
+}
+/** Read and validate one spreadsheet attachment from the workspace. */
+export declare const readCollectFile: (filePath: string) => Promise<{
+    buffer: Buffer;
+    fileName: string;
+    sizeBytes: number;
+}>;
+/** Spreadsheet import calls bound to one workspace credential. */
+export declare class CollectApi {
+    private readonly reviewApi;
+    constructor(reviewApi: ReviewApi);
+    preview(filePath: string): Promise<CollectPreview>;
+    dataSources(): Promise<CollectDataSource[]>;
+    plan(payload: {
+        sessionId: string;
+        dataSourceUrn?: string;
+        targetTable?: {
+            schema: string;
+            table: string;
+        };
+        modelId?: number;
+    }): Promise<CollectPlanResult>;
+    execute(payload: Record<string, unknown>): Promise<CollectExecuteResult>;
+    listResources(query?: string, limit?: number): Promise<CollectResourceRow[]>;
+}

package/lib/types/index.d.ts

@@ -64,6 +64,14 @@ interface VolatileRef<T> {
 export interface Config {
     /** DataOps browser/API origin reachable from the DSH Host. */
     baseUrl: string;
+    /**
+     * Browser-facing DataOps origin used by the resource sidebar iframe.
+     *
+     * `baseUrl` may point at a container-internal API address. Leave this empty in a
+     * same-origin portal deployment (the request Host is the correct origin) and set it
+     * only for a split-origin deployment where the browser reaches DataOps elsewhere.
+     */
+    webBaseUrl?: string;
     /** Local namespace for DataOps MCP tools. */
     serverName: string;
     /** DSH credential reference that stores the current DataOps access JWT. */

package/lib/types/resource-tab.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Host side of the "open a DataOps resource tab" bridge.
+ *
+ * A model tool cannot call a browser tab API. The tool publishes one event on this
+ * workspace-local SSE channel; the client half owns `betterSidebar.openTab`. The channel
+ * is scoped to one managed workspace (one DataOps user) and carries navigation only —
+ * authorization still happens at every DataOps request.
+ *
+ * @module resource-tab
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+/** SSE route the client subscribes to. */
+export declare const OPEN_RESOURCE_EVENTS_PATH = "/integrations/dataops/open-resource/events";
+/** Same-origin route the client uses to learn where the DataOps frontend lives. */
+export declare const RESOURCE_TAB_CONFIG_PATH = "/integrations/dataops/resource-tab/config";
+/** Browser tab type registered by the client half. */
+export declare const RESOURCE_TAB_TYPE = "dataops-resources";
+/** Modes the embed page knows how to apply after opening. */
+export type OpenResourceMode = 'focus' | 'grant' | 'detail' | 'audit';
+/** One navigation request delivered to every connected client. */
+export interface OpenResourceEvent {
+    type: 'open_resource';
+    requestId: string;
+    resourceId: number;
+    resourceName: string | null;
+    mode: OpenResourceMode;
+    nonce: string;
+}
+/** Minimal logger surface used by the hub. */
+interface HubLogger {
+    warn(message: string): void;
+}
+/**
+ * Fan-out registry for the workspace's live SSE subscribers.
+ *
+ * A workspace has one browser in the normal case, but a reconnect can briefly leave the
+ * previous response open. Broadcasting to the current set makes the new connection and the
+ * stale one harmless: the browser keeps one tab, and the client dedupes by resource tab id.
+ */
+export declare class OpenResourceHub {
+    private readonly logger;
+    private readonly clients;
+    private heartbeat;
+    constructor(logger: HubLogger);
+    /** Accept one SSE subscription and own its response until the client disconnects. */
+    subscribe(request: IncomingMessage, response: ServerResponse): void;
+    /** Send one navigation event to every connected client. */
+    broadcast(event: Omit<OpenResourceEvent, 'type' | 'requestId'> & {
+        requestId?: string;
+    }): OpenResourceEvent;
+    /** Number of live subscribers, used by the tool result to explain a missing browser. */
+    size(): number;
+    /** Close every subscriber; called by the plugin disposer. */
+    dispose(): void;
+    private ensureHeartbeat;
+}
+/** Resolve the browser-facing DataOps origin for the iframe. */
+export declare const resolveResourceTabConfig: (request: IncomingMessage, configuredWebBaseUrl: string | undefined) => {
+    embedBaseUrl: string;
+    sameOrigin: boolean;
+    tabType: string;
+};
+export {};

package/lib/types/tool-manager.d.ts

@@ -17,6 +17,7 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 import type { ReviewApi, ReviewApiResult } from './review-api.ts';
+import type { OpenResourceHub } from './resource-tab.ts';
 import { type AiToolName, type DataOpsScope } from './tool-scope.ts';
 /**
  * Reconcile the managed tools with the current DataOps scope.
@@ -28,6 +29,7 @@ import { type AiToolName, type DataOpsScope } from './tool-scope.ts';
 export declare class AiToolManager {
     private readonly ctx;
     private readonly reviewApi;
+    private readonly collectHub;
     private readonly definitions;
     private readonly registrations;
     private readonly unsubscribeExpiry;
@@ -36,7 +38,7 @@ export declare class AiToolManager {
     private revision;
     private inflight;
     private disposed;
-    constructor(ctx: Context, reviewApi: ReviewApi);
+    constructor(ctx: Context, reviewApi: ReviewApi, collectHub: OpenResourceHub);
     /** The scope the current registration set was derived from, when one has been read. */
     currentScope(): DataOpsScope | undefined;
     /** The tool names currently registered, for diagnostics and tests. */

package/lib/types/tool-scope.d.ts

@@ -113,6 +113,19 @@ export declare const AI_TOOL_ACCESS: {
     readonly dataops_api_docs: {
         readonly superAdminOnly: true;
     };
+    readonly dataops_collect_preview: {
+        readonly permission: "data:resource:manage";
+    };
+    readonly dataops_collect_plan: {
+        readonly permission: "data:resource:manage";
+    };
+    readonly dataops_collect_execute: {
+        readonly permission: "data:resource:manage";
+    };
+    readonly dataops_collect_resources: {
+        readonly permission: "data:resource:read";
+    };
+    readonly dataops_open_resource_tab: {};
 };
 /** Every managed tool name, in the order the manager considers them. */
 export declare const AI_TOOL_NAMES: AiToolName[];

package/lib/types/tools.d.ts

@@ -20,6 +20,7 @@
 import type { Context } from '@deepseek-ai/cordis';
 import { type ToolDefinition } from '@deepseek-ai/dsh-tools';
 import type { ReviewApi } from './review-api.ts';
+import type { OpenResourceHub } from './resource-tab.ts';
 import { type AiToolName, type DataOpsScope } from './tool-scope.ts';
 /** One managed tool together with the name the disclosure map uses. */
 export interface AiManagedTool {
@@ -38,4 +39,4 @@ export interface AiManagedTool {
  * @param readScope - Live accessor for the manager's current scope.
  * @returns One definition per managed tool name.
  */
-export declare function buildAiManagementTools(ctx: Context, reviewApi: ReviewApi, readScope: () => DataOpsScope | undefined): AiManagedTool[];
+export declare function buildAiManagementTools(ctx: Context, reviewApi: ReviewApi, readScope: () => DataOpsScope | undefined, collectHub: OpenResourceHub): AiManagedTool[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sparkelf/dsh-dataops-managed",
-  "version": "0.3.24",
+  "version": "0.3.25",
   "description": "DataOps JWT intake and credential-backed MCP tools for managed DeepSeek Harness workspaces.",
   "type": "module",
   "main": "./lib/index.js",
@@ -41,6 +41,7 @@
     "cordis.patch.yml",
     "skills/dataops-query/SKILL.md",
     "skills/dataops-query/i18n/zh.json",
+    "skills/dataops-collect/SKILL.md",
     "README.md",
     "LICENSE"
   ],

package/skills/dataops-collect/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: dataops-collect
+description: 把表格 / Excel / CSV 建成可问数的数据资源，或把新表格追加到已有资源时使用。包含新建与追加的分岔、计划确认、建表写入、权限入口和结果汇报；确认计划前绝不建表。
+---
+
+# 数据采集（AI 建资源）
+
+用户把一份表格交给 AI，AI 解析、出计划、用户确认后建表写数，最后得到一个能问数的资源。第一版只做一次性导入；一个会话一份文件、一个目标资源。
+
+## 一、什么时候用
+
+用户表达下面任一意图时使用本技能：
+
+- 把这份表格建成能问数的资源
+- 这个 Excel 帮我导进来
+- 上传个表能问数吗
+- 把这份数据加到已有的那个资源里
+- 追加到 XX 资源
+- 新建一个数据资源
+- 表格导入 / 导入成表 / 建成资源
+- 把 CSV 变成能查的表 / 能问数的表
+- 这份数据帮我入库 / 建表
+- 把这个 sheet 建成资源
+- 这个表以后能用来问数吗
+- 把这份销售表导入
+- 把这份名单建成资源
+- 加到门店销售明细里
+- 追加一份月度数据
+- 建个新资源，用这个文件
+- 导入到数据中台
+- 这个文件能建成资源吗
+- 把附件建成资源
+- 用这个表格建一张表
+
+不适用：纯问数、取数、查数据（用 `dataops-query`）；只讨论表结构但不导入。
+
+## 二、四个硬规则
+
+1. **一次会话一份文件、一个目标资源。** 多文件批量不做。
+2. **有引用 = 追加；无引用 = 先问，不默认新建。** 用户话里已经说清“新建”或“追加”的，跳过这一问；没说清又没引用，必须先出「新建资源 / 选择已有资源」二选一，不能直接出新建计划。
+3. **计划确认是唯一硬闸。** 用户点「开始导入」之前，绝不调用 `dataops_collect_execute`，绝不建表、绝不写数。预览和计划工具本身不建表，可以放心调用。
+4. **执行走原生工具流。** 不要自己造执行卡、进度卡；工具参数、结果、耗时、失败原因都在原生工具卡里。你只在旁边说人话。
+
+## 三、主流程
+
+### 1. 找到文件
+
+从当前消息的附件 / 系统上下文里取得表格在工作区的路径（通常是 `/workspace/...` 或 `temp/conversations/.../attachments/...`）。没有路径时，不要猜目录、不要扫全工作区；直接说“请把表格拖进输入框，或点输入框的 + 上传”，并给一个内联上传提示。
+
+### 2. 预览，不要建表
+
+调用：
+
+`dataops_collect_preview({ file_path })`
+
+返回 `sessionId`、`preview`、`dataSources`。用大白话复述：
+
+> 看了下，明细 sheet 共 12,000 行、18 列；表头在第 2 行。我先按明细建资源。
+
+文件读不出来也在这里说清楚：
+
+> 这个 xlsx 读不出来，可能加密了。你换个文件，或者告诉我表头在第几行。
+
+### 3. 先定去向
+
+- 当前会话里有 `resource-ref` 引用块 → 追加到该资源；
+- 用户说“新建 / 建个新资源 / 不要加到已有的” → 新建；
+- 用户说“追加 / 加到 / 并到 / 合到” → 追加；没有具体资源时先让用户选；
+- 都没有 → 出「新建资源 / 选择已有资源」GenUI，等用户选。
+
+选择已有资源时：
+1. 调用 `dataops_collect_resources({ query, limit: 8 })`；
+2. 用 `choices` 或 `list` + 按钮列出最多 8 个候选（资源名 + 表名 + 行数）；
+3. 用户选中后，把该资源作为本次目标，进入计划。
+
+### 4. 生成计划，不要执行
+
+调用：
+
+`dataops_collect_plan({ session_id, data_source_urn, target_schema?, target_table? })`
+
+- 不传 `target_table` = 新建表（CREATE_TABLE）；
+- 传 `target_schema` + `target_table` = 追加到已有表（EXISTING_TABLE）。
+
+返回后检查 `plan`：
+- 新建表：`plan.mode === 'CREATE_TABLE'`，有 `plan.createTable`、`plan.createSql`；
+- 追加：`plan.mode === 'EXISTING_TABLE'`，有 `plan.mappings`，并在计划里多一行映射摘要（匹配 N 个字段、新增 N 个、N 个类型不兼容）。
+
+### 5. 出计划 GenUI
+
+计划是主确认点。必须包含：
+
+- 资源名（AI 起草，可改）
+- 目标表（原始层库表名，AI 起草，可改）
+- 导入数据源（只有一个源时自动选中并置灰；多个源时让用户选）
+- 字段总数，以及哪几个类型拿不准（标黄 / 写“需确认”）
+- 去向（新建资源 / 追加到某个已有资源）
+- 描述与标签（AI 起草，可改）
+- 默认权限（仅自己可见）
+
+底部只有一组主次按钮：**开始导入**（`submit`，提交资源名/表名/描述）和 **再调整**（`button`）。不要做第二个确认步骤。
+
+计划 GenUI 示例（把 `<...>` 换成真实值）：
+
+```dsh-ui
+{"title":"导入计划","items":[{"type":"text","size":"body","content":"看了下，明细 sheet 共 <行数> 行、<列数> 列；我先按明细建资源。"},{"type":"card","title":"<资源名>","items":[{"type":"keyvalue","pairs":[{"key":"去向","value":"新建资源"},{"key":"导入数据源","value":"<数据源名>"},{"key":"目标表","value":"<schema.table>"},{"key":"字段","value":"<字段数> 列（<需确认数> 列类型需确认）"},{"key":"默认权限","value":"仅自己可见"}]},{"type":"table","columns":["字段","类型","说明"],"rows":[["<字段1>","<类型>","<说明>"],["<字段2>","<类型>","需确认"]]},{"type":"input","id":"resourceName","label":"资源名","value":"<资源名>"},{"type":"input","id":"tableName","label":"目标表","value":"<目标表>"},{"type":"textarea","id":"description","label":"描述与标签","value":"<描述>"},{"type":"submit","label":"开始导入","action":"dataops_collect_confirm","groups":["resourceName","tableName","description"]},{"type":"button","label":"再调整","tone":"ghost","action":"dataops_collect_adjust"}]}]}
+```
+
+规则：
+
+- 用户点「再调整」后，只在对话里改参数，然后重新调用 `dataops_collect_plan` / 修改计划，**不要执行**；
+- 用户改了参数，重新出计划，不直接执行；
+- 确认后，计划折叠成一行“已按此计划执行”的回执，把屏幕让给工具流；
+- 确认后如果要改参数，先停，再出新计划。
+
+### 6. 执行
+
+用户点「开始导入」后，从 GenUI 的 `fields` 取 `resourceName`、`tableName`、`description`，然后调用：
+
+`dataops_collect_execute({ session_id, data_source_urn, mode, target_schema?, target_table?, create_plan_json, mappings_json, resource_name, resource_description, resource_tags?, ai_visible?, access_level? })`
+
+- `mode` 用 `plan.mode`；
+- 新建表：`create_plan_json` 传 `JSON.stringify(plan.createTable)`，`mappings_json` 传 `"[]"`；
+- 追加：`mappings_json` 传 `JSON.stringify(plan.mappings)`；
+- `resource_name` 用用户确认后的资源名；
+- `access_level` 默认 `PRIVATE`；`ai_visible` 默认 `true`。
+
+执行期间只说阶段小结，例如：
+
+> 表建好了。现在写数据，一万两千行，估计一两分钟。
+>
+> 写完了，正在生成字段说明。
+
+失败只说三类，并给一个动作：
+- 文件问题 → 重新上传 / 告诉我表头在第几行；
+- 字段问题 → 调整映射 / 改类型；
+- 系统问题 → 重试。
+
+### 7. 结果 GenUI + 打开资源页签
+
+执行成功后：
+
+1. 调用 `dataops_open_resource_tab({ resource_id, resource_name, mode: 'focus' })`，让右侧栏自动打开 `dataops-resources` 页签并定位新资源；
+2. 出结果 GenUI，必须包含资源名、目标表、行数、字段数、“已可问数”、当前可见范围（默认“仅自己可见”），以及三个动作：**分配权限 / 去问数 / 查看详情**，外加一条 **查看操作记录** 文字链。
+
+结果 GenUI 示例：
+
+```dsh-ui
+{"title":"导入完成","items":[{"type":"callout","tone":"success","title":"已可问数","content":"资源已建成，可以开始问数。"},{"type":"keyvalue","pairs":[{"key":"资源名","value":"<资源名>"},{"key":"目标表","value":"<schema.table>"},{"key":"行数","value":"<行数>"},{"key":"字段数","value":"<字段数>"},{"key":"可见范围","value":"仅自己可见"}]},{"type":"row","items":[{"type":"button","label":"分配权限","tone":"primary","action":"dataops_open_grant"},{"type":"button","label":"去问数","action":"dataops_ask"},{"type":"button","label":"查看详情","action":"dataops_open_detail"}]},{"type":"button","label":"查看操作记录 →","tone":"ghost","small":true,"action":"dataops_open_audit"}]}
+```
+
+三个动作的处理：
+
+- 分配权限 → `dataops_open_resource_tab({ resource_id, mode: 'grant' })`，侧栏资源卡定位并自动打开授权弹窗；
+- 去问数 → 不要跳页，直接在对话里给 2-3 个可以问的问题示例，并说明资源已可被检索；
+- 查看详情 → `dataops_open_resource_tab({ resource_id, mode: 'detail' })`；
+- 查看操作记录 → `dataops_open_resource_tab({ resource_id, mode: 'audit' })`。
+
+## 四、引用资源（追加）
+
+引用可能来自输入框的资源 chip，也可能来自右侧栏资源卡的「添加到对话」。如果引用以结构化块出现，形如：
+
+```resource-ref
+{"kind":"dataops-resource","resourceId":123,"name":"门店销售明细","table":"dwd_store_sales"}
+```
+
+就把它当作本次追加目标，不要再问“新建还是追加”。如果用户在上传文件之前先引用了资源，直接按追加处理。
+
+如果「添加到对话」降级成发送一条消息，消息里必须带这个 `resource-ref` 块；没有结构化块时，按“用户口头提到资源名”处理，先用 `dataops_collect_resources` 找到资源再确认，不要凭名字猜 id。
+
+## 五、边界
+
+- 不做定时采集、增量水位、失败重试策略；
+- 不做多文件批量、文件夹上传；
+- 不做覆盖（只追加）；
+- 不在对话里做权限表单（GenUI 没有人员选择器）；
+- 不在 DSH 里做审计弹窗；操作记录在 DataOps 资源详情 / 系统审计。