@cloud411716/fancy-webnovel 1.0.46 → 3.0.0

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

@@ -0,0 +1,121 @@
+/**
+ * v2/snapshot.js —— 内容寻址快照与回滚。
+ *
+ * 只存哈希不能回滚；这里存真实内容对象：
+ *   设定/.snapshots/<id>/manifest.json  路径 → 对象哈希
+ *   设定/.objects/<sha256>              实际文件内容
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import {
+  V2_STAGES,
+  bytesHash,
+  ensureDir,
+  nowIso,
+  readJson,
+  stageDir,
+  writeJsonAtomic,
+} from './core.js';
+
+const SNAPSHOT_ROOT = ['设定', '.snapshots'];
+const OBJECT_ROOT = ['设定', '.objects'];
+
+function objectPath(projectRoot, hash) {
+  return path.join(projectRoot, ...OBJECT_ROOT, hash.replace(/^sha256:/, ''));
+}
+
+function digest(bytes) {
+  return 'sha256:' + crypto.createHash('sha256').update(bytes).digest('hex');
+}
+
+function stageJsonFiles(projectRoot) {
+  const out = [];
+  for (const stage of V2_STAGES) {
+    const dir = stageDir(projectRoot, stage.id);
+    if (!fs.existsSync(dir)) continue;
+    const walk = (current) => {
+      for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+        if (entry.name.startsWith('.') || entry.name === '_context') continue;
+        const full = path.join(current, entry.name);
+        if (entry.isDirectory()) {
+          if (['outlines', 'chapters', 'timelines'].includes(entry.name)) walk(full);
+          continue;
+        }
+        if (entry.name === 'bundle.json' || entry.name === 'README.md') continue;
+        if (entry.name.endsWith('.json') || entry.name.endsWith('.md')) out.push(full);
+      }
+    };
+    walk(dir);
+  }
+  const manifest = path.join(projectRoot, '设定', 'manifest.json');
+  if (fs.existsSync(manifest)) out.push(manifest);
+  return out.sort();
+}
+
+export function createSnapshot(projectRoot, label = '') {
+  const id = nowIso().replace(/[:.]/g, '-') + '-' + crypto.randomBytes(3).toString('hex');
+  const snapDir = path.join(projectRoot, ...SNAPSHOT_ROOT, id);
+  ensureDir(snapDir);
+  ensureDir(path.join(projectRoot, ...OBJECT_ROOT));
+  const files = {};
+  for (const file of stageJsonFiles(projectRoot)) {
+    const bytes = fs.readFileSync(file);
+    const hash = digest(bytes);
+    const obj = objectPath(projectRoot, hash);
+    if (!fs.existsSync(obj)) {
+      fs.writeFileSync(obj, bytes);
+    }
+    files[path.relative(projectRoot, file).split(path.sep).join('/')] = hash;
+  }
+  const manifest = {
+    id,
+    created_at: nowIso(),
+    label: String(label || ''),
+    files,
+  };
+  writeJsonAtomic(path.join(snapDir, 'manifest.json'), manifest);
+  return { ok: true, id, path: path.relative(projectRoot, snapDir).split(path.sep).join('/'), fileCount: Object.keys(files).length };
+}
+
+export function listSnapshots(projectRoot) {
+  const root = path.join(projectRoot, ...SNAPSHOT_ROOT);
+  if (!fs.existsSync(root)) return [];
+  const out = [];
+  for (const name of fs.readdirSync(root)) {
+    const manifest = readJson(path.join(root, name, 'manifest.json'), null);
+    if (manifest) out.push({ id: manifest.id || name, createdAt: manifest.created_at, label: manifest.label, fileCount: Object.keys(manifest.files || {}).length });
+  }
+  return out.sort((a, b) => String(b.id).localeCompare(String(a.id)));
+}
+
+export function rollbackSnapshot(projectRoot, snapshotId) {
+  const snap = readJson(path.join(projectRoot, ...SNAPSHOT_ROOT, snapshotId, 'manifest.json'), null);
+  if (!snap) return { ok: false, error: '快照不存在：' + snapshotId };
+  // 先给当前状态拍一张，保证回滚可撤销
+  const pre = createSnapshot(projectRoot, 'pre-rollback-' + snapshotId);
+  let restored = 0;
+  const errors = [];
+  for (const [rel, hash] of Object.entries(snap.files || {})) {
+    const obj = objectPath(projectRoot, hash);
+    if (!fs.existsSync(obj)) {
+      errors.push({ path: rel, message: '对象缺失：' + hash });
+      continue;
+    }
+    const target = path.join(projectRoot, ...rel.split('/'));
+    ensureDir(path.dirname(target));
+    fs.copyFileSync(obj, target);
+    restored += 1;
+  }
+  // 删除快照里没有的当前业务文件（避免回滚后残留新文件）
+  const current = new Set(stageJsonFiles(projectRoot).map((f) => path.relative(projectRoot, f).split(path.sep).join('/')));
+  for (const rel of current) {
+    if (Object.prototype.hasOwnProperty.call(snap.files || {}, rel)) continue;
+    try {
+      fs.unlinkSync(path.join(projectRoot, ...rel.split('/')));
+    } catch {
+      // ignore
+    }
+  }
+  return { ok: errors.length === 0, restored, errors, preSnapshot: pre.id, snapshot: snapshotId };
+}

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

@@ -0,0 +1,273 @@
+/**
+ * v2/stages.js —— 2.0 阶段编排（纯函数部分）
+ *
+ * 加载阶段文件、跑校验、补 _meta、写 bundle/README/status。
+ * LLM 调用在 index.js 的命令处理器里，不在这里。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  CONTRACT_VERSION,
+  SCHEMA_VERSION,
+  V2_STAGE_BY_ID,
+  asArray,
+  contentHash,
+  fileExists,
+  nowIso,
+  readJson,
+  readStageStatus,
+  relProjectPath,
+  stageDir,
+  stageFile,
+  writeJsonAtomic,
+  writeStageStatus,
+  writeTextAtomic,
+} from './core.js';
+import { contractFor } from './contracts.js';
+import { ensureContext, quantitySnapshot, validateBundle, writeBundle } from './context.js';
+import { buildManifest } from './manifest.js';
+import { renderScaleMd, validateScale } from './scale.js';
+import { detectProfileKey, getProfile, loadGenreProfiles } from './genre.js';
+import { validateMacro } from './macro.js';
+import { validateCast } from './cast.js';
+import { loadRhythm, validateRhythm } from './rhythm.js';
+import { loadWriting, validateWriting } from './writing.js';
+
+export function loadDocuments(projectRoot, stageId) {
+  const spec = V2_STAGE_BY_ID[stageId];
+  const dir = stageDir(projectRoot, stageId);
+  const out = {};
+  if (!spec) return out;
+  if (stageId === '20-macro') {
+    return {
+      world: readJson(path.join(dir, 'world.json'), null),
+      story: readJson(path.join(dir, 'story.json'), null),
+      volumes: readJson(path.join(dir, 'volumes.json'), null),
+      lines: readJson(path.join(dir, 'lines.json'), null),
+      endings: readJson(path.join(dir, 'endings.json'), null),
+      emotion: readJson(path.join(dir, 'emotion.json'), null),
+      roles: readJson(path.join(dir, 'roles.json'), null),
+    };
+  }
+  if (stageId === '30-cast') {
+    return {
+      characters: readJson(path.join(dir, 'characters.json'), null),
+      factions: readJson(path.join(dir, 'factions.json'), null),
+      locations: readJson(path.join(dir, 'locations.json'), null),
+      items: readJson(path.join(dir, 'items.json'), null),
+      conflicts: readJson(path.join(dir, 'conflicts.json'), null),
+      foreshadows: readJson(path.join(dir, 'foreshadows.json'), null),
+      climaxes: readJson(path.join(dir, 'climaxes.json'), null),
+      payoffs: readJson(path.join(dir, 'payoffs.json'), null),
+      relations: readJson(path.join(dir, 'relations.json'), null),
+      information: readJson(path.join(dir, 'information.json'), null),
+    };
+  }
+  for (const file of spec.requiredFiles) {
+    out[file.replace(/\.json$/, '')] = readJson(path.join(dir, file), null);
+  }
+  return out;
+}
+
+export function missingStageFiles(projectRoot, stageId) {
+  const spec = V2_STAGE_BY_ID[stageId];
+  if (!spec) return [];
+  return spec.requiredFiles.filter((f) => !fileExists(stageFile(projectRoot, stageId, f)));
+}
+
+export function stageGate(projectRoot, stageId) {
+  const spec = V2_STAGE_BY_ID[stageId];
+  const missing = [];
+  for (const up of (spec && spec.upstream) || []) {
+    const status = readStageStatus(projectRoot, up, { allowLegacy: false });
+    if (status.status !== 'passed') {
+      missing.push({ stage: up, status: status.status });
+    }
+  }
+  return { ok: missing.length === 0, missing };
+}
+
+export function validateStage(projectRoot, stageId, opts = {}) {
+  const scale = readJson(stageFile(projectRoot, '10-scale', 'scale.json'), null);
+  if (stageId === '00-baseline') {
+    const input = readJson(stageFile(projectRoot, '00-baseline', 'input.json'), null);
+    const formulas = readJson(stageFile(projectRoot, '00-baseline', 'formulas.json'), null);
+    const errors = [];
+    if (!input) errors.push({ code: 'BASELINE_INPUT_MISSING', path: '00-baseline/input.json', message: '缺少 input.json' });
+    if (!formulas) errors.push({ code: 'BASELINE_FORMULAS_MISSING', path: '00-baseline/formulas.json', message: '缺少 formulas.json' });
+    if (input) {
+      for (const key of ['book_name', 'target_chapters', 'target_words']) {
+        if (!input[key]) errors.push({ code: 'BASELINE_REQUIRED', path: 'input.' + key, message: '缺少必填字段' });
+      }
+    }
+    return { ok: errors.length === 0, errors, warnings: [], data: input };
+  }
+  if (stageId === '10-scale') {
+    const formulas = opts.formulasDoc || readJson(stageFile(projectRoot, '00-baseline', 'formulas.json'), null);
+    const profilesDoc = opts.profilesDoc || loadGenreProfiles(projectRoot);
+    const profileKey = (scale && scale.genre_profile) || detectProfileKey(readJson(stageFile(projectRoot, '00-baseline', 'input.json'), {}) || {}, profilesDoc);
+    const profile = opts.profile || getProfile(profilesDoc, profileKey);
+    return validateScale(scale, formulas, { ...opts, profilesDoc, profile, genreProfileKey: profileKey });
+  }
+  if (stageId === '20-macro') {
+    const macro = loadDocuments(projectRoot, stageId);
+    return validateMacro(macro, scale, opts);
+  }
+  if (stageId === '30-cast') {
+    const cast = loadDocuments(projectRoot, stageId);
+    const macro = loadDocuments(projectRoot, '20-macro');
+    return validateCast(cast, scale, macro, opts);
+  }
+  if (stageId === '40-rhythm') {
+    const macro = loadDocuments(projectRoot, '20-macro');
+    const cast = loadDocuments(projectRoot, '30-cast');
+    const rhythm = loadRhythm(projectRoot, stageDir(projectRoot, stageId), opts);
+    return validateRhythm(rhythm, scale, macro, cast, { ...opts, stageDir: stageDir(projectRoot, stageId) });
+  }
+  if (stageId === '50-writing') {
+    const writing = loadWriting(projectRoot);
+    return validateWriting(writing, { dir: writing.dir, ...opts });
+  }
+  return { ok: true, errors: [], warnings: [], data: null };
+}
+
+/**
+ * 给阶段所有业务 JSON 补 _meta（upstream / quantity_snapshot / content_hash）。
+ * 然后写 bundle/README，并刷新 manifest。
+ */
+export function finalizeStage(projectRoot, stageId, opts = {}) {
+  const spec = V2_STAGE_BY_ID[stageId];
+  if (!spec) return { ok: false, error: '未知阶段：' + stageId };
+  if (stageId === '40-rhythm') {
+    const map = readJson(stageFile(projectRoot, '40-rhythm', 'chapter_map.json'), null);
+    if (map && Array.isArray(map.chapters)) {
+      writeJsonAtomic(stageFile(projectRoot, '40-rhythm', 'index.json'), {
+        _meta: { schema_version: SCHEMA_VERSION, node_id: '40-rhythm.index', stage: '40-rhythm' },
+        chapters: map.chapters.map((c) => ({
+          chapter_id: c.chapter_id,
+          display_no: c.display_no,
+          title: c.title,
+          volume: c.volume,
+          act: c.act,
+          path: 'outlines/' + c.chapter_id + '.json',
+          status: c.status || 'draft',
+        })),
+      });
+    }
+  }
+  const scale = readJson(stageFile(projectRoot, '10-scale', 'scale.json'), null);
+  const dir = stageDir(projectRoot, stageId);
+  const manifestBefore = buildManifest(projectRoot, { write: false });
+  const upstreamOf = (ids) => asArray(ids).map((nodeId) => {
+    const node = manifestBefore.nodes && manifestBefore.nodes[nodeId];
+    if (!node) return null;
+    return {
+      node_id: nodeId,
+      path: node.path,
+      hash: node.hash,
+      snapshot: node.kind === 'stage' ? '_context/' + nodeId.split('-').pop() + '.json' : undefined,
+    };
+  }).filter(Boolean);
+  const files = [];
+  if (stageId === '40-rhythm') {
+    files.push(path.join(dir, 'chapter_map.json'));
+    let names = [];
+    try {
+      names = fs.readdirSync(path.join(dir, 'outlines')).filter((n) => n.endsWith('.json'));
+    } catch {
+      names = [];
+    }
+    for (const name of names) files.push(path.join(dir, 'outlines', name));
+    if (fs.existsSync(path.join(dir, 'index.json'))) files.push(path.join(dir, 'index.json'));
+  } else {
+    for (const name of spec.requiredFiles) files.push(path.join(dir, name));
+  }
+  if (stageId === '50-writing') {
+    files.push(path.join(dir, 'ledger.json'));
+  }
+  for (const file of files) {
+    if (!fs.existsSync(file)) continue;
+    const data = readJson(file, null);
+    if (!data || typeof data !== 'object') continue;
+    const rel = path.relative(dir, file).split(path.sep).join('/');
+    const isOutline = rel.startsWith('outlines/');
+    const upstreamIds = isOutline
+      ? ['40-rhythm.chapter_map', '10-scale', '20-macro', '30-cast']
+      : (spec.upstream || []);
+    const upstream = upstreamOf(upstreamIds);
+    const nodeId = isOutline
+      ? '40-rhythm.outline.' + rel.replace(/^outlines\//, '').replace(/\.json$/, '')
+      : stageId + '.' + rel.replace(/\.(json|md)$/, '').replace(/\//g, '.');
+    data._meta = {
+      schema_version: SCHEMA_VERSION,
+      contract_version: CONTRACT_VERSION,
+      node_id: nodeId,
+      stage: stageId,
+      path: path.join(spec.dir, rel).split(path.sep).join('/'),
+      status: opts.status || 'draft',
+      locked: false,
+      content_hash: contentHash(data),
+      generated_at: nowIso(),
+      upstream,
+      quantity_snapshot: quantitySnapshot(stageId, scale),
+      self_contained: {
+        context_dir: '_context',
+        required_files: (contractFor(stageId) && contractFor(stageId).readOrder || []).filter((x) => x.startsWith('_context/')),
+      },
+    };
+    writeJsonAtomic(file, data);
+  }
+  writeBundle(projectRoot, stageId);
+  buildManifest(projectRoot, { write: true });
+  return { ok: true, files: files.map((f) => relProjectPath(projectRoot, f)) };
+}
+
+/**
+ * 完整阶段校验：业务校验 + 自包含 + bundle。写 .stage-status.json。
+ */
+export function runStageValidation(projectRoot, stageId, opts = {}) {
+  const report = validateStage(projectRoot, stageId, opts);
+  const errors = [...asArray(report.errors)];
+  const warnings = [...asArray(report.warnings || [])];
+  if (opts.selfContained !== false) {
+    const context = ensureContext(projectRoot, stageId);
+    for (const e of asArray(context.errors)) errors.push(e);
+    writeBundle(projectRoot, stageId);
+    const bundle = validateBundle(projectRoot, stageId);
+    for (const e of asArray(bundle.errors)) errors.push(e);
+  }
+  const ok = errors.length === 0;
+  if (ok && stageId === '10-scale') {
+    writeTextAtomic(stageFile(projectRoot, '10-scale', 'scale.md'), renderScaleMd(report.data || readJson(stageFile(projectRoot, '10-scale', 'scale.json'), {})));
+  }
+  writeStageStatus(projectRoot, stageId, {
+    ok,
+    status: ok ? 'passed' : 'stale',
+    files: {},
+    errors,
+    warnings,
+  });
+  if (ok) {
+    finalizeStage(projectRoot, stageId, { status: 'passed' });
+  } else {
+    buildManifest(projectRoot, { write: true });
+  }
+  return { ok, errors, warnings, data: report.data };
+}
+
+export function describeStage(projectRoot, stageId) {
+  const status = readStageStatus(projectRoot, stageId);
+  return {
+    stage: stageId,
+    label: V2_STAGE_BY_ID[stageId] ? V2_STAGE_BY_ID[stageId].label : stageId,
+    status: status.status,
+    checkedAt: status.checkedAt,
+    errors: status.errors.length,
+    warnings: status.warnings.length,
+    missing: missingStageFiles(projectRoot, stageId),
+  };
+}
+
+export function stageOverview(projectRoot) {
+  return Object.keys(V2_STAGE_BY_ID).map((id) => describeStage(projectRoot, id));
+}

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

@@ -0,0 +1,216 @@
+/**
+ * v2/writing.js —— 50-writing：只按单章细纲写正文。
+ *
+ * 结构校验：
+ *   - 每章文件存在、标题章号正确、有效字数达标
+ *   - ledger 有对应条目
+ *   - must_write 至少有可识别内容落入正文
+ *   - must_not_write 的明确禁令没有被直接违反
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { asArray, readJson, readText, stageDir, v2Error } from './core.js';
+import { countEffectiveChars } from '../content-quality.js';
+import { loadRhythm } from './rhythm.js';
+import { knowledgeKey, replayKnowledge, validateKnowledgeSnapshot } from './knowledge.js';
+
+export function chapterFileName(displayNo) {
+  return '第' + String(displayNo).padStart(3, '0') + '章.md';
+}
+
+export function loadWriting(projectRoot) {
+  const dir = stageDir(projectRoot, '50-writing');
+  const ledger = readJson(path.join(dir, 'ledger.json'), { chapters: [] });
+  const rhythmDir = stageDir(projectRoot, '40-rhythm');
+  const rhythm = loadRhythm(projectRoot, rhythmDir);
+  const castDir = stageDir(projectRoot, '30-cast');
+  const cast = {
+    characters: readJson(path.join(castDir, 'characters.json'), null),
+    information: readJson(path.join(castDir, 'information.json'), null),
+    foreshadows: readJson(path.join(castDir, 'foreshadows.json'), null),
+  };
+  return { dir, ledger, rhythm, cast };
+}
+
+function keywordsOf(phrase) {
+  const text = String(phrase || '');
+  const out = new Set();
+  for (const part of text.split(/[，。；、：:;,.\s（）()“”"']+/)) {
+    if (part.length >= 2) out.add(part);
+    if (part.length > 6) {
+      out.add(part.slice(0, 4));
+      out.add(part.slice(-4));
+    }
+  }
+  return [...out];
+}
+
+function hasAnyKeyword(text, phrase) {
+  const kws = keywordsOf(phrase);
+  if (!kws.length) return true;
+  return kws.some((k) => text.includes(k));
+}
+
+export function validateWriting(writing, opts = {}) {
+  const errors = [];
+  const warnings = [];
+  const { ledger, rhythm, cast } = writing || {};
+  const knowledge = cast ? replayKnowledge(rhythm && rhythm.chapter_map && rhythm.chapter_map.chapters, cast) : null;
+  const chapters = asArray(rhythm && rhythm.chapter_map && rhythm.chapter_map.chapters);
+  const outlines = (rhythm && rhythm.outlines) || new Map();
+  const ledgerRows = asArray(ledger && ledger.chapters);
+  const ledgerByCh = new Map();
+  const ledgerById = new Map();
+  for (const row of ledgerRows) {
+    if (!row) continue;
+    if (row.ch !== undefined) ledgerByCh.set(Number(row.ch), row);
+    if (row.chapter_id) ledgerById.set(row.chapter_id, row);
+  }
+
+  const writingDir = opts.dir;
+  const chapterFilter = opts.chapterIds instanceof Set ? opts.chapterIds : null;
+  let written = 0;
+  for (const c of chapters) {
+    if (!c || c.status === 'archived') continue;
+    const displayNo = Number(c.display_no);
+    const id = c.chapter_id;
+    if (chapterFilter && !chapterFilter.has(displayNo)) continue;
+    const file = path.join(writingDir, 'chapters', chapterFileName(displayNo));
+    const text = readText(file, null);
+    if (text === null) {
+      errors.push(v2Error('WRITING_CHAPTER_MISSING', {
+        path: 'chapters/' + chapterFileName(displayNo),
+        message: '第 ' + displayNo + ' 章正文缺失',
+        contract: '50-writing/README.md#writing',
+        reference: '40-rhythm/chapter_map.json',
+      }));
+      continue;
+    }
+    written += 1;
+    const first = String(text).split('\n', 1)[0].trim();
+    const m = /^#\s*第\s*(\d+)\s*章(?:\s|$)/.exec(first);
+    if (!m) {
+      errors.push(v2Error('WRITING_TITLE', {
+        path: 'chapters/' + chapterFileName(displayNo),
+        message: '正文第一行必须是 `# 第N章 标题`',
+        actual: first.slice(0, 40),
+        contract: '50-writing/README.md#writing',
+      }));
+    } else if (Number(m[1]) !== displayNo) {
+      errors.push(v2Error('WRITING_TITLE', {
+        path: 'chapters/' + chapterFileName(displayNo),
+        message: '标题章号与 display_no 不一致',
+        expected: displayNo, actual: Number(m[1]),
+        contract: '50-writing/README.md#writing',
+      }));
+    }
+    const chars = countEffectiveChars(text);
+    if (chars < 500) {
+      errors.push(v2Error('WRITING_EMPTY_BODY', {
+        path: 'chapters/' + chapterFileName(displayNo),
+        message: '正文太短',
+        actual: chars,
+        hint: '至少写 500 个有效字符；如果细纲信息不足，先修细纲',
+        contract: '50-writing/README.md#writing',
+      }));
+    }
+    const target = Number(c.word_target || 0);
+    if (target > 0 && (chars < target * 0.6 || chars > target * 1.6)) {
+      warnings.push(v2Error('WRITING_WORD_COUNT', {
+        path: 'chapters/' + chapterFileName(displayNo),
+        severity: 'warning',
+        message: '正文字数与细纲 word_target 偏差较大',
+        expected: '约 ' + target, actual: chars,
+        contract: '50-writing/README.md#writing',
+      }));
+    }
+    const ledgerRow = ledgerById.get(id) || ledgerByCh.get(displayNo);
+    if (!ledgerRow) {
+      errors.push(v2Error('WRITING_LEDGER_ENTRY_MISSING', {
+        path: 'ledger.json#chapters',
+        message: '第 ' + displayNo + ' 章没有 ledger 条目',
+        contract: '50-writing/README.md#ledger',
+      }));
+    } else {
+      for (const key of ['ch', 'chapter_id', 'title', 'pov', 'word_count']) {
+        if (ledgerRow[key] === undefined || ledgerRow[key] === null || ledgerRow[key] === '') {
+          errors.push(v2Error('WRITING_LEDGER_FIELD', {
+            path: 'ledger.json#chapters[' + displayNo + '].' + key,
+            message: 'ledger 条目缺少字段：' + key,
+            contract: '50-writing/README.md#ledger',
+          }));
+        }
+      }
+      if (knowledge) {
+        const expected = knowledge.snapshots.get(displayNo) || new Map();
+        const changes = asArray(ledgerRow.knowledge_changes);
+        for (let j = 0; j < changes.length; j += 1) {
+          const change = changes[j];
+          if (!change || typeof change !== 'object' || !change.subject_type || !change.subject_id || !change.character) continue;
+          const key = knowledgeKey(change.subject_type, change.subject_id, change.character);
+          const exp = expected.get(key);
+          const to = change.to || change.state || change.coverage;
+          if (!exp) {
+            warnings.push(v2Error('WRITING_KNOWLEDGE_UNKNOWN', {
+              path: 'ledger.json#chapters[' + displayNo + '].knowledge_changes[' + j + ']',
+              severity: 'warning',
+              message: '章节地图没有登记这条知识：' + key,
+              contract: '50-writing/README.md#knowledge',
+            }));
+          } else if (to && to !== exp.state) {
+            errors.push(v2Error('WRITING_KNOWLEDGE_CONFLICT', {
+              path: 'ledger.json#chapters[' + displayNo + '].knowledge_changes[' + j + '].to',
+              message: '第 ' + displayNo + ' 章 ledger 的知识状态与章节地图冲突',
+              expected: exp.state, actual: to,
+              contract: '50-writing/README.md#knowledge',
+            }));
+          }
+        }
+        const snapshots = asArray(ledgerRow.knowledge_state).filter((x) => x && typeof x === 'object');
+        const snap = validateKnowledgeSnapshot(snapshots, expected, { chapterNo: displayNo, path: 'ledger.json#chapters[' + displayNo + '].knowledge_state' });
+        for (const e of snap.errors) errors.push(v2Error(e.code, { ...e, contract: '50-writing/README.md#knowledge' }));
+        for (const w of snap.warnings) warnings.push(v2Error(w.code, { ...w, severity: 'warning', contract: '50-writing/README.md#knowledge' }));
+      }
+    }
+    const outline = outlines.get(id);
+    const chapter = outline && outline.chapter || {};
+    const hard = chapter.hard_constraints || (outline && outline.hard_constraints) || {};
+    const must = asArray(hard.must_write || chapter.must_write);
+    for (const phrase of must) {
+      if (!hasAnyKeyword(text, phrase)) {
+        errors.push(v2Error('WRITING_MUST_WRITE', {
+          path: 'chapters/' + chapterFileName(displayNo),
+          message: '正文没有覆盖细纲必须写的内容：' + phrase,
+          contract: '50-writing/README.md#writing',
+          reference: '40-rhythm/outlines/' + id + '.json#chapter.hard_constraints.must_write',
+        }));
+      }
+    }
+    const mustNot = asArray(hard.must_not_write || chapter.must_not_write);
+    for (const phrase of mustNot) {
+      const textPhrase = String(phrase || '').trim();
+      if (textPhrase.length >= 4 && text.includes(textPhrase)) {
+        errors.push(v2Error('WRITING_MUST_NOT_WRITE', {
+          path: 'chapters/' + chapterFileName(displayNo),
+          message: '正文出现细纲明确禁止的内容：' + textPhrase,
+          contract: '50-writing/README.md#writing',
+          reference: '40-rhythm/outlines/' + id + '.json#chapter.hard_constraints.must_not_write',
+        }));
+      }
+    }
+  }
+
+  if (written === 0) {
+    errors.push(v2Error('WRITING_EMPTY', {
+      path: 'chapters',
+      message: '当前没有任何正文文件。',
+      contract: '50-writing/README.md#writing',
+    }));
+  }
+
+  return { ok: errors.length === 0, errors, warnings, data: writing };
+}
+
+export function renderLedgerRow(projectRoot, chapter, text, ledgerRow) {
+  return ledgerRow;
+}