DSH OMC TUI

DeepSeek Harness 的终端原生 TUI

当前版本：v0.2.17，适配 DeepSeek Harness v0.2.0-rc.2。 上一版本 v0.2.16 面向 DSH v0.1.7-rc.2，请勿混用。

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

兼容性契约 · 变更日志

DSH OMC TUI 主界面

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

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

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

📌 版本说明：本版本面向 DSH v0.2.0-rc.2，请使用同一版本线的 DSH 启动。跨数小时待机后，已有一次实际使用验证未出现键盘或鼠标乱码；其他终端环境仍欢迎反馈。

快速开始

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

npx --yes @deepseek-ai/[email protected] plugin --profile tui add [email protected]
npx --yes @deepseek-ai/[email protected] --profile tui

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

设计边界

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

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

当前适配：DSH `v0.2.0-rc.2`

本次从 v0.1.7-rc.2 累计检查至 v0.2.0-rc.2：前者引入动态工具与审批接续等行为；v0.2.0-rc.1 改进图片重传和工具调度异常恢复；v0.2.0-rc.2 调整模型目录，并提供可选的限时提问。preset registry、PTC runtime 和 Session V4 事件契约仍可沿用。TUI 继续通过 ctx.agents.create/resume、dispose()、snapshotEvents() 与 sessionQuery 使用官方生命周期；限时提问当前未启用，仍使用默认的 legacy 模式。

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

范围	结果	验收
Session 与权限	工具失败读取兼容 V3/V4 event payload，权限继续走官方 Session API	单元回归与真实 profile 启动通过
Profile 与 preset	沿用 preset registry，支持 standard、ptc、minimal、cordis 四种 scoped preset	`0.2.0-rc.2 --dump-config`、四种 preset 注册与切换通过
依赖	DSH peer dependency 对齐 `^0.2.0-rc.2`	隔离 Profile 安装与启动通过
既有能力	Agent、Jobs、附件、命令与模型能力调用签名保持兼容；`/model` 并行刷新 Provider 目录	隔离 mock 的完整 PTY 套件通过，包含模型变体选择；用户已实测真实 Provider 与 Chrome MCP 同时启用时，模型切换可以保存

适配期间不会为了同步上游而复制其 UI 功能，也不会提前移除本地安全保护；只处理 Harness API 与 durable event 契约产生的实际兼容问题。

插件功能

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：@deepseek-ai/[email protected]（预发布版本，需显式指定）
支持 ANSI 256 色的终端
图片显示建议使用 iTerm2 或支持 Kitty Graphics 的终端

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

安装和启动

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

npx --yes @deepseek-ai/[email protected] plugin --profile tui add [email protected]
npx --yes @deepseek-ai/[email protected] --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/[email protected] plugin --profile tui add /absolute/path/to/dsh-omc-tui
npx --yes @deepseek-ai/[email protected] --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`	列出当前工作目录下的历史会话标题与日期，选择后恢复内容
`/rename <标题>`	重命名当前会话
`/mcp` / `/hooks`	查看已挂载的 MCP 与 Hook 状态
`/export`	在导出面板中选择目录并确认导出 Markdown
`/exit`	安全退出终端（有活跃后台任务时弹出确认）

其他命令和快捷键可以在 TUI 中通过 ?、/help 或 Ctrl+P 查看。

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

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

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` 正常放行） `:(){ :
Windows (`pwsh`, `powershell`, `cmd`)	`Remove-Item -Recurse -Force C:\`、`del /f /s /q C:\*`、`rd /s /q C:\` `Clear-Disk`、`Initialize-Disk`、`Format-Volume` `format 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] 安全边界提示：

Danger Guard 定位于 Agent 工具执行前的启发式防误操作防线，专注于拦截模型误触发的破坏性指令；

静态分析无法穷尽所有动态构造（如运行时管道下载脚本 curl | sh、图灵完备混淆）；

必须叠加使用 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

dsh-omc-tui

Cài đặt

Mã nguồn

Thẻ

Tác giả

Readme

DSH OMC TUI

快速开始

设计边界

当前适配：DSH `v0.2.0-rc.2`

插件功能

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

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

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

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

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

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

环境要求

安装和启动

💡 快捷启动别名（推荐）

本地开发安装

常用快捷键

常用命令

Reasoning effort

主题和终端显示

项目结构

开发与验证

安全看门狗 (Danger Guard) 与安全边界

1. 内置防护覆盖矩阵

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

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

当前限制

反馈与贡献

License

Cài đặt

Mã nguồn

Thẻ

Tác giả

Readme

DSH OMC TUI

快速开始

设计边界

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

插件功能

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

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

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

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

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

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

环境要求

安装和启动

💡 快捷启动别名（推荐）

本地开发安装

常用快捷键

常用命令

Reasoning effort

主题和终端显示

项目结构

开发与验证

安全看门狗 (Danger Guard) 与安全边界

1. 内置防护覆盖矩阵

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

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

当前限制

反馈与贡献

License

当前适配：DSH `v0.2.0-rc.2`

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