dsh-maoying 0.1.18 → 0.1.20

package/lib/novel-parse.mjs

@@ -7,15 +7,26 @@
  * 永远是同一口径。五期（§9）在此追加：章纲 outlines/ 读取（readOutline /
  * listOutlines）、写作卡组装（buildBrief）与静态体检（checkProject）。
  *
- * 零依赖：只用 node:fs / node:path。YAML 解析走自带的极简子集
+ * 零依赖：只用 node:crypto / node:fs / node:path。YAML 解析走自带的极简子集
  * parseFlatYamlArray（本项目数据规范：yml 顶层只允许数组或平键，禁止深嵌套），
  * 与 dsh home 里的 yaml 包无关——yaml 包的真解析在 lib/yaml-loader.mjs 一侧，
  * 由 panel-core 自行惰性加载。
  */
 
+import { createHash } from 'node:crypto'
 import { existsSync, readdirSync, readFileSync } from 'node:fs'
 import path from 'node:path'
 
+/**
+ * sha256 hex（小写）：文本 → 指纹。全仓库唯一 hash 实现——面板「人工改动
+ * 保护」的各处基线（project_hash / 章节 chapter 的 hash / 章纲 outline.hash /
+ * style 的 hash）与各 save 路由的 base_hash 比对都从这一个口径出，避免多处
+ * 手搓摘要算法日后漂移（比如一方忘了 utf8 编码）。
+ */
+export function sha256Hex(text) {
+  return createHash('sha256').update(text, 'utf8').digest('hex')
+}
+
 /** 章节状态机（frontmatter status 枚举 + 中文标签；CLI 展示与面板共用）。 */
 export const CHAPTER_STATUSES = [
   ['pending', '待写'],
@@ -24,6 +35,13 @@ export const CHAPTER_STATUSES = [
   ['accepted', '已定稿'],
 ]
 
+/**
+ * 伏笔超期阈值：planted 状态超过该章数未推进即提醒（checkProject 的伏笔超期
+ * warn 用）。数字出处：skills/maoying-foreshadow-discipline/SKILL.md「清理纪律」
+ * ——planted 超过 30 章未推进应升级（置 progressing 并规划推进）或 abandoned。
+ */
+export const FORESHADOW_STALE_CHAPTERS = 30
+
 // CJK 计数范围：基本区 + 扩展 A + 扩展 B（\u{20000}-\u{2A6DF}）。扩展 B 在增补
 // 平面，必须带 u 标志按码点匹配——网文生僻字（如「𠮷」）此前会被漏计。
 const CJK_RE = /[\u4e00-\u9fff\u3400-\u4dbf\u{20000}-\u{2a6df}]/gu
@@ -785,6 +803,83 @@ function parseTimelineYear(year) {
   return m === null ? null : Number(m[0])
 }
 
+// ── AI 味统计（checkProject 第三组规则的实现；独立纯函数便于测试与复用）──────
+
+/** 连续同式开头判定下限：连续 ≥ 3 句以相同前 2 字开头算句式重复。 */
+export const STYLE_REPEAT_RUN = 3
+/** 比喻词密度阈值：每千 CJK 字超过 2 处判 AI 味风险。 */
+export const STYLE_METAPHOR_PER_KILO = 2
+/** 句长波动检查的最少句数：句数不足时统计无意义，不查。 */
+export const STYLE_SENTENCE_MIN = 20
+/** 句长变异系数（标准差/均值）下限：低于它说明长短句交替不足。 */
+export const STYLE_SENTENCE_CV_MIN = 0.3
+
+/** AI 高频比喻词清单（字面计数，不做修辞判定）。 */
+const METAPHOR_WORDS = ['仿佛', '宛如', '好似', '如同', '恍若', '好像']
+
+/** 章纲「钩子」小节的标题行：#{1,3} 级、「钩子」或「章尾钩子」打头即算。 */
+const OUTLINE_HOOK_RE = /^#{1,3}[ \t]*(?:章尾)?钩子/m
+
+/**
+ * 章节正文的 AI 味统计（纯函数，不读文件、不调模型）：按句切分（。！？…；，切分符不含逗号；
+ * 保留句文本），三条指标互相独立、命中才报，返回 warn 消息数组（level/file
+ * 由调用方挂）：
+ *   a. 连续同式开头——取最长的同前缀连续句段，达到 STYLE_REPEAT_RUN 报一次/章；
+ *   b. 比喻词密度——METAPHOR_WORDS 总次数 / 千 CJK 字超过 STYLE_METAPHOR_PER_KILO
+ *      （分母用 countCjk，与全库字数统计同口径）；
+ *   c. 句长波动——句数达 STYLE_SENTENCE_MIN 且变异系数（总体标准差/均值）
+ *      低于 STYLE_SENTENCE_CV_MIN。
+ */
+export function checkChapterStyle(body) {
+  const text = String(body ?? '')
+  const messages = []
+  const sentences = text
+    .split(/[。！？…；]+/)
+    .map((s) => s.trim())
+    .filter((s) => s !== '')
+  if (sentences.length === 0) return messages
+  // a. 连续同式开头：一次线性扫描，记最长的同前缀连续段
+  let best = null
+  let curPrefix = null
+  let curRun = 0
+  for (const sentence of sentences) {
+    const prefix = sentence.slice(0, 2)
+    if (prefix === curPrefix) curRun++
+    else {
+      curPrefix = prefix
+      curRun = 1
+    }
+    if (best === null || curRun > best.run) best = { prefix, run: curRun }
+  }
+  if (best.run >= STYLE_REPEAT_RUN) {
+    messages.push(`疑似句式重复：连续 ${best.run} 句以「${best.prefix}」开头`)
+  }
+  // b. 比喻词密度：字面总次数 / 千 CJK 字，严格超过阈值才报
+  let metaphorCount = 0
+  for (const word of METAPHOR_WORDS) metaphorCount += text.split(word).length - 1
+  const kilo = countCjk(text) / 1000
+  if (kilo > 0 && metaphorCount / kilo > STYLE_METAPHOR_PER_KILO) {
+    messages.push(
+      `比喻词密度偏高：${metaphorCount} 处 / ${Number(kilo.toFixed(1))}千字（阈值 ${STYLE_METAPHOR_PER_KILO}/千字）——AI 味风险`,
+    )
+  }
+  // c. 句长波动：句数足够且变异系数过低才报（均值 0 只可能全空句，已被过滤）
+  if (sentences.length >= STYLE_SENTENCE_MIN) {
+    const lengths = sentences.map((s) => s.length)
+    const mean = lengths.reduce((sum, l) => sum + l, 0) / lengths.length
+    if (mean > 0) {
+      const variance = lengths.reduce((sum, l) => sum + (l - mean) ** 2, 0) / lengths.length
+      const cv = Math.sqrt(variance) / mean
+      if (cv < STYLE_SENTENCE_CV_MIN) {
+        messages.push(
+          `句长节奏过平：${sentences.length} 句变异系数 ${cv.toFixed(2)}（阈值 ${STYLE_SENTENCE_CV_MIN.toFixed(2)}）——长短句交替不足`,
+        )
+      }
+    }
+  }
+  return messages
+}
+
 /**
  * 静态体检（五期 §9.6）：只查文件规范，不调模型。返回
  *   { ok, problems: [{ level: 'error'|'warn', file, message }], summary }
@@ -802,6 +897,9 @@ export function checkProject(novelDir) {
 
   const stems = new Set()
   const nums = new Set()
+  // 全书已写章节的最大卷章序数（vol,num）：伏笔超期检查的比对基准。规范文件名
+  // 优先；不合规范但 frontmatter 卷号章号可解析的章按 frontmatter 口径补入。
+  let maxWritten = null
   for (const file of chapterFiles) {
     const stem = file.slice(0, -3)
     stems.add(stem)
@@ -813,10 +911,12 @@ export function checkProject(novelDir) {
     }
     let meta = {}
     let fmRaw = null
+    let chapterBody = '' // AI 味统计要在循环尾用正文，try 块里的 parsed 出了作用域
     try {
       const parsed = parseChapterFile(readFileSync(path.join(chaptersDir, file), 'utf8'))
       meta = parsed.meta
       fmRaw = parsed.raw
+      chapterBody = parsed.body
     } catch {
       push('error', rel, '章节文件读取失败')
       continue
@@ -833,6 +933,16 @@ export function checkProject(novelDir) {
       push('error', rel, `status 越枚举：${meta.status}（合法值 pending|writing|review|accepted）`)
     }
     if (Number.isInteger(meta.num)) nums.add(meta.num)
+    // 汇总最大卷章序数：文件名可解析用文件名；否则退 frontmatter volume+num
+    // （裸章号口径的卷号记 0）。vol*1000+num 线性化比较——单卷章数远不到千。
+    const ordNum = key !== null ? key.num : (Number.isInteger(meta.num) ? meta.num : null)
+    if (ordNum !== null) {
+      const volMatch = /^v(\d+)$/.exec(typeof meta.volume === 'string' ? meta.volume.trim() : '')
+      const ordVol = key !== null ? key.vol : (volMatch !== null ? Number(volMatch[1]) : 0)
+      if (maxWritten === null || ordVol * 1000 + ordNum > maxWritten.vol * 1000 + maxWritten.num) {
+        maxWritten = { vol: ordVol, num: ordNum }
+      }
+    }
     const missingDims = FIVE_DIM_KEYS.filter((k) => meta[k] === undefined || meta[k] === '')
     if (missingDims.length > 0) push('warn', rel, `五维字段缺失：${missingDims.join('、')}`)
     if (meta.summary === undefined || meta.summary === '') push('warn', rel, 'summary 缺失（index.yml 与 stats 直接引用）')
@@ -854,6 +964,10 @@ export function checkProject(novelDir) {
     if (typeof meta.writer === 'string' && meta.writer !== '' && !CHAPTER_WRITERS.includes(meta.writer)) {
       push('error', rel, `writer 越枚举：${meta.writer}（合法值 author|ai）`)
     }
+    // AI 味统计（warn）：只查有正文的章；指标与阈值见 checkChapterStyle
+    if (chapterBody.trim() !== '') {
+      for (const message of checkChapterStyle(chapterBody)) push('warn', rel, message)
+    }
   }
 
   // —— foreshadows.yml：状态枚举、id 去重、章节引用、状态-字段自洽 ——
@@ -906,6 +1020,23 @@ export function checkProject(novelDir) {
     ) {
       push('error', 'foreshadows.yml', `伏笔 ${label} 的 resolved_chapter（${resolvedRef}）早于 planted_chapter（${f.planted_chapter}）`)
     }
+    // 清理纪律（skills/maoying-foreshadow-discipline/SKILL.md「清理纪律」：
+    // planted 超过 30 章未推进应升级推进或弃用）：planted 且埋设章可解析时，
+    // 与全书已写章节的最大卷章序数求间隔章数，超过阈值给 warn。
+    // abandoned/resolved/progressing 不查，埋设章解析不出（非规范写法）跳过。
+    // 与上面 expected_resolve 的反向提醒语义不同（那边查排期目标章是否已写出，
+    // 这边查时间跨度），同一条伏笔可能双报——允许。
+    if (f.status === 'planted' && plantedOrd !== null && maxWritten !== null) {
+      // 带卷引用按 vol*1000+num 线性化相减（卷内即章号差，跨卷差值上千、必然
+      // 超阈值）；裸章号无卷信息，与最大章号直接相减（同 nums 的存在性口径）。
+      const gap =
+        plantedOrd.vol === 0
+          ? maxWritten.num - plantedOrd.num
+          : maxWritten.vol * 1000 + maxWritten.num - (plantedOrd.vol * 1000 + plantedOrd.num)
+      if (gap > FORESHADOW_STALE_CHAPTERS) {
+        push('warn', 'foreshadows.yml', `伏笔 ${label} 埋设于 ${f.planted_chapter}，已 ${gap} 章未推进（阈值 ${FORESHADOW_STALE_CHAPTERS} 章）——确认是否遗忘`)
+      }
+    }
   })
 
   // —— timeline.yml：年份可解析、不倒挂（warn：故事内纪年本就允许花写）——
@@ -939,6 +1070,17 @@ export function checkProject(novelDir) {
     }
   })
 
+  // —— outlines/*.md：章纲缺「钩子」小节（warn：章纲本身可选，写了就须带钩子节）——
+  // 章纲纯 markdown 无 frontmatter；「钩子」或「章尾钩子」须独立成节写明
+  // （#{1,3} 级标题行，见 OUTLINE_HOOK_RE）。空 outlines/ 目录（或缺目录）不报。
+  const outlinesDir = path.join(novelDir, OUTLINES_DIR)
+  for (const file of listMdFiles(outlinesDir)) {
+    const text = readTextOrNull(path.join(outlinesDir, file))
+    if (text !== null && !OUTLINE_HOOK_RE.test(text)) {
+      push('warn', outlineFile(file.slice(0, -3)), '章纲缺「钩子」小节（## 钩子 或 ## 章尾钩子）——章尾钩子须独立成节写明')
+    }
+  }
+
   // —— characters/*.md：name 缺失是硬伤；重复键给 warn ——
   for (const card of cards) {
     if (typeof card.meta.name !== 'string' || card.meta.name.trim() === '') {

package/lib/panel-core.mjs

@@ -10,21 +10,42 @@
  *     parseStateSnapshot(novelDir) docs/creator-panel.md §3 的全量快照
  *                                  （五期起含 outlines 章纲清单）
  *     readChapter(novelDir, file)  章节正文全文（抽屉用；五期起带对应章纲
- *                                  outline 字段）
+ *                                  outline 字段，二者各带原文 sha256 hash——
+ *                                  面板正文/章纲编辑保存的 base_hash 基线）
  *     readOutlineFile(novelDir, file) 章纲全文（章纲弹层用；0.1.15 起按单
  *                                  写作的未建章章纲可看全文）
  *     projectFileHash(novelDir)    project.yml 原文 sha256 hex（快照
  *                                  project_hash / 保存旧版检测共用基线）
+ *     readStyleState(novelDir)     写作风格基准 novel/style.md 全文 + 指纹 +
+ *                                  插件模板全文（面板「写作风格」tab 取数，
+ *                                  found:false 表示文件尚未创建、不是错误）
  *
  *   写入面（行级原地替换三件套：读原文 → 手术 → 写后校验替换计数 === 1；
  *   计数不符或目标行缺失一律 409 拒写不落盘，把对 git diff 的扰动压到最小。
- *   createChapterFromOutline 是唯一例外——它从章纲落一个全新章节文件，不动
- *   任何既有文件的字节）
+ *   createChapterFromOutline 是例外之一——它从章纲落一个全新章节文件，不动
+ *   任何既有文件的字节；saveStyleText 是例外之二——style.md 是纯 markdown
+ *   基准文档、无 frontmatter/行级键位可言，整文件覆写就是它的最小手术；
+ *   mutateChapterBody 是例外之三——正文是自由形态文本，写原语是「frontmatter
+ *   围栏定位 + 围栏后整段替换」，围栏（含）之前逐字节保留；mutateOutlineBody
+ *   是例外之四——章纲纯 markdown，整文件替换。后四者写前都读原文比对
+ *   baseHash（人工改动保护与 mutateProject 同口径））
  *     mutateChapterStatus     章节 frontmatter 的 status 行
  *     mutateForeshadowStatus  foreshadows.yml 对应 id 条目块内的 status 行
  *     mutatePhase             project.yml 的 phase 行
  *     rebuildIndex            复用 lib/novel-parse 的 buildIndexYaml 重建
  *     createChapterFromOutline   从章纲建章（chapters/ 落 pending 空章，0.1.15）
+ *     saveStyleText           写作风格基准整文件覆写（novel/style.md，0.1.19）
+ *     mutateChapterBody       章节正文整段替换（面板正文编辑态保存）
+ *     mutateOutlineBody       章纲整文件替换（面板章纲对照栏编辑态保存）
+ *
+ *   受管文件面（0.1.20「全量可编辑写面」：白名单内的账本 yml / md 实体卡 /
+ *   章纲 / 章节删除走通用通道；白名单与结构校验口径见文末该节注释）
+ *     managedRelCheck         rel 白名单校验（按操作分类）
+ *     validateManagedText     保存/新建前的结构校验（解析失败/缺围栏 422）
+ *     readManagedFile         读全文 + 指纹（file-source）
+ *     saveManagedFile         整文件覆写 + 409 过期基线保护（file-save）
+ *     createManagedFile       新建（已存在 409）（file-create）
+ *     deleteManagedFile       删除（不存在 404，UI 层二次确认）（file-delete）
  *
  * 错误约定：本模块抛 PanelError（带 statusCode），路由层按 statusCode 回
  * JSON（403 拒绝 / 404 找不到 / 409 拒写 / 422 入参不合法）；未带状态码的
@@ -35,11 +56,10 @@
  * 绝不让它炸掉整个快照。
  */
 
-import { createHash } from 'node:crypto'
 import { mkdirSync, existsSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
 import path from 'node:path'
 
-import { buildIndexYaml, canonicalVolume, chapterSortKey, collectChapters, countCjk, FIVE_DIM_KEYS, parseFlatYamlArray, parseScalarText, splitFrontmatter, stripInlineComment } from './novel-parse.mjs'
+import { buildIndexYaml, canonicalVolume, chapterSortKey, collectChapters, countCjk, FIVE_DIM_KEYS, parseFlatYamlArray, parseScalarText, sha256Hex, splitFrontmatter, stripInlineComment } from './novel-parse.mjs'
 import { loadYamlLib, resolveDshHome } from './yaml-loader.mjs'
 
 /** 章节状态机（与 lib/novel-parse 的表同源：只取键）。 */
@@ -405,10 +425,7 @@ function readProject(novelDir, yamlLib, warnings) {
   }
 }
 
-/** sha256 hex（小写）：文本 → 指纹。 */
-function sha256Hex(text) {
-  return createHash('sha256').update(text, 'utf8').digest('hex')
-}
+/** sha256 hex（小写）：从 novel-parse 引全仓库唯一实现，本文件不再私有手搓。 */
 
 /**
  * project.yml 原文指纹（sha256 hex）：面板「人工改动保护」的基线。快照带出
@@ -426,6 +443,69 @@ export function projectFileHash(novelDir) {
   return sha256Hex(text)
 }
 
+/**
+ * 插件内置写作风格模板（templates/novel/style.md）全文：readStyleState 的
+ * template 字段原料——style.md 尚未创建时，面板用它在编辑器里预填默认基线。
+ * 每次现读（35 行小文件，不值得缓存）；读不到返回 null，面板据此禁用
+ * 「用默认基线创建」按钮，不炸面板。
+ */
+function styleTemplateText() {
+  try {
+    return readFileSync(new URL('../templates/novel/style.md', import.meta.url), 'utf8')
+  } catch {
+    return null
+  }
+}
+
+/**
+ * 写作风格基准读取（0.1.19，面板「写作风格」tab 取数）：novel/style.md 存在
+ * 则读全文 + sha256 指纹（hash 即保存路由 base_hash 的基线，口径与
+ * projectFileHash 一致）；不存在返回 found:false、text/hash 为 null——文件
+ * 尚未创建是常态不是错误，路由照 200 回，客户端空态引导创建。读失败不炸
+ * （照 projectFileHash 的宽容口径，读不动一律按不存在处理）。template 恒为
+ * 插件模板全文（读不到为 null）。
+ */
+export function readStyleState(novelDir) {
+  const template = styleTemplateText()
+  let text = null
+  try {
+    text = readFileSync(path.join(path.resolve(novelDir), 'style.md'), 'utf8')
+  } catch {
+    return { found: false, text: null, hash: null, template }
+  }
+  return { found: true, text, hash: sha256Hex(text), template }
+}
+
+/**
+ * 写作风格基准保存（0.1.19，面板「写作风格」tab 的编辑态）：novel/style.md
+ * 整文件覆写——纯 markdown 基准文档，无行级键位可言，整文件替换即最小手术
+ * （「行级原地替换」纪律的例外，与 agent 的写法兼容：写前读、原子写）。
+ *
+ * 校验：text 非 string 422。人工改动保护与 mutateProject 同口径：options.
+ * baseHash 是面板载入编辑器时的原文指纹，与写入前现读不一致 → 409 拒写；
+ * 文件不存在且 baseHash 非 null 同样 409（调用方声称基于既有版本改，磁盘却
+ * 无文件，宁可不写）；未传 baseHash 跳过检查（创建路径：文件不存在时直接
+ * 落盘）。空文本允许保存（空文件 = 无风格基准，agent 侧优雅降级）。
+ * 返回写后新指纹 hash，客户端下一轮 base_hash 直接取它。
+ */
+export function saveStyleText(novelDir, text, options = {}) {
+  if (typeof text !== 'string') fail(422, 'text 必须是字符串（style.md 全文）')
+  const target = path.join(path.resolve(novelDir), 'style.md')
+  let current = null
+  try {
+    current = readFileSync(target, 'utf8')
+  } catch {
+    current = null // 不存在（读不动也按不存在处理，宽容口径同 readStyleState）
+  }
+  const baseHash = typeof options.baseHash === 'string' ? options.baseHash.trim().toLowerCase() : ''
+  if (baseHash !== '' && (current === null || baseHash !== sha256Hex(current))) {
+    fail(409, 'style.md 已被外部修改，请刷新面板后基于最新内容重改再存')
+  }
+  writeAtomic(target, text)
+  // 返回写后指纹：客户端下一轮保存的 base_hash 直接取它，不必再拉一次快照。
+  return { ok: true, hash: sha256Hex(text) }
+}
+
 /**
  * 全量快照（docs/creator-panel.md §3，字段名冻结）。novelDir 为工作区的
  * novel 目录；project.yml 不在 = 未初始化（found: false，其余字段缺省）。
@@ -606,8 +686,10 @@ export function parseStateSnapshot(novelDir, options = {}) {
 /**
  * 章纲定位（readChapter 的 outline 字段，五期）：outlines/ 下与章节同 stem
  * 的文件。章纲纯 markdown 无 frontmatter，words 为全文 CJK 计数、body 为
- * 原文；无对应文件（含 outlines/ 目录不存在）返回 null——无章纲是常态，
- * 不告警。stem 已过 safeFileName，拼接结果不可能越出 novel 根。
+ * 原文、hash 为原文 sha256（面板章纲编辑保存的 base_hash 基线，与 body 同源
+ * 同刻读出——拆开读会有被外部改动的窗口）；无对应文件（含 outlines/ 目录不
+ * 存在）返回 null——无章纲是常态，不告警。stem 已过 safeFileName，拼接结果
+ * 不可能越出 novel 根。
  */
 function readOutline(novelDir, stem) {
   let text = null
@@ -616,20 +698,22 @@ function readOutline(novelDir, stem) {
   } catch {
     return null
   }
-  return { file: `${stem}.md`, words: countCjk(text), body: text }
+  return { file: `${stem}.md`, words: countCjk(text), body: text, hash: sha256Hex(text) }
 }
 
 /**
  * 章节全文（抽屉用）：路径校验同写路由；frontmatter 以对象返回（yaml 可用
- * 走真解析，否则平键回退），body 为原文正文；outline 为同 stem 章纲
- * （{ file, words, body }，无对应章纲时 null），章节抽屉的章纲对照栏取数。
+ * 走真解析，否则平键回退），body 为原文正文，hash 为章节文件原文 sha256
+ * （人工改动保护：正文编辑态保存时作 base_hash 回传，外部改动 409 拒写）；
+ * outline 为同 stem 章纲（{ file, words, body, hash }，无对应章纲时 null），
+ * 章节抽屉的章纲对照栏取数。
  */
 export function readChapter(novelDir, file, options = {}) {
   const { name, target } = locateChapter(novelDir, file)
   const text = readTarget(target, `章节 ${name}`)
   const { meta, body } = parseFrontmatterMeta(text, yamlLibOf(options))
   const outline = readOutline(novelDir, name.replace(/\.md$/i, ''))
-  return { ok: true, file: name, frontmatter: meta, body, outline }
+  return { ok: true, file: name, frontmatter: meta, body, hash: sha256Hex(text), outline }
 }
 
 /**
@@ -700,6 +784,78 @@ export function createChapterFromOutline(novelDir, file) {
   return { ok: true, file: `${stem}.md`, title }
 }
 
+// ── 正文/章纲写原语（面板编辑态保存）：自由形态 body，无行级键位可手术 ─────
+
+/**
+ * 章节正文保存（面板章节阅读页编辑态）：frontmatter 围栏（含闭合 --- 行）
+ * 之前逐字节保留，围栏后整段替换——正文是自由形态文本，任何行级手术都会
+ * 凭空改写作者的文字，整段替换才是最小干预；对 git diff 的扰动天然只落在
+ * 正文段内。校验与拒写：
+ *   - file 只认 chapters/ 下纯文件名（locateChapter 同款双保险，穿越 403）；
+ *   - body 非 string 422；章节缺 frontmatter 围栏 422（先补齐再编辑）；
+ *   - 章节不存在 404；
+ *   - options.baseHash 是编辑态载入时的原文指纹（chapter 路由的 hash），
+ *     归一（trim + 小写）后与写入前现读不一致 → 409 拒写不落盘（人工改动
+ *     保护，与 mutateProject 同口径）；未传跳过检查（旧调用方兼容）。
+ * 正文末尾无换行补一个 \n（ POSIX 文本文件惯例，textarea 草稿常缺尾换行）。
+ * 返回 { ok, hash }——写后新指纹，客户端下一轮 base_hash 直接取它。
+ */
+export function mutateChapterBody(novelDir, file, body, options = {}) {
+  if (typeof body !== 'string') fail(422, 'body 必须是字符串（章节正文全文）')
+  const { name, target } = locateChapter(novelDir, file)
+  const text = readTarget(target, `章节 ${name}`)
+  const fence = splitFrontmatter(text)
+  if (fence.raw === null) fail(422, `章节 ${name} 缺少 frontmatter 围栏，请先补齐再在面板编辑正文`)
+  // 旧版检测在读原文之后、落笔之前：指纹不一致就地 409，一个字节都不动。
+  const baseHash = typeof options.baseHash === 'string' ? options.baseHash.trim().toLowerCase() : ''
+  if (baseHash !== '' && baseHash !== sha256Hex(text)) {
+    fail(409, `章节文件已被外部修改，请刷新后基于最新内容重改再存：${name}`)
+  }
+  // 围栏闭合行从原文原样切出（与 splitFrontmatter 的闭合正则同形）——
+  // CRLF/行尾空白等字节一字不动，改写它的刀不属于正文编辑。
+  const cut = fence.index + fence.raw.length
+  const closeM = /\r?\n---[ \t]*(?:\r?\n|$)/.exec(text.slice(cut))
+  let preserved = text.slice(0, cut + closeM[0].length)
+  // 退化形状：闭合 --- 是文件末行且无换行（罕见），补一个换行防正文黏上围栏行。
+  if (!preserved.endsWith('\n')) preserved += '\n'
+  const next = preserved + (body.endsWith('\n') ? body : `${body}\n`)
+  writeAtomic(target, next)
+  // 返回写后指纹：客户端下一轮保存的 base_hash 直接取它，不必重拉章节。
+  return { ok: true, hash: sha256Hex(next) }
+}
+
+/**
+ * 章纲保存（面板章节阅读页章纲对照栏编辑态）：章纲纯 markdown 无
+ * frontmatter（spec §outlines），整文件替换即最小手术（与 saveStyleText
+ * 同一判断）。file 接受章节文件名或 stem（v01-c001.md / v01-c001 皆可——
+ * 调用方手里是章节上下文，不强迫换算），校验与 readOutlineFile 同口径：
+ * safeFileName（穿越 403）+ chapterSortKey（stem 不合 vXX-cXXX 规范 422）；
+ * 目标恒为 outlines/<stem>.md，章纲不存在 404（v1 不提供面板新建章纲）。
+ * baseHash 人工改动保护与 mutateChapterBody 同口径，409 文案点名章纲。
+ * 返回 { ok, hash }——写后新指纹。
+ */
+export function mutateOutlineBody(novelDir, chapterFile, body, options = {}) {
+  if (typeof body !== 'string') fail(422, 'body 必须是字符串（章纲全文）')
+  const name = safeFileName(chapterFile, 'file')
+  const stem = name.replace(/\.md$/i, '')
+  if (chapterSortKey(stem) === null) fail(422, `非章纲文件名（stem 不合 vXX-cXXX 规范）：${name}`)
+  const target = path.join(path.resolve(novelDir), 'outlines', `${stem}.md`)
+  let current = null
+  try {
+    current = readFileSync(target, 'utf8')
+  } catch (err) {
+    if (err?.code === 'ENOENT') fail(404, `章纲不存在：outlines/${stem}.md`)
+    fail(500, `章纲读取失败（${err?.code ?? err?.message ?? err}）`)
+  }
+  const baseHash = typeof options.baseHash === 'string' ? options.baseHash.trim().toLowerCase() : ''
+  if (baseHash !== '' && baseHash !== sha256Hex(current)) {
+    fail(409, `章纲文件已被外部修改，请刷新后基于最新内容重改再存：outlines/${stem}.md`)
+  }
+  const next = body.endsWith('\n') ? body : `${body}\n`
+  writeAtomic(target, next)
+  return { ok: true, hash: sha256Hex(next) }
+}
+
 // ── 写操作：行级原地替换 ────────────────────────────────────────────────────
 
 /**
@@ -899,3 +1055,184 @@ export function rebuildIndex(novelDir) {
   writeAtomic(path.join(novelDir, 'index.yml'), text)
   return { ok: true, chapters: chaptersCount }
 }
+
+// ── 受管文件（0.1.20「全量可编辑写面」）：通用读/存/建/删 ────────────────────
+//
+// 边界口径（docs/creator-panel.md §0）：语义规则（状态机、必填章号、memories
+// 不改旧账等）是 agent 纪律，不是人工编辑的禁区。人工编辑走「保存时结构校验
+// （解析失败/缺围栏 422 拒存）+ 保存后语义体检（check 黄条 / CLI check）+
+// git 回滚兜底」；所以这里的结构校验只管「面板存得进、快照就读得出」这一层，
+// 其余语义一律不问——留给 check。
+//
+// 白名单按操作分类、集中一处定义（只此一份，路由层不做二次判断）：
+//   - 读/存/建/删皆可：六个账本 yml + 四个 md 实体目录（slug 卡）+ outlines
+//     章纲（stem 复用 chapterSortKey）。md 实体卡与账本是快照与 agent 共享的
+//     数据源，人工改它们正是本次开放的目的。
+//   - 仅删：chapters/<vXX-cXXX>.md。正文有 chapter-save 专用路由（frontmatter
+//     围栏保护 + 状态机语义在那边），通用存若放开会绕过这层；删除是建章/重写
+//     的前置动作，必须开放，且 chapter-create 一条路即可重建。
+//   - 绝不进白名单：index.yml（派生文件，rebuild-index 覆盖，编辑无意义且
+//     误导——改完下次重建就被冲掉）、project.yml（有 project-save 表单路由，
+//     枚举/注释保留逻辑在那边）、novel/style.md（有 style-save 专用路由）。
+//     这三个不在 yml 六件套里，靠枚举穷举天然挡住；chapters 通用存靠操作分类
+//     挡住。rel 不在白名单一律 403——防穿越与防越权同码，不给探测回显差异。
+
+/** 受管 md 实体目录（<slug>.md，slug 全小写）。 */
+const MANAGED_MD_DIRS = ['characters', 'world', 'science', 'research']
+
+/** 受管顶层账本 yml（六个，快照同源读取）。 */
+const MANAGED_YML_FILES = ['relations.yml', 'timeline.yml', 'memories.yml', 'clue-board.yml', 'foreshadows.yml', 'volumes.yml']
+
+/** md 实体卡 slug 规范：全小写字母/数字，`-` 连接，不以 `-` 开头。 */
+const MANAGED_SLUG_RE = /^[a-z0-9][a-z0-9-]*$/
+
+/**
+ * rel 白名单校验：op ∈ read|save|create|delete。校验不过（缺参/slug 或 stem
+ * 不合规范）422，rel 不在白名单（含穿越形状与仅删目录的非删操作）403。返回
+ * { dir, name, kind }——kind 供 validateManagedText 分派结构校验口径。
+ */
+export function managedRelCheck(rel, op) {
+  if (typeof rel !== 'string' || rel.trim() === '') fail(422, '缺少 rel 参数（novel 根内的相对路径）')
+  if (rel.includes('\\')) fail(403, `rel 含反斜杠，已拒绝：${rel}`) // Windows 分隔符一律不认，形状先钉死
+  const segments = rel.split('/')
+  if (segments.length > 2) fail(403, `rel 超出「目录/文件名」一层深度，已拒绝：${rel}`)
+  const dir = segments.length === 2 ? segments[0] : ''
+  const name = segments[segments.length - 1]
+  if (dir === '' && MANAGED_YML_FILES.includes(name)) return { dir: '', name, kind: 'yml' }
+  if (dir !== '' && MANAGED_MD_DIRS.includes(dir)) {
+    if (!/\.md$/i.test(name) || !MANAGED_SLUG_RE.test(name.slice(0, -3))) {
+      fail(422, `文件名不合 slug 规范（${MANAGED_SLUG_RE.source} + .md）：${rel}`)
+    }
+    return { dir, name, kind: 'md' }
+  }
+  if (dir === 'outlines') {
+    const stem = name.replace(/\.md$/i, '')
+    if (!/\.md$/i.test(name) || chapterSortKey(stem) === null) {
+      fail(422, `章纲文件名不合 vXX-cXXX 规范：${rel}`)
+    }
+    return { dir, name, kind: 'outline' }
+  }
+  if (dir === 'chapters') {
+    // 仅删：正文存/读各有专用路由（chapter-save / chapter），通用通道只放
+    // 删除——放开通用存会绕过 frontmatter 围栏保护与状态机语义。
+    if (op !== 'delete') fail(403, `chapters/ 只开放删除（正文编辑走 chapter-save），已拒绝：${rel}`)
+    const stem = name.replace(/\.md$/i, '')
+    if (!/\.md$/i.test(name) || chapterSortKey(stem) === null) {
+      fail(422, `章节文件名不合 vXX-cXXX 规范：${rel}`)
+    }
+    return { dir, name, kind: 'chapter' }
+  }
+  fail(403, `rel 不在受管文件白名单内，已拒绝：${rel}`)
+}
+
+/** 白名单校验之后再来一道 resolve 包含校验：拼接结果必须落在 novel 根内
+ * （双保险防符号形状的意外，与 locateChapter 同纪律）。 */
+function managedTargetOf(novelDir, rel, op) {
+  const check = managedRelCheck(rel, op)
+  const root = path.resolve(novelDir)
+  const target = path.resolve(root, rel)
+  const within = path.relative(root, target)
+  if (within === '' || within.startsWith('..') || path.isAbsolute(within)) {
+    fail(403, `受管路径越界，已拒绝：${rel}`)
+  }
+  return { ...check, target }
+}
+
+/**
+ * 读受管文件（面板编辑态打开时取数）：不存在 404。hash 为原文 sha256，作
+ * file-save 的 base_hash 基线——与 chapter 路由同口径（读与指纹同刻同源）。
+ */
+export function readManagedFile(novelDir, rel) {
+  const { target } = managedTargetOf(novelDir, rel, 'read')
+  const text = readTarget(target, `源文件 ${rel}`)
+  return { ok: true, rel, text, hash: sha256Hex(text) }
+}
+
+/**
+ * 受管文本的结构校验（保存/新建共一道门，服务端只验形状）：
+ *   - 六个账本 yml：按快照同源口径解析（yamlLib 可用走真解析，否则
+ *     parseFlatYamlArray 极简回退——两条路必须同一结论，否则面板存得进、快照
+ *     读不出）；必须解析为顶层数组且条目全是平键对象（空数组/空文件允许）。
+ *     快照会把 null/裸标量/数组条目/空对象条目静默丢弃——存得进却读不出等于
+ *     丢数据，这里一并 422 带原因。
+ *   - 四个 md 实体目录：必须含成对 frontmatter 围栏（其他语义一律不管，留给
+ *     check）；outlines 章纲纯 markdown 无围栏，跳过此检查。
+ */
+export function validateManagedText(rel, text, yamlLib) {
+  const { kind } = managedRelCheck(rel, 'save')
+  if (kind === 'outline') return
+  if (kind === 'yml') {
+    // 空文件（含纯注释/空白）按空表放行：与快照「文件缺失按空表」同一宽容。
+    if (String(text).trim() === '') return
+    let data = null
+    if (yamlLib) {
+      try {
+        data = yamlLib.parse(text)
+      } catch {
+        data = null // 真解析不认——与快照同款回退，不因 yaml 在场而更严
+      }
+    }
+    if (data === null || data === undefined) data = parseFlatYamlArray(text)
+    if (!Array.isArray(data)) fail(422, `${rel} 顶层不是数组——受管账本 yml 只接受「- key: value」条目列表`)
+    data.forEach((item, index) => {
+      const plain = item !== null && typeof item === 'object' && !Array.isArray(item) && Object.keys(item).length > 0
+      if (!plain) fail(422, `${rel} 第 ${index + 1} 条不是平键对象（快照会静默丢弃该条，请删掉或补全后再存）`)
+    })
+    return
+  }
+  // md 实体卡：只验围栏成对，卡内键值/枚举全不问（角色 role 越枚举这类语义
+  // 由 check 标黄条，人工编辑不因此被挡）。
+  if (splitFrontmatter(text).raw === null) fail(422, `${rel} 缺少成对的 frontmatter 围栏（--- … ---），请补齐后再存`)
+}
+
+/**
+ * 存受管文件（编辑态保存）：目标不存在 404（新建走 file-create，一条路一个
+ * 语义）；text 非 string 422；base_hash 过期 409 拒写不落盘（人工改动保护，
+ * 与 project-save 同口径文案）；结构校验 422 带原因。写前读、原子写，尾无
+ * 换行补一个 \n（POSIX 文本文件惯例，与正文/章纲保存同惯例）。返回写后新
+ * 指纹 hash，客户端下一轮 base_hash 直接取它。
+ */
+export function saveManagedFile(novelDir, rel, text, options = {}) {
+  if (typeof text !== 'string') fail(422, 'text 必须是字符串（文件全文）')
+  validateManagedText(rel, text, yamlLibOf(options))
+  const { target } = managedTargetOf(novelDir, rel, 'save')
+  const current = readTarget(target, `源文件 ${rel}`)
+  const baseHash = typeof options.baseHash === 'string' ? options.baseHash.trim().toLowerCase() : ''
+  if (baseHash !== '' && baseHash !== sha256Hex(current)) {
+    fail(409, `${rel} 已被外部修改，请刷新后基于最新内容重改再存`)
+  }
+  const next = text.endsWith('\n') ? text : `${text}\n`
+  writeAtomic(target, next)
+  return { ok: true, rel, hash: sha256Hex(next) }
+}
+
+/**
+ * 新建受管文件：已存在 409（先到先建，绝不覆盖——与 chapter-create 同纪律）；
+ * 结构校验同 saveManagedText（新角色卡/新章纲由客户端模板预填，服务端只验
+ * 形状）。目录缺席先建（新 slug 落在还没建过的目录、测试夹具都可能出现）。
+ */
+export function createManagedFile(novelDir, rel, text, options = {}) {
+  if (typeof text !== 'string') fail(422, 'text 必须是字符串（文件全文）')
+  const { target } = managedTargetOf(novelDir, rel, 'create')
+  if (existsSync(target)) fail(409, `${rel} 已存在——不覆盖既有文件，改名或改走编辑`)
+  validateManagedText(rel, text, yamlLibOf(options))
+  const next = text.endsWith('\n') ? text : `${text}\n`
+  mkdirSync(path.dirname(target), { recursive: true })
+  writeAtomic(target, next)
+  return { ok: true, rel, hash: sha256Hex(next) }
+}
+
+/**
+ * 删除受管文件：不存在 404。不可逆操作，服务端不做二次确认（UI 层强制确认
+ * 弹层），白名单上它是最严的一档（见 managedRelCheck）。
+ */
+export function deleteManagedFile(novelDir, rel) {
+  const { target } = managedTargetOf(novelDir, rel, 'delete')
+  try {
+    unlinkSync(target)
+  } catch (err) {
+    if (err?.code === 'ENOENT') fail(404, `源文件不存在：${rel}`)
+    fail(500, `源文件删除失败（${err?.code ?? err?.message ?? err}）`)
+  }
+  return { ok: true, rel }
+}