跳到主内容

headless/harness/packages/bundle/headless

15Star3Fork1Issue0Watching

dsh 一次性任务组合包：在 dsh-base 之上挂上 CLI 启动器与直接驱动，将任务作为普通用户消息提交给 Agent，把最后一条 assistant 文本打到 stdout 后退出

分类⌨ 开发者工具
机审证据5/5方法论数据来源安装命令持续维护DSH 版本风险扫描
机审证据安装命令仓库已核验dsh-plugin Topic许可证READMEAI 百科

ⓘ 此插件是大仓库 WJZ-P/deepseek-harness-desktop 的子包，星数与活跃度统计的是整个仓库。

WJZ-PWJZ-P
·WJZ-P/deepseek-harness-desktop
语言
TypeScript
License
MIT
分支
main
dsh-plugin

安装

命令web profile
$ dsh plugin --profile web add @deepseek-ai/dsh-headless

在终端中运行以上命令，通过 dsh CLI 安装此插件。可在右上角切换 Profile。 第一次用 dsh？看这篇新手教程

对话式安装

帮我安装 DeepSeek Harness 插件 WJZ-P/deepseek-harness-desktop/harness/packages/bundle/headless：先查看仓库 https://github.com/WJZ-P/deepseek-harness-desktop 确认安全性，然后执行安装命令并验证插件加载成功。

把这段指令粘贴给 DSH Web GUI 里的助手，由它代你完成安装与验证。

本文档对应 WJZ-P/deepseek-harness-desktop 仓库中 harness/packages/bundle/headless 子目录，是落地页 /plugins/{owner}/{repo} 中插件百科模块的内容来源。本目录是该桌面发行版内嵌的 dsh 一次性任务 profile 组合包。

一句话定位

@deepseek-ai/dsh-headless 是 DSH 的"一次性任务"profile 组合包，在 dsh-base 之上叠加命令行启动器和一个直接驱动 Agent 的 runner，把一条任务作为普通用户消息提交、等待 agent 跑完后把最后一条 assistant 文本打到 stdout，再按结果请求进程退出（成功 0，其它 1）。

核心能力

  • 把命令行位置参数解析为单次任务文本，提供给 runner 作为启动输入（缺失或空白任务在 runner 激活前就拒绝）
  • 在 dsh-base 之上叠加编程用 persona（You are a coding agent powered by the {{model}} model ...）和工具模式（透传 DSH_TOOLS_MODE）
  • 关闭 HMR 的模块重载副作用，但保留启动器层面的"仅监听 patch 变化"行为，单次运行期间 patch 仍可热更新
  • 把 Code Mode 的 worker-thread 执行器作为核心执行能力挂载（在 patch 中插入 code-runtime 行），不依赖 Web 或浏览器层
  • 直接驱动一个全新持久化 Agent：读取默认模型选择、创建 session、把任务作为 user message 投出、等待 agent 回到 idle，然后 flush 并打印结果

技术实现

  • 语言: TypeScript（ESM，"type": "module"，tsconfig.json 通过 tsconfig.base.json 继承并指定 rootDir: src、outDir: lib/types）
  • 关键依赖: @deepseek-ai/cordis（宿主运行时，peer）、@deepseek-ai/dsh-agent（Agent 生命周期与默认模型装配）、@deepseek-ai/dsh-llm（createUserMessage 工厂）、@deepseek-ai/dsh-session（SessionId 与 sessions.flush）；dependencies 还包含 @deepseek-ai/dsh-cmdline、@deepseek-ai/dsh-code-runtime-worker-thread、@deepseek-ai/schemastery、commander
  • 架构模式: profile 组合包 + 普通 Cordis 插件 — cordis.patch.yml 通过 dsh.bundle.patch 字段暴露给 profile 组合器，在 dsh-base 上追加 4 行（persona、hmr 关闭、tools 模式、insert headless-runner/startup/code-runtime）；runtime 由 3 个普通 Cordis 插件组成：headless-runner（直接驱动）、headless-startup（命令行解析与 headlessStartup 服务提供者）、headless-invariant（空实现以满足 invariant 配套规则）
  • 入口文件: src/index.ts（runner 主驱动）+ src/startup.ts（命令行解析）+ src/invariant.ts（空 invariant 配套）+ 实质载荷 cordis.patch.yml

适用场景

任何需要在脚本/CI/容器里"丢一句话给 DeepSeek Agent，让它跑完就退"的场景：批量执行固定任务、回归测试一次性 prompt、嵌入到别的流水线把 DSH 当成无界面 worker。典型用法是 dsh --profile headless "<任务文本>"，runner 完成任务后立即退出，stdout 给你最终答案，退出码告诉你成功还是出错。

前置依赖与兼容性

依赖最低版本说明
DSH0.1.0-rc.5该包自身版本即为 0.1.0-rc.5；peerDependencies 声明 @deepseek-ai/cordis、@deepseek-ai/dsh-agent、@deepseek-ai/dsh-agent-default-model、@deepseek-ai/dsh-invariants、@deepseek-ai/dsh-llm、@deepseek-ai/dsh-session、@deepseek-ai/cordis-plugin-loader 需在宿主 profile 中由 dsh-base 及上层提供
Node^22.19.0 || >=24.0.0来自 monorepo 根 harness/package.json 的 engines.node；本包未单独声明 engines
平台macOS / Windows / Linuxpatch 自身不依赖平台分支；下层 dsh-base 中的 shell 栈按 process.platform 自动二选一（bash / pwsh），不影响 headless 入口
原生模块无该包未引入原生依赖；Code Mode 的 worker-thread 执行器属于进程内能力

安装方式

dsh plugin --profile web add github:WJZ-P/deepseek-harness-desktop/harness/packages/bundle/headless

配置项

本 bundle 的"配置项"由两部分组成：(1) runner 暴露的 Config.task，由 patch 用 !!js ctx.headlessStartup.task 注入，命令行的位置参数直接成为它；(2) patch 在 dsh-base 之上额外设置的系统级默认值，使用者一般不直接覆盖。如下表：

配置类型说明默认值
task（runner 行）字符串（必填）这次运行要交给 Agent 的单条任务文本。缺失或仅空白时 headless-startup 阶段就会报错，不会激活 runnerctx.headlessStartup.task，即 dsh --profile headless "..." 位置参数
system-prompt.persona（在 dsh-base 上覆盖）字符串把 Agent 的人设声明为"由指定模型驱动的编程 Agent"，并把当前工作目录拼进提示"You are a coding agent powered by the {{model}} model. Your working directory is {{cwd}}."
hmr.disabled（在 dsh-base 上覆盖）布尔关闭共享模块重载 HMR 行；启动器层面的"watch-only patch"热更新仍保留到运行结束true
tools.mode（在 dsh-base 上覆盖）字符串进程级 Code Mode 开关，沿用 Web 表面的同一份环境变量约定process.env.DSH_TOOLS_MODE（未设置时为 undefined，由下层 schema 决定是否启用 Code Mode）

常见问题

Q: 这个 bundle 跑起来会打开本地端口吗？

A: 不会。patch 明确不挂载 Host、HTTP server、Web runtime 或浏览器插件，进程不监听任何端口。

Q: 一定要通过 dsh --profile headless 启动吗？

A: 是。runner 在挂载时强制读取启动器提供的退出钩子（ctx.appExit）；在 dsh 启动器之外以 headless profile 启动会在激活时直接抛错，提示"the launcher must provide ctx.appExit before the tree mounts"。

Q: 可以让 agent 多轮追问或者多轮执行吗？

A: 不可以。runner 一次只提交一条用户消息（agent.followup(createUserMessage(...))），等待 agent 从忙到闲、打印该区间内最后一条非空 assistant 文本后立即请求退出，整个流程没有交互式追问面。

Q: 退出码代表什么？

A: 进程退出码由最后一轮 turn/end 决定：reason.kind === 'completed' → 0，其它情况（包括 error、aborted、或整段区间内根本没有 turn）一律 → 1。runner 失败（创建 Agent 抛错、Loader 还没就绪等）也会走 appExit(1) 并把 message 写到 stderr。

Q: 出错信息会写到哪里？

A: 成功时 stderr 保持空。当轮结束原因为 error 时，dsh: <code>: <message> 写到 stderr；正常运行的最终 assistant 文本写到 stdout，并附一个换行。即使区间内没有可用文本，runner 仍会写一个 \n 占位以保证下游管道不被空 stdout 误判为空结果。

Q: 任务文本从哪来？

A: 来自命令行。headless-startup 通过 commander 解析 dsh --profile headless "<task>" 的位置参数，多个词以空格拼接，并通过 ctx.provide('headlessStartup', { task }) 注入；任务为空或仅空白时直接调用 program.error(...) 退出，根本不会进入 runner。

Q: 想改默认模型或工具模式该动哪里？

A: 工具模式由环境变量 DSH_TOOLS_MODE 控制（patch 用 !!js process.env.DSH_TOOLS_MODE 透传到 tools.mode）；模型沿用 dsh-base 的默认模型选择机制，从 settings.yaml 或 Web 的 Models 页面管理即可，不需要重新打这个 bundle。

上手难度

入门 — 仅需一条 dsh --profile headless "任务文本" 命令即可运行；想换默认工具模式只需设置一个环境变量，无需阅读源码。

已知问题与限制

  • 只提交一个任务：runner 没有用于交互式后续输入的 surface；它会等待 Agent 在返回 idle 前完成的所有工作，并打印该区间内最后一条非空 assistant 消息，多轮对话场景请改用 Web profile
  • ctx.appExit 由启动器持有：在 dsh 启动器之外启动 headless profile 会在激活时明确报错，直到宿主提供该退出请求
  • 模型请求前缀无附加内容：runner 不向请求前缀添加任何东西（KV Cache 影响声明为"无"），但仍受下层 dsh-base 的 persona 与 tools 配置影响

查看使用指南 →

该插件的安装步骤、关键要点、FAQ 与兼容性说明（基于已收录字段派生）。

收录徽章

Listed on deepseek-plugin.org
[![Listed on deepseek-plugin.org](https://img.shields.io/badge/listed_on-deepseek--plugin.org-007EC6)](https://deepseek-plugin.org/plugins/WJZ-P/deepseek-harness-desktop/harness/packages/bundle/headless)

把这段 markdown 粘贴到你的 GitHub README，链接回本插件详情页。徽章只声明已被本站收录，不代表安全认证。

返回插件目录