鸿爪派·长文配图助手

概述

长文配图助手 v2.0

为长篇文章自动生成配图——从段落划分到提示词生成到一键批量生图，全流程自动化。

工作流程

文章内容 → 段落划分 → 提示词生成+嵌入 → 批量调API生图 → 验证交付

核心升级（v2.0）：新增 Agnes AI API 集成 + 批量生图脚本 scripts/gen_illustrations.py，从"只出提示词"升级为"一步到位出图片"。

Step 1: 收集输入

向用户确认以下信息（大部分有默认值，一轮对齐即可）：

Step 2: 段落划分

按以下优先级划分配图段落：

1. 显式标题：识别 ##、一、、1. 等标题标记——每个标题段落配一张图
2. 语义边界：主题转换、时间跳跃、场景切换
3. 长度均衡：单个配图覆盖300-600字为宜

详细规则见 references/paragraph-rules.md。

Step 3: 生成配图提示词并嵌入文章

为每个配图段落生成英文提示词，遵循以下模板：

[主体描述], [场景/背景], [风格关键词], [色调], [光线], [比例], no text, no letters, no words

提示词生成规则

1. 必须使用英文：英文提示词在 Agnes AI 上效果显著优于中文
2. 提取核心意象：从段落中识别最具画面感的1-2个元素
3. 抽象→具象：将"商业模式创新"转化为"齿轮运转、拼图组合"等画面
4. 风格锚定：全文所有提示词末尾追加相同的风格关键词串，保证一致性
5. 禁止文字：每条提示词末尾必须包含 no text, no letters, no words

提示词嵌入格式（关键约定）

将提示词嵌入文章 Markdown 的 HTML 注释中，方便批量脚本提取：

![配图1](images/article1/01.png)
<!-- PROMPT: A giant balance scale tipping dramatically, flat illustration, cool blue and teal, 16:9, no text, no letters, no words -->

格式规范：

• 图片占位符用 ![配图N](相对路径)
• 提示词紧跟在下一行的 <!-- PROMPT: ... --> HTML注释中
• 图片路径和提示词之间用换行分隔（非空行）
• 提示词为单行文本，不换行

完整示例

段落内容：

一、范式转移：从「卷参数」到「卷Agent」

2026年6月，全球AI行业完成了一次静悄悄的范式转移…

生成并嵌入：

![配图1](images/article1/01.png)
<!-- PROMPT: A giant balance scale tipping dramatically — on the heavier side, a pile of glowing GPU chips stacked like a mountain is crumbling and fading; on the lighter, rising side, interconnected robot arms and glowing network nodes form an ascending spiral. Flat illustration, modern geometric design, cool blue and teal with amber accent on the rising side, 16:9, no text, no letters, no words -->

风格预设详见 references/style-presets.md。

Step 4: 批量调用 Agnes AI 生图

这是 v2.0 的核心升级——不再只输出提示词，而是用脚本一键批量生成实际图片。

4.1 API 信息

详细 API 文档见 references/api-integration.md。

4.2 批量生图脚本

使用 scripts/gen_illustrations.py 一键批量生成所有配图：

# 基本用法：处理指定文章目录下的所有 Markdown 文件
python3 scripts/gen_illustrations.py /path/to/articles/

# 示例：处理 outputs 目录下的 5 篇文章
python3 scripts/gen_illustrations.py /sandbox/workspace/outputs/

脚本工作原理：

1. 扫描目录下所有 .md 文件
2. 用正则提取 ![配图N](path) + <!-- PROMPT: ... --> 对
3. 按顺序调用 Agnes AI API 生成每张图
4. 下载图片到 Markdown 中指定的相对路径
5. 自动处理 429 限流（等待15s后重试）
6. 输出统计报告（成功/失败数量）

脚本参数：

• AGNES_API_KEY：通过环境变量传入，或脚本内硬编码（不推荐）
• 请求间延迟：2秒（防限流）
• 重试次数：3次
• 超时：120秒

4.3 手动单张生成（可选）

如需手动生成单张图片，可直接 curl 调用：

curl https://apihub.agnes-ai.com/v1/images/generations 
  -H "Authorization: Bearer $AGNES_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"model":"agnes-image-2.1-flash","prompt":"YOUR PROMPT HERE","size":"1024x576"}'

返回格式：{"data":[{"url":"https://...image_url..."}]}

Step 5: 验证与交付

5.1 图片验证

生成完成后，验证图片完整性：

# 检查所有图片尺寸和大小
find images/ -name "*.png" | sort | while read f; do
  identify -format "%f → %wx%h (%[size] bytes)" "$f"
done

验收标准：

• 所有图片尺寸为 16:9 比例（Agnes AI 返回约 1312×736）
• 文件大小 ≥ 500KB（低于此值可能质量不佳）
• Markdown 中引用路径与实际文件路径完全匹配

5.2 输出格式

默认输出：带配图的完整 Markdown 文档

• 图片已下载到本地，Markdown 中的 ![配图] 占位符已对应实际文件
• <!-- PROMPT: --> 注释保留在 Markdown 中（便于后续重新生成）

可选输出：提示词清单

• 当用户不需要自动生图，只想获取提示词时使用
• 格式为 Markdown 表格：段落 | 段落摘要 | 配图提示词

工作流示例

示例1：公众号文章一键配图（最常见场景）

用户说："给这篇公众号文章配图"

1. 读取文章内容，确认风格偏好（默认 flat+tech）
2. 按 ## 标题划分段落，每段生成一张配图
3. 将提示词嵌入文章 Markdown：![配图N](path)n<!-- PROMPT: ... -->
4. 运行 scripts/gen_illustrations.py 批量生图
5. 验证图片，交付带配图的完整文章

示例2：多篇文章批量配图

用户说："给这5篇文章都配上图"

1. 对每篇文章执行 Step 2-3（段落划分+提示词嵌入）
2. 一次性运行批量脚本处理所有文章
3. 验证全部图片，按文章分别交付

参考资料

• 风格预设与提示词模板：references/style-presets.md
• Agnes AI API 集成文档：references/api-integration.md
• 段落划分详细规则：references/paragraph-rules.md
• 常见问题处理：references/troubleshooting.md
• 批量生图脚本：scripts/gen_illustrations.py

X402 支付接入（Pay Skill 协议）

本 Skill 已接入 SkillHub X402 Agent Pay 协议（基于 wechatpay v3 Native 支付），调用前由服务端完成预下单与支付触发，用户授权支付后 Agent 继续获取付费能力。计费模式：按调用量计费（per_call），单次调用 0.5 元（= 50 分）。

商户与密钥（已配置）

计费边界

• 计费单位：每次成功调用计 1 次（一次成功的生成/处理调用（长文批量配图））。
• 不计费场景：付费前置检查失败、参数校验未通过、签名错误导致的预下单失败、用户主动取消支付、上游 AI 服务生成失败（失败调用不计费）。
• 订单标识：out_trade_no 形如 long-article-illustration-skill_<YYYYMMDDHHMMSS>_<6位随机>，幂等去重。

X402 4 步调用流程

Step 1 · 付费前置检查（precheck）

Agent 调用本 Skill 前，必须先做付费前置检查：

1. 检查 weixinpay 插件是否安装：Agent 侧调用 weixinpay_check_plugin()（或检查 weixinpay_pay 工具是否在可用工具列表）。若未安装，引导用户启用 weixinpay 插件后再调用本 Skill，否则无法完成支付触发。
2. 读取请求中的 skill_id、skill_version、调用参数；
3. 校验 pub_key_id 是否在本商户有效密钥列表内（最多 3 对，本 Skill 使用 PUB_KEY_7695C2E0CDCCE5E919DAD0E730C1B24A）；
4. 生成幂等 out_trade_no，落库待支付订单；
5. 进入 Step 2。

若 weixinpay 插件缺失，本次调用直接返回错误 "需先安装 weixinpay 插件才能完成付费调用"，不进入 Step 2。

Step 2 · 微信支付下单（WeixinPay Native）

服务端调用微信支付下单接口创建预付订单：

POST https://api.mch.weixin.qq.com/v3/pay/transactions/native
Content-Type: application/json

{
  "appid": "wx1234567890abcdef",
  "mchid": "1116760867",
  "description": "long-article-illustration-skill - 单次调用",
  "out_trade_no": "long-article-illustration-skill_20260925120000_834721",
  "notify_url": "https://api.hongzhaoai.com/pay/notify/long-article-illustration-skill",
  "amount": { "total": 50, "currency": "CNY" }
}

返回 code_url（weixin://wxpay/bizpayurl?pr=...），用于 Step 3 的 pay_items[].pay_data.value。

Step 3 · X402 AI 预下单（payment_required 签名）

业务服务构造 payment_required 业务 JSON 并 Base64 编码：

{
  "skill_info": { "skill_id": "long-article-illustration-skill", "skill_version": "1.0.0" },
  "pay_type": "SKILL_PAY",
  "pay_mode": "AUTH_AND_PAY",
  "pay_items": [
    {
      "product_id": "LONGARTICLEI20260925001",
      "pay_data": { "type": "code_url", "value": "weixin://wxpay/bizpayurl?pr=example" }
    }
  ],
  "expires_at": 1784649665
}

用 Step 1 的 RSA 2048 私钥对以下 5 行签名串（每行以 n 结尾，最后一行也保留换行）做 SHA256withRSA：

SKILLHUB-SHA256-RSA2048
sh-GvUzjdxZ
<32位随机 nonce_str>
<Unix秒 timestamp>
<base64(payment_required)>

组装请求体：

{
  "signature_type": "SKILLHUB-SHA256-RSA2048",
  "developer_platform": "SKILLHUB",
  "developer_id": "sh-GvUzjdxZ",
  "pub_key_id": "PUB_KEY_7695C2E0CDCCE5E919DAD0E730C1B24A",
  "nonce_str": "<32位随机>",
  "timestamp": 1784648765,
  "signature": "<base64-signature>",
  "payment_required": "<base64-payment-required>"
}

调用 X402 预下单接口换取 payment_code（有效期 15 分钟）。

Step 4 · 支付触发（返回 402 + payment_code）

服务端把 payment_code 同时写入 HTTP Header 和响应体，返回给 Agent：

HTTP/1.1 402 Payment Required
WeixinPay-Required: <payment_code>
Content-Type: application/json

{
  "message": "本次调用需要支付后继续",
  "WeixinPay": {
    "WeixinPay-Required": "<payment_code>",
    "prompt": "本次使用微信支付，请将 WeixinPay-Required 的值作为 paymentCode 交给 weixinpay_pay，以向用户申请支付授权。"
  }
}

Agent 拿到 payment_code 后交给微信支付 Skill 发起用户授权；用户授权完成后，按本 Skill 业务协议继续调用获取结果。

支付后重试机制与异常处理

支付后重试机制（核心）：用户完成微信支付后，Agent 必须用相同的请求 body 重新调用本 Skill 接口（body 完全不变），并在 HTTP Header 中携带 WeixinPay-Required: <payment_code> 和 X-Pay-Token: <支付凭证>。服务端识别到支付已完成（通过 out_trade_no 查询微信支付结果），跳过 Step 1-4 的支付触发流程，直接返回业务结果。重试时 body 不能改、参数不能变，否则视为新调用需重新付费。

订单号传递与异常对账

订单号传递（核心）：每次付费调用生成的 out_trade_no 必须在支付完成后随重试请求一起传递——Agent 在重试时需在请求中携带 X-Out-Trade-No: <out_trade_no> 头部（或 body 中加 pay_trade_no 字段）。服务端按 out_trade_no 查询微信支付结果验证支付成功，然后返回业务结果。若重试时未携带订单号或支付凭证，服务端无法关联支付记录，将再次返回 402 触发新一轮付费。

• 传递链：服务端生成 out_trade_no → 微信下单 → payment_required.skill_info 关联 → payment_code 返回 Agent → 支付完成后 notify_url 回调 → 服务端按 out_trade_no 更新订单为已支付 → T+1 结算到绑定商户号。
• 对账依据：以微信支付回调或 out_trade_no 查询结果为准；SkillHub 商户中心提供调用与结算明细。

本 Skill 的 X402 接入遵循 SkillHub 官方《升级为 Pay Skill》规范（https://www.skillhub.cn/tutorials#agent-pay-upgrade）。

由 鸿爪派 出品。