ai-novel-studio README

The project's README from github.com/weike-zhang/ai-novel-studio. As one markdown file: README.md.

AI Novel Studio · AI 小说创作台

An AI novel generation platform with world building, interactive choices, and persistent character state.

简体中文 · Architecture · Run the web app

AI Novel Studio is an AI interactive fiction application built with Next.js and Go. Create a world, start a private journey, and choose what happens next. The server checks a model's proposed changes before committing them to the story.

For developers building narrative games or stateful AI applications, the useful part is the boundary between generated prose and stored facts: a model can propose an action, but it cannot rename an established character through a state patch.

See a valid turn commit and an invalid change fail

With Go 1.26 or newer, from the repository root:

cd services/server
go run ./cmd/demo

The demo uses the actual story engine with an in-memory repository and a deterministic fake provider. It needs no API key, database or Docker. Go may download module metadata on first use.

It commits a harbor scene, attempts to change a character's name, then checks that the rejected proposal leaves the committed version intact. This demonstrates validation behavior; it does not measure a real model's storytelling quality.

What is included

Part What you can inspect
Web application World discovery, authoring, private journeys, account flows and task progress
Story engine Frozen world snapshots, committed context, character and scene validation
Go API and worker Queued generation, model proposals, validation and transactional persistence
Data and contracts MySQL migrations, synthetic development data and an OpenAPI client
Model integration OpenAI-compatible requests, configurable endpoints and fallback handling

The public edition includes synthetic development content. It excludes the hosted site's catalog, original cover artwork, user data and production configuration. Payment-related code does not establish a live payment integration.

How a turn reaches the story

flowchart LR
  A[Player action] --> B[API and task reservation]
  B --> C[Outbox and RabbitMQ]
  C --> D[Go worker]
  S[Frozen world and committed state] --> D
  D --> E[Model proposal]
  E --> V[Validation]
  V --> T[MySQL transaction]
  T --> U[Web task progress]

The architecture guide connects each decision to its implementation and tests. The standalone demo uses an in-memory commit path; the full application uses the worker and database path.

Development

Node.js 22+ is required for the web application. From the repository root:

npm ci
npm run build:api-client
npm run test:web
npm run test:api-client
npm run tokens:check

For the Go packages:

cd services/server
go test ./...

Database, Redis, RabbitMQ and live-model integration tests require their explicit test environment variables. A default go test run does not prove those integrations work. Read development setup and the verification record before starting the full application.

Contribute

Useful contributions include a reproducible continuity failure, a focused validator regression test, or a clearer first-run instruction. Include the action, expected state and actual result; use synthetic data and remove credentials. See contributing and security reporting.

If you use these patterns in a story project, a star helps other developers find the implementation.

License

MIT. Dependency licenses remain applicable; see third-party notices.

ai-novel-studio (weike-zhang/ai-novel-studio)

Searching Database…

234 ·GitHub
Ai-novel-studio
What is this?AI Novel Studio is an AI-powered interactive fiction platform built with Next.js and Go, where you build a world, start a private journey, and choose what happens next while the server validates every AI-proposed change before it's saved.
Is this a ready-to-use app or a framework for building my own?It's a complete web application — a Next.js frontend plus a Go API and worker — not a library, and it ships with a standalone demo you can run without wiring up any external services yourself.
How do I try it out?Run the bundled demo from the repository root with Go 1.26+; it needs no API key, database, or Docker and commits a scene then shows an invalid character-rename proposal get rejected. Running the full web app additionally requires Node.js 22+ for the Next.js frontend.
What do I need to run the full application, not just the demo?Beyond Node.js 22+ for the frontend, the full app needs MySQL, Redis, and RabbitMQ, and the related tests require their own explicit test environment variables; live-model integration needs its own credentials too.
Does the demo prove the AI actually writes good stories?No — it only demonstrates that invalid state changes, like renaming an already-established character, get rejected while valid turns commit normally; it doesn't measure a real model's storytelling quality.
Who is this built for?It's aimed at developers building narrative games or stateful AI applications who want a working example of keeping generated prose separate from validated, persisted story facts.
How does it keep characters consistent across a story?The server checks every model-proposed change against the already-committed world state before persisting it, so a proposal that tries to rename or alter an established character fails while the committed version stays intact.
Does the public repo include real payments or the hosted site's content?No — the public edition ships only synthetic development data and excludes the hosted site's real catalog, cover artwork, user data, production config, and any working payment integration.
What does each half of the stack actually do?Next.js handles world discovery, authoring, private journeys, and accounts, while Go runs the API and worker that queue generation, validate model proposals, and persist committed turns transactionally to MySQL.
Can I use any LLM provider with it?Model integration goes through OpenAI-compatible requests with configurable endpoints and fallback handling, so you can point it at any compatible provider rather than a single hardcoded one.
What are similar projects?gin-vue-admin, sealos, bisibility, dataease, oxynote, artcraft-services, Chat2DB, ai-native-callcenter
Which topics is it in?openapi, mysql, redis, sql, openai-compatible, nextjs, golang, backend, database, web-app, go, frontend
Creator
weike-zhang
Size
0.4 MB
Stars
234
Updated
CommitOct 03
Age
15d
Commits · 90 Days