交互式终端界面（TUI）

RelayCore 自带功能完整的终端 UI，可实时检查流量。基于 ratatui 构建，使用体验类似 Shell 里的轻量级 Charles / Proxyman。

启动

relay-core-cli run --ui
# 可选：与 REST/SSE API 搭配使用，启用四面板布局
relay-core-cli run --ui --api-port 8082

启用 --ui 后 TUI 会接管终端，代理进程本身仍在同一进程中运行，无需启动额外服务。

布局

TUI 会根据终端宽度自适应：

宽度	布局	面板
≥ 120 列	四面板（需 `--api-port`）	流量列表 · 详情 · 当前规则 · 待处理拦截
80–119 列	两面板	流量列表 · 详情（水平分屏，比例随宽度变化）
< 80 列	单面板（`Tab` 切换）	全屏显示流量列表或详情

只有当 TUI 能连上 REST/SSE API（--api-port 已启用且可达）时才会出现四面板布局。脱离 API 时回退为本地两面板视图，规则与拦截面板不可见。

快捷键

全局

按键	动作
`q`	退出 TUI（代理在后台继续运行，SIGINT 时结束）
`?`	切换应用内帮助浮层
`Esc`	返回流量列表 / 关闭浮层
`Tab`	循环切换活动区域（列表 → 详情 → 规则 → 列表）
`1` / `2` / `3` / `4`	跳转到详情选项卡：概览 · 请求 · 响应 · 消息
`y`	将当前选中的 HTTP 流量复制为 cURL 命令
`Ctrl+C`	强制结束进程

流量列表（默认焦点）

按键	动作
`j` / `↓`	下一行
`k` / `↑`	上一行
`g`	跳到最新（顶部）并重新启用自动滚动
`G` / `End`	跳到最旧（底部）
`Enter` / `l` / `→`	聚焦详情面板
`d`	从本地列表中删除当前选中流量
`c`	清空整个流量列表（不影响代理）
`p`	暂停/恢复捕获。暂停时新流量计入待处理计数，不进列表。
`r`	聚焦规则面板（仅 API 模式）
`/`	打开过滤栏

流量详情

按键	动作
`j` / `k` 或 `↓` / `↑`	逐行滚动
`Ctrl+d` / `PageDown`	向下滚动 10 行
`Ctrl+u` / `PageUp`	向上滚动 10 行
`g` / `Home`	滚到顶部
`G` / `End`	滚到底部
`Tab`	循环切换详情选项卡（概览 → 请求 → 响应 → 消息 → 概览）
`h` / `←` / `Esc`	返回流量列表

过滤栏

在流量列表中按 / 开始过滤，Enter 或 Esc 提交/关闭。语法见下方的过滤表达式语法。

状态栏

底部一行始终显示运行状态：

实时请求速率（5 秒滑动窗口，req/s）
启动以来累计捕获的流量数
当前活动区域指示（LIST / DETAIL / RULES）
运行时长 hh:mm:ss
捕获暂停或自动滚动关闭时的待处理计数

鼠标支持

已启用鼠标捕获。可使用滚轮滚动列表，点击切换行或面板焦点。

过滤表达式语法

TUI 过滤栏与 relay-core-cli flows --filter、HTTP API 的 search_flows 共享同一解析器。按 / 打开过滤栏后输入表达式即可。完整语法见过滤表达式。

速览：

host:api method:POST status:>=400   # 失败的对 api 的 POST
ws status:500-599                    # 5xx 的 WebSocket
health                               # URL 含 "health" 的任意流

详情选项卡

概览 (Overview) — 方法、URL、状态、耗时、大小、主机、远端地址、命中的规则、错误信息
请求 (Request) — 起始行、请求头、请求体（受 max_body_size 限制）
响应 (Response) — 状态行、响应头、响应体
消息 (Messages) — WebSocket 消息日志（opcode、方向、大小、base64 内容）。普通 HTTP 此页为空。

复制为 cURL

在任意 HTTP/WebSocket 流量上按 y，即可将一条可移植的 POSIX shell cURL 命令复制到剪贴板。Header 值使用单引号转义；body 使用 --data-binary 写入。macOS 需要 pbcopy，Linux 需要 wl-copy / xclip；未找到时仍会构造命令并通过 toast 提示剪贴板不可用。

主题

TUI 内置三种配色方案。默认 relay 与 relaycore.dev 品牌色一致（近黑底 + 青色强调）。

主题 ID	别名	说明
`relay`	`brand`、`default`	relaycore.dev 品牌色 — 近黑底 + 青色强调（默认）
`slate`	`legacy`	Tokyo Night 风格 slate 背景 + 琥珀色焦点
`high-contrast`	`hc`、`high_contrast`、`highcontrast`	更亮的强调色与边框，适合对比度低的终端

解析优先级

主题按以下顺序解析（优先级从高到低）：

--theme <name> CLI 参数
RELAY_CORE_TUI_THEME 环境变量（clap 已将其绑定到 --theme）
~/.relay-core/config.toml 中的 [tui].theme
默认值 relay

# 临时覆盖
relay-core-cli run --ui --theme slate

# 持久化到本机
cat >> ~/.relay-core/config.toml <<'EOF'
[tui]
theme = "high-contrast"
EOF

# 环境变量覆盖（如 CI 场景）
RELAY_CORE_TUI_THEME=slate relay-core-cli run --ui

颜色语义

HTTP 方法：GET = 绿，POST = 橙，PUT = 青，DELETE = 红，PATCH = 蓝绿，HEAD = 紫，OPTIONS = 灰，WS = 青
状态码：2xx = 绿，3xx = 橙，4xx/5xx = 红，在途 = 暗色斜体
耗时：< 100 ms = 绿，< 500 ms = 暗，≥ 500 ms = 红
主机：8 色调色板，基于主机名哈希确定

主题名大小写不敏感。未知名称会报错并列出可选值。

捕获暂停与待处理计数

按 p 切换"暂停"模式。代理继续运行，TUI 仍持续跟踪新的流量更新，但列表被冻结，每次新事件都计入待处理计数。再按 p 恢复，清空待处理计数并重新跟随实时流量。

使用提示

多按 g 重新启用自动滚动——使用 j/k 手动滚动时会暂时关闭自动滚动，便于在持续流量中查看某一行。
TUI 仅在内存中保留最近 1,000 条流量。可结合 --save-stream <PATH> 将所有流量以 JSONL 形式落盘，供离线分析。
搭配 --api-port 可让 relay-core-cli flows 等下游工具共享同一代理实例。