掘金 JavaScript

AI 帮你画模板、点一下就云打印：sv-print 这三个月都干了啥

不简说 — Mon, 19 Oct 2026 03:01:50 GMT

AI 帮你画模板、点一下就云打印：sv-print 这三个月都干了啥

哈喽哇！我是小不，不简说的不～

上一篇关于 sv-print 的文章已经是是七月初了，现在都十月中了。中间 sv-print 更了 6 次，版本号从 0.2.22 一路滚到 0.2.26，插件也越来越多啦~

我原本想数一下这三个月新增了多少东西，数到一半放弃了，太多了 😂

所以这期不按时间线写了，按模块写。

云服务、
AI 设计、
数据源、
骑缝章、
矢量 PDF、
Word 导出、
静默打印客户端纸张管理

……你用哪个就看哪个，不用从头翻。

一句话概括这三个月：

sv-print 从"一个打印设计器"变成了"一个能连云、能被 AI 帮我干活、能对接 SaaS 的打印设计器"。

一、新插件篇：这一波最大的变化

1. `@sv-print/plugin-cloud` 云服务插件 🌩️

这个是这三个月里分量最重的一个。它把 sv-print 从"孤岛"拉进了云端生态。

能干啥：

可插拔登录：oauth / token / host / local 四种模式，面板直接切换，autoLogin 启动没登录就自动登录一次
服务端渲染：不用在浏览器里渲染，直接甩给服务端出 PDF
云打印 / 中转打印：打印任务下发到云端设备，本地机器只负责发指令
模板中心：模板存云端，多人协作、跨设备同步

import "@sv-print/plugin-cloud/dist/style.css";
import pluginCloud from "@sv-print/plugin-cloud";

const plugins = [
  pluginCloud({
    // host 缺省时走当前站点 /api
    autoLogin: true, // 启动未登录时自动发起一次登录
    auth: {
      type: "oauth",
      authorizeOrigin: "https://www.example.com",
      clientId: "sv-print-demo",
      // 生产推荐: client_secret 由宿主服务端持有
      exchangeToken: async (code, state) => {
        const res = await fetch("/my-backend/svprint/token", {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({ code, state }),
        });
        return (await res.json()).data; // { accessToken, ... }
      },
    },
  }),
];

const cloud = designerUtils.cloud;
// 模板中心
cloud.templateCenter.show();
// 服务端渲染(同步) / 云打印 / 中转打印
await designerUtils.printTemplate.serverRender({ sync: true, type: "pdf" });
await designerUtils.printTemplate.cloudPrint({ device_id: "dev-xxx" });

✨ 10-18 这一版又补了几块：

云打印现在是三步走——选设备 → 选打印机 → 下发任务。以前是拿 device_id 直接打，现在有了 getDevicePrinters，能先看看这台设备上到底有几台打印机、哪台是默认：

const cloud = designerUtils.cloud;
const devices = await cloud.getDevices();
if (!devices.length) throw new Error("暂无云打印设备");
const device = devices[0];
const printers = await cloud.getDevicePrinters(device.device_id);
const printer =
  printers.find((p) => p.isDefault && !p.disabled) ||
  printers.find((p) => !p.disabled);
if (!printer) throw new Error("设备暂无可用打印机");

// 用当前设计器的模板 json 和打印数据
await cloud.cloudPrint({
  device_id: device.device_id,
  print_type: "template",
  // template_data: templateJson, // 缺省取当前设计模板数据
  // preview_data: { name: "张三" }, // 缺省取当前设计打印数据
  print_options: { printer: printer.name, copies: 1, duplexMode: "simplex" },
});

⚠️ 这版还有个细节：非设计模式下也能用模板的云端方法了，还有新建模板时会自动把云服务初始化好。你要是只在预览页塞了个 PrintTemplate，以前得自己手动 connect，现在省了。

2. `@sv-print/plugin-view-ai` AI 辅助设计 🤖

用自然语言生成模板 JSON 和打印数据。听着很玄学，实际用起来还行。

三种连接模式，可以同时配好、运行时切：

provider：SDK 里塞 API Key，最省事，但 Key 会进前端包
proxy：你后端代理一层，Key 留在服务端 —— 生产环境推荐
customService：完全自定义，你自己接什么模型都行

还有流式响应、图片输入（Ctrl+V 直接粘贴截图进去让它认）、AI 工具调用、提示管理器。

import "@sv-print/plugin-view-ai/dist/style.css";
import pluginViewAi from "@sv-print/plugin-view-ai";

const plugins = [
  pluginViewAi({
    // proxy 轻量代理模式: 服务端注入 API Key, 生产环境防泄露
    proxy: {
      proxyUrl: "https://my-server.com/api/ai/proxy",
      targetBaseUrl: "https://api.openai.com/v1",
      model: "gpt-4o",
      // 从接口动态拉取模型列表 (优先级高于 models, 失败时回退)
      modelsUrl: "https://my-server.com/api/ai/models",
    },
    showPromptManager: true, // 显示提示管理器
    enableImageInput: true, // 支持 Ctrl+V 粘贴/上传/拖拽图片
    defaultShow: false, // 默认不显示
    icon: "sv-ai",
  }),
];

🎯 实际业务场景：

新产品要给客户演示打印效果，以前得设计师出一个模板。现在让业务对着 AI 说"做一张带骑缝章的多页合同，页眉有公司名和 logo"，出来的 JSON 直接进设计器微调一下就能用。

✨ 10-18 新增了 onApplied：

这个回调是"应用成功之后"才触发，不是点一下确认就给你。以前你想在 AI 生成完之后同步点什么，只能在 onApply 里赌一把；现在可以确定模板和打印数据都落地了再干活：

import pluginViewAi from "@sv-print/plugin-view-ai";

const plugins = [
  pluginViewAi({
    // onApply 用于应用前拦截; onApplied 在用户确认且应用成功后触发
    onApplied: async ({ templateJson, printData }) => {
      if (printData != null) {
        designerUtils.dataSource.setData("default", printData);
      }
    },
  }),
];

说白了就是：AI 给你生成了打印数据，那字段树得跟着长出来对吧。这一行就把它串上了。

3. `@sv-print/plugin-view-data-source` 数据源插件 🗂️

多数据源字段树，拖拽或者点选就能把字段绑到元素上，打印的时候自动从数据源取数。

数据源支持三种取数方式，优先级从低到高：

data：直接给原始打印数据，用 parseData 解析成字段树
request：配个 url + dataPath，点开懒加载
fetcher：自定义函数，想怎么取怎么取

import "@sv-print/plugin-view-data-source/dist/style.css";
import dataSourcePlugin, { parseData } from "@sv-print/plugin-view-data-source";

const plugins = [
  dataSourcePlugin({
    sources: [
      {
        name: "default",
        title: "默认数据源",
        data: parseData(printData), // 解析打印数据为字段树
        rawData: printData, // 原始打印数据
      },
      {
        name: "user",
        title: "用户数据",
        defaultExpand: true, // 默认展开
        // 接口方式获取字段
        request: { url: "/api/user/fields", dataPath: "data.list" },
      },
      {
        name: "order",
        title: "订单数据",
        defaultExpand: false, // 默认折叠, 点击后懒加载
        // 自定义函数获取字段 (优先级最高)
        fetcher: async () => {
          const res = await fetch("/api/order/schema");
          return (await res.json()).fields;
        },
      },
    ],
    pickerMultiple: true, // 多选模式
    pickerCloseOnSelect: false, // 多选模式下选后不关闭弹窗
    onFieldSet: (field, element, optionName) => {
      // 返回 false 可以拦截这次绑定
      if (field.type === "object") return false;
      const { type } = element.printElementType;
      if (optionName === "field") {
        // 表格/子模板要数组, 列字段名不能是数组
        if (
          ["table", "box"].some((i) => type.includes(i)) &&
          field.type !== "array"
        ) {
          return false;
        }
      }
      return true;
    },
  }),
];

✨ 10-18 新增：字段树右键能改能删了。

之前字段树只能看，现在右键可以直接改字段名、显示名称、类型。改的时候嵌套字段的路径会同步更新（不会出现改了父级子级路径还挂着老名字的情况），删的时候子字段一起带走。

更关键的是运行时 API 终于来了：

const dataSource = designerUtils.dataSource;

// 更新已有数据源配置, 保留未传配置, 清除缓存及手动字段覆盖
dataSource.updateSource("product", { title: "商品资料" });
// 替换原始数据并立即重建字段树, 清除旧取数配置及手动字段覆盖
dataSource.setData("product", { sku: "A", qty: 2 });
const productData = await dataSource.getRawData("product");
const allData = await dataSource.getRawData(); // 按打印规则合并所有数据源

这套 API 一出来，数据源就从"设计时配一次"变成"运行时能改"了。上面的 onApplied 里的 setData 就是这么用的。

4. 元素插件三连：骑缝章、PDF 元素、元素工具集 🖋️

骑缝章 `@sv-print/plugin-ele-seal`

按实际渲染页数切分章图，逐页在纸边显示，拼合起来正好还原完整章图。

这个功能在纸质合同、凭证类打印里是真刚需

import pluginEleSeal from "@sv-print/plugin-ele-seal";
const plugins = [pluginEleSeal()];
// 注册后左侧"插件"分组出现"骑缝章"元素, 拖入模板即可
// 章图来源: field 打印数据字段 > src 直接配置的图片地址
// pageRange 盖章页范围: "all" | "first:3" | "1-3,5" | "odd" | "even"

PDF 元素 `@sv-print/plugin-ele-pdf`

把 PDF 文件当元素塞进模板里渲染，支持 url / base64 / dataURL 三种来源，流式分页、文字叠加层、页码范围。

叠加层支持 #{field} 和 #{pdfMeta.xxx} 占位符 —— 意思是 PDF 页面上还能盖动态内容，比如在合同 PDF 上盖一个"已审核"水印章。

import pluginElePdf from "@sv-print/plugin-ele-pdf";
const plugins = [pluginElePdf()];
// 元素参数: pdfUrl 数据源 | pdfPageRange 页码范围如 "1,3,5-8"
// pdfOverlays 叠加层支持 #{field} 与 #{pdfMeta.xxx} 占位符

元素工具集 `@sv-print/plugin-view-ele-tools`

选中元素时元素上方浮一条工具栏，还能显示尺寸标签和微调按钮。

import pluginViewEleTools, {
  getDefaultTools,
} from "@sv-print/plugin-view-ele-tools";

const plugins = [
  pluginViewEleTools({
    showSizeBox: true, // 元素底部显示尺寸标签 + 微调按钮
    sizeBoxUnit: "mm",
    sizeBoxStep: 5,
    // 按元素类型自定义工具
    resolveTools: (ctx) => {
      if (ctx.elementType === "text") {
        return [
          ...getDefaultTools(),
          {
            key: "my-extra",
            title: "自定义",
            icon: "svicon sv-font-big",
            click: (ctx) => {
              ctx.selectEls.forEach((el) =>
                el.updateOption("fontSize", 20, false)
              );
              ctx.refreshPageStructure();
            },
          },
        ];
      }
      return null; // 使用内置默认
    },
  }),
];

讲真，尺寸标签这个我太喜欢了。手动调宽高全靠眼睛，标签一挂上毫米数，改起来心里有底。

5. 导出三连：矢量 PDF、Word、Excel 增强 📦

矢量 PDF `@sv-print/plugin-api-pdf-vector`

之前导出的 PDF 是"图片 PDF"，放大就糊、文字选不中。这个插件导的是矢量的：文字可选中、可搜索、可复制，矢量图形，字体子集嵌入。

import pluginApiPdfVector from "@sv-print/plugin-api-pdf-vector";
// 需一并安装 peerDependency: @imggion/html2realpdf
const plugins = [pluginApiPdfVector({})];

let printData = { name: "张三" };
// 1. 直接下载
await hiprintTemplate.toVectorPdf(printData, { name: "pdf名称" });
// 2. 获取 blob 自行处理
const res = await hiprintTemplate.toVectorPdf(printData, {
  isDownload: false,
  type: "blob", // blob、arraybuffer、bloburl、datauristring
  onProgress: (cur, total, phase) => {
    // phase: "snapshot" | "wasm" | "complete"
    console.log("进度", phase, cur, total);
  },
});

⚠️ 注意 peerDependency 那个 @imggion/html2realpdf，漏装直接跑不起来。别问我怎么知道的 🙃

Word 导出 `@sv-print/plugin-api-word`

导出可编辑的 docx。两种模式：

editable（默认）：网格表格还原，文本/表格/图片在 Word 里原生可编辑
positioned：浮动定位，所见即所得还原设计位置

import pluginApiWord from "@sv-print/plugin-api-word";
const plugins = [pluginApiWord()];

// editable(默认): 网格表格还原, 文本/表格/图片在 Word 中原生可编辑
template.toWord(printData, { mode: "editable", name: "出库单" });
// positioned: 浮动定位, 所见即所得还原设计位置
template.toWord(printData, { mode: "positioned" });
// 不自动下载, 拿到 Blob 自行上传
template.toWord(printData, { isDownload: false }).then((blob) => {
  const form = new FormData();
  form.append("file", blob, "report.docx");
  return fetch("/api/upload", { method: "POST", body: form });
});

Excel 导出增强 `@sv-print/plugin-api-excel`

新增 customTypeResolver / onBeforeWrite / multiSheet / pageGap，文本重叠和换行效果也改了，还原度更高。

多 sheet 这个参数比较顶 —— 之前一份报表导出一个 sheet，现在可以按业务拆多个。

骑缝章、PDF、Word 这几个渲染器资源，客户端里也能在线下载更新

客户端 2.0.9 把 pdfjs、elePdf、eleSeal、textAuto、formatter、eleW2html、eleBox、eleStable 都做成在线渲染器资源了，升级不用等客户端打包。

6. 新手引导 `@sv-print/plugin-driver` 🧭

新用户进来一脸懵，不知道元素怎么拖、面板是什么、预览在哪。这个插件把整套引导步骤配好了。

支持 cacheKey 做版本缓存（引导文案改了才重新走一遍）、onHighlightStarted / onDeselected 自定义高亮前后的动作、元素可以传函数动态找、还能 disableActiveInteraction 屏蔽高亮期间的交互。

import "@sv-print/plugin-driver/dist/style.css";
import pluginDriver from "@sv-print/plugin-driver";

// 重置滚动条位置：driver.js 执行时会居中显示。执行完后重置滚动条，避免样式错乱。
const restScroll = () => {
  globalThis.$(`#paperBox`).scrollTop(0);
  globalThis.$(`.svp-designer`).scrollTop(0);
  globalThis.$(`#SVPrint`).scrollTop(0);
};

const plugins = [
  pluginDriver({
    // 缓存key，判断某个版本的 steps 是否需要执行
    cacheKey: "driver:DesignGuidance-v1",
    steps: [
      {
        element: ".svp-header",
        popover: {
          title: "这是菜单栏",
          description: "支持插槽，也可以完全自定义哟！",
        },
      },
      {
        element: () => {
          const previewBox = document.querySelector(".previewBox");
          return previewBox.closest(".svp-modal-box");
        },
        onHighlightStarted: () => designerUtils.preview.show(),
        onDeselected: () => designerUtils.preview.hide(),
        popover: {
          title: "这是预览弹窗",
          description: "支持浏览器打印、静默打印、导出图片、导出pdf。",
        },
      },
      {
        element: "#dragBox-options",
        side: "left",
        popover: {
          title: "属性区域",
          description: "点面板看面板属性，点元素看元素属性。",
        },
      },
    ],
    autoStart: true, // 是否自动开启引导, 默认 true
    driverOptions: {
      showProgress: true,
      nextBtnText: "下一步",
      prevBtnText: "上一步",
      doneBtnText: "我知道了",
    },
    onComplete: () => {
      restScroll();
      console.log("onboarded");
    },
    onSkip: () => {
      restScroll();
      console.log("onSkip");
    },
  }),
];

上面那三条 steps 是我精简过的，实际内置了一整套（菜单栏、元素列表、画布、属性区、页面结构、历史记录、概览图、页眉页脚线……大概十七八步）。直接用现成的也行。

7. 参数修改 `@sv-print/plugin-options-modify` 弹窗式下拉

之前这个插件是把下拉框换成别的控件，这版内置了弹窗式单选/多选下拉。

选项特别多的时候，下拉框拉到天荒地老也找不完，现在直接弹窗，还能搜索、还能自定义添加、还能加校验。

import pluginOptionsModify, {
  getSelectToMultiselectModifyHandler,
  PopupSelectValueGetHandler,
  PopupSelectValueSetHandler,
  PopupSelectDestroyHandler,
} from "@sv-print/plugin-options-modify";

const plugins = [
  pluginOptionsModify({
    list: [
      {
        filter: (key, target) => {
          // 忽略一些特殊参数
          return (
            !["watermarkOptions", "panelLayoutOptions", "dataType"].includes(
              key
            ) &&
            target.hasClass("hiprint-option-item") &&
            target.find(".hiprint-option-item-field select").length > 0
          );
        },
        modifyHandler: getSelectToMultiselectModifyHandler({
          mode: "single", // "single" | "multiple"
          showSearch: true, // 是否显示搜索框
          allowCustom: true, // 是否允许自定义添加
          // 显示顶部栏：选项数量超过5个时显示
          shouldShowTopbar: (count, key) => count > 5,
          // 自定义添加前的校验：只接受数字
          beforeAddCustom: (v, key) => {
            if (["fontSize", "lineHeight"].includes(key)) {
              return !isNaN(Number(v)) || (alert("请输入数字"), false);
            }
            return true;
          },
        }),
        setValueHandler: PopupSelectValueSetHandler,
        getValueHandler: PopupSelectValueGetHandler,
        destroyHandler: PopupSelectDestroyHandler,
      },
    ],
  }),
];

8. 国际化 `@sv-print/plugin-i18n` 继续补 🔤

支持自定义参数选择器列表（optionsSelectorList），你的自定义参数也能翻译
元素 / 面板 / 设计器三个层级都有回调：onPanelSelected / onElementSelected / onDesigned
新增回调延迟处理：onDesignedDelay / onSettingsDelay / onPreviewDelay
设置弹窗、预览弹窗都接上了 hook（onSettings / onPreview）
处理了特殊 DOM（带 i/span 子标签的 button 这种）
missingKeyHandler 能把缺的 key 收集起来，方便批量补翻译

延迟处理这个挺实用 —— 有些 UI 组件是异步渲染的，翻译跑早了等于没翻，onDesignedDelay: 600 就能等它。

import pluginI18n from "@sv-print/plugin-i18n";

const plugins = [
  pluginI18n({
    resources: {
      /* ... */
    },
    onDesignedDelay: 600, // 设计回调延迟(部分 UI 调整后再翻译)
    onSettingsDelay: 0, // 设置回调延迟
    onPreviewDelay: 0, // 预览回调延迟
    onSettings: (opts) => {
      /* opts.type: "show" 等 */
    },
    onPreview: (element) => {
      /* ... */
    },
  }),
];

9. 编辑器 `@sv-print/plugin-view-code-edit` 📝

模板数据、打印数据、元素 json 都能用 CodeMirror 编辑了。缩进、换行、自定义补全、搜索面板全都能配，onReady 里还能 appendExtension 追加自己的扩展（监听文档变化、加快捷键），不覆盖原有配置。

import "@sv-print/plugin-view-code-edit/dist/style.css";
import pluginViewCodeEdit from "@sv-print/plugin-view-code-edit";

const plugins = [
  pluginViewCodeEdit({
    editorConfig: {
      lineMaxLength: 120,
      searchConfig: { caseSensitive: true, regexp: true },
      tabSize: 2,
      lineWrapping: true,
      // 自定义补全项（会与内置 hinnn API 补全合并）
      autocompletion: [
        { label: "myFunc", type: "function", info: "自定义函数" },
      ],
      onReady: ({ view, state, appendExtension, EditorView }) => {
        // 1. 监听文档变化
        appendExtension(
          EditorView.updateListener.of((update) => {
            if (update.docChanged) {
              console.log("内容变化:", update.state.doc.toString());
            }
          })
        );
        // 2. 追加快捷键
        appendExtension(
          keymap.of([
            {
              key: "Ctrl-s",
              run: () => {
                console.log("保存:", view.state.doc.toString());
                return true;
              },
            },
          ])
        );
      },
    },
  }),
];

10. 格式化器 `@sv-print/plugin-formatter` 占位符匹配

${xxx} 现在可以直接执行对应 key 的格式化器了，而且能按正则匹配字段名自动套格式化。

import pluginFormatter from "@sv-print/plugin-formatter";

const plugins = [
  pluginFormatter({
    name: "格式化器",
    funList: [
      { name: "金额", key: "money", fun: (v) => `¥ ${Number(v).toFixed(2)}` },
      { name: "布尔", key: "bool", fun: (v) => (v ? "是" : "否") },
      {
        name: "打印时间",
        key: "datetime",
        fun: (v) => new Date().toLocaleString(),
      },
    ],
    regexList: [
      // 1. RegExp：对 key / fullKey 依次 test()，命中即匹配
      { regex: /(^|\.)(amount|price|total)$/i, key: "money" },
      // 2. 字符串：与 key 或 fullKey 严格相等
      { regex: "isActive", key: "bool" },
      // 3. 函数：回调 (key, value, fullKey) => boolean
      { regex: (key, value, fullKey) => key === "datetime", key: "datetime" },
    ],
  }),
];

这条最妙的是第一条正则：amount / price / total 结尾的字段自动变金额格式。后端给什么字段名都不用管了。

二、设计器本体：不太起眼但很顶的那些

1. 设置弹窗 + `onSettings` hook + header 外部更新

7-30 加了设置弹窗（主题、自定义主题、语言、帮助、使用引导、快捷键），10-10 加了 onSettings hook 让插件能注入自己的 tab。

// 打开设置 // "basic" | "language" | "help" | "shortcut" | "about"
designerUtils.openSettings("basic");
designerUtils.closeSettings();
designerUtils.changeTheme("winter");
designerUtils.changeLanguage("繁体中文");

// 插件: 在设置弹窗注入自定义 tab
const myPlugin = {
  name: "my-plugin",
  hooks: [
    {
      hook: "onSettings",
      name: "mySettingsTab",
      run: (opts) => {
        if (opts.type !== "tabs") return; // type: "tabs" | "show"
        return {
          key: "my-tab",
          label: "我的设置",
          icon: "sv-tool",
          sort: 3, // 排序, 内置 tab 为 0~5
          render: (el) => {
            el.innerHTML = "<div>自定义设置内容</div>";
          },
          destroy: (el) => {},
        };
      },
    },
  ],
  leastHiprintVersion: "0.3.42",
};

header 也能从外部改了 —— 元素列表和菜单列表都能动态增删，可以原地改也可以返回新数组自己排序：

designerUtils.header.updateMenuList((list) => {
  list.splice(0, 0, {
    icon: "sv-templates",
    title: "模板中心",
    click: (util) => {},
  });
});
designerUtils.header.updateEleList((list) => {
  /* ... */
});

设计器底部还多了客户端连接状态、云服务登录态、版本号（点击切换引擎版本）。

2. `beforeGetHtml` 这条 hook 线

7-30 加的，getHtml / print / print2 都能用，9-28 补了 data 参数和异步支持。

let printData = {};
await hiprintTemplate.getHtml(printData, {
  beforeGetHtml: ({ template, html }) => {
    // 做一些处理, 支持 promise
    return html;
  },
});

同批还有 beforePrint / beforePrint2 也是 data + 异步。能返回 Promise 这一点很重要 —— 我以前想在打印前拉一次接口（拿最新的价格、库存），只能自己绕，现在直接 await。

3. 表格能力

表体行处理模式（新）：缩小字体 / 不换行+省略 / 不换行，三选一。表格塞不下的时候终于不是"硬撑到溢出"了
右键菜单编辑表头（新）：不用再改 columns 排序那一套
表格分页逻辑优化：首页空行、表格头处理、合并删除行、标题双击下拉选源
多选元素复制粘贴时按原有布局粘贴；旋转 ±90° 时客户端打印纸张的适配
显示规则 / 隐藏规则支持多选了

4. 交互细节

Alt + Wheel / Alt + +/- 缩放画布，快捷键说明同步更新了
dragbox 支持 cache 缓存拖拽后的位置，面板尺寸变化标尺跟着更新
showModal 的 content 支持 html 字符串了（以前传 html 会被当纯文本显示）
预览组件支持缩略图和样式配置
拖动方向支持键盘移动、框选移动，指定拖动方向时不处理吸附
dragbox 调整宽高后会自动吸附贴边

5. CLI 支持 dev 环境

create-sv-print-plugin 这个 CLI 现在能创建 dev 环境了，写插件可以热调试，不用每次打包再装。

三、静默打印客户端 2.0.9

安装包：pan.quark.cn/s/428f36751…

1. 纸张管理（这个我觉得该单独吹一下）📄

打印机详情里加了纸张管理面板：纸张列表、搜索、刷新、自定义纸张尺寸。新增三个接口 —— paperSizes、validatePaper、customPaper。

⚠️ 单位先说清楚：三个接口的宽高参数传的都是微米（μm），1mm = 1000μm。所以 A4 是 210000 × 297000，不是 210 × 297。返回结果里两个都给：widthMicrons / heightMicrons 是微米，widthMm / heightMm 是毫米，前端直接拿后者显示就完事。

// http 服务方式
// 纸张列表(单位: 微米, 同时返回 mm)
const list = await fetch(
  `http://127.0.0.1:7071/printer/getPaperSizes?printerName=${encodeURIComponent(
    "printerName"
  )}`
).then((r) => r.json());
// => { ok: true, printerId, papers: [{ name, widthMm, heightMm, widthMicrons, heightMicrons, paperCode? }] }

// 校验自定义纸张尺寸是否受驱动支持
const validate = await fetch("http://127.0.0.1:7071/printer/validatePaper", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    printerName: "printerName",
    widthMicrons: 210000,
    heightMicrons: 297000,
  }),
}).then((r) => r.json());
// => { ok: true, supported: true, orientation, reason?, validatedWidthMicrons?, validatedHeightMicrons? }

// 构造一个打印任务可用的自定义纸张描述并校验
const custom = await fetch("http://127.0.0.1:7071/printer/customPaper", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    printerName: "printerName",
    widthMicrons: 80000,
    heightMicrons: 60000,
  }),
}).then((r) => r.json());
// => { ok: true, supported, custom: true, driverWidthMicrons?, driverHeightMicrons?, reason? }

💡 为什么这个值得吹？

自定义纸张这事儿的真相是：光告诉打印机"我要用 80×60mm"是没用的，得看驱动认不认。所以 validatePaper 会回你 supported: true/false 和一个 reason，customPaper 还能返回驱动实际认下来的尺寸（driverWidthMicrons）。这才是真正能落地的信息，比"设置成功"四个字有用一百倍。

// socket / mqtt 方式 (监听发送共用同一个事件名)
socket.emit("paperSizes", "printerName");
socket.on("paperSizes", (res) => {
  console.log(res.papers);
});

socket.emit("validatePaper", {
  printerId: "printerName",
  widthMicrons: 210000,
  heightMicrons: 297000,
});
socket.on("validatePaper", (res) => {
  console.log(res.supported);
});

socket.emit("customPaper", {
  printerId: "printerName",
  widthMicrons: 80000,
  heightMicrons: 60000,
});
socket.on("customPaper", (res) => {
  console.log(res);
});

2. 调试能力

openDevTools 可以打开指定打印窗口 / 模板渲染窗口的开发者工具，预览窗口也加了调试按钮。

// 打开打印窗口 / 模板渲染窗口 的开发者工具 (已打开则关闭)
await fetch("http://127.0.0.1:7071/printer/openDevTools", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ printerName: "printerName", isRenderer: false }),
});

排查渲染问题终于不用猜了，直接开 DevTools 看 DOM。

3. 打印日志能改能重打

打印日志加了刷新按钮，数据用 CodeMirror 编辑器查看，支持编辑数据后重打；打印机详情的数据也改成编辑器查看。

这个我给满分。以前打印效果不对，只能去日志里扒那一坨 JSON，改完还得手动重新发请求，现在改完直接重打。

4. `print` 接口现在会等任务跑完

// http 调用 print, 现在会等待队列任务完成并返回执行结果
const result = await fetch("http://127.0.0.1:7071/printer/print", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    printer: "printerName",
    printType: "html",
    html: "<h1>sv-print</h1>",
    copies: 2,
    landscape: false,
    duplexMode: "longEdge",
    // capture 打印可透传 snapdom 参数
    captureType: "jpeg",
    captureOptions: { dpr: 3, backgroundColor: "#fff" },
  }),
}).then((r) => r.json());
// => { success: true, msg: '', data: ... }

以前是发出去就返回，我这边只能自己轮询日志。现在直接给执行结果，省事。

5. 其他

新增/优化	说明
云打印 SaaS	客户端侧适配
http 端口可配置	1024 ~ 65535，默认 7071
任务栏显示开关	配合下面这条一起用
关闭不退出应用	按 `showInTaskbar` 决定最小化到任务栏还是藏托盘，协议唤醒时自动弹窗
渲染窗口开关	关掉模板渲染窗口能省内存 ⚠️ 但关了之后传模板 json 打印就不可用了
capture 打印	支持透传 `captureOptions`（snapdom 参数，默认 `dpr: 2`）
插件资源升级	骑缝章、word、excel、组合框、表格、pdf、textAuto、formatter
渲染器资源在线更新	pdfjs、elePdf、eleSeal、textAuto、formatter、eleW2html、eleBox、eleStable
windows pdf 打印	pdf-to-printer 升到 5.8.1，支持 `paperKind`

⚠️ 升级提醒

::: tip 温馨提示本次更新请记得更新 print-lock.css 打印样式 :::

还有一个要留神：如果为了省内存把"开启模板渲染窗口"关了，那"传模板 json 打印"就不可用了。两个开关是有依赖关系的，别为了省那点内存把功能关了。

写到最后

三个月，6 次更新，20 多个包。写完这篇我脑子是木的 😂

但有一说一，这波更新的方向我挺认的。以前 sv-print 是"设计器 + 渲染器"，这三个月补的是它外面的那一圈：连云、连 AI、连数据源、连你后端的口子。这些都不是设计器本身该干的事，但恰恰是让它真能在生产落地的部分。

我自己的心法就一条：新东西先看它有没有把"我以前要自己造轮子的那个轮子"给造了。

这三个月里对我最有用的三个：

自定义纸张的 supported + reason —— 不用再猜驱动认不认了
打印日志编辑后重打 —— 调试时间直接砍半
beforeGetHtml 支持 async —— 打印前拉接口这件事终于不用绕路

至于 AI 设计那个，坦白说我现在还在观望阶段。让它生成"标准快递面单"挺好用，让它生成"我们公司那个很特殊的、带骑缝章、四页、页眉页脚都要动态的合同"——它给的 JSON 还是得我改。所以我的用法是：让它把 70% 的体力活干掉，剩下 30% 我自己收拾。这个比例我觉得挺健康。

AI 这东西吧，讲真，好用是好用，别当它是你同事就行 😂

整理时间：2026-10-19 覆盖版本：sv-print@0.2.23 ~ 0.2.26，@sv-print/hiprint@0.3.37 ~ 0.3.42，静默打印客户端@2.0.9 原始更新日志：sv-print 更新日志

AI 流式输出都用 SSE，什么时候必须换 WebSocket？

ErpanOmer — Mon, 19 Oct 2026 02:55:31 GMT

上个月，我们的 AI 客服助手全量上线，第三天运维就找上门：问答接口的 QPS 莫名翻了一倍，客服还收到一堆投诉，说回答半天不吐字，用户以为卡死，点一次发一次，重试越点越多。

查了一圈，根因不在大模型，而在传输层。Nginx 默认把流式响应缓冲起来攒一波再吐，首字硬生生拖到 8 秒；前端用的还是最省事的裸 EventSource，断了不报错、慢了不提示，用户只能靠狂点续命。重试流量反过来又压垮网关，恶性循环。

这就是流式场景最真实的场景：模型没问题，管子先爆了。今天就把这根管子讲透，什么时候 SSE 够用，什么时候必须换 WebSocket，以及各自的坑怎么填。

裸 `EventSource` 和 `WebSocket`

出问题后，组里出现两种声音。一种说 EventSource 一行代码就能跑，别折腾；另一种说干脆全量切 WebSocket，一劳永逸。这两条路我都踩过，都有坑，只是结果不同。

裸 `EventSource` 的坑在哪？

EventSource 的 API 是只读的：只支持 GET，不支持自定义请求头。token 只能拼在 URL 上，网关日志、CDN 日志、浏览器历史全是明文，安全评审直接打回。断线重连看似自动，实则裸奔：没有服务端配合回放 Last-Event-ID，重连后要么丢消息，要么从头发完整流，用户会看到回答闪一下重打一遍。更隐蔽的是超时，Nginx 默认 proxy_buffering on，流式响应会被攒批，首字时间完全不可控。

`WebSocket` 的坑呢？

WebSocket 是长连接，网关要为每个连接维持状态，连接数直接变成成本。我们的客服页是低频使用的页面，用户问完就关，为这种低频、单向、下行主导的流量维持全双工连接，实例数要翻几倍。移动端更惨，切后台、锁屏、进电梯，连接一断就得整套重连、重鉴权、重订阅，心跳和退避策略全要自己写。

结论很清晰了👉：下行主导、低频、低延迟要求不极致，用 SSE；双向实时、高频上行、需要服务端主动推且客户端也要频繁说话，才上 WebSocket。比如多轮问答、摘要生成是 SSE 的主场；协作编辑、语音对讲、实时游戏状态同步，才是 WebSocket 的主场。

生产级的 `SSE` 客户端长什么样

先看大多数人写的版本，十五分钟能跑，三个月后必返工：

// 这个能跑，但迟早返工
export function streamAnswer(url: string, onToken: (t: string) => void) {
  const es = new EventSource(url); // token 只能拼 URL，GET 裸奔
  es.onmessage = (e) => onToken(e.data);
  es.onerror = () => {
    es.close(); // 断了就关，没有重连，没有续接
  };
}

生产级版本必须同时解决四件事：POST + token 请求头鉴权、可取消、断线按 Last-Event-ID 续接、退避重试。直接上代码：

// 真正的 fetch + ReadableStream 的生产级 SSE 客户端
interface SSEMessage {
  id: string | null;
  event: string;
  data: string;
}

interface StreamOptions {
  headers?: Record<string, string>;
  lastEventId?: string | null;
  maxRetries?: number;
  baseDelayMs?: number;
  signal?: AbortSignal;
  onMessage?: (msg: SSEMessage) => void;
  onDone?: () => void;
}

function parseSSEBlock(block: string): SSEMessage | null {
  let id: string | null = null;
  let event = 'message';
  const dataLines: string[] = [];
  for (const line of block.split('\n')) {
    if (line.startsWith('id:')) id = line.slice(3).trim();
    else if (line.startsWith('event:')) event = line.slice(6).trim();
    else if (line.startsWith('data:')) dataLines.push(line.slice(5).trimStart());
    else if (line.startsWith(':')) continue; // 服务端心跳注释行
  }
  if (dataLines.length === 0 && id === null) return null;
  return { id, event, data: dataLines.join('\n') };
}

function sleep(ms: number, signal?: AbortSignal): Promise<void> {
  return new Promise((resolve, reject) => {
    const timer = setTimeout(() => {
      signal?.removeEventListener('abort', onAbort);
      resolve();
    }, ms);
    const onAbort = () => {
      clearTimeout(timer);
      reject(new DOMException('aborted', 'AbortError'));
    };
    signal?.addEventListener('abort', onAbort, { once: true });
  });
}

export async function streamSSE(url: string, body: unknown, options: StreamOptions = {}): Promise<void> {
  const { headers = {}, maxRetries = 5, baseDelayMs = 1000, signal, onMessage, onDone } = options;
  let lastEventId = options.lastEventId ?? null;
  let attempt = 0;

  while (true) {
    signal?.throwIfAborted();
    let res: Response;
    try {
      res = await fetch(url, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json', Accept: 'text/event-stream', ...headers },
        body: JSON.stringify({ ...(body as Record<string, unknown>), ...(lastEventId ? { resume_from: lastEventId } : {}) }),
        signal,
      });
    } catch (err) {
      if (err instanceof DOMException && err.name === 'AbortError') return; // 用户主动取消，不算失败
      if (++attempt > maxRetries) throw err;
      await sleep(Math.min(baseDelayMs * 2 ** attempt + Math.random() * 500, 30000), signal);
      continue;
    }

    if (!res.ok || !res.body) {
      if (++attempt > maxRetries) throw new Error(`stream failed: HTTP ${res.status}`);
      await sleep(Math.min(baseDelayMs * 2 ** attempt + Math.random() * 500, 30000), signal);
      continue;
    }

    attempt = 0; // 连上一次，清零计数
    const reader = res.body.getReader();
    const decoder = new TextDecoder();
    let buffer = '';

    try {
      for (;;) {
        const { done, value } = await reader.read();
        if (done) break;
        buffer += decoder.decode(value, { stream: true });
        const blocks = buffer.split('\n\n');
        buffer = blocks.pop() ?? '';
        for (const block of blocks) {
          const msg = parseSSEBlock(block);
          if (!msg) continue;
          if (msg.id) lastEventId = msg.id; // 记住位点，断线从这里续
          if (msg.event === 'done') {
            onDone?.();
            await reader.cancel().catch(() => undefined);
            return;
          }
          onMessage?.(msg);
        }
      }
      onDone?.();
      return; // 服务端正常关流，结束
    } catch (err) {
      if (err instanceof DOMException && err.name === 'AbortError') {
        await reader.cancel().catch(() => undefined);
        return;
      }
      if (++attempt > maxRetries) throw err; // 读一半断了，带位点重试
      await sleep(Math.min(baseDelayMs * 2 ** attempt + Math.random() * 500, 30000), signal);
    } finally {
      reader.releaseLock();
    }
  }
}

用法上配合 AbortController 做取消，组件卸载或用户点停止时直接 abort，不再有幽灵请求：

const controller = new AbortController();

streamSSE('/api/chat/stream', { messages }, {
  headers: { Authorization: `Bearer ${token}` }, // 头部鉴权，不拼 URL
  signal: controller.signal,
  onMessage: (msg) => appendToken(msg.data),
  onDone: () => setLoading(false),
}).catch((err) => {
  if (err instanceof DOMException && err.name === 'AbortError') return;
  toast('网络抖动，已自动重试仍失败，请再试一次');
  report(err); // 上报监控，带 lastEventId 便于复盘
});

// 用户点停止 / 组件卸载
controller.abort();

讲一讲遇到的一些坑

客户端写结实了，线上照样可能翻车。下面 👇 四个全是生产里真金白银换来的，每个都给兜底。

`Nginx` 吞流，首字永远慢

Nginx 默认 proxy_buffering on，会把上游的流攒成块再吐，流式直接退化成轮询。兜底要在 location 里显式关掉，并让上游声明不缓冲：

location /api/chat/stream {
  proxy_pass http://upstream;
  proxy_buffering off;          # 关键：禁止攒批
  proxy_cache off;
  proxy_read_timeout 300s;      # 流式需要长超时
  proxy_http_version 1.1;
  chunked_transfer_encoding on;
}

服务端再补一个响应头 X-Accel-Buffering: no，双保险。验收标准只有一个：首字时间进监控，超过 3 秒直接告警，别等用户投诉🤷‍♂️。

浏览器同域连接上限，`SSE` 会断开其他请求

HTTP/1.1 下浏览器对同一域名只有 6 个并发连接，SSE 一旦连上就长期占一个。用户开三个问答标签页，再加载页面资源就开始排队，页面转圈的锅最后全算在前端头上。兜底策略：全局限制同页 SSE 并发数为 1，后开的流先 abort 前一个；切 HTTP/2 则多路复用天然缓解，但网关的 stream 并发上限同样要核对，别从浏览器瓶颈换成网关瓶颈👋。

断线重连导致消息重复

网络抖动是常态，重连后服务端从 Last-Event-ID 重放，客户端如果直接追加，用户会看到半截回答突然重来一遍。正确做法是按 ID 去重 + 按位点替换：维护已收 ID 集合，重放的消息只用于补位不重复渲染；服务端必须保证 ID 单调递增，这是前后端要对齐的契约，不是前端单方面能解决的🫡。

网关空闲超时切断和移动端切后台直接失联

多数网关默认 60 秒无数据就掐连接，大模型思考超过 60 秒不吐字，连接就被静默掐掉。兜底是服务端每 15 秒发一条注释心跳（:\n\n），既保活又不污染业务流；客户端加一层兜底计时器，30 秒无任何字节就主动重连。同时统计要洗干净：重连次数、首字时间、完整率单独上报，别把重连算进接口成功率里，否则监控一片祥和，线上全是断流。

什么时候必须换 `WebSocket`

最后给一张决策表，贴在组里能少吵很多架。出现下面任意一条，SSE 不要硬撑，直接上 WebSocket！

WebSocket 也不是换过去就完事，心跳、重连退避、token 过期重鉴权，一行都不能少：

// WebSocket 保活与重连骨架：心跳 + 指数退避，token 过期单独处理
interface WSOptions {
  heartbeatMs?: number;
  maxRetries?: number;
  getToken: () => Promise<string>;
  onMessage: (data: string) => void;
}

export function connectWS(url: string, options: WSOptions): () => void {
  const { heartbeatMs = 25000, maxRetries = 8, getToken, onMessage } = options;
  let ws: WebSocket | null = null;
  let retries = 0;
  let timer: ReturnType<typeof setInterval> | null = null;
  let closed = false;

  const open = async () => {
    const token = await getToken();
    ws = new WebSocket(`${url}?token=${encodeURIComponent(token)}`);
    ws.onopen = () => { retries = 0; };
    ws.onmessage = (e) => {
      if (typeof e.data !== 'string') return;
      if (e.data === 'pong') return; // 心跳回包，直接丢弃
      onMessage(e.data);
    };
    ws.onclose = () => {
      if (timer) clearInterval(timer);
      if (closed || ++retries > maxRetries) return;
      setTimeout(open, Math.min(1000 * 2 ** retries, 30000)); // 退避重连
    };
  };

  timer = setInterval(() => {
    if (ws?.readyState === WebSocket.OPEN) ws.send('ping');
  }, heartbeatMs);
  void open();

  return () => { closed = true; if (timer) clearInterval(timer); ws?.close(); };
}

注意 token 过期时不要无脑重连，先刷新 token 再建连，否则重连风暴里全是 401，网关日志会被打爆。

流式传输的技术选型，从来都是成本多少的问题。SSE 便宜、简单、和 HTTP 基础设施处得来，配上可取消、可续接的客户端，能覆盖九成 AI 问答场景；WebSocket 留给真正双向的场景。但是别让低频页面替长连接买单！

好了，今天就分享到这里吧🙌

喜欢我的文章，也欢迎关注我的微信公众号：【前端技术官】。

主要分享：前端架构 · AI 编程 · 职场认知 · 开发者成长

微信扫码关注 👆

不定期更新，不刷屏，聊点真正有用的干货。

CPU就行, 老照片变清晰, 本地部署582mb腾讯的模型, 本地部署, 过节了给长辈们变个小魔术

半刻维度 — Mon, 19 Oct 2026 02:02:04 GMT

老照片糊成一团，一键变清晰。

这次项目用 Python 写。

但机器没要求。

随便一台电脑就行，集成显卡都够用。

不用买显卡，不用配 CUDA。

照片也不出电脑，全本地推理。

5 行核心代码：

from gfpgan import GFPGANer                    # 导入修脸器
import cv2                                     # 读图、写图

restorer = GFPGANer(
    model_path="weights/GFPGANv1.4.pth",       # 主模型权重
    upscale=2,                                 # 最终放大 2 倍
    arch="clean",                              # clean 版结构
    channel_multiplier=2,                      # 通道倍数，跟权重对应
)
_, _, out = restorer.enhance(
    cv2.imread("old.jpg"),                     # 读入老照片
    paste_back=True,                           # 修完的脸贴回原图
    weight=0.5,                                # 保真度，越小修得越狠
)
cv2.imwrite("new.jpg", out)                    # 结果存盘

就这些。

剩下都是工程活。

流程图

    上传老照片
        │
        ▼
    Real-ESRGAN 4x 超分（背景）
        │
        ▼
    facexlib 人脸检测对齐
        │
        ▼
    GFPGAN v1.4 修脸
        │
        ▼
    按遮罩贴回原图
        │
        ▼
    CPU 单张 8 秒，有显卡更快

1 痛点

爷爷奶奶那辈的照片，扫描出来脸糊成一团。

调云端 API，一张图几分钱。

全家几十张，账单吓人。

更麻烦的是，图得传外网。

家庭照片、客户资料，能往外发吗？

这套组合，全本地推理。

2 两个模型怎么分工

| 模型 | 星数 | 干啥 | | :-- | :-- | :-- | | GFPGAN | 37.6k | 修脸，专治糊脸 | | Real-ESRGAN | 36.8k | 超分，整图放大补像素 |

都是腾讯 ARC 实验室出品，同一套生态。

GFPGAN 靠 GAN + 人脸先验。

它见过几百万张脸，知道正常人脸该长啥样。

糊掉的五官，它敢按先验补回来。

Real-ESRGAN 管背景，整图放大 4 倍，像素一点点补。

两个一起用，脸和背景都清楚。

demo 就是个网页：拖图进去，滑条对比，参数可调，日志实时。

3 有显卡自动加速

设备选择就几行：

def pick_device():                                        # 挑一个运行设备
    forced = os.getenv("DEVICE", "").strip().lower()      # 读 DEVICE 环境变量
    if forced in ("cuda", "cpu"):                         # 手动指定过就听它的
        return forced
    return "cuda" if torch.cuda.is_available() else "cpu" # 有显卡上显卡

装 CPU 版 torch 它就走 CPU。

换 CUDA 版，代码一行不改。

显存小也不怕，超分器按分块跑：

tile = 512 if device == "cuda" else 192   # 显卡切大块，CPU 切小块省内存

实测（CPU，413×617 含人脸, CPU: AMD5500）：

所以 CPU 4秒出图。

因为我还有个老古董1660S显卡, 开了CUDA试了下, 确实快了很多, 但是就1张照片的话无所谓了, 就快2s。

4 装环境不用踩坑

三个坑，脚本全填平了。

一是 basicsr 源码安装时要 import torch。

先装 torch，再装模型库，顺序对了就能过。

二是 gfpgan 硬依赖 tb-nightly，国内源没有，用 --no-deps 绕过。

那包只有训练才用，推理一行不碰。

三是新版 torchvision 删了 functional_tensor，造个替身塞进去：

def patch_torchvision():
    import sys, types                                  # 改模块表 + 造新模块
    import torchvision.transforms.functional as F     # 新版功能都在这里
    shim = types.ModuleType(                           # 造一个空壳当替身
        "torchvision.transforms.functional_tensor")
    shim.__dict__.update(                              # 把函数全搬进替身
        {k: v for k, v in F.__dict__.items() if not k.startswith("__")})
    sys.modules[                                       # 注册进模块表
        "torchvision.transforms.functional_tensor"] = shim

import gfpgan 之前跑一次就行。

依赖全用 uv，比 pip 快一个数量级，源走清华：

uv venv                                                      # 建虚拟环境
uv pip install -r requirements.txt                           # 先装 torch 等基础依赖
uv pip install --no-deps basicsr facexlib realesrgan gfpgan  # 后装模型库，绕开 tb-nightly

5 权重下载不断线

四个文件，约 580MB。

GitHub 直连常被限速到几十 KB/s。

大文件走多线程分块下载：

headers = {**UA, "Range": f"bytes={start}-{end}"}   # 每个线程只下自己那段

镜像挂了自动回直连，重试 20 次。

还有个暗坑：官方 parsing_parsenet 的 v0.1.0 链接是 404，真地址在 v0.2.2。

脚本还会把检测、解析这两个权重复制进 facexlib 包目录。

不复制的话，运行时它自己去 GitHub 下，基本必卡。

6 接口简单，模型带缓存

FastAPI 接收图片、调修脸器、返回 base64：

@app.post("/api/restore")                          # 前端把图传上来
async def api_restore(file: UploadFile = File(...),
                      upscale: int = Form(2), weight: float = Form(0.5)):
    img = cv2.imdecode(                            # 字节流转图片矩阵
        np.frombuffer(await file.read(), np.uint8), cv2.IMREAD_COLOR)
    _, _, out = get_restorer(upscale, bg).enhance( # 取缓存的修脸器
        img, paste_back=True, weight=weight)
    ok, buf = cv2.imencode(".png", out)            # 编成 PNG
    return {"image": "data:image/png;base64="      # 拼 data URI 给前端
            + base64.b64encode(buf.tobytes()).decode()}

get_restorer 按 (device, upscale, bg) 缓存。

参数不变就复用，不重复加载模型。

没检测到人脸也不返回空，自动退化成整图超分。

前端日志直接打：

完成 · 8123ms · 检测到 1 张脸 · cpu

端口被占了自动找下一个空位。

分辨率高的执行时间也长, 但是效果真的好

7 跑起来

cd demo/24
powershell -ExecutionPolicy Bypass -File setup.ps1 -Run   # 装完直接起服务

老照片修复服务 · http://localhost:3024
  设备: cpu · 权重: D:\www\ai-coder\demo\24\weights

强制设备也简单：

$env:DEVICE="cpu";  .\.venv\Scripts\python.exe server.py   # 锁死 CPU
$env:DEVICE="cuda"; .\.venv\Scripts\python.exe server.py   # 有显卡走显卡

总结

• GFPGAN：37.6k 星，GAN + 人脸先验，专治糊脸
• Real-ESRGAN：36.8k 星，整图超分，管背景
• 本地推理：照片不离开电脑，CPU 只修脸 4 秒
• 一键脚本：三个装环境坑全填平，权重断了接着下

一张老照片，八秒钟的事。

不用买显卡，不用配 CUDA。

老照片发朋友圈，家人都会说，你小子有本事。

栗子前端技术周刊第 150 期 - Stack Overflow 开发者调查结果、TanStack Start 1.0...

晓得迷路了 — Mon, 19 Oct 2026 00:33:44 GMT

🌰栗子前端技术周刊第 150 期 (2026.09.11 - 2026.10.18)：浏览前端一周最新消息，学习国内外优秀文章，让我们保持对前端的好奇心。

📰 技术资讯

Stack Overflow 开发者调查结果：2026 年 Stack Overflow 开发者调查结果已公布（共有 30903 人参与）：JavaScript 连续第 12 年位居编程语言榜首，TypeScript 排在第 6 位。
TanStack Start 1.0：这款日渐流行、同时支持 React 和 Solid 的全栈框架迎来稳定版，为部署在 Node、Bun、Cloudflare Workers 等多平台的应用提供类型安全的服务端函数与流式 SSR。文中对比了它和 Next.js 的差异。
Bootstrap 6 Alpha：一睹这款热门框架自 2021 年以来的首个大版本。本次更新主打现代化改造：大部分 Sass 变量已转为 CSS 变量，JS 插件仅支持 ESM 模块，并且更多依托浏览器原生能力实现。
Bun 1.4.3：Bun 1.4.3 新增内置 TypeScript 类型检查器 bun check：bun check 移植自 TypeScript 7 的类型检查器，会读取你的 tsconfig.json，输出和 tsc 一致的报错信息。Jarred 称它的运行速度快 3～6 倍，同时还能集成到 bun run/bun test/bun build 命令中。空闲服务器进程现在 CPU 占用大幅降低，并且本次升级了 JavaScriptCore，带来多项性能提升。

📒 技术文章

Lazy Loading Images and Media: How Far Ahead Browsers Fetch：图片与媒体懒加载：浏览器会提前多久预加载资源 - Ben 测试了 Chrome、Firefox、Safari 对懒加载媒体资源的预加载超前距离。他还介绍了哪些资源可以懒加载（包括 Chromium 系浏览器中的视频与音频），并讲解了懒加载、立即加载以及 fetchpriority 该如何搭配使用。
浏览器为什么加载不了超大图片：一张 87 MB 的 JPEG 在 Network 面板中返回 200 OK，但页面上却只显示“图片加载失败”。问题究竟出在网络、组件，还是浏览器？
把 649 种文件格式塞进一个网页里：一个「文件不出浏览器」的预览器：一个跑在浏览器里的文件预览器：649 个扩展名——Office、PDF、OFD、CAD、三维、科研体数据、医学影像、压缩包、邮件、电子书、字体、流媒体、旧式音视频……全部在本机解析。没有上传接口，没有服务端转码，产物是纯静态文件，丢到任何静态托管就能用。

🔧 开发工具

reseter.css 3.0：这款热门 CSS 重置库迎来 v3 重大重构。完整版（full）和精简版（mini）现在都封装在 @layer reset 层中，让样式覆盖行为可控；全部采用逻辑属性，基于 Lightning CSS 构建，压缩后体积仅约 1KB。

H3 v2：基于 Web 标准重构的 UnJS HTTP 框架 —— 作为 Nitro 和 Nuxt 服务层底层的轻量 HTTP 框架，v2 版本现已稳定。本次重写围绕标准的 Request / Response 对象构建，同一个应用可在 Node、Bun、Deno、Workers，甚至浏览器中运行。

he 2.0：可靠的 HTML 实体编解码器。时隔八年迎来新版本，现已改为 ESM 模块并支持命名导出。

🚀🚀🚀 以上资讯文章选自常见周刊，如 JavaScript Weekly 等，周刊内容也会不断优化改进，希望你们能够喜欢。

💖 欢迎关注微信公众号：栗子前端

从零构建 Mastra RAG MVP：DeepSeek、SiliconFlow 与 PostgreSQL/pgvector 实战

大明二代 — Sun, 18 Oct 2026 11:29:34 GMT

最近我在尝试使用 Mastra 构建一个简单的 RAG（Retrieval-Augmented Generation，检索增强生成）应用。目标并不是一开始就做完整的知识库平台，而是先打通一条最小可用链路：把自己的 Markdown 技术文章导入向量数据库，然后用自然语言提问，让模型根据文章内容回答问题。

这次选用的技术组合是：

Mastra：组织 Agent 和 Tool。
DeepSeek：负责理解问题、决定调用检索工具并生成答案。
SiliconFlow：提供 BAAI/bge-m3 Embedding 模型，将文本转换为向量。
PostgreSQL + pgvector：保存并检索文档向量。
TypeScript：实现导入脚本、检索服务和命令行问答。

这篇文章记录 MVP 的实现思路、关键代码，以及真正遇到的几次错误。代码按这次项目的实现方式整理；Mastra 和 AI SDK 的具体类型、方法签名可能随版本调整，复制时应以项目安装版本为准。

一、先理解要实现的 RAG 链路

普通 LLM 并不知道我最近在 GitHub 上修改了什么，也不一定知道 Health Master 项目为什么从 MD5 迁移到 Argon2id。RAG 的思路是先检索外部知识，再将检索到的上下文提供给模型。

Markdown 技术文章
       │
       ▼
   MDocument
       │
       ▼
  Chunking（文本切分）
       │
       ▼
SiliconFlow / BAAI/bge-m3
       │
       ▼
Embedding（1024 维）
       │
       ▼
PostgreSQL / pgvector
       │
       ├──────────────────────────────┐
       │                              │
       ▼                              │
 用户自然语言提问                      │
       │                              │
       ▼                              │
  Mastra Agent（DeepSeek）            │
       │                              │
       ▼                              │
 knowledgeSearchTool                  │
       │                              │
       ▼                              │
 问题 Embedding → 相似度检索 ───────────┘
       │
       ▼
 返回相关 Chunk + source
       │
       ▼
 DeepSeek 组织答案

这里有两个阶段：Ingestion（知识入库） 和 Retrieval + Generation（检索与生成）。Embedding 模型和生成模型可以来自不同服务商；两者不需要是同一个模型。

二、项目初始化

在一个 Node.js / TypeScript 项目中安装依赖：

npm install @mastra/core @mastra/rag @mastra/pg @ai-sdk/openai-compatible ai dotenv
npm install -D typescript tsx

项目按职责拆分：

mastra-rag-app/
├── src/
│   ├── mastra/
│   │   ├── agents/
│   │   │   └── knowledge.agent.ts
│   │   ├── lib/
│   │   │   ├── embedding.ts
│   │   │   └── vector-store.ts
│   │   ├── services/
│   │   │   ├── knowledge.service.ts
│   │   │   └── retrieval.service.ts
│   │   └── tools/
│   │       └── knowledge-search.tool.ts
│   └── scripts/
│       ├── init-vector-db.ts
│       ├── ingest.ts
│       ├── search.ts
│       └── chat.ts
├── .env
└── package.json

环境变量示例：

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/mastra_rag
SILICONFLOW_API_KEY=your-siliconflow-api-key
SILICONFLOW_BASE_URL=https://api.siliconflow.cn/v1
DEEPSEEK_API_KEY=your-deepseek-api-key

不要把真实密钥提交到 Git 仓库。建议将 .env 加入 .gitignore，另提供不含密钥的 .env.example。

PostgreSQL 的准备工作

数据库需要安装 pgvector 扩展。确保使用的是支持 pgvector 的 PostgreSQL 实例，然后在目标数据库执行：

CREATE EXTENSION IF NOT EXISTS vector;

注意：安装数据库扩展与创建 Mastra 使用的向量表是两件不同的事。

三、配置 SiliconFlow Embedding

创建 src/mastra/lib/embedding.ts：

import { createOpenAICompatible } from "@ai-sdk/openai-compatible";

const apiKey = process.env.SILICONFLOW_API_KEY;
if (!apiKey) {
  throw new Error("SILICONFLOW_API_KEY is missing");
}

export const siliconflow = createOpenAICompatible({
  name: "siliconflow",
  baseURL: process.env.SILICONFLOW_BASE_URL ?? "https://api.siliconflow.cn/v1",
  apiKey,
});

export const embeddingModel = siliconflow.embeddingModel("BAAI/bge-m3");

BAAI/bge-m3 在这次调用中返回 1024 维向量。这决定了后续创建 pgvector 索引时的 dimension 参数。

这里踩过两个坑。

坑一：Embedding 请求返回 404

一开始配置的 baseURL 没有包含 /v1，请求最终命中了错误的路径。改为：

https://api.siliconflow.cn/v1

之后才进入正确的 Embedding 接口。对于 OpenAI-compatible Provider，Base URL 是否包含版本前缀必须核对服务商文档。

坑二：Embedding 请求返回 401

当时一度怀疑 .env 没有加载、API Key 无效，或者 SDK 的请求格式有问题。于是分别用原生 fetch 和 SDK 做最小化测试：

import "dotenv/config";
import { embed } from "ai";
import { embeddingModel } from "../mastra/lib/embedding";

const { embedding } = await embed({
  model: embeddingModel,
  value: "测试 Embedding 是否正常",
});

console.log("Dimensions:", embedding.length);

原生 HTTP 请求返回 200，SDK 测试也能输出 Dimensions: 1024，说明服务本身和模型调用没有问题。最终发现实际项目中的配置把 SILICONFLOW 拼成了 SILOCONFLOW，导致读取了错误的环境变量名。

这个排错过程的经验是：先用最小请求证明第三方 API 可用，再逐层检查业务代码，不要一开始就把所有问题归因于框架。

四、配置 PostgreSQL 向量存储

创建 src/mastra/lib/vector-store.ts：

import { PgVector } from "@mastra/pg";

export const INDEX_NAME = "knowledge_base";

export const vectorStore = new PgVector({
  id: "knowledge-vectors",
  connectionString: process.env.DATABASE_URL!,
});

这里的 INDEX_NAME 是后续写入和查询时使用的名称，必须保持一致。

坑三：Vector table 不存在

Embedding 调用成功后，导入时遇到：

MastraError: Vector table "knowledge_base" does not exist
id: MASTRA_VECTOR_PG_DESCRIBE_INDEX_FAILED

原因很直接：配置 PgVector 实例并不会自动替我们创建 knowledge_base 表。需要先创建索引对应的存储结构。

创建 src/scripts/init-vector-db.ts：

import "dotenv/config";
import { vectorStore, INDEX_NAME } from "../mastra/lib/vector-store";

async function main() {
  await vectorStore.createIndex({
    indexName: INDEX_NAME,
    dimension: 1024,
  });

  console.log(`Vector index "${INDEX_NAME}" initialized`);
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

首次运行前先执行初始化脚本。若索引已经存在，是否允许重复执行取决于所安装的 Mastra 版本；不应假设 createIndex() 一定是幂等的。

五、将 Markdown 切分并导入向量库

创建 src/mastra/services/knowledge.service.ts：

import { MDocument } from "@mastra/rag";
import { embedMany } from "ai";
import { embeddingModel } from "../lib/embedding";
import { vectorStore, INDEX_NAME } from "../lib/vector-store";

export async function ingest(text: string, source: string) {
  const document = MDocument.fromText(text);

  const chunks = await document.chunk({
    strategy: "recursive",
    maxSize: 512,
    overlap: 50,
  });

  if (chunks.length === 0) {
    return { count: 0 };
  }

  const { embeddings } = await embedMany({
    model: embeddingModel,
    values: chunks.map((chunk) => chunk.text),
  });

  await vectorStore.upsert({
    indexName: INDEX_NAME,
    vectors: embeddings,
    metadata: chunks.map((chunk, index) => ({
      text: chunk.text,
      source,
      chunkIndex: index,
    })),
  });

  return { count: chunks.length };
}

source 保存文档来源，例如 GitHub Raw Markdown URL。后面检索到 Chunk 时，可以用它展示引用来源。

编写导入脚本

下面是一个适合本地 Markdown 文件的 CLI 示例，创建 src/scripts/ingest.ts：

import "dotenv/config";
import { readFile } from "node:fs/promises";
import { resolve } from "node:path";
import { ingest } from "../mastra/services/knowledge.service";

const file = process.argv[2];
if (!file) {
  throw new Error("Usage: npm run ingest -- <markdown-file> [source-url]");
}

const text = await readFile(resolve(file), "utf8");
const source = process.argv[3] ?? file;
const result = await ingest(text, source);

console.log(`Ingested ${result.count} chunks from ${source}`);

运行示例：

npm run ingest -- ./articles/golang-argon2id-password-hashing.md \
  https://raw.githubusercontent.com/damingerdai/damingerdai.github.io/refs/heads/master/source/_posts/back-end/golang-argon2id-password-hashing.md

这篇 Argon2id 文章有 YAML Front Matter、标题、代码块和表格。当前 MVP 直接使用递归切分策略，能够工作，但不是专门针对 Markdown 语义结构优化的切分方式。后续可以考虑按标题层级分段，并避免将代码块截断。

当前限制：上面的 upsert 没有提供稳定的 Chunk ID。重复导入同一篇文章时，可能产生重复向量。幂等导入、文档更新和删除尚未实现。

六、先不接 Agent，验证向量检索

将检索独立成服务有一个好处：出现问题时，可以明确区分是 Embedding/向量检索不准确，还是 Agent/LLM 没有正确使用检索结果。

创建 src/mastra/services/retrieval.service.ts：

import { embed } from "ai";
import { embeddingModel } from "../lib/embedding";
import { vectorStore, INDEX_NAME } from "../lib/vector-store";

export async function retrieve(query: string, topK = 5) {
  const { embedding } = await embed({
    model: embeddingModel,
    value: query,
  });

  const results = await vectorStore.query({
    indexName: INDEX_NAME,
    queryVector: embedding,
    topK,
  });

  return results.map((result) => ({
    id: result.id,
    score: result.score,
    text: String(result.metadata?.text ?? ""),
    source: String(result.metadata?.source ?? ""),
  }));
}

创建 src/scripts/search.ts：

import "dotenv/config";
import { retrieve } from "../mastra/services/retrieval.service";

const query = process.argv.slice(2).join(" ") || "为什么使用 Argon2id？";
const results = await retrieve(query, 3);

for (const [index, result] of results.entries()) {
  console.log(`\n--- Result ${index + 1} ---`);
  console.log("Score:", result.score);
  console.log("Source:", result.source);
  console.log("Text:", result.text);
}

测试：

npm run search -- "Health Master 为什么使用 Argon2id？"

这里的 score 是检索相似度得分，不是模型答案的正确率，也不能直接当作可信度百分比。

七、将检索包装成 Mastra Tool

创建 src/mastra/tools/knowledge-search.tool.ts：

import { createTool } from "@mastra/core/tools";
import { z } from "zod";
import { retrieve } from "../services/retrieval.service";

export const knowledgeSearchTool = createTool({
  id: "knowledge-search",
  description:
    "Search the knowledge base for relevant information about stored documents.",
  inputSchema: z.object({
    query: z.string().describe("Search query"),
  }),
  outputSchema: z.object({
    results: z.array(
      z.object({
        source: z.string(),
        text: z.string(),
        score: z.number(),
      }),
    ),
  }),
  execute: async ({ query }) => {
    const results = await retrieve(query, 5);
    return {
      results: results.map(({ source, text, score }) => ({
        source,
        text,
        score,
      })),
    };
  },
});

这里没有直接使用封装好的向量查询工具，而是把自己的 retrieve() 包装成 Mastra Tool。这样未来要添加权限过滤、去重或 Reranking，可以只修改检索服务。

八、使用 DeepSeek 创建 Knowledge Agent

创建 src/mastra/agents/knowledge.agent.ts：

import { Agent } from "@mastra/core/agent";
import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
import { knowledgeSearchTool } from "../tools/knowledge-search.tool";

const deepseek = createOpenAICompatible({
  name: "deepseek",
  baseURL: "https://api.deepseek.com/v1",
  apiKey: process.env.DEEPSEEK_API_KEY!,
});

export const knowledgeAgent = new Agent({
  id: "knowledge-agent",
  name: "Knowledge Agent",
  instructions: `
你是一个基于私人知识库的中文技术问答助手。
回答知识库相关问题时先调用 knowledgeSearchTool 检索。
根据检索到的材料回答，避免编造项目细节。
如果资料不足，请明确说明。
尽可能注明文档来源；不要编造来源链接。
直接回答问题，不要输出“我现在去搜索”等过程说明。
`,
  model: deepseek.chatModel("deepseek-chat"),
  tools: { knowledgeSearchTool },
});

这里采用的是 Agent 自主调用 Tool 的方式。即使在指令中要求先检索，也不意味着从程序逻辑上强制每次执行检索。若未来要求严格的“先检索再回答”，应该把 retrieve() 放到 Agent 调用之前，由应用程序控制检索流程。

创建 src/scripts/chat.ts：

import "dotenv/config";
import { knowledgeAgent } from "../mastra/agents/knowledge.agent";

const question =
  process.argv.slice(2).join(" ") ||
  "Health Master 为什么从 MD5 迁移到 Argon2id？";

const response = await knowledgeAgent.generate(question);
console.log(response.text);

运行：

npm run chat -- "Health Master 为什么从 MD5 迁移到 Argon2id？"

在实际测试中，Agent 能找到文章中与 PR #333 相关的内容，并回答出具体的工程决策，例如：

引入 pkg/pwd 统一密码哈希与验证逻辑。
对旧 MD5 密码采用要求用户重置密码，而不是登录成功后静默升级哈希的方案。
使用 errcode.ErrLegacyPasswordResetRequired 表示旧密码需要重置。
将 users.password 字段扩展为 character varying(255)，容纳 Argon2id 的 PHC 字符串。

这些都是知识库文章里的项目细节，比仅仅回答“Argon2id 比 MD5 更安全”更能证明检索增强的实际价值。

九、调试 Agent 的 Tool Calls

初次调试时，我尝试这样打印工具调用：

console.log(call.toolName);
console.log(call.input);

结果全是 undefined。这并不是 Tool 执行失败，而是读取错了返回对象的字段路径。

我随后直接使用 Node.js 的 inspect() 打印原始结构：

import { inspect } from "node:util";

for (const [index, step] of response.steps.entries()) {
  console.log(`\n========== STEP ${index + 1} ==========`);
  console.log("Tool Calls:", inspect(step.toolCalls, { depth: 6, colors: true }));
  console.log("Tool Results:", inspect(step.toolResults, { depth: 6, colors: true }));
  console.log("Step Text:", step.text);
}

这次安装版本中，Tool Call 的实际结构是：

{
  type: "tool-call",
  payload: {
    toolCallId: "call_...",
    toolName: "knowledgeSearchTool",
    args: { query: "Health Master MD5 迁移 Argon2id 原因" }
  }
}

Tool Result 的关键结构则是：

{
  type: "tool-result",
  payload: {
    toolName: "knowledgeSearchTool",
    result: {
      results: [
        { source: "https://...", text: "...", score: 0.7279 }
      ]
    }
  }
}

因此要读取：

call.payload.toolName;
call.payload.args;
result.payload.result.results;

实际运行结果

这次测试有两个 Step：

Step 1：两次工具调用

knowledgeSearchTool
  query: Health Master MD5 迁移 Argon2id 原因

knowledgeSearchTool
  query: 密码哈希算法选择 Argon2id

两次调用分别返回 5 个相关 Chunk。第一组最高分约为 0.728，第二组最高分约为 0.731。返回片段来自同一篇 Markdown 文章，包含迁移原因、密码验证逻辑、Memory-hard、Salt 和旧 MD5 密码处理等内容。

Step 2：生成答案

这一步不再调用工具，而是直接输出中文回答，并在末尾列出原始 Markdown URL。最终 response.text 与 Step 2 的回答内容一致。

前一次测试曾出现英文开头：

I'll search the knowledge base for information about this migration.

说明模型有时会把检索前的说明文本也放进响应中。后续运行中这段英文没有再出现，但这属于模型行为，不应该把提示词约束视为绝对保证。

关于来源引用

当前实现将 source 存在向量 metadata 中，模型会尝试在回答中引用来源。不过，最终答案中的引用文字仍然由模型生成。更严格的做法是由应用程序直接汇总工具返回的 source 和 Chunk ID，再与答案一起展示，避免出现模型编造或错误拼接来源的情况。

十、package.json 脚本汇总

可以添加以下脚本：

{
  "scripts": {
    "db:init": "tsx src/scripts/init-vector-db.ts",
    "ingest": "tsx src/scripts/ingest.ts",
    "search": "tsx src/scripts/search.ts",
    "chat": "tsx src/scripts/chat.ts"
  }
}

建议按以下顺序验证：

# 1. 确保 PostgreSQL 已启动，并创建 pgvector 扩展

# 2. 首次创建向量表
npm run db:init

# 3. 导入一篇 Markdown
npm run ingest -- ./articles/golang-argon2id-password-hashing.md \
  https://raw.githubusercontent.com/damingerdai/damingerdai.github.io/refs/heads/master/source/_posts/back-end/golang-argon2id-password-hashing.md

# 4. 先验证纯向量检索
npm run search -- "为什么 Argon2id 需要 Salt？"

# 5. 最后测试 Agent
npm run chat -- "Health Master 为什么从 MD5 迁移到 Argon2id？"

十一、MVP 已经完成什么，还缺什么？

目前已经验证的能力：

能力	状态
Markdown 文本切分	已实现
SiliconFlow BGE-M3 Embedding	已验证，1024 维
PostgreSQL/pgvector 向量存储	已验证
问题向量化与相似度检索	已验证
DeepSeek + Mastra Agent	已验证
Agent 多次调用检索 Tool	已在日志中确认
返回文章来源	初步实现
幂等导入 / 增量更新	未实现
Markdown 语义切分	未实现
Reranking / 检索去重	未实现
引用真实性的程序化校验	未实现
自动化 RAG Evaluation	未实现
Web UI / 流式聊天	未实现

下一步我打算优先做 Document Lifecycle（文档生命周期管理）：

为每篇文档及 Chunk 生成稳定 ID。
使用内容 Hash 判断文档是否变化，避免无意义的重复 Embedding。
文档更新时替换旧 Chunk；文档删除时清理对应向量。
改进 Markdown 切分，保留标题层级和代码块上下文。
再考虑 Reranking、质量评估和 Web UI。

十二、总结

这次实现最大的收获，不是“成功调用了一个大模型 API”，而是把 RAG 拆成了几个能够独立验证的环节：

Embedding 失败时，先检查 API URL、环境变量和最小 SDK 调用。
向量入库失败时，检查数据库扩展和 Mastra 对应的索引/表是否存在。
Agent 回答不准确时，先看检索结果，再看 Tool Calls，最后才分析提示词。
不要把相似度分数误认为正确率，也不要把模型输出的引用当成天然可信的来源证明。

对于个人技术博客知识库而言，这已经是一个可运行的 RAG MVP。下一阶段的重点不应急着堆叠功能，而是让文档导入、更新、检索和引用变得稳定、可重复、可观察。

参考资料

源代码

mastra-rag-app

AI 流式传输工程指南：模型吐出半截 JSON，前端如何边收边渲染？

猫头_ — Sun, 18 Oct 2026 11:22:47 GMT

本文是通俗实战版。保留全部工程精华、性能实测对比与跨框架（原生 JS / Vue 3 / React）开箱即用代码，8 分钟即可读完并直接落地到项目中。

一、为什么不能等 JSON 吐完再解析？

做普通 AI 聊天时，模型吐出的是纯文本或 Markdown，前端收到一个字就往屏幕上追加一个字（打字机效果）。

但现在越来越多的 AI 功能要求模型直接返回 JSON 结构化数据，让前端渲染成交互组件：

典型业务场景	模型输出的 JSON 结构	边收边渲染带来的体验提升
商品 / 知识卡片	`{ title, summary, price, tags }`	标题先跳出来，摘要逐字填充，不用盯着空白卡片干等
流式数据表格	`{ columns, rows: [...] }`	表格一行接一行“长”出来，长表格首屏等待时间缩短 80%
智能表单填充	`{ name, phone, address }`	表单项逐个自动回填，用户能实时看到 AI 正在填哪一格
Agent 工具调用	`tool_calls[].function.arguments`	OpenAI 兼容接口的流式工具参数天生就是半截 JSON 碎片，边收边解析才能显示“正在搜索：xxx”

模型生成一段完整的 JSON 往往需要几百个 Token、耗时 5~15 秒。如果傻等到最后一个 } 才调用 JSON.parse()，用户就得对着白屏干等十几秒——流式传输也就失去了意义。

要在模型只吐出“半截 JSON”时就实时渲染 UI，全链路其实只需要闯过三关：

graph LR
    A(&#34;第一关：协议剥壳<br/>从 SSE 信封取出 content 碎片&#34;) --> B(&#34;第二关：结构补全<br/>把 {'title':'降噪耳 补成合法 JSON&#34;)
    B --> C(&#34;第三关：平滑渲染<br/>按帧节流 + 默认值兜底 + 防闪烁&#34;)

    %% 针对掘金渲染器的样式微调
    style A fill:#e8f4fc,stroke:#1890ff,stroke-width:1px,color:#333
    style B fill:#fcf8e3,stroke:#faad14,stroke-width:1px,color:#333
    style C fill:#ebfbf2,stroke:#52c41a,stroke-width:1px,color:#333

二、先避坑：流式接口里有“两层 JSON”，别混为一谈

很多刚接触流式开发的同学会问：“我在写 SSE 流式接收时，不是已经用 buffer 处理过半截 JSON 了吗？”

其实在流式结构化输出里，存在外层信封和内层业务数据两层完全不同的 JSON：

外层（SSE 信封 JSON，一行一条，几毫秒就完整）：
data: {"choices":[{"delta":{"content":"{\"title\":"}}]}
data: {"choices":[{"delta":{"content":"\"降噪耳"}}]}
data: {"choices":[{"delta":{"content":"机\"}"}}]}

内层（把所有 delta.content 拼起来的业务 JSON，要好几秒才完整）：
第 1 刻：{"title":
第 2 刻：{"title":"降噪耳
第 3 刻：{"title":"降噪耳机"}

这两层的处理策略截然不同：

维度	外层：SSE 传输信封	内层：业务内容 JSON（本文主角）
长什么样	`{"choices":[{"delta":{"content":"降噪"}}]}`	所有 `content` 累加拼出的 `{"title":"降噪耳机",...}`
多久能凑齐	收到换行符 `\n` 就齐了（通常几毫秒）	模型吐完最后一个 Token 才齐（几秒到几十秒）
处理方式	用 `buffer` 按 `\n` 切行，凑齐一行再 `JSON.parse`	不能干等：必须把半截字符串临时“补全”成合法 JSON

浏览器原生的 JSON.parse 是个“全有或全无”的严格解析器——只要末尾少一个引号或括号，它立刻抛 SyntaxError，绝不会把前面已经解析好的字段还给你：

JSON.parse('{"title":"AI 周');             // ❌ SyntaxError: Unterminated string
JSON.parse('{"title":"AI 周报","items":['); // ❌ SyntaxError: Unexpected end of JSON input
JSON.parse('{"ok":tr');                    // ❌ SyntaxError: Unexpected end of JSON input

所以在整个生成过程中，除了最后一刻，直接调 JSON.parse 100% 会失败。我们需要一个**“尽力而为”的补全器**。

三、核心原理：半截 JSON 是怎么被“补”出来的？

生产环境里我们直接调用成熟小库（如 partial-json），但花 2 分钟看懂它的原理，你就能明白为什么有些字段会提前出现、有些字段会被暂时丢弃。

模型可能在任意字符处停下，补全器的工作其实就是**“去烂尾、补引号、补括号”**三步：

断在哪里	当前收到的半截文本	补全策略	补全后的合法 JSON
字符串值中间	`{"title":"AI 周`	补右引号 `"` + 补右括号 `}`	`{"title":"AI 周"}`（文字可逐字展示）
转义符中间	`{"text":"中\u4e`	削掉未完成的 `\u4e`，再补 `"}`	`{"text":"中"}`（防非法转义报错）
半截 Key	`{"title":"周报","ite`	Key 没写完毫无意义，回退删掉 `"ite`，再补 `}`	`{"title":"周报"}`
有 Key 没 Value	`{"title":"周报","items":`	回退删掉悬空的 `"items":`，再补 `}`	`{"title":"周报"}`
尾逗号	`[{"name":"A"},`	删掉末尾悬空的 `,`，再补 `]`	`[{"name":"A"}]`
半截布尔 / null	`{"ok":tr`	`t` 开头只可能是 `true`，顺手补全再补 `}`	`{"ok":true}`

计算机是怎么知道最后该补 ]} 还是 }]} 的？答案是一个简单的栈（Stack）：

记引号状态：从头扫描字符，遇到未转义的 " 就切换“是否在字符串内”的状态；
记括号栈：在引号外部，每遇到 { 就往栈里记一个 }，遇到 [ 就记一个 ]；遇到闭合的 } 或 ] 就消掉栈顶那一个；
截断并补齐：需要渲染时，先把末尾悬空的逗号、冒号或半截 Key 削掉；如果停在字符串值中间就补一个 "；最后把栈里剩下的括号倒序拼到末尾。

下面这 35 行极简代码就能跑通核心流程（帮你吃透原理的演示版）：

function miniCompleteJson(partialStr) {
  let inString = false;
  let escaped = false;
  const closers = []; // 栈：记录还欠哪些闭合括号

  for (const ch of partialStr) {
    if (inString) {
      if (escaped) escaped = false;
      else if (ch === '\\') escaped = true;
      else if (ch === '"') inString = false;
      continue;
    }
    if (ch === '"') inString = true;
    else if (ch === '{') closers.push('}');
    else if (ch === '[') closers.push(']');
    else if (ch === '}' || ch === ']') closers.pop();
  }

  let fixed = partialStr;
  // 1. 如果停在字符串内部：先去掉末尾可能悬空的反斜杠，再补双引号
  if (inString) {
    if (escaped) fixed = fixed.slice(0, -1);
    fixed += '"';
  }
  // 2. 削掉末尾悬空的逗号、冒号或刚写了一半的 key（如 ,"pri 或 ,"price":）
  fixed = fixed.replace(/,\s*"[^"]*"?\s*:?\s*$/, '').replace(/[,:\s]+$/, '');
  // 3. 倒序补齐所有未闭合的括号
  return fixed + closers.reverse().join('');
}

// 实测效果：
console.log(miniCompleteJson('{"title":"降噪耳机","tags":["蓝牙",'));
// => '{"title":"降噪耳机","tags":["蓝牙"]}'
console.log(miniCompleteJson('{"title":"降噪耳机","pri'));
// => '{"title":"降噪耳机"}'

四、前端落地三板斧：不报错、不跳动、不卡顿

能解析出半截对象只是第一步。如果直接把半成品丢给页面渲染，往往会遇到组件白屏报错、数字疯狂闪烁、长 JSON 越滚越卡三大问题。

第一板斧：给半成品套一层“默认值视图函数”（防报错）

流式传输刚开始时，解析出来的可能是 {}，下一秒是 { title: "降噪" }，数组 specs 还是 undefined。如果在模板里直接写 data.specs.map(...)，第一帧就会报错崩溃。

标准做法：写一个纯函数 toCardView，把“任何字段都可能缺”的半成品，转换成结构固定的安全对象：

export function toCardView(partial) {
  return {
    title: typeof partial?.title === 'string' ? partial.title : '',
    summary: typeof partial?.summary === 'string' ? partial.summary : '',
    // ⚠️ 注意：价格还没生成出来时一定要给 null（显示骨架屏），别给 0（否则用户会以为商品免费！）
    price: typeof partial?.price === 'number' ? partial.price : null,
    tags: Array.isArray(partial?.tags)
      ? partial.tags.filter((t) => typeof t === 'string')
      : [],
    specs: Array.isArray(partial?.specs)
      ? partial.specs.map((s) => ({ label: s?.label ?? '', value: s?.value ?? '' }))
      : [],
  };
}

第二板斧：管住“不稳定”的数字与高度（防闪烁跳动）

流式卡片最影响观感的就是画面乱跳，记住这四条实战经验：

拒绝半截数字闪烁（8 → 89 → 899）：字符串逐字出现很自然，但价格如果从 ¥8 变成 ¥89 再变成 ¥899，看起来就像 Bug。用 partial-json 解析时，只要排除 Allow.NUM（只允许字符串、对象、数组处于半截状态），解析器就会等数字后面的逗号或括号出现、数字彻底定型后才返回该字段！
判断字段是否已写完（加打字光标）：既然 JSON 是按顺序生成的，只要后面的字段已经出现（或者流已结束），前面的字段就一定写完了。我们可以据此给“正在生成的最后一个字段”加上闪烁光标样式。
固定高度 + 骨架屏占位：标题、价格区域提前用 CSS 占好最小高度，值为空或 null 时显示灰色骨架条（Skeleton），避免文字填入瞬间把整张卡片撑高一截。
Schema 字段顺序设计（先短后长）：大模型会严格按照你在 Prompt 或 Structured Outputs Schema 中定义的字段顺序输出。把 title、price 等短字段放在最前面，把长文本 summary 放在后面，卡片骨架 1 秒内就能立住。

在控制台观察一帧一帧的真实产出，数据是这样“长”出来的：

帧  1: { title: "降噪耳",       summary: "",                 price: null, specs: [] }
帧  3: { title: "降噪耳机 X1",  summary: "主动降噪，续航 30", price: null, specs: [] }
帧  5: { title: "降噪耳机 X1",  summary: "主动降噪，续航 30 小时", price: 899, specs: [] }
帧  9: { title: "降噪耳机 X1",  summary: "...",              price: 899,  specs: [{ label: "重量", value: "250g" }] }

第三板斧：节流更新，别让解析退化成 $O(n^2)$ （防卡顿）

大模型吐 Token 极快，10 毫秒内可能连发四五个 chunk。如果每收到一个 chunk 就立刻全量补全 + JSON.parse + 刷新 UI，当 JSON 达到几十 KB（例如长表格）时，页面会越来越卡。

在一份 107 KB（1500 行表格，约 2.7 万个 chunk）的真实基准测试中，不同策略的耗时差距高达 60 倍：

解析与渲染策略	2.7 万个 chunk 总耗时	为什么差这么多？
A. 每个 chunk 都重头扫描 + `JSON.parse`	约 32.7 秒	每次都把前面攒下的几万字重扫一遍，工作量呈平方级（ $O(n^2)$ ）爆炸
B. 增量扫描，但每个 chunk 都 `JSON.parse`	约 8.3 秒	扫描快了，但 27000 次 `JSON.parse` 依然吃满 CPU
C. 按帧/定时节流（每 50 个 chunk 解析一次）	约 0.53 秒	解析次数从 27000 次降到 500 多次，丝滑不掉帧

所以在前端落地上，千万不要在 reader.read() 循环里直接调 parse 和更新状态，而是加一道节流阀：

动画敏感型（普通卡片）：用 requestAnimationFrame 对齐屏幕刷新率（60Hz 下约 16ms 最多解析渲染一次）；
重组件 / 虚拟DOM框架（React / Vue 大表格）：如果觉得每秒 60 次组件重渲染还是太频，可以直接用 50ms ~ 80ms 的定时器节流（每秒只更新 12~20 次），人眼看起来依然非常连贯，而框架重渲染开销直接再降 70%。

五、开箱即用：纯 JS 核心 + 原生 / Vue / React 接入

为了让代码在任何项目里都能直接复制使用，我们把逻辑拆成两层：

底层核心函数（纯 JavaScript，零框架依赖）：负责流读取、剥离代码围栏、节流解析与结束校验，通过 onUpdate 回调吐出数据；
UI 接入层：无论你用原生 DOM、Vue 3 还是 React，都只需要不到 10 行代码就能接上。

5.1 核心流式解析函数（纯 JS，框架无关）

先安装轻量库：npm i partial-json

// partialStream.js —— 纯 JS 实现，可在原生、Vue、React、小程序中通用
import { parse, Allow } from 'partial-json';
import { toCardView } from './cardView.js';

/**
 * 找到 JSON 正文起点：兼容模型在开头输出 "好的，结果如下：" 或 ```json 围栏
 */
function extractJsonBody(raw) {
  const fenceMatch = raw.match(/```(?:json)?\s*\n?([\s\S]*)/i);
  if (fenceMatch) {
    return fenceMatch[1].replace(/\s*```\s*$/, '');
  }
  const firstBracket = raw.search(/[{[]/);
  return firstBracket === -1 ? '' : raw.slice(firstBracket);
}

/**
 * 消费流式 JSON 文本，按指定间隔节流产出安全的视图对象
 * @param {ReadableStream} body - fetch 响应的 response.body
 * @param {(state: { data: any, done: boolean }) => void} onUpdate - 状态回调
 * @param {number} throttleMs - 节流间隔（默认 40ms，约 25fps，兼顾流畅度与框架性能）
 */
export async function consumePartialJson(body, onUpdate, throttleMs = 40) {
  const reader = body.pipeThrough(new TextDecoderStream()).getReader();
  let rawText = '';
  let timerId = null;

  const flush = () => {
    timerId = null;
    const jsonCandidate = extractJsonBody(rawText);
    if (!jsonCandidate.trim()) return;

    try {
      // 只允许字符串、对象、数组处于半截状态；排除 Allow.NUM 防止数字闪烁
      const partialObj = parse(jsonCandidate, Allow.STR | Allow.OBJ | Allow.ARR);
      onUpdate({ data: toCardView(partialObj), done: false });
    } catch {
      // 刚收到一两个字符尚无法解析时，静默跳过等下一拍
    }
  };

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    rawText += value; // 若后端是标准 SSE，这里改为提取出的 delta.content 即可
    if (timerId === null) {
      timerId = setTimeout(flush, throttleMs);
    }
  }

  // 流结束：清理定时器，用原生 JSON.parse 做最终完整性校验
  if (timerId !== null) clearTimeout(timerId);
  const finalJson = extractJsonBody(rawText).replace(/}\s*[^}]*$/, '}');
  const finalObj = JSON.parse(finalJson); // 若中途断流不完整，这里会如实抛错进入上层 catch
  onUpdate({ data: toCardView(finalObj), done: true });
}

💡 为什么这里默认用了 setTimeout(..., 40) 而不是固定死 requestAnimationFrame？ 在原生 DOM 里用 rAF（约 16ms 一次）很轻快；但在 React / Vue 等框架中，16ms 触发一次响应式更新意味着每秒要走 60 次组件重渲染（Diff）。设为 40ms ~ 50ms 节流（每秒更新 20~25 次），肉眼看打字机依然丝滑，同时能把 React / Vue 的渲染负担降低 60% 以上。

5.2 三端接入示例（任选其一）

有了上面的 consumePartialJson，在任何技术栈里接入都只需要几行：

写法 A：原生 JS（直接操作 DOM）

const titleEl = document.querySelector('#card-title');
const summaryEl = document.querySelector('#card-summary');
const priceEl = document.querySelector('#card-price');

async function start() {
  const res = await fetch('/api/product-card', { method: 'POST' });
  await consumePartialJson(res.body, ({ data, done }) => {
    titleEl.textContent = data.title || '标题生成中...';
    summaryEl.textContent = data.summary;
    priceEl.textContent = data.price !== null ? `¥${data.price}` : '价格计算中...';
  });
}

写法 B：Vue 3（Composition API）

<script setup>
import { ref } from 'vue';
import { consumePartialJson } from './partialStream';
import { toCardView } from './cardView';

const card = ref(toCardView({}));
const isDone = ref(false);

async function generate() {
  const res = await fetch('/api/product-card', { method: 'POST' });
  await consumePartialJson(res.body, ({ data, done }) => {
    card.value = data;
    isDone.value = done;
  });
}
</script>

写法 C：React（Hooks）

import { useState } from 'react';
import { consumePartialJson } from './partialStream';
import { toCardView } from './cardView';

export function ProductCard() {
  const [state, setState] = useState({ data: toCardView({}), done: false });

  async function generate() {
    const res = await fetch('/api/product-card', { method: 'POST' });
    await consumePartialJson(res.body, setState);
  }
  // 下面正常渲染 state.data 即可
}

六、工具怎么选？一张表对号入座

不用纠结重复造轮子，按你的项目情况直接选：

你的场景	推荐方案	特点与适用理由
常规前端项目（自建 SSE / Fetch 流）	`partial-json`	零依赖、体积小，支持通过 `Allow` 位掩码关掉半截数字防闪烁。
模型不听话，爱输出单引号、注释、尾逗号	`jsonrepair`	容错能力极强，不仅能补全截断，还能把各种不规范的“坏 JSON”修成标准格式。
Next.js / React 全栈项目（已用 AI SDK）	Vercel AI SDK (`streamText` + `Output.object`)	前后端一体，配合客户端 `useObject` Hook 自动搞定补全、节流和 Schema 校验。
超大 JSON、几千行的流式列表	`@streamparser/json`	事件驱动的真正 $O(n)$ 解析器，每当数组里有一个元素完整闭合就回调一次，完全不重扫前文（代价是拿不到半截字符串）。

七、上线前必看的 3 条生产安全底线

半截 JSON 补全出来的对象“长得很像完整数据”，这在生产环境里最容易埋雷。上线前务必检查这三件事：

半截数据“只做展示，绝不提交”：网络中断、用户点击“停止生成”、或者模型触发最大长度截断（finish_reason: "length"）时，补全器依然会给你一个合法的 JSON 对象，但里面少了一半字段。写数据库、提交表单、触发下一步业务接口，必须以 done === true 且通过原生 JSON.parse（或 zod.safeParse）完整校验为唯一标准。
Agent 工具调用参数在完整前绝不执行：假设模型正在生成删除目录的工具调用，半截参数 {"path": "/data 补全后是合法的 {"path": "/data"}，但模型原本要写的是 /data/tmp/cache。流式阶段解析出的参数只能用于 UI 预览（例如显示“正在准备清理目录：/data...”），真正执行工具必须等流结束并校验通过。
警惕结构化字段里的恶意链接与 XSS：结构化不等于安全。如果卡片包含 link、avatar 等 URL 字段，渲染到 <a href={link}> 前必须校验协议是否为 https://，防止模型被诱导输出 javascript:alert(1) 伪协议；普通文本字段坚持走文本插值（如 textContent、{{ title }}、{title}），不要直接塞进 innerHTML / v-html。

element-plus表格使用:filter-method过滤导致出现无数据

我的div丢了肿么办 — Sun, 18 Oct 2026 09:58:11 GMT

前端表格进行过滤

背景介绍：我们表格的过滤是后端做的
但是不知道为啥，在进行迁移的时候
表格过滤写上了 @filter-change="handleFilterChange"变成了前端过滤，
导致服务端返回数据后，表格显示的却是：暂无数据解决办法：去掉 @filter-change="handleFilterChange" 不要变成前端过滤

<template>
  <div>
    <el-button type="primary" @click="setTableData">设置数据</el-button>
     <el-table
          ref="normalTable"
          :data="tableData"  
          style="width: 100%" 
          max-height="440px"
          @filter-change="handleFilterChange"
        >
          <el-table-column
            v-for="(column, index) in tableDataOption"
            :key="index"
            :prop="column.prop"
            :label="column.label"
            :min-width="120"
            :column-key="column.prop"
            :filters="column.filter ? column.filterOptions : null"
            :filter-multiple=" false"
            :filter-method="column.filter ? filterHandler : null"
          />
        </el-table>
  </div>
</template>
<script setup lang="ts">
import { ref } from 'vue';


let tableData = ref<any[]>([])
const tableDataOption = ref<any[]>([])
// 过滤方法
const filterHandler = (value: any, row: any, column: any) => {
  const property = column.property
  // 过滤方法，返回 true 表示保留该行，否则不保留
  return  row[property] === value
}
function setTableData(){
  setTimeout(()=>{
      tableDataOption.value= [ 
        { "prop": "bucket",
         "label": "桶名称", 
         "filter": true, 
          filterOptions: [
            { "text": "A1", "value": "A1" },
            { "text": "B1", "value": "002" }
          ] 
       }, 
        { 
          "prop": "projectID", 
          "label": "企业项目", 
          "filter": false, 
          filterOptions: [ ] 
        } 
      ]
    tableData.value= [
      {
        "bucket": "A1",
        "childInfo": [],
        "projectID": "default",
        "id": "001",
        "name": "bucket-1e1f",
      },
      {
        "bucket": "B1",
        "childInfo": [],
        "projectID": "default",
        "id": "bucket-272e",
        "name": "bucket-272e",
      },
    ]
  },1300)
}
function handleFilterChange(newFilters: Record<string, string[]>) {
  console.log(newFilters)
}

</script>

<style scoped>

</style>

filters 的介绍

filters 表格列中数据过滤的选项,数组格式。
数组中的元素需要有 text 和 value 属性。
filter-method 是一个方法，它用于决定某些数据是否显示，会传入三个参数：value, row 和 column。
该方法返回 true 表示保留该行，否则不保留。

使用 filter-method 进行过滤需要注意的点

filter-method 进行过滤是纯前端完成的。
如果是后端进行过滤，就不要使用 filter-method了，会导致表格出现无数据的情况。
该方法返回 true 表示保留该行，否则不保留。

filter-change="handleFilterChange"

当表格的过滤条件发生变化的时候会触发该事件 filter-change
比如: 使用 filter-method 方法进行过滤后，就会触发这个方法。

设置过滤后，重新设置表格中的数据也会自动展示过滤后的数据

表格最初有10条数据，我们使用过滤filter-change后，展示了1条数据；
就算接口返回来8条数据，表格也只会展示1条数据（会自动过滤，只展示符合条件的数据）

向全世界售卖你的产品：做了一款教程引导插件

是江迪呀 — Sun, 18 Oct 2026 08:41:14 GMT

在AI时代我们需要做的是：将自己的能力、技能打包成一次制作多次售卖的商品，让全球都可以购买使用！

😵‍💫事情的起因是这样的，我看到同事在制作操作文档的时候非常耗时，基本的操作是：

graph TD
进入页面 --> 截图框选
截图框选 --> 页面信息脱敏
页面信息脱敏 --> 编辑步骤说明
编辑步骤说明 --> 保存使用word或者pdf发给对方

😵‍💫拿到操作文档的，操作起来更难受，需要在页面和文档之间反复切换。稍不留神看错了步骤，就要从头找好久才能接上步骤。

🤔我此时在想能不能把这个过程变得简单一些，能不能将教程搬到真实页面上进行引导指引，于是就有了roadbook插件的诞生。

使用 roadbook 只需要三步：录制、分享、跟练

一、录制

就按照日常操作一遍。

二、分享

点击分享，对敏感信息脱敏。

三、跟练

打开链接，输入密码，选择跟练方式：链接：tryroadbook.com/p/h9jpmggt 密码：g7Ri-diLB-aNXc-RGai

没有装插件可以悬浮跟练：

结尾

我都做了哪些内容：

首先试探需求，看看有没有人搜索这样的需求，有就做，没有就说明没有需求，那就果断放弃。
开通谷歌开发者身份，这个得有一个可以国际支付的卡。
AI写代码，完成基础功能，接入支付功能。
AI制作封面、宣传视频。
搜索优化、宣传。

感兴趣的可以去看看，给提提意见，有什么意见欢迎评论区讨论～

官网地址：tryroadbook.com/ 官网是全球可以购买使用的，也算是出海项目了.

高级篇：进阶多跳 RAG：子问题拆解 + 循环检索 + 智能规划，搞定复杂链式问题

YIAN — Sun, 18 Oct 2026 08:09:19 GMT

前言

单轮 RAG 只能回答「一跳就能查到答案」的问题，但现实中很多问题是链式的：需要先知道 A，才能查到 B，再根据 B 推出 C。直接把原始问题向量化检索，往往因为语义偏移命中不了正确答案。

本文是系列最终篇，我们把 RAG 升级到多跳推理版：

自动把复杂问题拆成有序子问题
按顺序逐个子问题检索，每步积累上下文
智能规划器判断是否信息足够，可提前终止
文档自动去重，避免重复内容干扰生成

一、多跳 RAG 完整架构

最终版的工作流是一个带循环的状态机：

START → route_question
     ├─ simple → direct_answer → END
     └─ complex → decompose_question → retrieve → plan_next_step
                                                     ├─ retrieve（继续循环）
                                                     └─ generate → END

核心新增四个能力：

decompose_question：把原始问题拆成有序的子问题链
循环检索：按顺序逐个检索子问题，每轮合并文档
plan_next_step：每轮检索后评估信息是否足够，决定继续还是生成
mergeUnique：多轮检索的文档自动去重，按相似度排序

二、状态扩展

为了支持循环和多跳，状态新增了多个控制字段：

表格

字段	作用
subQuestions	拆解后的子问题数组
nextSubIdx	当前检索到第几个子问题（指针）
currentQuery	当前正在检索的子问题
retrievalCount	已检索轮次
maxRetrievals	最大检索轮数，防止无限循环
plannedNext	下一步动作：retrieve /generate

三、核心模块逐段解析

1. 子问题拆解节点

用 LLM 把复杂问题拆成有序子问题，要求每条都能独立检索，不能有指代。

const DecomposeSchema = z.object({
  sub_questions: z.array(z.string()).min(1).max(8),
  reason: z.string()
});

const decomposeQuestionNode = async (state) => {
  console.log("---DECOMPOSE_QUESTION---");
  const decomposer = model.withStructuredOutput(DecomposeSchema);
  
  const out = await decomposer.invoke(`
    你是《天龙八部》多跳问答的【子问题拆解器】。
    用户原始问题：${state.question}
    
    任务：将问题拆成有序子问题列表 sub_questions，用于依次向量检索。
    要求：
    1. 链式推理、多层关系的问题，必须拆成多条；单跳即可答的也可只输出1条。
    2. 每条子问题必须是可独立检索的完整中文问句，禁止使用「他/她/此人」等指代。
    3. 顺序必须符合推理链：先搞清前置事实，再查后续结论。
    4. 不要把整句原题原样复制成唯一一条；不要拆成过碎的关键词列表。
    请输出 sub_questions 与简短 reason。
  `);

  const subQuestions = out.sub_questions.map(s => s.trim()).filter(Boolean);
  console.log(`拆解${subQuestions.length}条子问题(${out.reason})`);
  subQuestions.forEach((q, i) => console.log(`[${i+1}] ${q}`));

  return {
    subQuestions,
    nextSubIdx: 0,
    currentQuery: subQuestions[0]
  }
}

2. 文档去重合并

多轮检索会命中重复文档，用 Map 按 id 去重，保留相似度更高的版本，最终按分数降序。

const mergeUnique = (existingDocs, newDocs) => {
  const map = new Map();
  for (const d of [...existingDocs, ...newDocs]) {
    const key = String(d.id);
    const prev = map.get(key);
    if (!prev || Number(d.score) > Number(prev.score)) {
      map.set(key, d);
    }
  }
  return Array.from(map.values()).sort((a, b) => Number(b.score) - Number(a.score));
}

3. 循环检索节点

根据 nextSubIdx 指针取出当前子问题，执行检索，合并文档，指针后移。

const retrieveNode = async (state) => {
  const subs = state.subQuestions ?? [];
  const idx = state.nextSubIdx ?? 0;
  const q = subs[idx]?.trim();
  const round = state.retrievalCount + 1;

  console.log(`----第${round}轮，子问题 ${idx+1}/${subs.length}---`);
  console.log(`---查询 ${q} ---`);

  const newDocs = await retrieveRelevantContent(q, state.k);
  const merged = mergeUnique(state.documents ?? [], newDocs);

  console.log(`本轮命中${newDocs.length}条，累计去重后${merged.length}条`);
  return {
    documents: merged,
    retrievalCount: round,
    nextSubIdx: idx + 1,
    currentQuery: q
  }
}

4. 下一步规划节点

这是多跳 RAG 的「大脑」：综合已检索文档、剩余子问题、轮数上限，判断下一步动作。

const NextStepSchema = z.object({
  nextAction: z.enum(["retrieve", "generate"]),
  reason: z.string()
});

const planNextStepNode = async (state) => {
  console.log("---PLAN_NEXT_STEP---");
  const subs = state.subQuestions ?? [];
  const nextIdx = state.nextSubIdx ?? 0;
  const remaining = subs.length - nextIdx;

  // 拼接子问题状态和已检索文档摘要
  const subList = subs.map((s, i) => `${i + 1}.${s} 
    ${i < nextIdx ? "已检索": i === nextIdx ? "(下一轮将检索)" : "未检索"}`).join("\n");
  
  const docStr = state.documents.length === 0 
    ? "(尚无检索结果)"
    : state.documents.slice(0, 6).map((d, i) => 
      `[${i + 1}] score=${Number(d.score).toFixed(4)} 第${d.chapter_num}章：${d.content.slice(0, 200)}`
    ).join("\n\n");

  const prompt = `你是多跳 RAG 规划器。
  用户原始问题： ${state.question}
  子问题序列：
  ${subList}
  
  已检索轮次：${state.retrievalCount}; 剩余未检索子问题条数：${remaining}
  最大检索轮数上限：${state.maxRetrievals}
  已召回文档摘要:
  ${docStr}

  请判断下一步：
  1）已有足够依据回答原始问题 → nextAction=generate
  2) 仍缺关键事实、且还有未检索子问题、且未超轮数上限 → nextAction=retrieve
  硬性规则：
  - 剩余子问题为0，必须 nextAction=generate
  - 已达最大轮数，必须 nextAction=generate
  `;

  const planModel = model.withStructuredOutput(NextStepSchema);
  const { nextAction, reason } = await planModel.invoke(prompt);
  
  // 硬性规则兜底，防止模型判断失误
  let finalNext = nextAction;
  if (state.retrievalCount >= state.maxRetrievals) finalNext = "generate";
  if (remaining <= 0) finalNext = "generate";

  console.log(`[决策] plannedNext=${finalNext} (模型建议=${nextAction})(${reason})`);
  return { plannedNext: finalNext };
}

5. 条件循环与完整图

规划节点通过条件边形成循环，满足条件就继续检索，否则退出循环去生成答案。

const afterPlan = (state) => state.plannedNext === "retrieve" ? "retrieve" : "generate";
const afterRoute = (state) => state.strategy === 'simple' ? "direct_answer" : "decompose_question";

const graph = new StateGraph(GraphState)
  .addNode("route_question", routeQuestionNode)
  .addNode("direct_answer", directAnswerNode)
  .addNode("decompose_question", decomposeQuestionNode)
  .addNode("retrieve", retrieveNode)
  .addNode("plan_next_step", planNextStepNode)
  .addNode("generate", generateNode)
  .addEdge(START, "route_question")
  // 路由分支
  .addConditionalEdges("route_question", afterRoute, {
    direct_answer: "direct_answer",
    decompose_question: "decompose_question"
  })
  .addEdge("decompose_question", "retrieve")
  .addEdge("retrieve", "plan_next_step")
  // 循环分支：规划 → 继续检索 或 生成
  .addConditionalEdges("plan_next_step", afterPlan, {
    retrieve: "retrieve",
    generate: "generate"
  })
  .addEdge("direct_answer", END)
  .addEdge("generate", END)
  .compile();

四、多跳问题运行演示

问题：《天龙八部》中四大恶人排行第二的是谁？此人之子在身世揭晓前，其生父在武林中的公开身份是什么？

运行流程：

___ROUTE-QUESTION___
路由策略：complex 需要多步推理，涉及人物关系和身份细节

---DECOMPOSE_QUESTION---
拆解3条子问题(需要先确定第二恶人是谁，再找其子，最后查生父身份)
[1] 《天龙八部》中四大恶人排行第二的人物是谁？
[2] 四大恶人排行第二之人的儿子是谁？
[3] 该人物之子的生父在武林中的公开身份是什么？

----第1轮，子问题 1/3---
---查询 《天龙八部》中四大恶人排行第二的人物是谁？ ---
本轮命中5条，累计去重后5条

---PLAN_NEXT_STEP---
[决策] plannedNext=retrieve (模型建议=retrieve)(已确定第二恶人是叶二娘，但还需其子与生父信息)

----第2轮，子问题 2/3---
---查询 四大恶人排行第二之人的儿子是谁？ ---
本轮命中5条，累计去重后8条

---PLAN_NEXT_STEP---
[决策] plannedNext=retrieve (模型建议=retrieve)(已知其子是虚竹，还需生父公开身份)

----第3轮，子问题 3/3---
---查询 虚竹的生父在武林中的公开身份是什么？ ---
本轮命中5条，累计去重后12条

---PLAN_NEXT_STEP---
[决策] plannedNext=generate (模型建议=generate)(所有关键信息已齐全)

[AI回答（流式）]
四大恶人排行第二的是「无恶不作」叶二娘。她的儿子是虚竹，在身世揭晓之前，虚竹的生父玄慈方丈在武林中的公开身份是少林寺方丈，同时也是当年雁门关惨案的带头大哥...

五、整套 RAG 演进总结

我们用四篇文章，从 0 到 1 完成了完整的演进路线：

表格

版本	核心能力	适用场景
向量入库版	EPUB 切片 + Milvus 建库	知识库构建
基础单轮 RAG	检索 → 生成	简单单跳问题
智能路由版	问题分类 + 双分支分流	混合问题场景，优化资源
多跳推理版	子问题拆解 + 循环检索 + 智能规划	复杂链式、多跳推理问题

这套架构可以直接复用到任何垂直领域知识库，只需要换一下数据集和 Prompt 就能落地。

进阶篇：RAG 优化第一步：给你的问答系统加上智能路由，实现双分支分流

YIAN — Sun, 18 Oct 2026 08:08:30 GMT

言

基础版 RAG 有个很明显的浪费：不管什么问题都先走一遍向量检索。其实很多简单问题、常识问题，大模型本身就能准确回答，根本不需要查知识库，白白浪费了检索的时间和算力。

本文是系列第三篇，我们给 RAG 加上一个「问题路由器」，让系统自动判断问题类型：

简单问题：直接让 LLM 回答，不走检索
复杂问题：走 RAG 检索流程，基于知识库回答

一、架构升级：从直线到分支

升级后的工作流变成了带条件分支的结构：

START → route_question
     ├─ simple → direct_answer → END
     └─ complex → retrieve → rag_generate → END

核心新增两个部分：

route_question 路由节点：用 LLM + 结构化输出判断问题类型
direct_answer 节点：直接调用 LLM 回答简单问题

二、结构化输出的作用

路由节点需要稳定输出「simple/complex」两种结果，不能让 LLM 自由发挥文字。这里用 Zod 定义输出 Schema，配合 LLM 的结构化输出能力，保证每次都返回符合格式的结果。

三、完整代码逐段解析

1. 新增依赖与状态扩展

引入 Zod 用于结构化输出校验，状态中新增 strategy 和 routeReason 字段，记录路由结果和理由。

import { z } from 'zod';

// 状态扩展
const GraphState = Annotation.Root({
  question: Annotation,
  k: Annotation,
  strategy: Annotation,     // 路由策略：simple / complex
  routeReason: Annotation,  // 路由理由
  documents: Annotation,
  generation: Annotation
})

2. 定义路由 Schema

用 Zod 定义输出结构，strategy 是枚举值，只能是 simple 或 complex，reason 是判断理由。

const RouteSchema = z.object({
  strategy: z.enum(["simple", "complex"]),
  reason: z.string()
});

3. 路由节点实现

给 LLM 加上结构化输出约束，传入路由规则和用户问题，返回判断结果并更新状态。

const routeQuestionNode = async (state) => {
  console.log('___ROUTE-QUESTION___');
  
  // 给模型加上结构化输出约束
  const router = model.withStructuredOutput(RouteSchema);
  const route = await router.invoke(`
  你是问答路由器，请判断用户问题是否需要外部检索。
  规则：
  - simple: 常识问答、简短定义、无需特定小说细节即可回答。
  - complex: 需要《天龙八部》具体情节、人物关系、章节事实、原文细节或证据支持。
  
  用户问题： ${state.question}
  `);
  
  console.log(`路由策略：${route.strategy} ${route.reason}`);
  return {
    strategy: route.strategy,
    routeReason: route.reason
  }
}

4. 直接回答节点

对于 simple 类型的问题，直接调用 LLM 回答，不经过检索流程。

const directAnswerNode = async (state) => {
  console.log('----DIRECT_ANSWER----');
  process.stdout.write("\n [AI 回答（流式）] \n");
  
  let generation = "";
  const stream = await model.stream(`你是一个中文回答助手,
  请简洁回答问题。
  问题：${state.question}
  `);

  for await (const chunk of stream) {
    const text = typeof chunk.content === 'string' ? chunk.content : "";
    if (!text) continue;
    generation += text;
    process.stdout.write(text);
  }
  process.stdout.write("\n");

  return {
    documents: [],
    generation
  }
}

5. 条件边与图构建

用 addConditionalEdges 添加条件边，根据路由结果决定走哪个分支。

// 条件判断函数：根据 state.strategy 返回下一个节点名
const decideNext = (state) => (state.strategy === 'simple' ? "direct_answer" : "retrieve");

const graph = new StateGraph(GraphState)
  .addNode("route_question", routeQuestionNode)
  .addNode("direct_answer", directAnswerNode)
  .addNode("retrieve", retrieveNode)
  .addNode("rag_generate", generateNode)
  .addEdge(START, "route_question")
  // 条件分支：路由节点 → 直接回答 或 检索
  .addConditionalEdges("route_question", decideNext, {
    direct_answer: "direct_answer",
    retrieve: "retrieve"
  })
  .addEdge("retrieve", "rag_generate")
  .addEdge("direct_answer", END)
  .addEdge("rag_generate", END)
  .compile();

6. 主函数调用

和基础版类似，只是初始状态多了路由相关字段。

async function main () {
  const question = "阿朱是怎么死的？";
  const k = 5;

  // Milvus 连接代码省略，与基础版一致...

  const result = await graph.invoke({
    question,
    k: Number.isFinite(k)?k:5,
    strategy: "",
    routeReason: "",
    documents: [],
    generation: ""
  });

  console.log(JSON.stringify(result));
}

main().then(err => console.error(err));

四、两种场景的运行效果

场景 1：简单常识问题

___ROUTE-QUESTION___
路由策略：simple 这是基础常识问题，无需检索小说内容

 [AI 回答（流式）] 
阿朱是金庸小说《天龙八部》中的人物。

场景 2：小说细节问题

___ROUTE-QUESTION___
路由策略：complex 需要小说具体情节细节，必须检索原文

----检索中----
命中 5 条相关片段...

[AI回答（流式）]
阿朱是被萧峰一掌打死的...

五、升级收益与下一步

本次升级带来的提升

节省资源：常识问题跳过检索，减少向量数据库查询次数
响应更快：简单问题少了一次检索耗时，延迟大幅降低
架构清晰：路由逻辑独立，后续可以继续扩展更多分支

仍然存在的问题

对于多跳链式问题，单轮检索还是不够。比如：

《天龙八部》中四大恶人排行第二的是谁？此人之子在身世揭晓前，其生父在武林中的公开身份是什么？

这种问题需要先查「四大恶人第二是谁」，再查「他的儿子是谁」，再查「儿子的生父公开身份」，单轮检索根本答不准。

下一篇，我们就进入终极版：子问题拆解 + 多轮循环检索 + 智能规划器，实现真正的多跳推理 RAG。

入门篇：LangGraph 入门实战：从零搭建最简单的 RAG 问答系统

YIAN — Sun, 18 Oct 2026 08:07:38 GMT

前言

有了向量知识库，下一步就是搭建真正的 RAG 问答系统。很多人一开始会写一堆零散的函数调用，但流程一复杂就难以维护。LangGraph 提供了基于状态机的工作流编排方式，让 RAG 的每一步都清晰可控。

本文是系列第二篇，我们基于上一篇建好的《天龙八部》Milvus 向量库，用 LangGraph 搭建最基础的 RAG 流程：提问 → 向量检索 → 大模型生成答案。虽然简单，但这是所有复杂 RAG 的雏形。

一、基础 RAG 的核心流程

最简单的 RAG 只有两个核心节点，形成一条直线工作流：

START → retrieve（检索） → generate（生成） → END

retrieve 节点：接收用户问题，去 Milvus 向量库检索最相似的 Top-K 文本片段
generate 节点：把检索到的片段作为上下文，交给 LLM 结合问题生成答案

二、状态设计

LangGraph 的核心是「状态」，所有节点共享同一份状态数据，节点执行后更新状态，传递给下一个节点。

我们定义的状态包含四个字段：

question：用户原始问题
k：检索返回的片段数量
documents：检索到的文档列表
generation：最终生成的答案

const GraphState = Annotation.Root({
  question: Annotation,   // 用户问题
  k: Annotation,          // 检索 Top-K
  documents: Annotation,  // 检索到的文档
  generation: Annotation  // 生成的回答
});

三、完整代码逐段解析

1. 依赖与初始化

导入 LangGraph、Milvus 向量存储、大模型等依赖，初始化客户端。

import "dotenv/config";
import { ChatOpenAI, OpenAIEmbeddings } from "@langchain/openai";
import { Annotation, END, START, StateGraph } from '@langchain/langgraph';
import { Milvus } from '@langchain/community/vectorstores/milvus';

const COLLECTION_NAME = "ebook_collection";
const TOP_K = 5;

// 初始化大模型
const model = new ChatOpenAI({
  model: process.env.MODEL_NAME,
  temperature: 0, // 设为 0，保证回答稳定准确
  configuration: { baseURL: process.env.OPENAI_BASE_URL },
  apiKey: process.env.OPENAI_API_KEY
});

// 初始化向量模型（与入库时保持一致）
const embeddings = new OpenAIEmbeddings({
  model: "text-embedding-v3",
  dimensions: 1024,
  configuration: { baseURL: process.env.OPENAI_BASE_URL },
  apiKey: process.env.OPENAI_API_KEY
});

let vectorStore;

2. 检索节点

封装 Milvus 相似度搜索，返回带分数、章节信息的文档列表。

async function retrieveRelevantContent(question, k = TOP_K) {
  try {
    const docsWithScores = await vectorStore.similaritySearchWithScore(question, k);
    return docsWithScores.map(([doc, score]) => ({
      score,
      content: doc.pageContent,
      id: doc.metadata?.id ?? "unknown",
      book_id: doc.metadata?.book_id ?? "未知",
      chapter_num: doc.metadata?.chapter_num ?? "未知",
      index: doc.metadata?.index ?? "未知"
    }));
  } catch(error) {
    console.error("检索内容时出错：", error.message);
    return [];
  }
}

const retrieveNode = async (state) => {
  const documents = await retrieveRelevantContent(state.question, state.k);
  return { documents }; // 更新状态中的 documents
}

3. 生成节点

把检索到的文档拼接成上下文，构造 Prompt 交给 LLM 流式生成答案。

const generateNode = async (state) => {
  // 拼接上下文，标注片段序号和章节
  const context = state.documents
    .map((item, i) => `[片段 ${i+1}]
    章节: 第 ${item.chapter_num}章
    内容：${item.content}
    `).join("\n\n----------\n\n");

  const prompt = `
  你是一个专业的《天龙八部》小说助手。基于小说内容回答问题，用准确，详细的语言。
  请根据以下《天龙八部》小说片段内容回答问题：
  ${context}
  用户问题：${state.question}
  回答要求：
  1. 如果片段中有相关信息，请结合小说内容给出详细、准确的回答
  2. 可以综合多个片段的内容，提供完整的答案
  3. 如果片段中没有相关信息，请如实告知用户
  4. 回答要准确，符合小说的情节和人物设定
  5. 可以引用原文内容来支持你的回答
  AI 助手的回答：
  `;

  process.stdout.write("\n[AI回答（流式）]\n");
  let generation = "";
  const stream = await model.stream(prompt);
  
  // 流式输出，逐字打印
  for await (const chunk of stream) {
    const text = typeof chunk.content === "string" ? chunk.content : "";
    if (!text) continue;
    generation += text;
    process.stdout.write(text);
  }
  process.stdout.write("\n");

  return { generation };
}

4. 构建并编译图

把节点加入 StateGraph，定义边的连接关系，最后编译成可执行的图。

const graph = new StateGraph(GraphState)
  .addNode("retrieve", retrieveNode)
  .addNode("generate", generateNode)
  .addEdge(START, "retrieve")    // 起点 → 检索
  .addEdge("retrieve", "generate") // 检索 → 生成
  .addEdge("generate", END)      // 生成 → 结束
  .compile();

5. 主函数运行

连接 Milvus 向量库，传入问题调用图，输出检索结果和最终回答。

async function main() {
  const question = "阿朱的结局是什么？";
  const kArg = 5;

  console.log("连接到 Milvus...");
  // 连接已有的向量集合
  vectorStore = await Milvus.fromExistingCollection(embeddings, {
    collectionName: COLLECTION_NAME, 
    url: "localhost:19530",
    textField: "content",
    primaryField: "id",
    vectorField: "vector",
    indexCreateOptions: {
      metric_type: "COSINE",
      index_type: "HNSW",
      param: { M: 16, efConstruction: 200 },
      search_params: { ef: 64 }
    }
  });

  vectorStore.indexSearchParams = {
    metric_type: "COSINE",
    params: JSON.stringify({ef:64})
  }
  console.log('已连接');

  // 加载集合
  try {
    await vectorStore.client.loadCollection({collection_name: COLLECTION_NAME})
    console.log(`集合 ${COLLECTION_NAME} 已加载`);
  } catch(error) {
    if (!error.message.includes("already loaded")) throw error;
    console.log(`集合已处于加载状态`);
  }

  console.log("=".repeat(80));
  console.log(`问题：${question}`);
  console.log("=".repeat(80));

  // 调用图执行
  const result = await graph.invoke({
    question,
    k: Number.isFinite(kArg) ? kArg : TOP_K,
    documents: [],
    generation: ""
  });

  // 打印检索到的片段
  console.log("\n检索相关内容：");
  if (result.documents.length === 0) {
    console.log("未找到相关内容");
  } else {
    result.documents.forEach((item, i) => {
      console.log(`\n【片段 ${i+1} 相似度:】${item.score.toFixed(4)}`);
      console.log(`书籍: ${item.book_id}`);
      console.log(`章节: ${item.chapter_num}章`);
      console.log(`内容: ${item.content.substring(0, 200)}...`);
    })
  }
}

main().catch(err => console.error);

四、运行效果

执行后会先输出检索到的 5 个最相关片段，然后流式输出最终答案：

================================================================================
问题：阿朱的结局是什么？
================================================================================

检索相关内容：

【片段 1 相似度:】0.8921
书籍: 1
章节: 23章
内容: 萧峰一掌击在阿朱胸口，阿朱身子直飞出去...

...（其余片段省略）

[AI回答（流式）]
阿朱最终死于萧峰的掌下。在小镜湖青石桥上，阿朱为了化解父亲段正淳与萧峰的仇怨，易容成段正淳的模样赴约，被悲愤中的萧峰一掌击中，最终死在萧峰怀中...

五、基础 RAG 的局限

这版 RAG 虽然能跑通，但有明显的不足：

所有问题都走检索：哪怕是「1+1 等于几」这种常识，也要浪费一次向量检索
单轮检索能力有限：遇到「段誉遇到的神仙姐姐画像是谁的弟子」这种多跳问题，一次检索很难命中答案
没有流程控制：无法根据中间结果动态调整策略

下一篇，我们就来解决第一个问题：给 RAG 加上智能路由，让常识问题直接回答，复杂问题才走检索。

前置篇：手把手用 Milvus + LangChain 搭建小说向量知识库，《天龙八部》EPUB 一键入库

YIAN — Sun, 18 Oct 2026 08:06:54 GMT

本系列共四篇，从零到一完成从向量知识库搭建到多跳推理 RAG 的完整演进：

前置篇：Milvus 向量知识库搭建，《天龙八部》EPUB 一键入库
入门篇：LangGraph 基础单轮 RAG，检索→生成最简流程
进阶篇：智能路由分支 RAG，问题自动分流，常识直答、复杂检索
高级篇：多跳推理 RAG，子问题拆解 + 循环检索 + 智能规划

前置篇：手把手用 Milvus + LangChain 搭建小说向量知识库，《天龙八部》EPUB 一键入库

前言

做 RAG（检索增强生成）的第一步，永远是搭建自己的向量知识库。很多人入门时卡在「怎么把自己的文档变成向量存进去」，尤其是结构化的电子书，直接扔进去不仅检索不准，还浪费算力。

本文就以经典小说《天龙八部》EPUB 为例，从零到一带你完成：

EPUB 电子书按章节加载与智能切片
文本向量化生成 Embedding
Milvus 向量数据库集合设计与索引创建
流式批量插入，边处理边入库

全程基于 Node.js + LangChain + Milvus 原生 SDK，代码可直接运行，跑完就能拥有一个可用于 RAG 问答的小说向量库。

一、技术栈与前置准备

核心依赖

@zilliz/milvus2-sdk-node：Milvus 官方 Node.js SDK，用于集合管理与数据插入
@langchain/openai：调用 Embedding 模型生成向量
@langchain/community/document_loaders/fs/epub：EPUB 文件加载器，自动按章节拆分
@langchain/textsplitters：递归字符文本拆分器，控制切片长度
dotenv：环境变量管理

本地环境

本地启动 Milvus 服务（默认端口 19530，推荐 Docker 一键启动）
可用的 OpenAI 格式 Embedding 接口
准备好《天龙八部》EPUB 格式电子书

二、核心设计思路

1. 为什么要做文本切片？

大段整章文本直接向量化会导致：

向量语义过于宽泛，检索命中率低
单次检索上下文过长，干扰生成答案
超出 Embedding 模型最大输入长度

我们采用按章节拆分 + 二次固定长度切片的策略，每片 500 字符，保留 50 字符重叠，保证上下文连贯性。

2. Milvus 集合字段设计

表格

字段名	类型	作用
id	VarChar(100)	主键，由「书籍 ID_章节号_切片序号」组成，全局唯一
book_id	VarChar(100)	书籍 ID，支持多书籍混合入库
book_name	VarChar(200)	书籍名称
chapter_num	Int32	章节号，便于定位原文
index	Int32	章节内切片序号
content	VarChar(10000)	切片原文内容，用于生成答案
vector	FloatVector(1024)	文本向量，用于相似度检索

3. 索引选择

采用 IVF_FLAT 索引 + 余弦相似度（COSINE） ，把向量聚类分桶，检索时只比对最相关的桶，在保证准确率的同时大幅提升检索速度。

三、完整代码逐段解析

1. 依赖导入与常量定义

首先导入所需模块，定义全局常量，方便后续统一调整参数。

import "dotenv/config";
import { parse } from 'node:path';
import { 
  MilvusClient, 
  DataType,
  MetricType,
  IndexType 
} from '@zilliz/milvus2-sdk-node';
import { OpenAIEmbeddings } from "@langchain/openai";
import { EPubLoader } from "@langchain/community/document_loaders/fs/epub";
import { RecursiveCharacterTextSplitter } from "@langchain/textsplitters";

// 全局配置
const COLLECTION_NAME = 'ebook_collection';
const VECTOR_DIM = 1024;          // 向量维度，与 Embedding 模型对应
const CHUNK_SIZE = 500;           // 单切片字符数
const EPUB_FILE = './天龙八部.epub';
const BOOK_NAME = parse(EPUB_FILE).name; // 从文件名提取书名

2. 初始化 Embedding 与 Milvus 客户端

Embedding 模型负责把文本转成 1024 维向量；Milvus 客户端连接本地向量数据库。

// 初始化向量模型
const embeddings = new OpenAIEmbeddings({
  apiKey: process.env.OPENAI_API_KEY,
  model: process.env.EMBEDDINGS_MODEL_NAME,
  configuration: {
    baseURL: process.env.OPENAI_BASE_URL
  },
  dimensions: VECTOR_DIM
});

// 初始化 Milvus 客户端
const client = new MilvusClient({
  address: 'localhost:19530'
});

// 封装向量生成方法
async function getEmbedding(text) {
  const result = await embeddings.embedQuery(text);
  return result;
}

3. 创建集合与索引

ensureCollection 函数负责幂等性创建集合：不存在则创建，存在则跳过，最后保证集合处于加载状态。

async function ensureCollection(bookId) {
  try {
    // 检查集合是否已存在
    const hasCollection = await client.hasCollection({
      collection_name: COLLECTION_NAME
    });

    if (!hasCollection.value) {
      console.log('创建集合...');
      // 创建集合，定义所有字段
      await client.createCollection({
        collection_name: COLLECTION_NAME,
        fields: [
          { name: 'id', data_type: DataType.VarChar, max_length: 100, is_primary_key: true },
          { name: 'book_id', data_type: DataType.VarChar, max_length: 100 },
          { name: 'book_name', data_type: DataType.VarChar, max_length: 200 },
          { name: 'chapter_num', data_type: DataType.Int32 },
          { name: 'index', data_type: DataType.Int32 },
          { name: 'content', data_type: DataType.VarChar, max_length: 10000 },
          { name: 'vector', data_type: DataType.FloatVector, dim: VECTOR_DIM }
        ]
      });
      console.log('✓ 集合创建成功');

      // 为向量字段创建索引
      console.log('创建索引...');
      await client.createIndex({
        collection_name: COLLECTION_NAME,
        field_name: 'vector',
        index_type: IndexType.IVF_FLAT,
        metric_type: MetricType.COSINE,
        params: { nlist: 1024 } // 聚类分桶数量
      });
      console.log('✓ 索引创建成功');
    } 
    
    // 加载集合到内存，保证检索性能
    try {
      await client.loadCollection({ collection_name: COLLECTION_NAME });
      console.log('✓ 集合已加载');
    } catch (error) {
      console.log('✓ 集合已处于加载状态');
    }
  } catch (error) {
    console.error('创建集合时出错:', error.message);
    throw error;
  }
}

4. 批量插入数据

insertChunksBatch 接收一个章节的所有切片，并行生成向量，组装成 Milvus 要求的数据格式，批量插入。

async function insertChunksBatch(chunks, bookId, chapterNum) {
  try {
    if (chunks.length === 0) return 0;

    // 并行生成每个切片的向量
    const insertData = await Promise.all(
      chunks.map(async (chunk, chunkIndex) => {
        const vector = await getEmbedding(chunk);
        return {
          id: `${bookId}_${chapterNum}_${chunkIndex}`,
          book_id: bookId,
          book_name: BOOK_NAME,
          chapter_num: chapterNum,
          index: chunkIndex,
          content: chunk,
          vector: vector
        };
      })
    );

    // 批量插入
    const insertResult = await client.insert({
      collection_name: COLLECTION_NAME,
      data: insertData
    });

    return Number(insertResult.insert_cnt) || 0;
  } catch (error) {
    console.error(`插入章节 ${chapterNum} 的数据时出错:`, error.message);
    throw error;
  }
}

5. EPUB 流式处理

核心处理逻辑：加载 EPUB → 按章节拆分 → 逐章二次切片 → 边处理边插入。采用流式处理的好处是不需要把整本书都加载到内存，处理大文件更稳定。

async function loadAndProcessEPubStreaming(bookId) {
  try {
    console.log(`\n开始加载 EPUB 文件: ${EPUB_FILE}`);
    
    // 加载 EPUB，自动按章节拆分
    const loader = new EPubLoader(EPUB_FILE, { splitChapters: true });
    const documents = await loader.load();
    console.log(`✓ 加载完成，共 ${documents.length} 个章节\n`);

    // 初始化文本拆分器
    const textSplitter = new RecursiveCharacterTextSplitter({
      chunkSize: CHUNK_SIZE,
      chunkOverlap: 50, // 相邻切片重叠 50 字符，避免语义断裂
    });

    let totalInserted = 0;

    // 逐章处理
    for (let chapterIndex = 0; chapterIndex < documents.length; chapterIndex++) {
      const chapter = documents[chapterIndex];
      const chapterContent = chapter.pageContent;
      
      console.log(`处理第 ${chapterIndex + 1}/${documents.length} 章...`);
      
      // 二次切片
      const chunks = await textSplitter.splitText(chapterContent);
      console.log(`  拆分为 ${chunks.length} 个片段`);
      
      if (chunks.length === 0) {
        console.log(`  跳过空章节\n`);
        continue;
      }

      console.log(`  生成向量并插入中...`);
      const insertedCount = await insertChunksBatch(chunks, bookId, chapterIndex + 1);
      totalInserted += insertedCount;
      
      console.log(`  ✓ 已插入 ${insertedCount} 条记录（累计: ${totalInserted}）\n`);
    }

    console.log(`\n总共插入 ${totalInserted} 条记录\n`);
    return totalInserted;
  } catch (error) {
    console.error('加载 EPUB 文件时出错:', error.message);
    throw error;
  }
}

6. 主函数入口

串联整个流程：连接 Milvus → 确保集合存在 → 处理 EPUB 并入库。

async function main() {
  try {
    console.log('='.repeat(80));
    console.log('电子书向量知识库构建工具');
    console.log('='.repeat(80));

    console.log('\n连接 Milvus...');
    await client.connectPromise;
    console.log('✓ 已连接\n');

    const bookId = 1;
    await ensureCollection(bookId);
    await loadAndProcessEPubStreaming(bookId);

    console.log('='.repeat(80));
    console.log('处理完成！向量知识库已就绪');
    console.log('='.repeat(80));
  } catch (error) {
    console.error('\n错误:', error.message);
    console.error(error.stack);
    process.exit(1);
  }
}

main();

四、运行效果

执行脚本后，控制台会输出完整的处理进度：

================================================================================
电子书向量知识库构建工具
================================================================================

连接 Milvus...
✓ 已连接

创建集合...
✓ 集合创建成功
创建索引...
✓ 索引创建成功
✓ 集合已加载

开始加载 EPUB 文件: ./天龙八部.epub
✓ 加载完成，共 50 个章节

处理第 1/50 章...
  拆分为 12 个片段
  生成向量并插入中...
  ✓ 已插入 12 条记录（累计: 12）

...（中间章节省略）

总共插入 1286 条记录

================================================================================
处理完成！向量知识库已就绪
================================================================================

五、总结与预告

至此，我们已经把《天龙八部》整本书变成了 1000+ 条带向量的文本片段，存入了 Milvus 向量库。这是所有 RAG 应用的地基，接下来的问答系统都将基于这个知识库运行。

下一篇，我们将基于这个向量库，用 LangGraph 搭建最简单的单轮 RAG 问答系统，实现「提问 → 向量检索 → LLM 生成答案」的完整流程。

React 任务轮询，为什么不能只写一个 setInterval？

VimorphTech — Sat, 17 Oct 2026 15:33:10 GMT

假设任务页面每秒查询一次进度，而某次请求要两秒多才返回。这时继续按固定节奏发请求，同一个任务就可能出现多次查询同时在途。再切到另一个任务，旧请求的返回还可能更新页面。

第六篇讨论后台任务如何等待和重试。这一篇看浏览器一侧：查询什么时候发起，什么时候结束，页面离开后谁还可以提交结果。

Vimorph 的视频翻译、音色设计页面都有轮询调用。本文从当前共享函数的边界出发，提供独立的 React + TypeScript 示例，补上取消和旧结果保护；示例使用本地替身，不调用业务接口，也不代表产品页面已经具备下面的全部保护。

固定间隔不会等待异步回调

setInterval 会按自己的节奏调用回调。把回调写成 async，并不会让定时器等它返回的 Promise 完成后再计时。对耗时不稳定的查询，可以选择“本轮结束，再等一个间隔”的调度方式。MDN 的说明也讨论了耗时超过间隔的情况。

这样得到的是请求间的休息时间，不是严格每秒一次。假设查询花 2.5 秒，正常间隔设为 1 秒，下一次大约在这一轮开始 3.5 秒后发起；这些数字只解释调度关系，不是接口性能数据。

轮询还需要明确结束条件：任务已完成，不再查询；临时查询失败，适当延后；页面不再关注这个任务，停止本地轮询。最后一种情况不需要把服务器任务也标成失败。

共享函数的能力与页面接入

当前 frontend/lib/polling.ts 中的 startPolling 已经在 await tick() 之后安排下一轮，并用局部 inFlight 防止同一实例重叠。tick 返回 false 时停止；抛错时进入退避分支。

这里的“同一实例”很关键。React Effect 清理旧实例后，可以建立新实例；两者没有共享的请求锁。现有 stop() 清理调度与可见性监听，不会取消已经执行的 tick，也不会拦截 tick 内部的 setState。

错误能否到达调度器同样取决于接入方式。当前部分视频翻译回调内部 catch 后正常返回，外层就收不到拒绝，不能据此触发错误退避。本文示例让查询错误继续抛出，由轮询器统一安排下一次查询。

请求结束后再安排下一次

本例把轮询器缩到一个实例、一条调用链。首次通过零延时定时器启动，之后只在当前 tick 结算后建立下一次定时器，不再提供手动并行执行入口。

操作	职责
清除定时器	撤销尚未开始的下一轮
AbortController.abort()	通知配合 AbortSignal 的请求停止
返回后检查 signal	阻止失效实例继续更新页面

下面是完整的 src/poller.ts：

export type PollingOptions = {
  intervalMs: number;
  maxIntervalMs: number;
  // true: 继续查询；false: 已到终态，不再查询。
  tick: (signal: AbortSignal) => Promise<boolean>;
  onError: (error: unknown, nextDelayMs: number) => void | Promise<void>;
};

export function startPolling(options: PollingOptions): { stop: () => void } {
  const { intervalMs, maxIntervalMs, tick, onError } = options;
  for (const value of [intervalMs, maxIntervalMs]) {
    if (!Number.isSafeInteger(value) || value <= 0 || value > 2_147_483_647) {
      throw new RangeError('轮询间隔必须是有效的正整数毫秒数');
    }
  }
  if (maxIntervalMs < intervalMs) {
    throw new RangeError('最大退避间隔不能小于正常查询间隔');
  }

  const controller = new AbortController();
  let stopped = false;
  let timer: ReturnType<typeof setTimeout> | undefined;
  let delayMs = intervalMs;

  function stop() {
    if (stopped) return;
    stopped = true;
    if (timer !== undefined) clearTimeout(timer);
    timer = undefined;
    controller.abort();
  }

  async function run() {
    timer = undefined;
    if (stopped) return;
    let keepPolling: boolean;
    try {
      keepPolling = await tick(controller.signal);
    } catch (error) {
      // 只依据本实例是否停止，不凭错误名猜测取消。
      if (stopped) return;
      delayMs = Math.min(delayMs * 2, maxIntervalMs);
      try {
        await onError(error, delayMs);
      } catch {
        // 错误展示回调自身失败时，停止实例，避免未处理的 Promise 拒绝。
        stop();
        return;
      }
      if (!stopped) timer = setTimeout(run, delayMs);
      return;
    }
    if (stopped) return;
    if (!keepPolling) {
      stop();
      return;
    }
    delayMs = intervalMs;
    timer = setTimeout(run, delayMs);
  }

  // 首轮也经过调度，effect 在执行前清理时可以撤销它。
  timer = setTimeout(run, 0);
  return { stop };
}

正常查询后恢复 intervalMs；查询失败后延迟翻倍，受 maxIntervalMs 限制。示例页面使用 1 秒基础间隔和 8 秒上限，因此连续故障的等待间隔为 2、4、8、8 秒。间隔参数要求处于有效范围的正安全整数；最大间隔不能小于基础间隔，两者相等时按固定间隔运行。

指数退避只控制重试频率，不会自动判断错误是否应该重试，也不会自动限制总重试次数。 如果错误持续发生，达到8秒上限后仍会继续尝试。调用方可以在 onError 中调用本次轮询返回的 stop()，处理已确认不可恢复的错误，或落实失败预算、任务截止时间。本例没有内置HTTP错误分类；429、503和网络异常是否重试，都应结合接口协议与当前业务判断。

stop 先设置停止标记，再清定时器和中止 signal。即使在途 Promise 后来才 resolve 或 reject，run 也会返回，不再安排下一轮。轮询器会等待 onError 通知结算；通知自身抛错或拒绝就停止实例，避免产生未处理的拒绝。在通知期间调用 stop，结算后也不会重新启动轮询。页面中的通知只是同步更新提示。

AbortSignal 只是取消通知。底层查询不配合时，已经开始的Promise可能继续执行；stop不能强制终止任意Promise。停止后不再调度，由轮询器负责；阻止旧结果更新页面，还需要下面的结果归属检查。

在 React 中限定结果的归属

调度器只能决定何时再运行，无法撤回 tick 已经做过的页面更新。所以检查必须放在 await query(signal) 后、setState 前。

每次 Effect 创建自己的轮询器，也就拥有独立的 signal。cleanup 调用 stop 后，这个旧 signal 会一直保持 aborted；新实例使用另一个 signal。即使查询实现忽略取消，旧回调仍会放弃结果。React 官方示例也在清理后忽略过时响应。

以下为完整的 src/App.tsx。它依赖上面的 poller 和下一节的 fake-api；TaskPanel 随 task.id 变化重新挂载，停止、重新查询和卸载按钮都在这份文件中。

import { useEffect, useState } from 'react';
import { createFakeQuery, type Mode, type Task, type TaskSnapshot } from './fake-api';
import { startPolling } from './poller';

const labels: Record<Mode, string> = {
  normal: '正常查询', slow: '慢请求（2.5 秒）',
  flaky: '前两次失败', stubborn: '忽略取消的慢请求',
};

function TaskPanel({ task }: { task: Task }) {
  const [snapshot, setSnapshot] = useState<TaskSnapshot | null>(null);
  const [message, setMessage] = useState('等待首次查询');
  const [requestCount, setRequestCount] = useState(0);
  const [stopped, setStopped] = useState(false);
  const [session, setSession] = useState(0);

  useEffect(() => {
    setMessage(stopped ? '已停止本地查询' : '等待首次查询');
    if (stopped) return;
    setSnapshot(null);
    setRequestCount(0);
    const query = createFakeQuery(task);
    const polling = startPolling({
      intervalMs: 1000,
      maxIntervalMs: 8000,
      tick: async (signal) => {
        setRequestCount((value) => value + 1);
        const result = await query(signal);
        // 请求可能没有响应 abort；旧实例仍必须放弃更新页面。
        if (signal.aborted) return false;
        setSnapshot(result);
        setMessage(result.status === 'succeeded' ? '任务完成，停止查询' : '处理中，等待下次查询');
        return result.status !== 'succeeded';
      },
      onError: (error, nextDelayMs) => {
        const detail = error instanceof Error ? error.message : '查询失败';
        setMessage(`${detail}；${nextDelayMs / 1000} 秒后重试`);
      },
    });
    return () => polling.stop();
  }, [task, stopped, session]);

  return (
    <section className="panel" aria-labelledby="task-heading">
      <div className="task-top"><h2 id="task-heading">任务 #{task.id}</h2><span>{labels[task.mode]}</span></div>
      <p className="state" role="status">{message}</p>
      <div className="progress"><div style={{ width: `${snapshot?.progress ?? 0}%` }} /></div>
      <div className="stats"><span>示意进度 <strong>{snapshot?.progress ?? 0}%</strong></span><span>当前实例请求数 <strong>{requestCount}</strong></span></div>
      <div className="actions">
        <button onClick={() => setStopped(true)} disabled={stopped}>停止查询</button>
        <button onClick={() => { setStopped(false); setSession((value) => value + 1); }}>重新查询</button>
      </div>
      <p className="hint">停止的是页面查询，不会取消服务器任务。重新查询会重置这个本地替身。</p>
    </section>
  );
}

export default function App() {
  const [mode, setMode] = useState<Mode>('normal');
  const [task, setTask] = useState<Task>({ id: 1, mode: 'normal' });
  const [visible, setVisible] = useState(true);
  return (
    <main>
      <p className="eyebrow">REACT + TYPESCRIPT · LOCAL DEMO</p>
      <h1>让任务轮询有始有终</h1>
      <p className="intro">请求结束后再调度，失败时退避，离开后放弃旧结果。</p>
      <div className="toolbar">
        <label>模拟场景<select value={mode} onChange={(event) => setMode(event.target.value as Mode)}>
          {Object.entries(labels).map(([value, text]) => <option key={value} value={value}>{text}</option>)}
        </select></label>
        <button className="primary" onClick={() => { setTask({ id: task.id + 1, mode }); setVisible(true); }}>切换到新任务</button>
        <button onClick={() => setVisible((value) => !value)}>{visible ? '卸载任务面板' : '挂载任务面板'}</button>
      </div>
      {visible ? <TaskPanel key={task.id} task={task} /> : <section className="panel"><p>任务面板已卸载，本地查询已停止。</p></section>}
      <aside><strong>可操作的检查</strong><p>选择慢请求，观察请求不会按每秒叠加。选择失败场景，观察 2 秒、4 秒退避。选择忽略取消的慢请求，启动后切换新任务，旧响应不会覆盖新任务。</p><p>所有状态来自受控本地替身；没有调用 Vimorph 业务接口。</p></aside>
    </main>
  );
}

这里同时用了组件 key 和 signal 检查：前者让不同任务有各自的面板状态，后者阻止旧异步回调提交结果。Effect 依赖的是保持稳定的 task 对象；每次切换才创建新对象，不能在每次渲染时临时构造同一个任务的对象，否则会反复重建轮询。

同一任务重新查询时，session 会递增，促使旧Effect先执行cleanup，再建立新实例。因此，已经在查询时再次点击“重新查询”，也会替换旧实例。停止、重查与任务切换都使用同一条清理路径；每个实例自己的signal用于隔离晚到结果。

取消只能减少支持取消的请求继续占用资源，不能代替结果归属检查。旧查询若不响应 abort，切换后仍可能与新实例的查询同时在途；本例保证旧实例不再提交结果，没有承诺跨实例的所有物理请求都互斥。

错误分支不靠错误名称猜测用户取消。实例停止后，晚到的成功和错误都因结果已失效而被丢弃；这并不表示某个普通网络错误被重新分类成了取消错误。

用受控查询复现晚到响应

为了让几种时序可以重复观察，createFakeQuery 提供正常、慢请求、前两次失败，以及故意忽略取消的慢请求四种模式。完整的 src/fake-api.ts 如下：

export type Mode = 'normal' | 'slow' | 'flaky' | 'stubborn';
export type Task = { id: number; mode: Mode };
export type TaskSnapshot = {
  taskId: number;
  status: 'processing' | 'succeeded';
  progress: number;
  requests: number;
};

async function wait(ms: number, signal: AbortSignal, ignoreAbort: boolean): Promise<void> {
  let timer: ReturnType<typeof setTimeout> | undefined;
  let onAbort: (() => void) | undefined;
  try {
    await new Promise<void>((resolve, reject) => {
      if (!ignoreAbort && signal.aborted) {
        reject(signal.reason);
        return;
      }
      timer = setTimeout(resolve, ms);
      onAbort = () => reject(signal.reason);
      if (!ignoreAbort) {
        signal.addEventListener('abort', onAbort, { once: true });
        if (signal.aborted) onAbort();
      }
    });
  } finally {
    if (timer !== undefined) clearTimeout(timer);
    if (onAbort) signal.removeEventListener('abort', onAbort);
  }
}

// 受控本地替身：不访问服务器，不表示真实任务耗时或进度。
export function createFakeQuery(task: Task) {
  let requests = 0;
  return async (signal: AbortSignal): Promise<TaskSnapshot> => {
    requests += 1;
    const count = requests;
    const slow = task.mode === 'slow' || task.mode === 'stubborn';
    await wait(slow ? 2500 : 250, signal, task.mode === 'stubborn');
    if (task.mode === 'flaky' && count <= 2) {
      throw new Error('模拟查询失败；下次将按退避间隔重试');
    }
    const completed = task.mode === 'flaky' ? count - 2 : count;
    return {
      taskId: task.id,
      status: completed >= 3 ? 'succeeded' : 'processing',
      progress: Math.min(completed * 34, 100),
      requests: count,
    };
  };
}

配合 signal 的等待会在注册监听后再次检查 aborted，正常完成和取消都清理监听及计时器。忽略取消的模式则故意等到结果返回，用于检查页面端的保护，而不是假装所有第三方 API 都支持取消。

请求序号和进度由这个本地闭包生成。重新查询会新建替身、重置计数；它没有重新提交真实生成任务。状态 processing / succeeded 也是示例约定，实际接 HTTP 接口时应先校验响应结构，再按协议判断是否终态。

运行与观察

已有 React + TypeScript 项目可以按文中的 src 路径保存三个完整文件，并让入口渲染 App。完整交付工程还包含入口、样式、依赖锁文件与测试；本次使用 React 19.2.7、TypeScript 5.9.3、Vite 8.2.1。

本地交付包中的 examples/react-task-polling-demo.zip 解压后，根目录为 react-task-polling-demo。公开附件地址尚未提供，因此这里不放无法访问的下载链接。使用满足 package.json 中 engines 要求的 Node，在工程目录运行：

cd react-task-polling-demo
npm ci
npm test
npm run build
npm run dev

选择模拟场景后，点击“切换到新任务”应用它：

场景	观察内容
正常查询	三次成功响应后结束查询
慢请求	本轮结束后才开始计算下一次间隔
前两次失败	显示 2 秒、4 秒退避，后续正常查询恢复
忽略取消的慢请求	查询发出后切换任务或卸载，旧结果不再提交

停止按钮只结束当前页面的查询，后台任务是否取消必须走另一套业务接口。示例没有该接口。

验证范围与接入边界

此前已实际运行原共享函数的5项测试、教学工程的22项测试，以及2项独立边界检查，原始记录继续保留。本次保留核心实现，新增10项参数与长期pending边界测试，教学工程合计32项通过，0失败、0跳过，TypeScript检查与页面构建也通过。测试使用可控Promise、假定时器和受控触发，没有靠增加等待时间掩盖竞态。

教学测试覆盖慢请求不重叠、退避封顶与成功恢复、终态停止、首次执行前停止、在途取消、忽略取消的晚到结果及错误回调。原业务测试里页面隐藏用例使用 document stub，不是浏览器兼容性测试；也不能根据测试名就认定它验证了成功后的全部退避恢复。

此前的浏览器记录覆盖正常完成、停止与重新查询、故障恢复、任务切换和卸载；本次补查了在途停止后立即重查、快速切换任务、同任务连续重查以及在途卸载四组页面操作。界面检查只说明可见行为，不用它证明所有物理请求互斥或枚举内部定时器；相应停止调度行为由受控测试另行断言。

下面是保留的本地Fake API示例截图，进度来自受控替身，不是Vimorph正式工作台：

示例没有单次请求timeout，也没有任务级deadline：前者限制一次查询持续多久，后者限制整项任务可以等待多久。若查询一直pending，本实例不会再发下一条，但也不会自行判定超时；真实HTTP客户端需要配置请求超时，并把失败交给明确的重试或停止策略。异步onError若一直不结算，也会暂停在通知阶段。

页面隐藏自动暂停和最大失败次数没有内置。停止查询或请求超时，都不代表服务器或供应商后台任务已取消；取消后台任务需要另外的业务接口。

本轮运行环境为 Node 26.7.0。真实供应方、Vimorph 业务端到端、Safari、移动端和后台计时器节流未验证。开发入口启用了 StrictMode，但不把一次页面操作当成所有组件生命周期组合的证明。

让一次轮询有明确的结束方式

持续查询不需要持续制造请求。把下一轮放在本轮结算之后，再给实例设置明确的停止与结果提交规则，就能把请求频率和页面生命周期连接起来。

接入页面时，先看清三件事：查询错误是否还能传到调度器，清理是否通知了在途请求，晚到结果是否仍有资格更新当前任务。把这些约定写进调用处，比单独封装一个定时器更有用。

镜游小导：运行在 Rokid AR 眼镜上的景区实景讲解智能体

用户8895619548171 — Sat, 17 Oct 2026 13:24:39 GMT

一、项目简介

1.1 解决什么问题

传统景区讲解存在三个痛点：

低头成本高：手机/讲解器需要低头或手持，既危险又打断游览；
被动且嘈杂：跟团扩音器无法自主控制节奏，信息与大部队绑定；
交互太重：屏幕点按在走动中很别扭，AR 卡片一多就遮挡视线。

镜游小导的目标不是做「景区百科」，而是做一个安静、随时在身边的向导：只在用户看向某处、并点头确认时，才轻轻开口。

1.2 目标用户

自由行游客、博物馆/古迹爱好者；
带老人小孩、不便手持设备的家庭游客；
希望「看不打扰、听不费劲」的轻量交互人群。

1.3 一句话成果

戴上 Rokid 眼镜走进西湖或故宫，无需掏手机：停步看两秒，它轻声问一句；点点头，眼前景物上方浮出讲解卡片，耳边同步播讲；想深入了解就开口追问；走出景区，它自动休息。

二、场景与用户意图

2.1 触发场景

进园即值守：GPS 判定进入景区范围，智能体自动进入值守，不打扰；
视线停留触发：用户停下、注视某处景物约 2 秒，判定为「有意了解」；
主动唤起：任意时刻语音唤醒、按确认键（Enter/GlobalHook）、点头都可唤起；
离园休眠：连续若干次定位在景区外，自动收卡片、退出值守。

2.2 智能体如何理解与承接需求

核心是**「上下文 + 意图分流」**：

上下文：当前是否在景区（inPark）、当前景区（activePark）、当前点位（currentPoi）、当前模式（mode）；
意图分流：同一条语音「要不要讲」，在不同模式下含义不同——
- 在 ask 下 → 判断题（讲 / 不讲 / 没听清）；
- 在 qa/explain 下 → 追问内容或「停下/换一个」指令；
- 在 scan 下 → 全局指令（退出休息 / 附近讲讲）。

询问答复的判定就有明确的优先级（否定优先，避免「不好」被当成「好」）：

handleAskAnswer(text) {
  const positive = /(讲|要|好|行|可以|开始|嗯|介绍|听听|来吧|继续)/.test(text);
  const negative = /(不用|不要|算了|不讲|先不|不了|没事|走|逛|再说)/.test(text);
  if (positive && !negative) { this.confirmAsk(); return; }
  if (negative) { this.declineAsk('好的，那您先逛着，需要再叫我。'); return; }
  this.speakQuiet('嗯？要讲还是先走？'); // 没听清再问一次
}

三、方案设计

3.1 AIUI 智能体定义

项目以 Rokid AIUI 开放智能体形态交付：页面用 .ink 描述，运行在眼镜端智能体运行时，直接调用系统能力。AGENTS.md 里声明了智能体的身份、能力与技能：

身份：镜游小导 v1.0.0，景区 AR 实景讲解智能体；
权限（Capabilities）：geolocation、microphone、network、audio、accelerometer、gyroscope；
技能（Skills）：speech-recognition、speech-synthesis、scenic-explanation。

3.2 能力调用关系

用户意图	依赖能力	实现载体
判断是否在景区	定位	`navigator.geolocation`
视线停留锁定景物	陀螺仪/加速度计	`AbsoluteOrientationSensor`
语音确认/追问	麦克风	`SpeechRecognition`
讲解播报	扬声器	`speechSynthesis` / `wx.speech.playTTS`
生成讲解词/回答	网络 + 大模型	`LanguageModel`
景区外联网兜底	网络	OSM Overpass（`fetch`）

3.3 页面与卡片设计

HUD（常显）：模式 chip + 景区名 + 距离 + 聆听态，下一行常显定位坐标；
讲解卡片（Overlay）：点名称/副标题 + 最多 4 行正文 + 提示 + 实时识别文字；
Footer：状态文案 + 错误提示；
视觉约束：单色绿 CSS 变量、480×352 小屏适配、卡片轻量不压视线中心。

3.4 状态流转

        ┌───────── 走出景区 ─────────┐
        ▼                            │
     sleep ──进园──► scan ──视线停留/唤起──► ask
                      ▲                    │ 确认
                      │                    ▼
                      │◄──返回/离点── explain ──讲完──► qa
                      └────────返回键/离园────────────────┘

sleep 景区外；scan 值守；ask 轻声询问；explain 讲解中；qa 追问。
任意状态：返回键可逐级退出；离园统一回 sleep。

四、AIUI 实现

4.1 项目结构

境游小导/
├── AGENTS.md              # 智能体身份/能力/技能声明
├── app.json               # 页面注册 + 权限声明
├── app.js                 # 应用生命周期
├── package.json
├── pages/
│   └── index/
│       └── index.ink      # 唯一页面：状态机 + 交互 + 样式
├── lib/
│   ├── pois.js            # 重点景区素材 + 地理计算
│   ├── scenic-areas.js    # 全国 360 家 5A 名称库（生成产物）
│   └── geo-lookup.js      # 运行时 OSM 联网兜底
└── tools/
    ├── build-scenic-areas.mjs   # xlsx → scenic-areas.js
    └── data/5a-areas.xlsx       # 5A 经纬度源数据

4.2 配置：`app.json` 与 `package.json`

{
  "pages": ["pages/index/index"],
  "permissions": ["GEOLOCATION", "RECORD_AUDIO"],
  "window": { "navigationBarTitleText": "镜游小导" }
}

小坑：权限名必须大写（GEOLOCATION/RECORD_AUDIO），否则真机运行时会报 Geolocation permission 'GEOLOCATION' is required by the app manifest。

4.3 Ink 页面解剖

一个 .ink 文件三段式：

<script type="application/json" def>{ "navigationBarTitleText": "镜游小导" }</script>

<script setup>
import wx from 'wx';
import { findPark, nearestParkCenter, distanceMeters, bearingDegrees, nearestPoi } from '../../lib/pois.js';
import { lookupNearbyArea } from '../../lib/geo-lookup.js';
export default {
  data: { mode: 'sleep', inPark: false, overlayVisible: false, /* ... */ },
  onLoad() { /* 初始化 GPS/传感器/语音 */ },
  onVoiceWakeup() { /* 语音唤醒 */ },
  onHeadGesture(e) { /* 点头=确认，摇头=拒绝 */ },
  onKeyDown(e) { /* Enter/GlobalHook 主键 */ },
  /* ... 方法与状态机 ... */
};
</script>

<page>
  <view class="stage">
    <view class="hud">…模式 chip / 景区名 / 距离 / 聆听中…</view>
    <view class="overlay" ink:if="{{overlayVisible}}">…讲解卡片…</view>
    <view class="footer">…状态 / 错误…</view>
  </view>
</page>

<style>…单色绿主题、480×352 适配…</style>

<page> 用 ink:if / ink:for 做条件与列表渲染；setData({...}) 驱动视图更新。

4.4 定位：双通道 + 看门狗

不同宿主对定位能力支持不一，因此同时打开「持续订阅」和「单次取点」两条通道：

startGeoWatch() { /* watchPosition 持续订阅，出错时 clearWatch 并重试 */ }
pollGeoOnce()   { /* getCurrentPosition 单次取点，兼容仅支持单次定位的宿主 */ }
startGeoHealth() { // 看门狗：长时间收不到定位就补一次轮询
  this.geoHealthTimer = setInterval(() => {
    const limit = this.data.inPark ? GEO_INSIDE_SILENT_MS : GEO_OUTSIDE_SILENT_MS;
    if (now - this.lastFixAt >= limit && now - this.lastPollAt >= limit) this.pollGeoOnce();
  }, GEO_POLL_MS);
}

GPS_OPTIONS 中 maximumAge: 0 让宿主机不使用缓存旧坐标，模拟位置变化才能即时生效。

4.5 视线停留锁定

没有眼动 API，用头部姿态近似视线。四元数转 yaw/pitch，姿态稳定 2 秒即「停留锁定」：

handlePoseAngles(yaw, pitch) {
  if (this.data.mode !== 'scan' || !this.data.inPark) return this.resetDwell();
  const now = Date.now();
  if (this.anchorYaw === null) { this.anchorYaw = yaw; this.anchorPitch = pitch; this.stableSince = now; return; }
  if (angleDelta(yaw, this.anchorYaw) > DWELL_YAW_LIMIT || Math.abs(pitch - this.anchorPitch) > DWELL_PITCH_LIMIT) {
    this.anchorYaw = yaw; this.anchorPitch = pitch; this.stableSince = now; return;
  }
  if (this.stableSince && now - this.stableSince >= DWELL_MS) {
    this.onDwellLocked(((yaw % 360) + 360) % 360);
  }
}

锁定后，用「方位角差 + 距离」在讲解范围内选出最正对视线的点位：

pickPoiByGaze(heading) {
  for (const poi of this.activePois) {
    const d = distanceMeters(this.lat, this.lon, poi.latitude, poi.longitude);
    if (d > (poi.talkRangeMeters || 90)) continue;
    const diff = angleDelta(heading, bearingDegrees(this.lat, this.lon, poi.latitude, poi.longitude));
    if (diff <= HEADING_TOLERANCE) bestAligned = { poi, diff }; // 60° 容差
  }
  return bestAligned?.poi || (best?.distance <= 25 ? best.poi : null); // 超近距离兜底
}

4.6 数据层：三级景区

重点景区 PARKS：西湖（7 点）、故宫（5 点），带精确坐标与讲稿，支持逐点讲解；
全国 5A 名称库 SCENIC_AREAS：360 家，仅名称 + 坐标 + 半径，进园讲景区层面，讲解词由大模型生成；
联网兜底 lookupNearbyArea：都不命中时用 OSM Overpass 查周边命名景点，拼出动态景区。

// lib/pois.js —— 命中优先级：内置重点 > 名称库 > null
export function findPark(latitude, longitude) {
  const parkHit = matchIn(PARKS, latitude, longitude, 'park');
  if (parkHit) return parkHit.item;
  const areaHit = matchIn(SCENIC_AREAS, latitude, longitude, 'area');
  return areaHit ? areaToPark(areaHit.item) : null;
}

景点数据由脚本从 Excel 生成，保证可维护、不手改：

// tools/build-scenic-areas.mjs：xlsx → lib/scenic-areas.js
// 半径启发式：urban(古城/寺/塔/博物馆…)→2000m；large(山/湖/湿地…)→8000m；否则 3000m

4.7 卡片渲染与播讲

最多同时 4 行，讲一句推一行、旧行上滚；按句号断句，逐句「显示 + TTS」：

pushOverlayLine(text) {
  const next = (this.data.overlayLines || []).concat([{ id: makeId('line'), text }]);
  while (next.length > MAX_OVERLAY_LINES) next.shift();
  this.setData({ overlayLines: next });
}

TTS 有 speechSynthesis 与 wx.speech.playTTS 两条实现，带超时兜底，可随时打断。

五、交互与体验

5.1 重要界面

HUD 行：[值守] 杭州西湖距断桥残雪 42 米 [聆听中]，下一行常显 30.25930,120.15260 · 断桥残雪 42 米；
讲解卡片：断桥残雪 / 西湖十景 · 白堤东端 + 正文逐句浮现 + 提示「点头或按确认键，返回键跳过」；
Footer：值守中 · 注视景物两秒我会轻声问，按确认键可随时叫我。

5.2 操作路径

进园 → 轻声「已进入杭州西湖…」→ 值守；
停步注视 2 秒 → 卡片浮现「要不要我给您讲讲？」+ 语音；
点头 / 按确认键 / 说「要」→ 讲解（卡片逐句 + 播讲）；
开口打断 → 追问，只聊当前点位；
返回键 / 说「结束」/ 走出范围 → 回值守或休眠。

5.3 反馈机制

语音：进园/离园/询问/讲解全部用轻声 TTS，不刺耳；
视觉：模式 chip 变色、聆听态 chip、实时识别文字回显；
冷却：跳过过的点位 60 秒内不再打扰，避免反复询问；
容错：定位异常、语音不可用均以 footer 文案告知，不弹窗打断。

六、调试与验证

6.1 预览

AIUI Studio / Craft 预览（js.rokid.com/craft）：改完 .ink 即时预览 HUD 与卡片布局；
预览里用模拟坐标（如断桥坐标）验证进园、锁定、讲解全流程。

6.2 回归测试（Node 桩件）

把 lib/*.js 与页面脚本抽取到 Node 环境，用桩件替换 wx、传感器、语音，做了三套断言：

定位/坐标健壮性：22 条；
主流程状态机：19 条；
多景区 + OSM 动态景区：15 条。

七、成果与复盘

7.1 可运行成果

一个可在 Rokid AR 眼镜上运行的多景区讲解智能体：内置西湖/故宫 12 个点位，覆盖全国 360 家 5A 的景区层面讲解，任何其他地方也能联网兜底识别周边景点。

7.2 遇到的问题与解决

问题	现象	解决方案
定位权限	真机报 manifest 缺少 GEOLOCATION	`app.json` 声明大写权限
经纬度填反	模拟器坐标颠倒/被截断	`normalizeCoordinates` 自动纠正并提示
只支持单次定位的宿主	`watchPosition` 不回调	双通道 + 看门狗轮询
`watchPosition` 断线	出错后永久失联	错误回调 `clearWatch` 并置 `watchId=null` 后重试
Overpass 406	联网查询被拒	请求头必须带 `User-Agent`
联网识别只触发一次	出界计数一直增长，`===3` 不再命中	改用 `>=` / 按格变化触发
离园被旧请求拉回	在途请求返回后自动重新进园	请求 token 机制，离园即作废在途结果
OSM 顶掉内置名	边界处名称抖动	内置景区优先 + 围栏容差
卡片残留	退出后卡片卡在休眠界面	退出/休眠统一 `hideOverlay`
否定词误判	「不好」被当成确认	否定判定优先于肯定

7.3 后续迭代计划

视线标定：真机上对 yaw→正北做一次标定，提升锁定精度；
持续收音：追问模式在静音后自动续听，减少重复唤醒；
数据后台化：景区与讲稿改为后台实时下发，支持运营与热更新；
能力增强：室内定位 / 视觉 SLAM 辅助（弱 GPS 场景）、多语言、无障碍音效；
体验打磨：卡片层级与视觉降噪、语音打断的即时性、离园提醒的柔和度。

Vue3 事件：常用用法与开发高频坑点

Tony费 — Sat, 17 Oct 2026 05:43:18 GMT

前言：

Vue3 项目里，事件处理（@click、@change、@keyup 等）是最常见的内置事件。很多时候开发遇到的相关坑点问题不在"语法不会"，而在传参、修饰符、target 区分、异步访问、类型推断这些细节上。本文分享一下日常开发里真实会用到事件的写法，以及那些常见的报了诡异 bug、排查半天的坑。

一、事件的基础写法：

1. 最简单的用法

不传任何参数时，事件处理函数会自动收到原生事件对象作为第一个参数：

<template>
  <button @click="handleClick">点击</button>
</template>

<script setup>
  function handleClick(e) {
    console.log(e) // 原生 Event 对象
  }
</script>

2. 需要自定义参数 + 事件对象

只要传了自定义参数，就必须手动把 $event 一起传进去，否则事件对象会被覆盖掉：

<template>
  <button @click="handleClick('商品A', $event)">点击</button>
</template>

<script setup>
  function handleClick(name, e) {
    console.log(name) // '商品A'
    console.log(e.target) // 事件对象
  }
</script>

这是最经典的坑：带自定义参数却忘了 $event ，函数里拿到的 e 其实是自定义值，根本不是事件对象。

二、常用事件场景：

1. 获取当前点击的元素

<template>
  <div @click="handleClick">
    <span>内容</span>
  </div>
</div>

<script setup>
  function handleClick(e) {
    console.log(e.target) // 真正点击的元素（可能是 span）
    console.log(e.currentTarget) // 绑定事件的那个元素（div）
  }
</script>

target 和 currentTarget 是区分难度最高的两个概念，几乎每个项目都会有人踩坑：

e.target：用户实际点击的元素（子元素）
e.currentTarget：绑定事件监听的元素（父元素，始终不变）

嵌套结构里，点击 span 时：

target → span
currentTarget → div

业务上想拿"绑定事件的那个节点"，务必用currentTarget。

2. 输入框的输入事件

<template>
  <input @input="handleInput" />
</template>

<script setup>
  function handleInput(e) {
    console.log(e.target.value) // 当前输入的值
  }
</script>

3. 键盘事件（回车、按键判断）

<template>
  <input @keyup="handleKey" />
</template>

<script setup>
  function handleKey(e) {
    if (e.key === 'Enter') {
      console.log('按下了回车')
    }
    if (e.key === 'Escape') {
      console.log('按下了 Esc')
    }
  }
</script>

4. 阻止冒泡和默认行为

优先用修饰符，简单清晰：

<!-- 阻止冒泡 -->
<div @click.stop="handleClick">…</div>

<!-- 阻止默认行为（如表单提交、a 标签跳转） -->
<form @submit.prevent="handleSubmit">…</form>

<!-- 组合 -->
<a href="…" @click.prevent.stop="handleClick">链接</a>

需要在函数里动态判断时，再用事件对象方法：

  function handleClick(e) {
    if (某种条件) {
      e.stopPropagation() // 阻止冒泡
    }
    
    if (另一种条件) {
      e.preventDefault() // 阻止默认行为
    }
  }

三、开发高频坑点汇总：

坑点 1：传了自定义参数却忘了 $event

<template>
  <!-- 错误 -->
  <button @click="handleClick(10)">点击</button>
</template>

<script setup>
  // 你以为 e 是事件对象，其实是 10
  function handleClick(e) {
    console.log(e.target)  // undefined，报错！
  }
</script>

解决：需要事件对象就手动传 $event 。

坑点 2：参数顺序写反

<template>
  <!-- 模板里顺序 -->
  <button @click="handle('A', $event)">点击</button>
</template>

<script setup>
  // 函数里顺序必须和模板完全一致
  function handle(name, e) {
    // 正确：name='A'，e=事件对象
  }
</script>

顺序反了不会报错，但取值全乱，属于最隐蔽的坑。

坑点 3：target 和 currentTarget 混用

上面讲过，嵌套 DOM 里两者不同。用错了会导致：

想拿父级数据，却取到子元素的属性（undefined）
样式 / class 改到了错误节点

规则：凡是"绑定事件的那个元素"，一律用 currentTarget 。

坑点 4：修饰符和函数内阻止逻辑重复

<template>
  <!-- 用了 .stop -->
  <div @click.stop="handleClick">…</div>
</template>

<script setup>
  function handleClick(e) {
    e.stopPropagation() // 又手动阻止一次
  }
</script>

重复阻止一般不会报错，但会让逻辑混乱、排查困难。建议统一规范：

简单、固定的场景：用模板修饰符
需要条件判断的动态场景：只用函数内方法，别混用

坑点 5：异步回调里直接使用事件对象

  function handleClick(e) {
    setTimeout(() => {
      console.log(e.target)  // 可能拿到 null / undefined
    }, 500)
  }

原生事件对象在事件处理完后会被复用/回收，异步里再访问内容不稳定。

解决：先缓存需要的值。

  function handleClick(e) {
    const el = e.target
    const val = e.target.value
    setTimeout(() => {
      console.log(el, val) // 用缓存值，安全
    }, 500)
  }

坑点 6：键盘事件用 keyCode 已废弃

// 老写法，已废弃
if (e.keyCode === 13) { … }

用现代写法：

if (e.key === 'Enter') { … }
if (e.code === 'Enter') { … }

e.key：表示按键的字符 / 名称（如 'Enter'、'a'、'ArrowUp'）
e.code：表示物理按键位置（如 'KeyA'、'ArrowUp'）

区分中英文输入法布局时，用 e.code 更可靠。

坑点 7：事件绑定到组件标签上（组件事件）

给自定义组件用 @click 时，默认监听的是组件自定义事件，不是原生 DOM 事件：

<!-- 这样写，默认不会触发原生 click -->
<MyButton @click="handleClick" />

如果想让事件落到底层原生元素上，需要：

<MyButton @click="handleClick" @click.capture="…" />

或者在组件内部显式 defineEmits：

// MyButton.vue
const emit = defineEmits(['click'])
function onClick(e) {
  emit('click', e)
}

简单记：原生 DOM 元素直接用 @click 没问题；自定义组件上想监听原生事件，要么组件内部 emit ，要么用 .capture 等原生修饰符。

四、事件常用修饰符一览:

常用按键快捷写法：

<input @keyup.enter="submit" />
<input @keyup.esc="cancel" />
<input @keyup.ctrl.enter="save" />

五、事件处理函数几种写法的取舍:

六、开发规范建议:

绑定事件元素的节点操作，一律用 currentTarget，避免嵌套踩坑。
需要事件对象 + 自定义参数时，别漏 $event ，别写反顺序。
固定阻止逻辑用修饰符，动态判断用函数内方法，别混用。
异步里先缓存事件对象的属性，别直接延迟访问。
键盘判断用 e.key / e.code ，别用废弃的 keyCode 。
自定义组件的事件按"组件事件"处理，要原生事件就内部 emit 或加原生修饰符。

曝光埋点别放在组件渲染里：连续可见与去重范围怎么验收

SensorFlow — Fri, 16 Oct 2026 09:51:43 GMT

列表组件更新一次，曝光数就加一次；用户明明没滚到那张卡片，后台却已经收到曝光。这类问题通常不是报表计算慢，而是把“内容被创建”误当成“内容进入了约定的可见范围”。曝光埋点应先写触发契约，再把浏览器信号接到契约上。

本文由 SensorFlow 项目维护方整理，AI 协助起草；代码仅使用离线合成观测，不代表真实用户、浏览器兼容性实测或产品内置能力。

一次曝光究竟证明了什么

本文把一次合格曝光定义为：同一页面实例里，同一内容与位置组合，在页面可见时，元素几何相交比例持续不低于约定阈值，达到持续时间后最多产生一个候选事件。它不证明用户读懂、记住或点击，也不证明候选事件已送达服务端。

示例使用比例 0.5、连续 1000 毫秒，只是为了让测试边界清晰，不是广告计费标准，也不是所有列表的推荐值。产品、前端、分析和测试应共同决定真实阈值；不要用“业内都是这样”替代定义。

DOM 节点创建、接口成功返回、组件 mounted 和虚拟列表复用，都可以发生在用户尚未看到内容时。相反，同一条内容因为状态更新重新渲染，不应自动成为一次新曝光。

浏览器提供观测，业务负责解释

Intersection Observer 可以异步观测元素与视口或指定根的相交变化；intersectionRatio 描述面积比例。它们提供的是几何信号，不是人类注意力证明。

还要检查 document.visibilityState。切到后台后，不能仅因为上一次元素比例合格，就继续累计一次“前台连续曝光”。普通相交观测也不能独自保证元素未被遮挡；透明、覆盖、复杂容器以及可选的 trackVisibility 支持都需要单独评估。

实现时可以分四步：

在页面或路由进入时建立页面实例范围，确定内容ID和位置ID。
将相交、页面前后台及计时检查转换为同一时钟上的观测。
只在持续区间未中断且达到阈值时创建候选曝光。
创建后固定事件ID交给上报层；传输重试不重新触发业务曝光。

相交回调不会保证恰好在1000毫秒再次执行。真实适配器还需要到期检查，并在到期时重新确认页面和元素条件。下面的程序只验证已经提供的观测序列，不会替你注册监听、定时器或发请求。

用边界样本验收，而不是盯着总数猜

保存为 impression.cjs，执行 node impression.cjs。代码只依赖 Node 标准库；所有字符串ID均为合成标识，没有请求、Cookie、DOM或用户数据。

const assert = require('node:assert/strict');
function detector() {
  const since = new Map(), fired = new Set();
  let last = -Infinity;
  return function observe(at, item, slot, ratio, visible) {
    assert(Number.isFinite(at) && at >= 0 && at >= last);
    assert(typeof item === 'string' && item.length > 0);
    assert(typeof slot === 'string' && slot.length > 0);
    assert(Number.isFinite(ratio) && ratio >= 0 && ratio <= 1);
    assert.equal(typeof visible, 'boolean');
    last = at;
    const key = JSON.stringify([item, slot]);
    if (!visible) since.clear();
    if (!visible || ratio < 0.5) {
      since.delete(key);
      return false;
    }
    if (fired.has(key)) return false;
    if (!since.has(key)) since.set(key, at);
    if (at - since.get(key) < 1000) return false;
    fired.add(key);
    return true;
  };
}
const first = detector();
assert.equal(first(0, 'card-a', 'feed', 0.5, true), false);
assert.equal(first(999, 'card-a', 'feed', 0.5, true), false);
assert.equal(first(1000, 'card-a', 'feed', 0.5, true), true);
assert.equal(first(2000, 'card-a', 'feed', 1, true), false);
const interrupted = detector();
interrupted(0, 'card-a', 'feed', 1, true);
interrupted(700, 'card-a', 'feed', 0.49, true);
interrupted(800, 'card-a', 'feed', 1, true);
assert.equal(interrupted(1000, 'card-a', 'feed', 1, true), false);
assert.equal(interrupted(1800, 'card-a', 'feed', 1, true), true);
const background = detector();
background(0, 'card-a', 'feed', 1, true);
background(800, 'card-a', 'feed', 1, false);
assert.equal(background(1200, 'card-a', 'feed', 1, true), false);
assert.equal(background(2200, 'card-a', 'feed', 1, true), true);
assert.throws(() => background(2100, 'card-a', 'feed', 1, true));
assert.throws(() => detector()(0, 'card-a', 'feed', 1.1, true));
const anotherPage = detector();
anotherPage(0, 'card-a', 'feed', 1, true);
assert.equal(anotherPage(1000, 'card-a', 'feed', 1, true), true);
console.log('PASS: 11 synthetic impression checks');

999毫秒不触发、1000毫秒触发，能防止“看起来差不多”的边界漂移。700毫秒时比例跌破阈值后，重新进入要从800毫秒重新计时；切后台也会清空尚未合格的持续区间。同一页面实例内已经触发的卡片再次观察不重复，新页面实例则重新建立自己的去重范围。

这里用 Set 保存已经触发的逻辑键，用 Node strict assert 让失败明确中断。它是内存教学模型，不具备进程恢复、跨标签页共享或分布式去重。

去重键不要跟着节点身份走

虚拟列表可能把同一个节点先用于内容A，再用于内容B。如果用DOM节点本身作为唯一键，后者可能被错误压掉；如果每次渲染都生成随机新键，前者又可能被重复计数。键应来自明确的业务范围，而不是渲染框架的实现细节。

本文选择“页面实例＋内容＋位置”。实际业务也可能选择“会话＋内容”或“内容展示机会ID”；这些口径不能混着比较。同一内容在主列表和推荐栏出现，是否应该算两个机会，需要先回答报表要解释哪个位置，而不是在查询时临时拼补。

多卡片适配器在收到页面隐藏信号时，应及时向模型提供这一状态，使全部未完成区间失效。卡片卸载、换内容或退出观察时也要取消相应的等待检查。模型假设影响条件的状态变化已按顺序提供；中途信号丢失时，不能仅用首尾两点证明真实连续可见。示例没有处理资源释放、观察数据丢失、乱序补报或完整设备生命周期，不能直接贴进生产当成完整SDK。

上线前保留三层验收证据

前端测试先证明候选事件何时产生：卡片未进入视口、短暂划过、反复进出、切后台、虚拟列表换内容和路由返回都要覆盖。真实设备测试再检查时序、遮挡、定时节流及低版本行为，Node断言不能替代这一步。

接收测试证明一个固定事件ID在重试后怎样落地；报表测试最后证明“候选次数、唯一曝光、曝光人数”分别取什么范围。一个事件在控制台出现，只覆盖了这条链路的一小部分。

运营对点击率有疑问时，先把点击与曝光的内容、位置、页面范围和统计窗口对齐。不要拿全站点击人数除某个组件的曝光次数，也不要因为用户先点击就倒推出缺失的曝光事实。下一步最有效的行动，是把上面的合成边界换成自己组件的真实场景测试，而不是先改报表颜色。

REA 火了：一个 Electron 按钮的调用链，它能追到哪一步？

日耗10亿Token被老板赶出门 — Fri, 16 Oct 2026 09:20:26 GMT

今天刷掘金榜单，连续看到几篇 REA。名字也很直接：Reverse Engineer Anything，逆向一切。

看完介绍，我想试一个小问题：给它一个 Electron 项目的源码目录，它能不能顺着「添加草稿」这个按钮，找到最后处理数据的代码？

结果有点意思。它配上了两条 IPC 通道，也标出了代码位置；但页面里的调用，还有一部分停在 unknown。

先交代这次实际做了什么：准备了一个自写的 5 文件样本，用 REA 6.5.0 做静态分析。没有启动 Electron，也没有让模型复刻界面。这篇记录的是工具输出和源码复核。

REA 是给 AI Agent 使用的逆向分析工具，也提供 CLI。它可以把代码结构和分析证据交给模型，继续追踪某个功能。这里先单独跑 CLI，看看模型拿到的材料到底是什么。

样本很小：main.js 管主进程，preload.js 暴露桥接方法，renderer.js 处理页面操作，再加一个 HTML 和 package.json。功能只有添加、统计和清空草稿。

本机用 Node 24.19.0，REA 固定为 6.5.0。首次安装停在 Frida 的依赖安装脚本，后来使用已下载的缓存、跳过安装脚本，完成了静态分析。下面是成功执行的命令，样本路径换成了占位符：

npm --cache /private/tmp/rea-demo-npm-cache --offline --ignore-scripts \
  exec --yes --package rea-agents@6.5.0 -- \
  rea analyze-javascript-application /absolute/path/to/sample-app --json \
  > application-evidence.json

这里的 --offline 依赖前一次已经下载的缓存，首次安装不能直接照抄。常规运行方式见官方 CLI 文档。跳过安装脚本只在本文的 JavaScript 分析中验证过，原生分析能力没有测试。

输出中，3 个 JavaScript 文件均解析成功，找到了 1 个 BrowserWindow、1 个 preload 入口和 1 个桥接 API。更具体的结果是下面这组代码。

preload.js 把添加方法交给页面：

contextBridge.exposeInMainWorld('drafts', {
  add: (text) => ipcRenderer.invoke('draft:add', text),
  list: () => ipcRenderer.invoke('draft:list'),
  onCleared: (callback) =>
    ipcRenderer.on('draft:cleared', () => callback())
});

main.js 接收添加请求：

let drafts = [];

ipcMain.handle('draft:add', (_event, text) => {
  const draft = { id: drafts.length + 1, text: String(text).trim() };
  drafts.push(draft);
  return draft;
});

REA 将 preload 中的 invoke 和 main 中的 handle 配了起来。下面是原始输出中这条关系的部分字段，省略了 ID 等内容：

{
  "channel": "draft:add",
  "pairing_basis": "unique-exact-literal-channel",
  "handler_path": "main.js",
  "handler_operation": "handle"
}

也就是根据唯一、相同的通道名，定位到了另一端的处理函数。draft:list 也完成了配对。

对接手陌生项目的人来说，这种结果有用：至少知道接下来该打开哪个文件，而不是只拿到一段「这是一个草稿管理程序」的概括。不过，这条静态关系还不能证明运行时真的调用成功。

接着看页面代码：

await window.drafts.add(editor.value);
const drafts = await window.drafts.list();

人对照刚才的 preload，很容易理解这里想调用什么。但在这次输出的语义图里，这两个调用仍然有未解析记录。工具找到了桥接 API，不代表页面到主进程的每一段关系都已经自动串好。

清空功能也一样。源码里有 mainWindow.webContents.send('draft:cleared')，preload 里有对应监听；这次结构图识别了监听，却没有生成主进程一侧对应的发送边。

所以，报告里没找到某条关系，不能直接写成代码里没有这段逻辑。

这也是把报告交给模型时最值得保留的信息。只给模型一张整理得很漂亮的调用图，把 unknown 和限制说明删掉，它后面就更难区分哪些是工具找到的，哪些需要回到源码继续查。

还有一个小细节：草稿存到哪里了？

回看上面的 main.js，处理函数只是往数组里放数据。检查这个样本的源码，没有实现磁盘持久化。因此「找到了添加草稿的处理代码」可以说，「已经验证草稿保存成功，重启也不会丢」就说过头了。后一句还需要运行应用、重启和核对结果。

如果下一步接到 AI 编程助手里，我会把任务缩小到这几件事：

沿着添加草稿的功能继续查。每一步给出文件和行号，区分工具已建立的关系与需要读源码补充的关系。遇到 unknown，说明缺什么证据。最后检查数据存在哪里，并列出还需要怎样的运行验证。

下一步可以固定这份证据和问题，比较不同模型会不会主动追查 unknown。编程助手如果已通过 moyi API 接入支持的模型，就能沿用模型入口，REA 的工具连接仍需单独配置。这次没有做模型联调，因此还不能评价哪种组合效果更好。

跑完这个小样本，我更愿意把 REA 用在「帮我找到该读的代码」上。找到位置后，继续读、继续验证，比直接让 AI 给整个软件下结论踏实得多。

你们接手陌生项目时，会先让 AI 通读整个仓库，还是先挑一个具体功能，把调用过程追到底？

能解码不等于能信任：JWT 的签名到底验的是什么

harris1481543529758 — Fri, 16 Oct 2026 08:49:45 GMT

任何人都能读出 JWT 里的内容——它只是 Base64URL，不是加密。真正决定这个令牌能否被信任的是签名，而签名的验证有几种经典的绕过方式。

先亲手造一个，再亲手读出来

关于 JWT 的所有误解，都能靠亲手造一个来消除。不需要任何依赖，Node 自带的 crypto 就够：

import { createHmac } from 'node:crypto';

const b64u = (obj) => Buffer.from(JSON.stringify(obj)).toString('base64url');
const secret = 'dev-secret-not-a-real-key';

const h = b64u({ alg: 'HS256', typ: 'JWT' });
const p = b64u({ sub: 'u_1024', role: 'user', exp: 1790000000 });
const s = createHmac('sha256', secret).update(`${h}.${p}`).digest('base64url');

console.log(`${h}.${p}.${s}`);

我在 Node v22.17.1 / macOS 26.5.2 上跑出来的结果，本文后面所有例子都基于这一个令牌：

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1XzEwMjQiLCJyb2xlIjoidXNlciIsImV4cCI6MTc5MDAwMDAwMH0.1Uq490UTCjQu_qA7RScjHcHUgT65G2nBnogsqjkr3P0

三段用点号隔开，长度分别是 36 / 63 / 43 个字符。把前两段丢回去解码，得到的就是你刚刚写进去的那两个 JSON 对象——一个字节都没变：

Buffer.from(h, 'base64url').toString(); // {"alg":"HS256","typ":"JWT"}
Buffer.from(p, 'base64url').toString(); // {"sub":"u_1024","role":"user","exp":1790000000}
Buffer.from(s, 'base64url').length;     // 32

第三段解码出来是 32 个字节而不是文本——那是 HMAC-SHA256 的输出，256 位。它不是「加密后的前两段」，前两段并没有被藏起来，它只是对前两段算出来的一个固定长度的摘要。顺带解释一个人人都见过、很少有人追问的现象：几乎所有 JWT 都以 eyJ 开头，因为紧凑序列化的 header JSON 必然以 {" 加一个字母开头，而 {"a 编码出来是 eyJh、{"z 是 eyJ6，前三个字符恒为 eyJ。这不是什么魔法前缀，只是 Base64 的对齐结果。

Base64URL 不是加密，而且它和 Base64 差三个字符

「JWT 是加密的吗」这个问题之所以反复被问，很大程度上是因为那一长串东西看起来像密文。它不是。Base64URL 是编码，编码是可逆的、不需要密钥的公开变换，它和 Base64 的区别只有三处：+ 换成 -、/ 换成 _、末尾的 = 填充去掉。用五个字节就能把这三处差异一次看全：

const b = Buffer.from([0xfb, 0xef, 0xbe, 0x3f, 0xff]);
b.toString('base64');    // '++++P/8='
b.toString('base64url'); // '----P_8'

这三处差异的用意是让编码结果能安全地出现在 URL 路径、查询串和 HTTP 头里，不必再做一次百分号转义。但它也埋了一个很容易踩的坑：很多命令行 base64 工具既不认 - 和 _，也不容忍缺失的填充，而且出错时不吭声。在 macOS 上直接把 payload 段喂给 base64 -d：

T='eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1XzEwMjQiLCJyb2xlIjoidXNlciIsImV4cCI6MTc5MDAwMDAwMH0.1Uq490UTCjQu_qA7RScjHcHUgT65G2nBnogsqjkr3P0'
echo "$T" | cut -d. -f2 | base64 -d
# {"sub":"u_1024","role":"user","exp":179000000

它的退出码是 0，没有任何警告。payload 段是 63 个字符，63 除以 4 余 3，最后那组三个字符还差一个 = 才完整，于是 FreeBSD 版 base64（macOS 自带的就是它）把这不完整的一组整个丢掉了——少了两个字符 0}。注意后果的形状：花括号没了，输出连合法 JSON 都不是；更阴险的是 exp 从 1790000000 变成了 179000000，少一个零，看起来仍然是个像模像样的时间戳。这一段里恰好没有 - 和 _，所以它栽的纯粹是填充；换成签名段就是另一种栽法——那一段里有一个 _，base64 -d 同样一声不吭，吐出 30 个字节，而真正的 HMAC-SHA256 签名是 32 个字节。换成 Node 的 base64url 解码就没有这个问题：

node -e "console.log(Buffer.from(process.argv[1].split('.')[1],'base64url').toString())" "$T"
# {"sub":"u_1024","role":"user","exp":1790000000}

结论很直接：payload 里的每一项声明，对任何拿到令牌的人都是明文可读的。用户 ID、角色、租户编号放进去没问题，因为它们本来就是这个用户自己的身份；但内部主键、手机号、邮箱、任何你不愿写进日志的字段，都不该出现在那里。签名保证的是「没被改过」，不是「看不见」。

签名覆盖的是前两段，而且只覆盖前两段

签名的输入是 header段 + "." + payload段 这个字符串——注意是编码后的两段原文，不是解码出来的对象。所以只要这两段里任何一个字节变了，签名就对不上。改 payload 会被抓到，改 header 里一个跟算法毫不相干的字段也会：

const sign = (h, p) => createHmac('sha256', secret).update(`${h}.${p}`).digest('base64url');

// 把 role 从 user 改成 admin，签名段沿用原来的
sign(h, b64u({ sub: 'u_1024', role: 'admin', exp: 1790000000 })) === s; // false
// 只把 typ 从 JWT 改成 at+jwt，签名段沿用原来的
sign(b64u({ alg: 'HS256', typ: 'at+jwt' }), p) === s;                   // false

两次都是 false。把这件事说到位：签名验证通过，能证明的只有一句话——这个 header 与 payload 的组合，确实由持有密钥的一方签发过，并且此后一个字节都没改。 它不能证明的东西比能证明的多得多：不能证明令牌没过期，不能证明它没被吊销，不能证明它是发给你这个服务的，也不能证明用户此刻还有那个角色。这些都得靠另外的检查，而且那些检查跟密码学没有半点关系。

病根只有一句话：验证方读了令牌自称的算法

下面这个验证函数写得非常自然，自然到很多人第一次看不出问题在哪：

function naiveVerify(token, hmacKey, rsaPublicKey) {
  const [h, p, s] = token.split('.');
  const alg = JSON.parse(Buffer.from(h, 'base64url').toString()).alg; // ← 病根在这一行
  if (alg === 'none') return true;
  if (alg === 'HS256') return s === createHmac('sha256', hmacKey).update(`${h}.${p}`).digest('base64url');
  if (alg === 'RS256') return createVerify('RSA-SHA256').update(`${h}.${p}`)
    .verify(rsaPublicKey, Buffer.from(s, 'base64url'));
  return false;
}

问题在于 alg 是从 header 里读出来的，而 header 是攻击者可以随便改的那两段之一。于是「怎么验这个令牌」这个决定，被交给了那个等待被验证的令牌自己。

最短的利用方式就是 alg: none。规范里保留这个取值，本意是留给「完整性由传输层等其他手段保证」的场景，但落到一个会照着 header 办事的实现上，它等于一句「不用验」：

const forged = `${b64u({ alg: 'none', typ: 'JWT' })}.${b64u({ sub: 'u_1024', role: 'admin', exp: 1790000000 })}.`;
// eyJhbGciOiJub25lIiwidHlwIjoiSldUIn0.eyJzdWIiOiJ1XzEwMjQiLCJyb2xlIjoiYWRtaW4iLCJleHAiOjE3OTAwMDAwMDB9.
naiveVerify(forged, secret);  // true —— role 已经是 admin

注意末尾那个孤零零的点号：第三段是空的，因为攻击者把签名整个删掉了。伪造这个令牌不需要任何密钥，不需要爆破，甚至不需要看懂 HMAC 是什么——把 header 里的 HS256 改成 none、把 payload 改成想要的样子、把签名段清空，三步。

同一个病根的第二副面孔：HS256 / RS256 混淆

alg: none 太出名了，今天大多数库都会显式拒绝它。但只要「算法由令牌自称」这个病根还在，同一个洞就会换个形状再出现一次，而且这次不需要任何一个可疑的取值。

前提是服务端用 RS256：私钥签发，公钥验签。公钥按定义是公开的——它可能挂在 /.well-known/jwks.json 上，可能就印在你的 API 文档里。攻击者拿到这份公钥，把 header 的 alg 改成 HS256，然后把公钥的文本当作 HMAC 的密钥去签名：

const pub = publicKey.export({ type: 'spki', format: 'pem' });  // 公开的东西
const hh = b64u({ alg: 'HS256', typ: 'JWT' });
const pp = b64u({ sub: 'u_1024', role: 'admin', exp: 1790000000 });
const forged = `${hh}.${pp}.${createHmac('sha256', pub).update(`${hh}.${pp}`).digest('base64url')}`;

naiveVerify(forged, pub, pub);  // true

我实测的结果就是 true。成立的原因很朴素：验证方手上只有一份密钥材料，也就是那个公钥；它读到 header 说「这是 HS256」，就把这份材料当成 HMAC 的共享密钥用了。而 HMAC 的验证与签发用的是同一个密钥——于是一个本该只能验证、不能签发的公钥，被降格成了一个人人都有的签发密钥。顺带一提，两种令牌在外形上差别很明显：RS256（2048 位）的签名段是 342 个字符，HS256 的是 43 个，肉眼就能分辨；但没有任何代码会去看这个。

正确的做法：算法由验证方规定

两种攻击的修法是同一个，而且只有一句话：验证方自己决定接受哪个算法，用哪把密钥，然后拿令牌去对照——绝不反过来问令牌。 header 里的 alg 从此只有一个用途，就是和你规定的那个比一下，不相等就直接拒绝。

function verify(token, { algorithms, secret, now = Math.floor(Date.now() / 1000), leeway = 60 }) {
  const parts = token.split('.');
  if (parts.length !== 3) return { ok: false, why: '不是三段结构' };
  const [h, p, s] = parts;

  const head = JSON.parse(Buffer.from(h, 'base64url').toString());
  if (!algorithms.includes(head.alg)) return { ok: false, why: `算法 ${head.alg} 不在允许列表内` };

  const expect = Buffer.from(createHmac('sha256', secret).update(`${h}.${p}`).digest('base64url'), 'base64url');
  const got = Buffer.from(s, 'base64url');
  if (got.length !== expect.length || !timingSafeEqual(got, expect)) return { ok: false, why: '签名不匹配' };

  const c = JSON.parse(Buffer.from(p, 'base64url').toString());
  if (typeof c.exp === 'number' && now > c.exp + leeway) return { ok: false, why: '已过期' };
  if (typeof c.nbf === 'number' && now + leeway < c.nbf) return { ok: false, why: '尚未生效' };
  return { ok: true, claims: c };
}

同样的三个令牌喂给它，实测输出是：原令牌 {"ok":true,...}，alg: none 伪造 {"ok":false,"why":"算法 none 不在允许列表内"}，一个过期的令牌 {"ok":false,"why":"已过期"}。而 HS256/RS256 混淆那个令牌，只要把允许列表写成 ['RS256']，它在算法那一关就被拦下了——实测返回 {"ok":false,"why":"算法 HS256 不在允许列表内"}，根本走不到验签那一步。

几个细节值得单独点出来。算法列表是白名单，不是黑名单——只拒绝 none 是不够的，上一节那个例子里没有出现任何可疑取值。密钥要和算法绑死，HS256 用共享密钥、RS256 用公钥，不要让同一份材料被两条分支共用，那正是混淆攻击的落脚点。签名比对要用 timingSafeEqual，而不是 ===；字符串比较可能在第一个不同的字符处就返回，于是耗时会随着攻击者猜对的前缀变长而变化。顺序不能反：先验签名，再读声明。签名没通过之前，payload 里的每一个字段都是攻击者写的。

`exp` 只是一个数字，不检查就等于没有

exp、nbf、iat 都是普通的 JSON 字段，签名只保证它们没被改过，不会替你比较它们。这一点在实测里非常直观：我用一个 exp 为 1789000000（2026-09-10T00:26:40Z，写这篇文章时是四天前）的令牌，用正确的密钥签好，再交给前面那个 naiveVerify——它返回 true。签名确实是有效的，令牌确实是我签发的，而它确实已经过期了。「签名有效」和「令牌可用」是两个问题，第二个问题的答案不在密码学里，在你的那行 if 里。

按 RFC 7519，这三个字段的类型都是 NumericDate，也就是以秒为单位的 Unix 时间戳。JavaScript 的 Date 要的是毫秒，两者差三个数量级，于是这里成了一个高频 bug 点：把 Date.now() 直接写进 exp，令牌会变成永不过期；把 exp 直接丢给 new Date()，会得到 1970 年的某一天，于是每个请求都 401。关于这个千倍差在实践中还有哪些形状，可以看时间戳的三个坑。另外别忘了留一点时钟容差（上面那段代码里的 leeway）：签发方和验证方是两台机器，NTP 有漂移，几十秒的容差能挡掉一大类「刚签发就说过期」的诡异报障。

吊销是签名在结构上就表达不了的一件事

过期至少还写在令牌里，吊销连写都没处写。回头看上一节那个 verify() 函数：它从头到尾没有做任何一次 I/O——没查数据库，没发网络请求，全部计算都在本地完成。这正是 JWT 被选中的理由（验证方不必和签发方共享会话存储），但同一件事反过来说就是：令牌一旦签发出去，服务端就不再持有对它的任何控制。

具体后果是这样的：用户改了密码，那个在三十分钟前签发、还有二十分钟才到期的令牌，照样能用；管理员把某个账号停用了，已经发出去的令牌照样能用；你把 role 从 admin 降成 user，旧令牌里那个 admin 照样有效，直到它自己过期为止。这些都不是实现 bug，而是「验证方只做本地计算」这个设计的必然推论——它没有任何渠道知道你在服务端改了什么。

减损的办法只有两条，而且都要付代价。一是把 exp 压短，比如访问令牌只给 5 到 15 分钟，配一个可以在服务端撤销的刷新令牌；代价是刷新逻辑本身的复杂度，以及刷新接口成了新的攻击面。二是引入一份需要查询的状态——按 jti 建吊销名单，或者在用户记录上放一个版本号、令牌里带上同一个版本号，不一致就拒绝；代价是每次验证都要读一次那份状态，于是「无状态验证」这个卖点被还了回去。没有第三条路：要么容忍一个已知长度的时间窗口，要么花一次查询把窗口关掉。选哪个是业务决定，但必须是一个被明确做出的决定，而不是「我们用了 JWT，所以踢下线应该是即时的吧」。

这个解码器能告诉你什么，不能告诉你什么

本站的 JWT 解码工具只做解码，不验签。原因不是没实现，而是验签需要密钥，而向你索取生产环境的签名密钥这个动作本身就是错的——尤其是 HMAC，验证用的密钥和签发用的是同一个，交出去就等于交出了以你的名义签发任意令牌的能力。一个网页可以承诺「不上传」，但你没有办法在粘贴之前验证这个承诺；解码则完全不需要密钥，所以这个工具只做那件能安全做完的事。

还有一个边界更靠前：解码器只处理三段结构。如果你粘进去的东西有五段，那多半不是 JWT 而是 JWE——RFC 7516 的紧凑序列化是「受保护头.加密密钥.初始向量.密文.认证标签」五段，其中真正的载荷是加密过的，没有密钥就是一堆二进制，任何解码器都读不出人话。段数不对的时候，先确认你手上的到底是哪一种东西，再去怀疑工具。

把边界写清楚：这个工具能告诉你这个令牌说了什么——三段各自的内容、exp 换算成本地时间是什么时候、按你本机的钟算它过没过期。它不能告诉你这个令牌是不是真的。一个能干净解码、格式完好、还没到期的令牌，完全可以是前面那种三步伪造出来的东西。真正回答「能不能信」的只有持有密钥的那台服务器，而它回答这个问题的方式，就是本文中间那几节反复说的那一句：算法由它自己规定，不问令牌。

原文发表于 GoodToolkit。文中用到的 JWT 解码工具在这里，解码全在浏览器内完成，令牌不会离开你的设备。

浏览器为什么加载不了超大图片

chenCode — Fri, 16 Oct 2026 08:29:38 GMT

请求明明是 200，为什么浏览器还是加载不了超大图片？

一张 87 MB 的 JPEG 在 Network 面板中返回 200 OK，但页面上却只显示“图片加载失败”。问题究竟出在网络、组件，还是浏览器？

问题现象

最近在项目中做了一个成果文件预览功能，图片使用 Element Plus 的 ElImageViewer 打开。大部分图片都能正常预览，但有几张地图成果始终打不开。

打开 Chrome DevTools 后可以看到：

请求状态是 200 OK；
响应类型是 image/jpeg；
文件已经完整下载；
单张图片大约 40–91 MB；
<img> 仍然触发了 error 事件。

这说明问题已经不在 HTTP 请求阶段，而是发生在图片解码阶段。

200 OK 不等于图片能显示

浏览器展示一张网络图片，至少要经过以下步骤：

发起 HTTP 请求。
下载 JPEG、PNG 或 WebP 压缩数据。
浏览器解析图片格式。
将压缩数据解码成内存中的像素位图。
上传给 GPU 并绘制到页面。

Network 面板中的 200 OK 只能证明前两步基本成功，不代表后面的解码和绘制一定成功。

这也是为什么有时候请求看起来完全正常，页面上却仍然出现破图图标。

真正需要关注的不是文件大小，而是像素数量

这张无法打开的图片参数如下：

文件格式：JPEG
文件大小：约 87 MB
图片尺寸：34253 × 37794

总像素数为：

34253 × 37794 = 1,294,557,882

也就是约 12.95 亿像素。

JPEG 文件虽然只有 87 MB，但它只是磁盘和网络传输时的压缩体积。浏览器展示图片时，需要将它解码成未压缩的像素数据。

如果按 RGBA 四通道计算，每个像素需要 4 字节：

34253 × 37794 × 4
≈ 5,178,231,528 Bytes
≈ 4.82 GiB

也就是说，一张看起来只有 87 MB 的 JPEG，解码后可能需要接近 5 GB 内存。

这还没有计算：

压缩数据本身占用的内存；
图片解码过程中的临时缓冲区；
浏览器渲染进程的其他内存；
GPU 纹理可能产生的额外副本；
旋转、缩放或 Canvas 处理时产生的新位图。

因此，图片加载失败是一个很合理的结果。

Element Plus 有图片大小限制吗？

本次项目使用的是 ElImageViewer，起初很容易怀疑是组件限制了文件大小。

但查看组件实现后会发现，它最终仍然是通过普通的 <img> 加载图片：

<img
  :src="url"
  :style="imgStyle"
  @load="handleImgLoad"
  @error="handleImgError"
/>

ElImageViewer 提供的是遮罩层、缩放、旋转和拖拽等交互，并没有额外设置几十 MB 或几百 MB 的文件上限。

真正失败的是浏览器底层图片解码。

而且浏览器的可用上限并不是一个统一的“文件大小”数值，它会受到以下因素影响：

图片的宽度和高度；
像素总量；
颜色通道与位深；
操作系统和浏览器实现；
当前页面及渲染进程的可用内存；
GPU 支持的最大纹理尺寸。

所以不应该用“小于 100 MB 就能打开”这种简单规则判断。一张压缩率很高、但尺寸极大的图片，可能比文件更大但像素更少的图片更容易出问题。

如何定位这类问题？

1. 先看 Network，不要只看页面上的破图

重点确认：

Status Code: 200
Content-Type: image/jpeg
Content-Length: 91376018

如果状态码不是 200，先排查鉴权、路径、跨域、代理或静态资源映射。

如果状态码是 200，还需要检查 Content-Type 是否真的是图片。有些接口即使返回了登录页或 JSON 错误信息，状态码也可能是 200。

2. 监听 `<img>` 的 load 和 error

const image = new Image();

image.onload = () => {
  console.log("加载成功", {
    width: image.naturalWidth,
    height: image.naturalHeight
  });
};

image.onerror = event => {
  console.error("图片下载成功，但解码或渲染失败", event);
};

image.src = imageUrl;

需要注意：浏览器通常不会在 error 事件中提供详细的底层解码原因，所以还需要结合文件大小和图片尺寸判断。

3. 在服务器或本地查看真实尺寸

使用 ImageMagick：

identify large-map.jpg

或者：

magick identify large-map.jpg

在 macOS 上也可以使用：

sips -g pixelWidth -g pixelHeight large-map.jpg

不要只看资源管理器中的“87 MB”，宽度、高度和总像素量才是排查解码问题的关键。

方案一：后端生成预览图，原图单独下载

这是最通用、实现成本也最低的方案。

文件上传后，后端同时保存：

originalUrl：原始大图，用于下载或专业处理；
previewUrl：最长边为 6000–8000 px 的预览图，用于浏览器展示；
thumbnailUrl：列表页小图，例如 400–800 px。

使用 ImageMagick 生成预览图：

magick large-map.jpg \
  -resize "8000x8000>" \
  -strip \
  -quality 85 \
  preview.jpg

> 表示只缩小比目标尺寸更大的图片，不会放大小图。

前端优先使用预览地址：

const displayUrl = file.previewUrl || file.staticUrl;

并在界面中保留“下载原图”入口。

这种方式既保证了预览体验，也不会丢失原始高清文件。

这个阈值只是业务保护策略，不是浏览器的统一硬限制。应该结合目标设备、图片内容和实测结果调整。

为什么不能在前端先用 Canvas 压缩？

这是一个很常见的想法：

先把原图加载到 Canvas，然后缩小不就可以了吗？

问题是，想要将图片绘制到 Canvas，浏览器仍然需要先解码原图。

const image = new Image();
image.src = hugeImageUrl;

image.onload = () => {
  // 只有原图解码成功后，才能执行到这里
  context.drawImage(image, 0, 0, targetWidth, targetHeight);
};

但现在失败的正是 image.onload 之前的解码阶段，所以 Canvas 无法作为这个问题的通用补救手段。

即使某些设备勉强可以解码，创建超大 Canvas 本身也会遇到尺寸与内存限制。

总结

当图片在 Network 面板中返回 200 OK，但页面仍然加载失败时，不要只盯着跨域、组件或文件体积。

需要关注的是：

200 OK 只代表 HTTP 请求成功，不代表图片解码成功。
压缩文件体积不等于解码后的内存占用。
对于 RGBA 图片，可以先用 宽 × 高 × 4 估算基础内存。

HTTP 200，页面仍是旧状态：定位一次前后端字段错配

用户660267611879 — Fri, 16 Oct 2026 08:06:20 GMT

AI SaaS工程诊断实战（一）

点了‘确认订单’，请求返回200，页面还停在草稿。继续给AI一句‘再检查一下前端’，它可能加刷新、加等待，或者把两种字段都兼容。画面终于变了，却没有说清楚问题在哪里。

遇到这类问题，我会先选定一次操作，把入口、请求、响应、取值和页面放在同一条链上看。下面给一个能本地重做的最小例子。

本文为构造演示，与我的AI Coding系列共用教学素材。字段错误是人为设置的，不是某个模型或IDE的实测故障；不使用客户资料。文稿由AI辅助整理，示例与结论按文中方式核对。

1. 先观察这个不一致

服务里有两个独立对象，初始状态均为draft。两个页面使用相同处理逻辑，分别确认各自对象；关键差别是前端读取字段。

确认接口返回：

{"id":"broken","status":"confirmed"}

故障页面却这样取值：

const next = data.state;
if (next !== undefined) {
  document.getElementById('display').textContent = next;
}

响应提供status，页面读取state，结果为undefined。条件分支没有更新文本，页面继续显示draft。服务端再读已经是confirmed，所以‘请求成功’‘服务状态改变’和‘界面显示正确’是这里需要分别检查的三件事。

2. 沿一次操作查六个位置

位置	检查动作	本例应观察到什么
入口	确认点了哪个对象	故障页操作对象为broken
请求	看方法、路径与对象ID	POST /api/orders/broken/confirm
服务结果	再次读取同一对象	GET返回status=confirmed
响应	对照实际层级、字段与值	顶层status，值confirmed
消费	找前端实际读取位置	代码读取state，值undefined
展示	读取页面最后状态	仍是draft

本例的断点就在响应与前端消费之间。真实项目也可能是环境不一致、操作对象错误、缓存或异步任务尚未完成；这张表帮助定位，不把同一种表象都归为字段问题。

3. 依据约定决定改哪边

本例约定成功响应的顶层字段为status，所以将前端改为：

const next = data.status;
if (next !== undefined) {
  document.getElementById('display').textContent = next;
}

这是一处最小修正。data.state ?? data.status在这里没有必要，因为示例不存在两个需要兼容的正式版本。如果真实服务有版本迁移，兼容可能合理，但要说明兼容谁、何时删除。

反过来，如果项目的权威约定是state，该调整的可能是服务端。先找实际约定，再决定改动位置。不要拿本文的字段名当成通用规范。

4. 修正之后要检查什么

在两个独立页面分别执行确认后，对照以下结果：

观察项	/broken	/fixed
POST状态	200	200
返回status	confirmed	confirmed
前端读取	state→undefined	status→confirmed
页面展示	draft	confirmed
再执行GET	confirmed	confirmed

修正页只是证明本次操作中页面消费字段与响应一致。服务使用进程内字典，没有数据库持久化；重启会重置。登录、权限、并发、异步任务、缓存和错误提示均未作为本篇验证结论。

这里还留有一个刻意简化：缺字段时静默不更新。生产代码需要按实际契约校验结果并展示错误，不应把这段分支直接当成完整异常处理。

5. 在本地重做

把文末代码保存为demo.py，使用Python 3运行：

python demo.py

分别打开：

http://127.0.0.1:8767/broken
http://127.0.0.1:8767/fixed

点击‘确认订单’。页面会显示请求、HTTP状态、实际响应、取值字段、页面状态及一次GET再读。用完在终端停止服务。本例仅监听本机，用于教学；Python自带的简单HTTP服务不作为生产部署方案。

6. 下次可以直接填这张检查卡

本次操作/对象/环境：
期望结果/实际结果：
请求方法、路径、对象ID：
响应状态、层级、字段和类型：
独立读取结果及依据：
前端实际取值与写入位置：
页面最后状态：
断点、改动与验证结果：
尚未检查的环节：

先让AI按卡片列证据和未知，再提出修改。一次请求返回成功之后，继续看用户期待的结果有没有发生；把这条链说明白，修复范围通常也更容易确定。

—— Linksass｜AI SaaS独立开发者

完整演示代码

代码仅使用Python标准库。两个页面和API都由同一服务提供。

import json
from http.server import BaseHTTPRequestHandler, HTTPServer

orders = {"broken": "draft", "fixed": "draft"}
PAGE = '''<!doctype html><html lang="zh-CN"><meta charset="utf-8">
<title>前后端字段契约演示</title><style>body{font:18px system-ui;max-width:850px;margin:50px auto;line-height:1.8}pre{background:#eef2f6;padding:20px;white-space:pre-wrap}button{font:inherit;padding:8px 20px}</style>
<h1>前后端字段契约：MODE</h1>
<p>构造演示：同一响应，分别读取 state / status。服务只在本机运行，存储为进程内字典。</p>
<p>当前展示：<strong id="display">draft</strong></p>
<button id="confirm">确认订单</button><pre id="evidence">尚未操作</pre>
<script>
document.getElementById('confirm').onclick = async () => {
  const response = await fetch('/api/orders/MODE/confirm', {method:'POST'});
  const data = await response.json();
  const next = data.FIELD;
  if (next !== undefined) document.getElementById('display').textContent = next;
  const rereadResponse = await fetch('/api/orders/MODE');
  const reread = await rereadResponse.json();
  document.getElementById('evidence').textContent = JSON.stringify({
    request: 'POST /api/orders/MODE/confirm', http: response.status,
    response: data, frontend_field: 'FIELD', frontend_value: next ?? '(undefined)',
    displayed: document.getElementById('display').textContent,
    reread_http: rereadResponse.status, reread: reread
  }, null, 2);
};
</script></html>'''

class Handler(BaseHTTPRequestHandler):
    def reply(self, payload, code=200, html=False):
        content = payload.encode('utf-8') if html else json.dumps(payload).encode('utf-8')
        self.send_response(code)
        self.send_header('Content-Type', 'text/html; charset=utf-8' if html else 'application/json')
        self.send_header('Content-Length', str(len(content)))
        self.end_headers()
        self.wfile.write(content)

    def do_GET(self):
        mode = self.path.strip('/')
        if mode in orders:
            self.reply(PAGE.replace('MODE', mode).replace('FIELD', 'state' if mode == 'broken' else 'status'), html=True)
        elif self.path.startswith('/api/orders/') and self.path.rsplit('/', 1)[-1] in orders:
            key = self.path.rsplit('/', 1)[-1]
            self.reply({'id': key, 'status': orders[key]})
        else:
            self.reply({'error': 'not found'}, 404)

    def do_POST(self):
        parts = self.path.strip('/').split('/')
        if len(parts) == 4 and parts[:2] == ['api', 'orders'] and parts[2] in orders and parts[3] == 'confirm':
            key = parts[2]
            orders[key] = 'confirmed'
            self.reply({'id': key, 'status': orders[key]})
        else:
            self.reply({'error': 'not found'}, 404)

if __name__ == '__main__':
    print('Demo: http://127.0.0.1:8767/broken and /fixed', flush=True)
    HTTPServer(('127.0.0.1', 8767), Handler).serve_forever()

参考：Python http.server、MDN Response.ok。

掘金 JavaScript

AI 帮你画模板、点一下就云打印：sv-print 这三个月都干了啥

AI 帮你画模板、点一下就云打印：sv-print 这三个月都干了啥

一、新插件篇：这一波最大的变化

1. @sv-print/plugin-cloud 云服务插件 🌩️

2. @sv-print/plugin-view-ai AI 辅助设计 🤖

3. @sv-print/plugin-view-data-source 数据源插件 🗂️

4. 元素插件三连：骑缝章、PDF 元素、元素工具集 🖋️

骑缝章 @sv-print/plugin-ele-seal

PDF 元素 @sv-print/plugin-ele-pdf

元素工具集 @sv-print/plugin-view-ele-tools

5. 导出三连：矢量 PDF、Word、Excel 增强 📦

矢量 PDF @sv-print/plugin-api-pdf-vector

Word 导出 @sv-print/plugin-api-word

Excel 导出增强 @sv-print/plugin-api-excel

骑缝章、PDF、Word 这几个渲染器资源，客户端里也能在线下载更新

6. 新手引导 @sv-print/plugin-driver 🧭

7. 参数修改 @sv-print/plugin-options-modify 弹窗式下拉

8. 国际化 @sv-print/plugin-i18n 继续补 🔤

9. 编辑器 @sv-print/plugin-view-code-edit 📝

10. 格式化器 @sv-print/plugin-formatter 占位符匹配

二、设计器本体：不太起眼但很顶的那些

1. 设置弹窗 + onSettings hook + header 外部更新

2. beforeGetHtml 这条 hook 线

3. 表格能力

4. 交互细节

5. CLI 支持 dev 环境

三、静默打印客户端 2.0.9

1. 纸张管理（这个我觉得该单独吹一下）📄

2. 调试能力

3. 打印日志能改能重打

4. print 接口现在会等任务跑完

5. 其他

⚠️ 升级提醒

写到最后

AI 流式输出都用 SSE，什么时候必须换 WebSocket？

裸 EventSource 和 WebSocket

裸 EventSource 的坑在哪？

WebSocket 的坑呢？

生产级的 SSE 客户端长什么样

讲一讲遇到的一些坑

Nginx 吞流，首字永远慢

浏览器同域连接上限，SSE 会断开其他请求

断线重连导致消息重复

网关空闲超时切断 和 移动端切后台直接失联

什么时候必须换 WebSocket

CPU就行, 老照片变清晰, 本地部署582mb腾讯的模型, 本地部署, 过节了给长辈们变个小魔术

流程图

1 痛点

2 两个模型怎么分工

3 有显卡自动加速

4 装环境不用踩坑

5 权重下载不断线

6 接口简单，模型带缓存

7 跑起来

总结

栗子前端技术周刊第 150 期 - Stack Overflow 开发者调查结果、TanStack Start 1.0...

📰 技术资讯

📒 技术文章

🔧 开发工具

从零构建 Mastra RAG MVP：DeepSeek、SiliconFlow 与 PostgreSQL/pgvector 实战

一、先理解要实现的 RAG 链路

二、项目初始化

PostgreSQL 的准备工作

三、配置 SiliconFlow Embedding

坑一：Embedding 请求返回 404

坑二：Embedding 请求返回 401

四、配置 PostgreSQL 向量存储

坑三：Vector table 不存在

五、将 Markdown 切分并导入向量库

编写导入脚本

六、先不接 Agent，验证向量检索

七、将检索包装成 Mastra Tool

八、使用 DeepSeek 创建 Knowledge Agent

九、调试 Agent 的 Tool Calls

实际运行结果

关于来源引用

十、package.json 脚本汇总

十一、MVP 已经完成什么，还缺什么？

十二、总结

1. `@sv-print/plugin-cloud` 云服务插件 🌩️

2. `@sv-print/plugin-view-ai` AI 辅助设计 🤖

3. `@sv-print/plugin-view-data-source` 数据源插件 🗂️

骑缝章 `@sv-print/plugin-ele-seal`

PDF 元素 `@sv-print/plugin-ele-pdf`

元素工具集 `@sv-print/plugin-view-ele-tools`

矢量 PDF `@sv-print/plugin-api-pdf-vector`

Word 导出 `@sv-print/plugin-api-word`

Excel 导出增强 `@sv-print/plugin-api-excel`

6. 新手引导 `@sv-print/plugin-driver` 🧭

7. 参数修改 `@sv-print/plugin-options-modify` 弹窗式下拉

8. 国际化 `@sv-print/plugin-i18n` 继续补 🔤

9. 编辑器 `@sv-print/plugin-view-code-edit` 📝

10. 格式化器 `@sv-print/plugin-formatter` 占位符匹配

1. 设置弹窗 + `onSettings` hook + header 外部更新

2. `beforeGetHtml` 这条 hook 线

4. `print` 接口现在会等任务跑完

裸 `EventSource` 和 `WebSocket`

裸 `EventSource` 的坑在哪？

`WebSocket` 的坑呢？

生产级的 `SSE` 客户端长什么样

`Nginx` 吞流，首字永远慢

浏览器同域连接上限，`SSE` 会断开其他请求

网关空闲超时切断和移动端切后台直接失联

什么时候必须换 `WebSocket`

第三板斧：节流更新，别让解析退化成 $O(n^2)$ （防卡顿）