一个活的模拟世界。NPC 不是脚本木偶——他们有记忆、有性格、会演化。LLM 驱动世界变化，但不用 LLM 做一切。
想象一个世界，里面有几千个 NPC 在生活。农民种地，铁匠打铁，商人抬价，贵族争权。他们互相认识、互相关注、互相记仇。
你可以作为一个冒险者走进这个世界，在酒馆里跟老板打听消息，在铁匠铺修你的剑，在巷子里被神秘人拦住。或者作为一个领主，调税率、派间谍、跟邻国宣战。
关键是：这个世界会自己演化。方言会分化，宗教会分裂，新技术会被发现，城邦会变成帝国——没有人预先写了"剧本"，一切从 simulation 中涌现。
| 传统 RPG | World Framework |
|---|---|
| NPC 说固定台词 | NPC 根据记忆和关系生成对话 |
| 任务由设计师预设 | 事件从世界状态自动产生 |
| 世界只有玩家在动 | 所有 NPC 按 schedule 自行运转 |
| 玩家离开后世界暂停 | 每一日世界都在推进 |
# 0. 克隆并安装
npm install
# 1. 配置 LLM
cp .env.example .env
# 编辑 .env，填入 API Key 和 Base URL
# 2. （可选）生成一个新世界
npm run world:generate kingdom "你的世界种子描述"
# 3. 一键启动服务端 + TUI 客户端
./start.sh其他启动方式：
./start.sh dev # 热重载模式（开发推荐）
./start.sh server # 仅服务端
./start.sh client # 仅客户端
./start.sh logs # 查看日志
./start.sh status # 检查服务端状态
./start.sh test # 运行测试或手动分开启动：
# 终端 1：服务端
npm run dev
# 终端 2：TUI 客户端
npm run dev:tui键盘驱动，不需要鼠标。所有交互通过快捷键完成：
| 按键 | 功能 | 说明 |
|---|---|---|
W A S D |
移动 | 北/西/南/东 |
U / X |
上下 | 上楼/下楼 |
1–9 |
选择实体 | 选中房间内的 NPC 或物品，再按数字选择交互动作 |
R |
休息 | 恢复体力 |
Q |
状态 | 查看自身属性、需求、关系 |
I |
背包 | 管理物品（使用/观察/丢弃） |
J |
任务 | 查看进行中的任务 |
T |
游记 | 阅读每日游记（章回体） |
M |
地图 | 打开/关闭小地图 |
0 |
结束今天 | 结束当日行动，等待世界结算 |
Esc |
返回 | 取消选择 / 关闭弹窗 |
游戏循环：每回合是一"天"——自由行动（消耗精力）→ 结束今天 → 世界结算（NPC 行动、战斗、事件）→ 收到日报 → 新的一天开始。
规则引擎（纯代码，零 LLM 消耗） LLM 层（内容生成，按需调用）
├── Schedule 系统：NPC 按时辰作息 ├── 世界事件注入
├── Need 系统：饥饿/安全/社交/成就/休息 ├── NPC 记忆压缩为认知
├── Trait 系统：100+ 性格维度权重 ├── ContentPool 自迭代
├── Relation 图谱：NPC/玩家间 -100~+100 ├── NPC 对话生成
├── Social Ripple：交互波及附近 NPC ├── 日报/游记生成
├── Combat 系统：ATK/DEF/SPD/暴击 ├── 世界初始化
├── Quest 系统：发现/接受/推进/完成 └── 聚落/文化/语言演化
└── 路径寻路：BFS/A*
演化流水线：
检测(规则) → 生成(LLM) → 裁决(规则)
→ 物化(规则) → 传播(规则)
核心设计：LLM 永远不决定"是否发生演化"，只负责"如果发生演化，可以演化成什么"。所有决策权在规则引擎。
ContentPool：26 个字段的游戏内容池（职业表、日程表、名字池、战斗公式参数、社交涟漪配置等），全部从 YAML 加载，LLM 可以演化后写回。代码中禁止硬编码游戏内容。
核心子系统均已实现并可通过 TUI 客户端游玩：
- 已完成：NPC 日常、需求系统、性格系统、关系图谱、社交涟漪、战斗系统、任务/支线、对话系统、记忆系统、地图/寻路、世界生成、日报/游记
- 进行中：对话知识保留、场景交互、LLM 演化自由度扩展、历史/传说系统
- 待实现：Web UI
| 文档 | 内容 |
|---|---|
| 整体架构 | 定位、功能、5 层技术分层、协议、核心约束 |
| 概念与参考 | 关键概念、MVP 范围 |
| 模拟层细节 | NPC 分层激活、并发模型、AOI、记忆系统 |
| LLM 交互 | 14 种 LLM 交互定义 |
| 自演化 | 组织形式/语言/技术演化 |
| 玩家流程 | 接入、死亡/退出、反馈闭环 |
| ContentPool | 26 字段、三层加载、突变流水线 |
| 任务与支线 | 任务生命周期、支线触发 |
| 代码质量评估 | 各模块质量状态 |
| 开发指南 | 20 篇：字段新增、命令添加、陷阱 token、测试、日志等 |
| AGENTS.md | 开发者必读：代码规范、ContentPool 边界决策树 |
./start.sh test # 运行全部测试（Vitest，39 个测试文件）
./start.sh dev # 开发热重载模式
npm run lint # 类型检查 + Biome lint + 依赖校验
npm run format # 自动格式化技术栈：TypeScript · Node.js (服务端) · Bun (TUI 客户端) · Solid.js + OpenTUI · ws + YAML + zod · Vitest · Biome · Lefthook
架构约束：数据在 ContentPool，逻辑在引擎。代码与数据之间有硬边界。所有游戏内容（标签、公式参数、名字池、日程表）必须在 ContentPool 中定义，禁止在引擎代码中硬编码。