@waterwx/dsh-novel-forge 1.10.1 → 2.0.0

package/src/model-capability.ts

@@ -0,0 +1,215 @@
+/**
+ * 模型参数能力兼容层。
+ *
+ * 设计原则：**界面上保存的温度/思考档位是用户偏好，不是最终请求值。** 构造请求前
+ * 必须经过本层收敛到厂商允许的范围 —— 否则换模型、走自定义中转、或厂商改了约束，
+ * 就会出现「换个 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
+}
+
+/** 一道匹配规则：先命中先生效。 */
+interface CapabilityRule {
+  /** 规则名。 */
+  rule: string
+  /** 约束出处。 */
+  source: string
+  /** 模型 id 归一化后是否命中。 */
+  matches: (canonical: string) => boolean
+  capability: Omit<ModelCapability, 'rule' | 'source'>
+}
+
+const KIMI_SOURCE = 'https://platform.kimi.com/docs/api/models-overview.md'
+
+/**
+ * 把模型 id 归一化为「模型身份」。
+ *
+ * 处理：去空白与首尾斜杠、小写、剥掉供应商前缀（`kimi/kimi-k3` → `kimi-k3`）。
+ * @param model - 原始模型 id。
+ * @returns 归一化后的身份（小写、无前缀）。
+ */
+export function canonicalModelId(model: string | undefined): string {
+  if (typeof model !== 'string') return ''
+  const trimmed = model.trim().toLowerCase().replace(/^\/+|\/+$/g, '')
+  if (trimmed === '') return ''
+  const segments = trimmed.split('/')
+  return segments[segments.length - 1] ?? ''
+}
+
+const RULES: CapabilityRule[] = [
+  {
+    rule: 'kimi-k3-fixed-temperature',
+    source: KIMI_SOURCE,
+    // 只命中 k3 本身；k2.6 / k2.7 另立规则（约束不同）。
+    matches: (m) => /^kimi[-_.]?k-?3(?:[-_.]|$)/.test(m),
+    capability: { fixedTemperature: 1, supportsReasoning: true, reasoningControl: 'reasoning-effort' },
+  },
+  {
+    rule: 'kimi-k2.7-code-fixed-temperature',
+    source: KIMI_SOURCE,
+    matches: (m) => /^kimi[-_.]?k-?2[-_.]?7(?:[-_.]|$)/.test(m),
+    capability: {
+      fixedTemperature: 1,
+      // 不支持 reasoning_effort；思考由 thinking 控制且不可禁用。
+      supportsReasoning: false,
+      reasoningControl: 'thinking',
+      reasoningForcedOff: true,
+    },
+  },
+  {
+    rule: 'kimi-k2.6-temperature-by-thinking',
+    source: KIMI_SOURCE,
+    matches: (m) => /^kimi[-_.]?k-?2[-_.]?6(?:[-_.]|$)/.test(m),
+    capability: {
+      // 思考模式 1.0 / 非思考 0.6；本插件的结构化任务默认关闭思考，故取 0.6 不安全，
+      // 统一收敛到 1.0（思考档），避免"关思考却给 1.0"这类组合出错。
+      fixedTemperature: 1,
+      supportsReasoning: false,
+      reasoningControl: 'thinking',
+    },
+  },
+  {
+    rule: 'deepseek-reasoner-fixed-temperature',
+    source: 'OpenAI 兼容约定：DeepSeek R1/reasoner 不接受自定义 temperature',
+    matches: (m) => /^deepseek[-_.]?(r1|reasoner)(?:[-_.]|$)/.test(m),
+    capability: { fixedTemperature: 1, supportsReasoning: true, reasoningControl: 'reasoning-effort' },
+  },
+]
+
+/**
+ * 解析一条模型的能力约束。
+ * @param model - 模型 id（可能带供应商前缀）。
+ * @returns 命中的能力；无约束时返回 undefined。
+ */
+export function resolveModelCapability(model: string | undefined): ModelCapability | undefined {
+  const canonical = canonicalModelId(model)
+  if (canonical === '') return undefined
+  for (const rule of RULES) {
+    if (rule.matches(canonical)) return { ...rule.capability, rule: rule.rule, source: rule.source }
+  }
+  return 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 function convergeRequestParams(
+  params: RequestParams,
+  model: string | undefined,
+  options: { structured?: boolean; omitFixedTemperature?: boolean } = {},
+): ConvergedParams {
+  const capability = resolveModelCapability(model)
+  const adjustments: string[] = []
+  let temperature: number | undefined = params.temperature
+  let reasoningEffort = params.reasoningEffort
+
+  if (capability?.fixedTemperature !== undefined) {
+    const fixed = capability.fixedTemperature
+    if (options.omitFixedTemperature === true) {
+      if (temperature !== undefined) {
+        adjustments.push(`temperature: ${temperature} -> 省略（${capability.rule} 固定 ${fixed}，厂商建议不要显式传入）`)
+      }
+      temperature = undefined
+    } else if (temperature !== fixed) {
+      adjustments.push(`temperature: ${temperature} -> ${fixed}（${capability.rule} 固定值）`)
+      temperature = fixed
+    }
+  } else if (capability !== undefined) {
+    const min = capability.minTemperature ?? 0
+    const max = capability.maxTemperature ?? 2
+    const clamped = Math.min(max, Math.max(min, temperature ?? min))
+    if (clamped !== temperature) {
+      adjustments.push(`temperature: ${temperature} -> ${clamped}（${capability.rule} 取值范围）`)
+      temperature = clamped
+    }
+  }
+
+  // 不支持 reasoning_effort 的模型：不得下发该参数，否则厂商直接报错。
+  if (capability?.supportsReasoning === false && reasoningEffort !== undefined) {
+    if (reasoningEffort !== 'off') {
+      adjustments.push(`reasoningEffort: ${reasoningEffort} -> 省略（${capability.rule} 不支持该参数）`)
+    }
+    reasoningEffort = undefined
+  }
+
+  // 严格结构化任务：能力档案要求关闭思考时，覆盖用户偏好（输出稳定性优先）。
+  if (options.structured === true && capability?.reasoningForcedOff === true && reasoningEffort !== undefined) {
+    adjustments.push(`reasoningEffort: ${reasoningEffort} -> off（结构化任务强制关闭思考）`)
+    reasoningEffort = 'off'
+    // 该模型通过 thinking 控制且不可禁用：等价于不传任何推理参数。
+    if (capability.reasoningControl === 'thinking') reasoningEffort = undefined
+  }
+
+  return {
+    temperature,
+    reasoningEffort,
+    adjustments,
+    ...(capability === undefined ? {} : { rule: capability.rule, source: capability.source }),
+  }
+}

package/src/novel-context.ts

@@ -0,0 +1,286 @@
+/**
+ * 统一上下文组装与相关设定检索
+ *
+ * 取代各阶段各自拼装 prompt，消除「生成看得到、审稿看不到」的断层。
+ * 所有阶段通过 buildChapterContext 获取同一来源的事实与设定。
+ */
+
+import type { ProjectState, ChapterPlan, StoryBible, RoleRecord, ChapterFact, Foreshadow, Plotline } from './protocol'
+import { readFileSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+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 function retrieveRelatedFacts(
+  facts: ChapterFact[],
+  beatsText: string,
+  roleNames: string[],
+  limit = 15,
+): string[] {
+  if (facts.length === 0) return []
+
+  const trigrams = (s: string): Set<string> => {
+    const out = new Set<string>()
+    for (let i = 0; i + 3 <= s.length; i++) {
+      const tri = s.slice(i, i + 3)
+      if (tri.trim() !== '') out.add(tri)
+    }
+    return out
+  }
+
+  const beatsTri = trigrams(beatsText)
+  const beatRoles = roleNames.filter(n => beatsText.includes(n))
+
+  const recentTexts = new Set(facts.slice(-20).map(f => f.text))
+
+  return facts
+    .map((f, idx) => {
+      const head = f.text.slice(0, 80)
+      let score = 0
+      for (const tri of trigrams(head)) if (beatsTri.has(tri)) score += 1
+      if (beatRoles.length > 0) {
+        for (const n of beatRoles) if (head.includes(n)) score += 8
+      }
+      // 近因加权：越新越优先（封顶 40 章）
+      score += Math.min(idx, 40) / 10
+      return { f, score }
+    })
+    .filter(x => x.score >= 3)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, limit)
+    .map(x => `[第${x.f.chapterNo}章] ${x.f.text}`)
+    .filter(t => !recentTexts.has(t.slice(t.indexOf(']') + 2)))
+}
+
+/**
+ * 相关角色检索：beats 中出现的角色 + 主角/主要反派永远全量
+ */
+export function retrieveRelevantRoles(
+  bible: StoryBible | undefined,
+  roles: RoleRecord[] | undefined,
+  beatsText: string,
+): ChapterContext['relevantRoles'] {
+  const result: ChapterContext['relevantRoles'] = []
+  const seen = new Set<string>()
+
+  // 主角/主要反派永远全量
+  const alwaysRoles = (bible?.characters ?? []).filter(c =>
+    c.role === 'protagonist' || c.role === 'antagonist'
+  )
+  for (const card of alwaysRoles) {
+    if (seen.has(card.name)) continue
+    seen.add(card.name)
+    result.push({
+      name: card.name,
+      role: card.role,
+      traits: card.traits,
+      goals: card.goals !== '' ? card.goals : undefined,
+      knowledge: Array.isArray(card.knowledge) && card.knowledge.length > 0 ? card.knowledge : undefined,
+    })
+  }
+
+  // beats 中出现的角色
+  const beatRoles = (bible?.characters ?? []).filter(c => beatsText.includes(c.name))
+  for (const card of beatRoles) {
+    if (seen.has(card.name)) continue
+    seen.add(card.name)
+    result.push({
+      name: card.name,
+      role: card.role,
+      traits: card.traits,
+      goals: card.goals !== '' ? card.goals : undefined,
+      knowledge: Array.isArray(card.knowledge) && card.knowledge.length > 0 ? card.knowledge : undefined,
+    })
+  }
+
+  // 角色库补充（不在道藏里的）
+  for (const r of roles ?? []) {
+    if (seen.has(r.name)) continue
+    if (!beatsText.includes(r.name) && r.roleLabel !== 'protagonist' && r.roleLabel !== 'antagonist') continue
+    seen.add(r.name)
+    result.push({
+      name: r.name,
+      role: r.roleLabel,
+      traits: Array.isArray(r.traits) ? r.traits : [],
+      goals: r.goals !== undefined && r.goals !== '' ? r.goals : undefined,
+    })
+  }
+
+  return result
+}
+
+/**
+ * 构建章节统一上下文
+ *
+ * 各阶段调用此函数获取同一来源的事实与设定，消除上下文断层。
+ * 检索结果不足时自动回退全量，保证不丢失关键信息。
+ */
+export function buildChapterContext(
+  project: ProjectState,
+  chapter: ChapterPlan,
+  outputDir: string,
+  options: ContextBuildOptions = {},
+): ChapterContext {
+  const {
+    fullRoleCards = true,
+    relatedFactsLimit = 15,
+    recentFactsLimit = 20,
+  } = options
+
+  const bible = project.bible
+  const allFacts = project.facts ?? []
+  const roleNames = (project.roles ?? []).map(r => r.name).filter((n): n is string => typeof n === 'string' && n !== '')
+
+  // 上一章结尾 + 摘要
+  let prevChapterTail = ''
+  let prevChapterSummary: string | undefined
+  const prev = project.chapters.find(c => c.no === chapter.no - 1)
+  if (prev?.file !== undefined) {
+    try {
+      const prevPath = join(outputDir, prev.file)
+      if (existsSync(prevPath)) {
+        const text = readFileSync(prevPath, 'utf8')
+        prevChapterTail = text.replace(/^#\s+.*$/m, '').trim().slice(-900)
+      }
+    } catch { /* 文件缺失时忽略 */ }
+  }
+  prevChapterSummary = prev?.summary
+
+  // 事实：最近 + 相关
+  const recentFacts = allFacts.slice(-recentFactsLimit).map(f => `[第${f.chapterNo}章] ${f.text}`)
+  const relatedFacts = retrieveRelatedFacts(allFacts, chapter.beats, roleNames, relatedFactsLimit)
+
+  // 角色：相关角色
+  const relevantRoles = retrieveRelevantRoles(bible, project.roles, chapter.beats)
+
+  // 道藏规则：全部（规则数量通常不多，全量注入更安全）
+  const relevantWorldRules = bible?.worldRules ?? []
+
+  // 活跃剧情线
+  const activePlotlines = (project.plotlines ?? []).filter(l =>
+    l.status === 'active' || l.status === 'paused'
+  )
+
+  // 未回收伏笔
+  const activeForeshadows = (project.foreshadows ?? []).filter(f =>
+    f.status === 'planted' || f.status === 'progressing'
+  )
+
+  // 当前卷大纲
+  const volumeNo = chapter.volume ?? 0
+  const volume = project.volumes?.find(v => v.no === volumeNo)
+  const currentVolumeOutline = volume !== undefined
+    ? `第${volume.no}卷《${volume.title}》：${volume.summary}`
+    : ''
+
+  return {
+    complianceRedLines: [], // 由调用方注入 COMPLIANCE_REDLINES
+    bookRedLines: bible?.redLines ?? [],
+    relevantRoles: fullRoleCards ? relevantRoles : relevantRoles.map(r => ({ name: r.name, role: r.role, traits: [] })),
+    relevantWorldRules,
+    activePlotlines,
+    activeForeshadows,
+    prevChapterTail,
+    prevChapterSummary,
+    recentFacts,
+    relatedFacts,
+    currentVolumeOutline,
+    beats: chapter.beats,
+    chapterTitle: chapter.title,
+  }
+}
+
+/**
+ * 将上下文渲染为 prompt 文本块
+ * 各阶段可按需选择注入哪些块。
+ */
+export function renderContextBlocks(ctx: ChapterContext): {
+  rolesBlock: string
+  worldRulesBlock: string
+  factsBlock: string
+  plotlinesBlock: string
+  foreshadowsBlock: string
+  continuityBlock: string
+  redLinesBlock: string
+} {
+  const roleName = { protagonist: '主角', supporting: '配角', antagonist: '反派', other: '其他', female_lead: '女主', female_support: '女配', support: '配角', extra: '路人' } as Record<string, string>
+
+  const rolesBlock = ctx.relevantRoles.length > 0
+    ? '==================== 相关角色卡 ====================\n' +
+      ctx.relevantRoles.map(r =>
+        `- ${r.name}（${roleName[r.role] ?? r.role}）：${r.traits.join('、')}${r.goals ? `；目标：${r.goals}` : ''}${r.knowledge ? `\n  已知信息：${r.knowledge.join('；')}（未列出的该角色不知道）` : ''}`
+      ).join('\n')
+    : ''
+
+  const worldRulesBlock = ctx.relevantWorldRules.length > 0
+    ? '==================== 世界规则 ====================\n' + ctx.relevantWorldRules.map(r => `- ${r}`).join('\n')
+    : ''
+
+  const factsBlock = (ctx.recentFacts.length > 0 || ctx.relatedFacts.length > 0)
+    ? '==================== 事实库（最近 + 相关） ====================\n' +
+      (ctx.recentFacts.length > 0 ? `【最近 ${ctx.recentFacts.length} 条】\n${ctx.recentFacts.join('\n')}` : '') +
+      (ctx.relatedFacts.length > 0 ? `\n【相关旧事实 ${ctx.relatedFacts.length} 条】\n${ctx.relatedFacts.join('\n')}` : '')
+    : ''
+
+  const plotlinesBlock = ctx.activePlotlines.length > 0
+    ? '==================== 活跃剧情线 ====================\n' +
+      ctx.activePlotlines.map(l => `- [${l.kind}${l.status === 'paused' ? '·暂停' : ''}] ${l.name}：${l.goal}${l.progress ? `（进度：${l.progress}）` : ''}`).join('\n')
+    : ''
+
+  const foreshadowsBlock = ctx.activeForeshadows.length > 0
+    ? '==================== 活跃伏笔 ====================\n' +
+      ctx.activeForeshadows.map(f => `- [${f.status === 'planted' ? '已埋设' : '推进中'}] ${f.description}${f.targetChapter ? `（预计第${f.targetChapter}章回收）` : ''}`).join('\n')
+    : ''
+
+  const continuityBlock = ctx.prevChapterTail !== ''
+    ? `==================== 上一章结尾（紧接此状态继续） ====================\n${ctx.prevChapterTail}`
+    : ''
+
+  const redLinesBlock = ctx.bookRedLines.length > 0
+    ? '==================== 本书红线 ====================\n' + ctx.bookRedLines.map(r => `- ${r}`).join('\n')
+    : ''
+
+  return { rolesBlock, worldRulesBlock, factsBlock, plotlinesBlock, foreshadowsBlock, continuityBlock, redLinesBlock }
+}

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('；')}。每个字段只保留完成本阶段决策所需的信息，写完后立即结束输出，不要展开细纲或重复说明。`
+}