Introduction

DeepSeek Harness (DSH)’s default headless-startup plugin usually requires declaring tasks in a configuration file or running it with fixed command-line arguments. This limits “one-off” task execution scenarios in CI pipelines or ephemeral sessions. dsh-exec-extension provides a bundle that allows developers to inject tasks and configurations directly via the CLI, without persisting settings.yaml to disk.

Plugin Purpose

The plugin is maintained by LvDAO and complies with the interface specifications of official surface plugins (including dsh.bundle.patch, parseCmdline, and commander). It overrides headless-startup, disables the default [task...] declaration, and inserts replacement logic. This enables headless-runner to receive context such as headlessStartup.task via CLI arguments without modifying the existing code.

Installation and Activation

Before installation, ensure that DSH CLI is installed and use the same latest npm channel as the CLI. Since the latest tag of @deepseek-ai/dsh-headless may lag, the installation command must first obtain the current version of the 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

If network access is restricted, installation via a Git repository is supported:

dsh plugin --profile exec add github:LvDAO/dsh-exec-extension

Core Features

The plugin packages the capabilities required for a one-shot execution into the CLI, primarily providing the following features:

  • Task input methods: supports direct arguments, piped input (stdin merged into the prompt), or file attachment (@file / -f).
  • Session streaming output: use --format json or --mode json to obtain a JSONL stream of session events.
  • Runtime configuration: supports setting the working directory with --dir, and passing it via parameters such as --cwd / --cd.
  • Model and tool overrides: supports in-process model override (Rust WASM) without writing configuration files; supports switching tool display mode via --tools-mode (native/code/both).
  • Output constraints: provides --output-schema to constrain JSON Schema at the prompt level, but note that this is not a decoding-level constraint.
  • Security and permissions: provides sandbox modes (read-only / workspace-write / danger-full-access) and approval policies (ask / never / allow).

Typical Usage

The basic invocation format is as follows:

dsh --profile exec [options] [--] [task|-]

Examples:

# 直接传递任务字符串
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"

Notes and Limitations

When using the plugin, note the following points:

  1. Permission mode: the --yolo parameter is only for skipping permission prompts (automatic allowance); it does not automatically enable full access. If full access is required, you must explicitly use --sandbox danger-full-access.
  2. Nature of output constraints: --output-schema is a prompt-level constraint intended to guide the model to output content conforming to the Schema, rather than imposing a decoding-level constraint.
  3. Unknown flags: the CLI may report errors for unknown flags.
  4. Out-of-scope features: The plugin does not include the following features: MCP, Host, HTTP protocol, session resumption, --image image input, or forking a headless-runner process. These capabilities must be implemented via profile patches or process environment variables.

Summary

dsh-exec-extension is suitable for scenarios where the DeepSeek model needs to be invoked quickly from the command line to handle specific tasks (such as code analysis or text summarization). Through its plugin mechanism, it extends the flexibility of the CLI without modifying the core code of headless-runner.