使用 openuidev/devtools 调试 OpenUI 应用Inspect 事件面板与 Debug 工作台实战指南【免费下载链接】openuiThe Open Standard for Generative UI项目地址: https://gitcode.com/gh_mirrors/openui1/openuiopenuidev/devtools是 OpenUI 生态中的开发期专属 UI 组件它渲染一个悬浮按钮点击后打开OpenUI Inspect面板集中展示由openuidev/observability捕获的事件流并可进一步进入OpenUI Debug工作台对 Stream 事件进行解析、校验与回放调试。本文基于当前仓库 packages/devtools 的源码与文档讲解该包的自动/手动挂载方式、全部 Props 含义、CDN 版本固定策略、CSP 约束以及底层实现原理帮助你将其无缝集成进自己的 OpenUI 应用。一、包定位开发期的事件调试 UIopenuidev/devtools是一个Development-only仅开发期的 UI 组件。它本身不采集任何数据只负责把openuidev/observability已经捕获到的事件以可视化列表的形式呈现出来页面右下角默认位置出现一个悬浮圆形按钮点击后展开OpenUI Inspect抽屉按时间倒序列出事件每个 Stream 事件附带Debug按钮点击可打开OpenUI Debug工作台对事件对应的渲染结果进行编辑器级调试。从 package.json 可以看到该包的 peerDependencies 包含openuidev/observability0.0.4 0.1.0与openuidev/react-lang0.3.0 0.4.0可选这正是它与事件总线、渲染协议之间的依赖关系事件来自 observability 总线而 Debug 的渲染能力则复用 react-lang 的Renderer。二、快速开始自动挂载与手动挂载2.1 自动挂载推荐如果你的应用使用了openuidev/react-langwidget 会自动出现无需任何额外代码。这一机制实现在 packages/react-lang/src/devtoolsBootstrap.ts模块仅在process.env.NODE_ENV development时作为顶层副作用执行它通过Symbol.for(openui.devtools.autoMount)标记保证每个 JS realm 只自动挂载一次即使 ESM/CJS 双构建或存在多个包版本副本自动挂载时渲染的是与手动挂载完全相同的公开入口OpenUIDevtools /并传入version: 0与__autoMounted: true在 production 构建中该代码块会被打包器按NODE_ENV条件折叠openuidev/devtools根本不会进入生产依赖图。注意自动挂载只在NODE_ENV development时触发严格等于development而非! production这会把 Jest 等 jsdom 测试环境NODE_ENV test也排除在外。2.2 手动挂载你也可以在应用的任意位置自行挂载所有 Props 都会被原样转发给内部 widgetimport { OpenUIDevtools } from openuidev/devtools; function App() { return ( {/* your app */} OpenUIDevtools themedark positionbottom-left maxEvents{100} / / ); }手动挂载的实例永远优先于自动挂载实例——无论挂载多少次同一时刻只有一个实例真正渲染详见下文单例选举。三、Props 完整参考Prop默认值说明enableddev-only强制开启/关闭 widget。显式传入后生产构建也可强制显示。positionbottom-right悬浮按钮所在的角落top-left/top-right/bottom-left/bottom-right。maxEvents50保留的事件数量上限超出后最旧的事件先被丢弃。errorsOnlytrue只捕获 error/warning 级别事件还是捕获全部事件。autoOpenOnErrortrue出现错误时自动打开面板设置的初始状态。themelightwidget 界面主题light或dark面板内的 Settings 可覆盖。versionlatestCDN 版本固定0major/0.1minor/0.1.0精确省略则使用latest。3.1 类型定义与约束Props 的类型定义位于 packages/devtools/src/types.tsDevtoolsPosition精确枚举了四个角落version有严格校验必须是 major0、minor0.1或精确0.1.0三种形式之一其他字符串会被拒绝widget 不会挂载__autoMounted是内部标记由 react-lang 自动挂载传入用于单例选举非公开 API。3.2 关于 theme 的行为细节根据 types.ts 的注释如果显式传入了theme它将覆盖存储的 Settings 选择并被写入配置否则使用用户已存储的主题最后回退到light。widget 主题永远不会从宿主页面或操作系统自动探测——它只受 Props 与面板内 Settings 控制。四、实现原理薄包装 CDN 浏览器构建openuidev/devtools的 npm 包是一个薄宿主包装。理解这一点对排查问题很有帮助。4.1 双入口架构npm 包入口packages/devtools/src/OpenUIDevtools.tsx一个渲染null的 React 组件只在useEffect中调用mountOpenUIDevtoolsFromCdn浏览器构建dist/devtools.browser.js源码入口 packages/devtools/src/browser.ts完整的 Inspect/Debug UI运行时由薄包装动态拉取。这种拆分的好处是宿主应用的 React 依赖不会被复制两份widget 使用的是宿主自身的 React / ReactDOM / react-lang。4.2 CDN 加载与版本固定加载逻辑在 packages/devtools/src/cdn.tsconst VERSION_RE /^\d(\.\d){0,2}$/; export function normalizeCdnVersion(version?: string): string | null { const trimmed version?.trim(); if (!trimmed) return latest; return VERSION_RE.test(trimmed) ? trimmed : null; }省略version或传空字符串 → 使用latest传入非法字符串 → 返回null控制台打印警告提示应使用0/0.1/0.1.0widget 不挂载最终 URL 形如https://cdn.jsdelivr.net/npm/openuidev/devtoolstag/dist/devtools.browser.js对于非精确版本major/minor tagURL 会追加?t时间戳参数按 5 分钟粒度取整以规避 jsDelivr 对 tag 别名的缓存保证发布新版本后能及时拿到最新构建。发布机制发布该包的新版本会自动更新 jsDelivr 上的 CDN 文件无需额外 CDN 配置浏览器构建就是发布 tarball 内的dist/devtools.browser.js。4.3 宿主依赖注入browser.ts 中mountOpenUIDevtools通过参数接收宿主传入的React、ReactDOM、ReactDOMClient以及loadReactLang把它们填入模块级 slotpackages/devtools/src/browser-shims/slots.ts随后才动态import(./OpenUIDevtoolsWidget)渲染真实 UI。浏览器构建自身从不直接 importopenuidev/react-lang——这是刻意为之Debug 解析/渲染所需的 react-lang 由宿主模块图闭包提供。4.4 事件总线对接widget 挂载时从globalThis[Symbol.for(openui.observability)]读取事件总线。如果找不到总线说明宿主未先 importopenuidev/observability会打印警告并放弃挂载不影响应用其余部分。4.5 单例选举packages/devtools/src/lib/singleton.ts 实现了一个跨实例、甚至跨包副本共享的单例注册表键为Symbol.for(openui.devtools.singleton)选举规则手动挂载实例 自动挂载实例同优先级按挂载先后先挂载者胜出当当前 owner 卸载时下一个候选自动接管这正是 README 中手动挂载永远胜过自动挂载、同一时刻只有一个实例渲染的底层实现。4.6 事件缓冲与去重packages/devtools/src/lib/eventBuffer.ts 的addOrReplaceEvent负责维护事件列表以event.detail.id字符串作为稳定 ID新事件到来时先剔除同 ID 的旧事件再加入队首最终用slice(0, maxEvents)截断超出上限的最旧事件被丢弃——对应maxEventsProp。五、生产环境行为widget 默认在NODE_ENV production时不渲染任何内容OpenUIDevtools.tsx与OpenUIDevtoolsWidget.tsx中均有enabled ?? (process.env.NODE_ENV ! production)的判断。两种例外显式传入enabled{true}强制显示显式传入enabled{false}强制隐藏可用于开发期关闭。六、CSP内容安全策略注意事项widget 通过运行时 fetch 加载cdn.jsdelivr.net上的浏览器构建因此script-src必须允许cdn.jsdelivr.net否则 fetch 会失败。如果被 CSP 拦截widget 会静默消失应用其余部分不受影响。建议在开发环境的 CSP 中为script-src增加https://cdn.jsdelivr.net。七、OpenUI Debug 工作台7.1 从 Stream 事件进入 Debug开发环境中createLibrary()来自openuidev/react-lang会通过Symbol.for(openui.devtools.libraries)把活体 library注册给 widget见 packages/devtools/src/lib/libraryRegistry.tsLIBRARY_EVENT_KIND react-lang:library。Inspect 列表中每个 Stream 事件的Debug按钮会打开OpenUI Debug在独立的 tray 中呈现一个针对该 library 的编辑器包含宿主 CSS提供Render / Validation / Tree / JSON / Stream五个面板支持模拟 Stream 播放simulated stream playback。7.2 Debug 的渲染隔离Debug 通过宿主自己的Renderer渲染预览且其预览保持脱离事件总线——这意味着回放一个 Stream 时不会把新的卡片追加到 Inspect 列表避免调试过程污染事件流。7.3 弹出独立窗口调试packages/devtools/src/debug/eject.ts 提供openDebugWindow()打开一个命名的同源弹窗窗口名openui-debug并把宿主文档的 class、属性、color-scheme、link relstylesheet/style以及adoptedStyleSheets复制进弹窗从而让渲染预览在弹窗中也能解析与宿主一致的 CSS 环境。注意该函数必须在点击事件处理器内调用且不能传noopener需要拿到 Window 引用。八、开发与发布工作流openuidev/devtools当前版本为0.2.2脚本定义在 package.jsonpnpm buildtsdown构建 npm 包 scripts/build-browser.mjs生成浏览器构建pnpm testVitest 运行测试含 OpenUIDevtools.test.tspnpm typecheck/pnpm lint:check/pnpm format:check静态检查发布前会执行check:publint与check:attwprepublishOnly校验包导出形态与类型解析。需要指出的是浏览器构建属于发布产物devtools.browser.js的路径是打包后生成的而非源码中的文件若你想直接从源码理解完整 UI 结构可从 OpenUIDevtoolsWidget.tsx 入手它展示了 Inspect固定 480px 宽、贴右缘与 Debug占满剩余空间的 workspace 式面板的双 tray 布局、错误徽标按钮、设置菜单Auto-open on error / Show errors only / Theme以及Escape逐级关闭Debug → Inspect → 关闭的交互细节。九、典型接入清单应用引入openuidev/react-lang后开发环境自动获得 Inspect 悬浮按钮如需自定义手动渲染OpenUIDevtools /并传入 Props。显式传入version固定 CDN 版本推荐开发期固定 minor如0.1避免latest意外升级。检查 CSP确保script-src允许cdn.jsdelivr.net。按需调整maxEvents默认 50、errorsOnly默认只显示 error/warning、autoOpenOnError默认出错自动弹开面板与theme。生产构建无需任何改动——widget 默认不渲染确需在特殊环境显示时显式传enabled。通过上述配置你可以在不侵入应用代码的前提下获得一套完整的 OpenUI 事件可视化与 Stream 调试工作台将openuidev/observability捕获的运行时事件转化为可交互、可回放、可校验的开发体验。【免费下载链接】openuiThe Open Standard for Generative UI项目地址: https://gitcode.com/gh_mirrors/openui1/openui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考