dsh-whale-tui

grok-build 风格的 DeepSeek Harness 终端 TUI —— 自研完整实现，作为 DSH 插件发布。

鲸鱼在终端里替你干活。

当前状态：P1 全量完成。真实线上事件解析（assistant/chunk、usage、turn/end）、Esc 状态机（取消/清屏/回溯）、审批与 ask_user 双向通道、模型切换、权限预设、会话恢复（/resume）、计划审查（a/s/c/y/q）、任务面板（Ctrl+G）、剪贴板、主题量化、终端探测。demo 模式（--demo）无需 runtime/API key 即可体验全部交互。

设计依据

• docs/01-grok-tui-spec.md —— grok-build pager 交互细节复刻 spec（键盘绑定、Esc 语义、审批弹窗、工具卡、主题槽位等）+ DSH 落点对照 + P0/P1/P2 优先级
• docs/02-openma-teardown.md —— openma/deepseek-harness-tui（唯一 Rust/ratatui 同类）架构拆解 + 差距清单 + 可复用/要重做清单
• docs/04-dsh-capability-map.md —— deepseek-harness 0.1.0-rc.6 能力地图：29 个 ctx.* seam、13 个 session projection、19 个模型侧工具、32 个官方 web surface 对照，以及 DSH 独有能力的 TUI 落点与优先级（goal/GoalBar、上下文压力、沙箱、持久 PTY、cordis 自指插件…）

docs/01 回答「grok 怎么做 TUI」，docs/04 回答「DSH 有什么值得我们暴露」。两者方向不同，不要互相当替代。

架构（与 openma 同构，但协议双向化）

+------ plugin 模式（推荐） ---------------------------------------+
| dsh --profile tui（宿主 Node 进程）                                |
|   |- dsh-base + 本插件 tui-runner 行（cordis 插件, inject agents） |
|   |    spawn(dsh-tui --attach-fds, stdio inherit + fd3/4 pipe)    |
|   |    JsonRpcLineTransport（@deepseek-ai/dsh-sdk-protocol）       |
|   |    initialize / session/prompt / session/cancel / shutdown    |
|   |    session.event / session.status / subagent.* 通知转发        |
|   |    审批 / ask_user 双向请求；模型、权限、压缩、回溯扩展         |
|   +- dsh-tui（Rust/ratatui，TTY 归 TUI，fd3/4 走协议）             |
+------------------------------------------------------------------+

+------ standalone（未来）------------------------------------------+
| dsh-tui --runtime-bin <bin>：自己 spawn SDK runtime 子进程         |
+------------------------------------------------------------------+

构建与运行

cargo build                # 编译
cargo run -- --demo                 # 脚本化 demo（无需 runtime/API key）
cargo run -- --demo --theme light
cargo run -- --dump-frame 100x30     # 无 TTY 的确定性布局检查

插件模式（需要全局 dsh 0.1.0-rc.6，一条命令装好）：

npm install -g @deepseek-ai/dsh@0.1.0-rc.6   # 装到 /opt/homebrew/bin（或你的 npm prefix）

scripts/build-npm.sh                      # cargo release + stage vendor 二进制 + npm pack
dsh plugin --profile tui add ./dist/*.tgz # 安装到 tui profile
dsh --profile tui                         # 启动

终端适配

启动时探测终端（TERM_PROGRAM/TMUX）：VS Code 家族自动把退出键提示换成 Ctrl+D（宿主抢占 Ctrl+Q），状态栏显示终端名与 tmux 状态；色彩按终端能力量化（truecolor/256/16）。

社区发现

仓库带 dsh-plugin topic；发布 npm 后可被 awesome-dsh-plugin 精选列表与 dsh-find-plugin 检索收录。

模型默认路由

TUI 的默认 provider/model 从 ~/.dsh/settings.yaml 的 dsh-whale-tui: 块读取（缺省回退到全局 agent-default-model:，再回退 stock）：

dsh-whale-tui:
  provider: opencode-go
  model: deepseek-v4-flash

命令行 --provider / --model 优先级最高。

键位

Slash 命令（已实现）

目录

src/
  main.rs       CLI、终端守卫、事件循环
  bus.rs        AppEvent / Cmd
  proto.rs      NDJSON JSON-RPC（attach/spawn、request/notify、超时、kill/shutdown）
  app.rs        应用状态：RunState、Esc 状态机、follow-up 队列、焦点
  transcript.rs 会话事件 → 渲染 Cell（消息/思考/工具卡）
  ui.rs         ratatui 渲染：状态栏/scrollback/输入框/快捷键栏
  theme.rs      grok 式颜色槽位（深/浅两主题）
  demo.rs       脚本化 demo 流
npm/            TS 桥插件（cordis.patch.yml + lib/index.js + bin 入口）
scripts/        构建与打包（build-npm.sh / package-native.mjs）

实现状态

P1 闭环已落地：真实会话、事件流、审批与问题卡、模型/权限切换、恢复/回溯、压缩、任务与子代理视图均通过同一 fd3/fd4 JSON-RPC 通道运行。--dump-frame 用于确定性布局检查，插件模式用 dsh --profile tui 做真实会话验证。