A self-evolving novel writing engine for Chinese fiction with continuity tracking, multi-role quality review, foreshadowing management, character voice libra...
---
name: lobster-novel
description: Self-evolving novel writing engine for OpenClaw agents. Pipeline: context to writer to multi-role review to continuity tracking. Built-in quality checks, foreshadowing management, character voice library, and token cost optimization.
version: 1.4.0
homepage: https://github.com/awoo129/lobster-novel
metadata: {"emoji":"π¦","os":["linux","darwin","win32"],"requires":{"bins":[]}}
---
# 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
```bash
# 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
| Command | Description |
|---------|-------------|
| `init` | Initialize a new novel project |
| `status` | Show project status |
| `context [N]` | Generate writing context for chapter N |
| `write` | Auto-write next chapter |
| `save N file.md` | Save a chapter with review |
| `review N file.md` | Run quality review |
| `export [md\|txt\|html]` | Export the full novel |
| `style-template` | Manage style templates |
| `tokens` | Token usage analysis |
| `bible` | Manage novel bible |
| `continuity` | View continuity ledger |
| `foreshadow` | Manage foreshadowing items |
## 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
```bash
cd lobster-novel
python3 -m pytest tests/ -v
```
15 test modules.
## License
MIT
don't have the plugin yet? install it then click "run inline in claude" again.