核心概念速览
在 Yumina 里创作互动体验，你只需要理解下面这七个核心概念。不多不少，刚刚好。
世界（World）
一个完整的互动体验包。
如果 Yumina 是一个游戏平台，那世界就是平台上的一个"游戏"。它不是单独的某个角色或某段剧情——它是把角色、故事、规则、UI、音乐全部打包在一起的整体。玩家点开一个世界，就进入了一段完整的沉浸式体验。
从技术层面看，一个世界包含：词条、变量、规则、组件、渲染器、音频轨道、各种设置……所有你需要的东西都在这一个包里。你可以把它理解成一个自给自足的小宇宙。
词条（Entry）
世界的内容碎片。
角色人设、场景描写、写作风格要求、示例对话、世界观设定——这些全都是词条。每条词条有一个"角色"标签（character、lore、plot、style、example 等等），告诉引擎这段内容是干什么用的。
词条有两种工作模式：
- 常驻型：标记了"总是发送"的词条，每次 AI 生成回复时都会被塞进提示词里。适合核心人设、基础世界观这类必须时刻生效的内容。
- 触发型：设置了关键词的词条，只在最近的对话中出现了匹配的关键词时才会被激活。比如你写了一条关于"黑市"的设定，只有当对话提到"黑市"时，这条内容才会被发给 AI。
打个比方：词条就像剧本的不同页面。AI 不会一次把整个剧本读完，而是根据当前情节需要，翻到对应的那一页。这样既保证了 AI 拥有足够的上下文，又不会浪费宝贵的 token 预算。
变量（Variable）
世界的记忆。
HP、金币、好感度、当前所在地点、背包里的物品列表……任何需要在回合之间"记住"的数据，都用变量来存。
变量支持四种类型：
- 数字（
number）：生命值、金币、回合数 - 文字（
string）：当前地点名、角色状态描述 - 布尔值（
boolean）：门有没有开、任务完成了没有 - JSON 对象（
json）：背包物品列表、复杂的人际关系网
每个变量还可以设分类标签（stat、inventory、resource、flag、relationship、custom），方便在编辑器里分组管理。数字变量可以设最小值和最大值，引擎会自动帮你夹在范围内。
变量就像游戏的存档数据。没有变量，AI 生成的每一段回复都是"失忆"的——不知道玩家上回合做了什么、角色还剩多少血。有了变量，世界才有了连续性。
指令（Directive）
AI 改变世界状态的方式。
只要你的世界里有变量，引擎会自动教 AI 用指令来改变状态——你不需要手动写格式说明。AI 会在回复末尾用 [health: -10] 这样的格式来报告变化，引擎检测到后自动更新对应的变量。
你要做的只是在变量的"行为规则"里用大白话写清楚"什么情况下该改这个变量"，AI 会根据这些规则自己判断什么时候输出指令。
常见的指令长这样：
| 写法 | 含义 |
|---|---|
[health: -10] | 生命值减 10 |
[health: +20] | 生命值加 20 |
[gold: 500] | 金币设为 500 |
[location: 酒馆] | 当前位置设为"酒馆" |
[quest_complete: true] | 标记任务完成 |
创作者不需要写任何代码。变量 + 行为规则 + 引擎自动注入的格式说明，三者配合就搞定了。
规则（Rule）
世界的自动化行为。
"当 HP 降到 0 时，触发死亡结局"、"每 3 回合饥饿度加 1"、"进入森林时播放森林背景音乐"——这些都是规则。
每条规则由三部分组成，像一个微型的因果链：
- WHEN（什么时候检查）：触发时机。可以是"每当变量变化时"、"每 N 回合"、"出现特定关键词时"、"会话开始时"等等。这是规则开始工作的"闹钟"。
- IF（满足什么条件）：可选的前置条件。比如"HP 小于等于 0"、"金币大于 100"。条件之间可以是"全部满足"或"满足任一"。如果不设条件，WHEN 一触发就直接执行。
- THEN（做什么）：具体的动作列表。可以修改变量、注入临时提示词给 AI、开关其他词条或规则、给玩家弹通知、播放音效……一条规则可以串联多个动作。
规则是让世界"活"起来的核心机制。没有规则，状态变化全靠 AI 自觉；有了规则，你就有了一张可靠的安全网——哪怕 AI 偶尔"忘了"扣血，规则也能帮你兜底。
组件（Component）
玩家看到的 UI 面板。
组件是绑定在变量上的可视化控件，显示在聊天界面旁边或上方。Yumina 内置了五种组件类型：
| 类型 | 用途 | 绑定的变量类型 |
|---|---|---|
| 血条（stat-bar） | 进度条，适合 HP、MP、耐力 | 数字 |
| 文字面板（text-display） | 显示格式化文本，适合当前地点、状态 | 数字/文字/布尔 |
| 图片面板（image-panel） | 显示图片，适合场景图、角色立绘 | 文字（URL） |
| 背包格子（inventory-grid） | 物品网格，适合道具栏 | 文字（JSON） |
| Web 面板（web-panel） | 自定义 HTML/CSS/JS 内容 | 无需绑定 |
组件绑定到变量后，变量一变，组件就自动更新。玩家被砍了一刀，HP 变量减少，血条立刻跟着缩短——不需要你写任何刷新逻辑。
你可以把组件理解成仪表盘上的仪表。引擎在后台默默更新数据，组件负责把数据变成玩家看得懂的画面。
渲染器（Renderer）
聊天消息长什么样。
默认情况下，AI 的回复就是普通的 Markdown 文本——和你在 ChatGPT 里看到的差不多。但这对于沉浸式体验来说太素了。
渲染器（messageRenderer）让你用 TSX 代码完全接管消息的展示方式。你可以把 AI 的文字回复变成：
- 带角色头像的气泡对话
- 视觉小说风格的立绘 + 对话框
- 像素风战斗日志
- 全屏的互动场景
- ……任何你能想象的样子
渲染器拿到的是 AI 的原始回复文本和当前的游戏状态，输出的是一段自定义的 React 界面。这意味着你可以根据变量值动态调整显示效果——比如角色濒死时让文字颜色变红，或者在不同场景显示不同的背景图。
渲染器是让你的世界从"聊天机器人"升级为"互动体验"的关键一步。
运行流程
当玩家发送一条消息后，引擎内部会依次经历以下阶段：
词条 --> 构建提示词 --> AI 生成回复 --> 解析指令 --> 更新变量 --> 触发规则 --> 渲染给玩家拆开来看每一步：
词条 --> 构建提示词：引擎扫描所有词条，把常驻词条和被关键词激活的词条按优先级和分区（system-presets、examples、chat-history、post-history）组装成完整的提示词，发给 AI。
构建提示词 --> AI 生成回复：提示词连同聊天历史一起发给大语言模型，AI 生成一段回复文本。回复以流式（SSE）方式逐字返回，玩家可以实时看到 AI 在"打字"。
AI 生成回复 --> 解析指令：引擎用正则表达式扫描 AI 的回复，找出所有
[变量名: 操作 值]格式的指令，提取出来。解析指令 --> 更新变量：引擎按照指令逐条更新游戏状态中的变量值。数字会被夹在 min/max 范围内，类型会被校验。
更新变量 --> 触发规则：变量变化后，引擎遍历所有规则，检查哪些规则的 WHEN 条件被满足了、IF 条件是否通过，然后执行对应的 THEN 动作。动作可能会进一步修改变量，引发更多规则——但引擎会控制递归深度，防止无限循环。
触发规则 --> 渲染给玩家：最终的回复文本和更新后的游戏状态一起交给前端。如果世界定义了自定义渲染器，就用渲染器来展示消息；否则按普通 Markdown 渲染。组件面板同步刷新，反映最新的变量值。
整个流程在每次玩家发消息时都会跑一遍。对玩家来说，他们只看到 AI 回复了一段精彩的文字、血条动了一下、背景音乐切换了——背后的这套流水线完全透明。
小结
不需要一口气全记住。
这七个概念之间是层层递进的关系：世界是容器，词条和变量是内容，指令是 AI 与引擎的桥梁，规则是自动化，组件和渲染器是展示层。先有个整体印象就够了。
后面的章节会逐个深入讲解每个概念的细节、最佳实践和常见坑点。遇到不确定的地方，随时可以翻回这一页对照全局。