它很小，但它很重要
世界书命中详情看起来只是一个调试功能。 但对于一个需要可治理、可审计的 AI RP 引擎来说，它是很基础的观察面。 这篇文章说明为什么 TavernHeadless 要记录世界书条目的命中、来源和注入位置。
世界书系统的价值
酒馆的世界书系统，是一个很重要的系统。
它不像 RAG（检索增强生成）那样高度自动化。它不会替用户判断所有知识之间的关系，也不会自动把一批文档切块、向量化、检索和重排。
但它有自己的优点：可理解，也方便修改。
一条世界书条目通常包含几个很直观的部分：
- 触发关键词。
- 条目正文。
- 是否常驻。
- 是否启用辅助关键词。
- 注入位置。
- 扫描深度和优先级。
作者可以直接看到它为什么会生效，也可以直接改它。关键词太宽，就收窄。正文太长，就删减。位置不合适，就调整。
这种可理解性很重要。对于 AI RP 来说，世界书不是单纯的知识库。它也是作者控制世界观、角色关系、地点设定和剧情状态的一种方式。
但是，效用本身也要能观察
问题在于，世界书条目是否被写对，只是一半的问题。
另一半是：它在真实对话中到底有没有生效。
使用者需要知道：
- 某条世界书条目有没有被命中。
- 它是被哪一个关键词命中的。
- 它是在用户输入里命中的，还是在历史消息、角色描述、场景描述或递归内容里命中的。
- 命中之后，它被放进了提示词的哪个位置。
- 它进入提示词时的正文是什么。
- 它有没有因为预算裁剪、位置规则或其他处理而没有进入最终提示词。
如果这些问题看不到，世界书的可理解性就只停留在编辑阶段。
作者能理解自己写了什么，却不能方便地理解这些内容在运行时发生了什么。
这就形成了一个很大的反差：世界书系统的存在，是为了方便用户构建一个可控的知识库；但这个知识库在每一轮对话里的实际效用，却不容易被观察。
为什么这不是小问题
当 AI 回复不符合预期时，使用者往往会先怀疑模型。
但问题可能并不在模型。
可能是世界书条目根本没有被触发。也可能是触发了，但被放到了不合适的位置。也可能是触发了，但被后面的提示词覆盖。也可能是命中了太多条目，真正重要的内容被稀释了。
如果没有命中详情，使用者只能猜。
他可能会继续增加关键词，让条目更容易触发。结果触发范围变得更宽，新的误触发又出现了。
他也可能会把同一段设定复制到更多地方，以为这样能提高稳定性。结果提示词变得更长，内容之间也更容易冲突。
这种调试方式成本很高，而且很容易把问题越改越复杂。
所以，世界书命中观察面不是一个锦上添花的小面板。它直接关系到使用者能不能维护自己的知识库。
TavernHeadless 要回答的问题
TavernHeadless 对世界书的要求，不只是“能导入”和“能触发”。
它还应该回答下面这些问题：
- 这一轮有哪些条目被激活？
- 每个条目为什么被激活？
- 命中的关键词是什么？
- 命中发生在哪个输入来源里？
- 条目内容最终被放到了提示词哪里？
- 如果没有命中，原因是没有关键词、关键词不匹配、辅助关键词不满足，还是条目被禁用？
- 如果命中了但效果不对，能不能看到它进入提示词时的真实内容？
这些问题共同构成世界书的运行真相。
其中一部分可以进入摘要字段，例如本轮命中了多少条目、命中的 entry uid 列表。另一部分需要在调试路径里展开，例如 dry-run、preview、inspect、historical explain 或 runtime trace。
这样做的目标不是让普通聊天响应变得更重。详细命中信息可以按需打开。正常生成只保留必要快照，调试时再展开细节。
它很小
从功能形态上看，这件事确实很小。
它不创造新的文本。它不改变世界书的写法。它也不要求用户学习另一套知识库系统。
它只是把世界书触发过程里原本已经发生的事情记录下来：
- 哪个条目被激活。
- 哪个关键词命中。
- 命中来自哪里。
- 条目按什么位置进入提示词。
- 进入提示词时大概是什么内容。
这些信息本来就在系统运行中出现。区别只是过去用完就丢，现在把它留下来，给使用者查看。
所以它看起来很小。
但它很重要
它重要，是因为它让世界书从“我写了什么”变成“我写的东西实际怎样生效”。
这对应 Know What 和 Know How 的两个问题。
Know What 是：这一轮有哪些世界书条目真的生效了？
Know How 是：这些条目为什么生效，又是怎样进入提示词的？
没有这两层信息，使用者只能看到最终回复，却看不到世界书在其中起了什么作用。
有了这两层信息，使用者就可以判断：
- 是关键词需要调整。
- 是条目正文需要修改。
- 是注入位置不合适。
- 是扫描深度不够。
- 是条目之间互相冲突。
- 还是模型确实没有遵守已经注入的设定。
这些判断对大型 AI RP 项目很重要。项目越大，世界书条目越多，靠猜测维护就越困难。
和 Agentic 的关系
世界书命中详情对 Agentic 也有意义。
如果后续有 Director、Verifier、Memory Agent 或 NodeGraph，它们都需要知道当前回合到底使用了哪些背景信息。
Verifier 要检查输出是否违背世界观，就需要知道世界书里哪些设定已经进入提示词。
Director 要决定叙事方向，也需要知道当前场景已经被哪些条目约束。
Memory Agent 要判断一条事实是否应该写入长期记忆，也需要知道这条事实是来自用户输入、模型生成，还是来自世界书注入。
如果世界书命中过程没有记录，Agentic 系统就只能看到最终提示词或最终输出。它会失去一部分来源信息。
所以，这个小观察面，也是后续 Agentic 可解释性的基础之一。
和兼容模式的关系
世界书命中详情不应该改变兼容模式的行为。
兼容模式要做的是尽量保持酒馆资产的运行预期。世界书该怎样触发、怎样排序、怎样注入，仍然应该按照兼容规则执行。
命中详情只是观察这些过程，而不是干预这些过程。
换句话说：
- 关闭调试信息时，生成行为不应改变。
- 打开调试信息时，只是多返回命中和注入的解释。
- 兼容模式不因为增加观察面而变成另一套世界书系统。
这条边界很重要。否则调试能力本身会反过来污染兼容目标。
这个设计负担了什么
记录命中详情也有成本。
系统需要保存更多运行信息。触发引擎需要在调试模式下记录命中来源、关键词、位置和片段。提示词编排器需要把这些信息和最终注入位置对应起来。API 和 SDK 也需要暴露稳定的结构。
详细 trace 还可能比较大。如果每一轮都默认返回完整条目正文和命中片段，普通响应会变重，也可能泄露不必要的内部信息。
所以它应该是一个有边界的能力：
- 摘要信息可以进入常规快照。
- 详细命中信息按需打开。
- 历史解释可以读取已经保存的事实，而不是每次重新猜测。
- 调试输出要尽量反映真实进入提示词的内容，而不是只返回数据库里的原始条目。
这些都是额外工作。
但这份工作是值得的。
所以它很重要
世界书的价值在于可理解和可修改。
如果只能理解编辑时的条目，却不能理解运行时的命中和注入，那么这个价值是不完整的。
TavernHeadless 需要保留世界书的兼容能力，也需要补上运行时观察面。使用者应该能够看到：哪条条目命中了，为什么命中，放到了哪里，对最终提示词产生了什么影响。
这个能力很小。
但它决定了世界书能不能从“可编辑的知识库”，变成“可维护的知识库”。