tianming-novel-ai-writer: Stateful AI Novel Writing with 15-Dimension Tracking

Why Context Windows Break at Novel Scale

A common failure pattern in AI novel writing is that the model remembers a character's name but forgets their ability set three hundred chapters later, or introduces a setting detail that contradicts something established fifty chapters earlier. Using a longer context window pushes the problem further but does not solve it: once the context fills, older content is truncated.

The README describes this problem as the fundamental difference from other AI writing tools. Tianming does not try to hold the whole novel in the context window. Instead, it maintains a structured state database of fact fields, writes those fields per chapter as the narrative changes them, and feeds only the relevant subset of that state into each chapter's generation prompt. The context window sees current state, not history.

The README states this directly: coherence at chapter 3001 comes from chapter 3000's state write-back, not from the model's memory. Each chapter's generation reads the latest field values, not a recollection of events.

The README documents six specific failure patterns that occur with context-window-based approaches. Characters drift in personality as their settings are diluted by new content. Foreshadowing planted early is never collected. Hard rules established in the world-building section get broken because they were not emphasized in the current prompt. Character positions become inconsistent because no location state is tracked. Errors get written into subsequent chapters before anyone notices. Design changes cannot be propagated because there is no concept of a package to repack.

Tianming addresses each of these with a specific mechanism: character rule fields for personality constraint, foreshadowing state tracking by tier, hard constraint fields for world-view rules, per-character location tracking, gate 3 consistency validation to catch errors before they land, and a repack step to refresh the AI-visible data after a design change.

The 15-Dimension Fact Snapshot and 12 Change Declarations

After each chapter is generated and passes the gates, the system extracts 12 types of change declarations from the AI output and writes them into a 15-dimension fact snapshot. The next chapter reads that snapshot directly.

The 12 change types cover: character state changes (realm or level, new abilities, lost abilities, psychological state, key events, relationship changes), conflict progress, new plot nodes, foreshadowing actions (plant or payoff), location state changes, faction state changes, time advancement, character movement, item transfers, secret reveals, oath and constraint changes, and deadline constraint changes.

The 15 snapshot dimensions track: character state (realm and abilities), character location (where each character currently is), character appearance (hair color, eye color, personality markers to prevent contradictory descriptions), conflict progress, foreshadowing state by tier, plot nodes archived by chapter, location state, faction state, timeline, item state, world-view hard constraints, location characteristics, secret knowledge lists, oath and constraint status, and deadline constraint status.

The key closed-loop property is stated plainly in the README: chapter N+1 reads the updated snapshot written by chapter N's changes. The connection is through data fields, not model memory.

Six Generation Gates

Every generated chapter must pass six checks before it is written to storage. The README documents each gate:

Gate 1, protocol parsing: the AI output must contain a specific ---CHANGES--- delimiter followed by a complete JSON change declaration block. Missing fields cause the chapter to be rejected immediately.

Gate 2, reference validation: every character, location, and faction ID referenced in the CHANGES block must exist in the design data. An unknown ID is a reject.

Gate 3, consistency validation: character state changes, conflict advancement, and foreshadowing actions must not contradict the existing fact snapshot. The README gives an example: if a character's rule says they fear fire, a chapter where that character charges into a fire pit fails gate 3.

Gate 4, unknown entity detection: if more than five unregistered entities appear in the body text, or more than three are unnamed extras with no CHANGES record, the chapter is rejected.

Gate 5, appearance consistency: character appearance descriptions in the body text must match the character's profile fields. Location descriptions must match the location's feature fields.

Gate 6, blueprint presence check: if the chapter blueprint specifies that certain characters, factions, or locations must appear in the body text, they must be present. Missing too many triggers a rejection. A character who appears only once receives a warning about insufficient narrative weight.

Installing and Running the System

The repository requires .NET 8.0 SDK and Windows 10 build 19041 or above. The README gives the start command:

git clone https://github.com/zy-zmc/tianming-novel-ai-writer.git
dotnet run --project Core/App/天命.csproj

On first run, the model management screen prompts for an AI API key. The README states compatibility with OpenAI, Anthropic, and Gemini compatible interfaces. The system does not include any built-in API key. API keys are stored and managed locally.

The module structure is: Core/ for the application entry and startup, Framework/ for theming, common controls, the user system, and system settings, Services/ for AI services, project data, and version tracking, Modules/ for the design, generation, validation, and AI assistant modules, and Storage/ for configuration, themes, and templates. Dependencies flow as Modules to Services to Framework, with Core at the top.

The README documents multi-key rotation to avoid rate limiting and three generation modes: Agent mode for full generation execution, Plan mode for multi-step planning, and Edit mode for standard Q&A.

Two Bundled Local ONNX Models

The repository includes two local model files that are copied to the build output directory automatically via Services.props. The first is bge-small-zh-v1.5, used for semantic search and vector recall across historical chapters. When a chapter requires a callback to events from hundreds of chapters earlier, the system uses this model to retrieve the most semantically relevant historical fragments rather than scanning the full chapter archive.

The second is chinese-roberta-tiny, a masked language model used for the humanization feature. After the AI generates a passage, the system uses this model to suggest semantically equivalent word substitutions that reduce detectable AI-generated patterns. A semantic similarity check runs before and after substitution to prevent semantic drift.

Both models are released from memory after ten minutes of inactivity and reloaded on demand. If you want to reduce the binary size, deleting the corresponding Resources/ subdirectory disables the feature and the system degrades gracefully: vector search and humanization become unavailable, but everything else continues working.

Known Bugs in the Open-Source Version

The README is explicit about four known issues in the open-source release. The first is an English-Chinese mapping bug in CHANGES declarations that causes the validation step to fail at recognizing field names. The second is a missing feedback dimension injection in the rewrite retry path. These two are marked as required fixes before stable generation is possible. The README says an AI coding agent can fix them.

The third is a Console.OutputEncoding issue present in the open-source version but fixed in the private build; the README says this is a small change, about ten lines of code, and can be done by an AI assistant. The fourth is a state machine improvement to prevent premature recording that causes the model to misidentify state.

Beyond bugs, the system is Windows-only because it is built on WPF. No cross-platform port is mentioned. Running it on macOS or Linux requires a Windows virtual machine or a compatibility layer.

The last push was on 2026-08-24. The repository has no GitHub releases.

The README also notes that video tutorials exist on Bilibili for the official version and the open-source version, but the README warns that tutorials are for older versions because the project updated faster than the tutorial could follow. The open-source version and the official paid version diverge at the point where the encryption and private domain name were removed for open-source release. The README has a dedicated open-source explanation file at 开源说明.md.

License Terms and the Commercial Use Restriction

The code is released under the MIT license. However, the README includes an explicit commercial use note: any commercial use, including repackaging for sale, commercial SaaS deployment, or embedding in a paid product, requires contacting the original author for authorization. The contact is listed in the README as a QQ account.

This means the MIT license applies for personal and open-source use, but the author has added a commercial restriction that sits outside the standard MIT text. A team evaluating Tianming for a commercial product must treat this as a license negotiation requirement, not an open MIT grant. The README does not describe any formal licensing agreement process or pricing.

Editorial conclusion

tianming-novel-ai-writer is built for Chinese web-novel authors who write at scale: thousands of chapters, dozens of characters, multiple plotlines and foreshadowing threads. Its state-management architecture is the distinguishing feature; the six generation gates prevent errors from compounding across chapters. The system is Windows-only, requires a .NET 8.0 SDK, and the open-source version has four documented bugs that require repair before stable generation. Commercial use requires contacting the author separately from the MIT license terms. The last push was on 2026-08-24.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. zy-zmc/tianming-novel-ai-writer on GitHub