sn-image-imitate

sn-image-imitate

图像风格模仿场景技能（第 1 层），依赖 sn-image-base（第 0 层）提供的 sn-image-recognize、sn-text-optimize 和 sn-image-generate 工具。

功能：

• 从参考图像中提取高保真长描述
• 根据用户要求的内容变更改写描述，同时保留风格和布局
• 在改写描述时强制执行布局锁定约束
• 在生成后进行布局一致性审查，并进行有限次数的重试
• 返回结构化流程产物，便于调试和复现

非目标

• 不改变内容的纯神经风格迁移（请改用专用风格迁移工具）
• 对参考图像中的特定区域进行局部编辑／修补
• 处理视频或动画输入（仅支持单张静态图像）
• 在一次调用中根据多张参考图像批量生成
• 保证与参考图像达到像素级保真度；该技能的目标是保持布局和风格一致，而非精确复现

输入规范

• reference_image（string，必填）：风格参考图像的本地路径或 URL
• target_content（string，必填）：用户希望在生成图像中呈现的新内容
• output_mode（string，默认值为 friendly）：输出模式，可选 friendly 或 verbose
• aspect_ratio（string，默认值为 16:9）：生成图像的宽高比
• image_size（string，默认值为 2k）：输出图像尺寸预设
• max_attempts（int，默认值为 3）：为满足布局一致性而进行的最大生成尝试次数
• layout_threshold（float，默认值为 0.75）：接受结果所需的最低布局相似度分数

环境变量

依赖项安装和 API 密钥配置请参阅 sn-image-base 技能。

配置 sn-image-base 技能以搭配 SenseNova Token Plan 运行所需的最少环境变量：

SN_BASE_URL="https://token.sensenova.cn/v1"
SN_API_KEY="your-api-key"

回退优先级为专用变量 > 域名共享变量 > 全局变量。文本调用使用 SN_TEXT_API_KEY -> SN_CHAT_API_KEY -> SN_API_KEY；视觉调用使用 SN_VISION_API_KEY -> SN_CHAT_API_KEY -> SN_API_KEY；图像生成使用 SN_IMAGE_GEN_API_KEY -> SN_API_KEY。

如需了解更多配置，请参阅 sn-image-generate_en.md 中的 Python dependencies and API keys 部分。

API 配置

此技能的所有 API 调用都通过 sn-image-base 技能的 sn_agent_runner.py 执行， 更多详情请参阅 sn-image-base 技能的 README.md。

• VLM 调用：sn-image-recognize（第 1 和第 3 步）
• LLM 调用：sn-text-optimize（第 2 步）
• 图像生成调用：sn-image-generate（第 3 步）

遇到 MissingApiKeyError 或需要显式指定模型时：通过 CLI 参数显式传入模型和身份验证参数。请参阅 $SN_IMAGE_BASE/references/api_spec.md。

$SN_IMAGE_BASE 路径说明：$SN_IMAGE_BASE 是 sn-image-base 技能的安装目录（其中存在 SKILL.md）。Agent 可以通过技能名称 sn-image-base 定位此路径。

架构：主 Agent + 工作 Agent

此技能采用双层 Agent 架构：

• 主 Agent：接收用户请求、规范化参数、发送预检、调用工作 Agent，并向用户发送最终文本／图像
• 工作 Agent：执行固定的 3 步流水线，并返回结构化 JSON

职责边界：

• 工作 Agent 不会直接发送任何用户可见消息
• 主 Agent 负责发送所有面向用户的响应
• 工作 Agent 的最后一条消息必须且只能是返回契约中定义的 JSON 字符串
• 工作 Agent 直接执行 VLM／LLM／图像调用；这些底层调用不会使用嵌套子 Agent

工作流

主 Agent 工作流

1. 提取 reference_image、target_content、output_mode（默认值为 friendly）、aspect_ratio（默认值为 16:9）、image_size（默认值为 2k）、max_attempts（默认值为 3）和 layout_threshold（默认值为 0.75）
2. 验证必需输入：
   • 已提供 reference_image，且可以解析
   • target_content 非空
3. 发送预检消息："Using sn-image-imitate skill to generate a style-consistent image, please wait..."
4. 使用完整的规范化参数和工作目录启动 Worker Agent
5. 根据 Worker 结果执行操作：
   • status=ok：发送最终摘要和生成的图像
   • status=error：报告实际错误

Worker Agent 工作流

Worker Agent 接收 reference_image、target_content、output_mode、aspect_ratio、image_size、max_attempts、layout_threshold，以及此技能的工作目录（$SKILL_DIR）。

错误处理策略：

所有 sn_agent_runner.py 调用都遵循相同的错误处理规则：

• 如果子进程以非零代码退出、崩溃或超时：不要回退，返回 status=error，并附上 stderr 中的实际错误消息或系统错误字符串
• 如果子进程返回无效 JSON，或 JSON 缺少预期的 result 字段：返回 status=error，不要静默地使用空值或默认值继续执行
• 如果 VLM 审核调用在步骤 3 期间失败，则视为此次尝试未完成：不要记录分数，并根据剩余预算重试审核一次，或跳至下一次尝试

步骤 0 — 初始化

1. 按 YYYYMMDD_HHMMSS 格式生成 task_id
2. 创建临时目录：/tmp/openclaw/sn-image-imitate/<task_id>/，并将其设为 TEMP_DIR
3. 解析并规范化 REFERENCE_IMAGE
4. 保存用户请求：

echo "$TARGET_CONTENT" > "$TEMP_DIR/target-content.txt"

步骤 1 — 图像标注（长描述 + 布局蓝图）

使用 prompts/image_annotate.md 作为系统提示词，并对参考图像调用 sn-image-recognize。

python "$SN_IMAGE_BASE/scripts/sn_agent_runner.py" sn-image-recognize \
  --system-prompt-path "$SKILL_DIR/prompts/image_annotate.md" \
  --user-prompt "Please annotate this reference image and follow the required output format." \
  --images "$REFERENCE_IMAGE" \
  --output-format json

解析 JSON result，然后解析以下三个区块：

• SHORT_CAPTION: ...
• LONG_CAPTION: ...
• LAYOUT_BLUEPRINT_JSON: { ... }

如果解析失败、LONG_CAPTION 为空，或 LAYOUT_BLUEPRINT_JSON 不是有效 JSON，则返回 status=error。

保存输出：

echo "$SHORT_CAPTION" > "$TEMP_DIR/reference-short-caption.txt"
echo "$LONG_CAPTION" > "$TEMP_DIR/reference-long-caption.txt"
echo "$LAYOUT_BLUEPRINT_JSON" > "$TEMP_DIR/layout-blueprint.json"

步骤 2 — 生成新的长描述（改写内容并锁定布局）

目标：保留参考长描述中的风格、布局和视觉语言，同时将核心内容替换为 target_content。

必须保留的约束（以 layout-blueprint.json 为指导）：

• 视觉层级（标题／副标题／正文的强调顺序）
• 区域拓扑（主要区块的数量及其相对位置）
• 阅读流向（从左到右／从上到下／径向／时间线方向）
• 图表类型和数据编码形式（如有）
• 间距节奏和对齐模式
• 蓝图中主要区域的边界框及拓扑关系

首选系统提示词：prompts/caption_rewrite.md（建议添加）。 如果该文件不存在，则使用内联备用系统提示词：

Rewrite the long caption by preserving style and layout constraints while replacing semantic content according to user target. Do not change block topology, reading order, or visual hierarchy. Keep the caption detailed and directly usable for image generation.

调用 sn-text-optimize：

python "$SN_IMAGE_BASE/scripts/sn_agent_runner.py" sn-text-optimize \
  --system-prompt-path "$SKILL_DIR/prompts/caption_rewrite.md" \
  --user-prompt "Reference long caption:\n$LONG_CAPTION\n\nLayout blueprint JSON:\n$LAYOUT_BLUEPRINT_JSON\n\nTarget content:\n$TARGET_CONTENT\n\nReturn only the rewritten long caption." \
  --output-format json

将 JSON result 解析为 NEW_LONG_CAPTION。如果结果为空，则返回 status=error。

保存输出：

echo "$NEW_LONG_CAPTION" > "$TEMP_DIR/new-long-caption.txt"

步骤 3 — 图像生成与布局审查循环

按顺序执行 attempt，取值从 1 到 max_attempts：

生成图像（使用 sn-image-base 的 sn-image-generate 工具）：

python "$SN_IMAGE_BASE/scripts/sn_agent_runner.py" sn-image-generate \
  --prompt "$CURRENT_PROMPT" \
  --aspect-ratio "$ASPECT_RATIO" \
  --image-size "$IMAGE_SIZE" \
  --save-path "$TEMP_DIR/attempt_<N>.png" \
  --output-format json

VLM 配置要求：

• 当 max_attempts > 1 时，必须对每次尝试进行 VLM 审查
• 从 OpenClaw 配置中选择 VLM 模型，作为图像识别参数
• 如果 OpenClaw 配置中没有合适的 VLM 模型：
  • 告知用户当前参数组合无法执行
  • 建议添加 VLM 配置，或将 max_attempts 设为 1 以跳过审查
• 如果 VLM 调用超时或失败：不要回退，直接报告实际错误

布局一致性审查（仅在 max_attempts > 1 时执行）：

使用 prompts/layout_review.md 将候选图像与参考图像进行审查（以蓝图作为结构依据）：

python "$SN_IMAGE_BASE/scripts/sn_agent_runner.py" sn-image-recognize \
  --system-prompt-path "$SKILL_DIR/prompts/layout_review.md" \
  --user-prompt "Reference is image[0], candidate is image[1]. Layout blueprint JSON:\n$LAYOUT_BLUEPRINT_JSON\n\nEvaluate layout similarity and return JSON only." \
  --images "$REFERENCE_IMAGE" "$TEMP_DIR/attempt_<N>.png" \
  --output-format json

预期的审查 JSON（位于 result 中）：

{
  "layout_similarity_score": 0.0,
  "style_similarity_score": 0.0,
  "pass": false,
  "major_deviations": [],
  "fix_hints": []
}

保存尝试结果：

{
  "attempt": 1,
  "image": "$TEMP_DIR/attempt_1.png",
  "layout_similarity_score": 0.0,
  "style_similarity_score": 0.0,
  "pass": false,
  "major_deviations": [],
  "timing": {
    "image_generation": { "elapsed_seconds": 12.34, "model": "sn_image_model" },
    "vlm_review": { "elapsed_seconds": 5.67, "model": "sensenova-122b" }
  }
}

注意：elapsed_seconds 从每次 CLI 调用的 --output-format json 返回值中读取；image_generation.model 固定为硬编码占位符 "sn_image_model"（sn-image-generate 不会返回 model 字段）；vlm_review.model 从 sn-image-recognize 的 JSON 返回值中读取。当 max_attempts=1 时，省略 timing.vlm_review。

提前终止检查（仅在 max_attempts > 1 时执行）：

通过标准：

• layout_similarity_score >= layout_threshold

• pass = true

• 如果通过：立即退出循环，不再继续生成

• 如果未通过且仍有剩余尝试次数，则将修正提示附加到提示词中：

Layout correction requirements:
- <fix_hint_1>
- <fix_hint_2>
...

• 如果所有尝试都未达到阈值，则返回得分最高的候选图像，并标记 layout_passed=false

返回约定

Worker Agent 的最终响应必须是纯 JSON（不得包含额外文本或代码围栏）。

正常流程

{
  "status": "ok",
  "need_main_agent_send": true,
  "output_mode": "friendly|verbose",
  "result": {
    "image": "/tmp/openclaw/sn-image-imitate/<task_id>/attempt_2.png",
    "reference_image": "<resolved_reference_image>",
    "reference_short_caption": "<short caption from step 1>",
    "reference_long_caption": "<long caption from step 1>",
    "layout_blueprint": { "...": "..." },
    "new_long_caption": "<rewritten long caption from step 2>",
    "layout_passed": true,
    "selected_attempt": 2
  },
  "attempts": [
    {
      "attempt": 1,
      "image": "/tmp/openclaw/sn-image-imitate/<task_id>/attempt_1.png",
      "layout_similarity_score": 0.62,
      "style_similarity_score": 0.79,
      "pass": false,
      "major_deviations": ["center panel too narrow", "title block moved to top-right"]
    },
    {
      "attempt": 2,
      "image": "/tmp/openclaw/sn-image-imitate/<task_id>/attempt_2.png",
      "layout_similarity_score": 0.81,
      "style_similarity_score": 0.84,
      "pass": true,
      "major_deviations": []
    }
  ],
  "review": {
    "threshold": 0.75
  },
  "timing": {
    "total_elapsed_seconds": 24.56,
    "annotate": { "elapsed_seconds": 3.21, "model": "sensenova-122b" },
    "rewrite": { "elapsed_seconds": 2.45, "model": "sensenova-122b" },
    "generation_total": { "elapsed_seconds": 11.90, "model": "sn_image_model" },
    "review_total": { "elapsed_seconds": 7.00, "model": "sensenova-122b" }
  }
}

错误流程

{
  "status": "error",
  "error": "<actual_error_message>"
}

规则：

• status=ok 必须包含 need_main_agent_send: true
• result.image 必须是已生成图像的现有路径
• timing.total_elapsed_seconds 涵盖 Worker 的完整执行时间
• 如果步骤 1 的格式解析失败（包括无效的蓝图 JSON），则返回 status=error（不得静默继续）
• attempts 必须记录每次生成和审查尝试
• 如果没有尝试通过阈值，则返回得分最高的候选图像，并将 result.layout_passed=false

输出格式

友好模式（默认）

• 用一句简洁的话说明生成的图像遵循参考风格，并已更新为请求的内容
• 说明布局一致性是否达到阈值，以及尝试次数
• 发送单张图像：result.image

详细模式

Style imitation result
---
Reference short caption: <reference_short_caption>
---
Style/layout cues:
<brief extraction from reference_long_caption + layout_blueprint>
---
New long caption:
<new_long_caption>
---
#1 attempt=<n> layout_score=<0.00> style_score=<0.00> pass=<true|false> [selected]
  deviations: <major_deviations or none>
#2 attempt=<n> layout_score=<0.00> style_score=<0.00> pass=<true|false>
  deviations: <major_deviations or none>
...
---
Layout threshold: <0.75> | Passed: <true|false> | Selected: attempt <n>
Time statistics: Total <total>s | Annotation <t>s | Rewrite <t>s | Generation <t>s×<n> attempts | Review <t>s×<n> attempts
---
Images (selected image)

调用关系

• 底层依赖：sn-image-base → sn-image-recognize、sn-text-optimize、sn-image-generate

参考资料

• prompts/image_annotate.md - 图像标注与布局蓝图系统提示词（步骤 1，必需）
• prompts/caption_rewrite.md - 带布局锁定约束的说明文字改写系统提示词（步骤 2，必需）
• prompts/layout_review.md - 候选图像与参考图像的布局／风格审查提示词（步骤 3，必需）
• ../sn-image-base/SKILL.md - 基础工具行为与参数默认值