Novel Writing 创作插件（内置版 · 面向 Novel Studio）

这是 Novel Studio（小说创作工坊）内置的创作插件：不是独立分发、不依赖外部仓库， 插件的 dsh 侧源码与工坊服务端创作内核同仓维护、一起升级。

仓库关系：本目录的规范源在 novel-studio 仓库的 harness-plugins/novel-writing/。 若本目录同时以独立仓库（bbaz123/novel-writing-plugin）发布，则该仓库是发布镜像： 两份文件内容保持一致；安装请优先使用 novel-studio 仓库内的版本。

novel-studio/
├─ db.js / server.js / harness.js / public/app.js   ← 工坊主体（创作内核：上下文装配/红线/事件账本/记忆版本/提案确认）
└─ harness-plugins/novel-writing/                   ← 本插件（dsh 侧唯一来源）
   ├─ novel-tools.mjs           # novel_* 工具集（headless 与 GUI preset 同源）
   ├─ agent.cordis.yml          # GUI 会话 preset（写作人设 + novel_* 工具 + fs）
   ├─ preset.yml                # preset 元信息
   ├─ headless-cordis.patch.yml # 注入 headless profile 的区块片段（合并式安装）
   ├─ install.ps1               # 一键安装/升级/卸载（区块合并、保留用户其它 patch）
   ├─ plugin.json               # 清单：工具/端点/契约（文档与测试的唯一真源）
   ├─ test/smoke.mjs            # 端到端冒烟测试（node:test）
   ├─ ENGINE.md                 # 架构、端点、验收细节
   ├─ NATIVE_PLUGIN_GUIDE.md    # 如何在工坊内扩展本插件
   └─ README.md                 # 本文件

安装（两步）

# 1) 工坊本体：直接使用 novel-studio 仓库（创作内核已内置，无需覆盖任何补丁文件）。
#    重启：npm start（数据库启动时自动迁移新表/新列）

# 2) dsh 侧（本目录；发布镜像仓库中本目录即仓库根）：
powershell -ExecutionPolicy Bypass -File .\install.ps1
# 预演不落盘：… install.ps1 -DryRun    卸载：… install.ps1 -Uninstall

完成后打开 novel-studio 使用 AI 创作即可——后台 headless dsh 自动携带 novel 工具与创作纪律， 无需在 dsh 界面手动选 preset（身份经 NOVELSTUDIO_WORK_ID/CHAPTER_ID/MODE 环境变量注入）。

验证

# 服务端冒烟测试（不依赖 dsh，纯 HTTP 断言；需能定位到 novel-studio 仓库，
# 或用 NOVELSTUDIO_REPO 环境变量指定其根目录）
node test/smoke.mjs

# dsh 侧工具目录
cd <你的 deepseek-harness 目录>
pnpm dsh --profile headless "只输出一行：你当前可用的全部工具名称，用逗号分隔"
# 期望出现：novel_context, novel_works, novel_lookup, novel_scan, novel_style_contract,
#           novel_event_add, novel_memory_update, novel_foreshadows, novel_foreshadow_update,
#           novel_consistency, novel_blueprint, novel_review, novel_chapter_save

工具一览

工具	作用
novel_context	取作品/章节分层上下文（大纲/记忆/事件/未闭合伏笔/本章蓝图/目标字数/前后章衔接/角色卡/激活世界观/红线），分层预算截断
novel_works	列出作品（确认 work_id）
novel_lookup	关键词检索角色/词条/章节/剧情线（写前查证设定）
novel_foreshadows	列出未闭合（或全部）伏笔
novel_foreshadow_update	标记伏笔状态（resolved/dropped/open，可回链回收事件）
novel_consistency	成文后一致性核对：未闭合伏笔/出场角色状态/最近事件 vs 正文（蓝图为核对锚点）
novel_scan	确定性反 AI 腔红线扫描（可跳过引号内对话）
novel_style_contract	读取写作红线清单
novel_event_add	事件/伏笔/状态变化入账（伏笔状态与回收、幂等去重；headless 先落提案）
novel_memory_update	长期记忆摘要压缩/增量提交（版本快照可回滚；headless 先落提案）
novel_blueprint	保存本章写作蓝图（场景目标/情节点/冲突/钩子/目标字数），作者确认后落库
novel_review	保存成文的审稿报告（总评/问题清单/优点），作者在工坊界面确认清单并按清单修稿
novel_chapter_save	成稿写回章节正文（旧稿自动存历史版本，返回红线扫描）

关键机制

• 章节蓝图（写前规划）：AI 写作流程先出蓝图（场景目标/情节点/冲突与转折/角色状态变化/钩子/参考设定） → 弹窗确认可修改 → 落库（chapters.blueprint_json）→ 按蓝图成文；蓝图随上下文带入并作为 novel_consistency 的核对锚点；生成失败自动降级为直接成文，不阻塞。
• 每章目标字数控制：作品级默认（works.default_chapter_words，默认 2000，可 3000/5000/自定义）
  • 章节级覆盖（chapters.target_words）；成文不足目标时工坊自动续写补足（≤2 轮拼稿）， 结果弹窗按目标对比提示；作品还可配置总章数/故事结构/叙事视角参与大纲与蓝图生成。
• 审稿→修稿闭环：成文后可「先审稿再应用」——审稿报告（总评/问题/优点）→ 逐条确认/忽略 → 按确认清单修稿 → 段落级差异预览（新增绿/删改红）→ 合并到正文（旧稿存历史版本）。
• 批量章节生成：从第一个无正文章节顺序生成 N 章（≤10），每章自动蓝图→成文→字数补足→写回； 可随时停止，失败即停（已完成章节保留）。
• 伏笔/叙事线索面板：写作页右侧参考面板「伏笔」页签——分组展示、跳转埋设章节、 标记回收/废弃/恢复，与事件账本共用状态。
• 导入导出：TXT/Markdown/EPUB 导入（自动拆章、新建作品，EPUB 零依赖 zip 解析）； 整书 TXT/Markdown 与单章 TXT 导出。
• 提案确认（headless 防污染）：novel-studio 网页启动的任务带 NOVELSTUDIO_PROPOSE_MODE=1， AI 的事件/记忆入账先落提案表，任务结束随结果返回；作者在「AI 写作结果」弹窗勾选采纳， 或稍后在「小说设定 → 长期记忆 → 📥 待确认提案」里处理。GUI dsh 会话里作者在场，直接入账。
• 伏笔闭环：novel_foreshadows 查欠账 → 正文显式呼应 → novel_event_add(resolves_event_id=…) 自动把旧伏笔标记 resolved；作者确认废弃/恢复时用 novel_foreshadow_update 直接改状态； novel_context 里始终带【未闭合伏笔】层。
• 分层上下文预算：每层独立上限、红线/角色卡保底、总量收敛截断，超长记忆标注压缩提示， 不再一刀切盲截。
• 多关键词加权检索：/api/search 支持多关键词 AND 匹配、名称/标题加权排序、片段定位； 前端高亮命中关键词并按类型分组展示。
• 红线扫描与风格契约：默认 28 条反 AI 腔红线，作品级可覆盖（PUT /api/novel/redlines）； 扫描支持 skip_dialogue（引号内台词不计）与整词豁免（每条红线可配豁免词， 如「眸 → 豁免 眼眸/回眸/眸色」）；作品可配置正向风格要求随红线一起进入写作上下文； 写作页参考面板「红线」页签可查看清单并界面化管理（增删改/启用/豁免词）。
• 记忆版本管理：长期记忆每次保存/回滚自动留版本快照；「长期记忆 → 🕘 历史版本」 可查看列表、一键回滚、与当前摘要做差异预览（红色=旧有、绿色=新增）。
• 幂等与保留：事件按 dedup_key 去重；记忆版本每作品保留最近 200 个，超限自动剪除； 正文写回前自动存章节历史版本；审稿报告每章节保留最近 10 份。

安全（本地工具也要防）

• 服务端不再返回 Access-Control-Allow-Origin: *：跨源页面无法读取本地 API Key 与作品数据； 浏览器跨源写请求（POST/PUT/DELETE）一律 403。
• 请求体上限 32MB（EPUB 导入用）；红线正则长度上限 500、豁免词单个上限 100；非法 JSON/非 JSON 响应显式报错。
• 蓝图/审稿/正文写回等写类端点校验 work_id 与章节归属，防止串作品误写。

卸载 / 回退

powershell -ExecutionPolicy Bypass -File .\harness-plugins\novel-writing\install.ps1 -Uninstall

• 删除 ~/.dsh/.agent-presets/novel-writing（GUI preset）
• 从 ~/.dsh/profiles/headless/cordis.patch.yml 中整段移除本插件区块（保留其它 patch 条目）
• 工坊服务端的新表/新列向后兼容（旧功能不受影响），建议保留

环境要求

• Windows（安装脚本为 PowerShell；模块为纯 ESM JS，无第三方依赖）
• Node.js 22.5+（novel-studio 本体）+ 已构建的 deepseek-harness（dsh）仓库 + headless profile
• novel-studio 本地服务（http://127.0.0.1:3737，`PORT` 可覆盖；dsh 工具通过 NOVELSTUDIO_BASE_URL 自动定位）
• 应用本体：https://github.com/bbaz123/novel-studio