调试面板
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 条的环形记录里追加一条,不重画。打开时每帧最多重画一次。仓库那一侧的开销见检查接口 · 保证。
能看到别的标签页的数据吗? 不能。面板看的是这个标签页里的仓库;另一个标签页拿着本机数据的锁时,这里显示「内存(另一个标签页拿着锁)」。
