Ardot 画布插画生成

概述

Ardot Illustration From ImageGen

Deliver a custom raster illustration — generated with ImageGen — onto an Ardot design canvas as an image-filled frame, optionally wrapped in a captioned artboard, so the result is presentation-ready.

付费前置（Pay Skill · 强制第一步）

本技能在 SkillHub 以 Pay Skill（按次付费，0.10 元/次） 上架，费用由使用者支付给创作者（银橙AI）。在产出任何结果之前，必须先完整走完下列支付链路。★ 仅当第 4 步重试返回 HTTP 200 且响应中含 "access_granted": true（或服务端下发的付费交付内容）时，才可继续执行本技能；否则一律停止，不得用本地脚本 / 参考文件的结果替代交付。

用户取消支付后若想对同一笔订单重新支付：先与用户确认要对哪一笔订单重新支付，再将上次相同的 WeixinPay-Required 值作为 paymentCode 调用 mcp__weixinpay__weixinpay_retry_pay；当前会话中取不到真实凭据时，引导用户重新走上面的正常下单流程，不得编造 paymentCode。

Contents

1. [When to use](#1-when-to-use)
2. [Prerequisites & capability probe](#2-prerequisites–capability-probe)
3. [End-to-end workflow](#3-end-to-end-workflow)
4. [Tool cheatsheet](#4-tool-cheatsheet)
5. [Full worked example](#5-full-worked-example)
6. [Prompt notes for the generated image](#6-prompt-notes-for-the-generated-image)
7. [Quality self-check](#7-quality-self-check)
8. [Troubleshooting & degraded path](#8-troubleshooting–degraded-path)
9. [Deliverables](#9-deliverables)
10. [语言约定](#10-语言约定)
11. [与平台内置 Ardot 技能族的分工](#11-与平台内置-ardot-技能族的分工)

1. When to use

Trigger — the user asks for an illustration / scene / key visual / hero image, especially when the deliverable is an Ardot design file:

• 帮我画一张插画 / 生成一张 xx 场景的图
• 我要一张带落地窗 / 城市 / 办公室风格的插图
• 给这个方案配一张主视觉 / 封面图 / 概念图
• 用 Ardot 出一版插画设计稿
• English: "generate an illustration", "hero image", "key visual", "scene image"

Do not use for: vector icon systems, component libraries, or full-page layout (those are core Ardot design tasks); photographic-realistic portraits or copyrighted assets (confirm rights and style with the user first).

2. Prerequisites & capability probe

Probe both capabilities before starting:

Two paths:

• Full path (Ardot MCP available): ImageGen → place on Ardot canvas → validate → deliver .ardot + preview.
• Degraded path (Ardot MCP unavailable): ImageGen → save PNG → deliver image file + prompt, and state that the canvas step was skipped.

3. End-to-end workflow

Step 0 — Language announcement

Before the first content-producing operation, state the on-canvas language (default: the user's prompt language).

Step 1 — File-open gate (Ardot)

• If no design file is open, call mcp__ardot__create_design once, wait for the ready

context, then call mcp__ardot__fetch_file_info to confirm the file is ready.

• Gate rule: create_design / open_design must complete in their own message and be ready

before anything else. Never bundle them with later reads or edits.

Step 2 — Generate the image (ImageGen)

• Use the ImageGen deferred tool with a detailed English prompt.
• Pick a size that matches the target canvas aspect ratio (see §6).
• Set output_dir to the project's generated-images/ so the file path can be reused in Step 4.
• 核对产出尺寸再动手建画框（这一步能拦住「声明 9:16 却拿到 2:3」这类静默错误）：

python scripts/check_illustration.py <图片> --frame <计划画框宽x高> --expect-ratio <声明比例>

退出码 0 才继续；返回 3 说明图与画框比例不符，先按 §6 的建议重新生成或改画框尺寸。

Step 3 — Build the canvas structure (batch_edit)

One mcp__ardot__batch_edit call to create:

• a top-level artboard frame;
• an image frame sized to the image (fills: [], clipsContent: true, optional cornerRadius);
• optional caption text (fontSize >= 28).

Assign binding names so nodes can reference each other within the same batch, then read the image frame's node id from the response.

Step 4 — Apply the image (upload_images)

Call mcp__ardot__upload_images with the node id from Step 3 and the absolute image path. Note: it replaces the target node's fills.

Step 5 — Validate

• mcp__ardot__capture_screenshot(nodeIds:[artboardId]) to visually confirm framing, crop and caption.
• mcp__ardot__capture_layout for structural checks.
• Save screenshots under the project's .workbuddy/screenshots (internal artifact — do not surface the path to the user).

Step 6 — Deliver

Output the Ardot file (openable and presentable), plus a preview screenshot when useful, and a one-line summary.

4. Tool cheatsheet

4.1 batch_edit (ops syntax)

• The parameter key is operations (not ops). Each operation must be one line.
• I(parent, {props}) inserts a node; U(node, {props}) updates a node.
• Common props: type (frame/text/rectangle…), name, x/y, width/height, fill,

fills, cornerRadius, layout, clipsContent; for text content, fontSize, fontName, textAlignHorizontal, textAutoResize.

• Full node property list: references/ardot-tooling.md.

artboard=I(document, {type:"frame", name:"Illustration Artboard", width:1600, height:1180, fill:"#16181F", layout:"none"})
imgFrame=I(artboard, {type:"frame", name:"Office Illustration", x:32, y:32, width:1536, height:1024, fills:[], cornerRadius:12, clipsContent:true})
caption=I(artboard, {type:"text", name:"Caption", x:32, y:1078, width:1536, content:"豪华总裁办公室 · 插画", fontSize:34, fontName:{family:"Inter", style:"Medium"}, fill:"#C9CDD4", textAlignHorizontal:"CENTER", textAutoResize:"WIDTH_AND_HEIGHT"})

4.2 upload_images

{
  "fileId": "<ardot-file-id>",
  "items": [
    { "nodeId": "<imgFrame-id-from-batch-edit-response>", "filePath": "<absolute-path-to-generated-image.png>" }
  ]
}

• The target node must already exist; take its nodeId from the batch_edit response.

4.3 ImageGen

• Deferred tool: load its schema (ToolSearch) before invoking (DeferExecuteTool).
• Key parameters: prompt (detailed English), size, output_dir.

5. Full worked example

User: "帮我做一张豪华总裁办公室的插画，放到 Ardot 里。"

1. Announce 中文 canvas.
2. create_design → wait for ready → fetch_file_info.
3. ImageGen: prompt = detailed English (modern luxury office, floor-to-ceiling windows,

city night view, warm accent lighting, realistic illustration, 3:2); size = 1536x1024; output_dir = generated-images/.

1. batch_edit with the ops in §4.1.
2. Read imgFrame id → upload_images.
3. capture_screenshot(nodeIds:[artboardId]) → confirm.
4. Deliver: the Ardot file + preview image + one-line note.

6. Prompt notes for the generated image

• Formula: subject + scene + composition/angle + lighting + style + quality/aspect.

Templates by illustration type are in references/prompt-cookbook.md.

• Size table — 权威版本在 references/prompt-cookbook.md §2，此处只作摘要，两处如有出入以那份为准：

⚠️ 9:16 ≠ 1024×1536（那是 2:3）。竖版故事图必须用 864×1536，否则图与画框比例差 18.5%，填进去只会拉伸或留黑边。落画布之前先用脚本核一遍：

python scripts/check_illustration.py <图片> --frame <画框宽x高> --expect-ratio <声明比例>
# 从画框反查该生成什么档位：
python scripts/check_illustration.py --frame 1080x1920 --suggest

• Negative hints: 完整清单见 references/prompt-cookbook.md §4（水印 / 文字残影 / 人体结构畸形 /

低清模糊 / 空洞背景 / 过多留白），按需追加。

• Safe area: if a caption sits above/below, ask for headroom in the prompt.

7. Quality self-check

• [ ] Image aspect matches the target frame —— 用脚本核，不靠目测：

python scripts/check_illustration.py <图片> --frame <宽x高> --expect-ratio <A:B>（退出码 0 才算过）

• [ ] upload_images returned success and the image is visible on the frame
• [ ] Caption fontSize >= 28 and not clipped
• [ ] Screenshot re-checked for framing, crop and color
• [ ] Output file named clearly (e.g. illustration-office.png)

8. Troubleshooting & degraded path

Degraded path (no Ardot MCP)

1. Generate the illustration with ImageGen and save the PNG.
2. Deliver the PNG path + the prompt used + the size.
3. State plainly: "当前环境未连接 Ardot，已交付可直接使用的插画文件；连接后可再落到 Ardot 画布。"

9. Deliverables

• Full path: Ardot design file (artboard + illustration frame + optional caption) + preview screenshot.
• Degraded path: PNG illustration file + prompt + size note.

10. 语言约定

11. 与平台内置 Ardot 技能族的分工

Ardot 相关能力在平台上是一个技能族，本技能只做其中一条链路。各成员定位如下（前四者为平台内置，随 WorkBuddy 提供，不由本技能包附带、也无需手动引用）：

本技能的专有链路（不要与上述重叠的部分混为一谈）：

1. 用 ImageGen 产出栅格插画（不是矢量图标系统、不是组件库）；
2. 以 upload_images 作为 frame 填充落到 Ardot 文件；
3. 产出前用 scripts/check_illustration.py 核对实际出图比例与画框比例。

边界：矢量图标系统、组件库、整页版式属核心 Ardot 设计任务，不在本技能范围；写实人像与受版权素材需先与用户确认权利与风格。

Reference files

• references/ardot-tooling.md — Ardot MCP tools, batch_edit ops syntax, node properties, the file-open gate and validation tiers.
• references/prompt-cookbook.md — ImageGen illustration prompt templates by type, size/aspect table (权威版本), and negative prompts.
• scripts/check_illustration.py — 出图尺寸/比例核对与画框反查档位；零依赖，--selftest 31 例可自证。

计费条款（Pay Skill · 按次计费）

本技能在 SkillHub 上以 Pay Skill 形式上架，通过 SkillPay 按调用量计费；费用由使用者直接支付给创作者（银橙AI）。SkillHub 仅提供展示、投诉处理及其他平台服务，不作为该笔交易的收款方或服务实际提供方。请在支付前确认创作者名称、收款主体、计费单元、单价、服务内容和退款规则。

一、计费参数

二、付费前置检查（Pre-check）

服务端在发起计费前逐项校验，任一项不通过则直接返回能力结果、不发起计费：

调用方（Agent）侧另有一步前置检查：调用付费能力前，先检查当前 Agent 是否已安装 weixinpay 插件。

三、X402 计费链路（四段式）

第 1 段 · 请求资源，创建订单。 向本技能的计费端点发起请求：POST https://yinchengai.cn/skillpay/invoke/ardot-illustration-from-imagegen（JSON body）。首次请求只创建待支付订单，不执行业务、不扣费。

第 2 段 · 支付触发标识。 服务端返回 HTTP 402 Payment Required（或 200 兼容模式，以响应头是否存在为准），并给出两个响应头：

响应体同时给出应付金额与支付提示。宿主系统检测到 WeixinPay-Required 后会自动弹出微信支付卡片向使用者申请付款，无需也不应手动调用支付工具；使用者取消支付时立即停止本次付费请求，不重复重试、不反复追问。

第 3 段 · 支付后重试（必做）。 支付成功后必须重新发起同一请求获取付费内容，规则如下：

1. JSON body 与首次请求完全一致，不修改任何字段；
2. 通过 Header 原样携带 WeixinPay-Required 与 X-Out-Trade-No（支付信息只走 Header，body 不带支付信息）；
3. 服务端查单验真（微信订单状态为支付成功）后，才执行本技能并返回付费内容。

第 4 段 · 幂等与异常。 服务端按 out_trade_no 幂等：同一订单的重复请求直接返回已缓存结果，杜绝重复收费。

四、上架口径

三处单价必须完全一致，否则使用者付款会被拒：服务端计费配置 0.10 元 / amount_fen 10、支付平台登记单价 0.10 元/次、上架表单标价 0.10 元/次。计费参数以技能详情页与支付确认页展示为准；服务端裁决为唯一依据，客户端计数不生效。