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

package/src/output-budget.ts

@@ -0,0 +1,147 @@
+/**
+ * 结构化输出预算与字段长度合同。
+ *
+ * 背景：本插件此前给每个 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'
+
+/**
+ * 数值口径：以**本插件真实产出字段的体积**折算，不是照搬参考项目的数字
+ * （它的卷战略字段与本插件的章节字段结构不同，直接套用会造成新的截断）。
+ *
+ * 折算假设：中文约 1.5-2 token/字；账本式 JSON 的键名与括号再占约 15%。
+ * 例如单章条目 = 标题(≤40) + 摘要(≤300) + 本章目标(≤200) + beats + 最多 4 条
+ * payoff 指令 → 约 250-400 字 → **约 350 token/章**。若字段合同调整，这里必须同步。
+ */
+const SPECS: Record<OutputBudgetKind, OutputBudgetSpec> = {
+  // 每卷：roleLabel(≤32) + coreReward(≤64) + escalationFocus(≤64) + uncertainty，
+  // 再加书级阶梯字段（readerRewardLadder/escalationLadder/midpointShift/notes）。
+  'volume-strategy': { floor: 1_800, base: 1_200, perUnit: 220, ceiling: 6_000 },
+  // 每章 ≈350 token（见上方折算说明），另留写作余量；上限对齐单次调用能力。
+  'chapter-list': { floor: 2_500, base: 2_000, perUnit: 350, ceiling: 20_000 },
+  // 每角色：名字 + roleLabel + 定位 + 关系 + 弧线 ≈150 token。
+  'character-cast': { floor: 1_500, base: 1_000, perUnit: 150, ceiling: 8_000 },
+  // 清单类，每条几个短字段。
+  'item-list': { floor: 1_000, base: 800, perUnit: 60, ceiling: 4_000 },
+  // 拆书/反推：按输入正文体量走，每千字约 120 token。
+  analysis: { floor: 3_000, base: 2_000, perUnit: 12, ceiling: 16_000 },
+}
+
+/**
+ * 取出与任务类型相关的那一个规模量。
+ * @param kind - 任务类型。
+ * @param scope - 规模描述。
+ * @returns 单位数；分析类返回千字单位（向上取整）。
+ */
+export function scopeUnits(kind: OutputBudgetKind, scope: OutputScope): number {
+  const positive = (value: number | undefined): number =>
+    typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : 0
+  switch (kind) {
+    case 'volume-strategy':
+      return positive(scope.volumes)
+    case 'chapter-list':
+      return positive(scope.chapters)
+    case 'character-cast':
+      return positive(scope.characters)
+    case 'item-list':
+      return positive(scope.items)
+    case 'analysis':
+      // 输入正文每 1000 字算一个单位。
+      return Math.ceil(positive(scope.sourceChars) / 1_000)
+  }
+}
+
+/**
+ * 按规模推算输出额度。
+ * @param kind - 结构化任务类型。
+ * @param scope - 本次任务的规模（缺省时按最小规模处理）。
+ * @returns 建议的 `maxTokens`，落在该类型的 [floor, ceiling] 内。
+ */
+export function resolveOutputBudget(kind: OutputBudgetKind, scope: OutputScope = {}): number {
+  const spec = SPECS[kind]
+  const raw = spec.base + scopeUnits(kind, scope) * spec.perUnit
+  return Math.min(spec.ceiling, Math.max(spec.floor, Math.round(raw)))
+}
+
+/** 读取某类任务的规格（供诊断与测试断言）。 */
+export function outputBudgetSpec(kind: OutputBudgetKind): OutputBudgetSpec {
+  return { ...SPECS[kind] }
+}
+
+/**
+ * 结构化字段长度合同 —— 与 prompt 里的长度声明必须逐项一致。
+ *
+ * 两边同步的理由：只写进 schema，模型不知道就会超长被拒；只写进 prompt，模型
+ * 偶尔超长没人拦。本表是单一数据源。
+ */
+export const STRUCTURED_FIELD_LIMITS = {
+  /** 分卷战略：书级阶梯类字段。 */
+  volumeLadder: 160,
+  /** 分卷战略：每卷定位标签。 */
+  volumeRoleLabel: 32,
+  /** 分卷战略：每卷核心回报 / 升级焦点。 */
+  volumeReward: 64,
+  /** 分卷战略：不确定项原因。 */
+  volumeUncertaintyReason: 64,
+  /** 章节计划：单章标题。 */
+  chapterTitle: 40,
+  /** 章节计划：单章摘要。 */
+  chapterSummary: 300,
+  /** 章节计划：本章目标。 */
+  chapterGoal: 200,
+} as const
+
+/**
+ * 把长度合同渲染成可直接塞进 system prompt 的一句话，避免 prompt 与表漂移。
+ * @param entries - 要声明的字段（描述 + 上限），按声明顺序渲染。
+ * @returns 形如「为保证输出完整：A 不超过 160 字；B 不超过 64 字。」的中文说明。
+ */
+export function renderLengthContract(entries: ReadonlyArray<readonly [string, number]>): string {
+  if (entries.length === 0) return ''
+  const parts = entries.map(([label, limit]) => `${label}不超过 ${limit} 字`)
+  return `为保证输出完整：${parts.join('；')}。每个字段只保留完成本阶段决策所需的信息，写完后立即结束输出，不要展开细纲或重复说明。`
+}

package/src/prompt-slots.ts

@@ -0,0 +1,125 @@
+/**
+ * 提示词槽位：给作者留几个**安全可改**的位置，用来微调本书的写作偏好。
+ *
+ * 设计边界（很重要）：
+ *   * 槽位只追加"作者偏好"，**不允许覆盖**规则工程与合规红线——道藏、写作红线、
+ *     九条内容合规红线、反 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 const PROMPT_SLOTS: readonly PromptSlotSpec[] = [
+  {
+    id: 'styleExtra',
+    label: '文风补充',
+    hint: '追加到写作提示词末尾的风格偏好（句式、叙述习惯、用词倾向）。',
+    placeholder: '例如：多用短句和对话推进，少用成语；环境描写只写能影响动作的部分。',
+    maxChars: 1200,
+  },
+  {
+    id: 'antiAiExtra',
+    label: '反 AI 补充',
+    hint: '本书额外的"别这么写"清单，与内置反 AI 规则叠加（不能覆盖内置规则）。',
+    placeholder: '例如：不要每段都用比喻；不要用"空气中弥漫着"这类句式。',
+    maxChars: 1200,
+  },
+  {
+    id: 'dialogueExtra',
+    label: '对话补充',
+    hint: '角色说话方式的额外约束，写入时会与角色卡一起注入。',
+    placeholder: '例如：长辈说话带方言词；主角对熟人用绰号称呼。',
+    maxChars: 800,
+  },
+  {
+    id: 'endingHookExtra',
+    label: '章末钩子偏好',
+    hint: '对结尾钩子的额外要求（与章节计划里的 endingHook 叠加）。',
+    placeholder: '例如：结尾尽量落在一个未闭合的选择上，而不是新出现的敌人。',
+    maxChars: 600,
+  },
+]
+
+/** 槽位 id → 规格。 */
+const SLOT_BY_ID = new Map(PROMPT_SLOTS.map(s => [s.id, s] as const))
+
+/** 单个槽位的渲染结果。 */
+export interface RenderedSlot {
+  id: PromptSlotId
+  label: string
+  text: string
+  /** 是否因超长被截断。 */
+  truncated: boolean
+  /** 原文长度（截断前）。 */
+  chars: number
+}
+
+/**
+ * 读取并规整项目里的槽位内容（去空白、按上限截断）。
+ *
+ * @param project 项目状态。
+ * @returns 非空槽位列表（保持 PROMPT_SLOTS 的声明顺序）。
+ */
+export function readPromptSlots(project: ProjectState): RenderedSlot[] {
+  const stored = project.promptSlots ?? {}
+  const out: RenderedSlot[] = []
+  for (const spec of PROMPT_SLOTS) {
+    const raw = (stored[spec.id] ?? '').trim()
+    if (raw === '') continue
+    const truncated = raw.length > spec.maxChars
+    out.push({
+      id: spec.id,
+      label: spec.label,
+      text: truncated ? raw.slice(0, spec.maxChars) : raw,
+      truncated,
+      chars: raw.length,
+    })
+  }
+  return out
+}
+
+/**
+ * 把槽位渲染成注入提示词的段落。
+ *
+ * @param project 项目状态。
+ * @returns 提示词片段；无槽位时返回空串。
+ */
+export function renderPromptSlots(project: ProjectState): string {
+  const slots = readPromptSlots(project)
+  if (slots.length === 0) return ''
+  const lines = ['==================== 作者偏好（本书自定义，优先级低于道藏/红线/合规） ====================']
+  for (const slot of slots) {
+    lines.push(`【${slot.label}】${slot.text}${slot.truncated ? `（已按 ${SLOT_BY_ID.get(slot.id)?.maxChars ?? 0} 字上限截断，原 ${slot.chars} 字）` : ''}`)
+  }
+  lines.push('以上偏好只影响表达方式；与道藏、写作红线、内容合规红线冲突时，一律以后者为准。')
+  return lines.join('\n')
+}
+
+/**
+ * 校验并规整一次槽位写入。
+ *
+ * @param id 槽位 id。
+ * @param value 内容（空串表示清空该槽位）。
+ * @returns 归一化后的内容。
+ * @throws 槽位 id 不在白名单时抛错。
+ */
+export function normalizeSlotValue(id: string, value: string): string {
+  const spec = SLOT_BY_ID.get(id as PromptSlotId)
+  if (spec === undefined) throw new Error(`未知提示词槽位：${id}`)
+  return value.replace(/\r\n/g, '\n').trim()
+}

package/src/prompting.ts

@@ -0,0 +1,26 @@
+/** 章节写作约束：把写作骨架渲染成可附加到系统提示词末尾的必达/禁止/自查块。 */
+export function renderChapterWriterSkeleton(meta: {
+  targetChars: number
+  minChars: number
+  maxChars: number
+  pov?: string
+  tonePreference?: string
+  endingHookPreference?: string
+  antiAiRules?: string
+}): string {
+  const pov = meta.pov ?? '第三人称有限视角，严格跟随主角所见所知。'
+  const tone = meta.tonePreference ?? '文风贴合本书设定，用具体细节与动作推进。'
+  const hook = meta.endingHookPreference ?? '章末留一个明确的钩子（新信息、新风险或未闭合的选择）。'
+  const antiAi = meta.antiAiRules ?? ''
+  return [
+    '==================== 章节生成骨架（必达 / 禁止 / 输出前自查） ====================',
+    '【叙事视角】' + pov,
+    '【本章必达】本章必须发生实质变化——局面、关系、信息、风险、决策至少动一项；开篇直接进入情境，不复述上一章。',
+    '【禁止事项】不写以总结、复盘、解释为主的段落；不新增核心角色，不写入与上下文冲突的设定；不为凑字数注水。',
+    '【篇幅】目标 ' + meta.targetChars + ' 字，区间 ' + meta.minChars + '-' + meta.maxChars + ' 字；不够就继续推进有效情节，不许草草收尾。',
+    '【结尾】' + hook,
+    '【表达】用具体动作、对话与可感知细节往前推；' + tone,
+    '【反 AI】' + antiAi,
+    '【输出前自查】逐项确认：读者的回报、关键转折、章末净变化是否看得见？上一章留下的钩子有没有交代？人物的硬事实有没有被写反？确认无误再输出，正文里不要出现核查过程。',
+  ].join('\n')
+}