模组设计

本页介绍原创、改编和已有模组的体验改进，供创作者与编程助手参考。设计时要让玩家能理解处境并作出选择，也要为 AI 主持提供回应行动、裁定规则和维护状态所需的资料。文件格式、字段与平台能力见 模组结构；需要复杂配置时读取对应版本文档，已有源码时可核对 Schema。编程助手负责产出模组资料与配置，文中对主持、队友和玩家行为的说明，是为了帮助设计模组内容，不要求编程助手在创作时扮演这些角色。

先明确设计目标

开始设计前，用简短摘要说明人数与预计时长、规则系统、题材与核心体验、玩家目标、主要行动方式、挑战与失败预期、内容规模。把已确认的约束和暂时采用的假设分开说明。只追问会显著改变设计的问题，例如改编尺度、规则系统或预期难度；其余问题可以采用合理假设，继续设计。摘要可放在回复或已有创作说明中，无需另建设计文档。

冒险结构和失败后的处理原则，应根据具体模组确定。说明为何采用这种结构，以及玩家偏离预期、错过信息或失败时会怎样；可以设计不同路线、提前失败或严格的资源限制，但要符合目标体验，并为后果提供依据。不要把固定章节顺序、多线索保障、失败必定推进或某个线索数量规定为所有模组的标准。

按任务选择流程

原创模组

从核心体验与玩家目标出发，建立局势、行动空间和主要挑战，再选择支撑这些体验的规则与资料。先设计能走到结局的冒险骨架，再扩充支线、素材、地图与建卡。小型模组用简短摘要和场景资料即可；大型模组需要把路线、依赖和状态变化整理清楚。

自创规则时说明判定方式、资源尺度和典型行动结果，检查它们是否支持目标体验。采用已有规则时先核对实际来源与版本，再补模组专属裁定。模板里的字段和值不代表选定规则。

已有故事改编

开始前确认采用忠实改编、局部改善还是整体重构；用户已明确尺度时直接沿用。列出必须保留的设定、关键事件、规则与目标体验，再决定可以调整的结构、人物、线索和结局。区分原作内容、新增裁定和原创补充。

故事中写到“角色必然这样做”时，需要补充主持能够据以裁定的条件：人物为何行动、玩家能观察到什么、什么事件会改变局势、玩家作出其他选择时如何回应。忠实改编也要补齐原作缺失的行动依据与规则衔接；涉及改变核心内容的方案应符合已确认尺度。未获允许的核心改动先提出建议，不直接落实。

已有模组体验改进

先确认允许修改的范围，再阅读相关玩家资料、主持资料、字段、规则与开局。定位具体体验问题，例如目标不明、选择没有区别、主持缺少裁定依据、信息提前暴露或资源记录互相矛盾。说明问题发生的条件、现有行为和预期改善，再修改相关内容。

检查与所改机制相关的内容：调整线索可能影响路线，调整资源可能影响难度和结局。优先复用现有事实与状态。只修正局部问题时，无需重写整个模组或重新设计无关系统。

保持标识稳定，检查修改依赖

只调整展示文案时，优先修改文档 name、类型显示名或字段 label，保留文件路径、类型 ID、字段键和任务 ID。这些标识用于关联资料，不必随文案润色而改变。

确需重命名或删除时，按实际改动检查依赖：

• 文件路径与类型 ID：文档引用、字段 targets、公式中的 load()、正文链接、主持指令、开局和建卡来源，以及音色使用的文档标识；文档引用与音色匹配忽略格式扩展名，附件保留实际扩展名。
• 字段键或结构：所有文档原始数据、类型和文档公式、布局及字段组件、建卡写入目标，以及主持修改指令。
• 场景、任务、棋子等稳定 ID：相应配置、关联记录及重复执行的识别依据；显示名称变化不自动要求改变 ID。

搜索结构化配置与正文中的旧标识，逐项判断后修改，不做无法区分语义的全局替换。修改后核对真实计算结果与相关状态，而不只检查引用合法。例如把 hp 改成 health 后，遗漏的 $raw.hp ?? 0 仍可能合法，却把结果变为 0；检查方式见模组 CLI。已创建的冒险保留原有副本，本次修改由开发者手动在新冒险中验证，不要为完成重命名而顺带改写旧存档。

冒险结构与玩家选择

开场应说明角色为何参与、眼前能感知到什么，以及至少一个可以尝试的行动方向。区分玩家目标、主持知道的真相和系统结束条件；人物背景中的愿望不自动成为胜利条件。

按核心体验比较适合的结构，也可以组合使用：

结构	主要准备	需要推演的问题
章节或事件链	触发条件、转换条件、顺序与可选分支	未触发前一事件、提前行动或拒绝安排时如何回应？
调查网络	线索、获取方式、可推断结论与下一行动	关键线索错失、误读或提前取得后还能如何推进？
地穴或区域探索	地点联系、障碍、风险、资源与退路	改走路线、撤退、绕过敌人和重访地点会改变什么？
开放局势	人物动机、势力行动、时间压力与变化条件	玩家暂不介入时局势如何演变，介入又如何改变它？

重要选择应在信息、成本、风险、关系或后续局势上产生符合设计意图的区别。先明确玩家作决定时能够知道什么；有意制造未知风险时，应留下符合题材的可观察征兆。多条路线无需强行等价，也无需每个场景都设置分支。

对重要线索记录其所在位置或持有者、获取条件、实际揭露内容、支持的推断和可采取的下一步。调查型模组是否需要替代渠道由失败预期决定；若错失某条线索会阻断关键进展，说明这是刻意挑战还是应补救的设计缺口。

压力变化、信息获取、行动成本和阶段转折共同影响冒险节奏。明确哪些事件依赖玩家行动，哪些在满足时间或状态条件后发生；主持读到事件资料，不代表事件已经发生。预计时长作为设计目标，不能据资料篇幅声称已经验证。

可供主持执行的资料

重要地点和事件应能回答：进入或触发条件是什么、眼前可感知什么、有哪些可尝试行动、如何裁定、哪些状态会改变、变化后再访问会看到什么。按需要组织资料，不要求每份文档采用同一种格式。

人物资料提供动机、已知信息、能力与限制、态度和改变立场的条件。NPC 的建议与行动依据自身知识，玩家仍决定自己的行动；AI 队友也需要明确知识范围、参与动机和发言条件。

战斗、机关、追逐、谈判和环境危害要写出足以执行的判定数据或准确规则引用，包括触发范围、行动与退出条件、代价、奖励和可行的应对方式。难度结合人数、角色能力、遭遇频率和可恢复资源推演；单个敌人的数值不足以证明整场冒险平衡。

hostPrompt 负责导航与关键执行约定：开始或恢复时读取什么、何时读取场景规则、如何更新状态与结束冒险。详细事实和机制放在相应文档，通过准确引用读取，避免在多个地方维护整份规则和不同版本的真相。提示词不能赋予平台没有的工具或让文本规则自动执行。

类型顶层 description 只写简短用途，因为它会完整进入主持的常驻资料索引。不要在其中堆放裁定流程、字段维护约定或对象专属机制；这些内容放入可按需查阅的主持手册与对应资料，查阅路由统一放在 hostPrompt。精简现有类型介绍时，逐条确认移出的有效规则已有明确去处，合并重复内容，不因压缩上下文丢失规则。类型介绍没有硬长度限制，平台也不会自动截断；写法见类型介绍与主持索引。

让本局主持确实读得到规则

作者开发时能访问的资料，不一定在本局主持的读取范围内。仓库外的规则书、仓库根目录的说明、外部网页或 PDF 引用，不会自动成为主持在本局能读取的规则；不要假定主持工具可以浏览网页或解析任意附件。

关键裁定需要在 module/ 内提供主持能读取的执行摘要或规则文档，写清需要的判定参数、成本、结果和状态修改，并保留来源版本与章节定位。外部链接用于溯源，不作为唯一运行依赖，也不要求复制整本规则书。保存方式遵循模组结构，避免把普通说明文件误当成未声明类型的游戏文档。

hostPrompt 指向实际存在的入口、当前场景与相关规则；让主持在开始、恢复或遇到该机制时按需查阅，不把所有细节塞进提示词。推演时顺着这些引用检查文件是否包含执行所需内容，而非仅有“按原规则处理”的一句话。资料的读取范围与玩家可见范围分别设计，主持可读不等于玩家应该看见。

规则依据与平台能力

采用已有规则时，明确基础版本、实际来源、采用的勘误与自订规则，以及它们在本模组中的覆盖关系；不为所有模组规定同一优先级。规则出处应能定位到实际内容，不能用模型记忆、另一版规则或未核实的速查表冒充已确认依据。

不同来源冲突时先指出具体差异，依据本模组已有约定处理。关键规则缺失且无法核实时，优先用可用的同步提问工具确认；临时裁定或原创补充明确标为自订，并说明适用范围，不编造出处或悄悄改变改编尺度。已明确的规则选择无需重复询问。

如果设计需要某项平台能力，先核对对应版本的文档与实际 CLI；已有源码时可只读检查实现。确实不支持时，说明期望行为和现有能力的差距，提出写入模组规则的主持手动处理方案，或现有配置能够支持的方案，并说明影响。涉及核心体验变化时先确认，再修改模组；平台功能需求单独报告，不为完成模组自动扩展平台源码，不虚构字段或工具，也不靠删掉机制让配置通过校验。

规则、资源与状态

为机制设计字段前，按 字段建模与计算选择 选择原始状态、类型级计算、文档级覆盖、引用与揭露方式；说明选择依据。不要只因公式能够表达某个机制，就把需要主持更新的事实或事件改成计算字段。

对影响推进的重要机制，明确触发条件、行动前提、判定依据、成功与失败效果、成本、状态修改和终止条件。规则引用也要能找到当前机制所需的具体裁定。任何数值阈值和资源来源都应有清楚含义。

下面是一项原创机制的设计示例，字段名和值仅用于说明：

项目	约定
当前事实	角色携带的油灯剩余燃料为 20 分钟，初始未点燃
触发与成本	点燃期间，一次探索行动耗时 10 分钟，消耗同等燃料；叙述前说明耗时
修改与结果	主持保存行动耗时、燃料余量和点燃状态；耗尽时灭灯，下一行动按黑暗规则裁定
边界	有其他光源时按实际照明处理；重新点火不补充燃料，补充须有真实来源；燃料不足时明确熄灭的时点和影响

实际模组采用自身规则，不自动套用此例。由主持执行的消耗、资源补充与时间推进要写明规则约定，不假设平台提供计时器或自动规则引擎。

同一事实只保存一份原始状态，以它作为依据。地点状态、角色持有物的数量与余量、关系变化、发现记录和结局条件需要可追踪；展示派生值由公式计算。角色位置可以用角色上的地点引用或场景中的成员关系表达，按模组需要选择一份事实来源；需要反向名单时通过计算派生，平台不提供固定的场景成员结构。物品定义与角色持有状态区分处理，持有者消耗物品不应修改所有同类物品的定义。

对有持续影响的机制，在模组规则中说明改变哪些事实、何时视为完成，以及能否多次触发、每次触发的成本与奖励。涉及多份文档的交易、奖励等机制，明确状态归属与完成条件，见状态归属与结束结算。

资源尺度要对照预期行程与行动成本：初始资源能支持多少典型行动、在哪里补充、消耗后有哪些选择、是否可能迫使失败。挑战可以严苛；应检查后果是否符合预先选定的失败体验，而不是默认补发资源。

结局条件应能由实际状态判断，并区分目标完成、逃离、失败及可选奖励。逐项检查可选任务是否被误设为必需条件。在规则中要求主持先完成角色、资源和世界状态结算，最后明确调用 end_adventure 结束冒险；具体边界见自定义游戏状态。

玩家资料与展示

玩家开局资料说明扮演身份、已知关系、参与理由、基本行动方法及必要规则。角色的技能与装备应支持核心玩法；人数变化、无人选用的预设角色和迟到入场需要按设计范围考虑，不能把未选角色当作必然在场。

对关键秘密区分主持真相、玩家已经取得的证据与尚未得到的结论。首次观察、进一步调查和理解含义可以分别改变可见信息。揭露层级按模组需要设置，不强制为所有实体增加相同字段。

名称、正文、简介、图片、头像、引用摘要、开场和地图都要遵守信息揭露的安排。插画中出现的要素可能比文字揭露更早；决定何时展示，并检查是否提前暴露机关、人物身份或出口。当前共享展示规则的能力边界见计算字段，分队或角色秘密不能仅靠一条“不要透露”的提示实现。

详情、角色卡与列表优先展示当前行动需要的信息：可用资源、关键能力、状态效果、可查阅规则与已知线索。复杂建卡和自定义布局，应能帮助玩家作决定或减少操作，再按需要配置。

设计推演与交付

文件检查和 CLI 校验用于检查模组实现。对重要公式或状态机制，复用已有模组测试或实际计算结果接口检查；没有相应入口时完成校验和推演，明确未验证项，不搭建平台运行时或用自写模拟器代替平台验证，详见按风险检查实际结果。设计推演是在资料和状态逻辑层面检查过程，可以由创作者或编程助手完成。需要实际验证指定局面时，可通过 MCP 临时局预演驱动客户端已有 AI 队友与主持，记录真实裁定和状态；跳过的开局、完整路线、界面操作和声音仍需另行验收。

按任务范围选择代表性情况，用“起始状态 → 玩家行动或事件 → 判定与修改 → 可见信息及下一步”推演，并记录结论和仍未验证的假设：

• 从开场到第一次有效选择，再到典型路线与结局；仅修改局部机制时检查相关路线即可。
• 与所选失败原则有关的检定失败、线索错失、拒绝行动、资源耗尽或撤退。
• 重要事实改变后的重访、重复触发与上下文恢复，检查结算和奖励是否重复。
• 秘密揭露前后的玩家信息、分队或人数变化，以及各类已设计的结局。

推演时以保存的字段和值为依据，核对正文、主持指令和显示条件是否一致。格式合法，仍可能存在体验问题；推演成立，也不代表 AI 主持已经在实际会话中正确执行。难度与节奏还需要通过真实游玩来判断。

完成模组后，应说明关键设计取舍、改动范围、实际使用的 CLI 版本及结果、推演依据和结论，并提供本次改动的手动验收清单。清单写明操作或触发条件及预期结果，按规模选择项目，例如：

开发者操作	预期结果
用修改后的模组新建冒险，选择实际参与的角色并走完开场	正确入场，初始状态与资料一致，角色能知道下一步如何行动
揭露一项关键秘密，分别查看揭露前后的玩家资料	名称、文字、摘要与图片都按设计显示，尚未取得的信息保持隐藏
完成一次关键行动后恢复或重访	消耗与状态正确保存，已结算效果和奖励不重复
达成已配置的结局条件	先保存相关结算，再结束冒险，尾声与最终状态一致
使用本次新增的建卡或复杂布局	能完成预期操作，展示的信息支持实际行动

列出需要开发者验证的项目，区分推演结论和实际验收结果。委托编程助手执行 MCP 预演时，应附测试输入、步骤、实际结果与未验证项，普通创作请求不自动启动模型试玩；尚处于设计阶段时，交付设计摘要、可执行的冒险方案、推演结论和验收建议，不声称已经通过文件校验。