dsh-maoying 0.1.13 → 0.1.15

package/lib/novel-parse.mjs

@@ -709,8 +709,12 @@ const FORESHADOW_STATUSES = ['planted', 'progressing', 'resolved', 'abandoned']
 /** project.yml 的共创模式枚举（五期 §9.1）。 */
 const PROJECT_MODES = ['ai-draft', 'co-write', 'author-draft']
 
-/** 章节 frontmatter 的 volume 规范形态：v + 两位卷号。 */
-function canonicalVolume(vol) {
+/**
+ * 章节 frontmatter 的 volume 规范形态：v + 两位卷号。面板从章纲建章
+ * （panel-core 的 createChapterFromOutline）与本文件 check / collectChapters
+ * 共用同一规范形态。
+ */
+export function canonicalVolume(vol) {
   return `v${String(vol).padStart(2, '0')}`
 }
 

package/lib/panel-core.mjs

@@ -11,13 +11,20 @@
  *                                  （五期起含 outlines 章纲清单）
  *     readChapter(novelDir, file)  章节正文全文（抽屉用；五期起带对应章纲
  *                                  outline 字段）
+ *     readOutlineFile(novelDir, file) 章纲全文（章纲弹层用；0.1.15 起按单
+ *                                  写作的未建章章纲可看全文）
+ *     projectFileHash(novelDir)    project.yml 原文 sha256 hex（快照
+ *                                  project_hash / 保存旧版检测共用基线）
  *
- *   写入面（全部「读原文 → 行级字符串手术 → 写后校验替换计数 === 1」；
- *   计数不符或目标行缺失一律 409 拒写不落盘，把对 git diff 的扰动压到最小）
+ *   写入面（行级原地替换三件套：读原文 → 手术 → 写后校验替换计数 === 1；
+ *   计数不符或目标行缺失一律 409 拒写不落盘，把对 git diff 的扰动压到最小。
+ *   createChapterFromOutline 是唯一例外——它从章纲落一个全新章节文件，不动
+ *   任何既有文件的字节）
  *     mutateChapterStatus     章节 frontmatter 的 status 行
  *     mutateForeshadowStatus  foreshadows.yml 对应 id 条目块内的 status 行
  *     mutatePhase             project.yml 的 phase 行
  *     rebuildIndex            复用 lib/novel-parse 的 buildIndexYaml 重建
+ *     createChapterFromOutline   从章纲建章（chapters/ 落 pending 空章，0.1.15）
  *
  * 错误约定：本模块抛 PanelError（带 statusCode），路由层按 statusCode 回
  * JSON（403 拒绝 / 404 找不到 / 409 拒写 / 422 入参不合法）；未带状态码的
@@ -28,10 +35,11 @@
  * 绝不让它炸掉整个快照。
  */
 
-import { existsSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
+import { createHash } from 'node:crypto'
+import { mkdirSync, existsSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
 import path from 'node:path'
 
-import { buildIndexYaml, chapterSortKey, collectChapters, countCjk, parseFlatYamlArray, parseScalarText, splitFrontmatter, stripInlineComment } from './novel-parse.mjs'
+import { buildIndexYaml, canonicalVolume, chapterSortKey, collectChapters, countCjk, FIVE_DIM_KEYS, parseFlatYamlArray, parseScalarText, splitFrontmatter, stripInlineComment } from './novel-parse.mjs'
 import { loadYamlLib, resolveDshHome } from './yaml-loader.mjs'
 
 /** 章节状态机（与 lib/novel-parse 的表同源：只取键）。 */
@@ -397,6 +405,27 @@ function readProject(novelDir, yamlLib, warnings) {
   }
 }
 
+/** sha256 hex（小写）：文本 → 指纹。 */
+function sha256Hex(text) {
+  return createHash('sha256').update(text, 'utf8').digest('hex')
+}
+
+/**
+ * project.yml 原文指纹（sha256 hex）：面板「人工改动保护」的基线。快照带出
+ * project_hash，保存时回传 base_hash 比对——表单载入后文件被外部（作者手改
+ * / agent 推进 phase）动过就能查觉，拒绝静默覆盖。读不到/读失败返回 null
+ * （与「无 project.yml」同口径，不炸快照）。
+ */
+export function projectFileHash(novelDir) {
+  let text = null
+  try {
+    text = readFileSync(path.join(path.resolve(novelDir), 'project.yml'), 'utf8')
+  } catch {
+    return null
+  }
+  return sha256Hex(text)
+}
+
 /**
  * 全量快照（docs/creator-panel.md §3，字段名冻结）。novelDir 为工作区的
  * novel 目录；project.yml 不在 = 未初始化（found: false，其余字段缺省）。
@@ -409,10 +438,13 @@ export function parseStateSnapshot(novelDir, options = {}) {
   const warnings = []
 
   if (!existsSync(path.join(dir, 'project.yml'))) {
-    return { ok: true, root, novelDir: dir, found: false, warnings }
+    return { ok: true, root, novelDir: dir, found: false, project_hash: null, warnings }
   }
 
   const project = readProject(dir, yamlLib, warnings)
+  // 人工改动保护基线：快照顶层带 project.yml 原文指纹，客户端保存时原样回传
+  // （project-save 的 base_hash）；读不到为 null（不影响快照其余字段）。
+  const projectHash = projectFileHash(dir)
 
   const chaptersRaw = (() => {
     try {
@@ -451,6 +483,15 @@ export function parseStateSnapshot(novelDir, options = {}) {
     markers: strArray(meta.markers),
   }))
 
+  // 关系端点归一：契约规定 relations.yml 的 a/b 是角色 slug（characters/ 目录名），
+  // 而关系图客户端按角色 name（卡 frontmatter name，缺省回落 slug）找节点——不出
+  // 快照侧归一，带中文名的角色卡必然端点对不上、一条边都画不出。对得上角色卡的
+  // 端点改写成 name；对不上的（已死亡/未建档角色，或历史条目直接写了 name）原样
+  // 保留。novel-parse 侧（protagonistCards、relations 校验）仍按 slug 契约，不动。
+  const nameBySlug = Object.fromEntries(
+    characters.map((c) => [String(c.file ?? '').replace(/\.md$/i, ''), c.name])
+  )
+
   const relations = collectArrayYml(dir, 'relations.yml', yamlLib, warnings).map((r) => ({
     a: strOrNull(r.a),
     b: strOrNull(r.b),
@@ -459,7 +500,7 @@ export function parseStateSnapshot(novelDir, options = {}) {
     intensity: intOrNull(r.intensity),
     started: strOrNull(r.started),
     ended: strOrNull(r.ended),
-  }))
+  })).map((r) => ({ ...r, a: nameBySlug[r.a] ?? r.a, b: nameBySlug[r.b] ?? r.b }))
 
   const foreshadows = collectArrayYml(dir, 'foreshadows.yml', yamlLib, warnings).map((f) => ({
     id: strOrNull(f.id),
@@ -531,6 +572,7 @@ export function parseStateSnapshot(novelDir, options = {}) {
     root,
     novelDir: dir,
     found: true,
+    project_hash: projectHash,
     project,
     chapters,
     characters,
@@ -580,6 +622,74 @@ export function readChapter(novelDir, file, options = {}) {
   return { ok: true, file: name, frontmatter: meta, body, outline }
 }
 
+/**
+ * 章纲文件名解析（readOutlineFile / createChapterFromOutline 共用的入口
+ * 校验）：file 过 safeFileName 后必须 .md 结尾且 stem 合乎 vXX-cXXX 规范
+ * （与 collectOutlines 的收录口径一致——不合规范的面板本就不列，路由侧
+ * 一律 422 拒掉，不给穿越/探测留口子）。
+ */
+function outlineStemOf(file) {
+  const name = safeFileName(file, 'file')
+  if (!/\.md$/i.test(name)) fail(422, `非章纲文件名（只认 .md）：${name}`)
+  const stem = name.replace(/\.md$/i, '')
+  if (chapterSortKey(stem) === null) fail(422, `非章纲文件名（stem 不合 vXX-cXXX 规范）：${name}`)
+  return stem
+}
+
+/**
+ * 章纲全文（0.1.15 起面板「章纲弹层」用）：按单写作兼容未建章章纲后，
+ * 孤儿章纲也要能看全文。章纲纯 markdown 无 frontmatter，body 即原文；
+ * words 为全文 CJK 计数（口径与快照 outlines 一致）。章纲不存在 404。
+ */
+export function readOutlineFile(novelDir, file) {
+  const stem = outlineStemOf(file)
+  const outline = readOutline(novelDir, stem)
+  if (outline === null) fail(404, `章纲不存在：outlines/${stem}.md`)
+  return { ok: true, file: outline.file, words: outline.words, body: outline.body }
+}
+
+/**
+ * 章纲标题提取（createChapterFromOutline 用）：取章纲正文首条 `#` 标题行
+ * 文本，去结尾「章纲」二字（大纲师标题惯用后缀）后 trim；空则「（无标题）」
+ * （与 collectChapters 的缺省标题同形）。
+ */
+function outlineTitleOf(body) {
+  const hit = /^#[ \t]+(.+?)[ \t]*$/m.exec(String(body ?? ''))
+  const title = (hit === null ? '' : hit[1]).replace(/章纲$/, '').trim()
+  return title !== '' ? title : '（无标题）'
+}
+
+/**
+ * 从章纲建章（0.1.15，面板「按单写作」的孤儿章纲一键建章）：在 chapters/
+ * 下落一个 status=pending 的空章节——frontmatter 按 templates/novel/README.md
+ * 的章节模板（volume/num/title/status/summary + 五维五键，值待写留空），
+ * 正文留空。title 取章纲首条标题行（outlineTitleOf）。目标章节已存在 409
+ * （先到先建，绝不覆盖既有正文）；章纲不存在 404。写前确保 chapters/ 目录
+ * 在（手工项目 / 测试夹具可能还没建目录）。建章后走既有 pending 流转。
+ */
+export function createChapterFromOutline(novelDir, file) {
+  const stem = outlineStemOf(file)
+  const key = chapterSortKey(stem)
+  const target = path.join(path.resolve(novelDir), 'chapters', `${stem}.md`)
+  if (existsSync(target)) fail(409, `章节已存在：chapters/${stem}.md——无需重复建章`)
+  const outline = readOutline(novelDir, stem)
+  if (outline === null) fail(404, `章纲不存在：outlines/${stem}.md`)
+  const title = outlineTitleOf(outline.body)
+  const lines = [
+    '---',
+    `volume: ${canonicalVolume(key.vol)}`,
+    `num: ${key.num}`,
+    `title: ${yamlScalar(title)}`,
+    'status: pending',
+    `summary: ${yamlScalar('')}`,
+    ...FIVE_DIM_KEYS.map((k) => `${k}: ${yamlScalar('')}`),
+    '---',
+  ]
+  mkdirSync(path.dirname(target), { recursive: true })
+  writeAtomic(target, `${lines.join('\n')}\n`)
+  return { ok: true, file: `${stem}.md`, title }
+}
+
 // ── 写操作：行级原地替换 ────────────────────────────────────────────────────
 
 /**
@@ -679,12 +789,19 @@ export function mutatePhase(novelDir, phase) {
 const PROJECT_MODE_KEYS = ['ai-draft', 'co-write', 'author-draft']
 
 /**
- * 小说设置：project.yml 平键批量改写（创作台「小说设置」tab）。逐键做
+ * 书稿元信息保存：project.yml 平键批量改写（创作台「概览」的「编辑」态）。
+ * 逐键做
  * 「单行值替换、行尾注释原样保留」（与 mutatePhase 同一保注释刀法）；文件里
  * 没有的键按模板顺序补在末尾（带模板注释）。校验：phase/mode 越枚举 422、
  * title 空白 422。值统一经 yamlScalar 规范成可回读的 YAML 标量。
+ *
+ * 人工改动保护：options.baseHash 是面板表单载入时的 project.yml 原文指纹
+ * （快照 project_hash）。与写入前现读原文不一致 → 表单基线已过期（作者或
+ * agent 在载入后改过文件），409 拒写——静默覆盖会丢人工改动。未传 baseHash
+ * 跳过检查（旧调用方兼容）。返回值带写后新指纹 project_hash，客户端 reload
+ * 前即可拿到下一轮基线。
  */
-export function mutateProject(novelDir, values) {
+export function mutateProject(novelDir, values, options = {}) {
   if (values === null || typeof values !== 'object' || Array.isArray(values)) {
     fail(422, 'values 必须是键值对象')
   }
@@ -701,6 +818,12 @@ export function mutateProject(novelDir, values) {
 
   const target = path.join(novelDir, 'project.yml')
   const text = readTarget(target, 'project.yml')
+  // 旧版检测在读原文之后、落笔之前：指纹不一致就地 409，一个字节都不动。
+  // 客户端指纹归一到小写再比（指纹本身 hex，大小写宽容不构成安全口子）。
+  const baseHash = typeof options.baseHash === 'string' ? options.baseHash.trim().toLowerCase() : ''
+  if (baseHash !== '' && baseHash !== sha256Hex(text)) {
+    fail(409, 'project.yml 已被外部修改，请刷新面板后基于最新内容重改再存')
+  }
   const lines = text.split(/\r?\n/)
   const pending = new Map(Object.entries(next))
   for (let i = 0; i < lines.length; i++) {
@@ -724,8 +847,10 @@ export function mutateProject(novelDir, values) {
       lines.splice(insertAt, 0, ...missing)
     }
   }
-  writeAtomic(target, joinLines(lines, text))
-  return { ok: true }
+  const nextText = joinLines(lines, text)
+  writeAtomic(target, nextText)
+  // 返回写后指纹：客户端下一轮保存的 base_hash 直接取它，不必再等一次快照。
+  return { ok: true, project_hash: sha256Hex(nextText) }
 }
 
 /** YAML 平标量：安全字符裸写，含特殊字符（冒号空格/井号/引号/首尾空格等）

package/lib/self-update.mjs

@@ -0,0 +1,263 @@
+/**
+ * 面板内一键升级 —— 直接跑 pnpm 把本包装到当前 DSH profile（创作台面板用）。
+ *
+ * 背景：desktop 档的真实安装形态是 <dshHome>/profiles/<profile>/node_modules/
+ * dsh-maoying（真实目录，非 symlink），宿主 dsh CLI 拒绝管理 desktop 档，唯一
+ * 可行的升级命令是直接 pnpm：`pnpm --dir <profileDir> add dsh-maoying@latest`。
+ *
+ * 安全边界（缺一不可，全不满足绝不执行安装）：
+ *   1) 安装形态判定——插件包自身目录先 realpathSync 取真路径，真路径 ≠ 常规
+ *      路径即 link/symlink 安装（如 web 档指向 dev repo）→ 拒绝（dev-link，
+ *      请在开发目录 git pull）；真路径不匹配 <dshHome>/profiles/<profile>/
+ *      node_modules/dsh-maoying 结构 → 拒绝（unsupported-layout）。dshHome /
+ *      profile 取 env.DSH_HOME / DSH_PROFILE（~ 前缀手动展开），缺失时回退从
+ *      真路径的 profiles 祖先推导，推导不出同样拒绝。
+ *   2) pnpm 解析——按候选路径逐个 existsSync + accessSync(X_OK)（PATH 各目录
+ *      在前，homebrew / pnpm 官方安装位在后），一个都不可执行 → 拒绝
+ *      （pnpm-missing）。绝不用 shell:true，无注入面。
+ *   3) 超时 180 秒——超时 kill 子进程收敛为 timeout，不挂死面板请求。
+ *
+ * 所有失败路径都不抛错，一律收敛为 { ok: false, kind, message } 结果对象；
+ * 成功返回 { ok: true, kind: 'installed', from, to, restartRequired: true }。
+ * 硬约束：装完后运行中的进程仍是旧代码，必须重启 DeepSeek 才生效——restart-
+ * Required 恒 true，UI 文案必须明说，不得暗示装完即生效。依赖全部可注入
+ * （spawnImpl / realpathImpl / existsImpl / readImpl …），对齐 lib/version.mjs
+ * 的 fetchImpl 模式，方便测试。
+ */
+import { spawn as nodeSpawn } from 'node:child_process'
+import { accessSync, constants as fsConstants, existsSync, realpathSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { invalidateVersionCache } from './version.mjs'
+
+/** 安装超时：pnpm 冷缓存 + 国内网络最坏留足 3 分钟。 */
+export const SELF_UPDATE_TIMEOUT_MS = 180 * 1000
+/** 失败信息里保留的子进程输出尾部字节数（stdout / stderr 各一份）。 */
+const OUTPUT_TAIL_BYTES = 2048
+
+/**
+ * 插件包自身目录（package.json 所在目录）。抽成函数便于测试注入假安装位。
+ */
+function defaultPkgDir() {
+  return path.dirname(fileURLToPath(new URL('../package.json', import.meta.url)))
+}
+
+/**
+ * PATH 里 pnpm 之后的候选兜底（macOS 常见安装位；GUI 进程 PATH 常缺 pnpm，
+ * 宿主进程又不经过 shell，PATH 找不到时按固定路径逐个试）。
+ */
+function extraPnpmCandidates(env) {
+  const home = typeof env.HOME === 'string' && env.HOME.trim() !== '' ? env.HOME.trim() : os.homedir()
+  return [
+    '/opt/homebrew/bin/pnpm',
+    '/usr/local/bin/pnpm',
+    path.join(home, '.local', 'share', 'pnpm', 'pnpm'),
+    path.join(home, 'Library', 'pnpm', 'pnpm'),
+  ]
+}
+
+/** 解析 pnpm 可执行文件：PATH 各目录在前、常见安装位兜底，去重后逐个可执行性检查。 */
+function resolvePnpm(env, { existsImpl, accessImpl }) {
+  const pathEnv = typeof env.PATH === 'string' ? env.PATH : ''
+  const fromPath = pathEnv.split(path.delimiter).filter((d) => d !== '').map((d) => path.join(d, 'pnpm'))
+  const candidates = [...new Set([...fromPath, ...extraPnpmCandidates(env)])]
+  for (const candidate of candidates) {
+    try {
+      if (!existsImpl(candidate)) continue
+      accessImpl(candidate, fsConstants.X_OK)
+      return candidate
+    } catch {
+      /* 存在但不可执行（或探测异常）：换下一个候选 */
+    }
+  }
+  return null
+}
+
+/**
+ * 从真路径的 profiles 祖先推导 { home, profile }：真路径必须形如
+ * <dshHome>/profiles/<profile>/node_modules/dsh-maoying，其余形态返回 null。
+ */
+function deriveLayoutFromPath(realDir) {
+  const pkgName = path.basename(realDir)
+  const nmDir = path.dirname(realDir)
+  if (pkgName !== 'dsh-maoying' || path.basename(nmDir) !== 'node_modules') return null
+  const profile = path.basename(path.dirname(nmDir))
+  const profilesDir = path.dirname(path.dirname(nmDir))
+  if (path.basename(profilesDir) !== 'profiles') return null
+  return { home: path.dirname(profilesDir), profile }
+}
+
+/** env 里的 dsh home（~ 前缀手动展开，环境变量不经过 shell 展开）。 */
+function dshHomeFromEnv(env) {
+  const raw = typeof env.DSH_HOME === 'string' ? env.DSH_HOME.trim() : ''
+  if (raw === '') return null
+  if (raw === '~' || raw.startsWith('~/')) return path.join(os.homedir(), raw.slice(1))
+  return raw
+}
+
+/**
+ * 读安装目录 package.json 的 version；读不到（缺失 / 解析失败 / 字段异常）
+ * 返回 null——from 缺失不拦安装（pnpm 退出码才是成败信号），to 缺失照常
+ * ok:true（version 显示为 null，前端兜底显示）。
+ */
+async function readPkgVersion(pkgJsonPath, readImpl) {
+  try {
+    const raw = await readImpl(pkgJsonPath)
+    const pkg = JSON.parse(raw)
+    return typeof pkg?.version === 'string' && pkg.version !== '' ? pkg.version : null
+  } catch {
+    return null
+  }
+}
+
+/** 组装最小注入面：缺省走真实 Node 实现，测试逐项替换。 */
+function normalizeDeps(opts) {
+  const env = opts.env ?? process.env
+  return {
+    env,
+    spawnImpl: opts.spawnImpl ?? nodeSpawn,
+    pkgDirImpl: opts.pkgDirImpl ?? defaultPkgDir,
+    realpathImpl: opts.realpathImpl ?? ((p) => realpathSync(p)),
+    existsImpl: opts.existsImpl ?? ((p) => existsSync(p)),
+    accessImpl: opts.accessImpl ?? ((p, mode) => accessSync(p, mode)),
+    readImpl:
+      opts.readImpl ??
+      ((p) => readFile(p, 'utf8')),
+    logger: opts.logger ?? console,
+    timeoutMs:
+      typeof opts.timeoutMs === 'number' && opts.timeoutMs > 0 ? opts.timeoutMs : SELF_UPDATE_TIMEOUT_MS,
+  }
+}
+
+/**
+ * selfUpdate 主体（永不 reject；concurrency 去重与兜底 try/catch 在外层）。
+ * @returns {Promise<{ok: boolean, kind: string, from?: string|null, to?: string|null,
+ *           restartRequired?: boolean, message?: string}>}
+ */
+async function runSelfUpdate(opts = {}) {
+  const { spawnImpl, pkgDirImpl, realpathImpl, existsImpl, accessImpl, readImpl, env, logger, timeoutMs } =
+    normalizeDeps(opts)
+
+  // ── a) 安装形态判定 ──────────────────────────────────────────────────────
+  const pkgDir = pkgDirImpl()
+  let realDir
+  try {
+    realDir = path.resolve(realpathImpl(pkgDir))
+  } catch (err) {
+    return { ok: false, kind: 'unsupported-layout', message: `安装目录读取失败: ${err?.message ?? err}` }
+  }
+  if (realDir !== path.resolve(pkgDir)) {
+    return {
+      ok: false,
+      kind: 'dev-link',
+      message: '当前安装指向开发目录（symlink/link 安装），请到开发目录 git pull 更新，这里不代装',
+    }
+  }
+  const derived = deriveLayoutFromPath(realDir)
+  const home = dshHomeFromEnv(env) ?? derived?.home ?? null
+  const profileRaw = typeof env.DSH_PROFILE === 'string' ? env.DSH_PROFILE.trim() : ''
+  const profile = profileRaw !== '' ? profileRaw : derived?.profile ?? null
+  const profileDir = home && profile ? path.join(home, 'profiles', profile) : null
+  if (!derived || !profileDir || realDir !== path.resolve(path.join(profileDir, 'node_modules', 'dsh-maoying'))) {
+    return {
+      ok: false,
+      kind: 'unsupported-layout',
+      message: '当前安装形态不受面板内升级支持（不是 <dshHome>/profiles/<profile>/node_modules/dsh-maoying 目录安装），请用命令行升级',
+    }
+  }
+
+  // ── b) 解析 pnpm ────────────────────────────────────────────────────────
+  const pnpmPath = resolvePnpm(env, { existsImpl, accessImpl })
+  if (!pnpmPath) {
+    return {
+      ok: false,
+      kind: 'pnpm-missing',
+      message: '未找到 pnpm 可执行文件（PATH 与常见安装路径都没有），请先安装 pnpm 后重试',
+    }
+  }
+
+  const pkgJsonPath = path.join(realDir, 'package.json')
+  const from = await readPkgVersion(pkgJsonPath, readImpl)
+
+  // ── c) 执行安装（绝不用 shell:true，无注入面）────────────────────────────
+  const exitInfo = await new Promise((resolve) => {
+    let child
+    try {
+      child = spawnImpl(pnpmPath, ['--dir', profileDir, 'add', 'dsh-maoying@latest'], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+      })
+    } catch (err) {
+      resolve({ failed: true, kind: 'spawn-error', message: `pnpm 启动失败: ${err?.message ?? err}` })
+      return
+    }
+    let out = Buffer.alloc(0)
+    let errBuf = Buffer.alloc(0)
+    const keepTail = (buf, chunk) => Buffer.concat([buf, Buffer.from(chunk)]).subarray(-OUTPUT_TAIL_BYTES)
+    child.stdout?.on?.('data', (chunk) => { out = keepTail(out, chunk) })
+    child.stderr?.on?.('data', (chunk) => { errBuf = keepTail(errBuf, chunk) })
+    // 定时器只在进程仍存活时触发；exit 先到则清掉，不留挂起句柄。
+    const timer = setTimeout(() => {
+      try { child.kill() } catch { /* 已退出：忽略 */ }
+      resolve({
+        failed: true,
+        kind: 'timeout',
+        message: `pnpm 安装超时（${Math.round(timeoutMs / 1000)} 秒）已中止，请检查网络后重试`,
+      })
+    }, timeoutMs)
+    const onExit = (code, signal) => {
+      clearTimeout(timer)
+      if (code === 0) {
+        resolve({ failed: false })
+        return
+      }
+      const tailText = `${out.toString('utf8')}\n${errBuf.toString('utf8')}`.trim()
+      resolve({
+        failed: true,
+        kind: 'pnpm-failed',
+        message: `pnpm add 失败（${signal != null ? `signal ${signal}` : `exit ${code}`}）：${tailText !== '' ? tailText : '无输出'}`,
+      })
+    }
+    child.on?.('exit', onExit)
+    child.on?.('error', (err) => {
+      clearTimeout(timer)
+      resolve({ failed: true, kind: 'spawn-error', message: `pnpm 启动失败: ${err?.message ?? err}` })
+    })
+  })
+  if (exitInfo.failed) {
+    logger?.warn?.(`maoying 创作台: self-update 失败(${exitInfo.kind}): ${exitInfo.message}`)
+    return { ok: false, kind: exitInfo.kind, message: exitInfo.message }
+  }
+
+  // ── d) 成功后重读新版本 + 版本缓存失效 ───────────────────────────────────
+  const to = await readPkgVersion(pkgJsonPath, readImpl)
+  // 装的是磁盘上的新包，进程内 update-check 的 1h 缓存已是旧结论，立刻失效，
+  // 下次打开面板（重启后）按磁盘新版本重算 updateAvailable。
+  invalidateVersionCache()
+  logger?.info?.(`maoying 创作台: self-update 完成 ${from ?? '?'} → ${to ?? '?'}（重启 DeepSeek 后生效）`)
+  return { ok: true, kind: 'installed', from, to, restartRequired: true }
+}
+
+// in-flight 去重：并发的 selfUpdate（连点按钮 / 双面板）复用同一次安装
+// promise，pnpm add 绝不并发跑两份；promise 落定即清空。resetSelfUpdateInflight
+// 仅供测试隔离模块级状态。
+let inflight = null
+
+/** 测试专用：清空模块级 in-flight 状态（生产勿用）。 */
+export function resetSelfUpdateInflight() {
+  inflight = null
+}
+
+/**
+ * 面板一键升级入口（并发去重）。
+ * @returns {Promise<{ok: boolean, kind: string, ...}>} 永不 reject
+ */
+export async function selfUpdate(opts = {}) {
+  if (inflight) return inflight
+  inflight = runSelfUpdate(opts).finally(() => {
+    inflight = null
+  })
+  return inflight
+}

package/lib/version.mjs

@@ -310,6 +310,17 @@ async function detectLatest({ fetchImpl, timeoutMs, nowMs }) {
 // 注意并发窗口内各调用共享第一次调用注入的 now 语义（checkedAt 取先到者）。
 let inflight = null
 
+/**
+ * 版本缓存失效（面板一键升级专用，lib/self-update.mjs 调用）：pnpm 把磁盘
+ * 上的包装到新版本后，进程内这份缓存（含 1h TTL 与 7 天 lastGood 窗口里的
+ * 旧结论）整体作废——下次 getVersionInfo 按磁盘新版本重算 updateAvailable。
+ * 只重置缓存与 in-flight，不改任何检测行为。
+ */
+export function invalidateVersionCache() {
+  cache = { at: 0, info: null }
+  inflight = null
+}
+
 /**
  * 组合结果（面板路由专用）：带 1 小时内存缓存，过期才重新请求；请求失败时
  * 若上次成功结果在 lastGood 窗口（7 天，见 LASTGOOD_TTL_MS）内则原样复用

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-maoying",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "毛颖 — DSH 网文创作辅助插件：主编 + 五帮手编排（大纲/写手/审校/设定/考据），novel/ 结构化文件为数据库",
   "type": "module",
   "license": "MIT",