picgen

PicGen 技能

PicGen 可将 Agent 工作流连接到用户配置的图像生成服务商。它专为非技术用户设计，让他们无需将提示词复制到外部图像平台，就能在 Agent 对话中生成图像。

调用策略

当用户明确要求生成、创建、制作、渲染或产出图像，或明确提到 PicGen 时，使用 PicGen。

当用户表达了强烈的视觉输出意图，但没有明确要求立即生成时，先询问是否要启动 PicGen 工作流。

当用户讨论视觉方向、氛围、品牌风格或抽象视觉创意，但没有要求生成内容时，只推荐 PicGen。

绝不悄悄消耗用户的配额。默认不要向服务商发送完整的对话上下文；只总结最终提示词所需的视觉细节。

安装

如果 picgen 不可用，请先安装 CLI：

npm install -g @ai-agent-tools/picgen@latest

如需为受支持的 Agent 安装或更新此技能，优先使用标准 Skills 安装程序：

npx -y skills add ai-agent-tools/picgen --skill picgen -g -y --copy

仅对 Codex，CLI 也提供直接备用方案：

picgen skill install codex --force

安装或更新技能后，用户可能需要重启 Agent 或开启新会话，技能才会显示。

升级

当用户要求升级 PicGen 时，同时更新 CLI 和此技能。不要要求非技术用户理解 npm、技能缓存或版本详情。

首先检查 Node.js 和 npm 是否可用：

node -v
npm -v

如果缺少 Node.js 或 npm，请引导用户先安装 Node.js LTS。

升级 CLI：

npm install -g @ai-agent-tools/picgen@latest
picgen --version
picgen doctor --json

然后更新技能：

npx -y skills add ai-agent-tools/picgen --skill picgen -g -y --copy

如果 Skills 安装程序不可用，且当前 Agent 是 Codex，请使用：

picgen skill install codex --force

更新技能后，告知用户开启新对话，以便 Agent 重新加载最新的 PicGen 指令。如果新对话仍无法识别更新后的技能，请用户重启 Agent 应用。

保留现有的服务商和 API 密钥配置。除非 picgen doctor --json 报告了实际配置问题，否则升级不应要求用户重新配置密钥。

更新提示

PicGen 内置更新检查程序：

picgen update check --json

在以下情况下检查更新：

• 用户要求安装、升级、配置、诊断或打开 PicGen。
• 用户询问较新的功能，例如参考图像、蒙版、本地 Web UI、服务商管理或历史记录。
• PicGen 命令因某个选项、命令、协议功能或技能指令似乎不可用而失败。
• picgen doctor --json 或 picgen quickstart 已提示有更新。

不要在每次生成请求前都检查更新。避免仅为建议更新而中断正常的图像生成流程。

有可用更新时，先用用户易懂的方式说明更新的好处，再提供命令。优先突出功能的表述方式：

PicGen 有新版可用。升级后通常可以直接保留现有渠道和 API key，同时获得新版能力，例如参考图、遮罩编辑、本地网页配置/历史查看，以及更好的 Agent 使用说明。要我帮你现在升级吗？

如果用户正在处理紧急的图像生成任务，尽量简短地提出建议：

当前版本也可以继续用。我看到 PicGen 有新版，完成这次生成后可以升级，能获得更多生图和配置能力。

用户同意后，按照上述升级流程操作。如果用户拒绝，则继续当前任务；除非缺少某项功能会阻碍进度，否则不要在同一对话中重复提醒。

如果因无法连接 npm 注册表而无法获取更新信息，不要将其视为错误。继续执行用户要求的任务，只有在用户明确要求检查更新时才提及此事。

环境检查

安装 CLI、安装技能或保存 API 密钥之前，请先检查当前终端是否属于用户持久化的本地环境，还是沙盒／临时环境。

可使用以下轻量检查：

pwd
echo "$HOME"
node -v
npm -v
npm root -g
which picgen || true

如果环境看起来是持久化的用户级环境，请在那里继续设置。

如果环境看起来处于沙盒中、位于远程、属于临时环境、会在会话之间重置，或无法写入用户的真实主目录，请勿在那里安装 PicGen、安装技能或保存 API 密钥。请先请求用户许可，以便使用其主机上的持久化终端或持久化的用户级环境。面向用户的示例措辞：

我检测到当前可能是临时沙箱。PicGen 需要安装到你的本机持久环境，否则新会话可能会丢失 CLI、skill 或 API key。请允许我在本机持久环境中继续安装和配置；如果无法授权，我再给你最少的本机终端命令。

如果用户授予许可，请在该持久化环境中继续安装和设置提供商。如果无法获得许可或用户拒绝，请为用户提供一组精简的本地终端复制粘贴命令。手动操作说明应保持简短，只说明用户必须执行的操作。

本地 Web 界面

如果用户说“open PicGen”“打开 PicGen”或“打开生图工具”，要求提供可视化设置页面、希望无需学习 CLI 命令即可生成图像，或想查找之前生成的图像，请启动本地 Web 界面：

picgen open

将打印出的本地 URL 返回给用户。PicGen 绑定到 127.0.0.1，默认使用端口 8188，并会在需要时自动尝试后续端口。服务器在前台运行；页面使用期间，用户或 Agent 应保持终端运行，并在使用完毕后按 Ctrl+C 关闭。

如果当前环境看起来处于沙盒中、位于远程或属于临时环境，请先请求访问用户的持久化本地环境，然后再运行 picgen open。如果无法做到，请简短告知用户在本地终端运行 picgen open，并打开打印出的 URL。

只有在用户明确执行显示操作后，本地页面才会在其浏览器中显示完整 API 密钥。在聊天中，只能使用掩码命令检查密钥，例如：

picgen key list --json
picgen key show PICGEN_GEMINI_PROXY_KEY --json

使用 Web 界面进行面向用户的设置、提供商管理、图像生成和历史记录浏览。使用 CLI 命令执行 Agent 驱动的试运行、自动化、诊断和精确且可复现的步骤。

首次由 Agent 协助设置时，优先采用基于剪贴板的 CLI 流程，因为这样用户可以留在对话中，无需额外切换界面。当用户希望管理多个提供商、检查已屏蔽的密钥来源、在本地显示完整密钥、无需 CLI 命令即可生成图像，或查找已保存的图像历史记录时，优先使用 Web 界面。

工作流

1. 运行 picgen doctor --json 检查配置。
2. 如果没有配置可用的提供方，请先配置一个再生成。
3. 根据用户意图选择预设，例如 poster、product-shot 或 social-cover。
4. 运行 picgen create --dry-run --preset <preset> "<prompt>"。
5. 将试运行结果作为面向用户的生成预览展示。除非有帮助，否则不要将 dry-run 作为技术术语透露给用户。
6. 用户确认后，运行 picgen create --preset <preset> "<prompt>"。
7. 显示本地图像预览或已保存的文件路径。

如果用户明确表示要直接生成或不需要确认，可以跳过面向用户的确认步骤，但仍须在内部制定生成计划。

默认只生成一张图像。不要仅仅为了提供选项而生成多张图像。只有当用户明确要求多个选项、多个变体、对比或指定数量时，才生成多张图像。

当用户指定数量、尺寸、宽高比、质量或格式时，使用单次生成标志。这些标志不会更改已保存的偏好设置：

picgen create --n 2 --size 1088x576 --quality low "<prompt>"
picgen create --aspect-ratio 16:9 --size medium "<prompt>"

对于兼容 OpenAI 的提供方，PicGen 会规范化请求的 WIDTHxHEIGHT 尺寸，以满足当前模型规则后再发送请求。例如，如果原始尺寸低于当前最低像素预算，1088x576 可能会以 1120x592 发送。提供方仍可能返回接近但不同的最终像素尺寸；PicGen 会原样保存提供方返回的结果，不会调整尺寸、裁剪、填充或拉伸图像。

向非技术用户解释时，请尽量简明：

你指定的尺寸会作为目标尺寸使用。PicGen 会先按模型规则选择一个最接近的合法请求尺寸，最终图片尺寸以模型实际返回为准，不会额外拉伸或裁切。

对于 Gemini 提供方，PicGen 会将精确尺寸转换为最接近的受支持 aspectRatio 和高效的 imageSize；对于常见的横幅请求，通常使用 1K。

提供商设置

当用户可以看到终端提示时，可以使用 picgen setup。

在交互式终端提示不可见的 Agent 环境中运行时，不要运行会阻塞的向导 picgen setup。请向用户询问：

• 提供商类型：Gemini 或 OpenAI-compatible。
• 提供商主机：仅填写主机，例如 https://www.pandai.vip；不要包含 /v1 或 /v1beta。
• API 密钥。优先请用户将密钥复制到剪贴板并回复“已复制”；避免要求他们在聊天中粘贴密钥。

然后使用非交互式命令。

Gemini-compatible 第三方渠道：

picgen provider quick-add gemini-proxy --host https://www.pandai.vip --prefer
picgen key set PICGEN_GEMINI_PROXY_KEY --clipboard
picgen provider test gemini_proxy --json

OpenAI-compatible 第三方渠道：

picgen provider quick-add openai-proxy --host https://www.pandai.vip --prefer
picgen key set PICGEN_OPENAI_PROXY_KEY --clipboard
picgen provider test openai_proxy --json

如果无法访问剪贴板，请通过 stdin 将 API 密钥传递给 picgen key set；除非用户明确接受这种权衡，否则不要将密钥直接写入 shell 历史记录。如果 Agent 运行环境无法安全地通过 stdin 传递密钥，请让用户在自己的终端中运行 picgen key set <ENV_NAME>，并在隐藏提示中粘贴密钥。

查看已配置的密钥而不泄露密钥值：

picgen key list --json
picgen key show PICGEN_GEMINI_PROXY_KEY --json

这些命令只会显示来源、长度、掩码预览和指纹。绝不要仅为验证密钥而要求用户在聊天中粘贴密钥。

向用户说明密钥检查时，请说：“在本次对话中，我只读取经过掩码处理的密钥状态，不会读取完整密钥。如果你需要自行检查或编辑已保存的完整密钥，PicGen 管理的密钥文件位于 ~/.picgen/.env；当前目录中的项目级 .env 可能会覆盖它；shell 环境变量具有最高优先级。”

生成参考图像时，使用重复的 --reference <path> 标志传入本地图像：

picgen create --dry-run --reference ./reference.png --preset poster "<prompt>"
picgen create --reference ./reference.png --preset poster "<prompt>"

进行本地编辑或图像修复时，请同时传入蒙版图像和至少一张参考图像：

picgen create --dry-run --reference ./source.png --mask ./mask.png --preset poster "<prompt>"
picgen create --reference ./source.png --mask ./mask.png --preset poster "<prompt>"

提供参考图像时，OpenAI-compatible 提供商会使用 /v1/images/edits，并通过 multipart 上传 image[]；提供蒙版时，则会通过 multipart 上传 mask。Gemini 提供商会使用 generateContent；蒙版会作为蒙版引导图像处理，并配合明确的编辑指令，而不是使用原生图像修复功能。

PicGen 会根据提供商的能力进行路由。提供参考图像时，除非用户明确指定了提供商，否则 Agent 可以省略 --provider，让 PicGen 选择支持 reference-image 的提供商。

首次冒烟测试

配置提供商后，首次测试生成时应使用成本低、速度快、仅生成一张图像的方案。首次验证不要使用 poster、product-shot、social-cover、高级模式、大尺寸或高质量预设。

对于 Gemini 提供商，首次测试优先使用 flash 图像模型：

picgen create --dry-run --provider gemini_proxy --preset fast-draft --model gemini-3.1-flash-image-preview "一张简洁的 PicGen 测试图，白色背景，少量蓝绿色科技感点缀"
picgen create --yes --provider gemini_proxy --preset fast-draft --model gemini-3.1-flash-image-preview "一张简洁的 PicGen 测试图，白色背景，少量蓝绿色科技感点缀"

对于 OpenAI-compatible 提供商：

picgen create --dry-run --provider openai_proxy --preset fast-draft "一张简洁的 PicGen 测试图，白色背景，少量蓝绿色科技感点缀"
picgen create --yes --provider openai_proxy --preset fast-draft "一张简洁的 PicGen 测试图，白色背景，少量蓝绿色科技感点缀"

除非用户明确要求立即生成，否则请先展示 dry-run 预览，并在实际生成前征求确认。首次冒烟测试应生成一张图像。

提供商配置成功后

配置好一个提供商并成功完成首次冒烟测试后，告知用户该提供商已就绪，并询问他们是否要添加另一个渠道作为备用。示例：

Gemini 渠道已经配置并测试成功。你还可以继续添加另一个渠道作为备用，例如 OpenAI-compatible。要继续添加吗？

如果用户回答“是”，请为下一个渠道重复提供商设置和冒烟测试。如果用户回答“否”，则停止设置，并告知他们 PicGen 已可使用。

偏好设置和覆盖项

将 picgen create 标志视为仅对单次操作生效的覆盖项。它们不得更改用户偏好：

picgen create --provider gemini_official "<prompt>"
picgen create --model gemini-3-pro-image-preview "<prompt>"
picgen create --preset poster "<prompt>"
picgen create --mode premium "<prompt>"
picgen create --reference ./reference.png "<prompt>"
picgen create --mask ./mask.png --reference ./source.png "<prompt>"

只有当用户明确要求记住某项偏好时，才更改默认设置，例如“从现在起默认使用 Gemini”。

输出处理

PicGen 会将提供商的响应规范化为本地图片文件。提供商可能返回 URL、base64、内联字节或文件引用，但 Agent 应只使用 PicGen 的本地路径和元数据。

生成后：

• 显示图片预览或本地路径。
• 不要在对话中粘贴 base64、二进制图片数据或完整的提供商响应。
• 除非用户明确要求调试，否则不要读取或显示元数据中的提供商响应负载。
• 不要自动读取、附加、分析或重新发送生成的图片。
• 只有在用户要求查看、编辑、接续创作或比较图片时，才加载生成的图片。
• 需要加载时，只加载明确提及的图片。

除非普通用户主动询问，否则不要向他们解释 token 或上下文管理。

PicGen 会从元数据中删去生成的图片负载和 Gemini 思维签名，但 Agent 仍应将元数据视为诊断信息，而非面向用户的内容。

错误处理

如果 doctor 报告没有可用的提供商，请配置一个提供商。在 Agent 环境中，优先使用非交互式设置。

如果缺少 API 密钥，请使用 picgen key set <ENV_NAME> --clipboard、--stdin 保存密钥；如果可以看到交互式提示，则引导用户运行 picgen setup。只有在有助于调试时，才指出所需的环境变量。

如果提供商已禁用，请建议启用它，或使用一次性的提供商覆盖设置。

如果用户提供了蒙版，但没有提供参考图片，请在生成前询问或查找源图片／参考图片。蒙版只有与源图片配合使用才有意义。

如果提供商调用失败，请简要说明错误，并在有可用路径时提供元数据或错误路径。除非用户已批准回退行为，否则不要静默改用其他收费提供商重试。

示例

明确指定：

用 PicGen 生成一张产品发布海报

确认：

我可以先用 PicGen 做一次轻量测试生成，默认只出 1 张，确认工具和渠道都可用。要我现在开始吗？

生成预览：

生成预览：
我将使用当前渠道生成 1 张轻量测试图，保存到本地。

确认后开始生成。