dsh-TUI 启动后终端一片空白，通常不是单一故障，而是两层叠在一起：一层是 TUI 有没有把界面画到终端上，另一层是 Harness 会话有没有真正建立。判断顺序建议反过来走——先把会话层切出去，因为如果 Harness 自己都起不来，TUI 画得再对也只会得到一个空屏。先把后端单独跑通，再回头处理渲染。
空白屏的定位顺序建议是：先确认 Harness 后端能独立启动并就绪，再看终端渲染。判断依据都是可观察的——后端有明显的监听或 ready 日志、进程存活、TUI 初始化日志是否出现。如果后端单独跑也不就绪，问题在会话层；如果后端正常而 TUI 仍空白，才去查 TERM、终端尺寸和终端复用器。边界是：这一套只覆盖启动阶段，不覆盖运行过程中卡死的情况。
在最小终端环境里启动，排除主题与字体干扰
先排除终端本身的干扰。一部分“空白”其实是前景色和背景色撞在一起，或者字体缺字形，画面画了但看不见。做法是用一个不加载用户配置的最小环境启动，而不是在日常装了提示符插件、配色脚本的 shell 里直接跑。
env -i HOME="$HOME" PATH=/usr/bin:/bin \
TERM=xterm-256color LANG=C LC_ALL=C \
dsh-tui命令名和路径按你的实际安装替换。启动前后对比三个点：终端是否出现清屏或光标跳动的转义序列（出现说明 TUI 至少尝试接管屏幕）、是否有某一行文字闪过随即消失、把终端背景换成默认纯色后是否仍无内容。如果最小环境下依然全空，问题大概率不在主题和字体上，继续往下查会话层。这里的取舍是：先不要去调具体配色方案，先确认有没有绘制动作。
把 Harness 单独跑一遍，确认后端本身能起来
把 Harness 从 TUI 里拆出来，直接调用后端入口（可执行文件、子命令或服务脚本，按你的安装方式确定）。它不依赖界面，所以能独立给出成功或失败。
# 直接跑后端，输出同时落盘
/path/to/harness `--config` /path/to/config \
> /tmp/harness.log 2>&1 &
echo $!就绪状态的判断依据通常是可观察的：日志里出现监听地址或 ready / listening 之类的字样、进程停在等待连接的位置、或者手动发一次健康检查或握手请求能拿到响应。如果后端几秒内直接退出，用 echo $? 或日志尾部看退出码和报错。输出保存建议统一重定向到固定文件，不要只依赖滚屏，后面几步都要拿它做对照。适用边界：这一步只回答“后端能不能起来”，不回答“TUI 能不能连上后端”。
同时查看插件进程与会话进程
后端能跑之后，再同时盯两个进程：插件（TUI 本体）进程和会话进程。目的不是看资源占用，而是看两者是否都存活、以及谁先退出。
# 启动后 1~2 秒内采一次
pgrep -af 'dsh|harness'
# 等待 10 秒左右再采一次
sleep 10; pgrep -af 'dsh|harness'匹配串按你的实际进程名调整，不要照抄。两次采样的差异大致能区分几种情况：
| 第一次采样 | 第二次采样 | 更像哪一层的问题 |
|---|---|---|
| 两个都在 | 两个都在，界面仍空白 | 渲染层：会话起来了，画面没画出来 |
| 两个都在 | 只剩插件进程 | 会话层：后端中途退出，回日志找退出原因 |
| 只有插件进程 | 只有插件进程 | 会话层：后端从未被拉起，或路径、参数不对 |
| 两个都在 | 两个都没了 | 两者同时退出，先确认终端是否被主动关闭 |
切换终端复用器后复现同一现象
如果同一份配置在裸终端下空白，换一个终端复用器再跑一次，能判断空白是否跟终端实现本身有关。步骤是：先在裸终端（不经 tmux 或 screen）启动一次，记录现象；退出后在 tmux 里再启动一次，同样记录；条件允许再换 screen 或 zellij 做第三次对照。
tmux new -s dsh
# 在会话内启动 dsh-TUI，观察是否仍空白
# 顺手记录环境：echo "$TERM $COLUMNS x $LINES"复现条件要记成可对照的几项：TERM 的取值、COLUMNS 与 LINES 的尺寸、是否处于复用器内、是否出现清屏序列、是启动即空白还是运行一会儿才空白。常见的一类差异是复用器改写了 TERM，导致终端能力集与 TUI 预期不一致；窗口尺寸过小也可能让 TUI 认为没有可绘制区域。记录方式建议直接抄一份终端输出到文件，别只写一句“也空白”。
提高日志级别收集启动阶段输出
前几步只能告诉你哪一层出问题，要定位具体原因还得看启动期日志。做法是临时把日志级别调到 debug 或 trace，然后完整重启一次，不要在空白界面上热改配置。
# 环境变量方式，变量名按你的项目实际约定替换
LOG_LEVEL=debug /path/to/harness `--config` /path/to/config \
> /tmp/harness.debug.log 2>&1 &
# TUI 侧同样开调试并落盘
LOG_LEVEL=debug dsh-tui > /tmp/tui.debug.log 2>&1也可以改配置文件里的日志级别字段，适合不想改启动命令的场景。输出落盘位置建议固定成 /tmp 下的两个文件，便于并排看时间戳对齐。重点看这几类行：进程启动与配置加载是否成功、有没有配置或权限相关的报错、会话建立与握手是否完成、TUI 是否进入了备用屏（alternate screen）以及随后因何退出。如果 TUI 日志停在“已进入备用屏”而后端日志没有对应记录，基本可以判断是会话没接上，而不是画面画不出来。