12.2 TUI 实现

模型: claude-opus-4-6 (anthropic/claude-opus-4-6) 生成日期: 2026-02-17

---

OpenCode 的 TUI（Terminal User Interface，终端用户界面）是用户与 AI 对话的主要入口。与传统的 CLI 工具逐行输出文本不同，TUI 提供了类似图形界面的交互体验——有对话列表、消息气泡、权限确认弹窗、命令面板等组件，全部在终端中渲染。

衍生解释：什么是 TUI？

TUI（Terminal User Interface）是在文本终端中实现的图形化用户界面。与 GUI（Graphical User Interface）使用像素和窗口系统不同，TUI 使用文本字符和 ANSI 转义序列来实现颜色、布局和交互。

经典的 TUI 程序包括 vim、htop、tmux 等。现代 TUI 框架（如 Ink、Textual、Bubbletea）允许开发者使用 React、Python 或 Go 等语言来构建 TUI 程序，大大降低了开发门槛。

12.2.1 技术栈选择

OpenCode 的 TUI 基于以下技术栈：

层级	技术	作用
渲染框架	@opentui/solid	基于 Solid.js 的终端渲染引擎
响应式系统	Solid.js	细粒度响应式状态管理
API 通信	@opencode-ai/sdk/v2	TypeScript SDK，与 Server 通信
事件流	SSE / RPC	实时接收 Server 事件

衍生解释：React 渲染器（Renderer）的概念

React（以及 Solid.js 等类 React 框架）的架构将"状态管理与组件协调"与"实际渲染"分离。React 的核心（Reconciler）负责计算"哪些东西变了"，而 Renderer 负责"把变化应用到实际的目标上"。

• react-dom：渲染到浏览器 DOM

• react-native：渲染到移动端原生组件

• Ink：渲染到终端（使用 ANSI 转义序列）

• @opentui/solid：基于 Solid.js 的终端渲染器

OpenCode 使用 @opentui/solid——它将 Solid.js 组件树转换为终端输出。这意味着开发者可以用熟悉的 JSX 语法和响应式模式来构建 TUI，而不需要手动处理终端转义序列和光标定位。

12.2.2 Worker 线程模型

TUI 的一个重要设计决策是将 UI 渲染和 业务逻辑运行在不同的线程中：

主线程（UI 线程）                     Worker 线程（业务线程）
┌──────────────────┐                 ┌──────────────────┐
│  终端渲染引擎     │                 │  OpenCode Server │
│  用户输入处理     │  ←── RPC ──→   │  Session/Agent   │
│  组件状态管理     │                 │  MCP/Plugin      │
│  对话框/命令面板  │                 │  事件总线        │
└──────────────────┘                 └──────────────────┘

thread.ts 是 TUI 命令的入口，负责创建 Worker 线程并建立通信：

// cli/cmd/tui/thread.ts
export const TuiThreadCommand = cmd({
  command: "$0 [project]",   // 默认命令
  describe: "start opencode tui",
  handler: async (args) => {
    // 1. 创建 Worker 线程
    const worker = new Worker(workerPath, { env: /* ... */ })
    const client = Rpc.client<typeof rpc>(worker)

    // 2. 决定通信模式
    const shouldStartServer = /* 用户是否显式指定了端口或主机名 */

    if (shouldStartServer) {
      // 模式 A：启动 HTTP Server
      const server = await client.call("server", networkOpts)
      url = server.url
    } else {
      // 模式 B：直接 RPC 通信（无 HTTP 开销）
      url = "http://opencode.internal"
      customFetch = createWorkerFetch(client)
      events = createEventSource(client)
    }

    // 3. 启动 TUI 渲染
    await tui({ url, fetch: customFetch, events, args, onExit })
  },
})

两种通信模式的选择逻辑：

• 模式 A（HTTP Server）：当用户通过 --port、--hostname 等参数显式请求启动 Server 时，或者需要让外部客户端（如 Web UI、IDE 扩展）连接时，启动完整的 HTTP Server。TUI 通过 HTTP 和 SSE 与 Server 通信。

• 模式 B（直接 RPC）：默认模式。TUI 直接通过 Worker 线程的消息通道与业务逻辑通信，无需经过 HTTP 层。这种模式延迟更低、开销更小。createWorkerFetch() 模拟了 fetch API，实际上是通过 RPC 调用 Worker 中的 Server.App().fetch()。

Worker 线程（worker.ts）

Worker 线程负责运行 OpenCode 的核心业务逻辑：

// cli/cmd/tui/worker.ts

// 将 GlobalBus 事件通过 RPC 转发到主线程
GlobalBus.on("event", (event) => {
  Rpc.emit("global.event", event)
})

// 订阅 SDK 事件流并通过 RPC 转发
const startEventStream = (directory: string) => {
  const sdk = createOpencodeClient({
    baseUrl: "http://opencode.internal",
    directory,
    fetch: /* 直接调用 Server.App().fetch() */,
  })

  while (!signal.aborted) {
    const events = await sdk.event.subscribe({}, { signal })
    for await (const event of events.stream) {
      Rpc.emit("event", event)  // 转发给主线程
    }
  }
}

export const rpc = {
  // 代理 HTTP 请求
  async fetch(input) { /* ... */ },
  // 启动 HTTP Server
  async server(input) { /* ... */ },
  // 检查升级
  async checkUpgrade(input) { /* ... */ },
  // 热重载配置
  async reload() {
    Config.global.reset()
    await Instance.disposeAll()
  },
  // 关闭
  async shutdown() { /* ... */ },
}

Rpc.listen(rpc)

Worker 暴露了五个 RPC 方法，其中 reload 方法支持通过 SIGUSR2 信号触发配置热重载——用户修改 opencode.json 后，可以通过 kill -USR2 <pid> 或在 TUI 中触发重新加载，而不需要重启进程。

12.2.3 TUI 应用入口（app.tsx）

tui() 函数是 TUI 应用的入口，它负责创建 Solid.js 渲染树：

// cli/cmd/tui/app.tsx
export function tui(input: {
  url: string
  args: Args
  fetch?: typeof fetch
  events?: EventSource
  onExit?: () => Promise<void>
}) {
  return new Promise<void>(async (resolve) => {
    const mode = await getTerminalBackgroundColor()

    render(() => {
      return (
        <ErrorBoundary fallback={/* ... */}>
          <ArgsProvider>
            <ExitProvider>
              <KVProvider>
                <ToastProvider>
                  <RouteProvider>
                    <SDKProvider>
                      <SyncProvider>
                        <ThemeProvider mode={mode}>
                          <LocalProvider>
                            <KeybindProvider>
                              <PromptStashProvider>
                                <DialogProvider>
                                  <CommandProvider>
                                    <FrecencyProvider>
                                      <PromptHistoryProvider>
                                        <PromptRefProvider>
                                          <App />
                                        </PromptRefProvider>
                                      </PromptHistoryProvider>
                                    </FrecencyProvider>
                                  </CommandProvider>
                                </DialogProvider>
                              </PromptStashProvider>
                            </KeybindProvider>
                          </LocalProvider>
                        </ThemeProvider>
                      </SyncProvider>
                    </SDKProvider>
                  </RouteProvider>
                </ToastProvider>
              </KVProvider>
            </ExitProvider>
          </ArgsProvider>
        </ErrorBoundary>
      )
    }, {
      targetFps: 60,
      exitOnCtrlC: false,
      useKittyKeyboard: {},
    })
  })
}

16 层嵌套的 Provider 构成了 TUI 的上下文层级——这在 React/Solid.js 应用中是常见的"Provider Hell"模式。每个 Provider 向下传递特定的上下文：

Provider	职责
ArgsProvider	CLI 启动参数
ExitProvider	退出处理逻辑
KVProvider	键值存储（持久化用户偏好）
ToastProvider	通知消息（类似浏览器中的 Toast）
RouteProvider	页面路由管理
SDKProvider	OpenCode API 客户端
SyncProvider	数据同步（Session、Message 等）
ThemeProvider	颜色主题管理
LocalProvider	本地配置（当前 Agent、Model 等）
KeybindProvider	快捷键绑定
PromptStashProvider	未发送的输入缓存
DialogProvider	模态对话框管理
CommandProvider	命令面板（类似 VS Code 的 Ctrl+Shift+P）
FrecencyProvider	频率排序（常用命令优先）
PromptHistoryProvider	历史输入记录
PromptRefProvider	输入框引用

终端背景色检测

TUI 在启动时会自动检测终端的背景颜色来决定使用深色还是浅色主题：

async function getTerminalBackgroundColor(): Promise<"dark" | "light"> {
  if (!process.stdin.isTTY) return "dark"

  return new Promise((resolve) => {
    const handler = (data: Buffer) => {
      const str = data.toString()
      const match = str.match(/\x1b]11;([^\x07\x1b]+)/)
      if (match) {
        const color = match[1]
        // 解析 RGB 值并计算亮度
        const luminance = (0.299 * r + 0.587 * g + 0.114 * b) / 255
        resolve(luminance > 0.5 ? "light" : "dark")
      }
    }

    process.stdin.setRawMode(true)
    process.stdin.on("data", handler)
    // 发送 OSC 11 查询序列
    process.stdout.write("\x1b]11;?\x07")

    // 超时回退到 dark
    setTimeout(() => { cleanup(); resolve("dark") }, 1000)
  })
}

这利用了终端的 OSC 11（Operating System Command）协议——通过向标准输出写入 \x1b]11;?\x07，请求终端返回其背景色的 RGB 值。大多数现代终端（iTerm2、Windows Terminal、Alacritty 等）都支持这个协议。

12.2.4 路由系统

TUI 有两个"页面"：

• Home：会话列表页，显示所有会话。

• Session：会话详情页，显示对话内容和工具调用。

路由在 RouteProvider 中管理，通过 route.navigate() 切换：

// Home 页面：展示会话列表
// Session 页面：展示对话详情

function App() {
  const route = useRoute()

  return (
    <Switch>
      <Match when={route.data.type === "home"}>
        <Home />
      </Match>
      <Match when={route.data.type === "session"}>
        <Session />
      </Match>
    </Switch>
  )
}

12.2.5 命令面板

TUI 实现了一个类似 VS Code 的命令面板，通过快捷键激活。命令面板提供了 40 多个操作：

const commands = [
  { title: "Switch session",    value: "session.list",     keybind: "session_list" },
  { title: "New session",       value: "session.new",      keybind: "session_new" },
  { title: "Switch model",      value: "model.list",       keybind: "model_list" },
  { title: "Switch agent",      value: "agent.list",       keybind: "agent_list" },
  { title: "Toggle theme",      value: "theme.toggle",     keybind: "theme_toggle" },
  { title: "MCP status",        value: "mcp.status",       keybind: "mcp_status" },
  { title: "Session diff",      value: "session.diff" },
  { title: "Export session",    value: "session.export" },
  { title: "Copy last message", value: "message.copy" },
  // ... 更多命令
]

命令面板使用 FrecencyProvider 进行智能排序——用户最近和最常使用的命令会排在前面。

12.2.6 组件架构

TUI 的组件分布在 tui/component/ 目录下，按功能组织：

tui/component/
├── dialog-agent.tsx       # Agent 选择对话框
├── dialog-command.tsx     # 命令面板
├── dialog-mcp.tsx         # MCP 状态对话框
├── dialog-model.tsx       # 模型选择对话框
├── dialog-provider.tsx    # 对话框容器
├── dialog-session-list.tsx # 会话列表对话框
├── dialog-status.tsx      # 状态对话框
├── dialog-theme-list.tsx  # 主题选择对话框
├── prompt/                # 输入框组件
│   ├── history.tsx        # 历史记录
│   ├── frecency.tsx       # 频率排序
│   └── stash.tsx          # 输入缓存
└── ...

12.2.7 TUI 事件

TUI 内部使用事件总线进行组件间通信（见 11.2 节）：

// cli/cmd/tui/event.ts
export const TuiEvent = {
  PromptAppend:   BusEvent.define("tui.prompt.append",   z.object({ text: z.string() })),
  CommandExecute: BusEvent.define("tui.command.execute",  z.object({ text: z.string() })),
  ToastShow:      BusEvent.define("tui.toast.show",      z.object({ title, description })),
  SessionSelect:  BusEvent.define("tui.session.select",  z.object({ sessionID })),
}

例如，当用户在命令面板中选择"创建新会话"时，会发布 SessionSelect 事件，路由组件订阅该事件并切换到新会话页面。

12.2.8 小结

OpenCode 的 TUI 架构体现了几个现代前端工程实践在终端场景中的应用：

1. 组件化：使用 Solid.js 的 JSX 语法编写 TUI 组件，与 Web 前端开发体验一致。

2. 响应式：Solid.js 的细粒度响应式系统确保只有变化的部分被重新渲染，保证终端输出的流畅性。

3. 多线程：UI 线程和业务线程分离，避免长时间的 LLM 调用阻塞 UI 响应。

4. 抽象通信：通过 customFetch 和 EventSource 抽象，TUI 可以透明地在 RPC 模式和 HTTP 模式之间切换。

5. Context 层级：16 层 Provider 虽然看起来冗长，但每层都有明确的职责，将关注点清晰地分离。