Webnovel Writer

A long-form web novel plugin for Claude Code. From setting initialization, volume planning, chapter writing, review, memory accumulation, and status queries, to a read-only visual dashboard — the entire workflow is built in.

It tackles one thing: AI writes hundreds of chapters but still remembers settings, follows foreshadowing, and stays on the outline.

In short: a consistency system for long serialized works, not a one-shot generator that forgets.

Version Guide (updated 2026-09-21)

Branch	Version	Status
master (this branch)	v6 · Claude Code plugin	Maintained (critical bug fixes only); use this version if you're on Claude Code
v7	v7 · CLI multi-host rewrite	Frozen, unreleased; development archive only
v8	v8 · Writing workbench based on DeepSeek Harness	Source preview; installation & version notes

Feedback collected in the original v7 design post (Discussions #118) remains a key input for v8 design. The v7 CLI form has been evaluated and will not be released; the next generation will be developed as a dsh plugin. v8 publishes product source code, running skills, and usage tutorials; internal dev discussions and personal creative materials are not public content. v6 and v8 have different installation methods, and no verified migration path exists for moving old book repos directly.

Sponsors & Support

Webnovel Writer × Infistar.cc Infinite Galaxy｜All-Model APIs · Powering Continuous Long-Form Webnovel Writing

Thanks to Infistar.cc Infinite Galaxy for sponsoring Webnovel Writer and providing model service support!

• ⚡ Reliable support for long continuous writing: High-availability model channels and stable responses that cover outline planning, chapter creation, content review, polish/rewrite, and long-context writing.
• 🧠 Compatible with Claude Code and mainstream models: Supports models such as Claude, ChatGPT, Gemini, Kimi, GLM, and DeepSeek; you can flexibly configure the writing, review, and assistant models for long-form work.
• 📚 Powers memory and knowledge-base retrieval: Supports Embedding, Rerank, and other OpenAI-compatible interfaces, helping character setups, timelines, foreshadowing, and chapter content accumulate continuously while reducing forgetting and continuity errors in long-form creation.
• 🎁 Exclusive perks for Webnovel Writer users: Register through the exclusive referral link and complete your first call to claim [a $5-equivalent test credit / exclusive first-charge offer] and quickly experience a more stable, more coherent AI long-form writing workflow!

Thanks to PackyCode for sponsoring Webnovel Writer! PackyCode is a stable, efficient API relay service provider that connects you to mainstream LLMs in one sentence. Unified domain, unified API key, and intelligent failover, with 97% availability. 1:1 CNY recharge with no FX or hidden fees; new users get an instant discount on their first charge plus a $1 free trial credit, and multi-group discounts down to 50% off, along with dedicated high-speed channels for Codex/Claude Code. Register via this link and get started now!

Webnovel Writer is maintained in my spare time. If it saved you from re-organizing settings or re-aligning foreshadowing, email me your thoughts, feedback, or a note of support:

📮 ksdflisjdf@gmail.com

Why You Need It

The hard part of long-form fiction isn't chapter 1 — it's staying consistent at chapters 80, 200, and beyond:

• Character motives stay stable
• Power, timeline, place, world rules don't conflict
• Foreshadowing is logged, advanced, resolved
• Payoffs, romance, worldbuilding keep rhythm
• Post-chapter facts persist into a queryable state system

This system turns those "must-remember, must-not-break" constraints into steps Claude Code runs automatically: check sources before writing, record new facts and run a consistency review after writing, then sync the latest state into the retrieval index, chapter summaries, long-term memory, and Dashboard. It doesn't just "write" — it accumulates while writing.

Core Capabilities

Capability	Command	Description
Deep initialization	/webnovel-init	Stage-by-stage Q&A that helps you build the book's skeleton, setting bibles, master outline, and initial state
Volume planning	/webnovel-plan	Splits volumes and chapters based on the master outline, fills in the timeline, and writes back new settings
Chapter writing	/webnovel-write	One-shot workflow to finish a chapter: prepare context, draft, review, polish, record facts, auto-backup
Quality review	/webnovel-review	Reviews chapters across payoff, consistency, pacing, OOC, coherence, and retention dimensions
State query	/webnovel-query	Query characters, foreshadowing, pacing, entity relations, and runtime info
Project learning	/webnovel-learn	Capture writing techniques that worked in this book and store them in long-term project memory
Visual dashboard	/webnovel-dashboard	Read-only browsing of project state, entity graph, chapter content, and retention metrics
Project health check	/webnovel-doctor	Phase-aware inspection of directories, files, database, RAG, dependencies, and Dashboard artifacts

System layout

flowchart LR
    User[作者 / Claude Code] --> Skills[8 个 Skill 命令]
    Skills --> Agents[Context / Reviewer / Data / Deconstruction Agent]
    Agents --> Story[.story-system 合同与提交链]
    Story --> Commit[accepted CHAPTER_COMMIT]
    Commit --> State[.webnovel/state.json]
    Commit --> Index[index.db / vectors.db]
    Commit --> Summary[summaries / memory_scratchpad]
    State --> Dashboard[只读 Dashboard]
    Index --> Dashboard
    Summary --> Dashboard

The default main pipeline in v6.0.0 is called Story System, with several key roles:

• .story-system/: the single source of truth. The pre-writing "contract" and post-writing "commit" both live here
• Accepted CHAPTER_COMMIT: when a chapter is finished, new facts are booked in from here
• .webnovel/state.json, index.db, summaries/, memory_scratchpad.json: all read-only views derived from the main pipeline, used for querying and display
• .webnovel/projection_log.jsonl: projection execution log, used to pinpoint which of state/index/summary/memory/vector failed to sync
• project-status, doctor, preflight, and the Dashboard surface the main pipeline and runtime state directly, so you can spot problems at a glance

Quick start

1. Install the plugin

Install via the Claude Code Marketplace:

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

To apply it only to the current project, change --scope user to --scope project.

For more on installing, enabling, and everyday management of plugins, see the official Claude Code docs: Plugins · Plugin Marketplaces.

2. Install Python dependencies

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

3. Initialize a book

Type the following into Claude Code:

/webnovel-init

After init, a book project dir is created, containing:

project-root/
├── .story-system/        # 合同、章节提交和事件审计
├── .webnovel/            # 状态、索引、摘要、备份和长期记忆
├── 正文/                  # 章节正文
├── 大纲/                  # 总纲、卷纲、时间线和章纲
├── 设定集/                # 世界观、角色、力量体系等设定
└── 审查报告/              # 章节审查报告

4. Configure RAG

Go to the book project root, copy .env.example to .env, and fill in the API key:

cp .env.example .env

Minimal config:

EMBED_BASE_URL=https://api-inference.modelscope.cn/v1
EMBED_MODEL=Qwen/Qwen3-Embedding-8B
EMBED_API_KEY=your_embed_api_key

RERANK_BASE_URL=https://api.jina.ai/v1
RERANK_MODEL=jina-reranker-v3
RERANK_API_KEY=your_rerank_api_key

It works without an Embedding key—the system automatically falls back to BM25 keyword retrieval, though semantic recall will be a bit weaker. Both Embedding and Rerank can be swapped for any OpenAI-compatible endpoint.

5. Start planning and writing

/webnovel-plan 1      # 规划第 1 卷
/webnovel-write 1     # 写第 1 章
/webnovel-review 1-5  # 审查第 1-5 章
/webnovel-query 伏笔  # 查询项目状态

6. Open the visual dashboard

/webnovel-dashboard

The Dashboard is a read-only panel showing project state, entity relationship graphs, chapter content, foreshadowing, and retention data. The frontend is pre-built and ships with the plugin, so you don't need to run npm build locally.

Chapter workflow

/webnovel-write doesn't just hand the job to the model and call it a day; it's a full pipeline with checkpoints:

1. Preflight the project root, placeholders, and Story System health
2. Refresh the chapter's runtime contract
3. Call context-agent to generate the writing task brief
4. Draft the main text based on the brief
5. Call reviewer for multi-dimensional review; blocking issues stop the pipeline
6. Polish, typeset, run the Anti-AI final check
7. Call data-agent to extract facts
8. Generate the CHAPTER_COMMIT, driving state, index, summary, memory, and vector projections
9. Perform a chapter-level backup

This splits "how to write" from "what was written": style and pacing are free, but facts must be logged, reviewed, and archived—no fudging.

How to read the final report

When /webnovel-init, /webnovel-plan, /webnovel-write, and /webnovel-review finish, each produces a final report for the author, without dumping raw internal JSON, tracebacks, or long command logs. The report starts with a single overall status:

• Done: targets and key checks passed; move on.
• Partially done: main artifacts kept, but skips, auto-fixes, or small follow-ups remain.
• Your input needed: system halted safely; decide direction, fact trade-offs, file overrides, or blocking issues.
• Not done: key artifacts not reliably produced; rerun or debug per report.

Three fixed sections follow: (1) files produced and completion status, (2) problems encountered and unusually slow steps, (3) next-step suggestions. Auto-handled items are also noted, e.g., a projection failure that was retried successfully; only unrecoverable failures prompt you to check .webnovel/logs/run_last.log.

During execution only brief progress hints appear, showing current step and outputs; you're only asked for judgment on creative direction, fact consistency, file-overwrite risk, or blocking issues. Rerunning the same /webnovel-write 章号 checks for reliable breakpoints first, resuming from the failure point instead of rewriting body text, review, commit, or backup already reliably complete.

Built-in genres

37 Chinese web-novel genre templates are built in; mixing several is also supported. A partial list:

Type	Example genres
Xuanhuan/Xiuxian	cultivation, system-flow, high-martial, western fantasy, infinite, apocalypse, sci-fi
Urban/Modern	urban powers, urban daily, urban out-of-box, realistic, esports, livestream
Romance	classical, palace/household, sweet youth, tycoon, melodrama, stand-in, slice-of-life
Special	rule horror, mystery out-of-box, mystery supernatural, historical, wartime spy, Zhihu short, Cthulhu

See the full list in the genre template documentation.

Command reference

Claude Code Skill commands

Command	Example	Purpose
/webnovel-init	/webnovel-init	Initialize a new book project
/webnovel-plan	/webnovel-plan 1	Generate volume outline, timeline, and chapter outline
/webnovel-write	/webnovel-write 45	Write and commit a specified chapter
/webnovel-review	/webnovel-review 1-5	Review a chapter range
/webnovel-query	/webnovel-query 萧炎	Query characters, foreshadowing, state, etc.
/webnovel-learn	/webnovel-learn "这个钩子设计有效"	Write project experience into memory
/webnovel-dashboard	/webnovel-dashboard	Start the read-only visual dashboard
/webnovel-doctor	/webnovel-doctor --chapter 12	Read-only health check of project files, DB, RAG, and dependencies

CLI entry point

All command-line tools are accessed through scripts/webnovel.py:

python -X utf8 "<CLAUDE_PLUGIN_ROOT>/scripts/webnovel.py" --project-root "<PROJECT_ROOT>" <子命令> [参数]

Subcommands:

Subcommand	Description
where	Prints the currently resolved book project root
preflight	Validates plugin paths, project root, and Story System health
project-status	Emits a machine-readable short status, phase, and next step
doctor	Phase-aware project health check with impact and fix suggestions
write-gate	Validates at three natural boundaries: pre-write, pre-commit, post-commit
projections	Reruns or replays projections from existing commits
story-system	Generates contract seeds and runtime contracts
chapter-commit	Commits chapter facts and drives projections
story-events	Queries chapter events or checks event chain health
memory	Views, queries, exports, and backfills long-term memory
rag	Manages vector indexes and retrieval status
status	Emits the project health report

For more commands, see Command details.

Docs navigation

Document	Content
Docs hub	All documentation indexes and recommended reading order
System architecture & modules	Core philosophy, agent division of labor, Story System design
Command details	Quick reference for Skill commands and CLI subcommands
RAG & configuration	Retrieval flow, environment variables, default models
Genre templates	37 genre templates and mixed-genre rules
Project structure & operations	Directory hierarchy, health checks, backup & recovery
Plugin releases	Marketplace release and version sync process

Development & testing

Install deps after cloning:

python -m pip install -r requirements.txt
python -m pip install -r webnovel-writer/scripts/requirements.txt

Run tests:

python -m pytest

The Dashboard frontend lives at webnovel-writer/dashboard/frontend/; the release already includes dist/ build artifacts. When developing the frontend, you can enter that directory on its own and run:

npm install
npm run dev

Troubleshooting

Run preflight first:

python -X utf8 "<CLAUDE_PLUGIN_ROOT>/scripts/webnovel.py" --project-root "<PROJECT_ROOT>" preflight
python -X utf8 "<CLAUDE_PLUGIN_ROOT>/scripts/webnovel.py" --project-root "<PROJECT_ROOT>" doctor --format text

Check:

• Whether story_runtime.mainline_ready is true
• Whether .story-system/commits/chapter_XXX.commit.json exists and is accepted
• Whether projection_status is all done or skipped
• Whether index.db, summaries/, memory_scratchpad.json are generated correctly
• Whether the RAG API key has been written to .env in the book project root

For more operations notes, see Project structure & operations.

Contributing

Issues and PRs welcome. Use the bundled templates: fill in repro steps, env info, impact, and verification, and redact private info first.

Suggested flow:

git checkout -b feature/your-feature
git commit -m "feat: add your feature"
git push origin feature/your-feature

Contribute:

• New genre templates and genre rules
• Stronger chapter review dimensions
• Dashboard information architecture and visualization
• RAG retrieval, entity disambiguation, long-term memory
• Windows/macOS/Linux compatibility issues
• Docs, sample projects, and beginner tutorials

Changelog overview

版本	主要变化
v6.2.1 (当前)	修复 Windows 写章提交偶发的拒绝访问（WinError 5）：资料文件被短暂占用时自动重试
v6.2.0	写章结果更清楚，失败后更好恢复
v6.1.0	插件运行时加固：新增 doctor/project-status/write-gate/projection 重放、hooks、行为 eval 与发布校验
v6.0.0	Story System 全链路上线（合同种子 + 运行时合同 + 章节提交 + 事件审计），补齐集成测试
v5.5.5	长期记忆闭环：写前注入 + 写后沉淀，新增 memory 运维命令
v5.5.4	写作链提示词强约束，统一中文化审查和报告文案
v5.5.3	统一 preflight 预检命令，修复 Windows 终端编码问题
v5.5.2	大纲章节名同步到正文文件名
v5.5.1	修复卷级大纲上下文提取，补齐 Dashboard 和 Learn 命令文档
v5.5.0	新增只读可视化 Dashboard，支持实时刷新
v5.4.4	接入 Plugin Marketplace 安装机制
v5.4.3	增强 RAG 智能上下文（auto/graph_hybrid 回退 BM25）
v5.3	引入追读力系统（Hook / Cool-point / 微兑现 / 债务追踪）

License

This project is licensed under GPL v3.

Star history

Thanks

This project was developed with Claude Code, Gemini CLI, and Codex using a Vibe Coding approach.

Inspiration: Linux.do thread

Thanks to oh-story-claudecode for the story-breakdown process reference.