Webnovel Writer: Long-form Web Novel Creation Practice Based on Claude Code

Difficulty: Medium | Duration: 30 Minutes | Takeaway: Master the core methods of long-form web novel creation using an AI Agent system

Target Audience

• Developers with 1-5 years of experience interested in AI Agents
• Web novel authors wanting to assist their writing with AI
• Engineers currently building AI writing systems

Core Dependencies and Environment

• Required: Claude Code (Latest Version)
• Language: Python 3.10+
• RAG: Embedding API (ModelScope) + Rerank API (Jina)
• Optional: Node.js 18+ (For Dashboard)

Project Structure Tree

webnovel-writer/
├── .claude-plugin/
│   └── marketplace.json          # Plugin marketplace configuration
├── agents/                       # 8 Agents
│   ├── context-agent.md         # Creation task brief generation
│   ├── data-agent.md            # Entity and state management
│   ├── consistency-checker.md   # Setting consistency validation
│   ├── continuity-checker.md    # Narrative continuity validation
│   ├── high-point-checker.md    # Climax/Excitement density check
│   ├── ooc-checker.md           # Out-of-character (OOC) check
│   ├── pacing-checker.md        # Pacing ratio check
│   └── reader-pull-checker.md   # Retention/Reader-pull check
├── dashboard/                   # Visualization panel
│   ├── server.py                # Flask backend
│   ├── watcher.py               # File monitoring
│   └── frontend/                # React frontend
├── genres/                      # Genre templates
│   ├── xuanhuan/               # Xuanhuan
│   ├── dog-blood-romance/      # Melodramatic romance
│   ├── period-drama/           # Ancient Chinese setting
│   └── ...
├── skills/                      # Skill definitions
│   ├── init.md                  # Project initialization
│   ├── plan.md                  # Outline planning
│   ├── write.md                 # Content writing
│   ├── review.md                # Chapter auditing
│   └── ...
└── docs/                        # Detailed documentation
    ├── architecture.md
    ├── commands.md
    └── rag-and-config.md

Step-by-Step Guide

Step 1: Install Plugin

Open Claude Code and execute the following commands to install the plugin:

claude plugin marketplace add lingfengQAQ/webnovel-writer --scope user
claude plugin install webnovel-writer@webnovel-writer-marketplace --scope user

Step 2: Install Python Dependencies

python -m pip install -r https://raw.githubusercontent.com/lingfengQAQ/webnovel-writer/HEAD/requirements.txt

This command installs all dependencies for both the core writing pipeline and the Dashboard.

Step 3: Initialize Web Novel Project

In Claude Code, execute:

/webnovel-init

The system will prompt you for a book title, then create a project directory under the current Workspace and write the current project pointer to workspace/.claude/.webnovel-current-project.

Step 4: Configure RAG Environment (Required)

Enter the root directory of the initialized book project and create a .env file:

cp .env.example .env

Edit .env and fill in your API configurations:

# Embedding Model (For vector retrieval)
EMBED_BASE_URL=https://api-inference.modelscope.cn/v1
EMBED_MODEL=Qwen/Qwen3-Embedding-8B
EMBED_API_KEY=your_embed_api_key

# Rerank Model (For result reranking)
RERANK_BASE_URL=https://api.jina.ai/v1
RERANK_MODEL=jina-reranker-v3
RERANK_API_KEY=your_rerank_api_key

Step 5: Start Creating

You can now begin writing:

# Step 5a: Plan outline
/webnovel-plan 1

# Step 5b: Write Chapter 1
/webnovel-write 1

# Step 5c: Review Chapters 1-5
/webnovel-review 1-5

Execution logic for each command:

Step 6: Launch Visualization Dashboard (Optional)

/webnovel-dashboard

Dashboard features:

• Project status overview
• Entity graph visualization
• Chapter/Outline browsing
• Reader-pull metric viewing

(Optional) Step 7: Customize Agent Models

All built-in Agents in this project default to inherit (inheriting the current Claude session model). If you wish to specify a model for a specific Agent, edit the frontmatter of the corresponding file:

---
name: context-agent
description: Generate creation task brief
tools: Read, Grep, Bash
model: sonnet  # Specify use of the Sonnet model
---

Common options: inherit / sonnet / opus / haiku.

Core Architecture Analysis

Three Laws Against Hallucination

Webnovel Writer solves AI "hallucination" problems fundamentally using these three laws:

Dual Agent Architecture

The system adopts a classic "Read-Write Separation" architecture:

Context Agent (Read)

• Builds a "Creation Task Brief" before writing
• Loads chapter context, constraints, and reader-pull strategies
• Ensures the AI knows "what to write" and "what not to write"

Data Agent (Write)

• Extracts entities and state changes from the text
• Automatically updates state.json, index.db, and vectors.db
• Ensures a closed data loop so subsequent chapters "remember" what happened before

Six-Dimensional Parallel Audit

After each chapter is written, 6 Checkers are launched simultaneously:

Strand Weave Pacing System

The system features a built-in pacing control mechanism:

• Quest (Main Plot): Ideal ratio 60%, consecutive no more than 5 chapters
• Fire (Romance/Emotional line): Ideal ratio 20%, gap no more than 10 chapters
• Constellation (World-building/Lore): Ideal ratio 20%, gap no more than 15 chapters

Troubleshooting

Q1: Retrieval fails after RAG configuration

Symptom: "no results from RAG" prompt during writing

Troubleshooting:

1. Ensure the .env file is in the project root directory
2. Check if the API Key is correct
3. Try manually calling the Embedding API to verify connectivity

curl -X POST $EMBED_BASE_URL \
  -H "Authorization: Bearer $EMBED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "test text"}'

Q2: Model call timeout during writing

Symptom: /webnovel-write times out after running for a long time

Troubleshooting:

1. Check if the network to the API provider is stable
2. Try switching to a faster model (e.g., Haiku)
3. Increase the timeout parameter in the Agent configuration

Q3: State file corruption

Symptom: state.json or index.db reports "invalid json" or "database locked"

Troubleshooting:

1. Backup the current file
2. Run the built-in recovery script (see docs/operations.md)
3. Manually fix JSON formatting errors

Q4: Dashboard fails to start

Symptom: /webnovel-dashboard is unresponsive or errors out

Troubleshooting:

1. Confirm Python dependencies are fully installed
2. Check if port 5000 is occupied
3. View logs for specific error messages

Q5: Agent model settings not taking effect

Symptom: Modified Agent model configuration but it didn't change

Troubleshooting:

1. Confirm the correct Agent file was edited
2. Check if YAML format is correct (space after colon)
3. Restart the Claude Code session

Q6: Reader-pull check always fails

Symptom: Reader-pull Checker prompts "hooks are not strong enough"

Troubleshooting:

1. Check if there is a cliffhanger at the end of the chapter
2. See if explicit "plot holes/hooks" are left to be filled
3. Check for lack of expectation guidance for the next chapter

Extended Reading / Advanced Directions

1. Custom Genre Templates

The project includes various web novel genre templates (Xuanhuan, Ancient Drama, Melodrama, etc.). You can add your own genre configuration in the genres/ directory.

2. Integration with OpenClaw

Webnovel Writer can be used as a Skill for OpenClaw to achieve a more powerful automated creation workflow.

3. Deep Agent Customization

By modifying the prompts and tools in agents/*.md files, you can make the AI write according to your personal style.

4. Multi-model Hybrid Usage

Try using different models for different tasks: use Opus for the main text, Haiku for audits, and Sonnet for planning.