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

先看结论

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

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

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 指南中的 Web 模式。不要把“没有 Web UI”理解成“无状态”“没有工具”或“没有安全风险”。

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

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

node --version
npx --version

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

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

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

在测试目录中执行：

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：

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

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

一次任务的数据怎样流动

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

命令行任务
→ 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 架构解析。

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

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

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

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

echo $?

在 PowerShell 中查看：

$LASTEXITCODE

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

权限和审批边界

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

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 中文入门完成 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 都能完成任务。

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