莉莉宝

关于本站

Mon, 26 Oct 2026 00:00:00 GMT

🛠️ 关于本站#

这个网站使用 Astro 框架构建，采用了 Firefly 模板，Firefly 是基于 Fuwari 的二次开发。

Firefly 是一款基于 Astro 框架和 Fuwari 模板开发的清新美观且现代化个人博客主题模板，专为技术爱好者和内容创作者设计。该主题融合了现代 Web 技术栈，提供了丰富的功能模块和高度可定制的界面，让您能够轻松打造出专业且美观的个人博客网站。

🖥️在线预览： Firefly - Demo site

📝Firefly使用文档： https://docs-firefly.cuteleaf.cn

⭐Firefly开源地址：https://github.com/CuteLeaf/Firefly

⭐Fuwari开源地址：https://github.com/saicaca/fuwari

进阶技巧

Mon, 26 Oct 2026 00:00:00 GMT

宏：{{user}} 和 {{char}}#

宏是写在卡里的占位符。酒馆在发给 AI 之前（以及显示消息时）把它们换成实际内容。最常用的是 {{user}} 和 {{char}}。

常用宏#

宏	换成什么	例子
`{{user}}`	玩家当前用的名字	「{{user}}推开门」→「小明推开门」
`{{char}}`	当前角色的名字	「{{char}}抬起头」
`{{random::晴::雨::雪}}`	每次随机取一个	天气随机
`{{pick::晴::雨::雪}}`	随机取一个，但同一个聊天里固定不变	开局随机身份
`{{roll::1d20}}`	掷骰子	判定
`{{getvar::名字}}`	读聊天变量	好感度
`{{time}}`、`{{date}}`	现在的时间、日期	现实时间问候
`{{// 这是注释}}`	什么都不输出	给自己写备注

MVU 变量卡还会用 {{get_message_variable::stat_data.路径}} 读变量，见 mvu-statusbar。

为什么一定要用 {{user}}#

角色卡是给所有人用的。如果你在卡里写死「小明」，别人用时 AI 就会管他叫小明。所以：

指代玩家，一律写 {{user}}；
指代角色本身，可以写名字，也可以写 {{char}}。多角色卡（一张卡里好几个人）里 {{char}} 只是卡名，具体人物还是写名字更清楚。

容易踩的坑#

尖括号写法也会被替换：酒馆把 <USER>、<BOT>、<CHAR>（不分大小写）当成旧式宏，自动换成名字。你在界面代码里写了 <user> 这类标签，会被吃掉，见 pit-macro-escape。
反斜杠被去掉：新版宏引擎会把 \{、\} 前面的反斜杠删掉（这是给「想原样写出双花括号」准备的转义）。代码里的 \{ 会变成 {。
花括号连写：代码里两个花括号紧挨着（比如 {{a:1}} 这种嵌套写法），可能被当成宏处理。中间加个空格最保险。
宏在正则替换结果里也会执行：正则的「替换为」内容在显示前也会做一次宏替换。
AI 自己写出的 {{user}}：反过来 AI 输出里出现字面的 {{user}}，通常是卡里示例写法教坏了它。

不想被替换的文字被当成了宏#

现象：界面里的 <user> 标签变成了玩家名字；规则里写的「{{user}}」示例被替换掉了；代码里的双花括号莫名其妙变了样。

为什么#

酒馆会在很多地方做宏替换：角色描述、开场白、世界书、预设，以及正则替换后的结果。除了 {{user}}、{{char}} 这类宏，还有几个老写法也会被替换：

写法（不分大小写）	被替换成
`<USER>`	玩家名
`<BOT>`、`<CHAR>`	角色名
`<GROUP>`、`<CHARIFNOTGROUP>`	群聊成员 / 角色名

所以界面标签起名叫 <user>、<char>，会被直接换成名字。

常见中招场景#

让 AI 输出 <User>...</User> 这样的标签：标签名被换掉，正则匹配不到；
在规则里想给 AI 看「{{user}} 这个写法」：AI 看到的是名字；
界面代码里有双花括号（模板语法、嵌套对象）：可能被当成宏处理；
用了 {{random::...}} 却希望每次结果固定：random 每次都重新抽，固定的要用 {{pick::...}}。

怎么办#

标签别用这几个名字：改成 <玩家>、<主角>、<player_info> 等；
想原样显示花括号：写成 \{\{user\}\}，酒馆会去掉反斜杠，保留花括号；
代码里的双花括号：中间加个空格，写成 { { 或拆开写，最保险；
查找规则里有宏：正则设置里的「正则表达式查找时的宏」决定查找内容里的宏是否先替换，一般选「不替换」。

容易踩的坑#

只在某些地方被替换：开场白里被替换、AI 回复里不被替换，同一个标签表现不一致，很难查；
正则替换内容里的宏最后才替换：替换内容里写 {{user}} 会变成名字，这通常是想要的，但写在代码里就要小心；
未知的宏一般原样保留：拼错的宏不会报错，只是没效果，检查一下有没有拼错。

EJS 模板#

EJS 是一种「带条件的文字」写法：同一个世界书条目，可以根据变量输出不同的内容。比如好感度低时发「她对你很戒备」，高了才发「她开始信任你」。

需要什么#

酒馆本身不认识 EJS，要装提示词模板扩展（ST-Prompt-Template）。没装的话，<% %> 会原样发给 AI，既没效果又浪费 token。

基本写法#

1
<% if (getvar('stat_data.沈清.好感度') >= 60) { %>
2
沈清已经把{{user}}当成可以托付的人，会主动说起家里的事。
3
<% } else { %>
4
沈清对{{user}}仍有防备，只谈铺子里的事。
5
<% } %>

<% %> 里写判断，不会输出；
中间的普通文字按条件输出；
getvar('路径') 读变量，MVU 卡的变量在 stat_data 下，见 mvu-schema。

适合做什么#

阶段解锁：好感度、章节到了才放出的剧情、秘密；
按状态切换描述：受伤 / 健康、白天 / 夜晚；
省 token：不满足条件的大段内容根本不发。

容易踩的坑#

语法错一点，整条报错：括号、%> 少一个，整条内容都会出问题。改完一定在酒馆里试；
变量路径写错：路径不存在时读到的是空，条件永远不成立。路径要和变量结构一字不差；
别人没装扩展：卡用了 EJS，要在创作者注释里写明需要装提示词模板，见 card-creator-notes；
简单需求不必用 EJS：「到第几轮才出现」可以用世界书的延迟，见 worldbook-timed。

去 AI 味#

「AI 味」就是一读就知道是 AI 写的那种文风。卡里的文字会成为 AI 模仿的范本，所以卡本身没有 AI 味，聊天时 AI 味才会少。

常见的 AI 味#

毛病	例子
高频套话	「仿佛」「不禁」「一丝」「嘴角勾起一抹弧度」「眼中闪过一丝」
比喻堆砌	一段话三个「像……一样」
总结升华	每段结尾都来一句「这一刻，他终于明白了……」
对话工整	每个人说话都是完整书面句，没有口头禅、没有打断
情绪直说	「她感到非常难过」而不是写她做了什么
结构八股	环境描写 → 动作 → 对话 → 心理，每段都一样
万能温柔	不管什么人设，最后都变得体贴、包容、治愈

怎么去掉#

写具体，不写形容词：「她很冷淡」不如「她看都没看你，把账本翻过一页」；
给说话方式：口头禅、方言、句子长短、爱不爱用敬语，最好配示例，见 card-example-dialogue；
开场白就定好文风：AI 会模仿开场白的篇幅和写法，开场白写得干净，后面就干净，见 greeting-forms；
允许角色有缺点：冷淡就一直冷淡，不要写「但内心其实很温柔」，除非这是你想要的；
禁词表：在 App 的设置 →「禁词表」里加词，写卡时会要求模型避开，检查时会统计出现次数。

容易踩的坑#

禁词加太多：几百个禁词会让模型束手束脚，写得别扭。只放最刺眼的几十个；
在卡里写「不要有 AI 味」：模型不知道什么是 AI 味，要说具体的「不要用比喻」「对话用短句」；
反例写进卡里：「不要写『嘴角勾起一抹弧度』」反而会让模型更容易写出这句。尽量用正面描述。

容易踩的坑#

把自己的密钥写进卡：测试时在代码里填了 API 密钥，导出分享就泄露了。扫描会报「疑似 API 密钥」；
远程资源被墙或失效：CDN 链接在国内可能打不开，见 pit-cdn。

角色卡编写

Mon, 26 Oct 2026 00:00:00 GMT

创作者注释：写给玩家的说明书#

「创作者的注释」是写给玩家看的，不会发给 AI。玩家导入卡后在角色信息里能看到。好的说明能省掉一大半「怎么用不了」的提问。

建议写这些#

一句话简介：这张卡玩什么；
需要什么：要不要酒馆助手、提示词模板等扩展，推荐什么模型；
导入后要做的事：允许局部正则和脚本、导入世界书、开新聊天；
玩法提示：有哪些开场白、变量怎么用、有什么隐藏内容；
已知问题：哪些预设或美化主题会冲突；
版本记录：改了什么，旧聊天要不要重开。

一个模板#

1
【简介】民国经营 + 慢热恋爱，你扮演沈家铺子新来的账房。
2
【需要】酒馆助手（状态栏、选项按钮）。
3
【导入后】
4
1. 弹窗问是否允许正则、脚本时选「是」；
5
2. 弹窗问是否导入世界书时选「是」；
6
3. 开新聊天，左右滑动第一条消息可以选开局。
7
【推荐】Claude / Gemini，预设不要禁止覆盖主要提示词。
8
【更新】v1.1 修复状态栏不显示，请开新聊天。

容易踩的坑#

把规则写在这里：这里的内容 AI 看不到，写了也没用；
只写简介不写用法：玩家最常卡在「允许脚本」和「导入世界书」这两步，一定要写，见 pit-allow-scripts 和 pit-embedded-book；
用了特殊排版：不同版本酒馆显示效果不同，用简单的文字和换行最稳。

角色描述怎么写#

角色描述是卡里最重要、每轮都发的部分。它决定 AI 把这个角色演成什么样。

该写什么#

项目	写什么	例子
基本信息	姓名、年龄、身份	沈清，二十二岁，沈家绸缎庄的大小姐
外貌	两三个有辨识度的特征	总穿旧了的月白旗袍，左手戴一只银镯
性格	用行为表现，写清矛盾面	嘴上刻薄，但伙计生病会偷偷塞钱
说话方式	语气、口头禅、句子长短	说话短，爱用反问；生气时反而更客气
过去	只写影响现在行为的部分	父亲破产后自杀，她不信任任何「好心人」
和 {{user}} 的关系	怎么认识、现在怎么看对方	认为{{user}}是债主派来的眼线
目标 / 动机	角色现在想要什么	想在年底前保住铺子

写法建议#

写行为，不写形容词：「温柔」AI 只会演成万能好人；「会记得你随口说过不吃葱」才是具体的温柔；
写清边界：她绝对不会做什么？什么话题会让她翻脸？
结构化更稳：可以用标签包起来的条目式写法，模型更好区分，见 worldbook-format；
控制长度：一般几百到一千多字。更多的背景、配角、地点放进世界书，提到才发。

描述和世界书怎么分#

描述：每轮都要用到的核心人设；
世界书：配角、地点、组织、历史事件等「提到才需要」的内容。

有的卡把人设也全放进世界书（常驻条目），描述留空或只放一句摘要。效果差不多，关键是不要两边各写一遍，重复内容既占 token 又可能前后矛盾。

容易踩的坑#

写成小说：大段抒情描写对 AI 没用，它需要的是「怎么演」；
用固定名字指代玩家：一律用 {{user}}，见 macros；
自相矛盾：前面写「从不说谎」，后面写「为了保护家人撒过谎」，AI 会随机选一个演；
全是优点：没有缺点的角色很无聊，而且 AI 会越演越「圣母」，见 de-ai。

示例对话#

示例对话是给 AI 看的「说话样本」：角色在什么情况下会怎么说话。比起在描述里写「说话刻薄」，给两段真实对话效果好得多。

格式#

每一段以 <START> 开头，下面一行一句，用 {{user}}: 和 {{char}}: 标出谁在说：

1
<START>
2
{{user}}: 账我对完了，去年少了三百块。
3
{{char}}: 少了？（她终于抬起头）你知道上一个这么说的人现在在哪吗？
4
<START>
5
{{user}}: 你吃饭了吗？
6
{{char}}: ……关你什么事。（停顿）厨房还有半碗粥，自己去热。

<START> 表示「这是一段新的示例」，酒馆发送时会换成对应的分隔格式。

怎么写好#

覆盖不同情绪：平时、生气、害羞、示弱，各给一小段；
短而准：每段两三个来回就够，重点是语气；
写出角色独有的东西：口头禅、断句方式、爱用的动作；
{{user}} 的台词尽量简单：示例是给角色立规矩的，玩家的话只是引子。

什么时候发给 AI#

酒馆的「用户设置 → 聊天/消息处理 → 示例消息行为」有三个选项：

选项	效果
逐渐推出（默认）	上下文够就发；聊天记录长了会把示例挤出去
始终包含	一直发
永不包含	不发

所以默认情况下，示例对话主要影响开头的几十轮，后面聊天记录本身就成了样本。

容易踩的坑#

在示例里替 {{user}} 做很多事：AI 会学着抢话；
示例太长：占上下文，而且挤掉聊天记录；
写成剧情：示例里的事件 AI 可能当成「发生过的事」，在聊天里提起。示例要通用，别写具体剧情；
和开场白风格不一致：AI 会摇摆不定。

卡里的系统提示与历史后置指令#

角色卡的「高级定义 → 提示词覆盖」里有两个框：

主要提示词（卡里的系统提示）：替换预设里的「主要提示词」；
历史后置指令：替换预设里同名的那一块，它在聊天记录之后，离最新消息最近。

什么情况下会生效#

卡里写了主要提示词，酒馆默认会用它替换预设的主要提示词。但以下任一情况，卡里的就不生效：

「用户设置 → 角色处理 → 角色卡提示词优先」被关掉了（历史后置指令对应「首选角色卡指令」）；
预设里「主要提示词」这一块勾了 「禁止覆盖」；
预设里「主要提示词」这一块被关掉了。

很多流行预设会禁止覆盖或者干脆不用主要提示词，所以别把关键设定只放在这里，见 pit-char-prompt。

保留预设原文#

在卡的主要提示词里写 {{original}}，会在那个位置放回预设原来的主要提示词。这样你可以在预设的基础上追加，而不是整个替换：

1
{{original}}
2
本卡为多人群像，每次回复聚焦一到两个角色。

适合写什么#

主要提示词：这张卡的整体玩法说明，比如「这是一个经营类故事，{{user}}是账房」；
历史后置指令：短小、每次都必须遵守的要求，比如「回复末尾必须输出 <options> 标签」「不要替{{user}}说话」。

容易踩的坑#

写太长：历史后置指令紧贴最新消息，写一大段会严重干扰 AI 的回复；
和预设打架：预设要求第三人称，卡要求第二人称，AI 会摇摆。卡里明确写出你的要求，并在创作者注释里提示玩家；
把世界观放这里：设定应该放描述或世界书，这里只放「怎么写」的要求。

V2 / V3 卡与 PNG 内嵌#

角色卡有两种通行格式：V2 和 V3。你平时不用管它们的区别，但遇到「导入失败」「导入后内容不对」时，知道一点会好排查。

V2 和 V3#

V2（格式名 chara_card_v2）：用得最久、最通用。所有内容放在 data 里，卡内世界书叫 character_book。
V3（格式名 chara_card_v3）：在 V2 基础上扩展，加了资源列表、多语言创作者注释等。新版酒馆都能读。

两者的核心字段（描述、开场白、世界书……）基本一样，V3 卡在不支持它的旧工具里通常也能当 V2 读。

PNG 里怎么藏一张卡#

PNG 图片除了像素，还能带「文字附件」（技术上叫文本块）。角色卡把整份内容编码后放进文字附件：

V2 的附件名叫 chara；
V3 的附件名叫 ccv3。

酒馆读卡时优先读 ccv3，没有才读 chara。酒馆自己保存卡时两个都写。

容易踩的坑#

图片被压缩，卡就没了：QQ、微信、很多网盘和图床会「优化」图片，顺手把文字附件删掉。别人收到的只是一张普通头像，导入时报错或变成空卡。发卡时用「原图」或「文件」方式发，或者干脆发 JSON，见 pit-png-compress。
两份内容不一致：有些工具只改了 chara 没改 ccv3，酒馆读的是 ccv3，于是「怎么改了不生效」。用正规工具重新导出一次即可。
用看图软件编辑后保存：很多修图软件另存时会丢掉文字附件。要换头像，在酒馆里换。

想确认导出没丢东西#

卡片页「更多操作」里有 「往返校验」：把卡导出再读回来，逐个字段对比，见 app-export。

卡片前端是怎么工作的#

聊天里的状态栏、选项按钮、信息面板、彩色对白，统称「卡片前端」。它们不是 AI 画出来的，而是酒馆用正则把 AI 输出的文字「换装」成界面。

三步原理#

说明条目（世界书）告诉 AI：什么时候输出什么标签。比如「每次回复末尾，用 <options> 列出三个行动选项」；
显示正则把消息里的标签替换成一段界面代码。简单的直接是带样式的文字；复杂的是一个 HTML 代码块，由酒馆助手渲染成消息里的小网页；
清理正则把这些标签从发给 AI 的聊天记录里删掉。不删的话浪费 token，AI 还会越写越乱。

所以一个前端功能通常由「一条说明条目 + 一条显示正则 + 一条清理正则」组成。

两种渲染方式#

方式	是什么	需要什么
直接替换成 HTML	正则把标签换成带样式的文字，酒馆直接显示	只要允许这张卡的正则
HTML 代码块	正则换成一个包含完整网页的代码块，酒馆助手把它渲染成小窗口	还要装酒馆助手，并且开着「启用渲染器」

酒馆助手只渲染内容里含有 <html、<head> 或 <body 的代码块。代码块里没有这些标记，它就原样显示成代码。

几点常识#

只改颜色不需要 HTML：对白、动作、心理用不同颜色，正则直接套样式就行，见 regex-groups；
按钮通常是「填进输入框」：让玩家确认后再发，直接发送容易误触；
面板要有数据来源：MVU 变量（stat_data）、文字状态栏或酒馆变量，见 mvu-statusbar；
开局界面放在开场白里：开场白写一个占位标签，正则换成表单，玩家选完拼成第一句话；
预览 ≠ 酒馆：App 里的预览是模拟的，酒馆还会受显示设置、其他扩展、美化主题影响，一定要实测。

容易踩的坑#

什么都不显示：多半是没允许这张卡的正则或脚本，见 pit-allow-scripts；
显示成一堆代码：可能是代码块缺了 <body> 之类的标记，或者开了「在响应中显示标签」，见 pit-show-tags；
排版错乱、多出空行：酒馆会把消息当 Markdown 处理，HTML 里的缩进和空行会出问题，见 pit-markdown-html；
脚本报语法错误：代码里的 ' 这类写法被酒馆提前还原了，见 pit-code-entity；
旧消息里的界面不见了：酒馆助手有「渲染深度」，超过的楼层不渲染，这是正常的；
网络图片不显示：酒馆默认禁止外部媒体，见 pit-external-media。

开场白怎么写#

开场白是聊天的第一条消息。它的作用远不止「打个招呼」：AI 会照着开场白的文风、人称、篇幅往下写。开场白写成什么样，后面的聊天大概就是什么样。

四种常见形态#

场景切入：直接从一个画面开始，最常见。「雨下了三天，沈家铺子的门板只卸了一半……」
对话开头：角色先开口，一句话带出关系。「『新来的账房？』她没抬头，『先把去年的账对了。』」
信件 / 文档：日记、短信、委托书，用文本交代背景，适合悬疑和群像；
多选开局：列出几个身份或开局让玩家选，常配合开局表单界面。

写好开场白的要点#

从具体场景开始：时间、地点、正在发生什么，比一段背景介绍强；
给 {{user}} 留出行动空间：结尾停在一个需要玩家回应的点上，比如一个问题、一个选择、一个突发事件；
不要替 {{user}} 说话或做决定：「你点点头，决定留下」会让玩家出戏，AI 也会学着抢话；
篇幅就是示范：想要 AI 每次回三四百字，开场白就写三四百字；
人称要和你想要的一致：开场白用第二人称「你」，AI 后面多半也用「你」。

备选开场白#

一张卡可以有很多条开场白，玩家在聊天第一条消息上左右滑动切换。用途：

不同开局（初遇 / 重逢 / 敌对）；
不同路线、不同时间点；
MVU 卡可以给每条开场白配不同的初始变量，见 mvu-initvar。

容易踩的坑#

改了开场白，旧聊天不变：开场白只在新开聊天时用，见 pit-old-chat；
开场白里写设定说明：「（本卡设定：……）」这类话 AI 会以为是文风的一部分，说明请放创作者注释；
太长：开场白也算聊天记录，太长会一直占上下文；
重写开场白后界面没了：开局表单靠开场白里的占位标签，重写时别把它删掉。

MVU 变量系统

Mon, 26 Oct 2026 00:00:00 GMT

MVU 是什么#

MVU（MagVarUpdate）是运行在酒馆助手上的变量框架。有了它，角色卡能「记住」好感度、金钱、时间、位置、物品这些数值和状态，而不是全靠 AI 从聊天记录里猜。

没有变量会怎样#

AI 只能从聊天记录推断状态。聊久了，旧消息被挤出上下文，AI 就忘了「现在几点」「身上还有多少钱」，数值也会前后矛盾。

有了 MVU，状态被明确存起来，每轮都告诉 AI 当前是多少，AI 只需要说「变了多少」。

一轮是怎么跑的#

开局：MVU 读取初始变量，存进第一条消息，见 mvu-initvar；
发给 AI：常驻条目把当前变量和更新规则发给 AI，见 mvu-update-rules；
AI 回复：正文写完后，末尾输出一段更新命令，见 mvu-jsonpatch；
MVU 处理：读出命令，算出新变量，存到这一条消息上（存的位置叫 stat_data）；
显示：状态栏读变量，显示在消息里，见 mvu-statusbar。

变量是按楼层存的：每条 AI 消息都带着那一刻的变量。所以删掉、重新生成一条消息，变量会跟着回到上一楼的状态。

需要什么#

酒馆装了酒馆助手扩展；
卡里带着 MVU 脚本，并且导入时允许了脚本；
能访问 MVU 脚本所在的网络地址。

详细见 mvu-install。

两种写法#

zod 版（有变量结构校验）和经典版（没有校验），见 mvu-zod-vs-classic。

适合什么卡#

恋爱养成（好感度、关系阶段）；
经营、冒险（金钱、物品、属性）；
长篇剧情（时间、地点、章节、任务进度）。

只是聊天陪伴、没有数值玩法的卡，不需要 MVU，加了反而让 AI 每轮多写一段命令。

容易踩的坑#

变量太多：几十个变量，AI 每轮都要分析一遍，又慢又容易错，见 mvu-design；
状态栏一直「正在读取变量」：多半是脚本没启用或加载失败，见 mvu-errors；
改了初始变量旧聊天没变：初始变量只在开局读一次，见 pit-old-chat。

MVU 卡在酒馆里跑起来需要什么#

MVU 卡比普通卡多依赖几样东西。缺一样，变量就不动、状态栏就不出来。

1. 装酒馆助手#

酒馆顶部「扩展程序」→「安装扩展程序」，填入酒馆助手的仓库地址：

1
https://github.com/N0VI028/JS-Slash-Runner

装好后刷新页面，扩展面板里出现「酒馆助手」，确认它是开着的。

2. 导入卡时允许脚本和正则#

导入 MVU 卡后会弹两个窗口：

酒馆的「是否启用局部正则」：选是；
酒馆助手的「角色卡中包含酒馆助手可用的嵌入式脚本，是否现在就启用它们?」：选是。

点错了也能补救，见 pit-allow-scripts。

3. 网络能访问脚本地址#

MVU 本体和变量结构工具不在卡里，卡里只有一行「去这个地址加载」。地址一般在 jsdelivr 上，加载失败 MVU 就不工作，见 pit-cdn。

4. 开新聊天#

MVU 在聊天开始时读取初始变量。旧聊天、没有 MVU 时开的聊天，变量是空的。

检查是否跑起来了#

输入框上方出现「重新处理变量」等按钮：MVU 脚本已加载；
发一条消息，AI 回复末尾有更新命令，状态栏数值变了：整套都通了；
酒馆助手的「角色脚本库」里能看到 MVU 和变量结构脚本，且是启用状态。

容易踩的坑#

酒馆助手版本太旧：MVU 需要较新的酒馆助手，扩展面板里点更新；
用了手机上的精简版酒馆：有的第三方客户端不支持酒馆助手，MVU 卡无法使用；
脚本被关：酒馆助手设置里脚本总开关、角色脚本开关都要开着。

变量结构（zod Schema）#

zod 版 MVU 卡多一个「变量结构」脚本，规定每个变量是什么类型、取值范围、默认值。每次 AI 更新变量后，MVU 都按它校验，写错的会被修正或拦下。

长什么样#

1
const Schema = z.object({
2
  沈清: z.object({
3
    好感度: z.coerce.number().transform(v => _.clamp(v, 0, 100)).prefault(20),
4
    当前心情: z.string().prefault('戒备'),
5
  }).prefault({}),
6
  主角: z.object({
7
    金钱: z.coerce.number().prefault(0),
8
    背包: z.array(z.string()).prefault([]),
9
  }).prefault({}),
10
})

常用写法#

写法	作用
`z.object({...})`	一组变量
`z.coerce.number()`	数字；AI 写成 “12” 这样的文字也能转成数字
`z.string()`	文字
`z.boolean()`	真假
`z.array(...)`	列表
`z.enum(['上午','下午','夜晚'])`	只能是这几个值之一
`.transform(v => _.clamp(v, 0, 100))`	超出范围自动拉回 0～100
`.prefault(值)`	缺这个变量时用的默认值

只读变量#

以 _ 开头的变量约定为只读，更新规则会告诉 AI 不要改，比如 _最大体力。

容易踩的坑#

结构和初始变量对不上：初始变量里有、结构里没有的键，可能被丢掉；
用了 z.number() 不带 coerce：AI 偶尔写成字符串就校验失败；
范围太严：比如心情用 enum 只给三个值，AI 写了第四种就被拦下，变量不更新；
脚本没启用：变量结构脚本没开，校验和默认值都不生效，见 mvu-install。

初始变量 InitVar#

初始变量就是开局时变量的值。MVU 在聊天开始时读取它，存进第一条消息。

写在哪#

一条世界书条目，标题里带 [initvar]，内容用 YAML 写：

1
沈清:
2
  好感度: 20
3
  当前心情: 戒备
4
主角:
5
  金钱: 300
6
世界:
7
  时间: 第一天 上午

这条条目通常是禁用的：它只给 MVU 读，不需要发给 AI；
YAML 用空格缩进，同一层对齐，冒号后面有空格。

不同开场白，不同开局#

开场白里可以写一段 <initvar> 块，只写需要不同的部分，覆盖条目里的初始值：

1
<initvar>
2
世界:
3
  时间: 第三天 夜晚
4
沈清:
5
  好感度: 50
6
</initvar>

这样「初遇」和「重逢」两条开场白，就有各自的初始好感度。

zod 版和经典版的区别#

zod 版：只写纯值，缺的键由变量结构的默认值补上，见 mvu-schema；
经典版：可以写成 [值, "说明"] 的形式，说明会一起给 AI 看。

改了初始变量怎么生效#

新开聊天：自动用新的初始变量；
旧聊天：点输入框上方的「重新读取初始变量」按钮，或开新聊天，见 pit-old-chat。

容易踩的坑#

用了 Tab 缩进：YAML 不认 Tab，解析失败；
冒号是全角的：「好感度：20」解析不出来，要用半角冒号；
数字写成了文字：好感度: 二十 不是数字，后面的加减就会出错；
初始变量和变量结构对不上：zod 版会按结构校验，名字差一个字就会被丢掉或报错。

JSONPatch 与 _.set#

AI 每轮在回复末尾输出一段更新命令，告诉 MVU 哪些变量变了。现在推荐的写法是 JSONPatch。

完整的样子#

1
<UpdateVariable>
2
<Analysis>
3
- time passed: half a day
4
- 沈清.好感度: user helped with accounts, +3
5
</Analysis>
6
<JSONPatch>
7
[
8
  { "op": "delta", "path": "/沈清/好感度", "value": 3 },
9
  { "op": "replace", "path": "/世界/时间", "value": "第一天 下午" }
10
]
11
</JSONPatch>
12
</UpdateVariable>

<Analysis>：AI 先分析哪些变量该变，提高准确率；
<JSONPatch>：真正的命令，一个 JSON 数组。

操作#

op	作用	例子
replace	设成新值	时间改成「下午」
delta	数字加减，负数是减	金钱 -50
insert	加一个新键，或往列表里加一项	背包里加「钥匙」
remove	删掉一个键或列表里的一项	用掉了「钥匙」
move	把一个值挪到另一个路径	物品从背包移到仓库

path 怎么写#

以 / 开头，一级一级写变量名：/沈清/好感度；
列表用数字下标，从 0 开始：/主角/背包/0；
往列表末尾追加用 -：/主角/背包/-。

老写法 _.set#

1
_.set('沈清.好感度', 20, 23);//帮忙对账

意思是「从 20 改成 23」。还能用，但容易写错，新卡建议用 JSONPatch。注意结尾的分号不能少。

容易踩的坑#

JSON 格式错：少逗号、多逗号、用了中文引号，整段命令都会失败；
path 和变量名不一致：多一个字、少一个字都找不到；
delta 用在文字上：只有数字能加减；
每轮都输出所有变量：没变的不要写，规则里要强调「只写有变化的」；
命令留在历史里：旧楼层的命令要用正则从发给 AI 的历史里删掉，否则又长又干扰，见 mvu-regex。

更新规则 [mvu_update]#

更新规则告诉 AI 每个变量什么时候变、变多少。它是一条常驻的世界书条目，标题常带 [mvu_update]。规则写得越具体，AI 改得越稳。

一个好规则的样子#

1
变量更新规则:
2
  沈清.好感度:
3
    范围: 0~100
4
    含义: 0~30 戒备，31~60 熟悉，61~85 信任，86 以上 依赖
5
    增加: 被认真倾听、帮她解决铺子的麻烦 +1~3
6
    减少: 被敷衍、被冒犯、提起她父亲 -2~5
7
    check: 只看本轮发生的事，单轮变化不超过 5
8
  世界.时间:
9
    格式: 第N天 上午/下午/夜晚
10
    check: 按剧情推进，睡觉后进入下一天

每个变量写清这几件事#

项目	为什么
范围	防止越界
含义	让 AI 知道数值对应的状态，演得出差别
增加 / 减少的条件	什么事件会改变它
幅度	防止一轮涨爆
格式	文字类变量要写清格式，不然每次写法都不一样

配套的几条条目#

变量列表：常驻，每轮把当前变量值发给 AI；
输出格式：常驻，规定 AI 用 JSONPatch 输出，见 mvu-jsonpatch；
剧情推进：按变量解锁内容，见 mvu-plot。

这几条最好放在 @D 浅深度，或者顺序设大，保证不被预算挤掉。

容易踩的坑#

只写「根据剧情变化」：AI 不知道该变多少，要么不变，要么乱变；
增加条件太宽：「互动时 +1」等于每轮都加；
规则被预算挤掉：常驻条目也可能被挤掉，变量就不更新了，见 worldbook-budget；
规则和状态栏用的名字不同：规则里叫「好感」，状态栏读「好感度」，永远显示初始值。

全自动#

先设计变量表，再依次写变量结构、初始变量、更新规则、状态栏，全部直接写进卡，中间不停。适合想快速出一个能玩的版本。

半自动#

变量表、规则、状态栏写完后先停下给你确认：在清单里点开看、可以改，满意再采用，见 app-drafts。变量结构和初始变量直接由变量表生成，不再问模型。适合变量多、想每步把关。

容易踩的坑#

改了变量名，规则没跟着改：改名后跑一次检查；
按表重新生成会覆盖手改的部件：先确认再生成；
模拟通过 ≠ 酒馆能跑：酒馆里还要看脚本和网络，见 mvu-install。

状态栏与 #

状态栏是显示在 AI 回复末尾、展示当前变量的小面板。

怎么出来的#

每条 AI 回复末尾都有一个占位 <StatusPlaceHolderImpl/>（MVU 会自动补上）；
「状态栏」正则把占位替换成一段 HTML 代码块（仅影响显示）；
酒馆助手把代码块渲染成一个小网页；
小网页里的脚本等 MVU 准备好后，读取这一楼的变量，填进界面。

所以状态栏刚出来时会先显示「正在读取变量……」，一两秒后变成真实数值。

两种状态栏#

类型	原理	优点	需要
网页状态栏	代码块 + 脚本读变量	好看、能做进度条和标签页	酒馆助手
文字状态栏	正则直接用宏显示变量	简单、不依赖脚本渲染	只要正则

文字状态栏里用 {{get_message_variable::stat_data.沈清.好感度}} 这样的宏读值。

开场白也要有占位#

开场白（第 0 楼）末尾也要写 <StatusPlaceHolderImpl/>，否则第一屏没有状态栏。

容易踩的坑#

一直显示「正在读取变量」：MVU 没加载起来。检查酒馆助手和脚本是否启用、网络能否访问脚本地址，见 mvu-errors；
显示一堆代码：酒馆助手没装或「启用渲染器」没开；
状态栏脚本报语法错误：酒馆会把代码里的 ' 这类写法提前还原，破坏代码，见 pit-code-entity；
旧楼层的状态栏消失了：酒馆助手的「渲染深度」限制了只渲染最近几楼，这是为了性能，正常现象；
数值一直是初始值：状态栏读的路径和变量名对不上，或 AI 没有输出更新命令。

MVU 的五条正则#

MVU 卡通常带这几条正则，分工明确：

正则	作用	选项
状态栏	把消息末尾的占位换成状态栏界面	仅影响显示
隐藏占位	发给 AI 时去掉占位	仅影响后端提示词
隐藏更新命令	发给 AI 时去掉历史里的更新命令	仅影响后端提示词
折叠更新（生成中）	显示时把正在输出的命令折起来	仅影响显示
折叠更新（已完成）	显示时把命令折成可展开的小块	仅影响显示

为什么要隐藏旧命令#

每条 AI 回复末尾都有一段更新命令，聊几十轮就是几十段。全发给 AI：

浪费大量 token；
AI 会模仿旧命令，把过时的值抄回来。

有的卡会把历史里的更新命令全部删掉（也有卡用最大深度只处理最近几楼）。当前变量已经由变量列表条目每轮发给 AI，不需要靠历史。

为什么要折叠#

更新命令是给程序看的，玩家看到一大段 JSON 很出戏。折叠后玩家想看可以点开。

容易踩的坑#

状态栏正则两个选项都没勾：占位被永久替换成 HTML，见 pit-regex-scope；
隐藏命令的正则勾了「仅影响显示」：命令只是看不见，照样全部发给 AI；
局部正则没被允许：状态栏不出来、命令全露在外面，见 pit-allow-scripts；
正则标签名改了：输出格式里的标签和正则里的标签必须一致。

[mvu_plot]：剧情推进条目#

标题带 [mvu_plot] 的条目放「根据变量推进剧情」的内容。变量只是数字，剧情推进条目让数字真正改变故事。

能做什么#

阶段解锁：好感度到 60，沈清开始讲家里的事；
事件触发：金钱低于 0，债主上门；
结局分支：信任和好感都高，进入好结局路线。

两种写法#

写给 AI 自己判断#

不需要额外扩展，直接写清条件，让 AI 看着当前变量决定：

1
剧情推进:
2
  - 当 沈清.好感度 >= 60 且尚未发生时，安排她主动提起父亲的死
3
  - 当 主角.金钱 < 0 时，下一个场景债主上门

简单可靠，但 AI 偶尔会忘记或提前触发。

用 EJS 按条件输出#

装了提示词模板扩展后，可以用 EJS 让不满足条件的内容根本不发出去，见 ejs：

1
<% if (getvar('stat_data.沈清.好感度') >= 60) { %>
2
沈清已经信任{{user}}，会在深夜主动说起父亲的事。
3
<% } %>

更精准、更省 token，但玩家必须装扩展。

容易踩的坑#

条件一直满足，事件反复发生：要写「尚未发生时」，或者加一个真假变量记录「已发生」；
EJS 卡没说明要装扩展：玩家没装就会看到 AI 收到一堆 <% 代码；
只靠时间推进：想要「第几轮后才出现」，世界书的「延迟」更简单，见 worldbook-timed。

变量怎么设计#

变量设计好了，后面的规则、状态栏都顺；设计乱了，AI 改错、状态栏对不上、检查报一堆错。动手前花几分钟想清楚。

先问：这个数值会推动玩法吗#

只做会影响剧情或玩法的变量：

好感度到 60 解锁新剧情：要做；
金钱不够买不了东西：要做；
「今天穿什么衣服」只是描写：一般不用做，让 AI 自由发挥。

一张卡 5～15 个变量比较合适。超过 20 个，AI 每轮分析都很吃力。

按对象分组#

1
沈清:
2
  好感度: 20
3
  信任: 10
4
  当前心情: 戒备
5
主角:
6
  金钱: 300
7
  体力: 100
8
世界:
9
  日期: 民国二十三年 三月初一
10
  时间: 上午
11
  地点: 沈家铺子

第一层是「谁」或「什么」：角色名、主角、世界；
第二层是具体的值；
层级别超过三层。

命名#

用中文、用聊天里会说的词：「好感度」比「affection_lv」更容易让 AI 写对；
一个名字一个意思：别同时有「好感」和「好感度」；
以 _ 开头表示只读：比如 _最大体力，规则会告诉 AI 不要改。

类型怎么选#

类型	适合	注意
数字	好感度、金钱、体力	写清范围，比如 0～100
文字	心情、地点、时间	写清可选值或格式，比如「上午 / 下午 / 夜晚」
真假	是否已结识、任务是否完成	写清什么时候变
列表	背包物品、已知线索	写清怎么加、怎么删

容易踩的坑#

数值没有含义：好感度 47 和 52 有什么区别？在规则里写清楚每个区间代表什么，见 mvu-update-rules；
涨得太快：没写增减幅度，AI 一轮给 +20，几轮就满了；
改名字没改全：初始变量、规则、状态栏三处都要改；
把剧情写成变量：「剧情摘要」这种大段文字放变量里，每轮都改，又贵又乱。

MVU 常见报错与排查#

MVU 卡出问题，按「从外到内」查：先看框架有没有跑起来，再看 AI 有没有输出命令，最后看命令对不对。

状态栏一直「正在读取变量……」#

MVU 本体没加载起来。依次检查：

酒馆助手装了吗？开着吗？
导入时脚本允许了吗？去酒馆助手「脚本库 → 角色脚本」看 MVU 脚本是否开着；
网络能访问 MVU 的脚本地址吗？见 pit-cdn；
是不是旧版 App 导出的？0.4.1 修过一个会导致这个现象的问题，重新导出试试，见 pit-code-entity。

变量不更新#

现象	原因	办法
回复末尾没有更新命令	输出格式条目没发出去	确认它常驻、没被预算挤掉
改了又被改回去	变量结构的范围或类型拦下了	放宽结构，或在规则里写清范围
只有部分变量更新	规则太笼统	写具体的触发条件

初始变量不对#

解析失败：YAML 用了 Tab、全角冒号、缩进不齐；
旧聊天：初始变量只在开局读一次，点「重新读取初始变量」或开新聊天；
开场白里的 <initvar> 写错：它会覆盖条目里的值。

输入框上方的按钮#

按钮	用途
重新处理变量	重新读最新一条回复的命令
重新读取初始变量	按当前初始变量重置
重试额外模型解析	用额外模型解析时重来一次

容易踩的坑#

只在 App 里模拟通过：模拟不经过酒馆的网络和设置，一定要在酒馆实测；
删消息后变量回退：变量存在每一楼上，删掉最新一楼就回到上一楼的值，正常现象；
一次改太多：出问题时一次只改一处，改完开新聊天试。

MVU：zod 版和经典版有什么区别#

	zod 版	经典版
写法	多一个「变量结构」脚本：`const Schema = z.object({...})`	只有初始值和规则
校验	每次更新后按 Schema 校验，类型不对会被拦下	不校验，写错了就错着
数值钳制	Schema 里可写范围（如好感度 0~100），超出自动修正	只能靠规则里叮嘱模型
缺省值	初始值缺的键由 Schema 默认值补	全靠初始值写全
兼容性	需要较新的 MVU 与酒馆助手	老版本也能用
适合谁	新卡、变量多、在意稳定	改老卡、变量很少

两种都要求模型用 mvu-jsonpatch 输出更新。

怎么判断一张卡是哪种#

酒馆助手的角色脚本里有「变量结构」脚本、内容有 registerMvuSchema：zod 版；
初始变量里的值写成 [值, "说明"]：多半是经典版。

容易踩的坑#

把经典版的初始变量直接搬进 zod 版：[值, "说明"] 会被当成列表，类型对不上；
zod 版结构太严：AI 写了范围外的文字值，整条更新被拦下，看起来像「变量不更新」；
以为 zod 版不需要规则：结构只管校验，什么时候改、改多少还是要靠更新规则，见 mvu-update-rules。

避坑清单

Mon, 26 Oct 2026 00:00:00 GMT

发卡前自查清单#

卡做完了，发出去之前在酒馆里走一遍这个清单。大部分「别人用不了」的问题都能提前发现。

导入#

用一个干净的酒馆（或者先删掉旧版本）导入导出的文件，模拟玩家第一次拿到卡；
弹出「导入世界书」：选是，见 pit-embedded-book；
弹出「启用局部正则」「启用嵌入式脚本」：选是，见 pit-allow-scripts。

开局#

开新聊天，不要用旧聊天测，见 pit-old-chat；
开场白显示正常，没有露出代码或标签；
有状态栏的卡：状态栏出来了，数值是初始值；
每条备选开场白都切过去看一眼。

聊三到五轮#

AI 的回复风格对不对，有没有串成第一人称、替玩家说话；
世界书该触发的触发了：点 AI 回复上的「提示词」按钮看实际发了什么；
变量有没有更新，状态栏数值有没有变；
选项、面板等界面能点、能用。

换个环境#

换个预设：用一个流行的预设再聊几轮，见 preset-vs-card；
换手机看：界面在窄屏上排版正常；
关掉代理或换网络：用了外部脚本的卡，看能不能加载，见 pit-cdn。

发出去#

发文件，不要当图片发，见 pit-png-compress；
在简介或创作者注释里写清：需要什么扩展、推荐什么预设、导入时弹窗要选是。

容易踩的坑#

只在自己的酒馆测：自己的酒馆早就允许过脚本、装好了扩展，问题全被掩盖；
只测开场白：很多问题在第二、三轮才出现，比如变量不更新、正则吃掉内容；
改完没重新导出：在酒馆里改的东西不会回到 App 里，反之亦然。

卡里的系统提示没生效#

现象：卡里写了系统提示（主要提示词）或历史后置指令，但点「提示词」按钮一看，发出去的还是预设里的内容。

为什么#

卡里的系统提示是用来替换预设里「主要提示词」的。替换要同时满足这几个条件，缺一个就不替换：

条件	在哪看
用户设置开着「角色卡提示词优先」	用户设置 → 角色处理（默认开）
预设的主要提示词没有勾「禁止覆盖」	预设的提示词列表，编辑主要提示词
预设的主要提示词是开着的	预设的提示词列表，开关状态

历史后置指令同理：对应「首选角色卡指令」设置，以及预设里的历史后置指令块。

很多流行预设为了保证自己的效果，会关掉主要提示词或勾上禁止覆盖，这时卡的系统提示就白写了。

怎么办#

玩家：在预设里取消「禁止覆盖」，或换一个不禁止的预设。

写卡时：

关键规则别只放系统提示里：放进世界书常驻条目更稳，只要世界书块开着就能发出去，见 preset-vs-card；
系统提示里用 {{original}} 保留预设原来的内容，只在前后补充自己的，见 card-system-prompt；
系统提示只写「锦上添花」的东西，丢了也不影响基本能玩。

怎么确认#

点 AI 回复上的「提示词」按钮，找最前面的系统消息，看是卡里的内容还是预设的。

容易踩的坑#

在自己的预设下测试一切正常：你的预设没禁止覆盖，玩家的可能禁止了；
系统提示和预设打架：替换成功时，预设原来的主要提示词就没了，可能丢掉预设作者的关键设定；
以为系统提示比世界书更「权威」：模型并不会因为它叫系统提示就更听话，位置和写法更重要。

正则和脚本没被允许#

现象：状态栏不出来、标签和更新命令全露在外面、美化不生效、输入框上方没有 MVU 的按钮。

为什么#

卡里自带的正则和脚本有安全风险，酒馆和酒馆助手默认不会自动运行，导入时会弹窗问：

弹窗	管什么
酒馆：是否启用这张卡的局部正则	卡里的正则
酒馆助手：「是否现在就启用它们?」	卡里的脚本（MVU、按钮等）

点了「否」就不生效。正则的弹窗每个角色只问一次，群聊里不弹。

怎么补救#

正则：

扩展程序 → 正则 → 「局部正则」那一栏，打开「允许使用局部正则」开关；
确认列表里的每条正则没有被单独禁用。

脚本：

酒馆助手 → 脚本库 → 角色脚本，打开开关；
同时确认酒馆助手本身、脚本库总开关是开着的。

改完后刷新页面或重新进入聊天。

写卡时怎么避免#

简介里写清：「导入时两个弹窗都选『是』」；
开场白里的状态栏如果没出来，玩家立刻能看出问题，可以在开场白里加一句提示：「如果看到一堆代码，请检查是否允许了正则和脚本」。

容易踩的坑#

只允许了正则，没允许脚本（或反过来）：网页状态栏需要两者都开；
以为一次允许、所有卡都允许：每张卡单独允许；
预设正则改完不生效：预设正则要重新加载聊天才生效；
群聊：局部正则在群聊里的表现和单聊不同，群聊卡要单独测。

外部脚本加载失败#

现象：MVU 卡状态栏一直「正在读取变量……」，输入框上方没有 MVU 的按钮；有的界面一片空白。同一张卡，有人能用、有人不能用。

为什么#

有些代码不在卡里，而是卡里写了一个网络地址，用的时候临时下载：

MVU 本体、变量结构工具：从 jsdelivr 这类公共加速地址加载；
一些界面引用了外部的样式库、字体、脚本。

如果玩家的网络访问不了这个地址（网络限制、地址被墙、服务临时故障），代码就没下载下来，功能直接失效，而且通常不会有明显的报错提示。

怎么判断#

同一张卡换个网络（开或关代理、换手机流量）就好了：基本就是网络问题；
电脑上用浏览器开发者工具看网络请求，有红色的失败请求。

玩家能做什么#

换网络或使用代理后，刷新酒馆页面；
在酒馆助手里把 MVU 脚本的地址换成能访问的镜像（按卡作者的说明操作）。

写卡时怎么避免#

能不用外部资源就不用：界面的样式、脚本尽量直接写进卡里；
必须用的（如 MVU）：在简介里写清楚依赖网络，并提供备用地址；

容易踩的坑#

在自己的网络测试没问题：你有代理，玩家不一定有；
外部地址失效：引用的项目改了文件路径或停止维护，卡就突然坏了；
引用了来路不明的脚本：外部脚本可以读你的聊天、改你的设置，只用可信来源。

界面代码在酒馆里报错，预览却正常#

现象：状态栏、面板在 App 里预览一切正常，导入酒馆后却卡在「正在读取变量……」，或者一片空白；打开浏览器控制台能看到脚本语法错误。

为什么#

酒馆助手渲染的界面，代码是放在消息的代码块里的。酒馆在把消息转成网页时，会把代码块里的 HTML 转义写法提前还原一层：

代码里写的	被还原成
`'`	`'`
`"`	`"`
`<` / `>`	`<` / `>`
`&`	`&`

如果代码里本来就有这些写法（比如一个 JS 字符串 '''），还原后变成 '''，整段脚本语法错误，什么都不执行。

常见来源：转义函数、拼 HTML 的代码里经常需要写 <、'。

怎么办#

这是 App 0.4.1 修复的问题：导出时自动给代码多加一层转义，酒馆还原一层后正好是原样。用旧版导出的卡，用新版重新导出一次；
手写代码时，想在 JS 里表示这些实体，改用字符拼接或 JS 转义，比如 '&' + '#39;'，或者 '\x26#39;'；
自己手动多写一层：想要最终得到 '，就写 &#39;。

怎么确认是这个问题#

在酒馆里打开浏览器开发者工具，控制台有 SyntaxError；
用新版 App 重新导出、在酒馆里重新导入后问题消失，基本就是它。

容易踩的坑#

App 预览正常就以为没问题：App 的预览不经过酒馆的 Markdown 处理，一定要在酒馆里实测；
在酒馆里手改了代码再导出：手改时如果又写了实体，问题会回来；
只发生在代码块里：同样的写法放在普通 HTML 里不出错，所以很难想到是这个原因。

正则替换后美元符号和内容不见了#

现象：正则替换后，「$100」变成了空白或奇怪的数字；状态栏里的价格消失；界面代码里有一段莫名其妙变成了整段消息原文。

为什么#

在正则的「替换为」里，$ 加数字表示捕获组：$1 是第一个括号里的内容，见 regex-groups。酒馆会把替换内容里所有 $数字 和 $<名字> 都当成捕获组处理：

$100 被当成第 100 个捕获组，不存在，变成空；
编号超过实际组数时，结果不可预料：可能是空，也可能插进一个位置数字，甚至插进整段原文；
和一般编程语言不同，$$ 不会变成一个 $。

最容易中招的地方#

价格、货币：「售价 $5」；
界面代码写在替换内容里，代码中正好有 '$1' 这样的字符串，比如 JS 的字符串替换 s.replace(/(a)/, '$1')；
从别处复制来的模板里有 $ 开头的变量名，后面紧跟数字。

${...}、$(...) 这类写法不受影响，因为 $ 后面不是数字。

怎么办#

显示用的文字：把 $ 写成 $，网页显示出来就是 $；
或者换成全角 ＄ 或「美元」；
代码里：避免 $ 紧跟数字，比如 JS 字符串替换改用函数写法 s.replace(/(a)/, (m, a) => a)；
价格放进变量或捕获组里，而不是直接写在替换内容中。

容易踩的坑#

只在正则的替换内容里发生：同样的文字写在开场白、世界书里没问题，所以很难察觉；
测试时没测到：替换后内容「少了一点」很容易看漏，用正则编辑器的「测试模式」逐字核对；
查找里的 $：在查找规则里 $ 表示「结尾」，要匹配美元符号本身得写 \$。

卡里的世界书没生效#

现象：导入卡后，设定好像都没起作用；打开世界书面板，找不到这张卡的世界书，或者角色没有绑定世界书。

为什么#

卡里自带的世界书，导入时酒馆会弹窗问要不要导入。点了「否」或者直接关掉，世界书就没有导入。而且这个弹窗每张卡只问一次，之后不会再问。

另外：

在角色列表里批量导入时，可能没注意到弹窗；
用户设置里关掉了导入世界书的提示，也不会弹。

怎么补救#

打开这个角色 → 角色面板上的「…」更多菜单 → 「导入角色卡的世界书」。导入后，酒馆会生成一本同名世界书，并绑成这个角色的主要世界书。

导入后检查：

世界书面板里能找到这本书；
角色面板的地球图标亮着，点开能看到绑定的是这本。

写卡时怎么避免#

在创作者注释和简介里写：「导入时请在弹窗里选『是』导入世界书」；
关键的说明（比如变量规则）放在世界书里，世界书没导入时开场就会露馅，玩家能及时发现；
不要把同一本书再单独发一份让玩家手动绑定，容易绑重复。

更新卡时#

玩家导入新版卡时，如果已经有同名世界书，酒馆会提示将覆盖同名世界书，选是就用新版替换旧版。所以：

新版卡的世界书名字保持不变，玩家更新才顺利；
提醒玩家：自己在旧世界书里改过的内容，覆盖后会丢失，要先备份。

容易踩的坑#

在酒馆里改了世界书，以为卡里也改了：导入后的世界书是独立文件，和卡里那份没关系，要重新导出卡；
新版改了世界书名字：旧书不会被覆盖，玩家手里同时有两本，角色绑的可能还是旧的；
聊天里没生效但书已导入：检查预设的提示词列表里世界书块是否开着，见 preset-order。

消息里的外部图片、字体不显示#

现象：开场白或美化里引用的网络图片显示不出来，或者顶部提示「外部媒体被禁用」；用网络字体、背景图的样式没生效。

为什么#

酒馆的用户设置里有「禁止外部媒体」，默认开着。开着时：

消息里引用网络地址的图片、音频、视频被拦截；
样式里带网络地址的部分（比如 url(https://...) 的背景图、字体）被去掉。

这是为了防止卡片借图片偷偷访问外部网站（比如记录你的 IP）。

玩家怎么放行#

只放行这张卡：打开角色编辑面板，「角色描述」标题旁边有个链接图标，点它可以允许或禁止这个角色使用外部媒体；
全部放行：用户设置里关掉「禁止外部媒体」（不太推荐）。

写卡时怎么避免#

图片尽量少用：必须用的，在简介里提醒玩家点那个链接图标放行；
颜色、边框、渐变用纯样式写：不依赖任何外部文件；
字体用系统自带的：外部字体加载不了时，要有备选字体；
酒馆助手渲染的小网页：它的规则和普通消息不同，也可能受网络影响，见 pit-cdn；以玩家实测为准。

容易踩的坑#

你自己早就放行了：在自己的酒馆里看一切正常，玩家那边全是空白；
图床失效：免费图床的图片过段时间就没了，卡就「破相」了；
图片太大：几 MB 的背景图在手机上加载很慢，每条消息都加载一次更慢；
把图片转成超长的 base64 写进卡：能绕开拦截，但卡会变得非常大，每次显示都拖慢酒馆，慎用。

消息里的 HTML 排版乱了#

现象：开场白或正则里写的 HTML 排版全乱：多出空白、一半变成代码框、文字变成斜体、点击按钮没反应、样式不生效。

为什么#

消息显示前，酒馆会先把文字当 Markdown 处理，再做安全过滤。直接写在消息里的 HTML 会被这两步改动：

写法	结果
HTML 中间有空行	被拆成几段，结构断开
行首缩进 4 个空格	变成代码框
文字里有 `*`、`_`	可能变成斜体、粗体
`<script>`	被删掉
`onclick` 这类事件属性	被删掉
`<style>` 里的规则	被限制在消息范围内，`body` 这类选择器不按预期生效
外部图片、字体	默认被拦截，见 pit-external-media

另外酒馆默认开着「自动修复 Markdown」，可能给没配对的星号补上配对。

怎么办#

简单的装饰（颜色、边框、折叠块）：

HTML 写成紧凑的一段，中间不留空行；
不要用缩进；
只用内联 style="..."，不要依赖脚本。

需要交互的界面（按钮、标签页、读变量）：

放进代码块，代码里要有 <html>、<head> 或 <body>，由酒馆助手渲染成独立的小网页；
在小网页里脚本、样式都能正常工作，不受上面的规则影响；
但代码块有自己的坑，见 pit-code-entity。

容易踩的坑#

App 预览正常、酒馆里乱了：预览不经过酒馆的 Markdown 处理，一定要在酒馆里实测；
AI 输出的 HTML 也一样：让 AI 直接输出 HTML，很容易因为空行、缩进而乱掉，宁可让 AI 输出标签，再用正则换成 HTML；
「在响应中显示标签」开着：所有 HTML 都会显示成代码文字，见 pit-show-tags。

改了卡，旧聊天里没变化#

现象：改了开场白、初始变量、状态栏，导入酒馆后，在原来的聊天里还是旧的样子。

为什么#

聊天开始时，有些内容会复制一份存进聊天记录，之后和卡就没关系了；有些内容则是每次发送时现读卡里的。

内容	旧聊天里会不会变
角色描述、性格、情景、示例对话	会，每次发送都现读
系统提示、历史后置指令	会
开场白	不会，开局时已经存成第一条消息
初始变量	不会，开局时已经读进第一条消息
世界书	看你改的是哪份，见下文
正则、脚本	重新导入并刷新后会
已经存在的消息、变量	不会，按当时的样子存着

世界书改了没生效#

导入后的世界书是独立文件。重新导入卡时，如果世界书没有跟着更新，用角色面板「…」→「导入角色卡的世界书」再导入一次，会覆盖同名的旧书。

更新卡的正确做法#

在酒馆里选中旧角色，用角色面板「…」里的「替换 / 更新」导入新文件，保留聊天记录；
或者删掉旧角色和旧世界书，重新导入；
开新聊天测试。

旧聊天还想继续玩#

初始变量：点输入框上方的「重新读取初始变量」，见 mvu-initvar。注意这会按新的初始值重置；
开场白：手动编辑第一条消息，或者干脆开新聊天；
改了变量名：旧消息上存的还是旧名字，状态栏可能读不到，最好开新聊天。

容易踩的坑#

在旧聊天里测新版：看到的是新旧混合的效果，结论不可信；
直接再导入一次同一张卡：可能多出一个同名角色，你在旧的那个里测，当然没变化；
玩家反馈「更新没用」：在更新说明里提醒玩家开新聊天。

卡发出去变成了普通图片#

现象：你发出去的卡，别人导入时报错，或者导入后只有一张图、什么设定都没有。

为什么#

角色卡的所有内容（描述、开场白、世界书、正则、脚本）都藏在 PNG 图片的附加数据里，图片本身只是封面。

很多软件发送、保存图片时会压缩或转格式，附加数据就被扔掉了：

聊天软件当「图片」发送（不勾原图）；
部分图床、社交平台上传后重新压缩；
用修图软件打开再保存，或者截图；
有的相册「优化存储」会转成 JPG、HEIC 等格式。

怎么办#

当「文件」发送：聊天软件里选「文件」而不是「图片」；
打包成压缩包再发；
同时附一份 JSON：JSON 格式的卡只有数据没有图，不会被压缩；
发到网盘、论坛附件，而不是图片区。

怎么判断文件是否完好#

文件大小：带世界书的卡通常比同尺寸的普通图片大；
最直接：自己用酒馆导入一次收到的文件。

容易踩的坑#

改封面时用了别的软件：先在别的软件里改好图，再在 App 或酒馆里换封面，而不是直接改导出后的卡；
从网上「另存为」下载的卡：网站可能给的是压缩后的预览图，要找原文件下载按钮；
以为 JPG 也能当卡：角色卡只能是 PNG 或 JSON。

标签或代码原样露在消息里#

现象：消息里出现 <options>...</options>、<UpdateVariable> 这类标签原文，或者整段 HTML、代码以文字形式显示，而不是变成界面。

先看是哪一种#

表现	最可能的原因
所有卡、所有美化都变成代码文字	「在响应中显示标签」开着
只有这张卡的标签露出来	局部正则没被允许
大部分时候正常，偶尔露出来	AI 这次把标签写错了
生成过程中露出来，生成完就好	流式输出时标签还没闭合，正常现象
显示一整块代码框	酒馆助手没装或「启用渲染器」没开

「在响应中显示标签」#

用户设置里的这个选项（默认关）打开后，酒馆会把消息里的所有尖括号都当文字显示。正则生成的 HTML 也一起变成了代码文字。玩家关掉它就好。

局部正则没被允许#

见 pit-allow-scripts。

AI 写错了标签#

正则只认它规定的写法，AI 稍微写偏一点就匹配不到：

大小写不同：<Options> 和 <options>；
用了全角尖括号：＜options＞；
漏了结束标签，或者结束标签写错；
标签里多了空格、属性。

办法：

世界书里的格式要求写清楚，给一个完整示例；
正则查找时加 i 标志忽略大小写，见 regex-flags；
做一条兜底正则，把没闭合的标签也隐藏掉。

容易踩的坑#

只看了一两轮：AI 写错标签是偶发的，多聊几轮才会遇到；
在格式要求里用了 <user> 当标签名：会被替换成玩家名字，见 pit-macro-escape；
温度太高：格式更容易乱，见 preset-params。

世界书条目触发了却没发出去#

现象：条目明明是常驻的，或者关键词明明出现了，可「提示词」里就是找不到它；有时生效，有时不生效。

为什么#

世界书有预算，默认最多占上下文的 25%。这一轮触发的条目按「顺序」从大到小排队进预算，满了之后的全部丢掉，见 worldbook-budget。

很多人以为常驻条目一定会发，其实常驻也要排队。下面几种情况最容易超预算：

预设里的上下文长度设得小（比如 8k），25% 只有 2000 token 左右；
世界书条目多、每条都很长；
递归开着，一个条目带出一串，见 worldbook-recursion；
玩家同时开着全局世界书，和卡的世界书共用预算。

怎么确认#

点 AI 回复上的「提示词」按钮，看这条是不是真的发了；
世界书设置里打开「溢出警报」，超预算时会提示。

怎么办#

最关键的条目勾「无视回复限额」：比如 MVU 的变量列表、更新规则、输出格式，少了它们卡就不能玩；
重要条目顺序设大：先进预算；
精简内容：删重复、删废话，长条目拆成按关键词触发的短条目；
大段设定别常驻：常驻的只放每轮都必须知道的。

写卡时怎么避免#

按「玩家的上下文只有 16k」来估算：世界书常驻部分控制在 2000～3000 token 以内，比较安全。在简介里写明推荐的上下文长度。

容易踩的坑#

在自己的大上下文环境测试没问题：玩家的上下文更小，就出事了；
「无视回复限额」勾太多：等于没有预算，可能把聊天记录挤得太少；
以为顺序小的先进：是顺序数字大的先进预算，见 worldbook-order。

关键词条目总是触发或从不触发#

现象 A：一个按关键词触发的条目，几乎每轮都在。

现象 B：一个条目，聊天里明明提到了，就是不触发。

总是触发的原因#

原因	说明
用了角色名、玩家名当关键词	酒馆扫描时会把说话人的名字一起扫（「包括名称」默认开），每条消息都带名字
关键词太短太泛	单个汉字、「他」「门」「刀」这种词处处都有
关键词出现在开场白或 AI 的口头禅里	AI 自己每轮都说，自己触发自己
递归	别的条目内容里提到了它，见 worldbook-recursion

从不触发的原因#

原因	说明
玩家用的词和关键词不一样	只写了全名「沈清」，玩家说「清儿」「沈小姐」
英文名被「匹配整个单词」拦住	关键词 `Tom` 匹配不到 `Tommy`，新装酒馆默认开着这个选项
关键词之间用了全角逗号	「沈清，清儿」被当成一个关键词
扫描深度太小	提到的那句已经不在扫描范围里，见 worldbook-scan-depth
条目被禁用，或世界书没导入	见 pit-embedded-book
次要关键词逻辑设错	比如「与所有」要求次要关键词全都出现

怎么办#

角色本人的设定直接写进角色描述，或者做成常驻，不要用名字触发；
关键词写多个别称，用半角逗号分隔；
避免单字关键词，至少两个字；
测试时点「提示词」按钮看触发了哪些条目。

容易踩的坑#

中文不受「匹配整个单词」影响：不用担心中文关键词被它拦住；
大小写：默认不区分，英文名一般不用担心；
正则关键词：写成 /.../ 后完全按正则匹配，写错了不会报错，只是不触发。

预设配置

Mon, 26 Oct 2026 00:00:00 GMT

什么写进卡，什么留给预设#

写卡时常纠结：文风要求、输出格式该写在卡里，还是让玩家的预设来管？原则是：和这张卡有关的写进卡，通用的留给预设。

分工表#

内容	放哪	原因
人设、世界观、配角、地点	卡（描述 + 世界书）	只属于这张卡
开场白、示例对话	卡	只属于这张卡
变量规则、状态栏输出格式	卡（世界书常驻或 @D 条目）	卡的功能靠它，不能指望玩家预设
选项、面板等界面标签的输出要求	卡（世界书）	同上
这张卡特有的文风（古风、公文体、日记体）	卡	是卡的特色
通用文风（少用比喻、不要总结）	预设	每张卡都适用
破限	预设	和模型有关，不和卡有关
回复长度、人称	预设为主，卡里可以建议	玩家各有偏好
思维链格式	预设	和模型有关

为什么卡的关键规则要写进世界书#

玩家用的预设千差万别。卡里的系统提示可能被预设禁止覆盖，见 card-system-prompt。而世界书条目只要世界书块没被关，都会发出去，最稳。

所以常见做法是把 MVU 规则、界面说明都放在世界书条目里，而不是系统提示里。

和预设兼容的写法#

不要在卡里写破限：和玩家的预设叠加，容易起反作用；
不要规定太多通用格式：「每次回复 800 字」这类要求和预设冲突时，AI 会摇摆；
把必需的东西说清楚：「本卡需要 AI 在回复末尾输出 <options>」，这类要求写在世界书里，不依赖预设；
在创作者注释里写推荐预设：见 card-creator-notes。

容易踩的坑#

只在自己的预设下测试：换个流行预设试试，卡的功能是否还正常；
预设自带的正则和卡的正则冲突：比如都在处理同一个标签，见 regex-cheatsheet；
以为卡的系统提示一定生效：见 pit-char-prompt。

对话补全预设#

用 OpenAI、Claude、Gemini、DeepSeek 这类接口聊天时，用的是「对话补全」模式。这时预设决定了：

发给模型的提示词由哪些块组成、按什么顺序拼，见 preset-order；
每块用什么身份发（系统 / 用户 / AI）；
温度、上下文长度、最大回复长度等参数，见 preset-params。

预设在酒馆左上角第一个图标「AI 响应配置」里切换、导入、导出。

预设和角色卡的分工#

一句话：角色卡管「演谁」，预设管「怎么演」。

角色卡：人设、世界观、开场白、世界书；
预设：文风要求、叙事人称、回复长度、破限、思维链格式。

同一张卡换个预设，效果可能天差地别。详细分工见 preset-vs-card。

常见的预设内容#

块	作用
主要提示词	告诉模型「你在写一个角色扮演故事」
文风 / 写作要求	人称、篇幅、描写方式
破限	让模型放开写的提示词
思维链	要求模型先在标签里思考再回复
历史后置指令	紧贴最新消息的最终提醒

预设还能带别的东西#

预设正则：新版酒馆的预设可以自带正则，切换预设时一起生效；
酒馆助手的预设脚本库：脚本跟着预设走。

容易踩的坑#

预设和卡打架：预设规定第三人称、卡的开场白是第二人称，AI 会混乱；
预设关掉了世界书块：卡的世界书就发不出去，见 preset-order；
预设禁止覆盖主要提示词：卡里的系统提示不生效，见 card-system-prompt；
预设自带的思维链和卡的正则冲突：思维链标签没被隐藏，或卡的正则把思维链也改了。测试时用你推荐的预设。

Instruct 与 Context 模板#

如果你用的是文本补全接口（本地跑的模型、KoboldCpp、部分中转），酒馆不会用对话补全预设，而是用下面两种模板。用 OpenAI、Claude 这类对话补全接口的话，可以跳过这条。

Context 模板（上下文模板）#

规定角色卡各部分怎么拼成开头的一大段文字：描述放哪、性格放哪、示例对话怎么标记。

Instruct 模板（指令模板）#

规定每一条消息怎么包起来。不同模型有不同的格式，比如：

1
<|im_start|>user
2
你好<|im_end|>
3
<|im_start|>assistant

模板选错，模型分不清谁在说话，会出现自问自答、输出乱码标记、停不下来等问题。

怎么选#

看模型说明里写的是什么格式（ChatML、Llama 3、Mistral 等），选同名模板；
酒馆有「自动选择」，大部分情况选对了；
不确定就去模型的发布页找推荐设置。

容易踩的坑#

用对话补全却在调 Instruct：对话补全模式下这两个模板不起作用，改了也没反应；
卡里写了模型专用标记：比如在卡里写 <|im_start|>，换个模型就乱了。卡里只写普通文字。

提示词顺序（prompt_order）#

对话补全预设的面板底部有一个「提示词」列表，列出组成提示词的每一块。这个列表的顺序和开关，就是预设里的 prompt_order。

列表里有什么#

内置的块：

主要提示词、辅助提示、历史后置指令：预设作者写的指示；
世界书（前）/ 世界书（后）：卡的世界书条目插入的位置；
用户设定描述、角色描述、角色性格、情景：从卡和人设里取；
示例对话、聊天记录：从卡和聊天里取。

再加上预设作者自己添加的各种块（文风、破限、思维链……）。

能做什么#

拖动：改顺序；
开关：关掉的块不发送；
编辑：点笔形图标改内容；
新建块：位置可以选「相对」（按列表顺序）或「聊天中」（插在聊天记录的某个深度）；
禁止覆盖：勾上后，角色卡里的系统提示不能替换这一块，见 card-system-prompt。

顺序的影响#

越靠后（越接近聊天记录末尾）的内容，模型越重视。所以：

背景资料放前面；
格式要求、最终提醒放后面（历史后置指令、或「聊天中」深度 0～2）。

容易踩的坑#

世界书块被关或被删：卡的「角色定义前 / 后」条目全部发不出去，世界书像没生效一样。卡不生效时先检查这里；
聊天记录块被关：AI 完全不知道之前聊了什么；
角色描述块被关：有的预设为了「全部交给世界书」会关掉它，这时卡的描述字段白写。

常用参数：温度、上下文、回复长度#

预设面板最上面是一排参数。大部分保持默认就行，下面几个最常需要调。

上下文长度（Token）#

每次最多发多少 token 给模型。

不能超过模型的实际上限，超了会报错；
酒馆默认把滑块限制在一个较小的范围，勾「解锁上下文上限」才能拉大；
设得太小：世界书预算（默认占 25%）和聊天记录都很紧，AI 健忘；
设得太大：每次请求更贵、更慢，而且很长的上下文模型也未必都用得上。

一般 32k～64k 对角色扮演够用。

最大回复长度（Token）#

模型一次最多写多少。

太小：回复写一半被截断；
有思维链的模型，思考过程也算在里面，要留够；
它也从上下文里预留，设得越大，能放的聊天记录越少。

温度#

控制随机程度。

温度	效果
低（0.3～0.7）	稳定、保守，容易重复
中（0.8～1.0）	常用范围
高（1.2 以上）	更有创意，也更容易胡说、崩格式

MVU、状态栏这类要求固定格式的卡，温度别太高，否则变量更新容易写错。

其他#

参数	一句话
Top P / Top K	另一种控制随机的方式，一般不用动
频率惩罚 / 存在惩罚	减少重复用词，太大会让文字变怪
流式传输	回复一个字一个字出来
请求思维链 / 推理强度	让支持的模型先思考，更聪明也更慢
压缩系统消息	把连续的系统消息合成一条，部分接口需要

容易踩的坑#

回复总是截断：调大最大回复长度；或者用「继续」按钮接着写；
流式输出时界面闪烁、状态栏乱跳：流式时消息在不断变化，前端界面会反复刷新。酒馆助手有「允许流式渲染」开关可以关掉；
温度很高还抱怨 AI 不听话：先降温度再改卡；
有的模型不支持某些参数：比如部分推理模型会忽略温度。

正则表达式

Mon, 26 Oct 2026 00:00:00 GMT

常用正则速查#

写卡最常用的几条正则，直接抄，改改标签名就能用。每条都写明了该勾哪些选项。

1. 隐藏思维链#

模型在 <think> 标签里思考，不想看到也不想发回给 AI。

查找：/<think>[\s\S]*?<\/think>\s*/g
替换为：（留空）
作用范围：AI 输出
选项：仅影响显示 + 仅影响后端提示词（两个都勾）

新版酒馆会把很多模型的思考过程单独放进「推理」区，这时不需要这条。

2. 思维链折叠成可展开的块#

查找：/<think>([\s\S]*?)<\/think>/g
替换为：<details><summary>思考</summary>$1</details>
选项：仅影响显示

再配一条「仅影响后端提示词」的第 1 条，把它从历史里删掉。

3. 对白、心理上色#

查找：/「([^」\n]+)」/g
替换为：<span style="color:#c86">「$1」</span>
选项：仅影响显示

心理活动用其他括号的话，把两处「」换成对应的符号。

4. 从历史里删掉界面标签#

AI 输出了 <options>...</options>，显示时变成按钮，但不希望它留在历史里。

查找：/<options>[\s\S]*?<\/options>/g
替换为：（留空）
选项：仅影响后端提示词

5. 只保留最近几条的状态栏#

查找：/<StatusBlock>[\s\S]*?<\/StatusBlock>/g
替换为：（留空）
选项：仅影响后端提示词，最小深度 2

最近两条的状态还在，AI 知道当前状态；更早的删掉省 token。见 regex-depth。

6. 删掉多余空行#

查找：/\n{3,}/g
替换为：两个换行（在替换框里按两次回车）
选项：仅影响显示

7. 隐藏玩家输入里的指令括号#

玩家用「（旁白：……）」给 AI 下指令，不想在聊天里看到。

查找：/（旁白：[^）]*）/g
替换为：（留空）
作用范围：用户输入
选项：仅影响显示

抄的时候注意#

标签名要和你世界书里要求 AI 输出的一模一样，包括大小写；
先在「测试模式」里粘一段真实消息试；
同一个标签别让两条正则都去改，顺序靠后的会拿到已经被改过的内容；
预设、全局正则里可能已经有类似的规则，重复处理会出怪事。

容易踩的坑#

界面正则选了都不勾：原文被永久替换，见 pit-regex-scope；
美元符号：替换内容里的 $ 后面跟数字会被当成捕获组，见 pit-dollar；
作用范围没勾世界书：想处理世界书内容的正则要勾「世界书」，见 pit-regex-placement。

仅影响显示与仅影响后端提示词#

正则设置里有一组「表层替换」选项，决定这条正则改的是什么。这是正则最重要、也最容易弄错的设置。

三种组合#

设置	你看到的	发给 AI 的	聊天记录原文
仅影响显示（markdownOnly）	改了	不改	不改
仅影响后端提示词（promptOnly）	不改	改了	不改
两个都勾	改了	改了	不改
两个都不勾	改了	改了	永久改掉

「两个都不勾」时，正则在消息生成或发送的那一刻直接改写消息本身，原文就没了。

典型用法#

需求	选哪个
状态栏、选项按钮、美化	仅影响显示
从历史里删掉界面标签、旧的变量命令	仅影响后端提示词
显示和发送都要去掉某个内容	两个都勾
真正改写消息（很少需要）	都不勾

一个卡片前端功能通常是一对正则：一条「仅显示」把标签变成界面，一条「仅提示词」把标签从 AI 看到的历史里删掉。

容易踩的坑#

都不勾，状态栏把原文吃掉了：变量命令、标签被永久替换成 HTML，变量框架读不到，AI 下一轮也看不到。界面正则一定勾「仅影响显示」，见 pit-regex-scope；
只勾仅显示，AI 越写越乱：界面标签留在历史里，AI 看到一大堆标签会学着乱写；
以为仅显示的正则会改发送内容：它只改屏幕上的，AI 看到的还是原文；
改了正则旧消息没变：显示类的正则对已经显示的消息不会立刻重算，刷新或重新进入聊天才生效。

正则的最小深度与最大深度#

正则设置里的「最小深度 / 最大深度」让正则只对某几层消息生效。深度从最新消息往回数：最新一条是 0，前一条是 1，以此类推。

留空：不限制；
最小深度 2：最新的两条（深度 0、1）不处理；
最大深度 0：只处理最新一条。

典型用法#

需求	设置
只在最新消息显示状态栏，旧消息显示简版	状态栏正则「仅显示」+ 最大深度 0；另一条简版正则最小深度 1
发给 AI 时只保留最近几条的详细内容	「仅提示词」+ 最小深度 3，把更早的长内容删掉或换成摘要
删掉很早以前的变量更新命令	「仅提示词」+ 最小深度 5

用深度可以大幅省 token：最近几条保留完整信息，更早的只留正文。

显示和发送的深度怎么算#

显示：消息渲染时计算，最新一条是 0，系统消息不算；
发送给 AI：组装提示词时计算，聊天记录的最后一条是 0。

容易踩的坑#

旧消息的显示没跟着变：显示类正则只在消息渲染时计算一次。新消息来了，上一条不会自动重算，看起来还是「深度 0」的样子。刷新或重新进入聊天后才按新深度显示；
深度和楼层号不是一回事：楼层号从开场白往后数，深度从最新往前数；
以为深度对世界书也有用：世界书内容的正则只有「@D 深度」插入的条目才带深度；
最小深度大于最大深度：这条正则就什么都不处理了。

正则的写法与标志（g、s、i）#

「查找正则表达式」一栏推荐写成两边带斜杠、后面跟标志的形式：

1
/要找的内容/gs

常用标志#

标志	作用	什么时候要
`g`	替换所有匹配，不加只换第一处	几乎总是要
`s`	让 `.` 也能匹配换行	要匹配跨多行的内容时
`i`	不区分大小写	匹配英文标签时可选
`m`	`^`、`$` 匹配每一行的开头结尾	按行处理时

不写斜杠时，整行被当成规则本身，没有任何标志，也就只替换第一处。

最常用的几个符号#

写法	意思
`.`	任意一个字符（不含换行，除非加 `s`）
`[\s\S]`	任意一个字符，包括换行
`*` / `+` / `?`	前一个出现 0 次以上 / 1 次以上 / 0 或 1 次
`*?` / `+?`	同上，但尽量少匹配（非贪婪）
`[^」]`	除了「」」以外的任意字符
`\d` / `\s`	数字 / 空白
`^` / `$`	开头 / 结尾
`\`	转义，让 `.`、`(`、`/`、`*` 这些符号表示它本身

另外，竖线表示「或」：/你好|您好/ 两个都能匹配。

贪婪与非贪婪#

消息里有两段 <a>1</a> 中间 <a>2</a>：

/<a>[\s\S]*<\/a>/ 会从第一个 <a> 一直吃到最后一个 </a>，把中间全吞了；
/<a>[\s\S]*?<\/a>/g 才是分别匹配两段。

匹配标签内容时，几乎总是用 *?。

容易踩的坑#

忘了 g：只有第一处被替换，后面的原样留着；
标签内容有换行却用了 .*：匹配不到。用 [\s\S]*? 或加 s 标志；
斜杠没转义：在 /.../ 形式里写结束标签要写 <\/tag>；
中文标点全角半角：「：」和「:」是两个字符，规则里写哪个就只匹配哪个；
写完没测：正则编辑窗口里打开「测试模式」，粘一段真实消息进去看输出。

捕获组#

查找里用圆括号 ( ) 圈出的部分叫捕获组。替换时用 $1、$2 引用它们，第几个括号就是几号。

例子：折叠思维链#

查找：/<think>([\s\S]*?)<\/think>/g
替换为：<details><summary>思考</summary>$1</details>

([\s\S]*?) 抓住了标签中间的内容，替换时用 $1 放回去。

例子：给对白上色#

查找：/「([^」]+)」/g
替换为：<span style="color:#d4a">「$1」</span>

可用的引用#

写法	意思
`$1`～`$9`	第 1～9 个捕获组
`$0` 或 `{{match}}`	整个匹配到的内容
`$<名字>`	命名捕获组，查找里写成 `(?<名字>...)`

不想被捕获的括号#

只是为了分组、不需要引用的括号，写成 (?: )，不占编号：

/(?:你好|您好)，(\S+)/ 里，$1 是名字，不是问候语。

容易踩的坑#

编号数错了：嵌套括号按左括号出现的顺序编号；
引用不存在的组：结果不可预料，多数时候变成空，内容凭空消失，见 pit-dollar；
替换内容里本来就有美元符号：比如价格「$100」，会被当成第 100 个捕获组而变成空，见 pit-dollar；
替换内容里有宏：替换结果最后还会做一次宏替换，{{user}} 会变成名字。

酒馆正则#

酒馆正则就是「自动查找替换」：在消息显示前或发给 AI 前，按规则把一段文字换成另一段。卡片的美化、状态栏、隐藏思维链，基本都靠它。

正则在哪#

酒馆顶部的扩展图标（三个方块）→「正则」。里面分三组：

分组	存在哪	作用范围
全局正则	你的酒馆设置	所有角色、所有聊天
局部正则	角色卡里	只对这张卡，需要允许才生效，见 pit-allow-scripts
预设正则	预设里	用这个预设时

写卡时做的正则都是局部正则，会跟着卡导出。

一条正则的设置项#

设置	意思
查找正则表达式	要找的文字规则，见 regex-flags
替换为	换成什么，可以用 `$1` 引用捕获组，见 regex-groups
修剪掉	替换前先从匹配内容里删掉的文字
作用范围	对哪些内容生效：用户输入、AI 输出、快捷命令、世界书、推理
仅影响显示 / 仅影响后端提示词	只改看到的，还是只改发给 AI 的，见 regex-scope
在编辑时运行	手动编辑消息后也执行
最小深度 / 最大深度	只对某几层消息生效，见 regex-depth
正则表达式查找时的宏	查找内容里的 `{{user}}` 等要不要先替换

常见用途#

美化显示：给对白、动作、心理上颜色；
隐藏或折叠思维链；
状态栏、选项按钮：把标签换成界面，见 card-frontend；
清理历史：把界面标签、旧的变量更新命令从发给 AI 的内容里删掉，省 token。

常用写法直接抄 regex-cheatsheet。

容易踩的坑#

局部正则没被允许：导入卡时弹窗问「是否启用」，点了否就不生效，见 pit-allow-scripts；
只替换了第一个：查找内容不带 g 标志时只换第一处，见 regex-flags；
作用范围漏勾：只勾「AI 输出」时，玩家自己发的消息不会被处理（开场白算 AI 输出）；
预设正则改完不生效：要重新加载聊天。

正则勾错了作用范围#

现象：正则在测试模式里明明能匹配，实际聊天里就是不生效；或者只对一部分消息生效。

为什么#

正则的「作用范围」决定它处理哪些内容，没勾的就不会处理：

作用范围	处理的内容
用户输入	玩家发的消息
AI 输出	AI 的回复，包括开场白
快捷命令	斜杠命令产生的文字，一般用不到
世界书	世界书条目发给 AI 前的内容
推理	模型的思考过程（单独显示的那块）

常见搞错的情况#

想处理玩家的消息，只勾了 AI 输出：玩家消息里的标签原样留着；
想隐藏思考过程，只勾了 AI 输出：新版酒馆把思考过程单独存放，要勾「推理」；
想改世界书内容，勾了世界书但选了「仅影响显示」：世界书内容从来不显示，只会发给 AI，所以世界书的正则**必须勾「仅影响后端提示词」**才会执行；
世界书正则设了深度：只有插入在 @D 深度的条目才有深度，其他位置的条目不受深度限制影响。

怎么办#

新建正则时先想清楚：这条要处理谁的文字？
界面类正则一般勾「AI 输出」；如果玩家消息里也会有对应标签，再勾「用户输入」；
用「测试模式」只能验证查找和替换本身，作用范围要在聊天里实测。

容易踩的坑#

从老卡复制来的正则用了已废弃的范围：早期版本有「仅格式化显示」这种范围，现在改成了单独的选项，导入后要重新检查；
以为开场白不算 AI 输出：开场白和备选开场白都按 AI 输出处理；
正则对旧消息不生效：显示类正则要刷新或重新进入聊天才对已有消息重新计算。

正则把聊天原文永久改掉了#

现象：

编辑消息时发现原文里的标签、更新命令不见了，变成了一大段 HTML；
MVU 读不到更新命令，变量不动；
AI 下一轮看到的历史里塞满了界面代码，开始胡乱模仿。

为什么#

正则的「仅影响显示」「仅影响后端提示词」两个都不勾时，这条正则会在消息生成（或发送）的那一刻直接改写消息本身，而且改了就回不去了，见 regex-scope。

界面类的正则（状态栏、选项、美化）如果这样设置：

原来的标签被替换成 HTML，存进了聊天记录；
依赖原文的东西（MVU 的更新命令、其他正则）全找不到原文了；
这段 HTML 还会被当作历史发给 AI。

怎么办#

正则用途	正确设置
把标签变成界面	仅影响显示
把标签从发给 AI 的历史里删掉	仅影响后端提示词
显示和发送都不要	两个都勾

已经被改坏的旧消息只能手动编辑恢复，或者开新聊天。

写卡时怎么避免#

界面正则一律勾「仅影响显示」；
「两个都不勾」只留给真的想改写原文的情况（很少见）；
发卡前编辑一条 AI 消息看看原文，确认标签还在。

容易踩的坑#

从别的卡复制正则过来：别人的设置不一定对，复制后逐条检查；
两个都勾 ≠ 两个都不勾：两个都勾是「显示和发送都改、原文不动」，两个都不勾才是改原文；
开场白也会被改：开场白在开局时也会被「两个都不勾」的正则改写。

酒馆入门

Mon, 26 Oct 2026 00:00:00 GMT

角色卡是什么#

角色卡就是一份「给 AI 看的设定包」。你把它导入 SillyTavern（大家叫它「酒馆」），AI 就会照着里面的设定扮演角色、陪你聊天或跑剧情。

打个比方：AI 是演员，角色卡是剧本，预设是导演的要求，聊天记录是已经演过的戏。每次你发消息，酒馆会把这三样拼成一大段文字发给 AI，AI 接着往下演。具体怎么拼见 basics-prompt-assembly。

一张卡里有什么#

部分	作用	什么时候发给 AI
角色描述	角色是谁、长什么样、什么性格、和 {{user}} 什么关系	每轮都发
性格摘要、情景	补充性格关键词、当前所处的场景	每轮都发（很多卡留空）
开场白	聊天的第一条消息，可以有好几条备选	作为聊天记录的第一条
示例对话	给 AI 看「这个角色说话是什么样」	按设置发，见 card-example-dialogue
世界书	地点、配角、规则等补充设定	常驻的每轮发，其余被关键词触发才发
系统提示、历史后置指令	卡作者给 AI 的额外指示	每轮都发，见 card-system-prompt
正则	改写消息的显示或发给 AI 的内容	不发给 AI，是酒馆自己执行的
脚本	酒馆助手执行的代码，MVU 变量卡靠它	不发给 AI
创作者注释	写给玩家看的说明	不发给 AI，见 card-creator-notes

卡的样子#

PNG 图片：最常见。卡的全部内容藏在图片文件里，看起来就是一张头像，见 card-v2-v3；
JSON 文件：纯文字，没有头像，方便查看和修改。

新手最容易误会的几点#

卡不是越长越好：每轮都发的部分越长，越挤占聊天记录的空间，AI 反而记不住前面聊了什么，见 tokens。
写在卡里 ≠ AI 一定照做：AI 会被预设、聊天记录影响。重要的规则要写清楚、放对位置，见 worldbook-position。
改了卡，旧聊天不一定跟着变：开场白、初始变量只在新开聊天时生效，见 pit-old-chat。
界面和变量不归 AI 管：状态栏、按钮是正则和脚本做出来的，AI 只负责按格式输出文字，见 card-frontend。

从零开始写一张卡，看 basics-first-card；看到不懂的词，查 basics-glossary。

从零写一张卡：路线图#

第一次写卡，不知道从哪下手？按这个顺序来，每一步都有对应的词条可以细看。

第 1 步：想清楚「这张卡玩什么」#

先用一两句话回答三个问题：

谁：角色是谁？（「冷淡的落魄千金沈清」）
在哪：什么世界、什么场景？（「民国上海，沈家破产后」）
玩什么：玩家扮演谁、来干什么？（「{{user}}是新来的账房先生，帮她撑起铺子」）

「玩什么」最容易被忽略。只有人设没有玩法的卡，聊几句就没话说了。

第 2 步：写角色描述#

外貌、性格、说话方式、过去、和 {{user}} 的关系。重点是能指导 AI 怎么演的信息，而不是简历，见 card-description。

第 3 步：写开场白#

开场白决定第一印象，也决定 AI 后面的文风和篇幅。从一个具体场景切入，给 {{user}} 留出回应的空间，见 greeting-forms。

第 4 步：把细节放进世界书#

地点、配角、组织、物品……一条一条写，设好关键词。只有核心规则用常驻，见 worldbook-constant 和 worldbook-keywords。

第 5 步（可选）：加玩法#

想要好感度、金钱、时间这类数值：用 MVU 变量，见 mvu-what；
想要状态栏、选项按钮、美化排版：做卡片前端，见 card-frontend；
想要说话风格更稳：加几段示例对话，见 card-example-dialogue。

第 6 步：导入酒馆实测#

导出 PNG，导入酒馆，开新聊天，聊十几轮。看看：

AI 有没有 OOC（不像这个角色）、有没有替 {{user}} 说话；
世界书该触发的有没有触发；
状态栏、按钮显示正常吗。

遇到问题按 pit-checklist 一项项查。

新手常犯的错#

一上来就写几万字设定：先做一个能玩的小版本，玩起来再补；
描述里写满「她很温柔、善良、可爱」：形容词没用，写具体行为和说话方式；
开场白替 {{user}} 做了决定：「你决定留下来」这种话会让玩家出戏；
只在 App 里看，没在酒馆里试：酒馆的显示和 App 预览不完全一样，一定要实测。

一次发给模型的都有什么#

你每发一条消息，酒馆都会把一大段文字拼好发给模型。模型并不「记得」之前聊过什么，它每次都是从头读这一大段，然后写下一条回复。所以理解「这一大段里有什么、按什么顺序」，是写好卡的基础。

默认的拼接顺序#

用对话补全（OpenAI、Claude、Gemini、DeepSeek 这类接口）时，酒馆默认预设的顺序是：

主要提示词：比如「在 {{char}} 和 {{user}} 的虚构对话中写出 {{char}} 的下一条回复」。角色卡如果写了系统提示，默认会替换它，见 card-system-prompt；
世界书（角色定义前）；
用户设定描述：玩家给自己写的人设；
角色描述；
角色性格（性格摘要）；
情景；
辅助提示（预设里的一个自定义块）；
世界书（角色定义后）；
示例对话；
聊天记录：开场白 + 你们聊过的内容；
历史后置指令：放在最后、紧贴最新消息的指示。

另外：

世界书里位置设成「@D 深度」的条目、作者注释，会插进聊天记录中间（倒数第 N 条消息处），见 worldbook-position；
预设可以自己加很多块（文风要求、破限、输出格式……），也可以拖动改顺序，见 preset-order。

位置越靠后，影响越强#

模型对靠近末尾的内容最敏感。所以：

「必须遵守的格式」「每次都要输出的标签」放在深度 0～4 或历史后置指令里，效果最好；
背景设定、人物资料放在前面（角色定义前后）就行，它们是「参考资料」。

每部分该写什么#

位置	适合放
角色描述	角色是谁、外貌、性格、说话方式、和 {{user}} 的关系
世界书（关键词触发）	地点、配角、物品、事件等「提到才需要」的细节
世界书（常驻）	世界观核心规则、MVU 变量规则与输出格式
示例对话	说话风格样本
开场白	第一个场景，定下文风和篇幅
历史后置指令	简短但必须每次遵守的要求

想亲眼看看#

酒馆里 AI 回复右上角有一排小按钮，其中「提示词」（柱状图标，有时要先点「…」展开）能看到这一轮实际发出去的内容和每部分占多少 token。排查「AI 为什么不照设定来」时非常有用：先确认设定真的发出去了。

相关：tokens、preset-vs-card

术语表#

写卡圈常见说法，按拼音和字母大致排序。不懂的词先查这里。

说法	意思	详见
酒馆 / ST	SillyTavern，最常用的角色卡聊天前端	what-is-card
酒馆助手 / TH	酒馆扩展 JS-Slash-Runner，能运行卡里的脚本、渲染界面	pit-allow-scripts
角色卡 / 卡	给 AI 扮演用的设定包，通常是 PNG	what-is-card
世界书 / WI / 知识书	按关键词触发的补充设定	worldbook-entry
角色书	嵌在角色卡里的世界书	pit-embedded-book
蓝灯 / 绿灯	世界书条目的常驻 / 关键词触发	worldbook-constant
预设	规定提示词怎么拼、参数怎么设的配置	preset-chat
破限	预设里让模型放开写的提示词	preset-chat
开场白 / first_mes	聊天的第一条消息	greeting-forms
楼层	聊天里的一条消息，第 0 楼是开场白
深度 / @D	从最新消息往回数第几条	worldbook-position
token	模型计算长度的单位	tokens
上下文	每次发给模型的全部内容	tokens
宏	`{{user}}` 这类占位符	macros
正则	查找替换规则，用来美化或清理消息	regex-tavern
局部正则	存在角色卡里的正则，需要允许才生效	pit-allow-scripts
MVU	变量框架，让卡有好感度、金钱等数值	mvu-what
stat_data	MVU 存变量的地方	mvu-schema
InitVar	MVU 的初始变量	mvu-initvar
状态栏	显示在回复里的变量面板	mvu-statusbar
前端 / 卡片前端	卡自带的按钮、面板、美化界面	card-frontend
OOC	出戏，不像这个角色了
抢话	AI 替 {{user}} 说话或做决定	card-system-prompt
AI 味	套话多、比喻堆砌的文风	de-ai
思维链 / CoT	模型正式回复前的思考过程	regex-cheatsheet
流式	回复一个字一个字蹦出来	preset-params
温度	控制回复随机程度的参数	preset-params
V2 / V3	角色卡格式版本	card-v2-v3
EJS	能按变量条件输出不同内容的模板写法	ejs

token 与上下文#

token 是什么#

模型不是按「字」算长度，而是按 token（可以理解为「词块」）算。粗略换算：

中文：1 个字大约 1～1.5 个 token（不同模型不一样）；
英文：1 个单词大约 1～1.5 个 token。

酒馆里很多地方会显示 token 数，比如角色卡编辑页底部、世界书条目右上角。

上下文是什么#

上下文就是「每次发给模型的全部内容」，有长度上限（比如 32k、128k token）。每次你发消息，酒馆都要把这些塞进去：

预设里的提示词；
角色卡每轮都发的部分（描述、性格、情景、系统提示）；
常驻世界书 + 这轮被触发的世界书；
示例对话；
聊天记录（从最新的往回塞，塞不下的就丢掉）；
还要给模型的回复留空间（「最大回复长度」）。

前面几项占得越多，能塞进去的聊天记录就越少，AI 就越「健忘」。

写卡时怎么省#

每轮都发的内容要精炼：角色描述、常驻条目只放「每轮都必须知道」的东西；
细节交给关键词条目：地点、配角、物品，提到才发，见 worldbook-constant；
不要重复：同一段设定别在描述和世界书里各写一遍；
界面标签别进历史：卡片前端的占位标签、状态栏代码要用正则从发给模型的内容里删掉，见 regex-scope；

容易踩的坑#

世界书有预算：默认最多只占上下文的 25%，超了后面的条目直接不发，见 worldbook-budget。
上下文长度别乱调：预设里的「上下文长度」超过模型实际上限，请求会报错，见 preset-params。
中文比你想的贵：一张 5000 字的卡，光描述就可能占 6000 token 以上。

世界书完全指南

Mon, 26 Oct 2026 00:00:00 GMT

世界书条目的结构#

世界书（也叫 World Info、知识书）是一本「设定字典」。里面每一条叫条目，平时不发给 AI，聊天里出现了关键词才把这条内容塞进提示词。这样大量设定只在需要时出现，省 token。

一条条目由什么组成#

字段	酒馆里叫	作用
标题	标题 / 备注	给人看的名字，不发给 AI
关键词	主要关键字	聊天里出现这些词就触发，见 worldbook-keywords
次要关键词	可选过滤器	配合逻辑做更精细的条件
内容	内容	触发后插入提示词的正文，见 worldbook-format
触发方式	蓝灯 / 绿灯	常驻（每轮都发）或关键词触发，见 worldbook-constant
位置	插入位置	插在提示词的哪里，见 worldbook-position
深度	深度	位置选「@D」时，插在倒数第几条消息处
顺序	顺序	同一位置里谁前谁后，也影响预算优先级，见 worldbook-order
概率	触发概率 %	触发后再掷一次骰子决定发不发，默认 100
递归选项	不可递归 / 防止进一步递归 / 延迟到递归	见 worldbook-recursion
包含组	包含组 / 组权重	同组只取一条，见 worldbook-order
时间效果	黏性 / 冷却 / 延迟	触发后持续几轮、多久不再触发、第几轮后才能触发，见 worldbook-timed
扫描深度	扫描深度	本条单独设置往回看几条消息，见 worldbook-scan-depth

新建条目的默认值：顺序 100、位置「角色定义前」、深度 4、概率 100。

一条好条目的样子#

一条只讲一件事：一个地点、一个配角、一条规则；
关键词是聊天里真会出现的词：名字、别称、常见说法都加上；
内容自成一体：AI 只看到这一条也能明白，不要写「如上所述」；
标题写清楚：自己以后好找。

容易踩的坑#

条目写好了没生效：先看世界书是否真的绑定到了角色，嵌在卡里的世界书导入时要选「导入」，见 pit-embedded-book；
关键词太泛：比如「他」「门」，几乎每轮都触发，等于常驻；
条目太多被挤掉：世界书有预算上限，见 worldbook-budget；
条目被关掉了：条目左侧的开关、概率设成 0 都会让它不发。

条目写法：XML 包 YAML、description 留空#

条目内容怎么写，AI 都能读。但写得有结构，AI 更容易分清「这是哪个设定」，不会把两个配角的特征搞混。

推荐写法：标签包结构化文本#

外面用一对标签包住，里面用「名称: 内容」的条目式写法：

1
<地点_北城>
2
名称: 北城
3
氛围: 潮湿、霓虹、永远在下雨
4
势力: 青帮控制码头，巡捕房只管租界
5
要点:
6
  - 夜里十一点宵禁
7
  - 外地人进城要查良民证
8
</地点_北城>

好处：

边界清楚：标签告诉 AI 这一段从哪开始、到哪结束；
信息密度高：比整段散文省 token；
方便修改：哪一项要改一眼就能找到。

标签命名#

用「类别_名字」：<角色_沈清>、<地点_北城>、<规则_宵禁>；
同一张卡里风格统一；
中文、英文都可以，别用会和界面标签冲突的名字（比如 <options>）。

description 可以留空吗#

如果角色的设定已经完整放进世界书（常驻条目），角色卡的「描述」字段可以留空或只放一句摘要。这是很多大型卡的做法。

要点是不要重复：同一段设定在描述和世界书里各写一遍，既浪费 token，改的时候又容易只改一边，造成矛盾。

容易踩的坑#

嵌套太深：缩进好几层的 YAML，AI 读起来反而吃力，两层以内最好；
写成说明书：「本条目用于描述北城」这种话是废话，直接写内容；
在内容里写 {{char}} 指代配角：{{char}} 永远是卡的名字，配角要写名字；
在条目里写 HTML：发给 AI 的内容用纯文字，界面的事交给正则。

关键词怎么设#

关键词决定条目什么时候触发。设得好，设定在需要时准时出现；设得不好，要么永远不触发，要么每轮都触发。

基本规则#

一条可以有多个关键词，任意一个出现就触发；
默认不区分大小写；
最近几条消息里出现就算（看扫描深度，见 worldbook-scan-depth）。

选关键词的方法#

名字 + 别称：「沈清、沈小姐、大小姐、清儿」；
聊天里真会说的词：玩家不会说「北城行政区」，会说「北城」「城北」；
避免太短太泛：单个字（「门」「刀」）几乎处处都有；
英文名注意整词：见下面的「匹配整个单词」。

匹配整个单词#

世界书设置里有「匹配整个单词」，新装酒馆默认开着。开着时：

英文关键词要作为完整单词出现：关键词 Tom 不会匹配 Tommy；
中文不受影响：中文没有空格分词，酒馆把汉字两边都当作「边界」，「北城」照样能在「我们去北城吧」里匹配到。

次要关键词与逻辑#

条目还可以设「可选过滤器」（次要关键词），配合逻辑使用：

逻辑	意思
与任意	主关键词命中，且次要关键词任意一个也出现
与所有	主关键词命中，且次要关键词全都出现
非任何	主关键词命中，且次要关键词一个都没出现
非所有	主关键词命中，且次要关键词没有全部出现

例子：主关键词「沈清」，次要关键词「生气、吵架」，逻辑「与任意」，就能做出「只在和沈清吵架时触发」的条目。

正则关键词#

关键词写成 /北城|城北/ 这样两边带斜杠的形式，就按正则匹配，更灵活。正则关键词不受「匹配整个单词」「区分大小写」影响，大小写用末尾的 i 控制。

容易踩的坑#

用角色名当关键词：酒馆会把说话人名字一起扫描，角色名每条消息都有，等于常驻，见 pit-wi-keywords；
关键词里有空格或全角逗号：关键词用英文逗号分隔，全角逗号会被当成关键词的一部分；
单个汉字当关键词：「刀」会匹配「刀疤」「剪刀」「刀子嘴」，几乎每轮都触发；
只写了正式名称：玩家用昵称、简称时就不触发了。

插入位置与深度#

条目触发后插在提示词的哪里，由「插入位置」决定。位置不同，AI 对它的重视程度也不同：越靠近最新消息，影响越强。

全部位置#

酒馆里的名字	插在哪里	适合
角色定义前（↑Char）	角色描述前面	世界观、背景设定（默认）
角色定义后（↓Char）	角色描述后面	对角色的补充设定
示例消息前（↑EM） / 示例消息后（↓EM）	示例对话前后	很少用
作者注释前（↑AN） / 作者注释后（↓AN）	作者注释的前后	配合作者注释使用
插入深度 @D	聊天记录里倒数第 N 条消息处	必须遵守的规则、输出格式
锚点	只在预设或其他地方用对应宏引用时出现	高级用法

深度（@D）怎么算#

选「插入深度」时还要填深度数字，从最新消息往回数：

深度 0：在所有聊天记录的最后，紧贴着 AI 要写的回复，影响最强；
深度 1：在最新一条消息之前；
深度 4（默认）：在倒数第 4 条消息之前。

@D 还可以选这段内容以什么身份插入：系统、用户、AI。一般用系统。

怎么选#

背景资料（地点、人物、历史）：角色定义前后就行；
必须每次遵守的规则（输出格式、变量更新、标签要求）：@D 浅深度，0～4；
想让 AI 记得但别太强势的提醒：@D 4～8。

容易踩的坑#

预设关掉了世界书块：「角色定义前 / 后」的条目实际放在预设的「世界书（前）/ 世界书（后）」这两块里。有些预设把这两块关掉或删了，条目就算触发也发不出去，见 preset-order；
深度 0 放太多：多条长内容挤在最后，会严重干扰 AI 的回复，甚至让它复读规则；
深度设得比聊天记录还深：聊天刚开始只有两三条消息时，深度 10 的条目会被放在最前面；
以为位置能解决一切：AI 不遵守，先确认条目真的触发并且发出去了，见 basics-prompt-assembly。

顺序与分组#

顺序（order）#

每条条目有一个「顺序」数字，默认 100。它管两件事：

1. 同一位置里的先后#

同一插入位置的多条条目，数字小的排在前面，数字大的排在后面。

例如三条都在「角色定义后」：顺序 10、50、200，发出去的顺序就是 10 → 50 → 200。数字大的离聊天记录更近，对 AI 的影响通常更强。

2. 预算不够时谁先进#

世界书总长度有上限（见 worldbook-budget）。酒馆会先处理数字大的条目，预算满了，数字小的就被挤掉。

所以：越重要的条目，顺序数字设得越大。

包含组（分组）#

给几条条目填上同一个「包含组」名字，它们同时触发时只会发其中一条。适合互斥内容：

天气：晴 / 雨 / 雪，只能有一个；
随机事件：每次只发生一件；
同一角色的不同阶段：好感度低 / 中 / 高的描述。

选哪一条#

默认按「组权重」随机抽，权重 100 和 50 的条目，被抽中的机会大约 2 : 1；
勾了「确定优先级」的条目优先，几条都勾了就选顺序数字最大的；
开了「使用群组评分」的话，匹配到关键词更多的条目胜出。

容易踩的坑#

以为数字小的更优先：恰好相反，预算优先给数字大的；
常驻条目也参与预算排序：顺序小的常驻条目同样可能被挤掉；
组名写错一个字：就成了两个组，互斥失效；
组里放了常驻条目：常驻条目每轮都触发，会一直和同组条目抢位置。

扫描深度#

扫描深度决定酒馆往回看几条消息来找关键词。

全局设置在世界书面板顶部的「扫描深度」，默认 2；
深度 2 表示只看最近两条消息（一般就是你刚发的和 AI 上一条回复）；
单条条目可以单独设置扫描深度，覆盖全局值。

太小和太大#

设置	结果
太小（1～2）	话题刚提过一句，下一轮就不触发了，AI 突然「忘了」
太大（10 以上）	很久以前提过的东西还一直触发，占着预算

怎么选#

一般保持默认 2～4；
想让某个设定「提到后持续几轮」，与其加大扫描深度，不如用「黏性」，见 worldbook-timed；
重要的地点、人物关键词多加几个别称，比调大深度更有效。

扫描的是什么文字#

默认扫描聊天消息的正文；
「包括名称」开着时（默认开），每条消息前会带上说话人名字一起扫描，所以角色名、玩家名当关键词几乎每轮都触发；
条目里的「额外匹配来源」可以让它同时扫描角色描述、用户设定描述等。

容易踩的坑#

开场白也算消息：聊天刚开始时，开场白里的关键词会触发条目；
AI 的回复也会被扫描：AI 自己提到的词同样会触发条目，这通常是好事；
改扫描深度不生效：单条设置了扫描深度，就不再受全局值影响。

递归#

递归：已经触发的条目，它的内容也会被拿去匹配别的条目的关键词。

例子：玩家说「去北城」，触发了「北城」条目；北城条目的内容里写着「青帮控制码头」，于是又触发了「青帮」条目。这就是一次递归。

默认开不开#

全局开关在世界书面板的「递归扫描」；
新装的酒馆默认开着；
「最大递归深度」限制最多连锁几层，0 表示不限。

单条的三个递归选项#

选项	效果	用在哪
不可递归	本条不会被别的条目内容触发，只能被聊天触发	不想被连带出来的大段设定
防止进一步递归	本条的内容不再去触发别的条目	内容里提到很多名词的总纲、长条目
延迟到递归	本条只能被递归触发，聊天里直接提到不算	「提到 A 时顺带带出 B」的配套条目

什么时候用递归#

好用的地方：人物条目里提到他的组织，组织条目自动跟上，AI 了解得更完整；
危险的地方：条目越多、内容里提到的名词越多，连锁越长，一轮触发几十条，上下文直接被塞满。

建议#

常驻的总纲条目开「防止进一步递归」：它提到所有地名和人名，不关的话每轮都会把所有条目带出来；
大段设定开「不可递归」，只让玩家真正聊到时才出现；
条目多的卡，先关掉递归测一遍，再按需打开。

容易踩的坑#

不知道递归开着：新装酒馆默认开，你以为只触发了一条，实际带出了一串。用 AI 回复上的「提示词」按钮看看实际发了什么；
常驻条目引发连锁：常驻每轮都在，它内容里的关键词每轮都会触发别的条目；
递归 + 预算：连锁带出的条目会抢预算，可能把真正重要的条目挤掉，见 worldbook-budget。

世界书预算：为什么条目没发出去#

世界书不能无限往提示词里塞，有一个预算上限。超出预算的条目，即使触发了也不会发出去。

预算怎么算#

世界书面板顶部有两个设置：

上下文百分比：默认 25%。上下文长度 32000 时，世界书最多占 8000 token；
Token 预算上限：再加一个固定上限，0 表示不限。

两者取较小的那个。

谁先进预算#

酒馆把这一轮所有触发的条目排队，顺序数字大的先进，一直加到预算满为止，后面的全部丢掉。

正在「黏性」生效的条目排在最前面；
常驻条目不享受特权，照样按顺序排队；
勾了「无视回复限额」的条目不占预算，总能进去。

怎么知道被挤掉了#

世界书设置里打开「溢出警报」，超预算时会弹提示；
用 AI 回复上的「提示词」按钮看实际发了什么。

解决办法#

精简条目：最有效。删掉重复的、啰嗦的内容；
调大顺序数字：重要的条目顺序设大，保证先进预算，见 worldbook-order；
关键的条目勾「无视回复限额」：比如 MVU 的变量规则，少了它变量就不更新了；
提高上下文百分比：会挤占聊天记录，不建议超过 40%；
减少递归连锁：见 worldbook-recursion。

容易踩的坑#

上下文长度设得小：预设里上下文只设了 8000，世界书 25% 只有 2000 token，稍微长点的卡就不够用；
以为常驻一定会发：常驻条目顺序小、预算满了一样会被挤掉，见 pit-wi-budget；
百分比填超过 100：酒馆会重置成 25。

常驻 vs 关键词触发#

世界书条目有两种触发方式，在条目上用一个小灯表示：

蓝灯 = 常驻：不看关键词，每轮都发；
绿灯 = 关键词触发：最近几条消息里出现关键词才发。

各自适合什么#

方式	适合	例子
常驻	每轮都必须知道的核心内容	世界观总纲、主角关系、MVU 变量规则和输出格式、文风要求
关键词	提到才需要的细节	地点、配角、物品、组织、历史事件、招式

判断方法#

问自己：如果这一轮 AI 不知道这条，会出错吗？

会，而且任何时候都会 → 常驻；
只有聊到相关话题才会 → 关键词。

常驻要控制总量#

常驻条目每轮都占上下文，加起来越多，能放的聊天记录越少。经验值：

常驻总量控制在几百到两三千字；
单条常驻别写成长篇，拆成「总纲常驻 + 细节关键词」。

容易踩的坑#

常驻也受预算限制：常驻条目不是「一定会发」。预算满了，顺序靠后的常驻条目照样被挤掉，见 worldbook-budget；
常驻也看概率：概率不是 100 的常驻条目，也会随机不发；
关键词设成角色名字：酒馆默认会把说话人名字一起扫描（「包括名称」），角色名几乎每条消息都有，这条就等于常驻了，见 worldbook-keywords；
全部设成常驻图省事：短卡没问题，条目一多就挤爆上下文，AI 反而抓不住重点。

世界书的几种绑定方式#

酒馆里的世界书是独立的文件，要绑定到某个地方才会生效。同一本世界书可以绑在不同地方，作用范围不一样。

四种绑定#

绑定方式	在哪设置	作用范围
全局世界书	世界书面板「已启用的世界书（全局有效）」	所有角色、所有聊天
角色世界书	角色面板的地球图标：主要世界书 + 附加世界书	只在和这个角色聊天时
聊天知识	角色面板上的护照图标（长按打开绑定窗口）	只在这一个聊天里
用户设定世界书	用户设定面板	用这个人设时

角色卡里自带的世界书，导入时会生成一本同名世界书文件，并绑成这个角色的「主要世界书」，见 pit-embedded-book。

几本世界书同时生效时#

酒馆会把所有绑定的世界书合在一起扫描。排序看世界书设置里的「插入策略」：

角色世界书优先（新装默认）：角色的条目排在前面；
全局世界书优先：全局的排在前面；
均匀排序：大家混在一起按顺序数字排。

预算是所有世界书共用的，见 worldbook-budget。

写卡时注意#

卡的设定放进卡自带的世界书，导出时才会带上；
附加世界书不会跟着卡导出，别人拿到卡时就缺了这部分；
文风、通用规则类的世界书适合做成全局，但别和卡的内容打架。

容易踩的坑#

全局世界书忘了关：玩别的卡时也会触发，设定串台。玩完某张卡记得取消全局；
同一本世界书绑了两次：既是全局又是角色世界书，条目可能重复；
改了导入后的世界书，卡里的没变：导入后的世界书是独立文件，在酒馆里改了它，要重新导出卡才会带上；
重复导入同一张卡：可能生成多本同名世界书，绑定的不一定是你正在改的那本。

黏性、冷却、延迟#

条目设置里的「黏性 / 冷却 / 延迟」三个数字，都以消息条数为单位，用来控制条目在时间上的表现。默认都是空（不生效）。

黏性：触发后持续 N 条#

条目被触发后，接下来 N 条消息里不管还有没有关键词都保持触发。

用途：玩家提了一句「去北城」，接下来几轮虽然没再说「北城」，但人还在北城，设定应该一直在；
比调大扫描深度更精准，只影响这一条；
预算排队时，黏性生效中的条目排在最前面。

冷却：触发后 N 条内不再触发#

条目触发（黏性结束）后，接下来 N 条消息里即使出现关键词也不触发。

用途：随机事件、突发状况，避免每轮都发生；
配合概率使用效果更好：「30% 概率触发，触发后冷却 10 条」。

延迟：聊天至少 N 条后才能触发#

聊天记录不到 N 条时，这条怎么都不触发。

用途：中后期才出现的剧情、秘密，开局就触发会剧透；
比如延迟 20：聊到第 20 条消息以后，关键词才开始起作用。

组合例子#

需求	设置
进入某地后设定持续一阵	关键词「北城」+ 黏性 5
偶尔下雨，别天天下	常驻 + 概率 20 + 冷却 8
聊久了才揭露的身世	关键词「父亲」+ 延迟 30

容易踩的坑#

单位是消息条数，不是「轮」：你一条、AI 一条，一轮就是两条；
删消息、重新生成会影响计数：测试时结果可能和你想的不一样；
延迟是看总消息数：开新聊天才会从头算，旧聊天早就超过了；
黏性条目不受关键词约束：黏性期间即使话题已经换了，它还在占位置，数字别设太大。