@hedeqiang/dsh-nl2sql 0.12.1 → 0.13.0

package/channels/wecom.js

@@ -36,7 +36,7 @@
  */
 import { createHash, randomBytes } from 'node:crypto'
 import { ChannelError, postJson } from './http.js'
-import { renderChartPng as defaultRenderChartPng, chartable, resultMeta, isKpi, kpiText, resultAsMarkdownTable, toPlainMarkdown, mentionsAll, splitText } from './message.js'
+import { renderChartPng as defaultRenderChartPng, chartable, cellText, defangMd, fmtNum, resultMeta, isKpi, kpiText, resultAsMarkdownTable, toPlainMarkdown, mentionsAll, splitText } from './message.js'
 
 export const WEBHOOK_HOST = 'https://qyapi.weixin.qq.com'
 export const DEFAULT_GATEWAY = 'wss://openws.work.weixin.qq.com'
@@ -95,8 +95,9 @@ export function toWecomMarkdown(md) {
 }
 
 function resultBlock(r, { includeSql, maxRows = 10, table = true } = {}) {
-  const head = `**${r.title || '查询结果'}**  ${resultMeta(r)}`
-  if (r.error) return `${head}\n${r.error}`
+  // Data-derived text (title, error, values) is defanged: no links / tags / mentions from data.
+  const head = `**${defangMd(r.title || '查询结果')}**  ${resultMeta(r)}`
+  if (r.error) return `${head}\n${defangMd(r.error)}`
   const lines = [head]
   if (!r.rows?.length) lines.push('无数据')
   else if (isKpi(r)) lines.push(kpiText(r, { separator: '\n' }))
@@ -109,7 +110,7 @@ function resultBlock(r, { includeSql, maxRows = 10, table = true } = {}) {
 function resultAsText(r, maxRows) {
   const cols = r.columns.slice(0, 6)
   const rows = r.rows.slice(0, maxRows)
-  const out = [`> ${cols.map(c => c.name).join(' ｜ ')}`, ...rows.map(row => `> ${cols.map((c, i) => String(row[i] ?? '')).join(' ｜ ')}`)]
+  const out = [`> ${cols.map(c => defangMd(c.name)).join(' ｜ ')}`, ...rows.map(row => `> ${cols.map((c, i) => defangMd(c.kind === 'number' ? fmtNum(row[i]) : cellText(row[i], 60))).join(' ｜ ')}`)]
   if ((r.rowCount ?? r.rows.length) > rows.length) out.push(`<font color="comment">…共 ${r.rowCount ?? r.rows.length} 行</font>`)
   return out.join('\n')
 }
@@ -121,19 +122,19 @@ function resultAsText(r, maxRows) {
 export function planWebhook(message) {
   const sections = []
   const images = []
-  if (message.title) sections.push(`## ${message.title}`)
+  if (message.title) sections.push(`## ${defangMd(message.title)}`)
   if (message.text) sections.push(message.text)
   let hasTable = /(^|\n)\|[^\n]*\|\s*\n\|[\s:|-]+\|/.test(message.text ?? '')
   for (const r of (message.results ?? []).slice(0, 10)) {
     if (message.chartMode !== 'table' && !r.error && chartable(r)) {
-      sections.push(`**${r.title || '查询结果'}**  ${resultMeta(r)}（见下方图表）${r.sql && message.includeSql ? '\n```sql\n' + r.sql.slice(0, 1500) + '\n```' : ''}`)
+      sections.push(`**${defangMd(r.title || '查询结果')}**  ${resultMeta(r)}（见下方图表）${r.sql && message.includeSql ? '\n```sql\n' + r.sql.slice(0, 1500) + '\n```' : ''}`)
       images.push({ msgtype: 'image', result: r })
       continue
     }
     if (r.rows?.length && !isKpi(r) && !r.error) hasTable = true
     sections.push(resultBlock(r, { includeSql: message.includeSql }))
   }
-  if (message.footer) sections.push(message.footer)
+  if (message.footer) sections.push(defangMd(toPlainMarkdown(message.footer, { mentionAll: '' })))
   const md = sections.filter(Boolean).join('\n\n')
   const msgtype = hasTable ? 'markdown_v2' : 'markdown'
   const content = msgtype === 'markdown_v2' ? toPlainMarkdown(md, { mentionAll: '' }) : toWecomMarkdown(md)
@@ -238,10 +239,10 @@ function inboundText(body) {
 
 function aibotMarkdown(message) {
   const parts = []
-  if (message.title) parts.push(`**${message.title}**`)
+  if (message.title) parts.push(`**${defangMd(message.title)}**`)
   if (message.text) parts.push(toPlainMarkdown(message.text, { mentionAll: '' }))
   for (const r of (message.results ?? []).slice(0, 10)) parts.push(resultBlock(r, { includeSql: message.includeSql }))
-  if (message.footer) parts.push(toPlainMarkdown(message.footer, { mentionAll: '' }))
+  if (message.footer) parts.push(defangMd(toPlainMarkdown(message.footer, { mentionAll: '' })))
   return parts.join('\n\n')
 }
 

package/cordis.patch.yml

@@ -39,6 +39,10 @@
                 13. Local file data sources (type sqlite) hold user-uploaded CSV/Excel tables; write SQLite SQL for them (strftime/date, double-quoted identifiers, Chinese column names must be quoted).
                 14. Messages tagged [飞书…], [Telegram…], [企业微信…] or [钉钉…] come from IM chat members through a bot: answer in Markdown without asking questions (state assumptions instead); a member marked 只读成员 may only use nl2sql_metric or reuse verified example SQL from nl2sql_knowledge — if a query is refused for row-level or viewer restrictions, explain the restriction instead of retrying variations.
                 15. When the user confirms an answer is correct (e.g. "对", "没问题", "就是这个"), offer to store it; on agreement call nl2sql_knowledge action=save_example with the question and the final SQL.
+                16. In IM bot chats only: for "每天 9 点把这个发到群里" / "每周一推送" call nl2sql_subscribe (resultId of the result just shown, or a metric name + grain/range; time HH:MM, period daily/weekly/monthly); for "超过 X 提醒我" / "下跌 20% 告诉我" call nl2sql_alert_create (resultId or metric, condition threshold/change/anomaly, mentionMe when they say 提醒我); for "我的订阅" / "取消订阅" / "暂停告警" call nl2sql_subscriptions (list first, then pause/resume/cancel by id). Deliveries go to the current chat; confirm the schedule in one sentence. Page users are told to use 管理 → 告警与报告 instead.
+                17. For 对比 / 对账 / 核对 questions spanning two data sources (or two queries on one source) — e.g. "核对订单库和财务库昨天的金额", "两边的笔数对得上吗" — call nl2sql_reconcile once with one SQL per side (aggregate both to the same grain and return the key columns plus the values to compare, aliased consistently), keys and compare columns (add a small tolerance for amounts with rounding differences); do not run the two queries separately and compare by hand. Then explain the outcome in plain language: match rate, how many keys exist only on one side, which columns disagree and the size of the total differences, plus warnings (truncation, duplicate keys, masked keys); suggest likely causes (time-zone or date boundary, status filters, late-arriving data) and offer to save it as a scheduled reconciliation in 管理 → 对账.
+                18. For 预测 / forecast / "下周会是多少" questions, first get a daily (or weekly/monthly) time series with ONE measure (nl2sql_metric with grain, or nl2sql_query with time + value), then call nl2sql_forecast with its resultId and horizon; report the point forecast with its 95% range, name the method, and say it is a statistical extrapolation that ignores promotions, holidays and other known events.
+                19. For questions about recent periods (today / yesterday / this week / 最近 / 今天 / 昨天 / 本周), call nl2sql_freshness with the tables you query; when a table is stale or lagging (status stale/warn), say so before the numbers, e.g. "⚠️ withdrawals 最新数据停在昨天 17:55", and do not present missing recent data as a real drop.
 
                 You may only read data. Never attempt to modify data or schema; the tools reject anything but SELECT/SHOW/DESC/EXPLAIN.
           - id: time-context

package/docs/mcp.md

@@ -0,0 +1,119 @@
+# MCP server
+
+dsh-nl2sql can expose its governed data access to other AI tools — Claude Desktop, Cursor, Cline, VS Code (GitHub Copilot agent mode) and any other [Model Context Protocol](https://modelcontextprotocol.io/specification/) client. External models get the same guard rails as the built-in Data Q&A agent:
+
+- every statement passes **read-only admission** (one SELECT / WITH / SHOW / EXPLAIN; writes, DDL, multiple statements and system catalogs are refused);
+- **access policies** (hidden tables and columns, masked columns) and **sensitive-column masking** apply;
+- each token runs as an **actor** — the local owner, an existing **member** (role, data source scope, row-level rules) or a **role + data sources** (+ optional row rule);
+- the **privacy setting** "result data sent to the model" decides whether the model sees rows, per-column statistics, or only row counts;
+- every call is **audited** in History with source `mcp` and the token name.
+
+The server runs inside DeepSeek Harness, so Harness must be running while you use it.
+
+## Enable it
+
+1. Open **Data Q&A → 管理 / Admin → MCP 接入 / MCP access**.
+2. Turn the server on. It listens on `http://127.0.0.1:47860/mcp` by default (change the port there; the server restarts automatically). It is **off by default** and never binds to other interfaces.
+3. Click **New token**, give it a name and choose its scope:
+   - **Local owner** — the same access as asking on the page (policies still apply);
+   - **A member** — follows that member's role, data sources and row-level rules, live; disabling or deleting the member makes the token stop working;
+   - **Role + data sources** — analyst / viewer / admin on the selected data sources, with an optional row rule (`column IN (values)`).
+4. Copy the token — it is shown **once**. Only its SHA-256 hash is stored; if you lose it, revoke it and create a new one.
+
+The page shows ready-to-copy snippets for the clients below, filled in with the new token.
+
+## Claude Desktop (stdio bridge)
+
+Claude Desktop launches local MCP servers as processes speaking stdio. The package ships a small bridge, `nl2sql-mcp` (plain Node ≥ 18, no dependencies), that relays stdio to the HTTP endpoint. Add to `claude_desktop_config.json` (Settings → Developer → Edit Config):
+
+```json
+{
+  "mcpServers": {
+    "nl2sql": {
+      "command": "npx",
+      "args": ["-y", "-p", "@hedeqiang/dsh-nl2sql", "nl2sql-mcp"],
+      "env": {
+        "NL2SQL_MCP_URL": "http://127.0.0.1:47860/mcp",
+        "NL2SQL_MCP_TOKEN": "<YOUR_TOKEN>"
+      }
+    }
+  }
+}
+```
+
+You can run the bridge by hand to check it: `NL2SQL_MCP_TOKEN=… npx -y -p @hedeqiang/dsh-nl2sql nl2sql-mcp`, then type `{"jsonrpc":"2.0","id":1,"method":"tools/list"}`.
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `NL2SQL_MCP_URL` | `http://127.0.0.1:47860/mcp` | The MCP endpoint shown in the page |
+| `NL2SQL_MCP_TOKEN` | — | Bearer token (required) |
+| `NL2SQL_MCP_TIMEOUT_MS` | 660000 | Per-request timeout |
+
+## Cursor
+
+Cursor speaks Streamable HTTP directly. Add to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project):
+
+```json
+{
+  "mcpServers": {
+    "nl2sql": {
+      "url": "http://127.0.0.1:47860/mcp",
+      "headers": { "Authorization": "Bearer <YOUR_TOKEN>" }
+    }
+  }
+}
+```
+
+## VS Code
+
+Add to `.vscode/mcp.json` (or the user-level MCP configuration):
+
+```json
+{
+  "servers": {
+    "nl2sql": {
+      "type": "http",
+      "url": "http://127.0.0.1:47860/mcp",
+      "headers": { "Authorization": "Bearer <YOUR_TOKEN>" }
+    }
+  }
+}
+```
+
+Cline and other clients: use the HTTP URL with an `Authorization: Bearer …` header when the client supports remote/HTTP servers, otherwise the stdio bridge command above.
+
+## What the server offers
+
+**Tools** (all read-only):
+
+| Tool | What it does |
+|---|---|
+| `list_datasources` | Data sources this token may use, with engine and SQL dialect |
+| `get_schema` | Schema overview (visible tables, column roles, relations, dialect notes, glossary, metrics) or full detail of `tables` |
+| `query` | One read-only SQL statement → columns, rows / statistics / count per privacy setting, `rowCount`, `truncated`, `resultId` |
+| `query_metric` | A governed metric from the metric library (grain, dimensions, range, filters) |
+| `search_knowledge` | Verified question→SQL examples, glossary and metric definitions related to a question |
+| `drill` | Breakdown / detail of an earlier `resultId` (row rules re-applied) |
+| `explain_change` | Attribution: which dimensions explain the change between two periods of a result |
+| `reconcile` | Compare two queries (e.g. the same figures from two databases) — listed when the reconcile feature is installed |
+| `forecast` | Forecast a time-series result — listed when the forecast feature is installed |
+
+Tool errors (refused SQL, row-level restrictions, unknown tables) come back as results with `isError: true` so the model can correct itself.
+
+**Resources:** `nl2sql://datasource/{id}/schema` for every visible data source (and `nl2sql://datasource/{id}/table/{table}` for one table), as plain text.
+
+**Prompts:** `ask_data` — a template that walks the model through list → schema → knowledge → query.
+
+## Protocol details
+
+- Streamable HTTP, `POST /mcp`, plain JSON responses (no SSE); `GET` / `DELETE` → `405`.
+- Dual-era: the 2026-07-28 revision (stateless, per-request `_meta`, `server/discover`, header checks `MCP-Protocol-Version` / `Mcp-Method` / `Mcp-Name`) and the `initialize`-based revisions 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05 (`initialize` negotiates the version and mints an `Mcp-Session-Id`; unknown sessions → `404`). `ping`, `notifications/*` (→ `202`) and JSON-RPC batches are accepted.
+- Unsupported versions get error `-32022` with the supported list.
+
+## Security notes
+
+- **Local only.** The server binds to `127.0.0.1`. Requests whose `Host` is not `localhost` / `127.0.0.1` / `[::1]` are refused with `403` (DNS-rebinding defence), as are requests with a non-local `Origin` header — so web pages in your browser cannot call it.
+- **Tokens.** Every request needs `Authorization: Bearer <token>`; missing or unknown tokens get `401`. Tokens are 192-bit random values; only SHA-256 hashes are stored in `~/.dsh/nl2sql/state.json`, compared in constant time. Revoke a token in the page to cut a client off immediately. "Last used" is shown per token.
+- **Least privilege.** Prefer member- or role-scoped tokens for tools you do not fully trust. Owner tokens can read everything the page can (still read-only and policy-filtered).
+- **Data leaving the machine.** Whatever the MCP client receives is sent to *its* model provider. Use the privacy setting (Admin → Settings → Privacy, or per data source) to send only statistics (`summary`) or nothing (`none`) instead of rows.
+- **Audit.** History lists every MCP query with source `mcp`, the token name and the actor; refusals are logged as `blocked`.

package/filters.js

@@ -11,6 +11,8 @@
  * place safely (top-level UNION, no FROM) run unfiltered and report so.
  */
 
+import { lexSql } from './sql-guard.js'
+
 export const TIME_RANGES = ['today', 'yesterday', 'last7d', 'last30d', 'last90d', 'thisMonth', 'lastMonth', 'thisYear', 'custom']
 
 export function normalizeFilters(input) {
@@ -68,50 +70,50 @@ export function describeFilter(f) {
 
 const CLAUSE_END = /^(WHERE|GROUP|HAVING|ORDER|LIMIT|WINDOW|QUALIFY|FETCH|OFFSET|UNION|INTERSECT|EXCEPT|FOR|PIVOT)$/i
 
-/** Top-level (depth 0) word tokens of the outermost SELECT, with offsets. */
-function topLevelWords(sql) {
+/**
+ * Top-level (depth 0) word tokens of the outermost SELECT, with offsets.
+ * Tokenised with the dialect-exact lexer from sql-guard.js, so comments,
+ * strings and quoted identifiers are recognised exactly as the server does
+ * (e.g. MySQL `1--1` is code, not a comment).
+ */
+function topLevelWords(sql, dialect = 'mysql') {
   const words = []
   let depth = 0
-  for (let i = 0; i < sql.length;) {
-    const c = sql[i]
-    const n = sql[i + 1]
-    if ((c === '-' && n === '-') || c === '#') { while (i < sql.length && sql[i] !== '\n') i++; continue }
-    if (c === '/' && n === '*') { const e = sql.indexOf('*/', i + 2); i = e < 0 ? sql.length : e + 2; continue }
-    if (c === '\'' || c === '"' || c === '`') {
-      const q = c
-      const start = i
-      i++
-      while (i < sql.length) {
-        if (sql[i] === '\\' && q === '\'') { i += 2; continue }
-        if (sql[i] === q) { if (sql[i + 1] === q) { i += 2; continue } break }
-        i++
-      }
-      i++
-      if (depth === 0) words.push({ kind: 'quoted', text: sql.slice(start, i), start, end: i })
+  const { segments } = lexSql(sql, { dialect })
+  for (const seg of segments) {
+    if (seg.kind === 'comment') continue
+    if (seg.kind === 'string' || seg.kind === 'ident') {
+      if (depth === 0) words.push({ kind: 'quoted', text: seg.text, start: seg.start, end: seg.end })
       continue
     }
-    if (c === '(') { depth++; if (depth === 1) words.push({ kind: 'open', start: i, end: i + 1 }); i++; continue }
-    if (c === ')') { depth--; if (depth === 0) words.push({ kind: 'close', start: i, end: i + 1 }); i++; continue }
-    if (/[A-Za-z_]/.test(c)) {
-      let j = i
-      while (j < sql.length && /[\w$.\-*]/.test(sql[j]) && !(sql[j] === '-' && sql[j + 1] === '-')) j++
-      if (depth === 0) words.push({ kind: 'word', text: sql.slice(i, j), upper: sql.slice(i, j).toUpperCase(), start: i, end: j })
-      i = j
-      continue
+    const text = seg.text
+    for (let k = 0; k < text.length;) {
+      const c = text[k]
+      const i = seg.start + k
+      if (c === '(') { depth++; if (depth === 1) words.push({ kind: 'open', start: i, end: i + 1 }); k++; continue }
+      if (c === ')') { depth--; if (depth === 0) words.push({ kind: 'close', start: i, end: i + 1 }); k++; continue }
+      if (/[A-Za-z_]/.test(c)) {
+        let j = k
+        while (j < text.length && /[\w$.\-*]/.test(text[j]) && !(text[j] === '-' && text[j + 1] === '-')) j++
+        if (depth === 0) words.push({ kind: 'word', text: text.slice(k, j), upper: text.slice(k, j).toUpperCase(), start: i, end: seg.start + j })
+        k = j
+        continue
+      }
+      if (c === ',' && depth === 0) words.push({ kind: 'comma', start: i, end: i + 1 })
+      k++
     }
-    if (c === ',' && depth === 0) words.push({ kind: 'comma', start: i, end: i + 1 })
-    i++
   }
   return words
 }
 
 function unquote(t) {
+  if (t.startsWith('[') && t.endsWith(']')) return t.slice(1, -1)
   return t.replace(/^[`"]|[`"]$/g, '').replace(/``/g, '`').replace(/""/g, '"')
 }
 
 /** Parse the outermost query: FROM items with aliases, WHERE span, insertion point. */
-export function parseOuterQuery(sql) {
-  const words = topLevelWords(sql)
+export function parseOuterQuery(sql, { dialect = 'mysql' } = {}) {
+  const words = topLevelWords(sql, dialect)
   // Skip a leading WITH ... list: the main SELECT is the first top-level SELECT after the CTE bodies.
   let selectIdx = words.findIndex(w => w.kind === 'word' && w.upper === 'SELECT')
   if (words[0]?.upper === 'WITH') {
@@ -190,7 +192,7 @@ function literalFor(value, dialect) {
  */
 export function applyFilters(sql, filters, { dialect, schema, now }) {
   if (!filters.length) return { sql, applied: [], skipped: [] }
-  const outer = parseOuterQuery(sql)
+  const outer = parseOuterQuery(sql, { dialect })
   if (!outer || !outer.tables.length) return { sql, applied: [], skipped: filters.map(f => ({ ...f, reason: 'unsupported query shape' })) }
   const tables = schema?.tables ?? []
   const resolve = (ref) => {
@@ -224,14 +226,66 @@ export function applyFilters(sql, filters, { dialect, schema, now }) {
   }
   if (!predicates.length) return { sql, applied, skipped }
   const pred = predicates.join(' AND ')
+  // A trailing line comment would swallow whatever follows on the same line: break the line first.
+  const nl = (text) => (endsInLineComment(text, dialect) ? '\n' : '')
   let out
   if (outer.where) {
+    const head = sql.slice(0, outer.where.keywordStart)
     const existing = sql.slice(outer.where.keywordEnd, outer.where.end).trim()
-    out = `${sql.slice(0, outer.where.keywordStart)}WHERE (${pred}) AND (${existing})${outer.where.end < sql.length ? ' ' : ''}${sql.slice(outer.where.end)}`
+    out = `${head}${nl(head)}WHERE (${pred}) AND (${existing}${nl(existing)})${outer.where.end < sql.length ? ' ' : ''}${sql.slice(outer.where.end)}`
   } else {
     const before = sql.slice(0, outer.insertAt).replace(/\s+$/, '')
     const after = sql.slice(outer.insertAt)
-    out = `${before} WHERE ${pred}${after ? ` ${after}` : ''}`
+    out = `${before}${nl(before) || ' '}WHERE ${pred}${after ? ` ${after}` : ''}`
   }
+  verifyInjection(out, pred, Boolean(outer.where), outer.tables, dialect)
   return { sql: out, applied, skipped }
 }
+
+/** Raised when an injected predicate would not be a top-level conjunct of the rewritten query. */
+export class FilterInjectionError extends Error {
+  constructor(message) {
+    super(message)
+    this.code = 'nl2sql/filter-injection'
+  }
+}
+
+function endsInLineComment(text, dialect) {
+  const segs = lexSql(text, { dialect }).segments
+  const last = segs[segs.length - 1]
+  return Boolean(last && last.kind === 'comment' && last.end === text.length && !last.text.startsWith('/*'))
+}
+
+const tokenSig = (w) => (w.kind === 'word' ? `w:${w.upper}` : w.kind === 'quoted' ? `q:${w.text}` : w.kind)
+
+/**
+ * Defence in depth: re-lex the rewritten SQL with the dialect lexer and make
+ * sure the injected predicate is a top-level conjunct of the outer WHERE —
+ * balanced parentheses, the same FROM items, and a WHERE body made of exactly
+ * `(pred) AND (existing)` or exactly `pred`. Anything else (a stray `)`, a
+ * top-level OR next to the predicate, a comment swallowing it) is refused.
+ */
+function verifyInjection(out, pred, hadWhere, tables, dialect) {
+  const fail = () => { throw new FilterInjectionError('filter predicate could not be injected as a top-level condition; query refused') }
+  const lexed = lexSql(out, { dialect })
+  if (lexed.unterminated) fail()
+  let depth = 0
+  for (const seg of lexed.segments) {
+    if (seg.kind !== 'code') continue
+    for (const c of seg.text) {
+      if (c === '(') depth++
+      else if (c === ')' && --depth < 0) fail()
+    }
+  }
+  if (depth !== 0) fail()
+  const outer = parseOuterQuery(out, { dialect })
+  if (!outer?.where) fail()
+  const sameTables = outer.tables.length === tables.length && outer.tables.every((t, k) => t.name === tables[k].name && t.alias === tables[k].alias)
+  if (!sameTables) fail()
+  const body = topLevelWords(out, dialect).filter(w => w.start >= outer.where.keywordEnd && w.start < outer.where.end).map(tokenSig)
+  const expected = hadWhere ? ['open', 'close', 'w:AND', 'open', 'close'] : topLevelWords(pred, dialect).map(tokenSig)
+  if (body.length !== expected.length || body.some((t, k) => t !== expected[k])) fail()
+  // The predicate text must sit right after WHERE (inside the first parenthesis when ANDed with an existing condition).
+  const at = out.slice(outer.where.keywordEnd).replace(/^\s+/, '')
+  if (!at.startsWith(hadWhere ? `(${pred})` : pred)) fail()
+}

package/index.js

@@ -25,6 +25,7 @@ import { methods as m8 } from './service/alerts.js'
 import { methods as m9 } from './service/uploads.js'
 import { methods as m10 } from './service/admin.js'
 import { methods as mSuggest } from './service/suggestions.js'
+import { FEATURES } from './service/features.js'
 const { CHART_TYPES, DEFAULT_SETTINGS, RECORD_KINDS, RPC_PATH, Records, UserError, newId, pick, toUserError } = shared
 
 export const name = 'nl2sql'
@@ -124,6 +125,16 @@ class Nl2SqlService {
     return this.writing
   }
 
+  /**
+   * Scheduler jobs contributed by feature modules: every prototype method named
+   * `jobs_<feature>(now)` returns an array of { id, due(now), run() }.
+   */
+  schedulerJobs(now) {
+    const out = []
+    for (const k of Object.getOwnPropertyNames(Nl2SqlService.prototype)) if (k.startsWith('jobs_')) { try { out.push(...(this[k](now) ?? [])) } catch (error) { console.warn('nl2sql: %s failed: %s', k, error.message) } }
+    return out
+  }
+
   async dispose() {
     this.disposed = true
     if (this.alertTimer) clearInterval(this.alertTimer)
@@ -145,7 +156,7 @@ class Nl2SqlService {
   }
 
 }
-for (const m of [m0, m1, m2, m3, m4, m5, mChannels, m6, m7, m8, m9, m10, mSuggest]) Object.defineProperties(Nl2SqlService.prototype, Object.getOwnPropertyDescriptors(m))
+for (const m of [m0, m1, m2, m3, m4, m5, mChannels, m6, m7, m8, m9, m10, mSuggest, ...FEATURES.map(f => f.methods)]) Object.defineProperties(Nl2SqlService.prototype, Object.getOwnPropertyDescriptors(m))
 const DATASOURCE_PARAM = { type: 'string', description: 'Data source id or name. Omit to use the one bound to this session.' }
 
 function textBlock(text) {
@@ -188,7 +199,8 @@ function registerTools(ctx, service) {
         if (!args.datasource) throw new Error('`datasource` is required for action=use')
         const ds = service.requireDatasource(args.datasource)
         service.assertAccess(actor, ds)
-        const info = await service.bindSession(sessionId, ds.id)
+        // The agent tool binds only this session; the page's current data source is left alone.
+        const info = await service.bindSession(sessionId, ds.id, { setCurrent: false })
         return { bound: info.datasourceId, datasources: visible.map(d => pick(d, ['id', 'name', 'type', 'database', 'serverVersion'])) }
       }
       const info = sessionId ? service.sessionInfo(sessionId) : null
@@ -353,7 +365,8 @@ function registerOverviewTool(ctx, service) {
         const ds = service.datasourceForSession(exec.agent?.id, args.datasource)
         service.assertCanWriteSql(service.actorFor(exec.agent?.id), '生成自动概览')
         if (args.pin && service.actorFor(exec.agent?.id)) throw new Error('只有本机用户可以把图表固定到看板')
-        const { table, results } = await service.tableOverview({ datasourceId: ds.id, table: args.table, pin: Boolean(args.pin) })
+        const sessionId = exec.agent?.id
+        const { table, results } = await service.tableOverview({ datasourceId: ds.id, table: args.table, pin: Boolean(args.pin), sessionId, actor: service.actorFor(sessionId), source: 'agent' })
         return {
           model: { table, pinned: Boolean(args.pin), charts: results.map(r => (r.error ? { title: r.title, error: r.error } : { title: r.title, ...service.modelView(r) })) },
           display: { overview: true, table, results: results.map(r => (r.error ? { title: r.title, sql: r.sql, error: r.error } : displayMeta(r))) },
@@ -426,6 +439,8 @@ function displayMeta(result) {
 
 function registerRpc(ctx, service) {
   const methods = {
+    // Feature modules (service/features.js) contribute RPCs as rpc(service) → { name: fn }.
+    ...Object.assign({}, ...FEATURES.map(f => f.rpc?.(service) ?? {})),
     listDatasources: () => service.listDatasources(),
     saveDatasource: (p) => service.saveDatasource(p),
     deleteDatasource: (p) => service.deleteDatasource(p.id),
@@ -589,6 +604,9 @@ export async function apply(ctx, config) {
   service.startBots().catch(error => console.warn('nl2sql bot: start failed: %s', error.message))
   service.scheduleAlerts()
   registerAnalysisTools(ctx, service)
+  // Feature modules register their own agent tools: tools(ctx, service, helpers).
+  for (const f of FEATURES) f.tools?.(ctx, service, { displayMeta, textBlock, DATASOURCE_PARAM })
+  for (const f of FEATURES) f.start?.(ctx, service)
 }
 
 function registerAnalysisTools(ctx, service) {