@waterwx/dsh-novel-forge 2.1.2-alpha → 2.1.2

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

@@ -0,0 +1,61 @@
+/**
+ * 动作失败分级（fail-stop 规则）——不依赖 LLM/宿主服务的纯逻辑模块，可离线单测。
+ *
+ * 规则来源（借鉴同类 DSH 小说插件的规则设计）：
+ *  - 参数/契约类失败**不得重复同一调用**，解释一次即停；
+ *  - 瞬时故障允许有限重试，同样禁止无限重试。
+ * 规则必须可测试，否则只是文档。
+ */
+/**
+ * 动作失败分级：
+ * - `contract` 参数/契约类（参数缺失、片段未找到、章节不存在、非法取值…）：
+ *   同一调用只允许修正一次，禁止原样重复。
+ * - `transient` 瞬时故障（网络、模型中断、磁盘临时不可用…）：允许重试一次。
+ */
+export type ActionErrorKind = 'contract' | 'transient';
+/** 带分级的动作失败（executeAction 抛出，供 fail-stop 判定）。 */
+export declare class NovelActionError extends Error {
+    readonly kind: ActionErrorKind;
+    constructor(kind: ActionErrorKind, message: string);
+}
+/**
+ * 判定一次动作失败的类别。
+ *
+ * @param error 捕获到的异常。
+ * @returns `contract`（参数/契约，不重试原样调用）或 `transient`（瞬时，可重试一次）。
+ */
+export declare function classifyActionError(error: unknown): ActionErrorKind;
+/**
+ * 同一调用签名允许的总尝试次数（含首次）。
+ *
+ * @param kind 失败类别。
+ * @returns `contract` = 1（禁止原样重复），`transient` = 2（允许一次重试）。
+ */
+export declare function actionRetryLimit(kind: ActionErrorKind): number;
+/**
+ * 把动作参数规范化为稳定签名（键排序），用于识别「同一个调用」。
+ *
+ * @param args 动作参数。
+ * @returns 稳定字符串签名。
+ */
+export declare function safeArgsKey(args: Record<string, unknown> | undefined): string;
+/**
+ * 已失败调用记账：同一签名达到重试上限即 fail-stop。
+ */
+export declare class FailureLedger {
+    private readonly counts;
+    /**
+     * 记录一次失败并判断是否应当停止本轮。
+     *
+     * @param tool 工具名。
+     * @param args 该次调用参数。
+     * @param kind 失败类别。
+     * @returns `attempts` 本次是第几次失败；`stop` 是否达到上限（true = 立即停止，不再喂回模型）。
+     */
+    record(tool: string, args: Record<string, unknown> | undefined, kind: ActionErrorKind): {
+        attempts: number;
+        stop: boolean;
+    };
+    /** 已登记的失败签名数量（测试/诊断用）。 */
+    get size(): number;
+}

package/lib/types/ai-scan.d.ts

@@ -3,34 +3,88 @@
  *
  * 用途：生成/润色后自动扫描，结果作为「事实锚点」注入审稿提示词，
  * 让 LLM 做判断而非机械统计。也可用于 UI 展示 AI 味指标。
+ *
+ * ## 度量口径
+ *
+ * 下面五条口径全部用 **1279 章 / 6 本已发布书稿**实测标定过。前两条是**已修复的
+ * 真实缺陷**（不是调参偏好），后三条是把不可比的量纲换成可比的。
+ *
+ * 1. **段落**：书稿正文的自然段由**单换行**分隔（run.ts 写盘即如此），历史实现按
+ *    /\n{2,}/ 切 —— 在真实书稿上整章只切出 **2 段**（1279 章无一例外），于是段落方差、
+ *    过长段、连续解说段三项指标全部失效，其中「连续解说段 >= 3」永不成立。
+ *    现按 /\n+/ 切，并剔除 # 标题行。实测每章 p50 = 68 段，段落均长 p50 = 50 字。
+ * 2. **对话**：中文书稿主流用全角弯引号（语料 6 本里 **5 本**如此：番茄线上正文、
+ *    还债疯了、我养的废柴师妹、归墟玉主、保质期），历史实现的字符类只认 ASCII 双引号
+ *    与角括号，使这 5 本的对话占比**恒为 0**，并因此每章误加 10 分。
+ * 3. **段落整齐度**：用变异系数 CV = sigma / mean，不用方差 —— 方差的量纲是「字符平方」，
+ *    随段长平方缩放，段落均长 50 与均长 500 的章用同一个绝对阈值不可比。
+ *    语料 CV：p5 0.55 / p50 0.69 / p95 0.87。
+ * 4. **套话按稀有度加权**：历史实现把「重度 / 轻度」两档等同计分，而实测「知道」覆盖
+ *    78.4% 的已发布章节、「微微」48.2%，「难以言喻」0.0%、「不由得」0.1%。把前者与后者
+ *    等同，会让所有正常章节的基线虚高。现按相对语料的覆盖率给权重（见 PATTERN_COVERAGE）。
+ * 5. **短章不再爆炸**：密度分母取 max(字数, 2000) —— 历史实现里同样「1 次套话」，在
+ *    444 字的章值 18 分、在 3576 字的章值 2.2 分，同一现象 8 倍权重差。
+ *
+ * 分项满分与语料分位点的对应关系集中在 {@link SCORE_SPEC}，便于日后重新标定。
  */
 export interface AiScanResult {
     /** 总评分 0-100，越高越像 AI 写的 */
     aiScore: number;
-    /** 命中的套话及次数 */
+    /** 命中的套话及次数（weight 为该词按语料稀有度折算的权重，0 = 功能词） */
     clicheHits: Array<{
         word: string;
         count: number;
+        weight: number;
     }>;
-    /** 段落长度方差（过高=段落过于整齐） */
+    /** 判定用的自然段数（口径可自查：真实书稿每章数十段） */
+    paragraphCount: number;
+    /** 段落长度方差（保留原字段，注意其量纲随段长平方缩放，判定请用 cv） */
     paragraphLengthVariance: number;
-    /** 连续解释性叙事段数（≥3 视为问题） */
+    /** 段落长度变异系数 sigma / mean：与段长规模无关，整齐度判定用这个 */
+    paragraphLengthCv: number;
+    /** 连续解释性叙事段数（>=3 视为问题） */
     consecutiveExpositoryParagraphs: number;
     /** 句式重复率（相同开头句式占比） */
     sentenceRepetitionRate: number;
-    /** 过长段落数（>300字） */
+    /** 过长段落数（>300 字） */
     longParagraphCount: number;
-    /** 过短段落数（<20字） */
+    /** 过短段落数（<20 字） */
     shortParagraphCount: number;
     /** 对话占比（0-1） */
     dialogueRatio: number;
+    /** 作者生效规则里的确定性命中（按规则逐条统计；未传规则时为空） */
+    ruleHits: AiScanRuleHit[];
+    /** 各分项得分：便于自查「这章凭什么这么多分」，也是标定与单测的抓手 */
+    scoreParts: AiScanScoreParts;
     /** 问题摘要，可直接注入审稿提示词 */
     summary: string;
 }
-export declare function scanAiFlavor(text: string): AiScanResult;
-/** 扫描前后对比（润色时用） */
-export declare function compareAiScan(before: AiScanResult, after: AiScanResult): {
-    improved: boolean;
-    deltaScore: number;
-    details: string[];
-};
+/** 评分分项（每项满分与语料分位点的对应见 SCORE_SPEC）。 */
+export interface AiScanScoreParts {
+    /** 套话/模式：满分对应语料加权密度 p99（2.478/千字，63 模式并集口径） */
+    cliche: number;
+    /** 段落过于整齐（CV 低于语料 p5） */
+    uniformParagraphs: number;
+    /** 连续解释性叙事 */
+    expository: number;
+    /** 句首重复率（零点取语料 p50 = 0.37，满分取 p99 = 0.63） */
+    repetition: number;
+    /** 对话占比过低 */
+    lowDialogue: number;
+}
+/** 扫描器需要的规则输入（结构类型，避免 ai-scan 反向依赖协议层）。 */
+export interface AiScanRuleInput {
+    name: string;
+    severity?: 'forbidden' | 'risk' | 'encourage';
+    detectPatterns?: readonly string[];
+}
+/** 一条规则在本章的确定性命中（只报命中的规则）。 */
+export interface AiScanRuleHit {
+    name: string;
+    severity?: 'forbidden' | 'risk' | 'encourage';
+    matches: Array<{
+        pattern: string;
+        count: number;
+    }>;
+}
+export declare function scanAiFlavor(text: string, rules?: readonly AiScanRuleInput[]): AiScanResult;

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[];
@@ -23,8 +23,6 @@ export declare const BUILTIN_PLOT_BEATS: PlotBeatTemplate[];
 export declare function emptyProjectAssets(): ProjectAssets;
 /** 合并项目资产与内置库：返回「生效的反 AI 规则」（内置全局 + 项目自定义）。 */
 export declare function effectiveAntiAiRules(assets: ProjectAssets | undefined): AntiAiRule[];
-/** 安定 key：内置规则全局基线（globalBaselineEnabled）在新书/旧书一律生效。 */
-export declare function ensureGlobalBaseline(assets: ProjectAssets | undefined): ProjectAssets;
 /** 内置库种子化 upsert（对齐上游 SystemResourceBootstrapService 精神）。
  *  missing_only 仅补齐缺失的全局基线规则；sync_existing 还会按 key 刷新已内置规则的结构化字段。 */
 export declare function ensureBuiltinAssets(assets: ProjectAssets | undefined, mode?: 'missing_only' | 'sync_existing'): ProjectAssets;
@@ -38,7 +36,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/assistant.d.ts

@@ -15,8 +15,33 @@
 import type { Context } from '@deepseek-ai/cordis';
 import type { AssistantMessage, NovelConfig, ProjectState } from './protocol.ts';
 import { chapterFileName } from './engine.ts';
+import { type BookStage } from './stage-contract.ts';
 /** History file name inside the output dir. */
 export declare const ASSISTANT_HISTORY_FILE = "novel-assistant.jsonl";
+/**
+ * 按阶段渲染动作说明书。
+ *
+ * - `strict=false`（作者点明了要做什么）：全量说明书照给，只靠动作可见性段提示
+ *   哪些属于阶段外——作者有权指定任意动作。
+ * - `strict=true`（作者只说「继续/下一步」）：阶段外的写操作说明书直接**从提示词里移除**，
+ *   和执行层的阶段白名单完全一致，模型不再有机会去试错撞守卫。
+ *
+ * @param docs 动作说明书行。
+ * @param stage 阶段契约。
+ * @param strict 是否为「阶段即唯一命令」模式。
+ * @returns 裁剪后的说明书行。
+ */
+export declare function renderToolDocs(docs: readonly string[], stage: BookStage, strict: boolean): string[];
+/**
+ * 渲染「动作可见性」：把写操作分成「本阶段可用」与「阶段外（仅作者点名时执行）」，
+ * 让模型不必靠试错去发现哪些动作会被拒绝。
+ *
+ * @param stage 阶段契约。
+ * @returns 多行文本。
+ */
+export declare function renderActionVisibility(stage: BookStage): string;
+export { classifyActionError, actionRetryLimit, safeArgsKey, NovelActionError, FailureLedger } from './action-guard.ts';
+export type { ActionErrorKind } from './action-guard.ts';
 /** Load the persisted conversation (empty when none). */
 export declare function loadAssistantHistory(outputDir: string): AssistantMessage[];
 /** 清空助手对话记录（删除历史文件）。 */

package/lib/types/author-assets.d.ts

@@ -1,6 +1,6 @@
 /**
  * 作者资产库/总数据（跨书）— 按作者维度聚合的可复用资产。
- * 与书架同惯例持久化到 ~/.dsh/dsh-novel-forge-author-assets.json。
+ * 与书架同惯例持久化到 <DSH_HOME>/dsh-novel-forge-author-assets.json。
  * 提供读取/持久化/新增或更新/删除，以及「导入默认」：把书架书的写作资产/角色 +
  * 内置全局库（题材/反AI规则/风格模板/推进模式）批量沉淀成资产条目（默认库）。
  */
@@ -11,8 +11,6 @@ export declare function authorAssetsFile(): string;
 export declare function loadAuthorAssets(): AuthorAssetLibrary;
 /** 持久化作者资产库。 */
 export declare function saveAuthorAssets(library: AuthorAssetLibrary): void;
-/** 新建一条资产（自动生成 id 与时间戳）。 */
-export declare function createAuthorAsset(input: Omit<AuthorStyleAsset, 'id' | 'createdAt' | 'updatedAt'>): AuthorStyleAsset;
 /** 按 id 更新一条资产；不存在则追加。 */
 export declare function upsertAuthorAsset(input: AuthorStyleAsset): AuthorAssetLibrary;
 /** 删除一条资产；返回更新后的资产库。 */

package/lib/types/bookshelf.d.ts

@@ -1,6 +1,6 @@
 /**
  * 书架（Bookshelf）— 多书管理：一本书记录一个独立输出目录。
- * 状态持久化到 ~/.dsh/dsh-novel-forge-bookshelf.json（跟随 dsh 配置惯例）。
+ * 状态持久化到 <DSH_HOME>/dsh-novel-forge-bookshelf.json（跟随 dsh 配置惯例）。
  */
 import type { BookEntry, BookshelfSnapshot } from './protocol.ts';
 /** 书架配置文件路径。 */
@@ -37,6 +37,16 @@ export declare function activateBook(id: string): BookEntry | undefined;
 export declare function removeBook(id: string): boolean;
 /** 当前书输出目录（无书架则 undefined，回退 settings）。 */
 export declare function activeBookOutputDir(): string | undefined;
-/** 默认输出目录推断：~/.dsh/novels/书名。 */
-export declare function defaultOutputDirFor(bookName: string): string;
+/**
+ * 书目录重指向：把 outputDir 等于 from 的书条目全部改为 to（目录迁移联动）。
+ * @returns 重指向的条目数。
+ */
+export declare function repointBookDirs(from: string, to: string): number;
+/**
+ * 新书默认输出目录：`<配置的输出目录>/书名`；未配置时回退 `<DSH_HOME>/novels/书名`。
+ * @param bookName - 书名（剔除文件系统非法字符并截断到 40 字）。
+ * @param baseDir - settings 里配置的输出目录（未经激活书合并的原始值）。
+ * @returns 该书应写入的绝对目录。
+ */
+export declare function defaultOutputDirFor(bookName: string, baseDir?: string): string;
 export {};

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 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 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);
@@ -19,14 +19,6 @@ export declare class NovelApi {
     }>;
     /** 反推大纲：从已写章节正文反向生成全书总纲（NDJSON 流）。 */
     outlineReverse(onFrame: (frame: JobFrame) => void): Promise<void>;
-    /** 分镜·导演级：骨架 → 分镜表（镜头级）。 */
-    storyboardTable(chapterNo: number, skeleton: import('../protocol.ts').StoryboardSkeleton, styleId?: string, filterId?: string): Promise<import('../protocol.ts').StoryboardTableResponse>;
-    /** 漫剧方案管理：create / remove / activate。 */
-    manhuaPlans(req: import('../protocol.ts').MangaPlansRequest): Promise<import('../protocol.ts').MangaPlansResponse>;
-    /** 分镜·提示词级：分镜表 → 即梦可粘贴视频提示词。 */
-    storyboardPrompts(chapterNo: number, table: import('../protocol.ts').StoryboardTable, styleId?: string, filterId?: string): Promise<import('../protocol.ts').StoryboardPromptsResponse>;
-    /** 分镜·编剧级：单章 → 剧情骨架（节拍链）。 */
-    storyboardSkeleton(chapterNo: number): Promise<import('../protocol.ts').StoryboardSkeletonResponse>;
     /** 开书想法 → AI 大纲：生成 count 个方案（换批时传 exclude 避开已暂留方向）。 */
     outlineSuggest(idea: string, count?: number, exclude?: string[]): Promise<import('../protocol.ts').OutlineSuggestResponse>;
     /** 拆书分析：对已写章节做结构/人物/文风/卖点体检。 */
@@ -41,17 +33,30 @@ 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<{
         report: ReviewReport;
     }>;
+    /**
+     * 修订指令合并：把本章的审稿意见（勾选项）+ 时间线矛盾 + 张力偏差合成**一份**指令。
+     * 面板所有「按意见修订 / 一键按建议修订」入口都先走这里，保证同一章只改一轮。
+     */
+    revisionPlan(no: number, reviewIssues?: ReviewReport['issues'], opts?: {
+        includeTimeline?: boolean;
+        includeTension?: boolean;
+    }): Promise<RevisionPlanResponse>;
     /** 保存手动编辑的正文（自动备份 .bak；带报告则沿用落盘，否则保存后自动审稿）。 */
     chapterSave(no: number, text: string, report?: ReviewReport): Promise<import('../protocol.ts').ChapterSaveResponse>;
     patchConfig(patch: ConfigPatch): Promise<{
         config: NovelConfig;
+        settingsWarning?: string;
     }>;
+    /** 输出目录迁移：dryRun=true 仅预览目录内容；确认时传 to 搬迁。 */
+    moveOutputDir(to?: string, dryRun?: boolean): Promise<import('../protocol.ts').MoveOutputDirResponse>;
+    /** 本书参数：不带 patch 读取；带 patch 合并保存（字段传 null = 回退全局）。 */
+    bookSettings(patch?: Record<string, unknown>): Promise<import('../protocol.ts').BookSettingsResponse>;
     openFolder(): Promise<void>;
     /** 插件自更新：在 DSH profile 目录拉取最新 npm 版（需重启 DSH 生效）。 */
     pluginUpdate(): Promise<PluginUpdateResponse>;
@@ -122,11 +127,11 @@ export declare class NovelApi {
     }): Promise<{
         result: import('../protocol.ts').IdeaInspirationResult;
     }>;
-    /** 自动导演编排建议：基于全书上下文。 */
+    /** 自动编辑编排建议：基于全书上下文。 */
     director(focus?: string): Promise<{
         result: import('../protocol.ts').DirectorAdvice;
     }>;
-    /** 自动导演「采纳」出的书内待办：读取。 */
+    /** 自动编辑「采纳」出的书内待办：读取。 */
     directorTodosList(): Promise<{
         todos: import('../protocol.ts').DirectorTodo[];
     }>;
@@ -188,8 +193,6 @@ export declare class NovelApi {
         ok: boolean;
         no: number;
     }>;
-    /** 角色库：AI 提炼 / 采纳 / 更新 / 删除。 */
-    imageTest(req: import('../protocol.ts').ImageTestRequest): Promise<import('../protocol.ts').ImageTestResponse>;
     /** 对选中的提供商/模型发一次最小真实调用，验证连通性。 */
     llmTest(provider: string, model: string): Promise<LlmTestResponse>;
     /** 添加模型：厂商直填 key，或自定义 OpenAI 兼容路由（写 DSH 凭据 + 注册路由）。 */
@@ -203,20 +206,7 @@ export declare class NovelApi {
     /** 移除一个提供方（unset key + 移除 llm-pi-ai 路由）。 */
     removeProvider(req: RemoveProviderRequest): Promise<RemoveProviderResponse>;
     roles(req: import('../protocol.ts').RolesRequest): Promise<import('../protocol.ts').RolesResponse>;
-    /** 漫剧角色库：从分镜提名 / 建卡 / 更新 / 删除 / 形象锚点 / 精修提示词。 */
-    mangaRoles(req: import('../protocol.ts').MangaRolesRequest): Promise<import('../protocol.ts').MangaRolesResponse>;
-    /** 导出「即梦素材包」落盘到资产库 manga-assets/素材包/。 */
-    exportPackage(chapterNo: number, title: string, markdown: string): Promise<{
-        ok: boolean;
-        file: string;
-    }>;
-    /** 场景库：AI 提炼 / 采纳 / 更新 / 删除 / 图集。 */
-    scenes(req: import('../protocol.ts').ScenesRequest): Promise<import('../protocol.ts').ScenesResponse>;
-    /** 视觉世界观规则：提炼 / 保存。 */
-    visualRules(req: import('../protocol.ts').VisualRulesRequest): Promise<import('../protocol.ts').VisualRulesResponse>;
-    /** 道具库：从已写章节提炼常驻道具 / 保存清单。 */
-    mangaProps(req: import('../protocol.ts').MangaPropsRequest): Promise<import('../protocol.ts').MangaPropsResponse>;
-    /** 小说简介：AI 生成/补全（partial 留空 = 全量），或手动保存。 */
+    /** 小说简介：生成/补全（partial 留空 = 全量），或手动保存。 */
     blurb(action: 'generate' | 'save', text?: string, partial?: string): Promise<{
         blurb: string;
     }>;
@@ -231,7 +221,7 @@ export declare class NovelApi {
     rename(bookName: string): Promise<{
         bookName: string;
     }>;
-    /** 大世界：AI 提炼（generate）或手动保存（save）。 */
+    /** 大世界：提炼（generate）或手动保存（save）。 */
     world(action: 'generate' | 'save', world?: import('../protocol.ts').WorldState): Promise<{
         world: import('../protocol.ts').WorldState;
     }>;
@@ -288,6 +278,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/chip-prefs.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 右上角「小说工坊生成状态」芯片的显示偏好（纯客户端、localStorage）。
+ *
+ * 为什么是 localStorage 而不是插件配置：这是纯界面 chrome，与显示模式 / 界面密度 /
+ * 编辑器字号 / 芯片自身的位置记忆同类；哪个浏览器想清屏就哪个浏览器清，不需要跨端同步。
+ * 将来若要跨端，把键名沿用成 config 字段 `showRunChip` 即可平滑升级。
+ *
+ * 三态：
+ *   off    关闭（同时停止 4 秒轮询，不白跑）
+ *   active 只在生产单**运行中或已暂停**时显示（不想错过生成，也不想留残影）
+ *   always 只要该目录有生产单状态就显示（默认，保持历史行为）
+ */
+import type { RunState } from '../protocol.ts';
+export type RunChipMode = 'off' | 'active' | 'always';
+/** localStorage 键（与芯片位置记忆同一命名空间）。 */
+export declare const RUN_CHIP_MODE_KEY = "dsh-novel-forge.runChip.mode";
+/** 同页变更通知用的自定义事件名（跨标签页走原生 storage 事件）。 */
+export declare const RUN_CHIP_MODE_EVENT = "dsh-novel-forge:runchip-mode";
+/** 默认值与历史行为一致：有生产单状态就显示。 */
+export declare const DEFAULT_RUN_CHIP_MODE: RunChipMode;
+/** 设置页下拉用的三态选项（顺序即用户看到的顺序）。 */
+export declare const RUN_CHIP_MODE_OPTIONS: ReadonlyArray<{
+    value: RunChipMode;
+    label: string;
+}>;
+/** 读取偏好（缺失 / 非法 / 存储不可用 → 默认值）。 */
+export declare function readRunChipMode(): RunChipMode;
+/** 写入偏好并通知所有监听者；存储不可用时仍通知（本次会话内生效）。 */
+export declare function writeRunChipMode(mode: RunChipMode): void;
+/** 订阅偏好变化（同页 + 跨标签页 storage）；返回退订函数。 */
+export declare function subscribeRunChipMode(listener: (mode: RunChipMode) => void): () => void;
+/**
+ * 给定偏好与当前生产单状态，判断芯片是否应可见。
+ * null（没有生产单状态）永远不显示——这是渲染层与测试共用的唯一判据。
+ */
+export declare function isRunChipVisible(mode: RunChipMode, state: RunState | null | undefined): boolean;

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

@@ -8,8 +8,8 @@
  * the Node build (esm/index.mjs), which calls module.createRequire() for the
  * optional worker_threads path — inlining that into the browser bundle leaves
  * a bare require("module") the client-modules table cannot answer.
+ *
+ * XML 解析共享核心在 ../docx-core.ts（与服务端同源）。
  */
 /** Extract plain text from a docx buffer: one line per <w:p> paragraph. */
 export declare function extractDocxTextFromBuffer(buffer: ArrayBuffer | Uint8Array): string;
-/** Read a File as ArrayBuffer. */
-export declare function readFileAsArrayBuffer(file: File): Promise<ArrayBuffer>;

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;