deepseek-harness-tui: 终端原生交互式聊天 TUI（dsh 插件）

[gxinxing]

简介

deepseek-harness-tui 是一个基于 Ink（React for terminals）构建的终端原生交互式 TUI，作为 DeepSeek Harness 的 dsh 插件运行。

独立仓库：https://github.com/gxinxing/deepseek-harness-tui （已标记 dsh-plugin）

一行启动：

dsh --profile tui

设计理念

追求零装饰、终端原生体验：

• 不重新实现 Harness——它只是一个薄插件（~800 行 UI 代码），通过 Cordis 插件机制接入 dsh 的 agent/session/llm 服务
• 终端默认配色——不画框线，语义色仅在需要时出现：cyan（输入/用户/活动）、green（成功）、red（错误）、magenta（品牌）、dim（次要信息）
• OSC 11 主题自适应——通过终端背景色查询自动派生 tint，暗色/亮色主题均可
• CJK 感知换行——正确处理宽字符显示宽度

功能

功能	说明
底部锚定对话	用户/助手/工具消息在可滚动视图中展示
工具调用折叠	工具调用和结果折叠为紧凑单元格（• Running <cmd> → $ <cmd> + output + ✓ • 1.2s）
思维展示	Ctrl+T 切换推理块显示/折叠
模型切换	/model 列出当前模型，/model <name> 切换（如 deepseek-v4-pro）
输入历史	↑/↓ 回溯历史消息，连续重复自动去重
复制到剪贴板	/copy 复制最近一条助手回复到系统剪贴板
Markdown 渲染	标题保持 # 前缀加粗，代码块保留 fence，inline code 带 chip 背景
盲文旋转器	Agent 轮次期间的流畅 braille 动画
Todo 面板	todo_write 工具的实时状态展示

架构

src/
├── index.js     # Cordis 插件入口：注入 agent/session/llm 服务，注册 session/event 监听，React render
├── ui.js        # Ink 组件：对话记录、输入框、旋转器、工具单元格、Markdown 渲染
├── utils.js     # 纯工具函数（文本换行、ANSI 清理、颜色混合等，无 React 依赖）
└── theme.js     # 终端背景色检测（OSC 11）

cordis.patch.yml 定义 profile 补丁：禁用 headless 启动，注册 TUI runner。

测试

34 个单元测试覆盖纯工具函数：splitCodeBlocks、wrapText、truncate、stripAnsi、splitOutput、userMessageBg、codeChipBg、markdownLines。

npm test  # 34/34 passing

安装

# 需要 dsh 和 DeepSeek API Key
npm install -g @deepseek-ai/dsh
export DEEPSEEK_API_KEY=sk-...

# 克隆并运行
git clone https://github.com/gxinxing/deepseek-harness-tui.git
cd deepseek-harness-tui
npm install
dsh --profile tui

技术细节

• 纯 React.createElement，无 JSX，无构建步骤
• 所有 session event 访问均为防御式（可选字段 + 形状检查），harness 迭代快，UI 不会因未知类型崩溃
• ANSI escape 序列在展示前被 strip，防止原始工具输出重绘 TUI
• Tool output 截断为 head 10 + tail 6 行 + 省略计数

后续计划

• Approval 流程（y/n 按键审批工具调用）
• Session resume（/sessions + /resume <id>）
• 动态模型列表（通过 llm.listProviders() / llm.listModels()）
• 代码块语法高亮

---

作为社区插件分享，已按 CONTRIBUTING.md 建议标记 dsh-plugin topic。欢迎反馈和建议！

DeepSeek Harness 的设计支持深度定制，官方仓库中的包不天然比社区包更重要。这个 TUI 是一份灵感来源，而非官方实现。