02. 快速开始：安装、Web UI、Headless 与第一次运行诊断

02. 快速开始：安装、Web UI、Headless 与第一次运行诊断

系列：DeepSeek Harness 从入门到源码与二次开发

基于仓库：deepseek-ai/deepseek-harness 的 master 分支（核对日期：2026-08-26）

项目状态：官方仍标记为 Developer Preview ，内部 API、配置结构和包边界可能继续发生破坏性变化。

阅读约定：本文优先解释"设计与执行链"，示例代码若标注"示意"，应以仓库当前类型定义与生成文档为最终准绳。

这一篇目标不是"把命令抄一遍"，而是让你知道 每一步在验证什么。当 DSH 启动失败时，你应该能区分：Node/pnpm 环境问题、构建问题、Profile 组合问题、模型配置问题、Workspace 权限问题，以及运行期插件没有激活的问题。

1. 两种运行路径：npm 与源码

如果只是体验 DSH，最短路径是：

npx @deepseek-ai/dsh web

官方 README 当前说明 Web UI 默认服务于 http://127.0.0.1:3080。本地启动通常会打开浏览器；如果不希望自动打开，可使用 --no-open。

这条路径适合"先理解产品"。它的优势是不用关心 monorepo 构建。

如果目标是读源码或二次开发，则使用源码路径：

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

这里最重要的不是命令本身，而是区分：

pnpm install   → 安装 workspace 依赖 + 仓库安装期配置
pnpm run build → 构建 Host/Client 等产物
pnpm dsh web   → 用当前仓库产物启动一个 profile

2. 当前开发环境要求

截至核对日期，官方 development guide 列出的关键要求包括：

• Node.js 22.19+ 或 24+；CI 还覆盖 Node 26；
• pnpm 通过 Corepack 使用，仓库 package.json 固定具体 pnpm 版本；
• Git 2.26+；
• 如果要跑真实模型调用，需要相应 API key。

第一次检查建议：

node --version
corepack --version
pnpm --version
git --version

如果 pnpm --version 没有走 Corepack，不要先全局乱装多个 pnpm，优先：

corepack enable

3. 为什么安装后不建议直接开始改代码

先做一个"基线验证"：

pnpm run typecheck

如果目标是启动 Web，再执行：

pnpm run build
pnpm dsh web

原因很简单：如果原始 checkout 在你的机器上就有环境问题，那么之后任何源码修改造成的错误都会和环境错误混在一起。

开发时要建立这个习惯：

clean checkout 能否通过？
        ↓
你的改动引入了什么新的失败？

4. Web UI 第一次应该验证什么

启动 Web 后，不要一开始就给它复杂任务。第一次应该验证四件事：

4.1 模型配置是否可用

在 Settings / Models 中配置模型。模型问题和 Tool 问题要分开验证，先做一个不依赖工具的请求，例如：

Reply with one sentence confirming the model is reachable.

如果失败，优先检查 key、base URL、provider/model selection，而不是去怀疑文件系统插件。

4.2 Workspace 是否正确

DSH 的文件、Shell、AGENTS/skills 等行为通常和当前 workspace 有关。新手最常见的问题之一是"Agent 看不到文件"，实际原因是选错工作目录。

建议创建一个临时目录：

sandbox-demo/
  README.md
  notes.txt

然后让 Agent：

Read README.md and tell me the first heading. Do not modify files.

4.3 Tool 是否真的在当前 Agent scope 可见

能看到 Web 页面不代表每个 Tool 都已注册。Tool visibility 受 profile、scope、restriction、preset 等影响。

如果某个工具"不见了"，先问三个问题：

1. 对应 provider/consumer package 是否加载？
2. Tool 是否被当前 scope restriction 过滤？
3. 当前 Agent preset 是否挂载了相应插件？

4.4 Session 是否能够形成完整事件链

再执行一个低风险工具任务，例如读取文件。观察 UI 中是否出现：用户输入、模型消息、工具调用、工具结果，以及最终回答。

这一步实际上是在验证：

Agent admission
→ LLM request
→ tool pipeline
→ Session event
→ UI projection

5. Headless 模式为什么重要

源码开发文档给出的典型形式是：

pnpm dsh --profile headless "summarize this workspace"

Headless 不是"简化版 Agent"。它说明 DSH 的核心能力并不依赖 Web：同一个 Agent/Session/LLM/Tools 组合可以换一个入口。

这对自动化尤其重要。例如 CI 中可以做：

checkout repo
  ↓
启动 headless profile
  ↓
执行一次审计任务
  ↓
把结果写成 artifact

而不需要浏览器。

6. Profile 是启动行为的关键，不要把它当命令行皮肤

运行：

dsh --profile web ...

真正做的是选择一套插件组合。Web/Headless 只是官方常用模板，自己的科研 Harness 完全可以定义新的 profile。

理解这一点后，你会知道：某个功能没出现，不一定是代码坏了，也可能只是 当前 profile 没有组合那个插件。

7. --dump-config：排查"为什么没加载"的第一工具

对于配置型插件系统，一个常见误区是凭脑子猜"加载顺序"。更稳妥的方法是检查最终配置树，例如：

dsh --profile web --dump-config

重点看：

• 预期 Bundle 是否出现；
• 某行是否被上层 patch 覆盖；
• 插件是否 disabled；
• config 是否在插值后变成了意外值；
• 同名 row 是否被后续层替换。

后面学习 Profile/Bundle 时会详细解释。

8. API Key 与环境变量

真实密钥不要写进仓库，也不要放进博客示例。常见形式例如：

export DEEPSEEK_API_KEY='...'

或通过 .env / settings 机制提供，具体以当前 profile 与 adapter 文档为准。

更重要的是理解"密钥属于配置/凭据层"，不要把它硬编码到 Tool 或 Agent 业务逻辑里。

9. 一个推荐的最小诊断矩阵

遇到启动或运行问题时，不要只说"DSH 跑不起来"，先分类：

层次	验证方式	常见问题
Node/pnpm	node -v, pnpm -v	版本不匹配、没走 Corepack
依赖	pnpm install	lockfile / native dependency
类型	pnpm run typecheck	TS aggregate / generated type
构建	pnpm run build	Host/Client / web build
Profile	--dump-config	插件未组合、patch 覆盖
LLM	纯文本请求	key/provider/model 错误
Workspace	读一个小文件	cwd/workspace 不对
Tools	低风险工具调用	restriction/policy/provider
Session	UI/日志观察	持久化/投影/事件链

10. 从源码运行时的目录认知

刚 clone 后先只认识这些：

apps/       应用层
packages/   核心能力与产品包
packages/bundle/  默认组合
packages/boot/    启动相关
packages/llm/     模型抽象与 adapter
packages/core/    Agent/Session/Tools 等核心协议
packages/subagent/ 子 Agent 能力族
docs/       架构、子系统、指南与生成参考
scripts/    构建与文档生成脚本

不要第一天就逐个 package 阅读。先让系统跑起来，然后沿实际一次请求的路径阅读。

11. 常见问题

11.1 Web 能打开，但模型不可用

这说明 Web server 启动成功，不代表模型 provider 配置成功。先用不调用工具的最短提示验证 provider。

11.2 模型能回答，但不能读文件

优先检查 workspace、FS provider、tool consumer、tool restriction/sandbox/approval，而不是模型。

11.3 从源码运行出现大量类型错误

先确认 Node/pnpm 版本和 clean checkout baseline，再确认是否缺少 build/generated artifacts。不要一上来用 skipLibCheck 或删除类型约束"解决"。

11.4 Headless 与 Web 行为不一致

先比较 Profile 最终组合，而不是假设它们应完全相同。它们共享核心能力，但入口和附加插件不同。

12. 本篇实践任务

完成下面四步，再进入源码：

1. 启动 Web
2. 配置模型并完成纯文本请求
3. 选择一个临时 workspace，完成只读文件任务
4. 用 headless 对同一 workspace 做一次摘要

然后记录两者在工具、UI、事件呈现上的差异。

小结

"成功打开网页"不是跑通 DSH；真正的基线是 运行时、模型、Workspace、Tool pipeline 和 Session event 链路都能被分别验证。当你学会分层诊断，后续修改源码时会少掉大量无效排查。

官方参考资料

• https://github.com/deepseek-ai/deepseek-harness/blob/master/README.md
• https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/development.md
• https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md