keyline

keyline-mcp

keyline.dev：示例、基准测试，以及适用于各种客户端的配置说明。

为 AI Agent 打造的设计引擎：Agent 的 Canva。 keyline 是一款免费的 MCP 服务，可用于 Claude Code、Claude Desktop、Cursor、Codex、Gemini CLI 和任何 MCP 客户端。你的 Agent 只需描述一次社交媒体帖子、广告或横幅，并将其写成一个小型 JSON 场景；keyline 就会按各种尺寸将其渲染为图像和视频，并使用你的字体和颜色显示真实文本，每次运行的效果都完全一致。

无需浏览器，消耗更少令牌。 无需无头 Chrome、Puppeteer 或 Playwright：只需一个基于 Skia 的原生 Rust 二进制文件。每次编辑都会反馈各个尺寸下的问题，让 Agent 根据测量结果而非截图修正设计：消耗的令牌比由 Agent 驱动无头 Chrome 少 2 倍，比 Playwright MCP 少 6 倍（基准测试）。

一个提示词，五种尺寸：版式从 4:5 帖子自适应到 728×90 排行榜广告；keyline 的检查会在渲染前找出无法容纳的内容。

更多带动态效果的宣传活动，请访问 keyline.dev。此处展示的所有图像，包括上方的图像，均由 keyline 制作。

为什么

如今大多数人们发布的设计（促销帖子、活动传单、广告组）都是用 Canva 或 Adobe Express 等工具制作的。这些工具是为使用鼠标的人设计的，都不适合作为 Agent 的后端：

• Canva 和 Adobe Express 将自己的场景图保密：你可以导出像素图，却无法导出设计。
• 基于浏览器的渲染器（如 Polotno）需要在服务器上运行无头 Chrome。

keyline-mcp 正是缺少的那一环：一款以 Agent 为先的设计工具，其设计格式和渲染器从零开始构建，专为大模型创作、检查和导出而设计，既经济又可重复。设计以结构化数据形式保存（包含布局、令牌、样式和组件的类型化图层树），而非像素，因此 Agent 可以精确编辑，而不必重新生成图像。

工作原理

flowchart LR
    A[Agent] -- "layer_add / layer_update" --> S[(Scene JSON)]
    S --> L["Layout per size<br/>scale → constraints"]
    L --> C["Checks<br/>defects · advisories · facts"]
    C -- "ok, or what to fix" --> A
    L --> R["Skia renderer<br/>GPU, CPU fallback"]
    R --> P["PNG, JPEG, WebP, PDF, animated PNG, GIF, MP4 or WebM per size"]

1. 一个主版式。 设计只需在主尺寸下编写一次，并列出目标尺寸。
2. 自适应版式。 行、列、网格和设计工具约束会在每种尺寸下重新排布设计，无需约束求解器；任何图层都可以针对某种尺寸或宽高比类别进行调整。
3. 检查，而非预览。 每次编辑的回复都会指出每种尺寸下的问题，并提供修复问题所需的测量值。
4. 默认使用 GPU，需要确定性时使用 CPU。 渲染使用 GPU，并在必要时回退到 CPU；CPU 的输出可完全重复。

从这里开始： docs/concepts.md 介绍模型；docs/scene.md 介绍场景格式；docs/tools.md 介绍工具和配置。

面向 LLM，且仅面向 LLM

没有 GUI，也没有开发 GUI 的计划。每个设计决策都由一个问题来评判：Agent 要花多少 token 才能生成正确的图像？ 我们使用真实模型（通过 Claude Code 调用 Claude）构建真实的多版块广告来进行测量。

• 工具少，批量处理： 只有 6 个工具，而不是每个属性一个工具；一次调用即可构建完整广告。
• 回复简短： 编辑操作会返回变更的 ID、版本，以及 ok 或问题，绝不会返回整个场景。
• 省略默认值： 典型图层只需 4–6 个字段。
• 采用标准名称： 尽可能使用 CSS 名称和值（例如，帧上的 flexbox 和网格字段、fontWeight、borderRadius、rgba() 颜色），让模型首次编写场景就能写对。布局本身是 keyline 自有的布局系统，有文档说明，但并不完全仿照浏览器。
• 语义化目标： 使用 role 定位图层，因此 Agent 无需读取场景来查找 ID。
• 无需像素即可验证： 缺陷需要修复、建议需要判断、事实需要权衡；每项都提供修复所需的测量值（了解详情）。
• 使用名称，而非临时创建： 图标、形状、样式、令牌和组件都通过名称指定。仅图标一项，就将重建真实传单的单次运行成本从 $0.22–0.62 降至 $0.15–0.19。
• 基于测量，而非猜测： 每项变更都会通过多个真实模型运行进行评估，并收录在 keyline-bench 中。
• 审美判断留给模型： 服务只标记客观缺陷，其余内容则作为事实报告。

功能

• 图层：text、image（PNG、JPEG、SVG）、video、icon、rect、ellipse（以及弧形和圆环）、polygon（以及星形）、path（SVG 路径数据或命名形状）、line、frame（嵌套、裁剪、堆叠、网格）、spacer、firstFit，以及用于组件的 use
• **布局：**堆叠（CSS flexbox：行和列，支持间距、内边距、对齐、分布和换行；支持 fill、flexGrow 和优先级）、网格（CSS grid：轨道、命名区域、跨列/行）、带最小值/最大值和宽高比的 hug/fill/百分比尺寸、选择合适内容的方向列表和 firstFit、约束、九个位置的放置、每种尺寸的缩放系数、按尺寸和宽高比进行更改（media）、常见社交媒体和广告格式的尺寸预设，以及平台覆盖的安全区域
• **文本：**适应尺寸、换行或单行显示；行内标记（<b>、<i>、<span style=…>，将样式名称用作标签）；字重、斜体、字间距、行高、大小写；均衡或美观的换行；文字背后的高亮；下划线和删除线；沿曲线排列文本；点引导符；用图像、图案或渐变填充文本；轮廓；文本挖空其所在的框架。字体的工作方式类似 CSS 网页字体：指定任意 Google Fonts 字体系列，服务首次使用时会下载并缓存（记录在 fonts/index.json 中）；内置 Inter，也可以添加自己的字体文件
• **绘制：**堆叠填充（纯色、线性/径向/锥形渐变、图像、图案、胶片颗粒）、描边（内侧、居中或外侧、按边设置、虚线、带箭头、手绘效果）、阴影（外阴影和内阴影，可沿剪影或文本形状）、模糊和背景模糊、蒙版（渐变、形状、路径、其他图层或图像）、撕边效果、16 种混合模式、圆角、旋转、倾斜、翻转
• **图像：**填充、适应、裁剪或平铺，并设置始终保持在视野内的焦点；调整（亮度、对比度、饱和度、灰度、棕褐色、色相、双色调、着色、半色调）
• **图标：**内置约 5,000 个，可按名称使用：Lucide 线框图标，以及 Font Awesome Free 实心、常规和品牌图标，支持任意颜色
• **复用：**在任意图层上使用命名样式；使用令牌（{{brand}}，可置于任意字段或句子中），即可更新所有使用该令牌的字段；组件可放置一次或按每行数据放置一次；模板则是通过 URL 或路径加载并设置变量的场景文件，可针对每行值渲染一次
• **动画：**GSAP 风格的动画：进入和退出效果（淡入、向上淡入、弹出、缩放、模糊进入）；对不透明度、缩放、旋转、偏移、倾斜、模糊和颜色设置关键帧，并使用 GSAP 的缓动效果；以 random() 随机起始；子项错开动画；将文本拆分为可独立移动的字母或单词；描边自行绘制；数字递增
• **视频：**将视频剪辑作为图层，可裁剪、减速或循环播放，并叠加标题和图形；镜头按顺序播放，通过剪切、淡化、滑动、推入、擦除或缩放衔接；每段剪辑自带的声音会保留在视频中，并与配乐混合
• **资源：**按内容哈希存储。仅通过 http(s) 获取 URL，并拒绝私有和本地地址。
• **输出：**按尺寸导出 PNG、JPEG、WebP、矢量 PDF、动画 PNG、动画 GIF、MP4 或 WebM；可导出任意时刻的静帧；可为广告网络设置文件大小上限；还可选择生成联系表预览；条件允许时使用 GPU 渲染

快速开始

Claude Code（macOS 或 Linux）：插件会下载 keyline，并根据该版本的 SHA256SUMS 校验；或者使用 PATH 中的 keyline-mcp。

/plugin marketplace add keyline-dev/keyline
/plugin install keyline@keyline

Claude Desktop（搭载 Apple silicon 的 Mac 或 Windows）：从最新版本下载 keyline-mcp-<version>.mcpb，然后双击打开。设计及其渲染文件保存在 ~/keyline 中，每个设计各有一个文件夹；你也可以将 Claude 应使用的图像和徽标放入其中。如需改用自己的文件夹，请打开“设置” →“扩展” → keyline →“配置”，添加文件夹，然后点击保存。

其他客户端：安装后添加

每个版本都附有 SHA256SUMS 文件和构建证明：gh attestation verify <file> --repo keyline-dev/keyline。然后将 keyline 添加到客户端。命令是 keyline-mcp；如果客户端找不到它，请提供完整路径（which keyline-mcp）。

codex mcp add keyline -- keyline-mcp

{ "mcpServers": { "keyline": { "command": "keyline-mcp" } } }

接下来

让你的 Agent 设计一张海报："用这张照片制作一张邮寄投票传单，尺寸为 1080×1350、1200×1000 和 300×600 摩天楼广告。"

• **你的文件：**每个设计都有一个文件夹 ~/keyline/<name>/，用于存放场景和 renders/；Agent 会按路径在其中添加图片、视频和模板（比发送文件内容更省资源），并在后续会话中按名称找到设计。Claude Code 插件使用项目文件夹。其他情况下，--folder ~/work ~/brand 会替换 ~/keyline：设计保存在第一个文件夹中，文件则从所有文件夹中读取。标志放在命令之后（claude mcp add keyline -- keyline-mcp --folder ~/work），也可以放在 JSON 配置的 args 中。在 Docker 中，设计保存在 /data 卷中；挂载其他文件夹并传入它们。
• **视频：**PATH 中需要有 ffmpeg；其他所有内容，包括动画 PNG 和 GIF，都无需它即可正常工作。
• **选项：**每项设置都是一个标志（--folder、--no-motion、--data、--fonts、--renderer、--ffmpeg、--encoder）；请参阅 keyline-mcp --help 和 docs/tools.md。
• 不使用 Agent：keyline-mcp render scene.json --out renders/ 会渲染所有尺寸；如果存在 ! 缺陷，则以状态码 1 退出。在 GitHub Actions 中，uses: keyline-dev/keyline@v0 会为仓库中的场景执行此操作（详情）。
• **Linux 服务端 GPU：**需要 Vulkan 驱动（NVIDIA 的驱动或 Mesa）；没有 GPU 时，keyline 会使用 CPU 渲染。

工具

每种输入和回复格式都见 docs/tools.md。

典型调用：

{
  "sceneId": "s5b0a42a5e",
  "layers": [
    {
      "id": "headline",
      "type": "text",
      "x": 60,
      "y": 40,
      "width": 960,
      "fontSize": 64,
      "fontWeight": 800,
      "textAlign": "center",
      "color": "#1B2A5C",
      "text": "Proven <span style=\"color:#D0202E\">RESULTS</span> for WILLOWMERE Families",
      "constraints": {
        "horizontal": "stretch",
        "vertical": "top"
      }
    },
    {
      "type": "image",
      "asset": "photo",
      "y": 220,
      "width": 1080,
      "height": 460,
      "constraints": {
        "horizontal": "stretch",
        "vertical": "stretch"
      }
    },
    {
      "id": "cta",
      "type": "frame",
      "y": 830,
      "width": 1080,
      "height": 100,
      "fill": "#D0202E",
      "constraints": {
        "horizontal": "stretch",
        "vertical": "bottom"
      },
      "children": [
        {
          "id": "cta-text",
          "type": "text",
          "text": "VOTE BY MAIL",
          "x": 394,
          "y": 21,
          "fontSize": 48,
          "fontWeight": 800,
          "color": "#FFFFFF",
          "constraints": {
            "horizontal": "center",
            "vertical": "center"
          }
        }
      ]
    }
  ]
}

以及其回复，其中包含测试所用的尺寸（1080×1350，原始比例；1200×1000，比例为 0.85；300×600 的摩天大楼广告，比例为 0.28）：

added headline,image1,cta v2 ok
smallest text: portrait 48px (cta-text), wide 41px (cta-text), sky 13px (cta-text)

开发

cargo test                                         # unit and end-to-end tests
UPDATE_GOLDEN=1 cargo test --test e2e              # regenerate reference PNGs (deliberately; also e2e_features, e2e_paint, …)
cargo test --test llm_e2e -- --ignored --nocapture # a real model builds an ad; prints cost
cargo test -- --ignored web_fonts google_fonts     # web fonts download once and stay cached (network)
KEYLINE_MCP_BENCH=<label> cargo test --test llm_e2e -- --ignored --nocapture       # keep the run in ../keyline-bench/reference-ad/
KEYLINE_MCP_BENCH=<label> cargo test --test recreate_e2e -- --ignored --nocapture  # rebuild a local design from its image, scored

• 单元测试涵盖布局、文本适配、精细到像素检查的渲染、存储、URL 安全性和编辑。
• 布局测试会在布局完成后检查每个图层的位置和尺寸，不进行渲染。
• 端到端测试会通过 stdio 运行真实服务，在多种尺寸下构建设计，并将 PNG 与参考图像进行比较。图像按操作系统分别保存，因为字形栅格化因平台而异；比较时会使用较小的容差，因为字形边缘在不同操作系统版本之间也略有差异。
• 大模型测试会以无界面模式运行 Claude Code，因此需要 Claude 订阅，无需 API 密钥。这些测试会检查是否仍有缺陷，并报告工具调用、令牌数和等效 API 费用。设置 KEYLINE_MCP_BENCH 后，每次运行都会保留以供比较：参考广告位于 keyline-bench（检出到此仓库旁边，或位于 KEYLINE_BENCH），以及根据其图像重建的设计（保存在 Git 忽略的 bench/recreate/local/ 中，因为参考素材通常属于真实个人），并按外观相似度评分。
• **发布：**推送 v* 标签会构建 Linux .deb 和 tarball（amd64 和 arm64），并将它们附加到 GitHub 发布版本。

贡献请遵循 CLAUDE.md：仅使用 Rust，必须通过 cargo fmt 和 clippy -D warnings，更改会依据 rust-skills 规则进行审查，新依赖必须获得批准且采用宽松许可证，并且每项功能都必须附带单元测试和端到端测试。

许可证

功能源代码许可证 1.1，未来采用 Apache 2.0 许可证（FSL-1.1-ALv2）：可免费用于任何目的，包括商业用途，也可修改和再分发，但不得用于竞争：不得在取代 keyline 或提供实质相同功能的商业产品或服务中向他人提供 keyline，包括将其作为托管服务提供。你自己的内部使用、研究、教育以及为客户工作均获准。**每个版本发布两年后，该版本也可依据 Apache License 2.0 使用。**如需竞争用途的许可证，请联系作者。

欢迎依据贡献者协议提交贡献：贡献者将其更改的版权转让给作者。

第三方部分保留各自的许可证：Skia（BSD-3-Clause），通过 skia-safe 绑定（MIT）；resvg（Apache-2.0 或 MIT）；rmcp（Apache-2.0）；csscolorparser（MIT 或 Apache-2.0）；Inter（SIL OFL 1.1）；Lucide 图标（ISC）以及 Fonticons, Inc. 提供的 Font Awesome Free 图标（CC BY 4.0）。