一句话定位

omdsh 是基于 DeepSeek Harness 运行时构建的终端编程助手，复用 Harness 的全部插件能力（会话、工具、权限、模型），通过键盘驱动的 TUI 把它组合成可恢复、可扩展的对话式开发环境。

核心能力

• 启动可恢复的终端会话，支持续接、压缩、回退到任一用户轮次、把整段对话导出为 Markdown
• 通过四种会话控件切换行为：Agent 预设（Standard/PTC/Minimal/Cordis）、工作流（Default/Plan）、工具呈现（Native/Code/Both）、访问权限（只读/工作区可写/完全访问）
• 输入框支持 @文件 提及项目内文件或其他会话、粘贴剪贴板图片、复用持久化的提示词历史、用外部编辑器改写多行输入、按顺序取回排队中的追问
• 实时呈现工具调用与子代理进度，可用键盘在 Agent Hub 中选择子代理，从子代理的对话记录里继续指挥它
• 在输入框上方显示 Agent、Workflow、Tools、Access、模型、推理档位、工作区、Git 状态、上下文压力、Token、TTFT、吞吐、缓存、计时、轮次、步骤等运行信息
• 渲染层按行做差异更新，CJK 文本和 emoji 不会破坏对齐，长会话滚动也不会抖动

技术实现

• 语言: TypeScript（ESM，编译产物 lib/*.js）
• 关键依赖: @agi-fans/dsh-tui（本仓 TUI 实现）、@deepseek-ai/dsh-agent 与 dsh-agent-spine-demo（无 Host 的 agent 内核）、@deepseek-ai/dsh-session + dsh-session-persistence-jsonl（会话持久化）、@deepseek-ai/cordis（peer，插件容器）
• 架构模式: 通过 dsh.bundle.patch 把 config/cordis.yml 作为插件补丁注入宿主，由 boot() 把产品包 + 用户 Profile + Home 补丁 + MCP + agent-presets 覆盖层依次挂载；终端原生输入与渲染全部交给本地 TUI Provider，进程退出走带 5 秒强退兜底的关闭控制器
• 入口文件: apps/omdsh/src/bin.ts（CLI 解析） → apps/omdsh/src/boot.ts（挂载树） → apps/omdsh/src/composition.ts（拼装 Profile） → apps/omdsh/src/profile.ts（Profile 发现与产物层） → apps/omdsh/src/plugin.ts（omdsh plugin pnpm 转发）

适用场景

日常需要在终端里让 AI 协助阅读、修改代码、跑命令、写文件的开发者；尤其是希望会话可以续接、工具行为可控、并且能按需增减插件的人。它把 Harness 的全部运行时能力收拢到一个键盘优先的 TUI 里，比 Web UI 更轻、比官方裸 CLI 多了一层交互精修。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:agi-fans/oh-my-dsh/apps/omdsh

配置项

本插件以命令行开关、环境变量与 Harness 配置文件共同控制行为，常用项如下。

常见问题

Q: omdsh 和官方 DSH CLI 有什么区别？

A: omdsh 是基于同一套已发布的 DeepSeek Harness 运行时构建的社区 TUI 编辑，专注于终端交互；能力来源仍是 Harness 服务（会话、工具、权限、模型），omdsh 只负责组合和呈现。

Q: 如何配置 DeepSeek API Key？

A: 启动 omdsh 后运行 /login 命令，根据提示输入并保存 Key；也可以设置环境变量 DEEPSEEK_API_KEY，或写入 $DSH_HOME/settings.yaml。

Q: 会话保存在哪里，如何恢复？

A: 会话文件落在 $OMDSH_HOME/sessions（默认 ~/.dsh/sessions）；启动时加 --resume <id> 即可回到该会话，对话历史可继续追加、压缩或导出。

Q: 插件如何安装与卸载？

A: 使用 omdsh plugin add <package> 与 omdsh plugin remove <package> 即可，这两个命令底层调用 pnpm；其它 pnpm 动词也可经 omdsh plugin <args> 转发到 Profile 目录。

Q: 是否需要 pnpm 才能用插件功能？

A: 需要。omdsh 的 Profile 目录是一个 pnpm 项目，添加/移除插件必须通过 pnpm；如果 PATH 中找不到 pnpm 会直接报错并提示安装。

Q: 是否支持 Windows？

A: 支持。在 Windows 上 omdsh plugin 会通过 shell 调用 pnpm；终端输入、TUI 渲染走 Node + TTY，跨平台表现一致，但必须在真实终端中运行。

Q: 是否可以不接 DeepSeek 模型？

A: 可以。配置文件里同时挂载了 pi-ai 多 provider 通道与官方 DeepSeek 通道；/login 也支持切换到 OpenAI、Anthropic 或自定义 provider。

上手难度

入门 — 终端命令只有 omdsh 一个入口，登录一次即可开始对话；插件需要 pnpm 但首次 omdsh plugin add 会自动初始化 Profile，门槛不高。

已知问题与限制

• 会话全文检索走的是 JSONL，不是 SQLite FTS：Profile 主动把 session-query 设为 path: ':memory:' + openAt: never，目的是避免在 Node 22 上加载实验性的 node:sqlite；若需要搜索只能用 @session 精确匹配会话 ID。
• omdsh plugin 强依赖 PATH 中存在 pnpm，没有 pnpm 时直接退出并返回 127，不会自动安装。
• 通过 git+ / github: / .git 来源安装的插件，其 prepare 脚本在 pnpm 默认安全策略下会被阻止；安装日志会提示把脚本的 key 加到 Profile 的 pnpm-workspace.yaml#allowBuilds 后重跑。
• Node 版本必须 ^22.19 || >=24，旧版 Node 无法运行；engines.node 未在 omdsh 自己的 package.json 里声明，约束来自仓库根 package.json。
• 进程退出有 5 秒宽限期（PROCESS_SHUTDOWN_TIMEOUT_MS），超时会被强制 kill；长会话首次关闭时若 I/O 未排空，可能跳过清理直接退出。
• Profile 包里的产品 bundle 与其它 dsh.bundle.patch 必须保持版本一致，omdsh plugin 会在挂载前比对 @deepseek-ai/* 与 @agi-fans/dsh-tui 的 peer / 嵌套副本，不兼容时会回滚 add 操作。

Quick start

Requirements: Node.js 22.19 or later in the 22.x line, or Node.js 24 or newer, plus a DeepSeek API key for live model turns.

npm install --global @agi-fans/oh-my-dsh
omdsh

Run /login once inside omdsh to validate and save your DeepSeek API key, then start a conversation. To try it without a global installation, run npx @agi-fans/oh-my-dsh.

Highlights

• Durable conversations: resume sessions, rewind to a human turn, retry, compact, and export complete transcripts as Markdown.
• Four real session controls: choose a Harness Agent preset (Standard, PTC, Minimal, or Cordis), Workflow (Default or Plan), tool presentation (Native, Code, or Both), and Access (Read only, Workspace write, or Full access).
• Rich terminal input: mention project files and other sessions with @, paste clipboard images, reuse persistent prompt history, edit multiline prompts externally, and retrieve queued follow-ups.
• Readable tool activity: follow streaming calls and live subagent progress, press Down on an empty composer then Enter (or use Alt+A directly) to select a child in the keyboard-driven Agent Hub, steer a continuable child from its transcript, inspect distinct Input and Output sections, expand long results, and keep domain-specific presentation owned by tool plugins.
• Live operational context: see Agent, Workflow, Tools, Access, model, reasoning effort, workspace, Git state, context pressure, tokens, TTFT, throughput, cache, timings, turns, and steps without leaving the composer.
• Responsive by design: retain settled transcript layout, coalesce scroll updates, emit row-level terminal diffs, and preserve correct display-cell alignment for CJK text and emoji.

Learn

• Tutorials — complete a first task, add precise context, guide queued work, recover long sessions, customize the environment, and write an installable plugin.
• Skills and MCP — extend a project with reusable instructions and external tools.
• User plugins — install DSH bundles into the omdsh Profile with omdsh plugin.
• Architecture — understand the plugin boundaries and runtime data flow.
• Performance — inspect the benchmarks, methodology, and rendering optimizations.

Why oh-my-dsh

DeepSeek Harness provides a capable agent runtime and a strong architectural idea: everything is a plugin. oh-my-dsh brings that runtime into a calm, keyboard-driven terminal experience without creating a second agent core or hiding Harness behind a parallel abstraction.

The TUI remains a presentation and interaction layer. Sessions, tools, permissions, models, Skills, MCP servers, commands, and telemetry come from Harness services and plugins; omdsh composes them into a terminal application and adds the interface behavior needed to use them comfortably.

The project follows four principles:

• Harness-native: use published DeepSeek Harness packages as the source of truth for agent behavior, state, and lifecycle.
• Real plugin boundaries: create plugins for independently owned lifecycles and contribution points, not for every source file.
• One terminal owner: keep raw input, cursor state, viewport management, and atomic rendering inside the local TUI Provider.
• Progressive disclosure: keep the default view concise while making tools, telemetry, settings, and session detail discoverable on demand.

Reference checkouts under refs/ remain read-only research material. Runtime code depends only on published packages and oh-my-dsh workspace packages.

Architecture

DeepSeek Harness plugins and services
                │
                ▼
  @agi-fans/dsh-tui — terminal capability seam
                │
                ▼
  @agi-fans/oh-my-dsh — boot and plugin composition

The TUI package is split into a service definition, local terminal Provider, session and interaction adapters, tool-presentation bridge, command contributions, and interactive Runner. This isolates terminal ownership from Harness domain state and exposes plugin seams only where a capability has an independent lifecycle or owner. See the architecture overview for the current boundaries and data flow.

Performance

Performance is part of the TUI architecture: durable sessions replay in linear time, Harness Projections avoid repeated history scans, settled transcript blocks retain formatted layout, and the terminal writer emits row-level diffs. On the documented Apple M5 Pro environment, restoring 10,000 conversation turns takes a median 2.15 ms, 10,000 tool calls take 21.21 ms, and cached updates over a 5,000-turn surface average 0.24 ms per frame.

See the reproducible TUI performance report or run pnpm benchmark:tui locally.

Configuration

Run /login to configure a provider API key. DeepSeek still opens the official key dashboard, validates the key, and prefers the stored credential over an inherited DEEPSEEK_API_KEY. The same command can also activate a catalog provider such as OpenAI or Anthropic, or add a custom provider with its own id, base URL, protocol, and model ids. /model then lists every live route. /logout removes an omdsh-managed choice and, for DeepSeek, falls back to the environment when available.

Model settings can also come from $DSH_HOME/settings.yaml. Skills and MCP configuration are documented in Skills and MCP.

After an upgrade, omdsh can show release notes once at startup. Use /changelog for recent entries or /changelog full for the complete packaged history. A cached daily npm check reports newer versions without installing anything automatically; both behaviors can be customized in /settings.

Development

pnpm install
pnpm omdsh "list files"  # run from source
pnpm typecheck           # check TypeScript
pnpm test                # unit and pipe-mode tests
pnpm build               # build all workspace packages
pnpm smoke               # interactive PTY smoke test
pnpm smoke:happy         # mock-LLM happy path

The checkouts in refs/deepseek-harness, refs/oh-my-pi, and refs/pi are read-only references. Do not use them as runtime dependencies or modify them while developing omdsh.

Changelog

User-visible changes and release history are tracked in CHANGELOG.md.

Acknowledgements

oh-my-dsh exists because of these projects:

• DeepSeek Harness provides the runtime foundation, plugin architecture, and the conviction that agent capabilities should be composable rather than embedded in one application.
• Pi is the original open agent harness whose terminal interaction, differential rendering, and compact coding-agent craft still set the standard this community builds on.
• oh-my-pi continues that lineage and shows how thoughtful terminal interaction, compact information design, and careful keyboard workflows can make an agent feel fast and approachable.

Thank you to these projects and their contributors. omdsh is an independent community project: it is built on DeepSeek Harness and learns from Pi and OMP, but is not an official distribution of any of them.

License

oh-my-dsh is available under the MIT License.