dsh-lh-data 0.1.0

package/lib/parse.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 文件解析与类型推断 —— 移植自 `agentic-data-mini` 的 `src/lib/utils/fileParser.ts`。
+ *
+ * 保留的关键行为（设计文档 §4）：
+ * - XLSX：`XLSX.read({ type: 'buffer', cellDates: true })` + `sheet_to_json({ raw: true, defval: null })`，
+ *   Date → `YYYY-MM-DD`；默认第一个 sheet。
+ * - CSV：`Papa.parse({ header: true, skipEmptyLines: true, dynamicTyping: true, transformHeader: trim })`。
+ * - 列名：**保留原名（含中文）**，SQL 中双引号包裹；空列名 → `column`；重名追加 `_2`。
+ * - 类型推断：编码/号码类列名强制 text；13+ 位整数或 `xE+12` 科学计数法强制 text（防精度丢失）；
+ *   其余 numeric>80% / boolean>90% / date 正则>70%。
+ */
+export type ColumnType = 'text' | 'numeric' | 'boolean' | 'date';
+export interface ColumnInfo {
+    /** 原始表头（如「物料编码」）。 */
+    name: string;
+    /** SQL 中使用的列名（与 name 相同，或去重后加 `_2`）。 */
+    sanitizedName: string;
+    type: ColumnType;
+    nullable: boolean;
+    sample: unknown[];
+    description?: string;
+}
+export interface ParsedFile {
+    headers: string[];
+    rows: Record<string, unknown>[];
+    rowCount: number;
+    columns: ColumnInfo[];
+}
+export declare const DEFAULT_SAMPLE_ROWS = 100;
+/** 列名消毒：trim，空列名回落 `column`，其余保留原名。 */
+export declare function sanitizeColumnName(name: string): string;
+/** 重名列追加 `_2` / `_3`（原地修改）。 */
+export declare function deduplicateColumnNames(columns: ColumnInfo[]): void;
+/** 编码/号码类列：即使值是数字也应存 text（无数学含义）。 */
+export declare function isCodeOrIdField(columnName: string): boolean;
+/** 大数判定：13+ 位整数或 `1.78E+12` 这类科学计数法。 */
+export declare function isLargeNumber(value: unknown): boolean;
+/** 从采样值 + 列名推断列类型；列名优先级最高。 */
+export declare function inferColumnType(values: unknown[], columnName?: string): ColumnType;
+export declare function parseCSV(buffer: Buffer, sampleRows?: number): ParsedFile;
+export declare function parseXLSX(buffer: Buffer, sheetName?: string, sampleRows?: number): ParsedFile;

package/lib/preview.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 模型可见片段的构造 —— 设计文档 §5.3。
+ *
+ * 这里只做两件事：把结果裁成「前几行 + 可选尾几行」的预览，以及基于**全量数据**
+ * 生成类型化摘要（不是只看预览行）。摘要让模型在不读全表的情况下也能下结论，
+ * 从而不再需要逐页翻数据。
+ */
+import type { Database, Row } from './db';
+import type { ColumnType } from './parse';
+export type PreviewStrategy = 'head' | 'head-tail';
+export interface PreviewOptions {
+    previewRows: number;
+    previewStrategy: PreviewStrategy;
+    previewColumns: number;
+    summaryEnabled: boolean;
+    /** 参与摘要的列数上限（宽表保护）。 */
+    summaryMaxColumns: number;
+    /** 文本列取 top 值的列数上限。 */
+    summaryMaxTextColumns: number;
+}
+/** 一列的统计摘要；字段按类型给出，缺失即不适用。 */
+export interface ColumnSummary {
+    name: string;
+    type: ColumnType;
+    /** 非空值个数。 */
+    count: number;
+    min?: number | string | null;
+    max?: number | string | null;
+    avg?: number | null;
+    sum?: number | null;
+    /** distinct 取值数（文本列）。 */
+    distinct?: number;
+    /** 高频取值（文本列，distinct 过多时省略）。 */
+    top?: {
+        value: string;
+        count: number;
+    }[];
+    /** 布尔列为真的行数。 */
+    trueCount?: number;
+}
+export interface PreviewSlice {
+    rows: Row[];
+    columns: string[];
+    /** 是否折叠了列（结果列数超过 previewColumns）。 */
+    columnTruncated: boolean;
+    /** 头尾之间是否跳过了行。 */
+    gap: boolean;
+    /** 被跳过的行数。 */
+    skipped: number;
+}
+/** 头/尾各取多少行；`tail > 0` 时渲染层会在中间插入省略提示。 */
+export declare function previewSlicePlan(totalRows: number, options: PreviewOptions): {
+    head: number;
+    tail: number;
+};
+/** 裁剪预览列（超宽表只保留前 N 列）。 */
+export declare function previewColumns(columns: string[], options: PreviewOptions): {
+    columns: string[];
+    truncated: boolean;
+};
+/** 拼装一次预览切片（头行 + 可选尾行），同时报告跳过了多少行。 */
+export declare function buildPreviewSlice(headRows: Row[], tailRows: Row[], columns: string[], totalRows: number, options: PreviewOptions): PreviewSlice;
+/** 单元格按字符数截断，返回文本与被截断标记。 */
+export declare function truncateCell(value: unknown, max: number): {
+    text: string;
+    truncated: boolean;
+};
+/**
+ * 基于全表生成列摘要：numeric/date/boolean 走一次聚合扫描，
+ * 文本列额外做 distinct 计数与 top 取值（受列数上限保护）。
+ */
+export declare function summarizeColumns(db: Database, tableName: string, columns: {
+    name: string;
+    type: ColumnType;
+}[], options: PreviewOptions): Promise<ColumnSummary[]>;

package/lib/render.d.ts

@@ -0,0 +1,100 @@
+/**
+ * 模型可见文本的渲染（对齐 `dsh-lh-judge` 的 render.ts 定位）。
+ *
+ * 约定：`output.render` 只做纯函数渲染，不读状态；物理表名绝不出现在这里。
+ */
+import type { Row } from './db';
+import type { ColumnInfo } from './parse';
+import { type ColumnSummary } from './preview';
+export interface DatasetListItem {
+    datasetId: string;
+    name: string;
+    rowCount: number;
+    columnCount: number;
+    status: string;
+    sourcePath: string | null;
+    createdAt: number;
+}
+export declare const MAX_RENDER_CELL = 40;
+export declare const MAX_RENDER_ROWS = 50;
+export declare function truncateText(text: string, max: number): string;
+/** 单元格转义：去掉换行与竖线，避免破坏 markdown 表格。 */
+export declare function formatValue(value: unknown): string;
+export declare function formatTimestamp(epochMs: number): string;
+export declare function renderDatasetList(items: DatasetListItem[]): string;
+export declare function renderColumns(columns: ColumnInfo[]): string;
+export declare function renderRows(columns: string[], rows: Row[], maxRows?: number): string;
+/** 片段渲染的输入（结构化而非 import 工具类型，避免 render → tools 的循环）。 */
+export interface QueryPreviewInput {
+    name: string;
+    datasetId: string;
+    columnCount: number;
+    /** 实际命中行数。 */
+    matchedRows: number;
+    /** 本次可服务行数（已按上限收敛）。 */
+    totalRows: number;
+    preview: {
+        rows: Row[];
+        columns: string[];
+        /** 头段行数；`gap` 为真时其后是尾段。 */
+        headCount: number;
+        gap: boolean;
+        skipped: number;
+        columnTruncated: boolean;
+        hiddenColumns: number;
+    };
+    summary: ColumnSummary[];
+    /** 有小节被省略（预览只是结果的一部分）。 */
+    truncated: boolean;
+    /** 存在前端视图。 */
+    view?: {
+        pageSize: number;
+        stable: boolean;
+    };
+}
+/**
+ * 渲染查询结果的模型可见片段：行数概览 + 少量预览行 + 类型化摘要 + 视图提示。
+ * 目标是把上下文占用压到常量级，同时保留「足以下结论」的统计信息。
+ */
+export declare function renderQueryPreview(input: QueryPreviewInput): string;
+export interface SourceListItem {
+    id: string;
+    name: string;
+    type: string;
+    host: string;
+    port: number;
+    database: string;
+    status: string;
+    lastError: string | null;
+    lastCheckedAt: number | null;
+}
+export interface SourceTableItem {
+    tableName: string;
+    schemaName: string | null;
+    rowCount: number;
+    columnCount: number;
+    primaryKey: string | null;
+}
+export declare function renderSourceList(items: SourceListItem[]): string;
+export declare function renderSourceTables(sourceName: string, schema: string | null, items: SourceTableItem[]): string;
+export interface ConnectionTestView {
+    name: string;
+    success: boolean;
+    latency: number;
+    version: string | null;
+    error: string | null;
+}
+export declare function renderConnectionTest(view: ConnectionTestView): string;
+/** 包装成 dsh 的回注用户消息（带 source 标记，便于去重/追踪）。 */
+export interface UserMessage {
+    role: 'user';
+    content: {
+        type: 'text';
+        text: string;
+    }[];
+    source: {
+        kind: 'plugin';
+        plugin: string;
+    };
+}
+export declare function toUserMessage(text: string, plugin: string): UserMessage;

package/lib/scope-registry.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 工作区（scope）注册表 —— 设置页「聚合展示全部工作区」的枚举来源。
+ *
+ * 为什么需要这张表：`perWorkspace=false`（默认）时所有 scope 共用一个库文件，
+ * `SELECT DISTINCT scope_key FROM datasets` 就能枚举；但 `perWorkspace=true`
+ * 时每个 scope 是独立的 `<hash>.db`，库文件名是 scope 的单向哈希，
+ * **没有任何办法反查「这台机器上有哪些工作区」**。
+ *
+ * 因此把见过的 scope 记在**目录库**里：一个不做 scope 分片的固定库
+ * （`perWorkspace=false` 时与业务库是同一个文件，不额外占地方）。
+ *
+ * 与 `DatasetStore` 分开，是为了让 store 保持单一职责（数据集元数据）并守住
+ * 200 行的类体积上限。
+ */
+import { type DbConfig } from './db';
+export interface ScopeEntry {
+    /** 规范化后的工作区目录（默认模式）或 `ws:<id>`（perWorkspace 模式）。 */
+    scopeKey: string;
+    firstSeen: number;
+    lastSeen: number;
+}
+export declare class ScopeRegistry {
+    private readonly cfg;
+    private ready;
+    constructor(cfg: DbConfig);
+    /**
+     * 记录一次 scope 使用：新建数据集时调用，已存在则刷新 `last_seen`。
+     * 目录库要么与业务库同一个连接，要么是同目录下的兄弟文件，
+     * 因此这里的失败一律向上抛 —— 静默吞掉会让工作区从设置页里凭空消失。
+     */
+    record(scopeKey: string): Promise<void>;
+    /** 全部已知工作区，按最近使用倒序。 */
+    list(): Promise<ScopeEntry[]>;
+    /**
+     * 该 scope 是否已知。写操作的准入校验：设置页的请求带不到会话上下文，
+     * 若放行任意字符串，浏览器就能凭空造工作区、造库文件。
+     */
+    has(scopeKey: string): Promise<boolean>;
+    /** 目录库连接：幂等建表，且只回填一次。 */
+    private catalog;
+    /**
+     * 回填：`perWorkspace=true` 时目录库里没有 `datasets` 表，语句会失败 ——
+     * 那是预期情况，此时注册表本就只靠 `record()` 累积，静默跳过即可。
+     */
+    private backfill;
+}
+export declare function createScopeRegistry(cfg: DbConfig): ScopeRegistry;

package/lib/scope.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 作用域与路径解析（设计文档 §2.4 / §7.4）。
+ *
+ * - scopeKey：默认取调用 agent 的会话工作目录（规范化后的绝对路径），即
+ *   `exec.agent.session.header.cwd`（`SessionHeader`）；`perWorkspace` 时提升为
+ *   `WorkspaceId`（`ws:<id>`），不可用时回落 cwd。
+ * - 拿不到会话 cwd 时 fail-loud（抛 `ScopeError`）：不拿 `process.cwd()` 顶替，
+ *   否则数据集会静默登记到 dsh 进程的启动目录。
+ * - 路径：导入文件必须解析后落在 scope 目录内（防 `../` 穿越）+ 扩展名白名单。
+ */
+import type { ToolExec } from './tooling';
+export interface ScopeContext {
+    /** 数据集归属键（写入 `datasets.scope_key`）。 */
+    scopeKey: string;
+    /** 解析相对路径用的工作区目录。 */
+    cwd: string;
+    /** `perWorkspace` 模式下的 WorkspaceId。 */
+    workspaceId?: string;
+}
+export declare const FILE_EXTENSIONS: readonly [".xlsx", ".xls", ".csv"];
+export declare const DEFAULT_SCOPE = "default";
+export declare class ScopeError extends Error {
+    readonly code = "SCOPE_ERROR";
+    constructor(message: string);
+}
+/** 规范化目录：解析为绝对路径，并在 Windows 上把盘符小写化（便于比较）。 */
+export declare function normalizeDirectory(input: string): string;
+/**
+ * 目录的文件系统身份：`realpath` 后再规范化。
+ *
+ * Windows 的 junction / 符号链接、macOS 的 `/var` → `/private/var` 都会让纯词法
+ * 比较误判归属，因此 scope 目录与导入目标一律按文件系统身份比较。与 dsh 的
+ * `canonicalPath`（packages/sandbox/sandbox/src/roots.ts）同思路：用
+ * `realpathSync.native` 逐段跟随链接；路径不存在时原样返回，由后续的存在性校验
+ * （`assertReadableFile`）给出真正的错误。
+ */
+export declare function canonicalDirectory(input: string): string;
+/**
+ * 从一次工具执行解析 scope。
+ *
+ * 拿不到会话 cwd 时 fail-loud（抛 `ScopeError`）：宁可让这次调用失败，也不能静默用
+ * `process.cwd()` 顶替 —— 后者是 dsh 进程的启动目录，数据集会登记到错误的工作区
+ * （换回正确 cwd 后 `dataset_list` 就看不见它们）。
+ * `perWorkspace` 且拿不到 WorkspaceId 时仍用 cwd。
+ */
+export declare function resolveScope(ctx: unknown, cfg: {
+    perWorkspace: boolean;
+}, exec: ToolExec): Promise<ScopeContext>;
+/** target 是否位于 baseDir 之内（含子目录）。 */
+export declare function isInside(baseDir: string, target: string): boolean;
+/** 解析导入路径：相对路径以 cwd 为基，越界或扩展名不在白名单即拒绝。 */
+export declare function resolveInputFile(cwd: string, input: string): string;
+/** 读取前校验：必须是普通文件、非空且不超过 `maxBytes`。 */
+export declare function assertReadableFile(path: string, maxBytes: number): Promise<{
+    size: number;
+}>;

package/lib/sql.d.ts

@@ -0,0 +1,133 @@
+/**
+ * 只读校验器 + 结构化查询拼装 + 标识符引号化（设计文档 §7.1 / §7.3）。
+ *
+ * 参考实现的「禁词表」会误伤字符串字面量（如 `WHERE name='DROP'`），这里改为五步校验：
+ * 1. 按引号状态机剥离 `--` 与 `/* *\/` 注释（不动字符串字面量）；
+ * 2. 把字符串字面量内容置空后再扫分号，拒绝多语句；
+ * 3. 首关键字白名单 `{ SELECT, WITH, EXPLAIN }`；
+ * 4. 顶层关键字扫描（命中写/DDL/事务关键字即拒绝，因此 `WITH … DELETE` 也会被拦下）；
+ * 5. 表引用必须落在当前 scope 已登记的表名集合内；
+ * 6. 未显式声明 `LIMIT` 时补 `maxQueryRows`（有 `OFFSET` 无 `LIMIT` 直接拒绝）。
+ */
+export declare class SqlError extends Error {
+    readonly code = "INVALID_SQL";
+    constructor(message: string);
+}
+/** 标识符双引号包裹，内部 `"` 转义为 `""`（列名保留原名/中文）。 */
+export declare function quoteIdentifier(name: string): string;
+/**
+ * 剥离注释，保留字符串字面量与引号标识符内的原样内容。
+ * 逐个扫描字符，按 `'` / `"` / `` ` `` 的状态机跳过引号区域。
+ */
+export declare function stripComments(sql: string): string;
+/** 把单引号字符串字面量的内容替换为空格（保留引号与长度），供关键字扫描使用。 */
+export declare function blankStringLiterals(sql: string): string;
+/**
+ * 把模型书写的 `ds` 别名替换为数据集的物理表名。
+ *
+ * 模型拿不到（也不该拿到）物理表名，因此原始 SQL 用保留别名 `ds` 指代本数据集；
+ * 只替换裸标识符，引号与字符串字面量内部不受影响。
+ */
+export declare function substituteDatasetAlias(sql: string, tableName: string): string;
+/** 提取 `FROM` / `JOIN` 之后的表名（跳过子查询 `( … )`）。 */
+export declare function extractTableReferences(sql: string): string[];
+export interface ReadOnlyQueryOptions {
+    /** 当前 scope 已登记的物理表名集合。 */
+    allowedTables: Iterable<string>;
+    /** 未显式声明 LIMIT 时补上的行数上限。 */
+    maxRows: number;
+}
+/** 一条语句解析出的 `LIMIT` / `OFFSET`（只认字面量整数，参数化写法交给调用方）。 */
+export interface LimitClause {
+    limit: number;
+    offset: number;
+}
+/** 解析 `LIMIT n [OFFSET m | , m]`；只有 OFFSET 没有 LIMIT 时抛错（SQLite 要求 LIMIT 在前）。 */
+export declare function parseLimitClause(blanked: string): LimitClause | undefined;
+/** 校验后的只读语句：分页/计数都从 `baseSql` 派生。 */
+export interface NormalizedQuery {
+    /** 去掉注释与尾部分号、已通过关键字与表引用校验的语句（仍可能带模型声明的 LIMIT）。 */
+    stripped: string;
+    /** 与 `stripped` **等长**、字符串字面量置空的版本（关键字扫描用）。 */
+    blanked: string;
+    /** 首关键字：`SELECT` / `WITH` / `EXPLAIN`。 */
+    leading: string;
+    /** 模型显式声明的 LIMIT/OFFSET。 */
+    limit?: LimitClause;
+}
+/**
+ * 只读校验的前五步（设计文档 §5 的 1–5），不做 LIMIT 补全。
+ * 校验器只在这里收紧一次，派生的 count/page 语句都建立在它的输出上。
+ */
+export declare function normalizeReadOnlyQuery(sql: string, options: ReadOnlyQueryOptions): NormalizedQuery;
+/**
+ * 校验并规范化一条只读 SQL。返回值是可直接执行的单语句（已补 LIMIT）。
+ * 任何不合规都抛 `SqlError`。
+ */
+export declare function validateReadOnlyQuery(sql: string, options: ReadOnlyQueryOptions): string;
+/** `where` 是模型提供的布尔表达式片段（不含 WHERE 关键字），做同样的收紧校验。 */
+export declare function validateWhereExpression(expression: string): string;
+/** `orderBy` 形如 `单价 DESC, 名称`，逐项校验并引号化。 */
+export declare function validateOrderBy(expression: string): string;
+export interface StructuredQuery {
+    table: string;
+    columns?: string[];
+    where?: string;
+    orderBy?: string;
+    limit?: number;
+    offset?: number;
+    /** 该数据集已登记的列名（不含系统列之外的任意标识符）。 */
+    allowedColumns: string[];
+    maxRows: number;
+}
+/** 结构化查询的骨架：不带 LIMIT 的基础语句 + 稳定排序（总是以 `_row_id` 兜底）。 */
+export interface StructuredPlan {
+    baseSql: string;
+    orderBy: string;
+}
+/**
+ * 拼装结构化查询的骨架（插件自己拼 SQL，天然安全，作为推荐路径）。
+ * 排序恒定追加 `_row_id` 兜底键，保证翻页不重不漏（设计文档 §6）。
+ */
+export declare function buildStructuredPlan(query: StructuredQuery): StructuredPlan;
+/** 拼装结构化查询（插件自己拼 SQL，天然安全，作为推荐路径）。 */
+export declare function buildStructuredQuery(query: StructuredQuery): {
+    sql: string;
+    params: unknown[];
+};
+/** 一条可分页的只读查询计划。三条语句都建立在**已校验**的基础语句之上。 */
+export interface QueryPlan {
+    /** 已校验、已切掉模型声明的 LIMIT/OFFSET 与 ORDER BY 的基础语句。 */
+    baseSql: string;
+    /** 模型（或结构化参数）给出的排序项，已引号化；可空。 */
+    baseOrder?: string;
+    /** 兜底排序键（通常 `_row_id`）；拿不到时为空，此时不保证翻页稳定。 */
+    tie?: string;
+    /** `SELECT COUNT(*) … FROM (<baseSql>)`。 */
+    countSql: string;
+    /** 默认排序下的分页语句：`… ORDER BY … LIMIT ? OFFSET ?`。 */
+    pageSql: string;
+    /** 该计划能服务的最大行数（模型声明的 LIMIT 与 maxRows 取小）。 */
+    rowCap: number;
+    /** 模型是否显式声明了 LIMIT（未声明时视图上限另按 maxViewRows 计算）。 */
+    declaredLimit?: number;
+    /** 模型声明的 OFFSET：只影响它看到的片段，视图始终从第一行开始。 */
+    previewOffset: number;
+    /** 排序是否稳定：false 时前端禁止深翻页。 */
+    stable: boolean;
+    /** EXPLAIN 语句：不产生视图，也不分页。 */
+    explain: boolean;
+}
+/** 按「基础语句 + 排序项 + 兜底键」拼分页语句。 */
+export declare function composePagedSql(plan: Pick<QueryPlan, 'baseSql' | 'baseOrder' | 'tie'>): string;
+/** 由结构化参数派生查询计划（排序恒定以 `_row_id` 兜底）。 */
+export declare function planStructuredQuery(query: StructuredQuery): QueryPlan;
+/**
+ * 由模型书写的原始 SQL 派生查询计划。
+ *
+ * 基础语句先过 `normalizeReadOnlyQuery`（含表引用白名单），随后：
+ * 1. 切掉尾部 `LIMIT/OFFSET` —— 分页由视图接管，模型声明的 LIMIT 降级为行数上限；
+ * 2. 只有「单表 + 无 GROUP BY/DISTINCT + 非复合查询」时才补 `_row_id` 兜底排序，
+ *    其余情况保留模型自己的 ORDER BY，并把 `stable` 记为 false。
+ */
+export declare function planRawQuery(sql: string, options: ReadOnlyQueryOptions): QueryPlan;

package/lib/store.d.ts

@@ -0,0 +1,174 @@
+/**
+ * 数据集元数据（替代参考实现的 drizzle `dataset_metadata`）+ 归属断言。
+ *
+ * 设计文档 §5.3：`datasets` 表是插件自有的元数据表，物理表名只在本模块生成与持有，
+ * 对外只暴露 `datasetId` / 登记名。所有读写都带 `scope_key` 过滤（`assertOwned`）。
+ */
+import { type Database } from './db';
+import type { DataSourceStore } from './datasource/source-store';
+import { type ScopeRegistry } from './scope-registry';
+import type { ColumnInfo } from './parse';
+import type { ScopeContext } from './scope';
+import type { ToolExec } from './tooling';
+import type { ViewRegistry } from './view';
+/** 插件配置（结构子集由 index.ts 的 `Config` 复用，避免 tools → index 的类型循环）。 */
+export interface DataConfig {
+    /** libSQL 库路径；空 → `$DSH_HOME/lh-data/data.db`。 */
+    dbPath: string;
+    /** 非空则覆盖 dbPath，可为 `file:` 或 `libsql://`。 */
+    dbUrl: string;
+    /** 远程 Turso token；建议留空并走 `TURSO_AUTH_TOKEN`。 */
+    authToken: string;
+    /** true 时 scope 用 WorkspaceId 且每个工作区独立库文件。 */
+    perWorkspace: boolean;
+    requireApprovalForWrites: boolean;
+    allowRawSql: boolean;
+    maxFileBytes: number;
+    maxInsertRows: number;
+    maxQueryRows: number;
+    batchSize: number;
+    backgroundThresholdRows: number;
+    previewSampleRows: number;
+    readOnly: boolean;
+    /** 视图模式：auto（超阈值才建视图）/ always / never。 */
+    viewMode: 'auto' | 'always' | 'never';
+    viewThresholdRows: number;
+    viewThresholdBytes: number;
+    previewRows: number;
+    previewStrategy: 'head' | 'head-tail';
+    previewCellChars: number;
+    previewColumns: number;
+    summaryEnabled: boolean;
+    summaryMaxColumns: number;
+    summaryMaxTextColumns: number;
+    defaultPageSize: number;
+    maxPageSize: number;
+    maxViewRows: number;
+    viewRoutePrefix: string;
+    /** 是否挂载设置页管理接口（关闭后路由不注册，前端显示不可用）。 */
+    adminEnabled: boolean;
+    /** 管理接口请求体字节上限。 */
+    adminMaxBodyBytes: number;
+    /** 聚合列表扫描的数据集上限，超限即截断并提示。 */
+    adminMaxDatasets: number;
+    /** 是否启用数据源（关闭后不注册 datasource_* 工具与 /sources 接口）。 */
+    datasourceEnabled: boolean;
+    /** 远端表分块拉取的行数。 */
+    datasourceFetchBatchSize: number;
+    /** 连接 / 连通性测试的超时毫秒数。 */
+    datasourceConnectTimeoutMs: number;
+    /** 单次导入的行数上限，0 表示不限。 */
+    datasourceMaxImportRows: number;
+    /** 数据源密码的加密密钥；空 → 环境变量 LH_DATA_ENCRYPT_KEY。 */
+    datasourceEncryptKey: string;
+}
+export type DatasetStatus = 'importing' | 'ready' | 'failed';
+export interface DatasetRecord {
+    id: string;
+    scopeKey: string;
+    name: string;
+    tableName: string;
+    sourcePath: string | null;
+    /** 来自数据源时记录数据源 id；文件导入为 null。 */
+    sourceId: string | null;
+    /** 来自数据源时的定位串 `<schema>.<table>`（脱敏，不含凭据）。 */
+    sourceRef: string | null;
+    /** 用户可编辑的说明（设置页「改描述」的落点）；未填为 null。 */
+    description: string | null;
+    rowCount: number;
+    columns: ColumnInfo[];
+    status: DatasetStatus;
+    error: string | null;
+    createdAt: number;
+    updatedAt: number;
+}
+export declare class DatasetError extends Error {
+    readonly code = "DATASET_ERROR";
+    constructor(message: string);
+}
+/** 物理表名形状：`d_<scopeHash8>_<base40>_<ts36>`。 */
+export declare const PHYSICAL_TABLE_PATTERN: RegExp;
+export declare function assertPhysicalTableName(tableName: string): void;
+/** 物理表名生成：只由插件调用，去掉参考实现的 userId，改用 scope 哈希。 */
+export declare function generateTableName(base: string, scopeHash: string): string;
+export declare function makeDatasetId(): string;
+export declare class DatasetStore {
+    private readonly cfg;
+    /** 工作区注册表（跨工作区聚合枚举来源）；默认随配置自动创建。 */
+    readonly scopes: ScopeRegistry;
+    private readonly initialized;
+    constructor(cfg: DataConfig, 
+    /** 工作区注册表（跨工作区聚合枚举来源）；默认随配置自动创建。 */
+    scopes?: ScopeRegistry);
+    /** 该 scope 对应的库连接（幂等建表 + 增量迁移）。 */
+    database(scopeKey: string): Promise<Database>;
+    list(scopeKey: string): Promise<DatasetRecord[]>;
+    /** 按 datasetId 或登记名查找；找不到返回 undefined（不抛错）。 */
+    find(scopeKey: string, reference: string): Promise<DatasetRecord | undefined>;
+    /** 当前 scope 已登记的物理表名集合（dataset_query 的 sql 白名单）。 */
+    tableNames(scopeKey: string): Promise<string[]>;
+    /** 解析句柄 + 归属断言（defense-in-depth）。 */
+    require(scopeKey: string, reference: string, options?: {
+        requireReady?: boolean;
+    }): Promise<DatasetRecord>;
+    /** scope 内唯一的名字：已存在则追加 `_2` / `_3`。 */
+    uniqueName(scopeKey: string, name: string): Promise<string>;
+    create(record: DatasetRecord): Promise<void>;
+    update(scopeKey: string, id: string, patch: Partial<Pick<DatasetRecord, 'name' | 'rowCount' | 'columns' | 'status' | 'error' | 'sourcePath' | 'sourceId' | 'sourceRef' | 'description'>>): Promise<void>;
+    remove(scopeKey: string, id: string): Promise<void>;
+}
+export declare function createStore(cfg: DataConfig): DatasetStore;
+/** 后台任务注册表的最小视图（`ctx.jobs` 可选依赖）。 */
+export interface JobRegistryLike {
+    start(spec: {
+        kind: string;
+        label: string;
+        owner?: unknown;
+        run(): {
+            cancel(reason?: string): void;
+            done: Promise<unknown>;
+        };
+    }): string;
+}
+/**
+ * `dsh-host-webserver` 的最小视图（duck-typed，避免依赖 dsh 运行时）。
+ * 缺失时（CLI / TUI 剖面）不注册任何路由，视图能力整体降级。
+ */
+export interface WebServerLike {
+    register(route: {
+        kind: 'exact' | 'prefix';
+        path: string;
+        handler(request: unknown, response: unknown): void | Promise<void>;
+    }): () => void;
+}
+/** `dsh-client-connection` 的最小视图：给自建路由复用平台鉴权。 */
+export interface ConnectionLike {
+    /** 通过返回 undefined；否则返回应写入的 HTTP 状态码。 */
+    requestRejection(request: unknown): 401 | 403 | undefined;
+}
+/** 注入给工具的运行时依赖。 */
+export interface DataServices {
+    cfg: DataConfig;
+    store: DatasetStore;
+    /** 数据源登记表（catalog 库，全局共享）。 */
+    sources: DataSourceStore;
+    /** 解析一次调用的工作区；拿不到会话 cwd 时会 reject（`ScopeError`）。 */
+    scopeOf(exec: ToolExec): Promise<ScopeContext>;
+    /** 可选：`ctx.jobs` 不可用时后台导入降级为前台执行。 */
+    jobs?: JobRegistryLike;
+    /** 结果视图注册中心（设计文档 §6）。 */
+    views?: ViewRegistry;
+    /** 可选：HTTP 路由宿主；缺失即不提供前端分页。 */
+    webServer?: WebServerLike;
+    /** 可选：连接服务；缺失即不注册路由（自建路由必须有鉴权手段）。 */
+    connection?: ConnectionLike;
+}
+export interface ResolvedDataset {
+    scope: ScopeContext;
+    record: DatasetRecord;
+    db: Database;
+}
+/** 工具的统一入口：解析 scope → 断言归属 → 拿到库连接。 */
+export declare function resolveDataset(services: DataServices, exec: ToolExec, reference: string, options?: {
+    requireReady?: boolean;
+}): Promise<ResolvedDataset>;

package/lib/table.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 物理表的建/插/删 —— 移植自 `agentic-data-mini` 的 `src/lib/utils/tableManager.ts`。
+ *
+ * 保留的关键行为：`_row_id` 自增主键 + 业务列 + `_uploaded_at`；批量插入 100 行/批，
+ * 并按列类型做转换（boolean→0/1、numeric→Number、date→ISO、对象/数组→JSON）。
+ * 插件侧新增：批次之间的 `signal.throwIfAborted()` 检查点。
+ */
+import type { Database, Row } from './db';
+import type { ColumnInfo, ColumnType } from './parse';
+/** 系统列：插入/更新时必须剔除。 */
+export declare const SYSTEM_COLUMNS: readonly ["_row_id", "_uploaded_at"];
+export declare const DEFAULT_BATCH_SIZE = 100;
+export declare function columnTypeToSqlite(type: ColumnType): string;
+export declare function createDatasetTable(db: Database, tableName: string, columns: ColumnInfo[]): Promise<void>;
+/** 按列类型转换一个值（批量插入与单行更新共用）。 */
+export declare function coerceValue(raw: unknown, type: ColumnType): unknown;
+export interface InsertOptions {
+    batchSize?: number;
+    signal?: AbortSignal;
+}
+/** 批量插入，返回实际插入行数；每批之间检查取消信号。 */
+export declare function insertRows(db: Database, tableName: string, columns: ColumnInfo[], rows: Record<string, unknown>[], options?: InsertOptions): Promise<number>;
+export declare function dropDatasetTable(db: Database, tableName: string): Promise<void>;
+export declare function countRows(db: Database, tableName: string): Promise<number>;
+/** 剔除系统列，并报告未登记的列（写操作要明确拒绝未知列）。 */
+export declare function sanitizeRowData(data: Record<string, unknown>, columns: ColumnInfo[]): {
+    values: Record<string, unknown>;
+    unknownColumns: string[];
+};
+/** 单行更新：按 `_row_id` 定位，返回受影响行数。 */
+export declare function updateRow(db: Database, tableName: string, columns: ColumnInfo[], rowId: number, data: Record<string, unknown>): Promise<number>;
+/** 单行删除：按 `_row_id` 定位，返回受影响行数。 */
+export declare function deleteRow(db: Database, tableName: string, rowId: number): Promise<number>;
+/** 读取查询结果（列信息从首行推导）。 */
+export declare function selectRows(db: Database, sql: string, params?: unknown[]): Promise<{
+    rows: Row[];
+    columns: string[];
+}>;