codex-image-generation 0.3.0__tar.gz

codex_image_generation-0.3.0/.python-version

@@ -0,0 +1 @@
+3.11

codex_image_generation-0.3.0/CHANGELOG.md

@@ -0,0 +1,25 @@
+# 更新记录
+
+## 0.3.0 — 2026-11-01
+
+- 项目、发行包和启动命令统一命名为 `codex-image-generation`，Python 模块使用 `codex_image_generation`。
+- 作者署名更新为 TangRuoJie，采用 MIT 许可证，并在分发包中包含许可证。
+- 增加贡献指南、安全报告渠道、问题/PR 模板，以及通过检查后创建 Release 草稿的手动工作流。
+- 提供 wheel、源码包及带安装说明和校验和的 ZIP 本地发布流程。
+- 推荐用 `uv tool install` 安装到独立环境，使用者无需保留项目源码目录。
+- 增加安装后从其他目录启动的验证，覆盖 CLI、配置输出和 MCP stdio。
+- CLI 配置输出使用 UTF-8，兼容非 UTF-8 环境中的中文和 emoji 路径。
+- 统一文件名锁的大小写和 Unicode 归一化，减少不同文件系统上的同名并发冲突。
+- 重写安装与接入说明，拆分工具参考、发布流程及通用本地 wheel 启动示例。
+- 明确模型上下文、图片格式、预览、跨平台依赖和首次联网安装的边界。
+
+## 0.2.0
+
+- 公开工具收敛为 `generate_image`，本地配置诊断使用 `--check`。
+- `project_dir` 改为 `cwd`，默认直接保存到当前任务目录。
+- 复用已有 Codex provider 的 URL 与凭据，不再使用独立 URL/Key 覆盖设置。
+- 对话模型来自可靠调用上下文或已有 Codex 配置；移除独立图像模型配置和硬编码兜底。
+- 支持 PNG/JPEG/WebP、参考图、蒙版、历史图像引用和可选流式中间预览。
+- 保留部分失败中的成功原图，输出路径、模型来源、ID、用量及警告。
+
+从旧版升级时，应使用新版 `--print-config` 重新生成接入配置。旧的 `--responses-model`、`--image-model` 等启动设置不再适用。

codex_image_generation-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,43 @@
+# 参与贡献
+
+欢迎修复问题、改善文档和补充跨平台验证。较大的功能变更建议先在仓库 Issues 中说明使用场景与预期行为；每个 PR 尽量只解决一个问题。
+
+## 准备开发环境
+
+需要 Python 3.11+ 和 [uv](https://docs.astral.sh/uv/getting-started/installation/)。在源码根目录执行：
+
+```sh
+uv sync --locked
+uv run --locked python -B -m unittest discover -s tests -v
+```
+
+依赖安装可能联网；现有测试使用假凭据、临时文件和模拟上游，不调用真实图像 API。修改依赖时更新 `pyproject.toml`，执行 `uv lock`，一并提交 `uv.lock`。
+
+## 修改原则
+
+- 保持唯一公开工具 `generate_image` 的使用流程：描述图片，由调用方提供当前任务的绝对 `cwd`，默认保存到该目录。
+- URL 和凭据复用所选 Codex provider。不要另建 `api_key`、`base_url` 或 `image_model` 工具参数；请求不发送 `tools[].model`。
+- `current_model` 仅来自可靠的调用上下文，否则使用已有配置中的模型；不要猜测会话型号或增加硬编码兜底。
+- 已有文件不覆盖，部分失败保留成功原图。超时或断流后不要自动重复付费生成。
+- 行为修复应有能复现问题的测试。文档、排版等改动无需为了覆盖行数添加测试。
+- 涉及路径、文件保存或子进程时，考虑 Windows、macOS 和 Linux，并明确实际验证过的平台。
+
+工具接口和限制见 [工具参考](docs/TOOLS.md)。安装与打包行为变更应同步更新相应文档。
+
+## 打包相关改动
+
+```sh
+uv run --locked python scripts/build_release.py
+uv run --locked python scripts/smoke_wheel.py --wheel dist/codex_image_generation-0.3.0-py3-none-any.whl
+git diff --check
+```
+
+版本变化后将命令中的 wheel 文件名换成实际产物。安装验证使用临时工具环境和假 Codex 配置，不替换你的全局安装；首次运行可能下载依赖。完整流程见 [发布说明](docs/RELEASING.md)。
+
+## 提交 PR
+
+说明问题如何触发、修改后的行为，以及实际执行的验证。涉及界面或示例图片时，附上你有权公开的示例；跨平台改动请注明操作系统和 Python 版本。
+
+提交前检查差异和新文件。不要提交真实 API Key、完整 Codex 配置、私人中转地址、日志中的认证头，或未经授权的用户图片。复现数据使用假凭据和可公开的样例；报告疑似凭据泄漏或漏洞请使用 [私密报告渠道](SECURITY.md)。
+
+贡献将按本项目的 [MIT 许可证](LICENSE) 分发。请确保你有权提交相关代码、文档和素材。

codex_image_generation-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TangRuoJie
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

codex_image_generation-0.3.0/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: codex-image-generation
+Version: 0.3.0
+Summary: A local Codex MCP server for Responses image generation using existing provider credentials
+Keywords: codex,mcp,fastmcp,image-generation,responses
+Author: TangRuoJie
+Author-email: TangRuoJie <3177065378@qq.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Multimedia :: Graphics
+Requires-Dist: fastmcp>=4.1.4,<5
+Requires-Dist: openai>=3.42.0,<4
+Requires-Dist: pillow>=11.3,<14
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# Codex Image Generation MCP
+
+为使用中转站的 Codex 提供本地图像生成和编辑工具。安装后，直接告诉 Codex：
+
+> 生成一只阳光、动漫风格的可爱小狗，保存在当前项目中。
+
+Codex 调用 `generate_image`，工具复用用户已有的 Codex URL、API Key 和模型设置，保存原图并返回文件路径和预览。默认直接保存到当前任务目录，也可以指定文件夹、文件名和 PNG / JPEG / WebP 格式。
+
+无需另配图像模型；请求通过 Responses API 的 `image_generation` 工具完成，不发送 `tools[].model`。中转站必须支持这一接口，并允许所选对话模型调用图像工具。
+
+本项目由 TangRuoJie 维护，采用 [MIT 许可证](LICENSE)，是独立社区项目，与 OpenAI 无隶属关系。
+
+## 生成效果展示
+
+示例：阳光下、动漫风格的可爱小狗。
+
+![阳光下坐在草地上的动漫风格可爱小狗](sunny-anime-puppy.png)
+
+## 下载包后安装
+
+当前版本：**0.3.0**。分发包为 `codex-image-generation-0.3.0.zip`，内含 wheel、源码包、安装说明、许可证、配置示例和 SHA-256 校验清单。这是 Python 安装包，需要 [uv](https://docs.astral.sh/uv/getting-started/installation/)；首次安装需要联网下载 Python（如果缺少）和依赖。
+
+分享给别人时，发送 `dist/codex-image-generation-0.3.0.zip` 即可，对方按照包内 `INSTALL.md` 操作。以后公开 Release 后，下载其中的同名附件；GitHub 自动提供的 `Source code.zip` 是源码归档，不是这个安装分发包。
+
+**第 1 步：准备自己的环境。** 对方需要已安装 Codex、已有可用的中转站配置，并安装 uv。执行 `uv --version` 确认命令可用。URL、API Key 和模型复用对方自己的 Codex 配置，不需要复制作者的配置。
+
+**第 2 步：安装并检查。** 解压 ZIP，在包含 `.whl` 文件的解压目录打开终端。下面的命令适用于 Windows PowerShell、macOS 和 Linux：
+
+~~~sh
+uv tool install --python 3.11 ./codex_image_generation-0.3.0-py3-none-any.whl
+codex-image-generation --version
+codex-image-generation --check
+~~~
+
+如果系统找不到 `codex-image-generation`，执行 `uv tool update-shell` 后重新打开终端。版本应显示 `0.3.0`，检查结果应包含 `configured: true`；`connection_verified: false` 是正常的，因为此命令只检查本地配置，不请求中转站。检查失败时，先按 [安装说明中的故障排查](docs/INSTALL.md#常见问题) 修正现有配置。
+
+**第 3 步：生成接入配置。** 执行：
+
+~~~sh
+codex-image-generation --print-config
+~~~
+
+**第 4 步：保存配置。** 将上一步输出的整个 `[mcp_servers.image_generation]` TOML 配置块加入**自己电脑**的 Codex 用户配置文件并保存。这条命令只打印内容，不会自动完成接入。
+
+| 系统 | 默认配置文件 |
+| --- | --- |
+| Windows | `%USERPROFILE%\.codex\config.toml` |
+| macOS / Linux | `~/.codex/config.toml` |
+
+设置过 `CODEX_HOME` 时使用该目录下的 `config.toml`。已有同名 `[mcp_servers.image_generation]` 时替换该节，避免重复。保留已有的模型和 provider 设置。若认证依赖环境变量，启动 Codex 的环境也必须能读取这些变量。
+
+**第 5 步：重启 Codex 并验证。** 保存配置后重启 Codex，打开需要保存图片的项目，确认 MCP 已加载且包含 `generate_image` 工具。首次测试可以明确说：
+
+> 请使用 image_generation MCP，生成一只阳光、动漫风格的可爱小狗，保存在当前项目中。
+
+成功时应收到原图路径，并能在当前项目目录找到图片；仅安装成功或 `--check` 通过不代表已经验证上游出图能力。之后日常直接描述图片和保存位置即可，Codex 会按配置启动服务，无需每次安装或手动常驻一个终端。
+
+安装过程不会自动修改 Codex 配置。生成的接入配置使用安装环境中 Python 的绝对路径，不依赖项目源码目录或下载目录；常规安装完成后可以删除解压文件。包内不包含发布者的 URL、API Key 或 Codex 配置。
+
+完整的安装、升级、卸载、离线限制和故障排查见 [安装说明](docs/INSTALL.md)。也提供 [本地 wheel 的 uv 启动配置](examples/codex-uvx.toml)，采用该方式时需要保留 wheel。
+
+## 日常使用
+
+| 你对 Codex 说 | 工具行为 |
+| --- | --- |
+| 生成一张安静的书桌插画 | 在当前任务目录保存唯一命名的 PNG |
+| 生成透明背景的茶杯图标，存到 assets/tea.webp | 保存到指定目录，使用 WebP 和透明背景 |
+| 把这张图片中的沙发改成蓝色 | 将参考图传给上游进行编辑 |
+| 按上一张继续调整，光线暖一些 | 在同一 provider 支持历史引用时继续编辑 |
+
+风格可以是写实、动漫、插画、像素画、海报等，由提示词和上游图像模型决定。本项目封装官方 Responses 图像工具的调用方式；不保证与 ChatGPT 网页或 Codex 内置工具的模型路由、全部功能、界面和效果完全相同。
+
+支持的主要能力：
+
+- PNG、JPEG（含 `jpg` 别名）、WebP 静态图片；透明背景使用 PNG / WebP。
+- 尺寸、质量、背景、JPEG / WebP 压缩率等选项，具体可用值由上游模型决定。
+- 参考图、蒙版，以及同一 provider 的历史响应 / 图像 ID。
+- 可选流式中间图与 MCP 进度；客户端是否实时显示取决于其支持。
+- 原图落盘、受大小限制的预览、绝对路径和结构化结果。
+- 已有文件不覆盖；部分图片失败时保留成功结果；不会自动重试付费生成。
+
+不输出 SVG、GIF 动画或视频。所有参数、返回字段和限制见 [工具参考](docs/TOOLS.md)。
+
+## 模型、凭据与当前目录
+
+工具公开参数只有一个必需的业务输入 `prompt`，以及由 Codex 从任务上下文提供的绝对工作目录 `cwd`。用户不必在每次对话中手动填写路径；没有指定输出位置时，直接保存到 `cwd`。
+
+模型选择顺序：
+
+1. Codex 能可靠获知当前会话的精确 API 模型 ID 时，调用时传入 `current_model`。
+2. 未传入时，读取所选 Codex 配置中的 `model`。
+3. 两处都没有模型时明确报错，不硬编码兜底模型。
+
+普通 MCP 协议不保证提供当前会话模型。因此，界面临时切换模型后能否立即同步，取决于 Codex 是否传入可靠上下文；不能仅凭读取配置文件就承诺跟随所有界面切换。`current_model` 是调用参数，无需用户另建模型配置。
+
+连接设置只读取所选用户级 Codex provider：
+
+- 复用 `base_url`、环境变量 API Key、配置中的 bearer token、请求头和查询参数。
+- 在所选 provider 要求 API Key 认证时，支持读取 Codex 文件存储的 API Key。
+- 支持已有 profile；使用 `--profile` 选择。
+- 不扫描其他 provider 寻找密钥，不读取项目 `.env`，不实现 ChatGPT OAuth 或系统钥匙串登录。
+
+`--print-config` 会生成所需环境变量**名称**的白名单，不复制密钥值。若 provider 使用环境变量认证，启动 Codex 的环境也必须能访问这些变量。
+
+| 可选启动设置 | 用途 |
+| --- | --- |
+| `--codex-home` / `CODEX_HOME` | 定位已有 Codex 配置目录 |
+| `--profile` / `CODEX_IMAGE_PROFILE` | 选择已有 profile |
+| `CODEX_IMAGE_TIMEOUT` | 上游超时秒数，默认 300，范围大于 0 且不超过 3600 |
+
+## 系统兼容性
+
+项目使用 Python 3.11+，wheel 为 `py3-none-any`，不写死开发者目录。依赖中包含本机二进制组件，因此这一标签不表示任意旧系统都能直接安装。
+
+| 平台 | 验证情况 |
+| --- | --- |
+| Windows x64 | 本地测试、安装包独立环境启动和 stdio 验证 |
+| Linux x64 | 容器内安装、测试和 stdio 验证 |
+| macOS Apple Silicon | 已检查依赖 wheel 可获取；尚无 macOS 实机运行验证 |
+| macOS Intel | 当前 cryptography 50 系列缺少 Intel wheel，可能需要本机构建；尚未验证完整安装 |
+
+建议使用仍受支持的现代系统。旧版 Linux（例如 glibc 2.17）可能缺少当前 Pillow 的预编译包。首次安装需要联网；不将此包描述为免依赖、完全离线的可执行文件。
+
+## 源码开发与构建分发包
+
+仅使用工具时无需下载源码。维护项目时，在源码目录执行：
+
+~~~sh
+uv sync --locked
+uv run --locked python -B -m unittest discover -s tests -v
+uv run --locked python scripts/build_release.py
+uv run --locked python scripts/smoke_wheel.py --wheel dist/codex_image_generation-0.3.0-py3-none-any.whl
+~~~
+
+构建输出：
+
+~~~text
+dist/
+  codex_image_generation-0.3.0-py3-none-any.whl
+  codex_image_generation-0.3.0.tar.gz
+  codex-image-generation-0.3.0.zip
+  SHA256SUMS-0.3.0.txt
+~~~
+
+构建脚本检查包内容，不纳入本地配置、凭据或虚拟环境。源码包包含 README 使用的展示图 `sunny-anime-puppy.png`，其他生成图片不纳入；wheel 不包含展示图。安装冒烟测试使用临时安装目录、假凭据和无网络图像请求，从其他工作目录验证 CLI 与 MCP；不会替换你的全局安装。
+
+仓库包含 Windows、Linux、macOS 的 CI 工作流，执行测试、打包和安装验证，并保存构建产物。维护者可手动运行发布工作流，为已存在的版本标签创建 GitHub Release 草稿；只有全部检查通过才会创建草稿。工作流是否通过以实际运行结果为准。当前产物在本地构建，尚未上传 PyPI 或其他公开下载服务；不要将裸命令 `uvx codex-image-generation` 视为已验证的安装入口。
+
+详见 [发布维护说明](docs/RELEASING.md) 和 [更新记录](CHANGELOG.md)。
+
+## 贡献、反馈与许可
+
+- 作者：TangRuoJie；邮箱：[3177065378@qq.com](mailto:3177065378@qq.com)。
+- 贡献代码或改进文档，请先阅读 [贡献指南](CONTRIBUTING.md)。
+- 普通问题可通过仓库 Issues 反馈；漏洞或凭据泄漏请按 [安全报告说明](SECURITY.md) 私下联系。
+- 本项目采用 [MIT 许可证](LICENSE)，允许使用、修改和商业分发，分发时需保留版权及许可声明。第三方依赖遵循各自的许可证。
+
+## 官方参考
+
+- [Responses 图像生成工具](https://developers.openai.com/api/docs/guides/tools-image-generation)
+- [Responses Create API](https://developers.openai.com/api/reference/resources/responses/methods/create)
+- [Codex MCP 配置](https://developers.openai.com/codex/mcp)
+- [Codex 配置参考](https://developers.openai.com/codex/config-reference)

codex_image_generation-0.3.0/README.md

@@ -0,0 +1,163 @@
+# Codex Image Generation MCP
+
+为使用中转站的 Codex 提供本地图像生成和编辑工具。安装后，直接告诉 Codex：
+
+> 生成一只阳光、动漫风格的可爱小狗，保存在当前项目中。
+
+Codex 调用 `generate_image`，工具复用用户已有的 Codex URL、API Key 和模型设置，保存原图并返回文件路径和预览。默认直接保存到当前任务目录，也可以指定文件夹、文件名和 PNG / JPEG / WebP 格式。
+
+无需另配图像模型；请求通过 Responses API 的 `image_generation` 工具完成，不发送 `tools[].model`。中转站必须支持这一接口，并允许所选对话模型调用图像工具。
+
+本项目由 TangRuoJie 维护，采用 [MIT 许可证](LICENSE)，是独立社区项目，与 OpenAI 无隶属关系。
+
+## 生成效果展示
+
+示例：阳光下、动漫风格的可爱小狗。
+
+![阳光下坐在草地上的动漫风格可爱小狗](sunny-anime-puppy.png)
+
+## 下载包后安装
+
+当前版本：**0.3.0**。分发包为 `codex-image-generation-0.3.0.zip`，内含 wheel、源码包、安装说明、许可证、配置示例和 SHA-256 校验清单。这是 Python 安装包，需要 [uv](https://docs.astral.sh/uv/getting-started/installation/)；首次安装需要联网下载 Python（如果缺少）和依赖。
+
+分享给别人时，发送 `dist/codex-image-generation-0.3.0.zip` 即可，对方按照包内 `INSTALL.md` 操作。以后公开 Release 后，下载其中的同名附件；GitHub 自动提供的 `Source code.zip` 是源码归档，不是这个安装分发包。
+
+**第 1 步：准备自己的环境。** 对方需要已安装 Codex、已有可用的中转站配置，并安装 uv。执行 `uv --version` 确认命令可用。URL、API Key 和模型复用对方自己的 Codex 配置，不需要复制作者的配置。
+
+**第 2 步：安装并检查。** 解压 ZIP，在包含 `.whl` 文件的解压目录打开终端。下面的命令适用于 Windows PowerShell、macOS 和 Linux：
+
+~~~sh
+uv tool install --python 3.11 ./codex_image_generation-0.3.0-py3-none-any.whl
+codex-image-generation --version
+codex-image-generation --check
+~~~
+
+如果系统找不到 `codex-image-generation`，执行 `uv tool update-shell` 后重新打开终端。版本应显示 `0.3.0`，检查结果应包含 `configured: true`；`connection_verified: false` 是正常的，因为此命令只检查本地配置，不请求中转站。检查失败时，先按 [安装说明中的故障排查](docs/INSTALL.md#常见问题) 修正现有配置。
+
+**第 3 步：生成接入配置。** 执行：
+
+~~~sh
+codex-image-generation --print-config
+~~~
+
+**第 4 步：保存配置。** 将上一步输出的整个 `[mcp_servers.image_generation]` TOML 配置块加入**自己电脑**的 Codex 用户配置文件并保存。这条命令只打印内容，不会自动完成接入。
+
+| 系统 | 默认配置文件 |
+| --- | --- |
+| Windows | `%USERPROFILE%\.codex\config.toml` |
+| macOS / Linux | `~/.codex/config.toml` |
+
+设置过 `CODEX_HOME` 时使用该目录下的 `config.toml`。已有同名 `[mcp_servers.image_generation]` 时替换该节，避免重复。保留已有的模型和 provider 设置。若认证依赖环境变量，启动 Codex 的环境也必须能读取这些变量。
+
+**第 5 步：重启 Codex 并验证。** 保存配置后重启 Codex，打开需要保存图片的项目，确认 MCP 已加载且包含 `generate_image` 工具。首次测试可以明确说：
+
+> 请使用 image_generation MCP，生成一只阳光、动漫风格的可爱小狗，保存在当前项目中。
+
+成功时应收到原图路径，并能在当前项目目录找到图片；仅安装成功或 `--check` 通过不代表已经验证上游出图能力。之后日常直接描述图片和保存位置即可，Codex 会按配置启动服务，无需每次安装或手动常驻一个终端。
+
+安装过程不会自动修改 Codex 配置。生成的接入配置使用安装环境中 Python 的绝对路径，不依赖项目源码目录或下载目录；常规安装完成后可以删除解压文件。包内不包含发布者的 URL、API Key 或 Codex 配置。
+
+完整的安装、升级、卸载、离线限制和故障排查见 [安装说明](docs/INSTALL.md)。也提供 [本地 wheel 的 uv 启动配置](examples/codex-uvx.toml)，采用该方式时需要保留 wheel。
+
+## 日常使用
+
+| 你对 Codex 说 | 工具行为 |
+| --- | --- |
+| 生成一张安静的书桌插画 | 在当前任务目录保存唯一命名的 PNG |
+| 生成透明背景的茶杯图标，存到 assets/tea.webp | 保存到指定目录，使用 WebP 和透明背景 |
+| 把这张图片中的沙发改成蓝色 | 将参考图传给上游进行编辑 |
+| 按上一张继续调整，光线暖一些 | 在同一 provider 支持历史引用时继续编辑 |
+
+风格可以是写实、动漫、插画、像素画、海报等，由提示词和上游图像模型决定。本项目封装官方 Responses 图像工具的调用方式；不保证与 ChatGPT 网页或 Codex 内置工具的模型路由、全部功能、界面和效果完全相同。
+
+支持的主要能力：
+
+- PNG、JPEG（含 `jpg` 别名）、WebP 静态图片；透明背景使用 PNG / WebP。
+- 尺寸、质量、背景、JPEG / WebP 压缩率等选项，具体可用值由上游模型决定。
+- 参考图、蒙版，以及同一 provider 的历史响应 / 图像 ID。
+- 可选流式中间图与 MCP 进度；客户端是否实时显示取决于其支持。
+- 原图落盘、受大小限制的预览、绝对路径和结构化结果。
+- 已有文件不覆盖；部分图片失败时保留成功结果；不会自动重试付费生成。
+
+不输出 SVG、GIF 动画或视频。所有参数、返回字段和限制见 [工具参考](docs/TOOLS.md)。
+
+## 模型、凭据与当前目录
+
+工具公开参数只有一个必需的业务输入 `prompt`，以及由 Codex 从任务上下文提供的绝对工作目录 `cwd`。用户不必在每次对话中手动填写路径；没有指定输出位置时，直接保存到 `cwd`。
+
+模型选择顺序：
+
+1. Codex 能可靠获知当前会话的精确 API 模型 ID 时，调用时传入 `current_model`。
+2. 未传入时，读取所选 Codex 配置中的 `model`。
+3. 两处都没有模型时明确报错，不硬编码兜底模型。
+
+普通 MCP 协议不保证提供当前会话模型。因此，界面临时切换模型后能否立即同步，取决于 Codex 是否传入可靠上下文；不能仅凭读取配置文件就承诺跟随所有界面切换。`current_model` 是调用参数，无需用户另建模型配置。
+
+连接设置只读取所选用户级 Codex provider：
+
+- 复用 `base_url`、环境变量 API Key、配置中的 bearer token、请求头和查询参数。
+- 在所选 provider 要求 API Key 认证时，支持读取 Codex 文件存储的 API Key。
+- 支持已有 profile；使用 `--profile` 选择。
+- 不扫描其他 provider 寻找密钥，不读取项目 `.env`，不实现 ChatGPT OAuth 或系统钥匙串登录。
+
+`--print-config` 会生成所需环境变量**名称**的白名单，不复制密钥值。若 provider 使用环境变量认证，启动 Codex 的环境也必须能访问这些变量。
+
+| 可选启动设置 | 用途 |
+| --- | --- |
+| `--codex-home` / `CODEX_HOME` | 定位已有 Codex 配置目录 |
+| `--profile` / `CODEX_IMAGE_PROFILE` | 选择已有 profile |
+| `CODEX_IMAGE_TIMEOUT` | 上游超时秒数，默认 300，范围大于 0 且不超过 3600 |
+
+## 系统兼容性
+
+项目使用 Python 3.11+，wheel 为 `py3-none-any`，不写死开发者目录。依赖中包含本机二进制组件，因此这一标签不表示任意旧系统都能直接安装。
+
+| 平台 | 验证情况 |
+| --- | --- |
+| Windows x64 | 本地测试、安装包独立环境启动和 stdio 验证 |
+| Linux x64 | 容器内安装、测试和 stdio 验证 |
+| macOS Apple Silicon | 已检查依赖 wheel 可获取；尚无 macOS 实机运行验证 |
+| macOS Intel | 当前 cryptography 50 系列缺少 Intel wheel，可能需要本机构建；尚未验证完整安装 |
+
+建议使用仍受支持的现代系统。旧版 Linux（例如 glibc 2.17）可能缺少当前 Pillow 的预编译包。首次安装需要联网；不将此包描述为免依赖、完全离线的可执行文件。
+
+## 源码开发与构建分发包
+
+仅使用工具时无需下载源码。维护项目时，在源码目录执行：
+
+~~~sh
+uv sync --locked
+uv run --locked python -B -m unittest discover -s tests -v
+uv run --locked python scripts/build_release.py
+uv run --locked python scripts/smoke_wheel.py --wheel dist/codex_image_generation-0.3.0-py3-none-any.whl
+~~~
+
+构建输出：
+
+~~~text
+dist/
+  codex_image_generation-0.3.0-py3-none-any.whl
+  codex_image_generation-0.3.0.tar.gz
+  codex-image-generation-0.3.0.zip
+  SHA256SUMS-0.3.0.txt
+~~~
+
+构建脚本检查包内容，不纳入本地配置、凭据或虚拟环境。源码包包含 README 使用的展示图 `sunny-anime-puppy.png`，其他生成图片不纳入；wheel 不包含展示图。安装冒烟测试使用临时安装目录、假凭据和无网络图像请求，从其他工作目录验证 CLI 与 MCP；不会替换你的全局安装。
+
+仓库包含 Windows、Linux、macOS 的 CI 工作流，执行测试、打包和安装验证，并保存构建产物。维护者可手动运行发布工作流，为已存在的版本标签创建 GitHub Release 草稿；只有全部检查通过才会创建草稿。工作流是否通过以实际运行结果为准。当前产物在本地构建，尚未上传 PyPI 或其他公开下载服务；不要将裸命令 `uvx codex-image-generation` 视为已验证的安装入口。
+
+详见 [发布维护说明](docs/RELEASING.md) 和 [更新记录](CHANGELOG.md)。
+
+## 贡献、反馈与许可
+
+- 作者：TangRuoJie；邮箱：[3177065378@qq.com](mailto:3177065378@qq.com)。
+- 贡献代码或改进文档，请先阅读 [贡献指南](CONTRIBUTING.md)。
+- 普通问题可通过仓库 Issues 反馈；漏洞或凭据泄漏请按 [安全报告说明](SECURITY.md) 私下联系。
+- 本项目采用 [MIT 许可证](LICENSE)，允许使用、修改和商业分发，分发时需保留版权及许可声明。第三方依赖遵循各自的许可证。
+
+## 官方参考
+
+- [Responses 图像生成工具](https://developers.openai.com/api/docs/guides/tools-image-generation)
+- [Responses Create API](https://developers.openai.com/api/reference/resources/responses/methods/create)
+- [Codex MCP 配置](https://developers.openai.com/codex/mcp)
+- [Codex 配置参考](https://developers.openai.com/codex/config-reference)

codex_image_generation-0.3.0/SECURITY.md

@@ -0,0 +1,25 @@
+# 安全问题报告
+
+维护者：TangRuoJie。疑似漏洞、凭据泄漏或意外文件访问问题，请发送邮件至 [3177065378@qq.com](mailto:3177065378@qq.com)，不要先在公开 Issue 中披露可利用细节或真实凭据。
+
+邮件中请提供：
+
+- 项目版本、操作系统和 Python 版本。
+- 问题的影响、触发条件，以及使用假凭据和测试文件的最小复现步骤。
+- 已脱敏的错误信息；若已自行采取缓解措施，也请说明。
+
+无需发送 API Key、访问令牌、完整 `auth.json` / `config.toml` 或私人图片。若真实凭据已经公开，请先通过对应服务撤销或轮换该凭据，再报告泄漏位置。维护者会根据可复现性和影响处理报告，不承诺固定响应或修复时间。
+
+## 维护版本
+
+安全修复优先针对当前 0.3 系列的最新版本。旧版本不承诺回补；报告旧版问题时，请注明能否在最新版复现。
+
+## 数据与访问边界
+
+本工具通过本地 stdio 运行，应由可信的 MCP 客户端启动。它读取用户选择的已有 Codex 配置及其引用的凭据，向该 provider 配置的地址发送图像请求，并在调用方指定的目录保存文件。
+
+提示词、参考图和可选蒙版会作为请求内容发送给所选中转站或上游；远程参考图 URL 和 provider 文件 ID 也会传给上游处理。请只使用你信任的 provider，并提供有权处理的素材。
+
+工具不是独立的文件访问沙箱。调用方可以指定绝对输出路径和本地参考图路径，其可访问范围受运行进程的系统权限约束。不要把本地服务直接暴露给不可信调用方。
+
+`--check` 只解析本地配置，不访问上游。诊断内容仍可能包含私人地址或路径，公开反馈前请逐项脱敏。测试和构建检查不等于独立安全审计。

codex_image_generation-0.3.0/docs/INSTALL.md

@@ -0,0 +1,180 @@
+# 下载包安装与 Codex 接入
+
+安装一次后，可在任意项目中使用。MCP 复用使用者自己的 Codex 中转站配置；分发包不包含作者的 URL、API Key 或模型设置。
+
+## 获取正确的安装包
+
+当前可由维护者直接发送 `codex-image-generation-0.3.0.zip`；以后公开 Release 后，在该版本的附件中下载同名 ZIP。GitHub 自动生成的 `Source code.zip` / `Source code.tar.gz` 是源码归档，不是本指南推荐的安装分发包。
+
+解压后应能看到 `codex_image_generation-0.3.0-py3-none-any.whl`、`INSTALL.md`、`LICENSE`、配置示例、源码包和 `SHA256SUMS`。正常使用只需安装 wheel 并接入 Codex，不需要解压源码包，也不用把这些文件放进每个项目。
+
+第一次使用的顺序是：**准备 uv 和已有 Codex 中转站配置 → 安装 wheel → 检查配置 → 生成并保存 MCP 配置 → 重启 Codex → 实际生成一张图片**。
+
+## 准备条件
+
+- 安装 [uv](https://docs.astral.sh/uv/getting-started/installation/)。下文用 uv 建立独立的 Python 工具环境，不需要手动激活虚拟环境。
+- 已有可用的 Codex 中转站配置，包括 URL、认证方式和模型。中转站须支持 Responses API 的 `image_generation` 工具。
+- 安装时需要联网下载 Python（如果本机没有指定版本）和依赖；图片生成时需要访问中转站。
+
+安装 uv 后执行 `uv --version` 确认命令可用。无需另行安装 FastMCP、OpenAI SDK 或 Pillow，安装 wheel 时会自动处理这些依赖。
+
+安装包是 Python 包，不是免运行时的独立可执行文件，也不是离线依赖合集。建议使用 Python 3.11；包元数据允许 3.11 及以上版本，更高版本仍受依赖兼容性约束。
+
+## 推荐：安装到独立工具环境
+
+下载并解压 `codex-image-generation-0.3.0.zip`，找到 `codex_image_generation-0.3.0-py3-none-any.whl`。也可以直接取得这个 wheel 文件。
+
+最直接的方法是在包含 wheel 的解压目录打开终端：
+
+```sh
+uv tool install --python 3.11 ./codex_image_generation-0.3.0-py3-none-any.whl
+codex-image-generation --version
+codex-image-generation --check
+```
+
+版本应显示 `0.3.0`，检查结果应包含 `configured: true`。`connection_verified: false` 是正常结果，含义见后文。检查失败时先修正现有 Codex 配置，再继续接入。
+
+也可以从其他目录安装，使用下面的绝对路径示例；路径应指向实际解压出来的 wheel，不能直接指向 ZIP。
+
+Windows PowerShell 示例，路径替换为自己的下载位置：
+
+```powershell
+uv tool install --python 3.11 "C:\Users\YourName\Downloads\codex_image_generation-0.3.0-py3-none-any.whl"
+codex-image-generation --version
+codex-image-generation --check
+codex-image-generation --print-config
+```
+
+macOS 示例：
+
+```sh
+uv tool install --python 3.11 "$HOME/Downloads/codex_image_generation-0.3.0-py3-none-any.whl"
+codex-image-generation --version
+codex-image-generation --check
+codex-image-generation --print-config
+```
+
+Linux 示例：
+
+```sh
+uv tool install --python 3.11 "$HOME/Downloads/codex_image_generation-0.3.0-py3-none-any.whl"
+codex-image-generation --version
+codex-image-generation --check
+codex-image-generation --print-config
+```
+
+若终端提示找不到 `codex-image-generation`，执行 `uv tool update-shell`，按提示重新打开终端，再运行后三条命令。`uv tool dir --bin` 可查看命令所在目录。
+
+安装成功后，运行时使用 uv 的工具环境，不再依赖下载目录或项目源码。可以删除下载的 wheel；请保留 uv 的工具环境及其 Python 运行时。
+
+## 加入自己的 Codex 配置
+
+本地检查通过后运行 `codex-image-generation --print-config`，将输出的整个 `[mcp_servers.image_generation]` 表加入 Codex 用户配置并保存。此命令只打印配置，不自动修改文件。如果已有同名表，应替换该表，不要重复添加；保留原有的模型和 provider 设置。
+
+默认配置文件位置：
+
+| 系统 | 默认路径 |
+| --- | --- |
+| Windows | `%USERPROFILE%\.codex\config.toml` |
+| macOS / Linux | `~/.codex/config.toml` |
+
+使用自定义 `CODEX_HOME` 时，文件是该目录下的 `config.toml`。需要指定已有配置位置或 profile 时，在生成配置和诊断时使用同样的参数：
+
+```sh
+codex-image-generation --codex-home /absolute/path/to/codex-home --profile work --check
+codex-image-generation --codex-home /absolute/path/to/codex-home --profile work --print-config
+```
+
+这里的目录和 `work` 都是示例，须对应已有配置。Windows 可以使用带引号的 Windows 绝对路径。`--profile` 选择已有 profile，不创建第二套 URL、密钥或模型设置。
+
+生成的配置会使用当前已安装环境的 Python 绝对路径，以及本机 Codex 配置目录的绝对路径；无需把 MCP 安装目录设为项目目录。生成的配置只能用于当前电脑，其他使用者应在自己的电脑上执行 `--print-config`。
+
+配置中的 `env_vars` 是转发给 MCP 的环境变量名，不包含变量值。如果已有 provider 通过 `env_key` 或 `env_http_headers` 引用环境变量，启动 Codex 的进程也必须能读取这些变量。仅在另一个终端临时设置变量，不一定能传给已启动的桌面应用；设置后重新启动 Codex。不要把 API Key 复制进示例文件。
+
+保存配置后重启 Codex，打开需要保存图片的项目。确认 `image_generation` MCP 已加载且包含 `generate_image` 工具。首次验证建议明确指定工具：
+
+> 请使用 image_generation MCP，生成一只阳光、动漫风格、可爱的小狗，保存在当前项目中。
+
+Codex 应调用 `generate_image` 并传入当前任务的绝对 `cwd`；不指定目标目录时，原图直接保存在这个目录。需要指定位置时，可以说“保存到当前项目的 `assets/puppy.webp`”。
+
+完成验证的标准是：Codex 返回保存路径，且能在该路径找到可打开的图片。此后直接自然语言提出生成需求即可，不用每次写工具参数或重新配置 URL、Key、模型。
+
+Codex 会根据保存的 MCP 配置启动服务，不需要使用者手动保持一个服务终端。若直接运行不带参数的 `codex-image-generation`，它会进入 stdio 模式等待客户端消息，看起来没有输出是正常的；终端诊断请使用 `--version`、`--check` 或 `--print-config`。
+
+## 诊断命令的含义
+
+`--check` 只检查本地配置，不请求中转站、不生成图片、不产生图片生成费用。
+
+- `configured: true` 表示本地连接配置可解析。
+- `connection_verified: false` 表示没有进行网络验证，不能据此判断中转站是否支持图片工具。
+- `model_available_in_config` 表示配置里是否有可用模型；没有时，每次调用需要由 Codex 提供可靠的 `current_model`。
+- `session_model_auto_detection: false` 表示普通 MCP 无法自行确认 Codex 界面的临时模型选择。
+
+真正生成图片会调用中转站，可能产生费用。超时或断流后先检查结果和中转站记录，不要自动连续重试。
+
+## 常见问题
+
+| 现象 | 处理方法 |
+| --- | --- |
+| 找不到 `uv` | 按官方安装说明安装 uv，重新打开终端，再运行 `uv --version`。 |
+| 找不到 `codex-image-generation` | 确认 wheel 安装成功，执行 `uv tool update-shell`，按提示重新打开终端。 |
+| 安装时提示 wheel 文件不存在 | 确认 ZIP 已解压，在包含 `.whl` 的目录运行相对路径命令，或改用真实绝对路径。 |
+| `--check` 返回 `configured: false` | 根据错误检查原有 Codex 配置位置、所选 provider、认证来源；自定义位置/profile 时使用对应启动参数。 |
+| 检查结果为 `connection_verified: false` | 这是本地诊断的预期结果；实际生成图片才会验证上游连接和工具支持。 |
+| 终端检查通过，Codex 中却缺少认证环境变量 | `env_vars` 只转发变量名；让启动 Codex 的环境能读取这些变量，并重启 Codex。 |
+| Codex 找不到这个 MCP 或工具 | 确认已把完整配置块保存到正确的 `config.toml`，没有重复同名表，配置中的 Python 路径仍存在，然后重启 Codex。 |
+| MCP 能启动，但生成时上游报错 | 核对中转站对 Responses、`image_generation` 和所选对话模型的支持，以及具体参数限制；仅能聊天不代表能出图。 |
+| 切换了界面模型，返回的模型仍来自配置 | 普通 MCP 无法自行确认临时模型选择；可靠调用上下文未传入 `current_model` 时会使用配置中的模型。 |
+
+反馈问题时仅提供脱敏后的相关错误片段，不要发送 API Key、完整 Codex 配置或私人图片。
+
+## 可选：通过本地 wheel 启动
+
+不建立持久工具安装时，可以使用发布包中的 `codex-uvx.toml` 示例；源码中的同一文件位于 `examples/codex-uvx.toml`。它使用：
+
+```sh
+uv tool run --python 3.11 --from /absolute/path/to/codex_image_generation-0.3.0-py3-none-any.whl codex-image-generation
+```
+
+该模式的 wheel 必须保留在固定绝对路径。Codex 需要能找到 `uv`；桌面应用 PATH 不完整时，把 `command` 改为 uv 可执行文件的绝对路径。首次启动可能下载依赖，建议先在终端用同一命令追加 `--check` 完成准备。
+
+此模式不要将 `--print-config` 输出作为持久安装配置：输出可能指向 uv 的临时缓存环境，清理缓存后可能失效。需要稳定配置时采用上面的 `uv tool install`。
+
+项目尚未发布到公共包索引，因此不要使用省略本地 wheel 的 `uvx codex-image-generation` 或 `pip install codex-image-generation` 来代表本项目。
+
+## 升级、卸载与源码开发
+
+从较早的安装版本迁移时，请安装当前名称的包，并重新运行 `codex-image-generation --print-config` 更新接入配置，避免继续引用旧安装环境。
+
+下载新版本后重新安装本地 wheel：
+
+```sh
+uv tool install --force --python 3.11 /absolute/path/to/new-version.whl
+codex-image-generation --check
+codex-image-generation --print-config
+```
+
+`new-version.whl` 是路径占位，需替换为下载文件的真实完整文件名。用新的输出更新 Codex 的同名 MCP 配置，再重新加载 MCP。升级不改写 Codex 的 provider 设置，也不清理项目中已生成的图片。
+
+卸载时执行 `uv tool uninstall codex-image-generation`，并从 Codex 配置中移除对应 MCP 表。
+
+开发者在源码根目录使用：
+
+```sh
+uv sync --locked
+uv run --frozen codex-image-generation --check
+uv run --frozen codex-image-generation --print-config
+```
+
+源码方式生成的配置指向项目虚拟环境，移动/删除源码目录或重建环境后应重新生成配置。分发给其他人时优先使用 wheel。
+
+## 平台边界
+
+项目代码及 wheel 不含固定的作者目录，也不含系统专用可执行文件。实际运行还取决于 Python、FastMCP、Pillow 及其间接依赖。
+
+- Windows x64 和现代 Linux x64 已进行运行测试。
+- macOS 尚未进行实机运行测试。Apple Silicon 的依赖二进制解析已检查，但这不等于运行验证。
+- 当前依赖链中的 `cryptography 50.0.2` 缺少 Intel macOS wheel；Intel Mac 可能需要构建依赖，尚未验证，不承诺开箱即用。
+- 较老的 Linux、特殊 CPU 架构、自行编译的 Python/Pillow 需要单独验证；旧版 glibc 可能没有对应依赖 wheel。
+
+普通 MCP 无法保证像 Codex 内置工具那样实时显示生成过程。最终返回包含原图绝对路径和受大小限制的预览；完整文件以原图路径为准。