终端交互界面 DanielOu1208/deepseek-harness-tui

DeepSeek Harness TUI

面向官方 DeepSeek Harness 的专注、终端原生界面。

CI
CodeQL
Node.js 22.19+
License: MIT

使用隔离的 Harness home 从编译后的 TUI 中实际截取。未使用任何模型请求或私有会话数据。

一个面向官方 DeepSeek Harness 的独立终端 UI，使用 @earendil-works/pi-tui 渲染。

本包不会 fork 或替换 Harness。官方运行时仍然负责 agent 循环、模型、工具、权限、会话、检查点、压缩、目标、技能、MCP、子代理、配置文件和凭据。本包添加了 deepseek 启动器、一个 Cordis 配置文件包，以及终端交互层。

状态： 实验性 MVP，固定使用 DeepSeek Harness 0.1.0-rc.6。在 Harness 仍为预发布软件期间，请保持启动器和配置文件包版本一致。

亮点

| 官方运行时 | 在不 fork Harness agent 循环或持久化模型的情况下，添加终端交互层。 |
| 快速控制 | 无需离开输入框即可切换 plan/build 模式、推理强度、转录详情和权限。 |
| 持久化工作流 | 按工作区恢复、重命名、fork、归档、检查、导出和整理会话。 |
| 可见状态 | 查看当前活动模型、推理级别、权限模式、工作状态和大致上下文占用情况。 |

要求

- Node.js 22.19 或更新版本
- 一个 DeepSeek API key
- macOS、Linux 或 Windows

安装

一次全局安装即可提供启动器、匹配的官方 Harness 0.1.0-rc.6 运行时，以及此 TUI 包：

npm install --global --install-links github:DanielOu1208/deepseek-harness-tui

请保留命令中的 --install-links。对于 GitHub 源码安装，它会让 npm 将包复制到全局前缀中，而不是让启动器链接到 npm 的临时检出目录。

在不创建或更改 Harness 状态的情况下确认启动器：

deepseek --version
deepseek --help
第一次普通的 deepseek 启动会通过官方 Harness profile API 在 $DSH_HOME/profiles/tui（通常是 ~/.dsh/profiles/tui）下创建或补全官方 tui profile。现有的 profile 文件和用户补丁层会被保留。

认证

使用掩码终端输入存储密钥：

deepseek auth

密钥通过官方 Harness 凭据服务写入。它使用 $DSH_HOME/.credentials.yaml（通常是 ~/.dsh/.credentials.yaml），遵循 Harness 文件安全规则，并且从不打印密钥。

在不泄露凭据的情况下检查认证状态：

deepseek auth status

移除由 Harness 存储的密钥：

deepseek auth logout

登出会请求确认，并默认保留凭据。

继承的 DEEPSEEK_API_KEY 优先，并且有意设为只读。当它存在时，auth、auth status 和 auth logout 会说明环境正在提供当前生效的密钥。请在启动 deepseek 的 shell、服务、CI 配置或其他环境中更改或取消设置它；启动器不会声称覆盖或移除它。

从项目或用户 .env 文件继承的密钥也会连同其来源一并报告。deepseek auth logout 不会声称删除这些文件；请改为从所报告的 .env 来源中移除该密钥。

运行

deepseek
deepseek "explain this repository"
deepseek --cwd /path/to/project
deepseek --resume session-xxxxxxxx

参数会原样转发给官方 Harness tui profile。标准输入、标准输出、标准错误、终止信号以及 Harness 退出状态都会由启动器传递。

在 TUI 内：

- Enter 提交提示词。
- Escape 关闭当前菜单或问题，而不停止 agent。
- Ctrl+C 关闭打开的 panel 并停止当前回合；再次按下则退出。
- 当提示词为空时，Ctrl+D 退出。
- F2 打开设置列表。
- Shift+Tab 在 plan 和 build 模式之间切换。在活动回合期间，Harness 会在下一个安全的模型步骤应用该切换。
- Shift+Up 和 Shift+Down 提高或降低下一次模型请求的推理强度。该快捷键会在所公布的最高和最低级别处停止。
- 当平台提供支持时，Ctrl+V 从系统剪贴板附加受支持的图像；/attach path 是可移植的备选方案。
- Up/Down 和 Enter 操作菜单；Space 切换复选框答案。
- / 打开 Harness 命令。
- @ 打开文件补全。
- Transcript detail 默认为 Normal，可从 F2 → Transcript detail 更改。

页脚显示相对于活动模型容量的近似上下文占用，例如 ctx ~42K/1M (4%)。该估算描述的是下一次提示词，而不是计费用量，并且会在压缩后立即更新。在第一个 provider 用量样本之前，页脚会将已知容量显示为 ctx —/1M。
未知的斜杠命令会提交给官方 Harness 命令服务。其可用性取决于所组合的配置文件。

常见的本地命令：

| 命令 | 用途 |
| /help | 显示本地和官方 Harness 命令 |
| /new | 启动一个新会话 |
| /sessions、/resume | 按标题、ID 或工作目录搜索会话 |
| /resume | 直接打开已知会话 |
| /session [session-id] | 重命名、分叉或单向归档会话 |
| /workspaces | 按工作区浏览未归档的会话 |
| /model、/reasoning | 更改下一次模型请求 |
| /permission | 设置 read-only、workspace-write 或 danger-full-access 工具访问权限 |
| /settings 或 F2 | 打开 Pi 风格的设置列表 |
| /busy | 在代理运行时选择排队或引导行为 |
| /queue [prompt] | 管理排队的工作或将单独的后续轮次加入队列 |
| /steer | 在当前轮次的下一个安全步骤注入指导 |
| /attach [path] | 管理待处理的图像或附加 PNG、JPEG、GIF 或 WebP 文件 |
| /deliverables | 浏览成功的变更工具所报告的路径 |
| /inspect | 搜索模型步骤、工具调用、嵌套调用、计时和错误 |
| /stats | 显示整个会话的计时以及提供方令牌/缓存总计 |
| /activity | 检查后台作业、工作流和子代理后代 |
| /export [markdown\|json] | 原子性地导出当前会话，并移除已识别的图像负载 |
| /stop | 停止当前轮次并保持 TUI 打开 |
| /pause | 停止、刷新、打印恢复 ID 并退出 |
| /exit | 刷新并退出 |

旧的单数拼写 /setting 仍为兼容性而接受，但在补全和帮助中隐藏。

会话导航器按最近活动排序，并包含当前会话、持久化的非子代理分叉会话、工作目录和短会话 ID。/new 创建一个不相关的会话；/session 可以在已完成轮次的边界处创建分叉。子代理拥有的会话不进入普通导航，可在 /activity 下查看。当有排队消息等待时，切换会被阻止，因为否则处置活动的 Harness 代理会丢弃该排队工作。如果某个轮次正在运行且没有排队工作，TUI 会在停止前询问。

在 Harness 0.1.0-rc.6 中，归档是单向的：/session 会给出强烈警告并默认选择取消。归档日志仍然持久保留，可通过 /sessions archived 找到，但当前运行时没有暴露安全的取消归档操作。

裸 /queue 可以查看待处理工作、就地替换纯文本项，以及移除尚未被认领的项。运行时未暴露队列重排序功能，因此 TUI 不会用私有的收件箱状态来模仿它。
文本草稿按会话保存在 $DSH_HOME/tui/drafts/v1 下，使用仅所有者可访问的私有文件，并在导航期间恢复。待处理的图片有意不持久化。TUI 通过官方附件服务验证并存储图片，在终端历史中显示 [image]，且不要求终端特定的内联图形支持。

/export 在写入仅所有者可访问的 Markdown 或带版本号的 JSON 文件之前，会先刷新当前会话。官方图片附件、常见的 image/image_url 记录、二进制值以及 data:image URL 的原始或编码载荷会被移除，而引用元数据会被保留。插件事件结构是可扩展的，因此分享导出内容前请务必检查；导出内容仍可能包含敏感提示词、工具输出、本地路径以及无法识别的插件自定义数据。

danger-full-access 允许不受限制的工具访问。仅当当前会话和工作目录可信时才使用它。

转录详情

TUI 在保持用户提示词和助手回答可读的同时，减少内部转录噪声：

- Compact 显示单行上下文和工具活动。
- Normal 增加结构化的工具结果和有用的简短预览。
- Debug 显示有界推理、注入的上下文、工具输出和常规运行时事件。

所选模式全局保存在 Harness dsh-tui 设置命名空间中，并实时生效。它仅改变终端呈现：模型上下文和持久会话事件保持不变。调试输出仍有渲染安全限制；对于更大的原始内容，持久化的 Harness 会话仍是权威来源。

运行时和提供方设置

F2 包含只读的提供方能力与 Host 插件摘要。提供方配置文件仍位于 $DSH_HOME/settings.yaml；TUI 配置文件组合仍位于 $DSH_HOME/profiles/tui；用户代理预设仍位于 $DSH_HOME/.agent-presets。已注册的设置命名空间仍可从 F2 → Advanced runtime settings 更改。凭据从不显示；使用 deepseek auth status 检查其来源。

F2 → Support and feedback 会调用官方 /feedback 命令。其确认信息会说明会话共享是已启用、受反馈门控、已禁用还是未配置。

更新

npm install --global --install-links github:DanielOu1208/deepseek-harness-tui
deepseek --version

启动器会将随附的 Harness 包保持在匹配的 0.1.0-rc.6 版本线上。更新全局包不会清除会话、凭据、设置或用户拥有的配置文件补丁。

卸载

npm uninstall --global @chalk/dsh-tui

卸载该包会保留 $DSH_HOME 下的 Harness 用户数据。仅当你确实想要同时删除凭据、设置、配置文件和会话时，才移除该目录。

本地开发

git clone https://github.com/DanielOu1208/deepseek-harness-tui.git
cd deepseek-harness-tui
npm install
npm test
npm run build
npm link
deepseek --help

要在不接触真实 Harness 主目录的情况下测试打包构建，请将 DSH_HOME 指向一个临时目录，并直接调用编译后的启动器。

架构

deepseek launcher
-> official dsh profile boot (tui)
-> @deepseek-ai/dsh-base
-> @chalk/dsh-tui
-> pi-tui terminal interaction

捆绑包覆盖层是 cordis.patch.yml。它将此启动解析器和 TUI 运行器组合在 @deepseek-ai/dsh-base 之上；它不会将 Harness 运行时复制到此仓库中。

实时更新的 Web–TUI 能力对等矩阵 记录了哪些功能受支持、有意保持终端原生，或仍在计划中。

故障排除

deepseek: command not found

启用链接复制后重新安装：

npm install --global --install-links github:DanielOu1208/deepseek-harness-tui

然后检查 npm 的全局前缀：

npm config get prefix

在 macOS 和 Linux 上，该前缀内的 bin 目录必须在 PATH 中。更改 PATH 后请启动新的 shell，或运行 hash -r 以清除旧的命令查找缓存。

deepseek auth 提示环境凭据为只读

运行：

deepseek auth status

如果它报告 env (read-only)，请在启动进程的环境中取消设置 DEEPSEEK_API_KEY。根据设计，已存储的凭据无法覆盖继承的环境变量。

凭据文件权限

在 POSIX 系统上，官方提供程序会拒绝组或其他用户可读的凭据文件：

chmod 700 "${DSH_HOME:-$HOME/.dsh}"
chmod 600 "${DSH_HOME:-$HOME/.dsh}/.credentials.yaml"

检查组合后的配置文件

独立启动器会转发应用程序参数，而官方启动器级别的诊断信息仍可通过捆绑的 dsh 可执行文件使用。用于开发检查：

deepseek --dump-config

捆绑栈应包含 @deepseek-ai/dsh-base 和 @chalk/dsh-tui。

仅重置 TUI 配置文件

将 $DSH_HOME/profiles/tui 移开，然后再次运行 deepseek。启动器将在下一次更改状态的启动时初始化一个干净的配置文件。凭据和会话位于该配置文件目录之外。

安全注意事项

- 切勿将凭据放入此仓库、提示、截图、问题或终端日志中。
- deepseek --help 和 deepseek --version 不会初始化配置文件或打开凭据存储。
- 凭据文件权限可防止其他操作系统用户访问，但无法防止已以你的用户身份运行的进程。
- 会话遥测仍由官方基础配置文件控制，除非明确启用，否则默认处于禁用状态。

上游参考

- DeepSeek Harness
- DeepSeek Harness CLI 参考
- DeepSeek 凭证提供程序

许可证

MIT。请参阅 LICENSE 和 THIRD_PARTY_NOTICES.md。