Alethea World History Engine

阿莱西娅🌍

一种叙事图引擎，用于使用LLM或纯粹按程序生成、跟踪和可视化虚构世界。

历史图查看器

📖 概述

世界历史引擎是一个叙事框架，可以在两种模式下工作：

1. 人工智能辅助： 作为一个 MCP服务器 对于LLM（如克劳德）来说，允许他们一致地查询和修改世界状态。
2. 程序（独立）： 作为一个经典的生成器，您可以使用GUI或CLI基于YAML模板生成世界， 无需API密钥或LLM.

它维护着一个一致的内部图形数据库，其中包含实体（派系、人物、地点）及其关系。

✨ 主要特点

• 🕵️‍♂️ RAG小说： 在不填满LLM上下文窗口的情况下跟踪数千个实体。
• 🎲 双模式： 与Claude/OpenAI OR配合使用，作为独立的离线生成器。
• 🕸️ 基于图的一致性： 实体具有严格的关系（例如。， Faction A --[war]--> Faction B).
• ⏳ 时间旅行调试： 包括一个基于web的可视化工具(world_viz.html)带有时间轴滑块。回顾历史，看看50个时代前的世界是什么样子的。

🏗 建筑

以下是世界引擎实体的内部结构：

graph TD
    %% --- Styles ---
    classDef browser fill:#f9f,stroke:#333,stroke-width:2px;
    classDef mcp fill:#ffecb3,stroke:#ff6f00,stroke-width:2px,stroke-dasharray: 5 5;
    classDef storage fill:#e0e0e0,stroke:#333,stroke-width:2px;
    classDef core fill:#e1f5fe,stroke:#0277bd,stroke-width:2px;

    %% --- Clients ---
    subgraph Clients ["Clients & Interfaces"]
        BrowserUI[Browser
Web Visualizer / GUI]:::browser
        ClaudeApp[Claude Desktop
AI Assistant]:::mcp
    end

    %% --- Backend ---
    subgraph Backend ["Backend (Python)"]
        
        %% Entry Points
        subgraph EntryPoints ["Entry Points"]
            Server[server.py
HTTP API & GUI]:::core
            CLI[main.py
CLI Generator]:::core
            MCPSrv[mcp_server.py
MCP Server]:::mcp
        end

        DI((Dishka IOC))

        subgraph Services ["Services"]
            TES[TemplateEditorService]
            SIM_S[SimulationService]
            ST_S[StorytellerService]
            WQS[WorldQueryService]
            NS[NamingService]
        end
        
        %% Core Logic
        subgraph CoreEngine ["Core Engine"]
            WG[WorldGenerator]
            Repo[InMemoryRepository]
        end

        %% Connections
        ClaudeApp == Stdio/SSE ==> MCPSrv
        BrowserUI == HTTP ==> Server
        
        Server & MCPSrv & CLI --> DI
        DI --> Services
        Services --> CoreEngine
    end

    %% --- Storage ---
    subgraph Storage ["Storage"]
        YAML[(YAML Templates)]:::storage
        JSON[(World JSON)]:::storage
    end

    Repo -.-> JSON
    TES -.-> YAML

🚀 快速开始

🐳 Docker部署

1.塑造形象

从存储库的根构建容器映像：

docker build -t world-engine .

2.运行容器

运行映像，露出所需的两个端口。将此处的_api_key_here替换为您的实际密钥。如果使用标准OpenAI，可以跳过BASE_URL。:

docker run -d \
  --name world-engine \
  -p 8000:8000 \
  -p 8001:8001 \
  -e API_KEY="sk-..." \
  -e MODEL="claude-4-5-sonnet-latest" \
  -e BASE_URL="[https://api.anthropic.com/v1](https://api.anthropic.com/v1)" \
  world-engine

3.访问

• Web UI（独立生成）： 访问图形界面 http://localhost:8001.
• MCP服务器（AI集成）： 将您的Claude Desktop或其他MCP客户端连接到 http://localhost:8000.
• 日志： 查看两个服务的组合日志： docker logs world-engine-instance.

无Docker部署的先决条件

• Python 3.11+
• uv （推荐）或 pip

安装

# Clone the repository
git clone 
cd world-history-engine

# Install dependencies
uv sync

🎲 生成世界（独立）

您可以在不配置任何AI的情况下生成世界：

选项1：图形界面（GUI） 启动web服务器以交互方式生成和可视化世界。

uv run server.py
# Open [http://127.0.0.1:8001](http://127.0.0.1:8001) in your browser

选项2：命令行（CLI） 运行主生成脚本以在中创建新世界快照 world_output/.

uv run main.py

🤖 使用LLM（MCP服务器）运行

要将此引擎用作Claude内部的工具（用于交互式讲故事），请运行MCP服务器：

uv run mcp_server.py

将此添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "world-engine": {
      "command": "uv",
      "args": [
        "run",
        "mcp_server.py"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

要将此引擎用作Qwen Desktop中的工具，请在MCP设置中粘贴以下配置：

{
    "mcpServers": {
        "world-builder": {
            "url": "http://0.0.0.0:8000"
        }
    }

并添加 描述

📊 可视化你的世界

该引擎附带了一个独立的HTML可视化工具。

1. 创造一个世界 图形用户界面, 命令行界面，或 主控程序.
2. 打开 static/world_viz.html 在您的浏览器中。
3. 上传JSON导出（来自 world_output/).
4. 探索： 拖动节点，按派系过滤，并使用 时间线滑块 回放历史。

⚙️ 配置和模板

引擎的逻辑是数据驱动的。您可以在中修改模拟规则 data/templates/:

• factions.yaml：定义文化、禁忌和侵略程度。
• biomes.yaml：配置环境生成。
• resources.yaml：管理经济项目。

以及更多其他命名规则 data/naming

🗺️ 路线图

• \[\]持久存储（支持PostgreSQL和Neo4j）
• \[\]开发人工智能驱动的任务生成器

🤝 贡献

欢迎投稿！请查看问题选项卡或提交PR。

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。