前言¶
在 DeepSeek Harness (DSH) 中，純文本模型無法通過原生附件通道接收圖片，DSH 會直接拒絕包含圖片的消息。工程上的通用做法是傳遞文件路徑，由一個獨立的工具負責讀取並分析文件。dsh-codex-media 正是這一鏈條中的“分析端”工具。它只負責讀取路徑，不包含上傳邏輯，因此可以與 dsh-drop-to-path 配合使用，讓文本模型也能處理圖片和文檔。
插件簡介¶
該插件提供圖像和文檔分析能力，由本地 OpenAI Codex CLI 驅動，不依賴第三方運行時庫（僅使用 Node.js 22+ 內置特性）。
核心功能：
- analyze_image：對本地圖片進行描述或回答問題（支持 PNG, JPEG, WebP, GIF）。通過 codex exec --image 原生掛載圖片。
- analyze_document：分析本地文檔（PDF, Office, RTF 或文本格式）或回答針對性問題。模型僅返回答案，避免將提取的文本填充到 Agent 的上下文中。
- generate_image：根據文本提示生成圖片並保存到本地文件。默認使用 Hermes Agent One-shot 模式（無需 API Key），也支持 OpenAI Images API。
安裝與依賴¶
安裝前需滿足以下條件：
- Node.js >= 22
- 依賴插件 dsh-drop-to-path（MIT 許可證），該插件負責處理文件的上傳和路徑生成。
安裝步驟：
- 先安裝上傳依賴：
dsh plugin --profile web add github:loudMore/dsh-drop-to-path
- 再安裝分析工具：
dsh plugin --profile web add github:binsarjr/dsh-codex-media
- 重啓
dsh web並刷新頁面。
核心功能與傳輸方式¶
插件通過多種傳輸方式調用底層的 Codex 引擎。
支持的傳輸方式：
- cli（默認用於分析）：啓動 codex exec --json，解析 JSONL 流。依賴 Codex CLI 的認證（ChatGPT 登錄或 OPENAI_API_KEY）。
- hermes（默認用於生成）：啓動 hermes -z。依賴 Hermes Agent 的認證，可使用 ChatGPT 登錄，無需 API Key。
- api-compatible：直接調用 HTTP chat/completions 接口，文件以 base64 編碼發送。需配置 CODEX_ANALYSIS_API_KEY 和 CODEX_ANALYSIS_BASE_URL。
- api-responses：調用官方 OpenAI Responses API，支持 input_file 和 input_image。需配置相應的 API Key 和 Base URL。
配置與使用示例¶
插件在運行時通過環境變量控制行爲。
關鍵環境變量：
- CODEX_ANALYSIS_TRANSPORT：傳輸方式，默認 cli。
- CODEX_ANALYSIS_API_KEY / CODEX_ANALYSIS_BASE_URL：HTTP 傳輸所需的密鑰和地址。
- CODEX_ANALYSIS_IMAGE_MODELS / CODEX_ANALYSIS_DOCUMENT_MODELS：視覺模型和文檔模型的回退順序。
本地測試示例：
在項目目錄下執行以下命令驗證功能：
npm run smoke:image # 測試圖片分析
npm run smoke:document # 測試文檔分析
npm run smoke:generate # 測試圖片生成
注意事項¶
- 權限與安全：插件以當前 DSH 進程的權限運行。每次調用前都會進行嚴格驗證，包括檢查路徑非空、擴展名白名單、文件大小限制以及 PDF 的魔數簽名。
- 依賴關係：插件本身不包含上傳代碼，必須配合
dsh-drop-to-path使用。 - 代碼審查：作爲開源插件，安裝前建議查閱源碼與許可證（MIT）。
總結¶
dsh-codex-media 將本地 Codex 能力封裝爲 DSH 工具，解決了文本模型無法直接處理多媒體的問題。通過配置不同的傳輸方式，開發者可以在無需 API Key 的情況下使用 CLI/Hermes，或直接對接 OpenAI 兼容接口進行獨立部署。
