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

先看结论

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

依据：固定 Headless 说明 ↗（外部链接，在新标签页打开）与运行器实现 ↗（外部链接，在新标签页打开）。退出码表示轮次结束状态，不证明生成的答案正确或用户任务验收通过。

新版管道、续接与 JSON 事件另见0.1.6-alpha.1 差异，不要把新参数加到下方 rc.1 示例中。

如何运行一次性任务

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

npx @deepseek-ai/[email protected] --profile headless "只读取当前目录并概括文件用途，不要修改文件"

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

npx @deepseek-ai/[email protected] --profile headless --help

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

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

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

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

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

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

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

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

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

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

Headless、Web minimal 和 Python SDK 怎样区分

本轮不提供未经核对的 SDK 安装命令或工具启用 patch。依据：rc.1 CLI 与模式说明 ↗（外部链接，在新标签页打开）。

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

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

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

首次验证与故障分流

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

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

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

从标准输入传入任务

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

printf '%s\n' '只回答 OK，不调用工具' | npx @deepseek-ai/[email protected] --profile headless -

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

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

用 --json 获取运行事件

npx @deepseek-ai/[email protected] --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/数据根；将占位符替换后再执行：

npx @deepseek-ai/[email protected] --profile headless --session-id "替换为实际sessionId" --json "继续上一项任务，只回答简短总结"

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

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

依据：固定 Headless 文档 ↗（外部链接，在新标签页打开）、参数解析 ↗（外部链接，在新标签页打开）、任务与恢复校验 ↗（外部链接，在新标签页打开）、JSON 投影 ↗（外部链接，在新标签页打开）。同版 CLI 总览尚有“缺任务即错误”的旧概述，本节按上述更具体的参数解析与运行器实现说明 stdin 分支。

历史版本补充

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

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

本次发行说明 ↗（外部链接，在新标签页打开）汇总了旧 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 文档 ↗（外部链接，在新标签页打开）、发行说明 ↗（外部链接，在新标签页打开）。本节为源码与文档审阅，未运行 SDK 或 shell 任务；升级选择见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 更新说明，底层文件与网络权限继续按DSH 权限与沙箱指南核对。

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 官方发布说明 ↗（外部链接，在新标签页打开）

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