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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. package/README.md +4 -5
  2. package/lib/client.js +2470 -858
  3. package/lib/index.js +2155 -388
  4. package/lib/types/action-guard.d.ts +1 -1
  5. package/lib/types/assets.d.ts +7 -7
  6. package/lib/types/client/api.d.ts +31 -1
  7. package/lib/types/client/llmLive.d.ts +12 -14
  8. package/lib/types/client/panel/LiveFeedLog.d.ts +5 -0
  9. package/lib/types/client/panel/ModelManager.d.ts +2 -2
  10. package/lib/types/client/panel/PromptSlotsView.d.ts +11 -0
  11. package/lib/types/client/panel/TensionView.d.ts +14 -0
  12. package/lib/types/client/panel/TimelineView.d.ts +14 -0
  13. package/lib/types/engine.d.ts +40 -2
  14. package/lib/types/index.d.ts +4 -0
  15. package/lib/types/llm-live.d.ts +65 -34
  16. package/lib/types/llm-retry.d.ts +38 -0
  17. package/lib/types/market-radar-sources.d.ts +1 -1
  18. package/lib/types/prompt-slots.d.ts +57 -0
  19. package/lib/types/prompting.d.ts +2 -2
  20. package/lib/types/protocol.d.ts +283 -3
  21. package/lib/types/snapshots.d.ts +46 -0
  22. package/lib/types/stage-contract.d.ts +1 -1
  23. package/lib/types/tension.d.ts +65 -0
  24. package/lib/types/timeline.d.ts +37 -0
  25. package/package.json +3 -2
  26. package/src/action-guard.ts +1 -1
  27. package/src/assets.ts +300 -268
  28. package/src/assistant.ts +45 -29
  29. package/src/client/api.ts +76 -2
  30. package/src/client/llmLive.ts +26 -16
  31. package/src/client/panel/AssetsTab.tsx +2 -2
  32. package/src/client/panel/LiveFeedLog.tsx +204 -67
  33. package/src/client/panel/ModelManager.tsx +2 -2
  34. package/src/client/panel/NovelPanel.tsx +127 -13
  35. package/src/client/panel/PromptSlotsView.tsx +97 -0
  36. package/src/client/panel/SettingsView.tsx +35 -0
  37. package/src/client/panel/TensionView.tsx +196 -0
  38. package/src/client/panel/TimelineView.tsx +192 -0
  39. package/src/engine.ts +549 -108
  40. package/src/index.ts +12 -0
  41. package/src/llm-live.ts +260 -68
  42. package/src/llm-retry.ts +77 -0
  43. package/src/market-radar-sources.ts +173 -173
  44. package/src/prompt-slots.ts +125 -0
  45. package/src/prompting.ts +8 -8
  46. package/src/protocol.ts +314 -3
  47. package/src/routes.ts +325 -6
  48. package/src/run.ts +4 -0
  49. package/src/snapshots.ts +174 -0
  50. package/src/stage-contract.ts +189 -189
  51. package/src/tension.ts +240 -0
  52. package/src/timeline.ts +159 -0
package/src/protocol.ts CHANGED
@@ -24,6 +24,18 @@ export const NOVEL_API = {
24
24
  director: '/api/dsh-novel-forge/director',
25
25
  directorTodos: '/api/dsh-novel-forge/director/todos',
26
26
  llmLive: '/api/dsh-novel-forge/llm-live/stream',
27
+ /** 查看某次调用实际发送的 Prompt(按 sessionId)。 */
28
+ llmPrompt: '/api/dsh-novel-forge/llm-live/prompt',
29
+ /** 清零本次运行的用量账本。 */
30
+ usageReset: '/api/dsh-novel-forge/usage/reset',
31
+ /** 章节历史版本(快照)。 */
32
+ snapshot: '/api/dsh-novel-forge/snapshot',
33
+ /** 张力曲线(GET 数据 / POST 设置)。 */
34
+ tension: '/api/dsh-novel-forge/tension',
35
+ /** 提示词槽位(GET 列表 / POST 写入)。 */
36
+ promptSlots: '/api/dsh-novel-forge/prompt-slots',
37
+ /** 故事时间线(GET 列表 / POST 操作)。 */
38
+ timeline: '/api/dsh-novel-forge/timeline',
27
39
  marketRadar: '/api/dsh-novel-forge/market-radar',
28
40
  marketRadarScan: '/api/dsh-novel-forge/market-radar/scan',
29
41
  marketRadarApply: '/api/dsh-novel-forge/market-radar/apply',
@@ -297,6 +309,10 @@ export interface ChapterPlan {
297
309
  review?: ReviewReport
298
310
  /** 作者复盘:钩子兑现/结尾钩子/剧情线推进/连续性/节奏趋势(生成后自动)。 */
299
311
  authorReview?: AuthorReview
312
+ /** 本章目标张力 0-100(规划或作者设定;用于张力曲线)。 */
313
+ tension?: number
314
+ /** 本章实际张力 0-100(审稿时模型打分;缺省时回落到 review.tension)。 */
315
+ tensionActual?: number
300
316
  /**
301
317
  * 待确认草稿:润色(去AI味)或整章重写的产物正文。生成时先存这里,
302
318
  * 用户看过对比后点「采纳」才覆盖正文文件;点「放弃」则丢弃。刷新页面不丢失。
@@ -375,6 +391,8 @@ export interface ReviewReport {
375
391
  aiFlavor?: number
376
392
  /** 本地扫描命中的高频套话(按次数降序,取前若干)。 */
377
393
  aiPhrases?: Array<{ word: string; count: number }>
394
+ /** 本章张力 0-100(审稿模型评分;用于张力曲线的"实际"值)。 */
395
+ tension?: number
378
396
  /** When the review ran. */
379
397
  reviewedAt: string
380
398
  }
@@ -557,6 +575,132 @@ export interface StoryBible {
557
575
  }
558
576
 
559
577
  /** A planted/active/resolved foreshadowing thread. */
578
+ /**
579
+ * 张力曲线形状预设:
580
+ * `escalation` 递进爬升 / `suspense` 悬疑加压 / `wave` 波浪呼吸 /
581
+ * `frontLoad` 前紧后稳 / `flat` 平稳推进 / `custom` 自定义。
582
+ */
583
+ export type TensionCurvePreset = 'escalation' | 'suspense' | 'wave' | 'frontLoad' | 'flat' | 'custom'
584
+
585
+ /** 张力曲线配置(随项目保存)。 */
586
+ export interface TensionCurveConfig {
587
+ preset: TensionCurvePreset
588
+ /** preset=custom 时的逐章采样(0-100;缺省按章节数取默认值)。 */
589
+ custom?: number[]
590
+ }
591
+
592
+ /** 张力曲线的一条问题(实际 vs 目标 / 曲线形状)。 */
593
+ export interface TensionIssue {
594
+ severity: 'high' | 'medium' | 'low'
595
+ chapters: number[]
596
+ item: string
597
+ suggestion: string
598
+ }
599
+
600
+ /** 张力曲线数据点(面板绘图用)。 */
601
+ export interface TensionCurvePoint {
602
+ no: number
603
+ title: string
604
+ /** 目标张力。 */
605
+ target?: number
606
+ /** 实际张力(审稿打分)。 */
607
+ actual?: number
608
+ /** 参考曲线在此处的取值。 */
609
+ reference?: number
610
+ }
611
+
612
+ /** GET /tension 响应。 */
613
+ export interface TensionResponse {
614
+ preset: TensionCurvePreset
615
+ points: TensionCurvePoint[]
616
+ /** 规则核对发现的问题。 */
617
+ issues: TensionIssue[]
618
+ }
619
+
620
+ /** POST /tension 请求。 */
621
+ export interface TensionRequest {
622
+ op: 'preset' | 'set' | 'clear'
623
+ preset?: TensionCurvePreset
624
+ chapterNo?: number
625
+ /** op=set 时的目标张力(0-100)。 */
626
+ tension?: number
627
+ }
628
+
629
+ /** 允许作者编辑的提示词槽位 id(白名单)。 */
630
+ export type PromptSlotId = 'styleExtra' | 'antiAiExtra' | 'dialogueExtra' | 'endingHookExtra'
631
+
632
+ /** 一个提示词槽位的当前内容。 */
633
+ export interface PromptSlotState {
634
+ id: PromptSlotId
635
+ label: string
636
+ hint: string
637
+ placeholder: string
638
+ maxChars: number
639
+ value: string
640
+ }
641
+
642
+ /** GET /prompt-slots 响应。 */
643
+ export interface PromptSlotsResponse {
644
+ slots: PromptSlotState[]
645
+ }
646
+
647
+ /** POST /prompt-slots 请求:设置或清空一个槽位。 */
648
+ export interface PromptSlotsRequest {
649
+ id: PromptSlotId
650
+ /** 空串 = 清空该槽位(恢复默认)。 */
651
+ value: string
652
+ }
653
+
654
+ /**
655
+ * 故事时间线事件:从章节正文抽取的「故事内时间点 + 地点 + 参与角色 + 事件」。
656
+ * 用途:后续章节的时间连续性与地点衔接(比编年录更强调"顺序")。
657
+ */
658
+ export interface TimelineEvent {
659
+ /** 稳定 id(时间线内唯一)。 */
660
+ id: string
661
+ /** 所属章节号。 */
662
+ chapterNo: number
663
+ /** 故事内时间点(如「第三日黄昏」「入宗三个月后」「同日夜」)。 */
664
+ time: string
665
+ /** 相对顺序(同书内递增;无法判断时缺省)。用于检测时间倒流。 */
666
+ order?: number
667
+ /** 地点。 */
668
+ place: string
669
+ /** 参与角色(角色名)。 */
670
+ characters: string[]
671
+ /** 事件一句话。 */
672
+ event: string
673
+ /** 来源:模型抽取 / 作者手改。 */
674
+ source: 'extracted' | 'manual'
675
+ createdAt: string
676
+ }
677
+
678
+ /** 时间线矛盾(规则初筛 + AI 复核)。 */
679
+ export interface TimelineIssue {
680
+ severity: 'high' | 'medium' | 'low'
681
+ /** 定位到的章节(可多个)。 */
682
+ chapters: number[]
683
+ /** 问题描述。 */
684
+ item: string
685
+ /** 建议修法。 */
686
+ suggestion: string
687
+ }
688
+
689
+ /** GET /timeline 响应。 */
690
+ export interface TimelineResponse {
691
+ events: TimelineEvent[]
692
+ /** 规则初筛发现的问题(瞬时计算,不落盘)。 */
693
+ issues?: TimelineIssue[]
694
+ }
695
+
696
+ /** POST /timeline 请求:op=extract 抽单章 / check 全量检查 / update 手改 / remove 删除 / clear 清空。 */
697
+ export interface TimelineRequest {
698
+ op: 'extract' | 'check' | 'update' | 'remove' | 'clear'
699
+ chapterNo?: number
700
+ event?: TimelineEvent
701
+ id?: string
702
+ }
703
+
560
704
  export interface Foreshadow {
561
705
  /** Stable id. */
562
706
  id: string
@@ -993,6 +1137,12 @@ export interface ProjectState {
993
1137
  roles?: RoleRecord[]
994
1138
  /** 人物志:角色当前状态聚合结果(从编年录刷新后存档,打开页面直接显示)。 */
995
1139
  roleStatus?: RoleStatusCard[]
1140
+ /** 故事时间线(逐章抽取:时间点 / 地点 / 参与角色 / 事件)。 */
1141
+ timeline?: TimelineEvent[]
1142
+ /** 张力曲线配置(形状预设 + 自定义采样)。 */
1143
+ tensionCurve?: TensionCurveConfig
1144
+ /** 作者自定义的提示词槽位(白名单见 prompt-slots.ts)。 */
1145
+ promptSlots?: Partial<Record<PromptSlotId, string>>
996
1146
  /** 本书参数(写作/审稿/推理/模型快切;未设字段回退全局 config)。 */
997
1147
  bookSettings?: BookSettings
998
1148
  /** ISO timestamps. */
@@ -1150,6 +1300,13 @@ export interface NovelConfig {
1150
1300
  reviewModel?: string
1151
1301
  /** 全书质检(审计)用模型(缺省用 model)。 */
1152
1302
  auditModel?: string
1303
+ /**
1304
+ * 备用模型:主模型调用失败(网络/限流/额度/服务不可用)时自动切换重试一次。
1305
+ * 留空表示不切换。批量连写时能显著减少"整批中断"。
1306
+ */
1307
+ fallbackModel?: string
1308
+ /** 是否在出章后自动抽取故事时间线(失败不阻断出章)。默认开。 */
1309
+ autoTimeline?: boolean
1153
1310
  /** LLM reasoning effort: off = no thinking; low/high/max = thinking intensity. */
1154
1311
  reasoningEffort: 'off' | 'low' | 'high' | 'max'
1155
1312
  /** 分析类任务(提炼/拆书/反推大纲等)的推理档位;默认 low,不受上面写作档位影响。 */
@@ -1232,6 +1389,126 @@ export interface StageInfo {
1232
1389
  reason: string
1233
1390
  }
1234
1391
 
1392
+ // ------------------------------------------------------------ LLM 实况 / 用量
1393
+
1394
+ /** 单次 LLM 调用的 token 用量(来自 dsh-llm 的 usage chunk)。 */
1395
+ export interface LlmTokenUsage {
1396
+ inputTokens: number
1397
+ outputTokens: number
1398
+ /** 供应商给出的总用量(缺失时由输入+输出推导)。 */
1399
+ totalTokens?: number
1400
+ /** 思考(reasoning)通道用量。 */
1401
+ reasoningTokens?: number
1402
+ /** 命中缓存的输入用量。 */
1403
+ cacheReadTokens?: number
1404
+ }
1405
+
1406
+ /** LLM 实况帧:宿主 → 浏览器的 SSE 事件(每次调用一组 session_* 事件)。 */
1407
+ export interface LlmLiveFrame {
1408
+ type: 'session_started' | 'output_delta' | 'reasoning_delta' | 'phase_changed' | 'session_completed'
1409
+ /** 宿主生成,形如 ll-<base36>-<n>。 */
1410
+ sessionId: string
1411
+ /** 本次调用用途(如 正文生成/审稿/章节规划)。 */
1412
+ label?: string
1413
+ /** 使用模型。 */
1414
+ model?: string
1415
+ /** 事件时间(ISO)。 */
1416
+ at: string
1417
+ /** session_started:交互上下文。 */
1418
+ context?: { taskId?: string; interactionId: string }
1419
+ /** output_delta / reasoning_delta:本次增量文本。 */
1420
+ content?: string
1421
+ /** session 累计字符数。 */
1422
+ totalChars?: number
1423
+ /** reasoning 累计字符数。 */
1424
+ totalReasoningChars?: number
1425
+ /** phase_changed:新阶段。 */
1426
+ phase?: 'requesting' | 'streaming' | 'completed' | 'failed'
1427
+ /** phase_changed:阶段描述。 */
1428
+ phaseMessage?: string
1429
+ /** session_completed:最终预览(截断)。 */
1430
+ preview?: string
1431
+ /** session_completed:失败信息。 */
1432
+ error?: string
1433
+ /** session_completed:本次用量(供应商未上报时缺省)。 */
1434
+ usage?: LlmTokenUsage
1435
+ /** session_completed:本次调用耗时(毫秒)。 */
1436
+ elapsedMs?: number
1437
+ /** session_completed:首字耗时(毫秒;未拿到文本时缺省)。 */
1438
+ firstTokenMs?: number
1439
+ /** session_started:是否已记录可查看的 Prompt(面板据此显示「查看 Prompt」)。 */
1440
+ hasPrompt?: boolean
1441
+ /** session_started:Prompt 字符数(system + user)。 */
1442
+ promptChars?: number
1443
+ }
1444
+
1445
+ /** 按用途分组的用量。 */
1446
+ export interface LlmUsageBucket {
1447
+ label: string
1448
+ calls: number
1449
+ failed: number
1450
+ inputTokens: number
1451
+ outputTokens: number
1452
+ reasoningTokens: number
1453
+ elapsedMs: number
1454
+ }
1455
+
1456
+ /** 本次运行(进程内,重启归零)的 LLM 用量汇总。 */
1457
+ export interface LlmUsageSummary {
1458
+ calls: number
1459
+ failed: number
1460
+ inputTokens: number
1461
+ outputTokens: number
1462
+ reasoningTokens: number
1463
+ totalTokens: number
1464
+ elapsedMs: number
1465
+ /** 供应商未上报 usage 的调用次数(用于说明数据为何不完整)。 */
1466
+ callsWithoutUsage: number
1467
+ byLabel: LlmUsageBucket[]
1468
+ }
1469
+
1470
+ /** 一次调用的 Prompt 记录(供面板查看「实际发送了什么」)。 */
1471
+ export interface LlmPromptRecord {
1472
+ sessionId: string
1473
+ label?: string
1474
+ model?: string
1475
+ at: string
1476
+ system?: string
1477
+ user?: string
1478
+ /** system + user 的字符数(记录被截断时仍给出原始长度)。 */
1479
+ chars: number
1480
+ /** 记录本身是否被截断。 */
1481
+ truncated?: boolean
1482
+ }
1483
+
1484
+ /** 章节历史版本(快照):覆盖写入前自动留存,可回滚。 */
1485
+ export interface ChapterSnapshot {
1486
+ id: string
1487
+ chapterNo: number
1488
+ /** 快照文件(相对书目录)。 */
1489
+ file: string
1490
+ /** 留存原因(生成覆盖 / 采纳草稿 / 修订 / 手工)。 */
1491
+ reason: string
1492
+ chars: number
1493
+ at: string
1494
+ }
1495
+
1496
+ /** GET /snapshot 响应。 */
1497
+ export interface SnapshotResponse {
1498
+ snapshots: ChapterSnapshot[]
1499
+ /** 快照占用字节数。 */
1500
+ bytes: number
1501
+ }
1502
+
1503
+ /** POST /snapshot 请求:op=create 手工存档 / restore 回滚 / remove 删除 / prune 只留最近 N 个。 */
1504
+ export interface SnapshotRequest {
1505
+ op: 'create' | 'restore' | 'remove' | 'prune'
1506
+ chapterNo?: number
1507
+ id?: string
1508
+ /** prune:每章保留数量。 */
1509
+ keep?: number
1510
+ }
1511
+
1235
1512
  export interface StatusResponse {
1236
1513
  config: NovelConfig
1237
1514
  /** The persisted project, when one exists in the output dir. */
@@ -1242,6 +1519,8 @@ export interface StatusResponse {
1242
1519
  audit?: AuditStatus
1243
1520
  /** 宿主按项目真实状态算出的创作阶段(面板角标 / 外部自动化共用)。 */
1244
1521
  stage?: StageInfo
1522
+ /** 本次运行(进程内)的 LLM 用量汇总:调用次数 / 输入·输出·思考 token / 耗时。 */
1523
+ usage?: LlmUsageSummary
1245
1524
  /**
1246
1525
  * 截断声明:本次响应中被裁掉的字段说明(如「编年录:共 320 条,仅返回最近 80 条」)。
1247
1526
  * 消费方不得把缺失字段当作"不存在",需要完整数据时走专用接口。
@@ -1426,13 +1705,41 @@ export interface ChapterResponse {
1426
1705
  }
1427
1706
 
1428
1707
  /** POST /export request/response. */
1708
+ /**
1709
+ * 导出范围:
1710
+ * - `book` 整本正文(txt / md)
1711
+ * - `settings` 项目设定(总纲 / 道藏 / 大世界 / 写作资产 / 卷首语)
1712
+ * - `plan` 规划(卷计划 + 章节计划,含每章目标/要点/钩子/硬事实)
1713
+ * - `characters` 角色(角色库 + 人物志当前状态)
1714
+ * - `review` 质检记录(逐章审稿 + 作者复盘 + 伏笔/剧情线状态)
1715
+ * - `project` 项目 JSON(完整状态,用于备份/迁移;仅 json 格式)
1716
+ */
1717
+ export type ExportScope = 'book' | 'settings' | 'plan' | 'characters' | 'review' | 'project'
1718
+
1719
+ /** 导出范围全集(宿主校验用;顺序即 UI 展示顺序)。 */
1720
+ export const EXPORT_SCOPE_VALUES: readonly ExportScope[] = ['book', 'settings', 'plan', 'characters', 'review', 'project']
1721
+
1722
+ /** 导出范围的中文标签。 */
1723
+ export const EXPORT_SCOPE_LABELS: Record<ExportScope, string> = {
1724
+ book: '整本正文',
1725
+ settings: '项目设定',
1726
+ plan: '规划(卷/章节)',
1727
+ characters: '角色',
1728
+ review: '质检记录',
1729
+ project: '项目备份 JSON',
1730
+ }
1731
+
1429
1732
  export interface ExportRequest {
1430
- format: 'txt' | 'md'
1733
+ format: 'txt' | 'md' | 'json'
1734
+ /** 缺省 `book`(兼容旧调用)。 */
1735
+ scope?: ExportScope
1431
1736
  }
1432
1737
  export interface ExportResponse {
1433
1738
  file: string
1434
1739
  chars: number
1435
1740
  chapters: number
1741
+ scope: ExportScope
1742
+ format: 'txt' | 'md' | 'json'
1436
1743
  }
1437
1744
 
1438
1745
  /** POST /config request: patch any subset of the runtime config. */
@@ -1444,6 +1751,10 @@ export interface ConfigPatch {
1444
1751
  generateModel?: string
1445
1752
  reviewModel?: string
1446
1753
  auditModel?: string
1754
+ /** 备用模型(主模型失败时自动切换重试一次;空串 = 关闭)。 */
1755
+ fallbackModel?: string
1756
+ /** 出章后自动抽取故事时间线(默认开)。 */
1757
+ autoTimeline?: boolean
1447
1758
  reasoningEffort?: 'off' | 'low' | 'high' | 'max'
1448
1759
  analysisReasoning?: 'off' | 'low' | 'high' | 'max'
1449
1760
  chapterChars?: number
@@ -1581,7 +1892,7 @@ export interface AntiAiRule {
1581
1892
  scope?: Array<'writing' | 'review' | 'polish' | 'all'>
1582
1893
  }
1583
1894
 
1584
- /** 预置写法模板(来自 AI-Novel-Writing-Assistant 内置数据,一键绑定无需样本文本)。 */
1895
+ /** 预置叙事风格模板(一键绑定无需样本文本)。 */
1585
1896
  export interface StyleTemplateNarrativeRules {
1586
1897
  progressionMode?: string
1587
1898
  sceneUnitPattern?: string[]
@@ -1654,7 +1965,7 @@ export interface StyleTemplate {
1654
1965
  defaultAntiAiRuleKeys: string[]
1655
1966
  }
1656
1967
 
1657
- /** 起始风格画像:无样本文本也能快速绑定一套写法(对齐上游 DEFAULT_STARTER_STYLE_PROFILES)。 */
1968
+ /** 起始风格画像:无样本文本也能快速绑定一套写法。 */
1658
1969
  export interface StarterStyleProfile {
1659
1970
  /** stable key(如 starter-power-up)。 */
1660
1971
  key: string