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

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

@@ -28,9 +28,3 @@ export interface AiScanResult {
     summary: string;
 }
 export declare function scanAiFlavor(text: string): AiScanResult;
-/** 扫描前后对比（润色时用） */
-export declare function compareAiScan(before: AiScanResult, after: AiScanResult): {
-    improved: boolean;
-    deltaScore: number;
-    details: string[];
-};

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;

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

@@ -1,57 +1,36 @@
 /**
- * dsh-novel-forge — locale dictionaries (zh / en).
+ * dsh-novel-forge — 面板文案词典（简体中文单语）。
+ *
+ * 定位说明：小说工坊面板是**中文单语界面**——这里就是全部用户可见文案的唯一定义处，
+ * 键位即类型（`NovelKey`），新增文案请同时在此登记，不要散落到组件里硬编码。
+ * 文档层（README / docs / CHANGELOG）仍提供英文对照，那是给人读的，不是界面语言。
  */
-/** zh dictionary. */
+/** 面板文案（简体中文）。 */
 export declare const zh: {
     readonly 'entry.label': "小说工坊";
     readonly 'entry.tooltip': "AI 编译小说工作台：总纲 → 道藏 → 卷计划 → 章节计划 → 逐章生成+审稿";
-    readonly 'panel.title': "小说工坊";
     readonly 'common.close': "关闭";
     readonly 'common.loading': "加载中…";
-    readonly 'common.save': "保存";
     readonly 'common.error': "错误";
-    readonly 'common.success': "成功";
-    readonly 'common.generating': "生成中…";
     readonly 'common.chars': "字";
     readonly 'tab.workflow': "工作台";
     readonly 'tab.overview': "总纲";
     readonly 'tab.plan': "章节";
-    readonly 'tab.bible': "道藏";
-    readonly 'tab.foreshadow': "暗线";
     readonly 'tab.assistant': "AI 编辑 Agent";
     readonly 'tab.settings': "设置";
-    readonly 'workflow.title': "创作工作台";
-    readonly 'workflow.step1': "① 加载总纲";
-    readonly 'workflow.step2': "② 提炼道藏";
-    readonly 'workflow.step3': "③ 规划卷";
-    readonly 'workflow.step4': "④ 生成章节计划";
-    readonly 'workflow.step5': "⑤ 逐章写作 + AI 审稿";
-    readonly 'workflow.step6': "⑥ 润色 / 导出";
-    readonly 'workflow.loadOutline': "读取总纲";
-    readonly 'workflow.genBible': "提炼道藏";
     readonly 'workflow.genVolumes': "生成卷计划";
-    readonly 'workflow.genPlan': "生成章节计划";
-    readonly 'workflow.done': "已完成";
-    readonly 'workflow.todo': "待办";
     readonly 'workflow.bibleDone': "道藏已生成（{n} 条规则 / {c} 个人物 / {r} 条红线）";
     readonly 'workflow.volumesDone': "卷计划已生成（{n} 卷）";
     readonly 'workflow.planDone': "章节计划已生成（{n} 章）";
-    readonly 'workflow.progress': "进度：总纲 ✓ · 道藏 {bible} · 卷 {volumes} · 计划 {plan} · 已完成 {done}/{total} 章";
-    readonly 'overview.loadDocx': "从 docx 读取总纲";
-    readonly 'overview.loadDocxDefault': "读取默认总纲";
     readonly 'overview.loadingOutline': "正在解析 docx…";
     readonly 'overview.outlineHint': "总纲文本（可编辑）";
     readonly 'overview.outlineChars': "总纲字数";
     readonly 'overview.saveOutline': "保存总纲";
     readonly 'overview.saved': "总纲已保存";
     readonly 'overview.bookName': "书名";
-    readonly 'overview.loadCustom': "指定 docx 路径";
-    readonly 'overview.loadCustomHint': "绝对路径，留空使用默认";
     readonly 'plan.generate': "生成章节计划";
     readonly 'plan.generateHint': "章节数量";
     readonly 'plan.count': "章";
-    readonly 'plan.empty': "暂无章节计划，请先生成";
-    readonly 'plan.chapter': "章";
     readonly 'plan.pending': "待生成";
     readonly 'plan.generating': "生成中";
     readonly 'plan.written': "待审稿";
@@ -63,23 +42,17 @@ export declare const zh: {
     readonly 'plan.rewrite': "修订";
     readonly 'plan.review': "审稿";
     readonly 'plan.polish': "去AI味";
-    readonly 'plan.writeAll': "批量生成全部";
     readonly 'plan.writeAllPending': "批量生成剩余";
-    readonly 'plan.generated': "已生成";
-    readonly 'plan.progress': "进度";
     readonly 'plan.beats': "剧情要点";
     readonly 'plan.reviewReport': "审稿报告";
     readonly 'plan.reviewScore': "评分";
     readonly 'plan.reviewVerdict': "总评";
-    readonly 'plan.reviewIssues': "问题清单";
     readonly 'plan.reviewPass': "通过";
     readonly 'plan.reviewFail': "未通过";
-    readonly 'plan.approve': "手动通过";
     readonly 'plan.summary': "章节摘要";
     readonly 'plan.volumes': "卷";
-    readonly 'plan.noVolume': "未分卷";
     readonly 'bible.title': "道藏";
-    readonly 'bible.gen': "AI 提炼道藏";
+    readonly 'bible.gen': "提炼道藏";
     readonly 'bible.genre': "题材基调";
     readonly 'bible.worldRules': "世界规则";
     readonly 'bible.characters': "人物志";
@@ -87,9 +60,8 @@ export declare const zh: {
     readonly 'bible.style': "风格要求";
     readonly 'bible.none': "尚未生成道藏。生成后写作会严格遵守人设与金手指规则，审稿也会按红线检查。";
     readonly 'foreshadow.title': "暗线管理";
-    readonly 'foreshadow.suggest': "AI 建议暗线";
+    readonly 'foreshadow.suggest': "建议暗线";
     readonly 'foreshadow.none': "暂无暗线";
-    readonly 'foreshadow.status': "状态";
     readonly 'foreshadow.planned': "计划中";
     readonly 'foreshadow.planted': "已埋设";
     readonly 'foreshadow.progressing': "推进中";
@@ -99,7 +71,6 @@ export declare const zh: {
     readonly 'foreshadow.plantedAt': "埋设于";
     readonly 'foreshadow.setPlanted': "标记已埋设";
     readonly 'foreshadow.setResolved': "标记已回收";
-    readonly 'tab.facts': "编年录";
     readonly 'tab.plotlines': "剧情线";
     readonly 'plotlines.hint': "主线/支线/人物线/悬念线的推进管理：章节生成时会注入未完结的线，要求每章至少推进一条；关联章节记录推进节点。";
     readonly 'plotlines.empty': "还没有剧情线——长篇小说建议先建主线与几条支线。";
@@ -121,23 +92,16 @@ export declare const zh: {
     readonly 'plotlines.cancel': "取消";
     readonly 'plotlines.edit': "编辑";
     readonly 'plotlines.remove': "删除";
-    readonly 'plotlines.linkChapter': "关联本章";
     readonly 'plotlines.chapters': "已关联";
-    readonly 'plotlines.workflowTitle': "剧情线进度";
-    readonly 'plotlines.workflowEmpty': "未建剧情线（去「剧情线」页创建）";
-    readonly 'sensitive.title': "敏感词检查";
-    readonly 'sensitive.scanAll': "🔞 全书敏感词检查";
+    readonly 'sensitive.scanAll': " 全书敏感词检查";
     readonly 'sensitive.hint': "内置违禁词库硬匹配（政治/擦边/暴力/辱骂/广告/其他），发布前建议检查；只做提示，是否修改由你判断。";
-    readonly 'sensitive.clean': "✅ 未命中任何违禁词（扫描 {n} 章）";
+    readonly 'sensitive.clean': " 未命中任何违禁词（扫描 {n} 章）";
     readonly 'sensitive.hits': "命中 {n} 处（{chapters} 章受影响）";
     readonly 'sensitive.goFix': "去修订";
     readonly 'sensitive.fixPrefill': "请删除或替换正文中的违禁表达「{word}」（类别：{category}），用含蓄/间接的写法替代。";
     readonly 'facts.title': "编年录 / 时间线（{n} 条）";
     readonly 'facts.hint': "每章生成后自动抽取「已确立事实」（人物状态/境界资源/关系变化/伏笔落地），最近 20 条注入后续章节生成，保证长期一致。";
     readonly 'facts.backfill': "回填历史章节事实";
-    readonly 'facts.backfilled': "已从历史章节回填 {n} 条事实";
-    readonly 'settings.title': "设置";
-    readonly 'settings.outlinePath': "默认大纲路径";
     readonly 'settings.outputDir': "输出目录";
     readonly 'settings.provider': "模型提供商";
     readonly 'settings.model': "模型";
@@ -146,13 +110,7 @@ export declare const zh: {
     readonly 'settings.edit': "编辑";
     readonly 'settings.delete': "删除";
     readonly 'settings.modelCustomPlaceholder': "输入任意模型 id";
-    readonly 'settings.savedModels': "我的模型";
-    readonly 'settings.modelCards': "模型卡片（内置 + 已添加）";
-    readonly 'settings.savedModelName': "名称";
-    readonly 'settings.addModel': "添加模型";
-    readonly 'settings.catalogRefresh': "刷新厂商";
     readonly 'settings.refreshModels': "刷新模型";
-    readonly 'settings.savedModelsHint': "手动添加常用模型（provider + 模型 id），点击即可切换当前模型；厂商模式会写入 DSH 凭据并注册路由。";
     readonly 'settings.testConnection': "测试连通";
     readonly 'settings.testRunning': "测试中";
     readonly 'settings.testOk': "连通";
@@ -167,15 +125,9 @@ export declare const zh: {
     readonly 'settings.reasoning.low': "low · 低思考";
     readonly 'settings.reasoning.high': "high · 高思考";
     readonly 'settings.reasoning.max': "max · 最高思考（质检/推演）";
-    readonly 'settings.theme': "主题";
-    readonly 'settings.themeLiquid': "iOS 液态玻璃（绿）";
-    readonly 'settings.themeNeumorph': "新拟物（双阴影）";
-    readonly 'settings.themeHint': "存于浏览器本地，即时生效";
     readonly 'settings.chapterChars': "每章目标字数";
     readonly 'settings.maxTokens': "单章最大输出 tokens";
     readonly 'settings.reviewPassScore': "审稿通过分数（0-100）";
-    readonly 'settings.editorFontSize': "编辑器字号（仅编辑页显示）";
-    readonly 'settings.editorFontSizeHint': "存于浏览器本地，不影响其他设备";
     readonly 'settings.autoReview': "生成后自动审稿";
     readonly 'settings.autoAuthorReview': "生成后自动作者复盘";
     readonly 'settings.autoAuthorReviewHint': "复盘钩子兑现/结尾钩子/剧情线推进/连续性/节奏趋势，每章约 2000 token";
@@ -183,8 +135,8 @@ export declare const zh: {
     readonly 'settings.autoReviewAfterReviseHint': "按意见修订/润色产出草稿后自动附带一次 AI 审查，直接显示新稿评分与剩余问题（每章约 2-3k token，可关）";
     readonly 'settings.save': "保存设置";
     readonly 'settings.saved': "设置已保存";
+    readonly 'settings.savedUnpersisted': "设置已生效，但未能持久化（宿主未登记本插件的配置段），重启后会回到原值。";
     readonly 'settings.openFolder': "打开输出文件夹";
-    readonly 'settings.export': "导出";
     readonly 'settings.exportTxt': "导出 TXT";
     readonly 'settings.exportMd': "导出 Markdown";
     readonly 'settings.exported': "已导出：{file}（{chars} 字，{chapters} 章）";
@@ -194,19 +146,12 @@ export declare const zh: {
     readonly 'progress.error': "第 {no} 章失败：{message}";
     readonly 'progress.rewriting': "正在修订第 {no} 章…";
     readonly 'progress.polishing': "正在润色第 {no} 章…";
-    readonly 'progress.empty': "生成/审稿进度将显示在这里";
     readonly 'assistant.hint': "和 AI 编辑 Agent 讨论剧情、人设、暗线；达成一致后可让它直接修改总纲、道藏、章节内容。";
     readonly 'assistant.placeholder': "例如：我想让第 2 章结尾加一个悬念——墟境里传来爷爷的声音…";
     readonly 'assistant.send': "发送";
-    readonly 'assistant.toolStart': "⚙ 执行操作：{name}…";
-    readonly 'assistant.toolDone': "✓ {name} 完成：{detail}";
-    readonly 'assistant.toolError': "✗ {name} 失败：{detail}";
     readonly 'assistant.empty': "还没有对话。和 AI 编辑 Agent 聊聊剧情吧。";
     readonly 'status.projectNone': "输出目录中还没有项目。请先加载大纲。";
     readonly 'status.files': "已生成文件";
-    readonly 'api.error': "请求失败";
 };
-/** en dictionary (fallback). */
-export declare const en: Record<string, string>;
-/** Keys type for the zh dictionary. */
+/** 面板文案键位（= zh 词典的键）。 */
 export type NovelKey = keyof typeof zh;

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

@@ -1,7 +1,5 @@
 import type { NovelApi } from './api.ts';
 import type { PanelController } from './panel/controller.ts';
-/** The injected panel container. */
-export declare const PANEL_VIEW_SELECTOR = "[data-dsh-novelforge-view]";
 /**
  * Mount the panel React tree into the center column and bind visibility to
  * the controller.