node-resource-utils 0.0.0-stage → 1.1.7

package/resources/src/lib/ai.ts

@@ -0,0 +1,310 @@
+/**
+ * 本地大模型客户端（服务端专用）。
+ *
+ * 为什么要有这个：比赛本身就是"用 AI 造系统"，
+ * 如果造出来的系统里**没有真正的 AI 功能**，就和其他队伍站在同一起跑线上了。
+ * 把"调本地模型"这件事在骨架里封好，模型只需要把业务数据拼进 prompt。
+ *
+ * 约定：
+ *   - 地址/模型名走环境变量，换机器不用改代码
+ *   - 只在服务端调用（API Key 不能进浏览器）
+ *   - 统一超时 + 统一错误 → 面向用户的中文提示
+ */
+
+/**
+ * 配置来源：`AI_*` 优先，`OPENAI_*` 兜底。
+ *
+ * ★ 为什么两套都认：提示词里让 AI 去 `.env` 找 `OPENAI_BASE_URL / OPENAI_API_KEY / OPENAI_MODEL`
+ *   （这是业界最常见的叫法），而骨架一开始只读 `AI_*`。两边对不上时，用户按提示词
+ *   填了 `OPENAI_*`，`/api/ai/chat` 却仍走默认地址 —— 表现为"配了也没用"，且没有任何报错。
+ *   `openaiCompat.ts` 早就是两套都认的写法，这里补一致，避免同一个模型有两个入口
+ *   却有两条不同的配置路径。
+ */
+const pickEnv = (...names: string[]): string | undefined => {
+  for (const n of names) {
+    const v = process.env[n];
+    if (v && v.trim()) return v.trim();
+  }
+  return undefined;
+};
+
+/** 本地引擎地址，默认就是赛前测好的 8092 */
+export const AI_BASE_URL =
+  pickEnv('AI_BASE_URL', 'OPENAI_BASE_URL') ?? 'http://127.0.0.1:8092/v1';
+/** 模型 id，必须与引擎启动时的 --model-id 一致 */
+export const AI_MODEL = pickEnv('AI_MODEL', 'OPENAI_MODEL') ?? 'qwen3.8-27b-gsq';
+/** 本地引擎一般不校验 key，但 OpenAI 兼容接口要求这个头存在 */
+export const AI_API_KEY = pickEnv('AI_API_KEY', 'OPENAI_API_KEY') ?? 'local';
+
+export interface AiMessage {
+  role: 'system' | 'user' | 'assistant' | 'tool';
+  content: string;
+  /** 模型要调工具时，这一轮返回里带着它（原样回传，不要自己拼） */
+  tool_calls?: {
+    id: string;
+    type: 'function';
+    function: { name: string; arguments: string };
+  }[];
+  /** role='tool' 时，对应哪一次调用 */
+  tool_call_id?: string;
+}
+
+export interface AiOptions {
+  system?: string;
+  messages: AiMessage[];
+  maxTokens?: number;
+  temperature?: number;
+  timeoutMs?: number;
+}
+
+export class AiError extends Error {
+  constructor(message: string, readonly hint?: string) {
+    super(message);
+    this.name = 'AiError';
+  }
+}
+
+/**
+ * 调本地模型，返回完整文本。
+ *
+ * 用它做"一次性生成"：周报、数据解读、摘要、建议。
+ * 需要打字机效果时用 `streamAiChat`。
+ */
+export async function aiChat(opts: AiOptions): Promise<string> {
+  const { system, messages, maxTokens = 1024, temperature = 0.5, timeoutMs = 180_000 } = opts;
+
+  const body = {
+    model: AI_MODEL,
+    messages: system ? [{ role: 'system', content: system }, ...messages] : messages,
+    max_completion_tokens: maxTokens,
+    temperature,
+    enable_thinking: false,
+    thinking: { type: 'disabled' },
+    reasoning_effort: 'none',
+    stream: false,
+  };
+
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const res = await fetch(`${AI_BASE_URL}/chat/completions`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${AI_API_KEY}` },
+      body: JSON.stringify(body),
+      signal: ctrl.signal,
+      // Next.js 里不要缓存推理结果
+      cache: 'no-store',
+    });
+    if (!res.ok) {
+      const t = await res.text().catch(() => '');
+      throw new AiError(`本地模型返回 ${res.status}`, t.slice(0, 300));
+    }
+    const data = (await res.json()) as {
+      choices?: { message?: { content?: string } }[];
+    };
+    const text = data.choices?.[0]?.message?.content ?? '';
+    if (!text.trim()) throw new AiError('本地模型返回了空内容');
+    return text.trim();
+  } catch (e) {
+    if (e instanceof AiError) throw e;
+    if ((e as Error).name === 'AbortError') {
+      throw new AiError('本地模型响应超时', '引擎可能没启动，或并发太高（--max-concurrency 1）');
+    }
+    throw new AiError(
+      `连不上本地模型：${(e as Error).message}`,
+      `确认引擎已启动，且 ${AI_BASE_URL} 可访问（AI_BASE_URL 环境变量可覆盖）`
+    );
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** 流式版本，逐段回调，用于打字机效果 */
+export async function streamAiChat(
+  opts: AiOptions,
+  onDelta: (chunk: string) => void
+): Promise<void> {
+  const { system, messages, maxTokens = 1024, temperature = 0.5, timeoutMs = 300_000 } = opts;
+
+  const body = {
+    model: AI_MODEL,
+    messages: system ? [{ role: 'system', content: system }, ...messages] : messages,
+    max_completion_tokens: maxTokens,
+    temperature,
+    enable_thinking: false,
+    thinking: { type: 'disabled' },
+    reasoning_effort: 'none',
+    stream: true,
+  };
+
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const res = await fetch(`${AI_BASE_URL}/chat/completions`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${AI_API_KEY}` },
+      body: JSON.stringify(body),
+      signal: ctrl.signal,
+      cache: 'no-store',
+    });
+    if (!res.ok || !res.body) throw new AiError(`本地模型返回 ${res.status}`);
+
+    const reader = res.body.getReader();
+    const dec = new TextDecoder();
+    let buf = '';
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buf += dec.decode(value, { stream: true });
+      // SSE：逐行取 data: 后面的 JSON
+      let idx: number;
+      while ((idx = buf.indexOf('\n')) >= 0) {
+        const line = buf.slice(0, idx).trim();
+        buf = buf.slice(idx + 1);
+        if (!line.startsWith('data:')) continue;
+        const payload = line.slice(5).trim();
+        if (payload === '[DONE]') return;
+        try {
+          const j = JSON.parse(payload) as {
+            choices?: { delta?: { content?: string } }[];
+          };
+          const c = j.choices?.[0]?.delta?.content;
+          if (c) onDelta(c);
+        } catch {
+          /* 忽略半包 */
+        }
+      }
+    }
+  } catch (e) {
+    if (e instanceof AiError) throw e;
+    if ((e as Error).name === 'AbortError') throw new AiError('本地模型响应超时');
+    throw new AiError(`连不上本地模型：${(e as Error).message}`);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/* ============================ 工具调用（function calling） ============================ */
+
+/** 模型提出的一次工具调用 */
+export interface ToolCallRequest {
+  id: string;
+  name: string;
+  args: Record<string, unknown>;
+  /** 原始 JSON 字符串。回传给模型时必须原样，否则有的引擎会报 arguments 格式错 */
+  raw: string;
+}
+
+export interface ToolTurn {
+  /** 模型这一轮的文字说明（可能为空，尤其当它只想调工具时） */
+  content: string;
+  toolCalls: ToolCallRequest[];
+}
+
+/**
+ * 带工具的一轮调用（非流式）。
+ *
+ * ★ 为什么工具阶段不用流式：
+ *   `tool_calls` 在 SSE 里是**分片**下发的，同一个调用的 name 和 arguments
+ *   会跨多个 chunk 拼接，稍不留神就拼出半个 JSON。
+ *   工具轮只关心"要不要调、调什么"，等这一轮完整返回更稳；
+ *   拿到结果之后的**最终回答**照旧走 `streamAiChat`，打字机效果不受影响。
+ *
+ * ★ 调用方要保证 messages 里保留了完整的 tool 往返：
+ *   assistant(tool_calls) → tool(tool_call_id)。
+ *   只把工具结果塞进 user 消息里，模型会当成"用户说的话"而重复调用工具。
+ */
+export async function aiChatWithTools(
+  opts: AiOptions & { tools: unknown[]; toolChoice?: 'auto' | 'none' | 'required' }
+): Promise<ToolTurn> {
+  const { system, messages, tools, toolChoice = 'auto', maxTokens = 800, temperature = 0.2 } = opts;
+
+  const body = {
+    model: AI_MODEL,
+    messages: system ? [{ role: 'system', content: system }, ...messages] : messages,
+    tools,
+    tool_choice: toolChoice,
+    max_completion_tokens: maxTokens,
+    temperature,
+    enable_thinking: false,
+    thinking: { type: 'disabled' },
+    reasoning_effort: 'none',
+    stream: false,
+  };
+
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), 180_000);
+  try {
+    const res = await fetch(`${AI_BASE_URL}/chat/completions`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${AI_API_KEY}` },
+      body: JSON.stringify(body),
+      signal: ctrl.signal,
+      cache: 'no-store',
+    });
+    if (!res.ok) {
+      const t = await res.text().catch(() => '');
+      throw new AiError(`本地模型返回 ${res.status}`, t.slice(0, 300));
+    }
+
+    const data = (await res.json()) as {
+      choices?: {
+        message?: {
+          content?: string | null;
+          tool_calls?: {
+            id?: string;
+            type?: string;
+            function?: { name?: string; arguments?: unknown };
+          }[];
+        };
+      }[];
+    };
+    const msg = data.choices?.[0]?.message;
+    const calls: ToolCallRequest[] = [];
+
+    for (const [i, c] of (msg?.tool_calls ?? []).entries()) {
+      const name = c?.function?.name ?? '';
+      if (!name) continue;
+      // arguments 正常是 JSON 字符串，个别网关直接给对象
+      const raw =
+        typeof c.function?.arguments === 'string'
+          ? c.function.arguments
+          : JSON.stringify(c.function?.arguments ?? {});
+      let args: Record<string, unknown> = {};
+      try {
+        const parsed = JSON.parse(raw || '{}');
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+          args = parsed as Record<string, unknown>;
+        }
+      } catch {
+        // 模型给了半截 JSON：当成空参数，让工具层报"缺必填"，它会自己重来
+      }
+      calls.push({ id: c.id ?? `call_${i}`, name, args, raw: raw || '{}' });
+    }
+
+    return { content: (msg?.content ?? '').trim(), toolCalls: calls };
+  } catch (e) {
+    if (e instanceof AiError) throw e;
+    if ((e as Error).name === 'AbortError') {
+      throw new AiError('本地模型响应超时', '引擎可能没启动，或并发太高（--max-concurrency 1）');
+    }
+    throw new AiError(
+      `连不上本地模型：${(e as Error).message}`,
+      `确认引擎已启动，且 ${AI_BASE_URL} 可访问（AI_BASE_URL 环境变量可覆盖）`
+    );
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * 把模型输出里的 Markdown 表格/列表做轻量清洗，
+ * 免得直接塞进页面时带着 ``` 围栏或多余空行。
+ */
+export function cleanAiText(s: string): string {
+  return s
+    .replace(/^```[a-z]*\n?/i, '')
+    .replace(/\n?```$/i, '')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}

package/resources/src/lib/aiContext.ts

@@ -0,0 +1,357 @@
+import { prisma } from '@/lib/prisma';
+import ONTOLOGY from '@/lib/ontology';
+import { APP_NAME } from '@/lib/appInfo';
+
+/**
+ * AI 助手的统一上下文：当前时间 + 数据库快照。
+ *
+ * 为什么要有这个文件：
+ *   1. 模型不知道"现在"是几号 —— 问"这个月有几条申请"它只能瞎猜。
+ *      这里把北京时间、"本月/上月"的具体区间一起塞进 system prompt。
+ *   2. 一个对话框要同时回答"系统怎么用"和"库里有多少条"，
+ *      就必须每次都把业务数据快照带上，而不是分两个接口。
+ *   3. /api/ai/chat（流式）和 /api/ai/ask（非流式）共用同一套上下文，避免两边漂移。
+ *
+ * 注意：快照只读、只读 ontology 声明的业务表，且 User/Role 这类敏感表永远排除。
+ */
+
+/** 绝对不允许进快照的表 */
+const BLOCKED = new Set(['User', 'Role', 'Menu', 'UserRole', 'RoleMenu']);
+
+/**
+ * 每张表最多带多少行。
+ *
+ * ★ 从 30 降到 6：不是因为截断省事，而是架构变了 ——
+ *   助手现在能调 query_* 工具做精确查询，快照的作用从"数据来源"
+ *   退化成"让模型知道库里长什么样、字段怎么命名"。
+ *   继续塞 30 行只会挤占上下文、拖慢首字，且永远算不出全量。
+ */
+export const ROWS_PER_TABLE = 6;
+/** 单个字段值最长多少字符 */
+const MAX_FIELD_LEN = 40;
+/** 快照总字符上限（防止 prompt 爆掉） */
+const MAX_SNAPSHOT_CHARS = 7000;
+
+/** 北京时间固定 UTC+8（比赛机器在国内，不依赖服务器时区设置） */
+const TZ_OFFSET_MS = 8 * 3600_000;
+const WEEKDAYS = ['星期日', '星期一', '星期二', '星期三', '星期四', '星期五', '星期六'];
+
+interface RtField {
+  name: string;
+  kind?: string;
+  type?: string;
+}
+
+function rtModels(): Record<string, { fields?: RtField[] }> {
+  const rt = (prisma as unknown as {
+    _runtimeDataModel?: { models?: Record<string, { fields?: RtField[] }> };
+  })._runtimeDataModel;
+  return rt?.models ?? {};
+}
+
+interface Delegate {
+  findMany: (a?: unknown) => Promise<Record<string, unknown>[]>;
+  count: (a?: unknown) => Promise<number>;
+}
+
+function delegateOf(model: string): Delegate | null {
+  const d = (prisma as unknown as Record<string, unknown>)[model] as Partial<Delegate> | undefined;
+  return d && typeof d.findMany === 'function' && typeof d.count === 'function'
+    ? (d as Delegate)
+    : null;
+}
+
+/** 标量字段（排除关系字段与敏感字段） */
+function scalarFieldsOf(model: string): string[] {
+  const fields = rtModels()[model]?.fields ?? [];
+  return fields
+    .filter((f) => !f.kind || f.kind === 'scalar')
+    .map((f) => f.name)
+    .filter((n) => n !== 'password' && n !== 'deletedAt');
+}
+
+/** 时间字段：优先 createdAt，否则第一个 DateTime 字段 */
+function dateFieldOf(model: string): string | null {
+  const fields = rtModels()[model]?.fields ?? [];
+  if (fields.some((f) => f.name === 'createdAt' && (!f.kind || f.kind === 'scalar'))) {
+    return 'createdAt';
+  }
+  const dt = fields.find(
+    (f) => (!f.kind || f.kind === 'scalar') && (f.type === 'DateTime' || f.type === 'Date')
+  );
+  return dt?.name ?? null;
+}
+
+function hasField(model: string, name: string): boolean {
+  return (rtModels()[model]?.fields ?? []).some((f) => f.name === name);
+}
+
+export interface NowContext {
+  date: string;
+  time: string;
+  weekday: string;
+  /** 本月，形如 2026-10 */
+  month: string;
+  monthStart: string;
+  monthEnd: string;
+  /** 上月，形如 2026-09 */
+  prevMonth: string;
+  prevMonthStart: string;
+  prevMonthEnd: string;
+  /** 供数据库查询用的 UTC 边界 */
+  monthStartUtc: Date;
+  nextMonthUtc: Date;
+  todayStartUtc: Date;
+  tomorrowStartUtc: Date;
+}
+
+const pad = (n: number) => String(n).padStart(2, '0');
+
+/** 当前时间（北京时间）。所有"本月/上月/今天"的推算都以它为准 */
+export function nowContext(now = new Date()): NowContext {
+  const b = new Date(now.getTime() + TZ_OFFSET_MS);
+  const y = b.getUTCFullYear();
+  const m = b.getUTCMonth() + 1;
+  const d = b.getUTCDate();
+
+  const daysInMonth = new Date(Date.UTC(y, m, 0)).getUTCDate();
+  const prevY = m === 1 ? y - 1 : y;
+  const prevM = m === 1 ? 12 : m - 1;
+  const prevDays = new Date(Date.UTC(prevY, prevM, 0)).getUTCDate();
+
+  const todayStartUtc = new Date(Date.UTC(y, m - 1, d) - TZ_OFFSET_MS);
+  return {
+    date: `${y}-${pad(m)}-${pad(d)}`,
+    time: `${pad(b.getUTCHours())}:${pad(b.getUTCMinutes())}`,
+    weekday: WEEKDAYS[b.getUTCDay()],
+    month: `${y}-${pad(m)}`,
+    monthStart: `${y}-${pad(m)}-01`,
+    monthEnd: `${y}-${pad(m)}-${pad(daysInMonth)}`,
+    prevMonth: `${prevY}-${pad(prevM)}`,
+    prevMonthStart: `${prevY}-${pad(prevM)}-01`,
+    prevMonthEnd: `${prevY}-${pad(prevM)}-${pad(prevDays)}`,
+    monthStartUtc: new Date(Date.UTC(y, m - 1, 1) - TZ_OFFSET_MS),
+    nextMonthUtc: new Date(Date.UTC(y, m, 1) - TZ_OFFSET_MS),
+    todayStartUtc,
+    tomorrowStartUtc: new Date(todayStartUtc.getTime() + 86400_000),
+  };
+}
+
+/** 给模型看的时间说明 */
+export function nowPrompt(now = nowContext()): string {
+  return [
+    `【当前时间】${now.date} ${now.time} ${now.weekday}（北京时间）`,
+    `- 今天 = ${now.date}；本月 = ${now.month}（${now.monthStart} 至 ${now.monthEnd}）；上月 = ${now.prevMonth}（${now.prevMonthStart} 至 ${now.prevMonthEnd}）`,
+    '- 用户说"这个月/本月"就指上面本月区间；说"今天/昨天/最近N天"都以今天为基准往前推。',
+  ].join('\n');
+}
+
+/** 把一行压成紧凑文本 */
+function compactRow(row: Record<string, unknown>, fields: string[]): string {
+  const keep: Record<string, unknown> = {};
+  for (const f of fields) {
+    const v = row[f];
+    if (v === undefined || v === null) continue;
+    if (v instanceof Date) keep[f] = v.toISOString().slice(0, 10);
+    else if (typeof v === 'string') {
+      keep[f] = v.length > MAX_FIELD_LEN ? `${v.slice(0, MAX_FIELD_LEN)}…` : v;
+    } else if (typeof v === 'number' || typeof v === 'boolean') {
+      keep[f] = v;
+    }
+    // 关系对象/数组一律跳过
+  }
+  return JSON.stringify(keep);
+}
+
+export interface TableSnapshot {
+  model: string;
+  total: number;
+  /** 本月新增条数（有时间字段时才有） */
+  monthTotal?: number;
+  /** 今日新增条数 */
+  todayTotal?: number;
+  dateField: string | null;
+  fields: string[];
+  rows: string[];
+}
+
+/**
+ * 采集数据库快照。
+ *
+ * 除了样例行，还给每张表预算好「共几条 / 本月几条 / 今日几条」——
+ * 这是"这个月有多少条"这种问题能被答对的关键：样例只有 30 行，
+ * 模型自己数样例永远算不出全量。
+ */
+export async function buildSnapshot(scope: string[] = [], rowsPerTable = ROWS_PER_TABLE): Promise<TableSnapshot[]> {
+  const allModels = Object.keys(rtModels());
+  const declared = ONTOLOGY.entities.map((e) => e.model);
+  const candidates = (scope.length ? scope : declared.length ? declared : allModels).filter(
+    (m) => allModels.includes(m) && !BLOCKED.has(m)
+  );
+
+  const now = nowContext();
+  const out: TableSnapshot[] = [];
+  let budget = MAX_SNAPSHOT_CHARS;
+
+  for (const model of candidates) {
+    if (budget <= 0) break;
+    const d = delegateOf(model);
+    if (!d) continue;
+
+    const fields = scalarFieldsOf(model);
+    const dateField = dateFieldOf(model);
+    const baseWhere = hasField(model, 'deletedAt') ? { deletedAt: null } : {};
+    const count = (extra: Record<string, unknown> = {}) =>
+      d.count({ where: { ...baseWhere, ...extra } }).catch(() => d.count());
+
+    try {
+      const rows = await d
+        .findMany({
+          where: baseWhere,
+          take: rowsPerTable,
+          ...(dateField ? { orderBy: { [dateField]: 'desc' } } : {}),
+        })
+        .catch(() => d.findMany({ take: rowsPerTable }));
+
+      const total = await count();
+      const monthTotal = dateField
+        ? await count({ [dateField]: { gte: now.monthStartUtc, lt: now.nextMonthUtc } })
+        : undefined;
+      const todayTotal = dateField
+        ? await count({ [dateField]: { gte: now.todayStartUtc, lt: now.tomorrowStartUtc } })
+        : undefined;
+
+      const lines = rows.map((r) => compactRow(r, fields)).filter(Boolean);
+      budget -= lines.join('\n').length + 120;
+      out.push({ model, total, monthTotal, todayTotal, dateField, fields, rows: lines });
+    } catch {
+      // 表结构与预期不符就跳过，不影响其他表
+      continue;
+    }
+  }
+  return out;
+}
+
+/** 快照转成给模型看的文本 */
+export function snapshotToText(snapshot: TableSnapshot[], now = nowContext()): string {
+  return snapshot
+    .map((t) => {
+      const stats = [`共 ${t.total} 条`];
+      if (t.monthTotal !== undefined) stats.push(`本月(${now.month}) ${t.monthTotal} 条`);
+      if (t.todayTotal !== undefined) stats.push(`今日 ${t.todayTotal} 条`);
+      const head = `### 表 ${t.model}（${stats.join('；')}${t.dateField ? `；时间字段 ${t.dateField}` : ''}）`;
+      const fieldLine = t.fields.length ? `字段：${t.fields.join(', ')}` : '';
+      const rowLine = t.rows.length
+        ? `最近 ${t.rows.length} 条（按时间倒序）：\n${t.rows.join('\n')}`
+        : '（无数据）';
+      return `${head}\n${fieldLine}\n${rowLine}`;
+    })
+    .join('\n\n');
+}
+
+export interface AssistantContext {
+  system: string;
+  snapshot: TableSnapshot[];
+  now: NowContext;
+}
+
+export interface AssistantUser {
+  id: string;
+  name: string;
+  username: string;
+}
+
+export interface AssistantOptions {
+  withData?: boolean;
+  scope?: string[];
+  /** 当前登录用户。有它模型才能把"我""本人"落到具体的人身上 */
+  user?: AssistantUser;
+  /** 本次请求是否挂载了工具。false 时不写工具规则，避免模型凭空调不存在的工具 */
+  tools?: boolean;
+  /**
+   * 每张表带几行样例。
+   *
+   * 默认 6（chat 有工具，数据靠工具查）。
+   * 没有工具的调用方（/api/ai/ask）要传大一点，否则它只能看到几行，答不准。
+   */
+  rows?: number;
+}
+
+/**
+ * 组装统一助手的 system prompt。
+ *
+ * extra 是调用方追加的角色说明（会被截断，防止把上下文挤爆）。
+ * withData=false 时只要时间不要数据（比如纯使用答疑）。
+ */
+export async function buildAssistantContext(
+  extra?: string,
+  opts: AssistantOptions = {}
+): Promise<AssistantContext> {
+  const now = nowContext();
+  const snapshot =
+    opts.withData === false
+      ? []
+      : await buildSnapshot(opts.scope ?? [], opts.rows ?? ROWS_PER_TABLE);
+
+  const parts: string[] = [
+    `你是「${APP_NAME}」的内置助手。你既能回答这个系统怎么用，也能基于数据库里的真实数据回答业务问题。`,
+    nowPrompt(now),
+  ];
+
+  if (opts.user) {
+    parts.push(
+      `【当前操作人】${opts.user.name}（账号 ${opts.user.username}，用户 id = ${opts.user.id}）\n` +
+        '- 用户说"我 / 我的"时指这个人；涉及"操作人 / 申请人 / 提交人"这类字段，默认就是此人的 id。\n' +
+        '- 不要向用户索要自己的账号或 id。'
+    );
+  }
+
+  if (snapshot.length) {
+    parts.push(
+      `【数据库快照】下面是数据库里的真实内容（不是示例）。用户问数据时只能依据它回答。\n\n` +
+        snapshotToText(snapshot, now)
+    );
+  }
+
+  if (opts.tools) {
+    parts.push(
+      `【你能操作数据，不只是聊天】
+本次挂了工具，用法：
+1. query_<表>：只读查询，可按字段筛选、关键字搜索、分组统计。
+   问"有多少条 / 哪个部门最多 / 各状态各几条 / 有哪些"这类问题时**必须调用它**，
+   不要拿快照里的几行样例去估算 —— 快照只是让你知道表长什么样、字段怎么命名。
+2. create_<表>：新建一条记录。**调用后不会立即写库**，
+   界面上会出现一张确认卡片，等用户点「确认」才真正生效。
+   所以调用之后要对用户说"请在下方确认卡片上核对并确认"，
+   **绝对不要说"已经为你创建好了"**。
+3. 信息不全时，**直接把工具调出去**（哪怕只填得出一半参数）。
+   系统会自动弹出一张结构化表单：日期是日期选择器、状态是下拉框、必填项有标记，
+   用户填完提交后系统会直接生成确认卡。
+   所以不要因为"不知道从哪天开始"就停下来先问，
+   也不要用文字把缺的字段一条条列出来让用户自己打字 —— 表单比你问得准。
+4. 只有一种情况用 ask_user：要问什么取决于用户的选择，
+   或者必须先问清楚才能决定查哪张表。fields 只写字段名（如 ["startDate","endDate"]），
+   不要写中文标签，也不要自己编字段名。
+5. 不要编造：日期、姓名、事由、外键 id 都不能猜。
+   外键字段（如 deptId / vehicleId / employeeId）如果用户只说了名称，
+   表单会给出下拉选项让用户自己选 —— 你不要填 id，也不要填名称。
+6. 用户说"我 / 我的"时，申请人 / 提交人 / 负责人就是当前操作人，
+   直接用上面的用户 id，**不要问用户"你的 id 是多少"**。
+7. 一次只做一件事：用户说了三件事就分三轮做，别在一个调用里塞多个动作。`
+    );
+  }
+
+  parts.push(
+    `【回答规则】
+1. 问数据：能用工具就用工具，数字和名称要具体，并说明结论来自哪张表；确实查不到就直说缺什么，不要猜。
+2. 问用法：按模块给出可执行的步骤。
+3. 涉及"本月/这个月/今天/上个月/最近N天"时，用上面的当前时间推算，不要自己假设日期。
+4. 输出用 Markdown（小标题、列表、必要时表格），不要把整段答案包在 \`\`\` 里。
+5. 中文回答，简洁具体，不堆术语。`
+  );
+
+  const extraText = String(extra ?? '').trim();
+  if (extraText) parts.push(`【补充角色说明】${extraText.slice(0, 800)}`);
+
+  return { system: parts.join('\n\n'), snapshot, now };
+}