用 JSON Schema 设计你自己的卡片结构：NovelForge 动态输出模型与 Schema Studio 详解-开发者社区

人工智能
AI 应用
AI 写作
桌面应用
后端
前端
知识图谱

【免费下载链接】NovelForge

AI辅助长篇小说创作，卡片式创作，支持基于 JSON Schema的结构化 AI 生成与上下文引用，可扩展性强。

项目地址：https://gitcode.com/gh_mirrors/no/NovelForge

NovelForge 是一款 AI 辅助长篇小说创作工具，它的核心玩法是卡片式创作：角色、场景、大纲、章节正文都以"卡片"为单位管理。而每张卡片长什么样——有哪些字段、哪些必填、字段间如何关联——由你通过JSON Schema 动态输出模型来定义。本文带你用内置的Schema Studio（结构构建器），零手写 JSON 地为卡片设计出可控、可复用、可被 AI 严格遵循的结构。

为什么 AI 生成长篇设定，需要 JSON Schema 约束？

让大模型"自由发挥"写一张角色卡，你大概率会拿到一段文字：内容看着不错，但字段忽有忽无、格式不统一，后续引用、筛选、注入上下文时全都对不上。

NovelForge 的思路是Schema-first（结构先行）：

每种卡片类型都先定义一份 JSON Schema，作为该类型的默认输出模型；
AI 生成时按这份结构做结构化输出与校验，字段粒度流式填充；
卡片编辑器 UI 也由同一份 Schema 驱动，所见即所得。

一句话：你先设计"表"，AI 只负责"填表"，填错会被拦住。

动态输出模型：类型层 + 实例层的双层结构

NovelForge 的结构定义分两层，这是理解整个体系的关键：

层级	定义位置	作用范围	对应数据
类型层	设置 → 卡片类型 → 编辑结构	该类型下所有卡片	`CardType.json_schema`
实例层	卡片编辑器 → 结构（Schema Studio）	仅当前这张卡片	`Card.json_schema`

后端模型定义在 backend/app/db/models.py：CardType与Card各自持有一份可选的json_schema。当某张卡片没有实例级结构时，它就"跟随类型"；一旦覆写，该卡片使用自己的结构，其他卡片不受影响。

三步定义类型级卡片结构（Schema 快速上手）

🔧第一步：打开设置 → 卡片类型，选中某个类型（或新增类型），点击面板底部的编辑结构（Schema）按钮，进入结构编辑。

🔧第二步：在左侧结构构建器中点"新增字段"，为每个字段配置：

名称 / 显示名：name（字段键，建议英文）+ 中文显示名（用于表单标题）；
类型：string、number、integer、boolean、tuple（元组）、relation(embed)（内嵌引用其他类型）；
数组 / 必填开关：控制该字段是否可重复、AI 是否必须输出；
注解：字段描述会写入 Schema 的description，这是提升 AI 结构化准确率的关键，写清楚"这个字段填什么、怎么填"；
示例：提供 JSON 示例，进一步帮 AI 对齐输出。

🔧第三步：右侧表单预览会实时按 Schema 渲染出编辑表单，下方同步展示生成的Schema JSON——三者联动，改字段即见结果。确认无误后点"保存到类型"，后续新建该类型卡片都会使用这个结构。

构建器的核心实现见 frontend/src/renderer/src/components/setting/OutputModelBuilder.vue 与 frontend/src/renderer/src/utils/outputModelSchemaUtils.ts（builderToSchema/schemaToBuilder负责可视化字段与 JSON Schema 的双向转换）。

Schema Studio 详解：对单张卡片覆写结构

类型结构是"模板"，但具体某张卡可能需要加字段或换字段。在卡片编辑器工具栏右侧，点结构按钮即可打开Schema Studio（frontend/src/renderer/src/components/shared/SchemaStudio.vue）：

Schema Studio 的交互布局是三栏式：

左侧：结构构建器（同上）；
右上：表单预览，实时渲染该卡片的编辑表单；
右下：Schema JSON只读展示，方便复制到其他工具中调试。

底部有四个关键操作：

按钮	作用
恢复跟随类型	清除实例级覆写，此卡恢复使用类型结构
应用到类型	把这张卡的结构提升为类型默认结构，后续新建卡全部生效
仅此卡生效	只把结构保存到当前卡片（写入`Card.json_schema`）
关闭	放弃修改

这个"实例 → 类型"的提升路径很实用：先在单张卡上试验新字段，验证好用后再一键推广到整个类型，风险最小。

结构复用：relation(embed) 与 $ref 组合能力

长篇项目里，"角色"这种结构会反复出现。与其在每个类型里复制一遍字段，不如用relation(embed)字段引用其他卡片类型的输出模型：

新增字段，类型选relation(embed)；
在"关系配置"下拉中选择目标输出模型（列表来自所有已定义json_schema的卡片类型）；
保存后，该字段在 Schema JSON 中表现为"$ref": "#/$defs/目标模型名"，目标结构自动挂载到当前模型的$defs中。

这样角色卡、场景卡等已有结构就能像"组件"一样被组合，搭建出复杂的复合卡片而不用重复维护。

有效 Schema：系统如何用它校验 AI 输出

保存结构后并不用你做任何事。当你在这张卡上点"AI 生成"时，后端会：

取出卡片的有效 Schema（实例级覆写优先，否则回退到类型级），接口返回中即effective_schema，见 backend/app/api/endpoints/cards.py；
通过 backend/app/services/schema_service.py 把$ref指向的其他类型结构合并展开成完整 Schema；
交给结构化生成运行时（backend/app/services/ai/generation/structured_runtime.py），AI 按 Schema 逐字段输出并做校验，"看起来能用、落地却混乱"的输出会被结构约束挡掉。

卡片级的 AI 参数（模型、提示词、温度、max_tokens、超时）也可单独配置，支持"重置跟随类型 / 应用到类型"，与结构的双层机制保持一致：

实践清单：设计卡片结构的 6 条建议

注解写透：每个字段的"注解"用一两句话说明填什么、格式如何，这是 AI 结构化输出准确率的第一杠杆；
尽量新增，不要改存量结构：修改已存在模型的结构可能与已有数据冲突，官方文档也特别提醒了这一点；
善用"先实例后类型"路径：新字段先在单张卡上试验（"仅此卡生效"），跑通后再"应用到类型"；
重复出现的结构抽成独立类型，再用relation(embed)嵌入复用，避免字段散落多处；
用"必填"区分核心字段：必填字段保证关键信息不缺位，非必填字段留给 AI 按需补充；
善用数组字段：如"卷内关键事件列表"这类天然可重复的内容，直接开数组开关即可。

小结

NovelForge 的动态输出模型把"卡片长什么样"的控制权交还给了你：类型层定义默认结构，实例层按需覆写并支持一键提升；Schema Studio用三栏联动的可视化方式让 JSON Schema 无需手写即可管理；relation(embed)+$ref让结构像组件一样组合复用。配合上下文注入（@DSL）与知识图谱，这套"Schema 驱动 + AI 结构化生成"的组合，正是它支撑数百万字长篇创作一致性的底层能力。

📖 延伸阅读：完整功能说明见 README.md 中的 "Schema-first：类型/实例结构与参数" 章节。