node-resource-utils 0.0.0-stage → 1.1.8

package/resources/src/lib/aiTools.ts

@@ -0,0 +1,823 @@
+import { prisma } from '@/lib/prisma';
+import ONTOLOGY from '@/lib/ontology';
+import { readPayload, signPayload, TOKEN_TTL_MS } from '@/lib/aiToken';
+import { coercePayload, coerceValue, fieldsOfModel, hasSoftDelete, type FieldMeta } from '@/lib/graph-schema';
+import { inferValidationType, validateField } from '@/lib/validation';
+import { deptAllowed, deptScope, type ScopeUser } from '@/lib/rbac';
+
+/**
+ * AI 工具层 —— 让助手能真正操作业务数据，而不是只会聊天。
+ *
+ * ★ 核心设计：**工具不写死，从配置和 schema 自动生成。**
+ *   1. 有哪些工具 → 由 `ontology.ts` 的 entities 决定（配了哪些本体，就能操作哪些表）
+ *   2. 每个工具有什么参数 → 由 `prisma/schema.prisma` 反推（字段名/类型/枚举/外键/必填）
+ *   3. 参数怎么落库 → 复用 `graph-schema.ts` 的 coercePayload（和知识图谱面板同一套规则）
+ *
+ *   于是换业务时**一行工具代码都不用改**：改完 ontology 和 schema，工具自动跟着变。
+ *   这和知识图谱是同一个思想（配置驱动），只是把"画出来"换成了"能操作"。
+ *
+ * ★ 安全模型（三层，任何一层都不能省）：
+ *   1. **读工具**（query_*）随便调：只读、软件删过滤、字段白名单
+ *   2. **写工具**（create_*）绝不直接执行：
+ *      模型只能"提出"一个动作，服务端签名成 token 推给前端，
+ *      用户在确认卡上点「确认」才真正写库 —— 前端改不了参数（token 里有 HMAC）
+ *   3. 落库后写 audit 日志，module 记为「AI 助手」，事后可追
+ *
+ *   为什么写工具不直接执行：小模型会误解指令，一句"帮我加一条记录"可能填出
+ *   明天的日期 + 错误的事由。让人看一眼的成本远低于删脏数据的成本。
+ */
+
+/* ============================ 1. 工具清单 ============================ */
+
+/** 永远不暴露给 AI 的系统表：角色/菜单/关联表/审计日志 */
+const BLOCKED_MODELS = new Set(['Role', 'Menu', 'UserRole', 'RoleMenu', 'OperationLog']);
+
+/**
+ * 只读模型：能查，但**不生成 create_**。
+ *
+ * User 往往是业务里的"人员"（有些系统直接拿它当员工表），查询很有用；
+ * 但新建账号必须走系统管理页 —— 要密码、要角色、要部门，
+ * 让模型凭空建一个没有密码、没有角色的用户，只会制造脏数据。
+ */
+const READ_ONLY_MODELS = new Set(['User']);
+
+/** 模型名 → 工具名里的标识（DispatchRecord → dispatch_record） */
+function snake(s: string): string {
+  return s
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1_$2')
+    .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+    .toLowerCase();
+}
+
+interface BusinessEntity {
+  id: string;
+  label: string;
+  model: string;
+  titleField: string;
+}
+
+/**
+ * 参与工具生成的业务对象。
+ *
+ * ★ 唯一来源是 ontology.ts —— 这既是知识图谱的本体，也是 AI 的能力边界。
+ *   没写进 ontology 的表，AI 既画不出来也操作不了，语义一致。
+ */
+function businessEntities(): BusinessEntity[] {
+  const seen = new Set<string>();
+  const out: BusinessEntity[] = [];
+  for (const e of ONTOLOGY.entities) {
+    if (!e?.model || seen.has(e.model) || BLOCKED_MODELS.has(e.model)) continue;
+    seen.add(e.model);
+    out.push({ id: e.id, label: e.label, model: e.model, titleField: e.titleField });
+  }
+  return out;
+}
+
+/** 该模型的日期字段，用来做默认排序 */
+function dateFieldOf(model: string): string | null {
+  const fs = fieldsOfModel(model);
+  if (fs.some((f) => f.name === 'createdAt')) return 'createdAt';
+  const hit = fs.find((f) => f.kind === 'datetime');
+  return hit?.name ?? null;
+}
+
+/** 可写字段（必填的排前面，让模型先看必填项） */
+export function writableFields(model: string): FieldMeta[] {
+  return [...fieldsOfModel(model)].sort((a, b) => Number(b.required) - Number(a.required));
+}
+
+/** 单个字段 → JSON Schema 片段 */
+function propSchema(f: FieldMeta): Record<string, unknown> {
+  const p: Record<string, unknown> = { description: f.label };
+  switch (f.kind) {
+    case 'number':
+      p.type = 'number';
+      break;
+    case 'boolean':
+      p.type = 'boolean';
+      break;
+    case 'datetime':
+      p.type = 'string';
+      p.description = `${f.label}（日期或 ISO 时间，如 2026-10-20）`;
+      break;
+    case 'enum': {
+      const values = (f.options ?? []).map((o) => o.value);
+      p.type = values.some((v) => typeof v === 'number') ? 'number' : 'string';
+      if (values.length) p.enum = values;
+      break;
+    }
+    case 'fk':
+      p.type = 'string';
+      p.description = `${f.label}（填 ${f.refModel ?? '关联表'} 的主键 id，先用对应的 query 工具查出来，不要编造）`;
+      break;
+    default:
+      p.type = 'string';
+  }
+  return p;
+}
+
+export interface AiToolSchema {
+  type: 'function';
+  function: {
+    name: string;
+    description: string;
+    parameters: {
+      type: 'object';
+      properties: Record<string, unknown>;
+      required?: string[];
+    };
+  };
+}
+
+/** 查询工具的筛选参数（固定形状，字段名服务端再校验） */
+function queryParameters(model: string): AiToolSchema['function']['parameters'] {
+  const fs = fieldsOfModel(model);
+  const textFields = fs.filter((f) => f.kind === 'text' || f.kind === 'longtext').map((f) => f.name);
+  const groupCandidates = fs
+    .filter((f) => ['enum', 'text', 'boolean', 'fk'].includes(f.kind))
+    .map((f) => f.name);
+
+  const props: Record<string, unknown> = {
+    filters: {
+      type: 'object',
+      description:
+        '按字段筛选，键必须是本表字段名。等值直接写值；范围用 {gte,lte,gt,lt}；文本包含用 {contains:"xx"}。例：{"status":1} 或 {"startDate":{"gte":"2026-10-01"}}',
+    },
+    take: { type: 'number', description: '返回条数，默认 10，最大 30' },
+  };
+  if (textFields.length) {
+    props.keyword = { type: 'string', description: `关键字模糊搜索（匹配 ${textFields.slice(0, 4).join(' / ')}）` };
+  }
+  if (groupCandidates.length) {
+    props.groupBy = {
+      type: 'string',
+      enum: groupCandidates,
+      description: '按这个字段分组统计条数（问"哪个部门最多""各状态各几条"时用）',
+    };
+  }
+  const df = dateFieldOf(model);
+  if (df) {
+    props.orderBy = { type: 'string', description: `排序字段，默认 ${df} 倒序` };
+  }
+  return { type: 'object', properties: props };
+}
+
+/** 新增工具的参数：直接列字段，必填项进 required */
+function createParameters(model: string): AiToolSchema['function']['parameters'] {
+  const fs = writableFields(model);
+  const props: Record<string, unknown> = {};
+  for (const f of fs) props[f.name] = propSchema(f);
+  const required = fs.filter((f) => f.required).map((f) => f.name);
+  return { type: 'object', properties: props, ...(required.length ? { required } : {}) };
+}
+
+/**
+ * 生成全部工具定义。
+ *
+ * 每个业务对象两个工具：
+ *   query_<x>   只读查询 / 分组统计
+ *   create_<x>  新增一条（需用户确认）
+ *
+ * 故意不生成 update / delete：
+ *   - 改和删的影响面比新建大得多，模型填错一个 id 就改错人
+ *   - 骨架的删除本来就要先算影响清单，让它走原页面更安全
+ *   真需要时在下面 TOOLS 里手工追加一条，并保持 kind:'write'
+ */
+export function buildAiTools(): AiToolSchema[] {
+  const out: AiToolSchema[] = [];
+  for (const e of businessEntities()) {
+    const fs = fieldsOfModel(e.model);
+    if (!fs.length) continue;
+    const label = e.label;
+    const required = fs.filter((f) => f.required).map((f) => f.label);
+
+    out.push({
+      type: 'function',
+      function: {
+        name: `query_${snake(e.model)}`,
+        description: `查询「${label}」数据（只读）。可按字段筛选、关键字搜索、分组统计，返回总条数与明细。问数量、排名、明细、占比都用它。只能查到当前用户有权查看的数据。`,
+        parameters: queryParameters(e.model),
+      },
+    });
+
+    if (READ_ONLY_MODELS.has(e.model)) continue;
+
+    out.push({
+      type: 'function',
+      function: {
+        name: `create_${snake(e.model)}`,
+        description:
+          `新建一条「${label}」记录。` +
+          (required.length ? `必填：${required.join('、')}。` : '') +
+          '调用后不会立刻写库，会先请用户确认。信息不全时先问用户，不要编造。',
+        parameters: createParameters(e.model),
+      },
+    });
+  }
+
+  // 手写工具（审批流转、批量操作这类多步业务）追加在后面
+  for (const t of EXTRA_TOOLS) {
+    out.push({
+      type: 'function',
+      function: { name: t.name, description: t.description, parameters: t.parameters },
+    });
+  }
+
+  // 询问用户的统一出口：模型自己决定"要问什么"，前端渲染成结构化表单。
+  // 这是"文字追问"的替代品 —— 文字追问会丢字段、格式乱、模型还要再解析一遍。
+  out.push({
+    type: 'function',
+    function: {
+      name: FORM_TOOL_NAME,
+      description:
+        '需要用户补充信息时调用它，界面会弹出一张结构化表单，用户填完直接提交。' +
+        '只要还缺必填信息，就用这个工具，**不要用纯文字一条条追问**。' +
+        '如果是在为某个新建操作用收集信息，把 tool 填成对应的 create_<表> 工具名，' +
+        '系统会用该表的字段定义生成表单（含下拉选项、日期选择），用户提交后直接生成确认卡。',
+      parameters: {
+        type: 'object',
+        properties: {
+          title: { type: 'string', description: '表单标题，例如「补全请假申请信息」' },
+          question: { type: 'string', description: '一句话说明为什么要这些信息（可选）' },
+          tool: {
+            type: 'string',
+            description:
+              '要补全的写工具名，例如 create_leave_request。字段来自该工具时一定要填，填了才会用正确的控件和选项。',
+          },
+          fields: {
+            type: 'array',
+            items: { type: 'string' },
+            description:
+              '要用户填的字段名（用 schema 里的字段名，如 startDate、type）。不要写中文标签。',
+          },
+        },
+        required: ['title', 'fields'],
+      },
+    },
+  });
+
+  return out;
+}
+
+/** 询问用户工具的名字 —— 它不执行、不写库，只负责弹表单 */
+export const FORM_TOOL_NAME = 'ask_user';
+
+export function isFormTool(name: string): boolean {
+  return name === FORM_TOOL_NAME;
+}
+
+/* ============================ 1.5 手写工具扩展点 ============================ */
+
+/**
+ * 自动生成的工具只覆盖两件事：**单表通用查询** 和 **单表新增**。
+ *
+ * 审批流转、批量操作、跨表结算这类多步业务，靠 schema 硬凑是凑不出来的，
+ * 在这里追加一条即可。规则：
+ *   - `kind:'write'` 的工具自动走确认卡流程（/api/ai/act），不需要自己写确认逻辑
+ *   - `kind:'read'` 的工具直接执行
+ *   - `run` 里自己校验业务规则，返回 ToolResult（ok / summary / content）
+ *   - 写操作的 `run` 只会在用户点「确认」之后被调用，参数来自签名令牌
+ *
+ * 例子（取消注释并改写成你的业务）：
+ *
+ *   {
+ *     name: 'approve_leave',
+ *     description: '审批一条申请单（同意或驳回）',
+ *     parameters: {
+ *       type: 'object',
+ *       properties: {
+ *         id: { type: 'string', description: '申请单 id' },
+ *         agree: { type: 'boolean', description: 'true 同意，false 驳回' },
+ *       },
+ *       required: ['id', 'agree'],
+ *     },
+ *     kind: 'write',
+ *     run: async (args, ctx) => {
+ *       // 这里用 prisma 改状态 + 写流转记录，ctx.userId 是当前操作人
+ *       return { ok: true, summary: '已审批', content: '审批完成' };
+ *     },
+ *   },
+ */
+export interface HandTool {
+  name: string;
+  description: string;
+  parameters: AiToolSchema['function']['parameters'];
+  kind: 'read' | 'write';
+  run: (args: Record<string, unknown>, ctx: { userId: string }) => Promise<ToolResult>;
+}
+
+export const EXTRA_TOOLS: HandTool[] = [];
+
+function extraOf(name: string): HandTool | undefined {
+  return EXTRA_TOOLS.find((t) => t.name === name);
+}
+
+/** 工具名 → 模型 + 动作 */
+function parseTool(name: string): { action: 'query' | 'create'; model: string; entity?: BusinessEntity } | null {
+  const hit = /^(query|create)_(.+)$/.exec(name);
+  if (!hit) return null;
+  const action = hit[1] as 'query' | 'create';
+  const slug = hit[2];
+  const entity = businessEntities().find((e) => snake(e.model) === slug);
+  if (!entity) return null;
+  return { action, model: entity.model, entity };
+}
+
+export function isWriteTool(name: string): boolean {
+  const extra = extraOf(name);
+  if (extra) return extra.kind === 'write';
+  return parseTool(name)?.action === 'create';
+}
+
+/** 写工具的元信息：自动生成的（按 schema）还是手写的（按 JSON Schema） */
+export type WriteToolInfo =
+  | { kind: 'model'; model: string; entity?: BusinessEntity }
+  | { kind: 'hand'; tool: HandTool };
+
+export function writeToolInfo(name: string): WriteToolInfo | null {
+  const extra = extraOf(name);
+  if (extra) return extra.kind === 'write' ? { kind: 'hand', tool: extra } : null;
+  const p = parseTool(name);
+  if (!p || p.action !== 'create') return null;
+  return { kind: 'model', model: p.model, entity: p.entity };
+}
+
+/** 空值判定：表单提交时用户清空一个预填字段，也算"没填" */
+export function isBlank(v: unknown): boolean {
+  if (v === undefined || v === null) return true;
+  if (typeof v === 'string') return v.trim() === '';
+  if (Array.isArray(v)) return v.length === 0;
+  return false;
+}
+
+/**
+ * 手写工具的必填校验。
+ *
+ * 自动工具能从 schema 反推必填，手写工具只有 JSON Schema 的 required 数组可用。
+ * 取 description 的第一个分句当字段中文名，拼出来的话才像人话：
+ * 「还缺这些必填信息：开始日期、结束日期」而不是「startDate、endDate」。
+ */
+export function missingHandParams(tool: HandTool, args: Record<string, unknown>): string[] {
+  const required = tool.parameters.required ?? [];
+  const props = tool.parameters.properties ?? {};
+  return required
+    .filter((k) => isBlank(args[k]))
+    .map((k) => {
+      const p = props[k] as { description?: unknown } | undefined;
+      const d = typeof p?.description === 'string' ? p.description.trim() : '';
+      return d ? d.split(/[（(，,。；;：:]/)[0] || k : k;
+    });
+}
+
+/* ============================ 2. 数据访问 ============================ */
+
+interface Delegate {
+  findMany?: (a?: unknown) => Promise<Record<string, unknown>[]>;
+  count?: (a?: unknown) => Promise<number>;
+  create?: (a?: unknown) => Promise<Record<string, unknown>>;
+  groupBy?: (a?: unknown) => Promise<Record<string, unknown>[]>;
+}
+
+function delegateOf(model: string): Delegate | null {
+  const d = (prisma as unknown as Record<string, unknown>)[model] as Delegate | undefined;
+  return d && typeof d.findMany === 'function' ? d : null;
+}
+
+/** 软删表默认只看未删除的 */
+function aliveWhere(model: string): Record<string, unknown> {
+  return hasSoftDelete(model) ? { deletedAt: null } : {};
+}
+
+/**
+ * 把模型给的 filters 变成 Prisma where。
+ * ★ 只认 schema 里真实存在的字段 —— 模型编一个不存在的字段时静默忽略，
+ *   而不是抛错（抛错会让它反复重试同一个错误参数）。
+ */
+function buildWhere(model: string, filters: unknown): Record<string, unknown> {
+  const byName = new Map(fieldsOfModel(model).map((f) => [f.name, f]));
+  const where: Record<string, unknown> = {};
+
+  if (!filters || typeof filters !== 'object' || Array.isArray(filters)) return where;
+
+  for (const [k, v] of Object.entries(filters as Record<string, unknown>)) {
+    const f = byName.get(k);
+    if (!f || v === undefined || v === null || v === '') continue;
+
+    // 范围 / 包含
+    if (typeof v === 'object' && !Array.isArray(v)) {
+      const src = v as Record<string, unknown>;
+      const range: Record<string, unknown> = {};
+      for (const op of ['gte', 'lte', 'gt', 'lt'] as const) {
+        if (src[op] === undefined) continue;
+        const cv = coerceValue(f, src[op]);
+        if (cv !== undefined) range[op] = cv;
+      }
+      if (typeof src.contains === 'string' && f.kind !== 'number') {
+        range.contains = src.contains;
+      }
+      if (Object.keys(range).length) where[k] = range;
+      continue;
+    }
+
+    const cv = coerceValue(f, v);
+    if (cv !== undefined) where[k] = cv;
+  }
+  return where;
+}
+
+/** 一行压成紧凑 JSON（长文本截断，避免把上下文撑爆） */
+function packRow(row: Record<string, unknown>, titleField: string): string {
+  const keep: Record<string, unknown> = {};
+  const keys = Object.keys(row).filter((k) => k !== 'deletedAt');
+  // 标题字段 + id 必须带上，其余按 schema 顺序
+  const ordered = [titleField, 'id', ...keys.filter((k) => k !== titleField && k !== 'id')];
+  for (const k of ordered) {
+    if (!(k in row)) continue;
+    const v = row[k];
+    if (v === undefined || v === null) continue;
+    if (v instanceof Date) keep[k] = v.toISOString().slice(0, 16).replace('T', ' ');
+    else if (typeof v === 'string') keep[k] = v.length > 40 ? `${v.slice(0, 40)}…` : v;
+    else if (typeof v === 'number' || typeof v === 'boolean') keep[k] = v;
+  }
+  return JSON.stringify(keep);
+}
+
+export interface ToolResult {
+  ok: boolean;
+  /** 给用户看的一句话（也会显示在工具轨迹里） */
+  summary: string;
+  /** 回灌给模型的文本 */
+  content: string;
+}
+
+interface QueryArgs {
+  filters?: unknown;
+  keyword?: unknown;
+  groupBy?: unknown;
+  orderBy?: unknown;
+  take?: unknown;
+}
+
+/** 模型上有没有 deptId —— 没有的表（日志、字典、关联表）套不了部门范围 */
+function hasDeptField(model: string): boolean {
+  return fieldsOfModel(model).some((f) => f.name === 'deptId');
+}
+
+/**
+ * 读工具的 where 也要过数据范围。
+ *
+ * ★ 为什么必须：助手是「问一句就出全表」的最短路径。
+ *   列表页过滤了、导出发不了，用户转头问 AI "所有员工的姓名和电话" 就全出来了 ——
+ *   等于给行级权限开了个后门。
+ */
+function scopeWhereOf(model: string, user?: ScopeUser): Record<string, unknown> {
+  if (!user || !hasDeptField(model)) return {};
+  return deptScope(user);
+}
+
+/** 只读查询 */
+async function runQuery(
+  entity: BusinessEntity,
+  args: QueryArgs,
+  user?: ScopeUser
+): Promise<ToolResult> {
+  const d = delegateOf(entity.model);
+  if (!d?.findMany) return { ok: false, summary: `「${entity.label}」暂不支持查询`, content: '该表没有查询能力' };
+
+  const fs = fieldsOfModel(entity.model);
+  const take = Math.min(30, Math.max(1, Number(args.take) || 10));
+  const where = {
+    ...aliveWhere(entity.model),
+    ...buildWhere(entity.model, args.filters),
+    ...scopeWhereOf(entity.model, user),
+  };
+
+  const keyword = String(args.keyword ?? '').trim();
+  if (keyword) {
+    const textFields = fs
+      .filter((f) => f.kind === 'text' || f.kind === 'longtext')
+      .slice(0, 4)
+      .map((f) => f.name);
+    if (textFields.length) {
+      where.OR = textFields.map((name) => ({ [name]: { contains: keyword } }));
+    }
+  }
+
+  const groupBy = String(args.groupBy ?? '').trim();
+  const hasField = (n: string) => fs.some((f) => f.name === n);
+
+  try {
+    // 分组统计：问"哪个部门最多""各状态几条"走这条
+    if (groupBy && hasField(groupBy)) {
+      // ★ groupBy 的 orderBy 只能按 by 里出现过的字段排，
+      //   而 take 必须配 orderBy —— 所以这里按分组字段排，再在内存里按条数排。
+      //   直接写 take:30 而不给 orderBy，Prisma 会报
+      //   "Every field used for orderBy must be included in the by-arguments"。
+      const rows = d.groupBy
+        ? await d
+            .groupBy({
+              by: [groupBy],
+              where,
+              _count: { _all: true },
+              orderBy: { [groupBy]: 'asc' },
+            })
+            .catch((e: unknown) => {
+              throw new Error(`分组统计失败：${(e as Error).message}`);
+            })
+        : null;
+
+      if (rows) {
+        const counted = rows
+          .map((r) => ({
+            key: String(r[groupBy] ?? '（空）'),
+            count: (r._count as { _all?: number } | undefined)?._all ?? 0,
+          }))
+          .sort((a, b) => b.count - a.count)
+          .slice(0, 30);
+
+        // ★ 分组字段是外键时，必须把 id 换成名称。
+        //   否则"哪个部门最多"会答出一串 cuid —— 模型看不懂，用户更看不懂。
+        const gf = fs.find((x) => x.name === groupBy);
+        let labelOf = (v: string) => v;
+        if (gf?.kind === 'fk' && gf.refModel) {
+          const refEnt = businessEntities().find((e) => e.model === gf.refModel);
+          const titleField = refEnt?.titleField ?? 'name';
+          const refDelegate = delegateOf(gf.refModel);
+          const refs = refDelegate?.findMany
+            ? await refDelegate
+                .findMany({ select: { id: true, [titleField]: true }, take: 500 })
+                .catch(() => [])
+            : [];
+          const map = new Map(refs.map((r) => [String(r.id), String(r[titleField] ?? r.id)]));
+          labelOf = (v) => map.get(v) ?? v;
+        }
+
+        const total = typeof d.count === 'function' ? await d.count({ where }).catch(() => undefined) : undefined;
+        return {
+          ok: true,
+          summary: `按「${gf?.label ?? groupBy}」分组：${entity.label}共 ${counted.length} 组`,
+          content:
+            `「${entity.label}」共 ${total ?? '若干'} 条，按「${gf?.label ?? groupBy}」分组（条数从多到少）：\n` +
+            counted.map((c) => `${labelOf(c.key)}：${c.count} 条`).join('\n'),
+        };
+      }
+    }
+
+    const orderField = hasField(String(args.orderBy ?? ''))
+      ? String(args.orderBy)
+      : dateFieldOf(entity.model) ?? undefined;
+
+    const rows = await d.findMany({
+      where,
+      take,
+      ...(orderField ? { orderBy: { [orderField]: 'desc' } } : {}),
+    });
+
+    const total = typeof d.count === 'function' ? await d.count({ where }).catch(() => undefined) : undefined;
+
+    if (!rows.length) {
+      return {
+        ok: true,
+        summary: `「${entity.label}」没有匹配的数据`,
+        content: `按条件查询「${entity.label}」，0 条。`,
+      };
+    }
+
+    return {
+      ok: true,
+      summary: `查询「${entity.label}」：${total ?? rows.length} 条，返回 ${rows.length} 条`,
+      content:
+        `「${entity.label}」共 ${total ?? rows.length} 条，下面是 ${rows.length} 条：\n` +
+        rows.map((r) => packRow(r, entity.titleField)).join('\n'),
+    };
+  } catch (e) {
+    return {
+      ok: false,
+      summary: `查询「${entity.label}」失败`,
+      content: `查询出错：${(e as Error).message}`,
+    };
+  }
+}
+
+/** 写工具的参数预检：只校验，不写库 */
+export function validateWrite(name: string, args: Record<string, unknown>): {
+  ok: boolean;
+  missing?: string[];
+  message?: string;
+} {
+  // 手写工具的必填项来自它自己的 JSON Schema；以前这里直接放行，
+  // 结果"缺参数的审批动作"会被原样摆到确认卡上，用户点确认才报错。
+  const extra = extraOf(name);
+  if (extra) {
+    if (extra.kind !== 'write') return { ok: false, message: '不是可执行的新增动作' };
+    const missing = missingHandParams(extra, args);
+    if (missing.length) {
+      return { ok: false, missing, message: `还缺这些必填信息：${missing.join('、')}` };
+    }
+    return { ok: true };
+  }
+
+  const p = parseTool(name);
+  if (!p || p.action !== 'create') return { ok: false, message: '不是可执行的新增动作' };
+
+  const data = coercePayload(p.model, args);
+  const missing = fieldsOfModel(p.model)
+    .filter((f) => f.required && (data[f.name] === undefined || data[f.name] === ''))
+    .map((f) => f.label);
+
+  if (missing.length) {
+    return { ok: false, missing, message: `还缺这些必填信息：${missing.join('、')}` };
+  }
+
+  // 格式校验：和用户手填表单共用同一套底座。
+  // 模型/用户绕过前端直接发参数时，这里仍能拦住「手机号 123」「身份证少一位」这类脏数据。
+  for (const f of fieldsOfModel(p.model)) {
+    // 枚举/外键/布尔是选项或 id，不是用户手输的文本，不能套手机号/邮箱规则
+    if (f.kind === 'enum' || f.kind === 'fk' || f.kind === 'boolean') continue;
+    const value = data[f.name];
+    if (typeof value !== 'string' || !value.trim()) continue;
+    const type = inferValidationType(f.name, f.label, f.hint);
+    if (!type) continue;
+    const result = validateField(type, value, { label: f.label });
+    if (!result.ok) {
+      return { ok: false, message: result.message };
+    }
+  }
+  return { ok: true };
+}
+
+/** 真正写库（只能由 /api/ai/act 在用户确认后调用） */
+export async function runWrite(
+  name: string,
+  args: Record<string, unknown>,
+  ctx: { userId: string; user?: ScopeUser } = { userId: '' }
+): Promise<ToolResult & { row?: Record<string, unknown> }> {
+  const extra = extraOf(name);
+  if (extra) {
+    if (extra.kind !== 'write') return { ok: false, summary: '不是写操作', content: '该工具是只读的' };
+    try {
+      return await extra.run(args, ctx);
+    } catch (e) {
+      return { ok: false, summary: `执行失败：${(e as Error).message}`, content: (e as Error).message };
+    }
+  }
+
+  const p = parseTool(name);
+  if (!p || p.action !== 'create') return { ok: false, summary: '未知动作', content: '不支持的操作' };
+
+  const check = validateWrite(name, args);
+  if (!check.ok) {
+    return { ok: false, summary: check.message ?? '参数不完整', content: check.message ?? '' };
+  }
+
+  // ★ 数据范围：AI 也不能把记录写到别人部门去。
+  //   读能过滤只是"看不到"，写不校验就是"换个入口照样改"。
+  if (ctx.user && hasDeptField(p.model)) {
+    const targetDept = args.deptId === undefined || args.deptId === null ? undefined : String(args.deptId);
+    if (!deptAllowed(ctx.user, targetDept)) {
+      return {
+        ok: false,
+        summary: '超出数据范围',
+        content: '只能在自己有权管辖的部门范围内创建记录',
+      };
+    }
+  }
+
+  const d = delegateOf(p.model);
+  if (!d?.create) return { ok: false, summary: '该表不支持新增', content: '该表不支持新增' };
+
+  try {
+    const row = await d.create({ data: coercePayload(p.model, args) });
+    const title = p.entity ? String(row[p.entity.titleField] ?? row.id) : String(row.id);
+    return {
+      ok: true,
+      summary: `已新建「${p.entity?.label ?? p.model}」：${title}`,
+      content: `创建成功，记录 id = ${String(row.id)}`,
+      row,
+    };
+  } catch (e) {
+    return {
+      ok: false,
+      summary: `新建失败：${(e as Error).message}`,
+      content: `新建失败：${(e as Error).message}`,
+    };
+  }
+}
+
+/** 只读工具的统一入口（chat 路由用） */
+export async function runReadTool(
+  name: string,
+  args: Record<string, unknown>,
+  ctx: { userId: string; user?: ScopeUser } = { userId: '' }
+): Promise<ToolResult> {
+  const extra = extraOf(name);
+  if (extra) {
+    if (extra.kind !== 'read') {
+      return { ok: false, summary: `${name} 需要用户确认`, content: '写操作必须走确认流程' };
+    }
+    try {
+      return await extra.run(args, ctx);
+    } catch (e) {
+      return { ok: false, summary: `${name} 执行失败`, content: (e as Error).message };
+    }
+  }
+
+  const p = parseTool(name);
+  if (!p || !p.entity) {
+    return { ok: false, summary: `未知工具：${name}`, content: `没有名为 ${name} 的工具` };
+  }
+  if (p.action !== 'query') {
+    return { ok: false, summary: `${name} 不是只读工具`, content: '该工具需要用户确认后才能执行' };
+  }
+  return runQuery(p.entity, args as QueryArgs, ctx.user);
+}
+
+/**
+ * 动作摘要：给前端确认卡显示（人话）。
+ *
+ * ★ 异步是因为外键要翻成名称：确认卡上写「所属部门：cmvei0lpd0003…」
+ *   用户根本没法核对，必须显示「技术部」。这是"确认卡真的能被看懂"的前提。
+ */
+export async function describeAction(
+  name: string,
+  args: Record<string, unknown>
+): Promise<{ title: string; fields: { label: string; value: string }[] }> {
+  const extra = extraOf(name);
+  if (extra) {
+    // 手写工具没有字段元数据，直接按参数键显示（比不显示强，用户能核对）
+    return {
+      title: extra.description.split(/[。；;\n]/)[0] || name,
+      fields: Object.entries(args)
+        .filter(([, v]) => v !== undefined && v !== null && v !== '')
+        .map(([k, v]) => ({
+          label: k,
+          value: typeof v === 'object' ? JSON.stringify(v) : String(v),
+        })),
+    };
+  }
+
+  const p = parseTool(name);
+  if (!p) return { title: name, fields: [] };
+
+  const label = p.entity?.label ?? p.model;
+  const byName = new Map(fieldsOfModel(p.model).map((f) => [f.name, f]));
+  const fields: { label: string; value: string }[] = [];
+
+  for (const [k, v] of Object.entries(args)) {
+    if (v === undefined || v === null || v === '') continue;
+    const f = byName.get(k);
+    if (!f) continue;
+
+    let text = typeof v === 'object' ? JSON.stringify(v) : String(v);
+
+    if (f.kind === 'datetime') {
+      const d = new Date(text);
+      if (!Number.isNaN(d.getTime())) text = d.toISOString().slice(0, 10);
+    } else if (f.kind === 'fk' && f.refModel) {
+      // 外键翻名称，查不到就退回原值（宁可显示 id，也不要显示空白）
+      const refEnt = businessEntities().find((e) => e.model === f.refModel);
+      const titleField = refEnt?.titleField ?? 'name';
+      const rd = delegateOf(f.refModel);
+      const rows = rd?.findMany
+        ? await rd
+            .findMany({ where: { id: text }, take: 1, select: { [titleField]: true } })
+            .catch(() => [])
+        : [];
+      const hit = rows?.[0]?.[titleField];
+      if (hit !== undefined && hit !== null) text = `${String(hit)}（${text}）`;
+    }
+
+    fields.push({ label: f.label, value: text });
+  }
+  return { title: `新建「${label}」`, fields };
+}
+
+/* ============================ 3. 动作令牌 ============================ */
+
+/**
+ * 写动作不是让前端传参数，而是传一个签名令牌。
+ *
+ * 原因：前端能改的东西都不能信。若把 args 放在请求体里，
+ * 用户（或页面上的脚本）可以把"数量 1"改成"数量 30"再提交。
+ * 令牌里含 args + 用户 id + 过期时间，改一个字节签名就对不上。
+ *
+ * ★ 密钥与验签逻辑在 `lib/aiToken.ts` —— 表单令牌用的是同一套，
+ *   这样"用户填的表单"和"用户点的确认"是同一种可信度，不必维护两份密钥。
+ */
+export function signAction(userId: string, name: string, args: Record<string, unknown>): string {
+  // k 是令牌类型。表单令牌也带 n/a，不加这个标记的话，
+  // 一张"只填了一半的表单"可以直接拿去 /api/ai/act 冒充确认令牌。
+  return signPayload({ k: 'act', u: userId, n: name, a: args, e: Date.now() + TOKEN_TTL_MS });
+}
+
+export type ActionCheck =
+  | { ok: true; name: string; args: Record<string, unknown> }
+  | { ok: false; error: string };
+
+export function verifyAction(token: string, userId: string): ActionCheck {
+  const r = readPayload<{ k?: string; u?: string; e?: number; n?: string; a?: Record<string, unknown> }>(token, userId);
+  if (!r.ok) return { ok: false, error: r.error };
+  if (r.payload.k !== 'act') return { ok: false, error: '令牌类型不对，请重新发起' };
+  if (!r.payload.n) return { ok: false, error: '令牌缺少动作名' };
+  return { ok: true, name: r.payload.n, args: r.payload.a ?? {} };
+}