命令行

omdsh 二进制默认启动 TUI。子命令处理脚本执行、诊断、插件管理与补全;--dump-config 打印组合树。

用法

omdsh [options] [prompt...]
omdsh plugin add <package>
omdsh plugin remove <package>
omdsh plugin <pnpm-args...>
omdsh completions bash|zsh|fish
omdsh doctor [--json]
omdsh exec --json [--resume <id>] [prompt...]

位置参数形式的提示会启动 omdsh 并把拼接后的内容作为第一条消息提交。默认 TUI 入口的 --resume 不能与提示组合,--dump-config 不能与两者中的任何一个组合。

选项

选项作用
--model <route>本次进程使用的模型路由;写入 OMDSH_MODEL。默认 deepseek-flash。
--provider <route>本次进程使用的 provider 路由;写入 OMDSH_PROVIDER。默认 deepseek-official。
-r, --resume <session-id>重新打开一个持久会话。
--dump-config打印组合后的插件树并退出。
-h, --help显示内置帮助。
--version打印已安装版本。

命令行 flag 优先于所有分层环境来源。

exec 与 TUI 共享凭据库和 DeepSeek 账户 grant,但只有交互式 TUI 会挂载 loopback 账户登录宿主。要在 exec 中使用账户模型,请先在 TUI 里通过 /login 完成一次浏览器登录。

环境变量

变量作用
DEEPSEEK_API_KEY用于实时回合的 DeepSeek API Key。/login 会把校验后的 Key 存到同一个引用;由环境变量提供的值不会被覆盖。deepseek-account 会话改用共享账户 grant。
OMDSH_MODEL、OMDSH_PROVIDER默认路由覆盖;--model 与 --provider 的优先级更高。
OMDSH_HOME会话、设置、凭据、MCP 与 LSP 配置、插件和 Skills 的 home;回退到 DSH_HOME,再到 ~/.dsh。
OMDSH_PERMISSION_MODE初始 Access preset:read-only、workspace-write(默认)或 danger-full-access;之后可按会话用 /permission 修改。
NO_COLOR、FORCE_COLOR=0在没有显式颜色偏好时关闭彩色输出。见故障排查。

/model 会把模型偏好写入 Profile 补丁 profiles/omdsh/cordis.patch.yml;更早版本留下的 settings.yaml 会在启动时导入一次,并重命名为 settings.yaml.imported。

Plugin 与 completions

omdsh plugin add <package> 把 bundle 安装到用户 Profile,omdsh plugin remove <package> 删除一个,其余参数会转发给 Profile 目录中的 pnpm。见用户插件。

omdsh completions bash|zsh|fish 打印 omdsh 命令行的补全脚本,不启动 TUI,也不发起网络请求。在 shell 配置中加载:

eval "$(omdsh completions zsh)"

脚本执行

omdsh exec --json 使用现有 Profile、模型路由、工具和 Access 策略执行一条提示。它使用独立的机器输出消费端,不打开 TUI、不改变终端模式,也不把提示中的斜杠命令或 !command 当作交互命令执行。

omdsh exec --json "Explain this repository" > result.ndjson
cat task.txt | omdsh exec --json - > result.ndjson
omdsh exec --json --resume session-id "Continue the task" > result.ndjson

省略提示时,同样读取 stdin 直到 EOF,并将其作为一条 UTF-8 消息,大小限制为 8 MiB。位置参数不会读取 stdin,除非唯一参数为 -。--model 与 --provider 选择当前模型路由;-- 结束选项解析。Exec 必须带 --json。恢复会话时保留历史和权限,使用当前模型选择,只输出本次新增内容,不重放旧回复。需要格式迁移的会话须先在交互模式中恢复。

Stdout 使用逐行 JSON;诊断及普通插件日志写入 stderr。每条记录包含 schemaVersion: 1、递增的 sequence、type 和 data。消费端应忽略不认识的事件类型。事件包括 run.started、session.created 或 session.resumed、assistant.stream、assistant.message、turn.started/turn.finished、step.started/step.finished、tool.started/tool.finished、tool.ptc_result、委派状态与审批审计。会话记录携带 sessionId 和 root;持久事件另带 eventSequence 和 time。流式帧保留 Harness 的尝试标识和索引。工具负载保留 Harness 调用标识和规范结果;结果消息通过 message.toolCallId 配对。不导出请求头或 Profile 配置。

最后一条记录为 run.finished。它的 data 包含 outcome、exitCode、text,以及可选的 sessionId、sessionTotals;出现问题时,另带含 code 与 message 的 error。text 是本次执行新增的根 Agent 最近一条已提交助手正文;失败或取消时可能保留部分输出。sessionTotals 来自 Harness projection,覆盖整个根会话,恢复后也包含历史回合;它不是所有子会话的总账单。正常完成会等待托管子 Agent、父会话后续回复及持久化 flush,再释放资源并写入最终结果。

退出码含义
0已完成。
1执行、启动、清理或输出失败;达到 token 上限视为未完成。
2参数或输入无效。
3问题或审批需要人工输入。
130被 SIGINT 中断。
143被 SIGTERM 中断。

遇到问题或审批时,会输出 input.required,取消无人值守执行,并按拒绝优先的边界处理。Exec 不编造答案、不授予权限,也不扩大 Access;请在交互模式恢复会话后继续作出人工决定。第二次终止信号会强制退出。清理沿用交互式应用的五秒宽限;超时会报告 SHUTDOWN_TIMEOUT,写入失败结果后强制退出。中断后若输出在宽限内无法写完,会关闭通道,不声称最终记录已送达。命令语法无效时,协议尚未启动,使用说明写入 stderr;管道断开或强制终止可能使最终记录无法送达。写入遵守背压,待写协议输出限制为 32 MiB。

管道模式

当 stdin 或 stdout 不是 TTY——管道输入、CI——omdsh 会退化为按行输入与纯追加式输出。会话、命令与退出行为保持相同语义,只是不再占用交互式屏幕。

相关