Cline 中 OpenTUI Core 的六大核心模式：组合、事件、状态、生命周期、布局与调试

本篇技术指南以 Cline 仓库内置的 OpenTUI 技能参考文档 patterns.md 为主体，系统讲解 OpenTUI Core（@opentui/core）命令式 API 的六类核心模式：命令式与声明式组合、事件处理、状态管理、生命周期清理、响应式布局以及内置调试工具。读完本文，你可以直接在 Cline CLI 这类终端界面（TUI）项目上应用这些模式，并理解 Cline 自身在 apps/cli/src/tui/index.tsx 中是如何落地 createCliRenderer 与销毁流程的。

原文档位于 .agents/skills/opentui/references/core/patterns.md，是 OpenTUI 技能（入口见 .agents/skills/opentui/SKILL.md）中面向"实现指导"一层的参考文件；其配套的概念总览在 core/REFERENCE.md，完整 API 说明在 core/api.md。

两种组合模式：命令式 Renderable 与声明式 Constructs

OpenTUI Core 提供两套等价的组合路径。根据 core/REFERENCE.md 的对比表：命令式 Renderable 需要在创建时传入 renderer，直接通过方法变更；声明式 Constructs 创建的是 VNode，链式调用会被记录并在实例化时重放，写法更干净。两者可混用，最终都挂到 renderer.root 上。

命令式组合（Imperative Composition）

创建 Renderable 实例并用 .add() 组装成树：

import { createCliRenderer, BoxRenderable, TextRenderable } from "@opentui/core"

const renderer = await createCliRenderer()

// Create parent
const container = new BoxRenderable(renderer, {
  id: "container",
  flexDirection: "column",
  padding: 1,
})

// Create children
const header = new TextRenderable(renderer, {
  id: "header",
  content: "Header",
  fg: "#00FF00",
})

const body = new TextRenderable(renderer, {
  id: "body",
  content: "Body content",
})

// Compose tree
container.add(header)
container.add(body)
renderer.root.add(container)

关键点：renderer.root 是整棵 Renderable 树的挂载点（对应 core/api.md 中 renderer.root // Root renderable node 的说明），任何节点都可以通过 add / remove / getRenderable(id) 管理子节点。

Cline CLI 在认证流程中正是采用这条命令式路径：apps/cli/src/commands/auth.ts 中动态 await import("@opentui/core") 取得 createCliRenderer 并调用 createCliRenderer({...})，属于典型的"按需加载渲染器"写法。

声明式组合（Constructs）

使用 VNode 函数（Box、Text、Input 等）以函数调用形式组合：

import { createCliRenderer, Box, Text, Input, delegate } from "@opentui/core"

const renderer = await createCliRenderer()

// Compose as function calls
const ui = Box(
  { flexDirection: "column", padding: 1 },
  Text({ content: "Header", fg: "#00FF00" }),
  Box(
    { flexDirection: "row", gap: 2 },
    Text({ content: "Name:" }),
    Input({ id: "name", placeholder: "Enter name..." }),
  ),
)

renderer.root.add(ui)

从源码结构看，Constructs 返回的是 VNode 而非真实实例——renderer.root.add(ui) 时框架才会实例化并接入渲染循环。因此声明式写法特别适合封装成纯函数：给定 props 返回一棵 VNode 子树，天然便于复用与测试。

可复用组件：工厂函数与焦点委托

组件工厂函数

同一个"带标签输入框"可以用两种风格各写一份工厂：

// Imperative factory
function createLabeledInput(
  renderer: RenderContext,
  props: { id: string; label: string; placeholder: string }
) {
  const container = new BoxRenderable(renderer, {
    id: `${props.id}-container`,
    flexDirection: "row",
    gap: 1,
  })

  container.add(new TextRenderable(renderer, {
    id: `${props.id}-label`,
    content: props.label,
  }))

  container.add(new InputRenderable(renderer, {
    id: `${props.id}-input`,
    placeholder: props.placeholder,
    width: 20,
  }))

  return container
}

// Declarative factory
function LabeledInput(props: { id: string; label: string; placeholder: string }) {
  return delegate(
    { focus: `${props.id}-input` },
    Box(
      { flexDirection: "row", gap: 1 },
      Text({ content: props.label }),
      Input({
        id: `${props.id}-input`,
        placeholder: props.placeholder,
        width: 20,
      }),
    ),
  )
}

命名约定值得注意：命令式工厂以 createXxx 开头并显式接收 renderer；声明式工厂直接叫 Xxx 且不接收 renderer（VNode 延迟实例化，renderer 在挂载时提供）。

焦点委托（Focus Delegation）

delegate 把外层组件的 .focus() / .blur() 调用路由到内部嵌套元素——这是构建"看起来是一个组件、内部有多个可聚焦元素"的关键模式：

import { delegate, Box, Input, Text } from "@opentui/core"

const form = delegate(
  {
    focus: "email-input",     // Route .focus() to this child
    blur: "email-input",      // Route .blur() to this child
  },
  Box(
    { border: true, padding: 1 },
    Text({ content: "Email:" }),
    Input({ id: "email-input", placeholder: "[e-mail]" }),
  ),
)

// This focuses the input inside, not the box
form.focus()

没有 delegate 时 form.focus() 聚焦的是 Box 本身，输入框收不到按键；加上后调用方只面对一个统一接口。core/api.md 的 Constructs 一节给出了同一机制的最小示例（delegate({ focus: "email-input" }, Box(...))）。

事件处理：键盘、组件与鼠标三类

键盘事件

全局键盘事件统一挂在 renderer.keyInput 上，支持 keypress 与 paste 两个事件：

const renderer = await createCliRenderer()

// Global keyboard handler
renderer.keyInput.on("keypress", (key) => {
  if (key.name === "escape") {
    renderer.destroy()
    process.exit(0)
  }

  if (key.ctrl && key.name === "c") {
    // Ctrl+C handling (if exitOnCtrlC is false)
  }

  if (key.name === "tab") {
    // Tab navigation
    focusNext()
  }
})

// Paste events
renderer.keyInput.on("paste", (event) => {
  const text = decodePasteBytes(event.bytes)
  currentInput?.setValue(currentInput.value + text)
})

key 对象提供 name（"escape"、"tab"、"f1" 等）、ctrl、shift、meta、eventType（press/release/repeat）字段，详见 core/api.md 的 Keyboard Input 一节。两点实践注意：

• Ctrl+C 的退出行为受 exitOnCtrlC 配置控制，默认 true。Cline 在 apps/cli/src/tui/index.tsx 中显式设置了 exitOnCtrlC: false，以便自己接管中断逻辑——这正是原文档注释 "if exitOnCtrlC is false" 指代的场景。
• 粘贴事件返回的是字节（event.bytes），需要用 decodePasteBytes 解码后再拼接进输入框。

另外，Cline 在创建渲染器时还开启了 enableMouseMovement: true（见 apps/cli/src/tui/index.tsx），为下面的鼠标事件做准备。

组件事件

每个 Renderable 有自己的事件常量族。以 InputRenderable 与 SelectRenderable 为例：

import { InputRenderable, InputRenderableEvents } from "@opentui/core"

const input = new InputRenderable(renderer, {
  id: "search",
  placeholder: "Search...",
})

input.on(InputRenderableEvents.CHANGE, (value) => {
  performSearch(value)
})

// Select events
const select = new SelectRenderable(renderer, {
  id: "menu",
  options: [...],
})

select.on(SelectRenderableEvents.ITEM_SELECTED, (index, option) => {
  handleSelection(option)
})

select.on(SelectRenderableEvents.SELECTION_CHANGED, (index, option) => {
  showPreview(option)
})

Select 的两个事件语义不同（core/api.md 中有明确区分）：ITEM_SELECTED 在按 Enter 确认选择时触发；SELECTION_CHANGED 在方向键浏览时触发，适合用来做选项预览。Input 必须处于聚焦状态（input.focus()）才能接收按键。

鼠标事件

鼠标回调直接作为 Renderable 的 props 传入（onMouseDown / onMouseUp / onMouseMove），这是实现按钮按压与悬停效果的常用手法：

const button = new BoxRenderable(renderer, {
  id: "button",
  border: true,
  onMouseDown: (event) => {
    button.setBackgroundColor("#444444")
  },
  onMouseUp: (event) => {
    button.setBackgroundColor("#222222")
    handleClick()
  },
  onMouseMove: (event) => {
    // Hover effect
  },
})

按下时变亮、抬起时恢复并触发点击，用颜色切换模拟 Web 端的 active 状态。

状态管理：闭包、类与焦点管理器

本地状态

原文档给出两种零依赖的状态管理方式，适合命令式 TUI：

闭包状态——用工厂函数把可变量封闭在私有作用域中：

function createCounter(renderer: RenderContext) {
  let count = 0

  const display = new TextRenderable(renderer, {
    id: "count",
    content: `Count: ${count}`,
  })

  const increment = () => {
    count++
    display.setContent(`Count: ${count}`)
  }

  return { display, increment }
}

类状态——当状态需要与多个方法协作时升级为类，注意把渲染句柄私有化、通过 getRenderable() 向外暴露：

class CounterWidget {
  private count = 0
  private display: TextRenderable

  constructor(renderer: RenderContext) {
    this.display = new TextRenderable(renderer, {
      id: "count",
      content: this.formatCount(),
    })
  }

  private formatCount() {
    return `Count: ${this.count}`
  }

  increment() {
    this.count++
    this.display.setContent(this.formatCount())
  }

  getRenderable() {
    return this.display
  }
}

两者的共同原则是：状态变更后必须显式调用渲染方法（如 setContent）触发更新——Core 是命令式 API，不会自动做响应式重渲染。这也是 core/REFERENCE.md 建议需要"细粒度响应式"时改用 @opentui/react 或 @opentui/solid reconciler 的原因；Cline CLI 主界面正是选择了 React 路线（apps/cli/src/tui/index.tsx 用 @opentui/react 的 createRoot 渲染 <Root/>），而认证等轻量流程仍走 Core 命令式路径。

焦点管理（Focus Management)

用注册表 + 索引指针实现 Tab 循环导航，是全文档中信息量最大的代码之一：

class FocusManager {
  private focusables: Renderable[] = []
  private currentIndex = 0

  register(renderable: Renderable) {
    this.focusables.push(renderable)
  }

  focusNext() {
    this.focusables[this.currentIndex]?.blur()
    this.currentIndex = (this.currentIndex + 1) % this.focusables.length
    this.focusables[this.currentIndex]?.focus()
  }

  focusPrevious() {
    this.focusables[this.currentIndex]?.blur()
    this.currentIndex = (this.currentIndex - 1 + this.focusables.length) % this.focusables.length
    this.focusables[this.currentIndex]?.focus()
  }
}

// Usage
const focusManager = new FocusManager()
focusManager.register(input1)
focusManager.register(input2)
focusManager.register(select1)

renderer.keyInput.on("keypress", (key) => {
  if (key.name === "tab") {
    key.shift ? focusManager.focusPrevious() : focusManager.focusNext()
  }
})

实现细节值得品味：正反向都用模运算取模（- 1 + length 保证反向索引不越界），形成真正的环形导航；?. 链式调用防御空表。这与键盘事件一节中 key.name === "tab" 的占位逻辑正好呼应——把 focusNext() 替换为 focusManager.focusNext() 即成完整方案。

生命周期模式：清理与动态更新

资源清理

原文档的核心主张是"永远清理资源"：定时器、渲染器都必须成对管理。

const renderer = await createCliRenderer()

// Track intervals/timeouts
const intervals: Timer[] = []

intervals.push(setInterval(() => {
  updateClock()
}, 1000))

// Cleanup on exit
process.on("SIGINT", () => {
  intervals.forEach(clearInterval)
  renderer.destroy()
  process.exit(0)
})

// Or use onDestroy callback
const renderer = await createCliRenderer({
  onDestroy: () => {
    intervals.forEach(clearInterval)
  },
})

onDestroy 回调在 core/api.md 的 createCliRenderer(config?) 配置项中列出，是框架级钩子，比手动监听 SIGINT 更可靠（覆盖所有退出路径）。

Cline 的生产实现展示了更完整的销毁序列，见 apps/cli/src/tui/index.tsx：

1. 监听 renderer.on("destroy", ...) 事件，在其中 unmount React 根、恢复被捕获的 stdio（restoreStdio()）；
2. destroy() 用 destroyStarted 标志做幂等保护；
3. 真正销毁前用 queueMicrotask 延迟一拍，"让 OpenTUI 解析完当前 stdin 批次再拆除"，并在 renderer 还活着时复位终端标题（setTerminalTitle("")），注释里特别说明了要在微任务执行时复查 renderer.isDestroyed，因为 OpenTUI 自身的信号处理器可能在这期间先销毁了渲染器。

这段代码印证了技能文档 core/gotchas.md 的关键规则：不要直接 process.exit()，应走 renderer.destroy() 让终端正确离开备用屏幕。

动态更新

外部数据驱动 UI 的通用形状：初始占位 + 拉取 + 周期性轮询：

async function createDashboard(renderer: RenderContext) {
  const statsText = new TextRenderable(renderer, {
    id: "stats",
    content: "Loading...",
  })

  // Poll for updates
  const updateStats = async () => {
    const data = await fetchStats()
    statsText.setContent(`CPU: ${data.cpu}% | Memory: ${data.memory}%`)
  }

  // Initial load
  await updateStats()

  // Periodic updates
  setInterval(updateStats, 5000)

  return statsText
}

注意这里返回的 statsText 是"活的句柄"——调用方拿到后既能挂载也能继续驱动更新。另外别忘了把 setInterval 的句柄收集起来交给上一小节的清理逻辑。

布局模式：响应式与分栏

响应式布局

利用 renderer.width 做尺寸断点，并监听终端 resize：

const renderer = await createCliRenderer()

const mainPanel = new BoxRenderable(renderer, {
  id: "main",
  width: "100%",
  height: "100%",
  flexDirection: renderer.width > 80 ? "row" : "column",
})

// Listen for resize
process.stdout.on("resize", () => {
  mainPanel.setFlexDirection(renderer.width > 80 ? "row" : "column")
})

宽终端横排双栏、窄终端竖排堆叠。补充一点：renderer.on("resize", (width, height) => {}) 事件在 core/api.md 的 Renderer Events 一节中有列出，可作为 process.stdout.on("resize") 的框架内替代方案。Cline 的 React 端则用 useTerminalDimensions() hook 获取 termWidth/termHeight（见 apps/cli/src/tui/root.tsx），实现思路一致。

分栏面板（Split Panels)

按比例拆分的可复用工厂：

function createSplitView(renderer: RenderContext, ratio = 0.3) {
  const container = new BoxRenderable(renderer, {
    id: "split",
    flexDirection: "row",
    width: "100%",
    height: "100%",
  })

  const left = new BoxRenderable(renderer, {
    id: "left",
    width: `${ratio * 100}%`,
    border: true,
  })

  const right = new BoxRenderable(renderer, {
    id: "right",
    flexGrow: 1,
    border: true,
  })

  container.add(left)
  container.add(right)

  return { container, left, right }
}

左栏用百分比宽度 ratio * 100%，右栏用 flexGrow: 1 吃掉剩余空间——百分比 + flex 扩展的组合是终端 Flexbox（基于 Yoga 布局引擎）里做固定比例分栏的标准做法。函数返回对象而非单个节点，调用方可以直接往 left / right 里填内容。

调试模式：控制台覆盖层与状态检查

内置 Console 覆盖层

OpenTUI 自带一个可开关的调试控制台，配置 consoleOptions 即可启用：

const renderer = await createCliRenderer({
  consoleOptions: {
    startInDebugMode: true,
  },
})

// Show console
renderer.console.show()

// All console methods work
console.log("Debug info")
console.warn("Warning")
console.error("Error")

// Toggle with keyboard
renderer.keyInput.on("keypress", (key) => {
  if (key.name === "f12") {
    renderer.console.toggle()
  }
})

consoleOptions 的完整形状（position、sizePercent、startInDebugMode）以及控制器的四个方法 show() / hide() / toggle() / clear()，均见 core/api.md 的 Console Overlay 一节。调试输出不再冲乱主界面，而是收进底部覆盖层，这是 TUI 调试与 Web 开发者工具最接近的体验。

状态检查（State Inspection)

轻量做法是把关键状态序列化成日志，借上面的控制台输出：

function debugState(label: string, state: unknown) {
  console.log(`[${label}]`, JSON.stringify(state, null, 2))
}

// In your update logic
debugState("form", { name: nameInput.value, email: emailInput.value })

统一打标签 + 缩进 JSON，便于在控制台覆盖层里按字段搜索。更系统的回归手段（快照测试、交互测试）见技能参考 testing/REFERENCE.md。

在 Cline 仓库中的对应关系与参考索引

把本文模式映射到 Cline 仓库的实际代码，可以快速建立"文档模式 → 生产代码"的索引：

模式	文档位置	Cline 仓库中的印证
createCliRenderer 配置（exitOnCtrlC: false）	patterns.md 键盘事件节	apps/cli/src/tui/index.tsx
渲染器销毁与 destroy 事件清理	patterns.md 生命周期节	apps/cli/src/tui/index.tsx
命令式 createCliRenderer 动态导入	patterns.md 命令式组合节	apps/cli/src/commands/auth.ts
终端尺寸驱动布局	patterns.md 响应式布局节	apps/cli/src/tui/root.tsx（useTerminalDimensions）
@opentui/core 版本（0.4.3）与 React reconciler 并存	core/REFERENCE.md	apps/cli/package.json

延伸阅读（均在仓库内）：

• core/REFERENCE.md——Core 适用场景、快速上手、Renderables 与 Constructs 对比；
• core/api.md——Renderer 配置项、各 Renderable 属性、事件常量、RGBA 颜色工具；
• core/configuration.md 与 core/gotchas.md——渲染器配置与常见坑；
• layout/patterns.md 与 keyboard/REFERENCE.md——更细的布局与输入处理。

适用前提提醒：以上代码面向 @opentui/core 0.4.x（Cline CLI 当前依赖版本，见 apps/cli/package.json），运行环境为 Bun（原生构建涉及 Zig）；create-tui 脚手架用于新建项目，本文模式则适用于在既有项目中直接嵌入 OpenTUI Core 的场景。