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.
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.
pip install harnessNovelUpdate:
pip install --upgrade harnessNovelThe 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 webThe 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-novelsScreenshots depict an older workbench UI; they are kept as historical images and have not been reshot.
![]() |
![]() |
![]() |
![]() |
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.
- Optional deconstruction stage: Choose a high-quality novel and deconstruct it into structured knowledge when you want a structural reference.
- Story-design stage: Input your core inspiration and any deconstruction results, then let AI create an original plan.
- Iterative refinement: Adjust core gameplay, stages, character lines, mechanics, and chapter content at any time to gradually improve the work.
- 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.
- Python 3.10+
- LLM API: must support an OpenAI-compatible interface, such as DeepSeek, Zhipu GLM, Kimi, etc.
pip install harnessNovelUpdate:
pip install --upgrade harnessNovelAfter installation, the novel command is globally available.
novel configThis 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.
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.
# 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 1The 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.
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-arcsreads the current volume/stage and compresses it into a reusablearc_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.
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 itsversions/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-existingIf 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 --forceOutputs:
file_system/mechanics/profile.json: enabled state, mode, visible panel, precisionfile_system/mechanics/design.md: mechanics design notesfile_system/mechanics/rules.json: computable events, display rules, constraints the model must not alterfile_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.
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-novelworld-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.
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.
- Reference novels currently support
.txtformat. Common Chinese encodings are detected and converted to UTF-8 on import.
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 --jsonThe 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 | 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 |
--txt <path>: Reference novel file path. Used only byinit.--batch-size N: Chapters per reading window for story-arc detection. Default: 20. Used only byinit.--direction TEXT: Creative direction, for example "change to a modern urban setting". It is accepted bynovel-outline,story-design,design-concept,stage-design,story-design-extend, andstage-insert; its effect is scoped to that command's design stage.--direction-file PATH: Read creative direction from a file. It is accepted bynovel-outline,story-design,design-concept,stage-design,story-design-extend, andstage-insert.--use-reference: Withstory-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 bymechanics-init.--none: Explicitly disable the mechanics layer. Used bymechanics-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 byworld-build.--chunk-size N: Target-world material chunk size in characters. Default: 36000. Used only byworld-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 forworld-build. Accepts file name, path, or material ID. If omitted, the largest file is used by default.--merge-only: Rebuild onlyworlds/_final/*.mdand audits from existingworlds/<source>/*.md; does not re-extract cards.world-buildreuses checkpoints for extracted cards, the canon index, per-source aggregation, and final integration by default. Only explicit--forcerebuilds from scratch.--volume N: Volume number. Default: 1. In the new flow, one volume corresponds to one stage instage_roadmap.md.--stage N: Backward-compatible alias for--volume; it does not mean a stage inside a volume. Used bystory-arcs,chapter-outlines, andwrite.--after-stage N/--before-stage N: Relative insertion position for a new stage. Used only bystage-insert.--start N: Starting chapter number. Default: 1. Used only bywrite.--max N: Maximum number of chapters to generate. Used only bywrite.--no-humanize: Disable automatic humanization after chapter generation. Used only bywrite.--humanize-existing: Humanize existing chapter files. By default, only newly generated chapters are humanized. Used only bywrite.--json: Emit the offline quality report as JSON. Used only byquality-report.--force: Force regeneration and overwrite existing content.
Fei Niao one the way — Explorer





