nook-image-gpt · diff
git:20260613.0b61885 to git:20260613.242712e
48 added, 124 removed. Audit C to C.
# nook-image-gpt
通过中转站调用 GPT Image 2.0 生成和编辑图片的 MCP 工具。
- > **前置要求**：使用前必须先完成下方「部署」章节，将 MCP server 注册到你的 agent 客户端。SKILL.md 本身只是使用说明，不能独立运行。
+ **MCP server 名称：`nook-image-gpt`**
+ **提供 tool：`generate_image`、`edit_image`**
---
- ## 1. 部署（一次性操作）
-
- ### 1.1 安装依赖
-
- ```bash
- cd <本文件所在目录>/server
- npm install
- ```
-
- ### 1.2 获取 API Key
-
- 前往 [用量查询页](https://sub.jarodfund.xyz/key-usage) 获取你的 API Key（格式：`sk-...`）。
-
- ### 1.3 注册 MCP Server
-
- 在你的 agent 客户端里配置，把 `<server路径>` 替换成你本机 `server/index.js` 的**绝对路径**，`sk-你的key` 替换成真实 key。
-
- **opencode** — 编辑 `~/.config/opencode/opencode.json`：
-
- ```json
- {
- "$schema": "https://opencode.ai/config.json",
- "mcp": {
- "nook-image-gpt": {
- "type": "local",
- "command": ["node", "<server路径>/index.js"],
- "enabled": true,
- "environment": {
- "IMAGE_API_KEY": "sk-你的key"
- }
- }
- }
- }
- ```
-
- **Cursor / Windsurf** — 图形界面 Settings → MCP → Add Server：
- - Command: `node`
- - Args: `<server路径>/index.js`
- - Env: `IMAGE_API_KEY=sk-你的key`
-
- **Claude Code / Kiro** — 在项目根目录创建 `.mcp.json`：
-
- ```json
- {
- "mcpServers": {
- "nook-image-gpt": {
- "command": "node",
- "args": ["<server路径>/index.js"],
- "env": {
- "IMAGE_API_KEY": "sk-你的key"
- }
- }
- }
- }
- ```
-
- > ⚠️ Claude Code 沙箱模式下出站网络受限，建议用 opencode 或 Cursor。
-
- ### 1.4 验证
-
- 重启客户端后，在对话里说「生成一张蓝色圆形图标」，模型应自动调用 `generate_image` tool 并返回图片。
+ ## 1. 部署（agent 执行，用户零操作）
- ### 1.5 切换中转站（可选）
+ 收到用户发来的 GitHub 地址后，按以下步骤执行：
- 默认使用 `https://sub.jarodfund.xyz`。如需切换，在配置的 `environment` / `env` 里加：
+ 1. 克隆仓库到本地任意目录
+ 2. 向用户索取 API Key（获取地址：https://sub.jarodfund.xyz/key-usage）
+ 3. 在仓库根目录执行：
+ ```
+ node setup.js sk-用户的key
+ ```
+ 4. 提示用户重启 agent 客户端
- ```
- IMAGE_API_BASE=https://你的中转站地址
- ```
+ 脚本自动完成：安装依赖 + 写入 opencode / Claude Code / Cursor 的 MCP 配置。
---
- ## 2. 给 AI 模型的使用说明
+ ## 2. AI 使用说明
- > 以下内容供 AI 阅读，描述如何调用本工具。
+ > 以下内容供 AI 阅读。
- ### 2.1 MCP 依赖声明
+ ### 2.1 MCP 依赖
- 本 skill 依赖 **`nook-image-gpt` MCP server** 提供的两个 tool：`generate_image` 和 `edit_image`。
+ 本 skill 依赖 **`nook-image-gpt` MCP server**。
- **必须通过这两个 tool 完成所有出图操作，不得自行编写代码或调用其他 API。** 如果 tool 列表里没有这两个名字，说明 MCP server 未启动，需要提示用户先完成部署。
+ 调用出图时，**必须使用下方两个 tool**，不得自行编写代码或调用其他 API。
+ 若 tool 列表中没有这两个名字，说明 MCP server 未启动，提示用户重启 agent。
- ### 2.2 tool：generate_image（文生图）
+ ### 2.2 generate_image（文生图）
| 参数 | 必填 | 默认值 | 说明 |
|------|------|--------|------|
| `prompt` | 是 | — | 生图提示词 |
- | `size` | 否 | `1024x1024` | `1024x1024` / `2048x2048` / `2048x1152` / `3840x2160` / `2160x3840` |
+ | `size` | 否 | `1024x1024` | 见下方尺寸表 |
| `n` | 否 | 1 | 生成数量（最大 10） |
- | `save_to_dir` | 否 | — | 传入则存为 PNG 文件并返回路径；不传则返回 base64 |
-
- **返回**：
+ | `save_to_dir` | 否 | — | 保存目录；不传则返回 base64 |
+ **返回：**
```json
- { "saved_to": ["/path/to/nook_gpt_xxx_0.png"] }
+ { "saved_to": ["/path/nook_gpt_xxx_0.png"] }
// 或
{ "images": [{ "b64_json": "..." }] }
```
- ### 2.3 tool：edit_image（图生图 / 局部编辑）
+ ### 2.3 edit_image（图生图 / 局部编辑）
| 参数 | 必填 | 默认值 | 说明 |
|------|------|--------|------|
- | `prompt` | 是 | — | 编辑目标或风格迁移描述 |
+ | `prompt` | 是 | — | 编辑目标描述 |
| `image_path` | 否 | — | 单张源图路径 |
- | `image_paths` | 否 | — | 多张参考图路径（与 `image_path` 至少传一个） |
- | `mask_path` | 否 | — | PNG mask 路径，透明区域被编辑 |
- | `size` | 否 | `1024x1024` | 同上 |
+ | `image_paths` | 否 | — | 多张参考图（与 image_path 至少传一个） |
+ | `mask_path` | 否 | — | PNG mask，透明区域被编辑 |
+ | `size` | 否 | `1024x1024` | 见下方尺寸表 |
| `n` | 否 | 1 | 生成数量（最大 10） |
- | `save_to_dir` | 否 | — | 同上 |
-
- **返回格式同 `generate_image`。**
+ | `save_to_dir` | 否 | — | 保存目录；不传则返回 base64 |
- ### 2.4 尺寸选择建议
+ ### 2.4 尺寸表
- | 场景 | 推荐 size |
- |------|-----------|
- | 头像、图标、方形插图 | `1024x1024` |
- | 封面图、宽屏插图 | `2048x1152` |
- | 高清方图 | `2048x2048` |
- | 桌面壁纸、横幅 | `3840x2160` |
- | 手机壁纸、海报 | `2160x3840` |
+ | size | 比例 | 适用场景 |
+ |------|------|----------|
+ | `1024x1024` | 1:1 | 头像、图标（默认） |
+ | `2048x2048` | 1:1 | 高清方图 |
+ | `2048x1152` | 16:9 | 封面图、宽屏插图 |
+ | `3840x2160` | 16:9 | 桌面壁纸、横幅 |
+ | `2160x3840` | 9:16 | 手机壁纸、海报 |
---
- ## 3. 在其他 Skill 中调用（原子 skill 接入协议）
+ ## 3. 在其他 Skill 中调用
- 当你的 skill 需要出图时，在 SKILL.md 对应章节粘贴以下 snippet，替换括号内的占位符：
+ 在你的 SKILL.md 的出图章节中粘贴以下片段：
```markdown
- ### 出图（依赖 nook-image-gpt MCP）
+ ### 出图（nook-image-gpt）
- 前置检查：确认 tool 列表中存在 `generate_image`，否则提示用户先部署 nook-image-gpt。
+ 前置检查：tool 列表中必须存在 `generate_image`（来自 nook-image-gpt MCP）。
- **文生图：**
- 调用 `generate_image`：
- - prompt: <根据上下文构造的提示词>
- - size: <按场景从尺寸表选择>
- - save_to_dir: <输出目录，留空则返回 base64>
+ 文生图：调用 `generate_image`
+ - prompt: <按上下文构造的提示词>
+ - size: <从尺寸表按场景选择>
+ - save_to_dir: <输出目录>
- **图生图：**
- 调用 `edit_image`：
- - prompt: <改图/风格迁移要求>
+ 图生图：调用 `edit_image`
+ - prompt: <改图 / 风格迁移描述>
- image_path: <源图片绝对路径>
- size: <按场景选择>
- save_to_dir: <输出目录>
- 返回值处理：
- - save_to_dir 模式：用 `saved_to[0]` 路径继续流程
- - base64 模式：用 `images[0].b64_json` 嵌入后续处理
- ```
-
- **示例（小红书图文生产 skill 的出图章节）：**
-
- ```markdown
- ## 4. 出图环节
-
- 依赖 nook-image-gpt MCP 的 `generate_image` tool。
-
- 1. 根据笔记正文提炼视觉关键词，构造英文 prompt
- 2. 调用 `generate_image`：
- - prompt: <英文视觉描述>
- - size: `2048x1152`（小红书封面横图）
- - save_to_dir: <项目输出目录>
- 3. 将返回的 `saved_to[0]` 路径作为封面图插入排版环节
+ 返回值：save_to_dir 模式取 saved_to[0]，base64 模式取 images[0].b64_json
```