deepseek-harness-tui

在终端里运行 DeepSeek Harness：流式推理、工具调用、Skills、多图 prompt 与持久会话。

中文 · English

dsh-tui 是 DeepSeek Harness 的终端原生 agent UI：在一个 Rust/ratatui 界面里查看流式推理、工具调用、subagent、token 用量和持久化会话。它既可以 作为官方 dsh profile 插件运行，也可以直接连接 SDK JSON-RPC runtime。

快速开始

推荐：作为 dsh profile 插件运行

需要已安装并配置好的 dsh（当前集成基线为 0.1.0-rc.6）、Node.js 18+ 和 pnpm 10+。官方包覆盖 macOS Apple Silicon、macOS Intel、Linux x64 和 Windows x64。

dsh plugin --profile tui add @openma/deepseek-harness-tui
dsh --profile tui

安装命令不需要 -w。可用下面的命令确认 bundle 已挂载为 tui-runner：

dsh --profile tui --dump-config

先看 Demo

Demo 不需要 runtime 或 API key：

npm install --global @openma/deepseek-harness-tui
dsh-tui --demo

dsh-tui 是主命令；dsb 保留为兼容别名。

核心能力

• 完整的 agent 时间线：实时呈现推理、回复、工具参数与结果、plugin 上下文、 subagent 生命周期和 token/cache 指标；最新消息下方持续显示阶段、耗时与队列深度。
• 宿主能力原生接入：在 plugin 模式读取 dsh 的模型、agent preset、权限、 provider、凭据和可调用 skills；skills 与内置命令共享可搜索、可滚动的斜杠菜单。
• 多图 prompt：从文件、剪贴板或粘贴操作暂存最多 8 张图片，图片以可编辑的 [image n] chip 内联在草稿中，并支持名称、尺寸、大小和类型预览。
• 终端友好的 Markdown：渲染标题、列表、引用、代码块、行内代码、强调、 删除线、链接和图片标记，同时保留 CJK/Latin 混排与软换行样式。
• 高密度工具视图：工具调用清晰呈现进行中、成功和失败状态，结果可折叠， 长输出拥有独立滚动视窗，不会挤占整段对话。
• 适合长对话的控制：回合中可排队 follow-up、打断并立即发送；持久化 JSONL 会话通过 /new、/resume 和 --session-id 管理，workspace 模式信息也会缓存。
• 跨平台输入体验：readline 编辑、上下文快捷键，以及 macOS 的物理 ⌘/⌥ 修复和 Linux/Windows 的 ctrl 组合键，让常用移动与删除在不同终端保持一致。
• 终端原生界面：深浅主题、窄屏布局、鼠标选择/工具交互、原生/tmux/OSC 52 剪贴板，以及支持 kitty graphics protocol 的图片预览和可选 /liang 像素宠物。

两种运行模式

Plugin runner 在宿主 TTY 上启动原生二进制，并通过 Unix fd 3/4 或 Windows 认证 loopback TCP 提供一套与官方 SDK server 兼容的 JSON-RPC 接口。它不是对 @deepseek-ai/dsh-sdk-jsonrpc-server 的直接挂载；agent、工具、provider 和持久化 仍由外围 dsh profile 提供。

Standalone runtime

全局安装只提供 TUI 二进制。Standalone 模式还需要在工作区附近的 .venv 中 安装 DeepSeek Harness SDK，或显式指定 runtime：

python -m venv .venv
.venv/bin/pip install deepseek-harness-sdk
dsh-tui --workspace .

也可以设置 DSH_RUNTIME_BIN，或传入 --runtime-bin <path>。凭据优先使用 --api-key、DEEPSEEK_API_KEY，随后尝试读取本机 ~/.dsh 配置。

常用交互

界面内使用 /help 查看命令，使用 /keys 查看完整快捷键。

从源码构建

需要 Rust stable 和 Node.js 18+：

cargo test --locked
node --test scripts/package-native.test.mjs
bash scripts/build-npm.sh

本地脚本只编译当前平台，并将 tarball 写入 dist/。GitHub Actions 工作流 Package and publish npm 会分别构建以下目录，再汇总为一个 npm 包：

npm/vendor/darwin-arm64/dsh-tui
npm/vendor/darwin-x64/dsh-tui
npm/vendor/linux-x64/dsh-tui
npm/vendor/win32-x64/dsh-tui.exe

推送与 npm/package.json 和 Cargo.toml 版本一致的 tag（例如 v0.1.0） 会通过 npm Trusted Publishing（OIDC）发布到 latest，随后创建带 tarball 的 GitHub Release。版本不一致时 CI 会在发布前失败。

故障排查

• no native binary for ...：当前安装包不包含你的平台。确认安装的是 最新版本，并查看上方支持矩阵。
• cannot find ... dsh-jsonrpc-agent：这是 standalone runtime 缺失；安装 SDK、设置 DSH_RUNTIME_BIN，或改用 dsh plugin 模式。
• pnpm workspace root 错误：升级到 pnpm 10+，然后重新运行不带 -w 的 安装命令。
• ERR_REQUIRE_ESM_RACE_CONDITION：0.1.0 及更早的 runner 是 CJS，会和 dsh 并行加载的 ESM 插件抢同一份模块。升级到 0.1.1 以上，或从本仓库安装 npm/ 目录。
• 像素宠物不显示：终端可能不支持 kitty graphics protocol；主界面功能 不受影响。

项目结构

• src/：TUI 状态机、绘制、协议、runtime 生命周期和会话目录。
• npm/：dsh bundle runner、CLI shim、manifest 与原生二进制。
• scripts/：本地构建、跨平台打包校验、协议集成测试与资源生成。
• assets/：截图、主题资源和可选宠物精灵。

协议是 stdio 上的 NDJSON JSON-RPC 2.0。实现细节可从 src/proto.rs、src/controller.rs 和 npm/lib/index.js 开始阅读。

License

MIT。本项目与 DeepSeek、xAI 无关联； grok-build 是交互设计参考， DeepSeek Harness 是运行底座。