自动小说盒子

本地网页版长篇小说创作助手：一句话开篇 → 分部/分章逐步生成 → 支持重写、下一章、抽打、回退与手动编辑。所有数据保存在本地 data/ 目录。

开发与维护请从 架构索引 进入；产品与历史设计资料见 文档索引。

环境要求

• Node.js ≥ 20（自带 npm）
• 一个 OpenAI 兼容的 API（自建服务或第三方均可）：需要 Base URL、模型名与 API Key

一键启动

• macOS：双击 启动.command（首次运行若被 Gatekeeper 拦截，右键 → 打开 → 允许）
• Windows：双击 启动.bat

脚本会自动完成：检查 4399 端口 → 按锁文件和内容指纹核对并安全恢复根依赖 → 当前端源码、依赖策略或构建资源有变化时重新构建 → 启动服务 → 服务成功监听后打开浏览器。依赖恢复默认禁止第三方安装脚本，前端只会在锁文件策略校验通过后定向执行批准的精确版本。若放置了 certs/corp-ca.pem，企业根证书会在首次恢复依赖前生效。 如果 4399 已被占用，脚本只会提示占用 PID 并退出，不会自动结束其它进程。 同一 data/ 目录同一时间只允许一个服务实例写入；即使手动换用不同 PORT，第二个实例也会在恢复事务或监听端口前退出，避免跨进程并发覆盖作品。租约同时记录进程启动身份；异常退出后即使旧 PID 被另一个无关进程占用，也会用操作系统报告的实际启动时间辨别并安全接管。若系统不允许读取该身份，应用会保守地继续阻止启动，而不会冒险覆盖可能仍活跃的实例。租约和备份传输所有者这类小型内部元数据即使在检查后被原地扩张，句柄读取也只会读取各自上限外加一个探测字节，不会把增长后的文件无界载入内存。 停止服务时优先在启动终端按 Ctrl+C 并等待进程退出；收到终端窗口关闭信号时，服务也会尝试先结束进行中的请求、清理临时备份并释放数据租约。

也可以手动运行：

npm ci --ignore-scripts
node server/launcher-preflight.js record-dependencies
npm run build   # 构建前端 → web/dist
npm start       # 校验依赖和前端产物后启动，默认仅监听 127.0.0.1:4399（可用 PORT 覆盖）

npm start 只接受与当前锁文件内容指纹一致的根依赖，以及与当前源码、构建配置完全一致的前端产物；若提示 DEPENDENCY_INSTALL_NOT_CURRENT，请重新执行上面的 npm ci 和依赖记录命令；若提示 FRONTEND_BUILD_NOT_CURRENT，请先运行 npm run build。不要绕过预检继续提供陈旧或被意外改写的页面。预检在已打开的普通文件句柄上分块计算指纹，不会把依赖树、源码或构建产物整文件载入内存；同时限制目录深度、条目数、文件数、单文件 64 MiB，以及依赖 512 MiB、源码 128 MiB、构建产物 256 MiB 的累计读取量，异常膨胀或读取中继续增长的文件会让启动安全失败。依赖和构建指纹戳会先写入同目录私有临时文件再原子替换，不会跟随同名符号链接改写链接目标；node_modules、web 或 web/dist 根目录本身为链接时也会安全失败。

服务会拒绝浏览器跨站 API、跨站嵌入和陌生 Host，以防网页读写本地作品或进行 DNS rebinding / 点击劫持。若通过自定义主机名反向代理访问，请用逗号分隔的 ALLOWED_HOSTS 显式加入这些主机名。HTTPS 代理还必须用 PUBLIC_ORIGIN 精确声明浏览器访问的完整 Origin，例如 ALLOWED_HOSTS=novel.example PUBLIC_ORIGIN=https://novel.example npm start；代理需保留原始 Host，并关闭 SSE 响应缓冲（应用已发送 X-Accel-Buffering: no 且每 15 秒发送注释心跳，使用不识别该响应头的代理时仍需显式配置缓冲和空闲超时）。应用不会直接信任可伪造的 X-Forwarded-Proto。

前端内容哈希后的 JS/CSS 会使用长期不可变缓存；入口 HTML 和普通静态文件每次导航都会向当前服务重新验证，因此更新构建后不会继续引用已经替换的旧资源。

应用没有登录验证。非回环的 HOST 会被默认拒绝；只有在可信网络内明确接受暴露风险时，才同时设置 HOST=0.0.0.0 ALLOW_NETWORK_ACCESS=1 npm start。如需多人或公网访问，应在前置反向代理中添加认证与 HTTPS。

首次使用

1. 打开浏览器进入 http://localhost:4399。

2. 在「API 设置」中填入 Base URL、模型名、API Key，保存。Key 在展示时会被掩码。尚未保存的设置会触发页面离开提醒；返回或重新读取需要二次确认才会丢弃草稿。 设置保存会校验页面读取时的配置修订号；若另一标签页已经更新，旧页面不会覆盖新设置，需先重新读取。若网络中断或服务端在最终落盘后的收尾阶段返回 5xx，页面会基于同一目标配置安全重试一次；结果连续无法确认时则锁定保存并要求重新读取，不会无限重试。 Base URL 必须直接指向最终的 OpenAI 兼容接口；保存时就会按实际请求使用的同一规则校验并规范化地址、模型名和 Key，不会等到生成时才发现持久化配置不可用。三个字段都不接受换行等控制字符，避免 URL 被解析器静默改写，或 Key 到组装请求头时才失败。模型请求不会跟随 HTTP 重定向，避免把 API Key 和未公开作品内容转发到未配置的主机。带 API Key 的远程地址必须使用 HTTPS；明文 HTTP 只会在严格回环主机或未配置 Key 时发起。 保存好当前连接后，可点「检查连接 / 发现模型」，或展开「API 快速切换」把它登记为具名方案，用换行或逗号维护多个模型。方案也可点「检查并同步模型」读取 OpenAI 兼容的 /models 列表。该检查不发送任何小说内容、不跟随重定向，且有 30 秒和 1 MiB 响应上限；不支持标准 /models 的兼容服务可继续手工填写。应用方案时只会使用你明确选中的模型；调用失败不会自动换模型或换服务。当页面上方还有未保存设置时，切换需要二次确认，避免意外丢失草稿。 「模型分工」可分别为正文、大纲/设定、摘要/记忆、审稿、书名/章名指定某个方案中的某个模型。选「当前默认」则跟随上方当前连接；任何显式分工调用失败时都不会自动回退到默认模型。方案或其模型被删除时，相关分工会自动清除，避免生成时引用幽灵配置。 打开一本书的「核心设定」，还可在「本书固定模型」中让该书的正文、大纲、摘要、审稿和标题统一使用一个方案模型。它优先于全局模型分工；一次生成启动后会锁定当时的模型，期间切换只影响下一次任务。选「跟随全局设置」即可清除绑定。固定模型失败不会改用其它模型。

3. 在首屏输入一句话开篇（比如「一个失忆的少年在废墟里捡到会说话的猫」），点「开始 ✍️」。故事设想在往返 API 设置时会保留，刷新或关闭页面前会提醒；从现有书架新建时也可返回书架，已有设想需二次确认才会丢弃。创建后进入全书大纲页，点「🔄 重写」生成大纲，大纲会流式逐字出现。新生成的长篇大纲会要求明确题材承诺、主角长期/中期/当前三层目标、主线的 Promise—Progress—Payoff，以及重要人物的选择、代价和关系变化；这些是结构检查框架，不会替具体故事机械套模板。 进入「核心设定」后，先用「作品核心循环」明确读者反复期待的体验、主角反复行动、每轮可见收益、行动代价和升级方式。它会进入大纲、分部、正文生成与审稿，但不会强迫每章机械走完一轮；单章可以蓄力、变奏或承受余波。核心循环使用独立修订号，多页面冲突不会覆盖新版，基于旧循环返回的迟到正文或审稿也不会保存。同页的「承诺—推进—兑现账本」用于记录读者正在等待什么：计划中内容不会被误当成读者已知，只有正文真正建立后才改为待兑现；可登记预计兑现窗口、有效推进、实际结果和由此产生的新承诺。临期及逾期债务优先进入正文生成与长线审稿，账本变化同样会拒绝旧上下文返回的迟到结果。账本独立加载并使用乐观修订号，另一页面修改时会刷新服务器列表、保留本地草稿，并要求作者明确选择是否覆盖。下方可展开「创作资产库」：粘贴片段或导入 UTF-8 的 TXT/Markdown 文件，按用户原创、本人旧作、已授权、公共领域或外部短摘录声明来源，也可只登记参考链接而不抓取网页、不调用模型。一键提取会生成文风卡和故事结构卡；样本会发送到当前摘要模型，本地只保存最多 2000 字预览、长度和指纹，不保存原始全文。外部短摘录另有 1 万字符上限；授权、公共领域和短摘录必须填写权利说明。资产记录作品/章节备注、题材、场景标签和参考链接，可按内容指纹去重并导出不含原文的 JSON。每本书可绑定本书原生文风、一个外部主文风、最多 3 个辅助文风，以及战斗/对话/悬疑/感情/日常/高潮场景资产；章节页可临时选择本章场景。生成和审稿默认只发送这些被选中资产的结构化指令与可复用技法，受 16000 字符预算约束，不发送来源名称、作者/作品名、链接或样本预览。已经确认发布的章节可在章节页提取为本书原生文风并自动绑定，其优先级高于外部参考。绑定在生成期间变化时，迟到正文会被上下文修订校验拒绝。点「填入本书文风」仍只写入尚未保存的文风草稿，需检查后手动保存，不会覆盖已有草稿。同页的「长期记忆库」集中展示作者已确认的活动、失效和被替换事实，可按类型/状态/关键词筛选、查看跨分部剧情窗口并跳回来源章节；还会将活动事实整理为人物档案、人物关系图和能力/物品/地点/时间线等状态台账。关系的强度/公开程度/变化原因，能力的获得/升级/代价/使用记录，物品持有与损毁转移，人物移动和事件时间，以及势力成员、伏笔回收、作者/读者/人物知识边界等专用字段都会随确认事实保存、备份并按上下文预算发送给模型。尚未回收且到达计划章序的伏笔会按已完成章节数提醒。若同一人物生死、当前位置、物品持有人/数量或能力境界存在多个活动值，页面会提示连续性风险，但不会自动替作者改写事实。「撤销确认」需要连续两次点击，只把事实转为失效历史，不会硬删除来源记录。同一区域的「全书阶段摘要」可选 1–20 个连续分部，用摘要模型重算草稿，再由作者编辑和冻结；来源变化后未冻结草稿会过期并退出上下文，冻结版不会被自动覆盖。 「人物驱动力与声音」不复制长期记忆中的人物事实，而是保存当前欲望、恐惧、作者秘密、受压反应、说话习惯和禁用表达；关系温度按关键章节记录变化原因。实际相关的导演卡会进入章节策划、正文生成与审稿；作者秘密和私下张力会明确标成非读者/角色已知，不能被模型直接泄露。

4. 可点「🧩 AI 规划分部」从全书大纲、已发生分部摘要、世界圣经三层揭示路线和作者已确认的世界进度生成未来分部结构卡；弹窗除阶段承诺、目标、阻力、主线推进、高潮、兑现和结束状态外，还会逐部展示当前世界层级、可验证证据、人物行动、选择代价、认知增量、保留未知和进入下一层门槛。服务器会拒绝缺字段、空泛占位、倒退、跳层和“未完成门槛就换地图”的方案；摘要、大纲或世界圣经里的未来计划不会被当成正文已解锁。点击采纳后，这些结构项会与分部创建事务一起原子写入各部大纲，后续章节生成会实际读取，而不只是保留一组标题。也可以点「新建部」创建空白分部，再点该部下的「＋ 加章」建立第一章；空章正文上方会显示「✍️ 生成本章」。生成完成且出现正文后，底部才会提供「✍️ 生成下一章」，避免跳过空章。侧边栏出现 ✓ 表示该章已有正文。 当前新空章实际启用质量合同 v3 和写前节奏意图 v1；下段 v2 字段仍是兼容基础，v3 另外强制单一叙事节拍、读者认知前后、人物行动后果和世界线作用。节奏意图用受控枚举提前选择压力轨迹、破局方式、兑现规模、钩子机制和关键代价，并与最近五章比较；它只提示有证据的重复风险，不要求机械轮换。章节正文仍只能由配置的外部 API 模型生成，编辑系统只负责策划、组装上下文、审稿和发起返修。

5. 生成或重写前可先填写正文上方的「章节策划卡」：章级明确目标、阻碍、选择、兑现、钩子和硬约束，并可按顺序添加最多 12 个场景，逐场写清人物欲望、现场阻碍、具体行动、局势转折和代价。新空章节默认启用质量合同 v2：张力写清压力来源、三个以上具体局势变化、选择高点与兑现余波；有埋点任务时写清旧阅读债务、具体载体、当下作用、行动影响与保留未知；没有到期债务且本章应专注行动、关系或兑现时，可点「本章无埋点任务」，具体说明理由、章节聚焦和哪些既有未知保持不动。它不会强迫每章硬造谜团；但已进入兑现窗口或逾期的债务仍必须推进、兑现，或在补充说明中用稳定 ID 写清延期原因和下一检查点。世界展开先写读者与当前视角人物的展开前认知，再写既有依据、可验证证据、边界增量、选择代价与保留未知。“受阻→希望→反转”“埋一个伏笔”“出现更大势力”等空结构不能解锁正文生成。已有非空旧策划继续兼容；编辑任一质量字段、填入新版模板或采用新 AI 候选后才升级，旧页面不能再静默降级覆盖。也可点「AI 生成策划候选」让当前正文模型参考全书、本部、前情、核心循环、长期记忆、已选文风资产、最近章节节奏、已有正文和当前表单补全方案；模型只返回候选，不会保存策划或生成正文。候选会完整展示章级结构与场景链，作者先点「采用为编辑草稿」，检查或修改后仍须再点「保存策划卡」才会进入生成与审稿上下文；丢弃候选不会改动当前表单。生成候选时可以停止，正文、前情、设定或已保存策划在等待期间变化时，迟到结果会直接作废。场景链与质量合同会真实进入正文 API、审稿 API 和证据驱动精修 API，但模型不得逐栏复述标签，也不得用一段概述跳过关键行动。正文、重写、抽打和精修候选落盘前还有确定性泄漏门禁：出现 promise_… 债务编号、策划动作锚点、成组质量合同标签或审稿 JSON 字段时直接拒绝，重写不会覆盖旧稿，续写失败不会留下空章。世界圣经作为作者后台全貌进入这些 API；模型必须从已发生摘要、已确认记忆和人物知识边界判断当前已知，只能通过人物可核验的证据推进一层，不能提前泄露底层真相或把已知规则重新包装成谜底。策划卡保存使用独立修订号；另一页面修改策划后，基于旧场景链返回的迟到正文或审稿会被拒绝。想要重写：点「重写」，模型会参考当前版本并保持核心情节；想要定向调整：在「抽打」输入意见（如「节奏太慢，把关键冲突演成场景」）。未提交的候选、策划或抽打草稿都会锁住章节切换与其它编辑，并在刷新或关闭页面时提醒；启动失败、生成失败或正文落盘前停止时指令仍会保留，只有服务端确认正文已保存后才清空。旧版本都会自动进入回退栈。 章节有已保存策划时，新审稿还会显示「策划—成稿差异」：每个章级项和场景都用正文证据区分已落地、合理改写、未落地或证据不足。漏项可点「定向修复本项」进入只修复该场、保留其它已完成情节的抽打流程。上一完成章仍未解决的项会单独显示在下章策划卡；它们不是已发生事实，只有作者手动加入草稿并再保存才生效。源正文或源策划一旦变化，旧带入项会立即失效。

6. 需要回退：点「↩ 上一版」还原到上一个版本。

7. 也可以手动修改正文；编辑器会标记「有未保存修改」，可点「💾 保存」或按 Ctrl/⌘+S，切换页面时也会自动保存。仍有草稿时，侧栏、返回书架、设置和会替换正文的生成/版本操作会锁定；可保存草稿，或两次点击「放弃修改」明确丢弃。刷新或关闭页面时浏览器也会先提示确认。保存、清空和版本切换都会校验服务端版本链修订号；若另一标签页已经更新，本次陈旧操作会被拒绝，页面刷新服务器状态但保留本地草稿，需检查后手动保存为新版。正文实际变化时，基于旧正文生成的摘要、剧情路标、人物、章末交接快照、长期记忆候选和相应 AI 标题会先失效；来源于旧正文的已确认事实会标记为失效，不再参与生成。模型后处理成功后再按新正文填回派生信息。digest 会提取本章实际登场的全部人物及章末最新状态（不只新角色），并从正文最后时刻提取视角、时间地点、进行中动作、即时压力、人物/资源末态、知识边界和未完因果的交接快照，再生成带证据、重要度和正文指纹的长期记忆候选。交接快照不能读取未来策划补写，正文原文和作者确认事实优先；剧情路标只是摘要模型的后续建议，不是“下章必须写”的事实。候选默认不是事实，只有作者在章节下方点「确认事实」后才会进入后续上下文。若手工保存或中断导致派生信息缺失，可在章节页按当前正文指纹显式「重算本章记忆」；它会重新提取摘要、剧情路标、人物、章末交接快照和待确认候选，不修改人工章名/部名，期间正文变化时迟到结果会被拒绝。若同一主体和属性已有不同事实，系统只提示冲突，必须由作者显式确认替换，不会自动覆盖。同一正文重复后处理时，人物按最新完整快照替换，不会把两次识别累加成幽灵人物；digest 解析失败或缺少人物/候选字段时则保留已有同正文结果。分部和全书路标始终归属正文顺序中最后一个非空章节，重写较早章节不会让后续生成倒退到旧时间点；清空末章时则回到上一个非空章节的路标。

8. AI 重写、抽打和下一章会锁定生成开始时的目标版本及实际提示词上下文；寻找上一章时会跳过手工预建的空章和仅含空章的分部，承接正文顺序中最近的非空章节、章末交接快照、剧情路标和上一章全部登场人物的最新状态。下一章 API 不得静默重置快照中的视角、时间地点、进行中动作、伤势、关系、资源和知识边界；需要跳时、转场或换视角时必须在正文里写出可感知的过渡与因果。删章或导入旧备份后，提示词和本部聚合摘要中的章序号都按当前作品树的正文顺序计算，不沿用文件 ID 或历史序号。生成期间若另一标签页修改目标、大纲、核心设定、本部前情或实际上一章，旧上下文结果会被拒绝而不会混入新剧情。「下一章」还会同时核对建章前看到的末章和正文提交时的当前末章，避免两个标签页重复新增、重复计费，或把迟到正文插入另一页面已创建的后续章之前；失败回滚只删除仍保持初始空版本的新章，另一页面已经写入的正文会被保留。手动停止或连接错误后，页面会等待原流及回调完全收尾，再重新读取磁盘上的最终状态；核对完成前生成、编辑和导航保持锁定，避免刷新抢在服务端提交前或重复调用模型。大纲已保存但自动书名生成失败，或正文已保存但摘要/剧情路标/人物/章末交接快照提取或自动审稿未完成时，完成事件会明确列出后处理告警，页面不会再把降级结果提示为完整成功。

9. 手动审稿和生成后的自动审稿也会校验正文与审稿上下文；除总分、问题和可直接抽打的建议外，页面会显示结构化「网文章法检查」，逐项呈现黄金三章职责、前三章共同承诺、本章目标、阻碍升级、人物选择、场景化与转折、有效增量、铺垫兑现、章末钩子、表达比例、可见重复风险、长线推进、文风一致性、包装承诺一致性和内容风险线索。「场景化与转折」会检查关键事件是否由人物欲望、行动、反应和局势变化具体呈现；即使没有预填场景链，也不会把大事件很多却全部概述带过判成通过。包装承诺会对照书名、作品简介/初始设想与当前正文；前三章重点检查开篇是否及时兑现题材卖点，后续章节只检查是否继续服务该承诺，不猜测未提供的开篇。内容风险只提示当前正文中明显需要人工核对的线索，不作为法律结论或平台最新规则审核。文风一致性只在实际绑定资产时检查句式、叙事距离、人物语言、修辞密度和节奏，合理的场景变化不会机械判为风险；没有绑定时明确标为不适用。长线推进会对照实际发送的作品核心循环、承诺账本、全书/本部大纲、阶段摘要和已确认伏笔，提示持续阅读体验、主线承诺、人物线或伏笔长期停滞、逾期未兑现或无因果销账的证据；上下文不足时明确标为不适用，不会猜测未发送的历史。每张新审稿还会记录本章结构功能、冲突类型、情绪类型、爽点/兑现类型和主要表达方式，并从正文实际表现提取压力轨迹、破局方式、兑现规模、钩子机制和关键代价五维受控指纹；后续策划、正文与审稿会读取最近 5 个非空章节的有效记录。系统能确定性提示连续三章同一维度、连续两章完整同构和五章内单一手法支配，但它是可解释风险，不是机械轮换表；合理延续必须让因果后果、规模或代价发生可见升级。旧审稿没有指纹仍可读取，重新审稿后补齐。黄金三章按全书章序计算，不会在每个新分部重新计数；第一、二、三章分别采用不同职责，并明确禁止把所有题材强行改成同一种开局。旧版 10–14 项审稿和没有检查表的更早审稿仍可读取，重新审稿后即可补齐。审稿读取与保存使用同一当前逻辑章序，删章或恢复旧数据后不会因文件中的历史序号误报上下文过期。等待模型期间若正文、书名、简介、大纲、设定、本部前情、承诺账本、所选文风资产或最近章节的有效节奏记录变化，迟到审稿不会附着到新状态，正文不受影响。手动停止审稿后，页面会等原请求收尾再重新读取当前章节，避免服务端恰好已保存、页面却仍显示无审稿而诱发重复调用。审稿保存后这些内容再次变化时，旧审稿卡会明确标记为过期并提示重新审稿。

10. 章节页的「发布版本锁」用于记录你已在起点等平台真实发布的正文，需要二次点击确认，不会自动上传。系统会独立保存完整发布快照；此后本地改写显示为“未发布修改”，旧发布事实和已确认世界门槛仍以读者已见版本进入上下文，未发布记忆候选只能忽略、不能确认。当平台确实已更新时，再锁定当前修改为发布新版；旧版独有的事实和世界门槛会退出，依赖该门槛的后续世界层级也会撤销，避免新版剧情仍被旧证据解锁。旧快照仍可在覆盖前查看，整书备份会保留最新发布快照。同一区域可运行发布前检查：本地检查章名、控制字符、异常空行和正文首行重复章名，整书先按指纹筛选再逐字复核完全重复正文；剧情增量、结尾钩子、长线/文风/包装一致性和内容风险只读取当前有效审稿，审稿缺失或过期会明确要求补审。平台最新规则与合同始终显示为人工确认，工具不会标记为已合规。

11. 左侧「📅 连载管理」集中显示存稿箱、发布状态、全书当前字数和更新日历。有正文但未锁定发布版、或锁定后又修改的章节会进入存稿箱，点击即可回到原章；日历按每章最近一次发布快照的本地日期汇总章数和字符数。每日字数目标保存在作品中，带修订号防止另一标签页静默覆盖，并随单书备份迁移。统计读取章节正文和发布快照的有界投影，不把最多数百万字的完整版本历史装入作品树；“今日已锁定字数”只依据真实发布锁记录，不会把模型生成或本地保存冒充为平台已发布。

12. 「连载管理」中的“平台规则与合同核对”用于保存作者亲自打开官方作者规则、官方 AI 内容政策和当前适用合同后的核对记录。每条记录包含平台名、官方链接、合同核对说明、服务端核对时间和官方接口状态，随作品备份并用修订号防止旧页面覆盖；超过 30 天会提醒重新核对，但这只是提醒周期，不证明规则在期间没有变化。发布前检查可以提示近期记录存在，状态仍固定为“人工确认”，绝不会显示“已合规”。合同说明只写核对位置或结论，不要粘贴身份证、账号、密钥或合同全文。应用当前固定为“仅手动发布”：不保存平台账号、不处理验证码、没有自动上传路由。即使作者提供了近期、明确允许发布同步的官方 API 文档，也只标记为未来集成候选，仍需重新评估官方授权后另行实现；没有官方接口、接口未明确授权、记录过期，或需要绕过登录/验证码/平台限制时一律不能集成。

数据与备份

• 所有小说数据保存在项目目录下的 data/：
  • data/config.json：API 设置（Key 会存到本地）
  • data/api-profiles.json：多 API / 多模型方案库及单书固定模型绑定（Key 会存到本地）
  • data/writing-assets.json：全局创作资产库（结构化分析、来源信息、短预览、书籍与逐章场景绑定，不含样本全文）
  • data/books/<bookId>/：每本书一个目录
    • book.json：全书大纲/设定/人物/部列表，以及随书备份的每日字数目标和平台人工核对记录
    • section-XX/section.json + chapter-XX.json：分部、章节及带正文来源的长期记忆候选；作者确认后的活动/失效/被替换事实保存在对应作品的 book.json
  • data/.transfers/：上传与导出的私有临时目录（正常完成或下次启动后自动清理）
• 服务运行时请优先在书架点某本作品的「备份」，下载 .novelbox.json；服务端会在整书快照锁内完整生成并校验备份，再交给浏览器下载，避免并发保存把不同时间点的书、部、章数据混入同一文件；JSON 会按字段流式序列化到私有临时文件，规范化后立即释放原始解析树，末尾只流式复核书和分部引用，不会为大型作品再复制一份完整备份字符串或重新展开大型聚合元数据。兼容内部调用的内存备份也改用分片序列化计数，不会只为执行 100 MB 上限再生成一份同体量字符串。导出期间该书的新保存会短暂排队；下载连接连续 30 秒没有传输活动时会被终止并释放文件和传输槽。一次性下载链接约 5 分钟后失效。备份包含该书全部版本、摘要、审稿结果、记忆候选和已确认事实，但不会包含 API Key；导入时活动事实必须仍能对应到来源章节、逻辑章序和正文指纹，否则整本拒绝提交，失效或被替换的历史事实则可继续保留。
• 书架每本作品另有「TXT 正文」：服务端在同一整书快照锁内先生成 UTF-8 私有临时文件，再交给浏览器下载。文件只包含书名、分部标题、按全书顺序编号的章名和当前已保存正文，空章会跳过并在页面提示数量；不会夹带大纲、摘要、审稿、长期记忆、API 配置或创作资产。底层同时支持导出已锁定发布快照，便于后续发布状态管理；该功能只生成适合复制到作者后台的文本，不会登录或自动上传平台。
• 创作资产库里的「导出资产 JSON」可单独备份结构化卡片、来源信息、参考链接以及书籍/章节场景绑定，不包含样本全文或 API Key。如需备份整个实例（包括全部作品、创作资产库、回收站、API 设置、多 API 方案库和全部绑定），复制整个 data/ 前请先在启动终端按 Ctrl+C 正常关闭服务，并确认 Node 进程已经退出。不要在服务运行时逐文件复制该目录，否则跨文件更新可能形成不一致的备份。完整的 data/ 备份包含明文 API Key（包括方案库中的 Key），应像密码一样妥善保管。单本 .novelbox.json 不包含全局资产库、API 方案库、单书模型绑定或 API Key，但已经保存到该书「文风基调」的资产指令会随书备份；导入为新副本后需按需重新选择固定模型和文风资产。
• 正常关闭会等待进行中的请求完成，再清理预备备份并释放数据目录租约。若等待超时或再次收到关闭信号，服务会强制断开连接，但不会提前删除租约：异步写入可能仍在进程内收尾，新实例必须等旧进程真正退出后再按死亡 PID 接管，避免两个进程短暂并发写同一 data/。
• 从完整目录备份恢复时也要先关闭服务；先保留当前 data/ 作为可回退副本，再将备份作为一个整体恢复，不要把两份目录中的文件混合覆盖。正常关闭会移除实例租约；不要从仍在运行的实例复制或手工删除 .instance-lock.json。
• 在空书架首屏或书架顶部点「导入备份」即可恢复。导入会先把请求体有界流式落盘，再在已打开的文件句柄上持续执行 100 MB 总量上限并严格索引完整 JSON；即使初检后文件被替换或原地增长，也会按超限拒绝。随机读取分配前还会核对书、部、章各自的本地文件上限；逐分部读取、校验并写入对外不可见的私有暂存目录，规范化后会立即释放原始解析树，分部元数据落盘后只保留逐章校验所需的引用，不会在内存中同时保留全部分部对象或重复深克隆版本历史；只有整本完整成功后才会原子改名提交为新副本，绝不会覆盖同名或同 ID 的现有作品。备份中不连续或自定义的内部部、章 ID 会被保留；后续新建会无精度损失地避让已有路径，自定义 ID 的章节也可以正常删除。即使自定义分部 ID 下的章节增删恰好在落盘中途退出，下一次启动也会扫描并恢复事务，不会把旧事务留到后续编辑之后才重放；碰撞或残留事务也不会被误报成操作成功。
• 新建作品和导入备份会在请求前预分配随机作品 ID；若响应丢失、损坏或返回无法证明未提交的 5xx，页面只按该 ID 核对结果，不会把另一标签页同时创建的作品误认为本次成功。
• 新作品已确认创建、但自动打开失败时，页面会按该精确 ID 刷新书架；即使书架也暂时无法刷新，仍会明确提示不要重复创建。
• 书架改名会携带编辑前看到的作品名；若另一标签页已经改名，本次旧页面写入会被拒绝并自动刷新，不会静默覆盖较新的名称。
• 改名、移入回收站或恢复已被服务端确认、但随后状态刷新失败时，页面会明确提示“操作已落盘”，避免把刷新故障误认为写入失败而重复操作。删除和恢复只有在活动书架与回收站列表都成功重读后才会宣称状态已确认；任一读取失败都会保持“结果未确认”提示。
• 在书架删除作品时只会移入 data/trash/books/ 回收站，可直接在书架恢复；应用不会自动清空回收站。移入前会先重放并清理中断或残留的部章结构事务；若确实恢复了内容，本次删除会停止并刷新书架，要求再次确认，避免恢复出的章节被旧确认一并删除，也避免内部事务标记让完整回收站副本无法自动恢复。即使回收站副本的主数据损坏、目录被人工改名或变成不安全链接，条目仍会显示并标出磁盘位置，但会禁止自动恢复且不会跟随链接，以避免隐藏数据或越界读取。超过 2 MiB 的大型主数据在列表阶段仅做严格流式结构检查，不展开整份版本历史；点击恢复后仍会先把全部书、部、章数据完整校验到私有暂存区，但不会再深克隆刚解析的完整对象。任何异常都会保留原回收站副本且不污染活动书架。
• 若恢复主体已经提交、但旧回收站副本因磁盘故障未能清理，书架会同时显示活动作品和被标记的残留副本，并禁用重复恢复。应用不会自动覆盖或删除该副本；请先备份并确认两份数据后再人工处理。
• 新建的存储目录和 JSON 默认仅当前系统用户可访问；正常加载旧版配置与作品时也会逐文件收紧权限，避免 API Key 和正文被其他本机账号读取；完整性诊断仍保持只读。
• JSON 写入会先将同目录临时文件刷盘，再原子替换正式文件；整书导入、删除和恢复也会刷新相关目录，降低异常断电留下半写文件的风险。最终文件替换后，目录刷盘仍可能失败并返回 5xx/507，因此页面把这类写响应与连接中断一样视为“结果未确认”，先刷新磁盘权威状态再允许用户决定是否重试。进程若在原子改名前被强制终止，未提交的临时文件不会覆盖正式数据；书架轻检和深检都会校验配置、API 方案库与创作资产库，并报告 data/config.json、data/api-profiles.json、data/writing-assets.json、作品、分部或章节旁边的精确残留文件名，但不会跟随链接或自动删除，便于先备份和人工核对。
• 导入、上传或导出过程中若进程异常退出，应用会在后续启动或操作时清理确认失联的内部暂存目录。备份传输只使用当前实例的 data/.transfers/，不再扫描可能包含海量无关文件的操作系统公共临时目录。即使旧 PID 已被无关进程复用，也会继续核对进程启动身份。批量核验有查询数量和总耗时上限，身份无法读取或本轮预算已耗尽时按仍可能活跃处理，不符合内部命名的目录、符号链接和作品正文也不会被自动删除。
• 新增部、增章和失败新章回滚会先写入结构事务；进程在两个文件之间中断时，下次启动会幂等完成事务。若新建操作遇到上一笔残留事务，会先完成上一笔、明确拒绝把它冒充成本次成功，并要求页面刷新确认；损坏或来源不明的事务不会自动执行，只会在书架显示完整性告警。打开作品树、导出备份以及章节读取、保存、生成、摘要和审稿时，也会在对应写入锁内先完成受引用结构的残留事务；目标章已经进入删除流程时既不会出现在新快照中，也不会接受一份随后会被旧事务静默删除的新正文。页面在手动新建部/章和批量采纳 AI 分部时还会携带当前末项锚点；另一标签页已经追加时，本次操作会停止并自动刷新，避免产生意外重复结构。
• 章节 digest 需要更新作品、章节和分部三个文件；提交前会写入小型恢复标记。若磁盘故障或进程退出发生在中间，下次启动、打开作品树、导出或再次写入章节时会以当前章节文件为权威重建整部摘要和分部/全书剧情路标，避免章节已有摘要但聚合前情永久漏章。恢复重建会严格流式扫描每个章节 JSON，但仅保留受限摘要；清空、回退或重写正文后寻找最新剧情路标时，也只保留当前版是否非空及路标，不会把每个候选章的全部版本历史同时载入。损坏或不安全的恢复标记不会被自动执行；标记若已指向索引外章节，或正文指纹与生成时不一致，也会保留现场并作为目标冲突交由书架深度检查明确展示。
• 打开或刷新作品时，导航树会在整书写入锁内读取书、部、章元数据，避免与另一页面的增删章或摘要写入拼成跨时刻的混合状态。分部文件会严格流式扫描完整 JSON，但只保留标题和章节引用，不会为导航树展开最高 100 MB 的聚合摘要、人物和章节摘要映射。现代章节文件同样严格流式扫描，并校验正文版本数、每版长度和游标，但内存中只保留标题和“当前版是否为空”这一位信息，不会为一个侧边栏勾选同时展开多章全部版本历史；旧文件使用早期字段结构时自动回退到完整规范化读取。
• 新建、导入和恢复会在整书提交前核对活动作品目录容量，删除也会先核对回收站容量；达到 10,000 个目录子项时会保留原状态并明确拒绝本次操作，不会让一次成功响应把后续书架或回收站列表推入无法枚举的状态。
• 本地 JSON 会按用途执行文件大小上限与并发读取限制；原子保存会把 JSON 分块写入并刷盘私有临时文件，再整文件改名提交，不会先在内存中生成一份百兆级完整字符串。作品树、章节历史、版本操作、导入恢复等可能较大的 JSON 响应也会分块序列化并遵守浏览器连接背压，断开后停止发送。异常膨胀的作品、章节、配置或事务文件不会整份载入内存，也不会被启动恢复自动执行，书架诊断会标出具体位置；配置检查只返回稳定问题码，不会回显 API Key 或其他配置值。书架摘要会严格流式扫描完整的作品与分部 JSON（仍检查非法 UTF-8、重复键和尾随损坏），但只在内存中保留标题、更新时间和部章引用，不会为了列表展示同时展开多份大型版本历史。新增章在核对全书总章数时也只流式提取其它分部的章节引用，不会因一次建章展开全书聚合摘要。单本作品的主元数据损坏或变成非普通文件时只隔离该作品，其他健康作品仍可显示；凡是会让作品无法出现在书架摘要中的元数据异常，自动轻检也会同步告警，不会只在手动深检时才暴露。
• 书架自动执行的是轻量结构诊断，不读取全部章节正文；它会严格流式扫描完整作品与分部 JSON，但只保留 ID、书架字段和部章引用，不会把大型版本历史再物化一次。诊断会逐本取得作品写入锁，避免把另一标签页正在提交的正常结构事务误报为损坏。data/books、作品或分部目录若无法完整枚举，即使已引用文件仍能按路径读取，也会明确标记本次扫描不完整，不会在无法排除作品或孤立数据时返回健康；最外层作品目录是符号链接、不是普通目录或子项超限时也会返回结构化风险，而不是让检查自身报一个不明 500。排查手工改盘或磁盘损坏时，可点书架顶部「深度检查」，或访问 /api/storage/diagnostics?deep=1，显式执行完整 JSON 与字段边界检查；深检会完整解析文件，但就地迁移本轮私有解析对象，不再为纯校验复制整份大型版本历史。
• 长篇作品的本部聚合摘要会完整保存在本地和备份中；发送给模型时只携带最近 6 万字符并明确标记较早摘要已省略，避免合法的万章分部因累计前情超过模型输入上限而永久无法续写或审稿。
• 每个已有摘要的分部还会向作品主数据登记最多 5000 字的最近剧情，由此形成最多 2 万字符的跨分部剧情窗口。写作或审稿某一部时只选择正文顺序中位于它之前的分部，并优先保留最近几部；不会把当前部或后续部“剧透”进前情。正文重写、清空、删章和中断摘要事务恢复都会同步更新这个派生窗口，超出预算同样有明确省略标记。完整本部摘要仍保留在各自分部文件中，窗口不是完整数据的替代品。
• 已确认的长期记忆完整保存在本地；生成和审稿只读取仍为活动状态的事实，先按本次章节策划与待审/待重写正文直接命中的人物、物品、地点、伏笔和知识边界排序，再按近期前情相关度、重要度和新近度排序，并受独立 1.2 万字符预算约束。这样很久没出现但本章重新点名的旧事实仍会优先交给 API。超出预算时提示词会明确写出“其它已确认记忆因上下文预算省略”，章节页体检同时显示活动、任务命中、实际装入和省略数量；连任务命中项也装不下时会标成风险，不会让模型把未发送误解为事实不存在。确认记忆会改变实际使用该事实的生成/审稿上下文修订号；AI 策划的临时草稿也按实际选中的上下文做并发校验，因此等待模型期间另一页面刚修改的相关硬事实不会被迟到结果绕过。
• 所有单项内容都合法时，四项核心设定、全书/本部大纲、人物和章节正文的合计仍可能超过模型总输入。生成时每项核心设定保留开头与结尾各合计最多 2 万字符，全书大纲最多 4 万、本部大纲最多 3 万；合法备份中的上千个人物则为全书、本部和上一章分别保留最多 1.5 万字符的主要与最近条目，并明确标记中间省略。上一章正文最多发送最近 6000 字符：典型短章可完整承接，超长章才只取末尾窗口；当前章正文仍完整用于重写和审稿。完整数据始终保留在本地和备份中，未实际发送的中段变化也不会让进行中的生成无谓失效。章节页的“API 上下文体检”只返回每层是否装入、条目/字符数、裁剪状态和缺失风险，不把正文、秘密或提示词原文回传给界面。
• 模型流同时限制输入、输出、单个未分隔事件、累计传输量、并发数和请求时长。兼容服务若高频返回单字符事件，服务端会保留首 token 的即时反馈并批量发送后续小片段；浏览器读取较慢时会等待连接排空，断连则立即取消等待和上游请求，单次背压持续 30 秒仍未恢复也会终止连接，避免在内存里排队大量细碎写操作或长期占住模型并发槽。大型 JSON 响应使用同一背压超时。浏览器端也会严格校验 SSE 的 UTF-8 和事件结构；终止帧、手动停止、解析失败或界面回调异常都会取消未读响应并释放流 reader。服务端读取受限的上游 HTTP 错误详情时同样会在达到上限、读取失败或取消后关闭未读响应，不让废弃连接继续占用资源。
• 书架改名只有在标题真正变化时才视为草稿；此时会锁住打开、新建、设置、导入导出和删除等离开动作，刷新或关闭页面也会提醒。保存失败会保留输入，取消改名需二次确认。
• 审稿 API 只有在正文存在可逐字定位的连续证据、且动作与策划中的稳定债务 ID 和当前账本状态一致时，才会提出承诺建立、推进或兑现候选。模型不能直接改账本；作者点击确认后，服务端才以正文、审稿、策划和账本版本锚原子写入。
• 世界圣经的“分阶段揭示路线”必须按当前生活圈、中期势力与地域、长线文明与历史三层填写；每层包含阅读承诺、可验证证据、人物行动、选择代价、认知增量、保留未知和进入下一层门槛。章号不会自动解锁世界层级，上一层未由正文行动和证据完成时，配置 API 不得越级泄密。
• 分部计划写 open-next 仍只是作者目标。审稿 API 只有在当前章正文含有可逐字定位的门槛证据时才会显示“世界层级解锁候选”；作者点击确认后，后续分部规划才允许从相邻下一层开始。未确认的模型判断、剧情摘要和章数都不能推进层级。

常见问题

• 服务启动失败：检查 4399 端口是否被占用。macOS/Linux 可通过 PORT=5001 npm start 换端口；Windows 可通过 set PORT=5001 && npm start 换端口。
• 提示另一个实例正在使用 data/：请回到已运行实例，不要通过换端口重复启动。若提示 data/.instance-lock.json 无法验证，请先确认没有 Node 服务仍在运行并备份整个 data/；应用不会冒险自动删除无法确认归属的租约文件。
• 生成没反应：进入 API 设置检查 Base URL、模型名、Key 是否正确；日志会打印在启动脚本的终端窗口里。
• 模型连接中途断开、输出达到服务长度上限或缺少标准终止标记时，页面会显示明确原因，残缺内容不会落盘；确认配置或网络后手动重试即可。应用不会自动重试，以免重复计费。
• 生成的 JSON 报错：extractDigest 会自动尝试兜底；若摘要、剧情路标、人物或审稿仍未完成，正文保持已保存，页面会明确提示后处理告警。请先检查所用模型是否支持严格 JSON；审稿可以手动重试，摘要或剧情路标缺失时继续生成下一章可用的前情会减少。