← dsh-novel-writer 技术文档

技术文档

dsh-novel-writer 的 18 个工具全部在本地运行，不使用在线大模型：所有指标由规则统计与本地 ONNX 推理得出。本组页面面向二次开发与集成方，逐工具说明参数契约、计算原理、约束边界与源码位置。

阅读约定

每个工具页固定按以下顺序组织，可以跳读：

  • 参数：名称、类型、是否必填、语义与校验方式；
  • 输出结构：返回体字段与渲染层行为；
  • 计算原理：公式、词表、阈值与取舍，尽量给出可直接对照源码的表达式；
  • 约束与边界：对调用方模型的限制、被静默跳过的情形，以及跨版本不可比之处；
  • 源码位置：lib/*.js 中的对应实现。
关于数值。从 v4.3.0 起，本插件做了一轮口径整修（统一句末符、清洗动作词表、抽象度改最长匹配、修饰密度增加停用词、六维基线 μ=0 改绝对尺度判定等）。同一本书在新旧版本下的报告数值不可直接比较，涉及具体差异的页面会单独标注。
v5.0.0 新增两个工具。novel_chapter_brief（开写包）把动笔前要读的材料装配成一次只读调用；novel_fix_plan（改稿台）把风格自检的测量数据翻译成按优先级排序的待办清单。工具数 16 → 18，另为 novel_plot 增加 action: "graph" 结构视图（不新增工具，跨章计算并入既有伏笔工具）。两个新工具均不生成正文，也不调用在线模型。
v5.0.0 另有系统提示词的「档位 × 场景」两个正交维度。档位（systemPromptMode：off / brief / full）决定注入多少，场景（promptScene：general / writing / revising / auditing / setup）决定注入什么；场景仅在 full 档下生效，且只改提示词内容、不改任何工具能力。老状态文件没有 promptScene 键时落到 general（即 4.x 的通用工作流，本版仅在其中补入 7 行新工具入口指引），既有工作流不变。两字段的读写入口与完整语义见 novel_sentence_config。

工具总览

章节与文稿

novel_books列出章节库中的全部作品，含章节数与总字数。 novel_chapters列出某部作品的章节清单：章号、标题、字数、行数、更新时间。 novel_read按行号分段读取章节正文，返回带行号的内容与字数统计。 novel_new_chapter创建新章节文件，章号可显式指定或自动取下一个。 novel_chapter_brief开写包：一次只读调用装配动笔前的全部材料（承接口、伏笔距离、基线、锚段与骨架、禁用清单）。 novel_import扫描目录自动识别书名与章号并分组，支持复制或移动到书库。 novel_keywords统计中文相邻二字组、三字组与英文词的高频项。

分析与测量

novel_style_report风格画像报告：六维基线 μ±σ、指纹、题材、情感、氛围 12 维与语义距离。 novel_style_check新章与全书风格指纹对照，输出相似度与可执行的偏差清单。 novel_fix_plan改稿台：把风格偏差翻译成按严重度 / 代价排序的待办清单（带段落定位），改完可复测。 novel_sentence_analysis九类句式分布、排列规律、句长节奏、情感曲线与风格指纹。 novel_semantic_search本地向量检索：用自然语言定位全书语义相关段落。

设定、剧情与创作资料

novel_plot伏笔与剧情钩子登记：open / done 状态，scan 自动标注被提及的章节；action: graph 结构视图给出跨章的伏笔生命周期、人物出场矩阵与线索活跃度。 novel_settings人物、地点、道具、时间线、世界观用语规范五张表的增删改查。 novel_summary章节摘要按章管理，供长篇续写时快速回忆前情。 novel_outline创作资料维护：创作设定、人物、大纲、钩子记录与创作状态卡。

审计与配置

novel_continuity_check三路审计：衔接、OOC 与大纲走偏，输出带原文引用的问题清单。 novel_sentence_config查看与修改工具开关、功能开关、系统提示词档位与场景、风格基线容差。

该调哪个工具

工具数到 18 之后，「选对工具」本身也有了成本。下表按你想回答的问题给出口径；其中三个分析类工具名字最像，一并说明区别。

你想回答的问题用哪个主要输出
这本书整体是怎么写的（写作手法）novel_sentence_analysis九类句式分布与排列规律、句式模板、段落结构、句长节奏、情感曲线、风格指纹与节奏建议
我这一章写得像不像原著novel_style_check单章 vs 全书其余章的指纹相似度与 high / medium / low 分级、偏差清单、六维出带判定、原著锚段
这本书是什么风格novel_style_report六维测量与 μ±σ 基线、词汇、题材与流派、情感、氛围 12 轴、语义距离、锚包与 AI 风格判断
动笔前我该读哪些材料novel_chapter_brief承接口、上一章钩子、大纲方向行、命中人物卡、未回收伏笔及埋设距离、世界观禁用词、六维基线、锚段与骨架、禁用清单与三段式 plan
这一章要改哪里、改完没有novel_fix_plan按 severity → effort 排序的待办清单（带段落行号与改写方向，不给改写后的正文）+ verify 三态复测
全书有没有断线 / 丢人 / 忘伏笔novel_plot（action: "graph"）伏笔生命周期与埋设距离、人物出场矩阵与连续缺席（≥ 5 章）、线索活跃度与最大空档、时间线顺序核对、大纲方向行对照
三个分析工具已共享底层引擎与缓存，重叠在实现层、不在接口层。novel_sentence_analysis / novel_style_check / novel_style_report 用的是同一套句式与情感引擎，读写的也是同一批缓存文件（<book>-chapters-metrics.json 分章六维测量、<book>-full.json 全书分析、analysis/<book>-<sha1>.json 句式报告历史、style-reports/<book>.json 风格判断）——分章测量的指纹按文件名排序后再哈希，因此三者交替调用命中同一份缓存，不会互相击穿。它们不合并，是因为回答的问题互不替代（怎么写 / 像不像 / 是什么风格），输出形状也各不相同；合并会把三份 output.schema 并成一份、并让三个稳定的工具名消失（MCP 客户端配置、文档页与提示词一起失效），代价大于收益。这里用「意图 → 工具」的对照表做消歧，而不是减少工具数。

共同约定

书库根目录与路径

所有工具接受可选的 root（含 novels 子目录的目录）。解析优先级：调用参数 root → 插件配置项 → MCP 启动参数 --root → 环境变量 DSH_NOVEL_WRITER_ROOT → 当前工作目录。MCP 形态下，参数里的 root 必须落在启动时 --root 指定范围内；越界时由 MCP 层静默回退到 --root，只写入 stderr 日志，调用方不会收到错误（插件层 resolveRoot 本身不做范围校验，范围校验只在 MCP 层 isInsideRoot 进行）。书名、分类等片段经 sanitizeSegment 过滤，防止路径穿越。

数据落盘

所有派生数据集中写在 <书库根>/.novel-writer/ 下：plots（伏笔）、settings（设定）、summaries（摘要）、analysis（分析报告）、audits（审计）、embedding（语义索引）、style-reports（风格画像）。写盘采用临时文件 + 原子替换；失败会抛出 ENOVELWRITEFAIL 而不是静默丢弃。

语义引擎的可用性

语义检索、语义风格距离与语义隐性情感依赖随包分发的 bge-small-zh-v1.5 量化模型（约 24MB）与 onnxruntime-web（WASM）。引擎不可用时这些能力自动降级为纯规则模式，其余功能不受影响；返回体会以 skippedDims 或专用文案说明降级原因，而非返回空结果。

MCP 形态的边界

包内 mcp/server.mjs 把同样 18 个工具暴露为 stdio MCP 服务器（可用 Streamable HTTP 传输）。协议侧：未知工具返回 -32602（Protocol Error）；支持 2025-11-25 / 2025-06-18 / 2025-03-26 / 2024-11-05 版本协商并原样回显；JSON-RPC 批量请求自 2025-06-18 起按规范拒绝；单行报文上限 4 MiB；novel_import 的 src 默认限制在书库根内，需显式加 --allow-external-src 才能放开。