Easel

Easel

大模型能否用真实笔触作画，而不是用像素绘图？可以——这就是为此打造的 API。

Easel 是面向 AI Agent 的无界面绘画引擎：通过 Python、shell 或 MCP 驱动的画笔、颜料载量、湿润混色和画布纹理。画笔带有有限的颜料载量，沿着笔迹逐渐耗尽。颜料湿润地落在画布上，并与已有颜料混合；在这种颜料模型中，蓝色和黄色混合会变成绿色，而不是灰色。画布表面有纹理，颜料不足的画笔只会触及凸起部分——因此，干笔不是一种特殊效果，而是在粗糙画布上颜料耗尽时自然发生的效果。每次落笔后，你都会观察自己的作品，这正是关键所在：这个引擎专为能够看见自己刚刚所作之画的 Agent 打造。

它不是绘图库，不是光栅化器，也不是图像生成器——这里没有任何功能会把提示词变成图片。每一笔都由你选择并绘制。这里没有图层，也没有免费的撤销操作：你要分阶段作画，发现问题时就覆盖重画。

你必须能够看见图像。 方法的每个阶段都以查看成果结束——s.look()、预演、阶段后的检查——这些步骤都无法让不能接收图像的画师完成。没有图像输入能力的模型可以驱动整个 API，并最终生成一幅画，但它无法判断画作是否成功；一位参与 0.5.0 阶段测试的画师就曾这样描述自己完成的画作。视觉能力是这里的必要条件，而不是一项功能。

作画前请先阅读指南。 引擎只是画笔； PAINTER.md 才是方法；六次有度量的运行表明，方法才是更重要的那一半。指南随软件包一同发布，无需另行查找：easel guide 会打印第一页——约 1,400 字的完整工作流；easel guide --full 会打印其余内容。

from easel import Session, blob, cell

s = Session(1024, 768, texture="linen", ground="toned_grey", seed=7)
s.palette["shadow"] = s.palette.mix("ultramarine", "burnt_umber", 0.4)

s.block_in(blob(cell("D5")), brush="bristle", color="shadow", density=0.8)
s.look(values=True)                       # check the value structure
s.stroke([(0.2, 0.6), (0.6, 0.55), (0.9, 0.62)], "bristle", "yellow_ochre")
s.export("painting.png")

以这种方式创作的画作

洗车场内，从驾驶座望去 — 在 300 笔预算中用了 206 笔，画布为 1152×720 亚麻布质感，未使用参考照片。创作这幅画所用的十九个分阶段脚本就在旁边。

夜晚的自助洗衣店，从街对面望去 — 在 300 笔预算中用了 286 笔，画布为 1024×768 亚麻布质感，未使用参考照片。创作这幅画所用的十四个分阶段脚本就在旁边。

黎明时分，水淹停车场里的灰鹭 — 在 320 笔预算中用了 253 笔，画布为 1024×768 粗糙质感，未使用参考照片。同一位画家将同一主题画了两次，以区分两类错误；PAINTINGS.md 并列展示了两次尝试。

这些画作全都由大模型根据 PAINTER.md 创作，每次调用此 API 一次；没有人手触碰画布，也没有描摹。每一笔都记录在日志中，每段延时视频都由日志重建；每幅画旁的说明既记录了做对的地方，也记录了出错之处。PAINTINGS.md 汇集了完整记录，下文的 创作实例 则介绍每幅画是如何完成的。

**如果你正准备亲自依照指南作画：你决定好要画什么了吗？**如果决定好了，这些作品值得你参考，旁边的脚本更是这里最有价值的内容。如果还没决定，就先别看——创作实例会点明主题，而明确的主题会替你做出选择；此前有六次新会话都证明了这一点：它们把指南顺带列出的一个名词当成了主题来画。先做决定，再看。

画笔本身

每种画布纹理上的每种画笔、尺寸和压力曲线。使用 python scripts/make_brush_sampler.py 重新生成——这张图是项目的主要测试产物， 查看它可以发现测试套件无法发现的问题。

形体不必是矩形。每一行是一种构建形状的方式， 每一列是一种扫掠方式；最后一列是该形体原本会有的边界框。使用 python scripts/make_shape_sampler.py 重新生成。

安装

需要 Python 3.12 或更高版本。仅依赖 numpy 和 Pillow——在 Windows 上构建也毫不费力。

pip install easel-paint          # the engine, the CLI and the Python API
pip install "easel-paint[mcp]"   # and the MCP server

from easel import Session, blob, cell      # the import the documents teach
import easel_paint                         # the same engine under the installed name

发行包名是 easel-paint，绝不是 easel。 PyPI 上有一个无关的 easel 包，所以执行 pip install easel 安装到的是别人的包。这里两种导入名称都可用——easel_paint 会重新导出 easel——而所有示例都使用较短的名称。

在代码检出目录中，pip install -e . 和 pip install -e ".[mcp]" 会执行相同的两项操作。

两种安装方式都会安装 easel 命令。Pip 会将它放在解释器的 scripts 目录中，而该目录通常不在 PATH 中（不在时会发出警告），因此始终可以用 python -m easel ... 作为同一命令的另一种调用方式。

MCP 服务是一个可选扩展，因为引擎中的其他部分都不会导入它。参见下文的 MCP 服务。

如果你是 LLM Agent，请阅读 PAINTER.md

PAINTER.md 是为你编写的指南。它讲解的是工作流—— 铺好底色，从后往前绘制，检查明暗关系，细化，最后处理边缘和高光——而非罗列函数；开篇便是第一个小时：用一页讲完整套方法，让十项热身练习先于其他所有内容。

如果你已经安装了这个包，就不需要访问那个链接。 六份文档都包含在 wheel 中：python -m easel guide 会打印第一个小时的内容，--full 会打印其余内容，而 easel.docs.read() 可以将其中任意文档作为文本交给你。 第六份文档是 DIAGNOSIS.md，它是一个症状索引，而非供你阅读的文档——你已经练习过一遍，但结果不对，运行 easel diagnose concentric rings 就会打印出测量该问题的段落。

这是五份文档中的一份；五份文档中的每条规则只在所属文档中陈述一次，并从其他所有地方链接到该文档。测试套件会限制 PAINTER.md 的字数，让它保持为一份画师可以牢记的文档；其中引用的数值在 CALIBRATION.md 中测量得出，画师对自己练习过程的反馈也保存在那里，而不是放在规则旁边。

PAINTER.md	方法：循环、工作顺序、常见错误、练习和检查清单。牢记于心
RECIPES.md	一次讲解一种情境：按顺序调用、出错时的表现，以及背后的数值
PAINTING.md	颜料、画笔和规划工具的工作方式；最后一章讲解如何临摹照片。说明原因；运行 easel explain <code> 可打印提示所指的原因
REFERENCE.md	事实：单位、默认值，以及每个参数的作用
CALIBRATION.md	其他四份文档引用的每个数值背后的测量数据，以及每项数据的测量对象

引擎围绕一个习惯设计：

每绘制五到十五笔就检查一次。没有检查过的笔触，只是在猜。

llms.txt 是同一份导航说明，采用模型获取此仓库时越来越常被要求查阅的格式：摘要、继续阅读前需要了解的内容，以及每份文档的位置，全篇约 1,500 词。

包含内容

部件	作用
Session	你持有的唯一对象。画布、调色板、种子、历史记录、look()。
Canvas	线性光 RGB，以及 wetness、thickness、sketch（石墨）和画布 height（纹理）。
画笔	round_soft、round_hard、liner、flat、bristle、knife、smudge。程序化笔尖；tip_wobble 会让圆形笔尖拥有独特轮廓，并在每一笔触时重新绘制。
Palette	不含黑色的有限颜料组。混色、调亮、调暗，并为混合色命名。
区域	region("top-left")、cell("D6")、horizon(0.4)、below(...)、between(...)。
形状	不受方框限制的色块：blob、ellipse、hull、union、ribbon、polygon，以及 s.circle()，可在任何画布上绘制像素尺寸为圆形的形状。smooth() 会削去轮廓的尖角，roughen() 会让轮廓偏离原线，适用于任何未经规整的形状。它们都可用于区域适用之处；group() 可将多个形状作为一个整体移动；rotated() 可按像素旋转形状或组合。s.px(x, y) 按像素绘制，s.frame() 则为对象提供自身坐标系，并按像素倾斜。
色块	block_in(place, ...) 用重叠笔触填充矩形 或形状，直到轮廓边界为止；也可通过 edge="clean" 绘制其轮廓。需要涂料不透明时，设为 solid=True，因为 density 控制的是笔触间距，而不是填充效果。sweep(edge, ...) 沿边界逐步向内铺设色块。两者都会生成普通笔触。
过渡与修补	scumble(band, a, b, n) 以 n 道重叠笔触在两个值之间逐步铺设柔和过渡——就像渐变工具该做的事，只不过用的是颜料。设置 direction="inward" 会沿色块边缘环绕铺设，而非横向铺设，形成从中心向外衰减的值。cover(place, color) 会用已预设好所有修正步骤的配方覆盖错误。smudge(edge, ...) 会沿自身形状柔化边缘：可以是点，也可以是沿轮廓涂抹的色块。
look()	网格叠加、灰度值、区域裁切、并排对比、差异、地标，以及裁切区域内带标签的十分之一细网格。
绘制	pencil() 会在颜料下方铺设石墨；颜料会按实际覆盖的程度遮住它。不计为笔触。
规划	thumbnail() 会以扁平的小图绘制构图——每个位置显示其值；如果没有提供值，则使用计划中的位置和迄今铺设的所有色块——以此判断轮廓是否清晰可辨。easel run pass.py --thumbnail 会在正式付费绘制该笔触前，为这一遍绘制生成缩略图；preview() 会显示笔触在两个面板上的落点；rehearse() 会在副本上绘制并展示效果；cost() 会说明费用，cost_line() 会说明 原因；随后 paint() 会绘制同一计划，因此其中没有任何一行会被重复写入。只有这五个操作中的最后一个会触碰画布。
测量	compare(reference) 会以表格和热力图的形式，给出每个单元格的两者值及其差异。compare({place: value}) 则改为对照你自己写下的值计划进行测量，适用于完全没有参考图的绘画；并指出计划中彼此相差不到 0.10 的数值对。prepare(reference) 会将照片切分为带编号的色块。palette.chroma_of 表示 颜色有多鲜艳，与表示亮度的 value_of 并列。
检查	report() 会从日志中读取指南的常驻警告——整遍绘画只用一支固定尺寸的画笔、以同一角度堆叠多遍笔触、小得不像画笔的猪鬃笔、在色块之前先画细节、压力列表要求凿形笔刷画出某种宽度、主体在所有笔触中所占的比例——并测量画布，检查四项无法从日志中获得的信息：值的分布位置与画面是否有明确的光源、边缘在硬与软之间的分布、剩余底色面积，以及仍然显露的石墨量。run 会在每遍绘画后将其与预算行并列打印——先列出检查结果，再列出所有发生变化的测量值；每项检查结果都会根据绘制它的脚本行，标明所统计的笔触。
调用时	共三十三条提示，每条都包含代码和对应的测量依据：颜料即将落在指定位置之外、某个方向的耗费远高于色块自身的轴向、笔触末端即将顺坡而下、颜料膜厚度超过其用途、涂抹即将越过而非沿着边界移动、用无法闭合的梳状笔刷铺设实心色块。它们会同时出现在库、命令行外壳和 MCP 结果中；easel explain <code> 会打印出用于测量该项的说明。
最终检查清单	checklist() — easel check — 会回答指南最终检查清单中所有有数值依据的项目，然后将无法测量的三项以问题形式打印出来，并原样引用你填写的 why。
预算	Session(budget=300) 会记录画家被要求写下的预算分配：run 会报告已用和剩余预算，并列出该遍绘画中最耗费的调用及其对应代码行；cost 会标记出将消耗剩余预算很大一部分的计划。绝不会拒绝任何操作。
计划	s.plan(why=, values=, lightest=, subject_share=, bands=, ground=, key=, habits=, shares=) 会记录画家被要求在落下第一笔前确定的其余事项，包括各部分的预算占比；检查时会据此衡量画布，而非套用通用建议——其中还包括四项画面可以声明不受规则限制的内容，因为规则承认只有画家才知道某些事：作为主体的条纹、被埋没的底色、低调或高调的调性，以及在特定位置绘制的小圆点——例如脸部特征。保存在会话文件中；可在命令行外壳中运行 easel plan。
历史记录	每一笔触都会作为数据记录。撤销、重放、GIF 延时摄影、联系表。
坐标始终归一化为 0.0–1.0，原点位于左上角。不会暴露原始像素，因为绝对像素坐标恰恰是大模型最不擅长处理的。

命令行

会话状态保存在单个 .easel 文件中，因此你可以在 shell 中分步工作，无需让 Python 进程一直运行。

easel new painting.easel --size 1024x768 --texture linen --ground toned_grey --seed 7 --budget 300
easel run painting.easel first_pass.py
easel run painting.easel first_pass.py --thumbnail  # its masses, flat and small, unpainted
easel run painting.easel first_pass.py --rehearse   # against a copy, committing nothing
easel run painting.easel p2_sea.py p3_rocks.py --rehearse   # ...both passes, one copy
easel run painting.easel sky_a.py sky_b.py --alternatives   # ...two versions, side by side
easel run painting.easel p4_tower.py --check         # the post-pass check over the whole painting
easel look painting.easel --grid
easel look painting.easel --values
easel look painting.easel --region D4 --fine --reference ref.jpg
easel mark painting.easel top_l 0.335 0.315
easel compare painting.easel ref.jpg
easel prepare painting.easel ref.jpg --level coarse
easel undo painting.easel 3
easel export painting.easel painting.png
easel timelapse painting.easel painting.gif --every 3 --scale 240
easel brushes
easel guide                                          # the method, in about 1,400 words
easel guide --full                                   # all of PAINTER.md
easel guide --painting                               # the reasons under the rules
easel guide --recipes                                # the calls, in order, for a thing
easel guide --reference                              # units, defaults, every argument
easel diagnose concentric rings                      # it is wrong: the passage that says why
easel explain chisel-blank                           # it warned you: the measurement behind it
easel demo crosses a boundary                        # a recipe, painted beside its failure

上述命令也都可以通过 python -m easel ... 运行，适用于 easel 可执行文件不在 PATH 中的情况。

由 easel run 运行的脚本会预先将会话绑定为 s，并将整个公共 API 纳入作用域——无需导入任何内容。会话文件旁的 prelude.py 会先在同一作用域中运行，因此辅助函数和混合效果会在多次绘制之间保留；--prelude other.py 用于指定其他文件，--no-prelude 则会关闭此功能。

MCP 服务

面向支持 MCP 的客户端，提供相同的一组动词——不同之处在于，查看类工具会直接返回图像，而不是图像路径。look、thumbnail、preview、rehearse、compare 和 prepare 会以内嵌 PNG 的形式返回图像，就像 run 排演一轮绘制时所做的那样，因此指南建议的循环（每绘制五到十五笔就查看一次）只需一次调用。

pip install "easel-paint[mcp]"
easel-mcp --dir ~/paintings          # or: python -m easel.mcp_server

也可以不安装任何内容，客户端可按以下形式进行配置：

uvx --from "easel-paint[mcp]" easel-mcp --dir ~/paintings

这里提到这两部分，是因为两者缺一不可：服务端是可选组件，其控制台脚本名为 easel-mcp，而非 easel-paint。该服务已列入官方 MCP 注册表，名称为 io.github.Gemberkoekje/easel；发布于仓库根目录的文件是 server.json。

共有二十一个工具：十七个 CLI 动词，外加 preview、rehearse、cost 和 thumbnail——用于询问尚未绘制的笔触的四个工具。笔触由 run 绘制，它接收文本形式的脚本；run(rehearse=true) 会在副本上尝试完整的一轮绘制，但不会提交任何更改；run(alternatives=[...]) 会在各自独立的副本上尝试多个版本，并将结果并排返回；run(thumbnail=true) 会统计一轮绘制，并以扁平、缩小的形式返回笔触图层，在实际绘制前即可查看。绘制位置可以是名称、单元格、跨度、矩形、轮廓，或形状构建器，例如 {"blob": "D5", "radius": 0.12}。

run 会执行客户端发送的 Python 代码，与 easel run 完全相同：只对你愿意授予 shell 权限的绘画 Agent 启用它。

确定性

每个会话都会采用一个种子；使用相同种子运行相同脚本，生成的 PNG 也相同：在同一台机器上像素完全一致，在不同机器上最多有一个色阶的差异，因为不同的 numpy 构建版本可能会对少数像素进行不同的舍入。Linux 上重新构建了九幅作品，结果在该平台上像素完全一致，在 Windows 上最多相差一个色阶；每幅作品有 12 到 2,508 个像素。每一笔的随机性都来自由 (seed, stroke index) 派生的生成器，而不是来自一个持续运行的随机流，因此一笔的抖动只取决于它是第几笔——与之前的调用消耗了多少随机值无关。

这正是能够精确重放的原因：

s.replay()          # rebuilds the whole painting from its log; identical export
s.replay(upto=40)   # the state after the first 40 records

这也是 easel undo 能够跨多个 shell 调用生效的方式：会话文件保存的是日志，而非撤销快照；重建时使用的是已安装的引擎。easel timelapse 也是如此，因为文件不保存帧：影片是对日志进行重放，逐帧还原画作记录下来的内容。如果较早版本保存的文件中有些笔触因后续修复而呈现不同，打开文件时会显示提示。

黄金图像测试确保结果可靠。tests/golden/ 为每种纹理上的固定笔触脚本保存了哈希和 PNG，还保存了完整的画笔采样器；任何改变笔触外观的改动都会导致测试套件失败，并在失败时提供两张图像供你比较。测试首次运行时就捕获到了一个真实问题：笔尖遮罩缓存使用四舍五入后的半径作为键，但遮罩是根据精确半径生成的，因此脚本绘制的结果会受同一进程中此前运行过的内容影响。

设计说明

有几项值得了解的设计决策，因为正是它们让输出看起来像是画出来的，而不是生成出来的：

• **颜料混合，而非 RGB 平均。**颜色在 Kubelka-Munk K/S 空间中通过幂平均（p = 0.35）混合。直接对 RGB 求平均会让每种混合色都变成灰褐色；还需要设置反射率下限，否则通道值为零的颜色会压过混合结果，让红色 + 蓝色混出绿色。这个下限只裁剪算术运算，之后会从混合结果中扣除，因此即使颜色比它更暗，也仍会按配方呈现。参见 src/easel/color.py。
• **间距沿移动方向测量。**扁平笔尖或刀形笔尖在移动方向上很薄。若像圆形笔尖那样设置间距，就会留下一排排离散的笔触。
• **抖动会平滑处理，而不是逐个落笔点处理。**独立的逐点抖动会让相邻笔点成团或留出间隙，在笔点频率上看起来像条带。沿笔画缓慢游移，能带来自然画笔的参差边缘，又不会产生波纹。
• **齿纹门控会加入非周期颗粒。**用平滑阈值门控近似周期性的织纹，颜料耗尽时会形成半色调网点，看起来像印刷，而不像干笔刷。
• **画笔颜料不足时会拖出痕迹。**如果逐像素进行门控，即使颜料不足的画笔仍会在织纹尺度上留下点——像碎纸屑一样，看起来很脏。因此，随着载量降低，门控会沿笔画移动方向读取齿纹，鬃毛梳的刷毛也会逐根变干；两者都与齿纹自身的分布相匹配，因此载量仍按原样铺开，只改变形状，变成顺着画笔移动方向延伸的条纹。
• **鬃毛梳按笔画绘制，每根鬃毛都有自己的宽度。**每支画笔使用固定的梳齿，会让每道宽笔触都印出相同条纹，多次铺出的色块则会变成灯芯绒；如果笔尖上的鬃毛数量固定，条纹就会随画笔缩放，大色块会印出宽过画面中任何物体的条纹，而小笔触留下的会是画笔的标记，而非对象本身的特征。因此，每次笔画都会重新绘制间距、相位和缺失的鬃毛，数量则随画笔尺寸变化。对于圆形笔尖，tip_wobble 也遵循同样的原理，不过默认关闭：对于大多数笔触，圆盘是合适的轮廓；但连续画十五个小笔触时，圆盘就不合适了，因为它会把同一种形状印十五遍。
• **圆形笔尖的宽度随压力变化。**如果压力只改变颜料的铺量，那么不透明颜色一旦饱和，变化就看不见；这也意味着，带有渐细笔锋的笔触——比如眼皮、眉毛、睫毛、细枝——得用两种尺寸分两笔画。定向笔尖则保留其凿形，因为 flat 画笔的宽度就是它铺出的色块宽度。

状态

项目仍处于早期阶段，但已实现最初指定的全部功能。引擎、调色板、构图辅助工具、look()、历史记录、CLI、精密工具（绘制、地标、预览、预演、比较、准备）、形状色块和 MCP 服务都已可用。MCP 服务最后才加入，因为我们遵循一条原则：任何会改变 API 的内容，都必须先于暴露该 API 的功能落地；自推出以来，服务也一直跟上每次变更。

每一项功能的加入或修正，都源于画师实际使用指南操作引擎，并记录下遇到的问题——引擎变更会附带测试和测量结果，指南变更则会一直作为假设，直到下一次使用时经实际绘制验证。

实例详解

paintings/ 存放这些绘画会话创作的作品，每幅都是一个端到端的完整实例，而非画廊：构建作品的编号绘制脚本、旁边的辅助函数与混合配方文件 prelude.py、画家亲笔写下的 NOTES.md，以及完成后的 PNG 和延时视频——这样一来，创作顺序清晰可见，而不必事后重建。抽象的指南无法教会人这一点，而初次创作的人最不确定的恰恰就是这一点。

这里有两个不同的主张，而本页过去曾对每幅作品都提出过更强的主张。 无论哪幅作品都成立的是，日志可以逐笔重放：笔触的随机性取自 (seed, stroke index)，因此保存的绘画日志会将每一笔重新画在原处，黄金图像测试也验证了这一点。在同一台机器上，它可以精确到字节：两个版本的 numpy 可能会在小数点后第七位对混合结果进行不同的舍入，导致某幅作品的 786,432 个像素中有 729 个偏差了一级。作品由当前安装的引擎绘制，因此，早期版本绘错的笔触会在这里得到修正，而 CHANGELOG.md 会在对应版本下列出每一项修正。已提交的脚本能否重建画布则是另一回事，答案因作品而异——三十四幅作品中有七幅在 PAINTINGS.md 各自的表格中标注了 Reproducible: not claimed，通常是因为绘画步骤脚本曾被改写并重新运行，或者 look 脚本曾在绘画步骤之间作为步骤运行，而笔触的纹理取决于它在日志中的位置。每幅作品的表格都会说明它声称的是哪一种；较早的、声称可以实现更强可复现性的作品已通过 sha256 检查，而最新的七幅作品只有各自画家的声明，目前尚未在此重新运行验证。

PAINTER.md 指向这里时附带了一个条件，而这个条件正是全部权衡所在：如果你在打开此仓库之前就选好了主题，这些作品就是你的参考；如果你还没选，它们就会替你做决定。 一个实例会点明主题，而明确的主题会造成泄露——但已先做出决定的画家不会被一个名词左右，因此，不再展示这些作品的代价，不必由最能从中受益的画家承担。如果你即将运行 LESSONS.md 中的测量协议，这条规则就是协议的一部分，不是建议。

PAINTINGS.md 从外部而非画家的视角介绍这些相同的作品：它们耗费了什么、哪些尝试失败了，以及它们实际画得有多好。

其余内容的记录位置

指南本身的五个文件列在上表中。还有两个文件，是为参与项目开发而非使用指南作画的人准备的。 LESSONS.md 记录了六次测量绘画运行和一次对抗性审查的成果：方法、起关键作用的引擎决策、陷阱，以及仍未解决的问题——更改引擎或指南之前请先阅读，因为关于指南如何更改的规则也写在这里。 SUGGESTIONS.md 汇总了二十五位画家使用指南后提出的意见：哪些地方有问题，以及如何处理，每项各用两行说明。这里列出的事项都已处理——包括经测量后确认无需修复的十项，每项都注明了这一点——只有最上面的那一轮仍未完成，并且每一行都明确标明了这一点。 CHANGELOG.md 按版本而非画家划分同一段历史：各版本有哪些改动、哪些默认值发生了变化，以及升级后省略某个参数的脚本会画出哪些不同的内容。

许可证

MIT — 请参阅 LICENSE。

可选的 Mixbox 颜料模型比内置模型具有更好的混色效果，但其参考实现采用 CC BY-NC 许可。因此，它是可选扩展（pip install "easel-paint[mixbox]"），而非依赖项——启用前请确认其许可证适用于你的用途。