DeepSeek Harness CLI

基于 OpenTUI 0.5.x + SolidJS 构建的 DeepSeek Harness (DSH) 终端客户端。

它直接驱动本地运行的 DeepSeek Harness 实例：会话、工具调用、权限审批、计划模式、历史记录全部由 harness 持有，本客户端负责把它们渲染成一个流畅的终端界面——MiMo 风格启动屏、工具卡片动画，并在终端支持 Kitty/Sixel 图形协议时显示真正的 SVG 图标。不需要本地 API Key。

   dsh-cli                    # 探测并连接本地 harness
   dsh-cli -c                 # 直接恢复最近一次会话
   dsh --profile tui          # 作为 harness 组件以 TUI 模式启动

功能特性

会话管理：新建 / 恢复 / 重命名 / 分叉会话，-c 快速续接最近会话
流式渲染：正文、推理（Think 块）、工具调用增量实时渲染，30fps 下保持流畅
工具卡片：Bash / Read / Edit / Write / Search / Code / Todo / Question / Terminal / Job 等工具行分类，含摘要、展开正文、diff 查看器与运行闪光动画；行首图标使用 DSH web 客户端官方 SVG（预渲染为 PNG），通过 Kitty / Sixel 图形协议显示，不支持时自动回退 Unicode 字形
Think 块：推理内容以可折叠块呈现，与工具行共用闪光动画和 hover 折叠箭头交互
权限审批：harness 抛出的权限 / 提问 / 计划审批以弹窗呈现；权限请求支持多选 checkbox（Space 切换、a/n/i/l 全选 / 全不选 / 反选 / 只选最新、Enter 一次确认全部、Esc 全部拒绝）；沙箱升级授权（如写回 Windows D 盘）提供「允许本次 / 当前会话允许 / 拒绝」三个选项
计划模式：/plan 进入 / 退出计划模式，徽标实时反映 active/pending 状态
图片附件：Ctrl+V（或 /image clipboard）从宿主剪贴板粘贴图片，/image <路径> 附加本地图片；复制图片文件时剪贴板里的文件路径会被自动识别为附件。Windows Terminal / WSL2 会把 Ctrl+V 拦截成终端粘贴，粘贴事件同样会被识别——Windows 截图（Win+Shift+S）后直接在 WSL2 的 dsh-cli 里按 Ctrl+V 即可附加。图片以 base64 内容块真正发给 harness（视觉模型如 DeepSeek-V4-Flash-Vision-Exp 可直接看图）；输入区与会话内支持 Kitty/Sixel 缩略图，无图形协议时回退为文本标签
Slash 命令：本地命令 + harness 宿主命令 + 技能统一收录在 / 菜单
队列停靠：待发 / 引导中的消息可直接编辑、移除或发送
统计栏：轮次、步骤、LLM/工具耗时、首 token 平均、缓存命中率、token 用量
健壮连接：断线自动重连、流式卡死看门狗、从持久历史恢复会话
内置 skills：Ai-Thinker skills 技能集随 npm 包分发（vendor/），首次启动直接链接，无需联网克隆仓库

环境要求

需要 Node.js 22+（推荐 LTS）：harness 的 MCP 客户端用到了 Promise.withResolvers()，该 API 从 Node 22 起才可用。安装包自带固定版本 Bun 1.3.14（作为 @oven/bun-* 平台包随 npm 安装），harness 与 pnpm 在首次启动时自动补齐；只有从源码构建才额外需要 Bun。本地 DeepSeek Harness 实例在所有安装方式下都是可选的：dsh-cli 会自动探测并拉起。

Bun 以可选依赖（@oven/bun-*）随包分发，所以普通 npm install -g 无需再单独安装 Bun。如果该可选依赖被跳过（--omit=optional/--no-optional、平台/架构太特殊、或内网镜像拉不到对应二进制），dsh-cli 会依次回退到 ~/.bun/bin 再回退到 PATH；若两者都没有，会在启动时报出明确的 "bun is required" 提示——这时需自行安装 Bun（npm i -g bun，或按 https://bun.sh/install 安装）。

安装

一条命令安装（推荐）

npm install -g @ai-thinker/deepseek-harness-cli

这一条命令安装插件本体，并随依赖带上固定版本 Bun 1.3.14 与 OpenTUI 各平台原生库。@deepseek-ai/dsh（harness）、pnpm（harness 搭建 profile 需要）与 tui profile 会在首次启动时自动补齐/注册。装完即可直接运行，无需任何手动配置：

dsh-cli              # 自动探测 http://127.0.0.1:3081 上的 harness
                     # 没有则自动拉起 dsh --profile tui
dsh-cli -c           # 恢复最近一次会话并直接进入

想先快速体验、不全局安装？

npx @ai-thinker/deepseek-harness-cli

npx 临时运行同样在首次启动时自动补齐缺失部分；Bun 已随包分发，无需单独安装。

手动安装（可选）

想自己逐个安装？

安装 Bun（仅源码构建需要；安装版已随包自带 Bun 1.3.14）：

Linux / macOS：
```
curl -fsSL https://bun.sh/install | bash
```
Windows（PowerShell）：
```
powershell -c "irm bun.sh/install.ps1 | iex"
```
或用包管理器（各平台通用）：
```
npm install -g bun
# winget install Oven-sh.Bun
# scoop install bun
```
Windows 下建议在 WSL 中运行本项目——终端体验一致，USB 类工具也需要通过 WSL 的 usbip 附加。

Windows 客户端直连 WSL 里的 harness 时，客户端会自动把 D:\... 工作目录翻译成 WSL 可见路径（/mnt/d/...）再创建会话；如需手动指定，可设置 DSH_CWD（例如 wslpath -u 'D:\Users\Seahi\Desktop' 的输出）。
安装 DeepSeek Harness CLI（可选）——dsh-cli 也可以通过 npx 自动拉起 harness，但全局安装能让启动更快：
```
npm install -g @deepseek-ai/dsh
```

安装 dsh-cli——用上面的 npm 一条命令，或从源码安装：

git clone [email protected]:Ai-Thinker-Open/DeepSeek-Harness-CLI.git
cd DeepSeek-Harness-CLI
bun install
bun run build
bun link          # 把全局 `dsh-cli` 命令暴露出来

然后运行 dsh-cli（或 dsh-cli -c）。首次启动若 dist/ 缺失会自动构建，没有运行中的 harness 时也会自动拉起。

安装时会安装 / 检查哪些包（知情说明）

dsh-cli 在首次启动时会自动检查/补齐以下依赖（均为常规 npm 生态包，缺失时才安装，已有正确版本不会重复安装）：

@ai-thinker/deepseek-harness-cli 本体：内置 Ai-Thinker 技能（随 npm 包分发，离线可用）。
Bun 1.3.14：终端客户端运行时，作为 @oven/bun-<平台>-<arch> 平台包随依赖安装。Windows 上 bun 1.4+ 会触发 OpenTUI 段错误，因此运行时优先使用包内 1.3.14 并拒绝 1.4+。
@deepseek-ai/dsh：DeepSeek Harness 服务端（缺失时通过 npm 自动安装）。
pnpm：harness 构建 tui profile 所需（缺失时自动安装）。
dsh-cli 自身与 @deepseek-ai/dsh 采用「静默强制后台更新」：每次 dsh-cli 启动时后台查询 npm registry 并暂存新版到临时目录（把待更新写入 ~/.dsh/.updates-pending.json），下次启动在拉起 harness 前自动 npm install -g <pkg>@<最新版>，本次启动即运行最新版。不再弹出更新确认窗，失败静默回退当前版本、不阻塞（可用 DSH_NO_UPDATE_CHECK=1 关闭）。
首次启动的 bootstrap（可跳过）：把内置技能链接到 ~/.dsh/skills。

以上行为均可用环境变量控制：DSH_SKIP_BOOTSTRAP=1 跳过全部 bootstrap，DSH_NO_SKILLS=1 跳过技能链接，DSH_NO_UPDATE_CHECK=1 关闭启动时对 dsh-cli 自身与 harness 的更新检查，DSH_SKIP_RISK_CONFIRM=1 关闭目录风险确认。完整列表见 CHANGELOG.md。

快速开始

bun install
bun run build        # 产出 dist/cli.js, dist/startup.js, dist/runner.js, dist/dispatcher.js
bun link             # 可选：把 bin/dsh-cli 装到全局

然后直接运行：

dsh-cli              # 自动探测 http://127.0.0.1:3081 上的 harness
                     # 没有则自动安装 tui profile 并拉起 dsh --profile tui
dsh-cli -c           # 恢复最近一次会话并直接进入

bin/dsh-cli 是薄壳：dist/ 缺失时先自动构建，再把参数转交给 dist/dispatcher.js。

作为 DeepSeek Harness 组件运行

本包同时是一个 Cordis 插件（通过 package.json 的 dsh.bundle.patch 挂载 cordis.patch.yml），可以像其它 harness 界面一样启动：

标准安装方式是把本包作为 bundle 注册进 harness：

dsh plugin --profile tui add @ai-thinker/deepseek-harness-cli

注册后即可用任意 dsh 界面方式启动：

dsh --profile tui                        # 以 TUI 模式启动 harness + 终端客户端
dsh --profile tui --port 0               # 让系统分配空闲端口
dsh --profile tui --cwd ~/my-project     # 指定会话工作区
dsh --profile tui -c                     # 恢复最近会话

启动后 tui-runner 插件会读取已绑定的 web server 地址，通过 DSH_URL / DSH_CWD 拉起终端客户端，并在客户端退出时关闭整个 dsh 进程。

命令行选项（`dsh --profile tui`）

选项	说明
`--host <host>`	绑定地址，仅允许回环 `127.0.0.1`（默认值）
`--port <port>`	监听端口，`0` 表示由系统分配（默认 `3081`）
`--cwd <dir>`	新会话的工作目录（默认调用目录）
`-c, --continue`	启动时恢复最近一次会话
`-h, --help`	显示帮助

dsh-cli -c 也会把 --continue 转发给客户端。

支持多终端实例并存：默认端口 3081 已被占用时（包括 Windows 侧实例经 WSL2 localhost 转发「镜像」进 WSL 的隐形占用），新的 dsh --profile tui 会自动改用空闲端口并提示，而不是报 EADDRINUSE 失败；显式 --port 始终优先。再开一个 dsh-cli 则会直接复用已在运行的 harness——包括因 3081 被占用而避让到 3082+ 的那个实例：启动器会探测 3081 及其后 10 个端口（DSH_HARNESS_SCAN_PORTS）；若默认端口被非 harness 进程占用，还会打印占用它的 PID，而不只是建议 fuser -k。

环境变量

变量	说明
`DSH_URL`	harness 地址（默认 `http://127.0.0.1:3081`）
`DSH_HARNESS_SCAN_PORTS`	在 `DSH_URL` 之上继续探测的端口数，用于发现已运行的 harness（默认 `10`，置 `0` 关闭）
`DSH_NO_TERMINAL_FALLBACK`	置 `1` 关闭「终端失败后自动用保守渲染模式重试一次」
`DSH_CWD`	会话工作目录（默认当前目录）
`DSH_DEBUG`	置 `1` 时输出协议与调试日志
`DSH_HOME`	harness 数据目录（默认 `~/.dsh`）
`DSH_NPX_CACHE`	npx 缓存目录，加速 `dsh` 解析（默认 `~/.npm/_npx`）
`DSH_TOOLS_MODE`	进程级 Code Mode 开关（透传给 tools 行）
`OPENTUI_IMAGE_PROTOCOL`	图标渲染协议覆盖：`auto` / `kitty` / `sixel` / `blocks`
`OPENTUI_GRAPHICS`	置为 `false` 关闭 Kitty/Sixel 检测（图标回退为字形）
`DSH_SKIP_BOOTSTRAP`	置 `1` 完全跳过首次启动的资源安装
`DSH_NO_SKILLS`	置 `1` 跳过 Ai-Thinker skills 安装
`AT_SKILLS_URL`	未内置时 skills 仓库 git 地址（默认 `https://github.com/Ai-Thinker-Open/skills.git`）

内置资源

发布到 npm 的包自带运行资源，npm install -g 后即可离线启用：

vendor/ai-thinker-src：Ai-Thinker skills 仓库，首次启动把 skills/ 下的技能包链接进 ~/.dsh/skills/；

OpenTUI 原生库与 Bun 运行时不再随包体打包，而是通过官方 npm 平台包（@opentui/core-<平台>-<arch>、@oven/bun-<平台>-<arch>）在安装时按当前平台解析；换平台使用需要重新安装（例如 Windows 上装的包不能直接在 WSL 里运行）。

正常启动时不输出 bootstrap/启动进度信息，只有错误会打印到终端；需要详细日志时设置 DSH_DEBUG=1。harness（dsh）本身也支持全平台，但必须使用与运行平台一致的安装：WSL 里请用 WSL 的 npm 安装 @deepseek-ai/dsh，不要在 WSL 里运行 Windows 侧安装的 dsh。

首次启动（无论全局还是 npx 临时运行）都会自动补齐 harness 与 pnpm、注册 tui profile；Bun 已随包分发，无需额外安装。

运行时兜底依然保留：包内找不到 Bun 时会自动查找 ~/.bun/bin/bun(.exe) 或 PATH，dsh 缺失走 npx，pnpm 缺失自动安装。Windows 下所有子进程调用都兼容 .cmd shim，全平台一致。

常用操作

操作	说明
`Tab` / `Shift+Tab`	切换权限预设：`read-only` → `workspace-write` → `full-access`
`/`	打开命令菜单（本地 / host / 技能，按前缀过滤）
`Esc`	执行中取消当前回合 / 关闭菜单 / 返回主页 / 拒绝当前问题与权限申请
`Enter`	发送消息 / 确认选择
`↑↓`	菜单与选项移动
`Ctrl+V`	从宿主剪贴板粘贴图片到输入区（剪贴板无图片时按文本粘贴）
鼠标	点击展开工具卡片、队列行；hover 工具行显示折叠箭头；拖动选择文本（OSC52 复制）
`Ctrl+C`	退出

Slash 命令

本地：/sessions、/resume、/model、/rename、/fork、/image <路径|clipboard>、/help
host（由 harness 执行）：/compact、/feedback、/goal、/plan、/permission、/export
技能：会话的技能目录会并入 / 菜单，作为普通消息交给模型
MCP 风格：/server:tool 形式的输入走消息通道

开发

bun run dev           # 直跑 src/cli.tsx（需先有一个 harness 或 mock）
bun run dev:debug     # DSH_DEBUG=1 的调试模式
bun run icons         # 重新渲染 SVG 图标为 PNG，并重新生成 src/assets-icons.ts
bun run build         # 打包 dist/（把 solid-js 固定到客户端运行时）
bun run typecheck     # tsc --noEmit
bun test              # 全量测试（协议 / 事件折叠 / 渲染帧 / 交互）

图标

工具与 Think 图标以 SVG 形式存放在 assets/icons-src/：来源是 DSH web 客户端官方图标集（deepseek-ai/DeepSeek-Harness 的 packages/client/ui-primitives/src/icons），另有 TUI 专属的 terminal 自绘图标（job 使用官方齿轮图标）。bun run icons 会把每个图标渲染成 assets/icons/ 下的 64×64 PNG，并重新生成 src/assets-icons.ts（base64 data URL 模块），因此 bundle 不依赖运行时资源路径。界面上的 ToolIcon 在终端支持 Kitty / Sixel 图形协议时渲染 PNG（2 格宽），否则回退 Unicode 字形；tmux、普通 SSH 会话会自动使用字形。

没有真实 harness 时，用内置 mock 服务器联调 TUI：

bun scripts/mock-dsh-server.mjs           # 监听 127.0.0.1:3080
PORT=3456 bun scripts/mock-dsh-server.mjs # 换端口
MOCK_SLOW=1 bun scripts/mock-dsh-server.mjs  # 放大时序便于观察流式动画

DSH_URL=http://127.0.0.1:3080 bun run dev

mock 服务器实现了 DSH 协议（/api/<method> 一元 RPC、events.mux WebSocket 下行、/api/respond），收到 "ask …" 会触发权限提问（"ask multi permission" 会一次抛三条请求，方便验证多选弹窗）；消息里含 "问卷" / "ask-user" / "调研" 会一次抛出三道 ask-user 问题，用来验证分页审阅（Enter 记录并自动翻到下一题、←/→ 回看、最后一题按 Enter 后底部出现"确认全部"、再按一次 Enter 才提交、Esc 整批拒绝）；其余消息会按关键词回放一轮带工具调用的脚本回合（bash / read / grep / edit），方便观察工具卡片的闪光动画。

架构概览

bin/dsh-cli                   入口壳（缺 dist 自动构建）
  └─ src/dsh/dispatcher.ts    探测已有 harness → 直接跑 TUI；否则拉起 dsh --profile tui
dsh 进程内（cordis.patch.yml）
  └─ src/dsh/startup.ts       --host/--port/--cwd/-c 解析，提供 tuiStartup 服务
  └─ src/dsh/runner.ts        读 webServer 地址，spawn dist/cli.js，客户端退出时关停 dsh
TUI 进程
  └─ src/cli.tsx              OpenTUI renderer 配置
  └─ src/app.tsx              应用外壳：屏幕切换 / 权限模式 / toast / 命令路由
  └─ src/screens/*            home 与 session 两个屏幕
  └─ src/harness/session.ts   会话驱动核心：事件折叠 / mux 循环 / 重连 / 统计
  └─ src/harness/client.ts    DSH /api HTTP + events.mux WebSocket 传输
  └─ src/harness/fold.ts      事件 → ChatMessage 纯函数
  └─ src/harness/tool-card.ts 工具行分类 / 摘要 / 卡片模型 / diff
  └─ src/components/*         16 个 UI 组件（prompt / message-view / markdown / logo / tool-icon …）
  └─ src/assets-icons.ts      生成的图标 data-URL 模块（见 scripts/icons.mjs）

关键设计

双重身份：同一个包既可作为独立 CLI，也可作为 Cordis 插件在官方 dsh 进程内运行
只渲染变化：Solid <For> 按对象身份 memoize，配合脏标记 32ms 批量刷新，流式 chunk 洪峰下不卡顿
SVG 图标 + 优雅回退：官方 DSH 图标预渲染为 PNG（bun run icons），终端支持 Kitty/Sixel 时用图形协议显示，否则统一回退 Unicode 字形
单一 Solid 运行时：构建时把裸 solid-js 导入改写为客户端入口（solid-js/dist/solid.js），保证 bundle 与 @opentui/solid 共享同一运行时——双运行时会破坏渲染器上下文
快速工具延迟结算：读文件等毫秒级工具的结果延迟 600ms 呈现，让运行闪光动画可见
自愈连接：downlink 卡死 20s 触发看门狗 → 重连 + 从持久历史重建会话
键盘兼容：同时处理传统转义序列、DECCKM 与 kitty CSI-u 协议

目录结构

bin/              CLI 入口壳
assets/           icons-src/（SVG 源）+ icons/（生成的 PNG）
cordis.patch.yml  dsh 插件补丁（profile 行配置）
scripts/          build.ts 构建脚本、icons.mjs 图标管线、mock-dsh-server.mjs 开发用 mock
src/
  cli.tsx         OpenTUI 入口
  app.tsx         应用外壳
  screens/        home / session 屏幕
  harness/        会话驱动、传输、事件折叠、工具行模型
  components/     UI 组件
  dsh/            Cordis 插件（startup / runner / dispatcher / types）
  assets-icons.ts 生成的图标 data-URL 模块
test/             Bun 测试（协议、折叠、渲染帧、交互）

License

MIT

deepseek-harness-cli

Install

Source

Creators

Readme

功能特性

环境要求

安装

一条命令安装（推荐）

手动安装（可选）

安装时会安装 / 检查哪些包（知情说明）

快速开始

作为 DeepSeek Harness 组件运行

命令行选项（`dsh --profile tui`）

环境变量

内置资源

常用操作

Slash 命令

开发

图标

架构概览

关键设计

目录结构

License

Install

Source

Creators

Readme

功能特性

环境要求

安装

一条命令安装（推荐）

手动安装（可选）

安装时会安装 / 检查哪些包（知情说明）

快速开始

作为 DeepSeek Harness 组件运行

命令行选项（dsh --profile tui）

环境变量

内置资源

常用操作

Slash 命令

开发

图标

架构概览

关键设计

目录结构

License

命令行选项（`dsh --profile tui`）