前言¶
DeepSeek Harness (DSH) 的默认 headless-startup 插件通常要求在配置文件中声明任务，或者通过固定的命令行参数运行。这限制了在 CI 流水线或临时会话中进行“一次性”任务执行的场景。dsh-exec-extension 提供了一个 bundle，旨在让开发者通过 CLI 直接注入任务和配置，无需在磁盘上持久化 settings.yaml。
插件定位¶
该插件由 LvDAO 维护，遵循官方 surface 插件的接口规范（包含 dsh.bundle.patch、parseCmdline 和 commander）。它对 headless-startup 进行了覆盖，禁用了默认的 [task...] 声明，并插入了一个替换逻辑。这使得 headless-runner 能够在不修改原有代码的情况下，通过 CLI 参数接收到 headlessStartup.task 等上下文信息。
安装与启用¶
安装前请确保已安装 DSH CLI，并使用与 CLI 相同的 latest npm 通道。由于 @deepseek-ai/dsh-headless 的 latest 标签可能滞后，安装命令需要先获取 CLI 的当前版本。
dsh plugin --profile exec add @deepseek-ai/dsh-headless@$(npm view @deepseek-ai/dsh version)
dsh plugin --profile exec add dsh-exec-extension
dsh --profile exec --help
如果网络受限，支持通过 Git 仓库安装：
dsh plugin --profile exec add github:LvDAO/dsh-exec-extension
核心功能¶
该插件将一次执行（one-shot exec）所需的能力封装在 CLI 中，主要提供以下特性：
- 任务输入方式：支持直接传参、管道输入（stdin 合并到 prompt）或文件附加（
@file/-f）。 - 会话流式输出：通过
--format json或--mode json可以获取会话事件的 JSONL 流。 - 运行时配置：支持通过
--dir设置工作目录，通过--cwd/--cd等参数传递。 - 模型与工具覆盖：支持进程内模型覆盖（Rust WASM），无需写入配置文件；支持通过
--tools-mode切换工具展示模式（native/code/both）。 - 输出约束：提供
--output-schema用于在 prompt 层面约束 JSON Schema，但注意这不是解码层面的约束。 - 安全与权限：提供沙箱模式（
read-only/workspace-write/danger-full-access）和审批策略（ask/never/allow）。
典型用法¶
基本调用格式如下：
dsh --profile exec [options] [--] [task|-]
示例：
# 直接传递任务字符串
dsh --profile exec "summarize this"
# 通过管道读取 stdin 并合并到 prompt
cat README.md | dsh --profile exec "summarize this"
# 附加文件并使用 CI 自动审批模式
dsh --profile exec @notes.md --full-auto "use the notes"
注意事项与限制¶
在使用过程中需注意以下几点：
- 权限模式：
--yolo参数仅用于跳过权限提示（自动允许），它不会自动开启完全访问权限。如需完全访问，必须显式使用--sandbox danger-full-access。 - 输出约束性质：
--output-schema是 Prompt 级别的约束，旨在引导模型输出符合 Schema 的内容，而非强制解码层面的约束。 - 未知 Flag：CLI 可能会对未知 flags 报错。
- 功能非目标：该插件不包含以下功能：MCP、Host、HTTP 协议、resume 会话、
--image图像输入、以及 forkingheadless-runner进程。这些能力需通过 profile patch 或进程环境变量实现。
总结¶
dsh-exec-extension 适合需要在命令行中快速调用 DeepSeek 模型处理特定任务（如代码分析、文本总结）的场景。它通过插件化机制，在不修改 headless-runner 核心代码的前提下，扩展了 CLI 的灵活性。
