pi-subscription-image

English

一个 Pi 图片生成扩展：统一提供 generate_image_with_subscription 工具，使用现有 OpenAI Codex 与 xAI Grok 订阅账户额度生成或编辑图片。

为什么需要它

不同生图扩展通常会注册不同工具，并使用不同的参数、保存路径和返回格式。这个包提供一个稳定入口，按当前 Pi 会话自动路由，并把生成图片统一以内联图片返回。

功能

• 复用 Pi 的 openai-codex OAuth 登录生成 Codex 图片。
• 复用 Pi 的 xai 订阅登录调用 Grok Imagine。
• 提供 generate_image_with_subscription 工具和 /img 命令。
• openai-codex/* 会话自动选择 Codex，xai/* 会话自动选择 Grok。
• 其他模型会话可显式传入 provider=codex 或 provider=grok。
• 单次调用可顺序生成 1–4 张图片，避免并发消耗配额；后续某张失败时，仍返回已经生成的图片。
• Codex 支持最多 5 张 PNG、JPEG 或 WebP 参考图编辑。
• 统一支持 none、project、global、custom 保存模式。
• 即使可选的磁盘保存失败，仍返回已经生成成功的内联图片。
• 包含严格的 base64、MIME、超时、重试和响应校验。
• 不自行保存凭据，不发送遥测。

Provider 能力

能力	Codex	Grok
认证	Pi openai-codex OAuth	Pi xai 订阅登录
文生图	支持	支持
参考图编辑	支持，最多 5 张	当前未开放
输出格式	PNG、JPEG、WebP	Provider 决定，按返回字节检测
图片比例	写入 Prompt 约束	原生请求参数
分辨率	后端决定	1k、2k，默认 1k
质量等级	当前未开放	low、medium，仅 Imagine 2.0
默认模型	gpt-5.6-sol 路由，当前已知后端 gpt-image-2	grok-imagine-image-2.0

安装

首次发布后可从 npm 安装：

pi install npm:@specode/pi-subscription-image

本地开发阶段可临时试用：

pi --no-extensions --offline -e /path/to/pi-subscription-image

安装后重启 Pi 或执行 /reload。

登录

使用 Pi 原生登录命令：

/login

• Codex：选择 ChatGPT Plus/Pro (Codex)。
• Grok：选择 xAI 的 X Premium 或 SuperGrok 订阅登录。

可在不展示凭据的前提下检查状态：

/subscription-image status

使用

自然语言：

生成一张月球科研站日出时分的电影感 16:9 图片。

直接命令：

/img 一枚红熊猫扁平矢量图标

模型会调用 generate_image_with_subscription，参数如下：

参数	说明
prompt	必填，图片描述或编辑指令
provider	auto、codex 或 grok
model	Codex 路由模型或 Grok Imagine 图片模型
aspectRatio	通用图片比例约束
n	顺序生成 1–4 张
outputFormat	仅 Codex：png、jpeg、webp；Grok 的实际格式由 Provider 决定
resolution	仅 Grok：1k 或 2k，默认 1k
quality	仅 Grok Imagine 2.0：low 或 medium；默认不发送，由 Provider 决定
save	none、project、global 或 custom
saveDir	save=custom 时的目录
referencedImagePaths	Codex 最多 5 张本地参考图
numLastImagesToInclude	Codex 使用最近的会话图片进行编辑

支持以下参数别名：

• provider=openai 映射为 codex。
• provider=xai 映射为 grok。
• 旧的 aspect_ratio 会在校验前映射为 aspectRatio。

Codemode

在支持工具 outputSchema / structuredContent 的 Pi 版本中，可通过 codemode 调用同一个工具。直接工具调用与 /img 的行为不变。

const result = await tools.generate_image_with_subscription({
  prompt: "一只水彩风格的红熊猫",
});
for (const block of result.output) {
  if (block.type === "image") image(block);
  else text(block.text);
}

脚本收到 { provider, model, output, generationErrors, savedPaths, saveWarnings }。output 包含文本块和可直接传给 image() 的 base64 图片块。即使使用 save: "none" 或可选的磁盘保存失败，也会返回图片；保存错误见 saveWarnings。参数校验失败（包括 save=custom 未提供目录）会在消耗配额前 reject。第一张图片生成失败或调用被取消时，工具调用同样会 reject；启用保存时，取消前已经生成的图片仍会保存。多图请求中后续某张失败时，会停止生成并返回已经生成的图片，失败原因见 generationErrors。

不要用 text()、console 或 return 输出整个结果或 base64 数据，应使用 image(block) 展示图片。Pi codemode 单个脚本的输出上限为 16 MiB，base64 图片数据计入其中，多张较大的 Codex PNG 可能导致脚本失败。建议像示例一样保留默认保存，让图片在脚本展示前已写入磁盘；Codex 多图请求优先使用 outputFormat: "webp" 或 "jpeg"。生成可能需要数分钟，避免设置过短的脚本超时。这是现有订阅工具的适配，不是 models.generateImages() 接口。旧版 Pi 若不支持结构化工具结果，仍可直接调用工具，但无法把图片传入 codemode 脚本。

自动路由

没有指定 provider，或使用 provider=auto 时：

1. 有参考图输入时选择 Codex。
2. 当前会话为 openai-codex/* 时选择 Codex。
3. 当前会话为 xai/* 时选择 Grok。
4. 如果配置了 defaultProvider，则使用该值。
5. 否则要求显式指定 provider，避免误消耗订阅额度。

保存位置

模式	位置
none	只返回内联图片
project	<cwd>/.pi/generated-images/
global	~/.pi/agent/generated-images/
custom	saveDir 或配置目录

默认保存模式为 global。

配置

全局配置：

~/.pi/agent/extensions/subscription-image.json

可信项目配置：

<project>/.pi/extensions/subscription-image.json

只有项目处于可信状态时，项目配置才会覆盖全局配置。

{
  "defaultProvider": "codex",
  "save": "global",
  "saveDir": "~/Pictures/generated",
  "providers": {
    "codex": {
      "routingModel": "gpt-5.6-sol",
      "outputFormat": "png"
    },
    "grok": {
      "imageModel": "grok-imagine-image-2.0",
      "resolution": "1k"
    }
  }
}

providers.grok.quality 可设为 low 或 medium；省略时不向 xAI 发送该字段。旧的 codexRoutingModel 和 grokImageModel 配置仍兼容。全局与可信项目的 providers.codex、providers.grok 会分别深度合并。

真正统一的参数是 prompt、provider、model 覆盖入口、aspectRatio、n、save 和 saveDir。Provider 特有参数保持显式：Codex 使用 outputFormat 和参考图输入；Grok 使用 resolution、quality。扩展不会默认改写或润色 Prompt；只有 Codex 的比例要求会以确定性约束追加到 Prompt。

环境变量：

• PI_SUBSCRIPTION_IMAGE_PROVIDER
• PI_SUBSCRIPTION_IMAGE_SAVE_MODE
• PI_SUBSCRIPTION_IMAGE_SAVE_DIR
• PI_SUBSCRIPTION_IMAGE_CODEX_MODEL
• PI_SUBSCRIPTION_IMAGE_CODEX_OUTPUT_FORMAT
• PI_SUBSCRIPTION_IMAGE_GROK_MODEL
• PI_SUBSCRIPTION_IMAGE_GROK_RESOLUTION
• PI_SUBSCRIPTION_IMAGE_GROK_QUALITY
• PI_SUBSCRIPTION_IMAGE_GROK_BASE_URL

同时支持 PI_IMAGE_SAVE_MODE 和 PI_IMAGE_SAVE_DIR。

安全和服务边界

• 这是非官方社区扩展。
• 凭据只通过 Pi provider registry 解析，不写入本包自己的存储。
• Prompt 和参考图会发送到选择的 Provider。
• Codex 使用 ChatGPT Codex Responses 后端的内置 image_generation 工具。
• Grok 使用 xAI 图片生成接口。
• 订阅可用性、额度、地区限制和服务条款仍由对应 Provider 决定。
• Provider 后端发生变化时，可能需要升级本包。

开发

npm install
npm test
npm run smoke
npm run check

推送到 main 和 Pull Request 会运行类型检查、测试、Pi 加载 smoke 与包内容校验。npm 发布流程沿用 OIDC Trusted Publishing：创建 GitHub Release 后会重复这些检查，再通过 OIDC 发布，不保存长期 npm token。

许可证

MIT。实现参考和第三方归属见 THIRD_PARTY_NOTICES.md。