DSH 一次性任务执行组合包，跳过 Web 与浏览器，直接在命令行跑一次 Agent 并退出。
Install
$ dsh plugin --profile web add github:op7418/pilot-harness/packages/bundle/headlessRun the command above in your terminal to install this plugin via the dsh CLI. You can switch Profile in the top-right corner. New to dsh? Read the beginner tutorial
一句话定位
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 的情况下驱动一次完整对话。
前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DSH | 0.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.0 | monorepo 根 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 注释：源码中暂无未解决的开发标记。