# WorkBuddy GPT 原生生图插件

在 WorkBuddy 对话中，使用 **自定义 GPT + OpenCodex 本地代理** 生成、编辑图片，而不是调用 WorkBuddy 内置生图供应商。

这是独立的第三方 **MCP + Skill 插件**，不是修改 WorkBuddy 可执行文件的补丁，也不是 VSIX。工程基于本机既有生图 MCP 重构；没有复制旧服务的凭据、任务历史或图片。

## 工作原理与边界

~~~text
WorkBuddy 中的对话模型
  → workbuddy-gpt-image MCP 工具
  → OpenCodex /v1/responses
  → GPT hosted image_generation
  → 校验图片 → 保存本地文件 → MCP 图片预览 + 文件路径
~~~

- 主模型与图片模型是不同概念：顶层 model 负责调用工具；tools[0].model 是图片工具的请求参数。
- 默认主模型 gpt-5.5、图片请求模型 gpt-image-2 是本机原服务使用的配置，**不是所有账号都可用的承诺**。可改为代理实际公布、支持生图的完整路由 ID。
- **不会自动跟随 WorkBuddy 当前聊天窗口所选的模型。** 标准 MCP 调用不提供该选择；使用安装器的 --model 或环境变量显式选定同一条代理路由。
- 插件不绕过账号权限、额度、内容策略或代理限制。能聊天、能列出模型，不等于能生图；只有真实图片返回才算成功。
- 插件只实现 Responses 生图链路，不将失败请求偷偷改发 /images/generations、xAI Image Bridge、公开付费 API 或内置生图。OpenCodex 某些版本另有 Images API，不代表本插件已实现该协议。
- 参考图会通过本地代理发送到其配置的外部上游，**并非离线推理**。Skill 要求先取得用户对指定图片上传的同意；服务器只知道 MCP 调用者传入了路径，无法独立证明用户同意。默认参考图白名单为空时，调用者可指定任意可读且通过格式/大小校验的图片。建议设置 GPT_IMAGE_REFERENCE_ROOTS 限制读取范围。

## 功能

| MCP 工具 | 作用 |
| --- | --- |
| generate_gpt_image | 文生图或参考图编辑；立即返回 job_id，不把“提交”当成“生成成功” |
| get_image_job | 有界等待 0–30 秒，返回状态、实际尺寸、图片路径；完成时默认提供一次标准 MCP 图片块 |
| cancel_image_job | 取消排队/本地执行，不保证上游退款或立即停止 |
| check_image_backend | 仅查询 /models；不生图、不证明生图权限 |

支持 PNG/JPEG/WebP 输出请求；可输入 PNG/JPEG/WebP/GIF 参考图。一次任务只保存第一张最终图片；若上游返回多张，明确报告数量。

## 下载与安装方式

- **普通用户**：下载 [Releases](https://github.com/naipi11/workbuddy-gpt-image-plugin/releases) 中的 runtime ZIP，已包含构建产物和生产依赖，无需 npm/pnpm 安装或编译。按 [Release 快速开始](<QUICKSTART.md>) 解压、预览、安装；仍需 Node.js ≥22、WorkBuddy 和可用的本地代理。
- **开发者**：克隆仓库或下载 GitHub 自动生成的 Source code 包，按下方步骤安装依赖并构建。
- Release 并非插件运行所必需；它用于提供固定版本、校验和及省去构建的交付物，不代表 WorkBuddy 市场一键导入或 MSI/VSIX 安装器。

## 从源码快速开始

### 1. 准备运行时

需要 Node.js 22 或更高版本、pnpm，以及正在运行的 OpenCodex。在项目根目录安装依赖并构建：

~~~powershell
pnpm install --frozen-lockfile
pnpm run build
pnpm test
~~~

每次全新克隆或下载源码后都需要先安装依赖；Git 仓库不分发 node_modules（runtime Release 包另行包含生产依赖）。完成构建后再运行下面的脚本。不要移动/删除安装器引用的目录；移动后需重新安装。文中的 YOUR_RESPONSES_MODEL_ID 是占位符，必须替换为你的代理实际支持的完整模型 ID。

### 2. 不生图的后端检查

~~~powershell
node scripts/doctor.mjs
~~~

该命令通过真实 MCP stdio 握手列出四个工具，再查询本地代理的模型目录。它不会发起真实生成，也不会修改 WorkBuddy 配置，但会创建本地诊断目录/锁，并可能更新已中断的诊断任务历史；并非完全不写文件。

### 3. 预览安装，再明确应用

~~~powershell
# 默认 dry-run：展示新增项，不写文件
node scripts/install-workbuddy.mjs

# 使用与 WorkBuddy 自定义模型相同的完整代理 ID
node scripts/install-workbuddy.mjs --model "YOUR_RESPONSES_MODEL_ID"

# 确认预览后安装
node scripts/install-workbuddy.mjs --model "YOUR_RESPONSES_MODEL_ID" --apply
~~~

安装器仅合并一个 MCP 条目，并安装独立 Skill：

~~~text
~/.workbuddy/mcp.json                       # 新增 workbuddy-gpt-image，不改其他服务器
~/.workbuddy/skills/workbuddy-gpt-image/SKILL.md
~~~

- 原文件在修改前逐字节备份，文件名附带 backup 时间戳和随机 ID。
- 同名条目或 Skill 内容不同，需要明确 --replace；同样内容重复执行不写入。
- 发现旧 gpt-image-mcp 时只警告，**不会自动停用/覆盖旧服务及旧 gpt-image Skill**。在 WorkBuddy 中自行选择只启用一个，避免同名工具干扰。
- 不写入信任/批准记录，不改变聊天模型设置、OpenCodex 配置或 OAuth 登录。
- 默认使用执行安装器的 Node 路径。可用 --node 指定稳定的 Node.exe 绝对路径。
- 默认图片目录为 ~/WorkBuddy/gpt-image，允许输出范围也仅为该目录。需要写入特定工作区时显式增加 --output-root：

~~~powershell
node scripts/install-workbuddy.mjs --apply --output-root "C:\Users\你的用户名\WorkBuddy"
~~~

### 4. 在 WorkBuddy 内启用

1. 打开“插件 → MCP 服务器 → 配置 MCP”（不同版本名称可能变化）。
2. 检查并信任 workbuddy-gpt-image，确认连接成功、四个工具可见。
3. 启用 workbuddy-gpt-image Skill；重新开启对话，避免旧工具快照。
4. 选择支持工具调用的聊天模型，输入：

> 请使用 workbuddy-gpt-image 插件，通过 GPT 原生生图生成一张白底蓝色圆形图片。不要使用内置生图。等待生成完成后展示真实图片文件。

编辑示例：

> 请用 GPT 原生图片编辑，把我指定的这张图片中的蓝色圆形改成绿色，其他不变，保存为新文件。

插件返回标准 MCP image 内容块及本地路径。Skill 会在客户端实际提供 present_files 时使用它；不支持内嵌图片的版本仍可打开文件。**终端 MCP 成功不等于已完成 WorkBuddy 界面验收**，请以本机实际调用和展示为准。

### 5. 可选：一次真实生图验收

以下命令会消耗上游额度，只生成一次，不自动重试：

~~~powershell
$env:GPT_IMAGE_MAIN_MODEL = "YOUR_RESPONSES_MODEL_ID"
node scripts/doctor.mjs --generate --prompt "纯白背景，中央一个蓝色实心圆形，无文字" --out "test.png"
~~~

编辑验收可加 --reference "图片绝对路径"；--reference 可重复。诊断脚本的历史独立保存在项目 .local/doctor 下，不与 WorkBuddy 实际服务共用状态文件。

## 配置

配置通过 MCP entry 的 env 或进程环境变量提供；**不自动加载 .env 文件**。不需要把 ChatGPT OAuth token 复制给插件。

| 环境变量 | 默认值 / 含义 |
| --- | --- |
| GPT_IMAGE_BASE_URL | http://127.0.0.1:10100/v1；基址不要包含 /responses；运行时允许 HTTPS，安装器仅配置 loopback 代理 |
| GPT_IMAGE_MAIN_MODEL | gpt-5.5；可填完整代理路由 ID，不能凭空剥掉前缀 |
| GPT_IMAGE_IMAGE_MODEL | 未设置为 gpt-image-2；显式空串则不发送 tools[0].model，由上游选取 |
| GPT_IMAGE_SIZE | 1024x1024，请求值而非实测结果 |
| GPT_IMAGE_QUALITY | low；可选择 low/medium/high/auto |
| GPT_IMAGE_OUTPUT_FORMAT | png；可选 jpeg/webp |
| GPT_IMAGE_API_KEY / OPENCODEX_API_KEY | 可选：本地代理的数据接口 key，不是管理员 token 或 ChatGPT OAuth token |
| GPT_IMAGE_API_KEY_FILE | 默认 ~/.workbuddy/models.json；显式空串禁用自动读取 |
| GPT_IMAGE_OUTPUT_DIR | 直接启动为项目 outputs；安装器默认 ~/WorkBuddy/gpt-image |
| GPT_IMAGE_OUTPUT_ROOTS | 允许写出目录列表，Windows 用分号；显式设置时不自动放宽 |
| GPT_IMAGE_REFERENCE_ROOTS | 可选参考图读取白名单；默认只接受调用者显式给定路径，不扫描 |
| GPT_IMAGE_STATE_FILE | 安装器使用 ~/.workbuddy/plugin-data/workbuddy-gpt-image/jobs.json |
| GPT_IMAGE_TOTAL_TIMEOUT_MS | 600000，总执行超时 |
| GPT_IMAGE_CONNECT_TIMEOUT_MS | 30000，等待响应头超时；上游长时间不发响应头时可按实际情况增大 |
| GPT_IMAGE_QUEUE_TIMEOUT_MS | 600000，排队等待超时 |
| GPT_IMAGE_MAX_QUEUE / GPT_IMAGE_CONCURRENCY | 8 / 1 |
| GPT_IMAGE_MAX_RESPONSE_BYTES | 33554432，整个 SSE/JSON 响应大小限制 |
| GPT_IMAGE_MAX_REFERENCE_BYTES / GPT_IMAGE_MAX_REFERENCE_COUNT | 单张 12 MiB / 最多 4 张 |
| GPT_IMAGE_MAX_PREVIEW_BASE64_CHARS | 12000000，超过只返回路径；设 0 禁止预览 |

未显式提供 key 时，仅从与目标基址**同协议、端口、路径、主机**的 WorkBuddy 条目复用。localhost / 127.0.0.1 / ::1 仅在其他条件一致时等价。禁止 HTTP 远程明文、URL 内嵌凭据、认证重定向；不会把任意旧 key 发给新端点。

省略图片模型参数的安装示例：

~~~powershell
node scripts/install-workbuddy.mjs --image-model "" --apply
~~~

参考图读取白名单示例（设置到 MCP entry 的 env 中，仅允许你批准的目录）：

~~~json
{ "GPT_IMAGE_REFERENCE_ROOTS": "C:\\Users\\YOUR_NAME\\Pictures\\approved-for-upload" }
~~~

## 安全与任务语义

- 所有任务在本地异步执行；生成失败、断流、超时和取消均不自动重新提交。
- 只有完整成功的 Responses 终止事件和最终图片结果才可成功；失败事件优先于已收到的图片片段。
- Base64 严格解码、格式/尺寸/结构检查，PNG 额外核对 CRC；**结构检查不是完整像素解码器**。
- 输出白名单基于真实路径，已有文件不覆盖；实际格式与扩展名不符时纠正并说明。
- 文件使用同目录临时文件 + 独占硬链接发布，需要支持硬链接的文件系统（如 NTFS）。不支持的网络盘/FAT 盘请改用本地 NTFS 输出目录。
- 日志仅写 stderr、脱敏且有长度限制；stdout 只承载 MCP。
- **任务历史包含提示词、指令、参考图路径和结果路径**，不含图片 Base64 或 API key。历史未自动过期；如有敏感内容，在停止服务后自行清理历史及生成文件。
- 初始状态写入失败时不发送收费请求；生成后的状态持久化失败会明确警告，已生成图片不因此自动重发。
- 同一状态文件只允许一个 MCP 进程写入。多实例使用独立 GPT_IMAGE_STATE_FILE；进程中断后旧任务标记 interrupted，不自动恢复生成。
- 正常退出释放锁；已确认死亡的所有者锁可回收。若启动瞬间崩溃留下 .lock.guard，须确认所有实例已退出后手动移除该 guard；程序不会冒险强行抢锁。损坏历史会阻止启动，不会被静默清空。

## 可选的原生插件打包

[插件清单](<.codebuddy-plugin/plugin.json>)、[原生 MCP 配置](<.mcp.json>)、[Skill](<skills/gpt-image/SKILL.md>) 和 [斜杠命令](<commands/gpt-image.md>) 遵循共享 CodeBuddy 插件布局。原生配置使用 CODEBUDDY_PLUGIN_ROOT / CODEBUDDY_PLUGIN_DATA，依赖安装目录中存在构建产物及依赖。

这是为插件市场/原生载入准备的源代码布局；**不同 WorkBuddy 版本的本地包导入、DATA 变量解析、命令注册尚须界面验证**。推荐先使用上面的 MCP+Skill 安装器，不要两条路径同时安装。不承诺 zip/VSIX 双击导入或自定义 GUI 面板。

## 故障排查

| 现象 | 检查 |
| --- | --- |
| 工具不可见 | MCP 信任/启用、Node 路径、dist 构建、重新开启会话；不要篡改批准文件 |
| /models 成功但没有图片 | 账号/主模型是否支持 hosted image_generation；查看任务错误，不把文本当图片 |
| HTTP 401/403 | 本地数据接口认证、上游账号授权/限额；不要改用管理员 token |
| HTTP 400 或 unknown tool/model | 路由及图片参数；上游不支持时明确报错，不擅自切供应商 |
| HTTP 502、超时、截断 | OpenCodex 与上游连接；告知可能已计费，用户确认后才重试 |
| 输出路径越界 | 显式添加目标工作区到 GPT_IMAGE_OUTPUT_ROOTS，不自动放开全磁盘 |
| 图片不内联显示 | 使用返回的真实文件路径/客户端文件展示工具；不要再次生图 |
| 状态锁冲突 | 关闭旧实例或使用独立状态文件，避免同时启用两份插件 |

卸载：在 WorkBuddy 停用此服务，仅移除 workbuddy-gpt-image MCP 条目及对应独立 Skill。保留其他配置；是否删除历史/输出由用户决定。备份包含原配置，恢复前检查是否会覆盖后来新增的其他 MCP。

## 许可证与发布构建

本项目采用 [MIT License](<LICENSE>)，允许在保留版权和许可声明的条件下使用、修改、分发和商业使用，不提供担保。第三方依赖保留其各自的许可证，不因本项目采用 MIT 而改变。

Release 的制作流程、内容白名单和验证方法见 [发布说明](<docs/RELEASE.md>)。

## 验证与参考资料

- [本次验收记录](<docs/ACCEPTANCE.md>)：分别记录离线、真实代理与 WorkBuddy 界面状态。
- [WorkBuddy MCP 官方指南](https://www.workbuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/MCP-Guide)
- [共享插件清单与目录规范](https://www.codebuddy.cn/docs/cli/plugins-reference)
- [OpenAI Responses 图片生成工具](https://developers.openai.com/api/docs/guides/tools-image-generation.md)
- [OpenCodex 原生 Image 路由源码，2.84.0](https://github.com/lidge-jun/opencodex/blob/v2.84.0/src/server/images.ts)
- [OpenCodex Image Bridge：与原生 GPT 不同的上游桥接](https://opencodex.me/guides/image-bridge/)