lobster-novel

A self-evolving novel writing engine for OpenClaw agents. Designed for long-form Chinese fiction with rigorous continuity control, multi-role quality review, and built-in token cost management.

Quick Start

# Initialize a new novel project
python3 lobster_novel.py --dir my-novel init --title "Novel Title"

# View current status
python3 lobster_novel.py --dir my-novel status

# Generate writing context for chapter N
python3 lobster_novel.py --dir my-novel context N

# Auto-write next chapter via SenseNova API
python3 lobster_novel.py --dir my-novel write

# Save a manually written chapter with review
python3 lobster_novel.py --dir my-novel save N chapter.md --summary "Summary"

# Run quality review on a chapter
python3 lobster_novel.py --dir my-novel review N chapter.md

# Export the full novel
python3 lobster_novel.py --dir my-novel export md --output novel.md

# Manage style templates
python3 lobster_novel.py --dir my-novel style-template list
python3 lobster_novel.py --dir my-novel style-template activate "wuxia"

Architecture

lobster-novel/
├── core/                 # Core engine modules
│   ├── bible.py          # Novel bible manager (world-building, characters, settings)
│   ├── continuity.py     # Continuity ledger (per-chapter state snapshots)
│   ├── pipeline.py       # Writing pipeline orchestrator
│   ├── chapters.py       # Chapter generator with token analysis
│   ├── arc_planner.py    # Story arc planner
│   ├── beat_sheet.py     # Beat sheet generator
│   ├── contract.py       # Writer-agent contract enforcement
│   ├── style_lock.py     # Style constraint system
│   ├── conflict_detector.py
│   └── chinese_typeset.py
├── agents/               # Specialized agent roles
│   ├── context_agent.py  # Context preparation agent
│   ├── data_agent.py     # Data extraction agent
│   ├── reviewer_agent.py # Multi-role review agent
│   └── three_laws.py     # Three Laws of Novel Writing enforcement
├── review/               # Quality review modules
│   ├── quality_check.py  # 6-role static review
│   ├── aigc_detect.py    # AI-style pattern detector
│   ├── scorer.py         # Chapter scoring engine
│   ├── strand_balance.py # Strand balance checker
│   └── deai_writer.py    # De-AI writing assistant
├── memory/               # Memory & tracking systems
│   ├── character_tracker.py
│   ├── character_voice.py
│   ├── emotion_arc.py
│   ├── foreshadowing.py
│   ├── plot_tracker.py
│   ├── relationship_tracker.py
│   ├── style_library.py
│   └── novel_kg.py
├── tools/                # CLI tools
│   ├── novel-cli.py      # Main CLI (12 subcommands)
│   ├── auto_write.py     # Batch continuous writing
│   ├── batch_refine.py   # Batch chapter refinement
│   ├── serial_writer.py  # Serial chapter writer
│   └── v3_checkpoint.py
├── rag/                  # RAG systems
│   └── novel_rag.py
├── output/               # Export modules
│   └── export.py
├── templates/            # Style templates
├── scripts/              # Utility scripts
└── tests/                # Test suites

Writing Pipeline

User Idea → init → context → [write | manual writing]
  → save (auto quality review) → review (static + AI-style detection)
  → foreshadowing update → next chapter → export

Key Principles

1. Continuity First — Every chapter updates the continuity ledger.
2. Multi-Role Review — 6 roles: Reader, Editor, Storyteller, Satisfaction Analyst, Voice Validator, Web Novel Editor.
3. AI-Style Detection — Detects and flags AI-typical patterns.
4. Token Budget — Built-in token counting and cost estimation.
5. Style Lock — Enforces selected writing style throughout.

CLI Reference

Style Templates

Built-in templates: wuxia, xianxia, xuanhuan, historical, horror, romance, sci-fi, comedy.

Dependencies

• Python 3.10+
• SenseNova API key (via SENSENOVA_API_KEY env var)
• tiktoken (auto-installed if missing)

Testing

cd lobster-novel
python3 -m pytest tests/ -v

15 test modules.

License

MIT