@waterwx/dsh-novel-forge 2.1.5 → 2.3.0

package/lib/types/prompts/facts.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 章节记忆域：摘要 + 事实 + 时间线的抽取提示词。
+ *
+ * 三者的输入是同一份章节正文（合并调用的理由见 engine 侧注释）；
+ * 提示词同域放一处，改口径时五份一起看，避免「摘要说 3-6 条、事实说 3-8 条」漂移。
+ *
+ * 本文件同时是提示词注册表的域模块之一（见 catalog.ts）。
+ */
+import type { PromptEntry } from './catalog.ts';
+/** 摘要 + 事实（两件事一次出）。 */
+export declare function summaryFactsSystemPrompt(): string;
+/**
+ * 摘要 + 事实 + 时间线（三件事一次出）。
+ *
+ * @param wantTimeline - 关闭时间线时连 timeline 字段都不问，省掉输出 token
+ *   与模型的无用工作量。
+ */
+export declare function summaryFactsTimelineSystemPrompt(wantTimeline: boolean): string;
+/** 事实抽取：本章正文 → 已确立事实（每行一条，3-6 条）。 */
+export declare function extractFactsSystemPrompt(): string;
+/** 时间线抽取：一章正文 → 故事时间线事件（时间/地点/在场角色/事件）。 */
+export declare function timelineExtractSystemPrompt(): string;
+/** 时间线复核：规则初筛之外，让模型找时序矛盾（时间倒流/瞬移/跨度不合理/季节错位）。 */
+export declare function timelineReviewSystemPrompt(): string;
+/** 本域提示词登记（注册表消费）。 */
+export declare const entries: PromptEntry[];

package/lib/types/prompts/foreshadow.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 伏笔（暗线）域：从大纲与已写信息建议值得埋设的伏笔。
+ *
+ * 本文件同时是提示词注册表的域模块之一（见 catalog.ts）。
+ */
+import type { PromptEntry } from './catalog.ts';
+/** System prompt for foreshadow suggestions. */
+export declare function foreshadowSystemPrompt(): string;
+/** 本域提示词登记（注册表消费）。 */
+export declare const entries: PromptEntry[];

package/lib/types/prompts/market.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 市场域：题材雷达（榜单信号 → 生产底座）、雷达灵感、作品简介。
+ *
+ * 三份提示词共享同一条纪律：**严禁复用榜单作品的人名/专有设定/简介句子/
+ * 完整书名**，只能提炼读者需求、爽点机制与结构机会——市场雷达是拿来
+ * 找方向的，不是拿来抄的。
+ *
+ * 本文件同时是提示词注册表的域模块之一（见 catalog.ts）。
+ */
+import type { PromptEntry } from './catalog.ts';
+/** 市场雷达系统提示（分析师角色与输出纪律）。 */
+export declare function marketRadarSystemPrompt(): string;
+/** 雷达→灵感：基于市场信号/生产底座/创意简报，生成贴合市场的开书灵感。 */
+export declare function marketIdeaInspirationSystemPrompt(): string;
+/** 作品简介：面向读者的门面（卖点 + 开局钩子，不剧透）。 */
+export declare function blurbSystemPrompt(): string;
+/** 本域提示词登记（注册表消费）。 */
+export declare const entries: PromptEntry[];

package/lib/types/prompts/outline.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 开书与大纲域：创意灵感、大纲方案生成、反推总纲（两个来源）。
+ *
+ * 「反推大纲」与「大纲方案」方向相反（已写→总纲 vs 想法→方案），但同属
+ * 大纲资产的生产与再生产，放同一域。
+ *
+ * 本文件同时是提示词注册表的域模块之一（见 catalog.ts）。
+ */
+import type { PromptEntry } from './catalog.ts';
+/** 创意灵感：一句话/题材 → 多方向开书灵感。 */
+export declare function ideaInspirationSystemPrompt(): string;
+/**
+ * 大纲方案：作者的一句「想法」→ 2-3 个方向差异明显的完整大纲。
+ *
+ * @param n - 本次要输出的方案数（1-3）。
+ */
+export declare function outlineCandidatesSystemPrompt(n: number): string;
+/** 反推大纲 · 阶段一：分批为每章输出一行「事件摘要」。 */
+export declare function reverseOutlineBatchSystemPrompt(): string;
+/** 反推大纲 · 阶段二：各章事件摘要 → 全书总纲（Markdown）。 */
+export declare function reverseOutlineSystemPrompt(): string;
+/** 反推大纲 · 改编线：从拆章节选反推总纲，作为改编与续写的骨架。 */
+export declare function reverseOutlineFromAdaptationSystemPrompt(): string;
+/** 本域提示词登记（注册表消费）。 */
+export declare const entries: PromptEntry[];

package/lib/types/prompts/plan.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 规划域：分卷规划、章节规划（含续写后缀）、自动导演编排。
+ *
+ * 本文件同时是提示词注册表的域模块之一（见 catalog.ts）。
+ */
+import type { Volume } from '../protocol.ts';
+import type { PromptEntry } from './catalog.ts';
+/** System prompt for volume planning. */
+export declare function volumeSystemPrompt(): string;
+/** The chapter-planning prompt template. */
+export declare function planSystemPrompt(volumes: Volume[] | undefined): string;
+/**
+ * 续写规划的附加要求（拼在 planSystemPrompt 之后）。
+ *
+ * 与 user 侧的「续写硬性要求」分工：这里管**标题与接续的唯一性**，
+ * user 侧管「已发生事件不得重写」与全书进度感知。
+ */
+export declare function planContinuationSuffix(): string;
+/** 自动导演：整本编排/节奏/风险/再平衡建议（不输出正文）。 */
+export declare function directorSystemPrompt(): string;
+/** 本域提示词登记（注册表消费）。 */
+export declare const entries: PromptEntry[];

package/lib/types/prompts/plotlines.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 剧情线域：建议提炼、进度刷新（批量）、健康检查、下一阶段方案。
+ *
+ * 本文件同时是提示词注册表的域模块之一（见 catalog.ts）。
+ */
+import type { PromptEntry } from './catalog.ts';
+/** 建议剧情线：基于大纲/卷计划/已写章节/编年录，提炼候选线。 */
+export declare function suggestPlotlinesSystemPrompt(): string;
+/**
+ * 剧情线进度刷新（批量）。
+ *
+ * @param count - 本次要判断的线数。单条时问单线进度，多条时要求逐条判断、
+ *   name 与输入逐字相同（用于对齐回写，见 plotline-align.ts）。
+ */
+export declare function refreshPlotlinesSystemPrompt(count: number): string;
+/** 剧情健康检查：基于已写章节数/各线状态/编年录，判断是否需要新线及添加时机。 */
+export declare function plotlineHealthSystemPrompt(): string;
+/** 剧情方案：基于健康检查结果设计下一阶段方向与建议新线。 */
+export declare function plotlinePlanSystemPrompt(): string;
+/** 本域提示词登记（注册表消费）。 */
+export declare const entries: PromptEntry[];

package/lib/types/prompts/polish.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 润色域：整章去 AI 味润色、局部段落修订。
+ *
+ * 两者都按分层组装：润色口径与合规红线排最前（永不变），本书红线与写法
+ * 资产排后面（只随作者编辑变）——见 prompt-cache.ts。
+ *
+ * 本文件同时是提示词注册表的域模块之一（见 catalog.ts）。
+ */
+import type { ProjectState } from '../protocol.ts';
+import type { PromptEntry } from './catalog.ts';
+/** The de-AI-ify polish system prompt (with project writing assets injected). */
+export declare function polishSystemPrompt(project: ProjectState): string;
+/**
+ * 局部修订（只改一个自然段）的系统提示。
+ *
+ * 与整章修订的区别：不套用字数区间、不注入全书资料（大纲/资产/时间线），
+ * 只带合规红线、本书红线、反 AI 套话口径与角色卡——局部改写要的是「表达
+ * 卫生」，不是重新生成。同样按分层组装（约束口径排最前）。
+ */
+export declare function localRevisionSystemPrompt(project: ProjectState): string;
+/** 本域提示词登记（注册表消费）。 */
+export declare const entries: PromptEntry[];

package/lib/types/prompts/review.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 审稿域：章节审稿（九维）、修订验证、作者复盘、验证模式道藏注入。
+ *
+ * 审稿是逐章连打的动作，固定层（审稿口径 + 合规红线）排最前、本书层
+ * （道藏/资产）排后面——前缀稳定才有机会命中厂商输入缓存（见 prompt-cache.ts）。
+ *
+ * 本文件同时是提示词注册表的域模块之一（见 catalog.ts）。
+ */
+import type { ProjectState } from '../protocol.ts';
+import type { PromptEntry } from './catalog.ts';
+/** The review system prompt. */
+export declare function reviewSystemPrompt(project: ProjectState): string;
+/** 验证模式系统提示：修订后逐条核对原意见是否解决，只挑新增 high，不重复挑剔主观项。 */
+export declare function verifySystemPrompt(project: ProjectState): string;
+/**
+ * 验证模式下注入道藏。
+ *
+ * 原实现是 `JSON.stringify(project.bible).slice(0, 3000)`——有两个问题：
+ * 1. **腰斩的 JSON 不是 JSON**：`slice` 从中间切断，审稿员会看到语法残缺的
+ *    对象（字符串没闭合、数组没结尾），既浪费 token 又可能误读设定。
+ * 2. **静默截断设定**：世界规则/角色卡排在后面的字段最先被切掉，而那恰恰是
+ *    核对设定冲突最需要的部分。
+ *
+ * 改为结构化渲染 + 按「世界规则/角色/红线」分配独立预算。
+ */
+export declare function renderBibleForVerify(project: ProjectState): string;
+/** Build the author-review system prompt (narrative structure, not prose). */
+export declare function authorReviewSystemPrompt(): string;
+/** 本域提示词登记（注册表消费）。 */
+export declare const entries: PromptEntry[];

package/lib/types/prompts/world.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 大世界域：结构化设定（境界体系/地理区域/势力分布）的渲染与提炼。
+ *
+ * 本文件同时是提示词注册表的域模块之一（见 catalog.ts）。
+ */
+import type { WorldState } from '../protocol.ts';
+import type { PromptEntry } from './catalog.ts';
+/** 把大世界结构化数据渲染成提示词块（境界体系按顺序强约束）。 */
+export declare function renderWorld(world: WorldState | undefined): string;
+/** 大世界提炼：从大纲 + 道藏生成结构化境界体系/区域/势力。 */
+export declare function extractWorldSystemPrompt(): string;
+/** 本域提示词登记（注册表消费）。 */
+export declare const entries: PromptEntry[];

package/lib/types/prompts/writing.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 写作域：正文生成、整章修订、续写补齐的系统提示。
+ *
+ * ## 分层组装（缓存命中的纪律）
+ *
+ * 同一本书的连续多次调用里，输入的大部分是重复的，但各块的变化频率差着量级：
+ * 固定层（写作硬性要求 + 合规红线）永不变；本书层（道藏/世界/大纲/资产/槽位）
+ * 只随作者编辑变；本章层（伏笔/剧情线/骨架/时间线/张力）随创作进度逐章变。
+ * 厂商的输入缓存按**前缀**命中——顺序写死在 prompt-cache.ts，调用方只标层。
+ *
+ * 本文件同时是提示词注册表的域模块之一（见 catalog.ts）。
+ */
+import type { ProjectState } from '../protocol.ts';
+import type { PromptEntry } from './catalog.ts';
+/** Build the writing system prompt (bible + outline + active foreshadows).
+ *  `targetChars` 来自每章计划（规划时快照，= 设置的每章目标字数）；无则退回默认 3500。
+ *  字数区间按目标动态生成（±15%，取整到百位），避免系统提示词与设置互相冲突。
+ *  `lengthRule` 可覆盖第 1 条字数要求（整章修订/改编时按原文长度为准）。 */
+export declare function writeSystemPrompt(project: ProjectState, targetChars?: number, lengthRule?: string, beforeChapter?: number): string;
+/** Build the rewrite system prompt (fix review issues / instructions). */
+export declare function rewriteSystemPrompt(project: ProjectState, targetChars?: number, beforeChapter?: number): string;
+/**
+ * 正文续写补齐的附加要求（拼在 writeSystemPrompt 之后）。
+ *
+ * 触发场景：生成的正文不足目标字数 90% 时，最多补两轮。
+ */
+export declare function bodyContinuationSuffix(): string;
+/** 本域提示词登记（注册表消费）。 */
+export declare const entries: PromptEntry[];

package/lib/types/protocol.d.ts

@@ -59,6 +59,8 @@ export declare const NOVEL_API: {
     readonly chapterCheck: "/api/dsh-novel-forge/chapter/check";
     /** 保存手动编辑的正文（自动备份 .bak）。 */
     readonly chapterSave: "/api/dsh-novel-forge/chapter/save";
+    /** 补写本章计划的固定六项（目标 / 必达 / 保持 / 硬事实 / 结尾钩子 / 剧情要点）。 */
+    readonly chapterPlan: "/api/dsh-novel-forge/chapter/plan";
     readonly assistant: "/api/dsh-novel-forge/assistant";
     readonly assistantHistory: "/api/dsh-novel-forge/assistant-history";
     /** 清空助手对话记录。 */
@@ -298,6 +300,8 @@ export interface ChapterPlan {
     error?: string;
     /** Output file name once generated (relative to the output dir). */
     file?: string;
+    /** 正文写盘时间（文件 mtime，ISO）。**派生字段**：只在 /status 响应里出现，不落 novel-project.json。 */
+    writtenAt?: string;
     /** LLM summary of the chapter (narrative memory for later chapters). */
     summary?: string;
     /** Latest review report (present once reviewed). */
@@ -814,6 +818,8 @@ export interface Plotline {
     goal: string;
     /** 当前进度说明（最近推进到哪）。 */
     progress: string;
+    /** 下一目标（这条线接下来要推进到哪；作者填写，缺省表示未设定）。 */
+    nextGoal?: string;
     /** 生命周期状态。 */
     status: 'active' | 'paused' | 'resolved' | 'abandoned';
     /** 关联章节号（推进/落地的章节）。 */
@@ -1057,6 +1063,40 @@ export interface ChapterSaveResponse {
     /** 落盘的审稿报告（沿用工作区报告或保存后自动审稿）。 */
     report?: ReviewReport;
 }
+/**
+ * POST /chapter/plan 请求：作者补写本章计划的固定六项。
+ *
+ * 只覆盖**传入**的字段（缺省 = 保持原值），传空串 / 空数组表示清空该项。
+ * 这些字段原本只由规划步骤产出，作者没有入口修——但它们是生成与审稿的锚点，
+ * AI 排偏了就必须能人工纠正，所以开放这一条最小写入路径。
+ */
+export interface ChapterPlanPatchRequest {
+    chapterNo: number;
+    patch: {
+        /** 本章目标 / 义务合约（≤200 字）。 */
+        obligation?: string;
+        /** 本章必达项（≤4 条）。 */
+        mustAdvance?: string[];
+        /** 本章必须保持、不得破坏的项（≤4 条）。 */
+        mustPreserve?: string[];
+        /** 人物硬事实（≤6 条）。 */
+        characterHardFacts?: string[];
+        /** 结尾钩子要求（≤120 字）。 */
+        endingHook?: string;
+        /** 剧情要点（≤2000 字）。 */
+        beats?: string;
+    };
+}
+/** POST /chapter/plan 响应：回传合并后的章节计划，面板不必再拉一次全量 status。 */
+export interface ChapterPlanPatchResponse {
+    ok: true;
+    chapter: ChapterPlan;
+    /**
+     * 宿主按上限裁掉了什么（字数 / 条数超限）。本项目的不变量是**截断必须显式**：
+     * 作者写了 6 条必达项只留下 4 条时，不能让他以为 6 条都生效了。
+     */
+    notices?: string[];
+}
 /** POST /cover 请求：上传或移除封面。 */
 export interface CoverRequest {
     action: 'upload' | 'remove';
@@ -1398,6 +1438,13 @@ export interface LlmTokenUsage {
     /** 命中缓存的输入用量。 */
     cacheReadTokens?: number;
 }
+/**
+ * LLM 实况阶段。`cancelled` = 作者关页面 / 主动中断，**不是模型失败**：
+ * 既不计入用量账本的「失败」，也不触发备用模型（口径见 llm-retry.ts）。
+ */
+export type LlmLivePhase = 'requesting' | 'streaming' | 'completed' | 'failed' | 'cancelled';
+/** 一次调用结束时的阶段（进行中的两个阶段不会出现在这里）。 */
+export type LlmLiveFinalPhase = Extract<LlmLivePhase, 'completed' | 'failed' | 'cancelled'>;
 /** LLM 实况帧：宿主 → 浏览器的 SSE 事件（每次调用一组 session_* 事件）。 */
 export interface LlmLiveFrame {
     type: 'session_started' | 'output_delta' | 'reasoning_delta' | 'phase_changed' | 'session_completed';
@@ -1420,8 +1467,8 @@ export interface LlmLiveFrame {
     totalChars?: number;
     /** reasoning 累计字符数。 */
     totalReasoningChars?: number;
-    /** phase_changed：新阶段。 */
-    phase?: 'requesting' | 'streaming' | 'completed' | 'failed';
+    /** phase_changed / session_completed：阶段。 */
+    phase?: LlmLivePhase;
     /** phase_changed：阶段描述。 */
     phaseMessage?: string;
     /** session_completed：最终预览（截断）。 */
@@ -1447,6 +1494,8 @@ export interface LlmUsageBucket {
     inputTokens: number;
     outputTokens: number;
     reasoningTokens: number;
+    /** 命中缓存的输入用量（属于 inputTokens 的一部分，不额外相加）。 */
+    cacheReadTokens?: number;
     elapsedMs: number;
 }
 /** 本次运行（进程内，重启归零）的 LLM 用量汇总。 */
@@ -1457,6 +1506,8 @@ export interface LlmUsageSummary {
     outputTokens: number;
     reasoningTokens: number;
     totalTokens: number;
+    /** 命中缓存的输入用量（属于 inputTokens 的一部分，不额外相加）。 */
+    cacheReadTokens?: number;
     elapsedMs: number;
     /** 供应商未上报 usage 的调用次数（用于说明数据为何不完整）。 */
     callsWithoutUsage: number;

package/lib/types/routes.d.ts

@@ -9,6 +9,7 @@
  */
 import type { WebRoute } from '@deepseek-ai/dsh-host-webserver';
 import type { Context } from '@deepseek-ai/cordis';
+import { ProductionRunner } from './run.ts';
 import { type BibleResponse, type ConfigPatch, type ConfigResponse, type ExportResponse, type LoadOutlineResponse, type NovelConfig, type PlanResponse, type StatusResponse, type VolumesResponse } from './protocol.ts';
 import { chapterFileName } from './engine.ts';
 /** Route deps. */
@@ -24,6 +25,11 @@ export interface NovelRoutesDeps {
     };
     /** Loader entry id the settings section is addressed by (undefined when unknown). */
     settingsNs?: string;
+    /**
+     * 生产单执行器单例。由宿主持有并跨 `makeRoutes` 重用 —— 见该字段在工厂内的说明。
+     * 测试可省略（内部自建一次性实例）。
+     */
+    runner?: ProductionRunner;
 }
 /**
  * Build every /api/dsh-novel-forge route.

package/lib/types/run-selection.d.ts

@@ -41,11 +41,14 @@ export interface PickNextResult {
 /**
  * 选出生产单下一章要处理的章。
  *
- * 三种章：已 `approved` 快进；连败达上限的熔断跳过；其余为下一章。
+ * 四种章：已 `approved` 快进；已列入 `pendingManual` 的快进（人工已接管）；
+ * 连败达上限的熔断跳过；其余为下一章。
  *
  * @param chapters - 全书章节计划。
  * @param currentNo - 当前章号（含）。
  * @param endNo - 区间终点（含）。
  * @param failedAttempts - 章号 → 已失败次数（来自 `RunState.failedAttempts`）。
+ * @param pendingManual - 已列入待人工的章号（来自 `RunState.pendingManual`）。
+ *   必须传入，否则重写 N 轮仍不过的章会被反复选中，每轮烧两次 rewrite + 两次 verify。
  */
-export declare function pickNextChapter(chapters: ChapterPlan[], currentNo: number, endNo: number, failedAttempts: Record<string, number>): PickNextResult;
+export declare function pickNextChapter(chapters: ChapterPlan[], currentNo: number, endNo: number, failedAttempts: Record<string, number>, pendingManual?: readonly number[]): PickNextResult;

package/lib/types/stream-fallback.d.ts

@@ -46,6 +46,14 @@ export interface StreamWithFallbackOptions {
     maxTokensError: string;
     /** 产出文本的最小长度；不足则视为失败。 */
     minChars: number;
+    /**
+     * 取消信号。客户端断开时应abort —— 宿主 SDK 约定「implementations must honor
+     * `options.signal`」，不发信号等于让 LLM 调用在后台跑完整章（maxTokens 常20000），
+     * 用户关掉页面也停不下来。
+     *
+     * 中止时本函数抛出 `AbortError`，由调用方决定是静默收尾还是回错误帧。
+     */
+    signal?: AbortSignal;
 }
 /**
  * 执行流式生成，主模型失败且「一个字都没产出」时换备用模型重试一次。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@waterwx/dsh-novel-forge",
   "description": "AI 编译纯文本小说工作台 for the dsh web GUI: import a novel outline (docx/text), plan volumes & chapters with LLM, generate chapter by chapter (3000-4000 chars each), auto AI review & book audit, and export the full book as Markdown/TXT into your chosen output folder.",
-  "version": "2.1.5",
+  "version": "2.3.0",
   "type": "module",
   "author": "waterwx",
   "repository": {
@@ -116,6 +116,7 @@
     "check:fallback": "node scripts/check-fallback-tiers.mjs",
     "check:third-party": "node scripts/check-third-party.mjs",
     "check:contrast": "node scripts/audit-contrast.mjs",
+    "check:classes": "node scripts/check-css-classes.mjs",
     "check:third-party:list": "node scripts/check-third-party.mjs --list",
     "release": "node scripts/release.mjs",
     "release:dry": "node scripts/release.mjs --dry-run",