跳到主内容

headless/packages/bundle/headless

14Star0Fork0Issue0Watching

dsh 一次性任务组合包：在 dsh-base 上挂载 headless-runner，命令行收一个任务，跑完把最后回复写到 stdout 并退出，无 Web/HTTP 层

分类▣ 界面增强
机审证据5/5方法论数据来源安装命令持续维护DSH 版本风险扫描
机审证据安装命令仓库已核验dsh-plugin Topic许可证READMEAI 百科

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

ayuanwongayuanwong
·ayuanwong/dsh-ux
语言
TypeScript
License
BSD-3-Clause
分支
main
agent-harnessai-agentdeepseek-harnessdeveloper-toolsdshdsh-plugintypescriptweb-ui

安装

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

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

对话式安装

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

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

本文档对应 packages/bundle/headless 子路径，是落地页 /plugins/{owner}/{repo} 中插件百科模块的内容来源。该目录属于 DSH 主仓自带的 profile 组合包层，并非独立插件；安装命令把它作为 headless profile 的整包补足加进 dsh。

一句话定位

@deepseek-ai/dsh-headless 是 DSH 的"一次性任务"profile 组合包：基于 dsh-base 之上挂载 headless-runner 插件，从命令行读一个任务文本、创建一个全新的持久化 Agent、等模型跑完、把最后一条非空 assistant 回复写到 stdout，然后请求启动器退出进程；不挂载任何 Host、HTTP server、Web runtime 或浏览器插件。

核心能力

  • 从命令行接收单个任务文本（多个词自动用空格拼成一个任务），通过 commander 提供 --help 与空任务/纯空白任务校验
  • 创建一个全新的持久化 Agent（带随机 sessionId），将任务作为普通用户消息提交，等 Agent 完全停稳
  • 在所有事件落地后聚合本轮区间内的 assistant 文本，把最后一条非空回复写到 stdout
  • 退出码映射 turn/end 原因：completed → 0，其他（含 aborted）→ 1；error 还会把 code: message 写到 stderr
  • 退出前调用 ctx.sessions.flush 落盘会话日志，再请求 ctx.appExit 终止进程
  • 在 dsh-base 之上挂载 worker-thread 版 code-runtime（Code Mode 作为核心执行能力）、禁用 HMR；不挂载 Host / HTTP / Web / 浏览器

技术实现

  • 语言: TypeScript（ESM）
  • 关键依赖: @deepseek-ai/dsh-cmdline（命令行参数解析 + 退出钩子）、@deepseek-ai/dsh-code-runtime-worker-thread（Code Mode 执行能力）、commander（CLI 子命令定义与解析）、@deepseek-ai/schemastery（Config schema 校验）
  • 架构模式: profile 组合包 + 服务/消费者配对。cordis.patch.yml 通过 manifest 字段 dsh.bundle.patch 暴露给 profile 组合器，组合器读取后向 base 之上注入两条新行：headless-startup（provider，把命令行解析成 headlessStartup 服务）和 headless-runner（consumer，inject headlessStartup，从其 task 字段读取任务文本）
  • 入口文件: src/startup.ts（CLI provider，导出 name = 'headless-startup'）+ src/index.ts（runner，导出 name = 'headless-runner'、apply(ctx, config)）+ src/invariant.ts（空实现的 invariant 配套，仅注册包名）+ cordis.patch.yml（profile 组合器读取的 patch 载荷）

适用场景

适合把 DSH 当成命令行工具嵌进自动化：CI 流水线、cron 任务、批处理脚本等需要"调一次模型、拿一次回复、判断成败"的场景。和 dsh-web-app 不一样，本组合包不打开任何 HTTP/Web 端口、不依赖浏览器，跑完即退出；不需要多轮交互、不需要 Web UI 时用它最省心。

前置依赖与兼容性

依赖最低版本说明
DSH0.0.1-rc.2+自身版本号；需宿主已装好 dsh-base 与同名工作区包（@deepseek-ai/dsh-agent、dsh-llm、dsh-session 等 peerDeps）
Node>=22.19.0来自 monorepo 根 engines.node：^22.19.0 || >=24.0.0
平台macOS / Windows / Linux同一份 patch 在各平台都加载；shell 栈由 dsh-base 内按 process.platform 自动二选一（bash / pwsh）
原生模块无本包无原生模块依赖；Code Mode 由 @deepseek-ai/dsh-code-runtime-worker-thread 提供，走 worker_thread，不引入原生绑定

安装方式

dsh plugin --profile web add github:ayuanwong/deepseek-harness-ux/packages/bundle/headless

注：此命令把包安装到 web profile；如要把它作为独立 profile 触发"一次性任务"语义，请用 dsh --profile headless "任务文本" 调用（这是 DSH 启动器识别组合包 profile 的方式）。

配置项

本组合包对外只暴露一个 config：

配置类型说明默认值
task字符串（必填）这一轮要交给 Agent 的任务文本。普通用户不需要直接填这个字段，它由 headless-startup provider 从命令行位置参数解析并通过 ctx.headlessStartup.task 注入；schema 在 src/index.ts:36-38 声明为必填字符串无（必填）

下面这些是 cordis.patch.yml 在 patch 内声明的底层默认值，普通用户不需要也不应该直接覆盖：

行 ID默认值含义（人话）
system-prompt.config.personaYou are a coding agent powered by the {{model}} model. Your working directory is {{cwd}}.一次性任务的系统人设：编码 agent，模板变量在运行时替换
hmr.disabledtrue关掉模块热替换；watch 模式下仅保留用户 patch 层的热加载
tools.config.modeprocess.env.DSH_TOOLS_MODECode Mode / Function Mode 等工具模式开关，由环境变量 DSH_TOOLS_MODE 控制

常见问题

Q: 这个组合包和 dsh-web-app 有什么区别？

A: dsh-web-app 是浏览器面：挂载 HTTP server、Web runtime 和浏览器插件，可以持续对话；本组合包不开任何端口，只跑一次任务、输出结果、退出进程。脚本化调用选 headless，要 Web UI 选 web-app。

Q: 想在 CI 里调用 dsh 跑一个任务该怎么写？

A: 用 dsh --profile headless "任务内容"，任务结束后进程自动退出；退出码在 turn/end.reason.kind === 'completed' 时为 0、其他情况为 1，shell 流水线里可以直接 if 判断。要捕获最终回复用 stdout 重定向：dsh --profile headless "..." > answer.txt。

Q: 运行时报 must provide ctx.appExit 是什么意思？

A: ctx.appExit 是由 dsh 启动器注入的退出钩子，本包不自带。必须用 dsh --profile headless 启动器跑；如果自己在 Cordis 树里直接挂 headless-runner 而不带启动器，会在 apply 阶段立刻抛错退出。

Q: 怎么控制最终回复写到哪？

A: 写到进程 stdout（process.stdout.write，在 src/index.ts:129）。普通用户用 shell 重定向即可；测试场景下本包把 stdout/stderr 引用挂在 internals 上可被替换（见 tests/headless.spec.ts:55-58）。

Q: 任务跑失败了怎么拿到错误信息？

A: 当 turn/end.reason.kind === 'error' 时，本包会把错误以 dsh: CODE: message 的格式写到 stderr（src/index.ts:131）；stdout 同时输出一个换行占位，进程退出码为 1。

Q: 能把多次调用串起来、像聊天那样来回对话吗？

A: 不能。runner 没有交互式后续输入的 surface（README.md:19-20 明确说明）；每跑一次就是一个新进程。需要多轮对话请用 dsh-web-app 或 dsh-acp。

上手难度

入门 — 装好组合包后只要写一行 dsh --profile headless "任务" 就能跑；要自定义行为只需在自己的 profile cordis.patch.yml 里按 id 覆盖 patch 中已声明的行（headless-runner、headless-startup、system-prompt、hmr、tools）。

已知问题与限制

  • 只提交一个任务：runner 没有交互式后续输入面；它会等待 Agent 在返回 idle 前完成的所有工作，并打印该区间内最后一条非空 assistant 消息。多次对话场景请改用 dsh-web-app 或 dsh-acp（README.md:19）
  • ctx.appExit 由启动器持有：在 dsh 启动器之外启动 headless profile 会在激活时立即报错 headless-runner: the launcher must provide ctx.appExit before the tree mounts，直到宿主提供该退出请求（src/index.ts:144-147、README.md:20）
  • 空任务会被启动器拒绝：命令行没传位置参数或全是空白时，headless-startup 会用 commander 报"a task is required"并以退出码 1 终止，runner 永远不会激活（src/startup.ts:53）

查看使用指南 →

该插件的安装步骤、关键要点、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/ayuanwong/deepseek-harness-ux/packages/bundle/headless)

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

返回插件目录