# Regulum

**Repository Path**: qwe12345678/regulum

## Basic Information

- **Project Name**: Regulum
- **Description**: 一个内容生成器，未必能实现README.md里的所有特性，原KnowProlog
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-06-15
- **Last Updated**: 2025-09-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: AI, Nlp

## README

# Regulum (分层内容生成器)

一个基于规则和事件驱动的 Rust 内容生成框架。

Regulum 不仅仅是一个简单的模板引擎，它是一个具备上下文感知、动态逻辑和高度可扩展性的“内容生成生态系统”。它可以用于生成代码、配置文件、自然语言故事、游戏对话、测试数据等任何具有内在结构的内容。

## 🎯 项目目标与愿景

### 项目目标
开发一个基于规则和事件驱动的字符串生成框架。用户通过在 Rust 代码中定义一系列“元素”及其相互关系（如包含、邻接、标签等）和动态行为（通过监听函数），来程序化地生成复杂、结构化的文本内容。

### 项目愿景
Regulum 旨在成为一个具备上下文感知、动态逻辑和高度可扩展性的“内容生成生态系统”。它不仅能替代简单的模板引擎，更能处理需要复杂逻辑和结构化生成的任务，例如：
*   代码生成
*   动态配置文件
*   自然语言故事与游戏对话
*   结构化测试数据

## 核心概念

1.  **元素定义 (ElementDefinition):** 元素的“蓝图”或“类”。它是一个静态的结构体，在程序启动时定义好，包含了元素的所有规则和属性。
2.  **元素实例 (ElementInstance):** 元素在生成过程中的具体“对象”。它是在内存中构建的树形结构的一个节点，包含了对其定义的引用、父子关系以及运行时状态。
3.  **生成器 (Generator):** 整个生成过程的协调者。它持有一个所有 `ElementDefinition` 的注册表，并负责从一个根元素开始，递归地构建 `ElementInstance` 树，最终渲染成字符串。
4.  **生成上下文 (GenerationContext):** 这是传递给所有监听函数的“上帝对象”，它提供了丰富的 API，允许监听函数查询状态、修改生成流程、与其他元素通信。
5.  **元素钩子 (ElementHooks):** 一个 Trait，定义了元素可以监听的各种事件（如创建、填充前、渲染后等）。具体的元素定义可以实现这个 Trait 来注入自定义逻辑。

## 模块化设计

项目被划分为以下几个核心模块，以保持代码的清晰和可维护性：

*   `main.rs`: 项目入口，用于定义元素、注册元素并启动生成过程。
*   `element.rs`: 定义 `ElementDefinition` 结构体和 `ElementHooks` Trait。
*   `instance.rs`: 定义 `ElementInstance` 树节点结构。
*   `generator.rs`: 定义 `Generator` 和主要的生成逻辑。
*   `context.rs`: 定义 `GenerationContext` 和暴露给钩子函数的 API。
*   `rules.rs`: 封装所有规则的检查逻辑（黑白名单等）。
*   `error.rs`: 定义项目中的自定义错误类型。

## 项目结构
```
regulum/
├── Cargo.toml
└── src/
    ├── main.rs         # 入口和示例定义
    ├── element.rs      # ElementDefinition, ElementHooks
    ├── instance.rs     # ElementInstance, InstanceState
    ├── generator.rs    # Generator, 主要生成逻辑
    ├── context.rs      # GenerationContext 和 API
    ├── rules.rs        # 规则检查函数
    └── error.rs        # 自定义错误
```

## 扩展与优化

*   **性能优化**: 对于非常大的元素定义集，可以预计算合法的父子关系图，加速查找过程。
*   **异步支持**: `ElementHooks` 可以设计成异步 Trait，允许在钩子中执行 I/O 操作（如从数据库或网络获取内容）。
*   **外部定义**: 实现从配置文件（如 YAML, RON, TOML）加载 `ElementDefinition`，实现逻辑与配置分离。
*   **更强的通信机制**: `GenerationContext` 中可以加入一个基于 Channel 的消息系统，允许非直接相关的元素实例进行通信。
*   **集成随机库**: 在 `GenerationContext` 中集成一个可配置的随机数生成器（RNG），用于可复现的随机生成。