@cloud411716/fancy-webnovel 2.2.0 → 3.0.0

package/plugins/fancy-story-builder/scripts/v2/contracts.js

@@ -0,0 +1,493 @@
+/**
+ * v2/contracts.js —— 2.0 阶段契约（唯一文本源）
+ *
+ * 同一份文本用于：
+ *   - 生成阶段目录 README.md（项目内自包含）
+ *   - 生成 LLM 提示词（只指向项目内文件）
+ *   - bundle.json 的 checks 说明
+ *
+ * 禁止在这里写插件源码路径、node_modules、脚本文件名。
+ */
+export const STAGE_CONTRACT = {
+  '00-baseline': {
+    title: '输入基线',
+    purpose: '固化选题、参考与公式版本。后续阶段只读，不再重新解释选题。',
+    readOrder: ['input.json', 'references.json', 'formulas.json'],
+    outputs: ['input.json', 'references.json', 'formulas.json'],
+    sections: [
+      {
+        id: 'input',
+        title: 'input.json',
+        body: [
+          '必填：book_name、genre、positioning、target_chapters、target_words、core_conflict、reader_value、golden_finger、core_setting。',
+          '可选：hard_constraints（数组）、anti_tropes（数组）、one_line_pitch、selling_points。',
+          'target_chapters 与 target_words 必须是正整数；后续所有数量从它们推导。',
+          '这里只放输入，不写人物名、势力名、章节内容。',
+        ],
+      },
+      {
+        id: 'references',
+        title: 'references.json',
+        body: [
+          '记录对标作品、参考资料、来源文件与哈希。',
+          '没有参考时写空数组，不要省略文件。',
+        ],
+      },
+      {
+        id: 'formulas',
+        title: 'formulas.json',
+        body: [
+          '数量公式定义与版本，不是计算结果。',
+          '计算结果只看 10-scale/scale.json。',
+        ],
+      },
+    ],
+    checks: ['输入字段齐全', '目标章/字为正整数', '不包含人物、势力、剧情内容'],
+    forbidden: ['人物姓名', '势力名称', '章节剧情', '未经确认的固定数量'],
+  },
+  '10-scale': {
+    title: '数量',
+    purpose: '只回答“多少”：章、卷、幕、配额、节奏预算。不写人物、势力、地点、剧情。',
+    readOrder: ['_context/baseline.json', 'scale.json'],
+    outputs: ['scale.json', 'scale.md', '_context/baseline.json'],
+    sections: [
+      {
+        id: 'capacity',
+        title: 'capacity',
+        body: [
+          'target_chapters：来自 baseline.input.target_chapters。',
+          'target_words：来自 baseline.input.target_words。',
+          'avg_words_per_chapter = round(target_words / target_chapters)。',
+          'base_words_per_chapter：节奏公式的字数基准，默认 2000。',
+          'chapter_scale = base_words_per_chapter / avg_words_per_chapter。',
+        ],
+      },
+      {
+        id: 'structure',
+        title: 'structure',
+        body: [
+          'volume_count 等于 volumes 数组长度。',
+          '每卷 chapters 之和必须等于 target_chapters；chapter_start/chapter_end 连续覆盖 1..T。',
+          '每卷至少 1 幕；每卷 acts 的 chapters 之和必须等于本卷 chapters。',
+          'structure.acts 是全部卷幕的扁平表，act_id 唯一，volume_id 必须存在。',
+          'ratio 之和必须等于 1。',
+        ],
+      },
+      {
+        id: 'quotas',
+        title: 'quotas',
+        body: [
+          '人物：protagonist、core_supporting、volume_supporting、core_antagonist、volume_antagonist。',
+          '实体：factions、faction_relations、locations、items{core,branch,symbolic}、conflicts{core,phase,branch}。',
+          '节奏素材：foreshadows{small,medium,large}、climaxes{small,medium,large}、pleasures{small,medium,large}。',
+          '结构：endings、world_rules{core,information,social}、main_lines、branches、information_gaps。',
+          '关系：relations{character,faction,membership}。',
+          '所有配额必须是非负整数；下游会按这个数量严格核对。',
+        ],
+      },
+      {
+        id: 'distribution',
+        title: 'distribution',
+        body: [
+          '按卷拆分：每卷 chapters、卷级配角、卷级反派、阶段冲突、伏笔、高潮、爽点。',
+          'distribution 里的 chapters 必须等于对应卷的 chapters；所有卷都要有分布。',
+        ],
+      },
+      {
+        id: 'rhythm-budget',
+        title: 'rhythm_budget',
+        body: [
+          '钩子、揭示、反转、情绪峰值的最低值与目标值。',
+          'golden_three 记录黄金三章的特殊要求。',
+        ],
+      },
+      {
+        id: 'formulas',
+        title: 'formulas / derivations',
+        body: [
+          '每条公式都要有 value、range_low、range_high、formula。',
+          'range_low / range_high 是基础公式区间乘以题材 profile 倍率后的结果。',
+          'value 必须在调整后区间内；确实需要偏离时，在该公式条目写非空 deviation_reason。',
+          'LLM 只需写 `derivation_reasons` 说明偏离推荐值的原因；完整 formulas / derivations 由插件补齐。',
+          'formula_version 记录公式版本，genre_profile 记录选中的题材 profile。',
+        ],
+      },
+      {
+        id: 'forbidden',
+        title: '禁止事项',
+        body: [
+          '禁止出现人物姓名、势力名称、地点名称、道具名称、剧情句、章节标题。',
+          '本阶段不生成任何 wiki 页面；数字不是页面。',
+        ],
+      },
+    ],
+    checks: [
+      '各卷章数之和 = target_chapters',
+      '各卷幕章数之和 = 本卷章数',
+      'ratio 之和 = 1',
+      '所有配额是非负整数',
+      '每条公式值在合法区间内或有 deviation_reason',
+      '没有人物/势力/地点/剧情内容',
+    ],
+    forbidden: ['人物姓名', '势力名称', '地点名称', '道具名称', '剧情句', '章节标题'],
+  },
+  '20-macro': {
+    title: '宏观',
+    purpose: '先定世界、故事、卷纲、幕纲、主支线、结局、情绪曲线和角色功能位。',
+    readOrder: ['_context/baseline.json', '_context/scale.json', 'world.json', 'story.json', 'volumes.json', 'lines.json', 'endings.json', 'emotion.json', 'roles.json'],
+    outputs: ['world.json', 'story.json', 'volumes.json', 'lines.json', 'endings.json', 'emotion.json', 'roles.json'],
+    sections: [
+      {
+        id: 'world',
+        title: 'world.json',
+        body: [
+          'premise、theme、tone 必填。',
+          'world_rules 每条要有 id、name、content、scope、cost、impact、category。',
+          'category 只能是：核心 / 信息 / 社会。三类数量必须等于 scale.quotas.world_rules。',
+          '规则要能直接约束人物行为，不能只是氛围形容词。',
+        ],
+      },
+      {
+        id: 'story',
+        title: 'story.json',
+        body: [
+          'core_question：全书要回答的一个问题。',
+          'core_conflict：谁与谁为了什么对抗。',
+          'structure.acts 必须覆盖 scale 的每一幕，每幕写 goal、turn、end_state。',
+          'structure.climax / resolution 写全书高潮与收束方向。',
+        ],
+      },
+      {
+        id: 'volumes',
+        title: 'volumes.json',
+        body: [
+          '卷数量、卷 ID、章节区间必须与 scale 完全一致。',
+          '每卷写 title、goal、core_conflict、emotional_arc、ending_hook。',
+          '每卷 acts 数量、act_id、章节区间必须与 scale 完全一致；每幕写 goal、climax。',
+        ],
+      },
+      {
+        id: 'lines',
+        title: 'lines.json',
+        body: [
+          'main_line：唯一主线，id 形如 M001；nodes 至少覆盖每一卷，节点写 id、volume、act、goal、turn。',
+          'branches：数量等于 scale.quotas.branches；每条写 id、name、goal、start、turning、resolution、interweaves。',
+          'start/turning/resolution 使用 V001/A001 形式；interweaves 必须引用已有主线节点。',
+        ],
+      },
+      {
+        id: 'endings',
+        title: 'endings.json',
+        body: [
+          '结局数量等于 scale.quotas.endings。',
+          '必须恰好 1 个 level=全书级 的结局。',
+          '每个结局写 id、level、type、direction、required_foreshadow_recovery。',
+          'required_foreshadow_recovery 用 FS001 形式；此时伏笔实体还没生成，只做格式校验。',
+        ],
+      },
+      {
+        id: 'emotion',
+        title: 'emotion.json',
+        body: [
+          'volumes 数组必须覆盖每一卷。',
+          '每卷写 volume_id、arc（情绪走向）、peaks（峰值位置/强度）。',
+        ],
+      },
+      {
+        id: 'roles',
+        title: 'roles.json',
+        body: [
+          '宏观阶段只写角色功能位，不写姓名。',
+          'role_id 形如 ROLE-PROTAGONIST；function 用：主角 / 核心配角 / 卷级配角 / 核心反派 / 卷级反派。',
+          '每个功能位写 role_id、function、arc_question、macro_goal。',
+          '功能位数量必须与 scale.quotas.characters 五类配额一一对应；30-cast 会严格核对这些槽位是否被填满。',
+        ],
+      },
+      {
+        id: 'forbidden',
+        title: '禁止事项',
+        body: [
+          '不写具体人物姓名、势力名称、地点名称、道具名称。',
+          '不写章节细纲；章节落点留给 40-rhythm。',
+          '不引用尚未生成的实体 ID（伏笔回收要求除外，只允许 FSxxx 格式）。',
+        ],
+      },
+    ],
+    checks: [
+      '卷/幕数量与 scale 一致，章节区间连续',
+      '主线节点覆盖所有卷',
+      '支线数量 = scale.quotas.branches',
+      '结局数量 = scale.quotas.endings，且恰好 1 个全书级',
+      '角色功能位与人物配额一一对应',
+      '世界规则三类数量与配额一致',
+      '没有具体人名、势力名、地点名',
+    ],
+    forbidden: ['具体人物姓名', '势力名称', '地点名称', '道具名称', '章节细纲'],
+  },
+  '30-cast': {
+    title: '实体',
+    purpose: '把宏观功能位落成具体人物，并设计势力、地点、道具、冲突、伏笔、高潮、爽点、关系、信息差。',
+    readOrder: ['_context/baseline.json', '_context/scale.json', '_context/macro.json', 'characters.json', 'factions.json', 'locations.json', 'items.json', 'conflicts.json', 'foreshadows.json', 'climaxes.json', 'payoffs.json', 'relations.json', 'information.json'],
+    outputs: ['characters.json', 'factions.json', 'locations.json', 'items.json', 'conflicts.json', 'foreshadows.json', 'climaxes.json', 'payoffs.json', 'relations.json', 'information.json'],
+    sections: [
+      {
+        id: 'characters',
+        title: 'characters.json',
+        body: [
+          '每个人物写 id、role_slot、name、type、faction、description、goal、flaw、golden_finger、information_state、arc、voice、traits、exit。',
+          'type 只能是：主角 / 贯穿级核心配角 / 卷级重要配角 / 贯穿级核心反派 / 卷级反派；数量严格等于 scale.quotas.characters。',
+          'role_slot 必须填宏观 roles.json 的功能位；每个功能位恰好被 1 个角色占用。',
+          'goal 至少有 short_term / medium_term / long_term；arc.stages 至少 1 个；voice 必须有 catchphrase 与 rhythm。',
+        ],
+      },
+      {
+        id: 'factions',
+        title: 'factions.json',
+        body: ['每个势力写 id、name、type、description、goal、resources、territory。数量等于 scale.quotas.factions。'],
+      },
+      {
+        id: 'locations',
+        title: 'locations.json',
+        body: ['每个地点写 id、name、type、description、narrative_function。数量等于 scale.quotas.locations。'],
+      },
+      {
+        id: 'items',
+        title: 'items.json',
+        body: ['每个道具写 id、name、category、description、function。category 只能是 core / branch / symbolic，数量分别等于 scale.quotas.items。'],
+      },
+      {
+        id: 'conflicts',
+        title: 'conflicts.json',
+        body: [
+          '每个冲突写 id、name、type、description、core_goal、stakes、escalation_path、resolution_plan、participants。',
+          'type 只能是 core / phase / branch，数量分别等于 scale.quotas.conflicts。',
+          'escalation_path 至少 2 个节点，每个节点写 node_type、description。',
+          'participants 只能引用已存在的人物/势力/地点。',
+        ],
+      },
+      {
+        id: 'foreshadows',
+        title: 'foreshadows.json',
+        body: ['每个伏笔写 id、name、type、setup、clues、payoff_target、recovery_requirement。type 只能是 小/中/大，数量严格等于配额。可选 `scope`：book / volume / arc / chapter，用于区分全书级、卷级、章级回收窗口。'],
+      },
+      {
+        id: 'climaxes',
+        title: 'climaxes.json',
+        body: ['每个高潮写 id、name、type、description、payoff、participants。type 只能是 小/中/大，数量严格等于配额。'],
+      },
+      {
+        id: 'payoffs',
+        title: 'payoffs.json',
+        body: [
+          '每个爽点写 id、name、type、scale、setup、payoff、emotional_effect、required_setup。',
+          'scale 只能是 small / medium / large，数量严格等于 scale.quotas.pleasures。',
+          'required_setup 只能引用伏笔/冲突/高潮/其它爽点，或冲突升级节点 X001-escalation-1。',
+        ],
+      },
+      {
+        id: 'relations',
+        title: 'relations.json',
+        body: [
+          'character_relations：写 id、from、to、kind、initial_state、changes。两端必须是人物；不能指向自己。changes 可以为空（关系保持静态）；写了变化节点才校验 stage/trigger/description。',
+          'faction_relations：写 id、from、to、kind、initial_state、changes。两端必须是势力。changes 可以为空；写了变化节点才校验。',
+          'memberships：写 id、character、faction、position、kind。',
+          '三个数组的长度分别等于 scale.quotas.relations。',
+          '**关系类型 kind 是自由文本，不设枚举**：可以写“互相利用”“表面师徒、实际监视”“旧友但立场对立”等。',
+          '结构校验只检查两端存在、不能自指；变化节点如果写了才校验字段完整。关系是否前后矛盾、是否符合人物目标与冲突，交给 llm_wiki 的语义检查。',
+          '每条人物关系、势力关系、成员关系都会各自生成一个独立 wiki 页面，页面里带“语义验证点”，供 llm_wiki 逐条做语义校验。',
+        ],
+      },
+      {
+        id: 'information',
+        title: 'information.json',
+        body: [
+          '每个信息差写 id、conflict、info_name、who_knows、who_does_not_know、initial_knowledge、resolution_method、writing_ban。',
+          'initial_knowledge 写开篇时每个相关人物知道什么：character、state（unknown/partial/full/false）、knowledge、how（none/witnessed/told/inferred/document/rumor/experience/other）、source_character、scene、evidence。',
+          'conflict 必须是已存在的冲突；who_knows / who_does_not_know / initial_knowledge 只能引用已存在人物。',
+          '数量等于 scale.quotas.information_gaps。',
+        ],
+      },
+      {
+        id: 'forbidden',
+        title: '禁止事项',
+        body: [
+          '禁止出现 chapter、chapter_id、ch 等章节字段；章节落点只能在 40-rhythm 分配。',
+          '禁止引用不存在的实体 ID。',
+          '禁止物理删除宏观功能位；角色合并用 status=deprecated + merged_into。',
+        ],
+      },
+    ],
+    checks: [
+      '五类人物数量与配额一致',
+      '每个宏观 role_slot 恰好被 1 个角色填充',
+      '势力/地点/道具/冲突/伏笔/高潮/爽点数量与配额一致',
+      '关系数量与配额一致，两端存在；kind 不设枚举，只做结构校验',
+      '每条关系生成独立 wiki 页面，交由语义检查判断是否自洽',
+      '信息差数量与配额一致，冲突和人物存在',
+      'initial_knowledge 引用存在人物，状态和获知方式合法',
+      '没有章节字段',
+    ],
+    forbidden: ['章节号', '不存在的实体 ID', '删除宏观功能位'],
+  },
+  '40-rhythm': {
+    title: '节奏与细纲',
+    purpose: '把宏观和实体落到每一章：谁、何时、何地、为什么、怎么写；再为每章生成可独立写作的细纲。',
+    readOrder: ['_context/baseline.json', '_context/scale.json', '_context/macro.json', '_context/cast.json', 'chapter_map.json', 'outlines/<chapter_id>.json'],
+    outputs: ['chapter_map.json', 'outlines/<chapter_id>.json', 'index.json'],
+    sections: [
+      {
+        id: 'chapter-map',
+        title: 'chapter_map.json',
+        body: [
+          'chapters 必须覆盖 1..T，每章有稳定 chapter_id 和可调整 display_no。',
+          '每章写 title、volume、act、pov、cast、locations、time、why、how、foreshadow_actions、payoff_actions、information_gaps、knowledge_events、emotion、hook、word_target。',
+          'knowledge_events 记录本章角色知识变化：subject_type（information/foreshadow）、subject_id、character、change（learns/partially_learns/confirms/corrects/forgets/misinforms）、coverage（unknown/partial/full/false）、knowledge（具体知道什么）、how（witnessed/told/inferred/document/rumor/experience/other）、source_character、scene、evidence。',
+          'ending_actions 可选；每个 endings.json 里的结局节点至少要在对应卷末或全书末的章节落一次。',
+          'why 里写 main_line_nodes、branch_nodes、conflict、theme、stakes。',
+          'how 里写 function_main、function_aux、turn、ending_hook。',
+          'display_no 必须连续；volume/act 必须与 scale 的章节区间一致。',
+        ],
+      },
+      {
+        id: 'outline',
+        title: 'outlines/<chapter_id>.json',
+        body: [
+          '一章一个文件，文件名使用 chapter_id。',
+          'chapter 里写 chapter_id、number、title、volume、act、word_target、pov、time、locations、cast、why、how、continuity、coverage、knowledge_events。',
+          'pov 写 id、name、entry_state、exit_state；cast 写每个人的 id、name、role_in_chapter、entry、exit、knowledge。',
+          'knowledge_events 与章节地图同结构；cast[].knowledge 写本章结束时该角色知道什么（subject_type、subject_id、state、coverage、knowledge、how、scene、evidence），必须和章节地图的知识时间线一致。',
+          'how.scenes 至少 1 个；每个场景必须有 goal、obstacle、turn、outcome。',
+          'must_write / must_not_write 必须非空；ending 必须写 type、text、hook。',
+          'coverage 必须覆盖本章的主线节点、支线、冲突、伏笔、爽点、信息差。',
+          'continuity 必须说明与上一章/下一章的衔接（首章 from_prev 可为 null，末章 to_next 可为 null）。',
+        ],
+      },
+      {
+        id: 'coverage',
+        title: '覆盖矩阵',
+        body: [
+          '所有主线节点、支线、冲突、伏笔、爽点、信息差都必须至少有一个章节落点。',
+          '伏笔必须先埋后收；爽点必须先铺垫后兑现。',
+          '每章至少 1 个钩子；黄金三章建议强钩子。',
+        ],
+      },
+      {
+        id: 'foreshadow-order',
+        title: '伏笔顺序',
+        body: ['foreshadow_actions.action 用 埋设/回收/推进/强化；同一伏笔第一次回收不能早于第一次埋设。'],
+      },
+      {
+        id: 'forbidden',
+        title: '禁止事项',
+        body: [
+          '禁止细纲缺失或只写一句话。',
+          '禁止引用不存在的实体、冲突、伏笔、爽点、信息差。',
+          '禁止让本章出场人物/地点与章节地图不一致。',
+          '禁止把全书角色都塞进单章 cast。',
+        ],
+      },
+    ],
+    checks: [
+      '章节地图覆盖全部章节',
+      '卷/幕/章节区间与 scale 一致',
+      '主线/支线/冲突/伏笔/爽点/信息差都有落点',
+      '伏笔先埋后收',
+      '每章有 5W、硬约束、钩子',
+      '每章细纲自包含，cast/locations/coverage 与地图一致',
+      '角色知识事件按章节回放不矛盾：已经知道后不能重新写成不知道',
+    ],
+    forbidden: ['缺章', '缺细纲', '伏笔先收后埋', '细纲引用不存在的实体'],
+  },
+  '50-writing': {
+    title: '正文',
+    purpose: '只按单章细纲写正文，不重新设计剧情。',
+    readOrder: ['_context/scale.json', '_context/macro.json', '_context/cast.json', 'outlines/<chapter_id>.json', 'ledger.json'],
+    outputs: ['chapters/第001章.md', 'ledger.json'],
+    sections: [
+      {
+        id: 'writing',
+        title: '正文规则',
+        body: [
+          '每章第一行写 # 第N章 标题，N 与 display_no 一致。',
+          '必须覆盖细纲 must_write；绝对不能违反 must_not_write。',
+          '结尾必须按细纲 ending.type / text / hook 收束。',
+          '不要改上游设定；细纲缺信息时返回 OUTLINE_INCOMPLETE，不要自己发明。',
+        ],
+      },
+      {
+        id: 'ledger',
+        title: 'ledger.json',
+        body: [
+          '每章登记 ch、chapter_id、title、pov、time、locations、cast、knowledge_changes、foreshadow_status、information_status、ending_hook、word_count。',
+          'knowledge_changes 写结构化知识变化：subject_type、subject_id、character、from、to、coverage、knowledge、how、source_character、scene、evidence；重写时替换同章旧条目。',
+          '重写某章时替换同章旧条目，不要留两条。',
+        ],
+      },
+      {
+        id: 'forbidden',
+        title: '禁止事项',
+        body: ['禁止改人物名/势力名/伏笔落点', '禁止跳过细纲硬约束', '禁止自动改上游 JSON'],
+      },
+    ],
+    checks: ['章文件齐全', '标题与 display_no 一致', '正文非空且达到字数下限', 'ledger 有对应条目', 'ledger 知识变化与章节地图一致', 'must_write 覆盖、must_not_write 未违反'],
+    forbidden: ['改上游设定', '跳过细纲', '自动改上游 JSON'],
+  },
+  '60-deslop': {
+    title: '去味',
+    purpose: '只改文风，不改结构、情节、信息差和章尾钩子。',
+    readOrder: ['_context/../50-writing/ledger.json', 'chapters/第001章.md'],
+    outputs: ['reports/', 'revisions/'],
+    sections: [
+      {
+        id: 'deslop',
+        title: '去味规则',
+        body: ['不得修改 must_write / must_not_write。', '不得改变核心情节走向、关键事件、伏笔、信息差状态、章尾钩子。', '改动比例超过 35% 自动回滚。'],
+      },
+    ],
+    checks: ['结构与硬约束不变', '改动比例在阈值内', 'AI 腔检测下降'],
+    forbidden: ['改剧情', '改人物设定', '改章尾钩子'],
+  },
+};
+
+export function contractFor(stageId) {
+  return STAGE_CONTRACT[stageId] || null;
+}
+
+export function renderContractMarkdown(stageId) {
+  const c = contractFor(stageId);
+  if (!c) return '';
+  const lines = [];
+  lines.push('# ' + stageId + '：' + c.title);
+  lines.push('');
+  lines.push('> 本文件由插件生成，是这个阶段目录的自包含契约。');
+  lines.push('');
+  lines.push('## 目标');
+  lines.push('');
+  lines.push(c.purpose);
+  lines.push('');
+  lines.push('## 阅读顺序');
+  lines.push('');
+  for (const f of c.readOrder) lines.push('- `' + f + '`');
+  lines.push('');
+  for (const section of c.sections) {
+    lines.push('## ' + section.title);
+    lines.push('');
+    for (const para of section.body) lines.push(para);
+    lines.push('');
+  }
+  lines.push('## 阶段校验');
+  lines.push('');
+  for (const check of c.checks) lines.push('- ' + check);
+  lines.push('');
+  lines.push('## 禁止事项');
+  lines.push('');
+  for (const item of c.forbidden) lines.push('- ' + item);
+  lines.push('');
+  lines.push('## 自包含');
+  lines.push('');
+  lines.push('本目录的 `_context/` 是上游只读快照。把整个目录交给另一个模型时，它不需要访问项目其它目录，也不需要读取插件源码。');
+  lines.push('');
+  lines.push('错误提示只指向本目录的 README、`_context/` 和阶段 JSON；如果提示里出现插件源码路径，请直接报告为工具错误。');
+  lines.push('');
+  return lines.join('\n');
+}