dsh-maoying 0.1.20 → 0.1.21

package/lib/epub.mjs

@@ -121,9 +121,15 @@ export function buildZip(entries) {
  * XML 文本转义：& 必须先转（否则把刚生成的 &amp; 又转一遍），再 < > 与引号。
  * 章节正文与标题里出现的都过这里；属性值一律用生成的 ASCII 名不走它，引号
  * 转义属防御纵深（将来属性值万一改走用户输入也不破 XML）。
+ *
+ * L8：XML 1.0 非法控制字符（\x00-\x08、\x0B、\x0C、\x0E-\x1F；\t \n \r 合法
+ * 保留）先替换为 U+FFFD 再转义——混入即产非法 XHTML，阅读器可能拒载整本。
+ * 选替换不选剥离：脏字符多半是复制粘贴事故，U+FFFD 给作者与阅读器留下
+ * 「这里有脏字符」的可见痕迹，静默剥除会无声丢字。
  */
 export function escapeXml(text) {
   return String(text ?? '')
+    .replace(/[\x00-\x08\x0B\x0C\x0E-\x1F]/g, '\uFFFD')
     .replace(/&/g, '&amp;')
     .replace(/</g, '&lt;')
     .replace(/>/g, '&gt;')

package/lib/novel-parse.mjs

@@ -106,15 +106,21 @@ export function parseScalarText(raw) {
  *   - 顶层数组（volumes.yml / foreshadows.yml 等）：`- key: value` 起条目，
  *     缩进行补键；裸 `- 标量` 收作字符串条目。
  * 深嵌套不在支持范围（数据规范本身就禁止）。解析不了返回 null。
+ *
+ * H2：onWarn（可选回调）接收「认不出但没炸」的行告警——目前只有数组分支的
+ * 零缩进散键行一种；调用方（panel-core collectArrayYml / checkProject /
+ * buildBrief）把消息各自挂上文件名再入自家告警通道，散键不再静默蒸发。
  */
-export function parseFlatYamlArray(text) {
+export function parseFlatYamlArray(text, onWarn = null) {
   if (text === null) return null
   const lines = []
-  for (const raw of text.split(/\r?\n/)) {
+  const lineNos = [] // 源行号随行登记：散键告警要能定位到文件行
+  text.split(/\r?\n/).forEach((raw, i) => {
     const line = stripInlineComment(raw).replace(/\s+$/, '')
-    if (line.trim() === '' || line.trim().startsWith('#')) continue
+    if (line.trim() === '' || line.trim().startsWith('#')) return
     lines.push(line)
-  }
+    lineNos.push(i + 1)
+  })
   if (lines.length === 0) return null
   const first = lines[0].trim()
   if (first === '[]') return []
@@ -126,7 +132,8 @@ export function parseFlatYamlArray(text) {
       if (current !== null) arr.push(current)
       current = null
     }
-    for (const line of lines) {
+    for (let li = 0; li < lines.length; li++) {
+      const line = lines[li]
       const trimmed = line.trim()
       if (trimmed.startsWith('- ')) {
         flush()
@@ -141,6 +148,11 @@ export function parseFlatYamlArray(text) {
       } else if (trimmed === '-') {
         flush()
         current = {}
+      } else if (!/^[ \t]/.test(line)) {
+        // H2：数组形态里零缩进、非「-」起头的散键行不属于任何条目——旧实现会
+        // 静默并入前一条目，手改残留键能覆盖前条 status 且零告警。丢弃并告警
+        // （顶层纯键值不经过本分支——那是合法映射形态）。
+        if (onWarn !== null) onWarn(`第 ${lineNos[li]} 行零缩进散键「${trimmed}」不属于任何条目，已丢弃`)
       } else if (current !== null) {
         const m = /^([^:]+):\s*(.*)$/.exec(trimmed)
         if (m !== null) current[m[1].trim()] = parseScalarText(m[2])
@@ -215,7 +227,9 @@ export function chapterSortKey(stem) {
 function listMdFiles(dir) {
   if (!existsSync(dir)) return []
   return readdirSync(dir)
-    .filter((f) => f.endsWith('.md'))
+    // M10：.md 大小写不敏感（/\.md$/i）——panel-core 的 collectOutlines /
+    // collectMdEntities 同口径收录 .MD，CLI 侧不得把同一批文件漏在门外
+    .filter((f) => /\.md$/i.test(f))
     .sort((a, b) => a.localeCompare(b, undefined, { numeric: true }))
 }
 
@@ -317,6 +331,9 @@ export function buildIndexYaml(chapters, volumesRaw) {
   if (volumes.length === 0) lines.push('  []')
   for (const volume of volumes) {
     const id = String(volume.id ?? '')
+    // M8：重复 id 不在此处去重——index 重建是确定性纯函数、静默择一反而把数据
+    // 问题藏进产物；重复 id 由 checkProject 报 error 兜底，源头修 volumes.yml
+    // （claimed 用 Set，同批章节重复入卷只影响卷内字数之和，orphans 不受影响）。
     const members = chapters.filter((ch) => ch.volume === id)
     for (const ch of members) claimed.add(ch.stem)
     lines.push(`  - id: ${flowScalar(id || '（缺 id）')}`)
@@ -451,7 +468,8 @@ function collectCharacterCards(novelDir) {
   if (!existsSync(dir)) return []
   const cards = []
   for (const file of readdirSync(dir)) {
-    if (!file.endsWith('.md')) continue
+    // M10：口径与 listMdFiles 一致——.MD 大小写不敏感（面板实体卡目录收录同款文件）
+    if (!/\.md$/i.test(file)) continue
     const text = readTextOrNull(path.join(dir, file))
     if (text === null) continue
     const { meta, body, raw } = parseChapterFile(text)
@@ -462,9 +480,11 @@ function collectCharacterCards(novelDir) {
 }
 
 /** 顶层数组 yml 读取：文件缺失、解析失败或非数组一律给 []（条目只留对象）。
- * `-` 空条目后跟裸标量（`-\n- foo`）会被解析成无任何自有键的空对象，一并过滤。 */
-function readYamlArray(novelDir, name) {
-  const raw = parseFlatYamlArray(readTextOrNull(path.join(novelDir, name)))
+ * `-` 空条目后跟裸标量（`-\n- foo`）会被解析成无任何自有键的空对象，一并过滤。
+ * onWarn（H2）透传给 parseFlatYamlArray 收散键丢弃告警，消息不含文件名，
+ * 由调用方按需挂（checkProject 入 problems、buildBrief 入 warnings）。 */
+function readYamlArray(novelDir, name, onWarn = null) {
+  const raw = parseFlatYamlArray(readTextOrNull(path.join(novelDir, name)), onWarn)
   if (!Array.isArray(raw)) return []
   return raw.filter(
     (item) => item !== null && typeof item === 'object' && !Array.isArray(item) && Object.keys(item).length > 0,
@@ -606,8 +626,10 @@ export function buildBrief(novelDir, chapterRef, options = {}) {
   }
   const idx = chapters.findIndex((c) => c.stem === target.stem)
 
-  // 卷名：volumes.yml 的 title，缺了退「卷N」/卷 id
-  const volumesRaw = parseFlatYamlArray(readTextOrNull(path.join(novelDir, 'volumes.yml')))
+  // 卷名：volumes.yml 的 title，缺了退「卷N」/卷 id（H2：散键告警挂文件名入 warnings）
+  const volumesRaw = parseFlatYamlArray(readTextOrNull(path.join(novelDir, 'volumes.yml')), (w) =>
+    warnings.push(`volumes.yml: ${w}`),
+  )
   const volTitles = new Map()
   if (Array.isArray(volumesRaw)) {
     for (const v of volumesRaw) {
@@ -661,7 +683,7 @@ export function buildBrief(novelDir, chapterRef, options = {}) {
   // 出场角色卡：有章纲按章纲选人（卡名/ slug 命中 + 「出场角色：」行点名）；
   // 章纲缺失时回退「前章出场角色 + 主角」（主角判定见 protagonistCards 注释）
   const cards = collectCharacterCards(novelDir)
-  const relations = readYamlArray(novelDir, 'relations.yml')
+  const relations = readYamlArray(novelDir, 'relations.yml', (w) => warnings.push(`relations.yml: ${w}`))
   let roleCards = []
   let missingNames = []
   if (outline !== null) {
@@ -690,7 +712,7 @@ export function buildBrief(novelDir, chapterRef, options = {}) {
   // 活跃伏笔：status ∈ planted/progressing 的条目照录
   const hasForeshadowsFile = existsSync(path.join(novelDir, 'foreshadows.yml'))
   if (!hasForeshadowsFile) warnings.push('未找到 foreshadows.yml，活跃伏笔一节按空处理')
-  const activeForeshadows = readYamlArray(novelDir, 'foreshadows.yml').filter(
+  const activeForeshadows = readYamlArray(novelDir, 'foreshadows.yml', (w) => warnings.push(`foreshadows.yml: ${w}`)).filter(
     (f) => f.status === 'planted' || f.status === 'progressing',
   )
   const fsParts = activeForeshadows.map((f) => renderForeshadowBrief(f))
@@ -724,6 +746,15 @@ const CHAPTER_WRITERS = ['author', 'ai']
 /** 伏笔状态机枚举（docs/spec.md）。 */
 const FORESHADOW_STATUSES = ['planted', 'progressing', 'resolved', 'abandoned']
 
+/** 伏笔 source 枚举（templates/novel/foreshadows.yml 声明；缺省归 plan 不报）。 */
+const FORESHADOW_SOURCES = ['plan', 'backfill']
+
+/** clue-board.yml 的 kind 枚举（templates/novel/clue-board.yml 声明）。 */
+const CLUE_KINDS = ['clue', 'red-herring', 'deduction', 'question']
+
+/** memories.yml 的 category 枚举（templates/novel/memories.yml 声明）。 */
+const MEMORY_CATEGORIES = ['character', 'location', 'item', 'event', 'promise', 'appearance', 'arc', 'other']
+
 /** project.yml 的共创模式枚举（五期 §9.1）。 */
 const PROJECT_MODES = ['ai-draft', 'co-write', 'author-draft']
 
@@ -890,6 +921,16 @@ export function checkProject(novelDir) {
   const problems = []
   const push = (level, file, message) => problems.push({ level, file, message })
 
+  // H2：顶层数组账本 yml 的极简解析告警（零缩进散键被丢弃等）并入 problems——
+  // 与面板快照的 warnings 通道对齐，散键不能再静默蒸发。
+  const readAccountYml = (name) => readYamlArray(novelDir, name, (w) => push('warn', name, w))
+  // M9：账本章节引用统一校验——空值是「未填」不算悬空，指向未写章节报 error
+  // （口径与 foreshadows planted_chapter 的既有引用校验一致）。
+  const refCheck = (file, label, field, ref) => {
+    if ((typeof ref !== 'string' || ref.trim() === '') && typeof ref !== 'number') return
+    if (!chapterRefExists(ref, stems, nums)) push('error', file, `${label}的 ${field} 引用章节不存在：${ref}`)
+  }
+
   // —— chapters/：frontmatter 完整性、枚举、章号卷号一致 ——
   const chaptersDir = path.join(novelDir, 'chapters')
   const chapterFiles = listMdFiles(chaptersDir)
@@ -971,13 +1012,18 @@ export function checkProject(novelDir) {
   }
 
   // —— foreshadows.yml：状态枚举、id 去重、章节引用、状态-字段自洽 ——
-  const foreshadows = readYamlArray(novelDir, 'foreshadows.yml')
+  const foreshadows = readAccountYml('foreshadows.yml')
   const seenIds = new Map()
   foreshadows.forEach((f, i) => {
     const label = typeof f.id === 'string' && f.id !== '' ? f.id : `第 ${i + 1} 条`
     if (typeof f.status === 'string' && f.status !== '' && !FORESHADOW_STATUSES.includes(f.status)) {
       push('error', 'foreshadows.yml', `伏笔 ${label} status 越枚举：${f.status}（合法值 ${FORESHADOW_STATUSES.join('|')}）`)
     }
+    // M9：source 枚举（模板声明 plan|backfill）——缺省不报，面板快照侧同样把
+    // 非 backfill 归一成 plan，两侧口径一致
+    if (typeof f.source === 'string' && f.source !== '' && !FORESHADOW_SOURCES.includes(f.source)) {
+      push('error', 'foreshadows.yml', `伏笔 ${label} source 越枚举：${f.source}（合法值 ${FORESHADOW_SOURCES.join('|')}）`)
+    }
     if (typeof f.id === 'string' && f.id !== '') {
       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)
@@ -1039,10 +1085,26 @@ export function checkProject(novelDir) {
     }
   })
 
+  // —— volumes.yml：id 去重（M8：重复 id 会让同批章节被 filter 重复计入多个
+  // 卷，卷字数之和 ≠ total；写法对齐 foreshadows id 去重）——
+  const volumes = readAccountYml('volumes.yml')
+  const seenVolIds = new Map()
+  volumes.forEach((v, i) => {
+    if (typeof v.id === 'string' && v.id !== '') {
+      if (seenVolIds.has(v.id)) {
+        push('error', 'volumes.yml', `分卷 id 重复：${v.id}（第 ${seenVolIds.get(v.id) + 1} 条与第 ${i + 1} 条）——同 id 卷会把章节重复计入`)
+      } else {
+        seenVolIds.set(v.id, i)
+      }
+    }
+  })
+
   // —— timeline.yml：年份可解析、不倒挂（warn：故事内纪年本就允许花写）——
-  const timeline = readYamlArray(novelDir, 'timeline.yml')
+  const timeline = readAccountYml('timeline.yml')
   let prevYear = null
   timeline.forEach((t, i) => {
+    // M9：chapter 指向已写正文；放在年份解析之前，免得花写年份把引用校验跳过
+    refCheck('timeline.yml', `第 ${i + 1} 条时间线`, 'chapter', t.chapter)
     const parsed = parseTimelineYear(t.year)
     if (parsed === null) {
       push('warn', 'timeline.yml', `第 ${i + 1} 条 year 无法解析为数字：${t.year}`)
@@ -1054,14 +1116,34 @@ export function checkProject(novelDir) {
     prevYear = parsed
   })
 
+  // —— memories.yml：category 枚举 + source_chapter 引用（M9 补对称校验，
+  // 枚举以 templates/novel/memories.yml 声明为准）——
+  readAccountYml('memories.yml').forEach((m, i) => {
+    if (typeof m.category === 'string' && m.category !== '' && !MEMORY_CATEGORIES.includes(m.category)) {
+      push('error', 'memories.yml', `第 ${i + 1} 条记忆 category 越枚举：${m.category}（合法值 ${MEMORY_CATEGORIES.join('|')}）`)
+    }
+    refCheck('memories.yml', `第 ${i + 1} 条记忆`, 'source_chapter', m.source_chapter)
+  })
+
+  // —— clue-board.yml：kind 枚举 + related_chapter 引用（M9 补对称校验，
+  // 枚举以 templates/novel/clue-board.yml 声明为准）——
+  readAccountYml('clue-board.yml').forEach((c, i) => {
+    if (typeof c.kind === 'string' && c.kind !== '' && !CLUE_KINDS.includes(c.kind)) {
+      push('error', 'clue-board.yml', `第 ${i + 1} 条线索 kind 越枚举：${c.kind}（合法值 ${CLUE_KINDS.join('|')}）`)
+    }
+    refCheck('clue-board.yml', `第 ${i + 1} 条线索`, 'related_chapter', c.related_chapter)
+  })
+
   // —— relations.yml：a/b 角色有卡（warn：可能是已死亡/未建档角色，故不升 error）——
   const cards = collectCharacterCards(novelDir)
   const knownRoles = new Set(cards.map((c) => c.slug))
   for (const card of cards) {
     if (typeof card.meta.name === 'string' && card.meta.name !== '') knownRoles.add(card.meta.name)
   }
-  const relations = readYamlArray(novelDir, 'relations.yml')
+  const relations = readAccountYml('relations.yml')
   relations.forEach((r, i) => {
+    // M9：started/ended 指向已写正文（ended 空串是「未结束」，refCheck 视作未填跳过）
+    for (const k of ['started', 'ended']) refCheck('relations.yml', `第 ${i + 1} 条关系`, k, r[k])
     for (const side of ['a', 'b']) {
       const value = typeof r[side] === 'string' ? r[side].trim() : ''
       if (value !== '' && !knownRoles.has(value)) {
@@ -1119,12 +1201,14 @@ export function checkProject(novelDir) {
       if (!hasWorldLore) {
         push('error', 'world/', 'phase 已过 setting 但 world/ 与 science/ 均无条目（setting → outline 判据：世界观核心条目须落盘）')
       }
-      if (readYamlArray(novelDir, 'volumes.yml').length === 0) {
+      // 复用上方已读的 volumes / relations（M8/H2 起 readAccountYml 带告警采集，
+      // 这里重复读会导致同一份文件告警计两次）
+      if (volumes.length === 0) {
         push('error', 'volumes.yml', 'phase 已过 setting 但 volumes.yml 为空或缺失（setting → outline 判据：分卷规划须在案）')
       }
       // 关系网判据（六期补）：两张及以上角色卡时 relations.yml 不得为空——
       // 空关系网意味着设定阶段漏登关系，关系图与大纲师的戏剧权重都无从谈起。
-      if (cards.length >= 2 && readYamlArray(novelDir, 'relations.yml').length === 0) {
+      if (cards.length >= 2 && relations.length === 0) {
         push('error', 'relations.yml', 'phase 已过 setting 但 relations.yml 为空（setting → outline 判据：两张及以上角色卡时关系网须登记）')
       }
     }

package/lib/panel-core.mjs

@@ -304,7 +304,9 @@ function collectOutlines(novelDir, warnings) {
   const dir = path.join(novelDir, 'outlines')
   let names = []
   try {
-    names = readdirSync(dir).filter((n) => n.toLowerCase().endsWith('.md'))
+    // M10：.md 口径与 novel-parse listMdFiles 一致（/\.md$/i 大小写不敏感），
+    // 同一个 .MD 文件不许面板收录、CLI 排除
+    names = readdirSync(dir).filter((n) => /\.md$/i.test(n))
   } catch (err) {
     if (err?.code !== 'ENOENT') warnings.push(`outlines: 遍历失败（${err?.code ?? err?.message ?? err}）`)
     return []
@@ -336,7 +338,8 @@ function collectMdEntities(novelDir, sub, yamlLib, warnings) {
   const dir = path.join(novelDir, sub)
   let names = []
   try {
-    names = readdirSync(dir).filter((n) => n.toLowerCase().endsWith('.md')).sort((a, b) => a.localeCompare(b, undefined, { numeric: true }))
+    // M10：与 collectOutlines / novel-parse listMdFiles 同款 /\.md$/i 口径
+    names = readdirSync(dir).filter((n) => /\.md$/i.test(n)).sort((a, b) => a.localeCompare(b, undefined, { numeric: true }))
   } catch {
     return []
   }
@@ -372,11 +375,16 @@ function collectArrayYml(novelDir, fileName, yamlLib, warnings) {
   if (yamlLib) {
     try {
       data = yamlLib.parse(text)
-    } catch {
-      data = null
+    } catch (err) {
+      // H1：真解析失败不再静默——先记文件名+一句话错误再降级极简解析，畸形
+      // 文件（如未闭合 flow 序列）在面板至少留下「坏过」的痕迹，条目残缺可归因
+      warnings.push(`${fileName}: yaml 解析失败（${err?.message ?? err}），已降级极简解析`)
     }
   }
-  if (data === null || data === undefined) data = parseFlatYamlArray(text)
+  if (data === null || data === undefined) {
+    // H2：极简解析丢弃的零缩进散键行（novel-parse 侧 onWarn）挂上文件名并入 warnings
+    data = parseFlatYamlArray(text, (w) => warnings.push(`${fileName}: ${w}`))
+  }
   if (!Array.isArray(data)) {
     warnings.push(`${fileName}: 顶层不是数组，已按空表处理`)
     return []
@@ -402,8 +410,9 @@ function readProject(novelDir, yamlLib, warnings) {
       try {
         const parsed = yamlLib.parse(text)
         if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) data = parsed
-      } catch {
-        data = null
+      } catch (err) {
+        // H1：与 collectArrayYml 同理——真解析失败记 warning 再降级，不静默吞
+        warnings.push(`project.yml: yaml 解析失败（${err?.message ?? err}），已降级极简解析`)
       }
     }
     if (data === null) {

package/lib/self-update.mjs

@@ -30,8 +30,16 @@
  * 数组形式；darwin/linux 恒 shell:false，无注入面。
  *
  * 升级前版本预检：fetchLatestFromRegistry（10s）失败再 fetchLatestFromMirror
- * （10s），拿不到 latest 绝不做半截升级；compareVersions(target, current) <= 0
- * 直接短路「已是最新」，不 spawn。装完失效版本检测缓存。
+ * （10s），拿不到 latest 绝不做半截升级；latest 剥 v 后强制 semver 形状校验
+ * （X.Y.Z[-预发布]，M1）——被控源返回的串携带 shell 元字符时绝不进 spawn 参数
+ * （win32 shell:true 下即命令注入），不匹配按 no-target 拒绝。
+ * compareVersions(target, current) <= 0 直接短路「已是最新」，不 spawn。装完
+ * 失效版本检测缓存。
+ *
+ * 装后对账（M2）：退出码 0 只代表 pnpm/npm 自认装完，半装/坏包要重启才暴露
+ * ——装完回读安装位 package.json 的 version 与精确目标对账，读不到或不符一律
+ * 收敛 verify-failed（新 kind，走既有 ok:false 分支，client 透传兼容），
+ * message 给手动重装出路，绝不静默当成功。
  *
  * 安全边界（缺一不可，全不满足绝不执行安装）：
  *   1) 安装形态判定——插件包自身目录先 realpathSync 取真路径，真路径 ≠ 常规
@@ -55,10 +63,12 @@
  *     realpath 落在本 profile 目录内（如 profile 自带 .bin/maoying）→ 不是
  *     全局安装，跳过该候选继续找。找不到任何候选 → { found: false }。
  *   - 找不到全局安装 → globalCli: { ok: true, skipped: 'missing' }，不 spawn；
- *   - 全局 version 与精确目标同版 → skipped: 'same'，不 spawn；否则 spawn
- *     `npm i -g dsh-maoying@<target>`（cwd=os.tmpdir()、独立 120s 超时，npm
- *     候选链与 pnpm 同款 spawn ENOENT 探测：裸 npm → execPath 同目录 →
- *     /opt/homebrew/bin → /usr/local/bin → /opt/homebrew/opt/node@XX/bin）。
+ *   - 全局 version 不落后精确目标（含比目标更新，L5：绝不静默降级）→
+ *     skipped: 'same'，不 spawn；仅落后才 spawn `npm i -g dsh-maoying@<target>`
+ *     （cwd=os.tmpdir()、独立 120s 超时，npm 候选链与 pnpm 同款 spawn ENOENT
+ *     探测：裸 npm → execPath 同目录 → /opt/homebrew/bin → /usr/local/bin →
+ *     /opt/homebrew/opt/node@XX/bin）。装完同样回读全局安装位对账，不符收敛
+ *     globalCli.ok:false + kind:'verify-failed'（不强求回滚）。
  *   - 全局阶段失败（npm 缺失 / 非零 / 超时）**不拖累整体结果**：profile 已装
  *     好，重启照常生效；globalCli.ok:false + 中文 error（含手动出路
  *     `npm i -g dsh-maoying@<target>`）如实透出。dev-link / unsupported-layout /
@@ -85,6 +95,7 @@ import {
   fetchLatestFromMirror,
   fetchLatestFromRegistry,
   invalidateVersionCache,
+  isValidVersion,
 } from './version.mjs'
 
 /** 安装超时：pnpm 冷缓存 + 国内网络最坏留足 3 分钟。 */
@@ -119,9 +130,11 @@ function defaultPkgDir() {
  * spawn 失败透传 err.code（如 'ENOENT'，候选链据此换下一路），超时收敛为
  * 'ETIMEDOUT'。timeoutLabel 只用于超时文案标明哪条通道超时。超时先 SIGTERM，
  * TERM_GRACE_MS 后仍不退则 SIGKILL 兜底（pnpm 尊重 SIGTERM；SIGKILL 保证
- * close 事件必然到达，调用方绝不悬挂）。
+ * close 事件必然到达，调用方绝不悬挂）。win32（shell:true）下 child 只是
+ * cmd.exe 包装壳，SIGTERM 杀不到底层进程，超时改用 taskkill /T /F 按进程树
+ * 整棵杀（L12，见 timer 内注释）；platform 参数仅供测试注入，缺省进程平台。
  */
-export function defaultSpawn(command, args, options, timeoutMs, timeoutLabel) {
+export function defaultSpawn(command, args, options, timeoutMs, timeoutLabel, platform = process.platform) {
   return new Promise((resolve) => {
     let child
     try {
@@ -141,7 +154,21 @@ export function defaultSpawn(command, args, options, timeoutMs, timeoutLabel) {
     let timedOut = false
     const timer = setTimeout(() => {
       timedOut = true
-      try { child.kill('SIGTERM') } catch { /* 已退出：忽略 */ }
+      try {
+        if (platform === 'win32' && child.pid != null) {
+          // L12：win32（shell:true）下 child 只是 cmd.exe 包装壳，kill 只杀得
+          // 掉壳，底层 pnpm/node 变孤儿继续占用网络与文件锁。taskkill /T /F
+          // 按 PID 树杀整棵进程（/T 含子孙、/F 强制），壳被杀后 close 事件照
+          // 常到达；taskkill 自身启动失败（System32 内置，基本不可能）退回
+          // SIGKILL，下方宽限兜底不变。
+          const killer = nodeSpawn('taskkill', ['/T', '/F', '/PID', String(child.pid)], { stdio: 'ignore' })
+          killer.on('error', () => { try { child.kill('SIGKILL') } catch { /* 已退出：忽略 */ } })
+        } else {
+          // 非 win32：先 SIGTERM 给宽限（pnpm 尊重），TERM_GRACE_MS 后仍不退
+          // 由下方 SIGKILL 兜底。
+          child.kill('SIGTERM')
+        }
+      } catch { /* 已退出：忽略 */ }
     }, timeoutMs)
     const killTimer = setTimeout(() => {
       if (!timedOut) return
@@ -229,8 +256,13 @@ function buildCandidates({ platform, env, execPath, existsImpl, readdirImpl }) {
  * 全局 maoying CLI 检测（零 spawn，纯文件系统；机制见文件头注「全局 CLI 顺带
  * 更新」节）。bin 候选位 = env.PATH 各目录 + /opt/homebrew/bin + /usr/local/bin
  * （去重保序），找 `maoying`（win32 `maoying.cmd`），existsSync 预筛；命中后
- * realpathSync 两级上溯得包根，包根 package.json 的 name 必须是 dsh-maoying
- * 才认；包根 realpath 落在 profileDir 内（或就是它）→ 是 profile 自己的
+ * 定位包根：win32 且真路径是 .cmd/.exe shim 时（npm/pnpm 的全局 bin 是
+ * <prefix>/ 下的普通文件 shim，realpath 原样返回，两级上溯会得到 prefix 的
+ * 父目录 → 包根 name 校验必失败 → Windows 恒 skipped:'missing' 静默漏更，
+ * 见 M3），prefix 即 dirname(命令路径)，包根取 <prefix>/node_modules/dsh-
+ * maoying；否则 realpathSync 该 bin 两级上溯得包根（bin/maoying.mjs → 包根）。
+ * 包根 package.json 的 name 必须是 dsh-maoying 才认（防怪链接）；包根
+ * realpath 落在 profileDir 内（或就是它）→ 是 profile 自己的
  * .bin/maoying，跳过该候选继续找。全落空 → { found: false }。
  * 任何一步异常（断链 symlink / 包根不可读 / JSON 坏）都只跳过该候选，不抛错。
  */
@@ -250,7 +282,15 @@ function detectGlobalCli({ env, platform, profileDir, existsImpl, realpathImpl,
     if (!existsImpl(bin)) continue
     let cli
     try { cli = path.resolve(realpathImpl(bin)) } catch { continue }
-    const root = path.dirname(path.dirname(cli))
+    // M3：win32 的 .cmd/.exe shim 是 <prefix>/ 下的普通文件（realpath 原样
+    // 返回），两级上溯得到的是 prefix 的父目录，包根校验必失败；shim 形态下
+    // prefix 就是 dirname(命令路径)，包根直接取 <prefix>/node_modules/dsh-
+    // maoying。darwin/linux 的 bin 是包根 bin/ 下的真入口，两级上溯维持原语义
+    //（限 win32 判 shim：posix 上碰巧叫 *.cmd 的文件不按 shim 处理）。
+    const isWinShim = platform === 'win32' && /\.(cmd|exe)$/i.test(cli)
+    const root = isWinShim
+      ? path.join(path.dirname(cli), 'node_modules', 'dsh-maoying')
+      : path.dirname(path.dirname(cli))
     let manifest
     try { manifest = JSON.parse(readImpl(path.join(root, 'package.json'))) } catch { continue }
     if (manifest?.name !== 'dsh-maoying') continue
@@ -297,17 +337,28 @@ function buildNpmCandidates({ platform, execPath, existsImpl, readdirImpl }) {
 /**
  * 全局 CLI 阶段（profile 阶段落定后跑；失败绝不拖累整体结果，形状见文件头注）。
  * 返回 { ok: true, skipped: 'missing' } / { ok: true, skipped: 'same', version } /
- * { ok: true, from, to: targetVersion } / { ok: false, error, output? }。
+ * { ok: true, from, to: targetVersion } / { ok: false, error, output?, kind? }
+ * （kind 仅装后对账失败时为 'verify-failed'）。
  * spawn 走 npm 候选链（仅 ENOENT 换下一路），cwd=os.tmpdir()（npm 全局装与
  * cwd 无关，不该在 profile / 仓库里跑），独立 globalTimeoutMs 超时。
  */
 async function updateGlobalCliStage({ targetVersion, profileDir }, deps) {
   const { env, platform, execPath, spawnImpl, existsImpl, readdirImpl, realpathImpl, readImpl, logger, globalTimeoutMs } = deps
+  // M1：targetVersion 进 spawn 参数（win32 shell:true）前再闸一次形状——上游
+  // 已验，这里是双保险，非法串绝不拼参、绝不安装。
+  if (!isValidVersion(targetVersion)) {
+    const error = `目标版本串非法（${String(targetVersion)}），已拒绝更新全局 CLI；可手动执行：npm i -g dsh-maoying@latest`
+    logger?.warn?.(`maoying 创作台: 全局 CLI 更新失败(bad-target): ${error}`)
+    return { ok: false, error }
+  }
   const g = detectGlobalCli({ env, platform, profileDir, existsImpl, realpathImpl, readImpl })
   if (!g.found) return { ok: true, skipped: 'missing' }
   // 版本比对（'' = 包根 package.json 缺 version，当旧版处理装到精确目标）。
-  if (g.version !== '' && compareVersions(g.version, targetVersion) === 0) {
-    logger?.info?.(`maoying 创作台: 全局 maoying CLI 已是 ${g.version}，跳过更新`)
+  // L5：不落后（>=）即跳过——旧实现只对同版短路，全局比目标还新时会被
+  // `npm i -g dsh-maoying@<旧目标>` 静默降级；语义应为「全局仍落后才更到
+  // 同版」，绝不降级。
+  if (g.version !== '' && compareVersions(g.version, targetVersion) >= 0) {
+    logger?.info?.(`maoying 创作台: 全局 maoying CLI ${g.version} 不落后于目标 ${targetVersion}，跳过更新`)
     return { ok: true, skipped: 'same', version: g.version }
   }
 
@@ -354,6 +405,20 @@ async function updateGlobalCliStage({ targetVersion, profileDir }, deps) {
     logger?.warn?.(`maoying 创作台: 全局 CLI 更新失败(exit ${proc?.code}): ${output}`)
     return { ok: false, error, output }
   }
+  // M2：全局装后对账（思路同 profile，不强求回滚）——npm 退出码 0 只代表
+  // npm 自认装完，磁盘半装要重启才暴露。重跑同款零 spawn 检测回读全局安装位
+  // package.json：version 与精确目标相符才算成功；重检落空（读不到）或不符
+  // 如实报 verify-failed，error 带手动重装出路。整体结果仍由调用方维持
+  // ok:true（profile 已装好，全局失败不追责整单）。
+  const recheck = detectGlobalCli({ env, platform, profileDir, existsImpl, realpathImpl, readImpl })
+  if (!recheck.found || recheck.version !== targetVersion) {
+    const detail = recheck.found
+      ? `npm i -g 后磁盘 version ${recheck.version} ≠ 目标 ${targetVersion}`
+      : 'npm i -g 后未在 PATH 检测到全局 maoying 安装'
+    const error = `全局 CLI 更新后对账失败（${detail}），请手动重装：npm i -g dsh-maoying@${targetVersion}`
+    logger?.warn?.(`maoying 创作台: 全局 CLI 更新失败(verify-failed): ${detail}`)
+    return { ok: false, kind: 'verify-failed', error, output }
+  }
   logger?.info?.(`maoying 创作台: 全局 maoying CLI ${g.version} → ${targetVersion}`)
   return { ok: true, from: g.version, to: targetVersion }
 }
@@ -439,6 +504,17 @@ async function runSelfUpdate(opts = {}) {
   }
   const target = manifest.latest // 形如 v0.2.3
   const targetVersion = target.replace(/^v/, '')
+  // M1：targetVersion 使用前强制形状校验（X.Y.Z[-预发布]）——registry/npmmirror
+  // 被控时返回的串只剥 v 前缀就采信，会拼进 `dsh-maoying@${targetVersion}`
+  // 与响应文案（win32 shell:true 下即命令注入）。不匹配按 no-target 拒绝，
+  // 绝不 spawn。version.mjs 源头已验，这里是使用点的双保险。
+  if (!isValidVersion(targetVersion)) {
+    return {
+      ok: false,
+      kind: 'no-target',
+      message: `线上版本串非法（${target}），已拒绝升级以防注入；请稍后重试或用命令行升级`,
+    }
+  }
   // 全局 CLI 阶段的依赖包（两个成功路径各跑一次；失败路径整单拒绝、碰都不碰）。
   const globalDeps = { env, platform, execPath, spawnImpl, existsImpl, readdirImpl, realpathImpl, readImpl, logger, globalTimeoutMs }
   if (compareVersions(target, current) <= 0) {
@@ -513,12 +589,33 @@ async function runSelfUpdate(opts = {}) {
     }
   }
 
-  // ── e) 成功：版本缓存立刻失效（装的是磁盘新包，进程内 1h 缓存已是旧结论）。
-  //       to 取预检到的精确目标版本（退出码即成败信号，不做磁盘后验——本进程
-  //       代码不随升级变化，无从对账）。随后跑全局 CLI 阶段（方案 B：desktop
-  //       profile 与全局 npm 安装是两份独立拷贝，顺带更到同一精确版本）；全局
-  //       阶段失败不拖累整体——profile 已装好，重启照常生效，globalCli.ok:false
-  //       如实透出。
+  // ── e) 装后对账（M2）：退出码 0 只代表 pnpm 自认装完，半装/坏包要重启才
+  //       暴露。回读安装位 package.json 的 version 与精确目标对账，相符才算
+  //       成功；读不到或不符一律 verify-failed（新 kind，走既有 ok:false 分支，
+  //       client 透传兼容）并给手动重装出路；与其他 profile 阶段失败路径同
+  //       收敛，整单不碰全局。
+  const installedManifest = path.join(profileDir, 'node_modules', 'dsh-maoying', 'package.json')
+  let installedVersion = null
+  try {
+    installedVersion = JSON.parse(readImpl(installedManifest))?.version ?? null
+  } catch { /* 读不到 / 解析失败：对账按失败处理 */ }
+  if (installedVersion !== targetVersion) {
+    const detail = installedVersion === null
+      ? `读不到 ${installedManifest}（安装未落盘或已损坏）`
+      : `磁盘 version ${installedVersion} ≠ 目标 ${targetVersion}`
+    logger?.warn?.(`maoying 创作台: self-update 对账失败(verify-failed): ${detail}`)
+    return {
+      ok: false,
+      kind: 'verify-failed',
+      message: `升级后对账失败（${detail}），请手动重装：cd ${profileDir} && pnpm add dsh-maoying@${targetVersion}`,
+    }
+  }
+
+  // ── f) 成功：版本缓存立刻失效（装的是磁盘新包，进程内 1h 缓存已是旧结论）。
+  //       to 取预检到的精确目标版本（已与磁盘对账）。随后跑全局 CLI 阶段（方案
+  //       B：desktop profile 与全局 npm 安装是两份独立拷贝，顺带更到同一精确
+  //       版本）；全局阶段失败不拖累整体——profile 已装好，重启照常生效，
+  //       globalCli.ok:false 如实透出。
   invalidateVersionCache()
   logger?.info?.(`maoying 创作台: self-update 完成 ${current} → ${targetVersion}（重启 DeepSeek 后生效）`)
   const globalCli = await updateGlobalCliStage({ targetVersion, profileDir }, globalDeps)

package/lib/version.mjs

@@ -31,6 +31,17 @@ const MIRROR_LATEST = 'https://registry.npmmirror.com/dsh-maoying/latest'
 // 对任何 latest 误报新版，升级提示必须整体抑制（读不到版本就不提示）。
 const FALLBACK_VERSION = '0.0.0'
 
+/**
+ * 合法版本号形状（M1）：semver 核心三段 + 可选预发布段（如 1.2.3-rc.1）。
+ * 远端源（registry / npmmirror / GitHub tag）返回的串必须先过这道闸才允许
+ * 进缓存、参与比较或拼进安装参数——对 version 只校验非空字符串的话，被控源
+ * 返回的串可携带 shell 元字符，剥了 v 前缀就采信会经 self-update 的
+ * `dsh-maoying@<version>` 拼参（win32 shell:true 下即命令注入）。
+ */
+export function isValidVersion(value) {
+  return typeof value === 'string' && /^\d+\.\d+\.\d+(-[0-9A-Za-z.\-]+)?$/.test(value)
+}
+
 // 内存缓存 TTL：1 小时内复用上次成功结果，过期才真的发外网请求。
 const CACHE_TTL_MS = 60 * 60 * 1000
 // 请求失败时的 stale-if-error 窗口：上次成功结果在 7 天内仍原样复用（lastGood）。
@@ -66,6 +77,11 @@ export async function currentVersion() {
 function parseVersion(value) {
   let s = String(value ?? '').trim()
   if (s.startsWith('v') || s.startsWith('V')) s = s.slice(1)
+  // L3：build metadata（首个 '+' 起的段）按 semver 口径不参与比较，先截掉——
+  // 否则 '1.2.3+build' 的核心段被切成 ['1','2','3+build']，'3+build' 非纯数字
+  // 归 0，整体被误判成 1.2.0。
+  const plus = s.indexOf('+')
+  if (plus !== -1) s = s.slice(0, plus)
   const dash = s.indexOf('-')
   const coreText = dash === -1 ? s : s.slice(0, dash)
   const pre = dash === -1 ? '' : s.slice(dash + 1)
@@ -157,6 +173,8 @@ export async function fetchLatestRelease({ fetchImpl, timeoutMs = 3000 } = {}) {
     }
     const tag = typeof data?.tag_name === 'string' && data.tag_name !== '' ? data.tag_name : null
     if (!tag) return { ok: false, error: 'GitHub API 响应缺少 tag_name' }
+    // M1：tag 同款形状校验（剥 v/V 前缀后验），非法 tag 不进缓存也不参与比较。
+    if (!isValidVersion(tag.replace(/^v/i, ''))) return { ok: false, error: `GitHub release tag 非法: ${tag}` }
     const url = typeof data?.html_url === 'string' && data.html_url !== '' ? data.html_url : RELEASE_PAGE
     return { ok: true, tag, url }
   } catch (err) {
@@ -190,6 +208,9 @@ async function fetchLatestManifest(url, label, source, { fetchImpl, timeoutMs =
     // CDN 缓存抖动可能回形状不对的正文，按失败处理走下一级检测源。
     const ver = typeof data?.version === 'string' && data.version !== '' ? data.version : null
     if (!ver) return { ok: false, error: `${label} 响应缺少 version` }
+    // M1：形状非法（非 X.Y.Z[-预发布]，可能携带 shell 元字符）的 version 不进
+    // 缓存也不参与比较/安装，按该路失败处理走下一级检测源。
+    if (!isValidVersion(ver.replace(/^v/, ''))) return { ok: false, error: `${label} 响应 version 非法: ${ver}` }
     return { ok: true, latest: `v${ver}`, releaseUrl: RELEASE_PAGE, source }
   } catch (err) {
     return { ok: false, error: String(err?.message ?? err) }
@@ -329,15 +350,22 @@ export function invalidateVersionCache() {
  * 兜底）时 updateAvailable 恒 false：0.0.0 对任何 latest 都「更小」，比较必
  * 误报新版，升级提示整体抑制。检测源：npm registry 与 npmmirror 镜像并行
  * 竞速（先成功者胜），两路皆败才串行请求 GitHub release 兜底；三路皆败才
- * 算本次检测失败。并发调用经 in-flight 去重复用同一次检测。成功结果的
+ * 算本次检测失败。并发调用经 in-flight 去重复用同一次检测。`force: true`
+ * 为手动检测更新语义（路由 `update-check?fresh=1`）：先把模块级缓存压成
+ * 空再走正常流程——只保证不命中 1h TTL 内的陈旧 cache，**不保证「另发
+ * 一轮全新外网请求」**：若已有一轮 in-flight 检测在跑，它本来就是缓存
+ * 失效后发起的新检测，复用等它落定即可（有意语义，与 invalidateVersionCache
+ * 的整体作废不同——这里刻意不动 in-flight）。成功结果的
  * source 字段记录命中源。所有返回值均为缓存对象的浅拷贝——缓存要供最长
  * 7 天的 lastGood 复用，调用方原地改写返回对象不得污染缓存。
  * @returns {Promise<{current: string, latest: string|null, updateAvailable: boolean,
  *           releaseUrl: string|null, checkedAt: string, error: string|null,
  *           source: 'npm'|'mirror'|'github'|null}>}
  */
-export async function getVersionInfo({ fetchImpl, timeoutMs = 3000, now } = {}) {
+export async function getVersionInfo({ fetchImpl, timeoutMs = 3000, now, force = false } = {}) {
   const nowMs = typeof now === 'function' ? now() : typeof now === 'number' ? now : Date.now()
+  // force（手动检测）：缓存置空 → 下方 TTL 判定必不命中，走真实检测。
+  if (force) cache = { at: 0, info: null }
   // TTL 内直接复用缓存；一律返回浅拷贝，隔离调用方的原地改写。
   if (cache.info && nowMs - cache.at < CACHE_TTL_MS) return { ...cache.info }
   // in-flight 去重：并发调用共享同一次检测；浅拷贝统一在返回前做。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-maoying",
-  "version": "0.1.20",
+  "version": "0.1.21",
   "description": "毛颖 — DSH 网文创作辅助插件：主编 + 五帮手编排（大纲/写手/审校/设定/考据），novel/ 结构化文件为数据库",
   "type": "module",
   "license": "MIT",
@@ -30,6 +30,7 @@
     "index.mjs",
     "bin/",
     "lib/",
+    "scripts/",
     "presets/",
     "skills/",
     "templates/",