node-resource-utils 0.0.0-stage → 1.1.8

package/resources/src/lib/ontology.ts

@@ -0,0 +1,277 @@
+/**
+ * 本体论（Ontology）配置 —— 知识图谱的"通用引擎"。
+ *
+ * ★ 这是整套骨架里第二个差异化亮点（第一个是 AI 能力）。
+ *   评委打开看到一个能点的知识图谱，基本就记住你了。
+ *
+ * 设计思路：
+ *   图谱画什么，由这个文件里的声明式配置决定，跟代码完全解耦。
+ *   所以它**对任何业务系统都通用** —— 接自己的业务时只改这个文件。
+ *
+ * 三类本体：
+ *   - entities  本体（节点类型）：车辆、司机、部门、用车申请……
+ *   - relations  关系（边类型）：指派、所属、提交、审批……
+ *   - views     视图：把哪些本体和关系组成一张图
+ *
+ * ★ views[0] 就是 /graph 默认打开的视图。页面会自动读取 views 并渲染视图下拉，
+ *   **不需要改 graph/page.tsx** —— 换业务时只改这个文件就够了。
+ *   views 里引用的 entities / relations / root 必须都是已声明的 id，
+ *   `npm run check:config` 会在 1 秒内把这些引用错误报出来。
+ *
+ * 换系统的例子（请销假）：
+ *   entities:  Person(人) / LeaveRequest(请假申请) / LeavePlan(休假计划) / LeaveChange(变更申请)
+ *   relations: 提交(LeaveRequest→Person) / 依据(LeaveRequest→LeavePlan) / 变更(LeaveChange→LeaveRequest)
+ */
+
+export interface EntityDef {
+  /** 本体 id，全图唯一 */
+  id: string;
+  /** 显示名，比如"车辆" */
+  label: string;
+  /** Prisma 模型名，节点数据从这里查 */
+  model: string;
+  /** 节点上显示哪个字段（一般是名称/编号） */
+  titleField: string;
+  /** 节点上附带显示的字段（最多 2 个，超出会挤） */
+  subtitleFields?: string[];
+  /**
+   * 节点填充色。**必须用浅色**（pastel），文字才看得清。
+   * 深色填充 + 深色文字是踩过的坑：节点上的字完全读不出来。
+   */
+  color: string;
+  /** 节点边框色（同色系深一档，视觉更精致） */
+  borderColor?: string;
+  /**
+   * 分层序号：图谱按这个值从左到右排列。
+   * 小的在左（如部门），大的在右（如申请/日志）。不填则按数组顺序。
+   */
+  layer?: number;
+  /** 图标名（antd icon，可选） */
+  icon?: string;
+  /** 点击节点后跳转到哪个页面，用 :id 占位 */
+  link?: string;
+}
+
+export interface RelationDef {
+  id: string;
+  /** 关系显示名，比如"指派" */
+  label: string;
+  /** 起点本体 id */
+  from: string;
+  /** 终点本体 id */
+  to: string;
+  /**
+   * 关系怎么取数。三种写法：
+   *   { field: 'driverId' }                       外键字段：起点.id -> 终点.id
+   *   { field: 'driverId', reverse: true }        反向：终点.id -> 起点.id
+   *   { model: 'DispatchRecord', fromField, toField }  中间表（多对多）
+   */
+  via:
+    | { field: string; reverse?: boolean }
+    | { model: string; fromField: string; toField: string };
+}
+
+export interface GraphView {
+  id: string;
+  label: string;
+  /** 这个视图包含哪些本体 */
+  entities: string[];
+  /** 这个视图包含哪些关系 */
+  relations: string[];
+  /** 默认从哪个本体开始展开 */
+  root: string;
+}
+
+/**
+ * 节点详情面板的可选配置（不写也能用）。
+ *
+ * 面板的字段是**从 prisma/schema.prisma 反推**的（字段名/类型/注释 → 控件），
+ * 所以换业务时通常什么都不用配。只有两种情况需要在这里补：
+ *   - schema 字段没写注释、又想要好看的中文标签 → fieldLabels
+ *   - 字段是 String/Int 存枚举（SQLite 没有 enum）→ fieldOptions
+ *
+ * ★ 注意：fieldLabels / fieldOptions 放在 ONTOLOGY 顶层，**不要塞进 entity 对象里**——
+ *   scripts/check-config.mjs 用 `\{[^{}]*\}` 切 entity，嵌套对象会让它解析错位。
+ */
+export interface FieldOption {
+  label: string;
+  value: string | number;
+}
+
+export interface OntologyConfig {
+  entities: EntityDef[];
+  relations: RelationDef[];
+  views: GraphView[];
+  /** { 本体id 或 模型名: { 字段名: 中文标签 } } */
+  fieldLabels?: Record<string, Record<string, string>>;
+  /** { 本体id 或 模型名: { 字段名: 选项[] } } */
+  fieldOptions?: Record<string, Record<string, FieldOption[]>>;
+}
+
+/* ==================== 通用能力：业务表 ↔ 知识图谱 ==================== */
+
+/**
+ * ★ 任意业务列表页都能一键跳进图谱，**图谱页与引擎都不用改**。
+ *
+ *   1) 列表页放一个按钮（列定义里加一列即可）：
+ *        import { graphHref } from '@/lib/graph-link';
+ *        <Button href={graphHref('Employee', row.id)}>关联</Button>
+ *      graphHref 生成 `/graph?src=Employee:<id>`，是纯函数，客户端可直接引。
+ *
+ *   2) 图谱页读 src → 调 `/api/graph/focus` 解析（src/lib/graph-focus.ts）：
+ *        模型名 → 本体（entities[].model）
+ *              → 沿 relations **只往 layer 更小的方向**走，最多 2 跳，不回头
+ *        走到 1 个节点 → single：直接定位到该节点并打开详情面板
+ *        走到多个节点 → multi ：高亮这几个节点之间的连线，其余压暗
+ *
+ *   3) 反向也能回来：entity.link 里的 `:id` 换成记录主键就是 backLink。
+ *
+ *   所以接自己的业务时只做三件事：
+ *     ① prisma 建模型   ② 这里声明 entity + relation（记得给 layer）
+ *     ③ 列表页加一个 graphHref 按钮
+ *   判定 single / multi 完全由本体推导，页面里不要写死"关联谁"。
+ */
+
+/* ============================ 组织与账号（骨架自带模型） ============================ */
+
+export const ONTOLOGY: OntologyConfig = {
+  // 默认指向骨架里真实存在的模型，开箱就能看到图。
+  // 接自己的业务时换成你的本体即可（注释里有两套完整示例）。
+  //
+  // ★ 配色原则：**浅色底 + 深色字**。深色底会让节点文字完全读不出来（踩过）。
+  entities: [
+    {
+      id: 'department',
+      label: '部门',
+      model: 'Department',
+      titleField: 'name',
+      subtitleFields: [],
+      color: '#F2F0E4',
+      borderColor: '#D2CBB2',
+      layer: 0,
+      // link 决定「全局搜索搜到这条数据后点去哪里」：
+      //   ?id=:id → 页面自己按 id 打开记录（详情弹窗）
+      //   ?kw=:kw → 列表页按名称过滤（DataTable 已内置支持）
+      // 不写 link 的本体不参与数据搜索（搜到了也没地方跳）。
+      link: '/system/depts',
+    },
+    {
+      id: 'employee',
+      label: '员工',
+      model: 'Employee',
+      titleField: 'name',
+      subtitleFields: ['code', 'position'],
+      color: '#E9EFDF',
+      borderColor: '#B6C6A1',
+      layer: 1,
+      link: '/demo/employees?id=:id',
+    },
+    {
+      id: 'role',
+      label: '角色',
+      model: 'Role',
+      titleField: 'name',
+      subtitleFields: [],
+      color: '#F4EEDF',
+      borderColor: '#D8C8A4',
+      layer: 2,
+      link: '/system/roles?kw=:kw',
+    },
+    {
+      // 账号本身也是"业务记录"：一条账号同时挂着部门 + 若干角色，
+      // 正好是多实体关联（multi）的通用演示场景。
+      id: 'user',
+      label: '账号',
+      model: 'User',
+      titleField: 'username',
+      subtitleFields: ['name'],
+      color: '#E7EBDB',
+      borderColor: '#BFC9AC',
+      layer: 3,
+      link: '/system/users?kw=:kw',
+    },
+    {
+      id: 'log',
+      label: '操作日志',
+      model: 'OperationLog',
+      titleField: 'module',
+      subtitleFields: ['action'],
+      color: '#EFEDE6',
+      borderColor: '#CFC9BA',
+      layer: 3,
+      link: '/system/logs?kw=:kw',
+    },
+  ] as EntityDef[],
+
+  relations: [
+    { id: 'emp_dept', label: '所属部门', from: 'employee', to: 'department', via: { field: 'deptId' } },
+    // 部门自引用：parentId → 上级部门。
+    // 没有这条，组织树的根节点（比如"总公司"）在图上是**孤立的一个方块**：
+    // 人只铺在叶子部门，根部门没人指向它，看起来像加载失败。
+    { id: 'dept_parent', label: '上级部门', from: 'department', to: 'department', via: { field: 'parentId' } },
+    // OperationLog.userId 指向的是账号（User），不是员工（Employee）——别接错模型
+    { id: 'log_user', label: '操作人', from: 'log', to: 'user', via: { field: 'userId' } },
+    { id: 'user_dept', label: '所属部门', from: 'user', to: 'department', via: { field: 'deptId' } },
+    // 中间表写法：UserRole 是桥接表，fromField/toField 指向它自己的两个外键
+    {
+      id: 'user_role',
+      label: '拥有角色',
+      from: 'user',
+      to: 'role',
+      via: { model: 'UserRole', fromField: 'userId', toField: 'roleId' },
+    },
+  ] as RelationDef[],
+
+  views: [
+    {
+      // 默认视图放"部门树 + 人"（4 + 20 = 24 个节点）。
+      // ★ 角色不放进这个视图：Employee 上没有 roleId（角色挂在账号上），
+      //   放进来就是两三个没有任何边连着的孤立方块 —— 看角色去 access 视图。
+      // ★ 不要把 log 放进默认视图：log_user 是 1:N，BFS 会把每个员工的日志全拉进来，
+      //   右列一下涨到 20+ 个节点，变成一根柱子（实测踩过）。
+      //   需要看日志关联时，让 AI 接业务时自己加第二个视图（views 支持多个）。
+      id: 'org',
+      label: '组织与人员关系图',
+      entities: ['department', 'employee'],
+      relations: ['emp_dept', 'dept_parent'],
+      root: 'employee',
+    },
+    {
+      // 账号视角：一条账号连着一个部门 + 多个角色。
+      // 用户管理页点「关联」走的就是这个视图（single / multi 由 layer 推导）。
+      id: 'access',
+      label: '账号与权限关系图',
+      entities: ['department', 'role', 'user'],
+      relations: ['user_dept', 'user_role'],
+      root: 'user',
+    },
+  ] as GraphView[],
+
+  // 节点详情面板的可选配置（绝大多数情况不用写：字段是从 schema 注释反推的）
+  // fieldLabels: { employee: { jobNo: '工号', position: '职位' } },
+  // fieldOptions: { employee: { gender: [{ label: '男', value: 'male' }, { label: '女', value: 'female' }] } },
+};
+
+/* ============================ 请销假系统（示例，注释掉备用） ============================ */
+/*
+export const ONTOLOGY = {
+  entities: [
+    { id:'person', label:'员工', model:'User', titleField:'username', color:'#E9EFDF', borderColor:'#B6C6A1', layer:0 },
+    { id:'request', label:'请假申请', model:'LeaveRequest', titleField:'reason', color:'#F2F0E4', borderColor:'#D2CBB2', layer:1 },
+    { id:'plan', label:'休假计划', model:'LeavePlan', titleField:'name', color:'#F4EEDF', borderColor:'#D8C8A4', layer:1 },
+    { id:'change', label:'变更申请', model:'LeaveChange', titleField:'reason', color:'#EFEDE6', borderColor:'#CFC9BA', layer:2 },
+  ],
+  relations: [
+    { id:'submit', label:'提交人', from:'request', to:'person', via:{ field:'userId' } },
+    { id:'based_on', label:'依据计划', from:'request', to:'plan', via:{ field:'planId' } },
+    { id:'change_of', label:'变更自', from:'change', to:'request', via:{ field:'requestId' } },
+    { id:'approver', label:'审批人', from:'request', to:'person', via:{ field:'approverId' } },
+  ],
+  views: [
+    { id:'leave', label:'请销假关系图', entities:['person','request','plan','change'],
+      relations:['submit','based_on','change_of','approver'], root:'request' },
+  ],
+};
+*/
+
+export default ONTOLOGY;

package/resources/src/lib/openaiCompat.ts

@@ -0,0 +1,257 @@
+/**
+ * OpenAI 兼容 Provider 统一客户端（服务端专用）。
+ *
+ * ## 为什么要单独一个文件
+ *
+ * `src/lib/ai.ts` 是"本地引擎专用"的轻客户端（只打 /chat/completions）。
+ * 但实际接入时你可能会遇到两类 provider：
+ *
+ *   1. **Chat Completions 格式**（最常见）
+ *      POST {base}/chat/completions
+ *      请求 { model, messages:[{role,content}], max_tokens, temperature }
+ *      响应 { choices:[{ message:{ content } }] }
+ *
+ *   2. **Responses 格式**（OpenAI 新接口，DeepSeek/Qwen 部分网关也支持）
+ *      POST {base}/responses
+ *      请求 { model, input: "..."/[...], max_output_tokens, temperature }
+ *      响应 { output:[{ content:[{ type:'output_text', text }] }], output_text? }
+ *
+ * 这个文件把两者的差异吃掉，对外只暴露一个 `compatInvoke()`。
+ * **零新增依赖**（不像 openai SDK 会多装一堆包），离线环境最稳。
+ *
+ * ## 配置（环境变量）
+ *
+ * ```
+ * OPENAI_BASE_URL   https://api.openai.com/v1   或   http://127.0.0.1:8092/v1
+ * OPENAI_API_KEY    sk-xxx（本地引擎随便填）
+ * OPENAI_MODEL      gpt-4o-mini / qwen3.8-27b-gsq / ...
+ * OPENAI_API_MODE   chat | responses | auto   （默认 auto：先试 chat，404/400 再试 responses）
+ * ```
+ *
+ * 和 `ai.ts` 的关系：`ai.ts` 优先读 `AI_BASE_URL/AI_MODEL`，
+ * 这里优先读 `OPENAI_BASE_URL/OPENAI_MODEL`；两者都兼容，谁配了用谁。
+ */
+
+/* ============================ 1. 配置 ============================ */
+
+export const COMPAT_BASE_URL =
+  process.env.OPENAI_BASE_URL ?? process.env.AI_BASE_URL ?? 'http://127.0.0.1:8092/v1';
+
+export const COMPAT_API_KEY =
+  process.env.OPENAI_API_KEY ?? process.env.AI_API_KEY ?? 'local';
+
+export const COMPAT_MODEL =
+  process.env.OPENAI_MODEL ?? process.env.AI_MODEL ?? 'qwen3.8-27b-gsq';
+
+/** 接口形态。auto = 先 chat.completions，失败再试 responses */
+export type ApiMode = 'chat' | 'responses' | 'auto';
+export const COMPAT_MODE: ApiMode =
+  (process.env.OPENAI_API_MODE as ApiMode) ?? 'auto';
+
+export interface CompatMessage {
+  role: 'system' | 'user' | 'assistant';
+  content: string;
+}
+
+export interface CompatOptions {
+  system?: string;
+  messages: CompatMessage[];
+  maxTokens?: number;
+  temperature?: number;
+  timeoutMs?: number;
+  /** 强制指定本次用哪种接口；不填用全局 COMPAT_MODE */
+  mode?: ApiMode;
+}
+
+export class CompatError extends Error {
+  constructor(
+    message: string,
+    readonly hint?: string,
+    readonly status?: number
+  ) {
+    super(message);
+    this.name = 'CompatError';
+  }
+}
+
+/* ============================ 2. 底层：两种接口各一个函数 ============================ */
+
+/** 拼接 endpoint，兼容 base 带不带 /v1 */
+function endpoint(path: 'chat/completions' | 'responses'): string {
+  const base = COMPAT_BASE_URL.replace(/\/+$/, '');
+  return `${base}/${path}`;
+}
+
+function headers(): Record<string, string> {
+  const h: Record<string, string> = { 'Content-Type': 'application/json' };
+  // 本地引擎常常不校验 key，但 OpenAI 兼容端点要求这个头存在
+  if (COMPAT_API_KEY) h.Authorization = `Bearer ${COMPAT_API_KEY}`;
+  return h;
+}
+
+/** Chat Completions 形态 */
+async function callChatCompletions(opts: CompatOptions): Promise<string> {
+  const { system, messages, maxTokens = 1024, temperature = 0.4, timeoutMs = 120_000 } = opts;
+
+  const body = {
+    model: COMPAT_MODEL,
+    messages: system ? [{ role: 'system', content: system }, ...messages] : messages,
+    // 新旧字段都带上，不同网关认的不一样
+    max_tokens: maxTokens,
+    max_completion_tokens: maxTokens,
+    temperature,
+    stream: false,
+  };
+
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const res = await fetch(endpoint('chat/completions'), {
+      method: 'POST',
+      headers: headers(),
+      body: JSON.stringify(body),
+      signal: ctrl.signal,
+      cache: 'no-store',
+    });
+    if (!res.ok) {
+      const t = await res.text().catch(() => '');
+      throw new CompatError(
+        `Chat Completions 返回 ${res.status}`,
+        t.slice(0, 300),
+        res.status
+      );
+    }
+    const data = (await res.json()) as {
+      choices?: { message?: { content?: string } }[];
+    };
+    const text = data.choices?.[0]?.message?.content ?? '';
+    if (!text.trim()) throw new CompatError('Chat Completions 返回空内容');
+    return text.trim();
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** Responses 形态 */
+async function callResponses(opts: CompatOptions): Promise<string> {
+  const { system, messages, maxTokens = 1024, temperature = 0.4, timeoutMs = 120_000 } = opts;
+
+  // Responses 的 input 既可以是字符串，也可以是消息数组
+  const input = [
+    ...(system ? [{ role: 'system', content: system }] : []),
+    ...messages.map((m) => ({ role: m.role, content: m.content })),
+  ];
+
+  const body = {
+    model: COMPAT_MODEL,
+    input,
+    max_output_tokens: maxTokens,
+    temperature,
+    // 显式关掉 reasoning，避免有的网关默认开思考导致超时
+    reasoning: { effort: 'none' },
+  };
+
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const res = await fetch(endpoint('responses'), {
+      method: 'POST',
+      headers: headers(),
+      body: JSON.stringify(body),
+      signal: ctrl.signal,
+      cache: 'no-store',
+    });
+    if (!res.ok) {
+      const t = await res.text().catch(() => '');
+      throw new CompatError(`Responses 返回 ${res.status}`, t.slice(0, 300), res.status);
+    }
+    const data = (await res.json()) as {
+      output_text?: string;
+      output?: {
+        type?: string;
+        content?: { type?: string; text?: string }[];
+      }[];
+    };
+
+    // 优先用顶层 output_text（网关通常会给），否则从 output 里拼
+    if (data.output_text?.trim()) return data.output_text.trim();
+
+    const parts: string[] = [];
+    for (const item of data.output ?? []) {
+      for (const c of item.content ?? []) {
+        if (c?.type === 'output_text' && c.text) parts.push(c.text);
+        else if (c?.text) parts.push(c.text);
+      }
+    }
+    const text = parts.join('\n').trim();
+    if (!text) throw new CompatError('Responses 返回空内容');
+    return text;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/* ============================ 3. 对外统一入口 ============================ */
+
+/**
+ * 调一次 OpenAI 兼容 provider，返回纯文本。
+ *
+ * auto 模式下的策略：先试 chat/completions；
+ * 如果返回 404 / 400（说明这个 provider 没有该端点或不认这个 body），
+ * 再试 responses。两个都失败就抛出**包含两次原因**的错误，
+ * 方便你判断到底是配置错了还是 provider 不支持。
+ */
+export async function compatInvoke(opts: CompatOptions): Promise<string> {
+  const mode = opts.mode ?? COMPAT_MODE;
+  const errors: string[] = [];
+
+  const tryOne = async (m: 'chat' | 'responses') => {
+    try {
+      return m === 'chat' ? await callChatCompletions(opts) : await callResponses(opts);
+    } catch (e) {
+      const ce = e as CompatError;
+      const detail = ce.hint ? `${ce.message}（${ce.hint}）` : ce.message;
+      errors.push(`${m === 'chat' ? 'chat/completions' : 'responses'}: ${detail}`);
+      return null;
+    }
+  };
+
+  if (mode === 'chat' || mode === 'responses') {
+    const r = await tryOne(mode);
+    if (r) return r;
+    throw new CompatError(
+      `调用 ${mode} 接口失败`,
+      composeHint(errors.join('\n'))
+    );
+  }
+
+  // auto
+  const a = await tryOne('chat');
+  if (a) return a;
+  const b = await tryOne('responses');
+  if (b) return b;
+
+  throw new CompatError('两种接口形态都调用失败', composeHint(errors.join('\n')));
+}
+
+function composeHint(detail: string): string {
+  return (
+    `${detail}\n\n` +
+    `请检查：1) OPENAI_BASE_URL 是否以 /v1 结尾；2) OPENAI_MODEL 是否与 provider 一致；` +
+    `3) 该 provider 是否支持 chat/completions 或 responses；` +
+    `4) 可用 OPENAI_API_MODE=chat 或 responses 强制指定。`
+  );
+}
+
+/** 探测 provider 支持哪种接口，返回可用列表（用于设置页/自检） */
+export async function detectApiModes(): Promise<{ chat: boolean; responses: boolean }> {
+  const probe: CompatOptions = {
+    messages: [{ role: 'user', content: 'hi' }],
+    maxTokens: 8,
+    temperature: 0,
+    timeoutMs: 30_000,
+  };
+  const chat = (await callChatCompletions(probe).then(() => true).catch(() => false)) as boolean;
+  const responses = (await callResponses(probe).then(() => true).catch(() => false)) as boolean;
+  return { chat, responses };
+}

package/resources/src/lib/pending.ts

@@ -0,0 +1,98 @@
+/**
+ * 全局等待任务登记表（等待反馈体系的「大脑」）。
+ *
+ * 解决的问题：比赛出的题不可预知，页面里任何一个耗时动作都可能让人干瞪眼。
+ * 与其给每个按钮/每个页面各写一套 loading，不如让**所有耗时动作都往这里登记一条**，
+ * 由全局浮层统一兜底 —— 即使写页面的人忘了加 spinner，用户也不会看到"点了没反应"。
+ *
+ * 设计取舍：
+ *   - 不用 zustand：模块级 store 在 SSR 下会被所有请求共享，容易串数据。
+ *     这里用「不可变数组 + 订阅者 + useSyncExternalStore」，服务端快照恒为空，天然安全。
+ *   - 不做定时器轮询：只记录 startedAt，"已经等了多久"由展示组件自己算，
+ *     没人看的时候不产生任何 setInterval。
+ */
+
+export type PendingKind = 'request' | 'task';
+
+export type PendingTask = {
+  id: string;
+  /** 展示给用户的人话，例如「正在生成导出文件…」 */
+  label: string;
+  /** request = 拦截器自动登记；task = 组件显式登记（AsyncButton / useAsyncTask） */
+  kind: PendingKind;
+  /** 毫秒时间戳，展示层用它算已耗时 */
+  startedAt: number;
+};
+
+/**
+ * 三个阈值，全站统一。改这里 = 改所有地方的等待手感。
+ *
+ * 为什么是这三个数：
+ *   - 200ms：低于这个时间的操作，人几乎察觉不到，闪一下 spinner 反而像"抖了一下"
+ *   - 3s   ：超过 3 秒还没有任何反馈，用户就开始怀疑"我是不是没点上"
+ *   - 8s   ：超过 8 秒必须给一句解释，否则用户会去点第二次（于是重复提交）
+ */
+export const WAIT = {
+  /** 局部 spinner 延迟出现，避免快请求闪烁 */
+  LOCAL_DELAY: 200,
+  /** 全局浮层出现阈值 */
+  GLOBAL_APPEAR: 3000,
+  /** 文案升级为「较慢，仍在继续」的阈值 */
+  SLOW: 8000,
+} as const;
+
+/** 服务端与首帧都返回同一个常量引用，useSyncExternalStore 才不会无限重渲染 */
+const EMPTY: PendingTask[] = [];
+
+let tasks: PendingTask[] = EMPTY;
+let seq = 0;
+const listeners = new Set<() => void>();
+
+function emit() {
+  // 复制一份再遍历：监听器里调用 endTask 会改 listeners，直接遍历会抛
+  for (const fn of [...listeners]) fn();
+}
+
+/** 登记一个耗时动作，返回用于注销的 id */
+export function beginTask(label: string, kind: PendingKind = 'task'): string {
+  seq += 1;
+  const id = `wb-task-${seq}`;
+  tasks = [...tasks, { id, label, kind, startedAt: Date.now() }];
+  emit();
+  return id;
+}
+
+/** 注销。重复注销 / 传不存在的 id 都安全（并发请求各自 end，不会互相顶掉） */
+export function endTask(id: string | undefined | null): void {
+  if (!id) return;
+  if (!tasks.some((t) => t.id === id)) return;
+  tasks = tasks.filter((t) => t.id !== id);
+  emit();
+}
+
+/** 页面卸载 / 登出时清空，避免残留任务把浮层永久钉在屏幕上 */
+export function clearTasks(): void {
+  if (!tasks.length) return;
+  tasks = EMPTY;
+  emit();
+}
+
+export function subscribeTasks(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+export function getTasksSnapshot(): PendingTask[] {
+  return tasks;
+}
+
+export function getTasksServerSnapshot(): PendingTask[] {
+  return EMPTY;
+}
+
+/** 给非 React 场景（拦截器、原生事件）读当前任务数用 */
+export function pendingCount(): number {
+  return tasks.length;
+}

package/resources/src/lib/prisma.ts

@@ -0,0 +1,30 @@
+import { PrismaClient } from '@prisma/client';
+import { PrismaLibSql } from '@prisma/adapter-libsql';
+
+/**
+ * Prisma 7 的用法和 6 有两个硬性差别，照着老写法会直接跑不起来：
+ *
+ * 1. 连接串不能写在 schema.prisma 的 datasource 里（会报 P1012），
+ *    要放到项目根目录的 prisma.config.ts，供 migrate / db push 使用。
+ * 2. PrismaClient 必须传 driver adapter —— Rust 查询引擎已被移除，
+ *    运行时靠 JS 侧的查询编译器 + 数据库驱动。
+ *
+ * 这里选 libSQL 而不是 better-sqlite3，是为了内网离线：
+ * libSQL 的原生二进制以「普通 npm 平台包」（@libsql/win32-x64-msvc）分发，
+ * 安装时不需要任何联网下载或本地编译；better-sqlite3 则要靠
+ * prebuild-install 去 GitHub 取二进制，离线环境下拿不到。
+ */
+const adapter = new PrismaLibSql({
+  url: process.env.DATABASE_URL ?? 'file:./dev.db',
+});
+
+const globalForPrisma = globalThis as unknown as { prisma?: PrismaClient };
+
+export const prisma =
+  globalForPrisma.prisma ??
+  new PrismaClient({
+    adapter,
+    log: process.env.NODE_ENV === 'development' ? ['warn', 'error'] : ['error'],
+  });
+
+if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma;