剪贴簿风格插图插入器

将文章转换为带插图的 Markdown 文档：自动生成手工风格的剪贴簿式图像，并在逻辑断点处插入。

归属声明：基于 ViffyGwaanl 开发的 glm-image（MIT 许可协议）。

配置

内置脚本 scripts/generate.py 支持两个图像生成服务商，您至少需配置其一：

选项 A：GLM（BigModel / 智谱 AI）—— 中文文本首选

1. 注册地址：https://bigmodel.cn
2. 通过以下任一方式设置 API 密钥：
   • export GLM_API_KEY="your-key"
   • 在 ~/.openclaw/config.json 中添加 "glm_api_key": "your-key"
   • 在技能目录下的 .env 文件中添加 GLM_API_KEY=your-key

选项 B：OpenRouter —— 模型选择更广，英文文本效果最佳

1. 注册地址：https://openrouter.ai
2. 通过以下任一方式设置 API 密钥：
   • export OPENROUTER_API_KEY="your-key"
   • 在 ~/.openclaw/config.json 中添加 "openrouter_api_key": "your-key"
   • 在技能目录下的 .env 文件中添加 OPENROUTER_API_KEY=your-key

OpenRouter 默认模型：openai/gpt-5-image-mini（针对剪贴簿类提示词具备出色的文本渲染能力）。

自动检测机制：若同时配置了两个密钥，则默认优先使用 GLM。可通过 --provider openrouter 或 --provider glm 显式指定服务商。

输入参数

• article：完整文章正文（Markdown 或纯文本格式）
• image_count（可选）：需生成的图像数量，取值范围为 2–5（默认值：3）
• orientation（可选）：portrait（竖版，1088×1920，为默认值）或 landscape（横版，1920×1088）
• language（必需）：图像中文字所用语言 —— zh、en、ja、ko、fr、de、es。必须向用户明确询问，严禁默认或推测。

工作流程

第 0 步：检查 API 密钥

执行快速校验 —— 若未检测到 GLM_API_KEY 或 OPENROUTER_API_KEY，立即中止并提示用户如何配置（参见上方“配置”章节）。无有效密钥不得继续执行。

第 1 步：验证输入

在开始生成任何图像前：

• 确认文章长度不少于 200 单词。若不足，向用户发出警告：“文章可能过短，难以生成有意义的插图 — 是否仍要继续？”
• 统计主要章节或主题切换点（H2 标题、段落分隔等），用于确定图像插入位置。
• 向用户明确询问图像中文字应使用的语言。严禁根据文章语言自动推断。

第 2 步：生成图像提示词（Prompts）

读取 references/scrapbook-prompt.md 中的剪贴簿系统提示词。

多语言处理规则：

• 默认（zh）：按剪贴簿提示词原生输出方式，以中文生成图像描述
• 若 language=en 或其他语言：在生成 JSON 计划后，将所有 title 和 description 字段翻译为目标语言，再传入 generate.py；JSON 结构须保持完全一致。

基于该提示词分析文章，输出如下结构的 JSON 计划：

{
  "project_title": "文章标题 — 剪贴簿风格",
  "style": "实体混合媒介剪贴簿",
  "total_images": 3,
  "images": [
    {
      "image_id": 1,
      "title": "图像标题",
      "description": "300–500 字符的剪贴簿风格视觉描述……",
      "insert_after": "图像应插入其后的精确句子或标题"
    }
  ]
}

目标：每 300–400 单词内容生成 1 张图像。

第 3 步：并行生成全部图像

关键要求：所有图像生成任务必须同步启动。 单张图像生成耗时约 20–40 秒。若串行执行将显著浪费用户时间。请使用后台进程或并发 exec 调用，确保所有图像生成任务同时运行。

对 JSON 计划中的每张图像，并行执行内置脚本（全部同时启动）：

# 同时启动全部图像生成任务 —— 切勿等待某一张完成后再启动下一张
python3 scripts/generate.py "" --language  --size 1088x1920 &
python3 scripts/generate.py "" --language  --size 1088x1920 &
python3 scripts/generate.py "" --language  --size 1088x1920 &
wait  # 等待全部任务完成

在 OpenClaw Agent 上下文中，请使用并发的 exec 工具调用（每张图像一次调用），而非串行调用。Agent 必须在单次工具调用回合中发起全部 exec 请求，以确保并行执行。

附加参数：

• --provider glm|openrouter —— 覆盖自动检测逻辑
• --model —— 覆盖 OpenRouter 使用的模型（默认：openai/gpt-5-image-mini）

脚本自动执行以下操作：

• （仅限 OpenRouter）自动追加边距保护指令，防止图像边缘被裁切
• 每次运行结束后显示单张图像生成成本

失败处理：若某张图像生成失败，记录错误日志并继续处理其余图像，不得中止整个流程。在最终输出中标注失败图像，格式为：[Image generation failed: ]。

收集：每张成功生成图像的 URL 或本地路径，及其对应成本。

第 4 步：合成最终 Markdown

将每张图像插入其 JSON 计划中指定的 insert_after 锚点之后：

![图像标题](image_url)

若未在原文中找到完全匹配的 insert_after 锚点，则插入至最近的段落分隔处。

输出格式

返回完整的 Markdown 文章，包含以下要素：

1. 原文所有内容严格保留，一字不改
2. 图像按逻辑断点插入
3. 图像标题采用 JSON 计划中提供的 title 字段
4. 末尾附总结行：

Agent 所属方

由主 OpenClaw Agent 会话直接执行，不派生子 Agent。Agent 在单一会话中完成全文阅读、提示词生成、逐张调用 generate.py，以及最终 Markdown 合成。

成功标准

满足以下全部条件即视为成功：

1. 文章已通过长度校验（达标或用户已确认继续）
2. 成功生成含 2–5 条记录的图像提示词 JSON
3. 至少有一张图像成功生成
4. 返回最终 Markdown，且图像已正确插入

边界情况处理

• 文章过短（<200 单词）：发出警告并确认用户意图后方可继续
• 图像生成失败：内联记录错误，继续处理其余图像 —— 不得中止整体流程
• 锚点未找到：改为插入至最近的段落分隔处
• 无 API 密钥：立即抛出错误，并附带配置说明
• 全部图像均失败：返回原始文章（未修改），并在末尾附带错误汇总

使用建议

• 根据文章长度，在 2–5 张之间选择图像数量
• 图像应插入于主要主题切换点之后（避免插入段落中间）
• 图像描述需忠实遵循 references/scrapbook-prompt.md 中定义的剪贴簿风格
• 竖版（1088×1920）更适合内联于文章中的图像展示
• 使用 OpenRouter + gpt-5-image-mini 的单图成本约为 $0.045–0.050
• GLM 单张标准图像成本为 ¥0.10（$0.014）