novel-writer-cli 0.0.1

package/docs/user/storylines.md

@@ -0,0 +1,144 @@
+# 多线叙事指南
+
+本系统支持多 POV 群像、势力暗线、跨卷伏笔交汇等复杂叙事结构。
+
+## 核心概念
+
+### 故事线（Storyline）
+
+每条故事线有固定 ID（连字符命名，如 `main-arc`、`faction-war`），一经定义不可重命名。
+
+**类型**（`type:` 前缀）：
+
+| 类型 | 说明 |
+|------|------|
+| `type:main_arc` | 主线，贯穿全书 |
+| `type:faction_conflict` | 势力冲突线 |
+| `type:conspiracy` | 阴谋暗线 |
+| `type:mystery` | 悬疑/谜题线 |
+| `type:character_arc` | 角色成长线 |
+| `type:parallel_timeline` | 平行时间线 |
+
+### 卷级角色（Volume Role）
+
+每条故事线在每卷中有不同角色：
+
+- **primary**：本卷主要推进的线（通常 1-2 条）
+- **secondary**：辅助线，有最小出场频率要求
+- **seasoning**：调味线，偶尔出场，不做频率要求
+
+## 快速起步
+
+快速起步阶段，系统只初始化 1 条 `type:main_arc` 主线：
+
+```json
+{
+  "storylines": [
+    {
+      "id": "main-arc",
+      "name": "主线名称",
+      "type": "type:main_arc",
+      "scope": "novel",
+      "status": "active"
+    }
+  ]
+}
+```
+
+后续在卷规划阶段，PlotArchitect 会根据剧情需要建议新增故事线。
+
+## 活跃线限制
+
+**同时活跃 ≤4 条**。这是硬约束（LS-002），超出时系统会要求你暂停或合并故事线。
+
+为什么限制 4 条？因为每章写作时 ChapterWriter 需要接收所有活跃线的 context，线太多会导致 context 过载和串线风险。
+
+## 卷级调度
+
+进入卷规划时，PlotArchitect 生成 `storyline-schedule.json`：
+
+```json
+{
+  "active_storylines": [
+    { "storyline_id": "main-arc", "volume_role": "primary" },
+    { "storyline_id": "faction-war", "volume_role": "secondary" }
+  ],
+  "interleaving_pattern": {
+    "secondary_min_appearance": "every_8_chapters"
+  },
+  "convergence_events": [
+    {
+      "event": "两线在第 20 章交汇",
+      "involved_storylines": ["main-arc", "faction-war"],
+      "target_chapter_range": [18, 22]
+    }
+  ]
+}
+```
+
+关键字段：
+
+- `secondary_min_appearance`：副线最小出场间隔（如 `every_8_chapters` = 每 8 章至少出现 1 次）
+- `convergence_events`：交汇事件——多条线在指定章节范围内汇合
+
+## 防串线机制
+
+三层防护：
+
+1. **结构化 Context**：ChapterWriter 每次只接收当前章相关的故事线状态，而非全部
+2. **反串线指令**：prompt 中明确标注「本章属于 X 线，不得出现 Y 线的信息」
+3. **QualityJudge 后验**：LS-005 规则检查跨线实体是否泄漏
+
+每次续写都是独立的 LLM 调用，不依赖前一章的会话历史。
+
+## 交汇事件
+
+当多条故事线需要汇合时（如主角终于遇到暗线反派），在 `convergence_events` 中定义：
+
+- 涉及哪些线
+- 目标章节范围
+- 交汇后的状态变化
+
+卷末回顾时，系统会检查交汇事件是否在预定范围内达成。
+
+## 故事线记忆
+
+每条故事线有独立记忆文件 `storylines/{id}/memory.md`（≤500 字），由 Summarizer 每章更新。
+
+记忆文件记录这条线的关键事实，供 ChapterWriter 写作时参考，避免遗忘已建立的设定。
+
+## 桥梁关系
+
+故事线之间可以定义桥梁（bridge），表示两条线通过共享伏笔或角色关联：
+
+```json
+{
+  "relationships": [
+    {
+      "from": "main-arc",
+      "to": "conspiracy",
+      "type": "bridge:shared_foreshadowing",
+      "bridges": {
+        "shared_foreshadowing": ["foreshadow-id-1", "foreshadow-id-2"]
+      }
+    }
+  ]
+}
+```
+
+卷末回顾时，系统检查桥梁是否断链（共享伏笔是否在全局索引中存在）。
+
+## 日常操作
+
+| 场景 | 操作 |
+|------|------|
+| 新增故事线 | 卷规划时由 PlotArchitect 建议，你确认 |
+| 暂停故事线 | 将 status 改为 `dormant`（不计入活跃线） |
+| 合并故事线 | 交汇事件达成后，将一条线标记为 `resolved` |
+| 查看节奏 | `/novel:status` 展示各线出场频率和休眠提醒 |
+
+## 注意事项
+
+- 故事线 ID 用连字符（`main-arc`），类型用下划线 + `type:` 前缀（`type:main_arc`）
+- 不要手动编辑 `storylines/storylines.json`，通过 `/novel:start` → 更新设定来操作
+- 多线体系的完整能力在卷规划阶段才会展开，快速起步阶段保持简单

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "novel-writer-cli",
+  "version": "0.0.1",
+  "description": "Executor-agnostic novel orchestration CLI",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "novel": "dist/cli.js",
+    "novel-writer-cli": "dist/cli.js"
+  },
+  "files": [
+    "dist/",
+    "agents/",
+    "skills/",
+    "schemas/",
+    "scripts/",
+    "templates/",
+    "docs/user/",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DankerMu/novel-writer-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/DankerMu/novel-writer-cli/issues"
+  },
+  "homepage": "https://github.com/DankerMu/novel-writer-cli#readme",
+  "scripts": {
+    "dev": "tsx src/cli.ts",
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/cli.js",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test dist/__tests__/*.test.js"
+  },
+  "dependencies": {
+    "commander": "^14.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "tsx": "^4.20.0",
+    "typescript": "^5.9.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/schemas/README.md

@@ -0,0 +1,18 @@
+# JSON Schemas
+
+This directory contains machine-readable JSON Schemas that act as **single sources of truth** (SSOT) for project-facing JSON/JSONL files.
+
+## Integration plan
+
+- Templates SHOULD be derived from these schemas (and may include a `$schema` pointer for editor tooling).
+- Runtime validators SHOULD validate project files against these schemas (e.g., via Ajv or python-jsonschema) and fail fast on enum/range violations.
+- Specs SHOULD reference the schema path instead of duplicating field definitions.
+
+## Available schemas
+
+- `schemas/platform-profile.schema.json` — `platform-profile.json` (M6 baseline + M7 optional extensions)
+- `schemas/hook-ledger.schema.json` — `hook-ledger.json` (M7 retention hook ledger)
+- `schemas/promise-ledger.schema.json` — `promise-ledger.json` (M7 long-horizon narrative promise ledger)
+- `schemas/engagement-metrics.schema.json` — `engagement-metrics.jsonl` record (M7 engagement density stream)
+- `schemas/character-voice-profiles.schema.json` — `character-voice-profiles.json` (M7 per-character voice profiles)
+- `schemas/character-voice-drift.schema.json` — `character-voice-drift.json` (M7 voice drift directives)

package/schemas/character-voice-drift.schema.json

@@ -0,0 +1,135 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "schema_version": 1,
+  "title": "character-voice-drift.json",
+  "type": "object",
+  "required": ["schema_version", "generated_at", "as_of", "window", "profiles_path", "characters"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Optional schema pointer for editor tooling. Example: schemas/character-voice-drift.schema.json"
+    },
+    "schema_version": {
+      "type": "integer",
+      "enum": [1],
+      "description": "Schema version of character-voice-drift.json (SSOT in schemas/character-voice-drift.schema.json)."
+    },
+    "generated_at": { "type": "string", "format": "date-time" },
+    "as_of": {
+      "type": "object",
+      "required": ["chapter", "volume"],
+      "additionalProperties": false,
+      "properties": {
+        "chapter": { "type": "integer", "minimum": 1 },
+        "volume": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "window": {
+      "type": "object",
+      "required": ["chapter_start", "chapter_end", "window_chapters"],
+      "additionalProperties": false,
+      "properties": {
+        "chapter_start": { "type": "integer", "minimum": 1 },
+        "chapter_end": { "type": "integer", "minimum": 1 },
+        "window_chapters": { "type": "integer", "minimum": 1 }
+      }
+    },
+    "profiles_path": { "type": "string", "minLength": 1 },
+    "characters": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/character" }
+    }
+  },
+  "$defs": {
+    "drifted_metric": {
+      "type": "object",
+      "required": ["id", "baseline", "current", "detail"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "baseline": { "type": "number" },
+        "current": { "type": "number" },
+        "detail": { "type": "string", "minLength": 1 }
+      }
+    },
+    "signature_phrases": {
+      "type": "object",
+      "required": ["baseline", "current", "overlap"],
+      "additionalProperties": false,
+      "properties": {
+        "baseline": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "current": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "overlap": { "type": ["number", "null"], "minimum": 0, "maximum": 1 }
+      }
+    },
+    "metrics": {
+      "type": "object",
+      "required": [
+        "dialogue_samples",
+        "dialogue_chars",
+        "dialogue_len_avg",
+        "dialogue_len_p25",
+        "dialogue_len_p50",
+        "dialogue_len_p75",
+        "sentence_len_avg",
+        "sentence_len_p25",
+        "sentence_len_p50",
+        "sentence_len_p75",
+        "exclamation_per_100_chars",
+        "question_per_100_chars",
+        "ellipsis_per_100_chars"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "dialogue_samples": { "type": "integer", "minimum": 0 },
+        "dialogue_chars": { "type": "integer", "minimum": 0 },
+        "dialogue_len_avg": { "type": "number", "minimum": 0 },
+        "dialogue_len_p25": { "type": "integer", "minimum": 0 },
+        "dialogue_len_p50": { "type": "integer", "minimum": 0 },
+        "dialogue_len_p75": { "type": "integer", "minimum": 0 },
+        "sentence_len_avg": { "type": "number", "minimum": 0 },
+        "sentence_len_p25": { "type": "integer", "minimum": 0 },
+        "sentence_len_p50": { "type": "integer", "minimum": 0 },
+        "sentence_len_p75": { "type": "integer", "minimum": 0 },
+        "exclamation_per_100_chars": { "type": "number", "minimum": 0 },
+        "question_per_100_chars": { "type": "number", "minimum": 0 },
+        "ellipsis_per_100_chars": { "type": "number", "minimum": 0 }
+      }
+    },
+    "evidence": {
+      "type": "object",
+      "required": ["chapter", "excerpt"],
+      "additionalProperties": false,
+      "properties": {
+        "chapter": { "type": "integer", "minimum": 1 },
+        "excerpt": { "type": "string", "minLength": 1 }
+      }
+    },
+    "character": {
+      "type": "object",
+      "required": [
+        "character_id",
+        "display_name",
+        "drifted_metrics",
+        "signature_phrases",
+        "baseline_metrics",
+        "current_metrics",
+        "evidence",
+        "directives"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "character_id": { "type": "string", "minLength": 1 },
+        "display_name": { "type": "string", "minLength": 1 },
+        "drifted_metrics": { "type": "array", "items": { "$ref": "#/$defs/drifted_metric" } },
+        "signature_phrases": { "$ref": "#/$defs/signature_phrases" },
+        "baseline_metrics": { "$ref": "#/$defs/metrics" },
+        "current_metrics": { "$ref": "#/$defs/metrics" },
+        "evidence": { "type": "array", "items": { "$ref": "#/$defs/evidence" } },
+        "directives": { "type": "array", "items": { "type": "string", "minLength": 1 } }
+      }
+    }
+  }
+}
+

package/schemas/character-voice-profiles.schema.json

@@ -0,0 +1,141 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "schema_version": 1,
+  "title": "character-voice-profiles.json",
+  "type": "object",
+  "required": ["schema_version", "created_at", "selection", "policy", "profiles"],
+  "additionalProperties": false,
+  "patternProperties": {
+    "^_.*$": { "$ref": "#/$defs/comment_value" }
+  },
+  "propertyNames": {
+    "not": { "enum": ["__proto__", "constructor", "prototype"] }
+  },
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Optional schema pointer for editor tooling. Example: schemas/character-voice-profiles.schema.json"
+    },
+    "schema_version": {
+      "type": "integer",
+      "enum": [1],
+      "description": "Schema version of character-voice-profiles.json (SSOT in schemas/character-voice-profiles.schema.json)."
+    },
+    "created_at": { "type": "string", "format": "date-time" },
+    "selection": { "$ref": "#/$defs/selection" },
+    "policy": { "$ref": "#/$defs/policy" },
+    "profiles": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/profile" }
+    }
+  },
+  "$defs": {
+    "comment_value": {
+      "description": "Free-form comment fields supported by templates/specs.",
+      "type": ["string", "number", "boolean", "null", "object", "array"]
+    },
+    "selection": {
+      "type": "object",
+      "required": ["protagonist_id"],
+      "additionalProperties": false,
+      "properties": {
+        "protagonist_id": { "type": "string", "minLength": 1 },
+        "core_cast_ids": { "type": "array", "items": { "type": "string", "minLength": 1 } }
+      }
+    },
+    "thresholds": {
+      "type": "object",
+      "required": [
+        "avg_dialogue_chars_ratio_low",
+        "avg_dialogue_chars_ratio_high",
+        "exclamation_per_100_chars_delta",
+        "question_per_100_chars_delta",
+        "ellipsis_per_100_chars_delta",
+        "signature_overlap_min"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "avg_dialogue_chars_ratio_low": { "type": "number", "exclusiveMinimum": 0 },
+        "avg_dialogue_chars_ratio_high": { "type": "number", "exclusiveMinimum": 0 },
+        "exclamation_per_100_chars_delta": { "type": "number", "minimum": 0 },
+        "question_per_100_chars_delta": { "type": "number", "minimum": 0 },
+        "ellipsis_per_100_chars_delta": { "type": "number", "minimum": 0 },
+        "signature_overlap_min": { "type": "number", "minimum": 0, "maximum": 1 }
+      }
+    },
+    "policy": {
+      "type": "object",
+      "required": ["window_chapters", "min_dialogue_samples", "drift_thresholds", "recovery_thresholds"],
+      "additionalProperties": false,
+      "properties": {
+        "window_chapters": { "type": "integer", "minimum": 1 },
+        "min_dialogue_samples": { "type": "integer", "minimum": 1 },
+        "drift_thresholds": { "$ref": "#/$defs/thresholds" },
+        "recovery_thresholds": { "$ref": "#/$defs/thresholds" }
+      }
+    },
+    "metrics": {
+      "type": "object",
+      "required": [
+        "dialogue_samples",
+        "dialogue_chars",
+        "dialogue_len_avg",
+        "dialogue_len_p25",
+        "dialogue_len_p50",
+        "dialogue_len_p75",
+        "sentence_len_avg",
+        "sentence_len_p25",
+        "sentence_len_p50",
+        "sentence_len_p75",
+        "exclamation_per_100_chars",
+        "question_per_100_chars",
+        "ellipsis_per_100_chars"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "dialogue_samples": { "type": "integer", "minimum": 0 },
+        "dialogue_chars": { "type": "integer", "minimum": 0 },
+        "dialogue_len_avg": { "type": "number", "minimum": 0 },
+        "dialogue_len_p25": { "type": "integer", "minimum": 0 },
+        "dialogue_len_p50": { "type": "integer", "minimum": 0 },
+        "dialogue_len_p75": { "type": "integer", "minimum": 0 },
+        "sentence_len_avg": { "type": "number", "minimum": 0 },
+        "sentence_len_p25": { "type": "integer", "minimum": 0 },
+        "sentence_len_p50": { "type": "integer", "minimum": 0 },
+        "sentence_len_p75": { "type": "integer", "minimum": 0 },
+        "exclamation_per_100_chars": { "type": "number", "minimum": 0 },
+        "question_per_100_chars": { "type": "number", "minimum": 0 },
+        "ellipsis_per_100_chars": { "type": "number", "minimum": 0 }
+      }
+    },
+    "profile": {
+      "type": "object",
+      "required": ["character_id", "display_name", "baseline_range", "baseline_metrics", "signature_phrases"],
+      "additionalProperties": false,
+      "patternProperties": {
+        "^_.*$": { "$ref": "#/$defs/comment_value" }
+      },
+      "propertyNames": {
+        "not": { "enum": ["__proto__", "constructor", "prototype"] }
+      },
+      "properties": {
+        "character_id": { "type": "string", "minLength": 1 },
+        "display_name": { "type": "string", "minLength": 1 },
+        "name_variants": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "baseline_range": {
+          "type": "object",
+          "required": ["chapter_start", "chapter_end"],
+          "additionalProperties": false,
+          "properties": {
+            "chapter_start": { "type": "integer", "minimum": 1 },
+            "chapter_end": { "type": "integer", "minimum": 1 }
+          }
+        },
+        "baseline_metrics": { "$ref": "#/$defs/metrics" },
+        "signature_phrases": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "taboo_phrases": { "type": "array", "items": { "type": "string", "minLength": 1 } }
+      }
+    }
+  }
+}
+

package/schemas/engagement-metrics.schema.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "schema_version": 1,
+  "title": "engagement-metrics.jsonl record",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "generated_at",
+    "chapter",
+    "volume",
+    "word_count",
+    "plot_progression_beats",
+    "conflict_intensity",
+    "payoff_score",
+    "new_info_load_score",
+    "notes"
+  ],
+  "additionalProperties": false,
+  "propertyNames": {
+    "not": { "enum": ["__proto__", "constructor", "prototype"] }
+  },
+  "properties": {
+    "schema_version": {
+      "type": "integer",
+      "enum": [1],
+      "description": "Schema version of each engagement-metrics.jsonl record."
+    },
+    "generated_at": { "type": "string", "format": "date-time" },
+    "chapter": { "type": "integer", "minimum": 1 },
+    "volume": { "type": "integer", "minimum": 0 },
+    "word_count": { "type": "integer", "minimum": 0 },
+    "plot_progression_beats": { "type": "integer", "minimum": 0 },
+    "conflict_intensity": { "type": "integer", "minimum": 1, "maximum": 5 },
+    "payoff_score": { "type": "integer", "minimum": 1, "maximum": 5 },
+    "new_info_load_score": { "type": "integer", "minimum": 1, "maximum": 5 },
+    "notes": { "type": "string", "minLength": 1, "pattern": "\\S", "maxLength": 320 }
+  }
+}

package/schemas/hook-ledger.schema.json

@@ -0,0 +1,108 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "schema_version": 1,
+  "title": "hook-ledger.json",
+  "type": "object",
+  "required": ["schema_version", "entries"],
+  "additionalProperties": false,
+  "patternProperties": {
+    "^_.*$": { "$ref": "#/$defs/comment_value" }
+  },
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Optional schema pointer for editor tooling. Example: schemas/hook-ledger.schema.json"
+    },
+    "schema_version": {
+      "type": "integer",
+      "enum": [1],
+      "description": "Schema version of hook-ledger.json (SSOT in schemas/hook-ledger.schema.json)."
+    },
+    "entries": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/hook_ledger_entry" }
+    }
+  },
+  "$defs": {
+    "comment_value": {
+      "description": "Free-form comment fields supported by templates/specs.",
+      "type": ["string", "number", "boolean", "null", "object", "array"]
+    },
+    "hook_ledger_entry": {
+      "type": "object",
+      "required": [
+        "id",
+        "chapter",
+        "hook_type",
+        "hook_strength",
+        "promise_text",
+        "status",
+        "fulfillment_window",
+        "fulfilled_chapter",
+        "created_at",
+        "updated_at"
+      ],
+      "additionalProperties": false,
+      "patternProperties": {
+        "^_.*$": { "$ref": "#/$defs/comment_value" }
+      },
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "chapter": { "type": "integer", "minimum": 1 },
+        "hook_type": { "type": "string", "minLength": 1 },
+        "hook_strength": { "type": "integer", "minimum": 1, "maximum": 5 },
+        "promise_text": { "type": "string", "minLength": 1 },
+        "status": { "type": "string", "enum": ["open", "fulfilled", "lapsed"] },
+        "fulfillment_window": {
+          "type": "array",
+          "minItems": 2,
+          "maxItems": 2,
+          "items": { "type": "integer", "minimum": 1 }
+        },
+        "fulfilled_chapter": {
+          "type": ["integer", "null"],
+          "minimum": 1
+        },
+        "created_at": { "type": "string", "format": "date-time" },
+        "updated_at": { "type": "string", "format": "date-time" },
+        "evidence_snippet": { "type": "string" },
+        "sources": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "eval_path": { "type": "string", "minLength": 1 }
+          }
+        },
+        "links": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "promise_ids": {
+              "type": "array",
+              "items": { "type": "string", "minLength": 1 }
+            },
+            "foreshadowing_ids": {
+              "type": "array",
+              "items": { "type": "string", "minLength": 1 }
+            }
+          }
+        },
+        "history": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["at", "chapter", "action"],
+            "additionalProperties": false,
+            "properties": {
+              "at": { "type": "string", "format": "date-time" },
+              "chapter": { "type": "integer", "minimum": 1 },
+              "action": { "type": "string", "minLength": 1 },
+              "detail": { "type": "string" }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+