序章与开局

序章与开局方案写在 module.toml 或 module.json；角色自建流程写在对应类型定义中，见阶段式建卡。先完成最小模组，再按下面的规则扩展。

区分序章、建卡与正式开场

预设角色适合固定关系、入场速度重要或能力需要事先配合剧情的模组。如果选择身份和能力本身就是模组体验的一部分，则适合提供自建角色；也可同时支持，两类角色都要满足字段、资源和剧情入场要求。不能只设置 allowCreate: true 而省略工作台，也不能禁止自建却没有可用预设。

开局背景写在方案简介和开场叙述中。初始位置等玩法事实保存在模组自定义文档；不同方案需要不同初值时，在 opening.instructions 中要求主持读取并保存对应字段，见自定义游戏状态。预写开场中的事件不自动更新游戏状态；开场中已经发生的事实应与保存值一致。人物专属开场和 AI 队友指令也要检查知识范围，不能让某个未选择的角色成为故事成立的隐含前提。

配置开局方案

以下是一个开局方案的完整片段。沿用最小模组时，先复制阿青的角色文档为 character/林舟.toml，将其中的 name 改成“林舟”，保留有效的字段值。

在 module.toml 中保留顶层的 name、description，用下面的内容替换原来的整个 [[gameStarts]] 方案及其子表。这里仍使用 id = "river"，直接追加会造成 ID 重复。已有多个方案时，只替换要修改的那个方案；新增方案须使用不同 ID。

[[gameStarts]]
id = "river"
name = "河岸寻人"
description = "从渡口出发，寻找失踪的船夫。"
characterTypeIds = ["character"]
playablePaths = ["character/阿青", "character/林舟"]
allowCreate = false

[gameStarts.aiCompanions]
"character/林舟" = "扮演谨慎的林舟。讨论计划时提醒同伴留意水面；先声明行动意图，等待主持裁定。"

[gameStarts.opening]
mode = "scripted"
instructions = ""

[[gameStarts.opening.beats]]
text = "渡口的雾散了，船夫仍没有回来。"

[[gameStarts.opening.beats]]
text = '''
<message npc path="character/林舟" name="林舟">
我们沿着河岸找找吧。
</message>
'''

gameStarts 支持 1–30 个方案。路径从模组根目录出发，通常带类型名并省略文件扩展名；格式规则见文档类型与字段。同一文档身份不能重复配置 AI 队友。未写扮演指令的角色只能给真人选择。

只有一个开局时，应用直接采用该方案；多个开局时先展示简介，再由玩家选择。首次确认角色后，开局方案锁定。锁定前切换方案会清除受影响的未确认建卡进度。

角色确认后，如果仍有未占用且支持 AI 扮演的角色，首次确认角色的玩家选择添加同伴或独自开始；组队完成后才正式开场。真人和 AI 共用角色占用规则。后续队友设置与互动见AI 队友。

开发者手动验收：完成后新建冒险，选择阿青并确认，应出现添加 AI 队友的提示；选择林舟作为队友后，再看到两条开场消息。

预写开场与专属开场

mode = "scripted" 必须提供非空通用 beats，最多 100 条。每条包含 1–10000 字符的 text。正文与 AI 回复使用相同的说话人标签，每个分段是一条独立消息；没有标签的正文作为主持旁白，空行只分段落。

opening.overrides 可用预设角色路径作为键，提供该角色的专属 beats。键须属于 playablePaths，每份专属版本包含 1–100 条；自建角色使用通用版本。例如，在上例之后追加：

[[gameStarts.opening.overrides."character/阿青"]]
text = "你认出岸边的绳结，那是船夫常用的打法。"

旁白与 NPC 台词

选角前序章的介绍正文、开局方案简介和选角后的预写开场都支持下面的格式；AI 开场及后续主持回复也使用同一协议：

<message narrator>
你推开酒馆的大门，雨水顺着衣角滴落。
</message>
<message npc path="character/酒馆老板" name="陌生男人">
门关上，外面冷。
</message>
<message narrator>
他放下手里的抹布。
</message>
<message narrator>
你们打算怎么做？
</message>

标签独占一行。path 必须指向模组内现有的角色文档，保留类型目录、分组路径和文档名称；可省略 .json/.toml/.md 格式扩展名。不要使用绝对路径或 ..。name 是可选的公开称呼，省略时显示玩家可见资料中的名称；资料不可见或无法关联时显示 NPC 占位符。路径用于关联身份，不作为台词展示，头像和资料入口仍受玩家可见性限制。

同一 NPC 的不同称呼不会改变其身份。NPC、AI 队友和预写台词都按角色文档路径匹配模组音色。示例角色需先创建相应文档。

预写内容按分段顺序播完，问句本身不会创建中途选择或暂停步骤。需要玩家在序章中选择时使用 preludeFlow 的问答节点；正式开场的行动邀请放在最后。

AI 开场与初始化

使用 AI 开场时，用下面的片段替换该方案的整个 opening 配置，连同已有的 beats 与 overrides 子表一并移除：

[gameStarts.opening]
mode = "ai"
prompt = "从河岸清晨开始，结合已经确认的小队介绍渡口的异常，最后询问玩家下一步行动。"
instructions = "先查阅世界状态和已确认角色，按规则核对初始资源；不要重复给已经拥有的装备。"

prompt 在 AI 模式下必填，最长 10000 字符。instructions 是可选的一次性初始化指令，最长 10000 字符，可用于检查和更新角色或世界状态，不会自动加入后续每轮主持提示。

预写模式也支持 instructions：先完成初始化，再发布 beats。有初始化指令时需要配置模型；没有初始化指令的纯预写开场不需要模型。AI 模式把初始化与叙事放在同一个主持回合中。

位置、参与者、资源等状态由模组定义，平台不会自动创建场景或安排角色入场。需要初始化时，应在 instructions 中说明状态字段、前提和已完成步骤的识别方式，见自定义游戏状态。停止或失败不会撤销已经写入的游戏数据，作者编写 instructions 时应注明资源授予的前提，避免对已有资源再次授予。

分支序章

preludeFlow.steps 位于模组元配置顶层，最多 100 步，在选开局和角色之前执行。序章答案用于序章流程，不直接写入角色字段；需要写入角色卡的回答应配置在建卡任务中。

下面只展示顶层 preludeFlow 属性，不是完整的 module.json 文件。使用 JSON 元配置时，把它合并进现有文件，保留 name、description 和 gameStarts；已用 TOML 时，将同一结构转换为 TOML，或先把整份元配置转换为 JSON，不能同时保留两份元配置。

{
  "preludeFlow": {
    "steps": [
      {
        "id": "welcome",
        "type": "introduction",
        "title": "渡口",
        "body": "天刚亮，你来到渡口。"
      },
      {
        "id": "route",
        "type": "choice",
        "title": "你先观察哪里？",
        "options": [
          { "id": "bank", "label": "河岸", "value": "河岸", "next": "bank" },
          { "id": "pier", "label": "栈桥", "value": "栈桥", "next": "pier" }
        ]
      },
      {
        "id": "bank",
        "type": "introduction",
        "title": "河岸",
        "body": "泥里留着两串脚印。",
        "next": "$end"
      },
      {
        "id": "pier",
        "type": "introduction",
        "title": "栈桥",
        "body": "木桩上系着半截绳子。",
        "next": "$end"
      }
    ]
  }
}

开发者手动新建冒险后，应先看到“天刚亮”的介绍和观察地点的选择。选择河岸只出现脚印描述，选择栈桥只出现绳子描述，然后进入选角。

每步需要唯一 id 和 1–120 字符的 title；body 最长 10000 字符，required 默认 true。next 默认前往数组中的下一步，$end 结束序章，只能跳转到后续存在的步骤。单选优先采用选项的 next，再采用步骤的 next；多选不按单个选项分支。

options 中每项需要唯一 id、非空 label 和不重复的 value。也可以用 optionTypeId 从某类文档生成选项，保存不带扩展名的文档标识；optionRoutes 以文档路径为键指定单选分支。来源类型必须有可用文档，分支引用必须存在。

检查完整流程

修改配置后，用CLI检查引用和流程，再由开发者手动新建冒险，走完序章分支、开局选择、预设选角或自建、组队和开场。已有冒险继续使用自己的模组副本，可同步资料更新，但不会重播已完成的开场。当前选角和建卡属于开局流程，确认角色后不能通过主持工具重新进入选角或创建替补角色；想换身份从头体验时，新建冒险并重新选角或建卡。