# deepseek-harness-tui

> 给 DeepSeek Harness 提供的终端原生交互界面，基于 ACP 协议连接 agent 并支持主题、命令、插槽等客户端插件扩展。

## Metadata

- Author: [@openma-ai](https://github.com/openma-ai)
- Repo: <https://github.com/openma-ai/deepseek-harness-tui.git>
- GitHub: [openma-ai/Martty](https://github.com/openma-ai/Martty)
- Stars: 45
- Language: Rust
- License: [MIT](https://spdx.org/licenses/MIT.html)
- Homepage: <https://martty.sh>
- Topics: `agent`, `agents`, `deepseek-harness`, `deepseek-harness-plugin`, `deepseek-harness-plugin-dev`, `deepseek-harness-plugins`, `dsh-plugin`, `dsh-plugins`, `tui`, `tui-rs`
- Forks: 4
- Open Issues: 1
- Last push: 2026-08-21T02:15:18.000Z
- Added: 2026-08-14T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:openma-ai/deepseek-harness-tui
```

## Wiki

## 一句话定位
这是给 DeepSeek Harness (DSH) 准备的一套终端原生交互界面（终端里的"客户端"），通过 ACP 协议与 agent 通讯，把流式推理、工具调用、Skills、多图 prompt 和持久会话都画进终端。它本身是 DSH 生态的 terminal surface 插件，推荐装到 `tui` profile 后用 `dsh --profile tui` 启动。

## 核心能力
- 实时呈现 agent 时间线：流式推理、回复、工具参数与结果、subagent 生命周期，以及本回合 token 与 cache 用量
- 读取 ACP agent 自身声明的模型、权限、认证方式、可用命令，与内置命令合并到一个可搜索、可滚动的 `/` 斜杠菜单
- 多图 prompt：从文件、剪贴板或粘贴暂存最多 8 张图片，发送时以可编辑的 `[image n]` chip 内联在草稿里
- 终端友好的 Markdown 渲染：标题、列表、引用、代码块、行内代码、强调、删除线、链接、图片，并保留 CJK/Latin 混排
- 高密度工具视图：长结果默认只保留末四行可点击展开，状态（进行中/成功/失败）一目了然
- 长会话控制：回合中可排队 follow-up，也能立即 steer 当前回合；持久 JSONL 会话通过 `/new`、`/resume` 和 `--session-id` 管理
- 跨平台输入：readline 编辑、上下文快捷键、macOS 的物理 ⌘/⌥、Linux/Windows 的 ctrl 组合键统一手感
- 终端原生界面：明暗主题、窄屏自适应、鼠标选择、原生/tmux/OSC 52 剪贴板，支持 kitty graphics protocol 的图片预览与可选的 `/liang` 像素宠物

## 技术实现
- **语言**: TypeScript / Node.js（npm 端的 Cordis client 树）+ Rust / ratatui（终端绘制与状态机）
- **关键依赖**: `@deepseek-ai/cordis`（Cordis 插件容器）、`@openma/deepseek-harness-acp`（运行时携带的 ACP 客户端，作为 agent 端点）、`agent-client-protocol` Rust crate（与 agent 通信）、`ratatui` + `tui-markdown`（终端渲染）
- **架构模式**: 双进程 Cordis 架构。Host 进程在自己的 Base Cordis 树挂 ACP plugin，再由它启动独立的 TUI Client 子进程；两棵树只通过子进程的标准 stdin/stdout 上的 ACP 协议通信，Client 进程的 fd 3/4 仅承载用户 TTY（Unix）或带随机 token 的 loopback TCP（Windows）。插件通过 Cordis service（`tuiTheme`、`tuiSlots`、`tuiCommands`、`tuiOverlay`、`acpSessionConfig/Plan/Stats`）扩展；主题与视图能力协商后走 `_dsh/cordis/*` 与 `_dsh/cordis/tui/*` 扩展点
- **入口文件**: `npm/bin/dsh-tui.js`（CLI shim）、`npm/lib/index.js`（`dsh-tui-shell` Cordis 插件，负责 spawn Rust painter 并 mux ACP + compositor）、`src/main.rs`（Rust 入口）

## 适用场景
想在终端而不是浏览器里使用 DeepSeek Harness 的用户，特别是依赖 tmux/ssh、需要快速键鼠操作、想脚本化调用或不喜欢开浏览器窗口的开发者。它也适合做 demo：单独跑 `--demo` 不需要配置 API key 就能浏览 UI 体验；带 `--demo-skin` 还能换上内置的 `ember` 配色包看主题切换效果。

## 前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| Node.js | >= 18 | npm 端的 Cordis client tree 与 CLI shim 需要 Node 18 及以上 |
| DeepSeek Harness | 0.1.0-rc.6+ | 安装命令自动处理；本插件在 devDependencies 中声明 `@deepseek-ai/dsh@0.1.0-rc.6` |
| ACP 客户端（`dsh-acp`） | 0.4.13+ | 作为运行时依赖携带，profile 主路径自动挂载；standalone 模式下也可指定别的 ACP server |
| 操作系统 | macOS arm64/x64、Linux arm64/x64、Windows x64 | Linux x64 自 0.2.x 起改为静态 musl 链接，不依赖宿主 glibc 版本 |
| 原生模块 | 无 | Rust 二进制预编译并随包发布到 `npm/vendor/<platform>-<arch>/`，不走 node-gyp |

## 安装方式
```bash
dsh plugin --profile web add github:openma-ai/deepseek-harness-tui
```

## 配置项
本插件无需额外配置。`/auth`、`/model`、`/agent`、`/effort`、`/plan`、`/permission`、`/theme`、`/keys`、`/help`、`/image`、`/clip`、`/liang`、`/new`、`/resume`、`!cmd` 等行为由 agent 自身能力、运行时状态或运行时命令直接驱动。

下列环境变量只在开发与排障时使用，普通用户无需关心：

| 环境变量 | 用途 |
|---|---|
| `DSH_TUI_BIN` | 覆盖 Rust painter 路径，本地用 `cargo build` 产物调试时使用 |
| `DSH_TUI_AGENT` | 覆盖 standalone 入口默认查找的 ACP agent 命令 |
| `DSH_TUI_FORCE_TCP=1` | 在 Unix 上强制走带 token 的 loopback TCP（默认 Windows 才走 TCP） |
| `DSH_HOME` | 覆盖 DSH profile 与 home 目录查找路径 |

## 常见问题

**Q: 装好后还需要额外配置吗？**

A: 不需要。安装命令会自动创建 profile 并把 TUI、ACP 依赖一并装上，直接 `dsh --profile tui` 就能用；只有调试本地 Rust 编译产物时才需要 `DSH_TUI_BIN` 环境变量。

**Q: 没装 DSH Harness 也能跑吗？**

A: 可以。独立入口 `dsh-tui` 可以 `--agent dsh-acp` 或 `--agent dsh --agent-arg --profile --agent-arg acp` 接任意支持 ACP 协议的 agent；`--demo` 模式不需要任何 agent 或 API key 就能看 UI。

**Q: 支持哪些操作系统？**

A: macOS（arm64 / x64）、Linux（arm64 / x64）、Windows（x64）。Linux x64 包从 0.2.x 起改为静态 musl 链接，能直接在老发行版（如 Ubuntu 20.04）上跑，不需要 glibc 兼容层。

**Q: 不支持 DSH 私有扩展的 ACP agent 也能用吗？**

A: 可以。当 agent 在 `initialize` 的 `_meta.dsh.cordis` 里没声明该扩展时，TUI 只走标准 ACP（prompt、session、auth、update），不会出现兼容性问题。

**Q: 输入框旁边的小难梁宠物不显示怎么办？**

A: 只有 Ghostty、Kitty、WezTerm 等支持 kitty graphics protocol 的终端才会显示 RGBA 像素精灵；其他终端退回半块字符鲸鱼，且宽度低于 60 列时会自动隐藏。主界面功能不受影响。

**Q: 怎么卸载？**

A: 通过 `dsh plugin --profile tui remove @openma/deepseek-harness-tui` 即可，会同时撤销 profile 里的 TUI bundle 与配套的 ACP/Host rows。

**Q: 报 `spawn dsh-acp ENOENT` 怎么办？**

A: 没找到默认 agent 二进制。可以装 DSH 官方 ACP 客户端（`dsh-acp`），或者用 `--agent` 显式指向另一个 ACP server，例如 `--agent <其它 ACP 命令>`。

**Q: 安装包提示 `no native binary for ...` 怎么办？**

A: 当前安装版本没覆盖你的平台（darwin-arm64/x64、linux-arm64/x64、win32-x64 之外）。确认装的是最新版，或在本地跑 `scripts/build-npm.sh` 自己编译打包。

## 上手难度
入门 — 安装一行命令即可使用，进阶用户再去读 `docs/plugins.md` 写客户端插件扩展主题、插槽、命令等。

## 已知问题与限制
- 对话时间线插槽（`conversation.chat`）尚未开放；当前插件只能贡献 `chrome.right`、`conversation.input.dock`、`conversation.composer.dock`，ACP `session/update` 仍是 transcript 唯一真源，插件节点不能替换 composer 或伪装成会话事件
- "完全插件化"仍是目标架构，form 控件、更多 shell/conversation slot、运行时诊断面板与独立的 `ViewPreset` 仍在迁移路线图上，详见 `docs/migration.md`
- 第三方插件严格被限制只能拿到 `tuiTheme`/`tuiSlots`/`tuiCommands`/`tuiOverlay`/ACP session services 这些语义 API；TTY、raw mode、ratatui、kitty 转义、绝对行列坐标与 JSON-RPC 方法表不对插件开放，强行通过运行时直接读 stdin 或 ratatui 状态的写法会被新版本破坏
- 输入框旁的 `/liang` 像素宠物只在支持 kitty graphics protocol 的终端上以 RGBA 像素显示，其他终端退回半块字符鲸鱼；终端宽度低于 60 列时直接隐藏（README.md:312-314）
- 安装包如果提示 `no native binary for ...`，是因为该平台不在打包矩阵内（darwin-arm64/x64、linux-arm64/x64、win32-x64），需要本地用 `scripts/build-npm.sh` 自编译，或换装匹配平台的包

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [deepseek-harness-tui](https://deepseek-plugin.org/plugins/openma-ai/deepseek-harness-tui)
Wiki generated by AI (model: `MiniMax-M3`)