本页目录

LocalGPT：Rust 桌面应用，把文档/歌曲/剧本变成可行走的 3D 世界

localgpt · localgpt-app/localgpt

LocalGPT 是 Rust 桌面应用，基于 Open World Format。按仓库描述，文档、歌曲、剧本或提示词可变成可「行走」的 3D 世界（.world 包），用户与自己的 coding agent 可在其中共同编辑，变更可记录、归属、撤销与分支。项目使用 Bevy，REA...

其他 Godot JavaScript 存档系统音频系统 UI 系统高级

★ Stars 1,128 Forks 105 License Apache-2.0 更新 2026-11-14

GitHub 官方仓库在线 Demo Releases

国内开发环境适配

Windows

官方声明支持

Linux

官方声明支持

macOS

官方声明支持

引擎 / 框架：Godot 暂无中文教程标记未标记站长实测

从 crates.io / npm / Homebrew 安装依赖外网可达性较差时，可考虑配置 crates.io 与 npm 镜像；`cargo xtask fetch-assets` 需下载约 522 MB 的 CC0 资产包（Poly Haven 模型），国内网络可能较慢或需代理，具体源地址待核验。从源码构建需 Node 22 构建 `crates/app/ui` 前端页面，Linux 还需 pkg-config 与 Bevy 相关系统库（libasound2-dev、libudev-dev、libwayland-dev、libxkbcommon-dev、libfontconfig1-dev、libdbus-1-dev）。

中文项目介绍

LocalGPT 是一个用 Rust 编写的桌面应用，围绕 Open World Format（开放世界格式）构建。它要解决的事情很具体：把一份文档、一首歌、一个剧本或一句提示词，变成一个可以「走进去」的 .world 世界包；同时在同一个窗口旁边开出终端标签页，让你自己惯用的 coding agent 从外部一起编辑这个世界。

按 README 的说明，一个 world 不只是场景，它还是一个带历史的软件包：人可以在窗口里改，agent 可以在窗口外改，每一次改动都会被记录、标注作者、可撤销、可分支。项目本身不运行任何模型、不调用外部服务、不持有密钥——agent 由你自己提供，LocalGPT 只负责世界与历史。许可证为 Apache 2.0。

技术架构分析

安装与构建

README 给出三条安装路线：

预编译：npm install -g localgpt（macOS/Linux/Windows，得到 CLI 与 MCP shim）；brew install localgpt-app/tap/localgpt；macOS 上 brew install --cask localgpt-app/tap/localgpt 会装上 LocalGPT.app 与 localgpt。
从 crates.io：cargo install localgpt-gen（世界构建器）与 cargo install localgpt（world 子命令、MCP shim、previs）。注意桌面应用本身不以 crate 形式发布，只提供构建产物。
从源码：克隆仓库后先在 crates/app/ui 里 npm ci && npm run build（Node 22，用于配套的手机/平板页面），再 cargo run -p localgpt-app；可直接带参数启动：--doc notes.md、--song track.mp3、--world scene-1.world。cargo xtask bundle 生成 macOS 的 LocalGPT.app。

另外有一个每台机器只需下载一次的共享资产步骤 cargo xtask fetch-assets，拉取约 522 MB 的 CC0 资产包（Poly Haven 模型）。环境要求为 Rust stable、edition 2024（即 1.85 或更新）；Linux 上桌面相关 crate 还需要 Bevy 的系统依赖：libasound2-dev libudev-dev libwayland-dev libxkbcommon-dev libfontconfig1-dev libdbus-1-dev pkg-config。

技术要点与学习建议

项目把「世界」抽象成可与渲染、编辑、同步、导出、音频解耦的数据层，再用 Bevy 负责渲染、egui 负责原生 UI，很适合研究 ECS 与即时编辑的结合；ops.jsonl 的日志折叠模型、按作者撤销、分支与 --at 提交，是版本化协作编辑的一个清晰实现样本。Previs 强调确定性与可交付（board.html、shotlist.csv、逐场景 .world 压缩包），也展示了「不依赖模型」的工程化路径。想上手可从 CLI 的 localgpt world init / submit / log / verify 熟悉格式，再读 crates/world-* 与桌面 shell 代码。

构建时需注意 Rust 1.85+、Node 22（构建配套前端页面）以及一次性的大体积 CC0 资产下载；Linux 需先装齐 Bevy 的系统依赖。

补充说明

仓库构成

仓库不是一个单体的应用，而是多个 crate 与站点组成的组合体：

LocalGPT 桌面应用（crates/app）：一个窗口承载全部模式——由提示词生成世界（Gen）、由 Markdown 文档生成世界（Document）、由歌曲生成世界（Verse），或把任意 .world 包作为实时画布打开。
LocalGPT Gen（crates/gen，cargo install localgpt-gen）：独立的世界构建器，README 提到它通过 MCP 向 Claude Desktop、Claude Code、Codex、Gemini CLI 及编辑器提供 88 个工具，并提供中继以便 agent 驱动你正在看的窗口，还支持实时画布、无头运行、局域网或中继上的协作会话。
Previs（crates/previs，localgpt previs）：把剧本（PDF、Final Draft、Fountain、Markdown）转成逐场景的 .world，含布景、角色替身与镜头覆盖，并可输出可打印看板与镜头表。确定性执行，不使用模型。
localgpt 命令行（crates/cli）：localgpt world 提供 commit、undo、log、tips、verify、lint、find、link、screenshot；localgpt world mcp 是把开放世界的工具通过 stdio 暴露给任意 MCP agent 的 shim；另有 localgpt previs。无需模型、密钥或配置文件。
世界相关 crate（crates/world-*）：world-types、world-bevy、world-audio、world-export、world-sync、world-editor、world-agent，所有应用共用一套格式，底层是 Open World Format 的参考 crate。
站点目录：website*/ 对应 localgpt.app（文档站）、localgpt.md（previs）、localgpt.world（画廊与网页查看器）、localgpt.rs（开发日志）。

桌面应用：一个窗口，多种模式

localgpt-app 把 Gen 的世界用 Bevy 渲染进原生的 eframe/egui 面板（crates/app/src/shell），旁边是可以放你自己 coding agent 的终端。每个标签页都是以当前打开的文件夹为工作目录的普通登录 shell，你跑哪个 agent 都行；应用本身不跑语言模型、不持密钥、不认识具体 agent 名字，也不管理 agent 配置。

文档模式：世界旁边是大纲与编辑器；停止输入后不久文件保存、世界就地重建，只改动文字有变化的部分。光标移入某节，镜头飞过去；点击世界里的物体，对应章节回到视野。草稿之外的环境来自文档旁的 sidecar，由处理该文件的 agent 写入。
歌曲模式：Verse 在设备端做节奏、节拍网格、段落、能量曲线与情绪分析，据此挑选布置世界；原声在共享混音器上播放，世界的调制跟随音乐，世界下方的走带可暂停。无模型、无密钥、无上传。
包模式：.world 文件夹作为实时画布打开，窗口持有权威并对外提供该文件夹的 API，历史以图的形式绘制、可单步、可播放。

原生面板支持 macOS、Windows 与 Linux，README 亦坦承后两者较新、验证较少。

世界即包：从外部协同编辑

一个 .world 就是一个文件夹：manifest.json 是「此刻的世界」，ops.jsonl 是历来所有改动，assets/ 按内容哈希存放网格、贴图与声音，AGENTS.md 告诉 agent 该怎么改。任一版本的 state 都是把日志折叠到基底上的结果，manifest.json 只是头部那次折叠写下来的样子；渲染、编辑、撤销、分支、重放与多人都是对同一份历史的读取。

以 localgpt-gen --live scene-1.world（或 localgpt-app --world ...）打开后，任何能读该文件夹的 agent 都能改动世界：向 .live/endpoint.json 里的 API 提交一批 ops，整批要么全部提交，要么逐条给出可据此行动的原因后被拒绝。最省事的接法是用 shim：localgpt world mcp scene-1.world 再 claude mcp add。人也能编辑：视口里有移动/旋转/缩放把手与吸附，每个手势同样是一批、一条历史记录，Cmd+Z 撤销且按作者区分；带 --review 时 agent 的批次会先在画布上预览再由你接受或拒绝。历史是一棵树，向更早条目提交会开出分支；可选 --git 让每批成为一个 commit，verify 校验折叠结果仍等于 manifest；直接改 manifest.json 会被还原并记录。无窗口的一半是 localgpt world，同一套权威，适合脚本与 CI。