Project Genesis - 社会学模拟引擎

欢迎来到 Project Genesis！这是一个基于大语言模型的社会学模拟引擎，能够从简单的智能体行为中涌现出复杂的社会结构和文化现象。

🚀 快速开始

安装和运行

# 克隆项目
git clone https://github.com/your-repo/project-genesis.git
cd project-genesis

# 安装依赖 (需要先安装 uv)
uv sync

# 配置 API 密钥
export DEEPSEEK_API_KEY="your-api-key-here"

# 运行第一个模拟
uv run python -m sociology_simulation.main \
    simulation.era_prompt="stone age with magic" \
    world.num_agents=10 \
    runtime.turns=30

运行 Web Demo（简易可视化）

uv run python run_simple_web_simulation.py
# 打开浏览器访问
# http://localhost:8081

提示：该入口会启动一个简易 HTTP + WebSocket 服务，用于实时查看地图与智能体状态。

运行全功能 Monitor（控制台 + 模拟编排）

Monitor 会同时启动静态页面、HTTP API、WebSocket 推送与模拟调度后台，可在浏览器中启动/停止模拟、设定时代并与 Trinity 互动。

# 启动监控控制台，默认监听 0.0.0.0:8081（HTTP）与 0.0.0.0:8765（WebSocket）
uv run python scripts/run_web_simulation.py

# 自动启动一个模拟（可通过 CLI 覆盖 Hydra 配置）
uv run python scripts/run_web_simulation.py \
    --auto-start \
    --era "stone age with magic" \
    --turns 30 \
    --num-agents 12 \
    --world-size 48

# 高级：传入额外 Hydra override，例如切换到自定义场景
uv run python scripts/run_web_simulation.py \
    --auto-start \
    --scenario stone_age \
    --override runtime.seed=1234

启动成功后可访问 http://localhost:8081 进入监控界面：

• 通过左上角的控制按钮启动或停止模拟
• 在“Simulation Settings”中覆盖 Era 提示、回合数、智能体数量等配置
• 通过“Interactions”面板向 Trinity 或特定 Agent 发送消息
• 右侧仪表板实时显示世界状态、日志与回合事件

核心特性预览

智能涌现系统

• 🧠 动态技能创建 - Trinity 根据智能体行为创建新技能
• 🏛️ 社会结构自生成 - 群体、市场、政府的自然形成
• 📚 文化演化 - 知识传承和社会规范的自然发展

复杂环境系统

• 🌍 动态地理 - 地形、资源、气候的实时变化
• ⚡ 自然事件 - 灾害和环境变化驱动社会发展
• 🔄 生态平衡 - 资源与人口的动态平衡

📚 文档导航

🆕 新用户起步

1. 安装指南 - 系统要求、安装步骤、环境配置
2. 基础模拟 - 第一个石器时代模拟
3. 配置说明 - 详细的配置选项和参数调优

🔬 研究人员

1. 系统架构 - 整体架构设计和组件关系
2. Trinity 系统 - 神系统的设计和实现
3. 高级场景 - 复杂社会模拟案例

💻 开发者

1. 技术文档 - 了解实现细节
2. API 文档 - 进行功能扩展
3. 自定义时代 - 创建新模块

🎯 系统架构

Trinity (神系统)
├── 行为观察 - 监控智能体行为模式
├── 技能创建 - 动态创建和分配技能  
├── 事件生成 - 自然灾害和环境变化
└── 时代管理 - 引导社会发展进程

智能体系统
├── 动态技能 - Trinity 控制的技能系统
├── 社交网络 - 复杂的关系和声誉
├── 学习机制 - 知识获取和技能传承
└── 适应行为 - 环境和社会压力响应

社会结构
├── 群体系统 - 家庭、部落、工作团队
├── 文化记忆 - 知识积累和传统形成
├── 经济系统 - 市场、贸易、专业化
└── 政治系统 - 治理结构和权力分配

环境系统
├── 地理系统 - 64x64 动态地形
├── 资源经济 - 供需动态和价格机制
├── 自然事件 - 灾害和环境变化
└── 生态平衡 - 可持续发展机制

⚙️ 关键配置（实现版）

• world.terrain_algorithm: 地形算法选择，simple | noise | voronoi | mixed（默认 mixed）。
• runtime.hunger_growth_rate: 饥饿增长速率（默认 3.0）。
• runtime.auto_consume: 是否在饥饿高时自动进食（默认 true，兼容旧行为）。
• output.turn_summary_llm: 是否启用基于事实的 LLM 叙述（默认 true）。
• output.turn_summary_max_highlights: 摘要中最多高亮条目数（默认 5）。

说明：上述键为当前实现使用的实际键名；若早期计划文档中出现 world.terrain.algorithm 等嵌套命名，请以本节为准。

🧩 与开发计划的对应落地

• 初始化与地形多样性（A）：一次性规则生成 + 失败安全回退；多算法地形 + 进程内缓存；多样性校验。
• 资源交互与可靠性（B）：gather/consume 行为走本地分发，确定性、无 LLM 依赖；饥饿配置项保持兼容默认。
• 演化与繁衍（C）：每 3 回合无动作时执行温和演化回退；数值状态含 stamina 与冷却；基于启发式的繁衍建议与概率生成。
• 回合摘要与分析（D）：先算事实，再请求 LLM 叙述，并做一致性守卫，避免“技能单一”等与指标矛盾的描述。

相关实现入口：

• 配置：sociology_simulation/conf/config.yaml
• 地形生成：sociology_simulation/terrain_generator.py
• 世界逻辑：sociology_simulation/world.py
• Trinity：sociology_simulation/trinity.py
• 提示模板：sociology_simulation/conf/prompts.yaml

🛠️ 技术栈

• Python 3.10+ - 核心开发语言
• uv - 现代 Python 包管理器
• aiohttp - 异步 HTTP 客户端
• Hydra - 配置管理系统
• DeepSeek/OpenAI API - 大语言模型服务
• matplotlib - 数据可视化
• loguru - 高级日志系统

📁 仓库结构

.
├── sociology_simulation/           # 核心代码与 Hydra 配置（conf/）
├── scripts/                        # 可运行脚本与工具
│   ├── run_simple_web_simulation.py
│   ├── run_web_simulation.py
│   ├── run_with_web_export.py
│   └── reorg_repo.sh
├── web_ui/                         # Web UI 静态资源
│   ├── index.html                  # 监控面板主页面（测试依赖此路径）
│   ├── js/simulation-ui.js
│   ├── monitor/                    # 新版 React + Vite 监控控制台
│   ├── landing/index.html          # 项目 landing/demo 页面
│   └── experimental/               # 实验性页面
├── web_data/                       # 运行期导出 JSON（已 gitignore）
├── docs/                           # 文档（web-ui/、guides/、engineering/、plans/、agents/）
├── logs/  outputs/                 # 运行产物（已 gitignore）
├── test_*.py                       # 跨模块测试（可选下沉至包内 tests/）
├── pyproject.toml  uv.lock
└── README.md

说明：保留根级 run_simple_web_simulation.py 作为入口桩，内部委托到 scripts/run_simple_web_simulation.py，以保持既有使用习惯。

🔍 使用场景

📈 社会学研究

• 社会网络形成和演化分析
• 文化传播和社会分层研究
• 集体行为和群体动力学

🏛️ 人类学应用

• 技术发展和扩散模拟
• 社会组织演化研究
• 文化适应机制分析

💼 经济学建模

• 市场自发形成机制
• 分工和专业化发展
• 创新扩散和技术进步

🎮 游戏开发

• 动态世界生成
• NPC 行为和社会系统
• 玩家驱动的内容创作

📖 完整文档

用户指南

• 安装指南 - 系统要求、安装步骤、环境配置
• 配置说明 - 详细的配置选项和参数调优
• 运行教程 - 如何运行和监控模拟

技术文档

• 系统架构 - 整体架构设计和组件关系
• 智能体系统 - Agent 设计和行为机制
• Trinity 系统 - 神系统的设计和实现
• 技能系统 - 动态技能创建和管理

示例教程

• 基础模拟 - 第一个石器时代模拟
• 高级场景 - 复杂社会模拟案例
• 自定义时代 - 创建自定义时代和场景

API 参考

• Agent API - 智能体接口文档
• World API - 世界系统接口
• Trinity API - Trinity 系统接口

🌟 项目亮点

1. 真正的智能涌现

• 不使用预设的社会规则，所有社会现象都从智能体互动中自然涌现
• Trinity 系统动态观察和创建技能，没有硬编码的能力限制

2. 多层次复杂性

• 个体认知 → 社会网络 → 群体行为 → 文化演化
• 从石器时代到现代文明的完整发展轨迹

3. 灵活的配置系统

• 基于 Hydra 的模块化配置
• 支持命令行覆盖和自定义场景

4. 现代化开发体验

• 使用 uv 进行依赖管理
• 异步架构提高性能
• 完整的类型提示和文档

🤝 贡献指南

我们欢迎所有形式的贡献！

1. 提交 Bug 报告 - 在 Issues 中报告问题
2. 功能请求 - 提出新功能建议
3. 代码贡献 - 提交 Pull Request
4. 文档改进 - 帮助完善文档

开发环境设置

# 克隆项目
git clone https://github.com/your-repo/project-genesis.git
cd project-genesis

# 安装开发依赖
uv sync --group dev

# 运行测试
uv run pytest

# 代码格式化
uv run black .
uv run ruff check .

📞 获取帮助

🆘 常见问题

查看各文档的"常见问题"部分，或搜索 Issues

💬 社区支持

• GitHub Discussions
• 社区论坛

🐛 问题报告

• 提交 Bug 报告
• 功能请求

📄 许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件。

🔄 版本信息

• 当前版本: v2.0.0
• 最后更新: 2025年7月
• Python 版本: 3.10+
• 文档版本: v2.0

---

开始探索 Project Genesis，从解释社会到预测未来！ 🚀

"社会的复杂性不是设计出来的，而是涌现出来的。" - Project Genesis 设计理念