故障排查

中断与退出

第一次 Ctrl+C 清空 composer;composer 为空时改为中断活动回合,Esc 始终都能中断。第二次 Ctrl+C 退出,输入框为空时 Ctrl+D 退出,有文字时向前删除字符。持久会话退出时会打印 omdsh --resume <session-id>,方便在新终端里重新打开这段对话。

找回会话 id

/context 报告活动会话的详细信息,/resume 打开可搜索的选择器。只记得聊过什么时,用 /resume <查询> 搜索持久会话内容。见会话与历史。

最初使用 v0.5.0 至 v0.11.0 创建的会话可能包含一个未经扩展的 DSH 持久化读取器会拒绝的私有事件;omdsh 仍能打开它们。不要手工修改会话文件——它们可能被压缩并带有完整性校验。

DeepSeek 账户登录

/login → DeepSeek account 会用 loopback 回调地址(例如 http://127.0.0.1:<port>/oauth/callback)打开平台授权页。授权完成后,页面应结束在 .../dsh/authorized?login_source=web 并显示“授权已完成”。如果页面拉起 DeepSeek Harness Desktop,它的地址会带 login_source=desktop(或没有 login_source),属于 Desktop 发起的授权,不是 TUI;关闭那个标签页,重新从 /login 获取新地址,不要复用旧标签页。

由于标签页是从终端打开而不是由 window.open 打开,浏览器可能不会自动关闭它;看到完成提示后可手动关闭,授权成功后 TUI 自动返回账户页面。远程主机需要把 TUI 显示的 loopback 端口通过 SSH 转发到本机,回调才能到达 TUI。登录后共享账户会同时出现在 /login 与 /logout;登出会删除本地 grant,并在后台尝试撤销。

日志

交互式 TUI 会把插件的 console 输出重定向到 $OMDSH_HOME/omdsh/logs/omdsh.log,而不是 stdout,诊断文本不会写进 composer 或破坏画面。文件只保留在本机,可能包含运行细节;omdsh exec 仍使用自己的 stdout/stderr 协议。删除该文件即可重置日志。

颜色

在未设置显式颜色偏好时,NO_COLOR 与 FORCE_COLOR=0 会关闭彩色输出。显式选择——插件配置或在 /settings 中选择的值——仍然优先于环境变量;在 /settings 中开启颜色会立即生效,无需重启。

当 COLORTERM 报告支持 24 位色,或终端不属于已知的 16 色环境时,omdsh 使用 24 位色。Apple Terminal 的 24 位色支持不可靠,因此改用 256 色调色板;设置 COLORTERM=truecolor 可以覆盖。在 16 色终端中,主题颜色会与终端报告的调色板做匹配。

键盘协议

在实现了 Kitty 键盘协议的终端中,omdsh 会请求无歧义的按键上报,使 Alt 和 Ctrl 快捷键被可靠识别。退出、Ctrl+Z 挂起、外部编辑器运行期间,以及进程意外退出时,omdsh 都会把终端原本的按键编码还给终端。如果崩溃后 shell 中的 Esc 或 Ctrl+C 表现异常,执行 printf '\033[<u' 即可恢复。

滚动回看与复用器

普通更新期间 omdsh 保留终端原生滚动回看;只有真正的全屏浮层会借用备用屏幕。替换转录时同样保留:/clear、切换会话与 --resume 都会在带标签的接缝下方追加新文档,而不是清掉上面的内容——那段历史里还有 omdsh 启动前你 shell 打印的东西。在 tmux、screen 与 ConPTY 下,宿主滚动回看会被保留,resize 突发会先合并再重绘。附加或 resize 后如果显示看起来过期,用 Alt+L 重绘实时视图,终端原生历史继续保留。

已经滚进那段历史的行,是当时显示内容的快照,之后不会被改写。因此向上滚过接缝时,会看到已经结束的工具调用、或已经折叠成组头的工作段,仍按终端收到它们时的样子排列。接缝是唯一标记这次更替的地方,接缝之下的实时视图才是当前转录的准。

插件启动失败

不兼容的 bundle 或无法解析的包可能阻止插件加载。没有声明 dsh.bundle.patch 的普通库安装时会收到警告,并且不贡献组合层。omdsh --dump-config 显示组合树及各条目的来源,omdsh plugin remove <package> 移除 Profile 安装。服务无法解析时,请检查 DSH 兼容性及是否存在重复的 Cordis 或 Harness 副本。见用户插件。

更新与通知

每日更新检查只会提示存在新的 npm 版本,从不自动安装。升级后的版本说明、更新检查与终端通知都在 /settings → Terminal 中配置。见设置。

管道输入

当输入或输出不是 TTY 时,omdsh 退化为按行输入与纯追加式输出,而不是占用屏幕。CI 使用的就是这种模式。

相关