@waterwx/dsh-novel-forge 1.2.1-alpha → 1.3.0-alpha

package/lib/types/action-guard.d.ts

@@ -1,7 +1,7 @@
 /**
  * 动作失败分级（fail-stop 规则）——不依赖 LLM/宿主服务的纯逻辑模块，可离线单测。
  *
- * 规则来源（借鉴 dsh-ai-novel-writer）：
+ * 规则来源（借鉴同类 DSH 小说插件的规则设计）：
  *  - 参数/契约类失败**不得重复同一调用**，解释一次即停；
  *  - 瞬时故障允许有限重试，同样禁止无限重试。
  * 规则必须可测试，否则只是文档。

package/lib/types/assets.d.ts

@@ -1,17 +1,17 @@
 /**
  * Writing assets — 题材基底库 / 推进模式库 / 反 AI 规则 / 写法引擎.
  *
- * Ported from AI-Novel-Writing-Assistant (Apache-2.0) built-in seed data:
- * - 8 preset style templates (DEFAULT_STYLE_TEMPLATES)
- * - 12 anti-AI rules with concrete detect patterns (DEFAULT_ANTI_AI_RULES)
- * - genre tree + progression mode seeds
+ * 内置种子数据（本项目自研表述；结构参考了同类工具的功能划分）：
+ * - 8 套预置叙事风格模板
+ * - 12 条带命中模式的反 AI 规则
+ * - 题材树 + 推进模式种子
  * Assets persist with the project (novel-project.json) and are injected into
  * generation / planning / review prompts, and available to the AI assistant.
  */
 import type { AntiAiRule, GenreNode, PlotBeatTemplate, ProgressionMode, ProjectAssets, StarterStyleProfile, StyleAsset, StyleTemplate } from './protocol.ts';
-/** 预置写法模板（来自 AI-Novel-Writing-Assistant 内置 DEFAULT_STYLE_TEMPLATES）。 */
+/** 预置叙事风格模板（8 套，一键绑定无需样本文本）。 */
 export declare const BUILTIN_STYLE_TEMPLATES: StyleTemplate[];
-/** 内置全局反 AI 规则（来自 AI-Novel-Writing-Assistant 内置 DEFAULT_ANTI_AI_RULES）。 */
+/** 内置全局反 AI 规则（12 条，随插件发布；项目可叠加自定义规则）。 */
 export declare const BUILTIN_ANTI_AI_RULES: AntiAiRule[];
 /** 内置题材基底库（常用网文题材树，跨书复用）。 */
 export declare const BUILTIN_GENRE_LIBRARY: GenreNode[];
@@ -38,7 +38,7 @@ export declare function renderStyleAssets(assets: ProjectAssets | undefined): st
 export declare function renderAllAssets(assets: ProjectAssets | undefined): string;
 /** 预置写法模板 → 可直接绑定的 StyleAsset。 */
 export declare function styleTemplateToAsset(template: StyleTemplate): StyleAsset;
-/** 起始风格画像库：无样本文本也能快速绑定一套写法（对齐上游 DEFAULT_STARTER_STYLE_PROFILES）。 */
+/** 起始风格画像库：无样本文本也能快速绑定一套写法（4 档起步写法）。 */
 export declare const BUILTIN_STARTER_STYLE_PROFILES: StarterStyleProfile[];
 /** 起始风格画像 → 可直接绑定的 StyleAsset（绑定对应模板，名称用画像名）。 */
 export declare function starterProfileToAsset(profile: StarterStyleProfile): StyleAsset | null;

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

@@ -33,7 +33,7 @@ export declare class NovelApi {
         summary: string;
     }>;
     foreshadow(req: ForeshadowRequest): Promise<ForeshadowResponse>;
-    exportBook(format: 'txt' | 'md'): Promise<ExportResponse>;
+    exportBook(format: 'txt' | 'md' | 'json', scope?: import('../protocol.ts').ExportScope): Promise<ExportResponse>;
     chapter(no: number): Promise<ChapterResponse>;
     /** 审查手动编辑的正文（不落盘）。previousReport 传入时走「验证模式」（核对原意见解决 + 只挑新增 high）。 */
     chapterCheck(no: number, text: string, previousReport?: ReviewReport): Promise<{
@@ -269,6 +269,36 @@ export declare class NovelApi {
     }>;
     /** Run one assistant turn (NDJSON stream). */
     assistant(message: string, onFrame: (frame: import('../protocol.ts').AssistantFrame) => void): Promise<void>;
+    /** 张力曲线：数据 + 规则核对。 */
+    tension(): Promise<import('../protocol.ts').TensionResponse>;
+    /** 设置张力曲线预设。 */
+    tensionPreset(preset: import('../protocol.ts').TensionCurvePreset): Promise<void>;
+    /** 设置/清除某一章的目标张力。 */
+    tensionSet(chapterNo: number, tension?: number): Promise<void>;
+    /** 提示词槽位：列表。 */
+    promptSlots(): Promise<import('../protocol.ts').PromptSlotsResponse>;
+    /** 写入一个提示词槽位（空串 = 清空）。 */
+    promptSlotSet(id: import('../protocol.ts').PromptSlotId, value: string): Promise<void>;
+    /** 故事时间线：列表（含规则初筛问题）。 */
+    timeline(): Promise<import('../protocol.ts').TimelineResponse>;
+    /** 抽取某一章的时间线事件。 */
+    timelineExtract(chapterNo: number): Promise<{
+        events: import('../protocol.ts').TimelineEvent[];
+    }>;
+    /** 检查时间线矛盾（规则初筛 + AI 复核）。 */
+    timelineCheck(): Promise<import('../protocol.ts').TimelineResponse>;
+    /** 手工修正一条时间线事件。 */
+    timelineUpdate(event: import('../protocol.ts').TimelineEvent): Promise<void>;
+    /** 删除一条时间线事件。 */
+    timelineRemove(id: string): Promise<void>;
+    /** 章节历史版本列表。 */
+    snapshots(): Promise<import('../protocol.ts').SnapshotResponse>;
+    /** 回滚到某个历史版本。 */
+    snapshotRestore(id: string): Promise<void>;
+    /** 给某章手工存档。 */
+    snapshotCreate(chapterNo: number): Promise<void>;
+    /** 删除一个历史版本。 */
+    snapshotRemove(id: string): Promise<void>;
     /** Load the persisted assistant conversation. */
     assistantHistory(): Promise<import('../protocol.ts').AssistantMessage[]>;
     /** 清空助手对话记录。 */

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

@@ -2,20 +2,8 @@
  * 浏览器端「AI 创作实况」钩子：连接 /llm-live/stream (SSE)，按 LLM 调用分组会话。
  * 轻量实现，不持久化缓存（对齐上游 useLlmLiveFeed 的核心行为）。
  */
-export interface LlmLiveFrame {
-    type: 'session_started' | 'output_delta' | 'reasoning_delta' | 'phase_changed' | 'session_completed';
-    sessionId: string;
-    label?: string;
-    model?: string;
-    at: string;
-    content?: string;
-    totalChars?: number;
-    totalReasoningChars?: number;
-    phase?: 'requesting' | 'streaming' | 'completed' | 'failed';
-    phaseMessage?: string;
-    preview?: string;
-    error?: string;
-}
+import { type LlmLiveFrame, type LlmTokenUsage } from '../protocol.ts';
+export type { LlmLiveFrame };
 export interface LlmLiveSession {
     sessionId: string;
     label: string;
@@ -26,6 +14,16 @@ export interface LlmLiveSession {
     totalChars: number;
     startedAt: string;
     updatedAt: string;
+    /** 本次调用的 token 用量（供应商未上报时缺省）。 */
+    usage?: LlmTokenUsage;
+    /** 本次调用耗时（毫秒）。 */
+    elapsedMs?: number;
+    /** 首字耗时（毫秒）。 */
+    firstTokenMs?: number;
+    /** 是否保存了可查看的 Prompt。 */
+    hasPrompt?: boolean;
+    /** Prompt 字符数（system + user）。 */
+    promptChars?: number;
 }
 export declare function useLlmLiveFeed(enabled?: boolean): {
     connected: boolean;

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

@@ -2,6 +2,11 @@
  * 「实时调用 / LIVE」—— 内嵌到 AI 进度窗的下半区（详情层），不再独立浮窗。
  * 连接 /llm-live/stream，按 LLM 调用分组展示模型实时输出。
  *
+ * 除实时输出外，这里还承担两件与「花了多少」有关的事：
+ *   1) 每次调用显示 token 用量（输入↑ / 输出↓ / 思考）与耗时、首字耗时；
+ *   2) 「查看 Prompt」按 sessionId 拉取这次调用**实际发送**的 system / user。
+ * 顶部另有一条「本次运行」累计条（进程内，重启归零）。
+ *
  * 状态色全部走 panel.module.css 的 .lfPill / .lfDot（主题令牌 + --nf-streaming），
  * 不再内联硬编码色；布局性 inline style 保留（均为令牌引用或动态值）。
  */

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

@@ -1,7 +1,7 @@
 import type { NovelApi } from '../api.ts';
 import type { SavedModel } from '../../protocol.ts';
-/** 目录不可用时回退的内置预设（历史行为）。 */
-export declare const FALLBACK_MODEL_PRESETS: readonly ["deepseek-v4-flash", "deepseek-v4-pro", "deepseek-chat", "deepseek-reasoner"];
+/** 目录不可用时回退的内置预设（对齐当前模型目录）。 */
+export declare const FALLBACK_MODEL_PRESETS: readonly ["deepseek-flash", "deepseek-v4-pro", "deepseek-chat", "deepseek-reasoner"];
 export interface ModelManagerProps {
     api: NovelApi;
     provider: string;

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

@@ -0,0 +1,11 @@
+/**
+ * 提示词槽位：给作者留几个**安全可改**的位置来微调本书表达偏好。
+ *
+ * 边界写在界面上：槽位只**追加偏好**，不能覆盖道藏、写作红线、九条内容合规红线、
+ * 反 AI 规则与阶段契约 —— 这些由宿主锁定。清空即恢复默认。
+ */
+import type { NovelApi } from '../api.ts';
+export interface PromptSlotsViewProps {
+    api: NovelApi;
+}
+export default function PromptSlotsView({ api }: PromptSlotsViewProps): JSX.Element;

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

@@ -0,0 +1,14 @@
+/**
+ * 张力曲线：把「每章该有多紧」画出来并可逐章调整。
+ *
+ * 图上是三条线：
+ *   参考（虚线，形状预设） / 目标（实线，作者或规划设定） / 实际（散点，审稿打分）。
+ * 下方列出规则核对发现的曲线级问题（连续同值、高位不回落、长期低位、实际偏离目标）。
+ *
+ * 张力只影响写作提示词里的"松紧"指引，不改变任何校验规则。
+ */
+import type { NovelApi } from '../api.ts';
+export interface TensionViewProps {
+    api: NovelApi;
+}
+export default function TensionView({ api }: TensionViewProps): JSX.Element;

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

@@ -0,0 +1,14 @@
+/**
+ * 故事时间线：把逐章抽取的「时间点 / 地点 / 在场角色 / 事件」按章节顺序排开，
+ * 带规则初筛 + AI 复核的矛盾清单，并支持就地修正（手改后标记为 manual）。
+ *
+ * 与「编年录」的分工：编年录记事实状态，这里记**顺序**——专门抓时间倒流、
+ * 地点瞬移、跨度不合理这类长篇最容易崩的地方。
+ */
+import type { NovelApi } from '../api.ts';
+export interface TimelineViewProps {
+    api: NovelApi;
+    /** 章节号列表（用于「抽取本章」下拉）。 */
+    chapters: number[];
+}
+export default function TimelineView({ api, chapters }: TimelineViewProps): JSX.Element;

package/lib/types/engine.d.ts

@@ -12,7 +12,7 @@
  */
 export declare const COMPLIANCE_REDLINES: ReadonlyArray<string>;
 import type { Context } from '@deepseek-ai/cordis';
-import type { AdaptationDimension, AdaptAnalyzeResponse, AdaptationMapping, AdaptationRules, AdaptProposeResponse, AuditIssue, AuthorReview, BreakdownResponse, ChapterPlan, Foreshadow, NovelConfig, OutlineCandidate, Plotline, PlotlineHealthReport, PlotlinePlan, ProjectState, ReviewReport, RoleRecord, RoleStatusCard, StoryBible, AddModelRequest, AddModelResponse, LlmModelsResponse, LlmVendorsResponse, LlmProvidersResponse, RemoveProviderRequest, RemoveProviderResponse, LlmTestResponse, Volume, WorldState, AdaptMaterializeRequest, AdaptMaterializeResponse, AdaptMaterializeSaveRequest, AdaptMaterializeSaveResponse, MarketRadarRequest, MarketRadarResult, MarketRadarSignal, MarketRadarBriefRequest, ProductionFoundation, MarketCreativeBrief, BookAnalysisRequest, BookAnalysisResult, IdeaInspirationRequest, IdeaInspirationResult, DirectorRequest, DirectorAdvice } from './protocol.ts';
+import type { AdaptationDimension, AdaptAnalyzeResponse, AdaptationMapping, AdaptationRules, AdaptProposeResponse, AuditIssue, AuthorReview, ExportScope, TimelineEvent, TimelineIssue, BreakdownResponse, ChapterPlan, Foreshadow, NovelConfig, OutlineCandidate, Plotline, PlotlineHealthReport, PlotlinePlan, ProjectState, ReviewReport, RoleRecord, RoleStatusCard, StoryBible, AddModelRequest, AddModelResponse, LlmModelsResponse, LlmVendorsResponse, LlmProvidersResponse, RemoveProviderRequest, RemoveProviderResponse, LlmTestResponse, Volume, WorldState, AdaptMaterializeRequest, AdaptMaterializeResponse, AdaptMaterializeSaveRequest, AdaptMaterializeSaveResponse, MarketRadarRequest, MarketRadarResult, MarketRadarSignal, MarketRadarBriefRequest, ProductionFoundation, MarketCreativeBrief, BookAnalysisRequest, BookAnalysisResult, IdeaInspirationRequest, IdeaInspirationResult, DirectorRequest, DirectorAdvice } from './protocol.ts';
 /** Project state file name inside the output dir. */
 export declare const PROJECT_FILE = "novel-project.json";
 /** Chapter output file name, e.g. 第001章_开篇.md */
@@ -99,7 +99,7 @@ export declare function importBookText(filePath: string, outputDir: string): {
 /** 保证风格词块已内嵌（LLM 偶发漏嵌时兜底）：zh 段首前缀，en 末尾追加。 */
 export declare function suggestOutlines(ctx: Context, config: NovelConfig, idea: string, count?: number, exclude?: string[]): Promise<OutlineCandidate[]>;
 /** 拆书分析：对已写章节做结构/人物/文风/卖点四维体检。
- *  两阶段管道（借鉴 AI-Novel-Writing-Assistant）：
+ *  两阶段管道（先抽取候选、再落库）：
  *  ① 源片段笔记：每章抽取结构化笔记（剧情/人物/设定/写法/卖点/短板信号）
  *  ② 分节分析：按维度各跑一次 LLM，输出可读分析稿 + 结构化数据 + 证据链。
  *  @param scope 'recent'(默认最近20章) | 'volume:N' | 'all'
@@ -331,9 +331,47 @@ export declare function runMarketIdeaInspiration(ctx: Context, config: NovelConf
 }): Promise<IdeaInspirationResult>;
 /** 自动导演编排建议：基于全书上下文，给出下一卷/阶段编排 + 修复再平衡。 */
 export declare function runDirectorAdvice(ctx: Context, config: NovelConfig, project: ProjectState, req: DirectorRequest): Promise<DirectorAdvice>;
+/**
+ * 从一章正文抽取时间线事件（时间点 / 地点 / 参与角色 / 事件）。
+ *
+ * 会**替换**该章已有事件（重复抽取幂等）；抽取结果按 order 递增排序后写回项目。
+ * 失败时抛错，由调用方决定是否降级（自动流程用 try/catch 包住，不阻断出章）。
+ *
+ * @param ctx 宿主上下文。
+ * @param config 运行时配置。
+ * @param project 项目状态（就地更新 `project.timeline`）。
+ * @param outputDir 书目录。
+ * @param chapterNo 章节号。
+ * @returns 本次抽取到的事件（已写入 project）。
+ */
+export declare function extractTimelineForChapter(ctx: Context, config: NovelConfig, project: ProjectState, outputDir: string, chapterNo: number): Promise<TimelineEvent[]>;
+/**
+ * AI 复核时间线：在规则初筛之外，让模型找规则抓不到的时序问题
+ * （年龄/季节错位、回忆与当前时间混淆、跨章跨度不合理等）。
+ *
+ * @param ctx 宿主上下文。
+ * @param config 运行时配置。
+ * @param project 项目状态。
+ * @returns 模型给出的问题清单（与规则初筛结果合并由调用方决定）。
+ */
+export declare function reviewTimeline(ctx: Context, config: NovelConfig, project: ProjectState): Promise<TimelineIssue[]>;
 /** Export the whole book as one txt/md file. */
 export declare function exportBook(outputDir: string, project: ProjectState, format: 'txt' | 'md'): {
     file: string;
     chars: number;
     chapters: number;
 };
+/**
+ * 按范围导出：整本正文 / 设定 / 规划 / 角色 / 质检记录 / 项目 JSON。
+ *
+ * @param outputDir 书目录。
+ * @param project 项目状态。
+ * @param scope 导出范围。
+ * @param format txt / md / json（json 只对 `project` 范围有独立含义，其余按 md 落盘）。
+ * @returns 文件名、字符数与章节数。
+ */
+export declare function exportScope(outputDir: string, project: ProjectState, scope: ExportScope, format: 'txt' | 'md' | 'json'): {
+    file: string;
+    chars: number;
+    chapters: number;
+};

package/lib/types/index.d.ts

@@ -39,6 +39,10 @@ export interface Config {
     reviewModel?: string;
     /** 任务级模型路由：质检模型（留空则跟随 model）。 */
     auditModel?: string;
+    /** 备用模型：主模型失败时自动切换重试一次（留空 = 不切换）。 */
+    fallbackModel?: string;
+    /** 出章后自动抽取故事时间线（默认开）。 */
+    autoTimeline?: boolean;
     /** LLM reasoning effort (off/low/high/max). */
     reasoningEffort?: 'off' | 'low' | 'high' | 'max';
     /** 分析类任务（提炼/拆书/反推大纲等）的推理档位；默认 low。 */

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

@@ -1,44 +1,75 @@
 /**
- * LLM 实况 feed（对齐上游「AI 创作实况 / LIVE LOG」的轻量实现）。
+ * LLM 实况 feed：以「每次 LLM 调用」为粒度，把生命周期事件（开始/流式正文/阶段变化/完成）
+ * 推给订阅者，并提供环形缓冲供新连上的客户端重放。
  *
- * 以「每次 LLM 调用」为粒度，把生命周期事件（开始/流式正文/阶段变化/完成）推给订阅者，
- * 并提供环形缓冲供新连上的客户端重放。不持久化（与上游缓存不同，如需成 cache 再扩展）。
+ * 同时承担三件与用量有关的事（进程内，不落盘）：
+ *   1) **用量账本**：每次调用结束后按用途累计 token / 耗时，供 /status 展示；
+ *   2) **Prompt 记录**：保存每次调用实际发送的 system + user（环形，按需查询）；
+ *   3) **首字耗时**：调用方在拿到第一个文本增量时打点，用于观察模型响应速度。
  */
+import type { BlockAssembler, TokenUsage } from '@deepseek-ai/dsh-llm';
+import type { LlmLiveFrame, LlmPromptRecord, LlmTokenUsage, LlmUsageSummary } from './protocol.ts';
+export type { LlmLiveFrame };
 export type LlmLivePhase = 'requesting' | 'streaming' | 'completed' | 'failed';
-export interface LlmLiveFrame {
-    type: 'session_started' | 'output_delta' | 'reasoning_delta' | 'phase_changed' | 'session_completed';
-    /** 由服务端生成，形如 ll-<n>。 */
-    sessionId: string;
-    /** 本次调用用途（如 正文生成/审稿/章节规划）。 */
-    label?: string;
-    /** 使用模型（用于展示）。 */
-    model?: string;
-    /** 事件时间（ISO）。 */
-    at: string;
-    /** session_started / 部分帧：交互上下文。 */
-    context?: {
-        taskId?: string;
-        interactionId: string;
-    };
-    /** output_delta / reasoning_delta：本次增量文本。 */
-    content?: string;
-    /** session 累计字符数。 */
-    totalChars?: number;
-    /** reasoning 累计字符数。 */
-    totalReasoningChars?: number;
-    /** phase_changed：新阶段。 */
-    phase?: LlmLivePhase;
-    /** phase_changed：阶段描述。 */
-    phaseMessage?: string;
-    /** session_completed：最终预览（截断）。 */
-    preview?: string;
-    /** session_completed：失败信息。 */
-    error?: string;
-}
 type Listener = (frame: LlmLiveFrame) => void;
 export declare function nextSessionId(): string;
 export declare function subscribeLiveFeed(listener: Listener): () => void;
 export declare function emitLive(frame: LlmLiveFrame): void;
 export declare function liveLatest(): LlmLiveFrame[];
 export declare function clearLiveFeed(): void;
-export {};
+/** 把 dsh-llm 的 usage 转成线上形状。 */
+export declare function toLiveUsage(usage: TokenUsage | undefined): LlmTokenUsage | undefined;
+/** 本次运行的用量汇总（按耗时降序排列用途，便于看谁最贵）。 */
+export declare function liveUsage(): LlmUsageSummary;
+/** 清零用量账本（面板「重新计数」用）。 */
+export declare function resetLiveUsage(): void;
+/** 记一条 Prompt（超长截断并标记）。 */
+export declare function recordPrompt(input: {
+    sessionId: string;
+    label?: string;
+    model?: string;
+    system?: string;
+    user?: string;
+}): LlmPromptRecord;
+/** 取一条 Prompt 记录（不存在返回 undefined）。 */
+export declare function livePrompt(sessionId: string): LlmPromptRecord | undefined;
+/** 清空 Prompt 记录。 */
+export declare function clearLivePrompts(): void;
+/** 一次调用的打点句柄。 */
+export interface LiveCallHandle {
+    sessionId: string;
+    startedAt: number;
+    /** 用途（用于 session_completed 的用量分组）。 */
+    label: string;
+    /** 实际使用的模型。 */
+    model: string;
+    /** 首字耗时（毫秒），由 markFirstToken 写入。 */
+    firstTokenMs?: number;
+}
+/**
+ * 开始一次 LLM 调用：发 session_started、记 Prompt、起计时。
+ *
+ * @param input 用途/模型/实际发送的 system 与 user。
+ * @returns 打点句柄（结束时交给 endLiveCall）。
+ */
+export declare function beginLiveCall(input: {
+    label: string;
+    model: string;
+    system?: string;
+    user?: string;
+}): LiveCallHandle;
+/** 首字打点（调用方在收到第一个文本增量时调用，只记第一次）。 */
+export declare function markFirstToken(handle: LiveCallHandle): void;
+/**
+ * 结束一次 LLM 调用：从 assembler 取用量，发 session_completed（含 token/耗时/首字）。
+ *
+ * @param handle beginLiveCall 的句柄。
+ * @param assembler 本次调用的 BlockAssembler。
+ * @param extra 字符数/预览/失败信息等。
+ */
+export declare function endLiveCall(handle: LiveCallHandle, assembler: BlockAssembler, extra?: {
+    chars?: number;
+    preview?: string;
+    phase?: 'completed' | 'failed';
+    error?: string;
+}): void;

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

@@ -0,0 +1,38 @@
+/**
+ * 模型失败恢复规则（纯逻辑，可离线单测）。
+ *
+ * 解决的问题：批量连写时，主模型偶发限流/超时/额度耗尽会让**整批中断**，
+ * 而换一个模型重试一次往往就能过去。规则：
+ *   1) 只对「可重试」错误切换模型——用户主动取消、参数/契约类错误不重试；
+ *   2) 备用模型为空或与主模型相同则不切换；
+ *   3) 备用模型也失败时，抛**原始错误**（保留主因，不掩盖现场）；
+ *   4) 每次调用最多切换一次。
+ */
+/**
+ * 判断一次 LLM 失败是否值得换模型重试。
+ *
+ * @param error 捕获到的异常。
+ * @returns 可重试时为 true。
+ */
+export declare function isRetryableLlmError(error: unknown): boolean;
+/**
+ * 判断是否应当切换到备用模型。
+ *
+ * @param fallbackModel 配置的备用模型（空串 = 未配置）。
+ * @param primaryModel 本次实际使用的主模型。
+ * @param error 捕获到的异常。
+ * @returns 应当切换时为 true。
+ */
+export declare function shouldSwitchModel(fallbackModel: string | undefined, primaryModel: string, error: unknown): boolean;
+/**
+ * 用主模型执行；失败且满足切换条件时，用备用模型再执行一次。
+ *
+ * @param input 主模型 / 备用模型 / 实际执行函数（接收本次要用的模型 id）。
+ * @returns 执行结果（备用模型成功时返回其结果）。
+ * @throws 主模型失败且未切换时抛原错误；切换后仍失败时同样抛**主模型的原始错误**。
+ */
+export declare function withModelFallback<T>(input: {
+    model: string;
+    fallbackModel?: string;
+    onSwitch?: (from: string, to: string, error: unknown) => void;
+}, run: (model: string) => Promise<T>): Promise<T>;

package/lib/types/market-radar-sources.d.ts

@@ -1,5 +1,5 @@
 /**
- * 「热门题材雷达」真实榜单抓取源（移植自 AI-Novel-Writing-Assistant marketRadarSources）。
+ * 「热门题材雷达」真实榜单抓取源（公开榜单页面的地址与选择器，属事实性配置）。
  * 用全局 fetch 抓取公开榜单移动版页面，正则抽取元数据；无第三方依赖。
  */
 export type MarketRadarPlatform = 'fanqie' | 'qidian' | 'jinjiang';

package/lib/types/prompt-slots.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 提示词槽位：给作者留几个**安全可改**的位置，用来微调本书的写作偏好。
+ *
+ * 设计边界（很重要）：
+ *   * 槽位只追加"作者偏好"，**不允许覆盖**规则工程与合规红线——道藏、写作红线、
+ *     九条内容合规红线、反 AI 规则、阶段契约都由宿主锁定，槽位碰不到；
+ *   * 槽位内容随项目保存（`novel-project.json`），换书即换槽位；
+ *   * 每个槽位有长度上限，超长直接截断并标记（沿用「截断显式化」的规则）。
+ */
+import type { ProjectState, PromptSlotId } from './protocol.ts';
+/** 单个槽位的元信息。 */
+export interface PromptSlotSpec {
+    id: PromptSlotId;
+    /** 面板显示名。 */
+    label: string;
+    /** 一句话说明它影响什么。 */
+    hint: string;
+    /** 示例（面板占位符）。 */
+    placeholder: string;
+    /** 字符上限。 */
+    maxChars: number;
+}
+/** 允许作者编辑的槽位（白名单；不在此列表的提示词一律不可改）。 */
+export declare const PROMPT_SLOTS: readonly PromptSlotSpec[];
+/** 单个槽位的渲染结果。 */
+export interface RenderedSlot {
+    id: PromptSlotId;
+    label: string;
+    text: string;
+    /** 是否因超长被截断。 */
+    truncated: boolean;
+    /** 原文长度（截断前）。 */
+    chars: number;
+}
+/**
+ * 读取并规整项目里的槽位内容（去空白、按上限截断）。
+ *
+ * @param project 项目状态。
+ * @returns 非空槽位列表（保持 PROMPT_SLOTS 的声明顺序）。
+ */
+export declare function readPromptSlots(project: ProjectState): RenderedSlot[];
+/**
+ * 把槽位渲染成注入提示词的段落。
+ *
+ * @param project 项目状态。
+ * @returns 提示词片段；无槽位时返回空串。
+ */
+export declare function renderPromptSlots(project: ProjectState): string;
+/**
+ * 校验并规整一次槽位写入。
+ *
+ * @param id 槽位 id。
+ * @param value 内容（空串表示清空该槽位）。
+ * @returns 归一化后的内容。
+ * @throws 槽位 id 不在白名单时抛错。
+ */
+export declare function normalizeSlotValue(id: string, value: string): string;

package/lib/types/prompting.d.ts

@@ -1,5 +1,5 @@
-/** 章节写作约束：官方 writer 骨架渲染成可附加到现有系统提示词末尾的必达/禁止/自查块。 */
-export declare function renderOfficialChapterWriterSkeleton(meta: {
+/** 章节写作约束：把写作骨架渲染成可附加到系统提示词末尾的必达/禁止/自查块。 */
+export declare function renderChapterWriterSkeleton(meta: {
     targetChars: number;
     minChars: number;
     maxChars: number;