0.2 快速上手：跑起来一个 DSH

本章概览：用最短路径启动 DSH 的 Web UI 与 Headless 两种形态，配置模型、选择工作区并运行第一个任务，验证"一切皆插件"的可配置性。

前提条件

• 安装 Node.js（DSH 要求 Node ^22.19 || >=24；本仓库 CI 使用 Node 24）。
• 一个可用的模型 API Key（默认支持 DeepSeek；也支持 OpenAI 兼容端点等，见下文 模型配置）。

出处：AGENTS.md（deepseek-harness-src/AGENTS.md，Node 版本要求）

方式一：Web UI（推荐）

第 1 步：启动

npx @deepseek-ai/dsh web

命令会打印访问地址，默认 http://127.0.0.1:3080：

dsh web: http://127.0.0.1:3080

要点：

• dsh 进程把启动时所在目录作为默认文件系统位置（workspace 根）。
• 首次使用 web profile 时会从随附模板自动初始化（存放在 Harness home，即 $DSH_HOME，缺省 ~/.dsh）。

出处：@deepseek-ai/dsh README.zh.md（本地已安装包 node_modules/@deepseek-ai/dsh/README.zh.md）与 docs/user/guide/index.md

第 2 步：配置模型

打开 Settings → Models，填入 DeepSeek API Key 并保存。无需重启服务，模型路由立即可用。

出处：docs/user/guide/index.md（deepseek-harness-src/docs/user/guide/index.md）

这一行为背后的机制是 dsh-settings（用户设置 seam）与 dsh-credentials（凭据 seam）：配置保存到用户层后，llm-deepseek 适配器在每次请求时解析凭据引用，因此轮换后的凭据在下一次请求即生效，无需重启。

第 3 步：选择工作区

点击 Choose workspace，添加你启动 dsh 时所在的目录并选中。在选中工作区之前，会话编辑区不可用。

第 4 步：运行第一个任务

新建会话，发送：

Summarize this repository and identify its main packages.

你会看到 Agent 可以读取/编辑工作区文件、运行命令、委派子任务、维护计划；当操作需要审批（按当前权限策略）时，Web UI 会先询问。

方式二：Headless 一次性任务

npx @deepseek-ai/dsh --profile headless "Summarize this repository and identify its main packages."

行为特征：

• 运行一个全新的持久化会话，把任务作为普通用户消息提交；
• 等待 Agent 安静（quiescence）后，把最后一条非空的助手文本打印到 stdout；
• 成功（turn/end 完成）退出码 0，否则 1；
• 不打开任何监听端口，适合脚本化调用。

出处：packages/bundle/headless/README.md（deepseek-harness-src/packages/bundle/headless/README.md）

命令行速查

命令	含义
dsh --profile <name>	启动位于 $DSH_HOME/profiles/<name> 的指定 profile
dsh web	--profile web 的别名
dsh --profile headless "job"	一次性持久化会话任务
dsh plugin --profile <name> <pnpm args>	在 profile 目录中转发 pnpm 命令管理插件
dsh --profile web --dump-config	不启动，打印组合后的完整配置树
dsh --dump-default-config	打印默认配置
dsh --help	启动器自身的帮助（不是应用的）

参数归属规则：启动器只解析自己的 flag，其后所有内容交给被启动的 profile；所以启动器 flag 必须写在最前面，第一个启动器不认识的 token 标志着应用参数的开始。例如 dsh --profile web --port 8080 中 --port 属于 web 应用。

出处：@deepseek-ai/dsh README.zh.md

模型配置

DeepSeek

在 Web UI Settings → Models 填入 DeepSeek API Key。对应适配器为 @deepseek-ai/dsh-llm-deepseek，通过 ctx.llm.registerAdapter(['deepseek'], adapter) 注册 provider 路由。

出处：packages/llm/llm-deepseek/README.md（deepseek-harness-src/packages/llm/llm-deepseek/README.md）

其他提供商

官方指南 Configure models 覆盖其他 provider 与自定义 OpenAI 兼容端点（docs/user/guide/providers.md）。配置入口在用户设置的模型命名空间下；LLM 适配器通过 ctx.llm.registerConfigurableProviders 声明"可配置 provider 路由"，配置界面据此显示可用项。

常见问题排查

现象	原因与处理
启动后无法访问	确认打印的 URL；--host 0.0.0.0 会被拒绝（CLI 暂不支持全接口绑定）
模型不可用	检查 Settings → Models 的 Key；凭据是"引用"而非明文，解析发生在每次请求
--help 打印的不是 dsh 帮助	dsh --help 才是启动器帮助；dsh web --help 是 web 应用的帮助
想清理 profile	Harness home 缺省为 ~/.dsh，profile 在 $DSH_HOME/profiles/<name>

出处：packages/bundle/web-app/README.md（--host 0.0.0.0 拒绝行为，deepseek-harness-src/packages/bundle/web-app/README.md）

小结

你已经跑起来 DSH 的两种形态，并观察到一个关键事实：模型、工作区、权限这些部件都是运行时可配置的插件。下一章 0.3 运行机制初探 将揭开"组合"幕布——profile、组合包与配置树到底是怎么叠出来的。

参考资料

• README.zh.md — 运行方式（deepseek-harness-src/README.zh.md）
• docs/user/guide/index.md — Web UI 指南（deepseek-harness-src/docs/user/guide/index.md）
• docs/user/guide/providers.md — 模型提供商配置（deepseek-harness-src/docs/user/guide/providers.md）
• apps/cli/README.md — CLI 行为参考（deepseek-harness-src/apps/cli/README.md）