NovelRipple · 涟漪

改变一个选择，荡开一整个故事世界。
Change one moment. Ripple the whole story.

NovelRipple 把一部已经完成的小说，变成一个可以理解、探索和改写的故事世界。它先从原著中提炼人物、关系、主线、支线、暗线、伏笔、因果与世界规则，再允许用户从任意关键节点创造新的选择，并观察这次改变如何影响整条世界线。

核心体验

1. 导入一部小说。
2. 生成一张可追溯原文的「全书故事地图」，并实时看到后台生成进度。
3. 选择一个关键节点，保留原选择或提出新的选择。
4. 先预览人物、线索、因果与结局将受到的影响。
5. 确认后进入新的世界线，继续阅读、推演或创作。

故事地图

故事地图不是章节摘要堆叠，也不是一张难以操作的巨型关系图。每个重要节点都应回答：发生了什么、为什么发生、影响了谁、它由哪段原文支持。

地图至少覆盖：

• 故事脊柱：开端、目标、冲突、关键转折、高潮与结局；
• 人物网络：关系、动机、认知、秘密与人物弧；
• 叙事线索：主线、支线、暗线、伏笔及其回收状态；
• 世界约束：时间线、地点、规则、资源与因果关系。

原文事实、模型推断和新世界线生成内容必须清楚区分；重要结论应能回到对应的原文章节或片段。

两种世界线模式

模式	保持不变	可以变化
严格模式	用户选定的原著结局锚点或终局条件	通往结局的选择、事件顺序、人物关系与代价
完全开放模式	分叉前已经发生的历史，以及未被用户主动改写的世界规则	分叉后的主线、人物命运、冲突与最终结局

严格模式不是把故事生硬拉回原剧情。当新的选择与结局锚点无法同时成立时，产品应明确展示冲突，让用户调整约束，而不是牺牲因果合理性。完全开放模式也不是无规则续写；它仍然尊重已经建立的事实、人物认知和世界逻辑。

产品原则

• 简单优先：默认流程只有「导入 → 看图 → 改一点 → 看影响 → 继续故事」。
• 原著不被覆盖：原始文本和原始世界线保持只读，所有变化发生在独立分支中。
• 先理解，再推演，后写作：先建立故事地图，再计算连锁影响，最后生成正文。
• 证据可追溯：事实与推断分开，重要节点能定位到原文。
• 开放源码优先：每次产品迭代前先检索成熟实现，确认许可和适配度后优先复用；完整规则见 AGENTS.md。
• 复杂度需要证明：不因故事天然是图结构，就默认引入图数据库、微服务或多 Agent 系统。

第一阶段

第一个可用版本只跑通一条完整路径：

导入一部作品 → 得到故事地图 → 改变一个节点 → 预览涟漪 → 创建一条可继续的世界线

第一阶段不做大型通用写作套件、社交发布平台、游戏引擎、多人协作系统，也不预生成所有可能分支。只有真实使用证明需要时，才扩大能力和架构。

当前状态

v0.1.0 已冻结 M0 — First Ripple；正式封版状态与评测边界见 M0 封版报告。当前开发合同是 M1 — Real Story。M1-02A Provider / Evidence 兼容性门已通过；正式 M1-02 baseline保留产品质量与 First Ripple 的 FAIL；M1-03 section-first 真实回归失败后已按 retention gate 撤销；生产生成管线已替换为 Phase 1 分块召回。M1-04 已实现 Guided Review 的确定性能力，并取得 Story A 一次真人计时观察（7 分钟、16 次修正），但修正成本仍超过门槛、B/C 未测，correction-cost 结论保持 FAIL，详见 M1-04 回归报告。M1-05 Ripple Suggestions 与反馈重推已完成并通过人工语义复核，见 M1-05 回归报告。M1-06 当时按单场景验收，三篇全部 5 分；P0 已把 Continuation 扩展为场景节点树与分段上下文组装（0007）。M1-07 聚合评测曾判 FAIL 并让开发停下；2026-10-17 起评测改为质量仪表盘，硬规则和 CI 继续阻塞，质量目标只记录不阻塞（0005）。Phase 1 分块召回的真实模型 A/B/C 仪表盘数字尚未重测（私有基准正文不在仓库）。

M0 已完成确定性发布门禁。当前仓库支持创建故事项目，将 UTF-8 .txt / .md 保存为不可变 Source，并在刷新后从本地 SQLite 继续阅读；同时保留公开基准故事，用来回归验证故事地图与世界线领域合同。真实模型质量通过显式 Live Eval 单独验收，不进入默认 CI；历史配置失败记录不等于模型质量 PASS。

当前技术基线：

• Next.js App Router + TypeScript；
• React Flow 故事地图；
• SQLite + Drizzle ORM；
• Zod 领域 Schema；
• Vitest 领域测试与 Playwright 浏览器测试。

仓库已经建立最薄的 OpenAI-compatible 模型调用边界，并实现可调用的分块 Story Map 召回管线：按 Evidence Unit 分块抽取（每块一轮补抽）→ 人名归并 → 结局/人物结局 → 全书合并 → Evidence 解析与领域校验 → 版本化 Artifact。服务端从不可变 Source 的 Section / 自然段确定性派生带稳定 ID 的 Evidence Unit；模型候选只返回 Unit ID，服务端再生成现有 SourceReference 的 Source、Section、UTF-16 偏移与 Hash。未知、重复、跨 Source 或领域引用非法时均 fail closed，不做模糊匹配或相似度 fallback。

Story Map 生成现在是可恢复的后台任务：点击后立即进入阶段/分块进度视图，刷新页面仍从 jobs 表恢复同一任务；服务重启会把遗留任务标为 interrupted 并提供“重试”，重试创建新任务行而不是覆盖历史。任务只保存 Source ID、阶段计数、Artifact ID 和脱敏错误，不保存原文、Prompt 或模型输出；客户端每 1 秒轮询，成功后打开与旧流程相同的候选 Story Map。实现见 ADR 0008。

项目页默认进入 Guided Review：系统按可解释风险显示 inference / 低置信度、人物 identity、Ending、重要 Evidence 与高杠杆分叉队列，并展示进入 Ripple 前的 Readiness Checklist；完整 React Flow 图属于次级视图。用户可以 rename / merge 人物、修改别名与角色，更新/删除/基于所选 Source Evidence 新增/重排 Event，重指派 participants，以及新增/修改/删除/确认 Edge。每次修正和确认都创建新的 revision Artifact，不覆盖 AI 原始版本；服务端拒绝 stale revision，且只有通过 readiness 的新 draft 才能确认并进入 Ripple。M1-04 没有真实 split 需求证据，因此未实现 Character split。

Ripple Simulator 已支持 prevent / choice / outcome、严格与开放模式、结构化 Impact Plan 和四种 Anchor 状态。Preview 只使用已确认 Story Map 构造只读 Canonical 上下文；用户接受后才在同一事务中保存 accepted Impact Plan revision、幂等 Canonical Worldline 和子 Worldline。严格模式的 incompatible 会在写入前被拦截。

接受后的 Worldline 以 confirmed Story Map 为只读基线，并从 accepted Impact Plan 确定性派生 Delta，不复制 Canon。Continuation 先生成恰好 3 个未来方向，用户选择其一后生成 1 个带 statePatch 的完整场景；场景组成不可变场景节点树，任一场景都可以继续、重试本幕（同方向兄弟节点）或换一批方向，旧场景不覆盖。每次生成只读取当前路径：accepted Impact Plan 基础 Delta 沿根→当前节点折叠，较早场景以滚动摘要进入上下文；上下文按固定七段组装（世界线设定、相关原著事件、路径摘要、原著证据、最近场景、所选方向、锚点提醒），并用 CONTINUATION_CONTEXT_MAX_CHARS（默认 24000，只约束组装素材，不含 Prompt 模板）确定性裁剪，场景保存不含正文的 Context Manifest。方向和场景分别保存为可追踪 Artifact，刷新后可恢复；设计见 ADR 0007。场景若恢复已删除事实、删除 accepted Delta / Anchor / 分歧前 Canon，或占用非 generated: 事实命名空间，会在一次定向 repair 后 fail closed，不写入 Artifact。

Source 只在本地 SQLite 中持久化且永不被生成内容覆盖；执行 Story Map 生成时，正文会发送到你在环境变量中配置的 OpenAI-compatible 模型端点。请只配置你信任且符合数据处理要求的服务。

所有结构化结果都要经过本地 Zod Schema；Schema 与领域校验共享一次明确 repair，二次失败即关闭本次生成且不写入 Artifact。单元测试和浏览器测试使用确定性 Mock，不依赖外部模型。

真实端点通过服务端 OPENAI_API_KEY、可选 OPENAI_BASE_URL、OPENAI_MODEL 与 OPENAI_STRUCTURED_OUTPUT_MODE 配置；每次调用显式选择 json_schema、json_object 或 prompt_json：前者发送 strict JSON Schema，中者发送原生 JSON object response format 并由本地 Schema 作权威校验，后者不发送 response_format。所有模式使用 120 秒请求超时，不自动探测能力、不在失败后切换模式、不切换供应商。兼容端点需要实现 OpenAI Chat Completions 协议。版本化 prompt 位于 prompts/；Story Map、Impact Plan 与两阶段 Continuation 均进入固定管线。

本地启动

前置依赖

• Node.js 22.9 或更高版本（见 package.json 的 engines）。
• C/C++ 编译工具链：better-sqlite3 在 npm install / npm ci 时会通过 node-gyp 从源码编译原生模块，缺少工具链会直接安装失败（报 gyp ERR! not ok / 找不到 make）。需要：
  • Debian / Ubuntu：sudo apt-get install -y python3 make g++（或 build-essential python3）；
  • Fedora / RHEL：sudo dnf install -y python3 make gcc-c++；
  • Alpine：apk add python3 make g++；
  • macOS：xcode-select --install；
  • Windows：Visual Studio Build Tools（勾选"使用 C++ 的桌面开发"）+ Python 3。
• GitHub Actions 的 ubuntu-latest 已自带上述工具，CI 里有一步显式检查。

English: better-sqlite3 is compiled from source by node-gyp during npm install/npm ci, so you need Python 3, make and a C++ compiler (g++/clang) installed. On Debian/Ubuntu: sudo apt-get install -y python3 make g++.

启动

npm install
npm run dev

npm run dev 会先幂等执行本地 SQLite migration；也可单独运行 npm run db:migrate。

打开 http://localhost:3000 即可创建项目并导入 Source。重复导入规范化后内容相同的文件会打开已有 Source；内容发生变化时会创建新版本，旧 Source 不会被覆盖。

隐私：真实作品请用生产服务器运行。 开发模式请只导入测试或公版文本；处理真实作品时使用 npm run build && npm start。Next 16 开发模式默认会在终端记录 Server Function 名称、参数值与耗时，而本项目 action 会接收原著正文与改写指令；仓库已在 next.config.ts 设置 logging.serverFunctions: false，请保持关闭，避免作品内容进入日志。

常用验证命令：

npm run lint
npm run typecheck
npm run test:unit
npm run test:contract
npm test
npm run test:e2e
npm run build

配置真实 OpenAI-compatible 模型后，可以显式运行 npm run eval:live 对 ripple-001 做非默认 Live Eval；终端摘要与 .data/evals/m0-live-eval/<run-id>.json 会报告模型、Prompt 版本、事件/人物召回、Evidence、一级影响、Anchor 和 Continuation 合同结果。每次运行写入新文件，不覆盖历史报告；失败详情经过脱敏，不含 raw model output 或 Provider 回显。该命令不会被默认测试或 npm run check 调用。

M1 使用独立显式命令采集未经优化的真实作品 Story Map baseline：

npm run eval:m1:baseline -- \
  --manifest benchmarks/private/<story-a>/manifest.json \
  --manifest benchmarks/private/<story-b>/manifest.json \
  --manifest benchmarks/private/<story-c>/manifest.json

命令强制要求冻结的 Story A / B / C、至少一篇已由 Prompt 作者确认的 unseen 作品和真实 OpenAI-compatible 配置。它直接调用当前生产 Story Map 管线，把脱敏指标和本地评测数据库写入 Git ignored 的 .data/evals/m1-baseline/<run-id>/，且不进入默认 CI。自动阶段结束后状态只能是 awaiting_human_review；Event、Ending Candidate、Edge、修正成本以及 strict/open Ripple 与 Continuation 必须由独立复核者通过生产 revision/Worldline 流程完成，不能由被测模型替代。

评测不再是阻塞门禁，而是质量仪表盘（0005）：

npm run eval:m1 -- \
  --manifest benchmarks/private/<story-a>/manifest.json \
  --manifest benchmarks/private/<story-b>/manifest.json \
  --manifest benchmarks/private/<story-c>/manifest.json

它读取人工评分（作者自评有效，真人观察可选），把召回率、修正成本、续写评分等画成 met / below_target / not_measured，不阻塞；只有四条硬规则——原文与分歧前历史不被覆盖、证据可溯源、世界线隔离、坏输出被拒绝——被违反时才以非零退出。

产品范围、领域语义和评测规则分别见 docs/mvp.md、docs/domain.md 与 docs/evals.md。

参与开发或使用编码 Agent 前，请先阅读 AGENTS.md 与 CONTRIBUTING.md。安装、启动与验证命令以 package.json 中的脚本为准。

内容权利与隐私

只应导入拥有合法使用或改编权利的作品。实现、测试、日志和截图不得泄露用户原稿；公开测试夹具优先使用自建内容或公版作品。