---
title: "使用 DSH Headless 运行一次性 Agent 任务"
seo_title: "DeepSeek Harness Headless 教程：用 DSH 运行一次性 Agent 任务"
description: "基于 DeepSeek Harness 0.1.5-rc.1 固定源码，说明 DSH Headless 一次性任务的启动、推理日志、最终输出、退出码、Session 持久化与权限边界。"
canonical: https://52dsh.com/tutorials/dsh-headless-guide/
authors: ["52DSH 编辑部"]
audience: []
outcomes: []
prerequisites: ["Node.js 版本满足 ^22.19.0 或 >=24.0.0","已准备可用的模型 Provider 与凭据"]
difficulty: intermediate
estimated_action_time: null
next_steps: null
published_at: 2026-08-24
updated_at: 2026-09-16
verified_on: 2026-09-12
maintenance_status: community
verification_level: source_reviewed
risk_level: medium
dsh_version: 0.1.5-rc.1
plugin_id: null
tutorial_kind: null
related_plugin_url: null
---

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

基于 DeepSeek Harness 0.1.5-rc.1 固定源码，说明 DSH Headless 一次性任务的启动、推理日志、最终输出、退出码、Session 持久化与权限边界。

## 先看结论

DSH Headless 在一次进程中创建新的持久化 Agent，执行一项任务，等待停稳并 flush Session，再向 stdout 输出最终文本并退出；随附 Profile 不打开 Web UI 或监听端口。以下操作基于 `0.1.5-rc.1` 固定提交，2026-09-12 核对；本站未使用真实凭据运行任务。

依据：[固定 Headless 说明](https://github.com/deepseek-ai/deepseek-harness/blob/183f08e9c6dde7e36cd2318eaee70b0da08fb35e/packages/bundle/headless/README.zh.md)与[运行器实现](https://github.com/deepseek-ai/deepseek-harness/blob/183f08e9c6dde7e36cd2318eaee70b0da08fb35e/packages/bundle/headless/src/index.ts)。退出码表示轮次结束状态，不证明生成的答案正确或用户任务验收通过。

新版管道、续接与 JSON 事件另见[0.1.6-alpha.1 差异](#016-alpha1管道输入会话续接与-json-输出)，不要把新参数加到下方 rc.1 示例中。

## 如何运行一次性任务

先确认 Node.js 满足运行版本要求、pnpm/安装环境可用，且已配置模型 Provider 与凭据。进入可丢弃的测试工作区，使用固定版本：

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

查看帮助，不执行 Agent 任务：

```bash
npx @deepseek-ai/dsh@0.1.5-rc.1 --profile headless --help
```

npx 仍可能下载包，首次使用 Profile 也可能初始化配置，不能把帮助命令称为绝对无副作用。启动器参数要放在应用参数之前，任务文本作为 Headless 的位置参数传入。缺失或只有空白的任务会被拒绝；一次调用不支持交互式追问。

当前工作目录决定本次 Agent 的 cwd；任务文本中的“不要修改”不是沙箱。凭据准备见[模型与 Provider 配置](/tutorials/deepseek-harness-model-provider/)，不要把 Key 放进任务文本或命令行。

## stdout、stderr 和退出码分别意味着什么

| 信号 | rc.1 固定实现 | 怎样判断 |
|---|---|---|
| stdout | 所属事件区间最后一条非空 assistant 文本，末尾换行 | 作为结果文本，不当成逐步工具执行日志 |
| stderr | 提供方非空推理增量以 `dsh: reasoning:` 开始，也用于错误诊断 | 有内容不等于失败；没有推理增量的成功运行可为空 |
| 退出码 0 | 最终 `turn/end` 为 completed | 继续检查任务自身的文件、测试或其他验收结果 |
| 退出码 1 | aborted、error、没有所属轮次，或启动/驱动失败 | 根据错误信息判断失败阶段，不仅检查 stdout 是否非空 |

运行器按结束原因决定退出码，并非以“有没有答案文本”作为成功条件。stderr 在第一个推理增量之前可能保持安静，不能只凭短时间无输出判断卡死。推理日志和最终输出都可能包含任务信息，分享前脱敏。

在 macOS/Linux 的 shell 中，可以分别保存两路输出并立即读取状态：

```bash
npx @deepseek-ai/dsh@0.1.5-rc.1 --profile headless "只概括当前目录，不要修改文件" > result.txt 2> diagnostic.log
task_exit=$?
printf 'exit=%s\n' "$task_exit"
```

PowerShell 运行后使用 `$LASTEXITCODE` 读取原生程序退出码。重定向会创建本地文件，敏感任务不要将日志自动上传到公共 CI 产物。以上为验证步骤，未作为本站运行成功记录。

## Session 是否保留，下一次能继续追问吗

本版通过注册表创建新的持久化 Agent，提交任务、等待完全停稳、flush Session，再折叠该次调用拥有的事件区间得到最终结果。新一次命令会创建新 Agent，不能当作自动恢复上次聊天。历史会话的读取与恢复另见[Session 指南](/tutorials/dsh-session-guide/)。进程退出也不等于 Session、插件缓存或工作区文件已删除。

需要备份或升级时，按[更新、回退与卸载](/tutorials/dsh-update-uninstall/)分别处理程序、Profile 和数据；不要把打印的最终文本当成完整会话备份。

## Headless、Web minimal 和 Python SDK 怎样区分

| 模式 | 本页核对范围 | 不能直接套用的结论 |
|---|---|---|
| 完整 Headless | rc.1 的 base + headless 组合、任务驱动与退出 | 不能因无界面就认为无网络、只读或不持久化 |
| Web minimal Agent | rc.1 CLI 文档说明模型侧仅组合持久 shell，仍有共享 Web 宿主 | 工具少不代表 shell 无法写文件 |
| Python sdk-minimal | 独立组合，CLI 文档说明固定 danger-full-access 且省略审批与权限 settings | 不继承完整 Headless 的权限结论 |
| rc.2 与其他版本 | 本页未完成完整对应核验 | 包已发布不等于本文已经运行兼容验收 |

本轮不提供未经核对的 SDK 安装命令或工具启用 patch。依据：[rc.1 CLI 与模式说明](https://github.com/deepseek-ai/deepseek-harness/blob/183f08e9c6dde7e36cd2318eaee70b0da08fb35e/apps/cli/reference/README.zh.md)。

## 无界面任务怎样处理权限与审批

基于 base 的新会话默认使用 workspace-write 预设。它限制文件修改位置，读取与网络不由这项文件策略限制；部署的工具、patch 与系统后端仍需独立核对。

Headless 不提供浏览器审批界面。`ask` 没有可用应答者时不能放行，`never` 也不是全部允许。不要为绕过审批错误直接切换 danger-full-access。先缩小任务和工作区，按[权限与沙箱指南](/tutorials/dsh-permissions-sandbox/)检查实际策略。

## 首次验证与故障分流

1. 在测试目录记录运行版本、Profile 和工作区，不使用生产凭据。
2. 运行一个范围明确的读取任务，分别记录 stdout、stderr 与退出码。
3. 对照输出检查目录范围，并检查文件差异；退出 0 也需要人工验收结果。
4. 401 或缺少凭据进入[凭据与搜索认证排障](/errors/dsh-missing-credential-401/)；无法写入先检查[工作区与权限](/tutorials/dsh-permissions-sandbox/)。
5. 若需要持续多轮交互，改用[Web UI 安装与启动](/tutorials/deepseek-harness-install-web-ui/)；只有 Web 服务启动失败才进入[启动排障](/errors/web-ui-start-failed/)。

## 0.1.6-alpha.1：管道输入、会话续接与 JSON 输出

以下三项仅适用于 `0.1.6-alpha.1`，2026-09-16 按固定源码核对；上方默认命令和版本卡仍为 `0.1.5-rc.1`。未使用真实模型运行这些示例，不将源码审阅写成跨平台或 CI 验收。

### 从标准输入传入任务

macOS/Linux shell 示例，在可丢弃工作区、已配置测试模型与实际权限策略的前提下运行：

```bash
printf '%s\n' '只回答 OK，不调用工具' | npx @deepseek-ai/dsh@0.1.6-alpha.1 --profile headless -
```

省略任务且 stdin 不是终端，或任务仅为 `-`，才会读取标准输入；读到 EOF 后将完整文本作为任务，保留尾换行。给了普通位置参数时不会读取或自动拼接管道内容。空白位置参数、空管道会被拒绝；`-` 与其他任务词混用也会失败。交互终端上省略任务是用法错误。单独 `-` 读取终端时需要结束输入，不能当成会逐行执行的交互聊天。

“不要调用工具”只是任务文字，不是权限限制。上面是 POSIX 风格 shell 示例，不声称原样适用于 Windows cmd。

### 用 --json 获取运行事件

```bash
npx @deepseek-ai/dsh@0.1.6-alpha.1 --profile headless --json "只回答 OK，不调用工具" > run.jsonl 2> diagnostic.log
task_exit=$?
printf 'exit=%s\n' "$task_exit"
```

stdout 改为逐行 JSON，而非最终答案文本；stderr 保留诊断。正常进入运行器时先有 `session` 事件，其 `sessionId` 是后续续接要保存的精确 ID。`text` 和 `thinking` 来自已提交步骤，不是逐 token 流；中间还可能有 `status`、`tool_call` 和 `tool_result`。`final.text` 保存本次最终文本，但 **出现 final 不等于任务成功**：轮次内失败仍可输出 final，须结合进程退出码与 `status` 的 `turn_end` 原因。

运行器外失败可能输出 `error` 而没有 `final`；加载失败发生在运行器之前时，可能只有 stderr。不要把“没有 final”统一判定为网络错误。除终止 final 外，事件存在截断限制，JSON 投影也会省略未建模事件，因此 `run.jsonl` 不能替代完整 Session 备份。输出可能含任务、推理与工具信息，不自动上传公共 CI 产物。

### 用 --session-id 继续已有会话

从上一次 `session` 事件取得精确 `sessionId`，回到同一工作目录，并使用能访问该持久化数据的原 Profile/数据根；将占位符替换后再执行：

```bash
npx @deepseek-ai/dsh@0.1.6-alpha.1 --profile headless --session-id "替换为实际sessionId" --json "继续上一项任务，只回答简短总结"
```

未知 ID 会失败，不会自动创建空会话。续接要求已组合 Session 查询与持久化服务；记录的 cwd 不匹配或缺失、子 Agent/fork 会话、记录了该运行器不组合的 preset、preset 记录畸形，以及本进程内已有存活 Agent 持有的 ID，都会被拒绝。不要通过改会话 header 绕过检查，也不要让另一个进程同时驱动同一份会话。

每次调用仍只运行一个任务；续接不是保持终端里的多轮交互。旧格式会话是否可读取还受迁移规则约束，不承诺任意 Web 会话或旧版本数据都能续接。无界面不等于自动批准，不把 rc.1 沙箱说明当作对新版所有工具的运行验收；评估前按[升级与备份](/tutorials/dsh-update-uninstall/)和[权限指南](/tutorials/dsh-permissions-sandbox/)核对环境。

依据：[固定 Headless 文档](https://github.com/deepseek-ai/deepseek-harness/blob/0a15e36e7f82b6ed45af6fa9759f29b40dcd965d/packages/bundle/headless/README.zh.md)、[参数解析](https://github.com/deepseek-ai/deepseek-harness/blob/0a15e36e7f82b6ed45af6fa9759f29b40dcd965d/packages/bundle/headless/src/startup.ts)、[任务与恢复校验](https://github.com/deepseek-ai/deepseek-harness/blob/0a15e36e7f82b6ed45af6fa9759f29b40dcd965d/packages/bundle/headless/src/index.ts)、[JSON 投影](https://github.com/deepseek-ai/deepseek-harness/blob/0a15e36e7f82b6ed45af6fa9759f29b40dcd965d/packages/bundle/headless/src/json-stream.ts)。同版 CLI 总览尚有“缺任务即错误”的旧概述，本节按上述更具体的参数解析与运行器实现说明 stdin 分支。

## 历史版本补充

以下两段是旧批次的版本变化记录，不替代上方 rc.1 操作约定。

## 0.1.5-rc.1：SDK 与平台修复范围

[本次发行说明](https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.5-rc.1)汇总了旧 rc.1 以来的 SDK 变化，包括 Python 单文件 runtime 不再把 Bash 中以 `node` 开头的命令错误重写为 DSH runtime、Windows SDK 启动崩溃修复，以及 macOS x64 runtime wheel。不能把所有汇总项都称为 alpha.2 之后新增。

先确认使用的是 npm CLI 还是 Python SDK、平台与架构、实际运行版本，再选择对应排障路径。完整 SDK、Headless、ACP 的文件工具与 minimal 分开核对；只有持久 shell 也可以写文件，仍不等于只读。本站未执行 SDK 安装和上述故障复现，不提供未经验证的 wheel 安装命令。

## 0.1.5-alpha.2：minimal 默认只有持久 shell

本节仅适用 `0.1.5-alpha.2`：Web `minimal` 与 Python `sdk-minimal` 默认只提供持久 shell，`str_replace_editor` 改为显式启用。完整 SDK、Headless、ACP 的工具集合不能直接套用 minimal 的说明，后文历史示例仍保留各自版本范围。

固定 `sdk-minimal` 文档说明它不继承 `dsh-base`，使用平台对应的 Bash 或 PowerShell，并省略 Web、settings、托管凭据、文件系统工具与 subagent 等层。**工具少不等于只读**：其 danger-full-access 策略允许 shell 修改进程可访问路径，因此只能在隔离工作区评估。

若任务依赖独立编辑工具，先核对实际 Profile 的工具清单与配置，再明确启用；不要因为旧提示词出现工具名就认为工具存在。本页不提供未经本批运行验证的 patch 命令。持久 Bash 的完成和超时状态也应分别检查，不能只看最后一段文本。

来源：[固定 sdk-minimal 文档](https://github.com/deepseek-ai/deepseek-harness/blob/b2e3b2a0125854567a4a5fcba75782e42fe84901/packages/bundle/sdk-minimal/README.zh.md)、[发行说明](https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.5-alpha.2)。本节为源码与文档审阅，未运行 SDK 或 shell 任务；升级选择见[alpha.2 专题](/tutorials/deepseek-harness-0-1-5-alpha-2/)。

### alpha.4 起，Headless 默认可见 web_fetch

在 `0.1.2-alpha.4` 的固定组合中，完整 Python SDK、Headless、ACP 和只使用 `dsh-base` 的自定义 Profile 默认继承 `web_search` 与 `web_fetch`；不使用 base 的 `sdk-minimal` 不在此范围。这个变化不会改变 stdout、stderr 和退出码的职责，却会扩大模型默认可见的公网工具集合。

官方实现只接受经过验证的公开 `http:`、`https:` 目的地址，但抓取不经过 shell 或文件系统审批 preset，也不需要逐次文件审批。公开地址校验并不能阻止任务内容被发送到公网。受限部署应重新检查 Profile 的 `tool-web` 配置、敏感 URL、签名链接、内网地址、任务输入和日志脱敏，必要时在组合层显式关闭抓取。

“工具可见”不等于所有网址都会成功，也不代表模型一定调用它。本文没有运行 alpha.4 或 alpha.5 的真实网络任务；版本范围、Web PTC 工具变化与升级判断见[alpha.5 更新说明](/tutorials/deepseek-harness-0-1-2-alpha-5/)，底层文件与网络权限继续按[DSH 权限与沙箱指南](/tutorials/dsh-permissions-sandbox/)核对。


## 0.1.3-alpha.2 的默认工具变化怎样影响本文？

2026-09-07 的官方发布说明将 SDK、Headless、ACP 的默认工具补充为可用 `read`、`write`、`edit`；同一说明保留 Web minimal 和 SDK minimal 的精简定位。这是 **0.1.3-alpha.2 的版本变化**，不能反推更早的 `0.1.1-rc.2` 工具组成，也不能据此认为 Headless 只读。[alpha.2 官方发布说明](https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.3-alpha.2)

本节记录 `0.1.3-alpha.2` 的历史变化；本文当前操作命令以首屏标明的 `0.1.5-rc.1` 为准。本站未执行真实模型调用或 CI 任务验证。需要评估新版时，先按[版本选择与更新指南](/tutorials/dsh-update-uninstall/)核对目标版本，在隔离副本重新确认默认工具、权限、退出码和 Session 行为。

## 原始来源

- https://github.com/deepseek-ai/deepseek-harness/blob/0a15e36e7f82b6ed45af6fa9759f29b40dcd965d/packages/bundle/headless/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/0a15e36e7f82b6ed45af6fa9759f29b40dcd965d/packages/bundle/headless/src/startup.ts
- https://github.com/deepseek-ai/deepseek-harness/blob/0a15e36e7f82b6ed45af6fa9759f29b40dcd965d/packages/bundle/headless/src/index.ts
- https://github.com/deepseek-ai/deepseek-harness/blob/0a15e36e7f82b6ed45af6fa9759f29b40dcd965d/packages/bundle/headless/src/json-stream.ts
- https://github.com/deepseek-ai/deepseek-harness/blob/183f08e9c6dde7e36cd2318eaee70b0da08fb35e/apps/cli/reference/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/183f08e9c6dde7e36cd2318eaee70b0da08fb35e/packages/bundle/headless/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/183f08e9c6dde7e36cd2318eaee70b0da08fb35e/packages/bundle/headless/src/index.ts
- https://github.com/deepseek-ai/deepseek-harness/blob/183f08e9c6dde7e36cd2318eaee70b0da08fb35e/packages/bundle/headless/src/startup.ts
- https://github.com/deepseek-ai/deepseek-harness/blob/183f08e9c6dde7e36cd2318eaee70b0da08fb35e/packages/bundle/headless/cordis.patch.yml
- https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.5-rc.1
- https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.5-alpha.2
- https://github.com/deepseek-ai/deepseek-harness/blob/b2e3b2a0125854567a4a5fcba75782e42fe84901/packages/bundle/sdk-minimal/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.3-alpha.2
- 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
- https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.2-alpha.4
- https://github.com/deepseek-ai/deepseek-harness/blob/4e84901e6471b79ec0338099867ebb4606d12bb5/.agents/notes/implemented/feature/2026-09-01-shared-base-web-fetch-default.zh.md