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

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

@@ -0,0 +1,18 @@
+/**
+ * 热门题材雷达：真实榜单扫榜（聚合各平台榜单源，容错）。
+ */
+import { type CollectedRankingItem, type MarketRadarPlatform } from './market-radar-sources.ts';
+export interface MarketRadarGroup {
+    platform: MarketRadarPlatform;
+    platformLabel: string;
+    listKey: string;
+    listLabel: string;
+    status: 'ok' | 'error';
+    error?: string;
+    items: CollectedRankingItem[];
+}
+export interface MarketScanResult {
+    scannedAt: string;
+    groups: MarketRadarGroup[];
+}
+export declare function scanMarketRanking(platforms?: string[]): Promise<MarketScanResult>;

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

@@ -0,0 +1,31 @@
+/**
+ * 「热门题材雷达」真实榜单抓取源（公开榜单页面的地址与选择器，属事实性配置）。
+ * 用全局 fetch 抓取公开榜单移动版页面，正则抽取元数据；无第三方依赖。
+ */
+export type MarketRadarPlatform = 'fanqie' | 'qidian' | 'jinjiang';
+export interface MarketRadarListSource {
+    platform: MarketRadarPlatform;
+    platformLabel: string;
+    listKey: string;
+    listLabel: string;
+    channel: string;
+    sourceUrl: string;
+}
+export interface CollectedRankingItem {
+    rank: number;
+    title: string;
+    author?: string;
+    category?: string;
+    tags: string[];
+    synopsis?: string;
+    heatLabel?: string;
+    serialStatus?: string;
+    sourceUrl: string;
+}
+export declare const MARKET_RADAR_SOURCES: MarketRadarListSource[];
+export declare function hasPrivateUseCharacters(value: string | null | undefined): boolean;
+export declare function parseFanqieRanking(html: string, source: MarketRadarListSource): CollectedRankingItem[];
+export declare function parseFanqieDetail(html: string, item: CollectedRankingItem): CollectedRankingItem;
+export declare function parseQidianRanking(html: string, source: MarketRadarListSource): CollectedRankingItem[];
+export declare function parseJinjiangRanking(html: string, source: MarketRadarListSource): CollectedRankingItem[];
+export declare function collectMarketSource(source: MarketRadarListSource): Promise<CollectedRankingItem[]>;

package/lib/types/migrate-output.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 输出目录迁移（Migrate Output Dir）— 把一本书/默认输出目录的内容搬到新位置。
+ *
+ * 安全纪律（数据零丢失排序）：
+ *  1. copy 全部内容到新目录（源目录始终原样保留）；
+ *  2. 调用方完成配置写入 / 书架重指向后，最后一步才删源目录；
+ *  3. 中途任何失败，最坏情况只是新目录多一份副本，源数据零丢失。
+ */
+/** 目录内容清单（相对路径 + 总字节）。 */
+export interface DirContents {
+    files: string[];
+    bytes: number;
+}
+/** 规范化路径用于比较（统一分隔符，Windows 忽略大小写）。 */
+export declare function normalizeDir(dir: string): string;
+/** 列出目录全部内容（递归；子目录以 `name/` 形式占位列出）。 */
+export declare function listDirContents(dir: string): DirContents;
+/**
+ * 把 from 全部内容复制到 to（源目录保留，删除由调用方在收尾执行）。
+ * 目标必须不存在或为空目录（防覆盖无关数据）；禁止互相嵌套的目录对。
+ * @returns 复制的顶层条目数。
+ */
+export declare function copyDirContents(from: string, to: string): number;
+/** 删除源目录（仅复制 + 配置/书架重指向全部成功后调用）。 */
+export declare function removeDir(dir: string): void;

package/lib/types/model-capability.d.ts

@@ -0,0 +1,93 @@
+/**
+ * 模型参数能力兼容层。
+ *
+ * 设计原则：**界面上保存的温度/思考档位是用户偏好，不是最终请求值。** 构造请求前
+ * 必须经过本层收敛到厂商允许的范围 —— 否则换模型、走自定义中转、或厂商改了约束，
+ * 就会出现「换个 provider 就报参数错误」这类故障。
+ *
+ * 两条硬要求：
+ *  1. **按模型身份判断，不按 provider 判断**。同一个模型经由自定义中转调用时，
+ *     provider 名可能完全自定义，但参数约束属于模型本身；把判断写成
+ *     `provider === '某个厂商' && ...` 会让走中转的调用绕过约束。
+ *  2. **约束要有出处**。每条规则的来源写在规则上，不靠猜。下列规则来自厂商官方
+ *     《模型参数参考》（https://platform.kimi.com/docs/api/models-overview.md）：
+ *       · kimi-k3        : temperature 固定 1.0；支持顶层 reasoning_effort
+ *       · kimi-k2.7-code : temperature 固定 1.0；不支持 reasoning_effort（用 thinking，且不可禁用）
+ *       · kimi-k2.6      : thinking 固定 1.0 / 非 thinking 固定 0.6；不支持 reasoning_effort
+ *     官方同时建议：这类模型**不要显式传入 temperature**。本层因此优先「不传」，
+ *     仅在调用方无法省略该参数时才钳到允许值。
+ */
+/** 一次请求的参数约束。 */
+export interface ModelCapability {
+    /** 该模型只接受这一个温度值（如 Kimi 全系），缺省表示不约束。 */
+    fixedTemperature?: number;
+    /** 温度允许的下界（默认 0）。 */
+    minTemperature?: number;
+    /** 温度允许的上界（默认 2，主流 OpenAI 兼容区间）。 */
+    maxTemperature?: number;
+    /**
+     * 是否支持 OpenAI 兼容的 `reasoning_effort`。
+     * false 表示**不得下发**该参数（如 Kimi K2.x 用的是 `thinking`），下发会被厂商拒绝。
+     */
+    supportsReasoning?: boolean;
+    /**
+     * 推理控制方式：`reasoning_effort`（OpenAI 兼容顶层参数）或 `thinking`（Kimi K2.x 专属）。
+     * 运行时若适配层支持，应按此选择参数名；仅为诊断与后续适配保留。
+     */
+    reasoningControl?: 'reasoning-effort' | 'thinking' | 'none';
+    /** 严格结构化输出必须关闭思考（覆盖用户偏好）。 */
+    reasoningForcedOff?: boolean;
+    /** 命中的规则名，用于日志与测试断言。 */
+    rule: string;
+    /** 约束出处（文档 URL 或说明），便于复核与更新。 */
+    source: string;
+}
+/**
+ * 把模型 id 归一化为「模型身份」。
+ *
+ * 处理：去空白与首尾斜杠、小写、剥掉供应商前缀（`kimi/kimi-k3` → `kimi-k3`）。
+ * @param model - 原始模型 id。
+ * @returns 归一化后的身份（小写、无前缀）。
+ */
+export declare function canonicalModelId(model: string | undefined): string;
+/**
+ * 解析一条模型的能力约束。
+ * @param model - 模型 id（可能带供应商前缀）。
+ * @returns 命中的能力；无约束时返回 undefined。
+ */
+export declare function resolveModelCapability(model: string | undefined): ModelCapability | undefined;
+/** 一次待收敛的请求参数。 */
+export interface RequestParams {
+    temperature: number;
+    /** 请求方（含用户偏好）希望使用的思考档位；undefined 表示不涉及。 */
+    reasoningEffort?: 'off' | 'low' | 'high' | 'max';
+}
+/** 收敛结果：最终请求值 + 发生了哪些调整（便于日志与诊断）。 */
+export interface ConvergedParams {
+    /**
+     * 最终要下发的温度；`undefined` 表示**应当省略该参数**。
+     * 厂商建议这类模型不要显式传 temperature 时，本层返回 undefined。
+     */
+    temperature: number | undefined;
+    reasoningEffort?: 'off' | 'low' | 'high' | 'max';
+    /** 被本层改掉的项，形如 `temperature: 0.3 -> 省略`。 */
+    adjustments: string[];
+    /** 命中的规则名。 */
+    rule?: string;
+    /** 约束出处。 */
+    source?: string;
+}
+/**
+ * 把请求参数收敛到模型允许的范围。
+ *
+ * @param params - 调用方希望使用的参数。
+ * @param model - 实际要调用的模型 id（应传**实际模型**；换备用模型后需重算）。
+ * @param options - `structured: true` 表示这是严格结构化输出任务；
+ *   `omitFixedTemperature: true` 表示调用方可以不传温度（推荐，厂商建议如此），
+ *   此时固定温度会收敛为 undefined 而不是钳到固定值。
+ * @returns 最终请求值与被调整项。
+ */
+export declare function convergeRequestParams(params: RequestParams, model: string | undefined, options?: {
+    structured?: boolean;
+    omitFixedTemperature?: boolean;
+}): ConvergedParams;

package/lib/types/output-budget.d.ts

@@ -0,0 +1,86 @@
+/**
+ * 结构化输出预算与字段长度合同。
+ *
+ * 背景：本插件此前给每个 LLM 调用写死一个 `Math.max(config.maxTokens, N)`。短任务
+ * 与长任务拿到同一个额度，长任务（分卷、拆章、逐章规划）**额度不随规模增长**，
+ * 截断后只能抛「请增大 maxTokens」。这里把额度改成按规模推算，并给结构化字段
+ * 定长度上限，让预算花在结构上而不是被自由发挥吃光。
+ *
+ * 设计取舍：结构化输出的额度应当**随本次要产出的条目数增长**，并由硬上限兜住，
+ * 否则要么短任务浪费额度，要么长任务写到一半被截断。字段长度上限同时写进提示词
+ * 与解析端，两处共用一张表，避免漂移。
+ *
+ * 一条硬纪律：**不要用 JSON repair 去补被截断的结构**。repair 只能修已有结构，
+ * 补不出尚未输出的条目；在服务层手工补齐缺失项，等于把不完整的规划伪装成可用
+ * 资产。预算给够 + 输出够紧凑，才是正解。
+ */
+/** 一次调用的输出规模描述：给出能决定输出体量的那个量。 */
+export interface OutputScope {
+    /** 预期卷数（分卷/卷战略类）。 */
+    volumes?: number;
+    /** 预期章节数（章节列表/批量拆章类）。 */
+    chapters?: number;
+    /** 预期角色数（角色阵容/资产提炼类）。 */
+    characters?: number;
+    /** 预期条目数（伏笔、题材、资产等清单类）。 */
+    items?: number;
+    /** 需要覆盖的正文规模（字），用于拆书/反推这类按输入体量走的任务。 */
+    sourceChars?: number;
+}
+/** 一类结构化任务的预算规格。 */
+export interface OutputBudgetSpec {
+    /** 无视规模也要给到的下限。 */
+    floor: number;
+    /** 规模为 0 时的起步额度。 */
+    base: number;
+    /** 每单位规模追加的额度。 */
+    perUnit: number;
+    /** 硬上限：超过它只会让模型啰嗦，不会让结构更完整。 */
+    ceiling: number;
+}
+/** 结构化任务分组——按"输出里每个单位要写多少字段"分档，而不是按业务名。 */
+export type OutputBudgetKind = 'volume-strategy' | 'chapter-list' | 'character-cast' | 'item-list' | 'analysis';
+/**
+ * 取出与任务类型相关的那一个规模量。
+ * @param kind - 任务类型。
+ * @param scope - 规模描述。
+ * @returns 单位数；分析类返回千字单位（向上取整）。
+ */
+export declare function scopeUnits(kind: OutputBudgetKind, scope: OutputScope): number;
+/**
+ * 按规模推算输出额度。
+ * @param kind - 结构化任务类型。
+ * @param scope - 本次任务的规模（缺省时按最小规模处理）。
+ * @returns 建议的 `maxTokens`，落在该类型的 [floor, ceiling] 内。
+ */
+export declare function resolveOutputBudget(kind: OutputBudgetKind, scope?: OutputScope): number;
+/** 读取某类任务的规格（供诊断与测试断言）。 */
+export declare function outputBudgetSpec(kind: OutputBudgetKind): OutputBudgetSpec;
+/**
+ * 结构化字段长度合同 —— 与 prompt 里的长度声明必须逐项一致。
+ *
+ * 两边同步的理由：只写进 schema，模型不知道就会超长被拒；只写进 prompt，模型
+ * 偶尔超长没人拦。本表是单一数据源。
+ */
+export declare const STRUCTURED_FIELD_LIMITS: {
+    /** 分卷战略：书级阶梯类字段。 */
+    readonly volumeLadder: 160;
+    /** 分卷战略：每卷定位标签。 */
+    readonly volumeRoleLabel: 32;
+    /** 分卷战略：每卷核心回报 / 升级焦点。 */
+    readonly volumeReward: 64;
+    /** 分卷战略：不确定项原因。 */
+    readonly volumeUncertaintyReason: 64;
+    /** 章节计划：单章标题。 */
+    readonly chapterTitle: 40;
+    /** 章节计划：单章摘要。 */
+    readonly chapterSummary: 300;
+    /** 章节计划：本章目标。 */
+    readonly chapterGoal: 200;
+};
+/**
+ * 把长度合同渲染成可直接塞进 system prompt 的一句话，避免 prompt 与表漂移。
+ * @param entries - 要声明的字段（描述 + 上限），按声明顺序渲染。
+ * @returns 形如「为保证输出完整：A 不超过 160 字；B 不超过 64 字。」的中文说明。
+ */
+export declare function renderLengthContract(entries: ReadonlyArray<readonly [string, number]>): string;

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

@@ -0,0 +1,10 @@
+/** 章节写作约束：把写作骨架渲染成可附加到系统提示词末尾的必达/禁止/自查块。 */
+export declare function renderChapterWriterSkeleton(meta: {
+    targetChars: number;
+    minChars: number;
+    maxChars: number;
+    pov?: string;
+    tonePreference?: string;
+    endingHookPreference?: string;
+    antiAiRules?: string;
+}): string;