Zenith

代码有源代码管理、类型、测试和拉取请求。设计文件却什么都没有。它们是不透明的二进制文件——无法比较差异、无法评审更改，而且同一个文件在不同机器上的渲染结果可能不同。

这对人们来说是个问题，对 AI 来说问题更大。Agent 已经能编写代码并发起拉取请求，因为代码是它们可以阅读和推理的文本。让它们进入设计工具，它们就会两眼一抹黑。让 Agent“把标题改成品牌红色并收紧布局”，却没有任何安全可靠的操作对象——没有稳定的目标、没有验证、没有预览，也无法检查结果。

Zenith 解决了这个问题。我们的目标是让设计文件像代码一样可以安全地自动化处理：

• 纯文本，由你掌控——可读、可比较差异，并且永远属于你。
• 稳定 ID，让每项更改都是可评审的补丁，而不是鼠标拖拽。
• 确定性渲染——同一个文件始终生成相同的像素。
• 真正的验证——文本适配、颜色来自设计系统，而且没有内容溢出页面。
• 安全编辑——每项更改都是经过类型定义的事务，在应用前会经过检查并可预览，同时提供源文件差异和审计记录。

这是最常见的误解，值得开门见山地说明：Zenith 与 Nano Banana、ChatGPT image 或 Grok Imagine 这样的图像模型正好相反。

图像生成器给你一张扁平图片。它只是一堆像素——你无法打开它来移动徽标，无法强制标题使用你指定的品牌颜色，而要求“同样的内容，只是日期不同”会得到另一张图片。没有任何东西可以编辑、评审或保证。

Zenith 不生成图片，而是生成_设计本身_——一份结构化、可编辑的文档，其中每个元素都真实存在且可定位。Agent（或人）可以修改一行内容、替换一个颜色令牌，或重新生成一百个符合品牌规范的变体，而且每次渲染都精准且可重复。AI 编写和编辑源文件；Zenith 则保证其含义和呈现效果。

大多数设计工具都是为人们拖拽方框而构建的，自动化 API 则是后来才添加的事后功能——它只是覆盖在一个本就不是为软件驱动而设计的模型之上的薄弱、受限层。

Zenith 则反其道而行。它的基础是程序化、基于文本的确定性引擎。Agent、脚本和命令行都能直接驱动它。因此，自动化不是侧门，而是正门。

编辑器。 引擎和 CLI 是 AI Agent 驱动的界面。浏览器编辑器是构建于同一引擎之上的客户端：设计师可以微调一个方框，Agent 可以调整一百个变体的样式，两者都基于相同的确定性核心运行，并使用相同的验证、事务和版本历史记录。GUI 并不是一个事后附加自动化功能的独立产品。

.zen 文档会经过一条统一的确定性流水线。每个阶段都是独立的 crate，拥有清晰的契约边界，因此 GPU 后端或编辑器都可以使用相同的场景 IR：

_{由 Zenith 渲染 — 源文件：assets/showcase/pipeline.zen。}

  design.zen  (KDL plain text)
       │  parse + validate           zenith-core   →  diagnostics (Error/Warning/Advisory)
       ▼
  Document AST  ──transaction ops──▶  Document AST'  zenith-tx  →  dry-run / apply + audit record
       │  compile                    zenith-scene + zenith-layout
       │    · resolve tokens, geometry, anchors
       │    · shape text (rustybuzz), wrap, hyphenate
       ▼
  Scene IR  (backend-neutral display list)
       │  render                     zenith-render
       ├─▶ PNG   (tiny-skia, byte-identical)
       ├─▶ SVG   (outlined text, embedded assets)
       └─▶ PDF   (vector, native CMYK, bleed / trim / crop)

  local history / undo / versions    zenith-session   (off the render path; never affects pixels)

渲染路径上的所有部分都具有确定性且不含 C 代码：没有时间、随机性、HashMap、unsafe 或 C 依赖。无论在哪台机器上，相同的输入字节始终产生相同的输出字节。

zenith validate file.zen 是确保设计文件可安全编辑、值得放心交付的步骤。它就像编译器的类型检查器，不过针对的是文档：它会读取源文件，并在渲染或打印之前报告所有问题、风险或不符合品牌规范之处，这样 Agent（或你）就不用再靠“渲染出来仔细检查”来发现问题。

它会运行 70 多项检查，每项检查都会生成一条诊断信息，其中包含稳定的代码（例如 text.overflow）、易读的说明、出问题的节点 ID 和源文件位置。每条诊断信息都有以下三种严重级别之一：

具体来说，它会检查：

• 结构和引用有效 — 每个节点 ID 都唯一，且每个引用都指向实际存在的对象：令牌引用、图像资源、连接器目标、字段、母版/版块（id.duplicate、token.unknown_reference、asset.unknown_reference、connector.missing_target）。没有悬空链接，也没有导致内容悄无声息地无法渲染的拼写错误。
• 遵循设计系统规范 — 视觉属性必须来自令牌，而不是原始十六进制值（token.raw_visual_literal），这样修改品牌风格只需改一处；它还会标记循环引用、类型错误或未使用的令牌（token.cyclic_reference、token.type_mismatch、token.unused）。
• 没有内容溢出或超出画布 — 几何信息齐全且位于画布内，文本能放入文本框，子元素不会超出其框架，内容也符合页面边距和安全区要求（node.missing_geometry、text.overflow、text.fit_failed、frame.child_overflow、margin.violation、safe_zone.violation）。锚点必须能解析到实际的参考框架（anchor.unresolved_sibling、anchor.cycle）。
• 易读且适合打印 — 文本与背景的对比度会依据 WCAG 3 (APCA) 检查（contrast.low）；同时会验证色彩空间、出血和页面单双面设置，确保 PDF 确实适合打印（document.invalid_colorspace、page.invalid_bleed）。
• 模型完整性 — 也会检查较新的 variants、recipes 和 provenance 区块，确保生成或派生的作品保持一致（variant.unknown_source、recipe.unknown_palette_token）。

这为何重要：

• 对人来说 — 你可以在导出之前发现“标题跑出页面了”“灰字灰底看不清”“这个颜色不是品牌令牌”或“打印文件的色彩空间不对”等问题，而不是事后才发现。
• 对 Agent 来说 — zenith validate --json 提供精确、机器可读的契约。Agent 编辑源文件后进行验证，就能_确认_修改是否可靠 — 这张安全网让无需人工介入的编辑值得信赖。

_{由 Zenith 渲染 — 源文件：assets/showcase/loop.zen。}

zenith perceive page file.zen [--page N | --all-pages] [--json] 会以与 zenith render --png 相同的 1 倍比例渲染每一页，然后测量裁切框（出血部分会被裁掉）。zenith perceive vector 则直接从源文件测量路径几何形状。

输出描述像素和声明的几何信息，并非对设计质量的评判。请将其视为依据，再自行判断。

墨迹指与页面上最常见像素不同的所有像素。

如何读取 --json：

• schema 为 1。如果结构发生不兼容变更，该值会递增。信封中不包含工具版本，因此发布新版本不会改变其字节内容。
• pages[].metrics.<name>.status 的值为 measured 或 not_applicable。not_applicable 指标会附带 reason。
• clearspace 需要提供全部四个边距：margin-top、margin-bottom、margin-inner 和 margin-outer（页面或文档级）。grid_conformance 需要包含 segment 或 circle 辅助线的 construction 块。指标不会自行设定阈值，也不会虚构输入。
• 每个已测量指标都有一个 diagnostics 数组，其中包含 code、severity（info 或 warning）和 message。
• 每个非整数数值都会按远离零的方向四舍五入，保留 decimals（4）位小数。
• 页面测量成功时退出码为 0。感知诊断只是信号，永远不会导致命令失败。硬性验证错误会阻止该命令执行，就像它们会阻止 render 一样。

确定性：相同文档在所有目标平台上都会产生相同的字节内容。zenith-cli/tests/perceive_hashes.json 固定了每个示例在 Linux x64 和 arm64、macOS arm64 和 x64，以及 Windows x64 上的输出。MCP 通过 zenith_perceive 暴露相同的信封（doc、page、all_pages）。

根据一个设计生成多种输出的两种互补方式——一种改变尺寸，另一种改变内容。

_{由 Zenith 渲染——源文件：assets/showcase/variants.zen。}

尺寸／格式变体（zenith variant）

variants 块可将一个规范页面扩展为多个命名的目标尺寸。每个目标都会生成一个 .zen 配套文件和 PNG 或 SVG 图像。每个目标的 override 可更改可见性、文本和视觉属性。源令牌的编辑会传播到所有变体。锚定节点会根据每种尺寸重新布局。

variants {
  variant id="square" source="page.main" w=(px)1080 h=(px)1080 {
    override node="qr" visible=#false
  }
  variant id="story" source="page.main" w=(px)1080 h=(px)1920 { }
}

zenith variant poster.zen --out-dir out/ --manifest manifest.json
zenith variant poster.zen --out-dir svg/ --format svg --raster-scale 2

批处理命令没有 --deny 标志。文档、本地和全局策略决定回退诊断行为。禁止回退时，该变体不会写入文件。I/O 错误可能导致先前的输出保留。批处理不支持回滚。

生成过程具有确定性（相同源文件 → 字节完全一致的输出和清单，schema: zenith-variant-manifest-v1）。

数据邮件合并（zenith merge）

一个模板加一个 CSV，每行生成一个渲染设计——适用于本地化帖子、个性化图形、证书或营销活动变体。为变量文本／图像节点标记 role="data.<column>"（列名即 CSV 表头），然后合并：

# in poster.zen — bind the headline to the CSV "name" column:
text id="hero.name" role="data.name" x=(px)60 y=(px)160 w=(px)680 h=(px)90 fill=(token)"color.ink" font-family=(token)"font.body" font-size=(token)"size.heading" { span "Name" }

zenith merge poster.zen people.csv --out-dir out/ --name-by name --manifest manifest.json
zenith merge poster.zen people.csv --out-dir svg/ --name-by name --format svg --raster-scale 2

合并格式默认为 PNG。多页文件名会在 .png 或 .svg 前添加 -page-N。SVG 回退诊断遵循文档、本地和全局策略。禁止回退时，该行不会写入文件。I/O 错误可能导致先前已提交的输出保留。报告会保留这些路径。

每行都会独立且确定性地渲染。--name-by 可按列名命名文件（Alice.png、Bob.png）；--manifest 会为 CI 写入字节可复现的批处理记录（包含模板和数据哈希，以及每行的来源信息）。图像列同样适用——role="data.logo" 图像节点会按行替换其资源路径。

connector 是连接两个节点的语义箭头。它没有手动指定的几何信息 — 只需提供 from 和 to 节点 ID，引擎便会在编译时根据目标节点解析后的边界框推导出两个端点。移动任一边界框后，连接器会自动重新路由；相同的源始终生成相同的路径。它是仅描边的叶节点（无填充、无子节点）；要渲染它，必须指定 stroke 颜色。

• 端点锚定 — from-anchor / to-anchor 用于选择每一端的连接位置。简单流程图可使用命名网格锚点（top-left、bottom、center-right）；需要在同一形状周围布置多个不同连线的精致图表，则可使用 35/60 之类的轮廓划分锚点。划分锚点从顶部中心开始，按顺时针方向排列；椭圆沿其周长取点，矩形则按边长沿轮廓取点。默认值 auto 会选择朝向另一个边界框的边。
• 端口 — 页面可通过 ports { port node="agent" id="memory.vector" anchor="38/60" } 声明语义连接点；连接器随后可使用 from="agent#memory.vector" 或 to="store#in"。组件端口会透传到实例，因此 connector from="agent.instance#out" 无需复制坐标，也能保持与组件内部几何位置的关联。
• 路由模式（route=）— straight（默认值）绘制直线；orthogonal 绘制直角折线；avoid 使用避障正交路由器，使路径绕开其他节点的边界框（找不到清晰路径时，则回退为普通折线）。
• 回环 — 当 from 和 to 指向同一个节点时，连接器会在该节点一侧形成一个小回环（由锚点决定所在侧，默认是 top）。
• 箭头 — marker-start / marker-end = arrow 会添加与描边同色的实心箭头（默认值为 none）；箭头方向会沿实际路由线段确定，因此会与水平或垂直方向对齐。
• 线条跨越 — 页面级设置 line-jumps="arc" 或 line-jumps="gap" 后，连接器在交叉处会进行跨越：交叉线会出现小半圆凸起（arc），或形成断开的间隙（gap），使重叠箭头清晰可辨。跨越方式是确定性的 — 水平线会跨过垂直线 — 且嵌套连接器也适用。不设置（none / 默认值）时，渲染结果逐字节保持一致。
• 样式 — 支持 stroke（必填）、stroke-width、opacity、rotate 和 style 引用，遵循与其他基本图元相同的属性/样式级联规则。

page id="pg" w=(px)640 h=(px)360 line-jumps="arc" {
  ports {
    port node="n.start" id="out" anchor="1/4"
    port node="n.end" id="in" anchor="3/4"
  }
  shape id="n.start"  kind="process" x=(px)40  y=(px)150 w=(px)130 h=(px)60 fill=(token)"c.node" stroke=(token)"c.line" { span "Start" }
  shape id="n.end"    kind="process" x=(px)470 y=(px)150 w=(px)130 h=(px)60 fill=(token)"c.node" stroke=(token)"c.line" { span "Finish" }
  shape id="n.block"  kind="process" x=(px)290 y=(px)130 w=(px)70  h=(px)100 fill=(token)"c.block" stroke=(token)"c.blockline" { span "Block" }

  // Auto-routed flow bends around the Block instead of crossing it…
  connector id="e.flow"  from="n.start#out" to="n.end#in" route="avoid" marker-end="arrow" stroke=(token)"c.flow"  stroke-width=(token)"cw"
  // …and where a second connector crosses it, the page's line-jumps hops it.
  connector id="e.cross" from="n.top"   to="n.bottom" marker-end="arrow"               stroke=(token)"c.cross" stroke-width=(token)"cw"
}

完整的可运行文档请参阅 examples/connector-routing.zen。

资源包会导出以 <package>#<item> 形式寻址的条目，通过 zenith library add 将其实例化到文档中。条目分为三种类型：component（节点组，以 instance 形式放置）、token（滤镜／蒙版令牌）和 action（预设事务）。

资源包采用以下两种格式之一：

• .zen 文件 — 功能丰富的格式：直接编写令牌、组件和操作。它通过 library 自身条目声明其身份。
• *.svg 目录 — 即插即用格式，适用于图标集。每个 *.svg 都是一个图标，其 ID 为文件名（不含扩展名）。无需编写任何内容：将文件夹放入 <project>/libraries/，它就会成为一个资源包，地址为 @local/<dirname>#<stem>。

SVG 图标在添加时会转换为原生、可编辑的 path 节点，而不是作为不透明的光栅图嵌入，也不会使用 <image> 引用。可以像处理其他几何图形一样，使用实例覆盖样式（override ref="icon.0" stroke=(token)"brand" …）。转换是确定性的，且范围明确：添加一个图标，就只转换一个图标。

内置的 @zenith/icons-lucide 资源包包含完整的 Lucide 图标集（1745 个图标，ISC AND MIT）。图标数量太多，无法逐一列出，因此采用搜索优先的发现方式：

zenith library search sync                       # → refresh-cw (matched on its alias)
zenith library search arrow --category navigation
zenith library search cloud --kind component --limit 5
zenith library show  @zenith/icons-lucide#house  # format, license, aliases, tags, geometry
zenith library add   @zenith/icons-lucide#house --into poster.zen --page pg --at 40,40

搜索结果经过排序，而非进行子串扫描：名称与查询匹配的条目优先于别名与查询匹配的条目，后者又优先于仅有标签与查询匹配的条目——因此，搜索 home 会返回 house，而不是 lamp。查询中的每个词都必须匹配，categories 用于筛选，而非排序。

图标旁边可选放置 library.kdl，以提供身份信息和搜索元数据；如果没有该文件，仍可通过文件名找到图标：

library id="@acme/icons" version="1.0.0" {
  license "CC0-1.0"
  icon "rocket-launch" aliases="liftoff" tags="spaceship booster" categories="space"
}

无论采用哪种格式，项目资源包都会覆盖具有相同 ID 的内置资源包。

运行 zenith <command> --help 查看标志（每个命令都会打印说明和示例）。每个命令都支持 --json，以输出机器可读内容。

源文本窗格是内容的权威来源。画布显示引擎对该文本的渲染结果。在画布中进行的编辑（移动、调整大小、旋转、检查器字段）会转化为修改文本的事务。

Zenith 会为每个文档保留本地编辑历史，完全不影响渲染流程——它绝不会改变像素。首次编辑时，文档会获得一个稳定身份：一个写入文件且渲染器会忽略的 ULID doc-id。此后，每次引擎编辑（tx --apply、 library add、undo/redo/restore）都会记录为一个完整的快照（保存状态，而非操作日志），因此即使手动编辑，历史记录也能保留。

zenith tx poster.zen recolor.json --apply   # an edit — recorded automatically
zenith undo poster.zen                       # step back, rewriting the file in place
zenith redo poster.zen                       # step forward again
zenith history poster.zen                    # list the timeline (--json for tooling)

zenith version poster.zen "launch-v1"        # save a NAMED version, kept indefinitely
zenith restore poster.zen launch-v1          # rewrite the doc to that version
zenith restore poster.zen @head~1            # …or to a revspec: v2, @head~1, @latest:named, a name

zenith sync poster.zen                        # capture an out-of-band change (GUI / hand-edit / git checkout)

历史记录分为两个层级。撤销/重做会在临时会话时间线上移动——快速、本地，适用于进行中的工作。命名版本是持久化的内容寻址检查点（SHA-256 + DEFLATE），会一直保留，直到你将其删除；restore 可跳转到任意版本。sync 用于将引擎外部所做的编辑纳入历史记录，确保历史完整。历史记录尽力写入：如果无法写入，文件仍会保存——编辑绝不会因此受阻。

Zenith 附带一项技能，用于教会 AI 编码 Agent 如何使用 CLI——Agent 驱动的创作 → 验证 → 渲染 → 编辑循环、设计方案，以及 --help 无法涵盖的令牌/品牌规范。为你使用的 Agent 安装该技能：

zenith plugin install                  # auto-detect installed agents, install for your user
zenith plugin install --claude --codex # choose specific agents
zenith plugin install --all            # every supported agent
zenith plugin install --claude --scope project   # into ./ for one repo
zenith plugin list                     # see what's installed where

Claude Code、Codex 和 OpenCode 会获得完整的文件夹技能（参考资料包、模板和主题）；其他 Agent（Cursor、Windsurf、Aider、Zed、Gemini、Copilot、Continue、Kiro、 Antigravity）会获得一个独立的规则文件，其中链接回自文档化的 CLI。匹配的文件会保持不变。使用以下命令升级已安装的资源：

zenith plugin install --force

--force 会覆盖存在差异的已安装文件，包括用户所做的更改。不加此参数时，存在差异的文件会保持不变。使用 zenith plugin uninstall 移除安装内容。

MCP 服务（远程 / CI / 托管 Agent）

对于通过模型上下文协议发现功能的 Agent，以及 CI 和托管/SaaS 流水线，Zenith 可作为一流的 MCP 服务运行。它并非对 CLI 的简单封装：工具结果经过精简，为结构化 JSON；通过单个 zenith_schema 工具按需获取架构详情（因此模型无需携带每种节点/操作的架构）；大型或二进制产物（渲染结果、大型树、差异）会以指向内容寻址存储的资源链接形式返回，而非内联；文档可通过 doc-id 寻址，Agent 无需再管理路径。完整的创作循环均已开放——zenith_schema、zenith_validate、 zenith_inspect、zenith_tokens、zenith_tx、zenith_fix、zenith_render、zenith_perceive、zenith_fmt、zenith_merge、 zenith_theme_new，以及 scratch/candidate/promote/finalize 工作区工具。指针式编辑（命中测试、拖动、撤销、实时渲染）使用 zenith_editor_* 工具，详见浏览器编辑器。

MCP zenith_merge 支持 format: png|svg，默认使用 PNG。SVG 接受有限的 raster_scale 值，范围为 0 < F <= 4，默认值为 1。文档、本地和全局批处理策略均适用。结构化响应会保留已提交的路径和部分行。清单写入错误会保留行数，并将工具结果标记为错误。没有 MCP 变体工具。

通过 stdio（默认传输方式）运行：

zenith mcp

将任何支持 MCP 的客户端指向它：

{
  "mcpServers": {
    "zenith": { "command": "zenith", "args": ["mcp"] }
  }
}

……或者，对于 Claude Code：claude mcp add zenith -- zenith mcp。

远程 / 托管式服务。 使用可选的 http 功能构建，并在单个 /mcp 端点上提供原生 Streamable-HTTP 服务。传输层运行在与 zenith edit 相同的受限 std::net HTTP 层上，且不会增加依赖：

cargo install --path zenith-cli --features http --locked
zenith mcp --http 127.0.0.1:8080     # prints the token to stderr
# test it:
curl -s -XPOST http://127.0.0.1:8080/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

这些工具会读取和写入文件，因此 HTTP 传输层会在读取请求正文前检查每个请求：

• 绑定。 仅限回环地址。--allow-remote 允许使用其他地址。流量是纯 HTTP：请在前面部署 TLS 反向代理。
• 令牌。 Authorization: Bearer <token>。令牌为 ZENITH_MCP_TOKEN（至少 32 个字符）；否则，启动时会生成一个随机令牌并打印到 stderr。
• Host 和 Origin。 Host 必须是 localhost、IP 地址、--http 主机或 --allow-host 名称。浏览器的 Origin 必须指定同一主机。
• 正文。 Content-Type: application/json，最大 8 MiB。
• 根目录。 每个工具路径（文档、输出、数据、捆绑包）都必须位于 --root 之下，默认为工作目录。通过 stdio 使用时，--root 可选。在指定根目录后，文档读取的所有文件（导入项、资源、数据、本地 .zenith.kdl）都必须位于该根目录内。用户级全局配置（$HOME/.config/zenith/config.kdl）和系统字体不受此限制。

工作区存储（临时候选项、版本历史、渲染后的资源制品）位于 $XDG_DATA_HOME/zenith（默认为 ~/.local/share/zenith）下；设置 ZENITH_DATA_DIR 可在隔离式 / 托管式部署中更改其位置。

本地 Agent 应优先使用 CLI + 技能，而不是 MCP。如果环境可以运行二进制文件，直接运行 zenith（通过 zenith plugin install 安装）是最快的方式。只有在无法运行二进制文件时才使用 MCP 服务——例如远程主机、CI、沙盒或托管式 / 生产服务，在这些场景中，你需要通过协议提供完整的读写能力。MCP 服务在这些场景中是首选方案。

此代码仓库提供了 server.json（MCP 注册表清单）。手动触发 Publish MCP 工作流，可为选定的稳定标签发布相应的 npm 启动器和注册表条目（通过 GitHub OIDC——无需注册表令牌），让 Zenith 能在 MCP 目录中保持可发现，并可由客户端通过 npx -y @zenitheditor/zenith-mcp 启动。

• MCP 注册表名称：mcp-name: io.github.zenitheditor/zenith

每个 crate 负责一项工作，并提供稳定的契约。zenith-geometry 不依赖其他 Zenith crate。zenith-core 在这些 crate 中只依赖 zenith-geometry。

Zenith 文件只是文本，因此可以和代码放在一起。将它提交到 git。在 pull request 中并排查看差异，审查设计变更。在 CI 中渲染，及时发现上线前的布局问题。在工作流中生成多个变体。像回滚其他文件一样回滚它。设计不再是一个需要导入导出的独立世界，而是构建流程的一部分。

• AI 和 Agent 构建者：需要可靠地生成和编辑视觉内容，而不是靠截图碰运气。
• 工程团队：希望将设计资源放入代码库，在 PR 中审查，并在 CI 中构建。
• 大批量内容制作方——营销、出版、本地化：需要大量正确的变体。
• 工具构建者：更愿意基于开放格式构建，而不是依赖封闭的云 API。

公开展示库位于 zenitheditor/zenith-showcase，并在此作为 zenith-showcase 子模块链接。

这里汇集了可重复使用的 Zenith 示例：.zen 源文件、渲染输出、视觉方案、动作、滤镜、背景、海报、传单、书籍、杂志、广告、图表、演示文稿以及其他生成式设计作品。

只有在你拥有分享文件的权利，并且允许他人依据声明的许可证重复使用所提交的源文件、输出和资源时，才将文件放入展示库。私人作品、客户作品、仅用于作品集的作品或采用自定义许可证的作品，应改为链接到展示库的外部作品集；外部作品的许可仍由所有者决定。