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

package/lib/types/llm-live.d.ts

@@ -1,44 +1,70 @@
 /**
- * LLM 实况 feed（对齐上游「AI 创作实况 / LIVE LOG」的轻量实现）。
+ * LLM 实况 feed：以「每次 LLM 调用」为粒度，把生命周期事件（开始/流式正文/阶段变化/完成）
+ * 推给订阅者，并提供环形缓冲供新连上的客户端重放。
  *
- * 以「每次 LLM 调用」为粒度，把生命周期事件（开始/流式正文/阶段变化/完成）推给订阅者，
- * 并提供环形缓冲供新连上的客户端重放。不持久化（与上游缓存不同，如需成 cache 再扩展）。
+ * 同时承担三件与用量有关的事（进程内，不落盘）：
+ *   1) **用量账本**：每次调用结束后按用途累计 token / 耗时，供 /status 展示；
+ *   2) **Prompt 记录**：保存每次调用实际发送的 system + user（环形，按需查询）；
+ *   3) **首字耗时**：调用方在拿到第一个文本增量时打点，用于观察模型响应速度。
  */
-export type LlmLivePhase = 'requesting' | 'streaming' | 'completed' | 'failed';
-export interface LlmLiveFrame {
-    type: 'session_started' | 'output_delta' | 'reasoning_delta' | 'phase_changed' | 'session_completed';
-    /** 由服务端生成，形如 ll-<n>。 */
+import type { BlockAssembler, TokenUsage } from '@deepseek-ai/dsh-llm';
+import type { LlmLiveFrame, LlmPromptRecord, LlmTokenUsage, LlmUsageSummary } from './protocol.ts';
+export type { LlmLiveFrame };
+type Listener = (frame: LlmLiveFrame) => void;
+export declare function nextSessionId(): string;
+export declare function subscribeLiveFeed(listener: Listener): () => void;
+export declare function emitLive(frame: LlmLiveFrame): void;
+/** 把 dsh-llm 的 usage 转成线上形状。 */
+export declare function toLiveUsage(usage: TokenUsage | undefined): LlmTokenUsage | undefined;
+/** 本次运行的用量汇总（按耗时降序排列用途，便于看谁最贵）。 */
+export declare function liveUsage(): LlmUsageSummary;
+/** 清零用量账本（面板「重新计数」用）。 */
+export declare function resetLiveUsage(): void;
+/** 记一条 Prompt（超长截断并标记）。 */
+export declare function recordPrompt(input: {
     sessionId: string;
-    /** 本次调用用途（如 正文生成/审稿/章节规划）。 */
     label?: string;
-    /** 使用模型（用于展示）。 */
     model?: string;
-    /** 事件时间（ISO）。 */
-    at: string;
-    /** session_started / 部分帧：交互上下文。 */
-    context?: {
-        taskId?: string;
-        interactionId: string;
-    };
-    /** output_delta / reasoning_delta：本次增量文本。 */
-    content?: string;
-    /** session 累计字符数。 */
-    totalChars?: number;
-    /** reasoning 累计字符数。 */
-    totalReasoningChars?: number;
-    /** phase_changed：新阶段。 */
-    phase?: LlmLivePhase;
-    /** phase_changed：阶段描述。 */
-    phaseMessage?: string;
-    /** session_completed：最终预览（截断）。 */
+    system?: string;
+    user?: string;
+}): LlmPromptRecord;
+/** 取一条 Prompt 记录（不存在返回 undefined）。 */
+export declare function livePrompt(sessionId: string): LlmPromptRecord | undefined;
+/** 一次调用的打点句柄。 */
+export interface LiveCallHandle {
+    sessionId: string;
+    startedAt: number;
+    /** 用途（用于 session_completed 的用量分组）。 */
+    label: string;
+    /** 实际使用的模型。 */
+    model: string;
+    /** 首字耗时（毫秒），由 markFirstToken 写入。 */
+    firstTokenMs?: number;
+}
+/**
+ * 开始一次 LLM 调用：发 session_started、记 Prompt、起计时。
+ *
+ * @param input 用途/模型/实际发送的 system 与 user。
+ * @returns 打点句柄（结束时交给 endLiveCall）。
+ */
+export declare function beginLiveCall(input: {
+    label: string;
+    model: string;
+    system?: string;
+    user?: string;
+}): LiveCallHandle;
+/** 首字打点（调用方在收到第一个文本增量时调用，只记第一次）。 */
+export declare function markFirstToken(handle: LiveCallHandle): void;
+/**
+ * 结束一次 LLM 调用：从 assembler 取用量，发 session_completed（含 token/耗时/首字）。
+ *
+ * @param handle beginLiveCall 的句柄。
+ * @param assembler 本次调用的 BlockAssembler。
+ * @param extra 字符数/预览/失败信息等。
+ */
+export declare function endLiveCall(handle: LiveCallHandle, assembler: BlockAssembler, extra?: {
+    chars?: number;
     preview?: string;
-    /** session_completed：失败信息。 */
+    phase?: 'completed' | 'failed';
     error?: string;
-}
-type Listener = (frame: LlmLiveFrame) => void;
-export declare function nextSessionId(): string;
-export declare function subscribeLiveFeed(listener: Listener): () => void;
-export declare function emitLive(frame: LlmLiveFrame): void;
-export declare function liveLatest(): LlmLiveFrame[];
-export declare function clearLiveFeed(): void;
-export {};
+}): void;

package/lib/types/llm-retry.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 模型失败恢复规则（纯逻辑，可离线单测）。
+ *
+ * 解决的问题：批量连写时，主模型偶发限流/超时/额度耗尽会让**整批中断**，
+ * 而换一个模型重试一次往往就能过去。规则：
+ *   1) 只对「可重试」错误切换模型——用户主动取消、参数/契约类错误不重试；
+ *   2) 备用模型为空或与主模型相同则不切换；
+ *   3) 备用模型也失败时，抛**原始错误**（保留主因，不掩盖现场）；
+ *   4) 每次调用最多切换一次。
+ */
+/**
+ * 判断一次 LLM 失败是否值得换模型重试。
+ *
+ * @param error 捕获到的异常。
+ * @returns 可重试时为 true。
+ */
+export declare function isRetryableLlmError(error: unknown): boolean;
+/**
+ * 判断是否应当切换到备用模型。
+ *
+ * @param fallbackModel 配置的备用模型（空串 = 未配置）。
+ * @param primaryModel 本次实际使用的主模型。
+ * @param error 捕获到的异常。
+ * @returns 应当切换时为 true。
+ */
+export declare function shouldSwitchModel(fallbackModel: string | undefined, primaryModel: string, error: unknown): boolean;
+/**
+ * 用主模型执行；失败且满足切换条件时，用备用模型再执行一次。
+ *
+ * @param input 主模型 / 备用模型 / 实际执行函数（接收本次要用的模型 id）。
+ * @returns 执行结果（备用模型成功时返回其结果）。
+ * @throws 主模型失败且未切换时抛原错误；切换后仍失败时同样抛**主模型的原始错误**。
+ */
+export declare function withModelFallback<T>(input: {
+    model: string;
+    fallbackModel?: string;
+    onSwitch?: (from: string, to: string, error: unknown) => void;
+}, run: (model: string) => Promise<T>): Promise<T>;

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

@@ -15,5 +15,4 @@ export interface MarketScanResult {
     scannedAt: string;
     groups: MarketRadarGroup[];
 }
-export declare function getLastMarketScan(): MarketScanResult | null;
 export declare function scanMarketRanking(platforms?: string[]): Promise<MarketScanResult>;

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

@@ -1,5 +1,5 @@
 /**
- * 「热门题材雷达」真实榜单抓取源（移植自 AI-Novel-Writing-Assistant marketRadarSources）。
+ * 「热门题材雷达」真实榜单抓取源（公开榜单页面的地址与选择器，属事实性配置）。
  * 用全局 fetch 抓取公开榜单移动版页面，正则抽取元数据；无第三方依赖。
  */
 export type MarketRadarPlatform = 'fanqie' | 'qidian' | 'jinjiang';

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,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

@@ -1,30 +1,5 @@
-/**
- * 官方提示模板注册表（对齐上游 officialTemplates.ts 的轻量版）。
- *
- * 目标：把高频提示词从内联字符串升级为「可定位、可版本化、可诊断缺组」的资产，
- * 同时保留 writeSystemPrompt 的现有大段上下文注入（道藏/世界观/大纲/资产/伏笔/剧情线），
- * 只在其基础上补充「官方渲染骨架」的必达/禁止/自查块。
- */
-export interface OfficialTemplate {
-    id: string;
-    version: string;
-    /** 需要的 slot 变量（跨层注入点）。 */
-    slots: string[];
-    /** 需要的上下文分组（缺组时可诊断）。 */
-    contextGroups: string[];
-    /** system 提示模板（可用 {{slot.*}} 占位，运行时替换）。 */
-    system: string[];
-    /** human 提示模板（可用 {{context.*}} / {{input.*}} 占位）。 */
-    human: string[];
-}
-export declare const OFFICIAL_TEMPLATES: Record<string, OfficialTemplate>;
-export declare function getOfficialPromptTemplate(id: string): OfficialTemplate | null;
-export declare function getOfficialPromptTemplateVersion(id: string): string | null;
-/** 轻量稳定哈希（与上游 sha1 对齐精神：内容变化→版本变化）。 */
-export declare function hashPromptTemplate(id: string): string;
-export declare function getRequiredTemplateContextGroups(id: string): string[];
-/** 把官方 writer 骨架渲染成可附加到现有系统提示词末尾的约束/自查块。 */
-export declare function renderOfficialChapterWriterSkeleton(meta: {
+/** 章节写作约束：把写作骨架渲染成可附加到系统提示词末尾的必达/禁止/自查块。 */
+export declare function renderChapterWriterSkeleton(meta: {
     targetChars: number;
     minChars: number;
     maxChars: number;