pilot-harness/packages/bundle/headless

240Star13Fork16Issue1Watching

DSH 一次性任务执行组合包，跳过 Web 与浏览器，直接在命令行跑一次 Agent 并退出。

op7418op7418
·op7418/pilot-harness.git
语言
TypeScript
License
MIT
分支
main
ai-agentcodepilotdeepseekdeepseek-harnessdesktop-appdshdsh-pluginelectron

安装

$ dsh plugin --profile web add github:op7418/pilot-harness/packages/bundle/headless

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

一句话定位

dsh 的一次性任务组合包：在不启动 Web 界面或浏览器的前提下，从命令行接收一条任务文本，跑完一个 Agent 后把答案打到 stdout 并退出。

核心能力

  • 在命令行一次性执行任务，无需打开 Web 界面或浏览器
  • 自动创建一个持久化 Agent，把命令行任务作为用户消息提交，等 Agent 进入空闲后退出
  • 退出前调用 sessions.flush 把本次会话持久化，并把最后一条非空 Assistant 文本写入 stdout
  • 用退出码反馈结果：最终 turn 以"completed"收尾时退出码 0，其他情况（含错误、中止、空白 turn）退出码 1
  • 不打开任何监听端口，纯进程级执行，适合 CI、脚本、定时任务等自动化场景
  • 启动阶段缺少任务文本会被拒绝，提示用法并以非零码退出，避免空跑

技术实现

  • 语言: TypeScript（ESM，"type": "module"）
  • 关键依赖: @deepseek-ai/cordis（插件框架）、@deepseek-ai/dsh-agent（Agent 与 Inbox）、@deepseek-ai/dsh-session（持久化会话）、commander（命令行解析）
  • 架构模式: cordis 命名导出函数插件（name/inject/Config/apply），与 headless-startup、headless-invariant 三个同名插件一起被 cordis.patch.yml 注入到 dsh-base 之上；runner 通过 Cordis 上下文获取宿主服务（agentDefaultModel、agents、sessions），再经宿主提供的 appExit 钩子退出
  • 入口文件: src/index.ts（runner）、src/startup.ts（命令行提供方）、src/invariant.ts（不变量伴生插件）

适用场景

想在 CI、脚本或定时任务里直接跑一次 AI 任务、不愿意或不能开 Web 控制台时，这个组合包最合适。它只读取命令行参数、跑完一个 Agent、把答案打到 stdout、用退出码告诉调用方成败。 也可以作为 dsh 自身最小可用 Agent 调用栈的参考——一次性 runner + Code Mode worker + base 工具栈，足以理解 Cordis 插件如何在不挂载 Web 的情况下驱动一次完整对话。

前置依赖与兼容性

依赖最低版本说明
DSH0.1.0-rc.7+依赖工作区内的 dsh-base、dsh-agent、dsh-session、dsh-llm、dsh-invariants、dsh-cmdline、dsh-agent-default-model、dsh-code-runtime-worker-thread 等包；这些 peerDependencies 全部以 workspace:^ 形式声明
Node.js^22.19.0 || >=24.0.0monorepo 根 package.json 中 engines 字段的要求；bundle 自身未单独声明
平台跨平台全部为 Node.js 进程级逻辑，无系统调用或原生绑定
原生模块无依赖全部为纯 JS/TS，没有 node-pty、node:sqlite 等原生依赖

安装方式

dsh plugin --profile web add github:op7418/pilot-harness/packages/bundle/headless

安装后通过 dsh --profile headless "你的任务" 调用本组合包。

配置项

配置类型说明默认值
task字符串（必填）要让 Agent 执行的单次任务文本；命令行上多个词会以空格拼接无

该字段由 cordis.patch.yml 中的 headless-startup 插件在解析命令行后通过惰性配置注入，runner 自身不直接接受 Cordis 配置。

常见问题

Q: 任务可以多轮对话吗？

A: 不可以。runner 只把命令行参数作为一条用户消息提交给 Agent，等 Agent 处理完一个 turn 后就退出，没有追问或继续对话的入口。

Q: 退出码如何判断成败？

A: 退出码 0 表示最终 turn 以"completed"收尾；其他情况（含中止、模型报错、没有 turn 发生）均为 1，方便脚本与 CI 直接判断。

Q: 答非所问或模型报错时输出在哪？

A: 最后一条非空 Assistant 文本写到 stdout；模型报错的错误码和消息以"dsh: CODE: message"格式写到 stderr；正常情况下 stderr 为空。

Q: 不传任务文本会怎样？

A: 启动器在解析阶段就会拒绝，提示"a task is required"并以退出码 1 退出，runner 不会被激活，整个进程不进入 Agent 创建流程。

Q: 会打开端口吗？

A: 不会。这个组合包不挂载 Host、HTTP server 或 Web runtime，进程不监听任何端口，适合在容器或受限网络环境下运行。

Q: 怎么卸载？

A: 在当初安装时使用的 profile 下执行 dsh plugin --profile web remove github:op7418/pilot-harness/packages/bundle/headless 即可。

Q: 这个组合包会修改模型提示词吗？

A: 会。它的 cordis 补丁把 system-prompt 的人格改为"You are a coding agent powered by the {{model}} model"，并把当前工作目录注入到 persona。

Q: 数据存在哪？

A: 退出前会调用 sessions.flush 把这次会话持久化到宿主配置的 Session 存储，具体路径由 DSH 启动器和 Session 插件决定，本组合包不另设本地文件。

上手难度

入门 — 调用方式只有 dsh --profile headless "你的任务" 一个命令，没有 UI、配置文件或额外参数，普通用户复制一行命令就能跑起来。

已知问题与限制

  • 只支持一次提交：runner 没有交互式追问入口，提交完一条任务就等待退出，不支持多轮 follow-up。
  • 依赖宿主提供 ctx.appExit 钩子：在没有提供该钩子的宿主环境启动 headless profile 时，激活阶段会抛出"the launcher must provide ctx.appExit before the tree mounts"并失败。
  • 不挂载 Web 工具栈：没有 Host、HTTP、Web runtime 或浏览器插件，无法复用 Web 形态下的任何交互能力（如审批、文件浏览器、扩展 UI）。
  • 未发现 TODO/FIXME 注释：源码中暂无未解决的开发标记。
返回插件目录
pilot-harness/packages/bundle/headless — DeepSeek Harness 插件 | deepseek-plugin.org