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

package/src/global-assets.ts

@@ -0,0 +1,59 @@
+/**
+ * 全局资源库（跨书可复用的自定义题材/推进模式）。
+ * 雷达「同步底座到全局资源库」写入此处；/assets 返回时与内置库合并展示。
+ */
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import type { GenreNode, ProgressionMode } from './protocol.ts'
+
+interface GlobalAssets {
+  genres: GenreNode[]
+  modes: ProgressionMode[]
+}
+
+const FILE = join(homedir(), '.dsh', 'novel-forge-global-assets.json')
+let cache: GlobalAssets | null = null
+
+function load(): GlobalAssets {
+  if (cache !== null) return cache
+  try {
+    const raw = readFileSync(FILE, 'utf8')
+    const parsed = JSON.parse(raw) as Partial<GlobalAssets>
+    cache = { genres: Array.isArray(parsed.genres) ? parsed.genres : [], modes: Array.isArray(parsed.modes) ? parsed.modes : [] }
+  } catch {
+    cache = { genres: [], modes: [] }
+  }
+  return cache
+}
+
+function persist(): void {
+  if (cache === null) return
+  mkdirSync(join(homedir(), '.dsh'), { recursive: true })
+  writeFileSync(FILE, JSON.stringify(cache, null, 2), 'utf8')
+}
+
+export function globalGenreLibrary(): GenreNode[] {
+  return load().genres
+}
+
+export function globalProgressionLibrary(): ProgressionMode[] {
+  return load().modes
+}
+
+/** 新增/已有则跳过；返回 true=新增。 */
+export function addGlobalGenre(g: GenreNode): boolean {
+  const lib = load()
+  if (lib.genres.some(x => x.name === g.name)) return false
+  lib.genres.push({ ...g, children: g.children ?? [] })
+  persist()
+  return true
+}
+
+export function addGlobalMode(m: ProgressionMode): boolean {
+  const lib = load()
+  if (lib.modes.some(x => x.name === m.name)) return false
+  lib.modes.push({ ...m, payoffs: m.payoffs ?? [], risks: m.risks ?? [], primary: m.primary ?? false })
+  persist()
+  return true
+}

package/src/index.ts

@@ -7,8 +7,10 @@
  * changes.
  */
 
+import { homedir } from 'node:os'
+import { join } from 'node:path'
 import type { Context } from '@deepseek-ai/cordis'
-import { installSettingsSection, settingsNamespace } from '@deepseek-ai/dsh-settings'
+import type {} from '@deepseek-ai/dsh-settings'
 import z from 'schemastery'
 import type {} from '@deepseek-ai/dsh-host-webserver'
 import type {} from '@deepseek-ai/dsh-llm'
@@ -16,19 +18,20 @@ import type {} from '@deepseek-ai/dsh-system-prompt'
 import type { ConfigPatch, NovelConfig } from './protocol.ts'
 import { makeRoutes } from './routes.ts'
 import { activeBookOutputDir } from './bookshelf.ts'
+import { loadProject } from './engine.ts'
 
 /** Stable cordis plugin name. */
 export const name = 'novel-forge'
 
 /** Services required before the novel-forge surfaces can mount. */
-export const inject = ['webServer', 'llm', 'systemPrompt']
+export const inject = ['webServer', 'llm', 'systemPrompt', 'settings']
 
 /**
  * Settings namespace of the novel-forge capability — the section the web
  * settings surface edits. Spelled here rather than imported: the browser half
  * spells the same value and must not depend on a Host package.
  */
-export const NOVEL_SETTINGS_NAMESPACE = settingsNamespace('dsh-novel-forge')
+export const NOVEL_SETTINGS_NAMESPACE = 'dsh-novel-forge' as const
 
 /** Plugin config, validated by the same-named schemastery schema. */
 export interface Config {
@@ -44,8 +47,20 @@ export interface Config {
   provider?: string
   /** LLM model id. */
   model?: string
+  /** 任务级模型路由：正文生成模型（留空则跟随 model）。 */
+  generateModel?: string
+  /** 任务级模型路由：审稿模型（留空则跟随 model）。 */
+  reviewModel?: string
+  /** 任务级模型路由：质检模型（留空则跟随 model）。 */
+  auditModel?: string
+  /** 备用模型：主模型失败时自动切换重试一次（留空 = 不切换）。 */
+  fallbackModel?: string
+  /** 出章后自动抽取故事时间线（默认开）。 */
+  autoTimeline?: boolean
   /** LLM reasoning effort (off/low/high/max). */
   reasoningEffort?: 'off' | 'low' | 'high' | 'max'
+  /** 分析类任务（提炼/拆书/反推大纲等）的推理档位；默认 low。 */
+  analysisReasoning?: 'off' | 'low' | 'high' | 'max'
   /** Target characters per chapter. */
   chapterChars?: number
   /** Max output tokens per chapter call. */
@@ -58,40 +73,52 @@ export interface Config {
   autoAuthorReview?: boolean
   /** 修订/润色产出草稿后自动附带一次 AI 审查（默认开，可在设置页关闭省 token）。 */
   autoReviewAfterRevise?: boolean
-  /** 豆包/Seedream 生图 API Key。 */
-  imageApiKey?: string
-  /** 豆包/Seedream 生图模型 ID。 */
-  imageApiModel?: string
-  /** 是否启用豆包生图（默认关）。 */
-  imageApiEnabled?: boolean
+  /** 自定义背景图（URL / dataURL / 服务端路径引用）。 */
+  themeBackground?: string
+  /** 自定义背景遮罩/模糊强度 0-80。 */
+  themeBackgroundBlur?: number
+  /** 玻璃透明度 0-100（100=当前原样）。 */
+  themeOpacity?: number
+  /** 是否启用改编模式（默认关闭）。 */
+  enableAdaptMode?: boolean
 }
 
 export const Config: z<Config> = z.object({
   announceToAgent: z.boolean().default(true),
   enabled: z.boolean().default(true),
-  outlinePath: z.string().default('D:\\ryan work\\harness\\novels\\归墟玉主\\《归墟玉主》全书大纲_重新排版版.docx'),
-  outputDir: z.string().default('D:\\ryan work\\harness\\novels\\归墟玉主'),
+  outlinePath: z.string().default(''),
+  outputDir: z.string().default(join(homedir(), '.dsh', 'novels')),
   provider: z.string().default('deepseek-official'),
-  model: z.string().default('deepseek-v4-flash'),
+  model: z.string().default('deepseek-flash'),
+  generateModel: z.string().default(''),
+  reviewModel: z.string().default(''),
+  auditModel: z.string().default(''),
+  fallbackModel: z.string().default(''),
+  autoTimeline: z.boolean().default(true),
   reasoningEffort: z.union(['off', 'low', 'high', 'max']).default('off'),
+  analysisReasoning: z.union(['off', 'low', 'high', 'max']).default('low'),
   chapterChars: z.number().default(3500),
   maxTokens: z.number().default(12000),
   reviewPassScore: z.number().default(70),
   autoReview: z.boolean().default(true),
   autoAuthorReview: z.boolean().default(true),
   autoReviewAfterRevise: z.boolean().default(true),
-  imageApiKey: z.string().default(''),
-  imageApiModel: z.string().default(''),
-  imageApiEnabled: z.boolean().default(false),
+  themeBackground: z.string().default(''),
+  themeBackgroundBlur: z.number().default(0),
+  themeOpacity: z.number().default(100),
+  enableAdaptMode: z.boolean().default(true),
 })
 
 /** Schema defaults, re-read for hand-built test contexts. */
 const DEFAULT_ANNOUNCE = true
-const DEFAULT_OUTLINE_PATH = 'D:\\ryan work\\harness\\novels\\归墟玉主\\《归墟玉主》全书大纲_重新排版版.docx'
-const DEFAULT_OUTPUT_DIR = 'D:\\ryan work\\harness\\novels\\归墟玉主'
+const DEFAULT_OUTLINE_PATH = ''
+const DEFAULT_OUTPUT_DIR = join(homedir(), '.dsh', 'novels')
 const DEFAULT_PROVIDER = 'deepseek-official'
-const DEFAULT_MODEL = 'deepseek-v4-flash'
+const DEFAULT_MODEL = 'deepseek-flash'
 const DEFAULT_REASONING_EFFORT = 'off' as const
+const DEFAULT_ANALYSIS_REASONING = 'low' as const
+const DEFAULT_FALLBACK_MODEL = ''
+const DEFAULT_AUTO_TIMELINE = true
 const DEFAULT_CHAPTER_CHARS = 3500
 const DEFAULT_MAX_TOKENS = 12000
 const DEFAULT_REVIEW_PASS_SCORE = 70
@@ -103,7 +130,7 @@ const DEFAULT_AUTO_REVIEW_AFTER_REVISE = true
 const SECTION_ORDER = 160
 
 /** Model-facing announcement: plugin presence, capabilities, and limits. */
-export const NOVEL_GUIDANCE = '本机已安装 dsh-novel-forge 插件（AI 编译小说工作台）：侧边栏「小说工坊」入口。能力：读取 docx 大纲（默认 D:\\ryan work\\harness\\novels\\归墟玉主 大纲）或粘贴大纲文本；用 LLM 提炼道藏（人设/世界观/金手指规则/写作红线，即设定圣经）；生成卷计划与章节计划；逐章调用 LLM 生成 3000-4000 字正文并保存为 Markdown（默认输出到 D:\\ryan work\\harness\\novels\\归墟玉主）；每章自动生成摘要（叙事记忆）、自动 AI 审稿（人设/设定/红线/文笔/爽点/逻辑），支持按审稿意见重写、去 AI 味润色、暗线（伏笔）管理、批量连写与全本导出（txt/md）。限制：生成消耗 LLM API 额度；输出目录与模型可在插件设置中修改；章节正文质量取决于大纲完整度。用户提到「小说 / 大纲 / 写小说 / 章节 / 审稿 / 润色 / 归墟玉主」时即指本插件，请据此协作。'
+export const NOVEL_GUIDANCE = '本机已安装 dsh-novel-forge 插件（AI 编译小说工作台）：侧边栏「小说工坊」入口。能力：读取 docx 大纲、粘贴大纲文本或把 txt 全本拆章导入；用 LLM 提炼道藏（人设/世界观/金手指规则/写作红线）与大世界（境界/区域/势力）；生成卷计划与结构化章节计划（本章目标/剧情要点/必达项/义务合约/章末钩子）；逐章生成 3000-4000 字正文并保存为 Markdown（默认输出到用户主目录 ~/.dsh/novels）；每章自动生成摘要与编年录事实、抽取故事时间线（故事内时间/地点/在场角色/事件）、自动 AI 审稿（人设/设定/红线/文笔/爽点/逻辑/反 AI/呈现/合规九维）与作者复盘；支持按审稿意见合并修订（审稿 high + 时间线矛盾 + 张力偏差合成一轮，每章最多两轮后转人工）、去 AI 味润色、章节历史版本回滚、暗线（伏笔）管理、剧情线与角色库、张力曲线、全书一致性质检与敏感词扫描、分范围导出与项目备份、批量连写（生产单，可暂停/续跑）。限制：所有 AI 操作消耗 LLM API 额度；输出目录与模型可在插件设置中修改；章节正文质量取决于大纲完整度；张力/时间线问题默认只是建议（写日志与待办），不会自动改正文。用户提到「小说 / 大纲 / 写小说 / 章节 / 审稿 / 润色」时即指本插件，请据此协作。'
 
 /** Resolve a config-like value into the full runtime config. */
 export function resolveConfig(value: Partial<Config> | undefined): NovelConfig {
@@ -112,16 +139,23 @@ export function resolveConfig(value: Partial<Config> | undefined): NovelConfig {
     outputDir: value?.outputDir ?? DEFAULT_OUTPUT_DIR,
     provider: value?.provider ?? DEFAULT_PROVIDER,
     model: value?.model ?? DEFAULT_MODEL,
+    generateModel: value?.generateModel,
+    reviewModel: value?.reviewModel,
+    auditModel: value?.auditModel,
+    fallbackModel: value?.fallbackModel ?? DEFAULT_FALLBACK_MODEL,
+    autoTimeline: value?.autoTimeline ?? DEFAULT_AUTO_TIMELINE,
     reasoningEffort: value?.reasoningEffort ?? DEFAULT_REASONING_EFFORT,
+    analysisReasoning: value?.analysisReasoning ?? DEFAULT_ANALYSIS_REASONING,
     chapterChars: value?.chapterChars ?? DEFAULT_CHAPTER_CHARS,
     maxTokens: value?.maxTokens ?? DEFAULT_MAX_TOKENS,
     reviewPassScore: value?.reviewPassScore ?? DEFAULT_REVIEW_PASS_SCORE,
     autoReview: value?.autoReview ?? DEFAULT_AUTO_REVIEW,
     autoAuthorReview: value?.autoAuthorReview ?? DEFAULT_AUTO_AUTHOR_REVIEW,
     autoReviewAfterRevise: value?.autoReviewAfterRevise ?? DEFAULT_AUTO_REVIEW_AFTER_REVISE,
-    imageApiKey: value?.imageApiKey,
-    imageApiModel: value?.imageApiModel,
-    imageApiEnabled: value?.imageApiEnabled ?? false,
+    themeBackground: value?.themeBackground ?? '',
+    themeBackgroundBlur: value?.themeBackgroundBlur ?? 0,
+    themeOpacity: value?.themeOpacity ?? 100,
+    enableAdaptMode: value?.enableAdaptMode ?? true,
   }
 }
 
@@ -138,10 +172,22 @@ export function apply(ctx: Context, config?: Config): void {
     const resolved = resolveConfig(current())
     // 书架激活的书优先决定输出目录（settings 仍可改默认值）。
     const shelfDir = activeBookOutputDir()
-    if (shelfDir !== undefined) {
-      return { ...resolved, outputDir: shelfDir }
-    }
-    return resolved
+    if (shelfDir === undefined) return resolved
+    // 本书参数覆盖（novel-project.json.bookSettings；未设字段回退全局）。
+    const bs = loadProject(shelfDir)?.bookSettings
+    const book: NovelConfig = { ...resolved, outputDir: shelfDir }
+    if (bs === undefined) return book
+    if (bs.provider !== undefined) book.provider = bs.provider
+    if (bs.model !== undefined) book.model = bs.model
+    if (bs.reasoningEffort !== undefined) book.reasoningEffort = bs.reasoningEffort
+    if (bs.analysisReasoning !== undefined) book.analysisReasoning = bs.analysisReasoning
+    if (bs.chapterChars !== undefined) book.chapterChars = bs.chapterChars
+    if (bs.maxTokens !== undefined) book.maxTokens = bs.maxTokens
+    if (bs.reviewPassScore !== undefined) book.reviewPassScore = bs.reviewPassScore
+    if (bs.autoReview !== undefined) book.autoReview = bs.autoReview
+    if (bs.autoAuthorReview !== undefined) book.autoAuthorReview = bs.autoAuthorReview
+    if (bs.autoReviewAfterRevise !== undefined) book.autoReviewAfterRevise = bs.autoReviewAfterRevise
+    return book
   }
 
   const patchConfig = async (patch: ConfigPatch): Promise<NovelConfig> => {
@@ -150,16 +196,23 @@ export function apply(ctx: Context, config?: Config): void {
     if (patch.outputDir !== undefined) next.outputDir = patch.outputDir
     if (patch.provider !== undefined) next.provider = patch.provider
     if (patch.model !== undefined) next.model = patch.model
+    if (patch.generateModel !== undefined) next.generateModel = patch.generateModel
+    if (patch.reviewModel !== undefined) next.reviewModel = patch.reviewModel
+    if (patch.auditModel !== undefined) next.auditModel = patch.auditModel
+    if (patch.fallbackModel !== undefined) next.fallbackModel = patch.fallbackModel
+    if (patch.autoTimeline !== undefined) next.autoTimeline = patch.autoTimeline
     if (patch.reasoningEffort !== undefined) next.reasoningEffort = patch.reasoningEffort
+    if (patch.analysisReasoning !== undefined) next.analysisReasoning = patch.analysisReasoning
     if (patch.chapterChars !== undefined) next.chapterChars = patch.chapterChars
     if (patch.maxTokens !== undefined) next.maxTokens = patch.maxTokens
     if (patch.reviewPassScore !== undefined) next.reviewPassScore = patch.reviewPassScore
     if (patch.autoReview !== undefined) next.autoReview = patch.autoReview
     if (patch.autoAuthorReview !== undefined) next.autoAuthorReview = patch.autoAuthorReview
     if (patch.autoReviewAfterRevise !== undefined) next.autoReviewAfterRevise = patch.autoReviewAfterRevise
-    if (patch.imageApiKey !== undefined) next.imageApiKey = patch.imageApiKey
-    if (patch.imageApiModel !== undefined) next.imageApiModel = patch.imageApiModel
-    if (patch.imageApiEnabled !== undefined) next.imageApiEnabled = patch.imageApiEnabled
+    if (patch.themeBackground !== undefined) next.themeBackground = patch.themeBackground
+    if (patch.themeBackgroundBlur !== undefined) next.themeBackgroundBlur = patch.themeBackgroundBlur
+    if (patch.themeOpacity !== undefined) next.themeOpacity = patch.themeOpacity
+    if (patch.enableAdaptMode !== undefined) next.enableAdaptMode = patch.enableAdaptMode
     // Persist through the settings seam when available; otherwise keep in memory.
     // (ctx.get is the non-strict service access — no inject requirement, same
     // pattern installSettingsSection itself uses.)
@@ -193,7 +246,7 @@ export function apply(ctx: Context, config?: Config): void {
         text: NOVEL_GUIDANCE,
       })
     }
-    const routes = makeRoutes({ ctx, getConfig: resolve, patchConfig })
+    const routes = makeRoutes({ ctx, getConfig: resolve, patchConfig, rawConfig: () => current() })
     disposeRoutes = ctx.effect(
       () => {
         const disposers = routes.map(route => ctx.webServer.register(route))
@@ -204,7 +257,7 @@ export function apply(ctx: Context, config?: Config): void {
     void value
   }
 
-  installSettingsSection(ctx, NOVEL_SETTINGS_NAMESPACE, Config, config ?? {}, {
+  ctx.settings.installSection(ctx, NOVEL_SETTINGS_NAMESPACE, Config, config ?? {}, {
     setSource: (source) => {
       current = source
       sync()
@@ -214,10 +267,13 @@ export function apply(ctx: Context, config?: Config): void {
 
   // 运行时 skill：章节批量生产与值守处理（只在本插件环境可用）。
   // 通过 ctx.get('skills') 获取注册表（服务存在时注册，缺失则跳过，不影响其他能力）。
-  const skillsService = ctx.get('skills') as { register?: (skill: { name: string; description: string; content: string }) => () => void } | undefined
-  if (skillsService?.register !== undefined) {
+  const skillsService = ctx.get('skills') as { register?: (skill: { name: string; provider: string; description: string; content: string }) => () => void } | undefined
+  // [disabled 2026-09-05] 运行时 skill 注册按用户要求暂时关闭（排查 .length 报错）。
+  const enableRuntimeSkill: boolean = false
+  if (enableRuntimeSkill && skillsService !== undefined && skillsService.register !== undefined) {
     const disposeSkill = skillsService.register({
       name: 'novel-forge-chapter-batch',
+      provider: 'dsh-novel-forge',
       description: '批量生成小说章节并值守处理审稿未过的章节（豁免/按意见修订/验证模式/重新生成），依赖 dsh-novel-forge 的 /api/dsh-novel-forge/* 路由。',
       content: [
         '# 小说章节批量生产与值守处理',

package/src/llm-live.ts

@@ -0,0 +1,260 @@
+/**
+ * LLM 实况 feed：以「每次 LLM 调用」为粒度，把生命周期事件（开始/流式正文/阶段变化/完成）
+ * 推给订阅者，并提供环形缓冲供新连上的客户端重放。
+ *
+ * 同时承担三件与用量有关的事（进程内，不落盘）：
+ *   1) **用量账本**：每次调用结束后按用途累计 token / 耗时，供 /status 展示；
+ *   2) **Prompt 记录**：保存每次调用实际发送的 system + user（环形，按需查询）；
+ *   3) **首字耗时**：调用方在拿到第一个文本增量时打点，用于观察模型响应速度。
+ */
+
+import type { BlockAssembler, TokenUsage } from '@deepseek-ai/dsh-llm'
+import type {
+  LlmLiveFrame,
+  LlmPromptRecord,
+  LlmTokenUsage,
+  LlmUsageBucket,
+  LlmUsageSummary,
+} from './protocol.ts'
+
+export type { LlmLiveFrame }
+
+export type LlmLivePhase = 'requesting' | 'streaming' | 'completed' | 'failed'
+
+/** 帧缓冲上限（新连接重放用）。 */
+const MAX_BUFFER = 400
+/** Prompt 记录上限（环形，避免长跑吃内存）。 */
+const MAX_PROMPTS = 40
+/** 单条 Prompt 记录的最大字符数（system + user 合计），超出截断并标记。 */
+const MAX_PROMPT_CHARS = 60_000
+
+let buffer: LlmLiveFrame[] = []
+type Listener = (frame: LlmLiveFrame) => void
+let listeners = new Set<Listener>()
+let seq = 0
+
+/** 进程内用量账本。 */
+const usageTotals = {
+  calls: 0,
+  failed: 0,
+  inputTokens: 0,
+  outputTokens: 0,
+  reasoningTokens: 0,
+  totalTokens: 0,
+  elapsedMs: 0,
+  callsWithoutUsage: 0,
+  byLabel: new Map<string, LlmUsageBucket>(),
+}
+
+/** Prompt 记录（按 sessionId，保留最近 MAX_PROMPTS 条）。 */
+const prompts = new Map<string, LlmPromptRecord>()
+
+export function nextSessionId(): string {
+  seq++
+  return `ll-${Date.now().toString(36)}-${seq}`
+}
+
+export function subscribeLiveFeed(listener: Listener): () => void {
+  // 先重放现有缓冲（新连接能立即看到最近调用），再进入实时。
+  for (const frame of buffer) listener(frame)
+  listeners.add(listener)
+  return () => { listeners.delete(listener) }
+}
+
+export function emitLive(frame: LlmLiveFrame): void {
+  if (frame.type === 'session_completed') recordUsage(frame)
+  buffer.push(frame)
+  if (buffer.length > MAX_BUFFER) buffer = buffer.slice(-MAX_BUFFER)
+  for (const l of listeners) l(frame)
+}
+
+export function liveLatest(): LlmLiveFrame[] {
+  return [...buffer]
+}
+
+export function clearLiveFeed(): void {
+  buffer = []
+}
+
+// ------------------------------------------------------------------ 用量账本
+
+/** 把 dsh-llm 的 usage 转成线上形状。 */
+export function toLiveUsage(usage: TokenUsage | undefined): LlmTokenUsage | undefined {
+  if (usage === undefined) return undefined
+  return {
+    inputTokens: usage.inputTokens ?? 0,
+    outputTokens: usage.outputTokens ?? 0,
+    totalTokens: usage.totalTokens ?? (usage.inputTokens ?? 0) + (usage.outputTokens ?? 0),
+    reasoningTokens: usage.reasoningTokens ?? 0,
+    cacheReadTokens: usage.cacheReadTokens ?? 0,
+  }
+}
+
+/** 记一次已完成的调用（由 emitLive 内部调用）。 */
+function recordUsage(frame: LlmLiveFrame): void {
+  const failed = frame.phase === 'failed' ? 1 : 0
+  const usage = frame.usage
+  usageTotals.calls += 1
+  usageTotals.failed += failed
+  usageTotals.elapsedMs += frame.elapsedMs ?? 0
+  if (usage === undefined) {
+    usageTotals.callsWithoutUsage += 1
+  } else {
+    usageTotals.inputTokens += usage.inputTokens
+    usageTotals.outputTokens += usage.outputTokens
+    usageTotals.reasoningTokens += usage.reasoningTokens ?? 0
+    usageTotals.totalTokens += usage.totalTokens ?? usage.inputTokens + usage.outputTokens
+  }
+  const label = frame.label ?? '未标注调用'
+  const bucket = usageTotals.byLabel.get(label) ?? { label, calls: 0, failed: 0, inputTokens: 0, outputTokens: 0, reasoningTokens: 0, elapsedMs: 0 }
+  bucket.calls += 1
+  bucket.failed += failed
+  bucket.elapsedMs += frame.elapsedMs ?? 0
+  if (usage !== undefined) {
+    bucket.inputTokens += usage.inputTokens
+    bucket.outputTokens += usage.outputTokens
+    bucket.reasoningTokens += usage.reasoningTokens ?? 0
+  }
+  usageTotals.byLabel.set(label, bucket)
+}
+
+/** 本次运行的用量汇总（按耗时降序排列用途，便于看谁最贵）。 */
+export function liveUsage(): LlmUsageSummary {
+  return {
+    calls: usageTotals.calls,
+    failed: usageTotals.failed,
+    inputTokens: usageTotals.inputTokens,
+    outputTokens: usageTotals.outputTokens,
+    reasoningTokens: usageTotals.reasoningTokens,
+    totalTokens: usageTotals.totalTokens,
+    elapsedMs: usageTotals.elapsedMs,
+    callsWithoutUsage: usageTotals.callsWithoutUsage,
+    byLabel: [...usageTotals.byLabel.values()].sort((a, b) =>
+      (b.inputTokens + b.outputTokens + b.reasoningTokens) - (a.inputTokens + a.outputTokens + a.reasoningTokens)),
+  }
+}
+
+/** 清零用量账本（面板「重新计数」用）。 */
+export function resetLiveUsage(): void {
+  usageTotals.calls = 0
+  usageTotals.failed = 0
+  usageTotals.inputTokens = 0
+  usageTotals.outputTokens = 0
+  usageTotals.reasoningTokens = 0
+  usageTotals.totalTokens = 0
+  usageTotals.elapsedMs = 0
+  usageTotals.callsWithoutUsage = 0
+  usageTotals.byLabel.clear()
+}
+
+// ------------------------------------------------------------- Prompt 记录
+
+/** 记一条 Prompt（超长截断并标记）。 */
+export function recordPrompt(input: { sessionId: string; label?: string; model?: string; system?: string; user?: string }): LlmPromptRecord {
+  const system = input.system ?? ''
+  const user = input.user ?? ''
+  const chars = system.length + user.length
+  let record: LlmPromptRecord = {
+    sessionId: input.sessionId,
+    label: input.label,
+    model: input.model,
+    at: new Date().toISOString(),
+    system,
+    user,
+    chars,
+  }
+  if (chars > MAX_PROMPT_CHARS) {
+    // 优先保留 user（真正随调用变化的输入），system 按剩余预算截断。
+    const userPart = user.slice(0, MAX_PROMPT_CHARS)
+    const rest = MAX_PROMPT_CHARS - userPart.length
+    record = { ...record, user: userPart, system: system.slice(0, Math.max(0, rest)), truncated: true }
+  }
+  prompts.set(record.sessionId, record)
+  while (prompts.size > MAX_PROMPTS) {
+    const oldest = prompts.keys().next().value
+    if (oldest === undefined) break
+    prompts.delete(oldest)
+  }
+  return record
+}
+
+/** 取一条 Prompt 记录（不存在返回 undefined）。 */
+export function livePrompt(sessionId: string): LlmPromptRecord | undefined {
+  return prompts.get(sessionId)
+}
+
+/** 清空 Prompt 记录。 */
+export function clearLivePrompts(): void {
+  prompts.clear()
+}
+
+// --------------------------------------------------------------- 调用打点
+
+/** 一次调用的打点句柄。 */
+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 function beginLiveCall(input: { label: string; model: string; system?: string; user?: string }): LiveCallHandle {
+  const handle: LiveCallHandle = { sessionId: nextSessionId(), startedAt: Date.now(), label: input.label, model: input.model }
+  const record = recordPrompt({ sessionId: handle.sessionId, label: input.label, model: input.model, system: input.system, user: input.user })
+  emitLive({
+    type: 'session_started',
+    sessionId: handle.sessionId,
+    label: input.label,
+    model: input.model,
+    at: new Date().toISOString(),
+    context: { interactionId: handle.sessionId },
+    hasPrompt: true,
+    promptChars: record.chars,
+  })
+  emitLive({ type: 'phase_changed', sessionId: handle.sessionId, phase: 'streaming', phaseMessage: '模型正在返回内容', at: new Date().toISOString() })
+  return handle
+}
+
+/** 首字打点（调用方在收到第一个文本增量时调用，只记第一次）。 */
+export function markFirstToken(handle: LiveCallHandle): void {
+  if (handle.firstTokenMs === undefined) handle.firstTokenMs = Date.now() - handle.startedAt
+}
+
+/**
+ * 结束一次 LLM 调用：从 assembler 取用量，发 session_completed（含 token/耗时/首字）。
+ *
+ * @param handle beginLiveCall 的句柄。
+ * @param assembler 本次调用的 BlockAssembler。
+ * @param extra 字符数/预览/失败信息等。
+ */
+export function endLiveCall(
+  handle: LiveCallHandle,
+  assembler: BlockAssembler,
+  extra: { chars?: number; preview?: string; phase?: 'completed' | 'failed'; error?: string } = {},
+): void {
+  const usage = toLiveUsage(assembler.usage)
+  emitLive({
+    type: 'session_completed',
+    sessionId: handle.sessionId,
+    label: handle.label,
+    model: handle.model,
+    at: new Date().toISOString(),
+    totalChars: extra.chars,
+    preview: extra.preview,
+    phase: extra.phase ?? 'completed',
+    error: extra.error,
+    usage,
+    elapsedMs: Date.now() - handle.startedAt,
+    firstTokenMs: handle.firstTokenMs,
+  })
+}

package/src/llm-retry.ts

@@ -0,0 +1,77 @@
+/**
+ * 模型失败恢复规则（纯逻辑，可离线单测）。
+ *
+ * 解决的问题：批量连写时，主模型偶发限流/超时/额度耗尽会让**整批中断**，
+ * 而换一个模型重试一次往往就能过去。规则：
+ *   1) 只对「可重试」错误切换模型——用户主动取消、参数/契约类错误不重试；
+ *   2) 备用模型为空或与主模型相同则不切换；
+ *   3) 备用模型也失败时，抛**原始错误**（保留主因，不掩盖现场）；
+ *   4) 每次调用最多切换一次。
+ */
+
+/** 可重试错误特征（网络/超时/限流/服务端/额度类）。 */
+const RETRYABLE_PATTERNS: readonly RegExp[] = [
+  /失败/, /超时/, /timeout/i,
+  /network|fetch failed|ECONNRESET|ECONNREFUSED|ETIMEDOUT|EPIPE|EAI_AGAIN|socket hang up|terminated/i,
+  /频繁|限流|rate\s*limit|too many requests|\b429\b|\b5\d\d\b/i,
+  /overload|unavailable|capacity|服务不可用|繁忙/i,
+  /quota|balance|credit|insufficient|额度|余额/i,
+]
+
+/** 明确不可重试的特征（用户取消 / 契约类）。 */
+const NON_RETRYABLE_PATTERNS: readonly RegExp[] = [
+  /\baborted\b|已取消|用户取消/i,
+  /不在计划中|尚未生成|参数|非法|无效|需要/i,
+]
+
+/**
+ * 判断一次 LLM 失败是否值得换模型重试。
+ *
+ * @param error 捕获到的异常。
+ * @returns 可重试时为 true。
+ */
+export function isRetryableLlmError(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error)
+  if (NON_RETRYABLE_PATTERNS.some(re => re.test(message))) return false
+  return RETRYABLE_PATTERNS.some(re => re.test(message))
+}
+
+/**
+ * 判断是否应当切换到备用模型。
+ *
+ * @param fallbackModel 配置的备用模型（空串 = 未配置）。
+ * @param primaryModel 本次实际使用的主模型。
+ * @param error 捕获到的异常。
+ * @returns 应当切换时为 true。
+ */
+export function shouldSwitchModel(fallbackModel: string | undefined, primaryModel: string, error: unknown): boolean {
+  const fallback = (fallbackModel ?? '').trim()
+  if (fallback === '' || fallback === primaryModel) return false
+  return isRetryableLlmError(error)
+}
+
+/**
+ * 用主模型执行；失败且满足切换条件时，用备用模型再执行一次。
+ *
+ * @param input 主模型 / 备用模型 / 实际执行函数（接收本次要用的模型 id）。
+ * @returns 执行结果（备用模型成功时返回其结果）。
+ * @throws 主模型失败且未切换时抛原错误；切换后仍失败时同样抛**主模型的原始错误**。
+ */
+export async function withModelFallback<T>(
+  input: { model: string; fallbackModel?: string; onSwitch?: (from: string, to: string, error: unknown) => void },
+  run: (model: string) => Promise<T>,
+): Promise<T> {
+  try {
+    return await run(input.model)
+  } catch (error) {
+    const fallback = (input.fallbackModel ?? '').trim()
+    if (fallback === '' || fallback === input.model || !isRetryableLlmError(error)) throw error
+    input.onSwitch?.(input.model, fallback, error)
+    try {
+      return await run(fallback)
+    } catch {
+      // 备用模型也失败：抛主模型的原始错误，避免掩盖第一现场。
+      throw error
+    }
+  }
+}