无头模式与脚本化运行
本教程共 32 篇 · 第 5 篇 · 更新于 2026-08-15 · 约 5 分钟阅读
本节目标：学会用 headless 模式跑一次性任务，把 dsh 接进脚本和 CI。学完你能写出一条「跑任务 → 看退出码」的自动化命令。
什么是无头模式
Headless 直译是「无头」——没有界面。dsh 的 headless Profile 把整个交互压缩成三步：给一句任务、等它跑完、拿最终答案。
一条命令长这样：
npx @deepseek-ai/dsh --profile headless "run the tests"任务文本是位置参数，直接跟在 Profile 后面，用引号包起来。中文任务同样支持：
npx @deepseek-ai/dsh --profile headless "总结当前目录的项目结构"headless Profile 和 web Profile 一样，首次使用会从内置模板自动初始化。
Note无头模式不是「简化版脚本」。它启动的是同一套完整 Agent 运行时：照样组合插件树、创建 Agent、写会话日志、落盘持久化。它只是省略了 Web 宿主、HTTP 服务和浏览器客户端，不监听任何端口（来源：官方 CLI 参考）。
一次任务发生了什么
官方 CLI 参考描述了完整的执行流程：
- 通过核心注册表创建一个全新的、持久化的 Agent 会话
- 提交任务文本
- 等待 Agent 完全停稳（所有步骤、工具调用结束）
- 对会话执行 flush，把事件落盘
- 从持久化事件区间推导最后一个非空 assistant 文本和最终结束原因
- 最终答案打印到 stdout；结束原因是
completed就退出 0，否则退出 1
成功运行时，stderr 不输出任何内容，也不打开监听端口。这条纪律让 headless 特别适合管道和日志采集。
输出与退出码
输出契约简单清晰：
| 通道 | 内容 |
|---|---|
| stdout | 最终答案（干净文本，适合直接存文件或喂给下一个命令） |
| stderr | 错误信息（模型错误、配置错误等） |
| 退出码 0 | 任务正常完成（completed） |
| 退出码 1 | 任务未正常完成（模型报错等） |
在脚本里判断成功与否，看退出码就够了：
if npx @deepseek-ai/dsh --profile headless "run the tests" > result.txt; then
echo "任务完成，答案已保存到 result.txt"
else
echo "任务失败，退出码 $?"
fiTip想在 CI 里把 Agent 当「自动化同事」用，这个模式最合适：提交代码后自动跑测试、生成变更说明、检查文档完整性，都能用一条命令挂进流水线。
非交互与权限
headless 没有界面，自然也没有弹窗审批。那 Agent 执行写操作时谁来把关？
权限由权限预设决定。新会话默认使用 workspace-write 预设：Bash 和文件系统修改被限制在会话工作区与平台临时目录内，读取、网络访问不受限。预设表里还有更严格的配置和全开放配置（如 danger-full-access，谨慎使用）。
环境变量 DSH_PERMISSION_MODE 可以改变进程级默认预设。更细的权限体系（沙箱模式、审批策略、权限预设）在第 16 章展开。
Warning无头模式不会弹窗问你「同不同意」。任务一旦发出就会自己执行。跑自动化任务前，先想清楚工作区目录和权限预设，别在重要目录里裸跑。
适用场景
适合无头模式的地方：
- CI 流水线：代码提交后自动跑测试或生成报告
- 批量任务：循环处理多个目录、多个仓库
- 定时任务：配合 cron 或任务计划程序定时执行
- 嵌入程序：在 Python、Node 脚本里调用，拿到文本结果继续处理
- 远程/后台执行：SSH 到服务器跑任务，不需要图形界面
不适合的场景：需要逐步确认的复杂任务、需要人工中途干预的长交互。这类任务用 Web 界面更合适。
与 Web 模式对比
| 对比项 | headless | web |
|---|---|---|
| 界面 | 无，纯命令行 | 完整 Web UI |
| 交互方式 | 一次性任务，跑完退出 | 持续会话，随时追问 |
| 输出 | stdout 最终答案 + 退出码 | 界面流式输出、轨迹回放 |
| 审批 | 无弹窗，靠权限预设 | 超权限操作弹窗确认 |
| 端口 | 不监听任何端口 | 默认 127.0.0.1:3080 |
| 适用 | 自动化、CI、批量 | 日常开发、复杂任务 |
两者共用同一套运行时和会话机制，不是两个产品，只是同一个 Agent 的两种「产品面」。
常见问题
没传任务文本。 headless 的任务参数不能省略，缺了属于用法错误，非零退出。
任务失败但不知道原因。 退出码 1 时看 stderr，模型错误、Key 没配、网络不通都会写在那里。
任务跑很久没结束。 任务复杂度高或模型配置不当。想中断按 Ctrl+C，会走优雅排空流程（退出码 130）。
想给任务加配置。 用第 4 章的 --patch 覆盖层，和 web 模式完全一样：
npx @deepseek-ai/dsh --profile headless --patch ./ci.cordis.yml "run the tests"小结
无头模式把 Agent 变成了一个「可编程的命令」：任务文本进，最终答案出，退出码告诉你成没成。它和 Web 模式共享同一套运行时，只是省掉了界面。
到这里，「认识与上手」部分结束。你已经能安装、启动、对话、跑脚本。下一部分进入核心概念，先看看 dsh 的底座 Cordis 到底是什么。