---
title: "使用 DSH Headless 运行一次性 Agent 任务"
seo_title: "DeepSeek Harness Headless 教程：用 DSH 运行一次性 Agent 任务"
description: "基于 DeepSeek Harness 0.1.1-rc.2 官方源码，介绍 DSH Headless 的启动命令、任务输出、退出码、Session 持久化、权限边界和常见问题。"
canonical: https://52dsh.com/tutorials/dsh-headless-guide/
authors: ["52DSH 编辑部"]
published_at: 2026-08-24
updated_at: 2026-08-24
verified_on: 2026-08-24
maintenance_status: community
verification_level: source_reviewed
risk_level: medium
dsh_version: 0.1.1-rc.2
plugin_id: null
tutorial_kind: null
related_plugin_url: null
---

# 使用 DSH Headless 运行一次性 Agent 任务

基于 DeepSeek Harness 0.1.1-rc.2 官方源码，介绍 DSH Headless 的启动命令、任务输出、退出码、Session 持久化、权限边界和常见问题。

## 先看结论

DSH Headless 是 DeepSeek Harness 随发行版提供的一次性任务模式：它不启动 Web UI 或 HTTP 服务，而是创建一个新的持久化 Agent，把命令行中的任务作为用户消息提交，等待任务停稳，将最后一条非空 assistant 文本写到标准输出，然后退出。适合终端、SSH、脚本和经过安全设计的自动化流程，不适合需要连续追问或依赖浏览器审批的交互任务。

使用固定版本 npm 包时，最短形式是：

```bash
npx @deepseek-ai/dsh@0.1.1-rc.2 --profile headless "只读取当前目录并概括文件用途，不要修改文件"
```

本文依据官方 `dsh-v0.1.1-rc.2` 的固定提交进行源码审阅，没有使用真实凭据执行任务，也不把静态审阅描述为运行实测。DSH 仍处于 Developer Preview；版本变化后，应先重新检查 CLI、Profile、权限和持久化行为。

## 什么任务适合 Headless

Headless 的核心价值是“提交一次任务，得到最终文本，进程结束”。它可以作为以下流程的候选入口：

- 在终端中读取一个小型工作区并生成概括；
- 通过 SSH 发起无需浏览器界面的单次分析；
- 在脚本中根据退出码区分完成和未完成；
- 在隔离环境中执行已经明确权限、输入和验收结果的自动化任务。

它只提交一个任务，没有交互式后续输入界面。需要持续对话、浏览工作区状态、处理中途提问或点击审批时，优先使用[安装与 Web UI 指南](/tutorials/deepseek-harness-install-web-ui/)中的 Web 模式。不要把“没有 Web UI”理解成“无状态”“没有工具”或“没有安全风险”。

## 第一步：准备最小运行环境

当前官方包声明 Node.js 范围为 `^22.19.0 || >=24.0.0`。先检查环境：

```bash
node --version
npx --version
```

Headless 使用共享的默认模型选择。运行前需要让 DSH 能解析到对应 Provider 的凭据；官方基础 Bundle 会依次考虑继承环境、`$DSH_HOME/.credentials.yaml`、调用目录 `.env` 和 `$DSH_HOME/.env`。不要把 API Key 放进任务文本、截图、Git 仓库或公开日志。还没有配置模型时，先阅读[模型、API Key 与 Provider 配置](/tutorials/deepseek-harness-model-provider/)。

运行命令时所在目录会成为默认 workspace 根目录。第一次测试应进入一个只包含少量示例文件、可以丢弃且不含凭据的目录，不要直接在用户主目录、生产仓库或客户资料目录运行。

## 第二步：运行一次只读任务

在测试目录中执行：

```bash
npx @deepseek-ai/dsh@0.1.1-rc.2 --profile headless "只读取当前目录，列出文件并概括用途。不要修改文件，不要安装依赖，不要访问工作区外路径。"
```

这里把两条官方事实组合成完整安装版命令：官方根 README 使用 `npx @deepseek-ai/dsh` 启动 npm 包，CLI 参考把一次性任务定义为 `dsh --profile headless "任务"`。页面锁定 `0.1.1-rc.2` 是为了让命令与本文审阅的源码一致，并不代表编辑部已经使用真实模型运行过它。

任务文本可以由多个单词组成，启动器会将它们交给 Headless 的命令行提供方；缺失或只有空白的任务会在 Runner 激活前作为用法错误被拒绝。

## 从官方源码运行时使用另一套命令

只有在你已经克隆官方仓库并从源码开发时，才使用 `pnpm dsh`：

```bash
pnpm install
pnpm run build
pnpm dsh --profile headless "summarize this workspace"
```

官方开发文档明确要求先单独构建，再运行 TypeScript 入口。`pnpm dsh` 不会自动构建，也不是普通 npm 用户的安装命令；已有但过期的构建产物还可能继续运行旧代码。

## 一次任务的数据怎样流动

固定版本中的处理路径可以简化为：

```text
命令行任务
→ Headless Startup 解析位置参数
→ Runner 读取共享默认模型
→ 创建新的持久化 Agent 和 Session
→ 任务作为普通用户消息进入 Agent
→ 等待 Agent 完全停稳
→ flush Session
→ 读取本次区间最后一条非空 assistant 文本
→ 写入 stdout 并请求进程退出
```

Headless 直接叠加在 `dsh-base` 之上，保留编码 persona、工具模式和 Code Mode Worker，但不挂载 Host、ApiProxy、HTTP Server、Web Runtime 或浏览器插件。它不会打开监听端口。Profile 和 Bundle 的组合关系可继续阅读[DeepSeek Harness 架构解析](/tutorials/deepseek-harness-architecture/)。

每次调用都会创建一个新的持久化 Session，并在退出前执行 flush。基础 Bundle 的 JSONL 持久化根位于 `$DSH_HOME/sessions`。因此 Headless 不是“运行完不留记录”的无状态命令；消息、工具参数、结果和工作目录仍可能进入本地 Session 数据。Session 事件与持久化边界见[DSH Session 使用与恢复指南](/tutorials/dsh-session-guide/)。

## 第三步：检查输出和退出码

正常路径会把最后一条非空 assistant 文本写入 stdout，并以换行结束。最终 `turn/end` 原因为 `completed` 时返回退出码 0，其他最终原因返回 1；若最终原因为 `error`，还会把错误 code 和 message 写到 stderr。没有文本不应被自动当作成功，脚本需要同时检查退出码和输出内容。

在 macOS 或 Linux 中，可在命令完成后查看：

```bash
echo $?
```

在 PowerShell 中查看：

```powershell
$LASTEXITCODE
```

自动化流程至少记录 DSH 版本、工作目录、退出码和经过脱敏的结果。不要只搜索某段自然语言回答来判断成功，因为模型文本可能随任务和模型变化。

## 权限和审批边界

新 Session 默认采用 `workspace-write` 权限预设：文件修改限制在 workspace 和平台临时根目录，但读取与网络不由这项文件策略限制，进程可见性也取决于平台沙箱后端。完整边界见[DSH 权限与沙箱指南](/tutorials/dsh-permissions-sandbox/)。

Headless 没有浏览器界面，不应假定任务中途一定能弹出可操作的审批窗口。需要人工判断、外部消息、部署、数据库变更或敏感凭据的任务，不适合作为第一次无人值守任务。不要为了消除审批失败而直接切换到 `danger-full-access`；应先缩小工作区、减少工具范围，并把不可逆动作拆到独立且可审核的流程。

即使任务只要求“总结代码”，模型也可能选择调用读取、搜索或命令工具。任务文本是约束的一部分，但不能替代 DSH 权限配置、系统沙箱、最小凭据、网络出口控制和 Git 复核。

## Headless 与 Web 模式怎样选择

| 对比项 | Headless | Web |
|---|---|---|
| 入口 | `--profile headless` | `web` 或 `--profile web` |
| 交互 | 一次任务，无连续输入界面 | 浏览器会话，可持续交互 |
| 输出 | stdout、stderr、退出码 | Web 页面与 API |
| Session | 每次创建新的持久化 Session | 用户在界面创建和选择 Session |
| 网络端口 | 不打开监听端口 | 默认在本机启动 Web 服务 |
| 适合场景 | 终端、SSH、受控脚本 | 学习、配置、审批、长任务观察 |

两种模式共享基础 Bundle 中的模型、工具、持久化和安全能力，但应用表面不同。第一次使用 DSH 的用户更适合先按[DeepSeek Harness 中文入门](/tutorials/dsh-complete-guide/)完成 Web 路径，再把已经理解的低风险任务迁移到 Headless。

## 常见问题与排查

### 为什么不带任务会直接失败

Headless 的位置参数就是本次唯一任务。固定版本的 Startup 会拒绝缺失或只含空白的任务，避免启动一个不知道要做什么的 Agent。

### 为什么有输出但退出码不是 0

Runner 根据最终 `turn/end` 的原因决定退出码，而不是根据是否出现过 assistant 文本。脚本应以退出码为主，再保留脱敏输出用于诊断。

### 为什么模型或凭据错误发生在任务开始前后

Runner 会读取共享默认模型，实际请求仍需要对应 Provider 和凭据。先把模型连接与工具任务分开验证，不要通过在任务文本中粘贴 Key 绕过配置。

### Headless 是否完全不访问网络

不是。它不启动 HTTP Server 或浏览器客户端，不代表模型 Provider、搜索工具或任务中的外部服务不会访问网络。网络范围取决于当前组合、工具和部署策略。

### 能否直接用于 CI

可以把它作为 CI 候选入口，但需要先解决非交互审批、固定版本、最小权限、凭据注入、超时、退出码、日志脱敏和清理策略。本文没有对任意 CI 平台作兼容承诺。

## 结束、回退与清理

Headless 正常完成后会请求进程退出，没有需要继续关闭的 Web 服务。任务结束后按以下顺序复核：

1. 查看退出码和 stderr，确认不是未完成或错误退出；
2. 使用 `git status --short` 和文件 Diff 检查工作区是否出现意外修改；
3. 检查日志、Session 和 shell 历史中是否出现敏感值；
4. 删除本次专用的可丢弃测试目录，或恢复其中明确不需要的变更；
5. 记录 DSH 版本、模型、操作系统、任务目的和核验日期。

持久化 Session 位于 DSH Home 管理范围。不要为了清理一次测试而递归删除整个 `$DSH_HOME`，其中还可能包含 Profile、设置和凭据。需要清理特定 Session 时，先备份并准确识别目标；对重要数据优先保留原版本和恢复路径。

## 本文的验证范围

本文完成了官方 Release、CLI、Headless Startup、Runner、Bundle Patch、基础持久化和开发文档的固定提交审阅。没有执行真实模型请求，没有验证所有操作系统沙箱，也没有证明任意第三方工具、CI 或 Provider 都能完成任务。

开始处理真实仓库前，先按[安全工作区准备指南](/tutorials/safe-agent-workspace/)建立可回滚测试目录；需要理解一次性任务为何仍保留事件时，继续阅读[Session 持久化与恢复](/tutorials/dsh-session-guide/)。

## 原始来源

- https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.1-rc.2
- https://github.com/deepseek-ai/deepseek-harness/blob/b150a551b8d465e31e418e1b2eaf5e79bbb7d28e/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/b150a551b8d465e31e418e1b2eaf5e79bbb7d28e/apps/cli/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/b150a551b8d465e31e418e1b2eaf5e79bbb7d28e/apps/cli/reference/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/b150a551b8d465e31e418e1b2eaf5e79bbb7d28e/packages/bundle/headless/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/b150a551b8d465e31e418e1b2eaf5e79bbb7d28e/packages/bundle/headless/src/startup.ts
- https://github.com/deepseek-ai/deepseek-harness/blob/b150a551b8d465e31e418e1b2eaf5e79bbb7d28e/packages/bundle/headless/src/index.ts
- https://github.com/deepseek-ai/deepseek-harness/blob/b150a551b8d465e31e418e1b2eaf5e79bbb7d28e/packages/bundle/headless/cordis.patch.yml
- https://github.com/deepseek-ai/deepseek-harness/blob/b150a551b8d465e31e418e1b2eaf5e79bbb7d28e/packages/bundle/base/cordis.patch.yml
- https://github.com/deepseek-ai/deepseek-harness/blob/b150a551b8d465e31e418e1b2eaf5e79bbb7d28e/docs/development.zh.md