node-resource-utils 0.0.0-stage → 1.1.7

package/resources/src/lib/aiForm.ts

@@ -0,0 +1,532 @@
+import ONTOLOGY from '@/lib/ontology';
+import { coercePayload, optionsOf, type FieldMeta, type FieldOption } from '@/lib/graph-schema';
+import { isBlank, writableFields, writeToolInfo, type HandTool } from '@/lib/aiTools';
+import { inferValidationType } from '@/lib/validation';
+import { readPayload, signPayload, TOKEN_TTL_MS, type PayloadCheck } from '@/lib/aiToken';
+import type {
+  FormFieldKind,
+  FormFieldOption,
+  FormFieldSpec,
+  FormMode,
+  FormSpec,
+} from '@/lib/aiFormTypes';
+
+/**
+ * AI 输入表单生成器 —— 把"模型要问的信息"翻译成"用户能填的表单"。
+ *
+ * ★ 一句话原则：**字段定义只能来自 schema，不能来自模型的想象。**
+ *   模型负责说"我还缺哪些字段"（甚至只给字段名），
+ *   至于这个字段该用日期选择器还是下拉框、下拉里有哪些选项、
+ *   能不能为空、中文名叫什么 —— 全部由 `prisma/schema.prisma` +
+ *   `ontology.ts` 反推。于是换业务（请销假 / 派车 / 报销）不用改这里一行。
+ *
+ * ★ 两个入口：
+ *   - `buildWriteForm(工具名, 已填参数)` —— 写工具参数不全时自动弹，
+ *     提交后由服务端直接签动作令牌，**不再让模型重解析一遍**（少一次出错机会）。
+ *   - `buildAskForm(模型给的参数)` —— 模型主动调 ask_user 时弹，
+ *     可以绑到某个写工具（走 schema 定义），也可以是天马行空的自由追问。
+ *
+ * ★ 表单令牌里存了什么：工具名、已填参数、允许提交的字段白名单、标题、过期时间。
+ *   白名单是关键 —— 前端多塞一个 `roleId` 进来会被直接丢掉，
+ *   和确认令牌一样，前端改不动真正执行的内容。
+ */
+
+/** 一张表单最多问几项。超过就不是"补两个字段"，是在让人填一张长表 */
+const MAX_FIELDS = 6;
+
+/** 表单令牌载荷（短键是为了让令牌别太长） */
+export interface FormTokenPayload {
+  k: 'form';
+  u: string;
+  /** 写工具名；自由追问时为空 */
+  n: string;
+  m: FormMode;
+  /** 已填参数（写工具） */
+  a: Record<string, unknown>;
+  /** 允许提交的字段白名单（name + label，label 用于回灌文案） */
+  f: { n: string; l: string }[];
+  t: string;
+  d?: string;
+  e: number;
+}
+
+export function readFormToken(token: unknown, userId: string): PayloadCheck<FormTokenPayload> {
+  const r = readPayload<FormTokenPayload>(token, userId);
+  if (!r.ok) return r;
+  // 和确认令牌互斥：两种令牌能做的事完全不同，不能互相冒充
+  if (r.payload.k !== 'form') return { ok: false, error: '令牌类型不对，请重新发起' };
+  return r;
+}
+
+/* ---------------------------- 值的整形 ---------------------------- */
+
+function pad(n: number): string {
+  return String(n).padStart(2, '0');
+}
+
+/** 本地日期。不能用 toISOString：东八区凌晨 0~8 点会算成前一天 */
+function localDate(d: Date): string {
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+}
+
+function today(): string {
+  return localDate(new Date());
+}
+
+/** 任意日期值 → `YYYY-MM-DD`。纯日期字符串直接截取，避免时区偏移 */
+function dateText(v: unknown): string | undefined {
+  if (isBlank(v)) return undefined;
+  if (v instanceof Date) return Number.isNaN(v.getTime()) ? undefined : localDate(v);
+  const s = String(v).trim();
+  const m = /^(\d{4})-(\d{2})-(\d{2})/.exec(s);
+  if (m) return `${m[1]}-${m[2]}-${m[3]}`;
+  const d = new Date(s);
+  return Number.isNaN(d.getTime()) ? undefined : localDate(d);
+}
+
+/**
+ * 把模型给的值对齐到选项上。
+ *
+ * ★ 这是很常见的一类错误：模型填了「技术部」而不是部门 id，
+ *   或者填了「年假」而不是枚举值 `annual`。表单里如果能对上，
+ *   就在打开时换成正解 —— 比让用户在确认卡上看到"没选"好得多。
+ */
+function matchOption(v: unknown, options?: FormFieldOption[]): unknown {
+  if (!options?.length || isBlank(v)) return v;
+  const s = String(v).trim();
+  const byValue = options.find((o) => String(o.value) === s);
+  if (byValue) return byValue.value;
+  const byLabel =
+    options.find((o) => o.label === s) ??
+    options.find((o) => o.label.includes(s) || s.includes(o.label));
+  return byLabel ? byLabel.value : v;
+}
+
+function controlValue(
+  kind: FormFieldKind,
+  v: unknown,
+  options?: FormFieldOption[]
+): FormFieldSpec['value'] {
+  if (v === false || v === 0) return v;
+  if (isBlank(v)) return undefined;
+  switch (kind) {
+    case 'date':
+      return dateText(v);
+    case 'number': {
+      const n = Number(v);
+      return Number.isFinite(n) ? n : undefined;
+    }
+    case 'boolean':
+      return v === true || v === 'true' || v === 1 || v === '1';
+    case 'enum':
+    case 'fk':
+      return matchOption(v, options) as string | number;
+    default:
+      return String(v);
+  }
+}
+
+function isUnset(v: FormFieldSpec['value']): boolean {
+  return v === undefined || v === null || (typeof v === 'string' && v.trim() === '');
+}
+
+function formKind(f: FieldMeta): FormFieldKind {
+  if (f.kind === 'datetime') return 'date';
+  if (f.kind === 'longtext') return 'longtext';
+  if (f.kind === 'number' || f.kind === 'boolean' || f.kind === 'enum' || f.kind === 'fk') return f.kind;
+  return 'text';
+}
+
+/** 字段的候选选项：枚举直接给，外键查关联表（和知识图谱详情面板同一套） */
+async function optionsFor(f: FieldMeta): Promise<FormFieldOption[] | undefined> {
+  if (f.kind === 'enum') return f.options?.length ? f.options : undefined;
+  if (f.kind === 'fk' && f.refModel) {
+    const opts: FieldOption[] = await optionsOf(f.refModel);
+    return opts.length ? opts : undefined;
+  }
+  return undefined;
+}
+
+/**
+ * schema 注释能不能直接展示给用户。
+ *
+ * ★ 不能：`gender String @default("male") // male | female` 这行注释的读者是开发者，
+ *   原样放到表单里就是一句「male | female」挂在性别控件下面，用户看不懂。
+ *   只放行含中文的注释（那才是真的给使用者看的说明）。
+ */
+function usableHint(s?: string): string | undefined {
+  if (!s) return undefined;
+  const t = s.trim();
+  if (!/[\u4e00-\u9fa5]/.test(t)) return undefined;
+  return t.length > 40 ? `${t.slice(0, 40)}…` : t;
+}
+
+function placeholderOf(label: string, kind: FormFieldKind): string {
+  if (kind === 'enum' || kind === 'fk') return `请选择${label}`;
+  if (kind === 'date') return `请选择${label}`;
+  if (kind === 'number') return `请输入${label}`;
+  if (kind === 'longtext') return `请输入${label}`;
+  return `请输入${label}`;
+}
+
+/**
+ * 预填默认值。
+ *
+ * ★ 只做两件"几乎不会错"的推断，且都能改：
+ *   - 指向 User 且名字像"申请人/提交人/负责人" → 当前登录用户
+ *   - 名字像"申请日期/提交日期" → 今天
+ *   其余一律不猜。猜错的默认值比空白更糟：用户会直接提交。
+ */
+function defaultOf(
+  f: FieldMeta,
+  userId: string
+): { value: FormFieldSpec['value']; hint: string } | null {
+  if (f.kind === 'fk' && f.refModel === 'User' && /(user|applicant|owner|creator|submitter|handler|operator)/i.test(f.name)) {
+    return { value: userId, hint: '已按当前操作人预填，可修改' };
+  }
+  if (f.kind === 'datetime' && /^(apply|request|submit|report|leave|start)/i.test(f.name)) {
+    return { value: today(), hint: '已按今天预填，可修改' };
+  }
+  return null;
+}
+
+/* ---------------------------- 自动工具 → 表单 ---------------------------- */
+
+interface BuildOptions {
+  /** 只问这些字段（模型点名要问的），其余不显示 */
+  only?: string[];
+  /** 即使参数已经齐了也弹表单（模型主动"请用户核对/补充"时用） */
+  force?: boolean;
+}
+
+/**
+ * 写工具 → 表单。
+ *
+ * 返回 null 有两种情况：不是写工具，或者参数已经齐了（不需要打扰用户）。
+ * 前者是调用方用错了，后者是正常路径 —— 齐了就直接出确认卡。
+ */
+export async function buildWriteForm(
+  name: string,
+  args: Record<string, unknown>,
+  userId: string,
+  opts: BuildOptions = {}
+): Promise<FormSpec | null> {
+  const info = writeToolInfo(name);
+  if (!info) return null;
+
+  const cleanArgs =
+    info.kind === 'model'
+      ? (coercePayload(info.model, args ?? {}) as Record<string, unknown>)
+      : { ...(args ?? {}) };
+
+  if (info.kind === 'model') {
+    return buildModelForm(name, info.model, info.entity?.label ?? info.model, cleanArgs, userId, opts);
+  }
+  return buildHandForm(userId, name, info.tool, cleanArgs, opts);
+}
+
+async function buildModelForm(
+  toolName: string,
+  model: string,
+  entityLabel: string,
+  args: Record<string, unknown>,
+  userId: string,
+  opts: BuildOptions
+): Promise<FormSpec | null> {
+  // 标签/选项允许被 ontology 覆盖，和详情面板保持一致
+  const labels = ONTOLOGY.fieldLabels?.[model] ?? {};
+  const optOverride = ONTOLOGY.fieldOptions?.[model] ?? {};
+
+  const decorated: FieldMeta[] = writableFields(model).map((f) => ({
+    ...f,
+    label: labels[f.name] ?? f.label,
+    options: optOverride[f.name]?.length ? optOverride[f.name] : f.options,
+  }));
+
+  const only = opts.only?.length ? new Set(opts.only) : null;
+  const pool = only ? decorated.filter((f) => only.has(f.name)) : decorated;
+
+  const missing = pool.filter((f) => f.required && isBlank(args[f.name]));
+  if (!missing.length && !opts.force) return null;
+  if (!pool.length) return null;
+
+  const picked = pickFields(pool, missing, args);
+
+  const fields = await Promise.all(
+    picked.map(async (f) => {
+      const options = await optionsFor(f);
+      let value = controlValue(formKind(f), args[f.name], options);
+      let hint: string | undefined = usableHint(f.hint);
+
+      if (isUnset(value) && f.required) {
+        const d = defaultOf(f, userId);
+        if (d) {
+          value = d.value;
+          hint = d.hint;
+        }
+      }
+
+      // 注释常写成 `name String // 名称`，和标签一模一样。
+      // 原样展示就是「名称 / 名称」两行，纯噪音。
+      if (hint === f.label) hint = undefined;
+
+      return {
+        name: f.name,
+        label: f.label,
+        kind: formKind(f),
+        required: f.required,
+        value,
+        options,
+        placeholder: placeholderOf(f.label, formKind(f)),
+        hint,
+        validation: inferValidationType(f.name, f.label, f.hint, model),
+      } satisfies FormFieldSpec;
+    })
+  );
+
+  const title = `补全「${entityLabel}」`;
+  const stillMissing = fields.filter((f) => f.required && isUnset(f.value));
+  const description = stillMissing.length
+    ? `还差 ${stillMissing.map((f) => f.label).join('、')}。填好后会生成确认卡，确认后才写库。`
+    : '信息已基本齐全，请核对后提交。提交后会生成确认卡。';
+
+  return issue(userId, toolName, 'fill', args, title, description, fields);
+}
+
+/**
+ * 选字段：必填缺失 → 已填 → 可选空（补到上限）。
+ * 顺序最终按 schema 原序，保证每次打开表单的位置一致（不会因为模型填了几个字段就跳位）。
+ */
+function pickFields(
+  pool: FieldMeta[],
+  missing: FieldMeta[],
+  args: Record<string, unknown>
+): FieldMeta[] {
+  const chosen = new Set<string>(missing.map((f) => f.name));
+
+  // 已填的也要露出来：用户得能核对模型填的值，也能改掉填错的
+  for (const f of pool) {
+    if (chosen.size >= MAX_FIELDS) break;
+    if (!isBlank(args[f.name])) chosen.add(f.name);
+  }
+
+  /**
+   * 补位时优先补「还没出现过的控件类型」。
+   *
+   * ★ 为什么不按 schema 顺序硬取前 N 个：
+   *   入职日期排在 email 后面，一截断表单里就没有日期控件了 ——
+   *   而"日期用文本框填"正是这套组件要消灭的东西。
+   *   先保证 文本/数字/日期/枚举/外键 各有一个，再按顺序补剩下的。
+   */
+  const kinds = new Set([...chosen].map((name) => formKind(pool.find((f) => f.name === name)!)));
+  const rest = pool.filter((f) => !chosen.has(f.name));
+  for (const f of rest) {
+    if (chosen.size >= MAX_FIELDS) break;
+    const k = formKind(f);
+    if (kinds.has(k)) continue;
+    chosen.add(f.name);
+    kinds.add(k);
+  }
+  for (const f of rest) {
+    if (chosen.size >= MAX_FIELDS) break;
+    chosen.add(f.name);
+  }
+
+  // 最终按 schema 原序展示：同一张表每次打开字段位置都一样
+  return pool.filter((f) => chosen.has(f.name));
+}
+
+/* ---------------------------- 手写工具 → 表单 ---------------------------- */
+
+/** 手写工具的参数只有 JSON Schema，按 type / enum / description 粗略映射控件 */
+function handKind(p: { type?: unknown; description?: unknown }): FormFieldKind {
+  const t = String(p.type ?? '');
+  if (t === 'number' || t === 'integer') return 'number';
+  if (t === 'boolean') return 'boolean';
+  const d = String(p.description ?? '');
+  if (/(日期|时间|date|time)/i.test(d)) return 'date';
+  if (/(备注|说明|理由|原因|description|remark|reason|note)/i.test(d)) return 'longtext';
+  return 'text';
+}
+
+function handLabel(name: string, p: { description?: unknown }): string {
+  const d = String(p.description ?? '').trim();
+  if (!d) return name;
+  return d.split(/[（(，,。；;：:]/)[0] || name;
+}
+
+async function buildHandForm(
+  userId: string,
+  toolName: string,
+  tool: HandTool,
+  args: Record<string, unknown>,
+  opts: BuildOptions
+): Promise<FormSpec | null> {
+  const required = new Set(tool.parameters.required ?? []);
+  const props = tool.parameters.properties ?? {};
+  const only = opts.only?.length ? new Set(opts.only) : null;
+
+  const all: FormFieldSpec[] = [];
+  for (const [name, raw] of Object.entries(props)) {
+    if (only && !only.has(name)) continue;
+    const p = (raw ?? {}) as { type?: unknown; description?: unknown; enum?: unknown[] };
+    const kind = handKind(p);
+    const options = Array.isArray(p.enum) && p.enum.length
+      ? p.enum.map((v) => ({
+          label: String(v),
+          value: typeof v === 'number' ? v : String(v),
+        }))
+      : undefined;
+    const label = handLabel(name, p);
+    all.push({
+      name,
+      label,
+      kind,
+      required: required.has(name),
+      value: controlValue(kind, args[name], options),
+      options,
+      placeholder: placeholderOf(label, kind),
+      validation: inferValidationType(name, label, String(p.description ?? '')),
+    });
+  }
+
+  const missing = all.filter((f) => f.required && isUnset(f.value));
+  if (!missing.length && !opts.force) return null;
+  if (!all.length) return null;
+
+  // 必填缺失 + 已填 + 其余（同样受上限约束）
+  const chosen = new Set(missing.map((f) => f.name));
+  for (const f of all) {
+    if (chosen.size >= MAX_FIELDS) break;
+    if (!isUnset(f.value)) chosen.add(f.name);
+  }
+  for (const f of all) {
+    if (chosen.size >= MAX_FIELDS) break;
+    chosen.add(f.name);
+  }
+  const fields = all.filter((f) => chosen.has(f.name));
+
+  const title = `补全操作信息`;
+  const stillMissing = fields.filter((f) => f.required && isUnset(f.value));
+  const description = stillMissing.length
+    ? `还差 ${stillMissing.map((f) => f.label).join('、')}。填好后会生成确认卡，确认后才执行。`
+    : '请核对后提交，提交后会生成确认卡。';
+
+  return issue(userId, toolName, 'fill', args, title, description, fields);
+}
+
+/* ---------------------------- 模型主动追问 ---------------------------- */
+
+/**
+ * `ask_user` 工具 → 表单。
+ *
+ * 模型只给字段名（数组），不给控件类型 —— 这是刻意的：
+ * 小模型描述不准"这个字段该是日期还是枚举"，让它写只会写出错误控件。
+ * 字段名在 schema 里查得到就用 schema 的定义，查不到就退化成普通文本框。
+ */
+export async function buildAskForm(
+  raw: { title?: unknown; question?: unknown; tool?: unknown; fields?: unknown },
+  userId: string
+): Promise<FormSpec | null> {
+  const wanted = Array.isArray(raw.fields)
+    ? raw.fields
+        .map((v) => {
+          if (typeof v === 'string') return v.trim();
+          if (v && typeof v === 'object') return String((v as { name?: unknown }).name ?? '').trim();
+          return '';
+        })
+        .filter(Boolean)
+        .slice(0, MAX_FIELDS)
+    : [];
+
+  const title = String(raw.title ?? '').trim().slice(0, 40) || '请补充信息';
+  const question = String(raw.question ?? '').trim().slice(0, 200);
+  const toolName = String(raw.tool ?? '').trim();
+
+  // 绑定了写工具：直接复用该工具的字段定义（有下拉、有日期、有必填标记）
+  if (toolName) {
+    const spec = await buildWriteForm(toolName, {}, userId, {
+      only: wanted.length ? wanted : undefined,
+      force: true,
+    });
+    if (spec) {
+      return { ...spec, title, description: question || spec.description };
+    }
+  }
+
+  if (!wanted.length) return null;
+
+  const fields: FormFieldSpec[] = wanted.map((name) => ({
+    name,
+    label: name,
+    kind: 'text',
+    required: true,
+    placeholder: `请输入${name}`,
+    validation: inferValidationType(name, name),
+  }));
+
+  return issue(userId, '', 'ask', {}, title, question || '填写后我会继续处理。', fields);
+}
+
+/* ---------------------------- 签发 ---------------------------- */
+
+function issue(
+  userId: string,
+  tool: string,
+  mode: FormMode,
+  args: Record<string, unknown>,
+  title: string,
+  description: string,
+  fields: FormFieldSpec[]
+): FormSpec {
+  const payload: FormTokenPayload = {
+    k: 'form',
+    u: userId,
+    n: tool,
+    m: mode,
+    a: args,
+    f: fields.map((x) => ({ n: x.name, l: x.label })),
+    t: title,
+    d: description,
+    e: Date.now() + TOKEN_TTL_MS,
+  };
+  return {
+    token: signPayload({ ...payload }),
+    title,
+    description,
+    mode,
+    tool: tool || undefined,
+    fields,
+  };
+}
+
+/**
+ * 把用户提交的值合并进已填参数。
+ *
+ * ★ 只认令牌里的字段白名单。前端多塞的键一律丢弃 ——
+ *   否则表单就成了"绕过确认卡直接改任意字段"的后门。
+ */
+export function mergeFormValues(
+  payload: FormTokenPayload,
+  values: Record<string, unknown>
+): Record<string, unknown> {
+  const allowed = new Set(payload.f.map((x) => x.n));
+  const out: Record<string, unknown> = { ...(payload.a ?? {}) };
+  for (const [k, v] of Object.entries(values ?? {})) {
+    if (!allowed.has(k)) continue;
+    out[k] = typeof v === 'string' ? v.trim() : v;
+  }
+  return out;
+}
+
+/** ask 模式下回灌给模型的文本：字段名用中文标签，模型不用猜哪个键对应什么 */
+export function formValuesText(
+  payload: FormTokenPayload,
+  values: Record<string, unknown>
+): string {
+  const labelOf = new Map(payload.f.map((x) => [x.n, x.l]));
+  const lines = Object.entries(values ?? {})
+    .filter(([k, v]) => payload.f.some((x) => x.n === k) && !isBlank(v))
+    .map(([k, v]) => `${labelOf.get(k) ?? k}：${typeof v === 'boolean' ? (v ? '是' : '否') : String(v)}`);
+  return `【用户填写了表单：${payload.t}】\n${lines.join('\n') || '（未填写）'}`;
+}

package/resources/src/lib/aiFormTypes.ts

@@ -0,0 +1,83 @@
+/**
+ * AI 输入表单的数据契约 —— 前端组件与服务端生成器共用的唯一结构。
+ *
+ * ★ 为什么单独一个文件：
+ *   `aiForm.ts` 要读 prisma schema、查外键选项，是纯服务端代码；
+ *   前端组件只需要这几个 type。混在一起会把 node:fs 打进客户端包，
+ *   构建时会直接报错（这个坑在知识图谱那边踩过一次）。
+ *
+ * ★ 字段类型只保留渲染控件真正需要的几种，不做通用 JSON Schema 复刻：
+ *   text/longtext → Input/TextArea，number → InputNumber，
+ *   boolean → Switch，date → DatePicker，enum/fk → Select。
+ *   少一种类型，前端就少一个可能渲染错的控件。
+ */
+
+export type FormFieldKind = 'text' | 'longtext' | 'number' | 'boolean' | 'date' | 'enum' | 'fk';
+
+export interface FormFieldOption {
+  label: string;
+  value: string | number;
+}
+
+export interface FormFieldSpec {
+  /** 提交时用的键（= prisma 字段名 / 工具参数名） */
+  name: string;
+  label: string;
+  kind: FormFieldKind;
+  required: boolean;
+  /** 已填值 / 预填值。日期统一 YYYY-MM-DD 字符串 */
+  value?: string | number | boolean | null;
+  options?: FormFieldOption[];
+  placeholder?: string;
+  /** 字段下方的浅色说明（"已按当前操作人预填"这类） */
+  hint?: string;
+  /** 服务端按字段名/标签推断出的校验类型（见 lib/validation.ts） */
+  validation?: string;
+  /** 为什么问你：模型填错过、或者必填缺失 */
+  note?: string;
+}
+
+/** 表单提交模式，决定服务端拿到答案后走哪条路 */
+export type FormMode =
+  /** 补齐写工具参数 → 直接生成确认卡，不再过一遍模型 */
+  | 'fill'
+  /** 模型主动追问 → 答案回灌给模型，继续这一轮 */
+  | 'ask';
+
+export interface FormSpec {
+  /** 签名令牌：绑定工具名 + 已填参数 + 用户 + 有效期 */
+  token: string;
+  title: string;
+  description?: string;
+  mode: FormMode;
+  /** fill 模式下绑定的写工具名（仅用于展示与排查） */
+  tool?: string;
+  fields: FormFieldSpec[];
+}
+
+/** 前端卡片状态（服务端不知道，也不需要知道） */
+export type FormCardStatus = 'pending' | 'submitting' | 'done' | 'cancelled' | 'failed';
+
+export interface FormCard {
+  spec: FormSpec;
+  status: FormCardStatus;
+  error?: string;
+}
+
+/** 一眼能看懂的提交摘要（进对话历史，让后续追问有上下文） */
+export function formAnswerText(spec: FormSpec, values: Record<string, unknown>): string {
+  const parts = spec.fields
+    .filter((f) => values[f.name] !== undefined && values[f.name] !== null && values[f.name] !== '')
+    .map((f) => `${f.label} ${displayValue(f, values[f.name])}`);
+  const body = parts.length ? parts.join('，') : '（未填写内容）';
+  return `已填写《${spec.title}》：${body}`;
+}
+
+export function displayValue(field: FormFieldSpec, v: unknown): string {
+  if (field.kind === 'boolean') return v ? '是' : '否';
+  if (field.options?.length) {
+    const hit = field.options.find((o) => String(o.value) === String(v));
+    if (hit) return hit.label;
+  }
+  return String(v ?? '');
+}

package/resources/src/lib/aiToken.ts

@@ -0,0 +1,72 @@
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+
+/**
+ * 一次性令牌 —— AI 面板里两种"用户亲手做过的事"的技术底座。
+ *
+ *   1. 确认令牌（action）：模型提出的写操作，用户点「确认」才执行
+ *   2. 表单令牌（form）：模型要的信息，用户填完表单才继续
+ *
+ * ★ 为什么都要签名，而不是前端直接传参数：
+ *   前端能改的东西都不能信。若把 args 放在请求体里，用户（或页面上的脚本）
+ *   可以把"请 1 天假"改成"请 30 天假"再提交。令牌里含参数 + 用户 id + 过期时间，
+ *   改一个字节签名就对不上。
+ *
+ * ★ 密钥来源：AI_ACTION_SECRET → AUTH_SECRET（NextAuth v5）→ NEXTAUTH_SECRET → 启动时随机。
+ *   绝不用写死的字符串兜底 —— 那等于把签名密钥印在源码里。
+ *   随机密钥的代价是"服务重启后，重启前弹出、尚未确认的卡片会失效"
+ *   （确认时只提示超时/校验失败，重新问一次即可），这个代价可以接受。
+ *
+ * ★ 统一字段名（payload 里的短键是刻意的：令牌会进 URL/日志，越短越好）：
+ *   u = 用户 id，e = 过期时间戳，其余由调用方定义。
+ */
+const SECRET =
+  process.env.AI_ACTION_SECRET ??
+  process.env.AUTH_SECRET ??
+  process.env.NEXTAUTH_SECRET ??
+  randomBytes(32).toString('hex');
+
+function sign(body: string): string {
+  return createHmac('sha256', SECRET).update(body).digest('base64url');
+}
+
+/** 把一个 JSON 载荷签成 `body.signature` */
+export function signPayload(payload: Record<string, unknown>): string {
+  const body = Buffer.from(JSON.stringify(payload), 'utf8').toString('base64url');
+  return `${body}.${sign(body)}`;
+}
+
+export type PayloadCheck<T> = { ok: true; payload: T } | { ok: false; error: string };
+
+/**
+ * 验签 + 校验归属与有效期。
+ *
+ * 校验顺序是刻意的：先签名、再归属、最后过期。
+ * 签名不对时不应该告诉对方"这个令牌属于别人"——那是在泄露信息。
+ */
+export function readPayload<T extends { u?: string; e?: number }>(
+  token: unknown,
+  userId: string
+): PayloadCheck<T> {
+  if (typeof token !== 'string' || !token.includes('.')) return { ok: false, error: '令牌格式不对' };
+  const [body, sig] = token.split('.');
+  if (!body || !sig) return { ok: false, error: '令牌格式不对' };
+
+  const expect = sign(body);
+  const a = Buffer.from(sig);
+  const b = Buffer.from(expect);
+  if (a.length !== b.length || !timingSafeEqual(a, b)) {
+    return { ok: false, error: '令牌校验失败（参数被改动过）' };
+  }
+
+  try {
+    const payload = JSON.parse(Buffer.from(body, 'base64url').toString('utf8')) as T;
+    if (payload.u !== userId) return { ok: false, error: '令牌不属于当前登录用户' };
+    if (!payload.e || payload.e < Date.now()) return { ok: false, error: '已超时，请重新发起' };
+    return { ok: true, payload };
+  } catch {
+    return { ok: false, error: '令牌解析失败' };
+  }
+}
+
+/** 令牌有效期：10 分钟。放久了容易"确认的是十分钟前看到的内容" */
+export const TOKEN_TTL_MS = 10 * 60_000;