一句话定位

oh-my-dsh 仓库自带的一份最小可安装 bundle，唯一作用是在 omdsh 命令面板里注册一条 /hello 斜杠命令，用于演示"插件如何接入宿主"的最短路径。

核心能力

• 注册一条 /hello 斜杠命令，调用后输出一行确认通知
• 通过宿主提供的 commands 服务完成命令挂载，不重复打包 Cordis 或 dsh-commands
• 在重启 omdsh 后让命令出现在 /help 列表里，作为插件是否正确加载的探针
• 作为可拷贝的 bundle 起点，配合官方教程扩展为真实功能
• 通过 cordis.patch.yml 在空 Profile 根上插入一行，避免污染既有层

技术实现

• 语言: JavaScript (ESM)
• 关键依赖: @deepseek-ai/cordis ^4.0.1、@deepseek-ai/dsh-commands ^0.1.0-rc.8（均为 peerDependency，由宿主提供）
• 架构模式: Cordis bundle + ctx.effect 副作用注册；通过 cordis.patch.yml 在 Profile 根插入一行；inject = ['commands'] 声明对宿主 commands 服务的依赖
• 入口文件: index.js（导出 name / inject / apply，在 apply 内调用 ctx.commands.register）

适用场景

• 第一次接触 omdsh 插件机制的开发者，把目录拷一份改成自己的命令
• 想验证 omdsh 的插件挂载链路是否通畅，比如发版后跑一次 /hello 确认 bundle 已被识别
• 给团队或文档准备一段"20 行就能写完"的最小可行示例代码

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:agi-fans/oh-my-dsh/examples/hello

配置项

本插件无需额外配置。

常见问题

Q: 这个插件装上后能直接用吗？

A: 装上后必须重启 omdsh，新命令才会被识别。重启后输入 /hello，界面会打印 Hello from @agi-fans/omdsh-plugin-hello.。

Q: /hello 之外还能做什么？

A: 没有了。这个 bundle 只注册了一条命令，README 也明确写明它不贡献 TUI 界面、主题、overlay 或工具。

Q: 装这个示例会不会影响我的其他插件？

A: 不会。cordis.patch.yml 只在空 Profile 根上插入一行名为 omdsh-hello 的层，不动既有插件层，移除时执行 omdsh plugin remove @agi-fans/omdsh-plugin-hello 即可。

Q: 我想基于它写自己的命令，应该改哪里？

A: 改 index.js 里的 ctx.commands.register 调用，新增或重命名命令；同步修改 cordis.patch.yml 里的 id 和 name，避免和示例冲突。

Q: 为什么 dependencies 是空的？

A: 官方插件规约要求 @deepseek-ai/* 必须作为与宿主同版本的 peerDependencies，避免嵌套多份 Cordis 或 dsh-commands。本 bundle 严格遵循该约束。

Q: 报错说找不到 commands 服务怎么办？

A: 大概率是宿主 omdsh 版本低于 0.1.0-rc.8，或者没装 @deepseek-ai/dsh-commands。先升级宿主并重启，再重新 omdsh plugin add。

上手难度

入门 — 整份 bundle 只 23 行代码、一个 patch 文件，是理解 omdsh 插件机制的最小例子。

已知问题与限制

• 不贡献 TUI、主题、overlay、工具注册，仅作为示例与挂载探针
• 命令名 hello 是固定的硬编码字符串，缺少可配置入口
• 任何兼容性问题需通过宿主 omdsh 升级解决，bundle 自身不声明降级路径

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.