DSH OMC TUI

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

插件专注于终端渲染与键盘交互；模型、会话、工具、权限、后台任务及持久化均由 Harness 官方服务提供。

项目参考了 Claude Code 的交互习惯与终端美学，采用独立备用屏幕与自研视口差分渲染架构，在彻底避免历史刷屏与乱码的同时，依然保留了顺滑的滚轮回看、鼠标智能分词划选与纯净文本复制等原生级体验。

📌 当前版本：v0.2.15 面向 DSH v0.1.5-rc.1；已完成源码契约核对、隔离 Profile 启动、/status、权限切换、单元测试和模块导入验证。欢迎使用、点 Star 和反馈问题。

当前 Harness 适配：DSH v0.1.5-rc.1

v0.1.5-rc.1 将会话持久化升级为 V3/SessionHandle，移除插件环境中的 ctx.agent，并将系统 persona 配置拆分为 personaPrefix 与 personaSuffix。TUI 继续只通过 ctx.agents.create/resume、dispose()、snapshotEvents() 与 sessionQuery 使用官方生命周期；Profile patch 已迁移至 personaPrefix。

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

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

插件功能

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

• 备用屏幕与差分渲染：采用终端备用屏幕（Alternate Screen，类似 Vim/tmux）与自研 Viewport 差分渲染引擎。会话在独立全屏视口中运行，退出时一键恢复原 Shell 画面，不向终端 Scrollback 遗留大段历史或混乱空行。
• 顺滑滚轮回看与智能划选：内置 SGR 鼠标协议驱动的视口滚动；支持单击拖拽选区、双击中英文分词选择、三击选整行，复制时自动剥离 ANSI 样式纯净复制到系统剪贴板，亦可配合终端修饰键（macOS Option / Linux Shift）强制使用终端原生划选。
• 工业级防乱码与终端健壮性：完整消费 ECMA-48 CSI / OSC / DCS / SGR 回执，杜绝窗口缩放、焦点切换、外部编辑器返回或休眠唤醒时的控制序列乱码；后台挂起恢复后自动检测并修复 Raw Mode、输入流与鼠标追踪。
• 语义阅读锚点与渐进防误触：终端 Resize 窗口缩放时按内容语义锚点锁定阅读位置；生成期间按 Esc 先平滑滚动回底部、再次按下才触发任务中断。

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

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

• 原生视觉直通：连接多模态主模型（如 DeepSeek-V41-Flash、GPT-4o、Claude 3.5）时，图片作为原生 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，无需额外更换或配置新的 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）时，所有任务项与完成进度通过 Event Sourcing 100% 稳定重建。
• 后台长任务 (Jobs)：支持 Ctrl+B 将运行中的 Bash 放入后台，/jobs 实时读取输出流并支持快速刷新、取消或退出确认拦截。

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

• 行级红绿 Diff 审批：文件修改与敏感命令执行前弹出结构化行内审批卡片，清晰呈现行级差异，支持单键允许/拒绝与会话级权限提权（Shift+Tab）；单选、多选与自由文本问答直接在终端内完成。
• 事前 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 20 或更高版本
• DeepSeek Harness @deepseek-ai/dsh@0.1.5-rc.1（预发布版本，需显式指定）
• 支持 ANSI 256 色的终端
• 图片显示建议使用 iTerm2 或支持 Kitty Graphics 的终端

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

安装和启动

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

npx --yes @deepseek-ai/dsh@0.1.5-rc.1 plugin --profile tui add dsh-omc-tui

也可以从 GitHub 安装（会拉取源码，首次需按 pnpm 提示授权 prepare 构建脚本）：

npx --yes @deepseek-ai/dsh@0.1.5-rc.1 plugin --profile tui add github:ipromise2021/dsh-omc-tui

启动：

npx --yes @deepseek-ai/dsh@0.1.5-rc.1 --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.1.5-rc.1 plugin --profile tui add /absolute/path/to/dsh-omc-tui
npx --yes @deepseek-ai/dsh@0.1.5-rc.1 --profile tui

常用快捷键

常用命令

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

/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 控制器与终端事件循环

更完整的架构说明见 PRODUCT_SHOWCASE.md，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. 内置防护覆盖矩阵

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 上游接口变化后可能需要同步适配。
• Windows 和更多真实模型提供方仍需要进一步验证。
• /plugins、/fork、/rewind 等能力暂未在 TUI 中实现。
• 本插件只提供 TUI；模型、工具、Sandbox 和会话持久化由 DSH profile 提供。

反馈与贡献

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

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

提交代码前请运行：

npm test
npm run verify

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

License

MIT