跳到主内容

headless 使用指南

为 dsh 增加一次性任务 profile：传入一段任务文本运行 Agent 后打印最终答复并退出，适合脚本与 CI 调用。

本文为派生内容（基于 wiki / faq / compatibility_json 自动组装），非 AI 即时创作。

本文由本站基于该插件已收录的字段自动派生（wiki / faq / compatibility_json / readme），非 AI 即时创作。每节末尾标源字段。

快速上手

dshcode — @deepseek-ai/dsh-headless

— 源: plugin_wiki.wiki_content

安装与验证

dsh plugin --profile web add @deepseek-ai/dsh-headless

复制以上命令在 DSH Web Profile 内运行。安装完成后在「插件列表」启用即可。

— 源: plugins.install

关键要点

  • macOS: right-click the app in Finder and choose Open, then confirm in the dialog that appears. Alternatively run xattr -cr /Applications/DSHCode.app once in Terminal.
  • Windows: click More info on the SmartScreen dialog, then Run anyway.
  • LINUX DO — This project is continuously shared and discussed in the LINUX DO community.
  • dsh-genui — Provides the built-in generative UI plugin.
  • dsh-annotation — Provides the built-in selection-annotation workflow.

— 源: plugin_wiki.readme_zh (fallback readme_raw)

常见问题

这个组合包和 dsh-base 有什么区别？

base 把基础工具、模型、持久化等 60+ 能力按"出厂默认集合"全部注入；headless 只在 base 之上叠一层极简驱动层——不挂 Host、HTTP server、Web runtime 或浏览器插件，每一个进程只接一个任务、跑完后打印最终 assistant 文本再退出 0/1。

进程退出码代表什么？

最终 turn 的原因是 completed 时退出 0；aborted 或 error 时退出 1。错误情况下，stderr 会额外输出一行 "dsh: : "，成功时 stderr 为空。

不带任务文本直接跑会怎样？

启动器先打印 usage 错误 "a task is required, for example: dsh --profile headless "run the tests"" 并以 exit 1 结束，runner 在收到服务之前就被拒，不会启动 Agent。

可以在 dsh launcher 之外使用这个 profile 吗？

不可以。runner 必须在挂载前从宿主拿到退出请求服务；launcher 之外启动会在激活时明确抛错 "headless-runner: the launcher must provide ctx.appExit before the tree mounts"。

一个进程里能跑多个任务吗？

不能。每次 dsh --profile headless 调用只提交一个任务并等待返回到 idle，要再跑只能重新启动一个进程。profile 名义上是一个交互后端，实际上是单发任务运行器。

默认的 HMR 和 Code Mode 状态是什么？

HMR 在 headless profile 下被显式禁用，Code Mode 由 DSH_TOOLS_MODE 环境变量控制——值决定是否启用 worker 线程代码执行（与 Web profile 同源）。

会话数据存在哪里？

由 dsh-base 那一层的 session-persistence-jsonl 负责，落到 $DSH_HOME/sessions；headless 自身不另起存储面。

Agent 用什么模型？

跟随 dsh-base 的 agent-default-model 默认值（deepseek-official / deepseek-v4-flash）。要换模型在自己 profile 的 cordis.patch.yml 里按 id 整行覆盖这一行即可。

— 源: plugin_wiki.faq_json

兼容性

  • DSH: 未声明（本包与 dsh 1.0.5 同源发布）
  • Node: >=22.19.0（要求 ^22.19.0 或 >=24.0.0，源自仓库根 engines 字段）
  • Platforms: macOS, Linux, Windows

— 源: plugin_wiki.compatibility_json

踩坑提醒

安装前请审阅上游仓库；本指南基于已收录字段自动派生，可能滞后于最新版本。如发现与官方文档冲突，请以上游为准。

— 来源：通用规则