@hedeqiang/dsh-nl2sql 0.0.0-stage → 0.10.0

package/locale/en.json

@@ -0,0 +1 @@
+{"meta": {"title": "Data Q&A (NL2SQL)", "description": "Open Data Q&A in the sidebar to connect MySQL 5.7+, PostgreSQL or Elasticsearch (optionally over SSH), or upload CSV / Excel. After schema analysis, ask in plain language: the agent writes read-only SQL, runs it and charts the result in the conversation. Includes dashboards with global filters, drill-down and change attribution, a metric library and business knowledge, accuracy evaluation, alerts and scheduled reports, Lark / Feishu push and an @-mention bot, member scopes (data sources, viewer role, row-level rules) and audit. A setting controls what result data reaches the model (column statistics by default). Passwords live in the Harness credential store; data and logs stay in ~/.dsh/nl2sql. Turning the plugin off stops its page, tools and scheduled checks; saved data is kept."}}

package/locale/zh.json

@@ -0,0 +1 @@
+{"meta": {"title": "数据问答（NL2SQL）", "description": "在左侧栏「数据问答」中连接 MySQL 5.7+ / PostgreSQL / Elasticsearch（可经 SSH 隧道）或上传 CSV / Excel，分析表结构后用自然语言提问：Agent 写只读 SQL、执行并在对话中画图。支持看板与全局筛选、下钻与变化归因、指标库与业务知识、准确率评测、告警与定时报告、飞书推送与群内 @机器人问答、成员权限（数据源范围、只读角色、行级权限）和审计。查询结果按设置决定发给模型的内容（默认只发统计摘要）；数据源密码保存在 Harness 凭据库；数据和日志保存在本机 ~/.dsh/nl2sql。关闭插件后页面、工具和定时检查停止，已保存的数据保留。"}}

package/package.json

@@ -1,6 +1,92 @@
 {
   "name": "@hedeqiang/dsh-nl2sql",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.10.0",
+  "description": "Data Q&A (NL2SQL) for DeepSeek Harness: ask MySQL / PostgreSQL / Elasticsearch / CSV in plain language, charts, dashboards, alerts, Lark push and bot, access control.",
+  "type": "module",
+  "exports": {
+    ".": "./index.js",
+    "./client": "./lib/client.js",
+    "./locale/*.json": "./locale/*.json",
+    "./icon": "./icon.svg"
+  },
+  "files": [
+    "index.js",
+    "service/*.js",
+    "drivers.js",
+    "policy.js",
+    "filters.js",
+    "im.js",
+    "store.js",
+    "xlsx.js",
+    "analysis.js",
+    "lark-bot.js",
+    "sqlite-driver.js",
+    "sql-guard.js",
+    "lib/client.js",
+    "lib/client.echarts.js",
+    "cordis.patch.yml",
+    "locale/*.json",
+    "icon.svg",
+    "README.md",
+    "README.en.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "dependencies": {
+    "@larksuiteoapi/node-sdk": "1.76.0",
+    "@resvg/resvg-js": "2.6.2",
+    "echarts": "6.1.0",
+    "mysql2": "3.24.6",
+    "pg": "8.23.1",
+    "ssh2": "1.17.0"
+  },
+  "scripts": {
+    "build": "node scripts/build-echarts.mjs",
+    "test": "node test/run.mjs",
+    "build:client": "node scripts/build-client.mjs",
+    "test:fast": "node test/run.mjs --fast",
+    "check": "node scripts/build-client.mjs --check && node test/run.mjs --fast"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "immediately": true,
+      "inject": [
+        "@deepseek-ai/dsh-client-connection",
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-layout",
+        "@deepseek-ai/dsh-client-ui-sidebar",
+        "@deepseek-ai/dsh-client-ui-conversation",
+        "@deepseek-ai/dsh-client-ui-workspace"
+      ]
+    }
+  },
+  "license": "MIT",
+  "author": "hedeqiang <laravel_code@163.com>",
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "dsh-bundle",
+    "nl2sql",
+    "text-to-sql",
+    "bi",
+    "mysql",
+    "postgresql",
+    "elasticsearch",
+    "lark",
+    "feishu"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hedeqiang/dsh-nl2sql.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/policy.js

@@ -0,0 +1,362 @@
+import { lexSql } from './sql-guard.js'
+/**
+ * Table/column access policy and SQL identifier analysis.
+ *
+ * Policy shape (per data source):
+ *   { mode: 'all' | 'allow' | 'deny', tables: string[], hiddenColumns: string[], maskedColumns: string[] }
+ * Patterns are case-insensitive globs: `orders`, `ods_*`, `sales.*`; column
+ * patterns are `table.column` (`*.salary`, `hr_*.id_card`).
+ *
+ * Enforcement is syntactic and conservative: a statement is refused when it
+ * names a table the policy excludes, a system catalog, or a hidden column of a
+ * referenced table; hidden columns that arrive anyway (SELECT *) are dropped
+ * from the result. Database grants remain the strict boundary.
+ */
+
+export const EMPTY_POLICY = Object.freeze({ mode: 'all', tables: [], hiddenColumns: [], maskedColumns: [] })
+
+export function normalizePolicy(input) {
+  if (!input || typeof input !== 'object') return { ...EMPTY_POLICY }
+  const list = (v) => (Array.isArray(v) ? v : String(v ?? '').split(/[\n,，]/))
+    .map(x => String(x).trim()).filter(Boolean).slice(0, 2000).map(x => x.slice(0, 200))
+  const mode = ['all', 'allow', 'deny'].includes(input.mode) ? input.mode : 'all'
+  return { mode, tables: [...new Set(list(input.tables))], hiddenColumns: [...new Set(list(input.hiddenColumns))], maskedColumns: [...new Set(list(input.maskedColumns))] }
+}
+
+export function policyActive(policy) {
+  return Boolean(policy) && (policy.mode !== 'all' || policy.hiddenColumns.length > 0 || policy.maskedColumns.length > 0)
+}
+
+const globCache = new Map()
+export function glob(pattern) {
+  const key = pattern.toLowerCase()
+  let re = globCache.get(key)
+  if (!re) {
+    re = new RegExp(`^${key.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*').replace(/\?/g, '.')}$`)
+    globCache.set(key, re)
+  }
+  return re
+}
+
+function matchAny(patterns, name) {
+  const n = name.toLowerCase()
+  const last = n.split('.').pop()
+  return patterns.some(p => {
+    const re = glob(p)
+    return re.test(n) || (!p.includes('.') && re.test(last))
+  })
+}
+
+/** Whether the policy lets the model see / query this table. */
+export function tableAllowed(policy, table) {
+  if (!policy || policy.mode === 'all') return true
+  const hit = matchAny(policy.tables, table)
+  return policy.mode === 'allow' ? hit : !hit
+}
+
+function columnMatches(patterns, table, column) {
+  const t = table.toLowerCase()
+  const tl = t.split('.').pop()
+  const c = column.toLowerCase()
+  return patterns.some(p => {
+    const i = p.lastIndexOf('.')
+    if (i < 0) return glob(p).test(c)
+    const tp = glob(p.slice(0, i))
+    return (tp.test(t) || tp.test(tl)) && glob(p.slice(i + 1)).test(c)
+  })
+}
+
+export function columnHidden(policy, table, column) {
+  return Boolean(policy) && columnMatches(policy.hiddenColumns, table, column)
+}
+
+export function columnMasked(policy, table, column) {
+  return Boolean(policy) && columnMatches(policy.maskedColumns, table, column)
+}
+
+/** Schema as the model may see it: excluded tables and hidden columns removed. */
+export function filterSchema(schema, policy) {
+  if (!policyActive(policy)) return schema
+  const tables = schema.tables
+    .filter(t => tableAllowed(policy, t.name))
+    .map(t => ({
+      ...t,
+      columns: t.columns.filter(c => !columnHidden(policy, t.name, c.name)).map(c => (columnMasked(policy, t.name, c.name) ? { ...c, values: undefined, roles: [...new Set([...c.roles, 'sensitive'])] } : c)),
+      indexes: t.indexes.filter(i => i.columns.every(c => !columnHidden(policy, t.name, c))),
+    }))
+  const visible = new Set(tables.map(t => t.name))
+  const hiddenCol = (tbl, col) => columnHidden(policy, tbl, col)
+  const relations = schema.relations.filter(r => visible.has(r.from.table) && visible.has(r.to.table) && !hiddenCol(r.from.table, r.from.column) && !hiddenCol(r.to.table, r.to.column))
+  return { ...schema, tables, relations }
+}
+
+/** Annotate (not filter) a schema for the page: blocked tables and hidden/masked columns. */
+export function annotateSchema(schema, policy) {
+  if (!policyActive(policy)) return schema
+  return {
+    ...schema,
+    tables: schema.tables.map(t => ({
+      ...t,
+      blocked: !tableAllowed(policy, t.name),
+      columns: t.columns.map(c => ({ ...c, hidden: columnHidden(policy, t.name, c.name), policyMasked: columnMasked(policy, t.name, c.name) })),
+    })),
+  }
+}
+
+// ------------------------------------------------------------ SQL analysis
+
+/**
+ * Identifiers of a statement, lower-cased, with dotted parts joined
+ * (`db`.`t` → db.t), string literals and comments skipped. Also returns the
+ * raw tokens that follow FROM/JOIN, which may contain `-` and `*` in
+ * Elasticsearch index names.
+ */
+export function analyzeIdentifiers(sql, { dialect = 'mysql' } = {}) {
+  const ids = []
+  const fromTargets = []
+  const src = normalizeForScan(String(sql), dialect)
+  let i = 0
+  let prevWord = ''
+  let inFromList = false // after FROM target: `t alias, next` keeps listing tables
+  let depth = 0
+  let fromDepth = -1
+  const pushId = (parts) => { if (parts.length) ids.push(parts.join('.').toLowerCase()) }
+  while (i < src.length) {
+    const c = src[i]
+    const n = src[i + 1]
+    void n
+    // Input is normalized by normalizeForScan: comments are gone and every string literal is exactly ''.
+    if (c === '\'') { i += 2; prevWord = ''; continue }
+    if (c === '`' || c === '"' || /[A-Za-z_]/.test(c)) {
+      // A possibly dotted identifier chain.
+      const parts = []
+      const start = i
+      for (;;) {
+        if (src[i] === '`' || src[i] === '"') {
+          const q = src[i]
+          let j = i + 1
+          let text = ''
+          while (j < src.length) {
+            if (src[j] === q) { if (src[j + 1] === q) { text += q; j += 2; continue } break }
+            text += src[j]
+            j++
+          }
+          parts.push(text)
+          i = j + 1
+        } else if (/[A-Za-z_]/.test(src[i] ?? '')) {
+          let j = i
+          while (j < src.length && /[\w$]/.test(src[j])) j++
+          parts.push(src.slice(i, j))
+          i = j
+        } else if (src[i] === '*' && parts.length) {
+          parts.push('*')
+          i++
+          break
+        } else {
+          break
+        }
+        if (src[i] === '.' && /[`"A-Za-z_*]/.test(src[i + 1] ?? '')) { i++; continue }
+        break
+      }
+      const word = parts.length === 1 ? parts[0].toUpperCase() : ''
+      if (/^(WHERE|GROUP|ORDER|HAVING|LIMIT|ON|USING|UNION|SELECT|WINDOW|FETCH|OFFSET|SET|RETURNING)$/.test(word) && depth === fromDepth) inFromList = false
+      if (/^(FROM|JOIN)$/.test(prevWord)) {
+        inFromList = true
+        fromDepth = depth
+        // Raw target, including hyphens/wildcards that bare identifiers stop at.
+        let j = i
+        while (j < src.length && /[\w\-*.:]/.test(src[j])) j++
+        const raw = (parts.length === 1 && !/[`"]/.test(src[start]) ? src.slice(start, j) : parts.join('.')).toLowerCase()
+        fromTargets.push(raw)
+        if (j > i && !/[`"]/.test(src[start])) i = j
+      }
+      pushId(parts)
+      prevWord = word
+      continue
+    }
+    if (c === '(') depth++
+    if (c === ')') { depth--; if (depth < fromDepth) inFromList = false }
+    if (c === ',' && inFromList && depth === fromDepth) { prevWord = 'FROM'; i++; continue }
+    if (!/\s/.test(c)) prevWord = ''
+    i++
+  }
+  return { ids, fromTargets }
+}
+
+/**
+ * Rewrite SQL for identifier scanning using the dialect's exact lexical rules:
+ * comments become a space, string literals become '' (so nothing inside them is
+ * read as code), quoted identifiers are kept as "name", and whitespace around
+ * dots in name chains is removed (`information_schema . tables`).
+ */
+export function normalizeForScan(sql, dialect = 'mysql') {
+  const { segments } = lexSql(sql, { dialect })
+  const out = segments.map(sg => {
+    if (sg.kind === 'comment') return ' '
+    if (sg.kind === 'string') return "''"
+    if (sg.kind === 'ident') {
+      const t = sg.text
+      const inner = t[0] === '[' ? t.slice(1, -1) : t.slice(1, -1).split(t[0] + t[0]).join(t[0])
+      return `"${inner.replace(/"/g, '""')}"`
+    }
+    return sg.text
+  }).join('')
+  return out.replace(/\s*\.\s*(?=["A-Za-z_*])/g, '.').replace(/(["\w])\s+\./g, '$1.')
+}
+
+const SYSTEM_PREFIX = /^(information_schema|mysql|performance_schema|sys|pg_catalog|pg_toast)\./
+const SYSTEM_BARE = /^pg_(class|namespace|attribute|tables|views|user|shadow|roles|authid|stat\w*|settings|proc|database|index|indexes|constraint|description|type|matviews|policies|sequence\w*)$/
+
+/** Tables of the schema that a statement references. */
+export function referencedTables(sql, tables, { dialect = 'mysql' } = {}) {
+  const { ids, fromTargets } = analyzeIdentifiers(sql, { dialect })
+  const names = tables.map(t => t.name)
+  const lower = new Map(names.map(n => [n.toLowerCase(), n]))
+  const byLast = new Map()
+  for (const n of names) {
+    const last = n.toLowerCase().split('.').pop()
+    if (!byLast.has(last)) byLast.set(last, [])
+    byLast.get(last).push(n)
+  }
+  const out = new Set()
+  for (const id of [...ids, ...fromTargets]) {
+    if (lower.has(id)) { out.add(lower.get(id)); continue }
+    // db.table / schema.table / alias.column: try the last two and last parts.
+    const parts = id.split('.')
+    if (parts.length >= 2) {
+      const two = parts.slice(-2).join('.')
+      if (lower.has(two)) { out.add(lower.get(two)); continue }
+    }
+    // A bare name, or db.table where the last part names a table (MySQL database prefix).
+    const last = parts[parts.length - 1]
+    if ((parts.length === 1 || fromTargets.includes(id)) && byLast.has(last)) for (const n of byLast.get(last)) out.add(n)
+    // Elasticsearch wildcard targets: every matching index.
+    if (id.includes('*') && fromTargets.includes(id)) for (const n of names) if (glob(id).test(n.toLowerCase())) out.add(n)
+  }
+  return [...out]
+}
+
+/**
+ * Refuse a statement the policy does not admit.
+ * @returns undefined when admitted, otherwise a refusal message.
+ */
+export function checkAccess(sql, policy, schema, head, { dialect = 'mysql' } = {}) {
+  if (!policyActive(policy)) return undefined
+  const { ids, fromTargets } = analyzeIdentifiers(sql, { dialect })
+  const scan = normalizeForScan(String(sql), dialect)
+  if (policy.mode !== 'all' && head === 'SHOW') return '当前数据源启用了表访问控制，不允许执行 SHOW 语句；请使用 nl2sql_schema 查看可访问的表。'
+  for (const id of [...ids, ...fromTargets]) {
+    if (SYSTEM_PREFIX.test(id) || SYSTEM_BARE.test(id) || (fromTargets.includes(id) && id.startsWith('.'))) return `当前数据源启用了访问控制，不允许查询系统目录（${id}）。`
+  }
+  const tables = schema?.tables ?? []
+  const refs = referencedTables(sql, tables, { dialect })
+  const blocked = refs.filter(t => !tableAllowed(policy, t))
+  if (blocked.length) return `无权查询表：${blocked.join('、')}（数据源访问控制）。`
+  if (policy.mode === 'deny') {
+    // Deny patterns also cover FROM/JOIN targets not (yet) in the analyzed schema.
+    const raw = fromTargets.filter(t => t && !tableAllowed(policy, t.replace(/^"|"$/g, '')))
+    if (raw.length) return `无权查询表：${raw.join('、')}（数据源访问控制）。`
+  }
+  if (policy.mode === 'allow') {
+    // FROM/JOIN targets that resolve to no analyzed table (new tables, unanalyzed views) are refused too.
+    const resolves = (target) => referencedTables(`SELECT 1 FROM ${/[^\w.]/.test(target) ? `"${target}"` : target}`, tables, { dialect: 'postgres' }).length > 0
+    const ctes = new Set([...scan.matchAll(/(?:\bWITH(?:\s+RECURSIVE)?|,)\s*[`"]?([A-Za-z_][\w$]*)[`"]?\s*(?:\([^)]*\))?\s+AS\s*(?:NOT\s+)?(?:MATERIALIZED\s*)?\(/gi)].map(m => m[1].toLowerCase()))
+    const unknown = fromTargets.filter(t => t && !ctes.has(t) && !/^(select|lateral|unnest|generate_series|json_table|dual)$/.test(t) && !resolves(t))
+    if (unknown.length) return `无权查询未授权或未分析的表：${unknown.join('、')}。如果是新表，请先在页面上重新分析表结构并加入允许列表。`
+  }
+  const hidden = []
+  const masked = []
+  for (const t of refs) {
+    const table = tables.find(x => x.name === t)
+    for (const c of table?.columns ?? []) {
+      if (columnHidden(policy, t, c.name)) hidden.push({ table: t, column: c.name.toLowerCase() })
+      else if (columnMasked(policy, t, c.name)) masked.push({ table: t, column: c.name.toLowerCase() })
+    }
+  }
+  if (hidden.length || masked.length) {
+    const hiddenNames = new Set(hidden.map(h => h.column))
+    const hit = ids.find(id => hiddenNames.has(id.split('.').pop().replace(/^"|"$/g, '')))
+    if (hit) return `字段 ${hit} 已被数据源访问控制隐藏，不能在查询中使用。`
+    if (/\b(row_to_json|to_jsonb?|jsonb?_agg|json_object_agg|hstore|record_out|row)\s*\(/i.test(scan)) return '引用的表含有受保护的字段，不允许使用整行转换函数（row_to_json/to_json/json_agg/ROW(...) 等）。'
+    // Whole-row values: alias::type, CAST(alias AS …), (alias), alias in function args, alias.* inside a call.
+    const aliasNames = tableAliases(scan, refs)
+    for (const a of aliasNames) {
+      const q = a.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+      const asValue = new RegExp(`(?:^|[^\\w."])${q}\\s*::|\\bCAST\\s*\\(\\s*${q}\\s+AS\\b|\\(\\s*${q}\\s*[,)]|,\\s*${q}\\s*\\)|\\(\\s*${q}\\.\\*`, 'i')
+      if (asValue.test(scan)) return '引用的表含有受保护的字段，不允许把整行（表或别名本身）作为值使用；请明确列出需要的字段。'
+    }
+    // Masked columns may only be selected as plain columns (so results can be masked), not inside expressions.
+    if (masked.length) {
+      const maskedNames = new Set(masked.map(m => m.column))
+      const exprUse = maskedInExpression(scan, maskedNames)
+      if (exprUse) return `字段 ${exprUse} 需要脱敏显示，只能直接选取，不能用于表达式、函数或改名（AS）。`
+    }
+  }
+  return undefined
+}
+
+/** Table names and aliases introduced in FROM/JOIN for the referenced tables. */
+function tableAliases(scan, refs) {
+  const out = new Set()
+  const lastParts = new Set(refs.map(r => r.toLowerCase().split('.').pop()))
+  for (const m of scan.matchAll(/\b(?:FROM|JOIN|,)\s+((?:"[^"]+"|[\w$]+)(?:\.(?:"[^"]+"|[\w$]+))*)(?:\s+(?:AS\s+)?("?[A-Za-z_][\w$]*"?))?/gi)) {
+    const name = m[1].split('.').pop().replace(/^"|"$/g, '').toLowerCase()
+    if (!lastParts.has(name)) continue
+    out.add(m[1].split('.').pop().replace(/^"|"$/g, ''))
+    const alias = m[2]?.replace(/^"|"$/g, '')
+    if (alias && !/^(WHERE|JOIN|ON|LEFT|RIGHT|INNER|OUTER|FULL|CROSS|GROUP|ORDER|LIMIT|UNION|USING|NATURAL|HAVING|WINDOW)$/i.test(alias)) out.add(alias)
+  }
+  return [...out]
+}
+
+/**
+ * Whether a masked column appears anywhere other than as a plain select item
+ * (`col`, `t.col`) — e.g. inside a function, an operator, or renamed with AS.
+ */
+function maskedInExpression(scan, maskedNames) {
+  const m = /^\s*\(*\s*SELECT\s+(DISTINCT\s+)?([\s\S]*?)\s+FROM\s/i.exec(scan)
+  const items = m ? splitTop(m[2]) : []
+  for (const item of items) {
+    const text = item.trim()
+    const plain = /^(?:"?[\w$]+"?\.)*"?([\w$]+)"?$/.exec(text)
+    for (const name of maskedNames) {
+      const re = new RegExp(`(^|[^\\w$])"?${name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}"?($|[^\\w$])`, 'i')
+      if (!re.test(text)) continue
+      if (plain && plain[1].toLowerCase() === name) continue
+      return name
+    }
+  }
+  // Outside the select list (WHERE/GROUP BY/ORDER BY) masked columns are fine: they do not reach results.
+  return undefined
+}
+
+function splitTop(text) {
+  const out = []
+  let depth = 0
+  let cur = ''
+  for (const ch of text) {
+    if (ch === '(') depth++
+    if (ch === ')') depth--
+    if (ch === ',' && depth === 0) { out.push(cur); cur = ''; continue }
+    cur += ch
+  }
+  if (cur.trim()) out.push(cur)
+  return out
+}
+
+/** Result column indexes to drop (hidden) and to mask, given the referenced tables. */
+export function resultColumnPolicy(policy, columns, refs, schema) {
+  const drop = new Set()
+  const mask = new Set()
+  if (!policyActive(policy)) return { drop, mask }
+  const tables = (schema?.tables ?? []).filter(t => refs.includes(t.name))
+  columns.forEach((col, i) => {
+    const name = String(col.name).toLowerCase()
+    const origin = col.table && col.column ? [{ table: col.table, column: col.column }] : tables.map(t => ({ table: t.name, column: name.split('.').pop() }))
+    for (const o of origin) {
+      if (columnHidden(policy, o.table, o.column)) drop.add(i)
+      else if (columnMasked(policy, o.table, o.column)) mask.add(i)
+    }
+  })
+  return { drop, mask }
+}

package/service/access.js

@@ -0,0 +1,145 @@
+/**
+ * Nl2SqlService methods: access.
+ * Mixed into the service prototype by index.js; `this` is the service.
+ */
+import { ROLE_RANK, UserError, newId, oneOf, requireText, upsert } from './shared.js'
+
+export const methods = {
+  // ------------------------------------------------------------ access
+
+  /**
+   * Actors (multi-user): the local page/agent owner has full access; Lark
+   * users/chats are mapped to users with datasource scopes.
+   */
+  assertAccess(actor, ds) {
+    if (!actor || actor.kind === 'owner') return
+    const allowed = actor.datasourceIds
+    if (Array.isArray(allowed) && !allowed.includes(ds.id)) throw new UserError('nl2sql/access-denied', `${actor.name ?? '当前用户'} 无权访问数据源「${ds.name}」`)
+  },
+
+  /** The actor a session runs as (Lark user, evaluation), or undefined for the local owner. */
+  actorFor(sessionId) {
+    return sessionId ? this.state.sessionActors?.[sessionId] : undefined
+  },
+
+  /** Viewer: only governed answers (metric library, verified examples, dashboards) — no free SQL. */
+  assertCanWriteSql(actor, what = '自由编写 SQL') {
+    if (actor?.role === 'viewer') throw new UserError('nl2sql/viewer', `当前成员是「只读」角色，不能${what}。只读成员可以：查询指标库中的指标（nl2sql_metric）、复用已验证的样例问答（nl2sql_knowledge search 后用样例 SQL 原样查询）、查看看板。请改用这些方式回答，或请管理员调整角色。`)
+  },
+
+  /** Whether a statement is (whitespace-insensitively) one of the verified example SQLs of the data source. */
+  isVerifiedExample(ds, sql) {
+    const norm = (q) => String(q ?? '').replace(/;\s*$/, '').replace(/\s+/g, ' ').trim().toLowerCase()
+    const target = norm(sql)
+    return this.knowledgeFor(ds.id).examples.some(e => norm(e.sql) === target) || this.state.dashboards.some(d => d.widgets.some(w => w.datasourceId === ds.id && norm(w.sql) === target))
+  },
+
+  /**
+   * Row-level rules for an actor on a data source: [{ column, values }] combined
+   * from the member and the group. Every query must be rewritable to include them.
+   */
+  rowRulesFor(actor, ds) {
+    const rules = []
+    for (const r of actor?.rowRules ?? []) if (!r.datasourceId || r.datasourceId === ds.id) rules.push({ column: r.column, values: r.values })
+    return rules
+  },
+
+  /**
+   * Members: people (Lark open_id / email) and Lark chats, each with a role
+   * (admin | analyst | viewer) and a data source scope. The local owner is
+   * implicit. Lark messages from unknown people fall back to
+   * settings.larkDefaultRole (none = refuse).
+   */
+  listUsers() {
+    return (this.state.users ?? []).map(u => ({ ...u, datasourceNames: (u.datasourceIds ?? []).map(id => this.findDatasource(id)?.name ?? id) }))
+  },
+
+  async saveUser(input) {
+    const existing = input.id ? (this.state.users ?? []).find(u => u.id === input.id) : undefined
+    const u = existing ? { ...existing } : { id: newId('u'), createdAt: Date.now() }
+    u.kind = oneOf(input.kind ?? u.kind ?? 'person', ['person', 'chat'], 'kind')
+    u.name = requireText(input.name ?? u.name, 'name', 60)
+    u.role = oneOf(input.role ?? u.role ?? 'analyst', ['admin', 'analyst', 'viewer'], 'role')
+    u.larkOpenId = String(input.larkOpenId ?? u.larkOpenId ?? '').trim().slice(0, 100) || undefined
+    u.email = String(input.email ?? u.email ?? '').trim().slice(0, 200) || undefined
+    u.larkChatId = String(input.larkChatId ?? u.larkChatId ?? '').trim().slice(0, 100) || undefined
+    if (u.kind === 'person' && !u.larkOpenId && !u.email) throw new UserError('nl2sql/invalid', '成员需要填写飞书 open_id 或邮箱，用于识别身份')
+    if (u.kind === 'chat' && !u.larkChatId) throw new UserError('nl2sql/invalid', '群成员需要填写飞书 chat_id')
+    const allDs = input.allDatasources ?? (input.datasourceIds === undefined ? u.datasourceIds === null : false)
+    u.datasourceIds = allDs ? null : (input.datasourceIds ?? u.datasourceIds ?? []).filter(id => this.findDatasource(id))
+    u.defaultDatasourceId = input.defaultDatasourceId && this.findDatasource(input.defaultDatasourceId) ? input.defaultDatasourceId : (u.datasourceIds?.[0] ?? null)
+    u.disabled = Boolean(input.disabled ?? u.disabled ?? false)
+    u.note = String(input.note ?? u.note ?? '').slice(0, 300)
+    if (input.rowRules !== undefined) {
+      u.rowRules = (Array.isArray(input.rowRules) ? input.rowRules : []).map(r => ({
+        datasourceId: r.datasourceId && this.findDatasource(r.datasourceId) ? r.datasourceId : null,
+        column: requireText(r.column, 'rowRules.column', 64),
+        values: (Array.isArray(r.values) ? r.values : String(r.values ?? '').split(/[,，]/)).map(v => String(v).trim()).filter(Boolean).slice(0, 200),
+      })).filter(r => r.values.length).slice(0, 20)
+      if (u.rowRules.some(r => !/^[A-Za-z_\u4e00-\u9fa5][\w$\u4e00-\u9fa5]*$/.test(r.column))) throw new UserError('nl2sql/invalid', '行级规则的字段名只能包含字母、数字、下划线或中文')
+    }
+    const dup = (this.state.users ?? []).find(x => x.id !== u.id && ((u.larkOpenId && x.larkOpenId === u.larkOpenId) || (u.email && x.email === u.email) || (u.larkChatId && x.larkChatId === u.larkChatId)))
+    if (dup) throw new UserError('nl2sql/duplicate', `该身份已属于成员「${dup.name}」`)
+    u.updatedAt = Date.now()
+    this.state.users = upsert(this.state.users ?? [], u)
+    this.auditAdmin('user.save', `${u.name}（${u.role}）`)
+    await this.save()
+    return u
+  },
+
+  async deleteUser(id) {
+    const u = (this.state.users ?? []).find(x => x.id === id)
+    this.state.users = (this.state.users ?? []).filter(x => x.id !== id)
+    if (u) this.auditAdmin('user.delete', u.name)
+    await this.save()
+    return { deleted: id }
+  },
+
+  /**
+   * Resolve the effective actor for a Lark message: the person's own scope,
+   * narrowed by the chat's scope in group chats. Returns { actor } or { refused }.
+   */
+  resolveLarkActor({ openId, email, name, chatId, chatType }) {
+    const users = (this.state.users ?? []).filter(u => !u.disabled)
+    const person = users.find(u => u.kind === 'person' && ((openId && u.larkOpenId === openId) || (email && u.email && u.email.toLowerCase() === String(email).toLowerCase())))
+    const chat = chatType === 'group' ? users.find(u => u.kind === 'chat' && u.larkChatId === chatId) : undefined
+    const fallbackRole = this.state.settings.larkDefaultRole ?? 'none'
+    if (!person && !chat && fallbackRole === 'none') return { refused: '你还没有开通数据问答权限，请联系管理员在「数据问答 → 成员」中添加你的飞书账号。' }
+    const scopes = [person?.datasourceIds, chat?.datasourceIds].filter(x => x !== undefined)
+    let datasourceIds = null
+    for (const sc of scopes) if (Array.isArray(sc)) datasourceIds = datasourceIds === null ? [...sc] : datasourceIds.filter(id => sc.includes(id))
+    if (!person && !chat) datasourceIds = this.state.settings.larkDefaultDatasourceIds ?? []
+    const role = person?.role ?? chat?.role ?? fallbackRole
+    if (Array.isArray(datasourceIds) && datasourceIds.length === 0) return { refused: '你在当前群里没有可访问的数据源。' }
+    return {
+      actor: {
+        kind: 'lark', id: person?.id ?? `lark:${openId}`, name: person?.name ?? name ?? openId,
+        // Group chats: the narrower of the person's and the group's role.
+        role: [person?.role, chat?.role, (!person && !chat) ? fallbackRole : undefined].filter(Boolean).sort((a, b) => ROLE_RANK[a] - ROLE_RANK[b])[0] ?? role,
+        openId, chatId, chatName: chat?.name, datasourceIds,
+        rowRules: [...(person?.rowRules ?? []), ...(chat?.rowRules ?? [])],
+        defaultDatasourceId: chat?.defaultDatasourceId ?? person?.defaultDatasourceId ?? (datasourceIds?.[0] ?? null),
+      },
+    }
+  },
+
+  auditAdmin(action, detail, actor) {
+    this.records.put('admin', { id: newId('ad'), at: Date.now(), action, detail: String(detail).slice(0, 300), ...(actor ? { actor: { id: actor.id, name: actor.name, kind: actor.kind } } : {}) })
+  },
+
+  /** Per-actor usage for the members page. */
+  usageByActor(days = 30) {
+    const since = Date.now() - days * 86400000
+    const by = new Map()
+    for (const h of this.records.list('history', { since, limit: 100000 })) {
+      const key = h.actor?.id ?? 'owner'
+      const e = by.get(key) ?? { actorId: key, name: h.actor?.name ?? '本机', kind: h.actor?.kind ?? 'owner', queries: 0, errors: 0, blocked: 0, lastAt: 0 }
+      e.queries++
+      if (h.status === 'error') e.errors++
+      if (h.status === 'blocked') e.blocked++
+      e.lastAt = Math.max(e.lastAt, h.at)
+      by.set(key, e)
+    }
+    return [...by.values()].sort((a, b) => b.queries - a.queries)
+  },
+}