woke_novel

KO | EN

gitlite — search

#python #java #python3 #arduino #golang #machine-learning #rust #html #flask #javascript #seismology #nodejs

★ 15 Open GitHub ↗

Fully Automated Novel Generation Tool, Making Claude Your "English Web Novel Auto-Wenerator";全自动小说生成工具，让 Claude 成为你的「中文网文自动生成工具」流水线 · 多幕 · 断点续写 · 强约束模板驱动;

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# woke_novel

[English](README.md) | [简体中文](README_zh-CN.md)

Author-led long-form novel co-creation workflow for Claude CLI or Codex CLI.

```
██╗    ██╗ ██████╗ ██╗  ██╗███████╗    ███╗   ██╗ ██████╗ ██╗   ██╗███████╗██╗
██║    ██║██╔═══██╗██║ ██╔╝██╔════╝    ████╗  ██║██╔═══██╗██║   ██║██╔════╝██║
██║ █╗ ██║██║   ██║█████╔╝ █████╗      ██╔██╗ ██║██║   ██║██║   ██║█████╗  ██║
██║███╗██║██║   ██║██╔═██╗ ██╔══╝      ██║╚██╗██║██║   ██║╚██╗ ██╔╝██╔══╝  ██║
╚███╔███╔╝╚██████╔╝██║  ██╗███████╗    ██║ ╚████║╚██████╔╝ ╚████╔╝ ███████╗███████╗
╚══╝╚══╝  ╚═════╝ ╚═╝  ╚═╝╚══════╝    ╚═╝  ╚═══╝ ╚═════╝   ╚═══╝  ╚══════╝╚══════╝
```

**Lock the experience you want, then let Claude / Codex implement it**

*Pipeline · Multi-Act · Resume from Breakpoint · Strict Template-Driven*

`woke_novel` turns an external model CLI into an author-led Chinese web-novel writing pipeline. Before generation, a one-question-at-a-time interview locks the author's original intent, primary reader desire, mandatory payoffs, forbidden reframings, protagonist dignity, recurring story activity, conflict direction, and ending payoff into `作者叙事契约.json`. Claude or Codex then creates each artifact under that contract.

The workflow is designed for resumable, template-driven generation of a roughly 30-chapter Chinese web novel, from idea selection through worldbuilding, characters, story arc, chapter drafts, state tracking, and act summaries.

## Features

- **Claude CLI and Codex CLI support**: choose either backend from the interactive menu or pass `--provider claude/codex` on the command line.
- **Template-driven pipeline**: 20 workflow templates plus shared writing rules under `steps/`.
- **Pre-generation author contract**: no creative step runs until all reader-desire decisions are explicitly locked.
- **Anti-betrayal derivation**: planning layers must amplify the chosen payoff, preserve protagonist dignity, make the core premise indispensable, and culminate in maximum payoff.
- **Resumable execution**: progress is stored in `projects/<name>/.project_info.json`; `continue` resumes from the recorded cursor.
- **Multi-session orchestration**: workflow phases are split into separate CLI sessions to keep context boundaries manageable.
- **Dry-run mode**: use `--dry` to verify pipeline wiring without calling an external model CLI.
- **Project-local artifacts**: generated files are organized under `00_baseline`, `01_plots`, `02_guides`, `02_output`, `03_state`, and `04_characters`.

## Requirements

- Python 3.10+
- At least one supported model CLI installed and authenticated:
  - `claude` / `claude.cmd`
  - `codex` / `codex.cmd`
- Git, optional but recommended

Install Python dependencies:

```bash
pip install -r requirements.txt
```

Current Python dependencies are:

- `colorama`
- `rich`

## Quick Start

Clone the repository:

```bash
git clone https://github.com/keyboardgdy/woke_novel.git
cd woke_novel
```

Verify your model CLI:

```bash
claude --version
codex --version
```

Start the interactive menu:

```bash
python menu.py
```

Platform launchers are also included:

```bash
menu.bat       # Windows
./menu.sh      # Linux / macOS
./menu.command # macOS
```

The first run asks you to choose a backend, then guides you through genre selection, project naming, the author's raw premise, the one-question-at-a-time desire interview, explicit idea selection, and full workflow execution.

## Command Line Usage

```bash
python run_workflow.py <command> [args]
```

Available commands:

| Command | Purpose | Common arguments |
| --- | --- | --- |
| `init` | Create a project interactively | `--genre`, `--novel-size` |
| `loop` | Run the full workflow | `--project-name`, `--genre`, `--provider`, `--option-count`, `--dry` |
| `continue` | Resume from `.project_info.json` | `--project-name`, `--provider`, `--dry` |
| `single <step>` | Run one workflow step | `-p`, `-g`, `--provider`, `--max-retries`, `--dry` |
| `session <block> <steps>` | Run a group of steps in one session | `-p`, `-g`, `--provider`, `--dry` |

Examples:

```bash
# Dry-run a single step after editing its template
python run_workflow.py single 11 -p my_novel -g fantasy --dry

# Run one step for real
python run_workflow.py single 11 -p my_novel -g fantasy

# Use Codex CLI as the backend
python run_workflow.py single 11 -p my_novel -g fantasy --provider codex

# Run the full workflow
python run_workflow.py loop --project-name my_novel --genre fantasy --option-count 3

# Continue after interruption
python run_workflow.py continue --project-name my_novel
```

## Backend Behavior

Each workflow step sends a resolved prompt to the selected external CLI process and expects the model to write artifacts into the project directory.

Current backend invocation behavior:

| Backend | Invocation mode |
| --- | --- |
| Claude CLI | Uses `--permission-mode bypassPermissions` |
| Codex CLI | Uses `--dangerously-bypass-approvals-and-sandbox` |

Use this project only inside a local workspace you trust. If you want a more conservative Codex setup, adjust the Codex arguments in `workflow_runner.py` to use a workspace sandbox policy that fits your environment.

## Workflow Overview

The full workflow is organized into these major phases:

| Phase | Steps | Main outputs |
| --- | --- | --- |
| Author contract | Before `01` | Locked reader-desire contract; generation remains blocked while incomplete |
| Idea development | `01` x N, explicit selection, `02` | Creative seeds, one developed premise, selected-seed fingerprint |
| World and characters | `03`, `04` | Worldbuilding document, character JSON files, relationship matrix |
| Core story model | `04a` | Goal, opposition, stakes, story engine, escalation, causal nodes, ending choice |
| Main arc | `05`, `05a`, `05b`, `05c`, `18` | Causal story arc, act mapping, concrete act skeletons, cross-layer integration, project-level context |
| Opening | `06` to `10` | Opening contract, causal scene plan, prose implementation guide, prose draft, state document |
| Chapter loop | `11` to `16` | Chapter alignment contract, causal scene plan, prose implementation guide, prose, state, compact summary |
| Act ending | `17`, `18` | Act summary and refreshed project context |
| Final revision | `19` orchestrating `19a`–`19e` | Eight-chapter batches for diagnosis, structural rewrite, prose polish, and final acceptance |

The runner extracts act counts and chapter counts from generated framework files, then loops through the remaining chapters accordingly. For the first act, the opening chapter is created before the normal chapter loop. After the final act, logical step 19 backs up all chapter files and processes them in resumable eight-chapter batches. Each batch reads its immediate neighbors as context, while compact batch reports support the global plan and final acceptance.

## Project Layout

```text
woke_novel/
├── cli.py
├── menu.py
├── run_workflow.py
├── ui.py
├── workflow_runner.py
├── path_resolver.py
├── project_info.py
├── project_structure.py
├── steps/
├── docs/
├── logs/
└── projects/
    └── <novel_name>/
        ├── .project_info.json
        ├── 00_baseline/     # author contract, planning, and legacy planning history
        ├── 01_plots/
        ├── 02_guides/
        ├── 02_output/       # chapter files and the pre-step-19 backup
        ├── 03_state/        # state, cumulative summary, project context, final-revision report
        └── 04_characters/
```

Main modules:

| File | Responsibility |
| --- | --- |
| `menu.py` | Interactive menu entry point |
| `run_workflow.py` | Command-line workflow orchestration |
| `workflow_runner.py` | Step execution, retries, provider calls, session handling |
| `path_resolver.py` | Template path resolution and variable substitution |
| `project_info.py` | `.project_info.json` persistence and resume metadata |
| `project_structure.py` | Standard project directory creation |
| `steps/*.md` | Hard-constrained workflow prompts |

## Template Variables

`PathResolver.resolve()` replaces variables used in the Markdown templates. Common variables include:

| Category | Variables |
| --- | --- |
| Directories | `{project}`, `{baseline}`, `{plots}`, `{guides}`, `{output}`, `{state}`, `{chars}`, `{steps}` |
| Files | `{world}`, `{skeleton}`, `{axis}`, `{macro}`, `{constitution}`, `{evolution}` |
| Context | `{genre}`, `{project_name}`, `{round}`, `{round-1}`, `{option_index}`, `{user_description}`, `{ref_works}`, `{act_num}`, `{act_skeleton}`, `{prev_act_skeleton}`, `{current_unit}` |

Avoid hard-coding absolute paths in templates. When changing artifact paths, update both the template and the resolver mapping.

## Resume Metadata

Progress is stored in `projects/<name>/.project_info.json`. A typical file contains:

```json
{
  "novel_name": "<final title>",
  "genre": "fantasy",
  "last_step": "14",
  "current_round": 7,
  "selected_option": 2,
  "ref_works": ["Reference A", "Reference B"],
  "act_count": 3,
  "chapter_counts": [12, 10, 8],
  "total_chapters": 30
}
```

Use `continue` after `Ctrl+C`, a failed CLI call, or a machine restart.

## Development Notes

- Use `--dry` before running expensive model calls.
- After editing a step template, validate it with `single <step> --dry`.
- If you add a workflow step, update the step maps in `workflow_runner.py` and the orchestration logic in `run_workflow.py`.
- Step 18 writes `projects/<name>/03_state/项目上下文.md`, a normal artifact read only when a template names it. Novel projects do not generate an auto-loaded `CLAUDE.md`.

## License

MIT. See `LICENSE`.

woke_novel

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README