跳到主要内容

FTB 说明书索引

FTB 的勾选任务经常用于整合包教程。它们继续从“进行中任务”和解锁通知中过滤，同时可作为独立知识来源查询；查询不勾选任务、消耗材料或领取奖励。

使用​

  • 完整界面的任务页提供“查询说明书”输入框，输入关键词或问题后 Enter 查询。
  • 助手输入框使用 /guide <关键词或问题>、说明书 <关键词或问题> 或 查说明 <关键词或问题>。
  • 原版聊天栏使用 /system guide <关键词或问题>，命令和补全由现有模块指令注册链提供。
  • 管理员或控制台使用 /system ftb reload，重新收录 FTB 当前已加载的说明任务并重建索引；不改玩家进度或奖励。
  • 自然语言可由现有本地路由或模型路由选择说明书检索；不确定的意图仍按原路由处理。
  • 普通知识问题进入核心 system:question：先合并本地共享 / 玩家知识及可读说明书，再按来源回答；只有本地无结果、启用搜索模块且本次明确允许联网时才搜索。/question <问题> 禁止联网回退，/search <问题> 允许回退。

结果最多显示五个不同来源，按相关程度排序，包含任务名称、章节和匹配段落；原文较长时可以展开完整内容。查不到足够相关的内容时显示未找到，不生成无来源的操作说明。说明任务完成后仍可查询，但始终遵守原生可见性。该入口不改主动任务查询的编号缓存。

收录与权限​

当前采用用户确认的规则：只有原生 CheckmarkTask 或没有目标、有说明正文、且不属于新手礼包的任务。普通混合目标、纯物品获取目标和礼包不进入本索引。这里的“说明书”是结构筛选，不使用 AI 自动判断文风；一段符合条件的任务说明都可以成为来源。

说明书读取单独使用 FtbQuestReader.guideCandidates / guideReadable，不能复用会过滤 INTRODUCTION 的进行中视图。返回前检查章节始终隐藏、任务对当前队伍的可见性、hideDetailsUntilStartable 和 hideTextUntilComplete。完成状态本身不使原本可见的说明失效。

共享索引可以保存静态任务正文，但不保存玩家、队伍、进度、奖励领取状态或权限。查询时先生成当前玩家允许读取的 ID 集合，候选不使用隐藏文档填充名额；后台检索完成后回服务端线程重新检查任务、队伍、语言及正文是否仍匹配。权限或内容变化的条目不返回。隐藏内容不会随索引发送到客户端。

实现与体积​

这是纯 Java 的本地稀疏向量索引：复用 LexicalIndex 的词语、汉字及相邻特征、TF-IDF 与余弦相似度，按约 480 字符切段，并加入标题匹配。它不是神经网络 embedding，也不引入 ONNX、模型文件、Redis 或独立数据库进程。禁用领域别名时保留物品注册 ID 中的具体词，避免把所有物品 ID 都归成同一特征；意图路由的原有别名行为保持。

当前返回条件为相似度至少 0.08、查询特征覆盖率至少 0.25。它们是过滤无关片段的启发式阈值，不表示回答正确率或概率置信度。这套词法方法能覆盖关键词与近似表达，不能保证任意同义改写或跨语言语义匹配。

说明书通过统一 AgentDatabase 保存到 <存档>/system/database/shared.dat 的 system:ftb_guides 表，按语言保存原文；任务背景判定也进入同一个共享库的独立表，文件为 GZIP 压缩 NBT。玩家独立库使用 players/<UUID>.dat，预留给其他模块。类型化接口、清理规则和指令语义见 分层本地数据库。磁盘不序列化 TF-IDF 向量，首次查询在后台构建，显式重载会提前重建。

FtbQuestKnowledge 缓存各语言的静态快照，避免每次查询重新解析整份正文；每次只重新计算玩家授权 ID，命中来源返回前再次核对正文。FTB 原生 ClearFileCacheEvent 或手动指令使快照失效，翻译和任务编辑随后重新收录；手工修改磁盘文件需先通过 FTB 自身入口加载。重载用代次使旧查询失效；数据库损坏时报告错误并保留文件，不以空库静默覆盖。旧的两个独立缓存文件不再读取或迁移。

游戏对象和权限检查只发生在服务端队列；向量构建、检索和文件 I/O 在后台执行。首次查询可自动收录，无需客户端上传或手动导出任务文件。

后续磁盘向量后端的版本、依赖体积、适配及性能分析见 JVector 索引评估。目前仍使用上述 Codec 文件型数据库与稀疏内存索引，没有接入 JVector。

API 与代码入口​

/guide 和任务页说明书按钮直接执行本地检索，不请求 embedding 或聊天模型；自然语言不明确时，现有意图路由仍可能请求模型一次。普通问答的 system:question 则会在允许外部 AI 时将授权命中片段交给文本模型整理，发送前后均检查当前访问权限；本地有结果就不搜索。自动 TTS 朗读结果提示属于原有独立语音功能，不能据此把整次交互称为“无外部请求”。

  • data/database/AgentDatabases / AgentDatabase / DatabaseTable：两级作用域、文档和其他 Codec 表的统一持久化。
  • data/database/KnowledgeIndex：切段、稀疏向量与命中筛选。
  • compat/ftb/FtbQuestKnowledge：FTB 静态语料、失效代次与手动重新收录。
  • compat/ftb/FtbQuestGuideTool：游戏快照、授权 ID、异步检索与返回前复核。
  • compat/ftb/FtbQuestReader、FtbQuestText：结构筛选、可见性及按玩家语言读取。
  • module/builtin/quest/QuestGuideModule：单检索工具、指令和路由描述。
  • QuestGuideInput / QuestGuideOutput：按注册表 dispatch 的动作和卡片 Codec，公共 DTO 不引用 FTB 或客户端类。
  • assets/system/cards/quest_guide.json：匹配段落与可展开原文；任务页仍由 QuestSystemClientModule 装配。

未安装或未启用 FTB 模块时，不装配此工作流或加载 FTB 适配器。跨版本同步事项见 FTB 修复记录。