@waterwx/dsh-novel-forge 1.3.1 → 1.3.2-alpha

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

@@ -0,0 +1,19 @@
+/**
+ * 热门题材雷达：真实榜单扫榜（聚合各平台榜单源，容错）。
+ */
+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 getLastMarketScan(): MarketScanResult | null;
+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/novel-context.d.ts

@@ -0,0 +1,80 @@
+/**
+ * 统一上下文组装与相关设定检索
+ *
+ * 取代各阶段各自拼装 prompt，消除「生成看得到、审稿看不到」的断层。
+ * 所有阶段通过 buildChapterContext 获取同一来源的事实与设定。
+ */
+import type { ProjectState, ChapterPlan, StoryBible, RoleRecord, ChapterFact, Foreshadow, Plotline } from './protocol';
+export interface ChapterContext {
+    /** 平台合规红线（永远全量） */
+    complianceRedLines: string[];
+    /** 本书写作红线（永远全量） */
+    bookRedLines: string[];
+    /** 当前章相关角色卡（全量信息） */
+    relevantRoles: Array<{
+        name: string;
+        role: string;
+        traits: string[];
+        goals?: string;
+        knowledge?: string[];
+    }>;
+    /** 当前章相关道藏规则 */
+    relevantWorldRules: string[];
+    /** 活跃剧情线 */
+    activePlotlines: Plotline[];
+    /** 未回收伏笔 */
+    activeForeshadows: Foreshadow[];
+    /** 上一章结尾原文 */
+    prevChapterTail: string;
+    /** 上一章摘要 */
+    prevChapterSummary?: string;
+    /** 最近事实（近因记忆，top20） */
+    recentFacts: string[];
+    /** 相关旧事实（按本章 beats 检索，top15） */
+    relatedFacts: string[];
+    /** 当前卷大纲 */
+    currentVolumeOutline: string;
+    /** 本章 beats */
+    beats: string;
+    /** 本章标题 */
+    chapterTitle: string;
+}
+export interface ContextBuildOptions {
+    /** 阶段：writing/review/revise/polish/plan */
+    stage?: 'writing' | 'review' | 'revise' | 'polish' | 'plan';
+    /** 是否注入完整角色卡（false 时只注入角色名+定位） */
+    fullRoleCards?: boolean;
+    /** 相关事实检索上限 */
+    relatedFactsLimit?: number;
+    /** 最近事实数量 */
+    recentFactsLimit?: number;
+}
+/**
+ * 相关事实检索：trigram 重合度 + 角色名命中加权 + 近因加权
+ * 从 generateChapterStream 抽取，扩展为通用函数。
+ */
+export declare function retrieveRelatedFacts(facts: ChapterFact[], beatsText: string, roleNames: string[], limit?: number): string[];
+/**
+ * 相关角色检索：beats 中出现的角色 + 主角/主要反派永远全量
+ */
+export declare function retrieveRelevantRoles(bible: StoryBible | undefined, roles: RoleRecord[] | undefined, beatsText: string): ChapterContext['relevantRoles'];
+/**
+ * 构建章节统一上下文
+ *
+ * 各阶段调用此函数获取同一来源的事实与设定，消除上下文断层。
+ * 检索结果不足时自动回退全量，保证不丢失关键信息。
+ */
+export declare function buildChapterContext(project: ProjectState, chapter: ChapterPlan, outputDir: string, options?: ContextBuildOptions): ChapterContext;
+/**
+ * 将上下文渲染为 prompt 文本块
+ * 各阶段可按需选择注入哪些块。
+ */
+export declare function renderContextBlocks(ctx: ChapterContext): {
+    rolesBlock: string;
+    worldRulesBlock: string;
+    factsBlock: string;
+    plotlinesBlock: string;
+    foreshadowsBlock: string;
+    continuityBlock: string;
+    redLinesBlock: 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/prompt-utils.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 提示词共享常量与工具
+ *
+ * 所有 JSON 输出规则、通用约束集中在此，避免各阶段重复定义、互相打架。
+ */
+/** JSON 输出规则（所有要求模型输出 JSON 的地方共用） */
+export declare const JSON_OUTPUT_RULES: string[];
+/** JSON 输出规则的紧凑版（适合放在提示词末尾） */
+export declare const JSON_OUTPUT_RULES_COMPACT: string;
+/**
+ * 估算 prompt 的 token 数（粗略估算，用于上下文预算控制）
+ * 中文约 1.7 字/token，英文约 4 字符/token
+ */
+export declare function estimateTokens(text: string): number;
+/**
+ * 按 token 预算截断文本（保留开头，末尾加省略标记）
+ * 用于控制单块上下文不超预算。
+ */
+export declare function truncateByTokens(text: string, maxTokens: number, marker?: string): string;
+/** 通用「只改表达不改情节」约束（润色/局部修订共用） */
+export declare const EXPRESSION_ONLY_RULE: string[];
+/** 章节上下文各阶段的 token 预算（粗略，用于控制注入量） */
+export declare const CONTEXT_BUDGET: {
+    /** 章节生成：道藏+角色+大纲+事实+伏笔 */
+    readonly writing: 12000;
+    /** AI 审稿：道藏+角色+事实+正文 */
+    readonly review: 10000;
+    /** 修订：原意见+相关事实+目标正文 */
+    readonly revise: 8000;
+    /** 润色：风格资产+原正文 */
+    readonly polish: 6000;
+    /** 分章规划：大纲+道藏+角色+近期事实 */
+    readonly plan: 15000;
+};
+export type ContextStage = keyof typeof CONTEXT_BUDGET;

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;