[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-80724":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":14,"stars7d":16,"stars30d":16,"stars90d":15,"forks30d":15,"starsTrendScore":13,"compositeScore":17,"rankGlobal":10,"rankLanguage":10,"license":10,"archived":18,"fork":18,"defaultBranch":19,"hasWiki":20,"hasPages":18,"topics":21,"createdAt":10,"pushedAt":10,"updatedAt":29,"readmeContent":30,"aiSummary":31,"trendingCount":15,"starSnapshotCount":15,"syncStatus":16,"lastSyncTime":32,"discoverSource":33},80724,"bragi","wailers9\u002Fbragi","wailers9","一个面向架空世界故事创作者的 AI 架空世界与长篇故事引擎。它能从一句设定出发，自动生成层 层嵌套的历史、地理、角色关系与事件网络，并持续写出贴合世界观的剧情。支持 CLI 与可视化界面，可按时间和空间路径扩展世界，让故事像真实宇宙一样不断生长。项目用数字路径管理嵌套的时间、空间、   角色和事件节点，按需生成并补全世界资料，支持本地 Demo、OpenAI\u002FDeepSeek JSON   Agent、CLI 和黑白 Web 可视化界面，用于创建可持续展开的故事世界与剧情会话。","",null,"Python",45,3,1,0,2,42.01,false,"main",true,[22,23,24,25,26,27,28],"ai","creative-writing","fiction-writing","openai","procedural-generation","story-generation","worldbuilding","2026-06-12 04:01:29","# Bragi\n\n现有能够生成小说的 Agent 常常受限于短期记忆，容易出现角色情节设定冲突的问题。Bragi 通过标准化的时空规范和人物事件记录解决了这一问题，让agent每次都能带着世界记忆继续创作。\n\nBragi 是一个面向幻想创作者的 AI 架空世界与互动故事引擎。给它一句世界设定，它会像搭建一座会呼吸的宇宙一样，生成历史、地理、角色、事件和剧情，并在后续创作中持续记住这些设定。\n\nBragi 会把世界拆成可追踪的时间路径和空间路径，只在需要时扩展节点，让故事既能不断变大，又不会把所有信息一次性塞进上下文。你可以用它生成架空大陆、未来都市、魔法王朝、诡异海域、群像冒险，甚至让同一个世界持续写成长期连载。\n\n## 核心能力\n\n- **一句话生成架空世界**：从简单提示开始，生成世界概览、底层规则、历史脉络和空间结构。\n- **时间与空间双树结构**：用 `1,2,3` 这样的数字路径定位历史阶段和地点层级，方便持续扩展。\n- **按需补全世界细节**：当前剧情所处的时间和地点保留完整内容，附近节点保留摘要，需要时再扩写。\n- **自动生成角色网络**：生成主角、配角、关系、状态变化，并在故事推进时更新人物。\n- **持续写故事**：根据世界观、当前地点、历史事件、角色状态和用户方向继续生成剧情。\n- **事件与上下文管理**：自动记录公开事件、个人事件、主角选择、管理器提示和 token 用量。\n- **CLI + Web UI**：既能在命令行跑完整流程，也能打开本地黑白可视化界面操作。\n- **多 Agent 支持**：内置本地 Demo Agent，也支持 OpenAI 和 DeepSeek JSON Agent。\n\n## 界面预览\n\nBragi 提供一个本地 Web UI，用来创建世界、初始化时间与空间、生成故事片段，并查看当前路径、节点摘要、角色变化和事件更新。\n\n\u003Cp align=\"center\">\n  \u003Cimg width=\"100%\" alt=\"Bragi 本地 Web 可视化界面预览\" src=\"https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002F2614dc5c-403d-45e5-af79-b2472785f051\" \u002F>\n\u003C\u002Fp>\n\n## 项目结构\n\n```text\n.\n├── config\u002F                 # 默认配置和示例配置\n├── docs\u002F                   # 架构说明\n├── src\u002Fstory_world\u002F        # 核心代码\n│   ├── agents.py           # Demo \u002F OpenAI \u002F DeepSeek Agent\n│   ├── cli.py              # 命令行入口\n│   ├── generator.py        # 世界生成与节点扩展\n│   ├── story.py            # 故事会话管理\n│   ├── characters.py       # 角色生成与更新\n│   ├── storage.py          # 世界文件存储\n│   └── web.py              # 本地 Web UI\n├── tests\u002F                  # 单元测试\n└── runtime\u002F                # 运行时生成内容，默认不提交\n```\n\n更细的模块边界见 [docs\u002FARCHITECTURE.md](docs\u002FARCHITECTURE.md)。\n\n## 环境要求\n\n- Python `3.10+`\n- 推荐使用虚拟环境\n- 可选：OpenAI API Key，用于真实 GPT 生成\n- 可选：DeepSeek API Key，用于 DeepSeek 生成\n\n本地 Demo Agent 不需要任何外部 API，适合先验证流程。\n\n## 安装\n\n克隆仓库：\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fwailers9\u002Fbragi.git\ncd bragi\n```\n\n创建虚拟环境：\n\nmacOS \u002F Linux：\n\n```bash\npython3 -m venv .venv\nsource .venv\u002Fbin\u002Factivate\n```\n\nWindows PowerShell：\n\n```powershell\npython -m venv .venv\n.\\.venv\\Scripts\\Activate.ps1\n```\n\n安装项目：\n\n```bash\npython -m pip install -U pip\npython -m pip install -e .\n```\n\n如果你要运行测试：\n\n```bash\npython -m pip install pytest\npython -m pytest -q\n```\n\n## 配置 API Key\n\n### OpenAI\n\nmacOS \u002F Linux：\n\n```bash\nexport OPENAI_API_KEY=\"你的 OpenAI API Key\"\n```\n\nWindows PowerShell：\n\n```powershell\n$env:OPENAI_API_KEY=\"你的 OpenAI API Key\"\n```\n\n使用 OpenAI 时，默认模型写在 `config\u002Fworldgen.json`：\n\n```json\n{\n  \"agent\": {\n    \"default_agent\": \"demo\",\n    \"model\": \"gpt-5.5\",\n    \"reasoning_effort\": null,\n    \"temperature\": 0.95,\n    \"top_p\": 0.98\n  }\n}\n```\n\n你也可以在命令里临时覆盖：\n\n```bash\n--agent openai --model gpt-5.5\n```\n\n### DeepSeek\n\nmacOS \u002F Linux：\n\n```bash\nexport DEEPSEEK_API_KEY=\"你的 DeepSeek API Key\"\n```\n\nWindows PowerShell：\n\n```powershell\n$env:DEEPSEEK_API_KEY=\"你的 DeepSeek API Key\"\n```\n\n使用方式：\n\n```bash\n--agent deepseek --model deepseek-chat\n```\n\n### 模型建议\n\n建议优先使用 `deepseek-chat` 写故事。它的成本和速度更适合长篇互动生成，也更适合频繁续写、更新角色和推进事件。\n\n如果你想要更强的世界观搭建能力，可以先用 `gpt-5.5` 生成世界、初始化时间和空间节点，再用 `deepseek-chat` 承担后续故事续写：\n\nmacOS \u002F Linux：\n\n```bash\nPYTHONPATH=src python -m story_world.cli init-demo \\\n  --agent openai \\\n  --model gpt-5.5 \\\n  --prompt \"一个被月亮潮汐撕裂的海上王国\" \\\n  --time-id 1,2,3 \\\n  --space-id 2,1,1 \\\n  --protagonist \"年轻的灯塔学徒\"\n\nPYTHONPATH=src python -m story_world.cli story-start \\\n  --agent deepseek \\\n  --model deepseek-chat \\\n  --world-id \"\u003Cworld_id>\" \\\n  --time-id 1,2,3 \\\n  --space-id 2,1,1 \\\n  --protagonist \"年轻的灯塔学徒\"\n```\n\nWindows PowerShell：\n\n```powershell\n$env:PYTHONPATH=\"src\"\npython -m story_world.cli init-demo `\n  --agent openai `\n  --model gpt-5.5 `\n  --prompt \"一个被月亮潮汐撕裂的海上王国\" `\n  --time-id 1,2,3 `\n  --space-id 2,1,1 `\n  --protagonist \"年轻的灯塔学徒\"\n\npython -m story_world.cli story-start `\n  --agent deepseek `\n  --model deepseek-chat `\n  --world-id \"\u003Cworld_id>\" `\n  --time-id 1,2,3 `\n  --space-id 2,1,1 `\n  --protagonist \"年轻的灯塔学徒\"\n```\n\n## 配置文件\n\n默认会读取：\n\n```text\nconfig\u002Fworldgen.json\n```\n\n如果你想保留自己的配置，可以复制示例：\n\nmacOS \u002F Linux：\n\n```bash\ncp config\u002Fworldgen.example.json config\u002Fworldgen.local.json\n```\n\nWindows PowerShell：\n\n```powershell\nCopy-Item config\\worldgen.example.json config\\worldgen.local.json\n```\n\n然后运行命令时指定：\n\n```bash\n--config config\u002Fworldgen.local.json\n```\n\n常用配置项：\n\n- `runtime.worlds_root`：生成世界保存目录，默认 `runtime\u002Fworlds`\n- `space_depth`：空间树深度\n- `history_depth`：历史树深度\n- `space_default_branching`：每层空间分支数量\n- `history_default_branching`：每层历史分支数量\n- `world_generation.personal_requirements`：世界生成偏好\n- `story.generation_requirements`：故事写作风格要求\n- `story.min_story_chars`：单段故事最低字数\n- `story.story_length_mode`：故事长度模式，支持 `normal`、`long`、`infinite`\n- `story.update_cadence`：时间和地点更新节奏，支持 `slower`、`normal`、`faster`\n\n## 快速开始：本地 Demo\n\n不配置 API，也可以先跑通完整世界初始化流程：\n\nmacOS \u002F Linux：\n\n```bash\nPYTHONPATH=src python -m story_world.cli init-demo \\\n  --prompt \"一个漂浮群岛上的魔法工业时代\" \\\n  --time-id 2,1,3 \\\n  --space-id 1,2,2 \\\n  --protagonist \"年轻的飞艇机械师\"\n```\n\nWindows PowerShell：\n\n```powershell\n$env:PYTHONPATH=\"src\"\npython -m story_world.cli init-demo `\n  --prompt \"一个漂浮群岛上的魔法工业时代\" `\n  --time-id 2,1,3 `\n  --space-id 1,2,2 `\n  --protagonist \"年轻的飞艇机械师\"\n```\n\n输出里会包含 `world_id`，后续扩展世界和写故事都要用它。\n\n运行后生成内容会保存在：\n\n```text\nruntime\u002Fworlds\u002F\u003Cworld_id>\u002F\n```\n\n## 一条命令开始写故事\n\n用真实 Agent 创建世界并开始故事：\n\nmacOS \u002F Linux：\n\n```bash\nPYTHONPATH=src python -m story_world.cli play \\\n  --agent deepseek \\\n  --model deepseek-chat \\\n  --prompt \"一个被月亮潮汐撕裂的海上王国\" \\\n  --protagonist \"年轻的灯塔学徒\" \\\n  --world-requirements \"底层规则简单易懂，但必须有强烈的新鲜感\" \\\n  --generation-requirements \"减少景物堆砌，像小说一样清楚、生动、有悬念\"\n```\n\nWindows PowerShell：\n\n```powershell\n$env:PYTHONPATH=\"src\"\npython -m story_world.cli play `\n  --agent deepseek `\n  --model deepseek-chat `\n  --prompt \"一个被月亮潮汐撕裂的海上王国\" `\n  --protagonist \"年轻的灯塔学徒\" `\n  --world-requirements \"底层规则简单易懂，但必须有强烈的新鲜感\" `\n  --generation-requirements \"减少景物堆砌，像小说一样清楚、生动、有悬念\"\n```\n\n`play` 默认会进入互动模式。生成一段故事后，你可以直接输入下一步方向，例如：\n\n```text\n调查昨夜消失的船队\n```\n\n输入 `q` 退出。\n\n只生成一段并退出：\n\nmacOS \u002F Linux：\n\n```bash\nPYTHONPATH=src python -m story_world.cli play \\\n  --agent openai \\\n  --prompt \"一座建在巨兽背上的移动城市\" \\\n  --protagonist \"被流放的城市医生\" \\\n  --once\n```\n\nWindows PowerShell：\n\n```powershell\n$env:PYTHONPATH=\"src\"\npython -m story_world.cli play `\n  --agent openai `\n  --prompt \"一座建在巨兽背上的移动城市\" `\n  --protagonist \"被流放的城市医生\" `\n  --once\n```\n\n打印完整内部上下文：\n\nmacOS \u002F Linux：\n\n```bash\nPYTHONPATH=src python -m story_world.cli play \\\n  --agent openai \\\n  --world-id \"\u003Cworld_id>\" \\\n  --protagonist \"年轻的灯塔学徒\" \\\n  --full\n```\n\nWindows PowerShell：\n\n```powershell\n$env:PYTHONPATH=\"src\"\npython -m story_world.cli play `\n  --agent openai `\n  --world-id \"\u003Cworld_id>\" `\n  --protagonist \"年轻的灯塔学徒\" `\n  --full\n```\n\n## Web 可视化界面\n\n启动本地 Web UI：\n\nmacOS \u002F Linux：\n\n```bash\nPYTHONPATH=src python3 -m story_world.web --host 127.0.0.1 --port 8765\n```\n\nWindows PowerShell：\n\n```powershell\n$env:PYTHONPATH=\"src\"\npython -m story_world.web --host 127.0.0.1 --port 8765\n```\n\n打开：\n\n```text\nhttp:\u002F\u002F127.0.0.1:8765\n```\n\nWeb UI 可以完成：\n\n- 创建世界\n- 初始化时间、空间和角色\n- 生成当前故事片段\n- 提交用户方向继续剧情\n- 查看当前时间路径、空间路径、节点摘要、角色变化、事件更新和管理器提示\n\n## 常用 CLI 流程\n\n### 1. 创建世界并初始化当前位置\n\nmacOS \u002F Linux：\n\n```bash\nPYTHONPATH=src python -m story_world.cli init-demo \\\n  --agent openai \\\n  --prompt \"一个所有影子都拥有记忆的王国\" \\\n  --time-id 1,2,3 \\\n  --space-id 2,1,1 \\\n  --protagonist \"失去影子的书记官\"\n```\n\nWindows PowerShell：\n\n```powershell\n$env:PYTHONPATH=\"src\"\npython -m story_world.cli init-demo `\n  --agent openai `\n  --prompt \"一个所有影子都拥有记忆的王国\" `\n  --time-id 1,2,3 `\n  --space-id 2,1,1 `\n  --protagonist \"失去影子的书记官\"\n```\n\n### 2. 扩写某个历史节点\n\nmacOS \u002F Linux：\n\n```bash\nPYTHONPATH=src python -m story_world.cli enrich-history \\\n  --agent openai \\\n  --world-id \"\u003Cworld_id>\" \\\n  --prompt \"一个所有影子都拥有记忆的王国\" \\\n  --time-id 1,2,2\n```\n\nWindows PowerShell：\n\n```powershell\n$env:PYTHONPATH=\"src\"\npython -m story_world.cli enrich-history `\n  --agent openai `\n  --world-id \"\u003Cworld_id>\" `\n  --prompt \"一个所有影子都拥有记忆的王国\" `\n  --time-id 1,2,2\n```\n\n### 3. 扩写某个空间节点\n\nmacOS \u002F Linux：\n\n```bash\nPYTHONPATH=src python -m story_world.cli enrich-space \\\n  --agent openai \\\n  --world-id \"\u003Cworld_id>\" \\\n  --prompt \"一个所有影子都拥有记忆的王国\" \\\n  --space-id 2,1,2\n```\n\nWindows PowerShell：\n\n```powershell\n$env:PYTHONPATH=\"src\"\npython -m story_world.cli enrich-space `\n  --agent openai `\n  --world-id \"\u003Cworld_id>\" `\n  --prompt \"一个所有影子都拥有记忆的王国\" `\n  --space-id 2,1,2\n```\n\n### 4. 构建故事上下文\n\nmacOS \u002F Linux：\n\n```bash\nPYTHONPATH=src python -m story_world.cli build-context \\\n  --world-id \"\u003Cworld_id>\" \\\n  --time-id 1,2,3 \\\n  --space-id 2,1,1\n```\n\nWindows PowerShell：\n\n```powershell\n$env:PYTHONPATH=\"src\"\npython -m story_world.cli build-context `\n  --world-id \"\u003Cworld_id>\" `\n  --time-id 1,2,3 `\n  --space-id 2,1,1\n```\n\n### 5. 初始化角色\n\nmacOS \u002F Linux：\n\n```bash\nPYTHONPATH=src python -m story_world.cli init-characters \\\n  --agent openai \\\n  --world-id \"\u003Cworld_id>\" \\\n  --time-id 1,2,3 \\\n  --space-id 2,1,1 \\\n  --protagonist \"失去影子的书记官\" \\\n  --others \"生成2到4个和主线强相关的角色\"\n```\n\nWindows PowerShell：\n\n```powershell\n$env:PYTHONPATH=\"src\"\npython -m story_world.cli init-characters `\n  --agent openai `\n  --world-id \"\u003Cworld_id>\" `\n  --time-id 1,2,3 `\n  --space-id 2,1,1 `\n  --protagonist \"失去影子的书记官\" `\n  --others \"生成2到4个和主线强相关的角色\"\n```\n\n### 6. 开始故事会话\n\nmacOS \u002F Linux：\n\n```bash\nPYTHONPATH=src python -m story_world.cli story-start \\\n  --agent openai \\\n  --world-id \"\u003Cworld_id>\" \\\n  --time-id 1,2,3 \\\n  --space-id 2,1,1 \\\n  --protagonist \"失去影子的书记官\" \\\n  --generation-requirements \"像通俗幻想小说，节奏快，人物行动明确\"\n```\n\nWindows PowerShell：\n\n```powershell\n$env:PYTHONPATH=\"src\"\npython -m story_world.cli story-start `\n  --agent openai `\n  --world-id \"\u003Cworld_id>\" `\n  --time-id 1,2,3 `\n  --space-id 2,1,1 `\n  --protagonist \"失去影子的书记官\" `\n  --generation-requirements \"像通俗幻想小说，节奏快，人物行动明确\"\n```\n\n### 7. 提交选择并继续\n\nmacOS \u002F Linux：\n\n```bash\nPYTHONPATH=src python -m story_world.cli story-choose \\\n  --agent openai \\\n  --session-id \"\u003Csession_id>\" \\\n  --choice-text \"去档案馆寻找第一任国王的影子记录\"\n```\n\nWindows PowerShell：\n\n```powershell\n$env:PYTHONPATH=\"src\"\npython -m story_world.cli story-choose `\n  --agent openai `\n  --session-id \"\u003Csession_id>\" `\n  --choice-text \"去档案馆寻找第一任国王的影子记录\"\n```\n\n## 数据如何保存\n\n每个世界都有独立目录：\n\n```text\nruntime\u002Fworlds\u002F\u003Cworld_id>\u002F\n```\n\n常见文件：\n\n```text\nruntime\u002Fworlds\u002F\u003Cworld_id>\u002Fmanifest.json\nruntime\u002Fworlds\u002F\u003Cworld_id>\u002Findex.json\nruntime\u002Fworlds\u002F\u003Cworld_id>\u002Fusage.json\nruntime\u002Fworlds\u002F\u003Cworld_id>\u002Fevents\u002F\u003Chistory_path>.json\nruntime\u002Fworlds\u002F\u003Cworld_id>\u002Fsessions\u002F\u003Csession_id>.json\n```\n\n时间节点会按路径嵌套保存。比如 `1,3,3` 可能保存为：\n\n```text\nruntime\u002Fworlds\u002F\u003Cworld_id>\u002Fhistory\u002F1.0.0\u002F1.3.0\u002F1.3.3\u002Fnode.json\n```\n\n空间节点会挂在当前时间节点下面。比如当前时间是 `1,3,3`，空间是 `2,1,1`：\n\n```text\nruntime\u002Fworlds\u002F\u003Cworld_id>\u002Fhistory\u002F1.0.0\u002F1.3.0\u002F1.3.3\u002Fspace\u002F2.0.0\u002F2.1.0\u002F2.1.1\u002Fnode.json\n```\n\n`index.json` 会记录节点状态：\n\n- `summary`：只有摘要\n- `full`：完整节点\n- `pending_agent_completion`：等待 Agent 补全\n\n## 调试与 token 用量\n\n每次 Agent 调用都会记录用量：\n\n```text\nruntime\u002Fworlds\u002F\u003Cworld_id>\u002Fusage.json\n```\n\n如果 `config\u002Fworldgen.json` 中启用：\n\n```json\n{\n  \"story\": {\n    \"debug_story_agent_input\": true,\n    \"print_story_agent_input\": false\n  }\n}\n```\n\n故事 Agent 的输入会保存到：\n\n```text\nruntime\u002Fworlds\u002F\u003Cworld_id>\u002Fdebug\u002Fstory_agent_input_turn_0000.txt\n```\n\n如果你想直接在终端打印完整提示词，可以加：\n\n```bash\n--print-story-agent-input\n```\n\n## 开发\n\n安装开发依赖：\n\n```bash\npython -m pip install -e .\npython -m pip install pytest\n```\n\n运行测试：\n\n```bash\npython -m pytest -q\n```\n\n运行 Web UI：\n\nmacOS \u002F Linux：\n\n```bash\nPYTHONPATH=src python3 -m story_world.web --host 127.0.0.1 --port 8765\n```\n\nWindows PowerShell：\n\n```powershell\n$env:PYTHONPATH=\"src\"\npython -m story_world.web --host 127.0.0.1 --port 8765\n```\n\n## 适合用来做什么\n\n- 架空世界设定生成器\n- 长篇小说或跑团世界观辅助工具\n- 互动小说原型\n- AI Agent 叙事系统实验\n- 世界状态、角色状态、事件状态持续演化的故事沙盒\n","Bragi 是一个面向架空世界故事创作者的 AI 引擎，能够从一句设定出发自动生成层层嵌套的历史、地理、角色关系与事件网络，并持续写出贴合世界观的剧情。项目采用时间与空间双树结构管理节点，按需生成并补全世界资料，确保故事创作过程中的一致性和连贯性。它支持 CLI 与可视化界面，用户可以轻松创建和扩展幻想世界，适用于构建架空大陆、未来都市、魔法王朝等复杂背景下的长篇连载故事。","2026-06-11 04:01:46","CREATED_QUERY"]