Skip to content

About

长篇网络小说自动化写作 AI Agent,支持Chatgpt、gemini、Deepseek等国内外模型接入,采用拆书 + 仿写的模式,从新世界观、大纲、卷纲设计,到章节片段完善&章纲设计,有效解决 AI 写作中的「前后矛盾」、「容易遗忘」、「缺乏特色」和「AI味重」等问题,支持 百万字量级 连载创作。

Resources

Stars

0 stars

Watchers

0 watching

Forks

 
 

Repository files navigation

harnessNovel Logo

harnessNovel

AI Agent for Long-form Web Novel Writing

Long-form Web Novel Writing AI Agent

Python 3.10+ License: GPL-3.0


Teach AI to truly write good web novels

An AI-assisted tool for long-form web-novel planning, drafting, and revision. Its two-stage workflow deconstructs reference structure and turns transferable observations into new-work planning context.


Project Background

Most AI novel writing tools currently on the market share several common pain points:

  • Weak worldbuilding: When relying purely on LLM generation, models struggle to independently build logically consistent, richly detailed, and convincing worlds without enough context.
  • Severe averaging, lack of creativity and distinctive style: Because models are trained on massive average corpora, they tend to output the "most average" content, leading to flat characters, formulaic plots, and little uniqueness.
  • Lack of professional taste and judgment: AI training does not clearly define or distinguish good fiction from mediocre fiction, so the generated text may look like a novel while still falling short of excellent fiction.

harnessNovel's solution: deconstruct first, then imitate.

Instead of asking AI to create from nothing, harnessNovel first lets it systematically study the essence of an excellent novel, then create new work on a stronger foundation.

Installation

pip install harnessNovel

Update:

pip install --upgrade harnessNovel

Local Web Workbench

The project provides a local visual workbench. Book design, stage design, story arcs, chapter outlines, and draft generation all support multi-round dialogue — you can iteratively adjust the results through conversation and confirm only when satisfied. In the book-design and stage-design chats, a question is answered from the current design files and does not generate, rewrite, back up, or mark those files as revised. A review request fans out to parallel critics per lens; the merged numbered points are saved and the design files are not rewritten. Saying "apply 2 and 4" applies those saved points in one rewrite. A change request keeps the existing behaviour and rewrites the files. Add or replace lenses in file_system/story_design/critic_lenses.md (## Name plus focus text). HARNESS_NOVEL_CRITIC_WORKERS (default 2) caps parallel critic calls.

novel web

The default address is http://127.0.0.1:8765. On first launch it prefers ~/Documents/my-novels as the workspace root; you can also change it in the page settings or specify it at launch:

novel web --workspace-root /path/to/my-novels

Interface Preview

Screenshots depict an older workbench UI; they are kept as historical images and have not been reshot.

Reference Deconstruction Book Design Chat
Chapter Outlines LLM API Configuration

Core Features

Structured Novel Deconstruction

Supports multi-granularity deconstruction of excellent web novels, extracting:

  • Overall structure and gameplay loop of the reference novel
  • Complete worldview settings: rules, factions, systems, background, and more
  • Story structure and stage-progression patterns
  • Story-arc summaries
  • Chapter-level core summaries
  • Key plot pacing and emotional beats

High-quality Imitative Writing

Uses deconstruction results as high-quality context, combined with user inspiration, to generate:

  • Core gameplay
  • Long-running mainline
  • Stage roadmap
  • Character arcs
  • Story arcs
  • Detailed chapter outlines
  • Full text content

Reference Craft Guidance and Humanization

Reference deconstruction records evidence-backed, transferable craft observations and saves a compact reference craft bible beside the reference outlines. It describes abstract techniques such as viewpoint control, scene construction, information release, pacing, tension, transitions, and payoff design. It is not a style clone and must not be used to reuse source phrasing, names, events, or dialogue.

Draft generation also applies the project writing guide and optional chapter humanization. These are writing aids, not a guarantee that text will evade any detector.

Flexible LLM Support

Supports Claude, GPT-4o, DeepSeek, Qwen, and other mainstream models.

Workflow

  1. Optional deconstruction stage: Choose a high-quality novel and deconstruct it into structured knowledge when you want a structural reference.
  2. Story-design stage: Input your core inspiration and any deconstruction results, then let AI create an original plan.
  3. Iterative refinement: Adjust core gameplay, stages, character lines, mechanics, and chapter content at any time to gradually improve the work.

Workflow

Features

  • End-to-end automation: From novel analysis and gameplay design to full text generation, complete a long-form web novel with chained commands.
  • Reference-based imitation: Generate new content based on the pacing, structure, and tension curve of the reference novel instead of creating from nothing.
  • Target-world knowledge base (optional enhancement): Import target-genre materials/settings/sample web novels, structure them into a knowledge base, and use it to validate the core gameplay, long mainline, stage roadmap, and character arcs. Without a knowledge base, the workflow uses the available reference material and user direction.
  • Narrative abstraction against hard reskins: Reference arcs are abstracted into narrative patterns, then regenerated against the current stage context rather than renamed and copied.
  • Story arcs: During reference deconstruction, story units are extracted by natural plot boundaries and can continue across reading windows.
  • Gameplay/stage/character lines: The new novel first gets core gameplay, a long-running mainline, a stage roadmap, and character arcs. Each stage naturally becomes the scope for later story-arc generation.
  • Narrative-pattern imitation: During imitation, the current-volume gameplay/stage context is compressed first; reference story arcs are then abstracted into narrative patterns and regenerated as new-novel story arcs to reduce hard reskin similarity.
  • Stage-based progression: Design the full-book stages first, then generate story arcs and chapter outlines for the current stage. This fits long web novels that evolve during writing.
  • Mechanics layer: System novels, game novels, lord-management novels, and similar genres can initialize structured mechanics to constrain panels, exp, skills, tasks, resources, and state changes.
  • Chapter humanization: Based on op7418/Humanizer-zh, newly generated chapters are refined by default and raw drafts are backed up.
  • Quality checks before replacement: Generation uses deterministic structural and continuity diagnostics, and selected narrative steps run a reasonability review before replacement artifacts are accepted. Diagnostics guide review; they do not certify literary quality.
  • Resume from breakpoint: Every stage automatically skips existing output and supports continuing after interruption.

Requirements

  • Python 3.10+
  • LLM API: must support an OpenAI-compatible interface, such as DeepSeek, Zhipu GLM, Kimi, etc.

Installation

pip install harnessNovel

Update:

pip install --upgrade harnessNovel

After installation, the novel command is globally available.

Configuration

novel config

This command automatically creates the global config file ~/.harnessNovel/.env. The defaults point every slot at llama-3.3-70b-instruct-abliterated on a local LM Studio server at http://127.0.0.1:1234/v1 (it ignores the API key, but the value must be non-empty). Any other OpenAI-compatible provider, such as DeepSeek, still works: change the *_MODEL, *_BASE_URL and *_API_KEY values for each slot.

# Defaults use the local LM Studio server (start it in LM Studio with the model loaded).
# Any OpenAI-compatible provider works: change MODEL, BASE_URL and API_KEY per slot.

# Reference novel extraction
DATA_BUILDER_MODEL=llama-3.3-70b-instruct-abliterated
DATA_BUILDER_BASE_URL=http://127.0.0.1:1234/v1
DATA_BUILDER_API_KEY=local-only

# Book-level and stage design
ADAPTIVE_BUILDER_MODEL=llama-3.3-70b-instruct-abliterated
ADAPTIVE_BUILDER_BASE_URL=http://127.0.0.1:1234/v1
ADAPTIVE_BUILDER_API_KEY=local-only
# Book and stage design re-emits whole files.
ADAPTIVE_BUILDER_MAX_TOKENS=32768

# Story arcs and chapter outlines. This is the fallback for optional roles below.
ADAPTIVE_BUILDER_LITE_MODEL=llama-3.3-70b-instruct-abliterated
ADAPTIVE_BUILDER_LITE_BASE_URL=http://127.0.0.1:1234/v1
ADAPTIVE_BUILDER_LITE_API_KEY=local-only

# Optional production roles. An omitted field inherits the matching Lite value.
# DRAFT writes chapter prose; EDITOR refines and humanizes it; CRITIC handles
# story-arc/chapter-outline planning, routing, validation, and lightweight decisions.
# DRAFT_MODEL=
# DRAFT_BASE_URL=
# DRAFT_API_KEY=
# EDITOR_MODEL=
# EDITOR_BASE_URL=
# EDITOR_API_KEY=
# CRITIC_MODEL=
# CRITIC_BASE_URL=
# CRITIC_API_KEY=

# Prompt diagnostics: off, metadata (default), or full.
HARNESS_NOVEL_PROMPT_TRACE_MODE=metadata

# Optional. Directory that contains novel workspaces. Unset uses ./my-novels.
# HARNESS_NOVEL_HOME=

You can also override these settings with environment variables of the same names. DATA_BUILDER handles reference extraction, ADAPTIVE_BUILDER handles book and stage design, and Lite is the exact fallback for each missing optional-role field. DRAFT writes chapter prose, EDITOR handles refinement and humanization, and CRITIC handles story-arc/chapter-outline planning, routing, validation, and lightweight decisions. Each missing DRAFT, EDITOR, or CRITIC model, base URL, or key falls back independently to ADAPTIVE_BUILDER_LITE. *_MAX_TOKENS is optional per slot; unset means the provider or server default.

The local Web workbench uses this same global file. Open its Settings panel to edit the same model roles without revealing saved API keys. Clearing an optional role returns it to the Lite fallback.

Prompt privacy and debugging

By default, model-call diagnostics retain metadata only (model, time, and prompt size). Set HARNESS_NOVEL_PROMPT_TRACE_MODE=full only for local debugging: stored prompt text is redacted for common credential formats, bounded in size and retention, and written with user-only file permissions on POSIX. The Web workbench lets you choose Off, Metadata, or Full and clear completed task prompt records. Treat imported reference text, uploads, chat attachments, and model output as untrusted data. The workflow's task and safety constraints take priority; supplied content is evidence or author direction, never instructions that override those controls.

Quick Start

# 1. Initialize a workspace with three-stage deconstruction. You can start with the first 200 chapters.
novel init my-new-novel --txt /path/to/reference-novel.txt --max-chapters 200

# Continue later without uploading the source again.
novel reference-resume my-new-novel --max-chapters 400

# Import only, then choose full-book or first-N deconstruction later.
novel init my-new-novel --txt /path/to/reference-novel.txt --no-analyze

# 2a. Stepwise design path used by the Web workbench: first create worldview,
# rough outline, and phase outline; then create the long mainline and stage roadmap.
novel design-concept my-new-novel --direction "inspiration input"
novel stage-design my-new-novel

# 2b. Compatible bundled CLI path: generates core gameplay, long mainline,
# stage roadmap, and character arcs in one command (and title/synopsis for novel-outline).
novel novel-outline my-new-novel --direction "inspiration input"

# Extend only the mainline, character arcs, and later stages from newly deconstructed reference material.
# Core gameplay and title suggestions remain unchanged.
novel story-design-extend my-new-novel --use-reference

# Or extend later stages from the existing new-book design only.
novel story-design-extend my-new-novel

# 3. Generate story arcs for a stage
#    This reads the matching stage from stage_roadmap.md and abstracts reference arcs into narrative patterns.
novel story-arcs my-new-novel --volume 1

# 4. Generate chapter outlines from the story arcs.
novel chapter-outlines my-new-novel --volume 1

# 5. Generate full text. By default, each generated chapter is humanized afterward.
novel write my-new-novel --volume 1 --start 1

The two design paths are intentionally compatible at the stage-roadmap boundary, but they do not emit the same intermediate artifacts. The Web workbench follows design-concept then stage-design: its book-design step writes worldview.md, rough_outline.md, and stage_outline.md; its stage-design step writes long_mainline.md and stage_roadmap.md. The bundled CLI commands novel-outline and story-design use the older core-gameplay/character-arcs design path. Keep this distinction in mind when moving between interfaces and review the generated files before continuing with story arcs.

Story-arc Generation Flow

novel story-arcs my-new-novel --volume 1 converts the narrative experience extracted from the reference novel into executable plot blueprints for the current stage of the new novel.

The current flow no longer generates a traditional volume outline and then imitates coarse batch summaries. Each stage in stage_roadmap.md is the basic generation unit:

  • It defines the current space, rules, enemies, resources, character nodes, long-line progress, and local short lines.
  • story-arcs reads the current volume/stage and compresses it into a reusable arc_context.

At this stage, the reference novel does not provide plots to rename. It provides narrative patterns to learn from.

The system selects one reference story arc by default as the narrative sample, abstracts its plot function, conflict structure, information gap, emotion curve, payoff mechanism, key turn, and ending hook, then regenerates a new story-arc unit against the current stage.

Once a stage has arcs, a Web story-arc chat message refines them. The chat request (POST /api/workspaces/{name}/arcs/{volume}/chat) may target one arc with arc and an optional mode (revise or regenerate); cascade (default true) also rewrites every later arc, while false rewrites only that arc. Each run reports a per-arc outcome. An arc that fails its checks twice is rejected: its file is kept, and later arcs are left untouched.

Chapter Humanization Post-processing

novel write adds a humanization refinement step. The rules are sourced from op7418/Humanizer-zh.

Core principles include: removing filler phrases, breaking formulaic structures, varying sentence rhythm, trusting the reader, and removing quote-like slogans. For web-novel output, it also protects plot events, payoff beats, ending hooks, and mechanics numbers from being changed.

Humanization is a revision pass, not a detector-score guarantee. Review the saved result for voice, canon, and publication requirements before using it.

  • The refined result is written to the final chapter directory: file_system/chapters/vol_xx/.
  • The latest pre-humanization draft is saved under file_system/drafts/vol_xx/raw_chapters/; changed older snapshots are archived in its versions/ subdirectory.
# Default: generate and humanize each new chapter.
novel write my-new-novel --volume 1 --start 1

# Disable humanization and keep the raw draft.
novel write my-new-novel --volume 1 --start 1 --no-humanize

# Humanize existing chapter files.
novel write my-new-novel --volume 1 --start 1 --max 3 --humanize-existing

Optional: Mechanics Layer

If the new novel is a system novel, game novel, lord-management novel, infinite-flow novel, or needs stable tracking for realms, resources, skills, tasks, or relationship state, initialize the optional mechanics layer.

Non-system novels can disable it; later workflow stages will ignore it automatically.

# Automatically decide whether mechanics are needed: none / light_state / explicit_mechanics
novel mechanics-init my-new-novel

# Specify mechanics with a short direction
novel mechanics-init my-new-novel --direction "vampire devouring progression system with exp, blood purity, and skill tree"

# Read mechanics settings from a file. This has higher priority than --direction.
novel mechanics-init my-new-novel --file /path/to/mechanics.md

# Explicitly disable the mechanics layer
novel mechanics-init my-new-novel --none --force

Outputs:

  • file_system/mechanics/profile.json: enabled state, mode, visible panel, precision
  • file_system/mechanics/design.md: mechanics design notes
  • file_system/mechanics/rules.json: computable events, display rules, constraints the model must not alter
  • file_system/mechanics/state.json: initial state

Modes:

  • none: Mechanics disabled. No system panel.
  • light_state: No visible panel; internally tracks realms, resources, relationships, injuries, clue state, etc.
  • explicit_mechanics: Visible system/panel/exp/tasks/points/skill tree. Chapter outlines output mechanics event drafts; exact values should be calculated by later program logic.

story-arcs, chapter-outlines, and write automatically read file_system/mechanics/. If mechanics are disabled, they receive a disabled notice and should not force a system panel into the novel.

Optional: Target-world Knowledge Base

If the new novel needs to move into a target world that requires supporting materials, import and build the knowledge base before design-concept (the Web/stepwise path) or novel-outline (the bundled CLI path). Without a knowledge base, the workflow uses the available reference material and inspiration input; a reference novel is optional.

# Import one file, multiple files, or a material directory.
novel world-import my-new-novel /path/to/main-source.txt
novel world-import my-new-novel /path/to/supplement-source.txt

# Structure the target-world knowledge base. --primary specifies the main source.
novel world-build my-new-novel --primary main-source.txt

# Then generate the new design as usual; the knowledge base is loaded automatically.
novel design-concept my-new-novel --direction "inspiration input"
novel stage-design my-new-novel

world-build writes seven English section files under file_system/world_knowledge/worlds/_final/ (worldview.md, power_system.md, key_characters.md, factions.md, story_spine.md, key_items.md, skills_and_techniques.md). Existing Chinese filenames in that folder are still read.

Chat-based world building

On the Web workbench Target world step, chat can create and refine those same seven section files without a source import. An empty world starts as an interview: the model asks follow-up questions, writes sections once there is enough to record, and lists what is still missing. You can also chat against a world that was built from sources.

Optional extra rules live in file_system/world_knowledge/chat_guide.md. The file is appended after the built-in prompts and wins on conflict. Upload a .md or .txt guide from the chat panel, or reset the control to delete the file.

Source import and chat can be used together. If chat has edited the world, a later import or rebuild replaces those edits after copying _final to file_system/world_knowledge/worlds/_final_backup_<timestamp>. The Web UI asks for confirmation before that rebuild; cancel sends nothing.

Notes

  • Reference novels currently support .txt format. Common Chinese encodings are detected and converted to UTF-8 on import.

Offline Quality Report

Inspect the quality diagnostics and provenance sidecars already saved in a workspace without calling a model or changing files:

novel quality-report my-new-novel
novel quality-report my-new-novel --json

The report counts current, stale, and legacy-or-invalid provenance sidecars, and flags artifacts whose saved content hash no longer matches their file. It also groups valid and invalid diagnostics, decisions, errors, warnings, stages, and operations. Malformed JSON is counted and skipped safely. The Web workspace summary returns the identical read-only object as quality_report.

These diagnostics are deterministic workflow signals, not a literary-quality certification. The report cannot reconstruct dependency drift when a sidecar has no corresponding dependency source available locally.

Command Reference

Command Description
novel config Initialize the global config file
novel web [--host HOST] [--port PORT] [--workspace-root PATH] Start the local visual workbench
novel list List all workspaces
novel init <ws> --txt <path> [--batch-size N] [--max-chapters N] [--no-analyze] Create a workspace, normalize the source, and run the three-stage deconstruction; --no-analyze imports only
novel reference-resume <ws> [--batch-size N] [--max-chapters N] Resume or retry reference deconstruction
novel world-import <ws> <paths...> [--force] Import target-genre material files or directories
novel world-build <ws> [--force] [--merge-only] [--primary NAME] [--chapter-batch-size N] [--chunk-size N] [--max-workers N] Structure target-genre materials into a sectioned knowledge base
novel novel-outline <ws> [--force] [--direction TEXT] [--direction-file PATH] Bundled CLI path: generate core gameplay, long mainline, stage roadmap, character arcs, title, and synopsis
novel story-design <ws> [--force] [--direction TEXT] [--direction-file PATH] Generate core gameplay, long mainline, stage roadmap, and character arcs
novel design-concept <ws> [--force] [--direction TEXT] [--direction-file PATH] Stepwise book design: generate worldview, rough outline, and phase outline
novel stage-design <ws> [--force] [--direction TEXT] [--direction-file PATH] Stepwise stage design: generate the long mainline and stage roadmap from the book-design artifacts
novel story-design-extend <ws> [--use-reference] [--direction TEXT] [--direction-file PATH] Preserve existing design and append the mainline, character arcs, and later stages
novel stage-insert <ws> [--direction TEXT] [--direction-file PATH] [--after-stage N] [--before-stage N] Design a new stage from inspiration and insert it into the stage roadmap
novel mechanics-init <ws> [--file PATH] [--direction TEXT] [--none] [--force] Initialize or disable the optional mechanics layer
novel volume-outline <ws> [--volume N] [--force] Legacy flow: generate volume outline, per-volume worldview, and per-volume stage plan
novel story-arcs <ws> [--volume N] [--force] Generate story arcs and narrative patterns for a volume/stage
novel chapter-outlines <ws> [--volume N] [--force] Generate chapter outlines from story arcs
novel write <ws> [--volume N] [--start N] [--max N] [--no-humanize] [--humanize-existing] Generate full text serially and humanize each new chapter by default
novel quality-report <ws> [--json] Inspect saved provenance and deterministic quality diagnostics without generation

Parameters

  • --txt <path>: Reference novel file path. Used only by init.
  • --batch-size N: Chapters per reading window for story-arc detection. Default: 20. Used only by init.
  • --direction TEXT: Creative direction, for example "change to a modern urban setting". It is accepted by novel-outline, story-design, design-concept, stage-design, story-design-extend, and stage-insert; its effect is scoped to that command's design stage.
  • --direction-file PATH: Read creative direction from a file. It is accepted by novel-outline, story-design, design-concept, stage-design, story-design-extend, and stage-insert.
  • --use-reference: With story-design-extend, use only reference story arcs added since the last full-book design. Without it, extend from existing new-book design assets only.
  • --file PATH: Mechanics settings file path. Used by mechanics-init.
  • --none: Explicitly disable the mechanics layer. Used by mechanics-init.
  • --chapter-batch-size N: Number of chapters per batch for chapter-like materials. Default: 20. Falls back to character chunks when chapters cannot be detected. Used only by world-build.
  • --chunk-size N: Target-world material chunk size in characters. Default: 36000. Used only by world-build; chapter sources are also capped at 20 chapters per batch.
  • --max-workers N: Parallel extraction workers for target-world chapter batches. Default: 4; aggregation starts after all batches finish.
  • --primary NAME: Specify the main source for world-build. Accepts file name, path, or material ID. If omitted, the largest file is used by default.
  • --merge-only: Rebuild only worlds/_final/*.md and audits from existing worlds/<source>/*.md; does not re-extract cards.
  • world-build reuses checkpoints for extracted cards, the canon index, per-source aggregation, and final integration by default. Only explicit --force rebuilds from scratch.
  • --volume N: Volume number. Default: 1. In the new flow, one volume corresponds to one stage in stage_roadmap.md.
  • --stage N: Backward-compatible alias for --volume; it does not mean a stage inside a volume. Used by story-arcs, chapter-outlines, and write.
  • --after-stage N / --before-stage N: Relative insertion position for a new stage. Used only by stage-insert.
  • --start N: Starting chapter number. Default: 1. Used only by write.
  • --max N: Maximum number of chapters to generate. Used only by write.
  • --no-humanize: Disable automatic humanization after chapter generation. Used only by write.
  • --humanize-existing: Humanize existing chapter files. By default, only newly generated chapters are humanized. Used only by write.
  • --json: Emit the offline quality report as JSON. Used only by quality-report.
  • --force: Force regeneration and overwrite existing content.

About the Author

Fei Niao one the way — Explorer

QR code

Star History

Star History Chart

License

GPL-3.0

About

长篇网络小说自动化写作 AI Agent,支持Chatgpt、gemini、Deepseek等国内外模型接入,采用拆书 + 仿写的模式,从新世界观、大纲、卷纲设计,到章节片段完善&章纲设计,有效解决 AI 写作中的「前后矛盾」、「容易遗忘」、「缺乏特色」和「AI味重」等问题,支持 百万字量级 连载创作。

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages