WenShape (文枢): A File-Based Agent Pipeline for Long-Form Novel Writing

The Problem WenShape Targets: Consistency Across Hundreds of Chapters

Most LLM writing tools treat a novel as one long conversation. That works for a short story and breaks at scale, because the model has no durable place to put a character's eye colour, a city's political structure, or the fact that a minor noble died in chapter forty. WenShape's README frames the project around exactly this gap, stating that it is concerned not only with generated output but with consistency, traceability and maintainability in long-form writing. The intended user is someone writing a serialised novel, a multi-volume work, or fan fiction that must stay faithful to an existing canon. The repository description calls it a deep context-aware agent-based novel creation system, and the architecture reflects that: writing is decomposed into volumes, chapters, drafts, summaries, cards and a fact store, each stored separately. The project is not a chat wrapper. It is a small content management system with an LLM pipeline bolted to it, and that framing is the most useful thing to understand before evaluating anything else.

Volumes, Chapters and Drafts as Explicit Storage Objects

The README states that WenShape maintains a volume-to-chapter-to-draft structure rather than a single conversation stream. On disk this appears as volumes/*.yaml, summaries/*_summary.yaml, drafts/<chapter>/final.md and scene_brief.yaml. Chapter ordering is persisted through an order_index field, so the sequence survives batch operations instead of depending on directory listing order or creation time. The frontend volume tree and chapter management screens are described as corresponding directly to this storage layout. That is a real design decision with a real cost: every structural change to the book is a file write, and the application must keep the tree, the YAML and the Markdown in agreement. The benefit is that a chapter is a file you can open, edit by hand, or revert with git. For anyone who has watched a long AI-assisted draft become unrecoverable inside a chat history, the trade is understandable. It also means the project's data model is inspectable without running the application at all, which is unusual and worth noting.

Cards: Characters, World and Style as Versionable Assets

Long-term setting material is split into three card types. Character cards live in cards/characters/*.yaml, world cards in cards/world/*.yaml, and the style card is a single cards/style.yaml. The README describes world cards as having moved to a description-first structure, where new data is carried in a description field, while older rules and immutable fields are still read and merged into the description text for backward compatibility. That compatibility shim is a small but telling detail: it means the project has already changed its world-card schema once, and chose to keep reading old files rather than migrate them. If you are evaluating WenShape for a long project, expect further schema shifts and check whether the storage layer in backend/app/storage/ handles them the way this one was handled. Style as a single card rather than a per-project or per-volume setting is a limitation worth flagging. A book that shifts register between volumes, or a project containing two books with different voices, has no obvious place in this layout as described.

The Context Engine: BM25, Entity Boosting and Chapter Distance Decay

This is the part that distinguishes WenShape from a prompt template collection. Facts are stored in canon/facts.jsonl, chapter and volume summaries are YAML, and an evidence_service builds the evidence index. Retrieval combines BM25, entity enhancement, chapter binding and fact distance decay. The select_engine applies what the README calls a logarithmic chapter distance decay to facts, so a fact tied to a chapter near the current one is weighted higher, while a distant but still important world fact is not discarded outright. That last clause matters. A hard cutoff would drop foundational worldbuilding once the story moves far enough from it; a logarithmic decay keeps it in the candidate pool at reduced weight. The README is explicit that the system is not simply feeding all context to the model, which is the honest description of the trade: you gain a bounded, ranked context window and you accept that the ranking can be wrong. Nothing in the supplied material quantifies retrieval quality, so treat the mechanism as a design to inspect rather than a measured improvement.

The Fanfiction Workflow and Its Proposal Gate

Fan fiction gets a dedicated pipeline rather than a paste box. The README describes four steps: search, preview, crawl, proposal. The search_service supports 萌娘百科, Wikipedia and Fandom. The crawler_service handles body extraction, link detection and multiple fallback paths. The fanfiction router then feeds results to an agent that generates character and world card proposals. You can either search a wiki entry or paste any http/https page address directly for preview and extraction. The important constraint is that extracted content is not written into the project. It enters as a proposal, and you decide whether to keep, modify or discard it. That is a sensible boundary for a task where a crawler will occasionally grab navigation chrome, a disambiguation page, or the wrong character entirely. The cost is manual review of every proposal, which does not scale if you are importing a large canon. The README does not describe bulk acceptance, so assume proposal-by-proposal review is the intended path.

Running It: start.bat, start.py and the Windows Release Package

Two paths exist. The source route requires Python 3.10+ and Node.js 18+, and the README gives this command from the project root: cd WenShape-main followed by start.bat. That batch file invokes start.py, which checks the Python and Node.js environments, launches the frontend and backend services, and on first run fills in the basic local development configuration. The second route is the Windows release package, downloaded from the Releases page, unzipped and launched by double-clicking WenShape.exe, with no separate Python or Node.js installation. That package is built by build_release.py and the output lands in dist/WenShape/, with config.yaml, .env, data/ and static assets prepared alongside it. The presence of a .env in the release output is worth attention: model provider credentials are configured there, and the llm_gateway layer abstracts OpenAI, Anthropic, DeepSeek, Gemini, Qwen, Wenxin, AI Studio and custom OpenAI-compatible endpoints. If you plan to point WenShape at a private gateway or aggregation service, that custom-endpoint option is the relevant one.

Where WenShape Is the Wrong Tool, and What to Compare It Against

The licence is the first hard boundary. The README states the project uses the PolyForm Noncommercial License 1.0.0. That is a source-available licence, not an open source one, and the repository metadata reports NOASSERTION rather than a recognised SPDX identifier. Commercial use, including selling a service built on it, is outside the grant as described. Read the LICENSE file itself rather than relying on the README line. The second boundary is integration. WenShape is a full application with a React frontend and a FastAPI backend, and nothing in the supplied material describes a documented public API for embedding the pipeline elsewhere. If you want to call a context engine from your own tooling, this is the wrong shape. For that need, a library such as txtai or a plain LangChain retrieval chain gives you components without an application around them, at the cost of building the volume, chapter and card model yourself. The difference is architectural: WenShape ships an opinionated writing application, and the alternatives ship parts. Choose based on whether you want the application or the parts. A third boundary is the release cadence visible in the metadata. Releases v0.3.6, v0.3.9 and v0.4.0 landed between late February and early April 2026, and the repository was pushed in August 2026, so this is a project still moving. Expect schema and behaviour changes between versions, and pin a release rather than tracking main if you have a book in progress.

Maintenance Cost and What to Verify Before Committing

The maintenance story is better than average for a project of this type because the data is plain text. YAML, Markdown and JSONL files can be diffed, reviewed in a pull request and backed up with ordinary tools, and the README explicitly frames this as suitable for version management and long-term upkeep. Upgrading the application should not require migrating your manuscript, though the world-card compatibility note shows that schema changes do happen and the storage layer carries the burden of reading older files. The reading order the README recommends for new maintainers is a fair proxy for onboarding cost: start at frontend/src/pages/WritingSession.jsx, then backend/app/routers/session.py, then backend/app/orchestrator/orchestrator.py, then the agents directory, then context_engine and services, and finally storage. That is six areas before you understand the whole system, which is honest about the size of the codebase. Before you commit a novel to it, verify the LICENSE terms, confirm that the context engine's weighting suits your structure by reading backend/app/context_engine/, and check whether your intended model provider is reachable through llm_gateway or needs the custom OpenAI-compatible path.

Editorial conclusion

Adopt WenShape if you write long fiction and want your settings, summaries and facts stored as plain files you can diff and version, and if your use is noncommercial. Do not adopt it if you need a permissively licensed component, a headless API, or a system you can run without Python 3.10 and Node.js 18. Before committing, verify three things: the exact terms in the LICENSE file, since the repository metadata reports NOASSERTION rather than a recognised identifier; whether select_engine's chapter distance decay actually fits your book's structure, by reading backend/app/context_engine/; and whether the Windows release package is the version you want, since it is built by build_release.py rather than installed from source.

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. unitagain/WenShape on GitHub