跳到主要内容
路径文档
EnglishGitHub快速上手

快速上手

这一篇按官方公开仓库的运行方式先把 DSH 跑起来,不深究原理(原理留给 原理课程 和 学习路径)。

DSH 当前处于 Developer Preview，版本迭代可能包含兼容性变更。官方源码与发布说明以 deepseek-ai/deepseek-harness 为准。

这一程你会得到什么​

结束时你会:

  • 配好模型 API Key
  • 打开 Web UI 完成第一次对话,并看到"组合树"长什么样
  • 知道自己把东西存在了哪

0. 安装与版本要求​

需要 Node.js ^22.19.0 或 >=24.0.0。零安装启动方式是：

npx @deepseek-ai/dsh web

它会启动 Web UI，默认地址为 http://127.0.0.1:3080。如果你在官方源码仓库中开发，使用：

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

后文用 dsh 表示已经可用的 CLI 入口；使用零安装方式时，把 dsh ... 写成 npx @deepseek-ai/dsh ...。

1. 配置 API Key​

DSH 启动时按优先级读凭据:进程环境 → ~/.dsh/.credentials.yaml(托管存储)→ 工作目录 .env → ~/.dsh/.env(兜底)。

# 方式 1:写进 ~/.dsh/.env(作为兜底层)
echo "DEEPSEEK_API_KEY=sk-xxx" >> ~/.dsh/.env

# 方式 2:临时环境变量
export DEEPSEEK_API_KEY=sk-xxx
  • 官方 provider 名是 deepseek-official,模型如 deepseek-v4-flash(默认路由见 配置)。
  • 想用别的 provider / 自建网关,配 llm-pi-ai.providers(见 多模型)。

凭据安全:托管的 .credentials.yaml 由 DSH 原子落盘 0600(0700 目录);.env 是普通环境层,权限自负。更细的机制见 凭据管理 与 数据与隐私。

2. 启动 Web UI​

npx @deepseek-ai/dsh web

浏览器自动打开 http://127.0.0.1:3080。

第一次你会依次看到版本化提示与模型凭据引导；完成后进入工作台：

  • 左侧是可折叠的 Workbench 侧栏(展开宽栏或 56px rail)
  • 中间是可选的工作区:第一次会要求你选一个工作目录,DSH 的活动都发生在你选的这个目录里
  • 右上角可以切换 深/浅色主题

Web UI 默认只监听 127.0.0.1:3080(loopback,不暴露到局域网)。要局域网访问:dsh web --host 0.0.0.0。

打不开?常见原因​

症状排查
端口被占dsh web --port 8080 换端口
浏览器没自动开手动访问 http://127.0.0.1:3080
页面异常/空白dsh web --dump-config 看插件树是否正常(见下)

3. 第一次对话​

选定工作目录后,你输入的第一条消息就能触发完整链路:agent 选模型 → 装配上下文 → 调模型 → (可能)调工具 → 回写会话。整个过程都会写进 ~/.dsh/sessions/ 的会话日志(默认 zstd 压缩)。

试一个会触发工具的提问,比如"列出当前目录的前 10 个文件"。你会看到消息流里:

  1. 一个 user/message(你发的)
  2. 若干 assistant/message 或工具调用(tool/call → tool/result)
  3. agent 汇总成回答

这一条消息走过了什么,是 Agent 主循环 整篇的主题。现在先不用深究,确认它能动就行。

4. 验证与观察​

# 组合树:看 DSH 把哪些插件叠在了一起(排查"哪层覆盖了什么"的权威工具)
dsh web --dump-config | head -40

# 会话日志(默认 zstd 压缩、两级 --<cwd>--/<id>/ 目录)
zstdcat ~/.dsh/sessions/*/*/session.jsonl.zstd | tail -20

--dump-config 每一行通常带 # == 层来源注释,你能看出某个配置来自 base 层、web-app 层还是你的 profile 层。

5. 常用路径速查​

路径作用
~/.dsh/Harness 主目录(配置、会话、插件)
~/.dsh/profiles/web/Web profile(插件挂载、依赖、cordis.patch.yml)
~/.dsh/sessions/会话日志(zstd 压缩,两级目录)
~/.dsh/.envAPI Key(0600 权限)
~/.dsh/settings.yaml全局运行时设置(默认模型路由、权限预设等)

6. 常见问题​

问题解决
--dump-config 报错/断插件通常是某个插件解析失败：fail-loud 会告诉你哪个;删掉可疑的 patch 行重试
模型没反应检查 .env 的 key 是否正确、provider/model 是否配齐(见配置)
想换模型见 配置模型

下一步​

你现在能跑了。接下来按你的目标选一条路:

完整导航见 学习路径。