dsh-lh-data 0.1.0

package/src/render.ts

@@ -0,0 +1,294 @@
+/**
+ * 模型可见文本的渲染（对齐 `dsh-lh-judge` 的 render.ts 定位）。
+ *
+ * 约定：`output.render` 只做纯函数渲染，不读状态；物理表名绝不出现在这里。
+ */
+
+import type { Row } from './db'
+import type { ColumnInfo } from './parse'
+import { truncateCell, type ColumnSummary } from './preview'
+
+export interface DatasetListItem {
+  datasetId: string
+  name: string
+  rowCount: number
+  columnCount: number
+  status: string
+  sourcePath: string | null
+  createdAt: number
+}
+
+export const MAX_RENDER_CELL = 40
+export const MAX_RENDER_ROWS = 50
+
+export function truncateText(text: string, max: number): string {
+  return text.length <= max ? text : `${text.slice(0, Math.max(0, max - 1))}…`
+}
+
+/** 单元格转义：去掉换行与竖线，避免破坏 markdown 表格。 */
+export function formatValue(value: unknown): string {
+  if (value === null || value === undefined) return ''
+  if (value instanceof Uint8Array) return `<${value.length} bytes>`
+  if (typeof value === 'object') {
+    try {
+      return truncateText(JSON.stringify(value), MAX_RENDER_CELL)
+    } catch {
+      return '[object]'
+    }
+  }
+  return truncateText(String(value), MAX_RENDER_CELL)
+}
+
+function escapeCell(text: string): string {
+  return text.replace(/\|/g, '\\|').replace(/\r?\n/g, ' ')
+}
+
+function renderTable(header: string[], rows: string[][]): string {
+  if (header.length === 0) return '(无内容)'
+  const lines = [
+    `| ${header.map(escapeCell).join(' | ')} |`,
+    `| ${header.map(() => '---').join(' | ')} |`,
+    ...rows.map(row => `| ${row.map(escapeCell).join(' | ')} |`),
+  ]
+  return lines.join('\n')
+}
+
+export function formatTimestamp(epochMs: number): string {
+  if (!Number.isFinite(epochMs) || epochMs <= 0) return '-'
+  return new Date(epochMs).toISOString().replace('T', ' ').slice(0, 19)
+}
+
+export function renderDatasetList(items: DatasetListItem[]): string {
+  if (items.length === 0) return '当前工作区还没有数据集。用 `dataset_import` 导入工作区内的 .xlsx / .xls / .csv 文件。'
+  const rows = items.map(item => [
+    item.datasetId,
+    item.name,
+    String(item.rowCount),
+    String(item.columnCount),
+    item.status,
+    item.sourcePath ?? '-',
+    formatTimestamp(item.createdAt),
+  ])
+  return `当前工作区共有 ${items.length} 个数据集：\n\n${renderTable(
+    ['datasetId', '名称', '行数', '列数', '状态', '来源文件', '创建时间'],
+    rows,
+  )}`
+}
+
+export function renderColumns(columns: ColumnInfo[]): string {
+  if (columns.length === 0) return '(该数据集没有列信息)'
+  const rows = columns.map(column => [
+    column.name,
+    column.type,
+    column.nullable ? '是' : '否',
+    column.sample.map(formatValue).filter(value => value.length > 0).slice(0, 3).join(' / ') || '-',
+    column.description ?? '-',
+  ])
+  return renderTable(['列名', '类型', '可空', '样例', '说明'], rows)
+}
+
+export function renderRows(columns: string[], rows: Row[], maxRows: number = MAX_RENDER_ROWS): string {
+  if (rows.length === 0) return '(没有匹配的行)'
+  const shown = rows.slice(0, maxRows)
+  const body = shown.map(row => columns.map(column => formatValue(row[column])))
+  const table = renderTable(columns, body)
+  return rows.length > shown.length
+    ? `${table}\n\n（仅展示前 ${shown.length} 行，共 ${rows.length} 行）`
+    : table
+}
+
+// ── 查询结果片段（设计文档 §5.3） ────────────────────────────────────────
+
+/** 片段渲染的输入（结构化而非 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 }
+}
+
+function renderPreviewTable(columns: string[], rows: Row[], maxCell: number): string {
+  const body = rows.map(row => columns.map(column => {
+    const { text } = truncateCell(row[column], maxCell)
+    return text
+  }))
+  return renderTable(columns, body)
+}
+
+function formatSummaryValue(value: number | string | null | undefined): string {
+  if (value === null || value === undefined) return '-'
+  if (typeof value === 'number') return String(Number(value.toFixed(4)))
+  return truncateText(String(value), 24)
+}
+
+function renderSummaryLine(summary: ColumnSummary, totalRows: number): string {
+  const label = `${summary.name} ${summary.type}`
+  if (summary.type === 'boolean') {
+    return `- ${label}：真 ${summary.trueCount ?? 0} / 非空 ${summary.count} / 共 ${totalRows}`
+  }
+  if (summary.type === 'text') {
+    const distinct = summary.distinct ?? 0
+    const top = summary.top
+    if (top !== undefined && top.length > 0) {
+      const parts = top.map(entry => `${entry.value} ${entry.count}`).join(' / ')
+      return `- ${label}：distinct ${distinct} → ${parts}${distinct > top.length ? ' …' : ''}`
+    }
+    return `- ${label}：distinct ${distinct}（取值过于分散，已省略明细）/ 非空 ${summary.count}`
+  }
+  const parts = [`min ${formatSummaryValue(summary.min)}`, `max ${formatSummaryValue(summary.max)}`]
+  if (summary.type === 'numeric') {
+    parts.push(`avg ${formatSummaryValue(summary.avg)}`, `sum ${formatSummaryValue(summary.sum)}`)
+  }
+  parts.push(`空 ${Math.max(0, totalRows - summary.count)}`)
+  return `- ${label}：${parts.join(' / ')}`
+}
+
+/**
+ * 渲染查询结果的模型可见片段：行数概览 + 少量预览行 + 类型化摘要 + 视图提示。
+ * 目标是把上下文占用压到常量级，同时保留「足以下结论」的统计信息。
+ */
+export function renderQueryPreview(input: QueryPreviewInput): string {
+  const { preview } = input
+  const scope = input.matchedRows === input.totalRows
+    ? `共 ${input.totalRows} 行`
+    : `命中 ${input.matchedRows} 行（本次可服务 ${input.totalRows} 行）`
+  const lines: string[] = [
+    `数据集 ${input.name}（${input.datasetId}）：${scope} × ${input.columnCount} 列，返回 ${preview.rows.length} 行预览。`,
+    '',
+  ]
+
+  if (preview.rows.length === 0) {
+    lines.push('(没有匹配的行)')
+  } else if (preview.gap && preview.headCount > 0 && preview.headCount < preview.rows.length) {
+    lines.push(
+      renderPreviewTable(preview.columns, preview.rows.slice(0, preview.headCount), MAX_RENDER_CELL),
+      '',
+      `（… 省略 ${preview.skipped} 行 …）`,
+      '',
+      renderPreviewTable(preview.columns, preview.rows.slice(preview.headCount), MAX_RENDER_CELL),
+    )
+  } else {
+    lines.push(renderPreviewTable(preview.columns, preview.rows, MAX_RENDER_CELL))
+  }
+
+  if (preview.columnTruncated) {
+    lines.push('', `（仅展示前 ${preview.columns.length} 列，另有 ${preview.hiddenColumns} 列）`)
+  }
+
+  if (input.summary.length > 0) {
+    lines.push('', '摘要：', ...input.summary.map(summary => renderSummaryLine(summary, input.totalRows)))
+  }
+
+  if (input.view !== undefined) {
+    lines.push(
+      '',
+      `完整结果（${input.totalRows} 行）已在结果表格中展示${input.view.stable ? '' : '（该查询未声明稳定排序，仅展示首页）'}。`,
+      '若需据此下结论，请用更精确的 where 或聚合 SQL 再查一次；不要试图逐页读取全量。',
+    )
+  } else if (input.truncated) {
+    lines.push('', '（结果已按上限截断；需要完整数据请用更精确的 where 或聚合查询）')
+  }
+
+  return lines.join('\n')
+}
+
+// ── 数据源（脱敏：不含密码、不含远端凭据） ──────────────────────────────
+
+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 function renderSourceList(items: SourceListItem[]): string {
+  if (items.length === 0) return '还没有登记任何数据源。在「设置 → 数据集 → 数据源」里新建，或用管理接口登记。'
+  const rows = items.map(item => [
+    item.id,
+    item.name,
+    item.type,
+    `${item.host}:${String(item.port)}`,
+    item.database,
+    item.status,
+    item.lastError ?? '-',
+    item.lastCheckedAt === null ? '-' : formatTimestamp(item.lastCheckedAt),
+  ])
+  return `共 ${items.length} 个数据源：\n\n${renderTable(
+    ['sourceId', '名称', '类型', '地址', '库名', '状态', '最近错误', '最近检测'],
+    rows,
+  )}`
+}
+
+export function renderSourceTables(sourceName: string, schema: string | null, items: SourceTableItem[]): string {
+  if (items.length === 0) return `数据源「${sourceName}」${schema === null ? '' : `（schema ${schema}）`}里没有匹配的表。`
+  const rows = items.map(item => [
+    item.tableName,
+    item.schemaName ?? '-',
+    item.rowCount < 0 ? '未知' : String(item.rowCount),
+    String(item.columnCount),
+    item.primaryKey ?? '-',
+  ])
+  return `数据源「${sourceName}」共 ${items.length} 张表：\n\n${renderTable(['表名', 'schema', '估计行数', '列数', '主键'], rows)}`
+}
+
+export interface ConnectionTestView {
+  name: string
+  success: boolean
+  latency: number
+  version: string | null
+  error: string | null
+}
+
+export function renderConnectionTest(view: ConnectionTestView): string {
+  if (view.success) {
+    const version = view.version === null ? '' : `，版本 ${view.version}`
+    return `数据源「${view.name}」连接成功（${view.latency}ms${version}）。`
+  }
+  return `数据源「${view.name}」连接失败（${view.latency}ms）：${view.error ?? '未知错误'}`
+}
+
+/** 包装成 dsh 的回注用户消息（带 source 标记，便于去重/追踪）。 */
+export interface UserMessage {
+  role: 'user'
+  content: { type: 'text'; text: string }[]
+  source: { kind: 'plugin'; plugin: string }
+}
+
+export function toUserMessage(text: string, plugin: string): UserMessage {
+  return {
+    role: 'user',
+    content: [{ type: 'text', text }],
+    source: { kind: 'plugin', plugin },
+  }
+}

package/src/scope-registry.ts

@@ -0,0 +1,111 @@
+/**
+ * 工作区（scope）注册表 —— 设置页「聚合展示全部工作区」的枚举来源。
+ *
+ * 为什么需要这张表：`perWorkspace=false`（默认）时所有 scope 共用一个库文件，
+ * `SELECT DISTINCT scope_key FROM datasets` 就能枚举；但 `perWorkspace=true`
+ * 时每个 scope 是独立的 `<hash>.db`，库文件名是 scope 的单向哈希，
+ * **没有任何办法反查「这台机器上有哪些工作区」**。
+ *
+ * 因此把见过的 scope 记在**目录库**里：一个不做 scope 分片的固定库
+ * （`perWorkspace=false` 时与业务库是同一个文件，不额外占地方）。
+ *
+ * 与 `DatasetStore` 分开，是为了让 store 保持单一职责（数据集元数据）并守住
+ * 200 行的类体积上限。
+ */
+
+import { resolveCatalogDatabase, type Database, type DbConfig } from './db'
+
+const CATALOG_SQL = `
+CREATE TABLE IF NOT EXISTS dataset_scopes (
+  scope_key TEXT PRIMARY KEY,
+  first_seen INTEGER NOT NULL,
+  last_seen INTEGER NOT NULL
+);
+`
+
+/** 把已登记数据集的 scope 补进注册表（升级前遗留的数据靠它进来）。 */
+const BACKFILL_SQL = `
+INSERT OR IGNORE INTO dataset_scopes (scope_key, first_seen, last_seen)
+SELECT DISTINCT scope_key, ?, ? FROM datasets
+`
+
+export interface ScopeEntry {
+  /** 规范化后的工作区目录（默认模式）或 `ws:<id>`（perWorkspace 模式）。 */
+  scopeKey: string
+  firstSeen: number
+  lastSeen: number
+}
+
+export class ScopeRegistry {
+  private ready = false
+
+  constructor(private readonly cfg: DbConfig) {}
+
+  /**
+   * 记录一次 scope 使用：新建数据集时调用，已存在则刷新 `last_seen`。
+   * 目录库要么与业务库同一个连接，要么是同目录下的兄弟文件，
+   * 因此这里的失败一律向上抛 —— 静默吞掉会让工作区从设置页里凭空消失。
+   */
+  async record(scopeKey: string): Promise<void> {
+    const db = await this.catalog()
+    const now = Date.now()
+    await db
+      .prepare(
+        `INSERT INTO dataset_scopes (scope_key, first_seen, last_seen) VALUES (?, ?, ?)
+         ON CONFLICT(scope_key) DO UPDATE SET last_seen = excluded.last_seen`,
+      )
+      .run(scopeKey, now, now)
+  }
+
+  /** 全部已知工作区，按最近使用倒序。 */
+  async list(): Promise<ScopeEntry[]> {
+    const db = await this.catalog()
+    const rows = await db
+      .prepare('SELECT scope_key, first_seen, last_seen FROM dataset_scopes ORDER BY last_seen DESC')
+      .all()
+    return rows.map(row => ({
+      scopeKey: String(row.scope_key),
+      firstSeen: Number(row.first_seen ?? 0),
+      lastSeen: Number(row.last_seen ?? 0),
+    }))
+  }
+
+  /**
+   * 该 scope 是否已知。写操作的准入校验：设置页的请求带不到会话上下文，
+   * 若放行任意字符串，浏览器就能凭空造工作区、造库文件。
+   */
+  async has(scopeKey: string): Promise<boolean> {
+    const db = await this.catalog()
+    const row = await db
+      .prepare('SELECT 1 AS ok FROM dataset_scopes WHERE scope_key = ? LIMIT 1')
+      .get(scopeKey)
+    return row !== undefined
+  }
+
+  /** 目录库连接：幂等建表，且只回填一次。 */
+  private async catalog(): Promise<Database> {
+    const db = resolveCatalogDatabase(this.cfg)
+    if (this.ready) return db
+    await db.exec(CATALOG_SQL)
+    await this.backfill(db)
+    this.ready = true
+    return db
+  }
+
+  /**
+   * 回填：`perWorkspace=true` 时目录库里没有 `datasets` 表，语句会失败 ——
+   * 那是预期情况，此时注册表本就只靠 `record()` 累积，静默跳过即可。
+   */
+  private async backfill(db: Database): Promise<void> {
+    const now = Date.now()
+    try {
+      await db.prepare(BACKFILL_SQL).run(now, now)
+    } catch {
+      // 目录库里没有 datasets 表：perWorkspace 模式下正常。
+    }
+  }
+}
+
+export function createScopeRegistry(cfg: DbConfig): ScopeRegistry {
+  return new ScopeRegistry(cfg)
+}

package/src/scope.ts

@@ -0,0 +1,159 @@
+/**
+ * 作用域与路径解析（设计文档 §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 { realpathSync } from 'node:fs'
+import { stat } from 'node:fs/promises'
+import { extname, isAbsolute, relative, resolve } from 'node:path'
+import type { ToolExec } from './tooling'
+
+export interface ScopeContext {
+  /** 数据集归属键（写入 `datasets.scope_key`）。 */
+  scopeKey: string
+  /** 解析相对路径用的工作区目录。 */
+  cwd: string
+  /** `perWorkspace` 模式下的 WorkspaceId。 */
+  workspaceId?: string
+}
+
+export const FILE_EXTENSIONS = ['.xlsx', '.xls', '.csv'] as const
+
+export const DEFAULT_SCOPE = 'default'
+
+export class ScopeError extends Error {
+  readonly code = 'SCOPE_ERROR'
+
+  constructor(message: string) {
+    super(message)
+    this.name = 'ScopeError'
+  }
+}
+
+/** 规范化目录：解析为绝对路径，并在 Windows 上把盘符小写化（便于比较）。 */
+export function normalizeDirectory(input: string): string {
+  const resolved = resolve(input)
+  return process.platform === 'win32'
+    ? resolved.replace(/^([a-zA-Z]):/, (_match, drive: string) => `${drive.toLowerCase()}:`)
+    : resolved
+}
+
+/**
+ * 目录的文件系统身份：`realpath` 后再规范化。
+ *
+ * Windows 的 junction / 符号链接、macOS 的 `/var` → `/private/var` 都会让纯词法
+ * 比较误判归属，因此 scope 目录与导入目标一律按文件系统身份比较。与 dsh 的
+ * `canonicalPath`（packages/sandbox/sandbox/src/roots.ts）同思路：用
+ * `realpathSync.native` 逐段跟随链接；路径不存在时原样返回，由后续的存在性校验
+ * （`assertReadableFile`）给出真正的错误。
+ */
+export function canonicalDirectory(input: string): string {
+  try {
+    return normalizeDirectory(realpathSync.native(input))
+  } catch {
+    return normalizeDirectory(input)
+  }
+}
+
+/**
+ * 取会话工作目录。
+ *
+ * 真实 dsh 运行时挂在 `exec.agent.session.header.cwd`（`Agent.session` 是 `Session`，
+ * cwd 属于它的 `SessionHeader`）；`session.cwd` 是早期约定的扁平形状，仅作
+ * headless / 自测兼容位保留。
+ */
+function sessionCwdOf(exec: ToolExec): string | undefined {
+  const session: unknown = exec?.agent?.session
+  if (typeof session !== 'object' || session === null) return undefined
+  const header: unknown = (session as { header?: unknown }).header
+  const fromHeader: unknown = (header as { cwd?: unknown } | null | undefined)?.cwd
+  if (typeof fromHeader === 'string' && fromHeader.trim().length > 0) return fromHeader
+  const flat: unknown = (session as { cwd?: unknown }).cwd
+  return typeof flat === 'string' && flat.trim().length > 0 ? flat : undefined
+}
+
+/** 可选能力：把 cwd 提升为 WorkspaceId（duck-typed，缺失即回落）。 */
+async function lookupWorkspaceId(ctx: unknown, cwd: string): Promise<string | undefined> {
+  const registry: unknown = (ctx as { workspaceRegistry?: unknown } | null)?.workspaceRegistry
+  if (typeof registry !== 'object' || registry === null) return undefined
+  const resolveByPath: unknown = (registry as { resolveByPath?: unknown }).resolveByPath
+  if (typeof resolveByPath !== 'function') return undefined
+  try {
+    // `WorkspaceRegistry.resolveByPath()` 是异步的，返回 `Promise<Workspace | undefined>`。
+    const found: unknown = await (resolveByPath as (path: string) => Promise<unknown>).call(registry, cwd)
+    if (typeof found === 'string') return found.length > 0 ? found : undefined
+    if (typeof found === 'object' && found !== null) {
+      const record = found as { id?: unknown; workspaceId?: unknown }
+      const id = record.id ?? record.workspaceId
+      if (typeof id === 'string' && id.length > 0) return id
+    }
+  } catch {
+    return undefined
+  }
+  return undefined
+}
+
+/**
+ * 从一次工具执行解析 scope。
+ *
+ * 拿不到会话 cwd 时 fail-loud（抛 `ScopeError`）：宁可让这次调用失败，也不能静默用
+ * `process.cwd()` 顶替 —— 后者是 dsh 进程的启动目录，数据集会登记到错误的工作区
+ * （换回正确 cwd 后 `dataset_list` 就看不见它们）。
+ * `perWorkspace` 且拿不到 WorkspaceId 时仍用 cwd。
+ */
+export async function resolveScope(
+  ctx: unknown,
+  cfg: { perWorkspace: boolean },
+  exec: ToolExec,
+): Promise<ScopeContext> {
+  const raw = sessionCwdOf(exec)
+  if (raw === undefined) {
+    throw new ScopeError('无法解析工作区目录：exec.agent.session.header.cwd 缺失（本次调用没有 agent 会话？）')
+  }
+  const cwd = canonicalDirectory(raw)
+  if (!cfg.perWorkspace) return { scopeKey: cwd, cwd }
+  const workspaceId = await lookupWorkspaceId(ctx, cwd)
+  return workspaceId === undefined ? { scopeKey: cwd, cwd } : { scopeKey: `ws:${workspaceId}`, cwd, workspaceId }
+}
+
+/** target 是否位于 baseDir 之内（含子目录）。 */
+export function isInside(baseDir: string, target: string): boolean {
+  const rel = relative(baseDir, target)
+  if (rel.length === 0 || rel.startsWith('..')) return false
+  return !isAbsolute(rel)
+}
+
+/** 解析导入路径：相对路径以 cwd 为基，越界或扩展名不在白名单即拒绝。 */
+export function resolveInputFile(cwd: string, input: string): string {
+  const raw = typeof input === 'string' ? input.trim() : ''
+  if (raw.length === 0) throw new ScopeError('path 不能为空')
+  // 两侧都取文件系统身份，保证与 canonical 化的 scope 目录可比。
+  const base = canonicalDirectory(cwd)
+  const target = canonicalDirectory(isAbsolute(raw) ? raw : resolve(base, raw))
+  if (!isInside(base, target)) throw new ScopeError(`文件必须在工作区目录内：${raw}`)
+  const ext = extname(target).toLowerCase()
+  if (!(FILE_EXTENSIONS as readonly string[]).includes(ext)) {
+    throw new ScopeError(`不支持的文件类型：${ext || '(无扩展名)'}，仅支持 ${FILE_EXTENSIONS.join(' / ')}`)
+  }
+  return target
+}
+
+/** 读取前校验：必须是普通文件、非空且不超过 `maxBytes`。 */
+export async function assertReadableFile(path: string, maxBytes: number): Promise<{ size: number }> {
+  let info
+  try {
+    info = await stat(path)
+  } catch {
+    throw new ScopeError(`文件不存在或不可读取：${path}`)
+  }
+  if (!info.isFile()) throw new ScopeError(`不是文件：${path}`)
+  if (info.size === 0) throw new ScopeError(`文件为空：${path}`)
+  if (info.size > maxBytes) throw new ScopeError(`文件过大：${info.size} 字节，上限 ${maxBytes} 字节`)
+  return { size: info.size }
+}