终端交互界面 ipromise2021/dsh-omc-tui

DSH OMC TUI

DeepSeek Harness 的终端原生 TUI

TUI v0.2.18 适配 DeepSeek Harness v0.2.1-rc.2～rc.5，推荐使用已验证的 rc.5；暂不支持 v0.2.2-alpha.2。
TUI v0.2.17 配套 DSH v0.2.0-rc.2，请按版本匹配安装。

独立视口差分渲染，提供图片输入、划选回看、任务与 Plan 面板、行内审批和 Danger Guard 看门狗。

兼容性契约 · 变更日志

DSH OMC TUI 主界面

dsh-omc-tui 是面向 DeepSeek Harness 的 ANSI 终端界面插件。

智能体运行时、模型选择、会话、权限、Jobs 服务与持久化由 Harness 提供；插件负责终端交互与渲染，并提供视觉旁路工具和本地 ! Shell 入口。

项目参考了 Claude Code 的交互习惯与终端美学，采用备用屏幕与视口差分渲染，支持滚轮回看、鼠标划选和复制。退出备用屏幕后，会把当前已载入的会话内容写回终端历史，方便继续查看。

📌 版本说明：下方安装命令固定使用已验证的 DSH v0.2.1-rc.5 与 TUI v0.2.18 组合；从源码运行可参考本地开发安装。

快速开始

需要 Node.js 22.19+（22.x）或 24.2+，以及支持 ANSI 256 色的终端。用 tui 配置档安装并启动：

npx --yes @deepseek-ai/dsh@0.2.1-rc.5 plugin --profile tui add dsh-omc-tui@0.2.18
npx --yes @deepseek-ai/dsh@0.2.1-rc.5 --profile tui

首次启动后，按 DSH 的提示配置模型服务商和 API Key。其他安装方式见安装和启动。

设计边界

| 职责 | 实现位置 |
| 智能体、模型、权限、会话、Jobs 服务与持久化 | DSH 配置档和 Harness 官方服务 |
| 键盘/鼠标输入、面板、ANSI 渲染与会话投影 | 本插件的 src/input/、src/panels/、src/renderer/ 和 src/index.js |
| 用户输入的 ! Shell 命令 | 插件启动本地进程，后台化时优先注册到 Harness Jobs 服务 |
| 会话恢复 | 从 Harness 的 durable session events 重建 TUI 视图 |

插件通过 Harness API 创建和恢复智能体、提交业务操作；会话与权限不在插件内另建真相源。! Shell 进程属于当前 TUI，若 Jobs 服务无法注册，后台任务会暂存在当前进程内，退出后不能从该本地列表恢复。standard、ptc、minimal、cordis 四种智能体 preset 由 DSH preset registry 组合；/preset 可查看和切换，已有对话时会先确认新建会话。

当前适配：DSH v0.2.1-rc.2

本次对照官方 v0.2.0-rc.2 与 v0.2.1-rc.2 发布源码，适配会话工作目录、托管子代理、Preset 与凭据服务变化。TUI 继续通过 ctx.agents.create/resume、dispose()、snapshotEvents() 与 sessionQuery 使用官方生命周期；限时提问当前未启用，仍使用默认的 legacy 模式。

DeepSeek-V41-Flash（模型 ID deepseek-flash）现为上游默认模型，支持文本、图片以及会话内系统提示词更新。TUI 的初始化兜底模型和 /vision 常用模型候选均已纳入该模型。

| 范围 | 适配 |
| 当前目录 | 文件引用、目录补全、本地 Shell、技能、旁路智能体与状态显示通过 workingDirectory.get(session) 读取当前目录；历史会话仍按原始项目归组 |
| 配置档与 preset | 清除废弃 backgroundMode 和 tool-ralph 补丁；Standard/PTC/Cordis 使用官方时间上下文，Minimal 增加图片读取和自动压缩 |
| 凭据 | /provider 通过官方凭据服务判断已配置状态；保存和删除 Key 仅调用官方服务，保留继承的环境变量作为回退 |
| 依赖 | DSH peer dependency 对齐 ^0.2.1-rc.2，Cordis 对齐 ^4.0.5，Schemastery 对齐 ~3.18.5 |
| 既有能力 | 智能体、附件、命令、权限和问答调用签名保持兼容；Jobs 的 UUID ID 与新增生命周期事件由官方服务管理 |

适配期间不会为了同步上游而复制其 UI 功能，也不会提前移除本地安全保护；只处理 Harness API 与 durable event 契约产生的实际兼容问题。
本轮通过模块检查、单元回归、官方运行时提示词回归、隔离 mock Profile 的完整 7 项 PTY（含四种 Preset 挂载），以及实际 npm 包安装与启动验证。Chrome MCP 已改为固定项目依赖，启动不再经过 npx；已验证真实握手、工具发现，以及正常加载和失败重试期间输入框与中文草稿保持完整。连接失败由 TUI 显示一次提示。真实 Provider 联合场景和 Windows 未实测。

插件功能

1. 独立视口与原生级终端体验

- 备用屏幕与差分渲染：采用终端备用屏幕（Alternate Screen，类似 Vim/tmux）与 Viewport 差分渲染。会话在全屏视口中运行，退出时恢复原 Shell 画面，并将已载入的会话内容写回终端历史。
- 顺滑滚轮回看与智能划选：内置 SGR 鼠标协议驱动的视口滚动；支持单击拖拽选区、双击中英文分词选择、三击选整行，复制时自动剥离 ANSI 样式纯净复制到系统剪贴板，亦可配合终端修饰键（macOS Option / Linux Shift）强制使用终端原生划选。
- 输入恢复与终端健壮性：输入路由识别 CSI / OSC / DCS 等控制序列和鼠标报告；对分片方向键、残缺粘贴、图片传输超时与待机后的终端模式丢失设有恢复路径。跨数小时待机的实际使用中，键盘和鼠标未出现乱码。
- 语义阅读锚点与渐进防误触：终端 Resize 窗口缩放时按内容语义锚点锁定阅读位置；生成期间按 Esc 先平滑滚动回底部、再次按下才触发任务中断。

2. 双模态视觉体系（原生直传 + 自主决策 Sidecar）

支持在终端直接按 Cmd/Ctrl+V 粘贴 macOS / 桌面剪贴板图片，或通过 iTerm2 OSC 1337、Kitty Graphics 协议直接发送图片；内置高分屏自适应缩放引擎（2048px 安全基准线），并通过 Harness Attachment 管道自动管理与落盘。

- 原生视觉直通：主模型支持图片输入时，通过 Harness 附件管道把图片作为 image content block 交给模型。
- 自主旁路 Sidecar：连接纯文本/代码模型时，主 Agent（无需人工切换主模型、无需手动调用插件）结合任务意图自主判断何时需要看图并自动触发底层的 analyze_image 视觉工具；TUI 在后台动态拉起隔离的临时视觉 Subagent，定向提取 OCR 与 UI 布局细节后立即销毁并回传主会话。
- 待发图片快捷管理：图片以 [Image #n] 出现在输入框前缀；若需撤回，将光标移到文本开头后按 Backspace，可按后进先出顺序逐张移除，文本草稿不会丢失。

💡 视觉子代理模型与 API Key 配置提示：
- 使用 DeepSeek API：可配置 DeepSeek-V41-Flash（执行 /vision deepseek-official/deepseek-flash）；也可继续使用 deepseek-v4-flash-vision-exp。子代理与主模型使用同一提供方时，共用已配置的 DeepSeek API Key。
- 使用其他供应商视觉模型：若子代理希望调用其他提供商（如 OpenAI gpt-5.6-luna、Qwen 等），只需在 DSH 中配置好对应供应商的 API Key，再执行 /vision <provider>/<model>（或直接输入 /vision 查看常用路由推荐）绑定子代理视觉模型即可。

3. 沉浸式树遍历排版与代码高亮

- Thinking 折叠与 Ctrl+O 展开：流式阶段显示动画与耗时；思考完毕自动收折为一行徽标；按 Ctrl+O 可原位展开思维链与工具组。
- Markdown 与层级 Diff：代码块显示语言标签和缩进内容；展开工具调用后，Diff 保持在所属工具下方并按列宽截断。
- 四款护眼主题：内置 claude（暖色调）、deepseek（蓝色调）、mono（黑白）与 light（浅色，未选主题时自动感知终端背景）。

4. 实时任务中心与 Plan 联动 (Tasks & Plan)

- Durable 实时状态感知：全面接入 Harness 的 todo/write 持久化快照，任务创建、进行中与已完成状态实时流式驱动 /tasks 任务中心面板与底部状态栏。
- 会话恢复：历史会话恢复（-c / /resume）时，任务项与完成进度从 Harness 持久化事件重新投影；先显示最近内容，向上滚动到顶部时再载入更早的历史。
- 后台长任务 (Jobs)：运行中的 ! Shell 命令可用 Ctrl+B 放入后台，前台运行超过 60 秒也会自动转入后台继续执行；/jobs 可读取输出、刷新和取消任务。

5. 行内安全审批与原生看门狗 (Danger Guard)

- 行级红绿 Diff 审批：文件修改与敏感命令执行前弹出结构化行内审批卡片，清晰呈现行级差异，支持单键允许/拒绝与会话级权限提权（Shift+Tab）；单选、多选与自由文本问答直接在终端内完成。Shift+Tab 按 read-only → workspace-write → danger-full-access → read-only 的固定顺序轮转，从最危险的 danger-full-access 回绕到最安全的 read-only，档位写入 Harness 官方会话事件（permission/preset、sandbox/mode、approval/policy）。
- 事前 AST 危险守卫：内置 Danger Guard 原生 Watchdog，在工具执行前拦截 rm -rf /、Fork 炸弹、磁盘直写等危险指令，覆盖 Unix/macOS/Windows 多平台，支持 .dsh/danger-rules.json 自定义全段锚定规则。

6. 全景状态栏 (HUD) 与效率工作流

- 4 行全景自适应状态栏：实时呈现当前模型、Plan/Build 模式、权限档位、会话 Context 进度条与水位预警、Git 分支/变更/ahead/behind、活跃扩展（Skills/MCP/Hooks）与最近响应速度。支持 detailed、compact 和 minimal 三种密度。
- 无污染旁路提问 (/btw)：后台创建独立临时会话回答旁路问题，完全不污染主会话上下文与 Token 预算。
- 自动与平滑压缩 (/compact)：上下文达到阈值（Harness compaction-basic.thresholdRatio，默认 80%）时，在回合内自动触发平滑压缩；也可通过 /compact 手动触发。
- 会话回顾与空闲总结 (/recap)：随时生成会话历史摘要；空闲 15 分钟时自动生成呼吸总结。恢复长会话后，较早的转写会随向上滚动按需载入。
- 工作区逐级下钻 (@文件)：输入 @ 浏览工作区目录树，支持交互过滤、子目录钻取与文件内容高亮注入。
- 安全导出 (/export)：在专用面板中校验并导出 Markdown 会话记录，默认安全隔离于专用配置目录。

环境要求

- Node.js 22.19+（22.x）或 24.2+
- DeepSeek Harness 0.2.1-rc.2～rc.5，推荐 @deepseek-ai/dsh@0.2.1-rc.5（预发布版本，需显式指定）
- 支持 ANSI 256 色的终端
- 图片显示建议使用 iTerm2 或支持 Kitty Graphics 的终端

目前主要在 macOS、VS Code Terminal 和 iTerm2 中开发与验证。

安装和启动

从 npm 安装 dsh-omc-tui 到 tui profile（直接分发构建产物，无需 Git 依赖构建授权）：

npx --yes @deepseek-ai/dsh@0.2.1-rc.5 plugin --profile tui add dsh-omc-tui@0.2.18
npx --yes @deepseek-ai/dsh@0.2.1-rc.5 --profile tui

要从源码试用，请先检出本仓库，再按本地开发安装中的命令安装。

如果已经全局安装 DSH，也可以直接运行：

dsh --profile tui

💡 快捷启动别名（推荐）

日常使用与开发中，我更习惯在终端配置文件（如 ~/.zshrc 或 ~/.bashrc）中添加别名，直接输入 dsh-omc-tui 或 omc 快速启动（主要就是想少敲点键盘）：

添加到 ~/.zshrc 或 ~/.bashrc alias dsh-omc-tui="dsh --profile tui" alias omc="dsh --profile tui"

配置后，在任意工作目录下直接执行：

dsh-omc-tui
或 omc

本地开发安装

建议使用单独的 DSH_HOME，避免影响日常配置：

export DSH_HOME=/private/tmp/dsh-tui-dev
npx --yes @deepseek-ai/dsh@0.2.1-rc.5 plugin --profile tui add /absolute/path/to/dsh-omc-tui
npx --yes @deepseek-ai/dsh@0.2.1-rc.5 --profile tui

常用快捷键

| 按键 | 功能 |
| Enter | 发送消息或确认当前选项 |
| Ctrl+J | 输入多行内容 |
| Ctrl+C | 中断当前回合；空闲时退出 |
| Ctrl+O | 展开或折叠 Thinking 与工具组 |
| Ctrl+P | 打开命令面板 |
| Ctrl+R / Ctrl+F | 搜索输入历史 |
| Ctrl+G | 使用 $EDITOR 编辑 Prompt |
| Shift+Tab | 切换权限预设 |
| Ctrl+B | 将正在执行的 Bash 放入后台 |
| Ctrl+V | 粘贴文本或终端图片 |
| @ | 打开文件引用补全 |
| ? | 打开帮助面板 |

常用命令

| 命令 | 功能 |
| /model | 选择模型，并根据模型能力选择 reasoning effort |
| /preset | 查看并切换 standard、ptc、minimal、cordis；已有对话时确认后新建会话 |
| /vision <provider>/<model> | 配置 analyze_image 使用的旁路视觉模型 |
| /provider | 管理模型提供方、自定义端点和模型列表 |
| /plan [off\|message] | 进入或退出 Harness Plan 模式，可携带规划说明和图片 |
| /status | 查看会话、模型、Token 和扩展状态 |
| /settings | 设置主题、状态栏密度和 Context 预警 |
| /new | 使用当前模型、权限和预设创建新会话 |
| /btw <问题> | 在独立临时会话中提问，不加入主会话历史 |
| /compact | 压缩当前会话上下文 |
| /tasks | 打开任务中心；默认查看 Agent Plan，可切换后台任务 |
| /jobs | 兼容入口；直接打开后台任务页，读取输出、刷新或取消任务 |
| /skills | 浏览并在 TUI Profile 中切换 Skill 的 on/off 状态 |
| /resume | 列出当前工作目录下的历史会话标题与日期，选择后恢复内容 |
| /queue | 查看待处理消息，选择插入当前回合、继续等待、取消或取回本次终端提交的草稿 |
| /steer [消息] | 在下一个处理节点插入补充消息；无参数时将最后一条等待消息移入当前回合 |
| /rename <标题> | 重命名当前会话 |
| /mcp / /hooks | 查看已挂载的 MCP 与 Hook 状态 |
| /export | 在导出面板中选择目录并确认导出 Markdown |
| /exit | 安全退出终端（有活跃后台任务时弹出确认） |

其他命令和快捷键可以在 TUI 中通过 ?、/help 或 Ctrl+P 查看。
回答进行中按 Enter 发送新问题时，默认等待当前回合结束，输入框上方显示待处理消息。/queue 面板用 ↑↓ 选择，Enter 插入，w 或 Esc 关闭并保留等待状态，x 取消；本次终端提交的消息还可按 e 取回原文及图片继续编辑。插入通过 Harness 的 steer() 在下一个处理节点生效，不会立即终止正在输出的内容；消息会移出原等待队列，避免下一轮重复执行。队列内容来自 Harness 官方 Inbox，开始处理后从列表消失。此交互包含在 v0.2.18 中。

/resume 列表不按时间截断，也不限制为最近 50 条；显示当前目录中已持久化、有标题的非活跃主会话，没有标题的新会话和子会话不显示。列表先读取标题缓存，只为未缓存项批量查询标题；选择后才恢复完整会话数据。长历史首屏只排版最近 200 条事件，滚到顶部时按需载入更早内容。进程内列表缓存保留 5 分钟，每次打开都会核对官方活跃会话状态；当前 TUI 切换会话后及时更新，其他进程新增或删除的记录可能在缓存到期后才显示。恢复 preset 使用最后一次持久化选择，兼容其他客户端对空会话的预设修改。

/export 打开导出面板，默认填入 $DSH_HOME/exports/<项目名>/；未设置 DSH_HOME 时即为 ~/.dsh/exports/<项目名>/。首次按 Enter 校验时会创建该默认目录，避免会话导出文件混入 Git 工作区。可直接在面板的 Directory 输入框中编辑相对或绝对目录；自定义目录不会自动创建，按 Enter 会校验目录存在、类型与可写性，再确认导出；校验失败会在面板内显示原因且不会写入。导出目录和 Markdown 文件分别以仅当前用户可访问的权限创建。导出包含用户消息、助手回复与工具调用参数，分享前请自行检查敏感信息；文件名带会话尾号和 UTC 时间戳，不会覆盖此前导出结果。

权限审批

workspace-write 允许修改会话工作目录内的文件；目录外的修改等操作仍可能申请 danger-full-access。审批应以实际申请的权限为准：第一项仅允许本次操作，后续新操作可能再次询问；第二项将申请的档位通过 Harness 官方 API 保存到发起请求的会话。danger-full-access 会关闭该会话的沙箱限制和审批询问，请根据所需范围选择。

v0.2.18 已修正审批面板将 danger-full-access 错标为 workspace-write、第二项写入错误档位的问题，并对已排队的沙箱提权请求重新核对官方会话权限。独立的工具或浏览器审批不会因 workspace-write 而自动放行。

Reasoning effort

/effort 严格显示当前模型通过 Harness 声明的档位，不会猜测模型能力。官方适配器或内置模型目录通常会提供这类元数据；第三方中转、兼容接口和本地反向代理的模型列表往往只返回模型 ID，无法自动提供思考等级。此时状态栏显示 effort PROVIDER，表示请求未指定档位并继续使用模型或网关默认行为，不代表模型调用失败。

通过 /effort 或模型选择器确认档位后，TUI 会调用 Harness 的 agentDefaultModel.saveSelection() 保存完整的 { provider, model, reasoningEffort } 默认选择。该档位立即用于当前 TUI，之后创建的新会话也会恢复并显示相同等级；例如选择 high 后，新会话状态栏仍显示 effort HIGH。直接执行 /effort <id> 时也会先校验当前模型声明的档位，不支持的值不会写入设置。切换到未声明 reasoning effort 的模型时会清除旧覆盖值，并回到 PROVIDER。

需要在 TUI 中选择档位时，可在 settings.yaml 的具体模型上声明 reasoningEfforts。下面是本地反向代理 local-cpa 提供 gemini-3.7-flash、且该模型支持 low、medium、high 三档时的配置示例：

llm-pi-ai:
providers:
local-cpa:
apiKeyEnv: LOCAL_CPA_API_KEY
api: anthropic-messages
baseURL: http://127.0.0.1:8317
models:
- id: gemini-3.7-flash
name: gemini-3.7-flash
reasoningEfforts:
low: low
medium: medium
high: high

映射左侧是 TUI 使用的 Harness effort ID，右侧是发送给网关的实际值。若中转服务使用不同拼写，可以映射为它要求的值；例如 high: deep 会在 TUI 中显示 HIGH，并向中转发送 deep。只声明模型和网关真实支持的档位，未声明的值不会出现在选择器中，也不会由插件强制发送。修改模型能力配置后需要重启 DSH；随后通过 /effort 选择一次，所选档位会由 Harness 设置服务持久化，不需要编辑插件内部文件。

主题和终端显示

内置以下主题：

- claude：暖色调
- deepseek：蓝色调
- mono：黑白模式
- light：浅色模式

终端宽度、ANSI 控制序列、中文、emoji 和组合字符由本地渲染器处理，不依赖 Ink、Blessed、Chalk 或其他重型终端 UI 库。

项目结构

src/
├── commands/ 内置命令 ├── core/ 事件、Git 和基础工具 ├── input/ 输入编辑与补全 ├── panels/ 审批、模型、Jobs、Skills 等面板 ├── renderer/ ANSI、Markdown、Transcript 和 Statusline └── index.js TUI 控制器与终端事件循环

Harness 接口适配情况见 HARNESS_COMPATIBILITY.md。

开发与验证

npm test
npm run verify

如果准备了不含凭据的 Harness 测试夹具，还可以运行 PTY 集成测试：

DSH_TEST_FIXTURE_HOME=/path/to/dsh-home npm run test:pty

安全看门狗（Danger Guard）与安全边界

dsh-omc-tui 内置安全看门狗（Dangerous-Command Watchdog），在 Harness 的 tools/pre-execute 执行前切入点做结构化语法审查与单调阻断（Deny-or-Abstain），降低模型或子代理误执行高破坏性命令的风险。

1. 内置防护覆盖矩阵

| 平台 / 工具 | 结构化拦截的危险操作模式 |
| Unix / Linux / macOS (bash, sh, zsh 等) | rm -rf /、rm -rf ~（含多层相对路径越界 a/../../b、通配符与变量展开）chmod -R 777 /、find / -delete、find / -exec rm ...mkfs.、fdisk、dd of=/dev/sd 直写磁盘设备git push --force（保护 remote 分支，安全选项 --force-with-lease 正常放行）:(){ :|:& };: 等 Fork 炸弹 |
| Windows (pwsh, powershell, cmd) | Remove-Item -Recurse -Force C:\、del /f /s /q C:\*、rd /s /q C:\Clear-Disk、Initialize-Disk、Format-Volumeformat C: 磁盘格式化驱动器powershell -EncodedCommand 混淆载荷还原审查 |
| Shell 封装与深层混淆 | sudo、env、exec、timeout、sh -c、bash -lc、cmd /c 组合解构ANSI-C $'\x72\x6d' / $'\u0072\u006d' / $'\162\155' 转义还原深层嵌套子 Shell（depth > 32）与超长输入（> 128KB）采用 Fail-Closed 默认阻断 |

2. 自定义规则配置 (.dsh/danger-rules.json)

可在当前项目根目录或配置路径放置 .dsh/danger-rules.json 扩展自定义规则：

{
"enabled": true,
"block": [
"DROP\\s+DATABASE",
"kubectl\\s+delete\\s+namespace"
],
"allow": [
"^git status$",
"^npm test$"
]
}

- block：扩展自定义高危正则表达式（命中即拦截）。
- allow：强制基于全段锚定（^(?:pattern)$）放行安全白名单，杜绝子串或子 Shell 注入逃逸。
- 完全停用：设置环境变量 DSH_DANGER_GUARD=off 即可停用看门狗。

3. 威胁模型与安全边界说明

[!IMPORTANT]
安全边界提示：
1. Danger Guard 定位于 Agent 工具执行前的启发式防误操作防线，专注于拦截模型误触发的破坏性指令；
2. 静态分析无法穷尽所有动态构造（如运行时管道下载脚本 curl | sh、图灵完备混淆）；
3. 必须叠加使用 Harness 权限预设（Permission Presets）、沙箱隔离（Docker / Container / MicroVM）与生产凭据管控，切勿将纯静态守卫视为唯一的安全沙箱。

当前限制

- 项目仍处于 pre-release 阶段，Harness 上游接口变化后可能需要同步适配。
- 长待机输入已有跨数小时实际使用验证；跨终端环境和真实 Provider/图片端到端测试仍需继续覆盖。
- Windows 和更多真实模型提供方仍需要进一步验证。
- /plugins、/fork、/rewind 等能力暂未在 TUI 中实现。
- 本插件不提供独立 Agent Runtime 或模型服务；Sandbox 和会话持久化由 DSH profile 提供。

反馈与贡献

个人开发的开源项目，以实际终端使用体验为基础，按需开发、持续完善。欢迎使用、点 Star，也欢迎反馈 Bug 和提出功能建议。

如果遇到问题，可以提交 Issue。建议附上 DSH 版本、Node.js 版本、操作系统、终端类型和复现步骤。也欢迎直接提交 PR。

提交代码前请运行：

npm test
npm run verify

提交信息建议使用 Conventional Commits，例如 feat:、fix:、docs:。

License

MIT