novel-writer-cli 0.0.1

package/docs/user/novel-cli.md

@@ -0,0 +1,289 @@
+# `novel` CLI（确定性编排核心）
+
+`novel` CLI **不调用任何 LLM API**。它只负责：
+
+- 读取 `.checkpoint.json` 和 `staging/**` 计算确定性的下一步（可中断/可恢复）
+- 生成 instruction packet（JSON），作为“编排 → 执行器（Claude Code / Codex）”的稳定边界
+- 校验 `staging/**` 产物（validate）并推进 checkpoint（advance）
+- 将 `staging/**` 事务提交到正式目录（commit），并更新 `state/` 与 `foreshadowing/`
+
+## 全局选项
+
+- `--project <dir>`：指定小说项目根目录（默认从当前目录向上查找 `.checkpoint.json`）
+- `--json`：输出单个 JSON 对象（便于执行器/脚本消费）；不加时为人类可读输出
+
+## 命令速览
+
+| 命令 | 用途 |
+|------|------|
+| `novel status` | 查看 checkpoint / lock / next（只读） |
+| `novel next` | 计算确定性的下一步 step id |
+| `novel instructions <step>` | 输出 instruction packet（JSON） |
+| `novel validate <step>` | 校验 step 产物是否齐全/合规 |
+| `novel advance <step>` | 校验通过后推进 checkpoint |
+| `novel commit --chapter N` | 提交 staging 事务到正式目录（写入） |
+| `novel lock status/clear` | 查看/清理写入锁（解决中断导致的 stale lock） |
+| `novel promises init/report` | 承诺台账：初始化与窗口报告 |
+| `novel engagement report` | 参与度密度：窗口报告 |
+| `novel voice init/check` | 角色语气画像 + 漂移检测 |
+
+## 安装（npm）
+
+```bash
+npm i -g novel-writer-cli
+novel --help
+```
+
+或一次性运行：
+
+```bash
+npx novel-writer-cli --help
+```
+
+## 开发态运行（本仓库）
+
+```bash
+# 帮助
+npm run dev -- --help
+
+# 或构建后运行
+npm run build
+node dist/cli.js --help
+```
+
+## 最短路径：跑通“一章的确定性编排”
+
+以下示例假设你已在**小说项目根目录**（含 `.checkpoint.json`），或使用 `--project <dir>` 指定根目录。
+
+### 1) 计算下一步
+
+```bash
+novel next
+# 或：novel next --json
+```
+
+输出类似：
+
+```
+chapter:003:draft
+```
+
+### 2) 获取 instruction packet
+
+```bash
+novel instructions "chapter:003:draft" --json
+```
+
+可选：落盘到 `staging/manifests/`（便于审计/回放）：
+
+```bash
+novel instructions "chapter:003:draft" --json --write-manifest
+```
+
+可选：为执行器提供少量内嵌内容（当前仅支持 `brief` 模式，注入 `brief.md` 的前 2000 字预览）。使用该选项后 `packet.manifest.mode` 会变为 `paths+embed`，并携带 `packet.manifest.embed.brief_preview`：
+
+```bash
+novel instructions "chapter:003:draft" --json --write-manifest --embed brief
+```
+
+### 3) 用执行器跑这一步（Claude Code / Codex）
+
+执行器读取 instruction packet：
+
+- `packet.agent.name`：要运行的 subagent（如 `chapter-writer`）
+- `packet.manifest`：context manifest（以路径为主）
+- `packet.expected_outputs[]`：该步必须写入的 `staging/**` 目标文件
+
+可选：若 packet 同时包含 `novel_ask` + `answer_path`，则该 step 在执行 agent 之前存在一个**交互式 gate**：
+
+- 执行器必须先采集答案并写入 AnswerSpec JSON 到 `answer_path`（并通过校验），才允许继续执行 agent
+- 若 `answer_path` 已存在且校验通过，则直接跳过提问（可恢复/可审计）
+
+详见 [交互式门控（NOVEL_ASK）](interactive-gates.md)。
+
+执行器跑完后应回到终端断点（不要自动 commit）。
+
+### 4) 校验并推进 checkpoint
+
+```bash
+novel validate "chapter:003:draft"
+novel advance "chapter:003:draft"
+```
+
+然后再次运行：
+
+```bash
+novel next
+```
+
+它会基于 `.checkpoint.json.pipeline_stage` + `inflight_chapter` + `staging/**` 的存在性，返回确定性的下一步（例如 `chapter:003:summarize`）。
+
+### 5) 提交事务（commit）
+
+当 `novel next` 返回 `chapter:003:commit` 时：
+
+```bash
+novel commit --chapter 3
+```
+
+可先看计划但不落盘：
+
+```bash
+novel commit --chapter 3 --dry-run
+```
+
+commit 会执行（见 PRD §10.4）：
+
+- 移动 staging 产物到正式目录：`chapters/`、`summaries/`、`evaluations/`、`storylines/`、`state/`
+- 合并 `staging/state/chapter-XXX-delta.json` → `state/current-state.json`（并 append `state/changelog.jsonl`）
+- 从 delta 的 `foreshadow` ops 更新 `foreshadowing/global.json`
+- 更新 `.checkpoint.json`：`last_completed_chapter`、`pipeline_stage="committed"`、`inflight_chapter=null`
+
+## `status`：快速查看项目状态（只读）
+
+```bash
+novel status
+# 或：novel status --json
+```
+
+输出包含：checkpoint 摘要、lock 状态、以及当前 `novel next` 会返回的下一步。
+
+## `lock`：写入锁（解决并发与中断残留）
+
+`novel` 在需要写入项目文件时会使用项目根目录下的 `.novel.lock/` 目录作为写入锁（防止多个会话同时写导致状态损坏）。
+
+```bash
+# 查看锁状态
+novel lock status
+
+# 清理 stale lock（默认 >30min 视为 stale；活跃锁会拒绝清理）
+novel lock clear
+```
+
+> 常见场景：执行器在写入阶段中断（断电/kill/异常退出），留下 stale lock；此时可先 `novel lock status` 确认，再执行 `novel lock clear`。
+
+## 角色语气漂移（M7H.3，可选）
+
+角色语气漂移用于：为关键角色建立“台词基线画像”，并在后续章节检测偏移，生成纠偏指令 `character-voice-drift.json`，直到恢复为止（自动清除）。
+
+```bash
+# 初始化基线画像（建议在 quick-start 章节后）
+novel voice init --protagonist <character_id> --core-cast a,b,c --apply
+
+# 若 character-voice-profiles.json 已存在：用 --force --apply 覆盖（--force 仅在 --apply 时生效）
+novel voice init --protagonist <character_id> --core-cast a,b,c --force --apply
+
+# 手动检测/更新漂移文件（预览：不写文件；加 --apply 则写/清理）
+novel voice check --apply
+```
+
+一旦存在 `character-voice-drift.json`，后续 `chapter:*:draft` / `chapter:*:refine` 的 instruction packet 会自动注入纠偏指令（`packet.manifest.inline.character_voice_drift` + `packet.manifest.paths.character_voice_drift`）。
+
+## 长周期承诺台账（M7H.1，可选）
+
+承诺台账用于跟踪跨章/跨卷的“卖点/谜团/机制/关系弧”等长周期承诺，避免长时间不触碰导致读者遗忘。
+
+- 台账文件：`promise-ledger.json`（schema：`schemas/promise-ledger.schema.json`）
+- 窗口报告：`logs/promises/latest.json`（可选 history：`logs/promises/promise-ledger-report-vol-{V:02d}-ch{start:03d}-ch{end:03d}.json`）
+
+常用命令：
+
+```bash
+# 预览 seed（不写文件；用 --json 查看）
+novel promises init --json
+
+# 写入 promise-ledger.json（可选 --max-recent-summaries <n> 控制参考摘要数量）
+novel promises init --apply
+
+# 生成窗口报告（默认 scope=最近 10 章，展示 top 5 条待唤醒承诺；加 --history 同时写入 history 文件）
+# 前提：需先执行 novel promises init --apply 生成台账
+novel promises report --history
+```
+
+> `promise-ledger.json` 是用户可维护的台账；窗口报告是基于台账计算得到的“可执行建议”，用于规划/写作时参考（默认仅提示 / 不参与 blocking 判定）。
+
+## 参与度密度指标（M7H.2，可选）
+
+参与度密度用于对“推进/冲突/奖励/信息投放”的节奏做可度量的窗口化检查，避免连续多章低密度导致掉线。
+
+- 指标流：`engagement-metrics.jsonl`（由 `novel commit` 每章自动 append 一条记录；schema：`schemas/engagement-metrics.schema.json`）
+- 窗口报告：`logs/engagement/latest.json`（可选 history：`logs/engagement/engagement-report-vol-{V:02d}-ch{start:03d}-ch{end:03d}.json`）
+
+常用命令：
+
+```bash
+# 生成窗口报告（若 engagement-metrics.jsonl 缺失会给出 WARN，并写入一个空指标报告）
+# 指标流由 novel commit 自动填充，首次 commit 后即可使用
+novel engagement report --history
+```
+
+## 审计节奏与“非阻断”语义（M7H.4，可选）
+
+默认情况下，叙事健康相关输出都是 **best-effort**：
+
+- `novel commit` 每章都会 append `engagement-metrics.jsonl`（如可计算）
+- `logs/engagement/latest.json` 与 `logs/promises/latest.json` 默认按**周期性审计**维护（每 10 章 + 卷末），并且不会因为这些审计维护失败而阻断 `novel commit`（失败时只产生 WARN）
+
+在 `chapter:*:draft` / `chapter:*:refine` 的 instruction packet 中，上述报告在可用时会以 `engagement_report_summary` / `promise_ledger_report_summary`（以及 `*_degraded`）的形式被裁剪注入，供写作/润色参考。
+
+> 因此注入到 instruction packet 的 `*_report_summary` 在非审计章之间可能会滞后；把它视为“近期窗口提示”，而不是每章实时信号。
+
+## Engagement/Promises：advisory warnings vs Guardrails blocking（默认仅提示）
+
+Engagement/Promises 报告的 `issues[]` 目前仅用于节奏提示（`issues[].severity` 仅为 `warn`），不会影响 `novel next` 的 step 选择，也不会让 `novel commit` 因此失败。
+
+会触发 `...:title-fix` / `...:review` 等人工步骤的是 Guardrails 的 blocking 判定（见 [Guardrails（留存 / 可读性 / 命名）](guardrails.md)）；`...:hook-fix` 来自 `platform-profile.json.hook_policy`（见 [规范体系](spec-system.md)）。
+
+## 中断恢复示例
+
+场景：你在 `chapter:048:draft` 后中断了执行器。
+
+1) 重新进入项目目录后直接运行：
+```bash
+novel next
+```
+
+2) 若 `staging/chapters/chapter-048.md` 不存在，会回到：
+```
+chapter:048:draft
+```
+
+3) 若章节已写到 staging，但 summary/delta/crossref 不完整，会返回：
+```
+chapter:048:summarize
+```
+
+4) 若已 refined 但 eval 缺失，通常会返回：
+```
+chapter:048:judge
+```
+（若启用 `platform-profile.json.retention.title_policy.enabled=true`：当 `auto_fix=true` 时可能先返回 `chapter:048:title-fix`；当 `auto_fix=false` 且存在 hard 违规则可能返回 `chapter:048:review`。）
+
+5) 若 eval 已存在，通常会返回：
+```
+chapter:048:commit
+```
+
+但当启用 `platform-profile.json.retention.title_policy.enabled=true` 且 `platform-profile.json.retention.title_policy.auto_fix=true` 且标题缺失/不合规时，可能改为返回：
+```
+chapter:048:title-fix
+```
+（自动一次：只允许修改**标题行**，正文必须 byte-identical；若仍不满足则返回 `chapter:048:review` 进入人工处理）。
+
+当启用 `platform-profile.json.hook_policy.required=true` 且章末钩子缺失/偏弱时，可能改为返回：
+```
+chapter:048:hook-fix
+```
+（自动一次，且只允许修改最后 1–2 段），若仍不满足 hook 门槛则返回：
+```
+chapter:048:review
+```
+（人工处理后再重新 judge/commit）。
+
+> 这使得你可以在任何时刻中断并恢复：只要 `.checkpoint.json` 和 `staging/**` 未被破坏，`novel next` 就能给出确定性的下一步。
+
+## 平台画像与动态评分（M6）
+
+- `platform-profile.json`：平台画像/约束配置（字数/合规/信息负载/钩子策略/评分策略）。`platform` 与 `scoring.genre_drive_type` 一旦写入视为该项目的不可变绑定；若要更换平台/驱动类型，建议新建项目目录重新初始化。
+- `genre-weight-profiles.json`：质量评分动态权重库；QualityJudge 的权重以 instruction packet JSON 的 `manifest.inline.scoring_weights` 为准（由 `platform-profile.json.scoring` + `genre-weight-profiles.json` 计算得到；commit 后也会写入 `evaluations/*-eval.json.scoring_weights`）。
+- 当 `platform-profile.json.hook_policy.required=true` 时，QualityJudge 会额外输出 `hook_strength`（章末钩子强度），并且 `novel next` 在必要时会插入 `hook-fix` 微步骤来补强章末钩子。

package/docs/user/ops.md

@@ -0,0 +1,123 @@
+# 常用操作
+
+项目创建后的日常操作指南。
+
+> 本文描述的是 Claude Code Skill 入口（`/novel:*`）。这些入口会在底层调用 `novel` CLI，并通过执行器运行各 subagent。纯 CLI 编排参考见 [`novel` CLI](novel-cli.md)。
+
+## 续写下一章
+
+```
+/novel:continue
+```
+
+默认续写 1 章。每章经过完整流水线：
+
+```
+ChapterWriter（初稿）→ Summarizer（摘要）→ StyleRefiner（润色）→ QualityJudge（评分）
+```
+
+评分 ≥4.0 自动通过；3.5-3.9 二次润色；3.0-3.4 自动修订（最多 2 次）；2.0-2.9 暂停人工审核；<2.0 强制重写。
+
+批量续写多章：
+
+```
+/novel:continue 3
+```
+
+建议单次不超过 5 章。
+
+## 查看项目状态
+
+```
+/novel:status
+```
+
+输出当前进度、评分趋势、伏笔追踪、故事线节奏、成本统计。纯只读，不修改任何文件。
+
+## 规划新卷
+
+当一卷写完（或首次进入卷规划）时，运行：
+
+```
+/novel:start
+```
+
+系统检测到 `VOL_PLANNING` 状态后，自动推荐「规划本卷」。PlotArchitect 会生成：
+
+- 本卷大纲（每章关键事件 + 故事线分配）
+- 故事线调度（主线/副线/调味线的出场安排）
+- 章节契约（每章的前置/后置条件）
+- 伏笔计划（本卷要埋设和回收的伏笔）
+
+生成后系统会让你审核，确认后进入写作循环。
+
+## 卷末回顾
+
+一卷写完后，运行 `/novel:start` 并选择「卷末回顾」：
+
+- 全卷质量趋势（均分、低分章节）
+- NER 一致性报告（人名/地名/时间线矛盾）
+- 伏笔完成度（计划 vs 实际、超期短伏笔）
+- 故事线节奏（出场频率、休眠线提醒）
+- 桥梁检查（跨故事线的伏笔是否断链）
+
+回顾完成后自动进入下卷规划。
+
+## 质量回顾
+
+随时可以查看近期写作质量：
+
+运行 `/novel:start` 并选择「质量回顾」：
+
+- 近 10 章评分趋势
+- 低分章节列表
+- 修订率统计
+- 风格漂移检测
+- AI 黑名单命中率
+
+## 更新设定
+
+写作中途需要修改世界观或角色时：
+
+运行 `/novel:start` 并选择「更新设定」：
+
+- 选择更新类型（世界观 / 角色 / 关系）
+- 系统自动做变更前快照
+- WorldBuilder 或 CharacterWeaver 执行增量更新
+- 输出变更传播摘要（哪些契约受影响）
+
+> 角色退场有三重保护检查，不会意外删除仍在活跃的角色。
+>
+> **注意**：更新设定不会修改 `platform-profile.json`（`platform` 与 `scoring.genre_drive_type` 为不可变绑定）。如需更换平台或驱动类型，建议新建项目目录重新初始化。
+
+## 导入研究资料
+
+如果你用 doc-workflow 做过背景研究，可以导入：
+
+运行 `/novel:start` 并选择「导入研究资料」：
+
+- 系统扫描 `docs/dr-workflow/` 目录
+- 展示可导入的研究成果列表
+- 选择后复制到 `research/` 目录
+- 下次 WorldBuilder/CharacterWeaver 执行时自动引用
+
+也可以手动将 `.md` 文件放入 `research/` 目录。
+
+## 断点续写
+
+如果写作中途断开：
+
+```
+/novel:start
+```
+
+系统自动检测中断状态，推荐恢复操作。中断恢复是幂等的——不会重复生成已完成的内容。
+
+## 命令速查
+
+| 命令 | 作用 |
+|------|------|
+| `/novel:start` | 主入口：创建项目 / 规划卷 / 回顾 / 更新设定 |
+| `/novel:continue` | 续写下一章 |
+| `/novel:continue N` | 批量续写 N 章 |
+| `/novel:status` | 查看项目状态（只读） |

package/docs/user/quick-start.md

@@ -0,0 +1,97 @@
+# 快速起步指南
+
+30 分钟内创建项目并试写 3 章。
+
+> 本指南以 Claude Code 的 Skill 入口（`/novel:start` 等）为主；底层会调用 `novel` CLI 并运行各 subagent。若你只想手动跑 CLI 编排，见 [`novel` CLI](novel-cli.md)。
+
+## 准备
+
+- 安装 Claude Code CLI
+- 安装 `novel` CLI：`npm i -g novel-writer-cli`（或使用开发态 `node dist/cli.js`）
+- 准备一个空目录作为项目根目录
+- （可选）准备 1-3 章自己写的文字作为风格样本
+
+## Step 1: 创建项目
+
+在空目录下运行：
+
+```
+/novel:start
+```
+
+系统检测到空目录后，提示「创建新项目」。选择后进入信息收集：
+
+1. **题材**：玄幻 / 都市 / 科幻 / 历史 / 悬疑 等
+2. **主角概念**：一句话描述——谁 + 起始处境
+3. **核心冲突**：一句话描述——主角要克服什么
+4. **平台画像**：确认发布平台与叙事驱动类型（`genre_drive_type`），用于生成 `platform-profile.json` + `genre-weight-profiles.json`
+
+> 第 1-3 项在同一轮交互中完成；平台画像（平台 + `genre_drive_type`）会在后续 gate 中确认，写入 `platform-profile.json` 后不会重复追问/覆盖。
+>
+> `platform-profile.json.platform` 与 `platform-profile.json.scoring.genre_drive_type` 一旦写入视为该项目的不可变绑定；若要更换平台/驱动类型，建议新建项目目录重新初始化。
+
+## Step 2: 选择风格来源
+
+系统会问你风格从哪来，4 个选项：
+
+| 选项 | 适用场景 |
+|------|----------|
+| 提供原创样本 | 你有自己写过的章节（推荐） |
+| 指定参考作者 | 想模仿某位网文作者的风格 |
+| 使用预置模板 | 没有样本，先选一个通用模板 |
+| 先写后提 | 什么都没有，让系统先写 3 章再回提风格 |
+
+选「提供原创样本」效果最好——粘贴 1-3 章即可。没有样本也没关系，选后两个选项系统会自动降级处理。
+
+## Step 3: 等待初始化
+
+系统自动完成以下步骤（无需你操作）：
+
+1. WorldBuilder 生成精简世界观设定（≤3 条核心规则）
+2. CharacterWeaver 创建主角和核心配角
+3. 初始化 1 条主线故事线
+4. StyleAnalyzer 提取风格指纹（若提供了样本）
+
+## Step 4: 试写 3 章
+
+系统自动执行 3 轮写作流水线：
+
+```
+ChapterWriter → Summarizer → StyleRefiner → QualityJudge
+```
+
+每章完成后你能看到：章节标题、字数、质量评分。
+
+## Step 5: 确认下一步
+
+试写完成后，系统给出 3 个选项：
+
+1. **进入卷规划**（推荐）— 规划第 1 卷大纲，正式开始
+2. **调整风格设定** — 重新提供样本或修改参数
+3. **重新试写** — 清除结果重来
+
+选「进入卷规划」后，项目进入正式创作流程。
+
+## 中断恢复
+
+如果中途断开（网络问题、关闭终端等），重新运行：
+
+```
+/novel:start
+```
+
+系统会自动检测到未完成的快速起步，从中断的步骤继续。不会丢失已生成的内容。
+
+## 常见问题
+
+**Q: 试写 3 章的评分很低怎么办？**
+A: 选「调整风格设定」补充更好的样本，或选「重新试写」。试写阶段不影响正式创作。
+
+**Q: 可以跳过试写直接开始吗？**
+A: 不建议。试写 3 章是为了验证设定和风格是否合理，也为后续写作积累 context。
+
+**Q: 创建项目后怎么继续写？**
+A: 完成卷规划后，用 `/novel:continue` 逐章续写。详见 [常用操作](ops.md)。
+
+**Q: 项目目录里生成了哪些文件？**
+A: 核心文件包括 `brief.md`（创作纲领）、`world/`（世界观）、`characters/`（角色）、`style-profile.json`（风格指纹）、`chapters/`（章节正文）。详见 [规范体系](spec-system.md)。

package/docs/user/spec-system.md

@@ -0,0 +1,166 @@
+# 规范体系
+
+本系统用 4 层规范驱动写作，确保长篇小说在数百章后仍保持一致性。
+
+## 四层规范概览
+
+```
+L1 世界规则    → 硬约束，不可违反（类似编译错误）
+L2 角色契约    → 能力/行为边界，变更需走协议
+L3 章节契约    → 每章的前置/后置条件（类似函数签名）
+LS 故事线规范  → 多线叙事约束（防串线、控节奏）
+```
+
+## L1 世界规则
+
+**文件**：`world/rules.json`
+**生成者**：WorldBuilder
+
+每条规则标注 `hard`（不可违反）或 `soft`（可有例外但需说明理由）：
+
+```json
+{
+  "id": "W-001",
+  "category": "magic_system",
+  "rule": "修炼者突破金丹期必须经历雷劫",
+  "constraint_type": "hard",
+  "exceptions": []
+}
+```
+
+快速起步阶段只生成 ≤3 条核心 hard 规则，后续卷规划时按需扩展。
+
+ChapterWriter 收到 hard 规则时会以禁止项注入：违反即自动拒绝。
+
+## L2 角色契约
+
+**文件**：`characters/active/*.json`
+**生成者**：CharacterWeaver
+
+定义每个角色的能力边界和行为模式：
+
+- 能力上限（不能做什么）
+- 性格底线（绝不会做的事）
+- 关系约束（敌友关系不可突变）
+- 成长轨迹（从 A 到 B 需要什么条件）
+
+角色退场有三重保护：活跃伏笔检查 → 故事线依赖检查 → 用户确认。
+
+## L3 章节契约
+
+**文件**：`volumes/vol-XX/chapter-contracts/chapter-XXX.json`
+**生成者**：PlotArchitect（卷规划阶段）
+
+每章的前置条件（写之前必须满足什么）和后置条件（写完后必须达成什么）：
+
+- 继承哪条故事线
+- 必须推进的情节点
+- 必须出场的角色
+- 伏笔埋设/回收要求
+- 状态变更预期
+
+QualityJudge 验收时逐条检查章节契约的达成情况。
+
+## LS 故事线规范
+
+**文件**：`storylines/storyline-spec.json`
+**规则编号**：LS-001 ~ LS-005
+
+5 条核心故事线规则：
+
+| 规则 | 说明 |
+|------|------|
+| LS-001 | 故事线 ID 一经定义不可重命名 |
+| LS-002 | 同时活跃故事线 ≤4 条 |
+| LS-003 | 交汇事件必须按 schedule 在指定范围内完成 |
+| LS-004 | 副线最小出场频率（如每 8 章至少 1 次） |
+| LS-005 | 跨线实体不可泄漏（A 线的秘密不能无故出现在 B 线） |
+
+详见 [多线叙事指南](storylines.md)。
+
+## 质量门控
+
+QualityJudge 采用双轨验收：
+
+1. **合规检查**（硬门槛）：L1/L2/L3/LS 逐条校验，有 high-confidence 违规即强制修订
+2. **质量评分**（软评估）：8 维度加权评分
+
+> **注意（动态权重）**：实际评分权重以 `platform-profile.json.scoring` + `genre-weight-profiles.json` 计算得到的 instruction packet JSON 的 `manifest.inline.scoring_weights` 为准（commit 后也会写入 `evaluations/*-eval.json.scoring_weights`）；下表仅为 **legacy fallback 默认值**（当未提供 `scoring_weights` 时使用）。
+>
+> 当 `platform-profile.json.hook_policy.required=true` 时，会额外启用 **章末钩子强度**（`hook_strength`，1–5 分）维度；若低于 `hook_policy.min_strength`，`novel next` 可能返回 `chapter:NNN:hook-fix`（只改章末 1–2 段；最多一次）或 `...:review`。未启用时该维度权重为 0，不影响综合分。
+>
+> 若项目存在 `platform-profile.json.scoring`，但缺失 `genre-weight-profiles.json`，则质量评估/commit 会报错并提示你从 `templates/genre-weight-profiles.json` 恢复（这是动态权重的必需输入）。
+
+| 维度 | 权重 |
+|------|------|
+| 情节逻辑 | 18% |
+| 角色塑造 | 18% |
+| 沉浸感 | 15% |
+| 风格自然度 | 15% |
+| 伏笔处理 | 10% |
+| 节奏 | 8% |
+| 情感冲击 | 8% |
+| 故事线连贯 | 8% |
+
+评分阈值：≥4.0 通过，3.5-3.9 二次润色，3.0-3.4 自动修订，2.0-2.9 人工审核，<2.0 强制重写。
+
+## 文件结构
+
+```
+project/
+├── brief.md                  创作纲领
+├── .checkpoint.json           进度快照
+├── style-profile.json         风格指纹
+├── ai-blacklist.json          AI 用语黑名单
+├── platform-profile.json      平台画像/约束配置（平台绑定不可变）
+├── genre-weight-profiles.json QualityJudge 动态权重配置
+├── web-novel-cliche-lint.json （可选）网文套路词 / 模板腔 lint 词库
+├── world/
+│   ├── geography.md           地理设定
+│   ├── history.md             历史背景
+│   ├── rules.md               规则叙述
+│   ├── rules.json             L1 结构化规则
+│   └── changelog.md           变更记录
+├── characters/
+│   └── active/                活跃角色档案 + L2 契约
+├── storylines/
+│   ├── storylines.json        故事线定义
+│   ├── storyline-spec.json    LS 规范
+│   └── {id}/memory.md         各线记忆文件
+├── volumes/vol-XX/
+│   ├── outline.md             卷大纲
+│   ├── storyline-schedule.json 故事线调度
+│   ├── foreshadowing.json     伏笔计划
+│   └── chapter-contracts/     L3 章节契约
+├── chapters/                  章节正文
+├── summaries/                 章节摘要
+├── evaluations/               质量评估
+├── foreshadowing/global.json  伏笔全局索引
+├── state/current-state.json   世界状态快照
+└── logs/                      流水线日志
+```
+
+### 平台画像与不可变绑定
+
+`platform-profile.json` 在项目初始化时生成，用于约束字数/信息负载/合规策略/章末钩子策略，并提供 QualityJudge 的动态权重输入（`scoring`）。  
+其中 `platform-profile.json.platform`（以及对应的叙事驱动类型 `scoring.genre_drive_type`）一旦写入，系统视为该项目的**不可变绑定**：后续不会被“更新设定”等操作改写。若要更换平台/驱动类型，建议新建项目目录重新初始化。
+
+`web-novel-cliche-lint.json` 为可选文件：缺失时 cliché lint 会降级跳过（不阻断流水线）。启用后三级 severity 行为如下：
+
+| severity | 行为 |
+|----------|------|
+| `warn` | 仅在日志中提示，不影响评分或流水线 |
+| `soft` | 作为评分信号降低 `style_naturalness` 维度得分，不阻断 commit |
+| `hard` | 阻断 `novel commit`，必须修改后重新提交 |
+
+需要启用时可从 `templates/web-novel-cliche-lint.json` 复制到项目根目录并按需微调。当前 cliché lint 由 `scripts/lint-cliche.sh` 脚本执行（通过 `platform-profile.json.compliance.script_paths.lint_cliche` 配置），尚未作为 Agent context manifest 的内联输入注入。
+
+### Guardrails（留存 / 可读性 / 命名）
+
+`platform-profile.json` 还包含一组可选的 Guardrails 配置（可逐项启用/关闭），并在 `novel next`/`novel commit` 阶段产出可审计报告：
+
+- Retention：`retention.title_policy`、`retention.hook_ledger` → `logs/retention/*`
+- Readability：`readability.mobile` → `logs/readability/*`
+- Naming：`naming` → `logs/naming/*`
+
+如何配置这些字段、以及如何解读上述日志，见 [Guardrails 文档](guardrails.md)。