dsh-maoying 0.1.10 → 0.1.12

package/lib/panel-core.mjs

@@ -28,7 +28,7 @@
  * 绝不让它炸掉整个快照。
  */
 
-import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { 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'
@@ -176,6 +176,22 @@ function joinLines(lines, originalText) {
   return lines.join(eol)
 }
 
+/**
+ * 原子落盘：先写同目录临时文件，再 renameSync 原子替换——truncate+write
+ * 直写期间并发读会看到半截文件，rename 在同一文件系统上不存在中间态。
+ * 临时文件藏在同目录（保证 rename 跨设备语义成立），失败时扫尾后原样上抛。
+ */
+function writeAtomic(target, data) {
+  const tmp = path.join(path.dirname(target), `.${path.basename(target)}.${process.pid}.${Date.now()}.tmp`)
+  try {
+    writeFileSync(tmp, data, 'utf8')
+    renameSync(tmp, target)
+  } catch (err) {
+    try { unlinkSync(tmp) } catch { /* 临时文件没立起来就没什么可扫 */ }
+    throw err
+  }
+}
+
 // ── frontmatter 解析（yaml 可用走真解析，否则正则平键 + 条目块）───────────
 
 /**
@@ -184,7 +200,7 @@ function joinLines(lines, originalText) {
  * 一层列表）；规范禁止深嵌套，超出形状的行原样忽略。
  */
 function parseFrontmatterFallback(raw) {
-  const meta = {}
+  const meta = Object.create(null) // 无原型对象：__proto__ 键只进自身属性，改写不了原型
   let listKey = null
   for (const line of raw.split(/\r?\n/)) {
     const clean = stripInlineComment(line).replace(/\s+$/, '')
@@ -376,6 +392,7 @@ function readProject(novelDir, yamlLib, warnings) {
     length: strOrNull(data?.length),
     language: strOrNull(data?.language),
     phase: strOrNull(data?.phase),
+    mode: strOrNull(data?.mode),
     description: strOrNull(data?.description),
   }
 }
@@ -565,6 +582,20 @@ export function readChapter(novelDir, file, options = {}) {
 
 // ── 写操作：行级原地替换 ────────────────────────────────────────────────────
 
+/**
+ * 保注释赋值刀：把一行 `缩进key: 旧值  # 行尾注释` 的值换成 newValue，行尾
+ * 注释（连同值与注释间的空白）原样保留。值/注释切分复用 novel-parse 的
+ * stripInlineComment——引号内的 # 不算注释（`长#夜` 是合法标量），避开
+ * `(.*?)` 在值内第一个 # 提前截断、同值连存两次产出非法 YAML 的刀法损坏。
+ * 行须命中 headRe（捕获组 1 = `缩进key:`），未命中返回 null 由调用方兜底。
+ */
+function rewriteValueKeepComment(line, headRe, newValue) {
+  const body = stripInlineComment(line).replace(/\s+$/, '')
+  const head = headRe.exec(body)
+  if (head === null) return null
+  return `${head[1]} ${newValue}${line.slice(body.length)}`
+}
+
 /**
  * 章节状态流转：只动 frontmatter 围栏内的 status 行，其余字节原样保留。
  * status 出枚举 422；文件不存在 404；无围栏 / status 行缺失或多处 409 拒写。
@@ -575,11 +606,15 @@ export function mutateChapterStatus(novelDir, file, status) {
   const text = readTarget(target, `章节 ${name}`)
   const fence = splitFrontmatter(text)
   if (fence.raw === null) fail(409, `${name} 没有 frontmatter 围栏，无处替换 status 行`)
-  const replaced = replaceLineOnce(fence.raw, /^status:[^\n]*?$/, `status: ${status}`, {
-    what: `${name} frontmatter 的 status 行`,
-  })
+  const replaced = replaceLineOnce(
+    fence.raw,
+    /^status:[^\n]*?$/,
+    // 保注释刀法：只换值，用户写在行尾的注释原样保留（与 mutatePhase 一致）
+    (line) => rewriteValueKeepComment(line, /^(status:)/, status) ?? line,
+    { what: `${name} frontmatter 的 status 行` },
+  )
   const next = text.slice(0, fence.index) + replaced + text.slice(fence.index + fence.raw.length)
-  writeFileSync(target, next, 'utf8')
+  writeAtomic(target, next)
   return { ok: true, file: name, status }
 }
 
@@ -617,8 +652,9 @@ export function mutateForeshadowStatus(novelDir, id, status) {
     }
   }
   if (hits !== 1) fail(409, `foreshadows.yml 条目 ${id} 的 status 行应恰有一处，实得 ${hits} 处——已拒绝写入`)
-  lines[hit] = lines[hit].replace(/^([ \t]*status:)[ \t]*.*$/, `$1 ${status}`)
-  writeFileSync(target, joinLines(lines, text), 'utf8')
+  // 保注释刀法：只换值，行尾注释原样保留（headRe 弱于上方计数正则，兜底仅为防御）
+  lines[hit] = rewriteValueKeepComment(lines[hit], /^([ \t]*status:)/, status) ?? lines[hit]
+  writeAtomic(target, joinLines(lines, text))
   return { ok: true, id, status }
 }
 
@@ -636,10 +672,80 @@ export function mutatePhase(novelDir, phase) {
   const next = text.replace(new RegExp(phaseRe.source, 'm'), (line) =>
     line.replace(/^(phase:[ \t]*)(.*?)([ \t]*(?:#.*)?)$/, (_m, key, _value, comment) => `${key}${phase}${comment ?? ''}`),
   )
-  writeFileSync(target, next, 'utf8')
+  writeAtomic(target, next)
   return { ok: true, phase }
 }
 
+const PROJECT_MODE_KEYS = ['ai-draft', 'co-write', 'author-draft']
+
+/**
+ * 小说设置：project.yml 平键批量改写（创作台「小说设置」tab）。逐键做
+ * 「单行值替换、行尾注释原样保留」（与 mutatePhase 同一保注释刀法）；文件里
+ * 没有的键按模板顺序补在末尾（带模板注释）。校验：phase/mode 越枚举 422、
+ * title 空白 422。值统一经 yamlScalar 规范成可回读的 YAML 标量。
+ */
+export function mutateProject(novelDir, values) {
+  if (values === null || typeof values !== 'object' || Array.isArray(values)) {
+    fail(422, 'values 必须是键值对象')
+  }
+  const phase = typeof values.phase === 'string' ? values.phase : ''
+  if (!PHASE_KEYS.includes(phase)) fail(422, `phase 非法「${phase}」——七态只认 ${PHASE_KEYS.join(' / ')}`)
+  const mode = typeof values.mode === 'string' ? values.mode : ''
+  if (!PROJECT_MODE_KEYS.includes(mode)) fail(422, `mode 非法「${mode}」——只认 ${PROJECT_MODE_KEYS.join(' / ')}`)
+  const title = typeof values.title === 'string' ? values.title.trim() : ''
+  if (title === '') fail(422, 'title 不能为空——书稿总得有个名字')
+  const language = typeof values.language === 'string' && values.language.trim() !== '' ? values.language.trim() : 'zh'
+  const textFields = ['author', 'genre', 'length', 'description']
+  const next = { title, author: '', genre: '', length: '', language, phase, mode, description: '' }
+  for (const k of textFields) next[k] = typeof values[k] === 'string' ? values[k].trim() : ''
+
+  const target = path.join(novelDir, 'project.yml')
+  const text = readTarget(target, 'project.yml')
+  const lines = text.split(/\r?\n/)
+  const pending = new Map(Object.entries(next))
+  for (let i = 0; i < lines.length; i++) {
+    const m = /^([ \t]*)([A-Za-z][A-Za-z0-9_-]*):/.exec(lines[i])
+    if (!m || !pending.has(m[2])) continue
+    const [, indent, key] = m
+    // 保注释刀法：值/注释切分走 stripInlineComment（引号内 # 不算注释），
+    // 注释原样保留在行尾；键行形状异常时原样保留，宁缺毋写坏
+    lines[i] = rewriteValueKeepComment(lines[i], /^([ \t]*[A-Za-z][A-Za-z0-9_-]*:)/, yamlScalar(next[key])) ?? lines[i]
+    pending.delete(key)
+  }
+  // 模板补齐顺序：缺失键插在首个非注释内容行前，保持可读
+  if (pending.size > 0) {
+    const header = ['# project.yml —— 书稿元信息（平键，无嵌套）。phase 是七阶段工作流的状态机指针，', '# 每完成一个里程碑由主编推进并简报用户；mode 决定正文归谁写。']
+    const missing = [...pending.entries()].map(([k, v]) => `${k}: ${yamlScalar(v)}`)
+    let insertAt = lines.findIndex((l) => l.trim() !== '' && !l.trim().startsWith('#'))
+    if (insertAt === -1) insertAt = lines.length
+    if (lines.every((l) => l.trim() === '' || l.trim().startsWith('#'))) {
+      lines.splice(insertAt, 0, ...header, ...missing)
+    } else {
+      lines.splice(insertAt, 0, ...missing)
+    }
+  }
+  writeAtomic(target, joinLines(lines, text))
+  return { ok: true }
+}
+
+/** YAML 平标量：安全字符裸写，含特殊字符（冒号空格/井号/引号/首尾空格等）
+ *  时双引号包裹并转义；空串写成 ""。 */
+function yamlScalar(v) {
+  const s = String(v ?? '')
+  if (s === '') return '""'
+  // 类型漂移防护：形如布尔/数字/null 的字符串（《2046》这类书名）裸写会被
+  // YAML 回读成 number/boolean/null，strOrNull 置 null 后面板显示「—」——
+  // 一律双引号包裹，保住「回读仍是原字符串」（与 novel-parse 的 flowScalar 同口径）。
+  if (/^(true|false|null|~|yes|no|on|off|-?\d+|-?\d*\.\d+)$/i.test(s)) {
+    return '"' + s.replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"'
+  }
+  if (/^[\w\u4e00-\u9fff\u3000-\u303f\uff00-\uffef.,;:!?()（）【】《》「」『』·、—…·／/%+×\- ]+$/.test(s)
+    && !/(^|[\s:])#/.test(s) && !/:\s/.test(s) && !/^[-?:,\[\]{}#&*!|>'"%@`]/.test(s) && !/\s$/.test(s)) {
+    return s
+  }
+  return '"' + s.replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"'
+}
+
 /**
  * 重建 index.yml（与 CLI `maoying index` 同一实现）：chapters/ 缺失 404；
  * 成功返回章节数。
@@ -655,6 +761,6 @@ export function rebuildIndex(novelDir) {
     volumesRaw = null // volumes.yml 缺失/读不动：按无分卷重建，章节照收
   }
   const { text, chaptersCount } = buildIndexYaml(chapters, volumesRaw)
-  writeFileSync(path.join(novelDir, 'index.yml'), text, 'utf8')
+  writeAtomic(path.join(novelDir, 'index.yml'), text)
   return { ok: true, chapters: chaptersCount }
 }

package/lib/version.mjs

@@ -0,0 +1,340 @@
+/**
+ * 版本提示 —— 检测线上是否有比本地更新的版本（创作台面板用）。
+ *
+ * 同构移植自 dsh-paoding tools/lib/version.mjs（用户指定模仿其机制）。检测
+ * 源三级：npm registry 与 npmmirror 镜像两路并行竞速（manifest 形状与数据
+ * 一致，先成功者胜，官方源超时 / 被墙时国内几秒内可达的镜像顶上，分钟级
+ * 同步延迟对「有没有新版」这个判断无伤大雅）；两路 npm 源皆败再串行走
+ * GitHub releases/latest 兜底（独立数据源）。
+ *
+ * 零依赖纯 Node（>=18）：不引 cordis / npm 依赖，fetch 可注入（缺省用
+ * globalThis.fetch），超时用 AbortSignal.timeout()。所有失败路径都不抛错，
+ * 一律收敛为 { ok: false, error } 或带 error 字段的结果对象——调用方（面板
+ * 路由）按「失败即静默」处理，绝不影响主流程。
+ *
+ * 相对 paoding 版的差异：本文件在包内 lib/ 下，package.json 向上一级即是
+ * 包根（paoding 在 tools/lib/ 需向上两级）；包名与仓库名换成 dsh-maoying。
+ */
+import { readFile } from 'node:fs/promises'
+
+// 仓库（与包名一致）的 GitHub latest release 接口与落地页。
+const RELEASE_API = 'https://api.github.com/repos/lifangjin/dsh-maoying/releases/latest'
+const RELEASE_PAGE = 'https://github.com/lifangjin/dsh-maoying/releases/latest'
+// npm registry 的 latest 元数据端点（等价 dist-tags.latest，无认证无限流）。
+const REGISTRY_LATEST = 'https://registry.npmjs.org/dsh-maoying/latest'
+// npmmirror 镜像的同名端点：manifest 形状与官方源一致（顶层 version 即
+// latest），同步自 npm registry，官方源不可达时的国内快路。
+const MIRROR_LATEST = 'https://registry.npmmirror.com/dsh-maoying/latest'
+
+// 读不到 package.json 时的版本兜底。当前版本不可知（source: 'fallback'）时
+// updateAvailable 恒 false —— 拿「0.0.0 恒小于任何真实版本」去比较，反而必然
+// 对任何 latest 误报新版，升级提示必须整体抑制（读不到版本就不提示）。
+const FALLBACK_VERSION = '0.0.0'
+
+// 内存缓存 TTL：1 小时内复用上次成功结果，过期才真的发外网请求。
+const CACHE_TTL_MS = 60 * 60 * 1000
+// 请求失败时的 stale-if-error 窗口：上次成功结果在 7 天内仍原样复用（lastGood）。
+// 窗口刻意明显大于新鲜 TTL：外网偶发抖动不该立刻撤掉本可用的升级提示。
+const LASTGOOD_TTL_MS = 7 * 24 * 60 * 60 * 1000
+
+// 模块级缓存：只在成功后写入；失败结果不进缓存（下次调用仍会重试）。
+let cache = { at: 0, info: null }
+
+/**
+ * 本地版本：读包根 package.json 的 version。读失败（文件缺失 / 解析失败 /
+ * 字段异常）回退 FALLBACK_VERSION 并标记 source: 'fallback'。
+ * @returns {Promise<{version: string, source: 'package.json'|'fallback'}>}
+ */
+export async function currentVersion() {
+  try {
+    const raw = await readFile(new URL('../package.json', import.meta.url), 'utf8')
+    const pkg = JSON.parse(raw)
+    if (typeof pkg?.version === 'string' && pkg.version !== '') {
+      return { version: pkg.version, source: 'package.json' }
+    }
+  } catch {
+    /* 静默回退：版本读取失败不该打扰任何主流程 */
+  }
+  return { version: FALLBACK_VERSION, source: 'fallback' }
+}
+
+/**
+ * 拆版本号：剥前缀 v/V，按 '.' 切段，`-` 后为预发布后缀（原样保留）。核心段
+ * 必须纯数字才转数值，非纯数字段（如 '12abc'、空串）一律按 0——parseInt 的
+ * 前缀解析会把 '12abc' 当成 12，这里显式拒绝。
+ */
+function parseVersion(value) {
+  let s = String(value ?? '').trim()
+  if (s.startsWith('v') || s.startsWith('V')) s = s.slice(1)
+  const dash = s.indexOf('-')
+  const coreText = dash === -1 ? s : s.slice(0, dash)
+  const pre = dash === -1 ? '' : s.slice(dash + 1)
+  const core = coreText.split('.').map((n) => (/^\d+$/.test(n) ? Number(n) : 0))
+  return { core, pre }
+}
+
+/**
+ * 预发布段逐段比较：按 '.' 切段，纯数字段转数值比（rc.10 必须大于 rc.2，
+ * 字符串序会误判 'rc.10' < 'rc.2'），非数字段按字典序；段数不齐缺段视为
+ * 空段，空段小于非空段（semver 口径：rc.1 < rc.1.0）。
+ */
+function comparePre(a, b) {
+  const sa = a.split('.')
+  const sb = b.split('.')
+  const len = Math.max(sa.length, sb.length)
+  for (let i = 0; i < len; i++) {
+    const x = sa[i] ?? ''
+    const y = sb[i] ?? ''
+    if (x === y) continue
+    if (x === '') return -1 // 缺段（空）< 非空
+    if (y === '') return 1
+    if (/^\d+$/.test(x) && /^\d+$/.test(y)) return Number(x) < Number(y) ? -1 : 1
+    return x < y ? -1 : 1 // 非数字段（含数字段与非数字段混排）按字典序
+  }
+  return 0
+}
+
+/**
+ * 版本比较（可测纯函数）：a < b 返回 -1，相等返回 0，a > b 返回 1。
+ * 简化语义（不追求完整 semver）：剥前缀 v/V 后按 '.' 逐段数值比较，缺段补 0；
+ * 核心段相同时带预发布后缀（如 0.3.0-rc.1）视为低于无后缀同版本，两个都有
+ * 预发布后缀则按 '.' 切段逐段比较（数字段数值比、其余字典序，见 comparePre）。
+ */
+export function compareVersions(a, b) {
+  const pa = parseVersion(a)
+  const pb = parseVersion(b)
+  const len = Math.max(pa.core.length, pb.core.length)
+  for (let i = 0; i < len; i++) {
+    const x = pa.core[i] ?? 0
+    const y = pb.core[i] ?? 0
+    if (x !== y) return x < y ? -1 : 1
+  }
+  if (pa.pre !== pb.pre) {
+    if (pa.pre === '') return 1 // 无后缀 > 有后缀
+    if (pb.pre === '') return -1
+    return comparePre(pa.pre, pb.pre)
+  }
+  return 0
+}
+
+/**
+ * 请求 GitHub latest release。任何失败（网络 / 超时 / 限流 / 解析）都不抛出，
+ * 返回 { ok: false, error }；仓库尚无 release（404）不算错误，返回
+ * { ok: true, tag: null, url: null, notFound: true }。成功返回
+ * { ok: true, tag: 'vX.Y.Z', url: releasePage }。
+ */
+export async function fetchLatestRelease({ fetchImpl, timeoutMs = 3000 } = {}) {
+  const doFetch = typeof fetchImpl === 'function' ? fetchImpl : globalThis.fetch
+  if (typeof doFetch !== 'function') return { ok: false, error: 'fetch 不可用（当前运行时无 fetch 实现）' }
+  // GitHub API 必须带 User-Agent，顺手报上包名与本地版本便于排障。
+  const { version } = await currentVersion()
+  try {
+    const res = await doFetch(RELEASE_API, {
+      headers: {
+        'user-agent': `dsh-maoying/${version}`,
+        accept: 'application/vnd.github+json',
+      },
+      signal: AbortSignal.timeout(timeoutMs),
+    })
+    if (res.status === 404) return { ok: true, tag: null, url: null, notFound: true }
+    if (!res.ok) {
+      // 非 404 失败（403 限流、5xx 等）：带上 GitHub 的 message 便于排障
+      //（典型如未认证配额用尽的 rate limit 提示），仍按失败静默收敛。
+      let detail = ''
+      try {
+        const body = await res.json()
+        if (body && typeof body.message === 'string' && body.message !== '') detail = `: ${body.message}`
+      } catch {
+        /* 正文非 JSON 时忽略，只报状态码 */
+      }
+      return { ok: false, error: `GitHub API HTTP ${res.status}${detail}` }
+    }
+    let data = null
+    try {
+      data = await res.json()
+    } catch (err) {
+      return { ok: false, error: `GitHub API 响应解析失败: ${err?.message ?? err}` }
+    }
+    const tag = typeof data?.tag_name === 'string' && data.tag_name !== '' ? data.tag_name : null
+    if (!tag) return { ok: false, error: 'GitHub API 响应缺少 tag_name' }
+    const url = typeof data?.html_url === 'string' && data.html_url !== '' ? data.html_url : RELEASE_PAGE
+    return { ok: true, tag, url }
+  } catch (err) {
+    return { ok: false, error: String(err?.message ?? err) }
+  }
+}
+
+/**
+ * 请求一个 npm 系 manifest 端点（官方源与 npmmirror 镜像共用同一形状：完整
+ * manifest，顶层 version 即 latest）。任何失败（网络 / 超时 / 解析 / 形状不对）
+ * 都不抛出，返回 { ok: false, error }；成功返回 { ok: true, latest: 'vX.Y.Z',
+ * releaseUrl, source }（端点的 version 不带 v 前缀，这里统一补齐，与 GitHub
+ * tag 的显示口径一致）。
+ */
+async function fetchLatestManifest(url, label, source, { fetchImpl, timeoutMs = 3000 } = {}) {
+  const doFetch = typeof fetchImpl === 'function' ? fetchImpl : globalThis.fetch
+  if (typeof doFetch !== 'function') return { ok: false, error: 'fetch 不可用（当前运行时无 fetch 实现）' }
+  try {
+    const res = await doFetch(url, {
+      headers: { accept: 'application/vnd.npm+json' },
+      signal: AbortSignal.timeout(timeoutMs),
+    })
+    if (!res.ok) return { ok: false, error: `${label} HTTP ${res.status}` }
+    let data = null
+    try {
+      data = await res.json()
+    } catch (err) {
+      return { ok: false, error: `${label} 响应解析失败: ${err?.message ?? err}` }
+    }
+    // /<name>/latest 返回该版本的完整 manifest，顶层 version 即 latest 版本号；
+    // CDN 缓存抖动可能回形状不对的正文，按失败处理走下一级检测源。
+    const ver = typeof data?.version === 'string' && data.version !== '' ? data.version : null
+    if (!ver) return { ok: false, error: `${label} 响应缺少 version` }
+    return { ok: true, latest: `v${ver}`, releaseUrl: RELEASE_PAGE, source }
+  } catch (err) {
+    return { ok: false, error: String(err?.message ?? err) }
+  }
+}
+
+/**
+ * 请求 npm registry（官方源）的 latest 元数据——版本检测首选源。
+ */
+export async function fetchLatestFromRegistry(opts) {
+  return await fetchLatestManifest(REGISTRY_LATEST, 'npm registry', 'npm', opts)
+}
+
+/**
+ * 请求 npmmirror 镜像的 latest 元数据——官方源不可达（超时 / 被墙 / 代理
+ * 黑洞）时的国内快路：manifest 形状与官方源一致，同步延迟分钟级，对「有
+ * 没有新版」这个判断无伤大雅。
+ */
+export async function fetchLatestFromMirror(opts) {
+  return await fetchLatestManifest(MIRROR_LATEST, 'npmmirror', 'mirror', opts)
+}
+
+/**
+ * npm 双源并行竞速：registry 与 mirror 同时发起，谁先拿到有效版本（ok:true）
+ * 就用谁——两源 manifest 形状与数据一致（mirror 同步自官方源），成功语义
+ * 等价，先到先用不改变判定结果；单路超时同为 timeoutMs，npm 阶段最坏耗时
+ * 仍由 timeoutMs 封顶（原三级串行最坏 3×timeout 收敛为 npm 并行 1× +
+ * GitHub 串行 1×）。失败语义与旧串行链保持一致：registry 错误排前、mirror
+ * 排后（对应 failures[0] / failures[1]），两路皆败才由调用方串行走 GitHub
+ * 兜底。两路请求都提前挂好回调，先到即决出胜负，后到的结果作废但不产生
+ * 未处理异常。
+ */
+function raceLatestFromNpm(opts) {
+  return new Promise((resolve) => {
+    const errors = [null, null] // [registry 错误, mirror 错误]，全败时透出排障
+    let settled = 0 // 已落定的路数
+    let winner = false // 是否已决出胜者
+    const watch = (promise, index) => {
+      promise.then(
+        (hit) => {
+          if (winner) return // 已有先到者，本路结果作废
+          if (hit && hit.ok) {
+            winner = true
+            resolve({ ok: true, hit })
+          } else {
+            errors[index] = hit?.error ?? '未知失败'
+          }
+        },
+        (err) => {
+          errors[index] = String(err?.message ?? err)
+        },
+      ).finally(() => {
+        settled += 1
+        if (!winner && settled === 2) resolve({ ok: false, errors })
+      })
+    }
+    // registry 先挂监听：两路同步落定时胜者确定性偏向官方源
+    watch(fetchLatestFromRegistry(opts), 0)
+    watch(fetchLatestFromMirror(opts), 1)
+  })
+}
+
+/**
+ * 实际执行一轮检测（缓存 TTL 与并发去重之外的检测主体，供 getVersionInfo
+ * 调度）：npm registry 与 npmmirror 镜像并行竞速（见 raceLatestFromNpm），
+ * 两路皆败才串行请求 GitHub release 兜底；三路皆败按 lastGood / 降级收敛。
+ */
+async function detectLatest({ fetchImpl, timeoutMs, nowMs }) {
+  const { version: current, source: currentSource } = await currentVersion()
+  let hit
+  let failures = []
+  const npm = await raceLatestFromNpm({ fetchImpl, timeoutMs })
+  if (npm.ok) {
+    hit = npm.hit
+  } else {
+    failures = npm.errors
+    const rel = await fetchLatestRelease({ fetchImpl, timeoutMs })
+    hit = rel.ok && rel.tag
+      ? { ok: true, latest: rel.tag, releaseUrl: rel.url, source: 'github' }
+      : { ok: false, error: rel.ok ? 'GitHub release 尚未发布（404）' : rel.error }
+  }
+  // hit 必为对象（竞速胜者或 GitHub 兜底结果，失败也已收敛为结果对象），
+  // 无需再判真值。
+  if (hit.ok) {
+    const info = {
+      current,
+      latest: hit.latest ?? null,
+      // 当前版本不可知（fallback 0.0.0）时不提示升级，latest 缺失同理。
+      updateAvailable:
+        currentSource === 'fallback' || !hit.latest ? false : compareVersions(current, hit.latest) < 0,
+      releaseUrl: hit.releaseUrl ?? null,
+      checkedAt: new Date(nowMs).toISOString(),
+      error: null,
+      source: hit.source ?? null,
+    }
+    cache = { at: nowMs, info }
+    return info
+  }
+  // 三路皆败：优先复用 lastGood 窗口（7 天）内的上次成功结果；超窗才给降级
+  // 结果（不写缓存）。error 把各路原因都带上，并附代理排查提示——最常见的
+  // 「浏览器能上网、DSH 进程检测失败」是启动环境的代理变量指向了不可用的
+  // 代理（DSH 遵循 HTTPS_PROXY 等变量，浏览器不走它们）。
+  const combined = `三路检测均失败（npm registry: ${failures[0]}；npmmirror: ${failures[1]}；GitHub: ${hit.error}）。若本机经代理访问外网，请确认代理可用后重启 DSH 再试——DSH 进程遵循 HTTPS_PROXY / HTTP_PROXY 环境变量，浏览器不走它们，两者连通性可能不同`
+  if (cache.info && nowMs - cache.at < LASTGOOD_TTL_MS) return cache.info
+  return {
+    current,
+    latest: null,
+    updateAvailable: false,
+    releaseUrl: null,
+    checkedAt: new Date(nowMs).toISOString(),
+    error: combined,
+    source: null,
+  }
+}
+
+// in-flight 去重：并发的 getVersionInfo 调用（面板多处同时拉取）复用同一
+// 次检测 promise，只发一轮外网请求；promise 落定即清空，下次按缓存 TTL 走。
+// 注意并发窗口内各调用共享第一次调用注入的 now 语义（checkedAt 取先到者）。
+let inflight = null
+
+/**
+ * 组合结果（面板路由专用）：带 1 小时内存缓存，过期才重新请求；请求失败时
+ * 若上次成功结果在 lastGood 窗口（7 天，见 LASTGOOD_TTL_MS）内则原样复用
+ * （stale-if-error），否则返回带 error 的降级结果（latest 置 null、
+ * updateAvailable 恒 false——调用方静默）。当前版本不可知（FALLBACK_VERSION
+ * 兜底）时 updateAvailable 恒 false：0.0.0 对任何 latest 都「更小」，比较必
+ * 误报新版，升级提示整体抑制。检测源：npm registry 与 npmmirror 镜像并行
+ * 竞速（先成功者胜），两路皆败才串行请求 GitHub release 兜底；三路皆败才
+ * 算本次检测失败。并发调用经 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 } = {}) {
+  const nowMs = typeof now === 'function' ? now() : typeof now === 'number' ? now : Date.now()
+  // TTL 内直接复用缓存；一律返回浅拷贝，隔离调用方的原地改写。
+  if (cache.info && nowMs - cache.at < CACHE_TTL_MS) return { ...cache.info }
+  // in-flight 去重：并发调用共享同一次检测；浅拷贝统一在返回前做。
+  if (!inflight) {
+    inflight = detectLatest({ fetchImpl, timeoutMs, nowMs }).finally(() => {
+      inflight = null
+    })
+  }
+  const info = await inflight
+  return { ...info }
+}

package/lib/yaml-loader.mjs

@@ -15,10 +15,18 @@ import { fileURLToPath } from 'node:url'
 /** 插件包根（本文件位于 <包根>/lib/ 下，向上一级即包根）。 */
 const PLUGIN_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
 
-/** DSH_HOME 环境变量优先，缺省 ~/.dsh。 */
+/**
+ * DSH_HOME 环境变量优先（支持 ~ 前缀：环境变量不经过 shell 展开，`~/xxx`
+ * 或裸 `~` 在这里手动展开为真实家目录，避免拼出相对当前目录的「字面 ~」
+ * 不可用路径），缺省 ~/.dsh。
+ */
 export function resolveDshHome(env = process.env) {
   const fromEnv = typeof env.DSH_HOME === 'string' ? env.DSH_HOME.trim() : ''
-  return fromEnv !== '' ? fromEnv : path.join(os.homedir(), '.dsh')
+  if (fromEnv === '') return path.join(os.homedir(), '.dsh')
+  if (fromEnv === '~' || fromEnv.startsWith('~/')) {
+    return path.join(os.homedir(), fromEnv.slice(1))
+  }
+  return fromEnv
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-maoying",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "毛颖 — DSH 网文创作辅助插件：主编 + 五帮手编排（大纲/写手/审校/设定/考据），novel/ 结构化文件为数据库",
   "type": "module",
   "license": "MIT",
@@ -14,12 +14,16 @@
   "bin": {
     "maoying": "bin/maoying.mjs"
   },
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "smoke": "node scripts/smoke-client.mjs"
+  },
   "engines": {
     "node": ">=18",
     "dsh": ">=0.1.7 <0.3"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh": ">=0.1.7"
+    "@deepseek-ai/dsh": ">=0.1.7 <0.3"
   },
   "dependencies": {},
   "files": [

package/presets/maoying/agent.cordis.v2.yml

@@ -353,7 +353,8 @@
                   tailChars: 1024
     # ── 角色 preset：审校（one-shot，只读）────────────────────────────────────
     # persona 逐字复制 v1 delegation-review；tool-fs 收成 read/readImage 两开、
-    # write/edit 关闭——v1 只读 toolFilter 的实体化；无 write/edit/bash/skill。
+    # write/edit 关闭——v1 只读 toolFilter 的实体化；无 write/edit/bash；带
+    # skill 仅为加载审校清单等只读方法论技能，只读不改不变。
     - id: preset-maoying-review
       name: "@deepseek-ai/dsh-agent-preset"
       config:
@@ -389,6 +390,10 @@
             name: "@deepseek-ai/dsh-tool-fs-search"
             config:
               sampleOverCapGlobResults: false
+          - id: skill-filesystem
+            name: "@deepseek-ai/dsh-skill-filesystem"
+          - id: tool-skill
+            name: "@deepseek-ai/dsh-tool-skill"
           - id: tool-ask-user
             name: "@deepseek-ai/dsh-tool-ask-user"
           - id: tool-todo

package/presets/maoying/agent.cordis.yml

@@ -125,8 +125,8 @@
   name: '@deepseek-ai/dsh-tool-jobs'
 
 # ── skills ──────────────────────────────────────────────────────────────────
-# 主编经 restrict 的 registry deny 看不到技能目录；写手/大纲师/设定管理员保留
-# skill（二期方法论技能包落点）。
+# 主编经 restrict 的 registry deny 看不到技能目录；写手/大纲师/审校/设定管理员
+# 保留 skill（二期方法论技能包落点；审校只读不改，skill 仅用于加载审校清单）。
 
 - id: skill-filesystem
   name: '@deepseek-ai/dsh-skill-filesystem'
@@ -276,6 +276,9 @@
             - read_image
             - glob
             - grep
+            # skill：只用于按 persona 加载 maoying-review-checklist 等只读方法论
+            # 技能；审校仍无 write/edit/bash，只读不改的约束不变。
+            - skill
             - todo_write
             - ask_user_question
 

package/presets/maoying/restrict.mjs

@@ -13,13 +13,12 @@
  *   - 内部检索（热路径，不绕委派）：glob / grep / read / read_image / bash
  *   - 协调：todo_write / ask_user_question / goal_* / job_* / exit_plan_mode
  *
- * 主编看不到（请求成本归零）：web_search / web_fetch（考据委派 research）、
- * write / edit（落盘一律经角色或主编亲自验收后少量进行——主编保写权，
- * 见下方差异说明）、skill 目录（registry deny 堵 ~1.3k 注入）、以及未列出的
- * 一切通用委派与工作流工具。
+ * 主编看不到（白名单外收窄——只为省请求成本，不是安全边界）：web_search /
+ * web_fetch（考据委派 research）、skill 目录（registry deny 堵 ~1.3k 注入）、
+ * 以及未列出的一切通用委派与工作流工具。
  *
- * 说明：主编白名单保留 write/edit——主编需要亲自做小修小补
- * （改 phase、补 frontmatter、微调摘要），这些活不值得委派一次。
+ * write / edit 保留在白名单（见 MAIN_AGENT_ALLOW 尾段）：主编需要亲自做小修
+ * 小补（改 phase、补 frontmatter、微调摘要），这些活不值得委派一次。
  *
  * Host 工具（mcp__*、插件工具）一律不硬编码——是否挂载是检测期事实，
  * 硬编码会让未装对应插件的宿主直接出错。本文件只留 dsh 核心工具。

package/skills/maoying-review-checklist/SKILL.md

@@ -36,7 +36,7 @@ description: 网文章节审校清单——语言/节奏/人设/逻辑/伏笔/
 ### 5. 伏笔层（对照 foreshadows.yml）
 - 本章埋设的伏笔是否已登记（未登记记 P1，报给主编转设定管理员）；
 - 本章推进/回收的伏笔与台账状态一致；回收是否超出预期但合乎前文；
-- 活跃伏笔是否有间隔性提醒（长线伏笔超过 15 章未提及记 P2 提醒）。
+- 活跃伏笔是否有间隔性提醒（到限未动记 P2 提醒：high 超 10 章、normal 超 15 章、low 超 30 章，口径同 maoying-foreshadow-discipline）。
 
 ### 6. 剧透层
 - 本章是否提前泄露后期反转（对照章节大纲与已定稿章节的既有走向）；核心反转的铺垫应可回读成立但当时不点破。