Cline OpenTUI Solid Reconciler 避坑指南：从终端退出、响应性陷阱到 Store 更新规则

本文基于 Cline 仓库内置的 OpenTUI 技能参考文档 .agents/skills/opentui/references/solid/gotchas.md 展开，系统梳理使用 @opentui/solid（SolidJS Reconciler）构建终端界面时的全部已知陷阱：为什么绝不能直接调用 process.exit()、bunfig.toml 与 tsconfig 的 JSX 配置如何决定项目能否跑起来，以及信号解构、onCleanup、Store 直接突变等响应性陷阱的成因与正确写法。读完后，你可以独立完成一个基于 OpenTUI Solid 的 TUI 项目搭建、排错与性能调优，并理解 Cline CLI 自身在 TUI 生命周期管理上的工程实践。

背景：OpenTUI 与 Solid Reconciler 在 Cline 中的位置

OpenTUI 是一个运行在 Bun 上的终端 UI 框架，提供三套入口：命令式 core API、React Reconciler 和 Solid Reconciler。Cline 仓库将这套知识沉淀为 Agent 技能文档 SKILL.md，其决策树建议：需要细粒度响应性（fine-grained reactivity）与最优重渲染行为时，选择 solid/ 分支，配套阅读顺序为 REFERENCE.md → api.md / configuration.md / patterns.md / gotchas.md，而本文对应的 gotchas.md 正是其中的排障入口。

从源码结构看，Cline 自身的 CLI TUI 就构建在 OpenTUI 之上：apps/cli/package.json 中固定依赖了 @opentui/core 与 @opentui/react（均为 0.4.3 版本），入口在 apps/cli/src/tui/index.tsx。虽然 Cline CLI 选用的是 React Reconciler，但 Solid 与 React 两个分支共享同一套 core 运行时，因此文档中的 renderer.destroy()、createCliRenderer 等核心结论对两者同样成立，而响应性部分（信号、Store、onCleanup）是 Solid 分支特有的关键差异。

Critical：永远不要直接调用 process.exit()

文档将其标注为“最常见的错误（the most common mistake）”：直接 process.exit() 会立刻杀死进程，跳过节流缓冲与终端状态恢复，导致终端停留在损坏状态——光标被隐藏、仍处在 raw mode、仍显示备用屏幕（alternate screen）。

// WRONG - 终端停留在损坏状态
process.exit(0)

// CORRECT - 使用 renderer.destroy()
import { useRenderer } from "@opentui/solid"

function App() {
  const renderer = useRenderer()

  const handleExit = () => {
    renderer.destroy()  // 清理后正常退出
  }
}

renderer.destroy() 会在退出前完成完整的终端恢复（退出备用屏幕、恢复光标等）。这一点在 Cline CLI 的实践中有完整印证，apps/cli/src/tui/index.tsx 展示了生产级写法：

renderer.on("destroy", () => {
  unmountRoot();      // 先卸载 React 根
  restoreStdio();     // 恢复被捕获的 stdio
  resolveExit?.();   // 解决退出 Promise
});

const destroy = () => {
  unmountRoot();
  // 等 OpenTUI 解析完当前 stdin 批次后再拆除
  queueMicrotask(() => {
    if (!renderer.isDestroyed) {
      renderer.setTerminalTitle("");
    }
    renderer.destroy();
  });
};

几个值得注意的工程细节：其一，通过 createCliRenderer({ exitOnCtrlC: false, ... }) 关闭框架默认的 Ctrl-C 退出，改由自己接管退出时机（apps/cli/src/tui/index.tsx）；其二，用 queueMicrotask 延迟调用 renderer.destroy()，让 OpenTUI 先把当前 stdin 事件批次消费完；其三，用 isDestroyed 标志位做重入保护，防止信号处理器与自定义退出路径竞争触发二次销毁。这些都是“绝不调用 process.exit()”这条规则在真实项目中的落地形态。

配置问题三件套：bunfig.toml、JSX 设置、构建插件

Solid 的 JSX 需要 Solid 编译器转换，这一链路涉及三处配置，任何一处缺失都会产生“看起来莫名其妙”的报错。

1. 缺失 bunfig.toml

症状：JSX 语法报错、组件不渲染，典型报错为 SyntaxError: Unexpected token '<'——因为源码里的 JSX 根本没被转换。

修复：在项目根目录创建 bunfig.toml：

preload = ["@opentui/solid/preload"]

该 preload 会在你的代码运行前加载 Solid JSX 转换器。preload 是 Bun 的通用机制——Cline 仓库中同样有实例：apps/vscode/bunfig.toml 通过 preload = ["./src/test/bun-test-preload.ts"] 在 bun test 时预加载测试桩模块（用作文本说明：该文件注释写明它用于在单元测试中遮蔽 vscode 与 @cline/core 模块）。可见 bunfig.toml 的 preload 数组是 Bun 项目的标准注入点，OpenTUI Solid 只是把它用作 JSX 编译器的挂载位置。

2. tsconfig 的 JSX 设置错误

症状：JSX 被编译成 React 调用，报“找不到 React”相关错误。

修复：确保 tsconfig.json 包含（此处引用仓库根路径仅示意位置，实际应配置在你自己的 TUI 项目中）：

{
  "compilerOptions": {
    "jsx": "preserve",
    "jsxImportSource": "@opentui/solid"
  }
}

同技能目录下的 configuration.md 给出了完整推荐配置，两个关键项的含义是：jsx: "preserve" 表示让 Solid 编译器（而非 tsc）处理 JSX，TypeScript 只负责类型检查；jsxImportSource: "@opentui/solid" 指定 JSX 运行时从 OpenTUI 而非 react/jsx-runtime 导入。完整模板还包括 "module": "NodeNext"、"moduleResolution": "NodeNext"、"strict": true 与 "types": ["bun-types"]。

3. 构建时未挂 Solid 插件

症状：产物 bundle 里残留原始 JSX 文本。

修复：在 Bun.build 中加入 Solid 插件：

import solidPlugin from "@opentui/solid/bun-plugin"

await Bun.build({
  entrypoints: ["./src/index.tsx"],
  outdir: "./dist",
  target: "bun",
  plugins: [solidPlugin],
})

如果目标是分发单文件可执行程序，可继续加 compile: { target: "bun-darwin-arm64", outfile: "my-app" }（支持 bun-linux-x64、bun-windows-x64 等平台组合）。注意 preload 只对 bun run 的运行时生效，一旦进入 Bun.build 打包流程，就必须显式挂 solidPlugin，这是两条互不重叠的编译路径。

项目起步方式

最省事的做法是用脚手架（注意 create-tui 的选项必须放在项目名之前）：

bunx create-tui@latest -t solid my-app
cd my-app && bun install

目录名必须尚不存在；可选项包括 --no-git（跳过 git init）与 --no-install（跳过安装）。手动搭建则需 bun install @opentui/solid @opentui/core solid-js，入口文件为：

import { render } from "@opentui/solid"
import { App } from "./App"

render(() => <App />)

响应性陷阱：信号、解构与 Effect

这是 Solid 与 React 心智模型差异最大的区域，也是 gotchas.md 篇幅最重的部分。

1. 忘记调用信号（Missing ()）

症状：数值永远不更新，界面显示 [Function]。

// WRONG - 缺少 ()
const [count, setCount] = createSignal(0)
<text>Count: {count}</text>  // 渲染出 [Function]

// CORRECT
<text>Count: {count()</text>

信号本身就是函数，调用才会触发读依赖并拿到当前值。

2. 解构 props 破坏响应性

症状：props 不再响应更新。

// WRONG - 只解构一次，之后永远不更新
function Component(props: { value: number }) {
  const { value } = props
  return <text>{value}</text>
}

// CORRECT - 保持对 props 对象的追踪
function Component(props: { value: number }) {
  return <text>{props.value}</text>
}

// OR 使用 splitProps
function Component(props: { value: number; other: string }) {
  const [local, rest] = splitProps(props, ["value"])
  return <text>{local.value}</text>
}

原因：Solid 的响应性建立在“对信号对象的属性访问被追踪”之上，const { value } = props 把当前值固化为普通变量，追踪链就此断开。splitProps 是官方提供的折中方案——它返回的 local 仍是响应式的代理对象，同时把剩余 props 分离出去传给子组件。

3. Effect 中未访问信号

症状：createEffect 只在初始时运行一次，之后永不触发。

// WRONG - effect 体内没有访问任何信号
const [count, setCount] = createSignal(0)

createEffect(() => {
  console.log("Count changed")  // 之后永远不会再运行！
})

// CORRECT - 在 effect 体内访问信号
createEffect(() => {
  console.log("Count:", count())  // count 变化时运行
})

createEffect 是惰性追踪：它只订阅在 effect 函数体执行期间被读取过的信号。没读，就没有依赖，自然不会重跑——这与“注册回调后被动触发”的直觉正好相反。

HTML 实体解码

Solid 的 reconciler 会自动对 JSX 文本内容解码 HTML 实体，<、>、& 等会渲染为字面字符：

<text>Use &lt;box&gt; for containers</text>  // 显示: Use <box> for containers
<text>A &amp; B</text>                        // 显示: A & B

该行为覆盖三类入口：文本节点（text nodes）、content prop 与 text prop。对 TUI 尤其有用——在终端里显示形如 <box> 的组件名、A && B 这类逻辑表达式时，无需手动做转义-反转义。

组件命名：下划线，不是连字符

Solid 分支中多词组件统一使用下划线（underscore），React 风格的连字符会直接报错：

// WRONG - React 风格命名（报错）
<tab-select />
<ascii-font />
<line-number />

// CORRECT - Solid 命名
<tab_select />
<ascii_font />
<line_number />

概念	React 写法	Solid 写法
Tab 选择器	<tab-select>	<tab_select>
ASCII 字体	<ascii-font>	<ascii_font>
行号组件	<line-number>	<line_number>

这条规则与 Cline 仓库中 React 分支的实际用法形成对照：apps/cli/src/tui/ 下的组件文件按驼峰命名（如 root.tsx 中的 <Root>），而 core 参考文档中提到的 tab-select 类连字符小写组件属于 React/core 生态。从两份技能文档的结构看，命名差异是 reconciler 层刻意区分的，混用会直接抛错。

焦点问题：显式 focus 与 Select 事件模型

1. 输入框需要显式 focused

// WRONG - 不会获得焦点
<input placeholder="Type here..." />

// CORRECT
<input placeholder="Type here..." focused />

终端没有鼠标“点击聚焦”的默认行为，focused 属性（或运行时焦点调度）是获得键盘输入的前提。

2. Select 不响应的两个原因

options 必须是结构化的选项对象，且组件需要焦点：

// WRONG
<select options={["a", "b"]} />

// CORRECT
<select
  options={[
    { name: "A", description: "Option A", value: "a" },
    { name: "B", description: "Option B", value: "b" },
  ]}
  onSelect={(index, option) => {
    // Enter 键按下时触发
    console.log("Selected:", option.name)
  }}
  focused
/>

3. onSelect 与 onChange 的语义区分

这是最容易踩的语义坑：onSelect 在 Enter（确认选择）时触发，onChange 在方向键导航时触发。把提交逻辑挂在 onChange 上，会在用户仅仅用箭头键浏览列表时就被“误提交”。

// WRONG - 期望 onChange 在 Enter 时触发
<select
  options={options()}
  onChange={(i, opt) => submitForm(opt)}  // 方向键就会触发！
/>

// CORRECT
<select
  options={options()}
  onSelect={(i, opt) => submitForm(opt)}   // Enter 按下 - 提交
  onChange={(i, opt) => showPreview(opt)}  // 方向键 - 预览
/>

这一“导航即 onChange、确认即 onSelect”的事件模型与表单控件的浏览器语义完全相反，是从 Web 迁移到 TUI 的开发者需要重建的心智模型。

控制流：For / Index / Show

For 用于对象，Index 用于原始值

// 对象数组 - item 本身是响应式的
<For each={objects()}>
  {(obj) => <text>{obj.name}</text>}
</For>

// 原始值数组 - 用 Index，item() 才是响应式的
<Index each={strings()}>
  {(str, index) => <text>{index}: {str()}</text>}
</Index>

区别在于 For 追踪数组项的身份（identity），适合对象列表的增删与局部更新；Index 按位置追踪，适合字符串、数字等原始值数组——在 Index 中每一项以 str() 函数形式暴露，必须调用才能取到当前值。

Show 需要显式 fallback

// 可能出问题 - 无 fallback
<Show when={data()}>
  <Component />
</Show>

// 更好 - 显式 fallback
<Show when={data()} fallback={<text>Loading...</text>}>
  <Component />
</Show>

Show 的显隐切换由 when 信号的响应性驱动；fallback 提供条件为假时的占位内容，避免布局在状态到达前塌陷。

清理问题：onCleanup 是强制习惯

1. 忘记清理定时器

症状：内存泄漏、多个 interval 叠加运行。

// WRONG - interval 永不清除
function Timer() {
  const [time, setTime] = createSignal(0)
  setInterval(() => setTime(t => t + 1), 1000)
  return <text>{time()}</text>
}

// CORRECT
function Timer() {
  const [time, setTime] = createSignal(0)
  const interval = setInterval(() => setTime(t => t + 1), 1000)
  onCleanup(() => clearInterval(interval))
  return <text>{time()}</text>
}

TUI 应用往往长期运行，组件随路由/面板切换反复挂载卸载，不清理定时器会让后台任务随时间线性堆积。

2. Effect 内订阅的清理

createEffect(() => {
  const subscription = subscribe(data())

  // WRONG - 无清理，effect 重跑时旧订阅依然活跃
  // CORRECT
  onCleanup(() => subscription.unsubscribe())
})

关键点：onCleanup 注册的函数会在 effect 重新运行前以及组件卸载时执行，是 Solid 中“注册资源必须成对回收”的通用机制，对应关系为：setInterval ↔ clearInterval、订阅 ↔ unsubscribe、监听器 ↔ removeEventListener。

Store 问题：禁止直接突变

直接突变不触发更新

症状：数据变了，界面不动。

const [state, setState] = createStore({ items: [] })

// WRONG - 直接突变
state.items.push(newItem)  // 不会触发更新！

// CORRECT - 通过 setState
setState("items", items => [...items, newItem])

createStore 返回的是一个可深层代理（deep proxy）的响应式对象，但它只追踪通过 setState 写入的变更；对代理内部的直接突变绕过了变更通知路径。

嵌套路径更新

const [state, setState] = createStore({
  user: { profile: { name: "John" } }
})

// WRONG
state.user.profile.name = "Jane"

// CORRECT
setState("user", "profile", "name", "Jane")

setState 支持变长路径参数，可精确到任意深度的叶子节点，且支持函数更新形式做细粒度修改。

调试技巧

控制台不可见

OpenTUI 会接管 console 输出（因为 TUI 独占终端画面），需要手动调出内置调试控制台：

import { useRenderer } from "@opentui/solid"
import { onMount } from "solid-js"

function App() {
  const renderer = useRenderer()

  onMount(() => {
    renderer.console.show()
    console.log("Now visible!")
  })

  return <box>{/* ... */}</box>
}

render() 的选项中也提供 consoleOptions（如 position: ConsolePosition.BOTTOM、sizePercent: 30、startInDebugMode: false），可以在渲染期直接配置调试控制台的位置与初始状态；环境变量 OTUI_SHOW_STATS 与 SHOW_CONSOLE 则用于开关统计与全局控制台。

用 createEffect 追踪响应性

当某个视图“该刷新却没刷新”时，标准排查手段是加一个 effect 探针，确认信号是否真的在预期时机被读取与变更：

createEffect(() => {
  console.log("State:", {
    count: count(),
    items: items(),
  })
})

若探针不输出，说明该分支根本没建立依赖（回到“Effect 中未访问信号”一节）；若探针输出但 UI 不变，问题在渲染端（信号未调用、props 被解构等）。

运行时要求：Bun 与 async render

必须使用 Bun

# WRONG
node src/index.tsx
npm run start

# CORRECT
bun run src/index.tsx
bun run start

OpenTUI 依赖 Bun 的运行时特性（包括 top-level await 与 preload 机制），SKILL 文档同时说明 OpenTUI 的原生构建使用 Zig。

render() 是异步的

创建 renderer 时 render 是异步的：

// 直接调用没问题 - Bun 支持 top-level await
render(() => <App />)

// 需要拿到 renderer 实例时
import { createCliRenderer } from "@opentui/core"
import { render } from "@opentui/solid"

const renderer = await createCliRenderer()
render(() => <App />, renderer)

Cline CLI 的实际入口正是这种“先建 renderer、再渲染”的模式，apps/cli/src/tui/index.tsx 中的 renderOpenTui 以 await createCliRenderer({ exitOnCtrlC: false, autoFocus: false, enableMouseMovement: true }) 起手，随后才 createRoot(renderer) 并挂载根组件——exitOnCtrlC: false 与 autoFocus: false 这两个选项说明复杂应用通常要关闭框架默认行为、自行接管退出与焦点，与前述“绝不调用 process.exit()”“输入框需显式 focused”两条规则首尾呼应。

常见报错速查表

报错信息	根因	修复动作
Cannot read properties of undefined	漏掉的响应式访问	检查信号是否带 () 调用；props 是否被错误解构
JSX element has no corresponding closing tag	组件命名用了连字符	<tab-select> 改为 <tab_select>
store is not a function	把 store 当 signal 调用	store 直接属性访问：store.count 而非 store().count

第三个值得单独强调：createStore 返回的 [store, setStore] 中，store 是对象而非函数，读值用 store.count，写值用 setStore。而 createSignal 返回的读写对则是函数——两者 API 形态的差异是 Solid 中“store is not a function”类报错的全部来源。

小结

OpenTUI Solid 分支的陷阱可以归为四层：进程层（用 renderer.destroy() 替代 process.exit()，参考 apps/cli/src/tui/index.tsx 的生产级销毁流程）、配置层（bunfig.toml preload + jsxImportSource: "@opentui/solid" + Bun.build 挂 solidPlugin，三者缺一不可）、响应性层（信号必须调用、props 禁止裸解构、effect 体内必须读信号、store 禁止直接突变、资源必须 onCleanup）、交互层（显式 focused、onSelect/onChange 语义区分、下划线组件命名）。配合 SKILL.md 的决策树与 configuration.md 的完整配置模板，这套知识足以覆盖从 bunx create-tui -t solid 起步到打包分发的完整链路。