novel-writer-cli 0.3.0 → 0.5.0

package/dist/volume-commit.js

@@ -1,11 +1,13 @@
-import { rename } from "node:fs/promises";
+import { copyFile, readdir, rename } from "node:fs/promises";
 import { join } from "node:path";
 import { readCheckpoint, writeCheckpoint } from "./checkpoint.js";
 import { NovelCliError } from "./errors.js";
-import { ensureDir, pathExists, removePath } from "./fs-utils.js";
+import { ensureDir, pathExists, readJsonFile, readTextFile, removePath, writeJsonFile, writeTextFile } from "./fs-utils.js";
 import { withWriteLock } from "./lock.js";
+import { QUICKSTART_MINI_PLANNING_RANGE, quickstartMiniPlanningChapters, startsWithQuickstartMiniPlanningSeedSequence } from "./quickstart-mini-planning.js";
+import { isPlainObject } from "./type-guards.js";
 import { validateStep } from "./validate.js";
-import { volumeFinalRelPaths, volumeStagingRelPaths } from "./volume-planning.js";
+import { hasQuickstartMiniPlanningSeedBase, volumeFinalRelPaths, volumeStagingRelPaths } from "./volume-planning.js";
 async function doRenameDir(rootDir, fromRel, toRel) {
     const fromAbs = join(rootDir, fromRel);
     const toAbs = join(rootDir, toRel);
@@ -42,6 +44,264 @@ function requireCheckpointReady(checkpoint, volume) {
         throw new NovelCliError(`Cannot commit volume plan unless volume_pipeline_stage=commit (got ${String(checkpoint.volume_pipeline_stage ?? "null")}). Advance volume steps first.`, 2);
     }
 }
+function uniqueStrings(values) {
+    const out = [];
+    const seen = new Set();
+    for (const value of values) {
+        if (typeof value !== "string")
+            continue;
+        const trimmed = value.trim();
+        if (trimmed.length === 0 || seen.has(trimmed))
+            continue;
+        seen.add(trimmed);
+        out.push(trimmed);
+    }
+    return out;
+}
+function stableValueKey(value) {
+    try {
+        return JSON.stringify(value) ?? "undefined";
+    }
+    catch {
+        return String(value);
+    }
+}
+function uniqueValues(values) {
+    const out = [];
+    const seen = new Set();
+    for (const value of values) {
+        const key = stableValueKey(value);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(value);
+    }
+    return out;
+}
+function parseOutline(text) {
+    const lines = text.split(/\r?\n/u);
+    const chapterHeadingRe = /^###\s*第\s*(\d+)\s*章/u;
+    const headings = [];
+    for (let index = 0; index < lines.length; index++) {
+        const match = chapterHeadingRe.exec(lines[index] ?? "");
+        if (!match)
+            continue;
+        const chapter = Number.parseInt(match[1] ?? "", 10);
+        if (!Number.isInteger(chapter) || chapter < 1)
+            continue;
+        headings.push({ chapter, startLine: index, endLine: lines.length });
+    }
+    if (headings.length === 0) {
+        return { header: text.trimEnd(), blocks: new Map() };
+    }
+    for (let index = 0; index < headings.length; index++) {
+        const current = headings[index];
+        const next = headings[index + 1];
+        current.endLine = next ? next.startLine : lines.length;
+    }
+    const blocks = new Map();
+    for (const heading of headings) {
+        if (blocks.has(heading.chapter)) {
+            throw new NovelCliError(`Invalid outline during merge: duplicate chapter block for chapter ${heading.chapter}.`, 2);
+        }
+        blocks.set(heading.chapter, lines.slice(heading.startLine, heading.endLine).join("\n").trim());
+    }
+    return {
+        header: lines.slice(0, headings[0].startLine).join("\n").trimEnd(),
+        blocks
+    };
+}
+function mergeSchedule(existingRaw, incomingRaw) {
+    if (!isPlainObject(existingRaw) || !isPlainObject(incomingRaw))
+        return incomingRaw;
+    const existing = existingRaw;
+    const incoming = incomingRaw;
+    const merged = { ...existing, ...incoming };
+    merged.active_storylines = uniqueStrings([
+        ...(Array.isArray(existing.active_storylines) ? existing.active_storylines : []),
+        ...(Array.isArray(incoming.active_storylines) ? incoming.active_storylines : [])
+    ]);
+    if (Array.isArray(existing.convergence_events) || Array.isArray(incoming.convergence_events)) {
+        merged.convergence_events = uniqueValues([
+            ...(Array.isArray(existing.convergence_events) ? existing.convergence_events : []),
+            ...(Array.isArray(incoming.convergence_events) ? incoming.convergence_events : [])
+        ]);
+    }
+    const existingPattern = existing.interleaving_pattern;
+    const incomingPattern = incoming.interleaving_pattern;
+    if (Array.isArray(existingPattern) || Array.isArray(incomingPattern)) {
+        merged.interleaving_pattern = uniqueValues([
+            ...(Array.isArray(existingPattern) ? existingPattern : []),
+            ...(Array.isArray(incomingPattern) ? incomingPattern : [])
+        ]);
+    }
+    else if (isPlainObject(existingPattern) && isPlainObject(incomingPattern)) {
+        merged.interleaving_pattern = { ...existingPattern, ...incomingPattern };
+    }
+    return merged;
+}
+function mergeForeshadowing(existingRaw, incomingRaw) {
+    if (!isPlainObject(existingRaw) || !isPlainObject(incomingRaw))
+        return incomingRaw;
+    const existing = existingRaw;
+    const incoming = incomingRaw;
+    const merged = { ...existing, ...incoming };
+    const items = new Map();
+    const appendItem = (item) => {
+        if (!isPlainObject(item))
+            return;
+        const record = item;
+        const id = typeof record.id === "string" ? record.id.trim() : "";
+        if (id.length === 0) {
+            items.set(`__anon_${items.size}`, record);
+            return;
+        }
+        const previous = items.get(id);
+        if (!previous) {
+            items.set(id, record);
+            return;
+        }
+        const mergedRecord = { ...previous, ...record };
+        if (Array.isArray(previous.history) || Array.isArray(record.history)) {
+            mergedRecord.history = uniqueValues([
+                ...(Array.isArray(previous.history) ? previous.history : []),
+                ...(Array.isArray(record.history) ? record.history : [])
+            ]);
+        }
+        items.set(id, mergedRecord);
+    };
+    for (const item of Array.isArray(existing.items) ? existing.items : [])
+        appendItem(item);
+    for (const item of Array.isArray(incoming.items) ? incoming.items : [])
+        appendItem(item);
+    merged.items = Array.from(items.values());
+    if (existing.schema_version !== undefined && incoming.schema_version === undefined)
+        merged.schema_version = existing.schema_version;
+    return merged;
+}
+function mergeNewCharacters(existingRaw, incomingRaw) {
+    const existing = Array.isArray(existingRaw) ? existingRaw : [];
+    const incoming = Array.isArray(incomingRaw) ? incomingRaw : [];
+    const merged = [];
+    const seen = new Set();
+    for (const item of [...existing, ...incoming]) {
+        if (!isPlainObject(item)) {
+            merged.push(item);
+            continue;
+        }
+        const record = item;
+        const name = typeof record.name === "string" ? record.name.trim() : "";
+        const firstChapter = typeof record.first_chapter === "number" ? record.first_chapter : "?";
+        const key = `${name}|${String(firstChapter)}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        merged.push(record);
+    }
+    return merged;
+}
+async function jsonFilesEquivalent(leftAbs, rightAbs) {
+    return stableValueKey(await readJsonFile(leftAbs)) === stableValueKey(await readJsonFile(rightAbs));
+}
+async function mergeVolumePlanIntoExistingFinal(rootDir, volume) {
+    const staging = volumeStagingRelPaths(volume);
+    const final = volumeFinalRelPaths(volume);
+    const existingOutline = await readTextFile(join(rootDir, final.outlineMd));
+    const incomingOutline = await readTextFile(join(rootDir, staging.outlineMd));
+    const existingParsed = parseOutline(existingOutline);
+    const incomingParsed = parseOutline(incomingOutline);
+    const existingOutlineChapters = [...existingParsed.blocks.keys()].sort((left, right) => left - right);
+    const expectedSeedChapters = quickstartMiniPlanningChapters();
+    if (!startsWithQuickstartMiniPlanningSeedSequence(existingOutlineChapters)) {
+        throw new NovelCliError(`Refusing to merge into existing volume seed: expected outline to start with chapters ${expectedSeedChapters.join(", ")}, got ${existingOutlineChapters.join(", ") || "(none)"}.`, 2);
+    }
+    const incomingOutlineChapters = [...incomingParsed.blocks.keys()].sort((left, right) => left - right);
+    const invalidIncomingChapter = incomingOutlineChapters.find((chapter) => chapter <= QUICKSTART_MINI_PLANNING_RANGE.end);
+    if (invalidIncomingChapter !== undefined) {
+        throw new NovelCliError(`Refusing to merge staging outline containing seed chapter ${invalidIncomingChapter}; expected formal plan chapters after ${QUICKSTART_MINI_PLANNING_RANGE.end}.`, 2);
+    }
+    for (const chapter of existingOutlineChapters) {
+        if (chapter <= QUICKSTART_MINI_PLANNING_RANGE.end)
+            continue;
+        const existingBlock = existingParsed.blocks.get(chapter);
+        const incomingBlock = incomingParsed.blocks.get(chapter);
+        if (!incomingBlock) {
+            throw new NovelCliError(`Refusing to resume merge with unexpected existing outline chapter ${chapter} in ${final.outlineMd}.`, 2);
+        }
+        if (incomingBlock !== existingBlock) {
+            throw new NovelCliError(`Refusing to resume merge with conflicting outline block for chapter ${chapter} in ${final.outlineMd}.`, 2);
+        }
+    }
+    const mergedOutlineBlocks = new Map(existingParsed.blocks);
+    for (const [chapter, block] of incomingParsed.blocks.entries()) {
+        const existingBlock = mergedOutlineBlocks.get(chapter);
+        if (existingBlock && existingBlock !== block) {
+            throw new NovelCliError(`Refusing to merge conflicting outline block for chapter ${chapter}.`, 2);
+        }
+        mergedOutlineBlocks.set(chapter, block);
+    }
+    const outlineHeader = existingParsed.header.trimEnd().length > 0 ? existingParsed.header : incomingParsed.header;
+    const combinedOutline = [outlineHeader, ...[...mergedOutlineBlocks.keys()].sort((left, right) => left - right).map((chapter) => mergedOutlineBlocks.get(chapter))]
+        .filter((part) => part.trim().length > 0)
+        .join("\n\n");
+    const mergedSchedule = mergeSchedule(await readJsonFile(join(rootDir, final.storylineScheduleJson)), await readJsonFile(join(rootDir, staging.storylineScheduleJson)));
+    const mergedForeshadowing = mergeForeshadowing(await readJsonFile(join(rootDir, final.foreshadowingJson)), await readJsonFile(join(rootDir, staging.foreshadowingJson)));
+    const finalNewCharactersAbs = join(rootDir, final.newCharactersJson);
+    const mergedNewCharacters = mergeNewCharacters((await pathExists(finalNewCharactersAbs)) ? await readJsonFile(finalNewCharactersAbs) : [], await readJsonFile(join(rootDir, staging.newCharactersJson)));
+    const contractCopies = [];
+    const incomingContractNames = new Set();
+    const contractEntries = await readdir(join(rootDir, staging.chapterContractsDir), { withFileTypes: true });
+    for (const entry of contractEntries) {
+        if (entry.name.startsWith("."))
+            continue;
+        if (!entry.isFile() || !entry.name.endsWith(".json"))
+            continue;
+        const match = /^chapter-(\d+)\.json$/u.exec(entry.name);
+        if (!match) {
+            throw new NovelCliError(`Unexpected chapter contract filename during merge: ${staging.chapterContractsDir}/${entry.name}`, 2);
+        }
+        const chapter = Number.parseInt(match[1] ?? "", 10);
+        if (chapter <= QUICKSTART_MINI_PLANNING_RANGE.end) {
+            throw new NovelCliError(`Refusing to overwrite existing seed contract during merge: ${entry.name}`, 2);
+        }
+        incomingContractNames.add(entry.name);
+        const sourceAbs = join(rootDir, staging.chapterContractsDir, entry.name);
+        const destinationAbs = join(rootDir, final.chapterContractsDir, entry.name);
+        if (await pathExists(destinationAbs)) {
+            if (!(await jsonFilesEquivalent(sourceAbs, destinationAbs))) {
+                throw new NovelCliError(`Refusing to overwrite existing destination during merge: ${final.chapterContractsDir}/${entry.name}`, 2);
+            }
+            continue;
+        }
+        contractCopies.push({ sourceAbs, destinationAbs });
+    }
+    const finalContractEntries = await readdir(join(rootDir, final.chapterContractsDir), { withFileTypes: true });
+    for (const entry of finalContractEntries) {
+        if (entry.name.startsWith("."))
+            continue;
+        if (!entry.isFile() || !entry.name.endsWith(".json"))
+            continue;
+        const match = /^chapter-(\d+)\.json$/u.exec(entry.name);
+        if (!match) {
+            throw new NovelCliError(`Unexpected chapter contract filename in final dir during merge: ${final.chapterContractsDir}/${entry.name}`, 2);
+        }
+        const chapter = Number.parseInt(match[1] ?? "", 10);
+        if (chapter <= QUICKSTART_MINI_PLANNING_RANGE.end)
+            continue;
+        if (!incomingContractNames.has(entry.name)) {
+            throw new NovelCliError(`Refusing to resume merge with unexpected existing destination during merge: ${final.chapterContractsDir}/${entry.name}`, 2);
+        }
+    }
+    await writeTextFile(join(rootDir, final.outlineMd), `${combinedOutline.trimEnd()}\n`);
+    await writeJsonFile(join(rootDir, final.storylineScheduleJson), mergedSchedule);
+    await writeJsonFile(join(rootDir, final.foreshadowingJson), mergedForeshadowing);
+    await writeJsonFile(finalNewCharactersAbs, mergedNewCharacters);
+    await ensureDir(join(rootDir, final.chapterContractsDir));
+    for (const contractCopy of contractCopies) {
+        await copyFile(contractCopy.sourceAbs, contractCopy.destinationAbs);
+    }
+    await removePath(join(rootDir, staging.dir));
+}
 export async function commitVolume(args) {
     requireVolume(args.volume);
     const plan = [];
@@ -61,6 +321,7 @@ export async function commitVolume(args) {
         const finalAbs = join(args.rootDir, finalDir);
         const stagingExists = await pathExists(stagingAbs);
         const finalExists = await pathExists(finalAbs);
+        const canMergeExistingFinal = args.volume === 1 && finalExists && stagingExists && await hasQuickstartMiniPlanningSeedBase(args.rootDir);
         if (finalExists && !stagingExists) {
             const required = join(args.rootDir, volumeFinalRelPaths(args.volume).outlineMd);
             if (!(await pathExists(required))) {
@@ -68,7 +329,7 @@ export async function commitVolume(args) {
             }
             warnings.push(`Volume directory already exists (${finalDir}); treating as already committed and only normalizing checkpoint.`);
         }
-        else if (finalExists && stagingExists) {
+        else if (finalExists && stagingExists && !canMergeExistingFinal) {
             throw new NovelCliError(`Commit conflict: both staging and final volume directories exist (${staging} and ${finalDir}). Refusing to overwrite; resolve manually.`, 2);
         }
         else if (!stagingExists) {
@@ -76,7 +337,12 @@ export async function commitVolume(args) {
         }
         else {
             await validateStep({ rootDir: args.rootDir, checkpoint, step: { kind: "volume", phase: "validate" } });
-            await doRenameDir(args.rootDir, staging, finalDir);
+            if (canMergeExistingFinal) {
+                await mergeVolumePlanIntoExistingFinal(args.rootDir, args.volume);
+            }
+            else {
+                await doRenameDir(args.rootDir, staging, finalDir);
+            }
         }
         const updated = { ...checkpoint };
         updated.orchestrator_state = "WRITING";

package/dist/volume-planning.js

@@ -1,8 +1,11 @@
+import { readdir } from "node:fs/promises";
 import { join } from "node:path";
 import { NovelCliError } from "./errors.js";
-import { pathExists } from "./fs-utils.js";
+import { pathExists, readJsonFile, readTextFile } from "./fs-utils.js";
+import { QUICKSTART_MINI_PLANNING_RANGE as SHARED_QUICKSTART_MINI_PLANNING_RANGE, extractOutlineChapterNumbers, matchesQuickstartMiniPlanningSeedSequence, quickstartMiniPlanningChapters, startsWithQuickstartMiniPlanningSeedSequence } from "./quickstart-mini-planning.js";
 import { formatStepId, pad2, pad3 } from "./steps.js";
 export const CHAPTERS_PER_VOLUME = 30;
+export const QUICKSTART_MINI_PLANNING_RANGE = SHARED_QUICKSTART_MINI_PLANNING_RANGE;
 export function volumeForChapter(chapter) {
     if (!Number.isInteger(chapter) || chapter < 1) {
         throw new NovelCliError(`Invalid chapter: ${String(chapter)} (expected int >= 1).`, 2);
@@ -44,6 +47,79 @@ export function volumeFinalRelPaths(volume) {
         chapterContractJson: (chapter) => `${chapterContractsDir}/chapter-${pad3(chapter)}.json`
     };
 }
+export async function hasQuickstartMiniPlanningSeedBase(rootDir) {
+    const final = volumeFinalRelPaths(1);
+    const seedChapters = quickstartMiniPlanningChapters();
+    const requiredPaths = [
+        final.outlineMd,
+        final.storylineScheduleJson,
+        final.foreshadowingJson,
+        final.newCharactersJson,
+        final.chapterContractsDir,
+        ...seedChapters.map((chapter) => final.chapterContractJson(chapter))
+    ];
+    try {
+        for (const relPath of requiredPaths) {
+            if (!(await pathExists(join(rootDir, relPath))))
+                return false;
+        }
+        const outline = await readTextFile(join(rootDir, final.outlineMd));
+        if (!startsWithQuickstartMiniPlanningSeedSequence(extractOutlineChapterNumbers(outline)))
+            return false;
+        await readJsonFile(join(rootDir, final.storylineScheduleJson));
+        await readJsonFile(join(rootDir, final.foreshadowingJson));
+        await readJsonFile(join(rootDir, final.newCharactersJson));
+        for (const chapter of seedChapters) {
+            const raw = await readJsonFile(join(rootDir, final.chapterContractJson(chapter)));
+            if (!raw || typeof raw !== "object" || Array.isArray(raw))
+                return false;
+            if (raw.chapter !== chapter)
+                return false;
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function hasQuickstartMiniPlanningArtifacts(rootDir) {
+    if (!(await hasQuickstartMiniPlanningSeedBase(rootDir)))
+        return false;
+    const final = volumeFinalRelPaths(1);
+    try {
+        const outline = await readTextFile(join(rootDir, final.outlineMd));
+        if (!matchesQuickstartMiniPlanningSeedSequence(extractOutlineChapterNumbers(outline)))
+            return false;
+        const visibleContractEntries = (await readdir(join(rootDir, final.chapterContractsDir), { withFileTypes: true }))
+            .filter((entry) => !entry.name.startsWith("."));
+        if (visibleContractEntries.some((entry) => !entry.isFile()))
+            return false;
+        const contractFiles = visibleContractEntries.map((entry) => entry.name).sort();
+        const expectedContractFiles = quickstartMiniPlanningChapters().map((chapter) => `chapter-${pad3(chapter)}.json`);
+        return (contractFiles.length === expectedContractFiles.length
+            && !contractFiles.some((fileName, index) => fileName !== expectedContractFiles[index]));
+    }
+    catch {
+        return false;
+    }
+}
+export async function resolveVolumeChapterRange(args) {
+    const range = computeVolumeChapterRange({ current_volume: args.current_volume, last_completed_chapter: args.last_completed_chapter });
+    if (args.current_volume !== 1
+        || range.start !== QUICKSTART_MINI_PLANNING_RANGE.start
+        || range.end <= QUICKSTART_MINI_PLANNING_RANGE.end) {
+        return range;
+    }
+    if (await hasQuickstartMiniPlanningArtifacts(args.rootDir)) {
+        return { start: QUICKSTART_MINI_PLANNING_RANGE.end + 1, end: range.end };
+    }
+    const stagingExists = await pathExists(join(args.rootDir, volumeStagingRelPaths(1).dir));
+    if (!stagingExists)
+        return range;
+    if (!(await hasQuickstartMiniPlanningSeedBase(args.rootDir)))
+        return range;
+    return { start: QUICKSTART_MINI_PLANNING_RANGE.end + 1, end: range.end };
+}
 function normalizeVolumePipelineStage(value) {
     if (value === null || value === undefined)
         return null;
@@ -96,7 +172,7 @@ export async function computeVolumeNextStep(rootDir, checkpoint) {
         throw new NovelCliError(`Checkpoint inconsistent for VOL_PLANNING: pipeline_stage=${stageIdle} (expected null or committed). Finish the chapter pipeline or repair .checkpoint.json.`, 2);
     }
     const volume = checkpoint.current_volume;
-    const range = computeVolumeChapterRange({ current_volume: volume, last_completed_chapter: checkpoint.last_completed_chapter });
+    const range = await resolveVolumeChapterRange({ rootDir, current_volume: volume, last_completed_chapter: checkpoint.last_completed_chapter });
     const artifacts = await hasAllPlanningArtifacts({ rootDir, volume, range });
     if (stage === null || stage === "outline") {
         return {
@@ -138,6 +214,5 @@ export async function computeVolumeNextStep(rootDir, checkpoint) {
             evidence: artifacts.evidence
         };
     }
-    // normalizeVolumePipelineStage() ensures the above is exhaustive.
     throw new NovelCliError(`Unsupported volume_pipeline_stage: ${String(checkpoint.volume_pipeline_stage)}`, 2);
 }

package/docs/user/README.md

@@ -9,6 +9,7 @@
 
 - 快速上手（Skill 入口）：[快速起步指南](quick-start.md)
 - CLI 手册（最重要）：[`novel` CLI](novel-cli.md)
+- 老项目升级：[M8 迁移指南](migration-guide.md)
 - 常用操作（Skill 入口）：[常用操作](ops.md)
 - 规范体系（文件/契约/平台画像）：[规范体系](spec-system.md)
 - Guardrails（留存/可读性/命名）：[Guardrails](guardrails.md)

package/docs/user/migration-guide.md

@@ -0,0 +1,166 @@
+# M8 迁移指南
+
+这份指南面向已经在使用项目、现在想理解 M8 增量能力的作者。好消息是：M8 的核心变化都做了向后兼容（backward compatibility），大多数老项目**不需要停机迁移**；但如果你准备开新项目、重开项目，或想启用 M8 新特性，仍然建议把全文通读一遍。
+
+> 建议先按下表判断优先级，再跳到对应章节。只想继续写旧项目，可以先看与你当前项目最相关的章节；准备开新项目或重开项目，则一定要看最后的 Quick Start 工作流变更。
+
+## 迁移优先级速查
+
+| 场景 | 优先看什么 |
+|------|------------|
+| 老项目继续写，不想改流程 | `canon_status`、`excitement_type`、题材特定标准 |
+| 老项目想启用平台化评审 | 平台写作指南、`tomato` → `fanqie` |
+| 新开项目 / 重开项目 | 黄金三章门控 + Quick Start 工作流变更（Step F0 + Step F） |
+
+## 1. 正典状态（`canon_status`）迁移
+
+### 是否需要操作
+
+**默认不需要。** 老项目里没有 `canon_status` 字段的规则和角色，会自动按 `established` 处理。
+
+### 如何操作
+
+如果你想开始区分“现在就生效”和“只是先铺垫”的设定，可以逐步补字段：
+
+- 在 `world/rules.json` 里，为规则补 `canon_status`；
+- 在 `characters/active/*.json` 里，为角色补 `canon_status`；
+- 推荐用法：
+  - `established`：从当前章节开始就必须遵守；
+  - `planned`：允许进入上下文做铺垫，但暂不作为硬约束；
+  - `deprecated`：保留历史记录，但不再参与当前创作。
+
+一个实用判断标准是：如果这条规则 / 角色“现在违背了也不能算错”，就先标 `planned`，不要急着标 `established`。
+
+### 不操作会怎样
+
+**不会出问题。** 系统会把缺失字段当成 `established`，所以老项目行为与 M8 之前保持一致；只是你暂时用不上“计划中设定 / 已废弃设定”的精细语义。
+
+## 2. `tomato` → `fanqie` 平台名迁移
+
+### 是否需要操作
+
+**可选。** 如果你的老项目里仍然写的是 `platform: "tomato"`，功能上依然可用。
+
+### 如何操作
+
+如果你想把项目里的命名统一到新的规范，可以手动把可见配置改成 `fanqie`：
+
+1. 检查 `platform-profile.json` 中的 `platform` 字段；
+2. 如有需要，同步更新 `brief.md` 里的目标平台描述；
+3. 如果 `style-profile.json.platform` 里还保留旧值，也可以一起改成 `fanqie`，方便团队阅读与排障。
+
+> 新建项目时，界面只展示 `fanqie（番茄）`，不再展示 `tomato`；但系统内部仍会接受旧别名并自动做 canonical 化处理。
+
+### 不操作会怎样
+
+**几乎没有功能影响。** `tomato` 会继续作为 `fanqie` 的兼容别名工作，门控和平台规则仍会按番茄平台执行。唯一影响主要是：文档、配置和新项目命名不一致，阅读时略显混乱。
+
+## 3. 兴奋点类型（`excitement_type`）迁移
+
+### 是否需要操作
+
+**默认不需要。** 旧的 L3 章节契约没有 `excitement_type` 时，系统会按 `null` 处理。
+
+### 如何操作
+
+如果你想让节奏评审更贴近“这一章到底想让读者爽在哪里”，可以从新增或重规划的章节开始补：
+
+- 在 L3 契约里使用这些值：`reversal`、`face_slap`、`power_up`、`reveal`、`cliffhanger`、`setup`、`null`；
+- 如果你走的是新 Quick Start 或新的卷规划流程，PlotArchitect 通常会自动写入，不需要你手填；
+- 如果你手动维护旧项目的章节契约，可以只给关键章节补，不必一次性回填全书。
+
+### 不操作会怎样
+
+**系统仍能正常运行。** 缺失字段会被视为 `null`，QualityJudge 不会做特定爽点落地检查，只会按普通节奏标准评审。这意味着你失去的是“更精准的节奏反馈”，不是基本可用性。
+
+## 4. 黄金三章门控（golden chapter gates）迁移
+
+### 是否需要操作
+
+**对已经写完第 1–3 章的老项目，通常不需要。** 黄金三章门控只针对开局三章。
+
+### 如何操作
+
+如果你是下面两种情况，可以考虑补齐：
+
+- **全新项目 / 准备重开项目**：直接在初始化时选平台，系统会自动生成 `golden-chapter-gates.json`；
+- **老项目还没正式写完前三章**：如果你非常想把黄金门控补进来，最稳妥的方式仍然是备份后以新目录重新初始化；不要默认系统会把一个已在途项目自动改造成新的 Quick Start。
+
+如果你的前三章已经定稿，最稳的策略通常不是“硬套回去重判”，而是把 M8 门控用在**下一本书**或**重开的版本**上。
+
+### 不操作会怎样
+
+**不会影响已完成章节。** 已经过了开局阶段的项目不会因为 M8 新增黄金门控而被回滚；后续普通章节仍按标准质量门控执行。
+
+## 5. 平台写作指南（platform writing guide）迁移
+
+### 是否需要操作
+
+**可选，但很值得。** 如果你想让系统更明确地区分起点 / 番茄 / 晋江的节奏与钩子偏好，就应该补齐平台配置。
+
+### 如何操作
+
+建议按“先决定平台，再一次性补齐文件”的方式做：
+
+1. 确认你的项目主要面向哪个平台：`qidian` / `fanqie` / `jinjiang`；
+2. 显式设置或更新项目绑定：把 `platform-profile.json.platform` 设为你选定的平台；如果项目里已经存在旧值（例如 `tomato`），就在这里统一改成目标值。
+3. 确保项目根目录具备这些文件：
+   - `platform-profile.json`
+   - `genre-weight-profiles.json`
+   - `golden-chapter-gates.json`
+   - `platform-writing-guide.md`
+4. 如果老项目还没有这些文件，最稳妥的方法是：
+   - 新建一个临时目录执行 `novel init --platform <platform>`；
+   - 从新目录拷贝对应平台文件到老项目；
+   - 检查后再继续写作。
+5. 补齐后会生效的主要变化是：
+   - ChapterWriter 会读取 `platform-writing-guide.md`，按平台偏好的节奏密度、对白比例、钩子策略与情绪回报节奏来写；
+   - QualityJudge 会读取 `platform-profile.json.scoring` + `genre-weight-profiles.json`，给出平台化的动态权重评分；
+   - 如果当前处于开局三章，`golden-chapter-gates.json` 也会参与黄金门控。
+
+> 注意：`platform-profile.json.platform` 与 `scoring.genre_drive_type` 会被视为不可变绑定。老项目如果此前没有平台画像，第一次补齐时要尽量一次选准；不要在同一项目里频繁切平台。
+
+### 不操作会怎样
+
+**系统会继续使用平台无关（platform-agnostic）的默认评审。** 也就是说，写作仍能继续，但你拿不到平台化的节奏密度、对话比例、钩子策略和动态评分权重，反馈会更“通用”，不够贴平台。
+
+## 6. 题材特定标准（genre-specific standards）迁移
+
+### 是否需要操作
+
+**默认不需要。** 这是增强项，不是基础可用性的前提。
+
+### 如何操作
+
+如果你想启用题材感知的黄金三章规划与评审，需要同时满足两件事：
+
+1. `brief.md` 里的 `- **题材**：` 要填写清楚，并尽量使用系统已覆盖的题材（如玄幻、都市、科幻、历史、悬疑、言情）；
+2. 项目根目录中要有：
+   - `genre-excitement-map.json`
+   - `genre-golden-standards.json`
+
+新版本 `novel init` 已经会写入这两个模板文件；老项目如果缺失，直接从模板补齐即可。
+
+### 不操作会怎样
+
+**系统会退回通用标准。** 没有题材字段、题材无法匹配，或缺少这两个题材模板文件时，Quick Start 与 QualityJudge 会继续工作，只是不会应用玄幻 / 悬疑 / 言情等差异化标准。
+
+## 7. Quick Start 工作流变更（Step F0 + Step F）
+
+### 是否需要操作
+
+**对已经在写的老项目，通常不需要专门迁移；对准备开新项目、重开项目或想完整启用 M8 开局流程的用户，建议了解。**
+
+### 如何操作
+
+如果你要从 M8 的新开局方式重新开始，建议按下面理解：
+
+1. 新 Quick Start 的固定顺序是 `world → characters → style → f0 → trial → results`；
+2. `quickstart:f0` 会先为 `vol-01` 生成第 1–3 章的迷你规划种子，包括 `outline.md`、L3 契约、`storyline-schedule.json` 和 `foreshadowing.json`；
+3. `quickstart:trial` 不再是假定你直接连续写完三章，而是先试写 1 个代表性章节；
+4. `quickstart:results` 会结合这份试写章和黄金三章规划种子，决定你是进入正式卷规划、调整风格，还是重新试写；
+5. 如果你想在老项目上体验这套新流程，最稳妥的方式是新建目录重新初始化，而不是指望旧项目中途自动插入 Step F0。
+
+### 不操作会怎样
+
+**老项目不会因此失效。** 你仍然可以按现有状态继续写；只是当你看到新文档或新项目多了 Step F0、试写结果决策和黄金三章迷你规划时，如果没读这一节，可能会不知道这些新增步骤是做什么的。

package/docs/user/novel-cli.md

@@ -59,7 +59,7 @@ node dist/cli.js --help
 
 ```bash
 mkdir my-novel && cd my-novel
-novel init --platform tomato
+novel init --platform fanqie
 ```
 
 默认会：
@@ -67,17 +67,18 @@ novel init --platform tomato
 - 写入 `.checkpoint.json`
 - 创建 `staging/**` 必要目录
 - 写入若干模板文件（如 `brief.md`、`style-profile.json`、`ai-blacklist.json`、`web-novel-cliche-lint.json`）
+- 若指定 `--platform`，额外写入 `platform-profile.json`、`genre-weight-profiles.json`、`golden-chapter-gates.json`、`platform-writing-guide.md`
 
 常用选项：
 
 - `--minimal`：只创建 `.checkpoint.json` + `staging/**`（跳过模板文件）
 - `--force`：覆盖已有文件（谨慎使用）
-- `--platform qidian|tomato`：写入 `platform-profile.json`，并同时写入 `genre-weight-profiles.json`（用于 QualityJudge 动态权重）
+- `--platform qidian|fanqie|jinjiang`：写入 `platform-profile.json`，并同时写入 `genre-weight-profiles.json`、`golden-chapter-gates.json` 与 `platform-writing-guide.md`（兼容旧别名 `tomato`）
 
 也可指定目标目录（会在目录不存在时创建）：
 
 ```bash
-novel init --project ./my-novel --platform tomato
+novel init --project ./my-novel --platform fanqie
 ```
 
 ## 最短路径：跑通“一章的确定性编排”