opentui

OpenTUI 技能

权威参考文档位于同级的 docs/**/*.mdx 文件中。

在 OpenTUI 仓库中，此技能的根目录为 packages/web/src/content/。从仓库根目录访问时，同一批文件位于 packages/web/src/content/docs/**/*.mdx。

终端布局默认设置

请针对终端应用而非浏览器进行设计。高效利用可用的列和行。

• 相邻 UI 面板之间不要留空隙。
• 不要添加不必要的外边距或内边距。
• 优先采用紧凑、信息密集的布局，而非网站风格的卡片间距。

路径不变规则

• /docs 对应 docs/getting-started.mdx。
• /docs/components 对应 docs/components/overview.mdx。
• 其他所有 /docs/<slug> URL 都对应相对于此技能根目录的 docs/<slug>.mdx。
• 从仓库根目录访问时，在每个源路径前加上 packages/web/src/content/。
• /docs/releases/<version> 对应 docs/releases/<version>.md，即该版本的发行说明。

版本

文档描述的是此技能所对应的发行版或分支。每份发行说明都会列出该版本的变更，并链接到受影响的页面。当项目使用的 @opentui/core 版本早于文档所述版本时，请先阅读较新发行版的说明，再使用 API，并优先使用项目当前版本提供的内容。

选择软件包

可以直接使用 Core，也可以为 UI 选择 React 或 Solid 绑定。功能适合时，再推荐配套软件包。不要默认安装所有软件包。

• @opentui/core：使用 createCliRenderer() 和命令式可渲染对象及事件。
• @opentui/react：使用 createRoot() 和 React 组件、JSX 及 hooks。
• @opentui/solid：使用 render() 和 Solid 组件、JSX 及 signals。
• @opentui/keymap：在各视图间集中管理键盘绑定和命名命令。 此软件包支持焦点作用域层、可配置快捷键和多键序列。 从 @opentui/keymap/opentui 中的 createDefaultOpenTuiKeymap() 开始使用。 使用 @opentui/keymap/react 或 @opentui/keymap/solid 中的 providers 和 hooks。 对于简单的本地输入，使用直接键盘事件或组件本地绑定即可。
• @opentui/ssh：向标准 SSH 客户端提供终端 UI，无需在本地安装应用。 从软件包根目录导入 createServer()。将每个会话的 renderer 传递给 Core、React 或 Solid。 此软件包没有框架子路径。请阅读 SSH 指南，了解身份验证、中间件和会话清理。
• @opentui/qrcode：编码 QR 矩阵、终端文本或 SVG，也可以显示 QRCodeRenderable。对于 JSX，请使用 @opentui/qrcode/react 或 @opentui/qrcode/solid 中的 registerQRCode()。请参阅 QR 码组件。
• @opentui/three：使用 ThreeRenderable 在终端中渲染 Three.js WebGPU 场景。 此集成仅支持 Bun。选择使用前，请检查其运行时和依赖项要求。

完整的公共导入列表请参阅软件包入口点。 该列表包含测试、附加组件、宿主适配器和运行时模块映射。 使用 API 和符号索引查找导出项。 请使用公共软件包入口点，而非深入导入源文件。

按领域排列的阅读顺序

• 入门：/docs、/docs/getting-started/quickstart、/docs/getting-started/runtime-support
• 框架：/docs/bindings/react、/docs/bindings/solid
• 核心：/docs/core-concepts/renderer、/docs/core-concepts/layout、/docs/core-concepts/keyboard
• 组件：/docs/components、/docs/components/text、/docs/components/input、/docs/components/image、/docs/components/embedded-terminal
• 应用 API：/docs/core-concepts/clipboard、/docs/core-concepts/audio、/docs/application-apis/audio-streaming、/docs/application-apis/audio-capture、/docs/application-apis/animation
• 测试与调试：/docs/core-concepts/testing、/docs/test-and-debug/troubleshooting
• 扩展：/docs/plugins/slots、/docs/extend/runtime-plugins
• 按键映射：/docs/keymap/overview
• 集成：/docs/reference/ssh、/docs/reference/three、/docs/reference/qr-encoder
• 原生：/docs/native/overview
• 发布：/docs/ship/deploy、/docs/reference/standalone-executables
• 参考：/docs/reference/api-index、/docs/reference/package-entrypoints、/docs/reference/env-vars、/docs/reference/native-image

按意图快速查找

Intent(s)	Start here
getting-started, intro, examples, agent-skill	docs/getting-started.mdx
installation, quickstart	docs/getting-started/quickstart.mdx
runtime-support, bun, nodejs, native-artifacts, ffi, permissions, libc, runtime-assets	docs/getting-started/runtime-support.mdx
react, jsx, hooks, keyboard, paste, focus, blur, selection, animation, testing	docs/bindings/react.mdx
solid, jsx, signals, hooks, keyboard, animation, testing	docs/bindings/solid.mdx
core, renderer, terminal, scrollback, lifecycle	docs/core-concepts/renderer.mdx
layout, flexbox, yoga, positioning	docs/core-concepts/layout.mdx
keyboard, input, keybindings, paste, focus	docs/core-concepts/keyboard.mdx
components, component, component-support, support-matrix, react-components, solid-components	docs/components/overview.mdx
text, styling, content, selection	docs/components/text.mdx
input, form, editing, focus	docs/components/input.mdx
image, image-renderable, image-display, kitty, sixel	docs/components/image.mdx
embedded-terminal, terminal-renderable, ghostty, vt, pty	docs/components/embedded-terminal.mdx
clipboard, copy, osc52, host-clipboard	docs/core-concepts/clipboard.mdx
audio, native-audio, sound, playback, mixer, devices, tap	docs/core-concepts/audio.mdx
audio-streaming, audio-stream, pcm, f32le, radio, mp3, flac, icy, backpressure, reconnect	docs/application-apis/audio-streaming.mdx
audio-capture, microphone, pcm, recording, wav, audio-recorder	docs/application-apis/audio-capture.mdx
animation, timeline, easing, use-timeline	docs/application-apis/animation.mdx
testing, test-renderer, snapshots, frames	docs/core-concepts/testing.mdx
troubleshooting, terminal-reset, ffi-errors, native-loading, runtime-plugins, protocols, test-timeouts	docs/test-and-debug/troubleshooting.mdx
plugins, plugin, slots, registry, extensions	docs/plugins/slots.mdx
runtime-plugins, dynamic-import, external-modules, bun-plugin, module-maps, plugin-loading	docs/extend/runtime-plugins.mdx
keymap, keybindings, shortcuts, commands, leader, ex-commands	docs/keymap/overview.mdx
ssh, remote-tui, ssh-server, authentication, middleware	docs/reference/ssh.mdx
three, threejs, webgpu, 3d, sprites, physics	docs/reference/three.mdx
qr, qrcode, qr-encoder, svg-qr, gs1, eci, structured-append	docs/reference/qr-encoder.mdx
deploy, bundle, bun-executable, nodejs-esm, node-sea, ssh-deployment	docs/ship/deploy.mdx
standalone, executable, bun-compile, node-sea, node-assets	docs/reference/standalone-executables.mdx
api, symbols, exports, public-api, api-index, lookup	docs/reference/api-index.mdx
native, native-rendering, native-scene, native-api	docs/native/overview.mdx
package-exports, entrypoints, subpath-exports, imports	docs/reference/package-entrypoints.mdx
env, environment, configuration, flags	docs/reference/env-vars.mdx
native-image, image-decode, png, jpeg, webp, gif, rgba, pixels, resize	docs/reference/native-image.mdx

对于组件请求，请阅读 docs/components/overview.mdx，然后打开 docs/components/<name>.mdx。对于插件插槽详情，请从 docs/plugins/slots.mdx 开始，然后打开 Core、React 或 Solid 页面。

对于原生应用，请依次阅读 docs/native/overview.mdx、docs/native/resources.mdx 和 docs/native/frames.mdx。 docs/native/core.mdx 说明的是 Core 的 TypeScript 集成，而不是原生语言 API。 如需了解 Session 时钟、终端传输和原生文件操作，请阅读 docs/native/host-io-time.mdx。 然后选择 docs/native/c.mdx 或 docs/native/zig.mdx 来编写原生程序。

当前技能入口页面

• docs/getting-started.mdx
• docs/getting-started/quickstart.mdx
• docs/getting-started/runtime-support.mdx
• docs/bindings/react.mdx
• docs/bindings/solid.mdx
• docs/core-concepts/renderer.mdx
• docs/core-concepts/layout.mdx
• docs/core-concepts/keyboard.mdx
• docs/components/overview.mdx
• docs/components/text.mdx
• docs/components/input.mdx
• docs/components/image.mdx
• docs/components/embedded-terminal.mdx
• docs/core-concepts/clipboard.mdx
• docs/core-concepts/audio.mdx
• docs/application-apis/audio-streaming.mdx
• docs/application-apis/audio-capture.mdx
• docs/application-apis/animation.mdx
• docs/core-concepts/testing.mdx
• docs/test-and-debug/troubleshooting.mdx
• docs/plugins/slots.mdx
• docs/extend/runtime-plugins.mdx
• docs/keymap/overview.mdx
• docs/reference/ssh.mdx
• docs/reference/three.mdx
• docs/reference/qr-encoder.mdx
• docs/native/overview.mdx
• docs/ship/deploy.mdx
• docs/reference/standalone-executables.mdx
• docs/reference/api-index.mdx
• docs/reference/package-entrypoints.mdx
• docs/reference/env-vars.mdx
• docs/reference/native-image.mdx

工作规则

• 先阅读入口页面，再阅读与任务相关的更具体的规范页面。
• 直接阅读同级的 docs/**/*.mdx 文件。不要将其中的文字复制到此文件中。
• 页面之间的引用请使用规范的 /docs URL。 本文件中的链接请使用对应的相对 docs/**/*.mdx 路径。