# dsh-codex-connect

> Optional image capability for Codex Connect: allows models to call GPT Image to generate images, and provides a view_image tool to read local and public network images.

## Metadata

- Author: [@franksong2702](https://github.com/franksong2702)
- Repo: <https://github.com/franksong2702/dsh-codex-connect.git>
- GitHub: [franksong2702/dsh-codex-connect](https://github.com/franksong2702/dsh-codex-connect)
- Stars: 34
- Language: TypeScript
- License: [Apache-2.0](https://spdx.org/licenses/Apache-2.0.html)
- Homepage: <https://www.npmjs.com/package/dsh-codex-connect>
- Topics: `chatgpt`, `codex`, `deepseek-harness`, `dsh`, `dsh-plugin`, `gpt-image-2`, `oauth`
- Forks: 7
- Open Issues: 2
- Last push: 2026-08-20T16:01:18.000Z
- Added: 2026-08-20T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:franksong2702/dsh-codex-connect/packages/images
```

## Wiki

## 一句话定位
Codex Connect 在原有的 ChatGPT OAuth 与 Codex 模型之外，额外提供两项可选图片能力：让对话模型用自然语言 prompt 调用 GPT Image 生成图片，并提供 `view_image` 工具读取本地或公网图片。

## 核心能力
- 按 prompt 生成图片：把文字描述直接发送给 Codex 图片端点，生成结果以 DSH 附件形式落库并在对话里直接预览
- 读取本地图片文件：`view_image` 通过 Harness 文件系统读取绝对或相对路径图片，并把像素与媒体类型送给视觉模型
- 读取公网图片 URL：远程 `view_image` 仅允许公开 HTTP(S) 目标，并校验 DNS、阻止私网与云元数据
- 与 Codex OAuth 共享同一套登录：图片生成直接复用插件已有的 ChatGPT 凭据，不引入第二套认证
- 关闭能力后历史图片仍可回放：浏览器侧的图片结果视图与开关解耦，旧会话里的生成结果照常显示
- 出现 OAuth 失效、配额耗尽、网络中断等失败时，工具会返回固定、脱敏的文案，不会泄露响应正文

## 技术实现
- **语言**: TypeScript（Node.js 22+）
- **关键依赖**: `@deepseek-ai/cordis`、`@deepseek-ai/dsh-tools`、`@deepseek-ai/dsh-attachment`、`@earendil-works/pi-ai`
- **架构模式**: 在主插件 fiber 里注册 Cordis 服务 `openaiCodexTransport`，图片生成工具通过 `ctx.reflect.get` 拿到 transport 服务后再发起请求；`view_image` 工具与图片生成工具分别由独立的子 fiber 注入，关闭能力即 dispose 对应 fiber
- **入口文件**: `src/index.ts`（Host）、`src/client/index.tsx`（Web 设置与图片工具视图）

## 适用场景
想让 Codex 订阅下的对话模型既能读图又能生成图片的普通用户，不需要去申请额外的 OpenAI Platform API Key。场景举例：让 Agent 看一份本地的设计稿 PDF 后生成配图，或在公网调研阶段先 `view_image` 看截图、再用 prompt 直接产出配图。

## 前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| Node.js | ^22.19.0 或 >=24.0.0 | 由 `package.json#engines` 与 `compatibility.json` 共同声明 |
| DSH 插件 API 包 | 0.1.0-rc.7 | 包含 `dsh-agent`、`dsh-llm`、`dsh-tools` 等 13 个包，必须整体对齐升级 |
| `@earendil-works/pi-ai` | 0.82.1 | 与 DSH 插件 API 包作为一个组合一起升级 |
| 平台 | 跨平台 | 插件未声明平台限制 |

## 安装方式
```bash
dsh plugin --profile web add github:franksong2702/dsh-codex-connect/packages/images
```

## 配置项
| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
| `enableImageTool` | boolean | 是否注册 `view_image` 工具，允许模型从已审批的本地路径或公网 URL 读取图片 | `false` |
| `enableImageGeneration` | boolean | 是否注册 `codex_connect_image_generate` 工具，让模型按文字描述生成图片并保存为 DSH 附件 | `false` |
| `enableSearch` | boolean | 是否同时启用 Codex 独立搜索 provider（与图片能力并列的另一可选能力） | `false` |
| `searchModel` | string | 独立搜索使用的模型 id | `gpt-5.6-sol` |
| `searchMode` | enum | 搜索模式：`cached`、`indexed`、`live` | `cached` |
| `searchContextSize` | enum | 搜索上下文规模：`low`、`medium`、`high` | `medium` |
| `searchMaxOutputTokens` | number | 独立搜索响应允许的最大 token 数 | `10000` |

## 常见问题

**Q: 需要先在设置页做什么才能用图片能力？**

A: 先在 Codex Connect 卡片里点 **Sign in with ChatGPT** 完成 OAuth，然后在同一张卡里打开 **启用图片生成**（`enableImageGeneration`）与 **启用 view_image**（`enableImageTool`），点击 **保存更改**。能力关闭不会影响历史图片继续预览。

**Q: 一次能生成几张图？能控制尺寸吗？**

A: 一次 prompt 最多生成 4 张图，且受 DSH attachmentLimits 控制（单张字节、整批字节、像素上限）。插件不接受尺寸、质量、背景、张数或模型参数；输出大小与风格由服务端决定。

**Q: view_image 能读取本地任意路径吗？**

A: 可以，但读取路径要走 Harness 文件系统的审批流程，等同于普通文件读取工具；插件不会绕过权限。远程 source 必须是公网 HTTP(S) URL，且 DNS 与重定向都经过私网/元数据地址拦截。

**Q: 图片生成失败时报错会暴露账户信息吗？**

A: 不会。工具层把所有 transport 错误码映射为固定的本地化文案，不回显 OAuth、账户 id、响应正文或服务端日志；常见文案包括"重新登录""刷新授权""临时不可用，请稍后再试"等。

**Q: 关闭 `enableImageGeneration` 后，旧的图片结果会消失吗？**

A: 不会。工具会被注销、新调用会被拒绝，但图片本身以 DSH 附件形式保留在历史会话里，浏览器侧通过独立的工具视图 slot 继续渲染与下载。

**Q: 安装时 `github:franksong2702/dsh-codex-connect/packages/images` 这个路径有问题吗？**

A: 源码没有 `packages/images` 子目录；该路径按 DSH 插件市场约定用于指向"主包里的图片能力切片"，npm 与 GitHub 安装的实际包仍是根 `package.json` 中的 `dsh-codex-connect`，因此 `dsh plugin ... add github:.../packages/images` 实质等价于安装主包。

## 上手难度
入门 — 安装只需一行命令、设置页勾选两个开关即可启用，不需要写代码或自定义 endpoint。

## 已知问题与限制
- 单次 prompt 字符上限为 32000，超长或空白 prompt 直接拒绝
- 单张图片大小、总批次字节、单张像素上限都由 DSH attachmentLimits 决定，超过任意一项即整体失败，不返回部分结果
- 远程 `view_image` 不支持 localhost、私网、link-local 与云元数据地址；任何 DNS 重定向都会被拦截并拒绝连接
- 图片生成请求 120 秒未返回即视为超时；取消时服务器侧仍可能继续处理，工具会附上"The request may still be processing"提示
- 图片生成在模型调用层以 exclusive 模式运行，一次模型回复内不会并行触发多次生成
- 图片生成结果强依赖 ChatGPT 订阅是否包含 GPT Image 能力，订阅变更或配额耗尽都会让 `enableImageGeneration` 在运行时失效
- 关闭能力不影响历史图片回放，但开启与关闭切换依赖 DSH 0.1.0-rc.7 的 settings 生命周期；DSH rc.6 用户请留在 Alpha 4.9，否则配置 slot 可能不匹配

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [dsh-codex-connect](https://deepseek-plugin.org/plugins/franksong2702/dsh-codex-connect/packages/images)
Wiki generated by AI (model: `MiniMax-M3`)