Long Novel Agent Kit

Local continuity infrastructure for writing long novels with desktop agents.

Long Novel Agent Kit does not replace the model, the writing agent, or the author's judgment. It gives local desktop agents a durable project memory and a set of safety gates so a long novel can survive long context windows, agent handoffs, source material updates, and multi-chapter continuity drift.

中文说明 · 中文整体架构与功能说明

The Short Version

Use the desktop agent for intelligence. Use this kit for continuity.

• The desktop agent reads PDFs, old drafts, notes, web pages, images, and long files with its native tools.
• The agent writes confirmed summaries, facts, research notes, and decisions into .novel-agent/.
• Before drafting, the agent calls prepare-session or build-context instead of relying on chat history.
• Before delivery, the agent calls continuity checks and delivery helpers.
• After the author accepts a chapter, writer tools record the chapter and update durable state with author confirmation.
• Another local agent can later read the same .novel-agent/ state and continue the book.

Architecture At A Glance

flowchart TD
  Author["Author"]
  Agent["Local desktop agent<br/>Codex, Cursor, Claude Desktop, etc."]
  Native["Agent native abilities<br/>model, long context, file parsing, web, PDF/OCR, retrieval"]
  Skill["SKILL.md<br/>workflow instructions"]
  MCP["server.py<br/>stdio MCP tools"]
  CLI["cli.py<br/>local commands"]
  State[".novel-agent/<br/>durable novel state"]
  Pack["desktop-pack<br/>local HTML/JSON/command packet"]
  Runtime["standalone runtime<br/>no-Python CLI and MCP executables"]

  Author --> Agent
  Agent --> Native
  Agent --> Skill
  Agent --> MCP
  Agent --> CLI
  MCP --> State
  CLI --> State
  State --> MCP
  State --> CLI
  CLI --> Pack
  CLI --> Runtime
  Pack --> Agent
  Runtime --> Agent

Component Responsibilities

Component	What it does	What it does not do
Desktop agent	Reads sources, reasons about prose, drafts and revises chapters, uses its own search/parsing/model tools	It is not trusted as durable memory by itself
SKILL.md	Tells an agent the required writing protocol and when to call the tools	It does not store state or execute commands
server.py	Exposes the kit through local stdio MCP, with read-only and writer modes	It is not a remote server and does not require cloud hosting
cli.py	Provides local commands for setup, context, checks, packs, handoff, and writer operations	It does not call an LLM
.novel-agent/	Stores accepted continuity, sources, facts, chapters, proposals, audit rows, and snapshots	It is not a manuscript editor
desktop-pack	Creates a local packet with HTML pages, JSON state, schemas, commands, evidence templates, and handoff files	It does not prove the GUI desktop client has loaded MCP
standalone-build / desktop-handoff-bundle	Builds and packages no-Python local runtimes for another computer	It cannot cross-build every operating system reliably

Core State Model

Every novel project keeps long-term continuity in .novel-agent/.

File	Purpose
manifest.json	Project identity, schema version, current chapter metadata
rules.json	Required phrases, forbidden phrases, future markers, naming constraints
chapters.jsonl	Accepted chapter records, summaries, tails, handoff notes
facts.jsonl	Structured facts for continuity checks, such as ownership, location, status, relationships, timeline
sources.jsonl	Source summaries confirmed from old drafts, PDFs, notes, or other local materials
research.jsonl	Research notes and reliability notes from external lookup
conflicts.jsonl	Resolved contradictions and the chosen version
characters.json	Character state, arcs, relationships, and constraints
debts.json	Foreshadowing, promises, unresolved plot debt
contracts.jsonl	Chapter goals, required beats, forbidden moves, acceptance checks
proposals.jsonl	Proposed post-write updates awaiting review or application
agent_activity.jsonl	Local agent activity and handoff logs
desktop_verifications.jsonl	Real desktop client evidence records
audit.jsonl	Durable write audit trail
snapshots/	Rollback snapshots created before risky state changes

Capability Map

Problem	Main commands / tools	Result
Start a new novel state	init, quickstart	Creates .novel-agent/ and baseline files
Import an existing Gaoxia-style project	import-gaoxia, quickstart --source auto, import-audit	Converts chapters, Vault notes, memory, and narrative state into local continuity state
Save source summaries from the host agent	source-intake, add-source, add-research, resolve-conflict, add-fact	Turns parsed material into durable evidence and rules
Prepare a chapter	prepare-session, build-context, context-brief	Returns chapter-safe context, visible facts, rules, handoff, budget, and fingerprints
Check a draft	check-chapter, chapter-readiness, diff-contract	Finds rule violations, missing beats, fact conflicts, future leaks, and state conflicts
Help revision	chapter-revision-prompt, chapter-revision-compare	Produces targeted repair instructions and before/after issue comparison
Deliver to author	chapter-delivery, chapter-range-delivery	Bundles readiness, known issues, handoff state, and post-acceptance commands
Update long-term state after acceptance	record-chapter, proposal-template, propose-after-write, proposal-readiness, apply-after-write	Records accepted chapter and applies reviewed continuity updates
Prevent stale or wrong-project writes	write-session-check, expected project/state/context hashes	Blocks writer commands when the state has changed since context generation
Hand off to another local agent	handoff-report, handoff-readiness, handoff-integrity, agent-activity-report	Gives the next agent enough durable context to continue safely
Give a normal user a local packet	desktop-pack, pack-doctor, pack-schema-check, desktop-pack-readiness	Creates and validates a browser-readable and agent-readable local packet
Prove a real desktop client can use the kit	desktop-checklist, ingest-desktop-evidence, desktop-results-doctor, record-desktop-check, desktop-matrix	Separates local config checks from real GUI client evidence
Move to another computer without Python	standalone-build, desktop-handoff-bundle	Creates runtime executables plus a copyable project/pack/runtime bundle
Recover or audit state	snapshot, restore-snapshot, export-state, import-state, doctor, continuity-audit	Supports rollback, migration, and project health checks

The Main Writing Flow

sequenceDiagram
  participant A as Desktop Agent
  participant K as Long Novel Agent Kit
  participant S as .novel-agent
  participant U as Author

  A->>K: source-intake / add-source / add-research
  K->>S: store confirmed evidence
  A->>K: prepare-session chapter N
  K->>S: read facts, rules, sources, chapters, debts
  K-->>A: chapter-safe context and fingerprints
  A->>A: draft chapter with native model
  A->>K: check-chapter / chapter-readiness
  K-->>A: continuity and contract issues
  A->>U: deliver draft and known issues
  U-->>A: accept or request revision
  A->>K: record-chapter with author confirmation
  A->>K: propose-after-write / proposal-readiness
  K->>S: write audited accepted state when allowed

The important rule: generate context from durable state before writing. Do not treat chat history as the source of truth.

Read-Only Mode And Writer Mode

Read-only MCP is the default and recommended mode:

python server.py --read-only --tool-profile core

Read-only mode can prepare context, check drafts, build reports, inspect packs, and explain next steps. It cannot change .novel-agent/.

Writer mode can change durable state, so it is gated:

• The author must confirm the write.
• write-session-check compares project identity, state fingerprint, and chapter context fingerprint.
• Proposal readiness checks evidence, conflicts, and risk.
• .write.lock prevents concurrent writes.
• Snapshots are created before applied proposal updates.
• Every durable write appends to audit.jsonl.

Desktop Packs

desktop-pack is the bridge between the kit and ordinary local desktop-agent usage.

It writes a local directory containing:

• first-three.html, local-summary.html, and user-steps.html for a normal user
• pack-index.json, commands.json, commands-index.json, and schemas for an agent
• chapter-session.json, handoff-report.json, project status, continuity audit, and author review queue
• setup, install, upgrade, uninstall, local check, and archive scripts for macOS, Windows, and POSIX shells
• evidence templates and result JSON schemas for proving real GUI client behavior
• acceptance review and writer-mode authorization packets

The pack is a local guide and snapshot. If it is copied or moved, run pack-doctor, pack-freshness, or rebind-pack-kit before trusting old paths.

No-Python Handoff

For non-technical users on another computer, build a same-OS standalone runtime first:

python cli.py standalone-build \
  --output-dir release/long-novel-agent-runtime-macos-arm64 \
  --target-os macos \
  --apply \
  --force \
  --format json

Then create a handoff bundle:

release/long-novel-agent-runtime-macos-arm64/long-novel-agent desktop-handoff-bundle ./my-novel \
  --platform codex \
  --mode read-only \
  --chapter 1 \
  --runtime-dir release/long-novel-agent-runtime-macos-arm64 \
  --output-dir release/my-novel-agent-bundle \
  --archive \
  --force \
  --format json

The bundle contains project/, pack/, runtime/, launchers, MCP snippets, runtime command files, and agent-read-me-first.md. When both runtime executables are present, the target computer does not need Python.

For a Windows .exe release, build on Windows and follow Windows Runtime Release. The GitHub Actions template is stored at docs/github-actions-windows-release.yml; copy it into .github/workflows/ only when the GitHub token used for the push has workflow scope.

Quick Start From Source

git clone https://github.com/mushroomfk/long-novel-agent-kit.git
cd long-novel-agent-kit
python cli.py doctor
python cli.py init ./my-novel --title "My Novel"
python cli.py prepare-session ./my-novel --chapter 1 --platform codex --mode read-only --format markdown

Check a draft:

python cli.py check-chapter ./my-novel --chapter 1 --file chapters/001.md --format markdown

Generate a desktop setup guide:

python cli.py desktop-setup ./my-novel --platform codex --mode read-only --format markdown

What This Kit Does Not Do

• It does not run an LLM.
• It does not include embedding search.
• It does not parse PDF/OCR/web pages by itself.
• It does not upload manuscripts.
• It does not require a server for local desktop use.
• It does not replace literary judgment, editing taste, or author approval.

Those jobs belong to the host desktop agent and the author. This kit persists and verifies the continuity layer.

Repository Layout

.
├── cli.py                         # local CLI
├── server.py                      # stdio MCP server
├── install.py                     # local skill and MCP installer
├── SKILL.md                       # agent workflow instructions
├── schemas/                       # JSON schemas for proposals and desktop packs
├── assets/review-panel.html       # local static proposal review panel
├── examples/                      # smoke, handoff, evidence, and adversarial examples
├── docs/                          # architecture, install, workflow, and release docs
├── scripts/verify_agent_kit.py    # full regression check
└── scripts/adversarial_release_check.py

Verification

Run the full regression suite:

python scripts/verify_agent_kit.py

Run the stronger release gate:

python scripts/adversarial_release_check.py

An optional GitHub Actions workflow template is available at docs/github-actions-verify.yml. Repository maintainers with workflow scope can copy it to .github/workflows/verify.yml.

Requirements

• Python 3.10 or newer for source-based CLI/MCP usage.
• A local desktop agent that can start stdio MCP or run shell commands.
• Optional: PyInstaller when building no-Python runtime bundles.

Supported Local Agent Paths

• CLI-only agents can run python cli.py ....
• MCP-capable agents can start python server.py --read-only.
• Codex and Cursor local config paths can be generated automatically by install.py.
• Claude Desktop and generic JSON MCP clients can use explicit config snippets.

Remote connector-only platforms are outside this local stdio MCP flow.

License

MIT. See LICENSE.