@waterwx/dsh-novel-forge 2.0.0-alpha.1 → 2.0.0

package/lib/types/revision.d.ts

@@ -0,0 +1,76 @@
+/**
+ * 修订指令合并层（arbitration）。
+ *
+ * 问题：审稿、时间线、张力三条通道各自给建议，如果各自改一轮，会出现「改完 A 又违反 B」
+ * 的互相打脸：同一章可能被改三遍，最后一轮的改动把第一轮的修正覆盖掉。
+ *
+ * 规则（与面板/生产单共享同一份实现，避免两头各写一套）：
+ *  1. 同一章只交付**一份**修订指令（本模块负责汇总，调用方不得自行拼装）。
+ *  2. 固定优先级，不做权重打分（可解释、可复现）：
+ *       0 审稿 high（必改，是硬门）
+ *       1 时间线 high（硬矛盾：时间倒流、地点瞬移）
+ *       2 张力 medium（曲线偏差，建议性最强）
+ *       3 其余（审稿 medium / 时间线 medium）
+ *       4 低优先（审稿 low）
+ *  3. 一次修订最多吃 REVISION_ITEM_CAP 条，超出按优先级截断；截断数量显式回传，不静默丢弃。
+ *  4. 每章修订轮次上限 MAX_REVISION_ROUNDS，超出转人工待办。
+ *  5. 验证基准 = 本轮实际下发的全部条目（审稿 + 时间线 + 张力），
+ *     这样「复核」核对的就是「我们要求改的东西」，而不是只核对审稿那部分。
+ */
+import type { ProjectState, ReviewIssue, ReviewReport, RevisionItem, RevisionSource, Severity } from './protocol.js';
+/** 每章修订轮次上限：两轮仍不过即转人工，不做「无限自动修改」。 */
+export declare const MAX_REVISION_ROUNDS = 2;
+/** 单次修订指令最多携带的条目数（防止指令过长把正文挤出上下文）。 */
+export declare const REVISION_ITEM_CAP = 8;
+export declare const REVISION_SOURCE_LABELS: Record<RevisionSource, string>;
+/** 固定优先级：数值越小越先改。 */
+export declare function revisionPriority(source: RevisionSource, severity: Severity): number;
+/** 排序 + 去重 + 截断。去重时保留优先级更高的那条，并累加 count。 */
+export declare function mergeRevisionItems(items: RevisionItem[], cap?: number): {
+    items: RevisionItem[];
+    omitted: number;
+};
+export interface RevisionCollectOptions {
+    /** 目标章；缺省表示全书（用于整本批量修订）。 */
+    chapterNo?: number;
+    /** 显式指定的审稿意见；缺省取该章已落盘的审稿报告。 */
+    reviewIssues?: ReviewIssue[];
+    /** 是否纳入时间线矛盾（默认纳入）。 */
+    includeTimeline?: boolean;
+    /** 是否纳入张力偏差（默认纳入）。 */
+    includeTension?: boolean;
+}
+/** 汇总一章（或全书）的三类建议。纯函数，不改项目状态。 */
+export declare function collectRevisionItems(project: ProjectState, options?: RevisionCollectOptions): RevisionItem[];
+export interface RevisionPlan {
+    /** 已排序、去重、截断后的条目。 */
+    items: RevisionItem[];
+    /** 下发给模型的修订指令（唯一入口，调用方不要自行拼装）。 */
+    instruction: string;
+    counts: Record<RevisionSource, number>;
+    /** 因超出上限被截断的条数（显式回传，便于提示作者）。 */
+    omitted: number;
+    /** 验证基准：把本轮下发的全部条目当作「上一轮意见」，复核时逐条核对。 */
+    baseline: ReviewReport;
+}
+export interface BuildRevisionPlanOptions extends RevisionCollectOptions {
+    /** 审稿基线报告（提供后 baseline 会保留其分数与时间）。 */
+    baseReport?: ReviewReport;
+    /** 指令抬头（默认「按合并建议修订」）。 */
+    title?: string;
+    cap?: number;
+}
+/** 渲染修订指令。格式与历史「按审稿意见修订」保持同族，模型无需重新学习。 */
+export declare function renderRevisionInstruction(items: RevisionItem[], title?: string): string;
+/**
+ * 构造验证基准：把时间线/张力条目转成「上一轮意见」的编号项，
+ * 与审稿意见合并成一份报告。复核模型据此逐条核对，避免
+ * 「审稿说已解决、时间线说没改」这类互相打架的判定。
+ */
+export declare function buildRevisionBaseline(items: RevisionItem[], base?: ReviewReport): ReviewReport;
+/** 汇总 → 排序 → 指令 → 基准。面板与生产单都走这里。 */
+export declare function buildRevisionPlan(project: ProjectState, options?: BuildRevisionPlanOptions): RevisionPlan;
+/** 一行摘要，用于日志与面板提示（"审稿 3 · 时间线 1 · 张力 1，另截断 2 条"）。 */
+export declare function describeRevisionPlan(plan: RevisionPlan): string;
+/** 待办文本（生产单只提示不阻塞时写入项目待办，供作者人工决定）。 */
+export declare function revisionTodoText(item: RevisionItem): string;

package/lib/types/routes.d.ts

@@ -9,15 +9,21 @@
  */
 import type { WebRoute } from '@deepseek-ai/dsh-host-webserver';
 import type { Context } from '@deepseek-ai/cordis';
-import { type BibleResponse, type ConfigPatch, type ExportResponse, type LoadOutlineResponse, type NovelConfig, type PlanResponse, type StatusResponse, type VolumesResponse } from './protocol.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. */
 export interface NovelRoutesDeps {
     ctx: Context;
     /** Resolve the live plugin config (settings-aware). */
     getConfig: () => NovelConfig;
-    /** Persist a config patch through the settings seam. */
-    patchConfig: (patch: ConfigPatch) => Promise<NovelConfig>;
+    /** Persist a config patch through the settings seam (memory fallback included). */
+    patchConfig: (patch: ConfigPatch) => Promise<ConfigResponse>;
+    /** Raw settings config（未与激活书合并）——目录迁移判断默认目录是否需同步用。 */
+    rawConfig?: () => {
+        outputDir?: string;
+    };
+    /** Loader entry id the settings section is addressed by (undefined when unknown). */
+    settingsNs?: string;
 }
 /**
  * Build every /api/dsh-novel-forge route.

package/lib/types/run.d.ts

@@ -1,5 +1,17 @@
 import type { Context } from '@deepseek-ai/cordis';
 import type { NovelConfig, RunState } from './protocol.ts';
+/**
+ * 解析某个输出目录的书名（用于旧 run-state.json 的兜底）。
+ * 优先项目文件里的 bookName，其次目录名——两者都没有时返回空串。
+ * @param outputDir - 该书输出目录。
+ */
+export declare function resolveRunBookName(outputDir: string): string;
+/**
+ * 一句话描述"正在跑的是哪本书的哪一章"。
+ * 面板状态行与 409 报错共用，避免两处各写各的（也便于单测覆盖）。
+ * @param state - 运行中的生产单状态。
+ */
+export declare function describeRunningBatch(state: RunState): string;
 export declare class ProductionRunner {
     private deps;
     private state;
@@ -17,13 +29,23 @@ export declare class ProductionRunner {
     private persist;
     private log;
     /** 启动/续跑生产单：startNo..endNo 区间，endNo 超出计划时先自动补计划。 */
-    start(startNo: number, endNo: number): Promise<RunState>;
+    start(startNo: number, endNo: number, runDir?: string): Promise<RunState>;
     pause(): void;
     resume(): void;
     stop(): void;
+    /** 是否有生产单正在执行（目录迁移等磁盘级操作前须为 false）。 */
+    isWorking(): boolean;
     /** 主循环：从 currentNo 扫描到 endNo，逐章处理；支持暂停/停止。 */
     private loop;
     private processChapter;
+    /**
+     * 出章即核对曲线（建议性，不阻塞）：
+     * 规则初筛得到的时间线矛盾 + 张力曲线偏差写进运行日志；本章已完结时再落成项目待办。
+     * 默认**不**触发任何自动修订——要看/要改由作者在面板发起「一键按建议修订」；
+     * 只有当本章因审稿 high 本来就要修订时，这些问题才搭同一轮车（见 handleRejected），
+     * 因此不额外增加轮次，也不会出现「改完甲又违反乙」。
+     */
+    private auditChapterAdvisories;
     /** 完整质量门：生成 → 摘要+事实 → 伏笔标记 → 审稿 → 作者复盘。 */
     private produce;
     /** 被拒分级处理：无 high 豁免；有 high 按意见修订（最多 2 轮）+ 验证模式；仍不过 → 待人工。 */

package/lib/types/settings-persist.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Config-patch persistence for the novel-forge plugin.
+ *
+ * Historically the plugin only knew how to write through the host settings
+ * service (`ctx.settings.update`) and treated the section's name as a constant.
+ * From Harness 0.2 the section is inferred from this plugin's exported `Config`
+ * and addressed by the **entry id** the Loader assigned — which the plugin does
+ * not control. A wrong id makes every save fail, so this module keeps the split
+ * explicit: apply the patch to the live config, then try to persist it, and
+ * report (rather than throw) when the host cannot.
+ */
+/** Minimal structural view of the host settings service this plugin touches. */
+export interface SettingsLike {
+    /** Persist one section patch; absent on hosts that expose read APIs only. */
+    update?: (ns: string, patch: Record<string, unknown>) => Promise<unknown>;
+    /** Live section registry; absence means the host cannot enumerate sections. */
+    describe?: () => unknown;
+}
+/** Where a config patch ended up. */
+export interface ConfigPersistResult {
+    /** The merged config (live in memory regardless of persistence). */
+    config: Record<string, unknown>;
+    /**
+     * Why persistence did not happen, when it did not. Callers surface this to the
+     * author: a save that silently evaporates on restart is worse than a loud one.
+     */
+    settingsWarning?: string;
+}
+/**
+ * The Loader entry id the settings section is addressed by.
+ * @param ctx - plugin context (structurally typed: only `fiber.entry.options.id` is read).
+ * @returns the entry id, or undefined when the host exposes none.
+ */
+export declare function novelSettingsNamespace(ctx: unknown): string | undefined;
+/**
+ * Pick the settings section to write through.
+ *
+ * The entry id is authoritative; the declared legacy name is used only when the
+ * host actually registered a section under it. Guessing an id is never allowed:
+ * a write to a wrong section would persist another plugin's config.
+ * @param settings - the settings service, when present.
+ * @param entryNs - entry id resolved from the context, when available.
+ * @param legacyNs - this plugin's declared section name (0.1.x wiring).
+ * @returns the section id to write to, or undefined when none is addressable.
+ */
+export declare function resolveSettingsTarget(settings: SettingsLike | undefined, entryNs: string | undefined, legacyNs: string): string | undefined;
+/**
+ * Merge one patch into the live config and persist it when the host allows.
+ *
+ * Never throws for a persistence failure: the edit is valid and already applied,
+ * so failing the request would lose it and misreport a working save as an error.
+ * @param current - the config as currently resolved.
+ * @param patch - the subset to merge (`undefined` values are ignored by callers).
+ * @param settings - the settings service, when present.
+ * @param entryNs - entry id resolved from the context, when available.
+ * @param legacyNs - this plugin's declared section name.
+ * @returns the merged config plus a warning when it could not be persisted.
+ */
+export declare function persistConfigPatch(current: Record<string, unknown>, patch: Record<string, unknown>, settings: SettingsLike | undefined, entryNs: string | undefined, legacyNs: string): Promise<ConfigPersistResult>;

package/lib/types/snapshots.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 章节历史版本（快照）：覆盖写入前自动留存正文，支持列表 / 回滚 / 清理。
+ *
+ * 为什么需要它：生成、按意见重写、去 AI 味润色、采纳草稿都会**覆盖** `第N章_*.md`，
+ * 一旦改差（尤其是自动修订把好稿改坏）就没有退路。这里在覆盖前把旧稿存到
+ * `<书目录>/snapshots/`，并维护一份 `snapshots/index.json` 索引。
+ *
+ * 纯 Node 文件操作，不依赖模型；路由层只做参数校验与响应。
+ */
+import type { ChapterPlan, ChapterSnapshot } from './protocol.ts';
+/** 快照目录名（书目录下）。 */
+export declare const SNAPSHOT_DIR = "snapshots";
+/** 每章默认保留的快照数（超出后按时间淘汰最旧的）。 */
+export declare const DEFAULT_SNAPSHOT_KEEP = 20;
+/** 快照目录绝对路径。 */
+export declare function snapshotDir(outputDir: string): string;
+/** 读取索引（缺失/损坏时返回空数组）。 */
+export declare function loadSnapshots(outputDir: string): ChapterSnapshot[];
+/** 快照占用字节数（索引 + 正文）。 */
+export declare function snapshotsBytes(outputDir: string): number;
+/**
+ * 为一个章节留存快照（覆盖写入前调用）。
+ *
+ * @param outputDir 书目录。
+ * @param chapter 章节（需要已存在正文文件）。
+ * @param reason 留存原因（生成覆盖 / 采纳草稿 / 修订 / 润色 / 手工）。
+ * @param keep 每章保留数量（超出淘汰最旧）。
+ * @returns 新建的快照；无正文文件时返回 undefined（不产生空快照）。
+ */
+export declare function createSnapshot(outputDir: string, chapter: ChapterPlan, reason: string, keep?: number): ChapterSnapshot | undefined;
+/**
+ * 回滚到某个快照：把快照内容写回章节正文文件。
+ *
+ * 回滚前会**先给当前正文留一份快照**（reason=回滚前自动留存），所以回滚本身也可撤销。
+ *
+ * @param outputDir 书目录。
+ * @param chapter 目标章节。
+ * @param snapshotId 快照 id。
+ * @returns 回滚后的字符数。
+ * @throws 快照不存在或章节无正文文件时抛错。
+ */
+export declare function restoreSnapshot(outputDir: string, chapter: ChapterPlan, snapshotId: string): number;
+/** 删除一个快照（连同文件）。 */
+export declare function removeSnapshot(outputDir: string, snapshotId: string): boolean;
+/** 按每章保留数量清理（连文件一起删）。 */
+export declare function pruneSnapshots(outputDir: string, keep?: number): number;

package/lib/types/stage-contract.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 阶段契约（Stage Contract）——宿主计算的「当前阶段 → 本轮允许的动作」。
+ *
+ * 设计来源（「作者请求中的当前阶段决定唯一允许命令」这一约定）：
+ * 允许的动作必须由宿主根据真实项目状态算出，而不是指望模型记住或自律。
+ * 宿主计算结果同时用于三处：
+ *   1) 注入助手系统提示词：模型知道自己在哪一步、下一步该做什么；
+ *   2) 通用续写指令（「继续 / 下一步」）下的写操作白名单强约束（阶段即唯一命令）；
+ *   3) 拒绝写操作时给出可执行的、阶段相关的理由，而不是一句「不允许」。
+ *
+ * 注意：作者显式点名的写操作永远优先于阶段白名单（作者终审权）；
+ * 阶段强约束只在作者没有指定具体对象（通用续写）时生效。
+ */
+import type { ChapterPlan, ProjectState, StageInfo } from './protocol.ts';
+/** 一个阶段契约（assistant 侧需要作为类型使用）。 */
+export type BookStage = StageInfo;
+/**
+ * 作者这一轮是否只说了「继续/下一步」这类没有具体对象的指令。
+ *
+ * @param message 本轮用户消息。
+ * @returns 是通用续写指令时为 true。
+ */
+export declare function isGenericContinue(message: string): boolean;
+/**
+ * 根据项目真实状态计算当前创作阶段。
+ *
+ * @param project 当前项目（未加载时为 undefined）。
+ * @returns 阶段契约（推荐动作 + 写操作白名单 + 判定理由）。
+ */
+export declare function computeBookStage(project: ProjectState | undefined): BookStage;
+/**
+ * 判断某写操作是否在当前阶段的允许白名单内。
+ *
+ * @param stage 阶段契约。
+ * @param tool 助手工具名。
+ * @returns 允许时为 true。
+ */
+export declare function stageAllows(stage: BookStage, tool: string): boolean;
+/**
+ * 按阶段把一组动作分成「本阶段可用」与「阶段外」。
+ *
+ * @param stage 阶段契约。
+ * @param tools 动作名列表（通常是写操作登记表）。
+ * @returns 两个保持输入顺序的子集。
+ */
+export declare function splitByStage(stage: BookStage, tools: readonly string[]): {
+    available: string[];
+    outside: string[];
+};
+/**
+ * 渲染阶段契约为可注入提示词的一段文字。
+ *
+ * @param stage 阶段契约。
+ * @returns 多行文本。
+ */
+export declare function renderStageContract(stage: BookStage): string;
+/** 汇总章节状态计数（供面板/提示词展示，避免各处重复统计）。 */
+export declare function summarizeChapters(chapters: ChapterPlan[]): Record<string, number>;

package/lib/types/tension.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 张力曲线：把「每章该有多紧」显式化，并在出章后核对实际走向。
+ *
+ * 为什么要有它：长篇最常见的两种崩法——**一直高能没有呼吸**（读者疲劳）与
+ * **长时间低位打转**（读者流失）；这两种都不是单章问题，而是"曲线"问题，
+ * 单章审稿看不见。这里提供：
+ *   1) 参考曲线（本项目自行设计，仅作形状参照）；
+ *   2) 把「本章目标张力」注入写作提示词；
+ *   3) 规则核对：实际 vs 目标偏差、连续同值、高潮后不回落、长期低位。
+ *
+ * 本模块只放纯逻辑（可离线单测）；模型交互与落盘在 engine/routes。
+ */
+import type { ChapterPlan, ProjectState, TensionCurvePreset, TensionIssue } from './protocol.ts';
+/** 单章张力的取值范围。 */
+export declare const TENSION_MIN = 0;
+export declare const TENSION_MAX = 100;
+/** 参考曲线的中文标签（面板展示）。 */
+export declare const TENSION_PRESET_LABELS: Record<TensionCurvePreset, string>;
+/** 全部可选预设（UI 下拉用）。 */
+export declare const TENSION_PRESETS: readonly TensionCurvePreset[];
+/** 把参考形状按章节数重采样（最近邻，保持形状不引入平滑失真）。 */
+export declare function referenceCurve(preset: TensionCurvePreset, chapterCount: number): number[];
+/** 读一章的目标张力（未设置时返回 undefined）。 */
+export declare function targetTension(chapter: ChapterPlan): number | undefined;
+/** 读一章的实际张力（审稿时模型打分，未设置时返回 undefined）。 */
+export declare function actualTension(chapter: ChapterPlan): number | undefined;
+/** 收敛到合法区间并取整。 */
+export declare function clampTension(value: number): number;
+/**
+ * 渲染注入写作提示词的「本章张力」块。
+ *
+ * @param project 项目状态。
+ * @param chapterNo 本章章号。
+ * @returns 提示词片段；没有张力信息时返回空串。
+ */
+export declare function renderTensionBlock(project: ProjectState, chapterNo: number): string;
+export declare function detectTensionIssues(project: ProjectState): TensionIssue[];
+/**
+ * 组装面板需要的曲线数据（章节号 / 目标 / 实际 / 参考）。
+ *
+ * @param project 项目状态。
+ * @returns 逐章数据点与预设名。
+ */
+export declare function buildCurveData(project: ProjectState): {
+    preset: TensionCurvePreset;
+    points: Array<{
+        no: number;
+        title: string;
+        target?: number;
+        actual?: number;
+        reference?: number;
+    }>;
+};

package/lib/types/timeline.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 故事时间线：把「章节正文」压成可排序的时间事件，用于后续章节的时间连续性。
+ *
+ * 与编年录的分工：编年录记「事实」（人物状态/资源/关系），时间线记「顺序」
+ * （什么时候、在哪里、谁在场、发生了什么），专门用来抓时间倒流、地点瞬移与
+ * 跨越章节的时序矛盾。
+ *
+ * 本模块只放纯逻辑（可离线单测）：排序、注入渲染、规则初筛、事件归一化；
+ * 模型交互（抽取/复核）在 engine.ts，落盘与路由在 routes.ts。
+ */
+import type { ProjectState, TimelineEvent, TimelineIssue } from './protocol.ts';
+/** 注入后续章节的时间线锚点条数（超过则显式声明省略，遵循截断显式化规则）。 */
+export declare const TIMELINE_CONTEXT_LIMIT = 12;
+/** 归一化事件（清洗字符串、补 id/时间戳）。 */
+export declare function normalizeTimelineEvent(raw: Partial<TimelineEvent>, chapterNo: number, index: number, now?: string): TimelineEvent;
+/** 时间线排序：先章节、再 order（缺省排在该章末尾）、最后 createdAt。 */
+export declare function sortTimeline(events: readonly TimelineEvent[]): TimelineEvent[];
+/**
+ * 渲染注入到「写作/规划」提示词的时间线锚点块。
+ *
+ * @param project 项目状态。
+ * @param beforeChapter 只注入该章之前的锚点（含该章本身不注入，避免剧透）。
+ * @returns 提示词片段（无事件时返回空串）。带显式截断声明。
+ */
+export declare function renderTimelineBlock(project: ProjectState, beforeChapter: number): string;
+/**
+ * 规则初筛时间线矛盾（不调模型，瞬时计算）。
+ *
+ * 覆盖三类最容易犯又最容易用规则抓到的错：
+ *   1) 同一章内事件顺序号倒退；
+ *   2) 全书顺序号在章节推进后倒退（时间倒流）；
+ *   3) 相邻两章之间地点瞬移（同一角色在未交代移动的情况下跨地点）。
+ *
+ * @param project 项目状态。
+ * @returns 问题清单（可能为空）。
+ */
+export declare function detectTimelineIssues(project: ProjectState): TimelineIssue[];

package/package.json

@@ -1,8 +1,32 @@
 {
   "name": "@waterwx/dsh-novel-forge",
-  "description": "AI 编译小说工作台 for the dsh web GUI: import a novel outline (docx/text), plan chapters with LLM, generate chapter by chapter (3000-4000 chars each), and save every chapter as Markdown into your chosen output folder.",
-  "version": "2.0.0-alpha.1",
+  "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.0.0",
   "type": "module",
+  "author": "waterwx",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/watersxya/dsh-novel-forge.git"
+  },
+  "homepage": "https://github.com/watersxya/dsh-novel-forge",
+  "bugs": {
+    "url": "https://github.com/watersxya/dsh-novel-forge/issues"
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "小说工坊",
+    "novel-forge",
+    "novel-writing-workbench",
+    "novel-writing",
+    "写作助手",
+    "小说创作",
+    "网文写作",
+    "章节生成",
+    "AI审稿",
+    "story-writing"
+  ],
   "engines": {
     "node": "^22.19.0 || >=24.0.0"
   },
@@ -38,31 +62,31 @@
     "schemastery": "^3.18.0"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh-client-connection": "^0.1.2-alpha.3",
-    "@deepseek-ai/dsh-client-locale": "^0.1.2-alpha.3",
-    "@deepseek-ai/dsh-client-ui-settings": "^0.1.2-alpha.3",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.2-alpha.3",
-    "@deepseek-ai/dsh-host-webserver": "^0.1.2-alpha.3",
-    "@deepseek-ai/dsh-llm": "^0.1.2-alpha.3",
-    "@deepseek-ai/dsh-settings": "^0.1.2-alpha.3",
-    "@deepseek-ai/dsh-skill": "^0.1.2-alpha.3",
-    "@deepseek-ai/dsh-system-prompt": "^0.1.2-alpha.3",
-    "@deepseek-ai/dsh-tools": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-client-connection": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-locale": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-host-webserver": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-llm": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-settings": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-skill": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-system-prompt": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-tools": "^0.2.0-rc.2",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-client-connection": "^0.1.2-alpha.3",
-    "@deepseek-ai/dsh-client-locale": "^0.1.2-alpha.3",
-    "@deepseek-ai/dsh-client-ui-settings": "^0.1.2-alpha.3",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.2-alpha.3",
-    "@deepseek-ai/dsh-host-webserver": "^0.1.2-alpha.3",
-    "@deepseek-ai/dsh-llm": "^0.1.2-alpha.3",
-    "@deepseek-ai/dsh-settings": "^0.1.2-alpha.3",
-    "@deepseek-ai/dsh-skill": "^0.1.2-alpha.3",
-    "@deepseek-ai/dsh-system-prompt": "^0.1.2-alpha.3",
-    "@deepseek-ai/dsh-tools": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-client-connection": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-client-locale": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-client-ui-settings": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-client-ui-slots": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-host-webserver": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-llm": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-settings": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-skill": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-system-prompt": "0.1.2-alpha.3",
+    "@deepseek-ai/dsh-tools": "0.1.2-alpha.3",
     "@types/node": "^22.20.0",
     "@types/react": "~18.3.1",
     "@types/react-dom": "^18.3.5",
@@ -77,8 +101,6 @@
     "lib/**/*.js",
     "lib/**/*.d.ts",
     "src",
-    "assets/styles",
-    "skills",
     "scripts/patch-schemastery.mjs",
     "cordis.patch.yml",
     "README.md"
@@ -86,11 +108,14 @@
   "license": "Apache-2.0",
   "scripts": {
     "postinstall": "node scripts/patch-schemastery.mjs",
-    "build": "tsc -p tsconfig.build.json && tsdown",
+    "build": "node scripts/clean-types.mjs && tsc -p tsconfig.build.json && tsdown",
     "bundle": "tsdown",
     "watch": "tsdown --watch",
     "typecheck": "tsc --noEmit",
     "check:styles": "node scripts/check-theme-sizes.mjs",
+    "check:third-party": "node scripts/check-third-party.mjs",
+    "check:contrast": "node scripts/audit-contrast.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",
     "test": "vitest run"

package/src/action-guard.ts

@@ -0,0 +1,127 @@
+/**
+ * 动作失败分级（fail-stop 规则）——不依赖 LLM/宿主服务的纯逻辑模块，可离线单测。
+ *
+ * 规则来源（借鉴同类 DSH 小说插件的规则设计）：
+ *  - 参数/契约类失败**不得重复同一调用**，解释一次即停；
+ *  - 瞬时故障允许有限重试，同样禁止无限重试。
+ * 规则必须可测试，否则只是文档。
+ */
+
+/**
+ * 动作失败分级：
+ * - `contract` 参数/契约类（参数缺失、片段未找到、章节不存在、非法取值…）：
+ *   同一调用只允许修正一次，禁止原样重复。
+ * - `transient` 瞬时故障（网络、模型中断、磁盘临时不可用…）：允许重试一次。
+ */
+export type ActionErrorKind = 'contract' | 'transient'
+
+/** 带分级的动作失败（executeAction 抛出，供 fail-stop 判定）。 */
+export class NovelActionError extends Error {
+  readonly kind: ActionErrorKind
+  constructor(kind: ActionErrorKind, message: string) {
+    super(message)
+    this.name = 'NovelActionError'
+    this.kind = kind
+  }
+}
+
+/** 瞬时故障特征（先判，避免被下面的契约词误伤）。 */
+const TRANSIENT_PATTERNS: readonly RegExp[] = [
+  /助手调用失败/,
+  /生成失败|请求失败|调用失败/,
+  /network|fetch failed|ECONNRESET|ECONNREFUSED|ETIMEDOUT|EPIPE|EAI_AGAIN|socket hang up|aborted|terminated/i,
+  /超时|timeout/i,
+  /频繁|限流|rate\s*limit|too many requests|\b429\b/i,
+  /ENOSPC|EACCES|EBUSY|EPERM|EMFILE/,
+]
+
+/**
+ * 参数/契约类失败特征（兜底识别）。
+ *
+ * 宿主自己的前置条件失败已在抛出点标成 {@link NovelActionError}（引擎与助手动作层），
+ * 这里的正则只兜住漏标的历史消息与第三方错误。
+ */
+const CONTRACT_PATTERNS: readonly RegExp[] = [
+  /动作参数不是合法 JSON/,
+  /未知工具/,
+  /需要/,
+  /不存在/,
+  /尚未生成/,
+  /未找到/,
+  /不在计划中/,
+  /正文文件不存在/,
+  /还没有已写章节/,
+  /没有可分析的已写章节/,
+  /非法/,
+  /无效/,
+  /必须是/,
+  /无法识别/,
+  /请先/,
+]
+
+/**
+ * 判定一次动作失败的类别。
+ *
+ * @param error 捕获到的异常。
+ * @returns `contract`（参数/契约，不重试原样调用）或 `transient`（瞬时，可重试一次）。
+ */
+export function classifyActionError(error: unknown): ActionErrorKind {
+  if (error instanceof NovelActionError) return error.kind
+  const message = error instanceof Error ? error.message : String(error)
+  if (TRANSIENT_PATTERNS.some(re => re.test(message))) return 'transient'
+  if (CONTRACT_PATTERNS.some(re => re.test(message))) return 'contract'
+  // 未知错误默认按瞬时处理：允许一次重试，但同一调用签名仍有次数上限（见 fail-stop）。
+  return 'transient'
+}
+
+/**
+ * 同一调用签名允许的总尝试次数（含首次）。
+ *
+ * @param kind 失败类别。
+ * @returns `contract` = 1（禁止原样重复），`transient` = 2（允许一次重试）。
+ */
+export function actionRetryLimit(kind: ActionErrorKind): number {
+  return kind === 'contract' ? 1 : 2
+}
+
+/**
+ * 把动作参数规范化为稳定签名（键排序），用于识别「同一个调用」。
+ *
+ * @param args 动作参数。
+ * @returns 稳定字符串签名。
+ */
+export function safeArgsKey(args: Record<string, unknown> | undefined): string {
+  if (args === undefined) return ''
+  try {
+    return JSON.stringify(Object.keys(args).sort().map(key => [key, args[key]]))
+  } catch {
+    return String(args)
+  }
+}
+
+/**
+ * 已失败调用记账：同一签名达到重试上限即 fail-stop。
+ */
+export class FailureLedger {
+  private readonly counts = new Map<string, number>()
+
+  /**
+   * 记录一次失败并判断是否应当停止本轮。
+   *
+   * @param tool 工具名。
+   * @param args 该次调用参数。
+   * @param kind 失败类别。
+   * @returns `attempts` 本次是第几次失败；`stop` 是否达到上限（true = 立即停止，不再喂回模型）。
+   */
+  record(tool: string, args: Record<string, unknown> | undefined, kind: ActionErrorKind): { attempts: number; stop: boolean } {
+    const signature = `${tool}:${safeArgsKey(args)}`
+    const attempts = (this.counts.get(signature) ?? 0) + 1
+    this.counts.set(signature, attempts)
+    return { attempts, stop: attempts >= actionRetryLimit(kind) }
+  }
+
+  /** 已登记的失败签名数量（测试/诊断用）。 */
+  get size(): number {
+    return this.counts.size
+  }
+}