dshseek
English

seek://guides/choosing-a-dsh-surface

选择 DSH 的运行面：Web UI、Headless、SDK、ACP 与社区客户端

2026年9月5日Beginner← 全部教程

TL;DR

dsh 是一个启动器，自带五个 profile——web、headless、sdk、sdk-minimal、acp——首次使用时自动初始化。本文把每个运行面对应到 CLI reference 为它文档化的用途：日常交互用 Web UI，CI 与脚本用一次性 headless，嵌入程序用 Python SDK，编辑器接入用 ACP，外加本站地图收录的社区 TUI 与桌面客户端。

要点

  • dsh 自带五个随模板自动初始化的 profile——web、headless、sdk、sdk-minimal、acp；其他 profile 名需先用 dsh plugin add 填充
  • web profile 默认服务 http://127.0.0.1:3080，本地启动时打开浏览器，SSH 环境下改为只打印主机 URL，并刻意以 usage error 拒绝 --host 0.0.0.0
  • headless profile 是一次性运行器：任务文本作为位置参数，推理过程流到 stderr，stdout 只输出最终文本，completed 退出 0 否则 1——不监听任何端口
  • sdk 与 sdk-minimal 经 stdio 走 JSON-RPC；独立的 sdk-minimal 省略指令发现与 SQLite，并把权限预设钉死为 danger-full-access
  • acp profile 经 stdio 走 Agent Client Protocol，也就是编辑器接入时说的协议
  • 终端 UI 也是插件：CLI reference 演示了用 git 托管包把一个 TUI 装进专用的 tui profile，再用 dsh --profile tui 启动
  • profile 的配置以同一方式分层——bundle patch、profile 自身 patch、home 级 patch、--patch 覆盖层——base 系 profile 的凭据按环境变量、$DSH_HOME/.credentials.yaml、调用目录 .env、$DSH_HOME/.env 的顺序解析
  • base 系 profile 的新会话默认 workspace-write 权限预设；独立的 sdk-minimal 则钉死 danger-full-access

问「DSH 怎么跑」，诚实的回答是：看这次运行是为什么服务的。dsh 不是单一应用，而是一个自带多个 profile 的启动器，每个 profile 都是通向同一 agent 内核的不同运行面。本文把 CLI reference 文档化的每个运行面走一遍，说清各自的用途，最后落到社区客户端的位置。

一个启动器，五个随装 profile

CLI 行为参考定义了五个首次使用时自动从随装模板初始化的 profile：web、headless、sdk、sdk-minimal、acp。其他 profile 名启动时大声报错并提示先执行 dsh plugin --profile <name> add <package>——超出随装五件的 profile 都要自己组装，终端 UI 正是这样加进来的（下文详述）。

Profile 你运行的命令 你得到的东西
web dsh web（--profile web 的别名） http://127.0.0.1:3080 上的 Web UI，本地启动自动开浏览器
headless dsh --profile headless "任务文本" 一次性运行：stdout 最终文本 + 退出码约定
sdk stdio 客户端接入 stdio 上的 JSON-RPC，含 base bundle
sdk-minimal 由 Python SDK 启动 stdio 上的 JSON-RPC，独立精简树
acp 由讲 ACP 的编辑器启动 stdio 上的 Agent Client Protocol

web profile：默认的正门

上游 README 的 Run 一节以一条命令开场——npx @deepseek-ai/dsh web——对新手的第一次接触来说它就是正确答案。按 CLI reference，dsh web 是 --profile web 的硬编码别名；生产 runner 默认服务 http://127.0.0.1:3080，待 loader 树就绪后打开浏览器。碰参数之前有两件远程相关的事值得知道：在 SSH_CONNECTION 下启动会打印主机 URL 但跳过浏览器跳转（转发地址归你的 SSH 客户端管）；CLI 刻意不支持 --host 0.0.0.0——收到即以 usage error 退出，而不是把界面粗放地暴露出去。--trusted-host 向 /api 浏览器信任围栏追加具名授权。

进入 web profile 后按会话选择 agent preset——web 应用暴露 cordis、ptc、standard 三个预设，另有随装的 minimal 预设（界面里的极简模式），只组合持久化 bash 与 str_replace_editor。会话如何指向模型与提供方是另一个话题，见在 DSH 中配置模型与提供方。

headless：一个任务，一个退出码

dsh --profile headless "run the tests" 是文档化的自动化运行面。任务文本是位置参数；运行会创建一个全新持久化 Agent、提交任务并等待静默。输出纪律严格：推理增量以 dsh: reasoning: 标题流到 stderr，stdout 只承载最终助手文本，completed 退出 0、否则退出 1。没有任何东西在监听：随装的 headless profile 不挂浏览器连接、HTTP 服务、Web runtime 或浏览器客户端，不开监听端口。干净的 stdout 约定 + 退出码 + 无服务，这三件事使它成为 CI 与脚本的运行面。

SDK 与 sdk-minimal：把 DSH 嵌进你的程序

Python SDK 指南记录了嵌入路径：装 SDK、指向 base URL，SDK 会惰性拉起随装的 dsh --profile sdk-minimal 进程并复用直到上下文管理器退出。sdk 与 sdk-minimal 都在 stdio 上讲 JSON-RPC，都不接选项。差别在范围：sdk 由 base bundle 与 sdk-app bundle 组合，sdk-minimal 跑独立 bundle——以调用目录作为文件系统与沙箱根，省略指令发现与 SQLite，并把通常的 workspace-write 换成 danger-full-access。嵌入者得到一棵更安静的配置树，也继承了全权限默认值——把它指向你在乎的机器之前，这段话值得读两遍。

ACP：编辑器作为客户端

acp profile 不接选项，经 stdio 走 Agent Client Protocol——编辑器嵌入 agent 时说的就是这套协议。生态侧的对应物是本站地图收录的 ACP 桥（Zed 等编辑器接入），它把 Zed 一类编辑器接上 DSH。如果你的日常驾驶座是编辑器而不是浏览器标签页，该盯的就是这个运行面。

base 系 profile 共享的底层设施

各运行面在边缘处不同，底下的管道是共用的，CLI reference 对此写得明确：

  • 配置分层组合：profile manifest 里点名的 bundle patch，然后 profile 自身的 cordis.patch.yml，然后 home 级 $DSH_HOME/cordis.patch.yml，再按 argv 顺序叠加 --patch 覆盖层——同行的冲突后层获胜。我们的DSH Profile 与 dsh plugin 命令深入讲过这套机制。
  • 插件底层是 pnpm：dsh plugin --profile <name> add|remove|why|update 转发给 pnpm，manifest 声明了 dsh.bundle.patch 的依赖会自动加入层栈。bundle 成员变更在下一次 profile 启动时落地；live 型 profile 的 patch 文件编辑经热重载生效。
  • 凭据按固定顺序解析：继承的环境变量，然后 $DSH_HOME/.credentials.yaml，然后调用目录的 .env，最后 $DSH_HOME/.env。
  • base 系 profile 的权限默认 workspace-write：bash 与文件系统变更被限制在会话工作区和平台临时根内，读取与网络访问不受限。独立 sdk-minimal 树是文档写明的例外（danger-full-access）。
  • 指令文件按预算加载：base 系模式把调用目录当作工作区根，在 65,536 字节的渲染预算内加载适用的 AGENTS.md 或 CLAUDE.md。

社区客户端在哪里

随装 profile 不是故事的终点，因为启动器把 TUI 也当作普通插件：CLI reference 自己就演示了用 git 托管包把一个终端 UI 装进专用的 tui profile、然后 dsh --profile tui 启动。围绕这套机制长出了一个第三方客户端生态，通过核验的都在本站地图上——DSH TUI 全屏终端、Rust 实现的Rust/ratatui 终端客户端、DSH Desktop 桌面客户端，以及社区版DSH Desktop 社区桌面发行版。它们是社区项目而非上游运行面——README 的 developer-preview 警告（会有破坏性兼容变更）对它们格外适用，这也是本站条目携带 verifiedAt 日期与事实表、而不凭印象写的原因。

一段话版本

日常交互驾驶：dsh web。脚本或 CI 里跑一个任务：dsh --profile headless "..."。让自己的程序进入循环：Python SDK。让编辑器进入循环：ACP。想在熟悉的终端或桌面窗口里干活：地图上的社区客户端——像 DSH 里的一切一样，以插件方式安装。新手请从五分钟上手 DeepSeek Harness 开始，并把 DSH Profile 与 dsh plugin 命令放在手边，因为上面每个运行面都经同一套 profile 机制配置。

官方参考