image-batch-runner

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Image Batch Runner

图片批量运行器

Follow shared release-shell rules in:

```
postplus-shared
```
release-shell rules

Use this skill after persona and concept work already exists.

This skill is for:

batch-generating persona candidates
generating first-frame / cover candidates
applying light consistency edits to approved images
saving local image assets plus model-call metadata

This skill is not for unconstrained concept art.

请遵循以下共享发布壳规则：

```
postplus-shared
```
发布壳规则

本技能应在人物形象和概念工作已完成后使用。

本技能适用于：

批量生成人物形象候选图
生成首帧/封面候选图
对已核准图片进行轻度一致性编辑
保存本地图片资产及模型调用元数据

本技能不适用于无约束的概念艺术创作。

Quality Default

质量默认规则

When realism matters, default to the strongest provider quality settings that are practically available.

Default quality assumption:

higher image quality usually lowers visible AI artifacts
lower-quality first passes can exaggerate fake skin, eyes, and texture
it is better to step down only when cost, latency, or provider limits force it

Capture the chosen quality settings in the local request record so later QA can trace realism issues back to generation parameters.

当需要保证真实感时，默认使用当前可获取的最强供应商质量设置。

默认质量假设：

更高的图片质量通常能减少可见的AI伪影
低质量的首次生成可能会放大虚假皮肤、眼睛和纹理问题
仅在成本、延迟或供应商限制的情况下，才降低质量等级

将所选质量设置记录到本地请求记录中，以便后续QA可以追踪真实感问题与生成参数的关联。

Fact Rule

事实规则

Image generation inputs must be grounded in upstream research artifacts.

Required upstream inputs:

a benchmark-backed persona lock
a concept or shot need
visual constraints derived from benchmark evidence

Do not let the image model invent:

a new creator archetype
ad-like polish not supported by references
wardrobes or environments that break persona continuity

If the visual request is not supported by benchmark evidence, mark it as an explicit variant test.

图片生成输入必须基于上游研究成果。

必需的上游输入：

经基准验证的人物形象锁定
概念或镜头需求
基于基准证据的视觉约束

禁止让图片模型凭空生成：

新的创作者原型
参考资料未支持的广告级润色
破坏人物形象连续性的服装或环境

如果视觉请求无基准证据支持，请将其标记为显式变体测试。

Source Selection Rule

源选择规则

Use source files from the active project or client context.

If a current task already lives inside one project folder, keep the evidence lookup there first.

Do not assume one client's reports are the default source basis for all image work.

使用活跃项目或客户端上下文的源文件。

如果当前任务已位于某个项目文件夹内，优先在此文件夹中查找相关证据。

不要默认将某一客户端的报告作为所有图片工作的源依据。

Hosted Media

托管媒体

Current hosted image endpoint keys:

```
image-nano-banana-2-text
```
```
image-nano-banana-2-edit
```
```
image-seedream-v5-lite-text
```
```
image-seedream-v5-lite-edit
```
```
image-seedream-v5-lite-sequential
```
```
image-seedream-v5-lite-edit-sequential
```

Read

references/hosted-image-models.md

for endpoint request notes.

If you need image and video outputs to live under one durable asset folder instead of separate job folders, also read

references/unified-asset-contract-v1.md

当前可用的托管图片端点密钥：

```
image-nano-banana-2-text
```
```
image-nano-banana-2-edit
```
```
image-seedream-v5-lite-text
```
```
image-seedream-v5-lite-edit
```
```
image-seedream-v5-lite-sequential
```
```
image-seedream-v5-lite-edit-sequential
```

请阅读

references/hosted-image-models.md

获取端点请求说明。

如果您需要将图片和视频输出存放在同一个持久化资产文件夹而非单独的任务文件夹中，还请阅读

references/unified-asset-contract-v1.md

。

Core Scripts

核心脚本

```
scripts/generate_image.mjs
```
```
scripts/poll_prediction.mjs
```
```
scripts/upload_media.mjs
```
```
scripts/edit_image.mjs
```

These scripts take normalized request JSON files and write:

run metadata under

runs/image/<run-id>/

runs/upload/<run-id>/

downloaded image assets under
```
images/candidates/
```
asset-level records such as
```
asset.json
```
and
```
index.json
```

```
scripts/generate_image.mjs
```
```
scripts/poll_prediction.mjs
```
```
scripts/upload_media.mjs
```
```
scripts/edit_image.mjs
```

这些脚本接收标准化的请求JSON文件，并生成以下内容：

运行元数据存储在

runs/image/<run-id>/

或

runs/upload/<run-id>/

下载的图片资产存储在
```
images/candidates/
```
资产级记录，如
```
asset.json
```
和
```
index.json
```

Hosted Boundary Rule

托管边界规则

keep request files, raw provider responses, and polling state under
```
<work-folder>/.postplus/image-batch-runner/
```
when they are internal execution state
keep only final user-facing assets outside
```
.postplus/
```
if hosted image capability is unavailable, unauthorized, or returns a stable network error, stop immediately instead of switching to ad hoc shell glue

当请求文件、原始供应商响应和轮询状态属于内部执行状态时，将其保存在
```
<work-folder>/.postplus/image-batch-runner/
```
仅将最终面向用户的资产存放在
```
.postplus/
```
外部
如果托管图片功能不可用、未授权或返回稳定网络错误，请立即停止操作，不要改用临时shell脚本

Default Workflow

默认工作流

1. Lock the generation brief

1. 锁定生成简报

Before generating any image, write down:

```
assetId
```
```
runId
```
```
campaignId
```
```
personaId
```
```
conceptId
```
if relevant

assetPurpose

```
persona_candidate
```
```
cover_frame
```
```
shot_support
```
```
edit_fix
```

```
sourceBasis
```
```
mustKeep
```
```
canVary
```
```
mustAvoid
```

Do not jump straight from prose to provider call.

在生成任何图片之前，请记录以下信息：

```
assetId
```
```
runId
```
```
campaignId
```
```
personaId
```
相关的
```
conceptId
```
（如有）

assetPurpose

```
persona_candidate
```
```
cover_frame
```
```
shot_support
```
```
edit_fix
```

```
sourceBasis
```
```
mustKeep
```
```
canVary
```
```
mustAvoid
```

不要直接从文本描述跳转到供应商调用。

2. Produce a normalized request record

2. 生成标准化请求记录

For each generation job, create a local JSON request record containing:

asset id
run id
prompt
negative prompt if supported upstream
model name
mode
aspect ratio
resolution
output format
local asset directory
source basis

When the provider exposes multiple quality tiers or resolutions, default to the highest practical tier for first-pass realism work unless the job is explicitly a cheap draft or throughput test.

This request record is the stable local truth even if provider parameters evolve.

针对每个生成任务，创建包含以下内容的本地JSON请求记录：

资产ID
运行ID
提示词
上游支持的负面提示词（如有）
模型名称
模式
宽高比
分辨率
输出格式
本地资产目录
源依据

当供应商提供多个质量等级或分辨率选项时，首次真实感生成工作默认使用最高实用等级，除非任务明确为低成本草稿或吞吐量测试。

即使供应商参数发生变化，此请求记录也作为稳定的本地基准。

3. Call the provider and save raw response

3. 调用供应商并保存原始响应

Use the PostPlus-supported Node scripts in this skill directory for provider calls. Do not replace them with

curl

, inline

fetch

node -e

, or ad hoc shell glue.

Always save:

raw request JSON
raw provider response JSON
normalized asset manifest JSON
final downloaded image files

Do not treat the provider response alone as the asset store.

Current first-version execution path:

```
generate_image
```
for new persona or cover candidates
```
poll_prediction
```
if a high-quality or async image job returns before outputs are ready
```
upload_media
```
if an edit job starts from a local file
```
edit_image
```
using uploaded URLs

使用本技能目录中PostPlus支持的Node脚本进行供应商调用。请勿使用

curl

、内联

fetch

、

node -e

或临时shell脚本替代。

请始终保存：

原始请求JSON
原始供应商响应JSON
标准化资产清单JSON
最终下载的图片文件

不要仅将供应商响应作为资产存储。

当前第一版执行流程：

使用
```
generate_image
```
生成新的人物形象或封面候选图
如果高质量或异步图片任务在输出准备好前返回，使用
```
poll_prediction
```
如果编辑任务从本地文件开始，使用
```
upload_media
```
使用上传的URL调用
```
edit_image
```

4. Normalize local outputs

4. 标准化本地输出

Every batch should end with a small local manifest containing:

```
assetId
```
```
runId
```
```
personaId
```
```
conceptId
```
```
provider
```
```
model
```
```
mode
```
```
assets[]
```
- local path
- remote URL if any
- prompt hash
- source basis
- created time

This is the handoff to later review and render stages.

每个批量任务结束时，应生成一个小型本地清单，包含：

```
assetId
```
```
runId
```
```
personaId
```
```
conceptId
```
```
provider
```
```
model
```
```
mode
```
```
assets[]
```
- 本地路径
- 远程URL（如有）
- 提示词哈希
- 源依据
- 创建时间

这是后续审查和渲染阶段的交接依据。

5. Prefer edit over full regeneration once a face is approved

5. 面部核准后优先使用编辑而非重新生成

Use

edit

mode when the user feedback is about:

wardrobe tweaks
desk setup tweaks
lighting tweaks
background cleanup
microphone / accessory adjustment

Do not regenerate from scratch if the approved face and general structure are already correct.

当用户反馈涉及以下内容时，使用

edit

模式：

服装调整
桌面设置调整
光线调整
背景清理
麦克风/配件调整

如果已核准的面部和整体结构正确，请勿从头重新生成。

Path Selection Rule

路径选择规则

Store outputs inside the active project's asset structure when one already exists.

If no project-specific asset structure exists yet, choose a clear workspace asset folder and make the chosen path explicit.

If the output location will become a long-lived handoff point, prefer confirming the destination with the user.

如果已有活跃项目的资产结构，请将输出存储在该结构内。

如果尚无项目特定的资产结构，请选择一个清晰的工作区资产文件夹，并明确所选路径。

如果输出位置将成为长期交接点，建议与用户确认目标位置。

Example Persistence Convention

示例持久化约定

One possible project-local layout is:

text

assets/<asset-id>/
  asset.json
  index.json
  images/
    candidates/
    approved/
  runs/
    image/<run-id>/
      request.json
      response.json
      manifest.json
    upload/<run-id>/
      request.json
      response.json
      manifest.json

Keep the

runs/

intermediates under

<work-folder>/.postplus/image-batch-runner/

when they are internal execution state rather than the user-facing handoff.

Do not assume this example layout is the global default.

Avoid

/tmp

for final assets.

一种可能的项目本地布局如下：

text

assets/<asset-id>/
  asset.json
  index.json
  images/
    candidates/
    approved/
  runs/
    image/<run-id>/
      request.json
      response.json
      manifest.json
    upload/<run-id>/
      request.json
      response.json
      manifest.json

当

runs/

中间文件属于内部执行状态而非面向用户的交接内容时，请将其保存在

<work-folder>/.postplus/image-batch-runner/

。

不要假设此示例布局为全局默认。

避免将最终资产存储在

/tmp

目录。

Tool Contract

工具约定

This skill expects two tool adapters:

```
generate_image
```
```
upload_media
```
```
edit_image
```

The normalized request/response shapes live in

references/tool-contracts.md

For the current hosted integration:

```
generate_image
```
calls the selected model endpoint directly
```
upload_media
```
uploads local files to hosted media storage and returns a reusable URL
```
edit_image
```
must consume uploaded image URLs, not raw local file paths

Model selection rule:

set
```
request.model
```
to one of the hosted image endpoint keys above
default is
```
image-nano-banana-2-text
```
use Seedream sequential variants when cross-shot identity consistency matters more than single-image iteration speed
for Seedream models, prefer explicit
```
size
```
for sequential Seedream models, set
```
maxImages
```
to the intended number of outputs

本技能需要两个工具适配器：

```
generate_image
```
```
upload_media
```
```
edit_image
```

标准化的请求/响应格式请查阅

references/tool-contracts.md

。

对于当前的托管集成：

```
generate_image
```
直接调用所选模型端点
```
upload_media
```
将本地文件上传到托管媒体存储并返回可复用的URL
```
edit_image
```
必须使用上传的图片URL，而非原始本地文件路径

模型选择规则：

将
```
request.model
```
设置为上述托管图片端点密钥之一
默认值为
```
image-nano-banana-2-text
```
当跨镜头身份一致性比单图迭代速度更重要时，使用Seedream序列变体
对于Seedream模型，优先使用显式
```
size
```
参数
对于Seedream序列模型，将
```
maxImages
```
设置为预期的输出数量

Review Rule

审查规则

Before calling an image provider, verify:

persona is benchmark-backed
image request is tied to a real asset purpose
the job records what should stay fixed vs vary

After generation, review:

realism
benchmark fit
repeatability across 10 videos
risk of looking like a specific copied creator
ad-like drift

在调用图片供应商之前，请验证：

人物形象已通过基准验证
图片请求与实际资产用途相关
任务记录了应保持固定和可变化的内容

生成后，请审查：

真实感
基准匹配度
在10条视频中的可重复性
与特定创作者相似的风险
广告风格偏离

Failure Mode

失败模式

Stop and say the request is under-specified if any of these are missing:

no locked persona or visual direction
no asset purpose
no source basis
no local output path

Do not compensate for missing strategic inputs by inventing a style.

如果缺少以下任何一项，请停止操作并说明请求规格不足：

无锁定的人物形象或视觉方向
无资产用途
无源依据
无本地输出路径

不要通过自创风格来弥补缺失的战略输入。

Example Commands

示例命令

Generate from a normalized request file:

bash

node ${CLAUDE_SKILL_DIR}/scripts/generate_image.mjs \
  --request /path/to/request.json

Poll an async prediction later:

bash

node ${CLAUDE_SKILL_DIR}/scripts/poll_prediction.mjs \
  --request /path/to/request.json

Upload a local file for later edit:

bash

node ${CLAUDE_SKILL_DIR}/scripts/upload_media.mjs \
  --request /path/to/upload-request.json

Run an edit job using uploaded URLs:

bash

node ${CLAUDE_SKILL_DIR}/scripts/edit_image.mjs \
  --request /path/to/edit-request.json

从标准化请求文件生成图片：

bash

node ${CLAUDE_SKILL_DIR}/scripts/generate_image.mjs \
  --request /path/to/request.json

稍后轮询异步预测结果：

bash

node ${CLAUDE_SKILL_DIR}/scripts/poll_prediction.mjs \
  --request /path/to/request.json

上传本地文件供后续编辑：

bash

node ${CLAUDE_SKILL_DIR}/scripts/upload_media.mjs \
  --request /path/to/upload-request.json

使用上传的URL运行编辑任务：

bash

node ${CLAUDE_SKILL_DIR}/scripts/edit_image.mjs \
  --request /path/to/edit-request.json