novel-writer-cli 0.0.1

package/dist/validate.js

@@ -0,0 +1,131 @@
+import { join } from "node:path";
+import { NovelCliError } from "./errors.js";
+import { pathExists, readJsonFile, readTextFile } from "./fs-utils.js";
+import { checkHookPolicy } from "./hook-policy.js";
+import { loadPlatformProfile } from "./platform-profile.js";
+import { rejectPathTraversalInput } from "./safe-path.js";
+import { chapterRelPaths, formatStepId, titleFixSnapshotRel } from "./steps.js";
+import { assertTitleFixOnlyChangedTitleLine, extractChapterTitleFromMarkdown } from "./title-policy.js";
+import { isPlainObject } from "./type-guards.js";
+function requireFile(exists, relPath) {
+    if (!exists)
+        throw new NovelCliError(`Missing required file: ${relPath}`, 2);
+}
+function requireStringField(obj, field, file) {
+    const v = obj[field];
+    if (typeof v !== "string" || v.length === 0)
+        throw new NovelCliError(`Invalid ${file}: missing string field '${field}'.`, 2);
+    return v;
+}
+function requireNumberField(obj, field, file) {
+    const v = obj[field];
+    if (typeof v !== "number" || !Number.isFinite(v))
+        throw new NovelCliError(`Invalid ${file}: missing number field '${field}'.`, 2);
+    return v;
+}
+export async function validateStep(args) {
+    const warnings = [];
+    const stepId = formatStepId(args.step);
+    if (args.step.kind !== "chapter") {
+        throw new NovelCliError(`Unsupported step: ${stepId}`, 2);
+    }
+    const rel = chapterRelPaths(args.step.chapter);
+    if (args.step.stage === "draft") {
+        const absChapter = join(args.rootDir, rel.staging.chapterMd);
+        const exists = await pathExists(absChapter);
+        requireFile(exists, rel.staging.chapterMd);
+        const content = await readTextFile(absChapter);
+        if (content.trim().length === 0)
+            throw new NovelCliError(`Empty draft file: ${rel.staging.chapterMd}`, 2);
+        return { ok: true, step: stepId, warnings };
+    }
+    if (args.step.stage === "summarize") {
+        requireFile(await pathExists(join(args.rootDir, rel.staging.chapterMd)), rel.staging.chapterMd);
+        requireFile(await pathExists(join(args.rootDir, rel.staging.summaryMd)), rel.staging.summaryMd);
+        requireFile(await pathExists(join(args.rootDir, rel.staging.deltaJson)), rel.staging.deltaJson);
+        requireFile(await pathExists(join(args.rootDir, rel.staging.crossrefJson)), rel.staging.crossrefJson);
+        const deltaRaw = await readJsonFile(join(args.rootDir, rel.staging.deltaJson));
+        if (!isPlainObject(deltaRaw))
+            throw new NovelCliError(`Invalid delta JSON: ${rel.staging.deltaJson} must be an object.`, 2);
+        const delta = deltaRaw;
+        const chapter = requireNumberField(delta, "chapter", rel.staging.deltaJson);
+        if (chapter !== args.step.chapter)
+            warnings.push(`Delta.chapter is ${chapter}, expected ${args.step.chapter}.`);
+        const storylineId = requireStringField(delta, "storyline_id", rel.staging.deltaJson);
+        rejectPathTraversalInput(storylineId, "delta.storyline_id");
+        const memoryRel = chapterRelPaths(args.step.chapter, storylineId).staging.storylineMemoryMd;
+        if (!memoryRel)
+            throw new NovelCliError(`Internal error: storyline memory path is null`, 2);
+        requireFile(await pathExists(join(args.rootDir, memoryRel)), memoryRel);
+        // Crossref sanity.
+        const crossrefRaw = await readJsonFile(join(args.rootDir, rel.staging.crossrefJson));
+        if (!isPlainObject(crossrefRaw))
+            throw new NovelCliError(`Invalid crossref JSON: ${rel.staging.crossrefJson} must be an object.`, 2);
+        return { ok: true, step: stepId, warnings };
+    }
+    if (args.step.stage === "refine") {
+        requireFile(await pathExists(join(args.rootDir, rel.staging.chapterMd)), rel.staging.chapterMd);
+        const changesExists = await pathExists(join(args.rootDir, rel.staging.styleRefinerChangesJson));
+        if (!changesExists)
+            warnings.push(`Missing optional changes log: ${rel.staging.styleRefinerChangesJson}`);
+        return { ok: true, step: stepId, warnings };
+    }
+    if (args.step.stage === "judge") {
+        requireFile(await pathExists(join(args.rootDir, rel.staging.chapterMd)), rel.staging.chapterMd);
+        requireFile(await pathExists(join(args.rootDir, rel.staging.evalJson)), rel.staging.evalJson);
+        const evalRaw = await readJsonFile(join(args.rootDir, rel.staging.evalJson));
+        if (!isPlainObject(evalRaw))
+            throw new NovelCliError(`Invalid eval JSON: ${rel.staging.evalJson} must be an object.`, 2);
+        const evalObj = evalRaw;
+        const chapter = requireNumberField(evalObj, "chapter", rel.staging.evalJson);
+        if (chapter !== args.step.chapter)
+            warnings.push(`Eval.chapter is ${chapter}, expected ${args.step.chapter}.`);
+        requireNumberField(evalObj, "overall", rel.staging.evalJson);
+        requireStringField(evalObj, "recommendation", rel.staging.evalJson);
+        const loadedProfile = await loadPlatformProfile(args.rootDir);
+        const hookPolicy = loadedProfile?.profile.hook_policy;
+        if (hookPolicy?.required) {
+            const check = checkHookPolicy({ hookPolicy, evalRaw });
+            if (check.status === "invalid_eval") {
+                throw new NovelCliError(`Hook policy enabled but eval is missing required hook fields (${rel.staging.evalJson}): ${check.reason}. Re-run QualityJudge with the updated contract.`, 2);
+            }
+            if (check.status === "fail")
+                warnings.push(`Hook policy failing: ${check.reason}`);
+        }
+        return { ok: true, step: stepId, warnings };
+    }
+    if (args.step.stage === "hook-fix") {
+        const absChapter = join(args.rootDir, rel.staging.chapterMd);
+        const exists = await pathExists(absChapter);
+        requireFile(exists, rel.staging.chapterMd);
+        const content = await readTextFile(absChapter);
+        if (content.trim().length === 0)
+            throw new NovelCliError(`Empty draft file: ${rel.staging.chapterMd}`, 2);
+        return { ok: true, step: stepId, warnings };
+    }
+    if (args.step.stage === "title-fix") {
+        const absChapter = join(args.rootDir, rel.staging.chapterMd);
+        requireFile(await pathExists(absChapter), rel.staging.chapterMd);
+        const content = await readTextFile(absChapter);
+        if (content.trim().length === 0)
+            throw new NovelCliError(`Empty draft file: ${rel.staging.chapterMd}`, 2);
+        const snapshotRel = titleFixSnapshotRel(args.step.chapter);
+        const snapshotAbs = join(args.rootDir, snapshotRel);
+        requireFile(await pathExists(snapshotAbs), snapshotRel);
+        const before = await readTextFile(snapshotAbs);
+        assertTitleFixOnlyChangedTitleLine({ before, after: content, file: rel.staging.chapterMd });
+        const title = extractChapterTitleFromMarkdown(content);
+        if (!title.has_h1 || !title.title_text) {
+            throw new NovelCliError(`Invalid ${rel.staging.chapterMd}: title-fix must produce a non-empty Markdown H1 title line.`, 2);
+        }
+        return { ok: true, step: stepId, warnings };
+    }
+    if (args.step.stage === "review") {
+        warnings.push("Review step has no machine-validated outputs; resolve issues manually and re-run judge.");
+        return { ok: true, step: stepId, warnings };
+    }
+    if (args.step.stage === "commit") {
+        throw new NovelCliError(`Use 'novel commit --chapter ${args.step.chapter}' for commit.`, 2);
+    }
+    throw new NovelCliError(`Unsupported step: ${stepId}`, 2);
+}

package/docs/user/README.md

@@ -0,0 +1,17 @@
+# 用户手册
+
+本目录是 **novel-writer-cli** 的用户文档集合。这里的文档同时覆盖两层使用方式：
+
+- **CLI 层**：`novel ...`（确定性编排，不调用任何 LLM）
+- **执行器/Skill 层**：在 Claude Code / Codex 中使用 `/novel:*` 等入口命令（底层会调用 CLI，并运行各类 subagent）
+
+## 入口索引
+
+- 快速上手（Skill 入口）：[快速起步指南](quick-start.md)
+- CLI 手册（最重要）：[`novel` CLI](novel-cli.md)
+- 常用操作（Skill 入口）：[常用操作](ops.md)
+- 规范体系（文件/契约/平台画像）：[规范体系](spec-system.md)
+- Guardrails（留存/可读性/命名）：[Guardrails](guardrails.md)
+- 交互式门控（NOVEL_ASK）：[交互式门控](interactive-gates.md)
+- 故事线（storylines）：[故事线](storylines.md)
+

package/docs/user/guardrails.md

@@ -0,0 +1,179 @@
+# Guardrails（留存 / 可读性 / 命名）
+
+本项目的 Guardrails 是一组**确定性**检查：由 `platform-profile.json` 驱动，在 `novel next` 的关键节点生成可审计的 JSON 报告。当出现配置为 blocking 的问题时，`novel next` 会返回人工介入步骤（如 `...:review` / `...:title-fix`），阻止流水线推进到下一阶段。
+
+> **注意**：Guardrails 的判定发生在 CLI 层（`novel next`/`novel commit`）。当返回 `...:title-fix` / `...:review` 等步骤时，需要执行器按 instruction packet 约定运行对应 subagent，并在 `novel validate`/`novel advance` 后继续流水线。
+
+## 配置入口：`platform-profile.json`
+
+Guardrails 的配置都在项目根目录的 `platform-profile.json`：
+
+- **Retention（留存）**：`retention.title_policy`、`retention.hook_ledger`
+- **Readability（移动端可读性）**：`readability.mobile`
+- **Naming（命名冲突）**：`naming`
+
+参考配置（字段说明见下）：
+
+```json
+{
+  "retention": {
+    "title_policy": {
+      "enabled": true,
+      "min_chars": 2,
+      "max_chars": 30,
+      "forbidden_patterns": ["^\\s*$", "^(?:无题|未命名|待定)$"],
+      "auto_fix": false
+    },
+    "hook_ledger": {
+      "enabled": true,
+      "fulfillment_window_chapters": 12,
+      "diversity_window_chapters": 5,
+      "max_same_type_streak": 2,
+      "min_distinct_types_in_window": 2,
+      "overdue_policy": "warn"
+    }
+  },
+  "readability": {
+    "mobile": {
+      "enabled": true,
+      "max_paragraph_chars": 320,
+      "max_consecutive_exposition_paragraphs": 3,
+      "blocking_severity": "hard_only"
+    }
+  },
+  "naming": {
+    "enabled": true,
+    "near_duplicate_threshold": 0.88,
+    "blocking_conflict_types": ["duplicate"],
+    "exemptions": {}
+  }
+}
+```
+
+> 上述示例仅展示 guardrails 相关字段。实际 `platform-profile.json` 还包含 `compliance`（含 `banned_words` 等 schema 必填字段）、`scoring` 等其他顶级段落，详见 [规范体系 — 平台画像](spec-system.md#平台画像与不可变绑定)。
+>
+> Readability lint 脚本路径可通过 `compliance.script_paths.lint_readability` 配置（可选），缺省使用 `scripts/lint-readability.sh`。
+
+### 枚举值说明
+
+**`overdue_policy`**（hook ledger 超期策略）：
+
+| 值 | 含义 |
+|------|------|
+| `warn` | 仅警告，不阻断 |
+| `soft` | 需修订，但可被覆盖 |
+| `hard` | 阻断流水线推进 |
+
+**`blocking_severity`**（readability 阻断级别）：
+
+| 值 | 含义 |
+|------|------|
+| `hard_only` | 仅 severity=hard 的 issue 算 blocking |
+| `soft_and_hard` | soft 和 hard 均算 blocking |
+
+### 默认/降级行为
+
+- 若 `platform-profile.json` **文件不存在**：所有 guardrails 跳过（产生 warning 提示）。
+- 若 `retention`/`readability`/`naming` **字段缺失**或显式为 `null`：对应检查视为"未启用"（`status:"skipped"`）。
+- 若 `*.enabled` 为 `false`：同样视为"未启用"。
+- Readability lint 脚本缺失或执行失败时进入 `mode:"fallback"`，**只产生 warn 级问题**。这意味着 fallback 模式下 `blocking_severity` 设置实际无效——只有自定义 lint 脚本（`mode:"script"`）才能产出 `soft`/`hard` 级别的 issue。
+
+> **注意**：`retention` 和 `readability` 若为非 null 对象，则其子字段（如 `title_policy` + `hook_ledger`）均为 schema required。不可只提供其中一个。
+
+## 日志解读
+
+> `logs/` 的完整目录清单（SSOT）见 [09-logs-index.md](../dr-workflow/novel-writer-tool/final/prd/09-logs-index.md)。
+
+### Retention（留存）— `logs/retention/*`
+
+Retention 主要包含两类输出：
+
+1) **Hook ledger（章末钩子台账 + 窗口/多样性报告）**
+
+- 台账文件：`hook-ledger.json`（项目根目录）
+- 最新报告：`logs/retention/latest.json`
+- 历史报告：`logs/retention/retention-report-vol-{V:02d}-ch{start:03d}-ch{end:03d}.json`
+
+重点字段（`logs/retention/latest.json`）：
+
+- `has_blocking_issues`：为 `true` 时阻断流水线推进（取决于 `overdue_policy` 等策略）
+- `issues[]`：本窗口内的具体问题（`severity` 为 `warn|soft|hard`）
+- `debt.open[] / debt.lapsed[]`：仍未兑现/已超期的承诺条目摘要
+- `diversity.*`：最近窗口内 hook 类型分布（连击 streak、窗口内 distinct types 等）
+
+2) **Title policy（章节标题策略报告）**
+
+- 最新报告：`logs/retention/title-policy/latest.json`
+- 每章历史：`logs/retention/title-policy/title-policy-chapter-{C:03d}.json`
+
+重点字段：
+
+- `title.has_h1`：首个非空行是否为 `# H1` 标题
+- `policy`：生效的标题策略（来自 `retention.title_policy`；未启用时为 `null`）
+- `status`：`pass|warn|violation|skipped`
+- `has_hard_violations`：存在 hard 违规则通常会触发 `novel next` 的 `...:title-fix`/`...:review`
+
+> **注意**：标题检查还会使用 `compliance.banned_words`（M6 基线字段）做标题禁词检测。若标题被拒但 `forbidden_patterns` 无匹配，请检查 `banned_words` 配置。
+
+### Readability（移动端可读性 lint）— `logs/readability/*`
+
+- 最新报告：`logs/readability/latest.json`
+- 每章历史：`logs/readability/readability-report-chapter-{C:03d}.json`
+
+重点字段：
+
+- `mode`：`script` 或 `fallback`
+- `script.rel_path` / `script_error`：脚本路径与降级原因（若脚本缺失/失败）
+- `issues[]`：问题列表，fallback 模式下可检测的 issue 类型包括：
+  - `overlong_paragraph`：段落超过 `max_paragraph_chars`
+  - `exposition_run_too_long`：连续说明段超过阈值
+  - `dialogue_dense_paragraph`：单段内对话过密
+  - `mixed_quote_styles`、`mixed_ellipsis_styles`、`mixed_comma_styles`、`mixed_period_styles`、`mixed_question_mark_styles`、`mixed_exclamation_styles`：各类标点风格混用
+- `has_blocking_issues`：为 `true` 时阻断流水线推进（由 `blocking_severity` 决定"soft 是否算 blocking"）
+
+### Naming（命名冲突 lint）— `logs/naming/*`
+
+- 最新报告：`logs/naming/latest.json`
+- 每章历史：`logs/naming/naming-report-chapter-{C:03d}.json`
+
+重点字段：
+
+- `registry.total_characters / total_names`：当前角色档案规模（来自 `characters/active/*.json` + aliases）
+- `issues[]`：冲突列表，`conflict_type` 可选值：
+  - `duplicate`：重名（同名不同人）
+  - `near_duplicate`：近似名（相似度 ≥ `near_duplicate_threshold`）
+  - `alias_collision`：别名与他人 canonical/alias 冲突
+  - `unknown_entity_confusion`：NER 检测到的未知实体与已有角色名相似（始终为 warn，依赖 NER 预计算）
+- `has_blocking_issues`：为 `true` 时阻断流水线推进（由 `naming.blocking_conflict_types` 决定哪些冲突属于 hard）
+
+## 常见修复速查
+
+### Title policy
+
+- 确保首个非空行为 `# 标题`（H1）
+- 调整标题长度、避免命中 `forbidden_patterns`（同时注意 `compliance.banned_words` 也会影响标题检查）
+- 若 `auto_fix` 设为 `true`：`novel next` 可能先返回 `chapter:NNN:title-fix`（只允许改标题行；最多一次）
+
+### Readability
+
+- 将超长段落拆分为更短段落（或增加对话/动作打断）
+- 避免同章内混用标点风格（例如 `...` vs `……`、`,` vs `，`、`"` vs `""`）
+- 若你有自定义 lint 脚本：配置 `compliance.script_paths.lint_readability` 指向它；脚本失败会自动降级到 fallback（不阻断）
+
+### Naming
+
+- 在 `characters/active/*.json` 里重命名冲突角色，或为角色添加/整理 `aliases`
+- 使用 `naming.exemptions` 做白名单（当前仅支持 `ignore_names` 和 `allow_pairs` 两个字段，其余字段会被忽略）：
+
+```json
+{
+  "naming": {
+    "exemptions": {
+      "ignore_names": ["老王"],
+      "allow_pairs": [["张三", "张山"]]
+    }
+  }
+}
+```
+
+> `ignore_names` 中的名字会经过规范化（trim + 去空白 + toLowerCase）再匹配。`allow_pairs` 顺序无关——`["张三", "张山"]` 与 `["张山", "张三"]` 等价。

package/docs/user/interactive-gates.md

@@ -0,0 +1,124 @@
+# 交互式门控（`NOVEL_ASK`）
+
+`NOVEL_ASK` 是一种**工具无关**的问卷/提问中间表示（IR），用于把“必须由用户确认/选择的信息”从自然语言模板中抽离出来，变成：
+
+- 可审计：落盘为标准化 AnswerSpec JSON
+- 可恢复：重跑执行器时若答案已存在且校验通过，跳过重复提问
+- 可跨执行器：Claude Code / Codex 以不同交互能力呈现，但产出相同 AnswerSpec
+
+## 端到端最短示例（InstructionPacket → AnswerSpec → main step）
+
+### 1) InstructionPacket 里声明 gate
+
+当 instruction packet 同时包含 `novel_ask` + `answer_path` 时，表示该 step 在执行 agent 之前有一个前置 gate：
+
+```json
+{
+  "version": 1,
+  "step": "chapter:048:draft",
+  "agent": { "kind": "subagent", "name": "chapter-writer" },
+  "manifest": { "mode": "paths", "inline": {}, "paths": {} },
+  "novel_ask": {
+    "version": 1,
+    "topic": "platform binding",
+    "questions": [
+      {
+        "id": "platform",
+        "header": "Platform",
+        "question": "你准备发布到哪个平台？",
+        "kind": "single_choice",
+        "required": true,
+        "options": [
+          { "label": "qidian", "description": "起点" },
+          { "label": "jjwxc", "description": "晋江" },
+          { "label": "web", "description": "自建站/博客" }
+        ],
+        "default": "qidian"
+      }
+    ]
+  },
+  "answer_path": "staging/novel-ask/chapter-048-draft.answers.json",
+  "expected_outputs": [
+    {
+      "path": "staging/novel-ask/chapter-048-draft.answers.json",
+      "required": true,
+      "note": "AnswerSpec JSON record for the NOVEL_ASK gate (written before main step execution)."
+    },
+    { "path": "staging/chapters/chapter-048.md", "required": true }
+  ],
+  "next_actions": [
+    { "kind": "command", "command": "novel validate chapter:048:draft" },
+    { "kind": "command", "command": "novel advance chapter:048:draft" }
+  ]
+}
+```
+
+### 2) 执行器完成提问后，写入 AnswerSpec 到 answer_path
+
+```json
+{
+  "version": 1,
+  "topic": "platform binding",
+  "answers": {
+    "platform": "qidian"
+  },
+  "answered_at": "2026-02-27T10:12:34.000Z",
+  "answered_by": "claude_code"
+}
+```
+
+> `answered_by` 是审计字段：建议在 Claude Code 适配器写入 `claude_code`，在 Codex 适配器写入 `codex`（也可以用 `human` 等）。
+
+### 3) gate 通过后再执行主 agent
+
+- 若 `answer_path` 已存在且校验通过：直接执行主 agent（可恢复语义）
+- 若缺失：执行器必须先完成提问并写入 AnswerSpec
+- 若存在但无效：该 step 视为 **blocked**，不得继续执行主 agent（需修复/删除 AnswerSpec 后重试）
+
+## `answer_path` 约定与校验行为
+
+### `answer_path` 约定（推荐）
+
+`answer_path` 由编排器提供，且必须是 **project-relative** 路径。
+
+推荐放在 `staging/novel-ask/` 下，并在文件名中包含 step 信息，便于审计与回放，例如：
+
+- `staging/novel-ask/chapter-048-draft.answers.json`
+- `staging/novel-ask/novel-init.answers.json`
+
+> 需要重做 gate 时：删除该 AnswerSpec 文件，重新运行执行器即可触发再次提问。
+
+### 校验行为（摘要）
+
+执行器在进入主 agent 之前必须确保：
+
+- `answer_path` 必须是非空的项目相对路径：不允许绝对路径、`..` 段，且解析后不得逃出项目根目录
+- AnswerSpec 是合法 JSON object
+- `version/topic` 与 QuestionSpec 一致
+- `answers` 的 key 必须是 `snake_case`，且必须能在 QuestionSpec 里找到同名 question id（不允许多写未知字段）
+- required=true 的问题必须回答
+- `allow_other`（可选，默认 false）：设为 `true` 时允许 choice 问题回答不在 option labels 内的自定义字符串
+- choice 问题：当 `allow_other` 不是 `true` 时，答案必须落在 option labels 内
+- multi_choice：
+  - required=true：至少选 1 个
+  - required=false：若 0 选择，**必须完全不写入该 question id**（写空数组会被校验拒绝）
+  - 不允许重复选项（数组内 duplicate 会被校验拒绝）
+
+## Claude Code vs Codex：交互差异与降级策略
+
+目标是：**交互体验可以不同，但最终落盘的 AnswerSpec 必须一致**。
+
+### Claude Code（`AskUserQuestion`）
+
+- 优先编译为一个或多个 `AskUserQuestion`
+- `options[]` 每次有数量上限（2-4），选项过多时需要分页/循环
+- `free_text` 可能需要依赖 UI 的 “Other” 输入；若不可用可提示用户用普通消息输入再由适配器写入 AnswerSpec
+
+详见：`skills/cli-step/SKILL.md`
+
+### Codex（Plan Mode `request_user_input` + JSON fallback）
+
+- Plan Mode 下优先用 `request_user_input`（每题选项上限更低，且为互斥选项）
+- 若工具不可用或无法可靠表达语义（例如 `free_text`）：退化为严格 JSON 回答格式，由适配器构造 + 校验 AnswerSpec 后落盘
+
+详见：`.codex/skills/novel-cli-step/SKILL.md`