@waterwx/dsh-novel-forge 1.2.0 → 1.3.0-alpha

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;