القائمة
一个命令行图片生成工具。可以通过读取一段简单的文本指令脚本，即可完成 2D 图形绘制，并可以将生成的图片输出为 PNG 图像文件或 Base64 Data URL。也可以使用本工具的 draw_image 指令对已有的 PNG 图片进行裁剪、缩放和重绘。
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
| name | canvas-cli |
| description | 一个命令行图片生成工具。可以通过读取一段简单的文本指令脚本，即可完成 2D 图形绘制，并可以将生成的图片输出为 PNG 图像文件或 Base64 Data URL。也可以使用本工具的 draw_image 指令对已有的 PNG 图片进行裁剪、缩放和重绘。 |
提示：
canvas-cli命令的可执行文件放在本技能目录中，下述说明中的./canvas-cli指的就是这个可执行文件，canvas-cli 是可以直接运行的二进制可执行文件，不是脚本文件。。
./canvas-cli --input=<文件路径或内联指令> --output=<输出PNG路径>
./canvas-cli --input=<文件路径或内联指令> --output-data-url
选项：
| 选项 | 说明 |
|---|---|
--input=<path> | 指令文件路径，或直接内联的指令字符串（用 ; 分隔） |
--output=<path> | 输出 PNG 文件路径 |
--output-data-url | 将结果输出为 data:image/png;base64,... 字符串而非文件 |
每行一条指令，# 开头为注释，空行忽略。指令文件的第一行必须是 canvas 指令以初始化画布。
canvas <width> <height>
示例：canvas 1080 200
set_fill_style <color>
set_stroke_style <color>
set_line_width <width>
<color> 支持：
red、white、black、blue 等，例如 set_fill_style red#RGB、#RRGGBB、#RRGGBBAA，例如 set_fill_style #FF0000rgb(255,0,0)、rgba(255,0,0,128)，例如 set_stroke_style rgba(0,255,0,0.5)<width> 是线宽，单位像素，例如 set_line_width 5
set_font <size>px <family>
set_text_align <align>
示例：set_font 32px common
size：字号（像素），决定文字高度（等于 size）和宽度（全角字符等于 size，半角字符为 size / 2）。family：字体名，对应 lib/<family>.txt 位图字体文件，没有特别指定的情况下使用 common 这个内置字体。common（支持 ASCII 及常用中文字符）。set_text_align 设置文本对齐方式：
start / left：左对齐（默认），x 是文本左边缘。end / right：右对齐，x 是文本右边缘。center：居中对齐，x 是文本中心点。y 坐标始终是文本上方顶部位置，因此生成文本的时候需要特别注意 y 坐标的设置，确保文本纵向位置正确。示例：set_text_align center
fill_rect <x> <y> <w> <h>
---
### round_rect
`round_rect` 用于把圆角矩形追加到当前路径中，然后配合 `fill` 或 `stroke` 使用。
语法：
```txt
begin_path
round_rect <x> <y> <w> <h> <radii>
fill
stroke
<radii> 支持 1 到 4 个半径值，顺序和 CSS 一样：
示例：
canvas 400 200
set_fill_style #2563EB
begin_path
round_rect 50 40 300 120 24,24,24,24
fill
stroke_rect clear_rect
- `fill_rect`：用当前 `fill_style` 填充矩形。
- `stroke_rect`：用当前 `stroke_style` 描边矩形轮廓。
- `clear_rect`：将矩形区域清除为完全透明（不受当前样式影响）。
---
### 文字绘制
```txt
fill_text "<text>" <x> <y>
<text> 需用双引号包裹（支持空格和中文）。(x, y) 的含义取决于当前 text_align 设置：
start / left：x 是文本左边缘位置。end / right：x 是文本右边缘位置。center：x 是文本中心位置。y 始终是文本上方顶部位置。示例：fill_text "Hello, World!" 100 50 则代表从 (100, 50) 开始绘制文本，文本的左上角坐标为 (100, 50)。
路径操作与浏览器 Canvas API 完全对应：
begin_path
move_to <x> <y>
line_to <x> <y>
arc <cx> <cy> <radius> <start_angle> <end_angle>
close_path
fill
stroke
0 = 右方，顺时针为正）。arc 参数依次为：圆心 x、圆心 y、半径、起始角、终止角。fill / stroke 分别以 fill_style / stroke_style 填充/描边已定义路径。支持绘制线性渐变和径向渐变，当用户提到渐变时，没有特殊指定则认为是线性渐变。
# 线性渐变：从点 (x0, y0) 到点 (x1, y1)
create_linear_gradient <id> <x0> <y0> <x1> <y1>
# 径向渐变：从内圆 (x0, y0, r0) 到外圆 (x1, y1, r1)
create_radial_gradient <id> <x0> <y0> <r0> <x1> <y1> <r1>
<id>：渐变标识符，用于后续引用。add_color_stop <gradient_id> <offset> <color>
<offset>：位置偏移，范围 0 ~ 1（0 为起点，1 为终点）。<color>：颜色值，格式同 set_fill_style。set_fill_gradient <gradient_id>
set_stroke_gradient <gradient_id>
# 创建线性渐变（从左到右）
create_linear_gradient my_gradient 0 0 200 0
add_color_stop my_gradient 0 red
add_color_stop my_gradient 0.5 yellow
add_color_stop my_gradient 1 blue
set_fill_gradient my_gradient
fill_rect 0 0 200 100
# 创建径向渐变（从中心向外）
create_radial_gradient radial 100 100 0 100 100 100
add_color_stop radial 0 white
add_color_stop radial 1 black
set_fill_gradient radial
fill_rect 0 0 200 200
save
restore
保存/恢复当前绘图状态（包括样式、线宽、裁剪区域、字体设置等），但不包括当前路径。与 Web Canvas API 行为一致。
# 从 PNG 文件加载图片并绘制到画布
draw_image <path> <dx> <dy>
draw_image <path> <dx> <dy> <dWidth> <dHeight>
draw_image <path> <sx> <sy> <sWidth> <sHeight> <dx> <dy> <dWidth> <dHeight>
<path>：PNG 文件路径，支持相对路径（相对于输入脚本文件所在目录）或绝对路径。dx / dy：目标画布中放置图片左上角的坐标。dWidth / dHeight：目标绘制尺寸，用于缩放图片。sx / sy：源图中裁剪区域左上角坐标。sWidth / sHeight：源图裁剪区域尺寸。说明：
sWidth、sHeight、dWidth、dHeight 可以为负值，表示向相反方向扩展区域，但不会导致图片翻转。示例：
# 按原图尺寸绘制
draw_image ./avatar.png 40 20
# 缩放到 120x120
draw_image ./avatar.png 200 20 120 120
# 从源图裁剪 (10, 10, 80, 80)，绘制到目标 (380, 20, 160, 160)
draw_image ./avatar.png 10 10 80 80 380 20 160 160
canvas 1080 200
# 左边一半背景 - 径向渐变 (从中心向外)
create_radial_gradient radial_bg 270 100 0 270 100 200
add_color_stop radial_bg 0 white
add_color_stop radial_bg 0.5 #fded43
add_color_stop radial_bg 1 #a1cffd
set_fill_gradient radial_bg
fill_rect 0 0 540 200
# 右边一半背景 - 线性渐变 (从左到右)
create_linear_gradient linear_bg 600 0 1080 0
add_color_stop linear_bg 0 #c3c3c3
add_color_stop linear_bg 0.2 #7c4105
add_color_stop linear_bg 0.5 #e8d8c8
add_color_stop linear_bg 1 #2b05b6
set_fill_gradient linear_bg
fill_rect 550 0 240 200
# 画一张图片，设置位置
draw_image ../images/tests/image_220x200.png 860 0
# 画一张图片，设置位置，并调整宽高
draw_image ../images/tests/image_220x200.png 800 0 50 95
# 画一张图片，选取部分图片，设置位置，并调整宽高
draw_image ../images/tests/image_220x200.png 50 50 100 100 800 105 50 95
# 设置文字颜色
set_fill_style black
set_font 32px common
# 设置抗锯齿，默认就是 4，设置为 1 则没有抗锯齿
set_text_antialias_grid 4
# 居中对齐
set_text_align center
fill_text "让天下没有难生成的图。" 450 50
set_fill_style #ff0000
set_text_align start
set_font 32px common
fill_text "Make it so that no graph is difficult to generate." 20 90
set_fill_style blue
set_font 16px common
set_text_align right
fill_text "--- 2026.03.15" 820 130
运行：
./canvas-cli --input=script.txt --output=output.png