novel-maker 2.2.0

package/skill/scripts/auditor/hook_report.py

@@ -0,0 +1,115 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+钩子密度报告
+分析卷内所有章节的结尾钩子，输出类型分布、连续相同钩子警告。
+"""
+
+import os
+import sys
+import json
+from collections import Counter
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', 'common'))
+from nm_utils import (
+    list_chapters, read_chapter, detect_hook, detect_hook_type_from_patterns
+)
+
+
+def extract_last_paragraphs(text, n=3):
+    """Extract last N paragraphs (likely contains chapter ending hook)."""
+    paragraphs = [p.strip() for p in text.split('\n') if p.strip()]
+    if not paragraphs:
+        return text[-300:]
+    return '\n'.join(paragraphs[-n:])
+
+
+def analyze_volume(chapters_dir, recent_n=None):
+    chapter_files = list_chapters(chapters_dir, recent_n)
+    if not chapter_files:
+        return {'error': f'No chapters found in {chapters_dir}'}
+
+    results = []
+    for idx, filepath in enumerate(chapter_files):
+        raw, title, clean, wc = read_chapter(filepath)
+        ending = extract_last_paragraphs(raw)
+        hook_type = detect_hook_type_from_patterns(ending)
+
+        hook_sentences = []
+        import re
+        for m in re.finditer(r'[^。！？\n]{5,50}[。！？]', raw):
+            sentence = m.group(0)
+            from nm_utils import _HOOK_PATTERN_MAP
+            if any(pattern.search(sentence) for pattern in _HOOK_PATTERN_MAP.values()):
+                hook_sentences.append(sentence.strip())
+
+        results.append({
+            "chapter": idx + 1,
+            "title": title,
+            "word_count": wc,
+            "hook_type": hook_type,
+            "hook_sentences": hook_sentences[:3],
+            "ending_summary": ending[:200],
+        })
+
+    hook_types = [r["hook_type"] for r in results]
+    hook_dist = dict(Counter(hook_types))
+
+    consecutive_same = []
+    if len(hook_types) >= 3:
+        for i in range(len(hook_types) - 2):
+            if hook_types[i] == hook_types[i+1] == hook_types[i+2]:
+                consecutive_same.append(f"第{results[i]['chapter']}-{results[i+2]['chapter']}章连续使用「{hook_types[i]}」钩子")
+
+    return {
+        "total_chapters": len(results),
+        "hook_distribution": hook_dist,
+        "chapters": results,
+        "warnings": {
+            "consecutive_same_hook": consecutive_same,
+            "unknown_hooks": sum(1 for h in hook_types if h == "未知"),
+        }
+    }
+
+
+def main():
+    import argparse
+    parser = argparse.ArgumentParser(description="Hook density report")
+    parser.add_argument("chapters_dir", help="Chapters directory")
+    parser.add_argument("--recent", type=int, help="Only analyze last N chapters")
+    parser.add_argument("--json", action="store_true", help="Output as JSON")
+    args = parser.parse_args()
+
+    chapters_dir = args.chapters_dir
+    if not os.path.isdir(chapters_dir):
+        print(f"Error: {chapters_dir} is not a directory", file=sys.stderr)
+        sys.exit(1)
+
+    result = analyze_volume(chapters_dir, recent_n=args.recent)
+
+    if args.json:
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+    else:
+        print(f"=== 钩子密度报告 (最近{result.get('total_chapters', 0)}章) ===\n")
+        if 'error' in result:
+            print(result['error'])
+            return
+        print("钩子类型分布:")
+        for hook_type, count in sorted(result["hook_distribution"].items(),
+                                        key=lambda x: x[1], reverse=True):
+            bar = "█" * count
+            print(f"  {hook_type:4s}: {bar} ({count})")
+        print()
+        if result["warnings"]["consecutive_same_hook"]:
+            print("⚠ 警告 - 连续相同钩子:")
+            for w in result["warnings"]["consecutive_same_hook"]:
+                print(f"  {w}")
+        if result["warnings"]["unknown_hooks"] > 0:
+            print(f"\n⚠ {result['warnings']['unknown_hooks']} 章钩子类型未知，建议手动标记")
+        print()
+        for ch in result["chapters"]:
+            print(f"  第{ch['chapter']}章 [{ch['hook_type']}]: {ch['ending_summary'][:80]}...")
+
+
+if __name__ == "__main__":
+    main()

package/skill/scripts/auditor/pacing_optimizer.py

@@ -0,0 +1,303 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+节奏优化建议脚本
+基于节奏分析结果，提供具体的优化建议，帮助改善故事节奏。
+供审计师在审查时使用，或写手在修改时参考。
+
+用法:
+    python scripts/auditor/pacing_optimizer.py 章节目录 --json
+    python scripts/auditor/pacing_optimizer.py 章节目录 --recent 10
+"""
+
+import argparse
+import json
+import os
+import re
+import sys
+from collections import defaultdict
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', 'common'))
+from nm_utils import (
+    list_chapters, read_chapter, estimate_pacing, count_chinese,
+    detect_hook_type_from_patterns
+)
+
+# ─── 节奏规则 ───────────────────────────────
+PACING_RULES = {
+    'max_consecutive_high': 3,  # 不能连续3章S4+
+    'max_consecutive_low': 3,   # 不能连续3章S2-
+    'max_no_peak_interval': 8,  # 每8章必须有S4/S5
+    'max_no_mid_interval': 3,   # 每3章必须有S3+
+    'ideal_peak_ratio': 0.15,   # 理想高潮比例 15%
+    'ideal_mid_ratio': 0.35,    # 理想上升比例 35%
+    'ideal_low_ratio': 0.25,    # 理想平缓比例 25%
+    'ideal_valley_ratio': 0.10  # 理想低谷比例 10%
+}
+
+# ─── 优化建议模板 ──────────────────────────────
+OPTIMIZATION_SUGGESTIONS = {
+    'consecutive_high': {
+        'problem': '连续高潮',
+        'suggestion': '在高潮后插入1-2章平缓或低谷章节，让读者有喘息空间',
+        'example': '可以在第{chapter}章后加入角色日常、内心反思或环境描写'
+    },
+    'consecutive_low': {
+        'problem': '连续平淡',
+        'suggestion': '在平淡章节中插入小冲突或悬念，提升节奏',
+        'example': '可以在第{chapter}章加入意外事件、新角色登场或旧伏笔回收'
+    },
+    'no_peak': {
+        'problem': '缺乏高潮',
+        'suggestion': '在适当位置安排高潮章节，提升故事张力',
+        'example': '建议在第{chapter}章安排一次重要对决或关键转折'
+    },
+    'no_mid': {
+        'problem': '缺乏上升',
+        'suggestion': '增加上升章节，为高潮做铺垫',
+        'example': '可以在第{chapter}章加入角色成长、实力提升或关系进展'
+    },
+    'peak_ratio_low': {
+        'problem': '高潮比例过低',
+        'suggestion': '增加高潮章节数量，提升故事吸引力',
+        'example': '当前高潮比例{current}%，建议提升到{ideal}%'
+    },
+    'peak_ratio_high': {
+        'problem': '高潮比例过高',
+        'suggestion': '适当降低高潮频率，避免读者疲劳',
+        'example': '当前高潮比例{current}%，建议降低到{ideal}%'
+    },
+    'hook_missing': {
+        'problem': '章节结尾缺乏钩子',
+        'suggestion': '在章节结尾设置悬念或转折，吸引读者继续阅读',
+        'example': '可以在第{chapter}章结尾加入未解之谜或突发事件'
+    },
+    'pacing_jump': {
+        'problem': '节奏跳跃过大',
+        'suggestion': '在节奏突变处增加过渡章节，使变化更自然',
+        'example': '第{chapter}章从{from_pacing}直接跳到{to_pacing}，建议加入过渡'
+    }
+}
+
+
+def analyze_pacing_with_suggestions(chapters_dir, recent_n=None):
+    """Analyze pacing and generate optimization suggestions."""
+    chapter_files = list_chapters(chapters_dir, recent_n)
+    if not chapter_files:
+        return {'error': '未找到章节文件'}
+
+    # Analyze each chapter
+    chapters = []
+    pacing_sequence = []
+
+    for idx, cf in enumerate(chapter_files):
+        raw, title, clean, wc = read_chapter(cf)
+        pacing_label, pacing_score = estimate_pacing(clean)
+        hook = detect_hook_type_from_patterns(raw)
+
+        chapters.append({
+            'chapter_num': idx + 1,
+            'title': title,
+            'word_count': wc,
+            'pacing': pacing_label,
+            'pacing_score': pacing_score,
+            'hook': hook if isinstance(hook, str) else hook.get('type', '未知')
+        })
+        pacing_sequence.append(pacing_label)
+
+    # Calculate distribution
+    pacing_dist = defaultdict(int)
+    for p in pacing_sequence:
+        pacing_dist[p] += 1
+
+    total = len(pacing_sequence)
+    ratios = {k: round(v / max(total, 1) * 100, 1) for k, v in pacing_dist.items()}
+
+    # Detect issues and generate suggestions
+    issues = []
+    suggestions = []
+
+    # 1. Check consecutive high/low
+    current_pacing = pacing_sequence[0] if pacing_sequence else None
+    streak_start = 0
+
+    for i, pacing in enumerate(pacing_sequence):
+        if pacing != current_pacing:
+            streak_length = i - streak_start
+
+            if current_pacing in ['S4', 'S5'] and streak_length >= PACING_RULES['max_consecutive_high']:
+                issues.append({
+                    'type': 'consecutive_high',
+                    'chapters': f"第{streak_start+1}-{i}章",
+                    'length': streak_length
+                })
+                suggestions.append({
+                    'type': 'consecutive_high',
+                    'chapter': streak_start + 1,
+                    'detail': OPTIMIZATION_SUGGESTIONS['consecutive_high']['suggestion'],
+                    'example': OPTIMIZATION_SUGGESTIONS['consecutive_high']['example'].format(chapter=streak_start + 1)
+                })
+
+            elif current_pacing in ['S1', 'S2'] and streak_length >= PACING_RULES['max_consecutive_low']:
+                issues.append({
+                    'type': 'consecutive_low',
+                    'chapters': f"第{streak_start+1}-{i}章",
+                    'length': streak_length
+                })
+                suggestions.append({
+                    'type': 'consecutive_low',
+                    'chapter': streak_start + 1,
+                    'detail': OPTIMIZATION_SUGGESTIONS['consecutive_low']['suggestion'],
+                    'example': OPTIMIZATION_SUGGESTIONS['consecutive_low']['example'].format(chapter=streak_start + 1)
+                })
+
+            current_pacing = pacing
+            streak_start = i
+
+    # 2. Check peak interval
+    last_peak = None
+    for i, pacing in enumerate(pacing_sequence):
+        if pacing in ['S4', 'S5']:
+            if last_peak is not None and (i - last_peak) > PACING_RULES['max_no_peak_interval']:
+                issues.append({
+                    'type': 'no_peak',
+                    'gap': i - last_peak,
+                    'chapters': f"第{last_peak+1}-{i}章"
+                })
+                suggestions.append({
+                    'type': 'no_peak',
+                    'chapter': last_peak + PACING_RULES['max_no_peak_interval'] // 2,
+                    'detail': OPTIMIZATION_SUGGESTIONS['no_peak']['suggestion'],
+                    'example': OPTIMIZATION_SUGGESTIONS['no_peak']['example'].format(
+                        chapter=last_peak + PACING_RULES['max_no_peak_interval'] // 2
+                    )
+                })
+            last_peak = i
+
+    # 3. Check mid interval
+    last_mid = None
+    for i, pacing in enumerate(pacing_sequence):
+        if pacing in ['S3', 'S4', 'S5']:
+            if last_mid is not None and (i - last_mid) > PACING_RULES['max_no_mid_interval']:
+                issues.append({
+                    'type': 'no_mid',
+                    'gap': i - last_mid,
+                    'chapters': f"第{last_mid+1}-{i}章"
+                })
+                suggestions.append({
+                    'type': 'no_mid',
+                    'chapter': last_mid + PACING_RULES['max_no_mid_interval'] // 2,
+                    'detail': OPTIMIZATION_SUGGESTIONS['no_mid']['suggestion'],
+                    'example': OPTIMIZATION_SUGGESTIONS['no_mid']['example'].format(
+                        chapter=last_mid + PACING_RULES['max_no_mid_interval'] // 2
+                    )
+                })
+            last_mid = i
+
+    # 4. Check ratios
+    peak_ratio = ratios.get('S4', 0) + ratios.get('S5', 0)
+    if peak_ratio < PACING_RULES['ideal_peak_ratio'] * 100 * 0.7:  # 30% below ideal
+        suggestions.append({
+            'type': 'peak_ratio_low',
+            'current': round(peak_ratio, 1),
+            'ideal': round(PACING_RULES['ideal_peak_ratio'] * 100, 1),
+            'detail': OPTIMIZATION_SUGGESTIONS['peak_ratio_low']['suggestion'],
+            'example': OPTIMIZATION_SUGGESTIONS['peak_ratio_low']['example'].format(
+                current=round(peak_ratio, 1),
+                ideal=round(PACING_RULES['ideal_peak_ratio'] * 100, 1)
+            )
+        })
+
+    # 5. Check hooks
+    hook_missing_chapters = [ch for ch in chapters if ch['hook'] == '未检测']
+    if hook_missing_chapters:
+        suggestions.append({
+            'type': 'hook_missing',
+            'count': len(hook_missing_chapters),
+            'chapters': [ch['chapter_num'] for ch in hook_missing_chapters[:5]],
+            'detail': OPTIMIZATION_SUGGESTIONS['hook_missing']['suggestion'],
+            'example': f"以下章节缺少钩子：{', '.join(f'第{ch}章' for ch in hook_missing_chapters[:5])}"
+        })
+
+    # 6. Check pacing jumps
+    for i in range(len(pacing_sequence) - 1):
+        from_score = chapters[i]['pacing_score']
+        to_score = chapters[i+1]['pacing_score']
+        if abs(to_score - from_score) > 2:  # Jump of more than 2 levels
+            issues.append({
+                'type': 'pacing_jump',
+                'from_chapter': i + 1,
+                'to_chapter': i + 2,
+                'from_pacing': chapters[i]['pacing'],
+                'to_pacing': chapters[i+1]['pacing']
+            })
+            suggestions.append({
+                'type': 'pacing_jump',
+                'chapter': i + 1,
+                'from_pacing': chapters[i]['pacing'],
+                'to_pacing': chapters[i+1]['pacing'],
+                'detail': OPTIMIZATION_SUGGESTIONS['pacing_jump']['suggestion'],
+                'example': OPTIMIZATION_SUGGESTIONS['pacing_jump']['example'].format(
+                    chapter=i + 1,
+                    from_pacing=chapters[i]['pacing'],
+                    to_pacing=chapters[i+1]['pacing']
+                )
+            })
+
+    return {
+        'total_chapters': total,
+        'pacing_distribution': dict(pacing_dist),
+        'ratios': ratios,
+        'chapters': chapters,
+        'issues': issues,
+        'suggestions': suggestions,
+        'issue_count': len(issues),
+        'suggestion_count': len(suggestions)
+    }
+
+
+def main():
+    parser = argparse.ArgumentParser(description='节奏优化建议脚本')
+    parser.add_argument('chapters_dir', help='章节目录路径')
+    parser.add_argument('--recent', type=int, help='仅分析最近N章')
+    parser.add_argument('--json', action='store_true', help='JSON输出')
+    args = parser.parse_args()
+
+    if not os.path.isdir(args.chapters_dir):
+        print(f"错误: 目录不存在: {args.chapters_dir}", file=sys.stderr)
+        sys.exit(1)
+
+    result = analyze_pacing_with_suggestions(args.chapters_dir, args.recent)
+
+    if args.json:
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+    else:
+        if 'error' in result:
+            print(result['error'])
+            return
+
+        print(f"\n=== 节奏优化建议 (最近{result['total_chapters']}章) ===\n")
+
+        print("节奏分布:")
+        dist = result['pacing_distribution']
+        for label in ['S5', 'S4', 'S3', 'S2', 'S1']:
+            count = dist.get(label, 0)
+            ratio = result['ratios'].get(label, 0)
+            bar = "█" * count
+            print(f"  {label}: {bar} ({count}章, {ratio}%)")
+
+        print(f"\n问题数: {result['issue_count']}")
+        print(f"建议数: {result['suggestion_count']}")
+
+        if result['suggestions']:
+            print(f"\n优化建议:")
+            for i, suggestion in enumerate(result['suggestions'], 1):
+                print(f"\n  {i}. [{suggestion['type']}]")
+                print(f"     {suggestion['detail']}")
+                print(f"     示例: {suggestion['example']}")
+        else:
+            print(f"\n✓ 节奏良好，无需优化")
+
+
+if __name__ == '__main__':
+    main()

package/skill/scripts/auditor/pacing_report.py

@@ -0,0 +1,275 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+卷级节奏报告（含可视化）
+分析卷内所有章节的节奏分布、问题区域、追读力趋势，支持 emoji 可视化。
+供 `/novel-maker review pacing volume` 使用。
+
+用法:
+    python scripts/auditor/pacing_report.py 章节目录 --json
+    python scripts/auditor/pacing_report.py 章节目录 --visualize
+    python scripts/auditor/pacing_report.py 章节目录 --recent 10
+"""
+
+import os
+import sys
+import json
+import re
+from collections import Counter
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', 'common'))
+from nm_utils import (
+    list_chapters, read_chapter, estimate_pacing, detect_hook_type_from_patterns
+)
+
+PACING_NAMES = {
+    'S5': '极高潮', 'S4': '高潮', 'S3': '上升', 'S2': '平缓', 'S1': '低谷'
+}
+
+PACING_MARKERS = {
+    'S5': '🔴', 'S4': '', 'S3': '', 'S2': '🟢', 'S1': '⚪'
+}
+
+EMOTION_MARKERS = {
+    '爽': '💥', '感动': '❤️', '虐': '😢', '惊': '😱', '笑': '😂'
+}
+
+# 节奏规则
+MAX_CONSECUTIVE_HIGH = 3  # 不能连续3章S4+
+MAX_CONSECUTIVE_LOW = 3   # 不能连续3章S2-
+MAX_NO_PEAK_INTERVAL = 8  # 每8章必须有S4/S5
+MAX_NO_MID_INTERVAL = 3   # 每3章必须有S3+
+
+
+def analyze_pacing_volume(chapters_dir, recent_n=None):
+    chapter_files = list_chapters(chapters_dir, recent_n)
+    if not chapter_files:
+        return {'error': 'No chapters found'}
+
+    chapters = []
+    pacing_sequence = []
+
+    for idx, filepath in enumerate(chapter_files):
+        raw, title, clean, wc = read_chapter(filepath)
+        pacing_label, pacing_num = estimate_pacing(raw)
+        hook_type = detect_hook_type_from_patterns(raw[-500:] if len(raw) > 500 else raw)
+
+        chapters.append({
+            'num': idx + 1,
+            'title': title,
+            'words': wc,
+            'pacing': pacing_label,
+            'pacing_num': pacing_num,
+            'hook_type': hook_type,
+        })
+        pacing_sequence.append(pacing_num)
+
+    # 节奏分布统计
+    pacing_dist = Counter(c['pacing'] for c in chapters)
+    total = len(chapters)
+
+    # 问题区域检测
+    problems = []
+
+    # 连续高潮检测
+    run_start = 0
+    for i in range(1, len(pacing_sequence)):
+        if pacing_sequence[i] >= 4 and pacing_sequence[i-1] >= 4:
+            if i - run_start >= MAX_CONSECUTIVE_HIGH - 1:
+                problems.append({
+                    'type': 'consecutive_high',
+                    'chapters': f"第{run_start+1}-{i+1}章",
+                    'severity': 'warning',
+                    'message': f"连续{i-run_start+1}章S4/S5高潮，读者可能疲劳"
+                })
+        else:
+            run_start = i
+
+    # 连续平淡检测
+    run_start = 0
+    for i in range(1, len(pacing_sequence)):
+        if pacing_sequence[i] <= 2 and pacing_sequence[i-1] <= 2:
+            if i - run_start >= MAX_CONSECUTIVE_LOW - 1:
+                problems.append({
+                    'type': 'consecutive_low',
+                    'chapters': f"第{run_start+1}-{i+1}章",
+                    'severity': 'warning',
+                    'message': f"连续{i-run_start+1}章S1/S2平淡，读者可能弃读"
+                })
+        else:
+            run_start = i
+
+    # 峰值间隔检测
+    last_peak = -1
+    for i, p in enumerate(pacing_sequence):
+        if p >= 4:
+            if last_peak >= 0 and (i - last_peak) > MAX_NO_PEAK_INTERVAL:
+                problems.append({
+                    'type': 'peak_gap',
+                    'chapters': f"第{last_peak+2}-{i}章",
+                    'severity': 'warning',
+                    'message': f"超过{MAX_NO_PEAK_INTERVAL}章无S4/S5高潮"
+                })
+            last_peak = i
+
+    # 追读力趋势评估（每5章一组）
+    read_trends = []
+    for start in range(0, total, 5):
+        end = min(start + 5, total)
+        chunk = chapters[start:end]
+        avg_pacing = sum(c['pacing_num'] for c in chunk) / len(chunk)
+        high_count = sum(1 for c in chunk if c['pacing_num'] >= 4)
+        if avg_pacing >= 3.5:
+            rating = '★★★★★'
+        elif avg_pacing >= 3.0:
+            rating = '★★★★☆'
+        elif avg_pacing >= 2.5:
+            rating = '★★★☆☆'
+        elif avg_pacing >= 2.0:
+            rating = '★★☆☆☆'
+        else:
+            rating = '★☆☆☆☆'
+        read_trends.append({
+            'range': f"第{start+1}-{end}章",
+            'rating': rating,
+            'avg_pacing': round(avg_pacing, 1),
+            'peak_count': high_count,
+        })
+
+    # 钩子类型分布
+    hook_dist = Counter(c['hook_type'] for c in chapters)
+
+    # 后续建议
+    suggestions = []
+    if pacing_sequence[-3:] == [4, 4, 4] or pacing_sequence[-3:] == [5, 4, 5]:
+        suggestions.append("下一章安排日常缓冲（S2）")
+    if pacing_sequence[-3:] == [1, 1, 2] or pacing_sequence[-3:] == [2, 1, 1]:
+        suggestions.append("下一章安排冲突/高潮（S3+）")
+    if hook_dist.get('悬念', 0) + hook_dist.get('未知', 0) > total * 0.4:
+        suggestions.append("钩子类型过于单一，建议丰富悬念类型")
+
+    return {
+        'total_chapters': total,
+        'pacing_distribution': dict(pacing_dist),
+        'chapters': chapters,
+        'problems': problems,
+        'read_trends': read_trends,
+        'hook_distribution': dict(hook_dist),
+        'suggestions': suggestions,
+    }
+
+
+def generate_heatmap(chapters_dir, recent_n=None):
+    """生成节奏热力图（从 pacing_visualize.py 合并）"""
+    chapter_files = list_chapters(chapters_dir, recent_n)
+    if not chapter_files:
+        return "未找到章节文件"
+
+    lines = [f"章: " + " ".join(f"{i:02d}" for i in range(1, len(chapter_files) + 1))]
+    markers = []
+    for cf in chapter_files:
+        raw, _, _, _ = read_chapter(cf)
+        pacing_label, _ = estimate_pacing(raw)
+        markers.append(PACING_MARKERS.get(pacing_label, ''))
+    lines.append("    " + " ".join(markers))
+    return "\n".join(lines)
+
+
+def generate_emotion_stats(chapters_dir, recent_n=None):
+    """生成多维度情绪统计（从 pacing_visualize.py 合并）"""
+    chapter_files = list_chapters(chapters_dir, recent_n)
+    if not chapter_files:
+        return "未找到章节文件"
+
+    total_emotions = {}
+    for cf in chapter_files:
+        raw, _, _, _ = read_chapter(cf)
+        for emotion in EMOTION_MARKERS:
+            count = raw.count(emotion)
+            if count > 0:
+                total_emotions[emotion] = total_emotions.get(emotion, 0) + count
+
+    lines = []
+    chapter_count = len(chapter_files)
+    for emotion, count in sorted(total_emotions.items(), key=lambda x: -x[1]):
+        avg = chapter_count / count if count > 0 else 0
+        lines.append(f"- {EMOTION_MARKERS[emotion]} {emotion}：{count}次（平均{avg:.1f}章/次）")
+    return "\n".join(lines) if lines else "未检测到情绪关键词"
+
+
+def main():
+    import argparse
+    parser = argparse.ArgumentParser(description="Volume pacing report with visualization")
+    parser.add_argument("chapters_dir", help="Chapters directory")
+    parser.add_argument("--recent", type=int, help="Only analyze last N chapters")
+    parser.add_argument("--json", action="store_true", help="Output as JSON")
+    parser.add_argument("--visualize", action="store_true", help="Show heatmap and emotion stats")
+    args = parser.parse_args()
+
+    if not os.path.isdir(args.chapters_dir):
+        print(f"Error: {args.chapters_dir} is not a directory", file=sys.stderr)
+        sys.exit(1)
+
+    result = analyze_pacing_volume(args.chapters_dir, recent_n=args.recent)
+
+    if args.json:
+        # Add visualization data to JSON output
+        if args.visualize:
+            result['heatmap'] = generate_heatmap(args.chapters_dir, args.recent)
+            result['emotion_stats'] = generate_emotion_stats(args.chapters_dir, args.recent)
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+        return
+
+    if 'error' in result:
+        print(result['error'])
+        return
+
+    print(f"\n{'=' * 60}")
+    print(f"📊 节奏报告 (最近{result['total_chapters']}章)")
+    print(f"{'=' * 60}\n")
+
+    print("节奏分布:")
+    dist = result['pacing_distribution']
+    total = result['total_chapters']
+    for label in ['S5', 'S4', 'S3', 'S2', 'S1']:
+        count = dist.get(label, 0)
+        pct = round(count / max(total, 1) * 100, 0)
+        bar = "█" * count
+        name = PACING_NAMES.get(label, label)
+        print(f"  {label}({name:4s}): {bar} ({count}章, {pct}%)")
+
+    print(f"\n问题区域:")
+    if result['problems']:
+        for p in result['problems']:
+            print(f"  ⚠ {p['chapters']}: {p['message']}")
+    else:
+        print("  ✅ 无明显问题")
+
+    print(f"\n追读力趋势:")
+    for t in result['read_trends']:
+        print(f"  {t['range']}: {t['rating']} (平均节奏 {t['avg_pacing']}, 高潮{t['peak_count']}次)")
+
+    print(f"\n钩子分布:")
+    for h, c in sorted(result['hook_distribution'].items(), key=lambda x: x[1], reverse=True):
+        print(f"  {h}: {c}次")
+
+    if result['suggestions']:
+        print(f"\n改进建议:")
+        for s in result['suggestions']:
+            print(f"  → {s}")
+
+    print(f"\n章节节奏明细:")
+    for ch in result['chapters']:
+        print(f"  第{ch['num']}章: {ch['title']} ({ch['pacing']}, {ch['words']}字)")
+
+    if args.visualize:
+        print(f"\n{'=' * 60}")
+        print(f"🎨 节奏可视化")
+        print(f"{'=' * 60}\n")
+        print(generate_heatmap(args.chapters_dir, args.recent))
+        print(f"\n情绪统计:")
+        print(generate_emotion_stats(args.chapters_dir, args.recent))
+
+
+if __name__ == "__main__":
+    main()