# 安装 VORTEX API 生图技能包

本技能提供独立脚本，需要 Node.js 18+ 或 Python 3。客户端必须支持读取技能说明和执行本地命令；普通网页聊天窗口不能直接安装。下文提供 Codex、Claude Code 的安装位置，其他客户端需按其版本确认技能加载方式。

Node.js 调用使用 `node -- <脚本路径> ...`；`--` 防止运行时提前处理脚本的 `--env-file` 参数，确保密钥优先级由脚本决定。

推荐让当前 Agent 按本页完成安装，密钥由用户在本地配置。安装后先免费检查鉴权，再按用户意愿生成一张计费的示例图片，以验证实际生成、保存和展示流程。

## 1. 下载完整 ZIP

不要逐文件复制，也不要把目录 URL 当作可递归下载地址。完整安装包：

```text
https://vortexapi.xyz/skill/image-gen.zip
```

macOS/Linux 下载示例：

```bash
tmp_dir="$(mktemp -d)"
curl -fsSL "https://vortexapi.xyz/skill/image-gen.zip" -o "$tmp_dir/image-gen.zip" &&
  unzip -tq "$tmp_dir/image-gen.zip"
```

Windows PowerShell 下载示例：

```powershell
$ErrorActionPreference = 'Stop'
$downloadDir = Join-Path $env:TEMP ([guid]::NewGuid().ToString())
New-Item -ItemType Directory $downloadDir | Out-Null
$archive = Join-Path $downloadDir 'image-gen.zip'
Invoke-WebRequest 'https://vortexapi.xyz/skill/image-gen.zip' -OutFile $archive
```

ZIP 内已经包含完整的 `image-gen/` 目录，解压后必须保持目录结构不变。下载或校验失败时立即停止，不执行替换步骤。下面的安装命令接续同一终端中的下载步骤。不要直接从源码目录复制：源码中的站点占位符由下载接口替换。

升级时，先确认服务端已部署目标版本，再重新下载完整 ZIP，并按下方步骤备份、替换和验收。包内默认 API 地址优先取服务端配置的站点地址，可能与下载使用的域名不同；需要指定其他已确认的服务地址时使用 `--base-url`。

## 2. 安装到当前客户端

### Codex

推荐位置：

```text
~/.agents/skills/image-gen
```

macOS/Linux：

```bash
(
  set -eu
  skills_dir="$HOME/.agents/skills"
  mkdir -p "$skills_dir"
  stage_dir="$(mktemp -d "$skills_dir/.image-gen-install.XXXXXX")"
  unzip -q "$tmp_dir/image-gen.zip" -d "$stage_dir"
  for file in SKILL.md INSTALL.md package.json agents/openai.yaml scripts/node/image-gen.js scripts/python/image_gen.py references/api-recipes.md; do
    test -s "$stage_dir/image-gen/$file"
  done
  backup_dir=""
  if [ -e "$skills_dir/image-gen" ] || [ -L "$skills_dir/image-gen" ]; then
    mkdir -p "$HOME/.config/vortex-api/skill-backups"
    backup_dir="$(mktemp -d "$HOME/.config/vortex-api/skill-backups/image-gen.XXXXXX")"
    mv "$skills_dir/image-gen" "$backup_dir/image-gen"
    echo "旧版本已备份到：$backup_dir/image-gen"
  fi
  if ! mv "$stage_dir/image-gen" "$skills_dir/image-gen"; then
    if [ -n "$backup_dir" ]; then
      mv "$backup_dir/image-gen" "$skills_dir/image-gen"
    fi
    exit 1
  fi
  rmdir "$stage_dir"
)
```

Windows PowerShell：

```powershell
$ErrorActionPreference = 'Stop'
$skills = Join-Path $HOME '.agents\skills'
New-Item -ItemType Directory -Force $skills | Out-Null
$stage = Join-Path $skills ('.image-gen-install.' + [guid]::NewGuid().ToString())
Expand-Archive -Path $archive -DestinationPath $stage
$source = Join-Path $stage 'image-gen'
foreach ($file in @('SKILL.md', 'INSTALL.md', 'package.json', 'agents/openai.yaml', 'scripts/node/image-gen.js', 'scripts/python/image_gen.py', 'references/api-recipes.md')) {
    $item = Get-Item -LiteralPath (Join-Path $source $file)
    if ($item.PSIsContainer -or $item.Length -eq 0) { throw "安装包文件无效：$file" }
}
$target = Join-Path $skills 'image-gen'
$backup = $null
if (Test-Path -LiteralPath $target) {
    $backup = Join-Path $env:APPDATA ('vortex-api\skill-backups\' + [guid]::NewGuid().ToString() + '\image-gen')
    New-Item -ItemType Directory -Force (Split-Path $backup) | Out-Null
    Move-Item -LiteralPath $target -Destination $backup
    Write-Output "旧版本已备份到：$backup"
}
try {
    Move-Item -LiteralPath $source -Destination $target
} catch {
    if ($backup) { Move-Item -LiteralPath $backup -Destination $target }
    throw
}
Remove-Item -LiteralPath $stage
```

备份放在技能扫描目录之外，避免重复加载。如果 `~/.codex/skills/image-gen` 也存在，先核对其 `SKILL.md` 和脚本是否属于本技能；确认后将其移至上述备份目录，保留自定义内容，不直接删除或覆盖其他同名技能。安装失败时保留临时目录用于排查。

### Claude Code

安装到用户级技能目录：

```text
~/.claude/skills/image-gen
```

按上述临时解压、验证、备份和替换流程安装，将目标目录改为 `~/.claude/skills`，确保最终文件为 `~/.claude/skills/image-gen/SKILL.md`。

### OpenClaw、Hermes 和 OpenCode

这些客户端的技能目录及加载机制可能随版本变化，本包未逐一验证自动发现流程。先查阅当前客户端文档，再安装完整目录；不要把 skill、rule 和 knowledge 目录视为可互换。无法自动加载时，可让 Agent 读取 `SKILL.md` 的绝对路径并调用配套脚本。

### 其他客户端

只要客户端能够读取 `SKILL.md` 并执行本地命令，就可以直接保留完整的 `image-gen/` 目录，并使用绝对路径调用：

```bash
node -- /absolute/path/to/image-gen/scripts/node/image-gen.js --doctor
```

安装或更新后新建会话，让客户端重新加载技能。

## 3. 配置专用 Key

1. 打开 [https://vortexapi.xyz/keys](https://vortexapi.xyz/keys)。
2. 创建 **《生图专用》** 分组的密钥。
3. 在客户端环境变量设置或下述本地文件中填写 `IMAGE_GEN_API_KEY=你的密钥`。
4. Agent 检查配置是否可用，不读取并展示完整密钥。若用户已主动提供密钥，可按其要求保存，但不得在回复、日志或验证输出中回显。

所有客户端统一使用 `IMAGE_GEN_API_KEY`，不使用 `OPENAI_API_KEY`。

推荐持久化位置：

- macOS/Linux：`~/.config/vortex-api/.env`。
- Windows：`%APPDATA%\\vortex-api\\.env`。

Agent 写入时必须保留文件中的其他配置，只新增或替换 `IMAGE_GEN_API_KEY` 一行；macOS/Linux 文件权限设为 `600`。项目目录 `.env` 也可使用，但必须加入 `.gitignore`。

客户端若支持环境变量设置，也可以直接配置同名变量：

```bash
# macOS/Linux
export IMAGE_GEN_API_KEY='你的密钥'
```

```powershell
# Windows PowerShell
$env:IMAGE_GEN_API_KEY = '你的密钥'
```

## 4. 默认路由适配（可选）

如果用户要求普通的“生图、生成图片、图生图、编辑图片”默认使用 VORTEX，Agent 应在当前客户端支持的全局规则或用户指令中加入等价规则：

```text
生成或编辑图片时优先使用 image-gen Skill 及其内置脚本。
调用失败时不得静默切换到客户端内置图片工具或其他提供方。
成功后使用绝对路径展示生成结果。
```

### Codex 全局规则

仅在用户要求设为默认生图方式时，幂等更新 `~/.codex/AGENTS.md` 中以下托管区块；已有区块应整体替换，不得重复追加：

```markdown
<!-- vortex-image-gen:start -->
## VORTEX 默认生图

当用户请求生成或编辑图片时，优先使用 `$image-gen` 及其内置 Node.js/Python 脚本。
除非用户明确要求，否则不要调用内置 `imagegen` 或 `image_gen`。
VORTEX 调用失败时不得静默切换提供方，应返回原始结构化错误。
成功后将图片保存到用户指定位置，并使用绝对路径展示。
<!-- vortex-image-gen:end -->
```

`agents/openai.yaml` 是 Codex/OpenAI 风格的可选界面和调用元数据，不是其他客户端运行本技能的前置条件。

默认路由属于客户端偏好；显式调用技能最可靠。项目级指令或客户端更高优先级规则仍可能覆盖该偏好。

## 5. 安装验收

安装后使用技能目录的绝对路径运行任一脚本的 `--doctor`。它只请求 `/v1/models`，检查鉴权和目标模型可见性（默认 `gpt-image-2`），不生成图片：

```bash
SKILL_DIR="/absolute/path/to/image-gen"
node -- "$SKILL_DIR/scripts/node/image-gen.js" --doctor
python3 "$SKILL_DIR/scripts/python/image_gen.py" --doctor
node -- "$SKILL_DIR/scripts/node/image-gen.js" --doctor --model gpt-image-2.5-sunburst
```

成功结果包含：

```json
{ "ok": true, "mode": "doctor", "model": "gpt-image-2", "baseUrl": "https://vortexapi.xyz" }
```

未执行真实生图时，只能报告“安装、鉴权和模型可见性检查通过”；不能据此确认渠道可用、余额充足或生图链路正常。

### 可选：生成一张示例图片（会计费）

建议用一张示例图片验证完整流程。先说明这会按平台规则计费；用户的安装请求若已明确包含示例生图，直接执行，无需重复确认。仅要求安装或免费检查时，先询问是否执行此步骤。

在用户指定的输出目录中选择不覆盖已有文件的路径，只运行一次：

```bash
node -- "$SKILL_DIR/scripts/node/image-gen.js" --mode text --prompt "一只戴着宇航员头盔的橘猫，漂浮在星空中，简洁插画，无文字" --n 1 --out /absolute/output/path/vortex-example.png
```

没有 Node.js 时，将命令入口替换为 `python3 "$SKILL_DIR/scripts/python/image_gen.py"`，参数不变。读取成功 JSON 的 `paths`，确认文件存在且可打开，再用绝对路径展示图片。报告实际文件位置；只有这些检查完成后，才说明实际生图流程通过。

失败时展示结构化错误并停止，不自动重复计费请求，也不切换提供方。超时不代表服务端未执行或未计费，应先检查平台记录。`incomplete_image_result` 的 `detail.paths` 包含已经保存的部分结果。

## 6. 通用 Agent 安装请求模板

用户可以直接发送：

```text
请根据 https://vortexapi.xyz/skill/image-gen/INSTALL.md，为你当前所在的 Agent 客户端安装完整 image-gen Skill。
请先验证安装包，备份已有版本并保留其他配置。
指导我在本地配置 IMAGE_GEN_API_KEY，不要打印密钥。
安装后运行 --doctor。我同意按平台规则计费，再生成一张太空猫示例图片，保存并展示结果；失败时停止，不自动重试。
```

若只需免费检查，把最后一句改为“安装后只运行 --doctor，不执行计费生图”。若希望默认使用本技能，可追加“请将 VORTEX 配置为默认生图方式”。

## 7. 使用示例

```bash
SKILL_DIR="/absolute/path/to/image-gen"
node -- "$SKILL_DIR/scripts/node/image-gen.js" --mode text --prompt "生成一张太空猫" --out ./cat.png
node -- "$SKILL_DIR/scripts/node/image-gen.js" --mode image --image ./reference.png --out ./variation.png
node -- "$SKILL_DIR/scripts/node/image-gen.js" --mode image-prompt --prompt "融合两张参考图" --image ./a.png --image ./b.png --out ./result.png
node -- "$SKILL_DIR/scripts/node/image-gen.js" --model gpt-image-2.5-sunburst --stream false --prompt "生成一张太空猫" --out ./sunburst.png
```

三个模式默认使用 `gpt-image-2`，可用 `--model` 指定其他图片模型。文生图调用 `/v1/images/generations`；图生图和文+图生图调用 `/v1/images/edits`。默认 `--stream true`，使用 `--stream false` 请求非流式 JSON；两种响应均由脚本保存图片。模型配置快照与验证边界见 [SKILL.md](SKILL.md#模型与响应方式)。示例中的模型、尺寸、质量和张数不构成上游能力保证。

## 8. 常见问题文案

问题：如何安装生图 Skill，让 AI 助手生成或编辑图片？

以下答案可复制到站点 FAQ（低于 1000 字符）：

````markdown
生图 Skill 支持文生图和参考图编辑，需要可执行本地命令的 AI 助手，以及 Node.js 18+ 或 Python 3。

1. 前往 [密钥管理](https://vortexapi.xyz/keys)，创建「生图专用」分组的 Key，配置为 `IMAGE_GEN_API_KEY`。建议在本地填写，不要提交到代码仓库。
2. 将下面的指令发送给 AI 助手：

```text
请阅读 https://vortexapi.xyz/skill/image-gen/INSTALL.md，为当前客户端安装完整 image-gen Skill。
先验证安装包，备份旧版本并保留其他配置。
指导我在本地配置 IMAGE_GEN_API_KEY，不要打印密钥。
安装后运行 --doctor。我同意按平台规则计费，再生成一张太空猫示例图片，保存并展示；失败时停止，不自动重试。
```

只需免费检查时，将最后一句改为“安装后只运行 --doctor，不执行计费生图”。`--doctor` 通过不代表实际生图已验证。

安装后新建会话，发送“请使用 image-gen 生成图片”即可；编辑图片时附上参考图及修改要求。希望默认使用本技能时，可让助手配置默认生图规则。

[完整技能包](https://vortexapi.xyz/skill/image-gen.zip) · [安装说明](https://vortexapi.xyz/skill/image-gen/INSTALL.md)
````