命令行

以下新行为以 0.1.5-alpha.1（5dda764ed3）源码为准；npm latest / next 为 0.1.2-rc.1，alpha 通道为 0.1.5-alpha.1，见版本与通道。

dsh 是唯一入口命令,几乎所有操作都从一个 dsh 起。

官方零安装入口是 npx @deepseek-ai/dsh ...，要求 Node.js ^22.19.0 或 >=24.0.0。在官方源码仓库中则使用 pnpm dsh ...。下文统一写成 dsh ...。

一、基础用法

dsh --profile web                      # 启动 Web profile(等价 dsh web)
dsh web                                # Web UI(别名 --profile web)
dsh --profile headless "跑一下测试"      # 一次性任务,执行完退出
dsh plugin ...                         # 管理 profile 插件依赖

dsh run 子命令已移除;一次性任务改走 --profile headless <task>。

二、launcher flags(启动器层)

这些在传给 app 之前就被 dsh 消费:

--profile <name>           选定 $DSH_HOME/profiles/<name>(首次自动初始化)
--from-default-profile <name>  用随附模板初始化一个新的自定义 profile,然后启动它
--patch <path>            额外叠一个 overlay patch(可重复,优先级高于 profile 层)
--dump-config             打印组合树并退出
--dump-default-config     只打印 bundle 层(无用户层/--patch)

dsh --profile web --dump-config       # 看 web profile 的完整组合
dsh --profile tui --patch ./extra.yml # 自带 patch 启动
dsh --profile rescue --from-default-profile web  # 用 web 模板创建 rescue 并启动

两个关键机制:

启动器只吃自己的 flag,其余原样交给应用。第一个启动器不认识的 token 之后全是"内层参数",原样进配置树:如 dsh --profile tui --resume abc 的内层参数是 ['--resume', 'abc'](其中 --resume 是 TUI 应用自己的 flag)。
flag 位置敏感:启动器 flag 必须放在应用参数之前,--patch 放到某个应用 flag 后面就归应用了。启动器消费一个 --,需要把字面 -- 传给应用时写 -- --。
-V / --version 是启动器自己的 flag（必须位于应用参数之前）；-h / --help 交给应用解析，只有裸 dsh -h（没有 profile 可交付）才打印启动器帮助。
两种 dump 都不运行应用的命令行提供方，因此拒绝应用参数；--dump-config 叠加 profile 的 cordis.patch.yml、home 级 $DSH_HOME/cordis.patch.yml 与 --patch overlay，--dump-default-config 只打印 bundle 层且不接受 --patch。

三、Web 子命令

dsh web --port 8080              # 指定端口(0 = 随机)
dsh web --host <host>            # 绑定主机(0.0.0.0 被拒绝)
dsh web --trusted-host <host>    # 信任的主机(可重复)
dsh web --no-open                # 不自动打开浏览器
dsh web --dump-config            # 打印配置树并退出

Web UI 默认只监听 127.0.0.1:3080
工作区在 Web UI 内用目录选择器选(非 CLI flag)
开发 HMR:源码目录 pnpm run dev:web 重建 client 资源,dsh web 自动轮询热更

源码版 Web 通过终端打印的 token 启动链接换取浏览器会话；全部 RPC 与 WebSocket 都检查 cookie。--host 0.0.0.0 在启动时被拒绝，--trusted-host 只配置 Host 信任范围，不替代登录。

四、headless 一次性任务

--profile headless 跑一次性任务:任务文本就是命令行剩余部分,提交成一个普通用户消息,跑完把最后一段非空助手文本写到 stdout 退出。

dsh --profile headless "跑 pnpm test,把失败用例汇总成清单"
dsh --profile headless "审查 src/server.ts 的鉴权逻辑,给 3 条可执行建议"
dsh --profile headless "用 glob 列出所有还在用旧 API 的调用点" > /tmp/out.txt

行为要点:

退出码:turn/end 是 completed → 0,否则 1。
源码版把非空的提供方推理分片以 dsh: reasoning: 标题流式写到 stderr，stdout 只输出最终文本；没有推理内容的成功响应保持 stderr 为空。出错时 stderr 还包含错误码和消息。
只提交一个任务,无交互追问界面;不监听任何端口(不挂 Host/Web/浏览器)。
它是"跑完就退"的 CI/脚本友好形态,适合放进 shell、cron 或 Makefile。

五、插件管理

# 安装 bundle 插件(git 源一行)
dsh plugin --profile web add "github:dsh-external/<repo>#main"

# 本地目录开发
dsh plugin --profile web add link:/path/to/plugin

# 移除 / 查看依赖
dsh plugin --profile web remove <包名>
dsh plugin --profile web why <包名>

plugin 把参数原样转发给 pnpm,在 profile 目录执行;只接受 pnpm 能识别的源(纯 git 源、link: 等)。profile 缺失时先初始化它(有随附模板的用模板,其他名称只装 @deepseek-ai/dsh-base),相对路径 spec 先锚定到调用目录。&path: 子路径是 repository 插件机制自己的格式,装 monorepo 子包走插件面板的 repository 源,不经 dsh plugin add。安装 bundle 后重启 dsh web 生效(repository 插件即改即生效)。

六、查看配置

dsh web --dump-config              # 组合后配置树(带层来源注释)
dsh web --dump-default-config      # 只 bundle 层

--dump-config 是排查"哪层覆盖了什么"的权威工具(见启动与配置)。

七、环境变量

变量	作用
`DSH_HOME`	覆盖主目录(默认 `~/.dsh`)
`DSH_TELEMETRY_MODE`	遥测模式(默认 `FEEDBACK_ONLY`；`DISABLED` 全部留在本地，`FULL` 流式上传)
`DSH_TELEMETRY_DISABLED`	任意非空值关闭遥测
`DSH_TELEMETRY_OTLP_URL`	覆盖遥测上报端点
`DSH_PERMISSION_MODE`	权限/沙箱模式覆盖（默认 `workspace-write`；`danger-full-access` 会关闭审批）
`DSH_TOOLS_MODE`	工具呈现模式（`native`\|`ptc`\|`both`；未设置用 schema 默认 `native`）
`DEEPSEEK_API_KEY` 等	provider 凭据(也可存 `.env`)

完整列表见环境变量。

八、常见命令场景

想做什么	命令
跑一个 Web 会话	`dsh web`
跑一次性任务	`dsh --profile headless "任务"`
一次性任务存结果	`dsh --profile headless "任务" > /tmp/out.txt`
带应用层 flag 启动	`dsh --profile tui --resume abc`
看当前组合	`dsh web --dump-config`
只看 bundle 层	`dsh web --dump-default-config`
装个插件	`dsh plugin --profile web add "github:..."`
本地目录装插件	`dsh plugin --profile web add link:/path/to/plugin`
自带 patch 启动	`dsh --profile tui --patch ./extra.yml`

SDK 与 ACP 的 Profile 入口

dsh --profile sdk --help
dsh --profile sdk-minimal --help
dsh --profile acp --help

源码版统一用 dsh Profile 启动这些应用，替代旧的独立 demo bin。sdk、headless 与 acp 默认用 read/write/edit 编辑文件（0.1.3-alpha.2），sdk-minimal 与 Web minimal 仍用 str_replace_editor。sdk-minimal 是独立最小组合，不继承 base；它固定全文件访问，仅用于隔离的测试工作区。SDK / ACP 的 stdout 专用于协议帧，详见 SDK 和 ACP。

下一步

配置：profile / patch / 设置
插件：插件管理全貌
快速上手：第一次跑起来

一、基础用法​

二、launcher flags(启动器层)​

三、Web 子命令​

四、headless 一次性任务​

五、插件管理​

六、查看配置​

七、环境变量​

八、常见命令场景​

SDK 与 ACP 的 Profile 入口​

下一步​