第 04 章 · 安装、配置与第一个任务

本篇目标：五种启动形态任选其一跑通，并能 dump 出本机真实插件树。 动手前先读 4.1 节。 这不是客套。

4.1 安全前置：官方自己怎么说的

官方 SAFETY.md 原文（仓库根目录，运行前 README 强制要求阅读）：

DeepSeek Harness is experimental developer-preview software. It has not undergone a security audit and must not be treated as secure or production-ready.

以及：

Sandboxing, approval prompts, and permission controls can reduce risk, but they do not guarantee isolation or prevent damage. Even correctly enforced restrictions cannot protect resources that the project is allowed to access.

官方给出的 Responsible use 五条，逐条照做：

官方 README 同时写明：THERE WILL BE COMPATIBILITY-BREAKING CHANGES。重要环境必须固定版本号——仓库当前可见版本线索为 0.2.2-rc.1（2026-11-04 提交），本教程不保证命令与配置键在你读到的版本仍然一致。

⚠️ 本章所有命令，执行前先确认你在隔离环境里。 教程里的 npx 会拉起一个能执行模型生成代码、能装第三方插件、能联网的进程。

4.2 三条启动路径

路径 A · npm（最快）

官方 README + 官网：

# 前置：安装 Node.js（具体版本要求以仓库 package.json 的 engines 字段为准，自行核对）
npx @deepseek-ai/dsh web

• 默认启动 Web UI 于 http://127.0.0.1:3080，本地启动会自动开浏览器
• SSH 启动只打印 host URL（转发地址由 SSH 客户端或编辑器持有）
• --no-open：起服务但不开浏览器

npx @deepseek-ai/dsh web --no-open

路径 B · 源码（要改插件就必须走这条）

官方 README 原文步骤，原样照抄：

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build       # 准备仓库构建产物
pnpm dsh web         # 使用已构建产物启动，不会重新构建

开发态 官方 CONTRIBUTING.md：

pnpm run dev:web     # 单终端：构建 + serve + 源码改动时重建 client bundle
make help            # 列出 Web / Desktop 对应的 Make targets

路径 C · SDK / headless（自动化）

官方 docs/architecture.md 列出的 shipped profiles：

dsh --profile headless  # 或 dsh headless
dsh --profile sdk --dump-config

官方 BENCHMARK.md 给出跑分入口：按 docs/user/guide/python-sdk.md 安装 Python SDK 并运行 jsonrpc-agent minimal variant，独立任务必须使用独立 workspace 与独立 session id。第 15 章整章建立在这条纪律上。

4.3 第一次配置：三步，别跳

官方 docs/user/guide/index.md：

1. Settings → Models：填入 DeepSeek API key 并保存。模型路由立即生效，无需重启服务。其他 provider 与自定义 OpenAI-compatible endpoint 见 guide/providers.md。
2. Choose workspace：dsh 进程以启动目录为默认文件系统位置，但全新 Web UI 在添加工作区之前没有选中任何 workspace，会话输入框不可用。点击添加你启动 dsh 时的项目目录并选中。
3. Run a task：官方给的第一条测试指令——

Summarize this repository and identify its main packages.

Web UI 会依据当前权限策略，在需要审批的操作前询问。

常见「点了没反应」排查顺序：模型 key 是否保存 → workspace 是否选中 → 端口 3080 是否被占 → 是否走 SSH 需要手动转发。别先怀疑模型。

4.4 真正该做的第一步：--dump-config

官方 架构文档：一个运行中的 dsh 是启动时按层叠顺序组装出来的插件树。

profile 的 ordered bundles
  → profile 自带的 cordis.patch.yml
  → Harness home 的 patch
  → --patch overlays

patch 按 row id 定位，可以整体替换某行配置，或插入新行；preset patch 在 config.plugins 内部执行同样的操作。

dsh --profile web --dump-config

原文："Any row it prints can be replaced by a patch of your own."

这是全书最重要的一条命令。它把「我以为的 Harness」变成「实际在跑的 Harness」。任何配置问题、模式差异、插件不生效，第一步都应该是 dump 出真实树，而不是猜。第 13 章会用 cordis.patch.yml 改这棵树。

官方 补充：YAML 控制 HMR，base 启用 config-only dsh-hmr；headless / sdk / acp 禁用；sdk-minimal 完全不含。

4.5 官方文档站导航（中英各 95 页）

官方 站点提供 llms.txt，并约定：页面 URL 去掉末尾斜杠再加 .md 即该页原始 Markdown，根路径为 /index.md。这对批量抓取、喂给 LLM、做本地索引极其友好。

入门必读 9 页：

⚠️ 公开部署是高风险动作。DSH 未经过安全审计，默认只监听本机。放到公网前必须自行完成认证、隔离与凭据治理——本教程不提供「一键公网暴露」的配置。

4.6 五分钟体检（沿用原文的收尾动作，补全官方依据）

「在系统提示词里写『只读文件』是一种建议，不是强制边界」原文。真正的边界来自沙箱与审批，第 08、17 章分别给出实现。

4.7 本章产出与验收

核心产出：dump-config.txt（本机真实插件树快照）+ 一次完整任务回放（含审批记录）。

验收点：

• 能在隔离环境中跑起 Web UI，并完成第一个任务
• 能指出 dsh-base 与 dsh-web-app 的分工
• 能解释 sdk-minimal 为什么是唯一不套 dsh-base 的 profile
• 能用 llms.txt 的规则拼出任意一个文档页的 raw Markdown 地址
• 能默写 SAFETY.md 的核心警告，并说清它对「能否直接上生产」的结论

延伸阅读