OpenMax
免费试用

调试面板

Chat SDK 3.0 调试面板(Devtools):一个只读的浮层,看每个打开的会话在消息仓库里的窗口、改动日志、发送、本机存储、实时连接和最近的仓库事件。单独一个入口,不引入就不进你的包。

调试面板

调试面板是一个浮在页面上的只读面板,给接入 SDK 的开发和测试用:消息不见了、重复了、顺序不对,或者重连后没补上时,打开它就能看到消息仓库此刻在想什么,不用加日志、不用重现第二遍。思路和 React Query Devtools 一样:一个单独的入口,由你决定在哪些环境里引入、怎么打开。

它是什么

  • SDK 里的一个入口。 面板随 @openmaxai/chat-sdk 发布,在 @openmaxai/chat-sdk/devtools 入口下。只从这里引入,不用另外装包。
  • 不引入就不在包里。 @openmaxai/chat-sdk 的其他入口都不引用它;你的代码不 import @openmaxai/chat-sdk/devtools,打包结果里就没有面板的任何代码。
  • 环境和打开方式由你定。 面板不看 NODE_ENV,也不判断是不是生产环境:在哪些环境里引入、用哪个快捷键或 URL 参数打开,都由你在宿主里决定。
  • 只读。 面板只经仓库公开的检查接口读数据:不写仓库、不发请求、不碰本机存储,打开和关上它不改变聊天的任何行为。见只读保证。

安装与引入

面板随 @openmaxai/chat-sdk 一起装好,不用另外安装。把 ChatDevtools 放在 ChatProvider 里面任意位置,它读的是这个 Provider 的宿主的仓库和实时连接:

app.tsx

import { ChatDevtools } from "@openmaxai/chat-sdk/devtools";
import { ChatProvider } from "@openmaxai/chat-sdk/react";

export function App() {
  return (
    <ChatProvider host={host}>
      <Chat />
      <ChatDevtools />
    </ChatProvider>
  );
}

这样写会把面板打进所有环境的包里。只想在非生产环境里有它,见下面的只在非生产环境启用。

ChatDevtools 放好之后默认是收起的,只在页面上挂一个键盘监听,不画任何东西。

只在非生产环境启用

推荐用动态 import(),并由一个构建期就确定的常量决定要不要走这一支:常量为假时打包工具把整支连同 import() 删掉,生产包里没有面板的代码,URL 参数和快捷键也就都不起作用。

chat-devtools-slot.tsx

import { lazy, Suspense } from "react";

// 构建期常量:生产构建里是字面量 false,下面整支被删掉。
const devtoolsEnabled = process.env.NODE_ENV !== "production";

const ChatDevtools = devtoolsEnabled
  ? lazy(() =>
      import("@openmaxai/chat-sdk/devtools").then((m) => ({ default: m.ChatDevtools })),
    )
  : null;

export function ChatDevtoolsSlot() {
  if (!ChatDevtools) return null;
  return (
    <Suspense fallback={null}>
      <ChatDevtools shortcut="Alt+Shift+D" urlParam="chat-devtools" />
    </Suspense>
  );
}

app.tsx

<ChatProvider host={host}>
  <Chat />
  <ChatDevtoolsSlot />
</ChatProvider>

常量用你的构建工具在构建期替换的那种(Next.js 的 NEXT_PUBLIC_*、Vite 的 import.meta.env.*)。换成运行期才知道的值(比如从接口读的开关)也能用,只是面板的代码会留在包里,用 import() 分出的一块按需加载。

怎么打开

方式 默认 说明
快捷键 Alt+Shift+D 按一次打开,再按一次收起。shortcut 换成别的组合,给 false 关掉。焦点在输入框里时也生效
URL 参数 chat-devtools 页面地址带 ?chat-devtools=1 时,加载后直接打开。urlParam 换参数名,给 false 关掉。只在加载时读一次
你自己控制 — 给 open 和 onOpenChange,由你决定什么时候开(比如设置页里的一个开关)。这时快捷键和 URL 参数照样会调 onOpenChange

面板打开后浮在页面一角,不挡住聊天的点击,可以收成一个小按钮。

面板里有什么

顶部是会话选择:列出此刻打开着的会话(补洞在跟的那些),默认选中最近打开的那个;也可以切到仓库里加载过、已经关掉的会话(这时只剩水位)。下面按区块显示选中会话的状态,最后是全局的存储、实时连接和事件记录。数据变了面板跟着刷新,每帧最多刷新一次。

窗口

内存里这个会话的已加载区间。

显示 说明
seq 范围 区间覆盖的第一个和最后一个 seq,以及「更早还有 / 更新还有」
条数 区间里的服务端消息条数和上限(500)。本端的消息不算,在发送里
水位 已经连续拿到的最大 seq
缺口 仓库知道还没拿到的 seq 段:区间末尾到水位之间(迟到的一窗、水位那条被删),或水位之后推送来过、没接进来的。没有缺口时显示「无」
补洞 正在补(以及补完后是否还要再补一次);上一次补洞的触发时刻、结果(caughtUp、reloaded 等)、轮数和多久以前

改动日志

按改动日志补改动的进度。

显示 说明
本机改动水位 这个会话已经生效到哪一笔改动
服务端最新编号 最近一次从服务端读到的最新改动编号。比本机改动水位大,说明还有改动没补
先到的编号 推送跳了号时先到、在等前面那几笔的编号
上一次补改动 结果、取了几轮改动日志、按 id 取回了几条、说不在了几条,以及服务端是否说「太旧了」(tooOld,这时换入了最新一窗或作废了本机那一段)

发送

显示 说明
本端消息 发送中、失败、被拦,以及已确认、服务端那条还没对上的消息:client_msg_id、状态、对上之后服务端那条的 id
在途改动 自己的表态、编辑、撤回还没有结果的那几条消息,以及请求已成功、在等服务端那条带回新内容的

本机存储

显示 说明
存储 用的是 IndexedDB、内存,还是你自己实现的 ChatStorage;配了 IndexedDB 却在用内存时,显示原因(另一个标签页拿着锁、浏览器没有 Web Locks、IndexedDB 打不开)
标签页锁 这个标签页是否拿着本机数据的锁
加密 是否打开了静态加密
大约大小 浏览器估计的这个站点已用的存储和配额(整个站点,不只是聊天),打开面板时读一次,可以手动刷新
写入 排着没写完的写入数,最近一次写失败的原因和时间,因配额淘汰过几个会话
这个会话 区间是否在往本机写、本机那一段的 seq 范围

实时连接

显示 说明
连接状态 SDK 这一侧看得到的连接状态:idle(还没有聊天视图订阅,适配器还没被要求建连)、started(已要求适配器建连;它不报告此刻是连着还是在重连)、closed(宿主已 dispose),或 off(适配器没有实时通道)
连接状态(之后) 和 useConnectionStatus 同一个值(connected、reconnecting 等),以及补洞是否一直失败,等这个 hook 有了之后 规划中
最后一帧 适配器最后一次交给 SDK 入站信号的时间。心跳不算信号,所以会话安静时连接正常这个时间也会变旧
最后一个信号 补洞调度器收到的最后一个实时信号(新消息、重连成功、改动跳号)和它属于哪个会话

事件记录

最近 50 条仓库事件,新的在上。每条是一次 dispatch 的事件(类型、会话、涉及的消息 id 和 seq、谁发出的:你的代码、补洞、取数协调还是本机读回)和它给区间带来的变化,补洞的开始与结束、本机数据的打开、清掉和写失败也在里面。可以按会话过滤。

复制按钮把这 50 条按 JSON 复制到剪贴板,方便贴进 issue。默认不含消息正文和附件名,只有 id、seq、状态这类字段;要带正文给 includeMessageContent。面板挂上之后就开始记,收起时也记,所以打开时能看到打开之前发生的事。

只读保证

  • 只读仓库公开的检查接口。 面板拿到的都是快照的副本;它不调 dispatch,不调补洞调度器、取数协调器,不调 ChatStorage 的任何方法,不发网络请求。
  • 不改变聊天的行为。 挂上、打开、收起、卸掉面板,消息、补洞、本机存储和实时连接的行为都和没有面板时一样。检查接口自己的保证见检查接口 · 保证。
  • 不留东西。 面板不往 localStorage、sessionStorage、IndexedDB 或 Cookie 里写任何东西,刷新后回到收起状态(URL 参数除外)。
  • 复制只到剪贴板。 面板不上传任何东西。

不用 SDK 的宿主

直接用 @openmaxai/chat-store、不经 ChatProvider 的宿主,从 @openmaxai/chat-sdk/devtools 引入 ChatDevtoolsPanel,自己把仓库交进去。实时连接那一块要你给 connection,不给就不显示:

store-devtools.tsx

import { ChatDevtoolsPanel } from "@openmaxai/chat-sdk/devtools";

<ChatDevtoolsPanel
  store={store}
  connection={() => ({ status: socket.status, lastFrameAt: socket.lastFrameAt })}
/>;

API

ChatDevtools

从 @openmaxai/chat-sdk/devtools 引入,必须在 ChatProvider 里。

Prop 类型 默认值 说明
shortcut string | false "Alt+Shift+D" 打开、收起的快捷键,+ 连接,修饰键写 Ctrl、Alt、Shift、Meta,Mod 在 macOS 上是 Meta、其他系统是 Ctrl;按键按物理位置认(event.code),不受输入法和键盘布局影响。false 不监听
urlParam string | false "chat-devtools" 页面加载时 URL 带这个参数(值为 1 或 true)就直接打开。false 不读
defaultOpen boolean false 不受控时一开始是否打开
open boolean — 受控:是否打开
onOpenChange (open: boolean) => void — 快捷键、URL 参数、面板上的收起按钮要改变打开状态时调用
position "bottom-right" | "bottom-left" | "top-right" | "top-left" "bottom-right" 浮在哪个角
includeMessageContent boolean false 事件记录里显示、复制消息正文和附件名

ChatDevtoolsPanel

从 @openmaxai/chat-sdk/devtools 引入,不需要 ChatProvider。除 ChatDevtools 的全部 prop 外:

Prop 类型 说明
store ChatStore 必填,createChatStore 建的仓库
connection () => { status: string; lastFrameAt?: number } 可选,读实时连接的状态和最后一帧的时间(毫秒时间戳)。面板刷新时调它,要便宜、不能有副作用

入口与包

入口 里面有什么 依赖
@openmaxai/chat-sdk/devtools ChatDevtools,从 ChatProvider 取仓库和连接;ChatDevtoolsPanel,用你交进来的仓库 只经 @openmaxai/chat-store/inspect 读仓库;peer react 19

面板的样式随入口提供、只作用在面板自己的根元素里,不需要引入 CSS,也不受你的主题变量影响。

常见问题

生产环境里用户按了快捷键会怎样? 按只在非生产环境启用的写法,生产包里没有面板的代码,什么都不会发生。直接静态 import 的话,任何人按快捷键都能打开它;面板只读,但能看到消息 id 和会话 id。

面板会让聊天变慢吗? 收起时只在仓库事件发生时往一个 50 条的环形记录里追加一条,不重画。打开时每帧最多重画一次。仓库那一侧的开销见检查接口 · 保证。

能看到别的标签页的数据吗? 不能。面板看的是这个标签页里的仓库;另一个标签页拿着本机数据的锁时,这里显示「内存(另一个标签页拿着锁)」。