前言¶
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 的靈活性。
