dsh-novel-writer 4.1.1 → 4.3.0

package/README.en.md

@@ -7,49 +7,97 @@ English | [中文](./README.md)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg?style=flat-square)](LICENSE)
 [![Node](https://img.shields.io/badge/node-%3E%3D22.3-339933.svg?style=flat-square)](https://nodejs.org)
 [![DSH](https://img.shields.io/badge/DSH-%E2%89%A50.1.1--rc.2-4b8bbe.svg?style=flat-square)](https://github.com/deepseek-ai/deepseek-harness)
+[![GitHub stars](https://img.shields.io/github/stars/siweina/dsh-novel-writer.svg?style=flat-square&color=orange)](https://github.com/siweina/dsh-novel-writer/stargazers)
 
 **16 tools that turn "my writing drifted" into numbers you can act on.**
 Sentence, emotion and style-baseline analysis all run **on your machine**: a 24MB Chinese model ships with the package,
 **zero API cost, your manuscript never leaves the device**. Built for DeepSeek Harness (DSH); the same engine is also
 exposed as a **stdio MCP server** for Claude Desktop / Cursor.
 
+[Install](#install) · [60-second start](#60-second-start) · [See the output](#see-the-output) · [The 16 tools](#provided-tools-16) · [MCP server](#mcp-server-usable-outside-dsh)
+
+---
+
+## What problem does it solve
+
+| Your pain | What you get here |
+|---|---|
+| "This passage I just wrote doesn't sound like me" | **Six-metric style baseline**: μ±σ of the original measured per chapter across syntactic complexity / modifier density / abstraction / action density / hedging / gap index; a new chapter is compared dimension by dimension and flagged ⚠ when out of band |
+| "The AI says my style changed but can't say where" | **Style check**: similarity score + a deviation list (which sentence types increased, how far sentence length drifted, whether the dominant emotion changed) |
+| "Analysing a novel means paying for API calls" | Semantic search and emotion analysis run **fully local** — zero token cost |
+| "I planted a plot thread and forgot to pay it off" | **Plot registry**: add / list / scan / done, automatically recording which chapters mention each thread |
+| "Character settings contradict each other" | **Five settings tables + continuity audit** (bridge / OOC / outline drift) |
+| "I can't read the report" | Everything is **tabulated numbers + quoted anchors from your own text** — screenshot-ready |
+
 ## Install
 
+**Option 1: npm (recommended)**
+
 ```sh
 dsh plugin --profile web add dsh-novel-writer
-# or
-npm install dsh-novel-writer
 ```
 
-Requires **Node >= 22.3**. Restart the web app; a "写作助手功能" panel appears in the sidebar.
+**Option 2: From GitHub**
 
-## MCP server
+```sh
+dsh plugin --profile web add github:siweina/dsh-novel-writer#main
+```
+
+**Option 3: MCP (no DSH required)** — see [MCP server](#mcp-server-usable-outside-dsh)
+
+Requires **Node >= 22.3**. After installing, **restart the web app**; a 「写作助手功能」 ("Writing Assistant") panel
+appears in the sidebar.
+
+## 60-second start
 
 ```sh
-npx -y -p dsh-novel-writer dsh-novel-writer-mcp --root /path/to/your/novels
+mkdir -p novels/my-novel     # put chapter files inside (第01章.md, 第02章.md, …)
 ```
 
-See [mcp/README.md](./mcp/README.md) for the Claude Desktop / Cursor config.
+Then just ask in chat: **"run novel_style_report on my novel"** and you get:
 
----
+```text
+全书 1329 字：六维基线 μ=句法复杂度:2.3 修饰密度:35.6 抽象度:0.5 动作密度:101.7 不确定性:2.1 留白指数:7.0
+推荐容差 25%/35%/100%…
+```
 
-## Installation
+(Report text is currently Chinese-only — see the note for non-Chinese users below.)
 
-**Option 1: npm (recommended)**
+## See the output
 
-```sh
-dsh plugin --profile web add dsh-novel-writer
-# or
-npm install dsh-novel-writer
+**Style check** (new chapter vs. book baseline):
+
+```text
+相似度 0.946 · verdict: high
+偏差清单：心理占比略多 · 对话占比略少 · 短句占比略少 · 主导情绪由 anger 变为 joy
+fixAnchors：3 条原著锚段（对话 / 心理 / 描写各一条，供逐句对照修正）
 ```
 
-**Option 2: From GitHub**
+**Semantic search** (natural language, local vectors):
 
-```sh
-dsh plugin --profile web add github:siweina/dsh-novel-writer#main
+```text
+查询「与那盏没有点的灯有关的段落」→
+  第02章.md  0.619  对街那盏灯，亮了。
+  第01章.md  0.593  阿澈的目光越过老周的肩膀，落在对街那栋小楼上…
 ```
 
-After installing, **restart the web app** to activate (host registers 16 tools + state/reveal routes; browser mounts the "Writing Assistant" sidebar toggle panel).
+**Paragraph structure**: 34 paragraphs total (dialogue 5 / psychology 0 / mixed 15 / narration 14)
+
+## Why not an online AI writing tool
+
+| | This plugin | Online AI writing tools | Generic text-analysis libraries |
+|---|---|---|---|
+| Does the manuscript leave the device | **No** | Yes | Depends |
+| Cost | **0 (local inference)** | Billed per token | Self-hosted |
+| Purpose-built for Chinese fiction | **Yes** | Generic | No |
+| Style baseline (μ±σ) | **Yes** | Rare | No |
+| DSH integration | **16 tools + sidebar toggles** | None | None |
+| Usable without DSH | **Yes (MCP)** | Yes | You wrap it yourself |
+
+> **A note for non-Chinese users**: this plugin is designed for analysing and writing Chinese fiction — the sentence-pattern,
+> emotion and imagery engines, and the bundled semantic model, are all built and tuned for Chinese corpora, and the report
+> text itself is Chinese. Covering English and other languages *while* going deep on Chinese is genuinely beyond my current
+> ability. I'm sorry for the inconvenience and hope you understand.
 
 ---
 
@@ -62,7 +110,7 @@ After installing, **restart the web app** to activate (host registers 16 tools +
 5. **Emotion purification & quantification**: strong/weak emotion-word grading, pollution detection, caveat warning + AI re-verification; Valence sliding window → variance V / delta Δ / conflict index C + implicit imagery carriers.
 6. **Worldview & pragmatics detection**: auto cultural-baseline detection with confidence; speechStyle title/honorifics/rituals/tone norms; genre & theme + webnovel signals.
 7. **Writing toolkit**: plot tracking / five settings tables (characters·locations·items·timeline·worldview) / chapter summaries / continuity audit / batch import / style check / continuation writing.
-8. **Per-tool UI toggles**: "Writing Assistant" sidebar panel (master + grouped tool toggles + feature toggles), plain-language labels, data-dir usage & semantic-engine status display.
+8. **Per-tool UI toggles**: 「写作助手功能」 ("Writing Assistant") sidebar panel (master + grouped tool toggles + feature toggles), plain-language labels, data-dir usage & semantic-engine status display.
 9. **Style Baseline**: Six writing metrics (syntactic complexity / modifier density / abstraction / action density / hedging / gap index) + per-chapter μ±σ baseline band; `novel_style_report` outputs the band, `novel_style_check` compares new chapters (in-band ✓ / out-of-band ⚠); per-metric ±% tolerance configurable in the sidebar (**recommended = 1.5× σ of the book's chapter variance**, rounded, clamped to ±10%~100%; leave blank to use recommended) — free theme, writing style kept inside the band.
 10. **Writing sentinels**: `novel_continuity_check` extended — ①**bridge check** (`chapter`: time jumps / semantic distance / character continuity / hook handoff, with quoted evidence) ②**OOC check** (`ooc`: per-character emotion baseline deviation) ③**outline drift** (`outline`: direction vs body keyword overlap); **brief mode** for report tools.
 11. **Original mode & creation files**: fill in creation settings in the sidebar (worldview/characters/forbidden/main conflict/genre/extras, blank = model decides, per-book profile library); novel_outline maintains creation files (bible/characters/outline/hooks/status), enforcing the bible → outline → hook chain with dynamic batches (10→20→30 chapters) to prevent plot jumps and OOC.
@@ -93,6 +141,37 @@ After installing, **restart the web app** to activate (host registers 16 tools +
 
 ---
 
+## MCP server (usable outside DSH)
+
+The package ships a **stdio MCP server** (`mcp/server.mjs`) that exposes all 16 tools to any MCP client,
+e.g. Claude Desktop or Cursor. **It runs as a local process on your own machine — no server, no network, no daemon.**
+
+```bash
+npx -y -p dsh-novel-writer dsh-novel-writer-mcp --root /path/to/your/novels
+```
+
+Client config example (`claude_desktop_config.json` / Cursor `mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "dsh-novel-writer": {
+      "command": "npx",
+      "args": ["-y", "-p", "dsh-novel-writer", "dsh-novel-writer-mcp", "--root", "/path/to/your/novels"]
+    }
+  }
+}
+```
+
+> The package name (`dsh-novel-writer`) and the bin name (`dsh-novel-writer-mcp`) differ, so `npx -y dsh-novel-writer`
+> will **not** start the MCP server — always pass `-p dsh-novel-writer dsh-novel-writer-mcp`.
+
+Library-root priority: `--root` > env `DSH_NOVEL_WRITER_ROOT` > current working directory.
+`root` arguments must stay inside the configured root, and `novel_import`'s `src` is restricted to it as well unless you
+start the server with `--allow-external-src`. Details: [mcp/README.md](./mcp/README.md).
+
+---
+
 ## Configuration
 
 ```yaml
@@ -123,13 +202,23 @@ Under `<library-root>/.novel-writer/`: `plots` / `settings` / `summaries` / `ana
 
 **Permissions and external services**:
 
-- Filesystem: only the user-chosen library root (`novels/`), its data directory (`<root>/.novel-writer/`)
-  and the plugin state file (`~/.dsh/dsh-novel-writer/state.json`).
-- Local HTTP: five routes registered inside the DSH Web GUI, loopback-only by default.
+- Filesystem: reads/writes the user-chosen library root (`novels/`) and its data directory (`<root>/.novel-writer/`),
+  plus the plugin state file (`~/.dsh/dsh-novel-writer/state.json`). **One exception**: `novel_import`'s `src` is by design
+  allowed to point anywhere (that is how you import an old manuscript from elsewhere), and `mode:"apply"` + `move:true`
+  **deletes the source files** — the scope of the deletion is decided by the caller, so only point it at a directory whose
+  contents you know.
+- Built-in skill: registers its own `novel-writing` skill through `ctx.skills` (since v4.3.0); it only reads the packaged
+  `skills/novel-writing/SKILL.md`, **writes to no skill directory** and needs no host configuration; hosts without a `skills`
+  service are skipped silently.
+- Local HTTP: registers 5 routes inside the DSH Web GUI (state / reveal / reports / demo / update-check), loopback-only;
+  `allowLanState` defaults to off, so LAN access is denied by default.
+- MCP server (`mcp/server.mjs`): the `root` argument of every tool must fall inside the library root given to `--root`
+  (out-of-root values are rejected and fall back); `novel_import`'s `src` is likewise root-limited unless you explicitly
+  opt out with `--allow-external-src` (since v4.3.0).
 - Network: the only outbound call is the GitHub Releases API (`api.github.com`) for update checks —
   3s timeout, 24h cache, silent fallback; no manuscript content is sent.
-- Subprocesses: none, except opening the OS file manager with an argv array.
-- Lifecycle scripts: none.
+- Subprocesses: none, except opening the OS file manager with a plain argv array (no shell).
+- Lifecycle scripts: none (no preinstall / postinstall / prepare).
 
 **Failure bounds**: semantic engine failure falls back to pure rule mode; cache/disk failures never block
 tool results; a plugin load failure cannot affect the DSH host process.

package/README.md

@@ -191,10 +191,20 @@ npx -y -p dsh-novel-writer dsh-novel-writer-mcp --root /你的小说库路径
 
 **权限与外部服务**：
 
-- 文件系统：只读写用户指定的书库根目录 `novels/` 与其数据目录 `<root>/.novel-writer/`，
-  以及插件自身的开关文件 `~/.dsh/dsh-novel-writer/state.json`；不访问其他路径。
+- 文件系统：读写用户指定的书库根目录 `novels/` 与其数据目录 `<root>/.novel-writer/`，
+  以及插件自身的开关文件 `~/.dsh/dsh-novel-writer/state.json`。**例外一处**：`novel_import` 的 `src`
+  按设计可以指向任意目录（用于把别处的旧稿导入书库），`mode:"apply"` + `move:true` 会**删除源文件**——
+  删改范围由调用方决定，请只在明确知道源目录内容时使用。**例外仅此一处**：MCP 服务器默认把这个 `src`
+  也限制在书库根内（见下方 MCP 一节）。
+- 内置技能：通过 `ctx.skills` 注册自带 `novel-writing` 技能（v4.3.0 起），只读取包内
+  `skills/novel-writing/SKILL.md`，**不写入任何技能目录**、不需要改宿主配置；宿主没有 `skills` 服务时静默跳过。
 - 本地 HTTP：在 DSH Web GUI 内注册 5 条路由（state / reveal / reports / demo / update-check），
   仅回环地址可访问；`allowLanState` 默认关闭，局域网访问默认拒绝。
+- MCP 服务器（`mcp/server.mjs`）：工具参数里的 `root` 必须落在启动时 `--root` 指定的书库根之内，
+  越界会被拒绝并回退；`novel_import` 的 `src` 默认也限根内，确需导入外部目录时用
+  `--allow-external-src` 显式放开（v4.3.0 起）。单行报文上限 4 MiB，超限整行丢弃；stderr 默认只记一行错误摘要，
+  不回显正文与堆栈（需要完整堆栈用 `DEBUG=1`）；长任务可用 `notifications/cancelled` 取消。详见
+  [mcp/README.md 第 0 节](./mcp/README.md#0-安全边界v420-起)。
 - 外部网络：唯一外呼是 GitHub Releases API（`api.github.com`）检查新版本——3 秒超时、24 小时缓存、
   失败静默降级；请求不含任何书籍内容。
 - 子进程：无。唯一例外是打开系统文件管理器（Windows `explorer` / macOS `open` / Linux `xdg-open`），

package/cordis.patch.yml

@@ -1,4 +1,4 @@
-# dsh-novel-writer v4.0.0 bundle patch: 16 tools (incl. novel_semantic_search) + local embedding engine.
+# dsh-novel-writer v4.3.0 bundle patch: 16 tools (incl. novel_semantic_search) + local embedding engine.
 # dsh-novel-writer bundle patch: mounts the novel-writing assistant plugin
 # into the profile's loader tree. The entry's name is the plugin package
 # itself, resolved from the profile's node_modules.
@@ -7,7 +7,7 @@
 # runs in the host process (novel_* tools + /api/dsh-novel-writer/state
 # routes for the UI switch), and the dsh.client declaration in package.json
 # makes the browser half (exports "./client") load in the web GUI, mounting
-# the 「句式分析」 sidebar entry with the enable switch.
+# the 「写作助手功能」 sidebar entry with the enable switch.
 - insert:
     - id: novel-writer
       name: 'dsh-novel-writer'