设计：自适应支线插入引擎

状态：已实现（2026-10-03），pnpm verify 包含主线与自适应支线验证。关联：docs/story-framework.md §6（路由规则）、 docs/script/adaptive-branches.md（支线剧本与三张总表）、ADR-0003（Jev 置信度自适应）。读者：实现此功能的工程 agent。

1. 目标

每章结束后用 Jev 对用户行为轨迹打 7 维 score；对置信度不足的维度，在下一章的固定挂点动态插入一段支线剧情，补充该维度的行为采样。插入必须：

玩家无感：支线作为剧情独立成立，出口与主线严丝合缝；
测量有效：支线选择点与主线选择点同等规格地落入事件流；
成本可控：每章至多插入 1 条；Jev 故障时不插入（降级，不阻断主线）。

2. 触发时序

chapterEnd（第 N 章结束）
  → 汇总本 session 全部事件为 state
  → 一次 Jev 调用：7 个维度 score（并行，输出免费）
  → 提取每维 confidence
  → 插入决策（见 §3）→ 产出第 N+1 章的"插入计划"
  → 第 N+1 章开始，引擎带着插入计划运行

打分与画像报告页共用同一套 state 构建逻辑（ReportPage.buildState 提取为 src/engine/scoring.ts，报告页和插入决策都调它）。章末打分失败（Jev 故障/无 key） → 本章不插入任何支线，主线照常（console.warn 记录）。

3. 插入决策（对照支线册表 2 实现为代码）

输入：7 维 confidence、本周目已触发支线记录、目标章可用挂点。

过滤：confidence < 0.6 的维度为候选；risk / mate_preference 无支线定义，跳过；
排序：按「维度权重 × 置信度缺口 × 已测稀缺度」取首—— 维度权重：attachment > values > conflict_style > emotional_stability > culture （见支线册 §0.5）；缺口 = 0.6 − confidence；稀缺度 = 该维度已被采样的选择点数越少越优先；
选皮：变体与挂点按章绑定（第 2 章＝变体 A／挂点 1，第 3 章＝变体 B／挂点 2），不跨章搬运（与支线册 §0「变体皮肤规则」一致——变体场景与该章主线进度耦合）。同维度重复低置信：第 2 章插 A、第 3 章插 B（强制换皮）；A、B 都用尽仍低置信 → 记录 evidence_insufficient 标记，不插入（交 Act 2）；
每章至多 1 条；每章只有一个挂点，本章已有插入则不再插入，顺延到下一章的挂点（用其对应变体），无挂点可用则不插入；
时长红线：插入后该章预估时长 ≤ 45 分钟（支线 5-8 分钟 + 主线 25-35 分钟）。

4. 数据模型

支线包：content/branches/{branchId}.json（如 b-att-a.json），结构：

{
  "id": "b-att-a",
  "dimension": "attachment",
  "anchor": { "chapter": "chapter2", "afterNode": "c2-d4f" },  // 挂点 1：§2-4 后
  "startNodeId": "cb-att-a-01",
  "nodes": [ /* 与章节 JSON 同 schema 的 StoryNode 数组 */ ],
  // 支线选择点 pointId 用 CB-XXX-Y-ZZ 规则（支线册表 1），维度标签照支线册
}

引擎改动：

StoryEngine 增加 insertions: BranchPack[]（本局生效的插入计划）；
节点索引 nodeIndex 在装载插入计划时合并支线节点；
挂点重定向：到达 anchor.afterNode 的 next 时，若该挂点有插入，跳支线 startNodeId；支线最后一个节点的 next 在 JSON 里写为特殊值 "$resume"，引擎解析为"回到挂点原 next"；
支线节点参与现有全部机制：条件渲染（flags）、进度持久化、追问流。

5. 事件与测量

支线选择点事件正常 append，pointId（如 CB-VAL-A-01）即变量取值来源；
支线 flags（cb_*）进现有 flags 系统（src/engine/flags.ts 补映射，消费方见支线册表 3——注意"回写只许面向未来场景"规则）；
插入决策本身落一个 kind: 'branch_inserted' 事件（branchId、维度、触发置信度），供画像层做路径标记（温简 weak 线的公平性问题同款思路）。

6. 状态与持久化

ProgressSnapshot 增加 activeBranchId?: string 与 insertions 摘要，刷新恢复时若正处于支线中，恢复到支线内断点；
replay() 清空插入计划（新周目重新打分重新决策）；
同一 session 已触发的支线不再重复触发（A→B 换皮由 §3.3 保证）。

7. 实施拆分（建议一棒完成）

src/engine/scoring.ts：7 维打分 + 置信度提取（从 ReportPage 抽出复用）；
src/engine/branching.ts：插入决策纯函数（§3 全部规则，可单测）；
引擎装载/挂点重定向/$resume 解析/进度快照扩展；
content/branches/：把支线册 10 条变体 JSON 化（文案照 docs/script/adaptive-branches.md，pointId/变量照表 3）；
scripts/verify.ts 新增断言：决策矩阵表驱动测试（7 种触发情形照表 2）、挂点重定向与 $resume 汇合、支线事件落库、重复触发抑制、 Jev 故障不插入、replay 清空计划。

8. 未决问题（实现时可自行裁决，报备即可）

挂点锚点的精确 nodeId 以 JSON 现状为准（afterNode 需在实现时对照 chapter2/3.json 落定，支线册的 §2-4 后/§3-2 前是剧本坐标）；
支线中的 narration 讲述点：本期支线册均为按钮式选择点，无 V 类点，若后续支线加讲述点，追问流直接复用现有机制，无新增设计。

9. 实现裁决与验证

挂点按剧情坐标落定：A 在 chapter2/c2-branch-anchor（C2-03 三条后续汇合后、观星台前），B 在 chapter3/c3-d1b（台基下、登台前）。原示例 c2-d4f 位于路线裁断前，不作挂点。
A/B 绑定章节，不跨挂点搬运。第三章首次补测某维度也使用 B；当前章槽已占用则不叠加，下一章重新打分决定。
优先级采用权重 5/4/3/2/1 × (0.6-confidence) × 1/(1+独立测点数)；choice/narration 为有效测点，追问与路由事件不重复计数。主线时长默认保守取 35 分钟，支线按上限 8 分钟估算。
文化兜底检查刚完成章的主线解谜是否已有事件，不检查目标章尚未发生的解谜，否则文化支线会永远无法触发。
支线册少量时序措辞做了衔接修正：官牙发生在安门内登台前；漏刻不预先引用尚未复原的星图；分药后的 D 路径同样遵循 wenjian_health=weak 留营规则。测量维度和变量枚举不变。
advance() 返回 Promise，调用方须 await；章末防重复提交，HTTP 请求 15 秒超时。无 key 的自动 Mock 不参与插入决策，显式注入 Mock 可用于测试。
快照保存支线 ID 摘要与活动支线；恢复先合并节点索引，再定位断点。路由事件先于快照落盘，恢复时可从本 session 事件补回计划。重玩清除索引与计划，不改旧事件。
共 17 个支线选择点（两问解谜各计一个测点）。计时点记录耗时和超时，解谜记录两问答案、提示档数、是否解出，选择事件保存实际条件渲染后的文案。风声音效、缝宽演出和阅读/改选遥测未实现；当前 UI 点选即提交，不伪造这些信号。
pnpm exec tsx scripts/build-adaptive-branches.ts 从定稿支线册重生成十个静态包；运行时不解析 Markdown。
scripts/verify-adaptive.ts 覆盖决策矩阵、全部选项与超时/跳过、温简双状态、逐节点恢复、五维三章 A→B、事件/flags、重复点击与刷新、无 key/无效评分/网络故障、replay 会话隔离，由 scripts/verify.ts 统一执行。

7.6 KiB Raw Permalink Blame History Unescape Escape