@waterwx/dsh-novel-forge 1.3.1 → 1.3.2-alpha

package/src/run.ts

@@ -15,6 +15,7 @@ import {
   planChapters,
   generateChapterStream,
   summarizeAndExtractFacts,
+  extractTimelineForChapter,
   markForeshadowPlanted,
   reviewChapter,
   reviewChapterText,
@@ -24,13 +25,39 @@ import {
   rewriteChapterStream,
   chapterFileName,
 } from './engine.ts'
+import { countHanzi } from './engine.ts'
 import { loadBookshelf } from './bookshelf.ts'
+import { buildRevisionPlan, describeRevisionPlan, MAX_REVISION_ROUNDS, revisionTodoText } from './revision.ts'
 
 /** 生产单 checkpoint 文件名（放在书目录下）。 */
 function runStateFile(outputDir: string): string {
   return join(outputDir, 'run-state.json')
 }
 
+/**
+ * 解析某个输出目录的书名（用于旧 run-state.json 的兜底）。
+ * 优先项目文件里的 bookName，其次目录名——两者都没有时返回空串。
+ * @param outputDir - 该书输出目录。
+ */
+export function resolveRunBookName(outputDir: string): string {
+  const fromProject = loadProject(outputDir)?.bookName
+  if (typeof fromProject === 'string' && fromProject.trim() !== '') return fromProject.trim()
+  const base = outputDir.replace(/[\\/]+$/, '').split(/[\\/]/).pop() ?? ''
+  return base.trim()
+}
+
+/**
+ * 一句话描述"正在跑的是哪本书的哪一章"。
+ * 面板状态行与 409 报错共用，避免两处各写各的（也便于单测覆盖）。
+ * @param state - 运行中的生产单状态。
+ */
+export function describeRunningBatch(state: RunState): string {
+  const name = typeof state.bookName === 'string' && state.bookName.trim() !== ''
+    ? `《${state.bookName.trim()}》`
+    : '未标注书目'
+  return `${name}第${state.currentNo}章`
+}
+
 export class ProductionRunner {
   private state: RunState | null = null
   private working = false
@@ -57,6 +84,11 @@ export class ProductionRunner {
         if (parsed?.runId === undefined) continue
         // 重启恢复：若之前 running，则视为可续跑（loop 未在跑）。
         if (parsed.status === 'running') parsed.status = 'paused'
+        // 旧 run-state.json 没有 bookName：用该目录的项目名兜底，再退回目录名，
+        // 保证"这是哪本书"永远有答案（否则芯片/面板会显示一个无法归属的状态）。
+        if (parsed.bookName === undefined || parsed.bookName === '') {
+          parsed.bookName = resolveRunBookName(outputDir)
+        }
         this.state = parsed
         this.bookDir = outputDir
         return this.state
@@ -80,26 +112,34 @@ export class ProductionRunner {
   }
 
   /** 启动/续跑生产单：startNo..endNo 区间，endNo 超出计划时先自动补计划。 */
-  async start(startNo: number, endNo: number): Promise<RunState> {
+  async start(startNo: number, endNo: number, runDir?: string): Promise<RunState> {
     const config = this.deps.getConfig()
-    if (this.working) throw new Error('生产单正在运行中，请先暂停或停止')
-    let project = loadProject(config.outputDir)
+    if (this.working) {
+      // 报错要说清"在跑哪本书的哪一章"：全局单实例，含糊的提示会让多书用户无从下手。
+      const running = this.state
+      throw new Error(running === null
+        ? '生产单正在运行中，请先暂停或停止'
+        : `生产单正在运行中（${describeRunningBatch(running)}），请先暂停或停止`)
+    }
+    const outputDir = runDir ?? config.outputDir
+    let project = loadProject(outputDir)
     if (project === undefined) throw new Error('输出目录中没有项目')
 
     // 计划补足：目标区间超出已有计划 → 续写规划追加。
     if (endNo > project.chapters.length) {
       const need = endNo - project.chapters.length
       this.log(`计划不足，追加 ${need} 章计划…`)
-      const chapters = await planChapters(this.deps.ctx, config, project, need, undefined, config.outputDir)
-      mergeVolatileFromDisk(config.outputDir, project)
+      const chapters = await planChapters(this.deps.ctx, config, project, need, undefined, outputDir)
+      mergeVolatileFromDisk(outputDir, project)
       project.chapters.push(...chapters)
       project.updatedAt = new Date().toISOString()
-      saveProject(config.outputDir, project)
+      saveProject(outputDir, project)
       this.log(`计划已追加，全书 ${project.chapters.length} 章`)
     }
 
     this.state = {
       runId: `run-${Date.now().toString(36)}`,
+      bookName: project.bookName,
       startNo,
       endNo,
       status: 'running',
@@ -113,7 +153,7 @@ export class ProductionRunner {
     this.pauseRequested = false
     this.stopRequested = false
     // 绑定生产单目录（快照）：运行期间切书不影响本单的读写目标。
-    this.bookDir = config.outputDir
+    this.bookDir = outputDir
     this.working = true
     this.persist()
     void this.loop()
@@ -132,6 +172,9 @@ export class ProductionRunner {
   }
   stop(): void { this.stopRequested = true }
 
+  /** 是否有生产单正在执行（目录迁移等磁盘级操作前须为 false）。 */
+  isWorking(): boolean { return this.working }
+
   /** 主循环：从 currentNo 扫描到 endNo，逐章处理；支持暂停/停止。 */
   private async loop(): Promise<void> {
     // 全部读写固定使用生产单绑定目录（bookDir），绝不跟随当前激活书。
@@ -201,6 +244,42 @@ export class ProductionRunner {
       chapter.status = 'pending'
       await this.produce(project, chapter)
     }
+    this.auditChapterAdvisories(chapter.no)
+  }
+
+  /**
+   * 出章即核对曲线（建议性，不阻塞）：
+   * 规则初筛得到的时间线矛盾 + 张力曲线偏差写进运行日志；本章已完结时再落成项目待办。
+   * 默认**不**触发任何自动修订——要看/要改由作者在面板发起「一键按建议修订」；
+   * 只有当本章因审稿 high 本来就要修订时，这些问题才搭同一轮车（见 handleRejected），
+   * 因此不额外增加轮次，也不会出现「改完甲又违反乙」。
+   */
+  private auditChapterAdvisories(chapterNo: number): void {
+    const config = this.deps.getConfig()
+    const outputDir = this.bookDir ?? config.outputDir
+    const project = loadProject(outputDir)
+    if (project === undefined) return
+    const chapter = project.chapters.find(c => c.no === chapterNo)
+    if (chapter === undefined) return
+    // reviewIssues 传空数组：这里只核对曲线/时间线，审稿意见走审稿通道。
+    const plan = buildRevisionPlan(project, { chapterNo, reviewIssues: [], includeTimeline: true, includeTension: true })
+    if (plan.items.length === 0) return
+    this.log(`第${chapterNo}章 曲线/时间线核对：${describeRevisionPlan(plan)}——建议性提示，未自动改动`)
+    if (chapter.status !== 'approved') return
+    if (plan.counts.timeline === 0 && plan.counts.tension === 0) return
+    const todos = (project.todos ??= [])
+    const added: string[] = []
+    for (const item of plan.items.slice(0, 3)) {
+      const text = revisionTodoText(item)
+      if (todos.some(t => t.text === text)) continue
+      todos.unshift({ id: `td-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`, text, source: 'risk', done: false, createdAt: new Date().toISOString() })
+      added.push(text)
+    }
+    if (added.length > 0) {
+      project.updatedAt = new Date().toISOString()
+      saveProject(outputDir, project)
+      this.log(`第${chapterNo}章 已登记 ${added.length} 条建议性待办（可在时间线/张力面板一键按建议修订）`)
+    }
   }
 
   /** 完整质量门：生成 → 摘要+事实 → 伏笔标记 → 审稿 → 作者复盘。 */
@@ -215,15 +294,18 @@ export class ProductionRunner {
     chapter.generatingAt = new Date().toISOString()
     mergeVolatileFromDisk(outputDir, project)
     saveProject(outputDir, project)
-    this.log(wasError ? `第${no}章《${chapter.title}》重新生成…` : `第${no}章《${chapter.title}》生成…`)
+    this.log(`${wasError ? '重新生成' : '生成'} 第${no}章《${chapter.title}》…（模型 ${config.generateModel || config.model}）`)
     try {
-      for await (const step of generateChapterStream(ctx, config, project, outputDir, no)) { /* drain */ }
+      for await (const _step of generateChapterStream(ctx, config, project, outputDir, no)) { /* drain */ }
       try { await summarizeAndExtractFacts(ctx, config, project, outputDir, no) } catch (e) { console.warn('[dsh-novel-forge] run summary/facts:', (e as Error).message) }
+      if (config.autoTimeline ?? true) {
+        try { await extractTimelineForChapter(ctx, config, project, outputDir, no) } catch (e) { console.warn('[dsh-novel-forge] run timeline:', (e as Error).message) }
+      }
       try { markForeshadowPlanted(project, outputDir, no) } catch (e) { console.warn('[dsh-novel-forge] run foreshadow:', (e as Error).message) }
       if (config.autoReview ?? true) {
         const report = await reviewChapter(ctx, config, project, outputDir, no)
         if (this.state !== null) this.state.stats[wasError ? 'regenerated' : 'generated']++
-        this.log(`第${no}章 审稿 ${report.score}分 ${report.passed ? '✅ 通过' : '⚠️ 被拒'}`)
+        this.log(`第${no}章 审稿 ${report.score}分 ${report.passed ? ' 通过' : ' 被拒'}（模型 ${config.reviewModel || config.model}）`)
       } else {
         chapter.status = 'approved'
         mergeVolatileFromDisk(outputDir, project)
@@ -241,6 +323,12 @@ export class ProductionRunner {
             const review = await authorReviewChapter(ctx, config, project, no, body, prevTail)
             chapter.authorReview = review
             if (review.advancedLines !== undefined) autoLinkPlotlines(project, no, review.advancedLines)
+            // 结果回灌：把本章状态变化/新线索写进编年录事实库，供后续计划与整本控制用。
+            const backfillFacts: string[] = [...(review.stateChanges ?? []), ...(review.clues ?? [])]
+            if (backfillFacts.length > 0) {
+              project.facts ??= []
+              for (const text of backfillFacts) project.facts.push({ chapterNo: no, text })
+            }
             mergeVolatileFromDisk(outputDir, project)
             saveProject(outputDir, project)
           }
@@ -272,11 +360,15 @@ export class ProductionRunner {
       this.log(`第${no}章 豁免通过（无 high）`)
       return
     }
-    this.log(`第${no}章 修订（${highs.length} 个 high）…`)
-    for (let round = 1; round <= 2; round++) {
-      const instr = '按审稿意见修订（优先处理）：\n' + highs.map(h => `[${h.severity}] ${h.item}${h.suggestion !== '' ? `\n建议：${h.suggestion}` : ''}`).join('\n\n')
+    // 合并层：审稿 high + 时间线矛盾 + 张力偏差 → 一份指令，一轮改完。
+    // 张力/时间线本身不触发修订（建议性），只在「反正要改」时搭车，避免多通道互相覆盖。
+    let plan = buildRevisionPlan(project, { chapterNo: no, reviewIssues: highs, baseReport: report })
+    this.log(`第${no}章 修订（${describeRevisionPlan(plan)}）…`)
+    if (plan.omitted > 0) this.log(`第${no}章 修订指令已截断 ${plan.omitted} 条（超出单轮上限，优先级低者留待下一轮）`)
+    for (let round = 1; round <= MAX_REVISION_ROUNDS; round++) {
+      const instr = plan.instruction
       try {
-        for await (const step of rewriteChapterStream(ctx, config, project, outputDir, no, instr, undefined)) { /* drain */ }
+        for await (const _step of rewriteChapterStream(ctx, config, project, outputDir, no, instr, undefined)) { /* drain */ }
       } catch (error) {
         this.log(`第${no}章 第${round}轮修订出错：${(error as Error).message}`)
         continue
@@ -289,7 +381,8 @@ export class ProductionRunner {
         this.log(`第${no}章 第${round}轮草稿缺失，重试`)
         continue
       }
-      const verify = await reviewChapterText(ctx, config, fresh!, draft, chapter.review)
+      // 验证基准 = 本轮实际下发的全部条目（审稿 + 时间线 + 张力）：复核核对的就是「要求改的东西」。
+      const verify = await reviewChapterText(ctx, config, fresh!, draft, plan.baseline)
       const highs2 = (verify.issues ?? []).filter(i => i.severity === 'high')
       if (verify.passed || highs2.length === 0) {
         // 应用草稿（与 draft/apply 路由同逻辑）：备份原稿 → 落盘 → 定状态。
@@ -299,22 +392,26 @@ export class ProductionRunner {
         return
       }
       this.log(`第${no}章 第${round}轮仍不过（${highs2.length} high）`)
+      // 下一轮重新合并：以本轮仍未解决的 high 为审稿来源，并重新核对时间线/张力
+      // （上一轮基线里已解决的条目不再下发，避免「越修越多」）。
+      plan = buildRevisionPlan(fresh ?? project, { chapterNo: no, reviewIssues: highs2, baseReport: verify })
     }
     if (this.state !== null) this.state.pendingManual.push(no)
-    this.log(`第${no}章 ⚠️ 两轮修订仍不过 → 保留草稿待人工`)
+    this.log(`第${no}章  ${MAX_REVISION_ROUNDS} 轮修订仍不过 → 保留草稿待人工`)
   }
 
   private applyDraft(project: ProjectState, chapter: ChapterPlan, draft: string, report: ReviewReport): void {
     const config = this.deps.getConfig()
+    const outputDir = this.bookDir ?? config.outputDir
     const fileName = chapterFileName(chapter)
-    mkdirSync(config.outputDir, { recursive: true })
-    const targetPath = join(config.outputDir, fileName)
+    mkdirSync(outputDir, { recursive: true })
+    const targetPath = join(outputDir, fileName)
     if (existsSync(targetPath)) {
-      copyFileSync(targetPath, join(config.outputDir, `${fileName.replace(/\.md$/, '')}.bak.md`))
+      copyFileSync(targetPath, join(outputDir, `${fileName.replace(/\.md$/, '')}.bak.md`))
     }
     writeFileSync(targetPath, `# 第${chapter.no}章 ${chapter.title}\n\n${draft}\n`, 'utf8')
     chapter.pendingDraft = undefined
-    chapter.chars = draft.length
+    chapter.chars = countHanzi(draft)
     chapter.file = fileName
     if (typeof report.score === 'number') {
       chapter.review = report
@@ -325,6 +422,6 @@ export class ProductionRunner {
     }
     chapter.error = undefined
     project.updatedAt = new Date().toISOString()
-    saveProject(config.outputDir, project)
+    saveProject(outputDir, project)
   }
 }

package/src/snapshots.ts

@@ -0,0 +1,174 @@
+/**
+ * 章节历史版本（快照）：覆盖写入前自动留存正文，支持列表 / 回滚 / 清理。
+ *
+ * 为什么需要它：生成、按意见重写、去 AI 味润色、采纳草稿都会**覆盖** `第N章_*.md`，
+ * 一旦改差（尤其是自动修订把好稿改坏）就没有退路。这里在覆盖前把旧稿存到
+ * `<书目录>/snapshots/`，并维护一份 `snapshots/index.json` 索引。
+ *
+ * 纯 Node 文件操作，不依赖模型；路由层只做参数校验与响应。
+ */
+
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import type { ChapterPlan, ChapterSnapshot } from './protocol.ts'
+
+/** 快照目录名（书目录下）。 */
+export const SNAPSHOT_DIR = 'snapshots'
+
+/** 索引文件名。 */
+const INDEX_FILE = 'index.json'
+
+/** 每章默认保留的快照数（超出后按时间淘汰最旧的）。 */
+export const DEFAULT_SNAPSHOT_KEEP = 20
+
+/** 快照目录绝对路径。 */
+export function snapshotDir(outputDir: string): string {
+  return join(outputDir, SNAPSHOT_DIR)
+}
+
+/** 读取索引（缺失/损坏时返回空数组）。 */
+export function loadSnapshots(outputDir: string): ChapterSnapshot[] {
+  const file = join(snapshotDir(outputDir), INDEX_FILE)
+  if (!existsSync(file)) return []
+  try {
+    const parsed = JSON.parse(readFileSync(file, 'utf8')) as { snapshots?: ChapterSnapshot[] }
+    return Array.isArray(parsed.snapshots) ? parsed.snapshots : []
+  } catch {
+    return []
+  }
+}
+
+/** 写回索引。 */
+function saveSnapshots(outputDir: string, snapshots: ChapterSnapshot[]): void {
+  const dir = snapshotDir(outputDir)
+  mkdirSync(dir, { recursive: true })
+  writeFileSync(join(dir, INDEX_FILE), JSON.stringify({ snapshots }, null, 2), 'utf8')
+}
+
+/** 快照占用字节数（索引 + 正文）。 */
+export function snapshotsBytes(outputDir: string): number {
+  const dir = snapshotDir(outputDir)
+  if (!existsSync(dir)) return 0
+  let total = 0
+  try {
+    for (const name of readdirSync(dir)) {
+      try { total += statSync(join(dir, name)).size } catch { /* 跳过读不到的条目 */ }
+    }
+  } catch { /* 目录不可读时按 0 计 */ }
+  return total
+}
+
+/** 生成快照文件名（章节 + 时间戳 + 原因短标识）。 */
+function snapshotFileName(chapterNo: number, reason: string, at: string): string {
+  const stamp = at.replace(/[:.]/g, '-')
+  const tag = reason.replace(/[^\w\u4e00-\u9fa5-]+/g, '').slice(0, 12) || 'snap'
+  return `ch${String(chapterNo).padStart(4, '0')}_${stamp}_${tag}.md`
+}
+
+/**
+ * 为一个章节留存快照（覆盖写入前调用）。
+ *
+ * @param outputDir 书目录。
+ * @param chapter 章节（需要已存在正文文件）。
+ * @param reason 留存原因（生成覆盖 / 采纳草稿 / 修订 / 润色 / 手工）。
+ * @param keep 每章保留数量（超出淘汰最旧）。
+ * @returns 新建的快照；无正文文件时返回 undefined（不产生空快照）。
+ */
+export function createSnapshot(
+  outputDir: string,
+  chapter: ChapterPlan,
+  reason: string,
+  keep = DEFAULT_SNAPSHOT_KEEP,
+): ChapterSnapshot | undefined {
+  if (chapter.file === undefined || chapter.file === '') return undefined
+  const source = join(outputDir, chapter.file)
+  if (!existsSync(source)) return undefined
+  const at = new Date().toISOString()
+  const dir = snapshotDir(outputDir)
+  mkdirSync(dir, { recursive: true })
+  const name = snapshotFileName(chapter.no, reason, at)
+  const target = join(dir, name)
+  try {
+    copyFileSync(source, target)
+  } catch {
+    return undefined
+  }
+  const chars = chapter.chars ?? 0
+  const snapshot: ChapterSnapshot = {
+    id: name,
+    chapterNo: chapter.no,
+    file: `${SNAPSHOT_DIR}/${name}`,
+    reason,
+    chars,
+    at,
+  }
+  const snapshots = [...loadSnapshots(outputDir), snapshot]
+  saveSnapshots(outputDir, pruneList(snapshots, keep))
+  return snapshot
+}
+
+/** 按「每章保留最近 keep 个」裁剪列表，并删除被淘汰的文件。 */
+function pruneList(snapshots: ChapterSnapshot[], keep: number): ChapterSnapshot[] {
+  const byChapter = new Map<number, ChapterSnapshot[]>()
+  for (const s of snapshots) {
+    const list = byChapter.get(s.chapterNo) ?? []
+    list.push(s)
+    byChapter.set(s.chapterNo, list)
+  }
+  const kept: ChapterSnapshot[] = []
+  for (const list of byChapter.values()) {
+    list.sort((a, b) => b.at.localeCompare(a.at))
+    kept.push(...list.slice(0, Math.max(1, keep)))
+  }
+  return kept.sort((a, b) => a.at.localeCompare(b.at))
+}
+
+/**
+ * 回滚到某个快照：把快照内容写回章节正文文件。
+ *
+ * 回滚前会**先给当前正文留一份快照**（reason=回滚前自动留存），所以回滚本身也可撤销。
+ *
+ * @param outputDir 书目录。
+ * @param chapter 目标章节。
+ * @param snapshotId 快照 id。
+ * @returns 回滚后的字符数。
+ * @throws 快照不存在或章节无正文文件时抛错。
+ */
+export function restoreSnapshot(outputDir: string, chapter: ChapterPlan, snapshotId: string): number {
+  const snapshots = loadSnapshots(outputDir)
+  const snapshot = snapshots.find(s => s.id === snapshotId)
+  if (snapshot === undefined) throw new Error(`快照不存在：${snapshotId}`)
+  if (snapshot.chapterNo !== chapter.no) throw new Error(`快照属于第 ${snapshot.chapterNo} 章，与目标第 ${chapter.no} 章不符`)
+  const source = join(outputDir, snapshot.file)
+  if (!existsSync(source)) throw new Error(`快照文件已丢失：${snapshot.file}`)
+  if (chapter.file === undefined || chapter.file === '') throw new Error(`第 ${chapter.no} 章没有正文文件，无法回滚`)
+  createSnapshot(outputDir, chapter, '回滚前留存')
+  const body = readFileSync(source, 'utf8')
+  writeFileSync(join(outputDir, chapter.file), body, 'utf8')
+  return body.length
+}
+
+/** 删除一个快照（连同文件）。 */
+export function removeSnapshot(outputDir: string, snapshotId: string): boolean {
+  const snapshots = loadSnapshots(outputDir)
+  const snapshot = snapshots.find(s => s.id === snapshotId)
+  if (snapshot === undefined) return false
+  try { rmSync(join(outputDir, snapshot.file), { force: true }) } catch { /* 文件已不在 */ }
+  saveSnapshots(outputDir, snapshots.filter(s => s.id !== snapshotId))
+  return true
+}
+
+/** 按每章保留数量清理（连文件一起删）。 */
+export function pruneSnapshots(outputDir: string, keep = DEFAULT_SNAPSHOT_KEEP): number {
+  const snapshots = loadSnapshots(outputDir)
+  const kept = pruneList(snapshots, keep)
+  const keptIds = new Set(kept.map(s => s.id))
+  let removed = 0
+  for (const s of snapshots) {
+    if (keptIds.has(s.id)) continue
+    try { rmSync(join(outputDir, s.file), { force: true }) } catch { /* ignore */ }
+    removed++
+  }
+  saveSnapshots(outputDir, kept)
+  return removed
+}

package/src/stage-contract.ts

@@ -0,0 +1,189 @@
+/**
+ * 阶段契约（Stage Contract）——宿主计算的「当前阶段 → 本轮允许的动作」。
+ *
+ * 设计来源（「作者请求中的当前阶段决定唯一允许命令」这一约定）：
+ * 允许的动作必须由宿主根据真实项目状态算出，而不是指望模型记住或自律。
+ * 宿主计算结果同时用于三处：
+ *   1) 注入助手系统提示词：模型知道自己在哪一步、下一步该做什么；
+ *   2) 通用续写指令（「继续 / 下一步」）下的写操作白名单强约束（阶段即唯一命令）；
+ *   3) 拒绝写操作时给出可执行的、阶段相关的理由，而不是一句「不允许」。
+ *
+ * 注意：作者显式点名的写操作永远优先于阶段白名单（作者终审权）；
+ * 阶段强约束只在作者没有指定具体对象（通用续写）时生效。
+ */
+
+import type { ChapterPlan, ProjectState, StageInfo } from './protocol.ts'
+
+/** 创作阶段标识（线上形状见 protocol.ts 的 StageInfo）。 */
+export type BookStageId = StageInfo['id']
+
+/** 一个阶段契约。 */
+export type BookStage = StageInfo
+
+/** 大纲视为「已开书」的最短长度。 */
+const MIN_OUTLINE_CHARS = 50
+
+/** 通用续写指令（作者没有指定具体对象时，阶段白名单成为唯一命令）。 */
+const GENERIC_CONTINUE = /^(继续|下一步|接着来|接着写|往下|往下走|继续吧|go\s*on|continue|next)[。.!！?？\s]*$/i
+
+/**
+ * 作者这一轮是否只说了「继续/下一步」这类没有具体对象的指令。
+ *
+ * @param message 本轮用户消息。
+ * @returns 是通用续写指令时为 true。
+ */
+export function isGenericContinue(message: string): boolean {
+  return GENERIC_CONTINUE.test((message ?? '').trim())
+}
+
+/**
+ * 根据项目真实状态计算当前创作阶段。
+ *
+ * @param project 当前项目（未加载时为 undefined）。
+ * @returns 阶段契约（推荐动作 + 写操作白名单 + 判定理由）。
+ */
+export function computeBookStage(project: ProjectState | undefined): BookStage {
+  if (project === undefined || (project.outline ?? '').trim().length < MIN_OUTLINE_CHARS) {
+    return {
+      id: 'outline',
+      label: '开书',
+      recommend: ['outline_replace'],
+      allow: ['outline_replace'],
+      reason: project === undefined ? '尚无项目' : '大纲为空或过短',
+    }
+  }
+  if (project.bible === undefined) {
+    return {
+      id: 'bible',
+      label: '立设定',
+      recommend: ['bible_set_rule', 'bible_set_redline'],
+      allow: ['bible_set_rule', 'bible_set_redline'],
+      reason: '已有大纲，尚未提炼道藏',
+    }
+  }
+  const chapters = project.chapters ?? []
+  if (chapters.length === 0) {
+    return {
+      id: 'plan',
+      label: '排章节',
+      recommend: [],
+      // 章节规划不在助手的动作集里：通用「继续」不应被解释成改写总纲或设定。
+      allow: [],
+      reason: '有道藏但还没有章节计划（规划在「小说工坊」面板或生产单里执行）',
+    }
+  }
+  const generating = chapters.filter(c => c.status === 'generating')
+  if (generating.length > 0) {
+    return {
+      id: 'wait',
+      label: '等待中',
+      recommend: [],
+      allow: [],
+      reason: `第 ${generating.map(c => c.no).join('、')} 章正在生成，等它结束后再安排下一步`,
+    }
+  }
+  const errored = chapters.filter(c => c.status === 'error')
+  if (errored.length > 0) {
+    return {
+      id: 'write',
+      label: '逐章编译',
+      recommend: ['chapter_generate'],
+      allow: ['chapter_generate', 'chapter_rewrite', 'chapter_review'],
+      reason: `第 ${errored.map(c => c.no).join('、')} 章生成失败，需要重写`,
+    }
+  }
+  const rejected = chapters.filter(c => c.status === 'rejected')
+  if (rejected.length > 0) {
+    return {
+      id: 'revise',
+      label: '修订循环',
+      recommend: ['chapter_rewrite'],
+      allow: ['chapter_rewrite', 'chapter_review'],
+      reason: `第 ${rejected.map(c => c.no).join('、')} 章审稿未过，需要按意见修订`,
+    }
+  }
+  const awaitingReview = chapters.filter(c => c.status === 'written' || c.status === 'reviewing')
+  if (awaitingReview.length > 0) {
+    return {
+      id: 'review',
+      label: '审稿',
+      recommend: ['chapter_review'],
+      allow: ['chapter_review', 'chapter_rewrite'],
+      reason: `第 ${awaitingReview.map(c => c.no).join('、')} 章已写出但尚未审稿`,
+    }
+  }
+  const pending = chapters.filter(c => c.status === 'pending')
+  if (pending.length > 0) {
+    return {
+      id: 'write',
+      label: '逐章编译',
+      recommend: ['chapter_generate'],
+      allow: ['chapter_generate', 'chapter_rewrite', 'chapter_review'],
+      reason: `还有 ${pending.length} 章待写（下一章：第 ${pending[0]!.no} 章）`,
+    }
+  }
+  return {
+    id: 'export',
+    label: '定稿导出',
+    recommend: ['export_txt', 'blurb'],
+    // 全部通过后不再允许在「继续」下改写正文：要改必须由作者点名章节。
+    allow: ['export_txt', 'blurb'],
+    reason: `全书 ${chapters.length} 章均已通过审稿`,
+  }
+}
+
+/**
+ * 判断某写操作是否在当前阶段的允许白名单内。
+ *
+ * @param stage 阶段契约。
+ * @param tool 助手工具名。
+ * @returns 允许时为 true。
+ */
+export function stageAllows(stage: BookStage, tool: string): boolean {
+  return stage.allow.includes(tool)
+}
+
+/**
+ * 按阶段把一组动作分成「本阶段可用」与「阶段外」。
+ *
+ * @param stage 阶段契约。
+ * @param tools 动作名列表（通常是写操作登记表）。
+ * @returns 两个保持输入顺序的子集。
+ */
+export function splitByStage(stage: BookStage, tools: readonly string[]): { available: string[]; outside: string[] } {
+  const available: string[] = []
+  const outside: string[] = []
+  for (const tool of tools) {
+    if (stageAllows(stage, tool)) available.push(tool)
+    else outside.push(tool)
+  }
+  return { available, outside }
+}
+
+/**
+ * 渲染阶段契约为可注入提示词的一段文字。
+ *
+ * @param stage 阶段契约。
+ * @returns 多行文本。
+ */
+export function renderStageContract(stage: BookStage): string {
+  const recommend = stage.recommend.length > 0 ? stage.recommend.join('、') : '无（等待或由作者指定）'
+  const allow = stage.allow.length > 0 ? stage.allow.join('、') : '无'
+  return [
+    '==================== 当前创作阶段（宿主根据项目真实状态计算） ====================',
+    `阶段：${stage.label}（${stage.id}）`,
+    `判定依据：${stage.reason}`,
+    `建议下一步：${recommend}`,
+    `本阶段允许的写操作：${allow}`,
+    '阶段纪律：作者只说了「继续/下一步」而没指定具体对象时，只有上面的写操作会被执行，其余写操作一律拒绝；作者显式点名某个操作时以作者指令为准。',
+  ].join('\n')
+}
+
+/** 汇总章节状态计数（供面板/提示词展示，避免各处重复统计）。 */
+export function summarizeChapters(chapters: ChapterPlan[]): Record<string, number> {
+  const summary: Record<string, number> = {}
+  for (const chapter of chapters) {
+    summary[chapter.status] = (summary[chapter.status] ?? 0) + 1
+  }
+  return summary
+}