文档与CLI收口：统一预检、中文化约束与版本清理

.claude-plugin/marketplace.json

@@ -11,7 +11,7 @@
     {
       "name": "webnovel-writer",
       "description": "长篇网文创作系统（skills + agents + data chain + RAG）",
-      "version": "5.5.2",
+      "version": "5.5.4",
       "author": {
         "name": "lingfengQAQ"
       },

README.md

@@ -74,6 +74,12 @@ RERANK_API_KEY=your_rerank_api_key
 /webnovel-review 1-5
 ```
 
+如需排查本地 CLI / 插件目录 / 项目根解析问题，可直接运行统一预检：
+
+```bash
+python -X utf8 "<CLAUDE_PLUGIN_ROOT>/scripts/webnovel.py" --project-root "<WORKSPACE_ROOT>" preflight
+```
+
 ### 6) 启动可视化面板（可选）
 
 ```bash
@@ -111,7 +117,9 @@ model: sonnet
 
 | 版本 | 说明 |
 |------|------|
-| **v5.5.2 (当前)** | 支持将详细大纲中的章节名同步到正文文件名；修复 workflow_manager 在无参 find_project_root monkeypatch 下的兼容性问题。 |
+| **v5.5.4 (当前)** | 补齐写作链提示词强约束（流程硬约束、中文思维写作约束、Step 职责边界）；统一中文化审查/润色/Agent 报告文案；清理文档内部版本号与版本历史，降低与插件发版版本混淆。 |
+| **v5.5.3** | 新增统一 `preflight` 预检命令；写作链 CLI 示例统一为 UTF-8 运行方式，收口文档中的长 shell 预检片段并降低 Windows 终端乱码风险。 |
+| **v5.5.2** | 支持将详细大纲中的章节名同步到正文文件名；修复 workflow_manager 在无参 find_project_root monkeypatch 下的兼容性问题。 |
 | **v5.5.1** | 修复卷级单文件大纲在上下文快照中的章节提取问题；补齐命令文档中遗漏的 `/webnovel-dashboard` 与 `/webnovel-learn`。 |
 | **v5.5.0** | 新增只读可视化 Dashboard Skill（`/webnovel-dashboard`）与实时刷新能力；支持插件目录启动与预构建前端分发 |
 | **v5.4.4** | 引入官方 Plugin Marketplace 安装机制；统一修复 Skills/Agents/References 的 CLI 调用（`CLAUDE_PLUGIN_ROOT` 单路径，透传命令统一 `--`） |
@@ -123,7 +131,7 @@ model: sonnet
 推荐使用 GitHub Actions 的 `Plugin Release` 工作流统一发版：
 
 1. 打开仓库的 Actions 页面，选择 `Plugin Release`。
-2. 输入 `version`（例如 `5.5.2`）和 `release_notes`。
+2. 输入 `version`（例如 `5.5.4`）和 `release_notes`。
 3. 工作流会自动完成以下动作：
    - 同步 `plugin.json`、`marketplace.json` 与 README 当前版本
    - 提交版本变更

webnovel-writer/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "webnovel-writer",
-  "version": "5.5.2",
+  "version": "5.5.4",
   "description": "长篇网文创作系统（skills + agents + data chain + RAG）",
   "author": {
     "name": "lingfengQAQ"

webnovel-writer/agents/consistency-checker.md

@@ -7,19 +7,19 @@ model: inherit
 
 # consistency-checker (设定一致性检查器)
 
-> **Role**: Continuity guardian enforcing the second anti-hallucination law (设定即物理 - Settings are Physics).
+> **职责**: 设定守卫者，执行第二防幻觉定律（设定即物理）。
 
 > **输出格式**: 遵循 `${CLAUDE_PLUGIN_ROOT}/references/checker-output-schema.md` 统一 JSON Schema
 
-## Scope
+## 检查范围
 
-**Input**: Single chapter or chapter range (e.g., `45` / `"45-46"`)
+**输入**: 单章或章节区间（如 `45` / `"45-46"`）
 
-**Output**: Structured report on setting violations, power-level conflicts, and logical inconsistencies.
+**输出**: 设定违规、战力冲突、逻辑不一致的结构化报告。
 
-## Execution Protocol
+## 执行流程
 
-### Step 1: Load Reference Materials
+### 第一步: 加载参考资料
 
 **输入参数**:
 ```json
@@ -33,22 +33,22 @@ model: inherit
 
 `chapter_file` 应传实际章节文件路径；若当前项目仍使用旧格式 `正文/第{NNNN}章.md`，同样允许。
 
-**Parallel reads**:
-1. Target chapters from `正文/`
-2. `{project_root}/.webnovel/state.json` (current protagonist state)
-3. `设定集/` (world-building bible)
-4. `大纲/` (outline for context)
+**并行读取**:
+1. `正文/` 下的目标章节
+2. `{project_root}/.webnovel/state.json`（主角当前状态）
+3. `设定集/`（世界观圣经）
+4. `大纲/`（对照上下文）
 
-### Step 2: Three-Tier Consistency Check
+### 第二步: 三层一致性检查
 
-#### Tier 1: Power System Consistency (战力检查)
+#### 第一层: 战力一致性（战力检查）
 
-**Verify**:
+**校验项**:
 - Protagonist's current realm/level matches state.json
 - Abilities used are within realm limitations
 - Power-ups follow established progression rules
 
-**Red Flags** (POWER_CONFLICT):
+**危险信号** (POWER_CONFLICT):
 ```
 ❌ 主角筑基3层使用金丹期才能掌握的"破空斩"
    → Realm: 筑基3 | Ability: 破空斩 (requires 金丹期)
@@ -59,18 +59,18 @@ model: inherit
    → VIOLATION: Unexplained power jump
 ```
 
-**Check Against**:
+**校验依据**:
 - state.json: `protagonist_state.power.realm`, `protagonist_state.power.layer`
 - 设定集/修炼体系.md: Realm ability restrictions
 
-#### Tier 2: Location & Character Consistency (地点/角色检查)
+#### 第二层: 地点/角色一致性（地点/角色检查）
 
-**Verify**:
+**校验项**:
 - Current location matches state.json or has valid travel sequence
 - Characters appearing are established in 设定集/ or tagged with `<entity/>`
 - Character attributes (appearance, personality, affiliations) match records
 
-**Red Flags** (LOCATION_ERROR / CHARACTER_CONFLICT):
+**危险信号** (LOCATION_ERROR / CHARACTER_CONFLICT):
 ```
 ❌ 上章在"天云宗"，本章突然出现在"千里外的血煞秘境"（无移动描写）
    → Previous location: 天云宗 | Current: 血煞秘境 | Distance: 1000+ li
@@ -81,13 +81,13 @@ model: inherit
    → VIOLATION: Power regression unexplained
 ```
 
-**Check Against**:
+**校验依据**:
 - state.json: `protagonist_state.location.current`
 - 设定集/角色卡/: Character profiles
 
-#### Tier 3: Timeline Consistency (时间线检查)
+#### 第三层: 时间线一致性（时间线检查）
 
-**Verify**:
+**校验项**:
 - Event sequence is chronologically logical
 - Time-sensitive elements (deadlines, age, seasonal events) align
 - Flashbacks are clearly marked
@@ -106,7 +106,7 @@ model: inherit
 
 > 输出 JSON 时，`issues[].severity` 必须使用小写枚举：`critical|high|medium|low`。
 
-**Red Flags** (TIMELINE_ISSUE):
+**危险信号** (TIMELINE_ISSUE):
 ```
 ❌ [critical] 第10章物资耗尽倒计时 D-5，第11章直接变成 D-2（跳过3天）
    → Setup: D-5 | Next chapter: D-2 | Missing: 3 days
@@ -129,86 +129,79 @@ model: inherit
    → VIOLATION: Time regression without flashback marker
 ```
 
-### Step 3: Entity Consistency Check
+### 第三步: 实体一致性检查
 
-**For all new entities detected in chapters**:
+**对所有章节中检测到的新实体**:
 1. Check if they contradict existing settings
 2. Assess if their introduction is consistent with world-building
 3. Verify power levels are reasonable for the current arc
 
-**Report inconsistent inventions**:
+**报告不一致的新增实体**:
 ```
 ⚠️ 发现设定冲突:
 - 第46章出现"紫霄宗"，与设定集中势力分布矛盾
   → 建议: 确认是否为新势力或笔误
 ```
 
-### Step 4: Generate Report
+### 第四步: 生成报告
 
 ```markdown
-# 设定一致性检查报告 (Consistency Review)
+# 设定一致性检查报告
 
 ## 覆盖范围
-Chapters {N} - {M}
+第 {N} 章 - 第 {M} 章
 
-## 战力一致性 (Power System)
-| Chapter | Issue | Severity | Details |
-|---------|-------|----------|---------|
-| {N} | ✓ No violations | - | - |
+## 战力一致性
+| 章节 | 问题 | 严重度 | 详情 |
+|------|------|--------|------|
+| {N} | ✓ 无违规 | - | - |
 | {M} | ✗ POWER_CONFLICT | high | 主角筑基3层使用金丹期技能"破空斩" |
 
-**Verdict**: {X} violations found
+**结论**: 发现 {X} 处违规
 
-## 地点/角色一致性 (Location & Character)
-| Chapter | Type | Issue | Severity |
-|---------|------|-------|----------|
-| {M} | Location | ✗ LOCATION_ERROR | medium | 未描述移动过程，从天云宗跳跃到血煞秘境 |
+## 地点/角色一致性
+| 章节 | 类型 | 问题 | 严重度 |
+|------|------|------|--------|
+| {M} | 地点 | ✗ LOCATION_ERROR | medium | 未描述移动过程，从天云宗跳跃到血煞秘境 |
 
-**Verdict**: {Y} violations found
+**结论**: 发现 {Y} 处违规
 
-## 时间线一致性 (Timeline)
-| Chapter | Issue | Severity | Details |
-|---------|-------|----------|---------|
+## 时间线一致性
+| 章节 | 问题 | 严重度 | 详情 |
+|------|------|--------|------|
 | {M} | ✗ TIMELINE_ISSUE | critical | 倒计时从 D-5 跳到 D-2 |
 | {M} | ✗ TIMELINE_ISSUE | high | 大比倒计时逻辑不一致 |
 
-**Verdict**: {Z} violations found
-**Critical Timeline Issues**: {count} (MUST FIX before continuing)
+**结论**: 发现 {Z} 处违规
+**严重时间线问题**: {count} 个（必须修复后才能继续）
 
-## 新实体一致性检查 (Entity Consistency)
-- ✓ All new entities consistent with world-building: {count}
-- ⚠️ Inconsistent entities found: {count} (详见下方列表)
-- ❌ Contradictory entities: {count}
+## 新实体一致性检查
+- ✓ 与世界观一致的新实体: {count}
+- ⚠️ 不一致的实体: {count}（详见下方列表）
+- ❌ 矛盾实体: {count}
 
-**Inconsistent List**:
-1. 第{M}章："紫霄宗" (势力) - 与现有势力分布矛盾
-2. 第{M}章："天雷果" (物品) - 效果与力量体系不符
+**不一致列表**:
+1. 第{M}章："紫霄宗"（势力）- 与现有势力分布矛盾
+2. 第{M}章："天雷果"（物品）- 效果与力量体系不符
 
-## 建议 (Recommendations)
-- [For power conflicts] 润色时修改第{M}章，将"破空斩"替换为筑基期可用技能
-- [For location errors] 润色时补充移动过程描述或调整地点设定
-- [For timeline issues] 润色时统一时间线推算，修正矛盾
-- [For entity conflicts] 润色时确认是否为新设定或需要调整
+## 修复建议
+- [战力冲突] 润色时修改第{M}章，将"破空斩"替换为筑基期可用技能
+- [地点错误] 润色时补充移动过程描述或调整地点设定
+- [时间线问题] 润色时统一时间线推算，修正矛盾
+- [实体冲突] 润色时确认是否为新设定或需要调整
 
 ## 综合评分
-**Overall**: {PASS/FAIL} - {Brief summary}
-**Critical Violations**: {count} (Must fix before continuing)
-**Minor Issues**: {count} (Recommend fixing)
+**结论**: {通过/未通过} - {简要说明}
+**严重违规**: {count}（必须修复）
+**轻微问题**: {count}（建议修复）
 ```
 
-### Step 5: 标记无效事实（新增）
+### 第五步: 标记无效事实（新增）
 
-对于发现的 **CRITICAL** 级别问题，自动标记到 invalid_facts（pending）：
+对于发现的严重级别（`critical`）问题，自动标记到 `invalid_facts`（状态为 `pending`）：
 
 ```bash
-# 仅使用 CLAUDE_PLUGIN_ROOT，避免多路径探测带来的误判
-if [ -z "${CLAUDE_PLUGIN_ROOT}" ] || [ ! -d "${CLAUDE_PLUGIN_ROOT}/scripts" ]; then
-  echo "ERROR: 未设置 CLAUDE_PLUGIN_ROOT 或缺少目录: ${CLAUDE_PLUGIN_ROOT}/scripts" >&2
-  exit 1
-fi
-SCRIPTS_DIR="${CLAUDE_PLUGIN_ROOT}/scripts"
-
-python "${SCRIPTS_DIR}/webnovel.py" --project-root "{PROJECT_ROOT}" index mark-invalid \
+python -X utf8 "${CLAUDE_PLUGIN_ROOT:?CLAUDE_PLUGIN_ROOT is required}/scripts/webnovel.py" --project-root "{PROJECT_ROOT}" index mark-invalid \
   --source-type entity \
   --source-id {entity_id} \
   --reason "{问题描述}" \
@@ -218,18 +211,18 @@ python "${SCRIPTS_DIR}/webnovel.py" --project-root "{PROJECT_ROOT}" index mark-i
 
 > 注意：自动标记仅为 `pending`，需用户确认后才生效。
 
-## Anti-Patterns (Forbidden)
+## 禁止事项
 
-❌ Approving chapters with POWER_CONFLICT (战力崩坏)
-❌ Ignoring untagged new entities
-❌ Accepting teleportation without in-world explanation
-❌ **Downgrading TIMELINE_ISSUE severity** (时间问题不得降级)
-❌ **Approving critical/high timeline issues without fix** (严重时间问题必须修复)
+❌ 通过存在 POWER_CONFLICT（战力崩坏）的章节
+❌ 忽略未标记的新实体
+❌ 接受无世界观解释的瞬移
+❌ **降低 TIMELINE_ISSUE 严重度**（时间问题不得降级）
+❌ **通过存在严重/高优先级时间线问题的章节**（必须修复）
 
-## Success Criteria
+## 成功标准
 
-- 0 critical violations (power conflicts, unexplained character changes, **timeline arithmetic errors**)
-- 0 high-severity timeline issues (**countdown errors, time regression, major events without time progression**)
-- All new entities consistent with existing world-building
-- Location and timeline transitions are logical
-- Report provides specific fix recommendations for polish step
+- 0 个严重违规（战力冲突、无解释的角色变化、**时间线算术错误**）
+- 0 个高优先级时间线问题（**倒计时错误、时间回跳、重大事件无时间推进**）
+- 所有新实体与现有世界观一致
+- 地点和时间线过渡合乎逻辑
+- 报告为润色步骤提供具体修复建议

webnovel-writer/agents/context-agent.md

@@ -1,11 +1,11 @@
 ---
 name: context-agent
-description: 上下文搜集Agent (v5.5)，内置 Contract v2，输出可被 Step 2A 直接消费的创作执行包。
+description: 上下文搜集Agent，内置 Context Contract，输出可被 Step 2A 直接消费的创作执行包。
 tools: Read, Grep, Bash
 model: inherit
 ---
 
-# context-agent (上下文搜集Agent v5.5)
+# context-agent (上下文搜集Agent)
 
 > **Role**: 创作执行包生成器。目标是“能直接开写”，不堆信息。
 > **Philosophy**: 按需召回 + 推断补全，确保接住上章、场景清晰、留出钩子。
@@ -14,7 +14,7 @@ model: inherit
 
 - **Taxonomy**: `${CLAUDE_PLUGIN_ROOT}/references/reading-power-taxonomy.md`
 - **Genre Profile**: `${CLAUDE_PLUGIN_ROOT}/references/genre-profiles.md`
-- **Contract v2**: `${CLAUDE_PLUGIN_ROOT}/skills/webnovel-write/references/step-1.5-contract.md`
+- **Context Contract**: `${CLAUDE_PLUGIN_ROOT}/skills/webnovel-write/references/step-1.5-contract.md`
 - **Shared References**: `${CLAUDE_PLUGIN_ROOT}/references/shared/` 为单一事实源；如需枚举/扫描参考文件，遇到 `<!-- DEPRECATED:` 的文件一律跳过。
 
 ## 输入
@@ -42,7 +42,7 @@ model: inherit
 - 连续性与伏笔（时间/位置/情绪连贯；必须处理/可选伏笔）
 - 追读力策略（未闭合问题 + 钩子类型/强度、微兑现建议、差异化提示）
 
-2. **Contract v2（内置 Step 1.5）**
+2. **Context Contract（内置 Step 1.5）**
 - 目标、阻力、代价、本章变化、未闭合问题、核心冲突一句话
 - 开头类型、情绪节奏、信息密度
 - 是否过渡章（必须按大纲判定，禁止按字数判定）
@@ -122,7 +122,7 @@ python "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" where
 python "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" context -- --chapter {NNNN}
 ```
 
-### Step 0.5: Contract v2 上下文包（内置）
+### Step 0.5: Context Contract 上下文包（内置）
 ```bash
 python "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" extract-context --chapter {NNNN} --format json
 ```
@@ -215,7 +215,7 @@ python "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" index recent
   - 情绪底色 = 上章结束情绪 + 事件走向
   - 可用能力 = 当前境界 + 近期获得 + 设定禁用项
 
-### Step 5: 组装创作执行包（任务书 + Contract v2 + 直写提示词）
+### Step 5: 组装创作执行包（任务书 + Context Contract + 直写提示词）
 输出可直接供 Step 2A 消费的单一执行包，不拆分独立 Step 1.5。
 
 - 第 7 板块必须包含“伏笔优先级清单”：
@@ -228,7 +228,7 @@ python "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" index recent
   - 若 `可选伏笔` 超过 5 条：展示前 5 条并标注“其余 N 条可选伏笔已省略”
   - 若 `foreshadowing_data_missing=true`：明确输出“结构化伏笔数据缺失，当前清单仅供占位”
 
-Contract v2 必须字段（不可缺）：
+Context Contract 必须字段（不可缺）：
 - `目标` / `阻力` / `代价` / `本章变化` / `未闭合问题`
 - `核心冲突一句话`
 - `开头类型` / `情绪节奏` / `信息密度`
@@ -262,7 +262,7 @@ Contract v2 必须字段（不可缺）：
 6. ✅ 章末钩子建议类型明确
 7. ✅ 反派层级已注明（若大纲提供）
 8. ✅ 第 7 板块已基于 `plot_threads.foreshadowing` 按紧急度排序输出
-9. ✅ Contract v2 字段完整且与任务书一致
+9. ✅ Context Contract 字段完整且与任务书一致
 10. ✅ 逻辑红线校验通过（fail=0）
 11. ✅ **时间约束板块完整**（上章时间锚点、本章时间锚点、允许推进跨度、过渡要求、倒计时状态）
 12. ✅ **时间逻辑红线通过**（无回跳、无倒计时跳跃、大跨度有过渡要求）

webnovel-writer/agents/continuity-checker.md

@@ -7,19 +7,19 @@ model: inherit
 
 # continuity-checker (连贯性检查器)
 
-> **Role**: Narrative flow guardian ensuring smooth transitions and logical plot progression.
+> **职责**: 叙事流守卫者，确保场景过渡顺畅、情节线连贯、逻辑一致。
 
 > **输出格式**: 遵循 `${CLAUDE_PLUGIN_ROOT}/references/checker-output-schema.md` 统一 JSON Schema
 
-## Scope
+## 检查范围
 
-**Input**: Single chapter or chapter range (e.g., `45` / `"45-46"`)
+**输入**: 单章或章节区间（如 `45` / `"45-46"`）
 
-**Output**: Continuity analysis covering scene transitions, plot threads, foreshadowing, and logical flow.
+**输出**: 场景过渡、情节线、伏笔管理、逻辑流的连贯性分析。
 
-## Execution Protocol
+## 执行流程
 
-### Step 1: Load Context
+### 第一步: 加载上下文
 
 **输入参数**:
 ```json
@@ -33,22 +33,17 @@ model: inherit
 
 `chapter_file` 应传实际章节文件路径；若当前项目仍使用旧格式 `正文/第{NNNN}章.md`，同样允许。
 
-**Parallel reads**:
-1. Target chapters from `正文/`
-2. Previous 2-3 chapters (for transition context)
-3. `大纲/` (to check outline adherence - 大纲即法律)
-4. `{project_root}/.webnovel/state.json` (plot thread tracker, if exists)
+**并行读取**:
+1. `正文/` 下的目标章节
+2. 前 2-3 章（过渡上下文）
+3. `大纲/`（对照大纲 - 大纲即法律）
+4. `{project_root}/.webnovel/state.json`（情节线追踪器，若存在）
 
-### Step 2: Four-Tier Continuity Check
+### 第二步: 四层连贯性检查
 
-#### Tier 1: Scene Transition Smoothness (场景转换)
+#### 第一层: 场景转换流畅度（场景转换）
 
-**Check for**:
-- Abrupt location jumps without explanation
-- Time skips without markers
-- POV changes without clear breaks
-
-**Red Flags**:
+**检查项**:
 ```
 ❌ Abrupt Transition:
 上一段：林天在天云宗大殿与长老对话
@@ -61,24 +56,24 @@ model: inherit
 下一段：林天在秘境中遭遇妖兽
 ```
 
-**Transition Quality Grades**:
+**过渡质量评级**:
 - **A**: 自然过渡 + 时间/空间标记清晰
 - **B**: 有过渡但略显生硬
 - **C**: 缺少过渡，靠读者推测
 - **F**: 完全断裂，逻辑跳跃
 
-#### Tier 2: Plot Thread Coherence (情节线连贯)
+#### 第二层: 情节线连贯（情节线连贯）
 
-**Track active plot threads**:
+**追踪活跃情节线**:
 - **Main Thread** (主线): 当前核心任务/目标
 - **Sub-threads** (支线): 次要任务、悬念、铺垫
 
-**Check for**:
+**检查项**:
 - Threads introduced but never resolved (烂尾)
 - Threads resolved without proper setup (突兀)
 - Threads forgotten mid-story (遗忘)
 
-**Example Analysis**:
+**示例分析**:
 ```
 第40章引入: "宗门大比将在10天后举行"（主线）
 第45章: 大比正在进行中 ✓
@@ -92,18 +87,16 @@ vs.
 判定：⚠️ 线索悬空，可能遗忘或拖得太久
 ```
 
-#### Tier 3: Foreshadowing Management (伏笔管理)
+#### 第三层: 伏笔管理（伏笔管理）
 
-**Classify foreshadowing**:
+**伏笔分类**:
 | Type | Setup → Payoff Gap | Risk |
 |------|-------------------|------|
 | **Short-term** (短期) | 1-3 章 | Low |
 | **Mid-term** (中期) | 4-10 章 | Medium (容易被遗忘) |
 | **Long-term** (长期) | 10+ 章 | High (需明确标记) |
 
-**Red Flags**:
-```
-⚠️ Forgotten Foreshadowing:
+**危险信号**:
 第10章: "林天发现神秘玉佩，似乎隐藏秘密"
 第11-30章: 玉佩再未提及
 判定：⚠️ 伏笔遗忘风险，建议第31章回收或再次提及
@@ -114,14 +107,14 @@ vs.
 判定：✓ 伏笔回收合理，间隔15章属于中期伏笔
 ```
 
-**Foreshadowing Checklist**:
+**伏笔检查清单**:
 - [ ] 所有设置的伏笔是否在合理章节内回收？
 - [ ] 长期伏笔（10+章）是否定期提及以保持读者记忆？
 - [ ] 回收时是否自然，不生硬？
 
-#### Tier 4: Logical Flow (逻辑流畅性)
+#### 第四层: 逻辑流畅性（逻辑流畅性）
 
-**Check for plot holes and logical inconsistencies**:
+**检查情节漏洞与逻辑不一致**:
 
 ```
 ❌ Logic Hole:
@@ -140,9 +133,9 @@ vs.
 判定：✓ 因果清晰
 ```
 
-### Step 3: Outline Adherence Check (大纲即法律)
+### 第三步: 大纲一致性检查（大纲即法律）
 
-**Compare chapters against outline**:
+**将章节与大纲对照**:
 
 ```
 大纲第45章: "主角参加宗门大比，对战王少，险胜"
@@ -155,14 +148,14 @@ vs.
 判定：⚠️ 偏离大纲（难度降低），需确认是否有意调整
 ```
 
-**Deviation Handling**:
-- **Minor** (细节优化): 可接受
-- **Moderate** (情节调整): 需标记并确认
-- **Major** (核心冲突变化): 必须标记 `<deviation reason="..."/>` 并说明
+**偏差处理**:
+- **轻微**（细节优化）: 可接受
+- **中等**（情节调整）: 需标记并确认
+- **重大**（核心冲突变化）: 必须标记 `<deviation reason="..."/>` 并说明
 
-### Step 4: Pacing & Drag Check (拖沓检查)
+### 第四步: 拖沓检查（拖沓检查）
 
-**Identify dragging sections**:
+**识别拖沓段落**:
 ```
 ⚠️ Possible Drag:
 第45-46章: 两章都在描述"主角赶路"
@@ -176,84 +169,82 @@ vs.
 判定：✓ 有效省略无关紧要的过程
 ```
 
-### Step 5: Generate Report
+### 第五步: 生成报告
 
 ```markdown
-# 连贯性检查报告 (Continuity Review)
+# 连贯性检查报告
 
 ## 覆盖范围
-Chapters {N} - {M}
+第 {N} 章 - 第 {M} 章
 
-## 场景转换评分 (Scene Transitions)
-| Transition | From → To | Grade | Issue |
-|------------|-----------|-------|-------|
-| Ch{N}→Ch{M} | 天云宗大殿 → 血煞秘境 | C | 缺少移动过程描写 |
+## 场景转换评分
+| 转换 | 从 → 到 | 评级 | 问题 |
+|------|---------|------|------|
+| 第{N}章→第{M}章 | 天云宗大殿 → 血煞秘境 | C | 缺少移动过程描写 |
 
-**Overall Transition Quality**: {Average Grade}
+**场景转换总评**: {平均评级}
 
-## 情节线追踪 (Plot Threads)
-| Thread | Introduced | Last Mentioned | Status | Next Action |
-|--------|-----------|----------------|--------|-------------|
-| 宗门大比 | Ch 40 | Ch 46 (结束) | ✓ Resolved | - |
-| 血煞门入侵 | Ch 30 | Ch 30 | ⚠️ Dormant (16章未提及) | 建议Ch 47提及或回收 |
-| 神秘玉佩 | Ch 10 | Ch 10 | ⚠️ Forgotten (36章未提及) | 建议回收或删除伏笔 |
+## 情节线追踪
+| 情节线 | 引入 | 最近提及 | 状态 | 下一步 |
+|--------|------|---------|------|--------|
+| 宗门大比 | 第40章 | 第46章（结束）| ✓ 已解决 | - |
+| 血煞门入侵 | 第30章 | 第30章 | ⚠️ 休眠（16章未提及）| 建议第47章提及或回收 |
+| 神秘玉佩 | 第10章 | 第10章 | ⚠️ 遗忘（36章未提及）| 建议回收或删除伏笔 |
 
-**Active Threads**: {count}
-**Dormant/Forgotten**: {count}
+**活跃情节线**: {count}
+**休眠/遗忘**: {count}
 
-## 伏笔管理 (Foreshadowing)
-| Setup | Chapter | Type | Payoff | Gap | Status |
-|-------|---------|------|--------|-----|--------|
-| 李雪师父去过秘境 | 10 | Mid-term | Ch 25发现线索 | 15章 | ✓ Resolved |
-| 神秘玉佩 | 10 | Long-term | 未回收 | 36章+ | ❌ 遗忘风险 |
+## 伏笔管理
+| 设置 | 章节 | 类型 | 兑现 | 间隔 | 状态 |
+|------|------|------|------|------|------|
+| 李雪师父去过秘境 | 10 | 中期 | 第25章发现线索 | 15章 | ✓ 已回收 |
+| 神秘玉佩 | 10 | 长期 | 未回收 | 36章+ | ❌ 遗忘风险 |
 
-**Foreshadowing Health**: {X} resolved, {Y} pending, {Z} at risk
+**伏笔健康度**: {X} 已回收, {Y} 待处理, {Z} 有风险
 
-## 逻辑一致性 (Logical Flow)
-| Chapter | Issue | Type | Severity |
-|---------|-------|------|----------|
-| {M} | 前后矛盾（主角称"从未见过"但第30章遇见过） | Contradiction | High |
-| {M} | 突然获得力量无解释 | Missing Causality | Medium |
+## 逻辑一致性
+| 章节 | 问题 | 类型 | 严重度 |
+|------|------|------|--------|
+| {M} | 前后矛盾（主角称"从未见过"但第30章遇见过）| 前后矛盾 | high |
+| {M} | 突然获得力量无解释 | 因果缺失 | medium |
 
-**Logic Holes Found**: {count}
+**发现逻辑漏洞**: {count}
 
-## 大纲一致性 (Outline Adherence)
-| Chapter | Outline | Actual | Deviation Level |
-|---------|---------|--------|----------------|
-| {M} | 险胜王少 | 轻松碾压 | ⚠️ Moderate (难度调整) |
+## 大纲一致性
+| 章节 | 大纲 | 实际 | 偏差程度 |
+|------|------|------|---------|
+| {M} | 险胜王少 | 轻松碾压 | ⚠️ 中等（难度调整）|
 
-**Deviations**: {count} ({X} minor, {Y} moderate, {Z} major)
+**偏差数**: {count}（{X} 轻微, {Y} 中等, {Z} 重大）
 
-## 节奏拖沓检查 (Pacing Drag)
-- ⚠️ Chapters {N}-{M}: 两章赶路场景重复，建议压缩或增加事件
+## 节奏拖沓检查
+- ⚠️ 第{N}-{M}章: 两章赶路场景重复，建议压缩或增加事件
 
-## 建议 (Recommendations)
-1. **修复场景转换**: Ch{M}添加"三日后"等时间标记
-2. **回收遗忘伏笔**: 神秘玉佩已36章未提及，建议：
-   - Ch 47-50 安排回收场景
-   - 或回溯删除该伏笔（如不重要）
-3. **解决逻辑矛盾**: Ch{M}修改"从未见过"为"很少见到"
-4. **提及休眠线索**: 血煞门入侵线索建议Ch 47再次提及，保持读者记忆
-5. **压缩拖沓段落**: Ch{N}-{M}赶路场景合并为1章
+## 修复建议
+1. **修复场景转换**: 第{M}章添加"三日后"等时间标记
+2. **回收遗忘伏笔**: 神秘玉佩已36章未提及，建议回收或回溯删除
+3. **解决逻辑矛盾**: 第{M}章修改"从未见过"为"很少见到"
+4. **提及休眠线索**: 血煞门入侵线索建议第47章再次提及
+5. **压缩拖沓段落**: 第{N}-{M}章赶路场景合并为1章
 
 ## 综合评分
-**Overall Continuity**: {SMOOTH/ACCEPTABLE/CHOPPY/BROKEN}
-**Critical Issues**: {count} (必须修复)
-**Recommendations**: {count} (建议改进)
+**连贯性总评**: {流畅/可接受/生硬/断裂}
+**严重问题**: {count}（必须修复）
+**改进建议**: {count}（建议改进）
 ```
 
-## Anti-Patterns (Forbidden)
+## 禁止事项
 
-❌ Approving chapters with major outline deviations without `<deviation/>` tag
-❌ Ignoring forgotten foreshadowing (10+ chapters dormant)
-❌ Accepting abrupt scene transitions (Grade F)
-❌ Overlooking plot holes and contradictions
+❌ 通过存在重大大纲偏差且无 `<deviation/>` 标记的章节
+❌ 忽略遗忘伏笔（10+ 章休眠）
+❌ 接受突兀的场景转换（F 级）
+❌ 忽视情节漏洞和前后矛盾
 
-## Success Criteria
+## 成功标准
 
-- All scene transitions rated ≥ B
-- No active plot threads forgotten > 15 chapters
-- All long-term foreshadowing tracked and payoff planned
-- 0 major logic holes
-- Outline deviations properly tagged
-- Report identifies specific chapters for fixes
+- 所有场景转换评级 ≥ B
+- 无活跃情节线遗忘超过 15 章
+- 所有长期伏笔已追踪并有兑现计划
+- 0 个重大逻辑漏洞
+- 大纲偏差已正确标记
+- 报告指出需修复的具体章节

webnovel-writer/agents/data-agent.md

@@ -1,17 +1,19 @@
 ---
 name: data-agent
-description: 数据处理Agent (v5.4)，负责 AI 实体提取、场景切片、索引构建，并记录钩子/模式/结束状态与章节摘要。
+description: 数据处理Agent，负责 AI 实体提取、场景切片、索引构建，并记录钩子/模式/结束状态与章节摘要。
 tools: Read, Write, Bash
 model: inherit
 ---
 
-# data-agent (数据处理Agent v5.4)
+# data-agent (数据处理Agent)
 
-> **Role**: 智能数据工程师，负责从章节正文中提取结构化信息并写入数据链。
+> **职责**: 智能数据工程师，负责从章节正文中提取结构化信息并写入数据链。
 >
-> **Philosophy**: AI驱动提取，智能消歧 - 用语义理解替代正则匹配，用置信度控制质量。
+> **原则**: AI驱动提取，智能消歧 - 用语义理解替代正则匹配，用置信度控制质量。
 
-**v5.2 变更（v5.4 沿用）**:
+**命令示例即最终准则**：本文档中的所有 CLI 命令示例已与当前仓库真实接口对齐。脚本调用方式以本文档示例为准；命令失败时查错误日志定位问题，不去大范围翻源码学习调用方式。
+
+**当前约定**：
 - 章节摘要不再追加到正文，改为 `.webnovel/summaries/ch{NNNN}.md`
 - 在 state.json 写入 `chapter_meta`（钩子/模式/结束状态）
 
@@ -68,35 +70,22 @@ model: inherit
 - `${SCRIPTS_DIR}/webnovel.py`
 
 ```bash
-# 仅使用 CLAUDE_PLUGIN_ROOT，避免多路径探测带来的误判
-if [ -z "${CLAUDE_PLUGIN_ROOT}" ] || [ ! -d "${CLAUDE_PLUGIN_ROOT}/scripts" ]; then
-  echo "ERROR: 未设置 CLAUDE_PLUGIN_ROOT 或缺少目录: ${CLAUDE_PLUGIN_ROOT}/scripts" >&2
-  exit 1
-fi
-SCRIPTS_DIR="${CLAUDE_PLUGIN_ROOT}/scripts"
-
-# 建议先确认解析出的 project_root，避免写到错误目录
-python "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" where
+export SCRIPTS_DIR="${CLAUDE_PLUGIN_ROOT:?CLAUDE_PLUGIN_ROOT is required}/scripts"
+python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" preflight
+python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" where
 ```
 
-### Step A: 加载上下文 (v5.1 SQL 查询)
+### Step A: 加载上下文（SQL 查询）
 
 使用 Read 工具读取章节正文:
 - 章节正文: 实际章节文件路径（优先 `正文/第0100章-章节标题.md`，旧格式 `正文/第0100章.md` 仍兼容）
 
 使用 Bash 工具从 index.db 查询已有实体:
  ```bash
-  # v5.1: 从 SQLite 获取核心实体
-  python "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" index get-core-entities
-  
-  # v5.1: 获取实体别名
-  python "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" index get-aliases --entity "xiaoyan"
-  
-  # 查询最近出场记录
-  python "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" index recent-appearances --limit 20
-  
-  # v5.1: 按别名查找实体（一对多）
-  python "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" index get-by-alias --alias "萧炎"
+  python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" index get-core-entities
+  python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" index get-aliases --entity "xiaoyan"
+  python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" index recent-appearances --limit 20
+  python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" index get-by-alias --alias "萧炎"
   ```
 
 ### Step B: AI 实体提取
@@ -113,22 +102,22 @@ python "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" where
 | 0.5 - 0.8 | 采用建议值，记录 warning |
 | < 0.5 | 标记待人工确认，不自动写入 |
 
-### Step D: 写入存储 (v5.2 引入)
+### Step D: 写入存储
 
  **写入 index.db (实体/别名/状态变化/关系)**:
  ```bash
-  python "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" index upsert-entity --data '{...}'
-  python "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" index register-alias --alias "红衣女子" --entity "hongyi_girl" --type "角色"
-  python "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" index record-state-change --data '{...}'
-  python "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" index upsert-relationship --data '{...}'
+  python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" index upsert-entity --data '{...}'
+  python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" index register-alias --alias "红衣女子" --entity "hongyi_girl" --type "角色"
+  python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" index record-state-change --data '{...}'
+  python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" index upsert-relationship --data '{...}'
  ```
 
  **更新精简版 state.json**:
  ```bash
-  python "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" state process-chapter --chapter 100 --data '{...}'
+  python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" state process-chapter --chapter 100 --data '{...}'
  ```
 
-写入内容 (v5.2 引入):
+写入内容：
 - 更新 `progress.current_chapter`
 - 更新 `protagonist_state`
 - 更新 `strand_tracker`
@@ -172,13 +161,13 @@ hook_strength: "strong"
 ### Step G: 向量嵌入
 
 ```bash
-python "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" rag index-chapter \
+python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" rag index-chapter \
   --chapter 100 \
   --scenes '[...]' \
   --summary "本章摘要文本"
 ```
 
-**父子索引规则 (v1.2)**:
+**父子索引规则**：
 - 父块: `chunk_type='summary'`, `chunk_id='ch0100_summary'`
 - 子块: `chunk_type='scene'`, `chunk_id='ch0100_s{scene_index}'`, `parent_chunk_id='ch0100_summary'`
 - `source_file`:
@@ -193,14 +182,14 @@ if review_score >= 80:
 ```
 
 ```bash
-python "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" style extract --chapter 100 --score 85 --scenes '[...]'
+python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" style extract --chapter 100 --score 85 --scenes '[...]'
 ```
 
-### Step I: 债务利息计算（v5.4 新增）
+### Step I: 债务利息计算
 
 **默认不自动触发**。仅在“开启债务追踪”或用户明确要求时执行：
  ```bash
- python "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" index accrue-interest --current-chapter {chapter}
+ python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" index accrue-interest --current-chapter {chapter}
  ```
 
 此步骤会：
@@ -227,6 +216,11 @@ python "${SCRIPTS_DIR}/webnovel.py" --project-root "{project_root}" style extrac
 - Data Agent 报告中仍需返回：`timing_ms` + `bottlenecks_top3`
 - 规则：`bottlenecks_top3` 始终按耗时降序返回；当 `TOTAL > 30000ms` 时，需在报告文字部分附加原因说明。
 
+观测日志说明：
+- `call_trace.jsonl`：外层流程调用链（agent 启动、排队、环境探测等系统开销）。
+- `data_agent_timing.jsonl`：Data Agent 内部各子步骤耗时。
+- 当外层总耗时远大于内层 timing 之和时，默认先归因为 agent 启动与环境探测开销，不误判为正文或数据处理慢。
+
 ```json
 {
   "chapter": 100,

webnovel-writer/agents/high-point-checker.md

@@ -1,49 +1,49 @@
 ---
 name: high-point-checker
-description: 爽点密度检查 v5.5，支持迪化误解/身份掉马模式，输出结构化报告
+description: 爽点密度检查，支持迪化误解/身份掉马模式，输出结构化报告
 tools: Read, Grep, Bash
 model: inherit
 ---
 
-# high-point-checker (爽点检查器) v5.5
+# high-point-checker (爽点检查器)
 
-> **Role**: Quality assurance specialist focused on reader satisfaction mechanics (爽点设计).
+> **职责**: 读者满足感机制的质量保障专家（爽点设计）。
 
 > **输出格式**: 遵循 `${CLAUDE_PLUGIN_ROOT}/references/checker-output-schema.md` 统一 JSON Schema
 
 ## 核心参考
 
-- **Taxonomy**: `${CLAUDE_PLUGIN_ROOT}/references/reading-power-taxonomy.md`
-- **Genre Profile**: `${CLAUDE_PLUGIN_ROOT}/references/genre-profiles.md`
+- **分类法**: `${CLAUDE_PLUGIN_ROOT}/references/reading-power-taxonomy.md`
+- **题材画像**: `${CLAUDE_PLUGIN_ROOT}/references/genre-profiles.md`
 
-## Scope
+## 检查范围
 
-**Input**: Single chapter or chapter range (e.g., `45` / `"45-46"`)
+**输入**: 单章或章节区间（如 `45` / `"45-46"`）
 
-**Output**: Structured report on cool-point density, type coverage, and execution quality.
+**输出**: 爽点密度、类型覆盖、执行质量的结构化报告。
 
-## Execution Protocol
+## 执行流程
 
-### Step 1: Load Target Chapters
+### 第一步: 加载目标章节
 
-Read all chapters in the specified range from `正文/` directory.
+读取指定范围内 `正文/` 目录下的所有章节。
 
-### Step 2: Identify Cool-Points (爽点)
+### 第二步: 识别爽点
 
-Scan for the **8 standard execution modes** (执行模式):
+扫描 **8 种标准执行模式**：
 
-| Mode | Pattern Keywords | Minimal Requirements |
+| 模式 | 特征关键词 | 最低要求 |
 |------|-----------------|---------------------|
-| **装逼打脸** (Flex & Counter) | 嘲讽/废物/不屑 → 反转/震惊/目瞪口呆 | Setup + Reversal + Reaction |
-| **扮猪吃虎** (Underdog Reveal) | 示弱/隐藏实力 → 碾压 | Concealment + Underestimation + Domination |
-| **越级反杀** (Underdog Victory) | 实力差距 → 以弱胜强 → 震撼 | Gap Display + Strategy/Power-up + Reversal |
-| **打脸权威** (Authority Challenge) | 权威/前辈/强者 → 主角挑战成功 | Authority Established + Challenge + Success |
-| **反派翻车** (Villain Downfall) | 反派得意/阴谋 → 计划失败/被反杀 | Villain Setup + Protagonist Counter + Downfall |
-| **甜蜜超预期** (Sweet Surprise) | 期待/心动 → 超预期表现 → 情感升华 | Anticipation + Exceeding Expectation + Emotion |
-| **迪化误解** (Misunderstanding Elevation) | 主角随意行为 → 配角脑补升华 → 读者优越感 | Casual Action + Info Gap + Misinterpretation + Reader Superiority |
-| **身份掉马** (Identity Reveal) | 身份伪装 → 关键时刻揭露 → 周围震惊 | Concealment (long-term) + Trigger Event + Reveal + Mass Reaction |
+| **装逼打脸** | 嘲讽/废物/不屑 → 反转/震惊/目瞪口呆 | 铺垫 + 反转 + 反应 |
+| **扮猪吃虎** | 示弱/隐藏实力 → 碾压 | 隐藏 + 轻视 + 碾压 |
+| **越级反杀** | 实力差距 → 以弱胜强 → 震撼 | 展示差距 + 策略/爆发 + 反转 |
+| **打脸权威** | 权威/前辈/强者 → 主角挑战成功 | 建立权威 + 挑战 + 成功 |
+| **反派翻车** | 反派得意/阴谋 → 计划失败/被反杀 | 反派铺垫 + 主角反制 + 翻车 |
+| **甜蜜超预期** | 期待/心动 → 超预期表现 → 情感升华 | 期待 + 超越期待 + 情绪 |
+| **迪化误解** | 主角随意行为 → 配角脑补升华 → 读者优越感 | 随意行为 + 信息差 + 误解 + 读者优越 |
+| **身份掉马** | 身份伪装 → 关键时刻揭露 → 周围震惊 | 隐藏（长期）+ 触发事件 + 揭露 + 群体反应 |
 
-### Step 2.1: 迪化误解模式检测（v5.3 引入）
+### 第二步补充: 迪化误解模式检测
 
 **核心结构**:
 1. 主角随意行为（无心插柳）
@@ -61,7 +61,7 @@ Scan for the **8 standard execution modes** (执行模式):
 - B级：脑补尚可，效果一般
 - C级：脑补太刻意，配角显得蠢
 
-### Step 2.2: 身份掉马模式检测（v5.3 引入）
+### 第二步补充: 身份掉马模式检测
 
 **核心结构**:
 1. 身份伪装（需长期铺垫）
@@ -80,23 +80,23 @@ Scan for the **8 standard execution modes** (执行模式):
 - C级：无铺垫，突兀
 - F级：硬编身份，逻辑矛盾
 
-### Step 3: Density Check
+### 第三步: 密度检查
 
-**Recommended Baseline (rolling windows)**:
+**推荐基线（滚动窗口）**:
 - **Per chapter**: 优先有爽点或同等兑现；允许过渡章低密度
 - **Every 5 chapters**: 建议 ≥ 1 组合爽点（2种模式叠加）
 - **Every 10-15 chapters**: 建议 ≥ 1 里程碑爽点（改变主角地位）
 
-**Output**:
+**输出**:
 ```
-Chapter X: [✓ 2 cool-points] or [△ 0 cool-points - warning if consecutive]
+第 X 章: [✓ 2 个爽点] 或 [△ 0 个爽点 - 连续出现时需预警]
 ```
 
-### Step 4: Type Diversity Check
+### 第四步: 类型多样性检查
 
-**Anti-monotony requirement**: No single type should dominate 80%+ of cool-points in the review range.
+**反单调要求**: 审查范围内单一类型不得超过 80%。
 
-**Example**:
+**示例**:
 ```
 Chapters 1-2:
 - 装逼打脸: 3 (75%) ✓
@@ -113,89 +113,89 @@ Chapters 45-46:
 Mode diversity: Warning - Monotonous pacing
 ```
 
-### Step 5: Execution Quality Assessment
+### 第五步: 执行质量评估
 
-For each identified cool-point, check:
+对每个已识别的爽点，检查：
 
-1. **Setup sufficiency**: Was there adequate build-up (至少1-2章伏笔)?
-2. **Reversal impact**: Is the twist unexpected yet logical?
-3. **Emotional payoff**: Did it deliver catharsis (读者情绪释放)?
-4. **30/40/30 Heuristic**: Is the structure clear enough (no rigid ratio required)?
-   - 30% Setup/Buildup (铺垫)
-   - 40% Delivery/Execution (兑现)
-   - 30% Twist/Aftermath (微反转)
-5. **Pressure/Relief Ratio** (压扬比例): Does it match the genre?
+1. **铺垫充分性**: 是否有充分的前期铺垫（至少1-2章）?
+2. **反转冲击**: 转折是否出人意料又合乎逻辑?
+3. **情绪回报**: 是否实现了读者情绪释放?
+4. **30/40/30 参考结构**: 结构是否清晰（不要求严格比例）?
+   - 30% 铺垫蓄势
+   - 40% 兑现执行
+   - 30% 微反转/余波
+5. **压扬比例**: 是否匹配题材?
    - 传统爽文: 压3扬7
    - 硬核正剧: 压5扬5
    - 虐恋文: 压7扬3
 
-**Quality Grades**:
-- **A (优秀)**: All criteria met, strong execution, structure clear
-- **B (良好)**: Most criteria met, may have minor ratio issues
-- **C (及格)**: Basic criteria met but structure weak
-- **F (失败)**: Sudden cool-point without setup, or logically inconsistent
+**质量评级**:
+- **A（优秀）**: 所有标准达标，执行有力，结构清晰
+- **B（良好）**: 多数标准达标，可能有轻微比例问题
+- **C（及格）**: 基本标准达标但结构偏弱
+- **F（失败）**: 爽点缺少铺垫突然出现，或逻辑不一致
 
-### Step 6: Generate Report
+### 第六步: 生成报告
 
 ```markdown
-# 爽点检查报告 (Cool-Point Review)
+# 爽点检查报告
 
 ## 覆盖范围
-Chapters {N} - {M}
+第 {N} 章 - 第 {M} 章
 
-## 密度检查 (Density)
-- Chapter {N}: ✓ 2 cool-points (装逼打脸 + 越级反杀)
-- Chapter {M}: △ 0 cool-points **[WARNING - 连续出现时需补强]**
+## 密度检查
+- 第 {N} 章: ✓ 2 个爽点（装逼打脸 + 越级反杀）
+- 第 {M} 章: △ 0 个爽点 **[预警 - 连续出现时需补强]**
 
-**Verdict**: {PASS/WARNING/FAIL} (rolling-window based)
+**结论**: {通过/预警/未通过}（基于滚动窗口）
 
-## 类型分布 (Mode Diversity)
-- 装逼打脸 (Flex & Counter): {count} ({percent}%)
-- 扮猪吃虎 (Underdog Reveal): {count} ({percent}%)
-- 越级反杀 (Underdog Victory): {count} ({percent}%)
-- 打脸权威 (Authority Challenge): {count} ({percent}%)
-- 反派翻车 (Villain Downfall): {count} ({percent}%)
-- 甜蜜超预期 (Sweet Surprise): {count} ({percent}%)
+## 类型分布
+- 装逼打脸: {count}（{percent}%）
+- 扮猪吃虎: {count}（{percent}%）
+- 越级反杀: {count}（{percent}%）
+- 打脸权威: {count}（{percent}%）
+- 反派翻车: {count}（{percent}%）
+- 甜蜜超预期: {count}（{percent}%）
 
-**Verdict**: {PASS/WARNING} (Monotony risk if one type > 80%)
+**结论**: {通过/预警}（单一类型 > 80% 时有单调风险）
 
-## 质量评级 (Quality)
-| Chapter | Cool-Point | Mode | Grade | 30/40/30 | 压扬比 | Issue (if any) |
-|---------|-----------|------|-------|---------|--------|----------------|
+## 质量评级
+| 章节 | 爽点 | 模式 | 评级 | 30/40/30 | 压扬比 | 问题 |
+|------|------|------|------|---------|--------|------|
 | {N} | 主角被嘲讽后一招秒杀对手 | 装逼打脸 | A | ✓ | 压3扬7 | - |
-| {M} | 突然顿悟突破境界 | 越级反杀 | C | ✗ | 压1扬9 | 缺少铺垫（no prior struggle），压扬比失衡 |
+| {M} | 突然顿悟突破境界 | 越级反杀 | C | ✗ | 压1扬9 | 缺少铺垫，压扬比失衡 |
 
-**Verdict**: Average grade = {X}
+**结论**: 平均评级 = {X}
 
-## 建议 (Recommendations)
-- [If density warning] Chapter {M} 低密度，建议补{mode}型爽点或同等兑现
-- [If monotony] 过度依赖{mode}型，建议增加{other_modes}
-- [If quality issue] Chapter {M} 的爽点执行不足，需要补充{missing_element}
-- [If structural weakness] 爽点结构偏弱，建议补铺垫/兑现/余波中的缺项
-- [If pressure/relief violation] 压扬比例不符合{genre}类型，建议调整为{ratio}
+## 修复建议
+- [密度预警] 第 {M} 章低密度，建议补{mode}型爽点或同等兑现
+- [单调风险] 过度依赖{mode}型，建议增加{other_modes}
+- [质量问题] 第 {M} 章的爽点执行不足，需要补充{missing_element}
+- [结构偏弱] 爽点结构偏弱，建议补铺垫/兑现/余波中的缺项
+- [压扬比问题] 压扬比例不符合{genre}类型，建议调整为{ratio}
 
 ## 综合评分
-**Overall**: {PASS/FAIL} - {Brief summary}
+**结论**: {通过/未通过} - {简要说明}
 ```
 
-## Anti-Patterns (Forbidden)
+## 禁止事项
 
-❌ Ignoring consecutive low-density chapters without warning
-❌ Ignoring sudden cool-points without setup
-❌ Approving 5+ consecutive chapters of the same type
+❌ 忽略连续低密度章节且不预警
+❌ 忽略缺乏铺垫的突发爽点
+❌ 通过连续 5+ 章同类型爽点
 ❌ 迪化误解中配角智商明显下线
 ❌ 身份掉马无任何前期暗示
 
-## Success Criteria
+## 成功标准
 
-- Rolling window density stays healthy (not continuously low)
-- Type distribution shows variety (no single type > 80%)
-- Average quality grade ≥ B
+- 滚动窗口密度保持健康（不连续低密度）
+- 类型分布显示多样性（单一类型不超过 80%）
+- 平均质量评级 ≥ B
 - 迪化误解的脑补需合理
 - 身份掉马需有铺垫
-- Report includes actionable recommendations
+- 报告包含可执行的修复建议
 
-## v5.3 输出格式增强（v5.5 沿用）
+## 输出格式增强
 
 ```json
 {

webnovel-writer/agents/ooc-checker.md

@@ -7,34 +7,34 @@ model: inherit
 
 # ooc-checker (人物OOC检查器)
 
-> **Role**: Character integrity guardian preventing OOC (Out-Of-Character) violations.
+> **职责**: 角色完整性守卫者，防止 OOC（Out-Of-Character）违规。
 
 > **输出格式**: 遵循 `${CLAUDE_PLUGIN_ROOT}/references/checker-output-schema.md` 统一 JSON Schema
 
-## Scope
+## 检查范围
 
-**Input**: Single chapter or chapter range (e.g., `45` / `"45-46"`)
+**输入**: 单章或章节区间（如 `45` / `"45-46"`）
 
-**Output**: Character behavior analysis, OOC violations, and personality drift warnings.
+**输出**: 角色行为分析、OOC 违规、人设漂移警告。
 
-## Execution Protocol
+## 执行流程
 
-### Step 1: Load Character Profiles
+### 第一步: 加载角色档案
 
-**Parallel reads**:
-1. Target chapters from `正文/`
-2. `设定集/角色卡/` (all character profiles)
-3. Previous chapters for behavioral baseline (if reviewing chapters > 10)
+**并行读取**:
+1. `正文/` 下的目标章节
+2. `设定集/角色卡/`（所有角色档案）
+3. 前序章节作为行为基线（若审查章节 > 10）
 
-### Step 2: Extract Character Profiles
+### 第二步: 提取角色档案
 
-**For each major character, extract**:
+**对每个主要角色，提取**:
 - **Personality traits** (性格): e.g., "隐忍冷静/嚣张狂妄/温柔体贴"
 - **Speech patterns** (说话风格): e.g., "言简意赅/喜欢嘲讽/礼貌用词"
 - **Core values** (价值观): e.g., "重视承诺/追求力量/保护弱者"
 - **Behavioral tendencies** (行为倾向): e.g., "三思而后行/冲动鲁莽/谨慎多疑"
 
-**Example Profile**:
+**角色档案示例**:
 ```
 角色：林天（主角）
 性格：隐忍冷静、智谋深沉、不轻易暴露实力
@@ -43,9 +43,9 @@ model: inherit
 行为倾向：三思而后行，善于隐藏真实意图
 ```
 
-### Step 3: Behavior Sampling
+### 第三步: 行为采样
 
-**For each chapter, extract character actions and dialogue**:
+**对每章，提取角色的动作和对话**:
 
 ```
 第45章 - 林天行为采样:
@@ -54,10 +54,10 @@ model: inherit
 [情绪] 暴怒失控
 ```
 
-### Step 4: OOC Detection (三级判定)
+### 第四步: OOC 检测（三级判定）
 
-#### Level 1: Minor Deviation (轻微偏离)
-**Definition**: Character behaves slightly differently, but has plausible in-world justification.
+#### 一级: 轻微偏离
+**定义**: 角色行为略有不同，但有合理的世界观内解释。
 
 **Examples**:
 ```
@@ -74,8 +74,8 @@ model: inherit
 判定：✓ 危机激发隐藏面，有前置铺垫
 ```
 
-#### Level 2: Moderate OOC (中度失真)
-**Definition**: Character acts inconsistently without adequate setup or explanation.
+#### 二级: 中度失真
+**定义**: 角色行为不一致，缺乏充分的铺垫或解释。
 
 **Examples**:
 ```
@@ -92,8 +92,8 @@ model: inherit
 判定：⚠️ 性格转变过快，需铺垫（如特殊原因/渐进变化）
 ```
 
-#### Level 3: Severe OOC (严重崩坏)
-**Definition**: Character acts completely opposite to established traits with no justification.
+#### 三级: 严重崩坏
+**定义**: 角色行为与既定特征完全相反，且无任何解释。
 
 **Examples**:
 ```
@@ -110,9 +110,9 @@ model: inherit
 判定：❌ 性格全面改变无解释，核心人设崩塌
 ```
 
-### Step 5: Speech Pattern Check
+### 第五步: 对话风格检查
 
-**Verify dialogue consistency**:
+**校验对话一致性**:
 
 | Character Type | Expected Style | OOC Examples |
 |---------------|----------------|--------------|
@@ -120,9 +120,9 @@ model: inherit
 | **反派（嚣张型）** | 嘲讽、轻蔑、自信 | ❌ "对不起...我错了..." (突然怯懦) |
 | **修仙者** | "阁下/道友/在下" | ❌ "牛逼/666/OMG" (现代网络用语) |
 
-### Step 6: Character Development vs. OOC
+### 第六步: 角色成长 vs. OOC
 
-**Distinguish legitimate growth from OOC**:
+**区分合理成长与 OOC**:
 
 ```
 ✓ Character Development:
@@ -136,78 +136,78 @@ model: inherit
 判定：❌ 无解释的性格突变，非成长而是失真
 ```
 
-**Growth Checklist**:
+**成长检查清单**:
 - [ ] 性格转变有合理触发事件？
 - [ ] 转变过程有渐进式铺垫？
 - [ ] 转变后的行为与触发事件逻辑一致？
 
-### Step 7: Generate Report
+### 第七步: 生成报告
 
 ```markdown
-# 人物OOC检查报告 (Character Consistency Review)
+# 人物OOC检查报告
 
 ## 覆盖范围
-Chapters {N} - {M}
+第 {N} 章 - 第 {M} 章
 
 ## 主要角色行为采样
 
 ### 林天（主角）
-| Chapter | Action/Dialogue | Profile Match | OOC Level |
-|---------|----------------|---------------|-----------|
-| {N} | "..." 冷静观察，未轻举妄动 | ✓ 符合"隐忍冷静" | None |
-| {M} | "你找死！"暴怒冲向对手 | ✗ 不符合"三思而后行" | ⚠️ Moderate |
+| 章节 | 行为/对话 | 人设匹配 | OOC 级别 |
+|------|----------|---------|---------|
+| {N} | "..." 冷静观察，未轻举妄动 | ✓ 符合"隐忍冷静" | 无 |
+| {M} | "你找死！"暴怒冲向对手 | ✗ 不符合"三思而后行" | ⚠️ 中度 |
 
-**OOC Analysis**:
+**OOC 分析**:
 - 第{M}章林天失去冷静，**缺少触发原因**
 - 建议补充：对手触及底线（如威胁家人）来合理化情绪爆发
 
 ### 慕容雪（女配）
-| Chapter | Action/Dialogue | Profile Match | OOC Level |
-|---------|----------------|---------------|-----------|
-| {M} | 突然对路人温柔体贴 | ✗ 不符合"高傲冷漠" | ⚠️ Moderate |
+| 章节 | 行为/对话 | 人设匹配 | OOC 级别 |
+|------|----------|---------|---------|
+| {M} | 突然对路人温柔体贴 | ✗ 不符合"高傲冷漠" | ⚠️ 中度 |
 
-**OOC Analysis**:
+**OOC 分析**:
 - 性格转变缺少铺垫，建议：
   - 补充慕容雪性格变化的原因（如受主角影响）
   - 或将此场景改为"表面冷漠实则关心"来保持人设
 
 ## 对话风格检查
-| Character | Expected Style | Violations Found |
-|-----------|----------------|-----------------|
+| 角色 | 预期风格 | 发现违规 |
+|------|---------|---------|
 | 林天 | 言简意赅 | ✓ 无违规 |
-| 反派王少 | 嚣张嘲讽 | ✗ 第{M}章突然谦逊（智商下线） |
+| 反派王少 | 嚣张嘲讽 | ✗ 第{M}章突然谦逊（智商下线）|
 
 ## 性格转变检查
-| Character | Previous Trait | Current Trait | Justification | Verdict |
-|-----------|---------------|---------------|---------------|---------|
+| 角色 | 原有特征 | 当前特征 | 合理性 | 判定 |
+|------|---------|---------|--------|------|
 | 林天 | 谨慎 | 自信 | ✓ 实力提升+经历铺垫 | ✓ 合理成长 |
 | 慕容雪 | 高傲 | 温柔 | ✗ 无铺垫 | ❌ OOC |
 
-## 建议 (Recommendations)
+## 修复建议
 1. **修复第{M}章林天OOC**: 补充对手触及底线的情节
 2. **慕容雪性格转变**: 添加渐进式铺垫（3-5章）或调整此章表现
 3. **反派王少智商崩坏**: 修改对话，恢复嚣张狂妄但逻辑在线的人设
 
 ## 综合评分
-**OOC Violations**:
-- Severe (严重): {count}
-- Moderate (中度): {count}
-- Minor (轻微): {count}
+**OOC 违规**:
+- 严重: {count}
+- 中度: {count}
+- 轻微: {count}
 
-**Overall**: {PASS/WARNING/FAIL}
-**Priority Fixes**: {列出必须修复的严重OOC}
+**结论**: {通过/警告/未通过}
+**优先修复项**: {列出必须修复的严重OOC}
 ```
 
-## Anti-Patterns (Forbidden)
+## 禁止事项
 
-❌ Approving severe OOC without flagging (e.g., 反派智商下线)
-❌ Ignoring character speech pattern violations
-❌ Confusing OOC with character development
+❌ 通过存在严重 OOC 且未标记的章节（如反派智商下线）
+❌ 忽略角色对话风格违规
+❌ 混淆 OOC 与角色成长
 
-## Success Criteria
+## 成功标准
 
-- 0 severe OOC violations
-- Moderate OOC has plausible in-world justification
-- Character development is gradual and well-motivated
-- Speech patterns match established profiles
-- Report distinguishes between OOC and legitimate growth
+- 0 个严重 OOC 违规
+- 中度 OOC 有合理的世界观内解释
+- 角色成长是渐进且有动机的
+- 对话风格与既定档案匹配
+- 报告能区分 OOC 和合理成长

webnovel-writer/agents/pacing-checker.md

@@ -7,19 +7,19 @@ model: inherit
 
 # pacing-checker (节奏检查器)
 
-> **Role**: Pacing analyst enforcing Strand Weave balance to prevent reader fatigue.
+> **职责**: 节奏分析师，执行 Strand Weave 平衡检查，防止读者疲劳。
 
 > **输出格式**: 遵循 `${CLAUDE_PLUGIN_ROOT}/references/checker-output-schema.md` 统一 JSON Schema
 
-## Scope
+## 检查范围
 
-**Input**: Single chapter or chapter range (e.g., `45` / `"45-46"`)
+**输入**: 单章或章节区间（如 `45` / `"45-46"`）
 
-**Output**: Strand distribution analysis, balance warnings, and pacing recommendations.
+**输出**: 情节线分布分析、平衡预警、节奏建议。
 
-## Execution Protocol
+## 执行流程
 
-### Step 1: Load Context
+### 第一步: 加载上下文
 
 **输入参数**:
 ```json
@@ -33,32 +33,19 @@ model: inherit
 
 `chapter_file` 应传实际章节文件路径；若当前项目仍使用旧格式 `正文/第{NNNN}章.md`，同样允许。
 
-**Parallel reads**:
-1. Target chapters from `正文/`
-2. `{project_root}/.webnovel/state.json` (strand_tracker history)
-3. `大纲/` (to understand intended arc structure)
+**并行读取**:
+1. `正文/` 下的目标章节
+2. `{project_root}/.webnovel/state.json`（strand_tracker 历史）
+3. `大纲/`（理解预期弧线结构）
 
-**Optional: Use status_reporter for automated analysis**:
+**可选: 使用 status_reporter 进行自动化分析**:
 ```bash
-# 获取 Strand Weave 详细分析（推荐）
-# 仅使用 CLAUDE_PLUGIN_ROOT，避免多路径探测带来的误判
-if [ -z "${CLAUDE_PLUGIN_ROOT}" ] || [ ! -d "${CLAUDE_PLUGIN_ROOT}/scripts" ]; then
-  echo "ERROR: 未设置 CLAUDE_PLUGIN_ROOT 或缺少目录: ${CLAUDE_PLUGIN_ROOT}/scripts" >&2
-  exit 1
-fi
-SCRIPTS_DIR="${CLAUDE_PLUGIN_ROOT}/scripts"
-
-python "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" status -- --focus strand
-
-# 输出包含:
-# - Quest/Fire/Constellation 占比统计
-# - 违规检测（连续Quest>5章等）
-# - 章节列表与主导Strand
+python -X utf8 "${CLAUDE_PLUGIN_ROOT:?CLAUDE_PLUGIN_ROOT is required}/scripts/webnovel.py" --project-root "${PROJECT_ROOT}" status -- --focus strand
 ```
 
-### Step 2: Classify Chapter Strands
+### 第二步: 章节情节线分类
 
-**For each chapter, identify the dominant strand**:
+**对每章，识别主导情节线**：
 
 | Strand | Indicators | Examples |
 |--------|-----------|----------|
@@ -66,9 +53,9 @@ python "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" status -- -
 | **Fire** (感情线) | 情感关系/暧昧/友情/羁绊 | 与李雪的感情发展、师徒情深、兄弟义气 |
 | **Constellation** (世界观线) | 势力关系/阵营/社交网络/揭示世界观 | 新势力登场、修仙界格局展示、宗门政治 |
 
-**Classification Rules**:
-- A chapter can have **undertones** of multiple strands, but only **one dominant**
-- Dominant =占据章节内容 ≥ 60%
+**分类规则**:
+- 一章可以有多条情节线的**底色**，但只有**一条主导**
+- 主导 = 占据章节内容 ≥ 60%
 
 **Example**:
 ```
@@ -79,9 +66,9 @@ python "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" status -- -
 → Dominant: Fire
 ```
 
-### Step 3: Balance Check (Strand Weave Violations)
+### 第三步: 平衡检查（Strand Weave 违规）
 
-**Load strand_tracker from state.json**:
+**从 state.json 加载 strand_tracker**:
 ```json
 {
   "strand_tracker": {
@@ -96,15 +83,15 @@ python "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" status -- -
 }
 ```
 
-**Apply Warning Thresholds**:
+**应用警告阈值**：
 
-| Violation | Condition | Severity | Impact |
+| 违规类型 | 触发条件 | 严重度 | 影响 |
 |-----------|-----------|----------|--------|
-| **Quest Overload** | 连续 5+ 章 Quest 主导 | High | 战斗疲劳，缺少情感深度 |
-| **Fire Drought** | 距上次 Fire > 10 章 | Medium | 人物关系停滞 |
-| **Constellation Absence** | 距上次 Constellation > 15 章 | Low | 世界观单薄 |
+| **Quest 过载** | 连续 5+ 章 Quest 主导 | High | 战斗疲劳，缺少情感深度 |
+| **Fire 干旱** | 距上次 Fire > 10 章 | Medium | 人物关系停滞 |
+| **Constellation 缺席** | 距上次 Constellation > 15 章 | Low | 世界观单薄 |
 
-**Example Violations**:
+**违规示例**:
 ```
 ⚠️ Quest Overload (连续7章)
 Chapters 40-46 全部为 Quest 主导
@@ -118,7 +105,7 @@ Last Fire chapter: 34 | Current: 46 | Gap: 12 chapters
 Last Constellation: 38 | Current: 46 | Gap: 8 chapters
 ```
 
-### Step 4: 节奏标准
+### 第四步: 节奏标准
 
 **每10章理想分布与缺席阈值**:
 
@@ -128,18 +115,18 @@ Last Constellation: 38 | Current: 46 | Gap: 8 chapters
 | Fire (感情线) | 20-30% | 10 章 | 人物关系停滞 |
 | Constellation (世界观线) | 10-20% | 15 章 | 世界观单薄 |
 
-### Step 5: Historical Trend Analysis
+### 第五步: 历史趋势分析
 
-**If state.json contains 20+ chapters of history**:
+**若 state.json 包含 20+ 章历史数据**：
 
-Generate strand distribution chart:
+生成情节线分布图：
 ```
 Chapters 1-20 Strand Distribution:
 Quest:         ████████████░░░░░░░░  60% (12 chapters)
 Fire:          ████░░░░░░░░░░░░░░░░  20% (4 chapters)
 Constellation: ████░░░░░░░░░░░░░░░░  20% (4 chapters)
 
-Verdict: ✓ Balanced pacing (符合理想比例)
+结论：✓ 节奏均衡（符合理想比例）
 ```
 
 vs.
@@ -150,79 +137,79 @@ Quest:         ███████████████████░  95%
 Fire:          █░░░░░░░░░░░░░░░░░░░   5% (1 chapter)
 Constellation: ░░░░░░░░░░░░░░░░░░░░   0% (0 chapters)
 
-Verdict: ✗ Severe imbalance (Quest 过载，节奏单调)
+结论：✗ 严重失衡（Quest 过载，节奏单调）
 ```
 
-### Step 6: Generate Report
+### 第六步: 生成报告
 
 ```markdown
-# 节奏检查报告 (Pacing Review)
+# 节奏检查报告
 
 ## 覆盖范围
-Chapters {N} - {M}
+第 {N} 章 - 第 {M} 章
 
 ## 当前章节主导情节线
-| Chapter | Dominant Strand | Undertones | Intensity |
-|---------|----------------|-----------|-----------|
-| {N} | Quest | Fire (20%) | High (战斗密集) |
-| {M} | Quest | - | Medium |
-
-## Strand Balance 检查
-### Quest Strand (主线)
-- Last appearance: Chapter {X}
-- Consecutive chapters: {count}
-- **Status**: {✓ Normal / ⚠️ Warning / ✗ Overload}
-
-### Fire Strand (情感线)
-- Last appearance: Chapter {Y}
-- Gap since last: {count} chapters
-- **Status**: {✓ Normal / ⚠️ Warning / ✗ Drought}
-
-### Constellation Strand (世界观线)
-- Last appearance: Chapter {Z}
-- Gap since last: {count} chapters
-- **Status**: {✓ Normal / ⚠️ Warning}
-
-## 历史趋势 (if ≥ 20 chapters)
-Recent 20 chapters distribution:
-- Quest: {X}% ({count} chapters)
-- Fire: {Y}% ({count} chapters)
-- Constellation: {Z}% ({count} chapters)
-
-**Trend**: {Balanced / Quest-heavy / Fire-deficient / ...}
-
-## 建议 (Recommendations)
-- [If Quest Overload] 连续{count}章Quest主导，建议在第{next}章安排：
-  - 与{角色}的感情发展场景 (Fire)
-  - 或揭示{势力/世界观元素} (Constellation)
-
-- [If Fire Drought] 距上次Fire已{count}章，建议补充：
+| 章节 | 主导线 | 底色 | 强度 |
+|------|--------|------|------|
+| {N} | Quest | Fire（20%）| 高（战斗密集）|
+| {M} | Quest | - | 中等 |
+
+## Strand 平衡检查
+### Quest 线（主线）
+- 最近出现: 第 {X} 章
+- 连续章数: {count}
+- **状态**: {✓ 正常 / ⚠️ 预警 / ✗ 过载}
+
+### Fire 线（情感线）
+- 最近出现: 第 {Y} 章
+- 距上次间隔: {count} 章
+- **状态**: {✓ 正常 / ⚠️ 预警 / ✗ 干旱}
+
+### Constellation 线（世界观线）
+- 最近出现: 第 {Z} 章
+- 距上次间隔: {count} 章
+- **状态**: {✓ 正常 / ⚠️ 预警}
+
+## 历史趋势（需 ≥ 20 章数据）
+最近 20 章分布:
+- Quest: {X}%（{count} 章）
+- Fire: {Y}%（{count} 章）
+- Constellation: {Z}%（{count} 章）
+
+**趋势**: {均衡 / Quest偏重 / Fire不足 / ...}
+
+## 修复建议
+- [Quest 过载] 连续{count}章Quest主导，建议在第{next}章安排：
+  - 与{角色}的感情发展场景（Fire）
+  - 或揭示{势力/世界观元素}（Constellation）
+
+- [Fire 干旱] 距上次Fire已{count}章，建议补充：
   - 与李雪/师父/伙伴的互动
-  - 不必是专门的感情章，可作为undertone穿插
+  - 不必是专门的感情章，可作为底色穿插
 
-- [If Constellation gap] 世界观扩展不足，建议：
+- [Constellation 间隔] 世界观扩展不足，建议：
   - 揭示新势力或修仙界格局
   - 展示新的修炼体系或设定
 
 ## 下一章节奏建议
-Based on current balance, Chapter {next} should prioritize:
-**Primary**: {Strand} (因为距上次{gap}章)
-**Secondary**: {Strand} as undertone
+基于当前平衡状态，第 {next} 章应优先：
+**主导**: {线}（因为距上次{gap}章）
+**底色**: {线}
 
 ## 综合评分
-**Overall Pacing**: {HEALTHY/WARNING/CRITICAL}
-**Reader Fatigue Risk**: {Low/Medium/High}
+**节奏总评**: {健康/预警/危险}
+**读者疲劳风险**: {低/中/高}
 ```
 
-## Anti-Patterns (Forbidden)
+## 禁止事项
 
-❌ Approving 5+ consecutive Quest chapters without warning
-❌ Ignoring Fire drought > 10 chapters
-❌ Accepting identical pacing patterns across 20+ chapters
+❌ 通过连续 5+ 章 Quest 主导且不预警
+❌ 忽略 Fire 干旱超过 10 章
+❌ 接受 20+ 章中完全相同的节奏模式
 
-## Success Criteria
+## 成功标准
 
-- No single strand dominates > 70% of recent 10 chapters
-- All strands appear at least once per their threshold
-- Report provides actionable next-chapter recommendation
-- Trend analysis shows balanced distribution (if sufficient history)
+- 最近 10 章内单一情节线不超过 70%
+- 所有情节线在各自阈值内至少出现一次
+- 报告提供可执行的下一章建议
+- 趋势分析显示分布均衡（若有足够历史数据）

webnovel-writer/agents/reader-pull-checker.md

@@ -1,18 +1,18 @@
 ---
 name: reader-pull-checker
-description: 追读力检查器 v5.5，评估钩子/微兑现/约束分层，支持 Override Contract
+description: 追读力检查器，评估钩子/微兑现/约束分层，支持 Override Contract
 tools: Read, Grep, Bash
 model: inherit
 ---
 
-# reader-pull-checker (追读力检查器) v5.5
+# reader-pull-checker (追读力检查器)
 
-> **Role**: 审查"读者为什么会点下一章"，执行 Hard/Soft 约束分层。
+> **职责**: 审查"读者为什么会点下一章"，执行 Hard/Soft 约束分层。
 
 ## 核心参考
 
-- **Taxonomy**: `${CLAUDE_PLUGIN_ROOT}/references/reading-power-taxonomy.md`
-- **Genre Profile**: `${CLAUDE_PLUGIN_ROOT}/references/genre-profiles.md`
+- **分类法**: `${CLAUDE_PLUGIN_ROOT}/references/reading-power-taxonomy.md`
+- **题材画像**: `${CLAUDE_PLUGIN_ROOT}/references/genre-profiles.md`
 - **章节追读力数据**: `index.db → chapter_reading_power`
 - **上章钩子**: `state.json → chapter_meta` 或 `index.db`
 
@@ -22,7 +22,7 @@ model: inherit
 - 题材 Profile（从 `state.json → project.genre`）
 - 是否为过渡章标记
 
-## 输出格式（v5.3 引入，v5.5 更新）
+## 输出格式
 
 ```json
 {
@@ -65,9 +65,9 @@ model: inherit
 
 ## 一、约束分层
 
-### 1.1 Hard Invariants（硬约束）
+### 1.1 硬约束
 
-> **违反 = MUST_FIX，不可申诉跳过**
+> **违反 = 必须修复，不可申诉跳过**
 
 | ID | 约束名称 | 触发条件 | severity |
 |----|---------|---------|----------|
@@ -76,7 +76,7 @@ model: inherit
 | HARD-003 | 节奏灾难 | 连续N章无任何推进（N由profile决定） | critical |
 | HARD-004 | 冲突真空 | 整章无问题/目标/代价 | high |
 
-**Hard Violation 输出**:
+**硬约束违规输出**:
 ```json
 {
   "id": "HARD-002",
@@ -88,11 +88,11 @@ model: inherit
 }
 ```
 
-### 1.2 Soft Guidance（软建议）
+### 1.2 软建议
 
-> **违反 = 可申诉，但需记录 Override Contract 并承担债务**
+> **违反 = 可申诉，但需记录 `Override Contract` 并承担债务**
 
-| ID | 约束名称 | 默认期望 | 可Override |
+| ID | 约束名称 | 默认期望 | 可覆盖 |
 |----|---------|---------|-----------|
 | SOFT_NEXT_REASON | 下章动机 | 读者能明确“为何点下一章” | ✓ |
 | SOFT_HOOK_ANCHOR | 期待锚点有效性 | 有未闭合问题或明确期待（章末/后段均可） | ✓ |
@@ -103,7 +103,7 @@ model: inherit
 | SOFT_EXPECTATION_OVERLOAD | 期待过载 | 新增期待 ≤ 2 | ✓ |
 | SOFT_RHYTHM_NATURALNESS | 节奏自然性 | 避免固定字距机械打点 | ✓ |
 
-**Soft Suggestion 输出**:
+**软建议输出**:
 ```json
 {
   "id": "SOFT_MICROPAYOFF",
@@ -118,7 +118,7 @@ model: inherit
 
 ---
 
-## 二、钩子类型扩展（v5.3 引入）
+## 二、钩子类型扩展
 
 ### 2.1 完整钩子类型
 
@@ -140,7 +140,7 @@ model: inherit
 
 ---
 
-## 三、微兑现检测（v5.3 引入）
+## 三、微兑现检测
 
 ### 3.1 微兑现类型
 
@@ -176,11 +176,11 @@ model: inherit
 
 ---
 
-## 五、Override Contract 机制
+## 五、`Override Contract` 机制
 
-### 5.1 何时可Override
+### 5.1 何时可覆盖
 
-当 `soft_suggestions` 中的建议无法遵守时，可提交 Override Contract：
+当 `soft_suggestions` 中的建议无法遵守时，可提交 `Override Contract`：
 
 ```json
 {
@@ -207,9 +207,9 @@ model: inherit
 
 ### 5.3 债务与利息
 
-- 每个Override产生债务（量由题材profile的debt_multiplier决定）
+- 每个 `Override` 产生债务（量由题材 profile 的 `debt_multiplier` 决定）
 - 每章债务累积利息（默认10%/章）
-- 超过due_chapter未偿还，债务变为overdue
+- 超过 `due_chapter` 未偿还，债务变为 `overdue`
 
 ---
 
@@ -220,13 +220,13 @@ model: inherit
 2. 读取上章钩子/模式记录
 3. 检查当前债务状态
 
-### Step 2: Hard Invariants 检查
+### Step 2: 硬约束检查
 1. 检查可读性（关键信息完整性）
 2. 检查上章钩子兑现
 3. 检查节奏停滞
 4. 检查冲突存在
 
-**任何 Hard Violation → 立即标记 MUST_FIX**
+**任何硬约束违规 → 立即标记为必须修复**
 
 ### Step 3: 钩子分析
 1. 识别本章期待锚点（优先章末，允许后段）
@@ -243,10 +243,10 @@ model: inherit
 2. 检测钩子类型重复
 3. 检测开头模式重复
 
-### Step 6: Soft Guidance 评估
+### Step 6: 软建议评估
 1. 汇总所有软建议
-2. 标注可Override的建议
-3. 列出允许的rationale类型
+2. 标注可覆盖的建议
+3. 列出允许的 `rationale` 类型
 
 ### Step 7: 生成报告
 1. 计算总分
@@ -257,20 +257,20 @@ model: inherit
 
 ## 七、评分规则
 
-### 7.1 Hard Violations
-- 任何 Hard Violation → 直接 FAIL
+### 7.1 硬约束违规
+- 任何硬约束违规 → 直接未通过
 - 必须修复后重新审核
 
-### 7.2 Soft Score（无Hard Violation时）
+### 7.2 软评分（无硬约束违规时）
 
 | 得分 | 结果 |
 |------|------|
-| 85+ | PASS |
-| 70-84 | PASS with warnings |
-| 50-69 | CONDITIONAL（可通过Override）|
-| <50 | FAIL |
+| 85+ | 通过 |
+| 70-84 | 通过（有警告） |
+| 50-69 | 条件通过（可通过 `Override`）|
+| <50 | 未通过 |
 
-### 7.3 Soft 得分计算
+### 7.3 软评分计算
 
 | 检查项 | 权重 | 问题类型 |
 |--------|------|----------|
@@ -294,7 +294,7 @@ model: inherit
    index_manager.save_chapter_reading_power(ChapterReadingPowerMeta(...))
    ```
 
-2. **处理 Override Contract**（如有）
+2. **处理 `Override Contract`**（如有）
    ```python
    index_manager.create_override_contract(OverrideContractMeta(...))
    index_manager.create_debt(ChaseDebtMeta(...))
@@ -309,9 +309,9 @@ model: inherit
 
 ## 九、成功标准
 
-- [ ] 无 Hard Violations
-- [ ] Soft Score ≥ 70（或有有效Override）
+- [ ] 无硬约束违规
+- [ ] 软评分 ≥ 70（或有有效 `Override`）
 - [ ] 存在可感知的未闭合问题/期待锚点（章末或后段）
-- [ ] 微兑现数量达标（或有Override）
+- [ ] 微兑现数量达标（或有 `Override`）
 - [ ] 无连续3章以上同型
 - [ ] 输出清晰的"下章动机"

webnovel-writer/references/checker-output-schema.md

@@ -1,4 +1,4 @@
-# Checker 统一输出 Schema (v5.4)
+# Checker 统一输出 Schema
 
 所有审查 Agent 应遵循此统一输出格式，便于自动化汇总和趋势分析。
 

webnovel-writer/references/context-contract-v2.md

@@ -1,4 +1,4 @@
-# Context Contract v2
+# Context Contract
 
 ## 目的
 - 为 `Context Agent`、`Writer`、`Review` 提供统一、可排序、可追踪的上下文契约。

webnovel-writer/references/entity-management-spec.md

@@ -1,14 +1,11 @@
 # 实体管理规范 (Entity Management Specification)
 
-> **版本**: 5.4（基于 5.1 规范）
 > **适用范围**: 所有实体类型（角色/地点/物品/势力/招式）
 > **核心目标**: AI 驱动的实体提取、别名管理、版本追踪
->
-> **v5.4**: 版本号对齐，规范沿用 v5.1。
 
 ---
 
-## v5.1 变更
+## 当前规范变更
 
 1. **SQLite 存储**: 实体、别名、状态变化、关系迁移到 `index.db`
 2. **state.json 精简**: 仅保留进度、主角状态、节奏追踪（< 5KB）
@@ -20,7 +17,7 @@
 
 ---
 
-## 一、存储架构 (v5.1)
+## 一、存储架构
 
 ### 1.1 数据分布
 
@@ -99,7 +96,7 @@ CREATE TABLE relationships (
 
 ---
 
-## 二、处理流程 (v5.1)
+## 二、处理流程
 
 ### 2.1 Data Agent 自动提取
 
@@ -156,7 +153,7 @@ python "${SCRIPTS_DIR}/webnovel.py" --project-root "$PROJECT_ROOT" index get-rel
 
 ## 三、标签体系 (可选)
 
-> v5.1 主流程使用 Data Agent 自动提取。以下标签仅用于**手动标注场景**。
+> 当前主流程使用 Data Agent 自动提取。以下标签仅用于**手动标注场景**。
 
 ### 3.1 新建实体 (`<entity>`)
 
@@ -237,7 +234,7 @@ def generate_entity_id(entity_type: str, name: str, existing_ids: set) -> str:
 
 ### 5.1 别名冲突
 
-v5.1 允许 **aliases 一对多**：同一别名可以指向多个实体。
+当前结构允许 **aliases 一对多**：同一别名可以指向多个实体。
 
 当 `ref="别名"` 命中多个实体且无法消歧时，报错：
 
@@ -261,7 +258,7 @@ v5.1 允许 **aliases 一对多**：同一别名可以指向多个实体。
 
 ## 六、迁移说明
 
-从 v5.0 迁移到 v5.1：
+从旧版结构迁移到当前结构：
 
 ```bash
 # 运行迁移脚本
@@ -280,7 +277,7 @@ python "${SCRIPTS_DIR}/webnovel.py" --project-root "$PROJECT_ROOT" index stats
 
 ## 七、总结
 
-### 7.1 v5.1 核心改进
+### 7.1 当前结构的核心改进
 
 1. **SQLite 存储**: 解决 state.json 膨胀问题
 2. **精简 JSON**: state.json 保持 < 5KB

webnovel-writer/references/genre-profiles.md

@@ -1,10 +1,10 @@
-# 题材配置档案 (Genre Profiles) v5.5
+# 题材配置档案 (Genre Profiles)
 
 > **定位**：本文档定义各题材的追读力配置参数，供 Step 1.5 / Context Agent / Checkers 读取。
 >
 > **原则**：配置用于"调整权重和建议"，不做硬性裁决。
 >
-> **v5.5**：基于 xslca.cc 热门榜实证数据扩展，新增 history-travel / game-lit，并更新 shuangwen / xianxia / urban-power 关键参数。
+> **说明**：基于 xslca.cc 热门榜实证数据扩展，新增 history-travel / game-lit，并更新 shuangwen / xianxia / urban-power 关键参数。
 
 ---
 
@@ -689,14 +689,3 @@ override_config:
 | 微兑现类型清单 | 哪些类型偏好 |
 | Hard/Soft 标准 | 阈值调整 |
 | Override 理由类型 | 哪些理由允许 |
-
----
-
-## 五、版本历史
-
-| 版本 | 日期 | 变更 |
-|------|------|------|
-| v5.5 | 2026-02-26 | 基于 xslca.cc 热门榜实证数据更新：新增 history-travel/game-lit profile，强化 xianxia 阶位制/资源货币化，urban-power 3章一峰节奏，shuangwen 数值反馈约束 |
-| v5.4.1 | 2026-02-06 | 新增 3 个内置题材profile：电竞/直播文/克苏鲁 |
-| v5.4 | 2026-02-03 | 版本号对齐，内容不变 |
-| v5.3 | 2026-02-01 | 初版，包含8个内置题材profile |

webnovel-writer/references/reading-power-taxonomy.md

@@ -1,11 +1,9 @@
-# 追读力分类标准 (Reading Power Taxonomy) v5.4
+# 追读力分类标准 (Reading Power Taxonomy)
 
 > **定位**：本文档定义"追读力"相关的统一分类标准，供 Step 1.5 / Context Agent / Checkers 共享使用。
 >
 > **原则**：所有分类用于"指导性建议"，不做硬性评分裁决。
 >
-> **v5.4**：版本号对齐，内容沿用 v5.3。
-
 ---
 
 ## 一、钩子类型 (Hook Types)
@@ -269,7 +267,7 @@
 | 悬疑 | 信息/线索 | 1-2 |
 | 日常 | 关系/情绪 | 1 |
 
-### 3.3.1 新增题材补充（v5.4.1）
+### 3.3.1 新增题材补充
 
 | 题材 | 关键追读触发 | 钩子偏好 | 微兑现重点 |
 |------|-------------|---------|-----------|
@@ -359,13 +357,3 @@
 | `micro_payoffs` | 新增 | 微兑现列表 |
 | `hard_violations` | 新增 | 硬约束违规列表 |
 | `soft_suggestions` | 新增 | 软建议列表 |
-
----
-
-## 六、版本历史
-
-| 版本 | 日期 | 变更 |
-|------|------|------|
-| v5.4.1 | 2026-02-06 | 增补电竞/直播文/克苏鲁题材追读触发建议 |
-| v5.4 | 2026-02-03 | 版本号对齐，内容不变 |
-| v5.3 | 2026-02-01 | 初版，新增情绪钩/选择钩/渴望钩、迪化误解/身份掉马、微兑现体系、Hard/Soft分层 |

webnovel-writer/references/shared/core-constraints.md

@@ -1,12 +1,10 @@
 ---
 name: core-constraints
 purpose: 每次章节写作前加载，确保三大定律执行
-version: "5.4"
 ---
 
 <context>
 此文件用于章节创作时的核心约束检查。Claude 已知一般写作规范，这里只补充网文特定的防幻觉协议。
-v5.4：版本号对齐，内容沿用 v5.2。
 注意：此文件为 shared 单一事实源；禁止在各 Skill 的 references 下复制修改。若需更新，请修改本文件。
 </context>
 
@@ -20,15 +18,15 @@ v5.4：版本号对齐，内容沿用 v5.2。
 | **设定即物理** | 实力/招式/物品 ≤ index.db 记录 | 写作前查询确认 |
 | **发明需识别** | 新实体由 Data Agent 自动提取 | 章节完成后处理 |
 
-## 新实体处理流程（v5.2 引入，v5.4 沿用）
+## 新实体处理流程
 
-v5.2 引入的规则，v5.4 沿用：正文不再要求 XML 标签：
+当前规则：正文不再要求 XML 标签：
 
 1. **写作时**: 直接写纯正文，新角色/地点/物品正常描写
 2. **完成后**: Data Agent 自动识别新实体并写入 index.db
 3. **不确定实体**: Data Agent 标记为 uncertain，由人工确认
 
-## 章节约束分层（v5.5）
+## 章节约束分层
 
 ### Hard（必须）
 

webnovel-writer/scripts/__init__.py

@@ -4,7 +4,7 @@ webnovel-writer scripts package
 This package contains all Python scripts for the webnovel-writer plugin.
 """
 
-__version__ = "5.4.0"
+__version__ = "5.5.4"
 __author__ = "lcy"
 
 # Expose main modules

webnovel-writer/scripts/data_modules/tests/test_webnovel_unified_cli.py

@@ -92,6 +92,46 @@ def test_extract_context_forwards_with_resolved_project_root(monkeypatch, tmp_pa
     ]
 
 
+def test_preflight_succeeds_for_valid_project_root(monkeypatch, tmp_path, capsys):
+    module = _load_webnovel_module()
+
+    project_root = tmp_path / "book"
+    (project_root / ".webnovel").mkdir(parents=True, exist_ok=True)
+    (project_root / ".webnovel" / "state.json").write_text("{}", encoding="utf-8")
+
+    monkeypatch.setattr(sys, "argv", ["webnovel", "--project-root", str(project_root), "preflight"])
+
+    with pytest.raises(SystemExit) as exc:
+        module.main()
+
+    captured = capsys.readouterr()
+    assert int(exc.value.code or 0) == 0
+    assert "OK project_root" in captured.out
+    assert str(project_root.resolve()) in captured.out
+
+
+def test_preflight_fails_when_required_scripts_are_missing(monkeypatch, tmp_path, capsys):
+    module = _load_webnovel_module()
+
+    project_root = tmp_path / "book"
+    (project_root / ".webnovel").mkdir(parents=True, exist_ok=True)
+    (project_root / ".webnovel" / "state.json").write_text("{}", encoding="utf-8")
+
+    fake_scripts_dir = tmp_path / "fake-scripts"
+    fake_scripts_dir.mkdir(parents=True, exist_ok=True)
+
+    monkeypatch.setattr(module, "_scripts_dir", lambda: fake_scripts_dir)
+    monkeypatch.setattr(sys, "argv", ["webnovel", "--project-root", str(project_root), "preflight", "--format", "json"])
+
+    with pytest.raises(SystemExit) as exc:
+        module.main()
+
+    captured = capsys.readouterr()
+    assert int(exc.value.code or 0) == 1
+    assert '"ok": false' in captured.out
+    assert '"name": "entry_script"' in captured.out
+
+
 def test_quality_trend_report_writes_to_book_root_when_input_is_workspace_root(tmp_path, monkeypatch):
     _ensure_scripts_on_path()
     import quality_trend_report as quality_trend_report_module

webnovel-writer/scripts/data_modules/webnovel.py

@@ -9,6 +9,7 @@ webnovel 统一入口（面向 skills / agents 的稳定 CLI）
 - 所有写入类命令在解析到 project_root 后，统一前置 `--project-root` 传给具体模块。
 
 典型用法（推荐，不依赖 PYTHONPATH / 不要求 cd）：
+  python "<SCRIPTS_DIR>/webnovel.py" preflight
   python "<SCRIPTS_DIR>/webnovel.py" where
   python "<SCRIPTS_DIR>/webnovel.py" use D:\\wk\\xiaoshuo\\凡人资本论
   python "<SCRIPTS_DIR>/webnovel.py" --project-root D:\\wk\\xiaoshuo index stats
@@ -23,6 +24,7 @@ from __future__ import annotations
 
 import argparse
 import importlib
+import json
 import subprocess
 import sys
 from pathlib import Path
@@ -104,6 +106,54 @@ def cmd_where(args: argparse.Namespace) -> int:
     return 0
 
 
+def _build_preflight_report(explicit_project_root: Optional[str]) -> dict:
+    scripts_dir = _scripts_dir().resolve()
+    plugin_root = scripts_dir.parent
+    skill_root = plugin_root / "skills" / "webnovel-write"
+    entry_script = scripts_dir / "webnovel.py"
+    extract_script = scripts_dir / "extract_chapter_context.py"
+
+    checks: list[dict[str, object]] = [
+        {"name": "scripts_dir", "ok": scripts_dir.is_dir(), "path": str(scripts_dir)},
+        {"name": "entry_script", "ok": entry_script.is_file(), "path": str(entry_script)},
+        {"name": "extract_context_script", "ok": extract_script.is_file(), "path": str(extract_script)},
+        {"name": "skill_root", "ok": skill_root.is_dir(), "path": str(skill_root)},
+    ]
+
+    project_root = ""
+    project_root_error = ""
+    try:
+        resolved_root = _resolve_root(explicit_project_root)
+        project_root = str(resolved_root)
+        checks.append({"name": "project_root", "ok": True, "path": project_root})
+    except Exception as exc:
+        project_root_error = str(exc)
+        checks.append({"name": "project_root", "ok": False, "path": explicit_project_root or "", "error": project_root_error})
+
+    return {
+        "ok": all(bool(item["ok"]) for item in checks),
+        "project_root": project_root,
+        "scripts_dir": str(scripts_dir),
+        "skill_root": str(skill_root),
+        "checks": checks,
+        "project_root_error": project_root_error,
+    }
+
+
+def cmd_preflight(args: argparse.Namespace) -> int:
+    report = _build_preflight_report(args.project_root)
+    if args.format == "json":
+        print(json.dumps(report, ensure_ascii=False, indent=2))
+    else:
+        for item in report["checks"]:
+            status = "OK" if item["ok"] else "ERROR"
+            path = item.get("path") or ""
+            print(f"{status} {item['name']}: {path}")
+            if item.get("error"):
+                print(f"  detail: {item['error']}")
+    return 0 if report["ok"] else 1
+
+
 def cmd_use(args: argparse.Namespace) -> int:
     project_root = normalize_windows_path(args.project_root).expanduser()
     try:
@@ -145,6 +195,10 @@ def main() -> None:
     p_where = sub.add_parser("where", help="打印解析出的 project_root")
     p_where.set_defaults(func=cmd_where)
 
+    p_preflight = sub.add_parser("preflight", help="校验统一 CLI 运行环境与 project_root")
+    p_preflight.add_argument("--format", choices=["text", "json"], default="text", help="输出格式")
+    p_preflight.set_defaults(func=cmd_preflight)
+
     p_use = sub.add_parser("use", help="绑定当前工作区使用的书项目（写入指针/registry）")
     p_use.add_argument("project_root", help="书项目根目录（必须包含 .webnovel/state.json）")
     p_use.add_argument("--workspace-root", help="工作区根目录（可选；默认由运行环境推断）")

webnovel-writer/scripts/webnovel.py

@@ -4,6 +4,7 @@
 webnovel 统一入口脚本（无须 `cd`）
 
 用法示例：
+  python "<SCRIPTS_DIR>/webnovel.py" preflight
   python "<SCRIPTS_DIR>/webnovel.py" where
   python "<SCRIPTS_DIR>/webnovel.py" index stats
 
@@ -33,4 +34,3 @@ def main() -> None:
 if __name__ == "__main__":
     enable_windows_utf8_stdio(skip_in_pytest=True)
     main()
-

webnovel-writer/skills/webnovel-init/SKILL.md

@@ -4,7 +4,7 @@ description: 深度初始化网文项目。通过分阶段交互收集完整创
 allowed-tools: Read Write Edit Grep Bash Task AskUserQuestion WebSearch WebFetch
 ---
 
-# Project Initialization (Deep Mode v2)
+# Project Initialization (Deep Mode)
 
 ## 目标
 

webnovel-writer/skills/webnovel-init/references/creativity/anti-trope-game.md

@@ -8,7 +8,6 @@
 - 三、非套路爽点（替代传统打脸）
 - 四、组合示例
 - 五、使用指南
-- 版本历史
 
 ---
 
@@ -169,11 +168,3 @@
 - ✅ 约束贯穿全文
 - ✅ 约束驱动剧情发展
 - ✅ 约束与爽点相辅相成
-
----
-
-## 版本历史
-
-| 版本 | 日期 | 变更 |
-|------|------|------|
-| v1.0 | 2026-02-26 | 初版，基于 xslca.cc 热门榜实证分析数据 |

webnovel-writer/skills/webnovel-init/references/creativity/anti-trope-rules-mystery.md

@@ -9,7 +9,6 @@
 - 四、组合示例
 - 五、规则设计模板
 - 六、使用指南
-- 版本历史
 
 ---
 
@@ -213,11 +212,3 @@
 - ✅ 破解需要付出代价
 - ✅ 规则之间有有趣的交互
 - ✅ 主角的胜利来自智慧而非能力
-
----
-
-## 版本历史
-
-| 版本 | 日期 | 变更 |
-|------|------|------|
-| v1.0 | 2026-02-03 | 初版 |

webnovel-writer/skills/webnovel-init/references/creativity/anti-trope-urban.md

@@ -8,7 +8,6 @@
 - 三、非套路爽点（替代传统打脸）
 - 四、组合示例
 - 五、使用指南
-- 版本历史
 
 ---
 
@@ -168,11 +167,3 @@
 - ✅ 约束贯穿全文
 - ✅ 约束驱动剧情发展
 - ✅ 约束与爽点相辅相成
-
----
-
-## 版本历史
-
-| 版本 | 日期 | 变更 |
-|------|------|------|
-| v1.0 | 2026-02-26 | 初版，基于 xslca.cc 热门榜实证分析数据 |

webnovel-writer/skills/webnovel-init/references/creativity/anti-trope-xianxia.md

@@ -8,7 +8,6 @@
 - 三、非套路爽点（替代传统打脸）
 - 四、组合示例
 - 五、使用指南
-- 版本历史
 
 ---
 
@@ -158,11 +157,3 @@
 - ✅ 约束贯穿全文
 - ✅ 约束驱动剧情发展
 - ✅ 约束与爽点相辅相成
-
----
-
-## 版本历史
-
-| 版本 | 日期 | 变更 |
-|------|------|------|
-| v1.0 | 2026-02-03 | 初版 |

webnovel-writer/skills/webnovel-init/references/creativity/category-constraint-packs.md

@@ -8,7 +8,6 @@
 - 男频分类约束包
 - 女频分类约束包
 - 通用增味包
-- 版本历史
 
 ---
 
@@ -375,12 +374,3 @@
 - 角色矛盾：野心扩张 vs 生存底线
 - 钩子：选择钩
 - 爽点：零和博弈 + 代价型
-
----
-
-## 版本历史
-
-| 版本 | 日期 | 变更 |
-|------|------|------|
-| v1.1 | 2026-02-26 | 基于 xslca.cc 热门榜实证数据新增：M23-M27（历史穿越/游戏/科幻克苏鲁）、F19-F20（历史穿越女频） |
-| v1.0 | 2026-02-03 | 初版 |

webnovel-writer/skills/webnovel-init/references/creativity/creativity-constraints.md

@@ -13,7 +13,6 @@
 - 七、三问筛选法 (Three-Question Filter)
 - 八、评分系统 (Scoring System)
 - 九、输出格式
-- 十、版本历史
 
 ---
 
@@ -326,12 +325,3 @@
 - 爽点密度: {cool_point_density}/5
 - 长线潜力: {long_term_potential}/5
 ```
-
----
-
-## 十、版本历史
-
-| 版本 | 日期 | 变更 |
-|------|------|------|
-| v1.1 | 2026-02-26 | 扩展题材专属反套路引用：新增 urban（都市/历史）与 game（游戏/科幻） |
-| v1.0 | 2026-02-03 | 初版，定义创意约束系统 |

webnovel-writer/skills/webnovel-init/references/creativity/market-trends-2026.md

@@ -11,7 +11,6 @@
 - 四、读者偏好变化
 - 五、平台差异
 - 六、可执行建议
-- 版本历史
 
 ---
 
@@ -58,15 +57,6 @@
 ---
 
 ## 六、可执行建议
-
 - 低风险创新：{视角/机制微调等}
 - 中风险创新：{叙事结构/多主角等}
 - 高风险创新：{全新题材/实验叙事等}
-
----
-
-## 版本历史
-
-| 版本 | 日期 | 变更 |
-|------|------|------|
-| v1.0 | 2026-02-03 | 模板占位 |

webnovel-writer/skills/webnovel-init/references/system-data-flow.md

@@ -5,14 +5,13 @@ purpose: 重定向到权威版本
 
 <context>
 此文件已迁移到统一位置，避免多版本不同步问题。
-v5.4：版本号对齐，权威版本已更新。
 </context>
 
 <instructions>
 
 ## 权威版本位置
 
-`${CLAUDE_PLUGIN_ROOT}/skills/webnovel-query/references/system-data-flow.md` (v5.4)
+`${CLAUDE_PLUGIN_ROOT}/skills/webnovel-query/references/system-data-flow.md`
 
 ## 加载方式
 
@@ -35,7 +34,7 @@ cat "${CLAUDE_PLUGIN_ROOT}/skills/webnovel-query/references/system-data-flow.md"
     └── archive/            # 归档数据
 ```
 
-### v5.1 核心变化
+### 当前结构核心变化
 - **双 Agent 架构**: Context Agent (读) + Data Agent (写)
 - **无 XML 标签**: 纯正文写作，Data Agent AI 自动提取实体
 - **SQLite 存储**: entities/aliases/state_changes 迁移到 index.db

webnovel-writer/skills/webnovel-query/references/system-data-flow.md

@@ -1,12 +1,10 @@
 ---
 name: system-data-flow
 purpose: 项目初始化和状态查询时加载，理解数据结构
-version: "5.4"
 ---
 
 <context>
 此文件用于项目数据结构参考。Claude 已知一般文件组织，这里只补充网文工作流特定的目录约定和脚本职责。
-v5.4：版本号对齐，内容沿用 v5.2。
 </context>
 
 <instructions>
@@ -27,11 +25,11 @@ v5.4：版本号对齐，内容沿用 v5.2。
     └── archive/            # 归档数据（不活跃角色/已回收伏笔）
 ```
 
-## v5.1 架构变更
+## 架构变更说明
 
 **核心变化**: 解决 state.json 膨胀问题（20章后 token 爆炸）
 
-| 数据类型 | v5.0 存储位置 | v5.1 存储位置 |
+| 数据类型 | 旧版存储位置 | 当前存储位置 |
 |----------|--------------|--------------|
 | entities_v3 | state.json | **index.db** (entities 表) |
 | alias_index | state.json | **index.db** (aliases 表) |
@@ -42,7 +40,7 @@ v5.4：版本号对齐，内容沿用 v5.2。
 | strand_tracker | state.json | state.json (保留) |
 | disambiguation_* | state.json | state.json (保留) |
 
-## v5.2 双 Agent 架构
+## 双 Agent 架构
 
 ```
 写作前: Context Agent 读取数据 → 组装上下文包
@@ -59,7 +57,7 @@ v5.4：版本号对齐，内容沿用 v5.2。
 Context Agent (读) ←→ index.db + state.json ←→ Data Agent (写)
 ```
 
-## 脚本/模块职责速查 (v5.1)
+## 脚本/模块职责速查
 
 ### 核心脚本
 
@@ -70,14 +68,14 @@ Context Agent (读) ←→ index.db + state.json ←→ Data Agent (写)
 | `backup_manager.py` | 章节号 | 自动 Git 备份 |
 | `status_reporter.py` | 无 | 生成健康报告/伏笔紧急度 |
 | `archive_manager.py` | 无 | 归档不活跃数据 |
-| `data_modules/migrate_state_to_sqlite.py` | 项目路径 | 迁移旧 state.json 到 SQLite (v5.1 新增) |
+| `data_modules/migrate_state_to_sqlite.py` | 项目路径 | 迁移旧 state.json 到 SQLite |
 
 ### data_modules 模块
 
 | 模块 | 职责 |
 |------|------|
 | `state_manager.py` | 实体状态管理（精简 state.json + SQLite 同步） |
-| `sql_state_manager.py` | SQLite 状态管理（v5.1 新增，替代 JSON 写入） |
+| `sql_state_manager.py` | SQLite 状态管理（替代 JSON 写入） |
 | `index_manager.py` | SQLite 索引管理（实体/别名/关系/状态变化/章节/场景） |
 | `entity_linker.py` | 别名注册与消歧 |
 | `rag_adapter.py` | 向量嵌入与语义检索 |
@@ -85,7 +83,7 @@ Context Agent (读) ←→ index.db + state.json ←→ Data Agent (写)
 | `api_client.py` | LLM API 调用封装 |
 | `config.py` | 配置管理 |
 
-## 每章数据链（v5.2 顺序）
+## 每章数据链
 
 ```
 1. Context Agent 组装创作任务书
@@ -122,7 +120,7 @@ Context Agent (读) ←→ index.db + state.json ←→ Data Agent (写)
 
 > `update_state.py` 用于手动/脚本化更新 `progress`/`protagonist_state`/`strand_tracker` 等字段；主流程通常由 Data Agent 在处理数据链时同步推进进度。
 
-## state.json 精简结构 (v5.2)
+## state.json 精简结构
 
 ```json
 {
@@ -153,9 +151,9 @@ Context Agent (读) ←→ index.db + state.json ←→ Data Agent (写)
 }
 ```
 
-> **v5.1 变更**: entities_v3、alias_index、state_changes、structured_relationships 已迁移到 index.db，不再存储在 state.json 中。
+> **当前结构说明**: entities_v3、alias_index、state_changes、structured_relationships 已迁移到 index.db，不再存储在 state.json 中。
 
-## index.db 表结构 (v5.1)
+## index.db 表结构
 
 ```sql
 -- 实体表
@@ -210,7 +208,7 @@ CREATE TABLE appearances (...);
 
 ## Data Agent AI 提取流程
 
-v5.0 不再要求 XML 标签，由 Data Agent 智能提取：
+当前主流程不再要求 XML 标签，由 Data Agent 智能提取：
 
 1. **实体识别**: 从正文语义识别角色/地点/物品/势力
 2. **实体匹配**: 优先匹配已有实体（通过 alias_index）
@@ -229,7 +227,7 @@ v5.0 不再要求 XML 标签，由 Data Agent 智能提取：
 
 **推荐字段**: content, status, planted_chapter, target_chapter, tier
 
-## alias_index 格式 (v5.0 一对多)
+## alias_index 格式（一对多）
 
 ```json
 {
@@ -258,7 +256,7 @@ cat "$PROJECT_ROOT/.webnovel/state.json" | jq '.progress'
 </example>
 
 <example>
-<input>v5.1: 查询实体（SQL）</input>
+<input>查询实体（SQL）</input>
 <output>
 ```bash
 python "${SCRIPTS_DIR}/webnovel.py" --project-root "$PROJECT_ROOT" index get-entity --id "xiaoyan"
@@ -271,7 +269,7 @@ python "${SCRIPTS_DIR}/webnovel.py" --project-root "$PROJECT_ROOT" index get-cor
 </example>
 
 <example>
-<input>v5.1: 按别名查找实体（一对多）</input>
+<input>按别名查找实体（一对多）</input>
 <output>
 ```bash
 python "${SCRIPTS_DIR}/webnovel.py" --project-root "$PROJECT_ROOT" index get-by-alias --alias "天云宗"
@@ -281,7 +279,7 @@ python "${SCRIPTS_DIR}/webnovel.py" --project-root "$PROJECT_ROOT" index get-by-
 </example>
 
 <example>
-<input>v5.1: 查询状态变化</input>
+<input>查询状态变化</input>
 <output>
 ```bash
 python "${SCRIPTS_DIR}/webnovel.py" --project-root "$PROJECT_ROOT" index get-state-changes --entity "xiaoyan" --limit 10
@@ -291,7 +289,7 @@ python "${SCRIPTS_DIR}/webnovel.py" --project-root "$PROJECT_ROOT" index get-sta
 </example>
 
 <example>
-<input>v5.1: 查询关系</input>
+<input>查询关系</input>
 <output>
 ```bash
 python "${SCRIPTS_DIR}/webnovel.py" --project-root "$PROJECT_ROOT" index get-relationships --entity "xiaoyan"
@@ -319,7 +317,7 @@ python "${SCRIPTS_DIR}/webnovel.py" --project-root "$PROJECT_ROOT" index entity-
 </example>
 
 <example>
-<input>v5.1: 迁移旧 state.json 到 SQLite</input>
+<input>迁移旧 state.json 到 SQLite</input>
 <output>
 ```bash
 python "${SCRIPTS_DIR}/webnovel.py" --project-root "$PROJECT_ROOT" migrate -- --backup
@@ -334,10 +332,10 @@ python "${SCRIPTS_DIR}/webnovel.py" --project-root "$PROJECT_ROOT" migrate -- --
 ❌ 伏笔状态写成"待回收" → ✅ 使用规范值"未回收"
 ❌ 手工更新忘记加 planted_chapter → ✅ 脚本已自动补全
 ❌ 归档路径混淆 → ✅ 固定为 `.webnovel/archive/*.json`
-❌ alias_index 期望单对象 → ✅ v5.0+ 使用数组格式（一对多）
-❌ 期望 XML 标签提取 → ✅ v5.0+ 由 Data Agent AI 自动提取
+❌ alias_index 期望单对象 → ✅ 当前结构使用数组格式（一对多）
+❌ 期望 XML 标签提取 → ✅ 当前主流程由 Data Agent AI 自动提取
 ❌ 使用旧版 data_modules.state_manager schema → ✅ 统一使用 entities_v3 结构
-❌ v5.1 仍从 state.json 读取 entities_v3 → ✅ 改用 SQL 查询 index.db
-❌ v5.1 仍写入 state.json 大数据 → ✅ 改用 SQLite 增量写入
-❌ v5.1 state.json 膨胀 → ✅ 运行迁移脚本: `python "${SCRIPTS_DIR}/webnovel.py" migrate`
+❌ 仍从 state.json 读取 entities_v3 → ✅ 改用 SQL 查询 index.db
+❌ 仍写入 state.json 大数据 → ✅ 改用 SQLite 增量写入
+❌ 让 state.json 持续膨胀 → ✅ 运行迁移脚本: `python "${SCRIPTS_DIR}/webnovel.py" migrate`
 </errors>

webnovel-writer/skills/webnovel-query/references/tag-specification.md

@@ -1,13 +1,12 @@
 ---
 name: tag-specification
-purpose: XML 标签格式参考（v5.1 引入，v5.4 可选使用）
-version: "5.4"
+purpose: XML 标签格式参考
 ---
 
 <context>
 此文件用于 XML 标签格式参考。
 
-**v5.1 引入的变更（v5.4 沿用）**:
+**当前约定**：
 - 章节写作时**不再要求**添加 XML 标签
 - Data Agent 会自动从纯正文中提取实体，写入 index.db
 - 标签仅用于**手动标注**场景（如明确标记重要实体、补充提取遗漏）

webnovel-writer/skills/webnovel-resume/references/system-data-flow.md

@@ -5,14 +5,13 @@ purpose: 重定向到权威版本
 
 <context>
 此文件已迁移到统一位置，避免多版本不同步问题。
-v5.4：版本号对齐，权威版本已更新。
 </context>
 
 <instructions>
 
 ## 权威版本位置
 
-`../webnovel-query/references/system-data-flow.md` (v5.4)
+`../webnovel-query/references/system-data-flow.md`
 
 ## 加载方式
 
@@ -35,7 +34,7 @@ cat "${SKILL_ROOT}/../webnovel-query/references/system-data-flow.md"
     └── archive/            # 归档数据
 ```
 
-### v5.1 核心变化
+### 当前结构核心变化
 - **双 Agent 架构**: Context Agent (读) + Data Agent (写)
 - **无 XML 标签**: 纯正文写作，Data Agent AI 自动提取实体
 - **SQLite 存储**: entities/aliases/state_changes 迁移到 index.db

webnovel-writer/skills/webnovel-resume/references/workflow-resume.md

@@ -1,17 +1,15 @@
 ---
 name: workflow-resume
 purpose: 任务恢复时加载，指导中断恢复流程
-version: "5.4"
 ---
 
 <context>
 此文件用于中断任务恢复。Claude 已知错误处理流程，这里只补充网文创作工作流特定的 Step 难度分级和恢复策略。
-v5.4：版本号对齐，内容沿用 v5.2。
 </context>
 
 <instructions>
 
-## Step 中断难度分级 (v5.4)
+## Step 中断难度分级
 
 | Step | 名称 | 影响 | 难度 | 默认策略 |
 |------|------|------|------|----------|

webnovel-writer/skills/webnovel-review/references/core-constraints.md

@@ -1,7 +1,6 @@
 ---
 name: core-constraints
 purpose: 每次章节写作前加载，确保三大定律执行
-version: "5.4"
 ---
 
 <!-- DEPRECATED: use ${CLAUDE_PLUGIN_ROOT}/references/shared/core-constraints.md -->

webnovel-writer/skills/webnovel-write/SKILL.md

@@ -4,7 +4,7 @@ description: Writes webnovel chapters (default 2000-2500 words). Use when the us
 allowed-tools: Read Write Edit Grep Bash Task
 ---
 
-# Chapter Writing (Structured Workflow v2)
+# Chapter Writing (Structured Workflow)
 
 ## 目标
 
@@ -33,6 +33,15 @@ allowed-tools: Read Write Edit Grep Bash Task
 - `.webnovel/summaries/ch{NNNN}.md`
 - `.webnovel/state.json` 的进度与 `chapter_meta` 更新
 
+### 流程硬约束（禁止事项）
+
+- **禁止并步**：不得将两个 Step 合并为一个动作执行（如同时做 2A 和 3）。
+- **禁止跳步**：不得跳过未被模式定义标记为可跳过的 Step。
+- **禁止临时改名**：不得将 Step 的输出产物改写为非标准文件名或格式。
+- **禁止自创模式**：`--fast` / `--minimal` 只允许按上方定义裁剪步骤，不允许自创混合模式、"半步"或"简化版"。
+- **禁止自审替代**：Step 3 审查必须由 Task 子代理执行，主流程不得内联伪造审查结论。
+- **禁止源码探测**：脚本调用方式以本文档与 data-agent 文档中的命令示例为准，命令失败时查日志定位问题，不去翻源码学习调用方式。
+
 ## 引用加载等级（strict, lazy）
 
 - L0：未进入对应步骤前，不加载任何参考文件。
@@ -114,47 +123,26 @@ allowed-tools: Read Write Edit Grep Bash Task
 
 环境设置（bash 命令执行前）：
 ```bash
-# WORKSPACE_ROOT：Claude Code 的工作区根（通常等于 $CLAUDE_PROJECT_DIR）
 export WORKSPACE_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
+export SCRIPTS_DIR="${CLAUDE_PLUGIN_ROOT:?CLAUDE_PLUGIN_ROOT is required}/scripts"
+export SKILL_ROOT="${CLAUDE_PLUGIN_ROOT:?CLAUDE_PLUGIN_ROOT is required}/skills/webnovel-write"
 
-if [ -z "${CLAUDE_PLUGIN_ROOT}" ] || [ ! -d "${CLAUDE_PLUGIN_ROOT}/skills/webnovel-write" ]; then
-  echo "ERROR: 未设置 CLAUDE_PLUGIN_ROOT 或缺少目录: ${CLAUDE_PLUGIN_ROOT}/skills/webnovel-write" >&2
-  exit 1
-fi
-export SKILL_ROOT="${CLAUDE_PLUGIN_ROOT}/skills/webnovel-write"
-
-if [ -z "${CLAUDE_PLUGIN_ROOT}" ] || [ ! -d "${CLAUDE_PLUGIN_ROOT}/scripts" ]; then
-  echo "ERROR: 未设置 CLAUDE_PLUGIN_ROOT 或缺少目录: ${CLAUDE_PLUGIN_ROOT}/scripts" >&2
-  exit 1
-fi
-export SCRIPTS_DIR="${CLAUDE_PLUGIN_ROOT}/scripts"
-
-if [ ! -f "${SCRIPTS_DIR}/extract_chapter_context.py" ]; then
-  echo "ERROR: 缺少脚本: ${SCRIPTS_DIR}/extract_chapter_context.py" >&2
-  exit 1
-fi
-
-# 解析真实书项目根（后续所有 Read/Write 路径都必须以 $PROJECT_ROOT 为前缀，避免写到工作区根目录）
-export PROJECT_ROOT="$(python "${SCRIPTS_DIR}/webnovel.py" --project-root "${WORKSPACE_ROOT}" where)"
+python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${WORKSPACE_ROOT}" preflight
+export PROJECT_ROOT="$(python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${WORKSPACE_ROOT}" where)"
 ```
 
+**硬门槛**：`preflight` 必须成功。它统一校验 `CLAUDE_PLUGIN_ROOT` 派生出的 `SKILL_ROOT` / `SCRIPTS_DIR`、`webnovel.py`、`extract_chapter_context.py` 和解析出的 `PROJECT_ROOT`。任一失败都立即阻断。
+
 输出：
 - “已就绪输入”与“缺失输入”清单；缺失则阻断并提示先补齐。
 
 ### Step 0.5：工作流断点记录（best-effort，不阻断）
 
 ```bash
-# 开始整条任务
-python "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" workflow start-task --command webnovel-write --chapter {chapter_num} || true
-
-# 进入某一步（示例：Step 1）
-python "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" workflow start-step --step-id "Step 1" --step-name "Context Agent" || true
-
-# Step 1 完成后记录（每个 Step 结束都要调用）
-python "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" workflow complete-step --step-id "Step 1" --artifacts '{"ok":true}' || true
-
-# 全部 Step 结束后，再结束整条任务
-python "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" workflow complete-task --artifacts '{"ok":true}' || true
+python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" workflow start-task --command webnovel-write --chapter {chapter_num} || true
+python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" workflow start-step --step-id "Step 1" --step-name "Context Agent" || true
+python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" workflow complete-step --step-id "Step 1" --artifacts '{"ok":true}' || true
+python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" workflow complete-task --artifacts '{"ok":true}' || true
 ```
 
 要求：
@@ -162,7 +150,7 @@ python "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" workflow co
 - 任何记录失败只记警告，不阻断写作。
 - 每个 Step 执行结束后，同样需要 `complete-step`（失败不阻断）。
 
-### Step 1：Context Agent（内置 Contract v2，生成直写执行包）
+### Step 1：Context Agent（内置 Context Contract，生成直写执行包）
 
 使用 Task 调用 `context-agent`，参数：
 - `chapter`
@@ -174,12 +162,12 @@ python "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" workflow co
 - 若 `state` 或大纲不可用，立即阻断并返回缺失项。
 - 输出必须同时包含：
   - 7 板块任务书（目标/冲突/承接/角色/场景约束/伏笔/追读力）；
-  - Contract v2 全字段（目标/阻力/代价/本章变化/未闭合问题/开头类型/情绪节奏/信息密度/过渡章判定/追读力设计）；
+  - Context Contract 全字段（目标/阻力/代价/本章变化/未闭合问题/开头类型/情绪节奏/信息密度/过渡章判定/追读力设计）；
   - Step 2A 可直接消费的“写作执行包”（章节节拍、不可变事实清单、禁止事项、终检清单）。
 - 合同与任务书出现冲突时，以“大纲与设定约束更严格者”为准。
 
 输出：
-- 单一“创作执行包”（任务书 + Contract v2 + 直写提示词），供 Step 2A 直接消费，不再拆分独立 Step 1.5。
+- 单一“创作执行包”（任务书 + Context Contract + 直写提示词），供 Step 2A 直接消费，不再拆分独立 Step 1.5。
 
 ### Step 2A：正文起草
 
@@ -194,6 +182,12 @@ cat "${SKILL_ROOT}/../../references/shared/core-constraints.md"
 - 禁止占位符正文（如 `[TODO]`、`[待补充]`）。
 - 保留承接关系：若上章有明确钩子，本章必须回应（可部分兑现）。
 
+中文思维写作约束（硬规则）：
+- **禁止"先英后中"**：不得先用英文工程化骨架（如 ABCDE 分段、Summary/Conclusion 框架）组织内容，再翻译成中文。
+- **中文叙事单元优先**：以"动作、反应、代价、情绪、场景、关系位移"为基本叙事单元，不使用英文结构标签驱动正文生成。
+- **禁止英文结论话术**：正文、审查说明、润色说明、变更摘要、最终报告中不得出现 Overall / PASS / FAIL / Summary / Conclusion 等英文结论标题。
+- **英文仅限机器标识**：CLI flag（`--fast`）、checker id（`consistency-checker`）、DB 字段名（`anti_ai_force_check`）、JSON 键名等不可改的接口名保持英文，其余一律使用简体中文。
+
 输出：
 - 章节草稿（可进入 Step 2B 或 Step 3）。
 
@@ -239,9 +233,24 @@ cat "${SKILL_ROOT}/references/step-3-review-gate.md"
 
 审查指标落库（必做）：
 ```bash
-# 统一入口 webnovel.py：无需 cd / PYTHONPATH，且自动注入 --project-root
-python "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" index save-review-metrics --data '@review_metrics.json'
+python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" index save-review-metrics --data "@${PROJECT_ROOT}/.webnovel/tmp/review_metrics.json"
+```
+
+review_metrics 字段约束（当前工作流约定只传以下字段）：
+```json
+{
+  "start_chapter": 100,
+  "end_chapter": 100,
+  "overall_score": 85.0,
+  "dimension_scores": {"爽点密度": 8.5, "设定一致性": 8.0, "节奏控制": 7.8, "人物塑造": 8.2, "连贯性": 9.0, "追读力": 8.7},
+  "severity_counts": {"critical": 0, "high": 1, "medium": 2, "low": 0},
+  "critical_issues": ["问题描述"],
+  "report_file": "审查报告/第100-100章审查报告.md",
+  "notes": "单个字符串；selected_checkers / timeline_gate / anti_ai_force_check 等扩展信息压成单行文本写入此字段"
+}
 ```
+- `notes` 在当前执行契约中必须是单个字符串，不得传入对象或数组。
+- 当前工作流不额外传入其它顶层字段；脚本侧未在此处做新增硬校验。
 
 硬要求：
 - `--minimal` 也必须产出 `overall_score`。
@@ -275,6 +284,27 @@ cat "${SKILL_ROOT}/references/writing/typesetting.md"
 - `storage_path=.webnovel/`
 - `state_file=.webnovel/state.json`
 
+Data Agent 默认子步骤（全部执行）：
+- A. 加载上下文
+- B. AI 实体提取
+- C. 实体消歧
+- D. 写入 state/index
+- E. 写入章节摘要
+- F. AI 场景切片
+- G. RAG 向量索引（`rag index-chapter --scenes ...`）
+- H. 风格样本评估（`style extract --scenes ...`，仅 `review_score >= 80` 时）
+- I. 债务利息（默认跳过）
+
+`--scenes` 来源优先级（G/H 步骤共用）：
+1. 优先从 `index.db` 的 scenes 记录获取（Step F 写入的结果）
+2. 其次按 `start_line` / `end_line` 从正文切片构造
+3. 最后允许单场景退化（整章作为一个 scene）
+
+Step 5 失败隔离规则：
+- 若 G/H 失败原因是 `--scenes` 缺失、scene 为空、scene JSON 格式错误：只补跑 G/H 子步骤，不回滚或重跑 Step 1-4。
+- 若 A-E 失败（state/index/summary 写入失败）：仅重跑 Step 5，不回滚已通过的 Step 1-4。
+- 禁止因 RAG/style 子步骤失败而重跑整个写作链。
+
 执行后检查（最小白名单）：
 - `.webnovel/state.json`
 - `.webnovel/index.db`
@@ -285,6 +315,11 @@ cat "${SKILL_ROOT}/references/writing/typesetting.md"
 - 读取 timing 日志最近一条；
 - 当 `TOTAL > 30000ms` 时，输出最慢 2-3 个环节与原因说明。
 
+观测日志说明：
+- `call_trace.jsonl`：外层流程调用链（agent 启动、排队、环境探测等系统开销）。
+- `data_agent_timing.jsonl`：Data Agent 内部各子步骤耗时。
+- 当外层总耗时远大于内层 timing 之和时，默认先归因为 agent 启动与环境探测开销，不误判为正文或数据处理慢。
+
 债务利息：
 - 默认关闭，仅在用户明确要求或开启追踪时执行（见 `step-5-debt-switch.md`）。
 
@@ -292,10 +327,12 @@ cat "${SKILL_ROOT}/references/writing/typesetting.md"
 
 ```bash
 git add .
-git commit -m "Ch{chapter_num}: {title}"
+git -c i18n.commitEncoding=UTF-8 commit -m "第{chapter_num}章: {title}"
 ```
 
 规则：
+- 提交时机：验证、回写、清理全部完成后最后执行。
+- 提交信息默认中文，格式：`第{chapter_num}章: {title}`。
 - 若 commit 失败，必须给出失败原因与未提交文件范围。
 
 ## 充分性闸门（必须通过）
@@ -317,7 +354,7 @@ git commit -m "Ch{chapter_num}: {title}"
 test -f "${PROJECT_ROOT}/.webnovel/state.json"
 test -f "${PROJECT_ROOT}/正文/第${chapter_padded}章.md"
 test -f "${PROJECT_ROOT}/.webnovel/summaries/ch${chapter_padded}.md"
-python "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" index get-recent-review-metrics --limit 1
+python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" index get-recent-review-metrics --limit 1
 tail -n 1 "${PROJECT_ROOT}/.webnovel/observability/data_agent_timing.jsonl" || true
 ```
 

webnovel-writer/skills/webnovel-write/references/core-constraints.md

@@ -1,7 +1,6 @@
 ---
 name: core-constraints
 purpose: 每次章节写作前加载，确保三大定律执行
-version: "5.4"
 ---
 
 <!-- DEPRECATED: use ${CLAUDE_PLUGIN_ROOT}/references/shared/core-constraints.md -->

webnovel-writer/skills/webnovel-write/references/polish-guide.md

@@ -1,7 +1,6 @@
 ---
 name: polish-guide
 purpose: 章节生成后的润色阶段加载，基于审查报告修复问题 + 强化网文口感
-version: "6.0"
 ---
 
 <context>
@@ -264,18 +263,18 @@ version: "6.0"
 
 必须输出：
 1. 润色后的章节正文
-2. 修复摘要（建议结构）
+2. 修复摘要（结构如下）
 
 ```text
-[Polish Report]
-- critical_fixed: N
-- high_fixed: N
-- medium_low_fixed: N
-- anti_ai_rewrites: N
+[润色报告]
+- 严重问题已修复: N 处
+- 高优先级已修复: N 处
+- 中低优先级已修复: N 处
+- Anti-AI 改写: N 处
 - anti_ai_force_check: pass/fail
-- poison_risk: pass/fail
-- deviations:
-  - {location}: {reason}
+- 毒点风险: pass/fail
+- 偏离记录:
+  - {位置}: {原因}
 ```
 
 若 `critical` 未清零，必须显式标注“未通过”，并返回 Step 4 继续修复。

webnovel-writer/skills/webnovel-write/references/step-3-review-gate.md

@@ -76,19 +76,29 @@ parallel Task(agent, {chapter, chapter_file, project_root}) for agent in selecte
 
 ```text
 审查汇总 - 第 {chapter_num} 章
-- selected_checkers: {list}
-- critical issues: {N}
-- high issues: {N}
-- overall_score: {score}
+- 已启用审查器: {list}
+- 严重问题: {N} 个
+- 高优先级问题: {N} 个
+- 综合评分: {score}
 - 可进入润色: {是/否}
 ```
 
 ## 审查指标落库（必做）
 
 ```bash
-python "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" index save-review-metrics --data '@review_metrics.json'
+python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" index save-review-metrics --data "@${PROJECT_ROOT}/.webnovel/tmp/review_metrics.json"
 ```
 
+review_metrics 文件字段约束（当前工作流约定只传以下字段）：
+- `start_chapter`（int）、`end_chapter`（int）：单章时二者相等
+- `overall_score`（float）：必填
+- `dimension_scores`（Dict[str, float]）：按已启用 checker 计算
+- `severity_counts`（Dict[str, int]）：键为 critical / high / medium / low
+- `critical_issues`（List[str]）
+- `report_file`（str）
+- `notes`（str）：在当前执行契约中必须是单个字符串；`selected_checkers`、`timeline_gate`、`anti_ai_force_check` 等扩展信息统一压成单行文本写入此字段，不得作为独立顶层键传入
+- 当前工作流不额外传入其它顶层字段；脚本侧未在此处做新增硬校验
+
 ## 进入 Step 4 前闸门
 
 - `overall_score` 已生成。
@@ -117,7 +127,7 @@ if len(critical_timeline) > 0:
         print(f"- 第{issue.chapter}章: {issue.description}")
     return BLOCKED
 else:
-    PASS: "时间线检查通过"
+    通过: "时间线检查通过"
 ```
 
 **修复指引**：

webnovel-writer/skills/webnovel-write/references/style-adapter.md

@@ -1,6 +1,8 @@
 ## 定位
 Step 2B 专用提示词，将粗稿改写为网文风格。
 
+**中文优先原则**：本步骤的改写说明、改写日志、变更摘要一律使用简体中文表述。英文仅保留在 CLI flag、checker id、JSON 键名等不可改的机器标识上。
+
 **与 Step 4 (polish-guide) 的职责边界**:
 - **Step 2B (本步骤)**: 纯风格转换 —— 句式改写、抽象→具体、网文口感
 - **Step 4**: 问题修复 —— 基于审查报告修复 critical/high 问题 + AI痕迹检测

webnovel-writer/templates/output/index-schema.md

@@ -1,8 +1,8 @@
-# index.db 表结构说明 (v5.4，基于 v5.1/v5.2)
+# index.db 表结构说明
 
 > 以 SQLite 存储大规模数据（实体/别名/场景/关系）。
 >
-> **v5.4**：结构沿用 v5.1/v5.2，并新增追读力/可观测性相关表。
+> 当前结构包含追读力/可观测性相关表。
 
 ## 表一览
 
@@ -68,13 +68,13 @@
 - description (TEXT)
 - chapter (INTEGER)
 
-### v5.3 追读力债务相关表
+### 追读力债务相关表
 - override_contracts
 - chase_debt
 - debt_events
 - chapter_reading_power
 
-### v5.4 可观测性与审查相关表
+### 可观测性与审查相关表
 - invalid_facts
 - review_metrics
 - rag_query_log

webnovel-writer/templates/output/state-schema.md

@@ -1,8 +1,8 @@
-# state.json 结构说明 (v5.4)
+# state.json 结构说明
 
 > 该文件为运行态精简状态，避免体量膨胀。实体等大数据存于 index.db。
 >
-> **v5.4**：以下示例与 `update_state.py` 当前校验字段保持一致。
+> 以下示例与 `update_state.py` 当前校验字段保持一致。
 
 ```json
 {