@waterwx/dsh-novel-forge 2.1.5 → 2.2.0

package/lib/types/assistant.d.ts

@@ -54,7 +54,7 @@ export declare function clearAssistantHistory(outputDir: string): void;
  */
 export declare function executeAction(ctx: Context, config: NovelConfig, project: ProjectState, outputDir: string, name: string, args: Record<string, unknown>): AsyncGenerator<string, string, unknown>;
 /** Run one user turn. Yields stream frames; persists history. */
-export declare function runAssistantTurn(ctx: Context, config: NovelConfig, project: ProjectState, outputDir: string, userMessage: string): AsyncGenerator<{
+export declare function runAssistantTurn(ctx: Context, config: NovelConfig, project: ProjectState, outputDir: string, userMessage: string, signal?: AbortSignal): AsyncGenerator<{
     frame: 'delta';
     text: string;
 } | {

package/lib/types/client/api.d.ts

@@ -3,7 +3,7 @@
  * fetch, same origin; generation/rewrite/polish ride NDJSON streams read
  * incrementally.
  */
-import { type AssetsPatch, type AssetsResponse, type AddModelRequest, type AddModelResponse, type LlmModelsResponse, type LlmProvidersResponse, type LlmVendorsResponse, type RemoveProviderRequest, type RemoveProviderResponse, type BibleResponse, type ChapterResponse, type ConfigPatch, type ExportResponse, type ForeshadowRequest, type ForeshadowResponse, type JobFrame, type LoadOutlineResponse, type AdaptExecuteRequest, type AdaptRewriteFrame, type AdaptMaterializeSaveRequest, type AdaptMaterializeSaveResponse, type PluginUpdateResponse, type LlmTestResponse, type NovelConfig, type PlanResponse, type ReviewReport, type RevisionPlanResponse, type StatusResponse, type StyleEngineRequest, type StyleAsset, type VolumesResponse } from '../protocol.ts';
+import { type AssetsPatch, type AssetsResponse, type AddModelRequest, type AddModelResponse, type LlmModelsResponse, type LlmProvidersResponse, type LlmVendorsResponse, type RemoveProviderRequest, type RemoveProviderResponse, type BibleResponse, type ChapterResponse, type ChapterPlanPatchResponse, type ConfigPatch, type ExportResponse, type ForeshadowRequest, type ForeshadowResponse, type JobFrame, type LoadOutlineResponse, type AdaptExecuteRequest, type AdaptRewriteFrame, type AdaptMaterializeSaveRequest, type AdaptMaterializeSaveResponse, type PluginUpdateResponse, type LlmTestResponse, type NovelConfig, type PlanResponse, type ReviewReport, type RevisionPlanResponse, type StatusResponse, type StyleEngineRequest, type StyleAsset, type VolumesResponse } from '../protocol.ts';
 /** Error carrying the route's JSON error message. */
 export declare class NovelApiError extends Error {
     constructor(message: string);
@@ -49,6 +49,8 @@ export declare class NovelApi {
     }): Promise<RevisionPlanResponse>;
     /** 保存手动编辑的正文（自动备份 .bak；带报告则沿用落盘，否则保存后自动审稿）。 */
     chapterSave(no: number, text: string, report?: ReviewReport): Promise<import('../protocol.ts').ChapterSaveResponse>;
+    /** 补写本章计划（目标 / 必达 / 保持 / 硬事实 / 结尾钩子 / 剧情推进）：只覆盖传入字段。 */
+    chapterPlan(no: number, patch: import('../protocol.ts').ChapterPlanPatchRequest['patch']): Promise<ChapterPlanPatchResponse>;
     patchConfig(patch: ConfigPatch): Promise<{
         config: NovelConfig;
         settingsWarning?: string;

package/lib/types/client/llmLive.d.ts

@@ -2,13 +2,14 @@
  * 浏览器端「AI 创作实况」钩子：连接 /llm-live/stream (SSE)，按 LLM 调用分组会话。
  * 轻量实现，不持久化缓存（对齐上游 useLlmLiveFeed 的核心行为）。
  */
-import { type LlmLiveFrame, type LlmTokenUsage } from '../protocol.ts';
+import { type LlmLiveFrame, type LlmLivePhase, type LlmTokenUsage } from '../protocol.ts';
 export type { LlmLiveFrame };
 export interface LlmLiveSession {
     sessionId: string;
     label: string;
     model?: string;
-    phase: 'requesting' | 'streaming' | 'completed' | 'failed';
+    /** 阶段契约只有一份定义（protocol.ts），面板不再自行枚举。 */
+    phase: LlmLivePhase;
     phaseMessage: string;
     preview: string;
     totalChars: number;
@@ -25,6 +26,10 @@ export interface LlmLiveSession {
     /** Prompt 字符数（system + user）。 */
     promptChars?: number;
 }
+/** 是否仍在进行中：cancelled 属于已结束，不能显示为「生成中」。 */
+export declare function isActivePhase(phase: LlmLivePhase): boolean;
+/** SSE 帧 → 会话表（纯函数，导出供单测覆盖 cancelled 结案）。 */
+export declare function applyFrame(current: Record<string, LlmLiveSession>, frame: LlmLiveFrame): Record<string, LlmLiveSession>;
 export declare function useLlmLiveFeed(enabled?: boolean): {
     connected: boolean;
     sessions: LlmLiveSession[];

package/lib/types/client/locales.d.ts

@@ -83,6 +83,7 @@ export declare const zh: {
     readonly 'plotlines.kindMystery': "悬念线";
     readonly 'plotlines.goal': "目标/终点";
     readonly 'plotlines.progress': "当前进度";
+    readonly 'plotlines.nextGoal': "下一目标";
     readonly 'plotlines.status': "状态";
     readonly 'plotlines.statusActive': "推进中";
     readonly 'plotlines.statusPaused': "暂停";

package/lib/types/client/panel/AuthorInbox.d.ts

@@ -0,0 +1,23 @@
+export type InboxTone = 'high' | 'warn' | 'info';
+export interface InboxItem {
+    id: string;
+    /** 要做什么（动词开头的一句话）。 */
+    title: string;
+    /** 来源：AI 审稿 · 高优 / 时间线 / 张力 / 待审 … */
+    source: string;
+    /** 补充说明（原因、影响、原文摘录）。 */
+    detail?: string;
+    tone: InboxTone;
+    actionLabel: string;
+    onAction: () => void;
+}
+export declare function AuthorInbox({ items, total, shown, onOpenAll, empty }: {
+    items: InboxItem[];
+    /** 未截断的总条数（> items.length 时提示还有多少）。 */
+    total: number;
+    /** 列表区最大高度由外层控制时用的展示条数说明。 */
+    shown?: number;
+    onOpenAll?: () => void;
+    /** 空态文案。 */
+    empty: string;
+}): JSX.Element;

package/lib/types/client/panel/CabinetSnapshot.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 资料侧柜内容（2.1.7）：本书此刻的生成上下文。
+ *
+ * 从 demo 的资料侧柜取**内容组织**：四张「此刻事实 + 新鲜度」卡 ——
+ *   编年录最近锚点 / 人物志当前状态 / 剧情线最近推进 / 写作资产当前绑定。
+ * 与 demo 的差别：数据全部取自真实存档（timeline / roleStatus / plotlines /
+ * assets.styleAssets），缺数据时给**可执行的空态**而不是留空；
+ * 「剧情线进度 42%」这类没有数据源的百分比不编（改用「推进章节 · 第 N 章」）。
+ *
+ * 形态由调用方决定：宿主里是**面板内的右滑抽屉**（demo 的 fixed 全屏遮罩层
+ * 放进宿主会话列会盖住整个窗口）。
+ */
+import type { ProjectState } from '../../protocol.ts';
+export declare function CabinetSnapshot({ project }: {
+    project: ProjectState | null;
+}): JSX.Element;

package/lib/types/client/panel/ChapterPlanPanel.d.ts

@@ -0,0 +1,24 @@
+import type { NovelApi } from '../api.ts';
+import type { ChapterPlan, Plotline } from '../../protocol.ts';
+/** 把章节 beats 按结构标签渲染（本章目标 / 剧情要点 / 爽点 / 结尾钩子 等前缀加粗）。 */
+export declare function renderBeats(beats: string): JSX.Element;
+export interface ChapterPlanPanelProps {
+    chapter: ChapterPlan;
+    /** 全部剧情线：内部按 `chapters` 是否含本章来筛关联项。 */
+    plotlines: Plotline[];
+    api: NovelApi;
+    busy: boolean;
+    /** 保存成功后回传合并结果，由外层并入 project.chapters（工作台的唯一数据源）。 */
+    onSaved: (chapter: ChapterPlan) => void;
+    /** 截断声明汇入外层（不静默吞掉：作者写了 6 条只留 4 条时必须看见）。 */
+    onNotice: (message: string) => void;
+    /** 关联剧情线的动作入口：打开「长线管理」抽屉。 */
+    onLinkLines: () => void;
+}
+/**
+ * 左栏计划面板：六项固定分组 + 就地补写。
+ *
+ * 编辑态一次只开一个分组：`patch` 只覆盖传入字段，同时开两处会让两个
+ * 草稿互相看不见，保存时机也变得含混。
+ */
+export declare function ChapterPlanPanel({ chapter, plotlines, api, busy, onSaved, onNotice, onLinkLines }: ChapterPlanPanelProps): JSX.Element;

package/lib/types/client/panel/ConfirmDialog.d.ts

@@ -1,4 +1,6 @@
 export type ConfirmTone = 'danger' | 'warn' | 'info';
+/** 弹层共用键盘边界与焦点回归；只有最上层弹窗响应按键。 */
+export declare function useDialogFocus(open: boolean, onClose: () => void, canClose?: boolean): import("react").MutableRefObject<HTMLElement | null>;
 export interface ConfirmSpec {
     /** 弹窗标题：一句话说清要做什么。 */
     title: string;

package/lib/types/client/panel/HomeHero.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 总编台 hero（2.1.7 / 取自 prototype/NovelForge_总编台_Demo.html 的信息结构）。
+ *
+ * 为什么要有它：此前的首屏是「4 张指标卡 + 工序轨道」，作者看到的是**仪表盘**，
+ * 得自己拼出"现在最该干什么"。hero 把这件事收敛成一条视线：
+ *   在哪一章 → 该做什么 → 为什么现在做 → 做它的代价 → 边界（不会自动改写正文）。
+ *
+ * 与 demo 的差别（刻意保留）：demo 的大标题是一句文学化钩子（"旧钥已经发热…"），
+ * 那需要"生成一句钩子"的数据源；这里用宿主**真实**的推荐动作标题，永远为真。
+ * 虚线右侧的进度/节点也全部来自真实状态，不编造百分比。
+ */
+import type { ReactNode } from 'react';
+export interface HomeHeroAction {
+    /** 眉标：推荐下一步 / 需要你确认 / 阶段：等待中 … */
+    eyebrow: string;
+    /** 主标题（一件具体的事）。 */
+    title: string;
+    /** 为什么现在做。 */
+    reason: string;
+    /** 主 CTA 文案（动词开头）。 */
+    actionLabel: string;
+    onClick: () => void;
+}
+export interface HomeHeroProps {
+    /** 当前对象（如「第 8 章 · 雨夜之后」）。 */
+    kicker: string;
+    /** 印章里的短标记（章号 / 阶段序号）。 */
+    seal: string;
+    /** 印章下方说明。 */
+    sealNote: string;
+    stageLabel?: string;
+    action: HomeHeroAction;
+    /** 次要动作（如「查看批注」）。 */
+    secondary?: {
+        label: string;
+        onClick: () => void;
+    };
+    busy: boolean;
+    busyLabel: string;
+    /** meta 行：只放**能真算出来**的事实。 */
+    meta: Array<{
+        label: string;
+        value: string;
+        tone?: 'ok' | 'warn' | 'bad';
+    }>;
+    /** 本批次进度；无批次传 null。 */
+    batch: {
+        label: string;
+        percent: number;
+        caption: string;
+    } | null;
+    /** 章节节点：上一章 / 现在 / 下一步。 */
+    nodes: Array<{
+        label: string;
+        text: string;
+        tone: 'done' | 'now' | 'next';
+    }>;
+    children?: ReactNode;
+}
+export declare function HomeHero({ kicker, seal, sealNote, stageLabel, action, secondary, busy, busyLabel, meta, batch, nodes, children, }: HomeHeroProps): JSX.Element;

package/lib/types/client/panel/ReviewIssueCard.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 审稿问题卡片（2.1.6 / 方案 §7「审稿问题卡片化」）。
+ *
+ * 为什么单独成卡而不是继续用 `<ul><li>`：
+ *   1. 此前每条意见被压成一行带色文字 —— 「问题」和「建议」用同一个色号、同一种排版，
+ *      作者扫读时无法快速分辨"哪句是诊断、哪句是处方"。
+ *   2. 勾选框与文字在同一行内联，窄容器下换行会把勾选框甩到行尾，勾错是常事。
+ *   3. 卡片把三件事固定成三层：**严重度徽章 + 维度** / **问题** / **建议**，
+ *      颜色只承担严重度（图形版语义色 → 文字版 -ink，保证对比度）。
+ */
+import type { ReactNode } from 'react';
+import type { ReviewIssue } from '../../protocol.ts';
+/** 严重度的作者口径文案（与 Severity 类型一一对应）。 */
+export declare const SEV_LABEL: Record<string, string>;
+export declare function ReviewIssueCard({ issue, dimensionLabel, checked, onToggle, disabled }: {
+    issue: ReviewIssue;
+    /** 维度中文名（由调用方查表，避免把文案表搬进组件）。 */
+    dimensionLabel?: string;
+    checked: boolean;
+    onToggle: (next: boolean) => void;
+    disabled?: boolean;
+    /** 预留：卡片右上角的附加动作（如「单条重写」）。 */
+    actions?: ReactNode;
+}): JSX.Element;

package/lib/types/client/panel/RunPanel.d.ts

@@ -1,5 +1,7 @@
 import type { NovelApi } from '../api.ts';
-export declare function RunPanel({ api, totalChapters }: {
+export declare function RunPanel({ api, totalChapters, onOpenChapter }: {
     api: NovelApi;
     totalChapters: number;
+    /** 打开某章的章节工作台（队列行的「打开工作台」与失败态的重试入口共用）。 */
+    onOpenChapter?: (no: number) => void;
 }): import("react").JSX.Element;

package/lib/types/client/panel/Skeleton.d.ts

@@ -0,0 +1,6 @@
+export declare function SkeletonLines({ label, lines }: {
+    /** 说清「在等什么」，如「正在读取写作资产…」。 */
+    label: string;
+    /** 占位行数。 */
+    lines?: number;
+}): JSX.Element;

package/lib/types/client/panel/helpers.d.ts

@@ -5,6 +5,7 @@
  * （键位不匹配会在编译期报错），保持客户端 bundle 自包含、不引入运行时语言服务。
  * 需要多语言时再接入 DSH 的 locale 服务，届时只需替换本函数实现。
  */
+import type { KeyboardEvent } from 'react';
 import { type NovelKey } from '../locales.ts';
 /** Translate one key with optional {placeholder} substitution. */
 export declare function tt(key: NovelKey, params?: Record<string, string | number>): string;
@@ -18,3 +19,14 @@ export declare function kindLabel(kind: string): string;
 export declare function plotlineStatusLabel(status: string): string;
 /** 剧情线状态颜色。 */
 export declare function plotlineStatusColor(status: string): string;
+/**
+ * 上下键在同类条目之间移动焦点（设计方案 §12「上下键移动章节列表 / 审稿问题」）。
+ *
+ * 只管焦点移动，不接管 Enter / 空格：条目保持原生 button 与 checkbox，
+ * 「空格勾选问题」「Enter 打开章节」继续由浏览器负责，不另造一套键盘语义。
+ * 焦点不在列表条目上时直接放行，方向键仍然用来滚动页面。
+ *
+ * @param event 列表容器上收到的 keydown。
+ * @param itemSelector 条目选择器，如 `.${css.wbIndexRow}` 或 `input[type="checkbox"]`。
+ */
+export declare function moveFocusByArrow(event: KeyboardEvent<HTMLElement>, itemSelector: string): void;

package/lib/types/engine.d.ts

@@ -26,13 +26,25 @@ export declare function inferBookName(outline: string): string;
 export declare function loadProject(outputDir: string): ProjectState | undefined;
 /** Persist the project state next to the chapters. */
 export declare function saveProject(outputDir: string, project: ProjectState): void;
+/** `mergeVolatileFromDisk` 会覆盖的易变字段的全集（也是 `keep` 的合法取值域）。 */
+declare const VOLATILE_FIELDS: readonly ["bible", "roles", "plotlines", "roleStatus", "blurb", "coverPath", "facts", "assets", "world", "volumes"];
+/** 易变字段名。用于 {@link mergeVolatileFromDisk} 的 `keep`：声明「本次我改过它，别覆盖」。 */
+export type VolatileField = (typeof VOLATILE_FIELDS)[number];
 /**
  * 并发保护：长任务（章节计划生成/正文生成）在内存中持有旧快照，
  * 期间其他请求可能修改了「易变字段」（道藏/角色库/剧情线/人物志存档/简介/封面）。
  * 保存前用磁盘最新版本合并这些字段，避免旧快照覆盖新修改（曾导致角色卡丢失）。
- * 注意：调用方若自己修改了这些字段，不要使用本函数。
+ *
+ * ⚠️ `keep` 不是可选的礼貌参数，而是本函数唯一的正确用法保证：
+ * 调用方只要自己写过这些字段中的任何一个（哪怕只是 `project.plotlines[0].chapters.push(no)`），
+ * **必须**把它列进 `keep`，否则本函数会用磁盘旧值把本轮成果整块覆盖掉。
+ * 历史上正是漏了 `facts` / `plotlines`，导致作者复盘回灌的事实与剧情线关联被静默丢弃。
+ *
+ * @param outputDir - 项目目录。
+ * @param project - 待保存的内存项目（原地修改）。
+ * @param keep - 本次调用方已自行修改过的易变字段，这些字段不从磁盘覆盖。
  */
-export declare function mergeVolatileFromDisk(outputDir: string, project: ProjectState): void;
+export declare function mergeVolatileFromDisk(outputDir: string, project: ProjectState, keep?: readonly VolatileField[]): void;
 /** 对一段文本做违禁词硬匹配，返回命中（词/类别/次数）。 */
 export declare function checkSensitiveText(text: string): Array<{
     word: string;
@@ -45,6 +57,15 @@ export declare function listChapterFiles(outputDir: string): string[];
 export declare function syncProjectWithDisk(project: ProjectState, outputDir: string): void;
 /** Read a chapter's markdown body from disk (undefined when missing). */
 export declare function readChapterFile(outputDir: string, chapter: ChapterPlan): string | undefined;
+/**
+ * 章节正文的**写盘时间**（文件 mtime，ISO）—— 面板「今日产出 / 日环比」的唯一本地事实来源。
+ *
+ * 为什么不把它写进 novel-project.json：它是**派生数据**。落盘后一旦文件被外部替换、
+ * 从备份回拷、或手工改名，存档里的时间戳就开始撒谎；mtime 永远跟着真实文件走。
+ * 代价是每次 /status 要对每个有正文的章 stat 一次 —— 本地磁盘上是微秒级，
+ * 相对它换来的"今天的产出是真的"，这个代价可以接受。
+ */
+export declare function chapterWrittenAt(outputDir: string, chapter: ChapterPlan): string | undefined;
 /** Create a fresh project from an outline. */
 export declare function createProject(outline: string, outlinePath?: string): ProjectState;
 /**
@@ -200,7 +221,7 @@ export declare function designPlotlinePlan(ctx: Context, config: NovelConfig, pr
  * untouched (local revision). Without `target`, the whole chapter is
  * rewritten. Yields delta text; persists when done.
  */
-export declare function rewriteChapterStream(ctx: Context, config: NovelConfig, project: ProjectState, outputDir: string, chapterNo: number, instructions: string, target?: string): AsyncGenerator<{
+export declare function rewriteChapterStream(ctx: Context, config: NovelConfig, project: ProjectState, outputDir: string, chapterNo: number, instructions: string, target?: string, signal?: AbortSignal): AsyncGenerator<{
     frame: 'start';
 } | {
     frame: 'delta';
@@ -212,7 +233,7 @@ export declare function rewriteChapterStream(ctx: Context, config: NovelConfig,
 }, void, unknown>;
 /** Stream a chapter polish (de-AI-ify). Draft-mode: the polished body lands
  *  in `chapter.pendingDraft` and is only applied on draft/apply. */
-export declare function polishChapterStream(ctx: Context, config: NovelConfig, project: ProjectState, outputDir: string, chapterNo: number): AsyncGenerator<{
+export declare function polishChapterStream(ctx: Context, config: NovelConfig, project: ProjectState, outputDir: string, chapterNo: number, signal?: AbortSignal): AsyncGenerator<{
     frame: 'start';
 } | {
     frame: 'delta';
@@ -225,7 +246,7 @@ export declare function polishChapterStream(ctx: Context, config: NovelConfig, p
 /** 统计中文字符数（汉字），与「每章字数」红线口径一致（不含标点/换行）。 */
 export declare function countHanzi(text: string): number;
 /** Generate one chapter (streaming). Yields progress frames; persists when done. */
-export declare function generateChapterStream(ctx: Context, config: NovelConfig, project: ProjectState, outputDir: string, chapterNo: number): AsyncGenerator<{
+export declare function generateChapterStream(ctx: Context, config: NovelConfig, project: ProjectState, outputDir: string, chapterNo: number, signal?: AbortSignal): AsyncGenerator<{
     frame: 'start';
 } | {
     frame: 'delta';
@@ -242,7 +263,7 @@ export declare function summarizeChapter(ctx: Context, config: NovelConfig, proj
  * 反向推大纲：从已写章节正文反推出全书总纲（分卷 + 章节要点 + 主线/人物弧线/伏笔清单）。
  * 两阶段：分批提取章节事件摘要 → 汇总生成大纲。不修改章节/设定，只返回大纲文本。
  */
-export declare function reverseOutlineFromChapters(ctx: Context, config: NovelConfig, project: ProjectState, outputDir: string, onProgress?: (done: number, total: number, phase: string) => void): Promise<string>;
+export declare function reverseOutlineFromChapters(ctx: Context, config: NovelConfig, project: ProjectState, outputDir: string, onProgress?: (done: number, total: number, phase: string) => void, signal?: AbortSignal): Promise<string>;
 /**
  * 改编模式 P0：全文分析 → 原文设定卡片 / 可改范围矩阵。
  * 拆章统计 + 取样正文，让 LLM 一次输出结构化 JSON：
@@ -278,6 +299,7 @@ export declare function rewriteAdaptationBook(ctx: Context, config: NovelConfig,
         no: number;
         title: string;
     }) => void;
+    signal?: AbortSignal;
 }): Promise<{
     adaptedText: string;
     rewritten: Array<{

package/lib/types/llm-live.d.ts

@@ -8,7 +8,7 @@
  *   3) **首字耗时**：调用方在拿到第一个文本增量时打点，用于观察模型响应速度。
  */
 import type { BlockAssembler, TokenUsage } from '@deepseek-ai/dsh-llm';
-import type { LlmLiveFrame, LlmPromptRecord, LlmTokenUsage, LlmUsageSummary } from './protocol.ts';
+import type { LlmLiveFinalPhase, LlmLiveFrame, LlmPromptRecord, LlmTokenUsage, LlmUsageSummary } from './protocol.ts';
 export type { LlmLiveFrame };
 type Listener = (frame: LlmLiveFrame) => void;
 export declare function nextSessionId(): string;
@@ -65,6 +65,6 @@ export declare function markFirstToken(handle: LiveCallHandle): void;
 export declare function endLiveCall(handle: LiveCallHandle, assembler: BlockAssembler, extra?: {
     chars?: number;
     preview?: string;
-    phase?: 'completed' | 'failed';
+    phase?: LlmLiveFinalPhase;
     error?: string;
 }): void;

package/lib/types/llm-retry.d.ts

@@ -15,6 +15,17 @@
  * @returns 可重试时为 true。
  */
 export declare function isRetryableLlmError(error: unknown): boolean;
+/**
+ * 判断一次失败是「取消」（作者关页面 / 主动中断）还是模型故障。
+ *
+ * 取消有两种现场：适配器给出 `aborted` 收尾块，或抛出 `AbortError` / 本插件自己的
+ * 断开错误。它必须和真实失败分开记账——否则面板「本次运行失败 N 次」会把作者的正常
+ * 中断统计成模型不稳定，进而误导备用模型档位判断（与规则 1「用户取消不重试」同一口径）。
+ *
+ * @param input 收尾块 kind（字符串）或捕获到的异常。
+ * @returns 属于取消时为 true。
+ */
+export declare function isCancellation(input: unknown): boolean;
 /**
  * 判断是否应当切换到备用模型。
  *

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：最终预览（截断）。 */

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.2.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",