@waterwx/dsh-novel-forge 2.0.1-alpha → 2.1.0

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

@@ -0,0 +1,119 @@
+/**
+ * 模型参数能力兼容层。
+ *
+ * 设计原则：**界面上保存的温度/思考档位是用户偏好，不是最终请求值。** 构造请求前
+ * 必须经过本层收敛到厂商允许的范围 —— 否则换模型、走自定义中转、或厂商改了约束，
+ * 就会出现「换个 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;
+/**
+ * 全文输出（正文/改写/润色）的 token 预算。
+ *
+ * ## 为什么放在这里
+ *
+ * 它是「按模型身份决定参数」这件事的最后一环，与 {@link convergeRequestParams}
+ * 同源；而本模块**零运行时依赖**，可以脱离宿主包离线单测。反过来若留在
+ * engine.ts，就只能靠类型检查"证明"它对——而它恰恰是这次修复的核心行为。
+ *
+ * ## 行为
+ *
+ * - 用户配的 `maxTokens` 始终是**上限**：`Math.max` 保证不会因为用户调小而
+ *   让长章写不完（3500 字中文约需 5~6k token，20000 是留足余量的地板）。
+ * - 换到备用模型时，若作者通过 `config.fallbackMaxTokens` 显式给了预算就改用它。
+ *   能力表没有上下文窗口数据，此时不猜、不硬编码任何 clamp 数值——那只会造出
+ *   一个假的正确。**没填就返回 undefined**（沿用请求原值），把决定权留给作者。
+ *
+ * @param config - 当前配置。
+ * @param model - 本次实际要用的模型。
+ * @param primaryModel - 主模型 id（与 `model` 相同即主路径）。
+ * @returns 该模型应使用的 maxTokens；undefined 表示沿用调用方原值。
+ */
+export declare function fullTextBudget(config: {
+    maxTokens: number;
+    fallbackMaxTokens?: number;
+}, model: string, primaryModel: string): number | undefined;

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

@@ -0,0 +1,36 @@
+/**
+ * 请求参数收敛的**执行层**（model-capability.ts 是规则层）。
+ *
+ * ## 为什么独立成文件
+ *
+ * `applyModelCapability` 需要 `ReasoningEffortId` 这个 dsh-llm 运行时值，而
+ * `model-capability.ts` 必须保持零运行时依赖（它有一组离线单测，且被大量结构化
+ * 任务路径复用）。所以把「规则」留在 model-capability，把「把规则应用到请求上」
+ * 挪到这里。
+ *
+ * 顺带解开了 engine.ts ↔ stream-fallback.ts 的循环依赖：
+ * 流式兜底要重算参数，本模块正是它该依赖的东西，不需要绕回 engine。
+ */
+import { type GenerateOptions } from '@deepseek-ai/dsh-llm';
+/** `applyModelCapability` 的可选行为开关。 */
+export interface ApplyModelCapabilityOptions {
+    /** 严格结构化输出任务：能力档案要求时强制关闭思考。 */
+    structured?: boolean;
+    /**
+     * 按**本次实际模型**重算输出预算。
+     *
+     * 能力表（model-capability.ts）目前不含上下文窗口数据，所以这里不猜、
+     * 不硬编码任何 clamp 数值——那只会造出一个假的正确。改为把决定权交给调用方：
+     * 流式长文路径用它保证「备用模型不会沿用主模型的 20000 预算而撞 max-tokens」。
+     */
+    maxTokensFor?: (model: string) => number | undefined;
+}
+/**
+ * 把能力约束应用到一份请求上。
+ *
+ * @param base - 调用方拼好的原始请求。
+ * @param model - **本次实际要调用的模型**（切换备用模型后必须重算，故在循环内调用）。
+ * @param options - 附加行为开关。
+ * @returns 收敛后的请求（固定温度的模型会省略 temperature / 不支持的参数会被移除）。
+ */
+export declare function applyModelCapability(base: GenerateOptions, model: string, options?: ApplyModelCapabilityOptions): GenerateOptions;

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/plotline-align.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 剧情线批量刷新的**结果对齐**。
+ *
+ * ## 为什么单独成文件
+ *
+ * 批量刷新让模型一次返回 `{items: [{name, progress}]}`，再按 name 对齐回原线。
+ * 这里最容易出的错是**错位**：一旦线名对不上，模型给 A 线的进度就会被写到
+ * B 线上。这种 bug 不报错、界面也正常显示，只是内容全错了，作者很难发现。
+ *
+ * 所以必须能离线验证。而对齐逻辑所在的 engine.ts 依赖宿主包
+ * `@deepseek-ai/dsh-llm`，脱离 dsh 环境 import 就失败——故规则层放这里。
+ */
+/** 一条待刷新的线（对齐只需要 id 与 name）。 */
+export interface AlignLine {
+    id: string;
+    name: string;
+}
+/** 对齐结果：text 为空串表示这条线没拿到进度。 */
+export interface AlignedProgress extends AlignLine {
+    text: string;
+}
+/**
+ * 把模型返回的 items 对齐回原始线列表。
+ *
+ * 对齐规则（按优先级）：
+ * 1. **线名逐字匹配**——模型原样回显 name，最可靠；
+ * 2. name 缺失或重复时，按**出现顺序**兜给尚未匹配的线
+ *    （宁可可能错位，也不能让作者看到一片空白）；
+ * 3. 模型漏项的线**留空**，绝不拿别人的进度填。
+ *
+ * @param items - 模型返回的原始 items（不保证是数组/对象）。
+ * @param lines - 原始线列表，顺序即最终返回顺序。
+ * @returns 与 `lines` 一一对应的结果（长度恒等）。
+ */
+export declare function alignPlotlineProgress(items: unknown, lines: AlignLine[]): AlignedProgress[];

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;