zenith

center"> # <img src="assets/hero.png"极光 — 为人工智能予创建和编辑真实 width="900"> <h为人工智能时代打造的设计引擎。</h3> 纯文本 <strongstrong> 设计文件，您可以阅读、差异比较、，并让代理安全编辑 — <strong>确定性strong> 为像素精确和印刷就绪的</p> <p> a href="#安装"><strong>安装</strong></a> <a href="#快速开始"><strong>快速开始</strong></a> <a href="#功能特点"><strong>功能特点</strong></a> <a href="#验证 -- 安全网"><strong>验证</strong></a> <="#命令界面"><命令</strong></a> <a href代码代理一起使用"><</a> </p> <a href=".com/zenitor/zenith/actions/workflows/ci.yml"><="https://github.com/zenitheditor//actions/workflows/ci.yml alt="持续集成状态> <a://github.com/itor/zenithimg src="https.io/github/v/release/zenitheditor/zenith?include_prereleases&label=发布版本" alt=" 发布版本 <ahttps://crrates/zenimg src=".shields.io/cratesith-tool?label.io" alt="crates.io上的 zenith-tool <a://crates.iozenith-tool"><https://img.shields/d/zenithlabel=下载量"crates.io 下载量"></a> <a hrefregistry.modelcontextprotocol.io/v0/servers/io.github.zenitheditor%2Fzenith/versions/latest="https://img/MCP-registryb5bd6" alt="MCP 注册表列表"></a> <ahttps://github.com/zenitheditor/zenith"><img src="https://img.shields.io/badge-0a7f5a极光示例> <a hrefimg src="https.shields.io/github/license/itor/zenith" alt="许可证"></a> > _{<i README 中的每个横幅和极光创建代码位于 <a/showcase">assetsa>。} </div> --- 是一种用于设计文件的格式和引擎 — 海报、演示文稿、书籍图形、图表等简单：**设计代码一样工作。**阅读、差异比较测试它，并让代理安全地编辑它。 `.zen` 文件是一种人类可读的 [KDL](https://kdl.dev) 文本。引擎解析它，验证它是否符合大型诊断集，将其编译为与后端无关的场景，并将同一文件渲染为 **每次都相同的像素** — 作为 PNG 或印刷就绪的 PDF。 > 下面的章节都折叠起来，以保持的可浏览性 — 点击任意标题的 展开。**安装** 和 **快速开始**。 ## 安装 脚本来zenith` CLI，它可以检测您的平台并从 Releases 下载匹配的预。 **Linux /```bash fsSL https://rawzenitheditor/zenith/main/scripts/install ``` **WindowsShell)** ```powershell irm.githubusercontent.com/zenitheditor/zen/scripts/install.ps1 | iex ``` 设置 `ZENITH_INSTALL_DIR` 以更改（默认为 `~/.`）： ```bashITH_INSTALL_DIR=//bin \ curl - https://raw.githubusercontent.com/zenitheditor//scripts/install.sh |``` ### 使用 cargo cargo install zen # 从 crates.io `zenith`文件） cargo install://github.com/itor/zenith zenith-tool # 从源 ``` 库 crates（`zenith-core`、``、`zenene`、`zenith、`zenith-txzenith-session`其自身名称发布，供直接使用极光引擎的 Rust。 ### 使用 npmbash npm install -zenitheditorith-mcp n @zenithedzenith-mcp ``` npm 包从 GitHub Releases 安装匹配的 `zenith` 二，并专注于 MCP 注册路径。未作用域zenith` 二是 Rust CLI。 Hub Releases 直接Hub Releases](.com/zenit/zenith/releases | 平台架构 | | | :------- | :------------------------------------ | | Linux | x86_ | `zenith-<版本>-linux-x64.tar | | Linux | aarch64 | `zenith-<版本>-linux-arm64.tar.gz` | | macOS | x86_64 | `zenith-<版本>-macos-x64.tar.gz` | | macOS | Apple Silicon | `zenith-<版本>-macos-arm64.tar.gz` | | Windows | x86_64 ith-<版本64.zip### 更新bash zenith update 最新稳定版本 update --pre 版本 zenith <标签> 特定发布标签，例如标签 ``` 使用 --version` 从源代码本地开发或源： ```bash --recurse-submodules https.com/zenitzenith cd zenith cargo buildcargo install ---cli # 安装ith` 到 ./scriptslocal # 安装到 ~/.local/bin二进制文件位于/release/zenith` 工具链或系统库 — 依赖关系图是无 C 的，并且在区中禁止使用 `unsafe`。 ## 快速开始 ```bash zenith validate examples/hello.zen # 报告诊断信息（添加 --json 以获取机器输出） zenith fmt examples/hello.zen # 规范化、幂等格式化 tokens examples/hello.zen # 列出设计令解析值 zenith inspect examples/hello.zen # 打印节点树（只读） zenith render examples/hello.zen --out . # 编译并渲染为 PNG zenith render examples/multipage.zen --all-pages out/ # 每个页面一个 PNG zenith render examples/hello.zen --pdf # 印刷就绪的 PDF zenith render examples/hello.zen --scene scene.json # 转储场景 IR ``` 最小有效文档： ```kdl zenith version=1 { project id="proj.hello" name="极光" tokens format="zenith-token-v1" { token id="color.bg" type="="#f8fafc" token id="color.ink" type="="#111827" token id="" type="fontFamily" value="Noto Sans" token id="size.heading" type="dimension" value=(px)42 } styles {} document id="doc.hello" title="极光" { page id="page.hello" w=(px)=(px)160 { rect id="rect.bg" x=(pxpx)0px)480px)160 fill=(token)"color.bg text id="text" x=(px)24 y=(px)24 w=(px)432 h=(px)112 fill=(token)"color.ink" font-family=(token)"font.body" font-size=(token)"size.heading" { span "" } } } 参见 [`examples/`](./examples) 以获取可运行的 `.zen` 文件，涵盖形状、富文本、内联 `markdown`（从外部文件加载）、代码块、图像、框架/组、多页面文档和样式，以及更丰富的特性 — `gradient`、`shadow`、`blur`、`filter`、`、`table`、`flowchart`（形状 + 连接器）、图表（条形/线形/面积//环形花线，带有图例、值标签和数据绑定）和 `anchors` 为什么 <details><代码有了源代码控制、类型、测试。设计文件却 这伤害了人们并了 AI。</summary有了源代码控制测试和拉。设计文件却没有是不透明的二进制 您无法差异比较无法审查更改，相同的文件可以在不同机器上呈现这对人们问题，对 AI 如此。代理已经可以编写打开拉取是它们可以推理的文本。将设计工具中，它们就会失要求代理“将为品牌红色并”，但抓取的稳定目标 — 没有验证，没有预览，没有检查结果的方法。 极光解决了目标是使代码一样可自动化 **纯文本拥有 — 可读比较、永久属于- **稳定 ID**更改都是可审查的补丁，而不是鼠标拖动。 - **确定性渲染** — 相同的文件始终产生相同的像素。 - **真正的验证** — 文本适合，颜色来自设计系统，没有任何元素溢出页面。 - **安全编辑** — 每个更改都是类型化的事务，在落地和预览差异和审计</details 不是 AI 图像生成 <details><summary>模型相反：极光生成可编辑的 <em>设计</em>，图片。</summary> 常见的混值得明确：极光与 Nano Banana、 图像或 Grok图像模型生成器为您平面图片。它像素 — 您并移动徽强制标题的品牌颜色，请求“相同的内容但会为您。没有任何内容可编辑、审查或保证光不生成图片 _设计本身_ — 一个结构化、可编辑的每个元素都是可寻址的。或人员）可以、交换颜色令生成一百个体，并且每次渲染可重复的。写和编辑；极光保证和外观。 </details 优先考虑 AI 原生，而非工具加><summary>可编程、确定；可视化上的客户端 —前门。</设计工具都是为人类拖动框的，而自动化 API添加的 — 一个有限的层，打算由模型之上。 则是反其道而行基础编程的、基于、确定性的引擎。脚本和命令行直接，自动化不是；它是前**未来发展方向。** 目前，极光和 CLI — AI 代理驱动的界面。路线图是一个 **可视化编辑器，允许人类和 AI 代理共同编辑相同的 `.zen` 文档**：设计师调整一个框，代理重构一百个变体，并且两者都使用具有相同验证、事务和版本历史的确定性核心。GUI 是引擎上的客户端 — 而不是一个单独的产品，其自动化功能是附加的。现在优先考虑 AI；**下阶段：AI + 人类，共同协作。** </details> ## 工作原理 <details><summary>一个确定性的流程：解析 + 验证 → AST → 编译 → 场景 IR → 渲染（PNG/PDF）。</summary> `.zen` 文档流经一个单独的确定性流程。每个阶段都是一个具有干净契约边界的独立 crate，因此未来的 GPU 后端、SVG 导出或可视化编辑器可以消耗相同的场景 IR： <p align="center"><img src="assets/showcase/pipeline.png" alt="流程：.zen 源代码 → 验证 → 编译 → 场景 IR → 渲染 → PNG/PDF" width="900"></p> _{<i>由极光渲染：<a href="assets/showcase/pipeline.zen"><code>assets/showcase/pipeline.zen</code></a>.</i>} ```text design.zen (KDL 纯文本) │ 解析 + 验证 zenith-core → 诊断信息（错误/警告/建议） ▼ 文档 AST ──事务操作──▶ 文档 AST' zenith-tx → 预览 / 应用 + 审计记录 │ 编译 zenith-scene + zenith-layout │ · 解析令牌、几何、锚点 │ · 形状文本（rustybuzz）、换行、连字符 场景 IR （后端无关的显示列表） │ 渲染 zenith-render ├─▶ PNG （tiny-skia，字节相同） └─▶ PDF （矢量，原生 CMYK，出血 / 修剪 / 裁剪） 本地历史 / 撤销 / 版本 zenith-session （在渲染路径之外；从不影响像素） ``` 影响渲染路径的一切都是 **确定性和无 C** 的：没有时间、没有随机性、没有 `HashMap`、没有 `unsafe`、没有 C 依赖。相同的字节总是产生相同的输出，在任何机器上。 </details> ## 它能做什么 <details><summary>令牌、全节点集、真实排版、视觉效果、锚点、配方、事务引擎、确定性 PNG/PDF、历史、库和数据合并。</summary> - **脚手架和身份** — `zenith new` 创建一个可编辑的文档（最小有效模板，默认 `.zen` 扩展名，父目录创建），并在首次写入时生成稳定的 `doc-id`；任何 `.zen` 文件在首次编辑时都会获得其身份和工作区存储 — 无需手动设置步骤。 - **纯文本 `.zen` 格式** — KDL v2 源代码，包含 `project` / `tokens` / `styles` / `document` / `page` 结构；每个节点都带有稳定的 ID。 - **设计令牌** — `color`（sRGB **和** 原生 CMYK）、`dimension`、`number`、`fontFamily`、`fontWeight`、`gradient`（线性/径向）、`shadow`、`filter` 和 `mask`，带有别名链和循环检测。 - **全节点集** — `rect`、`ellipse`、`line`、`polygon`、`polyline`、`text`、`code`、`image`、`frame`、`group`、`pattern`、`shape`、`connector`、`chart`、`instance`、`field`、`footnote`、`toc` 和 `table`，以及为向前兼容而保留的未知节点的无损传递。 - **真实排版** — 使用捆绑的 Noto Sans / Noto Sans Mono 进行 `rustybuzz` 形状渲染，字体回退，Knuth–Liang 分割，丰富的内联跨度（粗体/斜体/下划线/删除线/高亮/内联代码/链接），线程文本流（链），首字母缩进，标签引导，文本环绕，以及当字符不可用时的 `font.glyph_missing` 诊断。 - **精简长篇文本** — 通过从外部 `.md`/`.txt` 文件（`text src="copy/article.md"`）或数据字段中获取正文副本来保持 `.zen` 文件较小，并选择 **markdown**（`format="markdown"`）进行内联标记（`**bold**`、`*italic*`、`==highlight==`、`++underline++`、`~~strike~~`、`` `code` ``、 `[label](url)`）和完整的 **块结构** — `# headings`（h1–h6），空白行段落，块引用，有序/无序列表，围栏代码块和 `---` 规则。每个角色的排版（字体，大小，重量，填充，间距）由文档、页面或文本范围内的 `block role="h1"` 声明控制（层叠：text > page > doc），因此 `.zen` 文件拥有所有布局和样式，而 `.md` 文件保持纯粹的文字。对于超过一个框的长篇内容，链接多个 `text` 节点以进行手动分页；当内容不适合时，会触发 `text.overflow` 警告。 - **视觉效果** — 线性和径向渐变，分层阴影，高斯模糊，羽毛遮罩，12 种 Porter-Duff 混合模式，不透明度级联，每个角的半径和图像拟合/剪辑形状/对象位置。 - **锚点** — 相对于页面的 9 点放置，安全区，父容器或兄弟节点（优先级：zone > sibling > parent > page），所有这些都具体化为显式，确定性的几何形状（无锚点 = 与手动放置的坐标字节相同）。 - **程序化配方** — `recipes` 源代码块记录了生成的图案是如何制作的（种类，种子，生成器，参数，调色板令牌，扩展的节点 ID），可通过类型化的配方事务进行检查和编辑，因此程序化视觉效果保持可复制和可重新调整。 - **事务引擎** — 类型化的操作集（设置填充/描边/几何形状，添加/删除/重新父级/分组，对齐/分布，页面操作，令牌操作，查找替换，图案分离等）作为 **默认干运行** 应用，具有引用完整性和 ID 唯一性强制执行，源差异，场景差异，影响的节点 ID 和审计记录。 - **确定性渲染** — 通过 tiny-skia 实现像素精确的 PNG，并通过 print-ready PDF（原生 DeviceRGB/CMYK，MediaBox/TrimBox/BleedBox，无嵌入时间戳），单页，所有页面或对开页。场景 IR 可以导出为 JSON。 - **真实 PDF 文本，而非图片** — PDF 输出嵌入真实的，可选择的/可搜索的/可索引的文本（子集字体 + ToUnicode）和可点击的超链接，默认情况下； 在 `text`/`code` 节点上设置 `selectable=#false` 以将其渲染为轮廓。 `--embed-full-fonts` 嵌入整个面部以取代子集。 - **本地历史记录** — 文档身份（文件中戳记的 ULID doc-id，渲染器忽略），用于撤销/重做的临时会话 DAG 和具有命名版本的持久内容寻址版本存储（SHA-256 + DEFLATE） — 完全脱离渲染路径。 - **工作区草稿候选** — 内容寻址 `.zen` 快照用于设计探索，与历史记录一起存储：`scratch new` 记录候选，`scratch list`/`show` 审查它们，`candidate` 转换其生命周期（草稿 → 已选 | 已拒绝），`promote --into <page>` 将选定的候选合并到交付成果中，而 `finalize` 删除已拒绝的候选。 `bundle`/`unbundle` 将整个文档存储（历史记录 + 草稿）打包成一个便携的，确定性的 `.zenithbundle`。 - **库子系统** — 嵌入式预设包（`@zenith/flowchart`，`@zenith/filters`，`@zenith/masks`，`@zenith/brand-kit`）；`library add` 将项目物化为具有 `libraries` + `provenance` 跟踪的自包含文档。 使用 `zenith library show <pkg>#<item>` 检查任何项目。 - **AI 资产来源** — 当图像/插图来自图像模型时，Zenith 记录了它的制作过程：`ai-prompt`，`ai-model`，`ai-provider`，`ai-seed`，`ai-license`，`ai-source-rights`，`ai-safety-status`，`ai-reuse-policy`（连同 `sha256` 内容锁定）。 运行 `zenith schema asset` 获取完整的字段列表。 - **可变数据合并** — `role="data.<column>"` 绑定驱动 CSV 邮件合并跨文本和图像列以及多页面模板，具有每行 JSON 报告和字节可复制的清单。 - **自描述 CLI** — `zenith schema` 将可编写的表面（每个节点类型 + 其属性，事务操作集，令牌类型以及 `page`/`asset`/`document`/`variant`/`diagnostics`/`brand` 表面）作为人类文本或 `--json` 发出，因此代理可以从 CLI 本身发现它可以编写的内容，而不是猜测 — 与 `zenith validate` 的可操作诊断配对以进行修复循环。 </details> ## 验证 — 安全网 <details><summary>70 多项检查（错误/警告/建议），在渲染或打印前捕获错误、风险或品牌不符的问题。</summary> `zenith validate file.zen` 是使设计文件安全可编辑和可信赖的文件。它类似于编译器的类型检查器，但用于文档：它读取源代码并在渲染或打印前报告所有错误、风险或品牌不符的问题 — 因此代理（或您）永远不需要“渲染它并肉眼检查”以发现某些内容已损坏。 它运行 **70 多项检查**，每项检查都作为带有稳定代码（例如 `text.overflow`）、人类消息、受影响的节点 ID 和源位置的诊断报告。每项诊断都有三个严重程度之一： | 严重程度 | 含义 | 影响 | | --- | --- | --- | | **错误** | 确定的问题，会产生错误输出 | **阻止渲染** — `render` 拒绝并且 `validate` 以非零退出，直到修复 | | **警告** | 可能的问题或风险构造 | 仍会产生输出；值得一看 | | **建议** | 信息性注释 | 永远不会阻止；仅供参考 | 它实际检查的内容，用通俗的语言表达： - **结构和引用解析** — 每个节点 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`）。 为什么它很重要： - **对于人员** — 您在导出前就能发现“标题跑到页面外”、“灰色文字太难读”、“颜色不是品牌令牌”或“打印文件颜色空间错误”等问题。 - **对于代理** — `zenith validate --json` 是一个精确的、机器可读的契约。代理编辑源，验证，然后 **知道** 更改是否健全 — 安全网使无人工编辑值得信赖。 <p align="center"><img src="assets/showcase/loop.png" alt="代理循环：作者 → 验证 → 渲染 → 检查 → 编辑" width="620"></p> _{<i>由 Zenith 渲染 — 来源：<a href="assets/showcase/loop.zen"><code>assets/showcase/loop.zen</code></a>。</i>} </details> ## 变体 <details><summary>从一个设计中生成多个输出的两种方法：<code>zenith variant</code>（尺寸）和 <code>zenith merge</code>（数据）。</summary> 从一个设计中生成多个输出的两种互补方法 — 一种变化 **尺寸**，另一种变化 **内容**。 <p align="center"><img src="assets/showcase/variants.png" alt="一个典型设计以方形、故事和横幅尺寸渲染" width="900"></p> _{<i>由 Zenith 渲染 — 来源：<a href="assets/showcase/variants.zen"><code>assets/showcase/variants.zen</code></a>。</i>} ### 尺寸/格式变体（`zenith variant`） 声明一个 `variants` 块并将一个规范页面扩展为许多命名目标尺寸（方形、故事、横幅、广告位） — 每个都写入一个原生 `.zen` 页面和一个渲染的 PNG，可选地为每个目标覆盖（隐藏/显示节点、交换文本、更改填充）。源令牌编辑会自动传播到每个变体，并且锚定节点会重流到每个尺寸。 ```kdl 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 { } } ``` ```bash zenith variant poster.zen --out-dir out/ --manifest manifest.json ``` 生成是确定性的（相同来源 → 字节相同的输出 + 清单，`schema: zenith-variant-manifest-v1`）。 ### 数据邮件合并（`zenith merge`） 一个模板加上一个 CSV 变成 **每行一个渲染设计** — 用于本地化帖子、个性化图形、证书或活动变体。 将可变文本/图像节点标记为 `role="data.<column>"`（列是 CSV 头），然后合并： ```kdl # 在 poster.zen 中 — 将标题绑定到 CSV 的 “name” 列： 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" } ``` ```bash zenith merge poster.zen people.csv --out-dir out/ --name-by name --manifest manifest.json ``` 每一行都独立且确定性地渲染。 `--name-by` 按列命名文件（`Alice.png`、`Bob.png`）； `--manifest` 编写一个字节可复制的批处理记录（模板 + 数据哈希和每行来源）用于 CI。 图像列也可以使用 — `role="data.logo"` 图像节点会根据行交换其资产路径。 </details> ## 连接器 <details><summary>语义箭头，其端点源自其 <code>from</code>/<code>to</code> 节点 — 自动路由、箭头、自我循环和线路跳跃。</summary> `connector` 是两个节点之间的语义箭头。 它 **没有作者几何形状** — 您为其提供 `from` 和 `to` 节点 ID，引擎在编译时从这些目标的已解析框中派生两个端点。 移动任一框，连接器会自动重新路由； 相同的源始终产生相同的路径。 它是一个仅限描边的叶节点（无填充，无子节点）； 为使其渲染，需要 `stroke` 颜色。 - **端点锚定** — `from-anchor` / `to-anchor` 选择每个端点在 **九点网格** 上的位置：水平带（`left` / `center` / `right`）可选地与垂直带（`top` / `center` / `bottom`）组合，用连字符表示，例如 `top-left`，`bottom-center`，`center-right`。 裸令牌命名该边的中点（`top` = `top-center`）； `mid` / `middle` 是 `center` 的同义词。 默认值 `auto` 选择面对其他框的边缘。 - **路由模式**（`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` 和样式引用，遵循与其他基元相同的属性/样式级联。 ```kdl page id="pg" w=(px)640 h=(px)360 line-jumps="arc" { 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" } // 自动路由流程绕过 Block 而不是穿过它… connector id="e.flow" from="n.start" to="n.end" route="avoid" marker-end="arrow" stroke=(token)"c.flow" stroke-width=(token)"cw" // …当第二个连接器穿过它时，页面的 line-jumps 会跳过它。 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`](./examples/connector-routing.zen) 以获取一个完整的、可运行的文档。 </details> ## 命令界面 <details><summary>作者 · 渲染 · 编辑 · 变体 · 库 · 主题 · 历史 · 代理 — 每个命令都支持 <code>--json</code>。</summary> 运行 `zenith <command> --help` 获取标志（每个命令都打印描述和示例）。 每个命令都支持 `--json` 以获取机器可读的输出。 | 分组 | 命令 | | --- | --- | | **作者** | `new` · `validate` · `fmt` · `tokens` · `inspect` | | **渲染** | `render` (`--pdf` · `--scene` · `--all-pages` · `--spread` · `--page`) | | **编辑** | `tx`（类型化事务，默认干运行） | | **变体** | `variant`（一个设计 → 许多尺寸/格式）· `merge`（CSV 数据邮件合并） | | **库** | `library list` · `library add` | | **主题** | `theme new`（从品牌颜色合成令牌包） | | **历史** | `history` · `undo` · `redo` · `version` · `restore` · `sync` | | **工作区** | `scratch new/list/show` · `candidate <status>` · `promote --into <page>` · `finalize` · `bundle/unbundle` | | **代理** | `plugin install` · `plugin uninstall` · `plugin list` · `mcp` | </details> ## 历史与版本 <details><summary>本地文档编辑历史（快照、撤销/重做、持久命名版本）——完全独立于渲染路径。</summary> Zenith 为每个文档保存一个**本地编辑历史**，完全独立于渲染路径 - 它永远不会改变像素。在第一次编辑时，文档会被赋予一个稳定的身份：一个 ULID `doc-id` 被标记到文件中，并被渲染器忽略。从那时起，每次引擎编辑（`tx --apply`、`library add`、`undo`/`redo`/`restore`）都会被记录为一个完整的**快照**（状态，而不是操作日志），因此历史记录即使在手动编辑后也能保存。 ```bash zenith tx poster.zen recolor.json --apply # 编辑 - 自动记录 zenith undo poster.zen # 后退，覆盖文件 zenith redo poster.zen # 前进 zenith history poster.zen # 列出时间线（--json 适用于工具） zenith version poster.zen "launch-v1" # 保存命名版本，永久保留 zenith restore poster.zen launch-v1 # 恢复到该版本 zenith restore poster.zen @head~1 # ... 或恢复到修订规范：v2，@head~1，@latest:named，名称 zenith sync poster.zen # 捕获带外更改（GUI / 手动编辑 / git 签出） ``` 有两个层级。**撤销/重做** 在临时会话时间线中进行 - 快速、本地、适用于正在进行的作品。**命名版本** 是持久的、内容寻址的检查点（SHA-256 + DEFLATE），保留直到您删除它们；`restore` 可以跳转到任意一个。`sync` 是外部编辑如何折叠回历史记录以保持完整性的方式。历史记录是尽力而为的：如果无法写入，您的文件仍然保存 - 编辑永远不会被阻止。 </details> ## 与您的编码代理一起使用 <details><summary>通过 <code>zenith plugin install</code> 为 Claude Code / Codex / OpenCode / Cursor / … 安装技能，并为远程/CI 安装 MCP 服务器。</summary> Zenith 配备了一个技能，可以教 AI 编码代理如何驱动 CLI - 代理作者 → 验证 → 渲染 → 编辑循环，设计配方和 `--help` 无法传递的令牌/品牌纪律。为您使用的代理安装它： ```bash zenith plugin install # 自动检测已安装的代理，为您的用户安装 zenith plugin install --claude --codex # 选择特定代理 zenith plugin install --all # 所有支持的代理 zenith plugin install --claude --scope project # 进入 ./ for one repo zenith plugin list # 查看已安装的位置 ``` Claude Code、Codex 和 OpenCode 获得完整的目录技能（引用包、模板和主题）；其他代理（Cursor、Windsurf、Aider、Zed、Gemini、Copilot、Continue、Kiro、Antigravity）获得一个单独的自包含规则文件，指向自文档 CLI。写入是幂等的 - 随时重新运行以更新，或使用 `zenith plugin uninstall` 删除。 ### MCP 服务器（远程 / CI / 主机代理） 对于通过模型上下文协议发现功能的代理 - 或用于 CI 和托管/SaaS 管道 - Zenith 作为一流的 MCP 服务器运行。它**不是**一个薄 CLI 包装器：工具结果被修剪为结构化 JSON，通过单个 `zenith_schema` 工具按需获取模式详细信息，大型或二进制工件（渲染、大树、差异）以**资源链接**返回到内容寻址存储，而不是内联，文档可按 `doc-id` 地址 - 代理停止处理路径。完整的作者循环被公开 - `zenith_schema`、`zenith_validate`、`zenith_inspect`、`zenith_tokens`、`zenith_tx`、`zenith_render`、`zenith_fmt`、`zenith_merge`、`zenith_theme_new`，以及 scratch/candidate/promote/finalize 工作区工具。 通过 stdio 运行它（默认传输）： ```bash zenith mcp ``` 将任何 MCP 感知客户端指向它： ```json { "mcpServers": { "zenith": { "command": "zenith", "args": ["mcp"] } } } ``` ... 或者，对于 Claude Code：`claude mcp add zenith -- zenith mcp`。 **远程/托管服务。** 使用可选的 `http` 功能构建并在单个 `/mcp` 端点提供原生 Streamable-HTTP： ```bash cargo install --path zenith-cli --features http --locked zenith mcp --http 127.0.0.1:8080 # 测试它： curl -s -XPOST http://127.0.0.1:8080/mcp \ -H 'Content-Type: application/json' \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' ``` 工作区存储（scratch 候选版本、版本历史、渲染资源工件）位于 `$XDG_DATA_HOME/zenith`（默认为 `~/.local/share/zenith`）；设置 `ZENITH_DATA_DIR` 以在隔离/托管部署中重新定位它。 > **本地代理应首选 CLI + 技能**，而不是 MCP。直接运行 `zenith`（由 `zenith plugin install` 教授）是在环境可以运行二进制文件时最快的路径。当环境无法运行时，请使用 MCP 服务器 - 远程主机、CI、沙盒或托管/生产服务，您希望在协议后面提供完整的读写接口。服务器在那里是一流的。 存储库提供了一个 [`server.json`](./server.json)（MCP 注册表清单）。手动 **发布 MCP** 工作流发布了匹配的 npm 启动器和注册表条目，用于选定的稳定标签（通过 GitHub OIDC - 无需注册表令牌），因此 Zenith 可以从 MCP 目录中发现并通过 `npx -y @zenitheditor/zenith-mcp` 由客户端启动。 - MCP 注册表名称：`mcp-name: io.github.zenitheditor/zenith` </details> ## 工作区 <details><summary>一个 7-crate Rust 工作区；<code>zenith-core</code> 依赖于树中没有其他内容。</summary> Zenith 是一个 Rust 工作区。每个 crate 拥有一个关注点并公开一个稳定接口；`zenith-core` 依赖于树中没有其他内容。 | Crate | 责任 | | ---------------- | ----------------------------------------------------------------------------------------- | | `zenith-core` | KDL 解析器适配器、语义 AST、规范格式化、令牌、验证、诊断 | | `zenith-layout` | 文本塑形和字体度量（`rustybuzz` + `ttf-parser`）；第三方类型在此限定 | | `zenith-scene` | 后端中立的场景 IR + 编译（几何、文本包装、锚点、opacity/clip） | | `zenith-render` | CPU PNG 后端（tiny-skia）和矢量 PDF 后端；确定性强制 | | `zenith-tx` | 交易操作集、应用/试运行引擎、差异和审计记录合约 | | `zenith-session` | 本地机器文档标识、会话 DAG、持久版本（内容寻址存储） | | `zenith-cli` | `zenith` 命令行工具 - 调度、参数解析和 JSON/人类输出 | </details> ## 在您的存储库中 <details><summary>`.zen` 文件只是文本 - 提交它、在 PR 中审查、在 CI 中渲染、回滚。</summary> 因为 Zenith 文件只是文本，所以它存在于您的代码所在的位置。将它提交到 git。在拉取请求中与差异一起审查设计更改。在 CI 中渲染它，以在发布前捕获损坏的布局。在管道中生成变体。像其他文件一样回滚。设计不再是一个单独的世界，您导出和导入它，而是成为构建的一部分。 </details> ## 适用对象 <details><summary>AI/代理构建者、工程团队、大批量生产者、工具构建者。</summary> - **AI 和代理构建者** 需要可靠地生成和编辑视觉内容，而不是通过截图和祈祷。 - **工程团队** 希望存储库中有设计资产，在 PR 中审查，在 CI 中构建。 - **大批量生产者** - 市场营销、出版、本地化 - 需要大量正确的变体。 - **工具构建者** 希望在开放格式上构建，而不是封闭的云 API。 </details> ## 样板 <details><summary>可重复使用的 Zenith 示例位于 <code>zenith-showcase</code> 子模块中。</summary> 公共样板位于 [`zenitheditor/zenith-showcase`](https://github.com/zenitheditor/zenith-showcase) 并链接为 [`zenith-showcase`](./zenith-showcase) 子模块。 它是可重复使用的 Zenith 示例的存放地：`.zen` 源代码、渲染输出、视觉配方、操作、过滤器、背景、海报、传单、书籍、杂志、广告、图表、演示文稿和其他生成的设计作品。 仅当您有权利分享它们并且允许他人在声明的许可证下重用提交的源代码、输出和资产时，才将文件放入样板。如果私有、客户端、投资组合专用或自定义许可的工作，应改为从样板的外部画廊链接；外部作品的许可由所有者保留。 </details> ## 状态 Zenith 处于其首个公开发布系列中。作者 → 验证 → 编辑 → 渲染管道能够端到端运行：解析、诊断集、事务引擎、PNG/PDF 渲染、本地历史记录、库子系统和变数据合并均已实现并测试。格式、线路类型和命令界面可能会随着项目的成熟而继续演化。 ## 贡献 参见 [CONTRIBUTING.md](CONTRIBUTING.md) 以了解如何开发引擎，并参见 [AGENTS.md](AGENTS.md) 以了解绑定存储库约定（人类和代理贡献者的真实来源）。 ## 许可证 Apache-2.0。参见 [LICENSE](LICENSE)。