dsh-maoying 0.1.11 → 0.1.13

package/lib/epub.mjs

@@ -37,12 +37,19 @@ export function crc32(buf) {
   return (c ^ -1) >>> 0
 }
 
-/** 转 DOS 时间（zip 头用，本地时区；秒精度 2 秒一档）。 */
-function dosDateTime(date) {
+/**
+ * 转 DOS 时间（zip 头用，本地时区；秒精度 2 秒一档）。导出仅为测试可直接
+ * 断言 1980 纪元等边界。
+ */
+export function dosDateTime(date) {
   const time =
     ((date.getHours() & 0x1f) << 11) | ((date.getMinutes() & 0x3f) << 5) | ((date.getSeconds() >> 1) & 0x1f)
+  // 年份下限 clamp 到 1980：DOS 时间纪元从 1980 年起、年份只存 7 位，更早的
+  // 系统时钟（或被拨错的机器时间）会按无符号位回绕映射成 2107+ 的「未来」，
+  // 统一按 1980 处理保证 zip 头时间不早于纪元。
+  const year = Math.max(date.getFullYear(), 1980)
   const day =
-    (((date.getFullYear() - 1980) & 0x7f) << 9) | (((date.getMonth() + 1) & 0xf) << 5) | (date.getDate() & 0x1f)
+    (((year - 1980) & 0x7f) << 9) | (((date.getMonth() + 1) & 0xf) << 5) | (date.getDate() & 0x1f)
   return { time, day }
 }
 
@@ -111,11 +118,17 @@ export function buildZip(entries) {
 }
 
 /**
- * XML 文本转义：& 必须先转（否则把刚生成的 &amp; 又转一遍），再 < >。
- * 章节正文与标题里出现的都过这里；属性值一律用生成的 ASCII 名，不走它。
+ * XML 文本转义：& 必须先转（否则把刚生成的 &amp; 又转一遍），再 < > 与引号。
+ * 章节正文与标题里出现的都过这里；属性值一律用生成的 ASCII 名不走它，引号
+ * 转义属防御纵深（将来属性值万一改走用户输入也不破 XML）。
  */
 export function escapeXml(text) {
-  return String(text ?? '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+  return String(text ?? '')
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;')
 }
 
 /** XML 声明 + DOCTYPE 头：三个 XHTML 文件共用。 */
@@ -151,6 +164,12 @@ function chapFile(index) {
 
 /** content.opf：元数据 + manifest + spine。uuid 由调用方给（randomUUID）。 */
 function contentOpf({ title, author, uuid, chapters, modified }) {
+  // uuid 只接受 36 位 hex-dash 形状（即 crypto.randomUUID() 的产物）：它不经
+  // 转义直接内插进 XML，入前形状校验是调用方契约的硬保证——脏数据在这里
+  // 炸出中文报错，而不是产出被注入的 OPF。
+  if (typeof uuid !== 'string' || !/^[0-9a-f-]{36}$/i.test(uuid)) {
+    throw new TypeError(`buildEpub: uuid 必须是 36 位 UUID 字符串（crypto.randomUUID() 产物），实得「${String(uuid)}」`)
+  }
   const manifestItems = chapters
     .map((_, i) => `    <item id="c${String(i + 1).padStart(2, '0')}" href="${chapFile(i)}" media-type="application/xhtml+xml"/>`)
     .join('\n')
@@ -224,6 +243,18 @@ ${paragraphs}
  *   chapters      [{ heading, paragraphs }]，顺序即 spine 顺序
  */
 export function buildEpub({ title, author, uuid, chapters }) {
+  // 形状兜底：chapters 必须是数组，且每章 paragraphs 必须是段落数组——上游
+  // （章节解析侧）形状漂移时在这里给出带章号的中文报错，而不是抛 undefined
+  // 调 .map 的 TypeError 原始栈。
+  if (!Array.isArray(chapters)) {
+    throw new TypeError(`buildEpub: chapters 必须是章节数组（[{ heading, paragraphs }]），实得 ${typeof chapters}`)
+  }
+  chapters.forEach((chapter, i) => {
+    if (!chapter || typeof chapter !== 'object' || !Array.isArray(chapter.paragraphs)) {
+      const got = chapter?.paragraphs === null ? 'null' : typeof chapter?.paragraphs
+      throw new TypeError(`buildEpub: 第 ${i + 1} 章（${chapter?.heading ?? '无标题'}）的 paragraphs 必须是段落数组，实得 ${got}`)
+    }
+  })
   const modified = `${new Date().toISOString().replace(/\.\d{3}Z$/, '')}Z`
   const entries = [
     // mimetype 必须第一个条目且 stored、内容不带换行——EPUB 规范的身份证

package/lib/novel-parse.mjs

@@ -24,9 +24,11 @@ export const CHAPTER_STATUSES = [
   ['accepted', '已定稿'],
 ]
 
-const CJK_RE = /[\u4e00-\u9fff\u3400-\u4dbf]/g
+// CJK 计数范围：基本区 + 扩展 A + 扩展 B（\u{20000}-\u{2A6DF}）。扩展 B 在增补
+// 平面，必须带 u 标志按码点匹配——网文生僻字（如「𠮷」）此前会被漏计。
+const CJK_RE = /[\u4e00-\u9fff\u3400-\u4dbf\u{20000}-\u{2a6df}]/gu
 
-/** CJK 字符计数（基本区 + 扩展 A 区，覆盖常用汉字）。 */
+/** CJK 字符计数（基本区 + 扩展 A/B 区，含增补平面生僻字）。 */
 export function countCjk(text) {
   const matches = String(text ?? '').match(CJK_RE)
   return matches === null ? 0 : matches.length
@@ -34,7 +36,9 @@ export function countCjk(text) {
 
 /**
  * 行内注释剥除：`#` 只有出现在行首或空白之后才算注释；单双引号内的 # 原样
- * 保留（双引号内 \" 是转义引号，翻转前回看前一字符）。
+ * 保留（双引号内 \" 是转义引号——判定看引号前连续反斜杠的奇偶：成对说明
+ * 反斜杠自身被转义、引号是收尾引号；只回看一个字符会把 "a\\" 的收尾引号
+ * 误判成转义，导致注释剥不掉）。
  */
 export function stripInlineComment(line) {
   let inSingle = false
@@ -46,7 +50,11 @@ export function stripInlineComment(line) {
       continue
     }
     if (inDouble) {
-      if (c === '"' && line[i - 1] !== '\\') inDouble = false
+      if (c === '"') {
+        let slashes = 0
+        for (let j = i - 1; j >= 0 && line[j] === '\\'; j--) slashes++
+        if (slashes % 2 === 0) inDouble = false
+      }
       continue
     }
     if (c === "'") inSingle = true
@@ -96,11 +104,9 @@ export function parseFlatYamlArray(text) {
   if (first.startsWith('-')) {
     const arr = []
     let current = null
-    let bare = false
     const flush = () => {
       if (current !== null) arr.push(current)
       current = null
-      bare = false
     }
     for (const line of lines) {
       const trimmed = line.trim()
@@ -113,7 +119,6 @@ export function parseFlatYamlArray(text) {
           current[m[1].trim()] = parseScalarText(m[2])
         } else {
           arr.push(parseScalarText(rest)) // 裸标量条目
-          bare = true
         }
       } else if (trimmed === '-') {
         flush()
@@ -124,7 +129,7 @@ export function parseFlatYamlArray(text) {
       }
     }
     flush()
-    return bare || arr.length > 0 ? arr : []
+    return arr // 原式 `bare || arr.length > 0 ? arr : []` 恒等于 arr，删简
   }
   // 平键映射
   const map = {}
@@ -149,27 +154,34 @@ export function parseFlatYamlArray(text) {
  * `---` 之后的正文（去首个空行）。只切不解析，解析交给上层。
  */
 export function splitFrontmatter(text) {
-  const open = /^---[ \t]*\r?\n/.exec(text)
+  // 带 BOM 的文件开头是 \uFEFF，会让下面的开头围栏正则失配 → frontmatter 整体
+  // 静默失效（meta 全空、check 全报缺键）。解析入口先剥 BOM：bom 作统一偏移，
+  // index 仍按原文计（+1 补回），保住「raw === text.slice(index, index + raw.length)」
+  // 的契约——写侧行级手术（panel-core 用 fence.index 拼接替换）不能错位。
+  const bom = text.charCodeAt(0) === 0xfeff ? 1 : 0
+  const rest = bom === 0 ? text : text.slice(1)
+  const open = /^---[ \t]*\r?\n/.exec(rest)
   if (open === null) return { raw: null, index: -1, body: text }
   const rawStart = open[0].length
-  const close = /\r?\n---[ \t]*(?:\r?\n|$)/.exec(text.slice(rawStart))
+  const close = /\r?\n---[ \t]*(?:\r?\n|$)/.exec(rest.slice(rawStart))
   if (close === null) return { raw: null, index: -1, body: text }
   return {
-    raw: text.slice(rawStart, rawStart + close.index),
-    index: rawStart,
-    body: text.slice(rawStart + close.index + close[0].length).replace(/^\r?\n/, ''),
+    raw: text.slice(rawStart + bom, rawStart + bom + close.index),
+    index: rawStart + bom,
+    body: text.slice(rawStart + bom + close.index + close[0].length).replace(/^\r?\n/, ''),
   }
 }
 
 /**
  * 解析章节文件：`---` 围栏 frontmatter（简单键值，一行一个）+ body。
- * 无围栏时全部按 body 处理。
+ * 无围栏时全部按 body 处理。raw 为围栏内原文（check 侧扫重复键用），无围栏
+ * 时为 null。
  */
 export function parseChapterFile(text) {
   const { raw, body } = splitFrontmatter(text)
-  if (raw === null) return { meta: {}, body }
+  if (raw === null) return { meta: {}, body, raw: null }
   const meta = parseFlatYamlArray(raw)
-  return { meta: meta !== null && typeof meta === 'object' && !Array.isArray(meta) ? meta : {}, body }
+  return { meta: meta !== null && typeof meta === 'object' && !Array.isArray(meta) ? meta : {}, body, raw }
 }
 
 /** 从文件名取排序键：v01-c001.md → { vol: 1, num: 1 }；不合规范的文件返回 null。 */
@@ -178,19 +190,29 @@ export function chapterSortKey(stem) {
   return m === null ? null : { vol: Number(m[1]), num: Number(m[2]) }
 }
 
+/**
+ * 「列目录下 .md + numeric 感知名称序」在 collectChapters / listOutlines /
+ * checkProject 出现三次，收敛到这里。目录不存在给 []（调用方按需先判存在）。
+ */
+function listMdFiles(dir) {
+  if (!existsSync(dir)) return []
+  return readdirSync(dir)
+    .filter((f) => f.endsWith('.md'))
+    .sort((a, b) => a.localeCompare(b, undefined, { numeric: true }))
+}
+
 /** 章节五维叙事字段的 frontmatter 键名（值一律中文句子）。 */
 export const FIVE_DIM_KEYS = ['cognitive_frame', 'emotional_anchor', 'world_texture', 'suspense', 'interpersonal_tension']
 
-/** 收集章节：读取 chapters/*.md，按卷号+章号升序。目录不存在返回 null。 */
+/** 收集章节：读取 chapters/*.md，按卷号+章号升序（文件名不合规范的杂散文件沉底）。目录不存在返回 null。 */
 export function collectChapters(root) {
   const chaptersDir = path.join(root, 'chapters')
   if (!existsSync(chaptersDir)) return null
-  const files = readdirSync(chaptersDir)
-    .filter((f) => f.endsWith('.md'))
-    .sort((a, b) => a.localeCompare(b, undefined, { numeric: true }))
+  const files = listMdFiles(chaptersDir)
   const chapters = []
   for (const file of files) {
     const stem = file.slice(0, -3)
+    const key = chapterSortKey(stem) // 排序键一次算好——volume/num/sortKey 三个字段都要用
     let text = null
     try {
       text = readFileSync(path.join(chaptersDir, file), 'utf8')
@@ -202,9 +224,9 @@ export function collectChapters(root) {
     chapters.push({
       file,
       stem,
-      sortKey: chapterSortKey(stem),
-      volume: typeof meta.volume === 'string' && meta.volume !== '' ? meta.volume : (chapterSortKey(stem) ? `v${String(chapterSortKey(stem).vol).padStart(2, '0')}` : ''),
-      num: Number.isInteger(meta.num) ? meta.num : (chapterSortKey(stem) ? chapterSortKey(stem).num : null),
+      sortKey: key,
+      volume: typeof meta.volume === 'string' && meta.volume !== '' ? meta.volume : (key !== null ? canonicalVolume(key.vol) : ''),
+      num: Number.isInteger(meta.num) ? meta.num : (key !== null ? key.num : null),
       title: typeof meta.title === 'string' && meta.title !== '' ? meta.title : '（无标题）',
       status,
       summary: typeof meta.summary === 'string' ? meta.summary : '',
@@ -217,6 +239,10 @@ export function collectChapters(root) {
     if (a.sortKey !== null && b.sortKey !== null) {
       return a.sortKey.vol !== b.sortKey.vol ? a.sortKey.vol - b.sortKey.vol : a.sortKey.num - b.sortKey.num
     }
+    // 文件名不合规范的杂散 .md 一律沉底（与 listOutlines 同策略）——否则会排
+    // 在正常章之前，混进导出并污染 brief 的「前章」链。
+    if (a.sortKey !== null) return -1
+    if (b.sortKey !== null) return 1
     return a.stem.localeCompare(b.stem, undefined, { numeric: true })
   })
   return chapters
@@ -227,7 +253,10 @@ export function collectChapters(root) {
 /**
  * 流式上下文里的标量落盘：数字直写；字符串在含 YAML 结构字符（流式项分隔、
  * 键值形态、起首指示符、注释引入、首尾空白、控制字符）时按 JSON 双引号落值
- * （JSON 字符串即合法 YAML 双引号标量），否则保持原文。
+ * （JSON 字符串即合法 YAML 双引号标量）；裸写会被 YAML 读成数字/布尔的串
+ * （'1984'、'true'、'3.14' 这类类型漂移）同样要引起来——落值前用自家
+ * parseScalarText 试解析，结果 !== 原串（类型或值变了）即按 JSON 引号落值，
+ * 保证读回来自始至终是字符串。
  */
 export function flowScalar(value) {
   if (typeof value === 'number' && Number.isFinite(value)) return String(value)
@@ -241,7 +270,8 @@ export function flowScalar(value) {
     /\s[:#]/.test(s) ||
     /^\s|\s$/.test(s) ||
     /[\x00-\x1f]/.test(s)
-  return unsafe ? JSON.stringify(s) : s
+  if (unsafe) return JSON.stringify(s)
+  return parseScalarText(s) !== s ? JSON.stringify(s) : s
 }
 
 /** 章节一行条目（flow mapping，num/title/status/words/summary 一行）。 */
@@ -305,8 +335,8 @@ export function buildIndexYaml(chapters, volumesRaw) {
 
 const OUTLINES_DIR = 'outlines'
 
-/** 读文本文件；读不到返回 null（本模块私有助手，与 bin 侧同名函数同语义）。 */
-function readTextOrNull(file) {
+/** 读文本文件；读不到返回 null（导出供 bin 等其他文件复用，与 bin 侧本地副本同语义）。 */
+export function readTextOrNull(file) {
   try {
     return readFileSync(file, 'utf8')
   } catch {
@@ -335,10 +365,8 @@ export function readOutline(novelDir, chapterFile) {
 /** 列出全部章纲 [{ file, chapter, words }]，按章号升序（不合文件名规范的排最后，按名称序）。 */
 export function listOutlines(novelDir) {
   const dir = path.join(novelDir, OUTLINES_DIR)
-  if (!existsSync(dir)) return []
   const outlines = []
-  for (const file of readdirSync(dir)) {
-    if (!file.endsWith('.md')) continue
+  for (const file of listMdFiles(dir)) {
     const stem = file.slice(0, -3)
     const text = readTextOrNull(path.join(dir, file))
     if (text === null) continue
@@ -355,6 +383,14 @@ export function listOutlines(novelDir) {
   return outlines
 }
 
+/**
+ * 只数 outlines/ 下的 .md 个数，不读内容。checkProject 的数纲数只需要个数，
+ * 走 listOutlines 会把每份章纲全文读进来做 CJK 计数——纯浪费。
+ */
+function countOutlineFiles(novelDir) {
+  return listMdFiles(path.join(novelDir, OUTLINES_DIR)).length
+}
+
 // ── 写作卡 brief（五期 §9.6）────────────────────────────────────────────────
 //
 // 把一章的写作输入打成一个 md（章纲 + 前章结尾 + 出场角色卡 + 活跃伏笔 +
@@ -400,18 +436,21 @@ function collectCharacterCards(novelDir) {
     if (!file.endsWith('.md')) continue
     const text = readTextOrNull(path.join(dir, file))
     if (text === null) continue
-    const { meta, body } = parseChapterFile(text)
-    cards.push({ slug: file.slice(0, -3), file: `characters/${file}`, meta, body })
+    const { meta, body, raw } = parseChapterFile(text)
+    cards.push({ slug: file.slice(0, -3), file: `characters/${file}`, meta, body, raw })
   }
   cards.sort((a, b) => a.slug.localeCompare(b.slug))
   return cards
 }
 
-/** 顶层数组 yml 读取：文件缺失、解析失败或非数组一律给 []（条目只留对象）。 */
+/** 顶层数组 yml 读取：文件缺失、解析失败或非数组一律给 []（条目只留对象）。
+ * `-` 空条目后跟裸标量（`-\n- foo`）会被解析成无任何自有键的空对象，一并过滤。 */
 function readYamlArray(novelDir, name) {
   const raw = parseFlatYamlArray(readTextOrNull(path.join(novelDir, name)))
   if (!Array.isArray(raw)) return []
-  return raw.filter((item) => item !== null && typeof item === 'object' && !Array.isArray(item))
+  return raw.filter(
+    (item) => item !== null && typeof item === 'object' && !Array.isArray(item) && Object.keys(item).length > 0,
+  )
 }
 
 /**
@@ -675,6 +714,32 @@ function canonicalVolume(vol) {
   return `v${String(vol).padStart(2, '0')}`
 }
 
+/**
+ * 扫 frontmatter 原文找重复键：解析器对重复键 last-wins（宽容不炸），但静默
+ * 覆盖会藏「改了前一个没生效」的困惑，check 侧给 warn 提醒。判定口径与
+ * parseFlatYamlArray 的平键分支对齐：只认零缩进键，键名去首尾引号。
+ */
+function findDuplicateFrontmatterKeys(raw) {
+  if (raw === null) return []
+  const seen = new Set()
+  const dups = []
+  for (const line of raw.split(/\r?\n/)) {
+    const cleaned = stripInlineComment(line)
+    const trimmed = cleaned.trim()
+    if (trimmed === '' || trimmed.startsWith('#')) continue
+    const indent = cleaned.match(/^[ \t]*/)[0].length
+    const m = /^([^:]+):/.exec(trimmed)
+    if (m === null || indent !== 0) continue
+    const key = m[1].trim().replace(/^['"]|['"]$/g, '')
+    if (seen.has(key)) {
+      if (!dups.includes(key)) dups.push(key)
+    } else {
+      seen.add(key)
+    }
+  }
+  return dups
+}
+
 /**
  * 账本里的章节引用是否存在：认 stem（v01-c001，含不补零写法）与裸章号。
  * 空值视为「未填」，不算悬空。
@@ -691,6 +756,21 @@ function chapterRefExists(ref, stems, nums) {
   return false
 }
 
+/**
+ * 章节引用转可比较的序数 {vol, num}：认 v01-c002（含不补零写法）、「卷-章」
+ * 与裸章号（裸章号无卷信息，卷号记 0，仅用于与带卷引用的近似比较）。
+ * 只做格式解析、不查存在性——expected_resolve 的排期承诺口径用它。
+ */
+function parseChapterRefOrdinal(ref) {
+  const raw = String(ref ?? '').trim().replace(/[－—–]/g, '-').replace(/\.md$/i, '')
+  let m = /^[vV](\d+)-c(\d+)$/.exec(raw)
+  if (m !== null) return { vol: Number(m[1]), num: Number(m[2]) }
+  m = /^(\d+)-(\d+)$/.exec(raw)
+  if (m !== null) return { vol: Number(m[1]), num: Number(m[2]) }
+  if (/^\d+$/.test(raw)) return { vol: 0, num: Number(raw) }
+  return null
+}
+
 /** 时间线年份还原：数字直用；字符串抓第一段数字；抓不到返回 null。 */
 function parseTimelineYear(year) {
   if (typeof year === 'number' && Number.isFinite(year)) return year
@@ -710,11 +790,7 @@ export function checkProject(novelDir) {
 
   // —— chapters/：frontmatter 完整性、枚举、章号卷号一致 ——
   const chaptersDir = path.join(novelDir, 'chapters')
-  const chapterFiles = existsSync(chaptersDir)
-    ? readdirSync(chaptersDir)
-        .filter((f) => f.endsWith('.md'))
-        .sort((a, b) => a.localeCompare(b, undefined, { numeric: true }))
-    : []
+  const chapterFiles = listMdFiles(chaptersDir)
   if (!existsSync(chaptersDir)) push('error', 'chapters/', '找不到 chapters/ 目录——先跑 maoying init')
 
   const stems = new Set()
@@ -729,12 +805,20 @@ export function checkProject(novelDir) {
       push('warn', rel, '文件名不合规范（应为 v<卷号2位>-c<章号3位>.md），章纲与账本对不上它')
     }
     let meta = {}
+    let fmRaw = null
     try {
-      meta = parseChapterFile(readFileSync(path.join(chaptersDir, file), 'utf8')).meta
+      const parsed = parseChapterFile(readFileSync(path.join(chaptersDir, file), 'utf8'))
+      meta = parsed.meta
+      fmRaw = parsed.raw
     } catch {
       push('error', rel, '章节文件读取失败')
       continue
     }
+    // 重复键：解析保持 last-wins 宽容，但静默覆盖值得提醒（角色卡同理，见 characters 段）
+    const dupKeys = findDuplicateFrontmatterKeys(fmRaw)
+    if (dupKeys.length > 0) {
+      push('warn', rel, `frontmatter 重复键（解析时后者覆盖前者）：${dupKeys.join('、')}`)
+    }
     for (const k of REQUIRED_CHAPTER_KEYS) {
       if (meta[k] === undefined || meta[k] === '') push('error', rel, `frontmatter 缺少必填键 ${k}`)
     }
@@ -750,8 +834,14 @@ export function checkProject(novelDir) {
       if (typeof meta.volume === 'string' && meta.volume !== '' && meta.volume !== expectedVolume) {
         push('error', rel, `frontmatter volume（${meta.volume}）与文件名卷号（${expectedVolume}）不一致`)
       }
-      if (meta.num !== undefined && meta.num !== '' && meta.num !== key.num) {
-        push('error', rel, `frontmatter num（${meta.num}）与文件名章号（${key.num}）不一致`)
+      // num 常被手写成 '3' 这类单引号字符串：比较前按 Number() 归一（与
+      // collectChapters 的宽容口径对齐），转不出数字（NaN）时维持严格不等判断。
+      if (meta.num !== undefined && meta.num !== '') {
+        const parsedNum = Number(meta.num)
+        const mismatch = Number.isNaN(parsedNum) ? meta.num !== key.num : parsedNum !== key.num
+        if (mismatch) {
+          push('error', rel, `frontmatter num（${meta.num}）与文件名章号（${key.num}）不一致`)
+        }
       }
     }
     if (typeof meta.writer === 'string' && meta.writer !== '' && !CHAPTER_WRITERS.includes(meta.writer)) {
@@ -759,7 +849,7 @@ export function checkProject(novelDir) {
     }
   }
 
-  // —— foreshadows.yml：章号引用存在性、状态枚举、id 去重 ——
+  // —— foreshadows.yml：状态枚举、id 去重、章节引用、状态-字段自洽 ——
   const foreshadows = readYamlArray(novelDir, 'foreshadows.yml')
   const seenIds = new Map()
   foreshadows.forEach((f, i) => {
@@ -771,13 +861,44 @@ export function checkProject(novelDir) {
       if (seenIds.has(f.id)) push('error', 'foreshadows.yml', `伏笔 id 重复：${f.id}（第 ${seenIds.get(f.id) + 1} 条与第 ${i + 1} 条）`)
       else seenIds.set(f.id, i)
     }
-    for (const k of ['planted_chapter', 'expected_resolve', 'resolved_chapter']) {
+    // 埋设/回收章是已发生的事实，必须指向已写出的章（空值在此跳过——resolved
+    // 缺兑现章属于「漏规则」，在下面单查）。
+    for (const k of ['planted_chapter', 'resolved_chapter']) {
       const ref = f[k]
       if ((typeof ref !== 'string' || ref.trim() === '') && typeof ref !== 'number') continue
       if (!chapterRefExists(ref, stems, nums)) {
         push('error', 'foreshadows.yml', `伏笔 ${label} 的 ${k} 引用章节不存在：${ref}`)
       }
     }
+    // expected_resolve 是排期承诺（docs/spec.md）：目标章天然多数尚未写出，
+    // 只查格式合法性（能解析出卷/章），不查存在性——按官方模板排到未来章号
+    // 不该报「引用章节不存在」。
+    const expected = f.expected_resolve
+    if ((typeof expected === 'string' && expected.trim() !== '') || typeof expected === 'number') {
+      if (parseChapterRefOrdinal(expected) === null) {
+        push('error', 'foreshadows.yml', `伏笔 ${label} 的 expected_resolve 格式不合法：${expected}（应为 v<卷>-c<章>、「卷-章」或裸章号）`)
+      } else if (f.status === 'planted' && chapterRefExists(expected, stems, nums)) {
+        // 反向提醒：排期目标章已写出却还停在埋设态，多半是忘了登记推进/回收
+        push('warn', 'foreshadows.yml', `伏笔 ${label} 的 expected_resolve（${expected}）指向的章节已写出，但 status 仍为 planted——确认是否漏登记推进/回收`)
+      }
+    }
+    // docs/spec.md：resolved 回收时 resolved_chapter 必填
+    const resolvedRef = f.resolved_chapter
+    const resolvedEmpty =
+      resolvedRef === undefined || resolvedRef === null || (typeof resolvedRef === 'string' && resolvedRef.trim() === '')
+    if (f.status === 'resolved' && resolvedEmpty) {
+      push('error', 'foreshadows.yml', `伏笔 ${label} status 为 resolved 但未填 resolved_chapter（回收必须登记兑现章）`)
+    }
+    // docs/spec.md：resolved_chapter 不得早于 planted_chapter（两章号均可解析才比）
+    const plantedOrd = parseChapterRefOrdinal(f.planted_chapter)
+    const resolvedOrd = parseChapterRefOrdinal(resolvedRef)
+    if (
+      plantedOrd !== null &&
+      resolvedOrd !== null &&
+      (resolvedOrd.vol < plantedOrd.vol || (resolvedOrd.vol === plantedOrd.vol && resolvedOrd.num < plantedOrd.num))
+    ) {
+      push('error', 'foreshadows.yml', `伏笔 ${label} 的 resolved_chapter（${resolvedRef}）早于 planted_chapter（${f.planted_chapter}）`)
+    }
   })
 
   // —— timeline.yml：年份可解析、不倒挂（warn：故事内纪年本就允许花写）——
@@ -811,11 +932,15 @@ export function checkProject(novelDir) {
     }
   })
 
-  // —— characters/*.md：name 缺失是硬伤 ——
+  // —— characters/*.md：name 缺失是硬伤；重复键给 warn ——
   for (const card of cards) {
     if (typeof card.meta.name !== 'string' || card.meta.name.trim() === '') {
       push('error', card.file, '角色卡缺少 name')
     }
+    const dupKeys = findDuplicateFrontmatterKeys(card.raw)
+    if (dupKeys.length > 0) {
+      push('warn', card.file, `frontmatter 重复键（解析时后者覆盖前者）：${dupKeys.join('、')}`)
+    }
   }
 
   // —— project.yml：mode 枚举 ——
@@ -829,7 +954,7 @@ export function checkProject(novelDir) {
 
   const summary = {
     chapters: chapterFiles.length,
-    outlines: listOutlines(novelDir).length,
+    outlines: countOutlineFiles(novelDir), // 只列目录计数，不为数数把章纲全文读进来
     foreshadows: foreshadows.length,
     problems: {
       error: problems.filter((p) => p.level === 'error').length,