火狐AI | 文档中心

切换主题

JSON 美化 ​

JSON 美化的核心思路是：让模型返回结构化 JSON，再由平台按 type 匹配模板，渲染成 HTML 和 CSS。

前言

  • 如果你只是想先做出效果，不打算手写模板，可以使用平台里的 JSON 美化助手。
  • 官方助手提供预览功能，支持将生成的模板快速应用至角色。

适用场景 ​

在真正动手前，先判断你要做的是哪一类。

1. 标准组件

适合做持续更新、和正文一起返回的数据模块，例如：

  • 状态栏
  • 任务卡
  • 背包 / 物资列表
  • 人物信息卡
  • 时间线 / 日志
  • 提示条 / 预警条

如果你需要 AI 在后续对话里持续更新数据，通常就属于这一类。

2. 首条小剧场

适合只在开局展示一次的内容，例如：

  • 开场说明
  • 角色介绍
  • 首次引导
  • 信息收集表单
  • 开局前置 / 后置说明
3. 全局样式

适合统一聊天区域的整体外观，例如：

  • 容器背景
  • 消息气泡
  • 日夜模式配色
  • 字体和整体氛围

它负责的是“整体外观”，不是具体业务数据。

选择方法

  • 只想改整体外观：选 全局样式
  • 只想开局展示一次：选 首条小剧场
  • 每次都需要更新的数据：选 标准组件

基础示例 ​

1. 定义 JSON 数据 ​

JSON 数据用于开场白或模型返回时，通过 type 字段匹配对应的美化模板。

md
```json
{
  "type": "status-card",
  "title": "指挥官简报",
  "comment": "保持冷静，优先稳定全排士气。"
}
```

JSON 数据必须放在 json code block 代码块中

text
- 头部写：```json
- 尾部写：```
- 确保前后换行，整体是合法 JSON
- 字段名、双引号、逗号都要写对

提示

  • type 是 JSON 的唯一标识，用于匹配模板和插槽
  • 剩余字段负责承载动态内容，支持数字、字符串、对象、数组、布尔类型
  • 字段名尽量使用英文，语义越贴近业务，模型更新越准确

2. 定义 JSON 模板 ​

进入角色卡编辑，新建 JSON 美化模板。

1. 填写 JSON 名称

  • 全局样式（消息气泡）
  • 开场小剧场
  • 顶部状态栏
  • 下一步行动

这是脚本的显示名称，只用于你自己识别和管理。

2. 填写 JSON 标识

  • status-card

JSON 模板真正的匹配标识就是 type。如果多个模板使用同一个 type，后者会覆盖前者。

提示

  • 模型返回的 {"type":"status-card"} 会匹配这个模板
  • type 建议使用语义清晰的英文命名，方便模型直接理解这段 JSON 的用途
  • 多个 JSON 模板需要嵌套时，可以通过 {{slot:status-card}} 语法占位，拼出更复杂的 HTML 结构

3. 定义 CSS 样式

css
.status {
  padding: 14px;
  border-radius: 12px;
  background: skyblue;
}

提示

  • 这里不需要再包 <style> 标签
  • 支持 @import 语法，可用于引入字体

4. 定义 HTML 模板

html
<div class="status">
  <h3>{{title}}</h3>
  <p>{{comment}}</p>
</div>

提示

  • 通过 {{ title }} 这类插值表达式，可以从模型输出的 JSON 中读取数据
  • 支持遍历、判断、插槽等模板语法
  • 字段缺失时默认输出空字符串

至此，最基础的 JSON 美化就搭好了。你可以在这个基础上继续扩充样式、结构和交互。

首条小剧场 ​

当 type 为 intro-before 或 intro-after 时，不需要去匹配正文里的 JSON 数据，平台会直接渲染你定义的 style 和 html。

它只在开场白中生效，适合表单信息收集、角色卡介绍、引导说明等场景。

  • intro-before：显示在开场白内容前
  • intro-after：显示在开场白内容后

提示

  • 支持插值表达式替换，比如 {{ user }} 和 {{ char }}
  • 但不会去匹配正文里的 JSON 块

全局样式 ​

当 type 为 global-theme 时，平台只会注入你定义的 style，html 不会生效。

适用场景：引入字体、聊天背景、消息气泡、剧情 HUD、状态面板等需要统一装饰的模块。

  • .markdown-body：消息容器类名
  • .markdown-dark：夜间模式类名

消息容器 ​

示例

css
/* 设置消息容器背景色和文字颜色 */
.markdown-body {
  color: #000;
  background: #ecf7ff;
}

/* 夜间模式 */
.markdown-dark {
  color: #fff;
  background: #1f2933;
}

提示

  • 你可以继续给消息容器补样式
  • 例如字体、边框、圆角、间距、渐变背景、伪元素装饰等

聊天气泡（p 标签） ​

这是一条 p 标签的气泡效果

第二条消息也会继承同样的样式

小手机 1v1 风格，类似微信 / WhatsApp

样式代码
css
@import url('https://fonts.googleapis.com/css2?family=ZCOOL+KuaiLe&display=swap');

.markdown-body {
  display: flex;
  flex-direction: column;
  gap: 16px;
}

.markdown-body p {
  margin: 0;
  width: fit-content;
  max-width: 75%;
  padding: 10px 16px;
  margin: 3px 1px;
  border-radius: 14px;
  border: 2px solid #FFD9C8;
  font-family: 'ZCOOL KuaiLe', "Comic Sans MS", cursive, sans-serif;
  background: #FFF9F5;
  color: #FF6B8B;
  font-weight: 500;
  word-break: break-word;
}

/* 夜间模式颜色适配 */
.markdown-dark p {
  background-color: #3B2830;
  border-color: #D87093;
  color: #FCE8EE;
}

对话气泡（q 标签） ​

这是一条 q 标签的对话气泡效果。适用于剧情 / 对白场景。句尾要带标点，样式才会生效。
样式代码
css
@import url('https://fonts.googleapis.com/css2?family=ZCOOL+KuaiLe&display=swap');

.markdown-body q {
  /* display: block：遇到对话就换行 */
  /* display: inline-block：正文和对话在一行 */
  display: block;
  width: fit-content;
  max-width: 85%;
  margin: 12px 0;
  padding: 10px 16px;
  background-color: #fff0f5;
  color: #5c3a41;
  border: 2px solid #ffb6c1;
  border-radius: 18px 18px 18px 4px;
  font-family: 'ZCOOL KuaiLe', "Comic Sans MS", cursive, sans-serif;
  word-wrap: break-word;
}

/* 夜间模式颜色适配 */
.markdown-dark q {
  background-color: #2b181d;
  color: #fce8ed;
  border: 2px solid #c25975;
}

提示

  • 多个 JSON 条目同时存在时，尽量不要重复定义同名样式
  • 同名规则如果重复出现，后面的样式会覆盖前面的样式

插槽与嵌套 ​

当你配置了多个 JSON 模板，且它们的 HTML 模板存在父子嵌套关系时，只需要在父模板里写上 {{slot:type}} 占位，系统就能自动建立父子关系。

渲染器会收集 AI 返回的 JSON 数据。即使返回顺序不固定，也能按模板关系把结构拼起来。

父级 HTML

html
<div>
  <h3>{{title}}</h3>
  <!-- slot 插槽：在这里插入 type 为 status-detail 的子模板 -->
  <div>{{slot:status-detail}}</div>
</div>

子级 HTML（type = status-detail）

html
<div>
  <p>{{name}}</p>
  <p>{{age}}</p>
</div>

什么时候才值得拆成多个模板？

  • 外层总卡片 + 内层明细
  • 概览区 + 详情区
  • 主卡片 + 子列表

如果只是普通状态栏、任务卡、人物卡，不需要一开始就拆得太细。

模板引擎 ​

JSON 模板渲染基于 LiquidJS，支持插值、条件判断、循环、过滤器等常用语法；采用沙箱执行，不支持任意 JS 代码，适合快速上手。

常用语法参阅：

结合 AI 辅助

  1. 先定义好需要展示的 JSON 数据和结构
  2. 把 JSON 数据示例发给 AI
  3. 让它按 LiquidJS 语法生成你想要的 HTML 模板和 CSS 样式

提示词怎么写 ​

和传统正则方案不同，JSON 美化要求 AI 显式输出需要更新的 JSON 块，并保持对应的 type 和字段结构稳定。

提示词要说清两件事：写在哪一段，以及要更新哪些 type 的数据。

1. 位置和格式 ​

推荐统一写在 后续历史指令 里，搭配 xml 或 yaml 结构描述。

基础示例

text
<Output_Format>
  <Response_Structure>
    - 回复内容必须按以下顺序输出：
    1. state（顶部信息）
    2. 正文叙事与 NPC 对话（自然语言）
    3. status（状态栏）
    4. quicks（下一步行动）
    - JSON 与叙事文本之间不得交叉、嵌套或混合
  </Response_Structure>

  <JSON_Return_Protocol>
    - 根据最新剧情与上下文，更新 state、status、quicks JSON 中的数据
    - 仅更新必要字段，未发生变化的字段与上一状态保持一致
    - 禁止更改 JSON 数据中的 type 字段
    - 禁止更改 JSON 数据的字段与数据结构，禁止新增或删除字段
    - 禁止在 JSON 中加入解释性文本或注释
    - 确保 JSON 格式能够被 JSON.parse 解析
  </JSON_Return_Protocol>
</Output_Format>

2. 通用提示词 ​

适合开场白里已经携带 JSON 数据，不需要额外再告诉模型整套 JSON 长什么样。

基础示例

text
1. 结合上下文，根据最后一个 type=xxx 的 JSON 数据，进行相应更新并返回
2. 保持 type 字段不变，仅更新其余字段
3. 如果某个字段信息未知，用 "" 或简短说明代替

# 扩展（结合剧情任意输出数量）
例：至少包括 1 个 status-card 和 1~3 个 status-detail

3. 1v1 小手机（类似微信） ​

适合已经定义好全局样式，并且已经实现气泡效果的场景。

基础示例

text
对话风格要求：
1. 以角色身份回复用户，使用对话式语言。
2. 回答简短、口语化，禁止大段叙述。
3. 聚焦当下对话，不预先推理或解释。
4. 用真诚直接的语气回应 {{user}}，可以黑暗、负面或冲动。
5. 使用生活化语言，偶尔自然地带一点表情。

对话环境：
- 发生在即时聊天软件内，双方没有见面，也没有旁白。
- 根据上下文，回复 1~5 条消息，多条消息使用换行分隔。

提示

  • 某个字段比较特殊时，可以补充对应的 xml/yaml 举例，或者额外强调更新规则
  • 开场白里已经带了初始 JSON，一般不需要把整份 JSON 再贴一遍，强调 type 即可
  • 当字段很多、模型容易漏字段时，再附带字段清单或示例 JSON，让它逐项补齐
  • 如果开场白没有定义 JSON，而是通过世界书触发，就需要列出完整的 JSON 结构和更新规则

更多参考 ​

字段怎么定义更稳 ​

比起“字段多不多”，更重要的是“字段清不清楚”。

1. 字段要服务于展示 ​

适合放进 JSON 的内容说明
时间、地点、名称适合直接展示在界面上
状态、数值、进度、等级适合做面板、状态栏、进度显示
对象、列表、状态面板适合驱动结构化渲染
不适合放进 JSON 的内容原因
一大段剧情原文不利于展示，也不利于结构化处理
固定不变的内容更适合直接写在模板或文案中
换行多、标点多的文案需要转义、容易出错、不方便维护

2. 字段要简单且有语义 ​

推荐写法为什么更稳
title一眼能看出字段用途
location表意明确，便于维护
weather语义直接，适合展示
progress适合进度类数据
status适合状态类展示
items适合列表数据
不推荐写法问题
value1含义不明确
dataA可读性差
extraInfo边界模糊，越更新越杂
other什么都能塞，模型更新目标不明确

3. 结构尽量扁平 ​

优先把字段写得简单、扁平一点。

别一开始就堆很多层嵌套，否则后面改起来会很累，AI 也更容易漏字段。

定义字段的简单方法

先问自己一句：“这项信息，用户在界面上是不是要单独看到？”

如果答案是“要”，它就适合做成字段。

如果只是剧情里顺带提到、并不会单独展示，那通常不必放进 JSON。

JSON 数据自修复 ​

部分模型可能会返回格式不完全正确的 JSON，比如标点或引号有问题。平台会尽量把它修复成可用 JSON，避免界面直接渲染失败。

如果你遇到页面里的 UI 正常，但某段文案明显不通顺或缺失，可以先点开编写消息查看原始内容，确认模型返回的 JSON 是否有问题。

这类问题通常手动修一下就能解决，也可以把有问题的 JSON 发给 AI，修好后再贴回消息里。

注意事项 ​

  • JSON 对格式有严格要求，请始终使用正确的双引号、逗号和英文键名
  • 开场白中的 JSON 数据必须使用 json 代码块包裹，并保证前后换行
  • 字段语义化：name、age 比 value1、value2 更容易让 AI 理解字段含义和更新逻辑
  • 可以使用在线工具快速校验或格式化 JSON

相关链接：

火狐AI 产品文档

Copyright © 2026 Huohu AI