企业官网建设流程全解析

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

NovelForge 是一款 AI 辅助长篇小说创作工具，它的 AI 卡片生成功能并非"一次性吐出整段结果"，而是采用字段粒度流式生成：大模型以"指令流"的方式逐字段写入卡片，前端实时渲染、用户可随时反馈纠偏。本文带你剖析这套指令流生成架构的实现原理，看看它如何让 AI 生成过程既快又稳。

传统整段生成为什么不够用

在 v0.9.0 之前，很多 AI 写作工具的卡片生成方式是"点击生成 → 等待几十秒 → 拿到一整段 JSON"。这种方式有三个痛点：

• 等待焦虑：卡片字段一多，生成时间可达分钟级，中途毫无反馈；
• 要么全对要么全错：只要结构校验失败，只能整卡重新生成；
• 无法中途纠偏：AI 写歪了方向，用户只能干等结束后推倒重来。

NovelForge 的解法是指令流（Instruction Stream）：让 LLM 像"打字员"一样，一边用自然语言思考，一边逐行输出单行 JSON 指令，每写一个字段就立刻落库到卡片上。

上图中，右下角的 AI 生成面板正在逐条执行"设置字段: character_action_list"等指令，左侧卡片表单同步填充，这就是字段粒度流式生成的实际效果。

总体架构：一条四段式流水线

整个流程横跨前后端，核心代码集中在backend/app/services/ai/generation/目录：

1. 提示词构建：prompt_builder.py 把"卡片任务提示词 + 指令流生成规范 + 目标 JSON Schema"拼成 System Prompt；
2. 流式调用与逐行解析：instruction_generator.py 通过chat_model.astream拉取 LLM 流式输出，边收边解析指令；
3. 实时校验与自动修复：instruction_validator.py 对每条指令做路径、类型、约束校验，失败则反馈给 LLM 重生成；
4. SSE 事件下发与前端执行：ai.py 将事件以 SSE 流推给前端，instructionExecutor.ts 机械地应用指令并刷新表单。

用户只需在"开始生成卡片"对话框中给出要求（如"阶段数量不要超过5个"），点击"开始生成"，指令流就启动了。

核心设计：set / append / done 三种指令

指令流的规范定义在 指令流生成规范.txt 中，LLM 只被要求掌握三种单行 JSON 指令：

{"op":"set","path":"/main_target/story_type","value":"主线"} {"op":"append","path":"/hobbies","value":"阅读"} {"op":"done"}

• set：按 JSON Pointer 路径给字段赋值，支持整个对象或深层子字段两种粒度；
• append：向数组字段逐个追加元素，天然适合"标签列表、角色列表"这类内容；
• done：声明生成结束，触发系统做最终完整性校验。

关键在于：指令之间允许穿插任意自然语言。LLM 可以"先思考、再动手"，思考内容会被后端识别为thinking事件推给前端展示，用户因此能实时看到 AI 的思路，而不只是一片空白。

字段粒度流式的实现细节：逐行解析 JSON

流式输出最大的难题是：JSON 会被网络切成任意碎片，如何可靠地从中提取完整指令？instruction_generator.py 的答案是一个轻量状态机：

• 行缓冲：把 chunk 累积进buffer，按\n切分出完整行，不完整的半行保留到下一轮；
• 逐字符扫描：用brace_depth（花括号深度）、in_string（是否在字符串内）、escape_next（转义标记）三个变量跟踪 JSON 边界，只有字符串外的花括号才计数，避免值里包含{时误判；
• 宽容解析：单行 JSON 解析失败时，会先尝试清理尾部逗号等常见错误；仍失败则记入failed_instructions，累积到 5 条才强制中断流，避免偶发噪声毁掉整轮生成；
• 思考分流：不在 JSON 累积过程中的自然语言行，直接作为thinking事件下发。

这样，"生成一个字段"就是流中最小的交付单元——一个set指令被解析校验后，前端表单立刻多出一个已填好的字段。

实时校验与自动修复：Schema 是安全网

每条指令在执行前都要过 instruction_validator.py 这一关：

• 路径校验：path是否真实存在于目标 Schema 中（自动兼容$.xxx、items[0]等写法，统一转为 JSON Pointer）；
• 类型校验：值的类型、enum枚举、字符串长度、数值范围、数组长度约束逐一检查，且支持$ref与allOf递归解析；
• 完整性终检：收到done时，后端用build_model_from_json_schema动态生成 Pydantic 模型，对累积数据做一次整体校验，缺失的default值会被自动注入。

一旦校验失败，系统不会把错误抛给用户，而是构造修复提示（包含失败指令、当前已应用数据、缺失字段清单）追加进对话，让 LLM 继续补写；重试采用指数退避（1s/2s/4s），默认最多 3 轮。这个"校验—反馈—修复"闭环，是把不稳定的 LLM 输出兜底成可靠数据的关键。

卡片的 Schema 来源就是 image-13 所示的结构构建器——在"设置 → 卡片类型"中为每种卡片定义字段结构，这份 JSON Schema 同时驱动表单渲染、AI 参数配置与上述所有校验。

前端执行层：SSE 事件与轻量指令执行器

后端通过/api/ai/generate/stream端点（ai.py）以 SSE（data: {json}\n\n）格式推送五类事件：thinking、instruction、warning、error、done。

前端 generation.ts 中的generateWithInstructionStream用fetch+ReadableStream逐行解析 SSE，事件类型与后端一一对应（见 types/instruction.ts）。解析出的指令交给 InstructionExecutor 执行——由于所有校验已在后端完成，前端只用 lodash 的set/get机械落值，再把 GenerationPanel.vue 的消息流（思考、动作、警告）展示出来，形成"已生成 N 个字段"的进度反馈。

生成所用的模型、提示词、温度、最大 tokens 均可在卡片类型设置页配置（如上图），也支持在编辑器工具栏按单卡微调。

这套架构带来了什么

• 秒级首反馈：第一个字段落地只需几秒，用户全程可见进度；
• 低成本纠偏：对某个字段不满意，直接在输入框写指导意见即可让 LLM 局部重写，不必整卡重来；
• 截断自愈：LLM 未发done就断流时，系统会检测缺失字段并自动发起补全，而不是把残缺数据交给用户；
• 人机协同节奏：思考（thinking）与动作（instruction）分离展示，生成过程本身成了可读的"创作日志"。

从"整段等待"到"字段粒度流式生成"，NovelForge 用一套极简的三指令协议 + 逐行 JSON 状态机 + Schema 双层校验，把 LLM 的不确定性收敛在了每个字段的最小单元里。这套"指令流 + 实时校验 + 自动修复"的设计模式，同样适用于任何需要结构化 AI 输出的场景，值得参考。

相关模块路径速查：

• 指令流生成服务：instruction_generator.py
• 指令校验器：instruction_validator.py
• System Prompt 构建：prompt_builder.py
• 指令流规范提示词：指令流生成规范.txt
• 前端指令执行器：instructionExecutor.ts

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