开源 Zine：让模型只管结构，视觉交给前端

项目地址：github.com/huaxustar/zine · MIT 协议 从 辣椒AI 的「AI 知识卡片」工具中抽取，重写为独立开源项目。

一、要解决的问题

把一篇文章、一份报告、或者一个主题，变成一套排版精美、可以直接发到社交平台的卡片。

看起来是个内容生成问题，实际上一大半是视觉问题。而视觉问题交给大模型处理，会遇到几件麻烦事：

• 模型生成的 HTML/CSS 质量不稳定，同一个提示词跑两次结果差别很大
• 想换个风格就得重新生成，每次都要花模型调用
• 生成的样式代码难以维护，出问题时无从下手
• 排版细节（字距、行高、留白节奏）模型基本不可控

为什么模型不适合做视觉

大模型在视觉设计上有几个结构性短板：

不一致性：同一个提示词"生成一篇关于气候变化的卡片"，两次生成的配色可能完全不同——第一次是绿色调、第二次是蓝色调。对开发者和用户来说，这意味着"同样的输入得到不同的输出"，体验不可预期。

不可控的细节：你可以告诉模型"间距大一点"，但它不一定理解"大一点"是 16px 还是 24px。排版系统需要精确控制，而模型的工作方式是统计近似——它在语义层面上很准确，在像素层面上很粗糙。

每次生成都要钱：如果生成卡片需要 5000 token 的输出（其中一半是 CSS），那每次调整风格都要花一次调用的费用。在运营场景中，一条内容做 3-5 个版本是常态，累积成本不容小觑。

二、职责切开

Zine 的核心决定是：模型只输出结构，前端负责全部视觉。

模型的输出是一份结构化数据：标题、每张卡片的要点、引述、需要强调的部分。它完全不知道最终长什么样——不生成任何一行样式代码。

前端拿到这份结构，套上主题类名渲染。于是：

长文/主题 ──▶ 模型 ──▶ 结构化卡片数据 ──▶ 前端渲染 ──▶ 卡片 ──▶ 导出 PNG
                        （无任何样式）      （主题决定视觉）

换主题只是换一个 class，零模型调用、零 token 消耗、瞬间完成。 用户可以把一整套卡片在各个主题之间反复切换，直到满意为止——这在"模型生成样式"的方案里是不可想象的（每切一次都要重新生成，还不保证质量）。

职责分离的三个收益

可预期：同样的内容换不同的主题，产出的视觉差异来自主题设计，模型输出是稳定的。用户知道"内容是正确的，我只在选择风格"。

可维护：视觉效果问题是前端问题——调行高、改配色、适配不同平台——这些应该在前端层面解决，而不是改提示词。主题代码是标准前端代码，可以用任何前端的调试和迭代方式来处理。

成本可控：模型只需要生成结构化数据（通常几百 token），不生成任何样式代码。对于需要大批量生成卡片的场景（比如一个运营团队要把 50 篇文章转成卡片），成本的差异会非常显著。

三、主题是一套排印系统，不是换色

我们对"主题"的定义比较严格：每一套主题都是完整的排印系统——字体栈、配色、装饰语言、留白节奏、层级对比，全套配齐。

不是同一套版式换个主色调。换色出来的东西看着就是同一个模板，用户一眼能看穿。

一个合格的 Zine 主题至少定义这些变量：

• 字体系统：标题字体、正文字体、代码/数字等宽字体。不同场景（正式报告 vs. 社交媒体）对字体气质的要求完全不同
• 配色系统：不仅仅是主色、辅色、背景色，还包括文字在不同背景上的对比度——这对于卡片在移动端的可读性至关重要
• 留白系统：页面边距、卡片间距、段间距、标题和正文之间的呼吸感。排版的核心是"没内容的地方"而不是"有内容的地方"
• 装饰系统：分隔线样式、强调标记、引用块样式。这些是主题个性的主要载体

卡片是纯 DOM 渲染的，所以任何 DOM 转图片的方案都能用来导出 PNG，不依赖特定的截图服务。我们推荐 html-to-image 或 dom-to-image，但如果你的部署环境不支持，也可以用自己的方案——Zine 输出的就是一个标准的 HTML 元素，不绑定导出工具。

四、关于主题的许可决策：一次值得记录的绕行

这件事我们想公开说明，因为它对做开源的人有参考价值。

Zine 最初版本的主题实现，在代码注释里标注"视觉质量参考"了两个上游项目。我们在准备开源时去核了这两个上游的实际许可：

而我们代码注释里写的是"均 MIT"——与上游实际许可不符。

这里的关键问题是：我们的主题文件到底是"独立重写、只借鉴了视觉风格"，还是"照搬了上游的 CSS 表达"？风格和思想不受版权保护，具体的代码表达受保护。这个判断只有最了解代码怎么写成的人才能下，看代码是确证不了的。

我们评估了三条路：

• A. Clean-room 重写——完全从零设计自有的排印系统，100% 自有，安全 MIT
• B. 确认为独立实现后纳入并致谢——但上游作者商业化姿态明确，仍有声誉风险
• C. 只开源内容引擎，主题留空交给社区——最保守，但首发缺少"开箱即用的好看卡片"这个卖点

我们选了 A。 主题系统按 clean-room 方式整体重写了一遍，以自家品牌视觉为基线，不含任何来自上游的代码或 CSS 表达，随仓库以 MIT 发布。原来的主题文件在上游产品和开源仓库里都被整体替换掉了。

这条路多花了一次设计工作量。但换来的是：这套视觉是我们自己的，可以放心用、放心改、放心让别人用。

给开源维护者的许可检查清单

写下这段是想说：开源前认真核一遍上游许可，是一件必须做的事。 注释里写的许可不算数，要去看上游仓库里到底有没有 LICENSE 文件、写的是什么。一份简单的检查清单：

1. 跑一遍 npm ls --all 或 pip freeze，列出所有直接依赖
2. 逐个确认每个依赖的 LICENSE 文件（不能只看 package.json 里的 license 字段——那个字段也可能写错）
3. 特别注意 copyleft 许可（AGPL、GPL），确认你的使用方式是否触发感染条款
4. 对"参考过"的上游（但没直接依赖），检查是否无意中照搬了代码表达
5. 写一个 NOTICE 文件，列出所有依赖及其许可

五、项目结构

zine/
├── packages/
│   ├── zine-core/    Python —— 提示词、解析、校验、生成
│   └── zine-react/   @zine/react —— 卡片组件 + 主题系统
├── examples/         可运行的完整示例
└── docs/             architecture.md · theming.md

同样支持 Anthropic 和 OpenAI 两种协议，一个环境变量切换，本地部署的模型也能用。

六、适合谁

• 内容创作者/运营——把一篇文章拆成一组适合社交平台的卡片。一篇 3000 字的长文章在公众号上合适，但在小红书、微博上需要拆成 3-5 张图文卡片——Zine 做这个拆解。
• 文档转卡片——发布说明、README、报告转成要点卡。技术团队最需要的其实是"把一份技术文档变成非技术同事也能理解的卡片"，Zine 的要点提取能力很适合这个场景。
• 学习笔记——把长文压缩成便于记忆的摘要卡。学生和研究者可以把一篇论文的要点提取为一组卡片，复习效率远高于重读原文。
• 开发者——把两个包嵌进自己的产品。如果你在做内容工具或知识管理产品，可以直接集成 Zine 作为"导出为卡片"的功能入口。

仓库：github.com/huaxustar/zine