前言¶
在 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 兼容接口进行独立部署。
