mojulo

Mojulo

Mojulo 是面向编码 Agent 的3D 工厂与媒体工作室：一个 MCP 服务，可运行在 Agent 所在的任何地方，无论是你的机器，还是 Agent 为自己创建的一次性 Linux 环境。你已经在使用的 Agent（Claude Code、Codex、任何 MCP 主机，或可打开 Linux 环境的聊天应用：Claude、带有 Codex 的 ChatGPT、Grok、Meta Muse、Google AI Studio）都可以通过对话制作可供游玩、打印、阅读、聆听和观看的内容（游戏、物件、可步行探索的世界、图片、乐谱），而保存下来的是源文件，而非网格。每个产物都是一个小巧且确定性的配方：几百字节的 JSON，或一段 OpenSCAD 程序；内核可将其编译回相同的几何体，每次读取的结果都相同（在同一平台上逐字节一致），并可导出为 Godot、Blender、Unity、Unreal、glTF、OpenUSD，或按真实比例制作的可打印 STL / 3MF。它足够小巧，可以从临时环境带回本地，再在自己的磁盘上重新生成。它是编译器，而非生成器：你可以像编辑和比较代码一样编辑和比较配方，渲染结果则可以随时丢弃。无需 API 密钥，无需账户，也不会向外部发送遥测数据。你的 Agent 负责思考；mojulo 负责保存状态和处理几何体。

快速开始

npx mojulo init

需要 Node 22.14+ 和支持 MCP 的编码 Agent（Claude Code 或 Codex；Claude Desktop 也可以）。init 会查找你机器上的主机，每个主机只询问一次，然后打开 http://localhost:3001 中的仪表板。所有内容都会放在 ~/.mojulo/ 中。接着打开一个新的 Agent 会话并询问：“这是什么？”

在 Claude Code 中，你也可以安装插件：/plugin marketplace add zombico/mojulo，然后运行 /plugin install mojulo@mojulo。它会启动固定在一个版本上的同一服务（plugins/mojulo）。插件版本不包含用于 AI 图像、语音和网格生成器的交接工具，也不会自行下载浏览器、ffmpeg 或搜索模型。Claude Code 中请使用插件或 init，不要两者都用：注册两次会运行两个服务。

首次安装占用较大：npx 会拉取一个约 7 MB 的包，连同依赖一起安装后，磁盘占用约为 227 MB，npm 缓存约为 140 MB（下载量约 79 MB；数据是在一台 macOS arm64 机器上对 3.0.0 测得，冷启动响应约需 4.5 秒，几乎全是 npm 安装时间）。最大的部分是 node-web-audio-api（音频）、manifold-3d（精确布尔运算）和 better-sqlite3。仪表板是一个单独的包，首次打开时才会获取；本地搜索模型则通过可选的 mojulo install recall 安装（没有它时，semantic_search 会按词法排序）。清单中的内容都不会自行访问网络；各项依赖的说明见 docs/tech-requirements.md。已在 macOS（Apple Silicon）和 Claude Code 下的原生 Windows 上验证（init 和首次渲染）。在 Linux x64 上，测试套件会在 CI 中运行；下文的 Agent 沙箱路径也已在 Claude 应用和网页、使用 Codex 的 ChatGPT 工作模式、Grok 聊天、Meta Muse 和 Google AI Studio 中实际运行，直至生成模型并导出。

# Claude Code (--scope user makes mojulo available in every project):
claude mcp add --scope user mojulo -- npx -y mojulo

# Codex: add to ~/.codex/config.toml
[mcp_servers.mojulo]
command = "npx"
args = ["-y", "mojulo"]

// Claude Desktop: add under "mcpServers" in claude_desktop_config.json, then restart.
// If it fails with "spawn npx ENOENT", replace "npx" with the absolute path from `which npx`.
"mojulo": { "command": "npx", "args": ["-y", "mojulo"] }

运行位置，以及可以添加的三项内容

Mojulo 会在 Agent 运行的任何地方运行；在一个地方生成的配方，在另一个地方重新生成时，几何形状也相同。两种形态，一次安装。

在 Agent 的沙箱中运行，不需要在你的机器上安装任何东西。 只需对 Agent 说一句话，就能在它为自己准备的 Linux 沙箱中安装 mojulo：

• Claude 应用（macOS、Windows、网页、iOS）；Grok 聊天；Google AI Studio；Meta Muse（iOS、网页、macOS 应用，三者共用一个会话）：打开一个 Linux 沙箱，并在其中安装 mojulo npm 包。
• ChatGPT（包含 Codex）：在工作模式下，打开一个 Linux 沙箱，并在其中安装 mojulo npm 包。

这些平台都已按此方式运行：从输入这句话开始，直到生成模型并交回导出文件。你会获得相同的配方和相同的导出文件：导出结果会注明此主机的入口、资源页面、PR、文件卡片或 Muse 的资源库。沙箱没有可供你访问的仪表板；将场景烘焙为 PNG 需要浏览器，而平台可能不允许下载浏览器；并且大多数主机会在会话结束时清除沙箱。因此，请索取资源包（一个 zip：world.html、网格、用于按实际尺寸制作物体的打印 STL、recipe.json、README），并保存配方。Meta Muse 是个例外：它的所有客户端共用一个 VM，因此 ~/.mojulo 会在不同对话间保留。没有 MCP 客户端的沙箱不会发送 initialize，因此请让 Agent 先运行 npx mojulo orient：它会输出 MCP 客户端连接时收到的内容，并将其转换为 shell 中可用的形式，同时指向路由索引。Claude 的沙箱用这种方式制作了一个按实际尺寸构建的 47 部件手机，并交回了 glTF；Grok 聊天的沙箱则通过 shell 生成了一座城市。这些沙箱中也可以安装 Blender。 在你的计算机上：macOS、Windows、Linux。 npx mojulo init 会将 mojulo 接入它找到的 Agent，在 localhost:3001 打开仪表板，将所有内容保存在 ~/.mojulo/ 下，并探测你的 PATH，查找可选的本地工作器（Blender、切片软件、OpenSCAD、游戏引擎）。这是完整的工作流程，也是来自云端的配方回到本地的地方。

哪些 Agent 已在哪里运行。 持久（你的计算机，或会保留 ~/.mojulo/ 的云端计算机） · 临时（Web Agent 的一次性 Linux 云端计算机；请保留配方）。空白表示尚未验证，不代表“无法运行”。

Agent	macOS	Windows	Web Agent Linux 云端计算机（无头）
Claude Code
Claude app（macOS、Windows、web、iOS）
ChatGPT（工作模式；Codex）	Codex
Hermes Agent
Grok（Build；聊天）	Build
Meta Muse（iOS、web、macOS 应用；跨平台共用一个会话）
Google AI Studio

有两项可选功能，在这两个位置的选择相同：

不带参数运行 mojulo install 会显示这两项中哪些已安装。

自 3.0 起，聊天机器人工厂不再是 mojulo 的一部分，并将迁移到独立项目。包含该功能的早期 2.x 版本已无人维护，并存在已知安全问题（SECURITY.md）。现在运行 mojulo install chatbot 不会安装任何内容，只会打印此通知。

从 2.x 升级？ 请先阅读从 2.x 升级：未锁定版本的 npx mojulo 会在下次启动时升级到 3.0，而 3.0 会重新加密已保存的服务提供商密钥，因此 2.x 将无法再读取这些密钥。

对它说的五句话

每个示例都是一句对 Agent 说的话、它调用的工具，以及最终保存的配方。以下示例均可在无需密钥和离线的情况下运行。

1. “用 OpenSCAD 为我设计一个 Raspberry Pi 4 外壳托盘”

Agent 调用 mint_solid { kind: 'scad' }，程序就是配方，并按原样存储：

board_w = 85; board_d = 56; clear = 1; wall = 2; floor_t = 2; wall_h = 12;
holes = [[3.5, 3.5], [61.5, 3.5], [3.5, 52.5], [61.5, 52.5]];   // the Pi's M2.5 pattern
module rounded_box(w, d, h, r) { hull() for (x = [r, w - r], y = [r, d - r]) translate([x, y, 0]) cylinder(r = r, h = h, $fn = 48); }
module tray() {
  color("#3a3f4b") difference() {
    rounded_box(board_w + 2 * (clear + wall), board_d + 2 * (clear + wall), floor_t + wall_h, 3);
    translate([wall, wall, floor_t]) rounded_box(board_w + 2 * clear, board_d + 2 * clear, wall_h + 1, 1.5);
    translate([board_w + 2 * clear + wall - 1, wall + 2, floor_t + 3]) cube([wall + 2, board_d + 2 * clear - 4, wall_h]);   // USB / Ethernet
    translate([wall + clear + 5, -1, floor_t + 3]) cube([55, wall + 2, wall_h]);                                            // USB-C, HDMI, audio
  }
}
module standoffs() {
  color("#c9a227") for (p = holes) translate([wall + clear + p[0], wall + clear + p[1], floor_t])
    difference() { cylinder(d = 6, h = 3, $fn = 32); translate([0, 0, -1]) cylinder(d = 2.5, h = 5, $fn = 24); }
}

其中 parts: { tray: 'tray();', standoffs: 'standoffs();' }。OpenSCAD 本身会在每次读取时对其进行网格化处理：它在进程内以 WebAssembly 运行，并使用 Manifold 后端，因此布尔运算精确，所有边缘都很锐利。color() 用于着色；每个命名部件都是一个渲染组，movers 中的铰链可以让它摆动。同一个引用用于轨道视图、.glb、引擎资源包，以及按原样制作的 91 × 62 × 14 mm model.stl；model.scad 则会原样返回源代码。使用 update_sketch 更改 wall_h 后，读数会指出发生变化的那个部件。对于 OpenSCAD 无法表达的内容，例如融合连接、带笔触的凹痕、带种子的噪声，源代码会调用 mojulo_field("<id>")，并在该位置烘焙由同一配方生成的场实体。

2. “建一个 20 × 24 ft 的客厅，南墙上要有一扇门”

这就是顶部的 GIF。Agent 调用 create_sketch { title, manifest: { kind: 'floorplan', … } }，存储的清单如下：

{ "kind": "floorplan", "width": 24, "height": 28,
  "rooms": [ { "x": 2, "y": 2, "w": 20, "h": 24, "glyph": "L" } ],
  "doors": [ { "x": 12, "y": 26, "room": 0, "edge": "S" } ],
  "furnish": true, "view": "cutaway", "seed": 7 }

L 字形和种子会为其配置家具：沙发、两把椅子、地毯、落地灯和窗户。“在天花板上添加筒灯”会添加 "potLights": true，其他内容不会改变。"levels": [...] 会将其叠成一栋有楼梯贯穿各层楼板的建筑。同一配方可以在浏览器的 /world 中漫游，导出为 .glb，或作为艺术处理资源包发送到 Blender。在 Blender 中，Cycles 烘焙可以将追踪到的光照写回网格自身的顶点颜色，让光照结果能在任何地方运行，且无需运行时成本。

3. “做一张橡木餐桌，并向我展示它是如何组装的”

Agent 调用 mint_solid { kind: 'workbench' } 并提供一个框架，build 会生成构件和接合结构：

{ "units": "mm",
  "frames": [ { "id": "table", "unit": "mm", "explode": 90,
                "build": { "type": "table", "w": 1400, "d": 800, "h": 750, "species": "oak" } } ] }

桌腿通过榫卯结构接合围板，尺寸经过设计，使榫头在桌腿内部不会彼此相碰；桌面则由角码支撑。每个接合处都通过精确内核切割，橡木则由合成原木锯切而成，因此木纹和运动方式都会随切割而变化。explode: 90 会沿每块部件的装配方向将其拉开 90 mm；设为 0，桌子就会组装起来。报告仅供参考，从不拒绝：其中包含每个构件的切割和运动、跨度检查、部件的组装顺序、倾倒风险、五金清单和切割清单。同一个 frames 条目还可以构建带门和抽屉的箱体、带软垫的沙发、木构架、钢结构和砌体结构。将部件收集到一个存储包中，再生成 instruction_manual，即可获得无文字的装配说明页；或者设置 layout: 'kit'，将其平铺打印成模型套件。

4. “按真实比例建一座纽约风格的城市”

Agent 调用 compose_world { base: 'city', seed: 11, overrides: { profile: 'metro', flavor: 'new-york' } }。metro 会按比例构建城市，范围约为 0.8 × 0.5 km；风格参数则决定建筑特色：这里是砖砌公寓楼、消防梯、水箱和装饰艺术风格的阶梯式退台，其他风格还包括 paris、london、tokyo 等。整座城市完全由种子决定：更改种子即可生成新城市，保留种子则可在任何机器上重新生成同一座城市。context: { time: 'night' } 会为城市添加夜景灯光，asset: { monument: 'eiffel-tower' } 则会按真实尺寸放置地标。打开 /world，即可使用 WASD 漫游，或在街道、鸟瞰和天际线视图之间切换。除了 city 之外，还有其他基底：交通枢纽、K-12 校园、火把照明的地牢、行星体、彩绘景观、真实比例地形，以及可漫游的有限群 Cayley 图。

5. “给我做一款卡丁车竞速游戏，然后让我以应用的形式玩它”

design_game 从上到下设计游戏（主角、能力、装备和系统），并通过 run: true 完成每个就绪步骤。关卡是带有游戏目标的世界（到达出口、生存二十秒、赢得比赛）；create_game 将这些关卡、合成的配乐和角色绑定为一款游戏，并使用可在关卡间沿用的类型化存储；只有在每个关卡都通过目标试运行，并完成一场抵达胜利条件的流程后，它才会生成游戏。带机器人对手的竞技场射击游戏、带对手车手的卡丁车竞速游戏、飞行、潜行和节奏游戏都由相同的组件构建而成。

游戏可直接在浏览器中运行：export_game 会生成一个可部署到任意静态托管服务的独立文件夹；target: 'desktop' 则会将其转换为 Electron 应用（离线运行 npm install && npm start；签名由你负责）。各游戏引擎会收到一份转换结果，并附带未能转换内容的报告：target: 'godot' 会生成一个真正的 Godot 4 项目，这是支持最完善的引擎；Unity 和 Unreal 则会获得一个数据包和一个导入器（Unreal 实例）。

**还可以从一句话生成：**摆好姿势的人物或奔跑中的动物，并为 glTF 或 VRM 绑定骨骼；带退台式顶层复式公寓的六层建筑；通过带种子的数学算法合成、无需采样素材的氛围循环音效或完整配乐；根据你展示给 Agent 的照片还原房间布局。完整目录见 docs/tour.md。

适用场景

一份配方，多个目标，全部基于同一个 ref：/api/sketches/<ref>/{svg,scene,world,model.glb,model.stl,model.3mf,model.usdz,model.scad}。每个 URL 都会在请求时确定性地重新生成：在同一平台（操作系统、CPU 和 Node 版本）上，字节级完全一致；在其他平台上，几何形状也只存在浮点舍入误差，因为 V8 的 Math 会因 CPU 和 Node 版本不同而在最后一位产生不同的舍入结果（嵌入的纹理 PNG 压缩后的字节也可能不同，但像素绝不会不同）。每次交接都会附带一份清单，注明哪些内容没有随交付物一同传递。

所有导出均无需安装任何内容；系统会写入打包文件，并在验收方式一栏报告“已跳过”及原因。安装相应引擎后，会增加机器验收环节。验收环节只提供建议并加盖标记，不会拒绝任何内容，也绝不会声称有人亲自查看过。原则：docs/bicycles.md。

留在你机器上的内容

• 配方 存储在 ~/.mojulo/mojulo-lite.db 这一个 SQLite 文件中。渲染结果是派生数据，可以随时丢弃。
• 你的配方集。 save_recipe 会将配方保存到 ~/.mojulo/data/cookbook，其中是本地 git 仓库中的普通 card.md + recipe.json 文件夹，且没有远程仓库；数月后仍可通过 semantic_search 按意图检索。内置的配方集格式相同，并随软件包一同提供，因此每次安装（包括 Agent 环境）都自带关于学习对象、世界、循环、实体、镜头和服装的章节，以及一些全新的类别，无需设置。
• 导出内容是普通文件，可用任何工具打开；导出的 World 页面自带 three.js，除非你指定使用 CDN 版本（cdn: true）。如果你保存过提供方密钥，它们会使用 AES-256-GCM 加密，并通过每次安装专属的密钥存储在 ~/.mojulo/secret.key 中。
• 没有外部遥测。 不会向维护者或分析服务发送任何内容。外发流量包括安装时访问 npm、首次使用时的少量一次性下载（如果没有浏览器，则在明确要求渲染时下载浏览器；首次生成 MP4 时下载 ffmpeg；首次打开仪表板时下载仪表板软件包；运行 mojulo install recall 后下载搜索模型），以及 Agent 请求时进行的更新检查；在 Claude 插件下，浏览器、ffmpeg 和模型不会自动下载。完整列表：docs/tech-requirements.md。
• 本地工具调用日志。 每次工具调用都会记录在同一个 SQLite 文件中：工具名称、耗时、状态、参数名称和大小（不含值）、截断后的错误文本，以及 MCP 客户端名称和会话信息。日志不会离开本机，保留 30 天或 50,000 行；设置 MOJULO_MCP_TELEMETRY=off 可将其关闭。
• 配方可以携带代码。 带有 program（代码入口）的配方使用 JavaScript，并会在渲染时以你的权限运行；请像对待代码一样对待共享配方。

控制平面默认仅供单一操作员使用，且只监听 localhost。stdio MCP 没有网络接口；除非设置 CONTROL_PLANE_MCP_KEY，否则 HTTP MCP 路由会返回 404。不要将其暴露到公共互联网；如需远程访问，请使用隧道或 Tailscale。威胁模型：SECURITY.md。条款及“操作员自行承担后果”的立场：TERMS.md、docs/responsibility-model.md。开源项目 mojulo 将始终采用 Apache-2.0 许可，且不包含外部遥测；如果将来探索托管版 mojulo 云服务，它将是独立的可选产品，本地安装不会因此改变，也不依赖于它。

工作原理

一个 Next.js 应用通过同一个 SQLite 提供两种界面：MCP 服务（npm 包使用 stdio，远程客户端使用 HTTP），供你的 Agent 调用；以及位于 localhost:3001 的仪表板，用于呈现累积的内容。编译器的结构如下：配方是源（参数加上一个 kind），内核是后端，每次读取时都会重新生成配方；每个发射器都是一个目标，拥有自己的坐标系，并负责从原生的 z-up 米制坐标系进行单位转换。对于给定参数，内核的输出是对已生成记录的兼容性承诺，并经过逐字节测试。可选的本地工作器（Blender、slicers、mesh sculptors、ComfyUI、Kokoro）由操作者托管，绝非依赖项；缺少某个工作器只会导致相应环节降级，不会造成任何环节中断。

此外，内置内容默认启用且不会妨碍使用：图表，外部模型绘制的定向图像，出版物和研究笔记本，推理交由你的 Agent 执行的本地应用，以及基于你已有 MCP 构建的工作流。

• docs/tour.md — 完整介绍：mojulo 能做什么，以及适合哪些人
• docs/AGENT-REFERENCE.md — 环、包和工具线、工作流、基底、数据布局
• docs/MCP-ARCHITECTURE.md — 传输、会话绑定、审议界面
• docs/POLYGONIZER-SYNTHESIS.md — 几何基底
• docs/tech-requirements.md — 实测占用、引擎组件、切片器、工作器、平台说明
• docs/local-blender-worker.md、docs/local-slicer-worker.md、docs/local-mesh-worker.md、docs/local-image-worker.md — 可选工作器
• AGENTS.md — 适用于非 Claude 宿主

mojulo/
├── control/        Next.js control plane: MCP server, dashboard, kernels, emitters, runtime supervisor
└── docs/           Concept docs

默认设置的由来

Mojulo 的运行器、函数和功能源自创作者对游戏开发的研究：基于访谈的调研，以及多年对艺术指导和游戏系统制作方式的个人钻研。Claude 帮助将这些研究转化并整合到 mojulo 的系统中，让使用者能够顺畅地使用。mojulo 制作的所有内容，都是由其自身代码根据配方中的参数生成的。它不会反编译游戏，也不会获取游戏素材，更不会随附任何游戏素材。默认设置只是起点：若要超越这些设置，需要不断迭代、调整配方、提供你自己的参考资料、查看渲染结果并进行修改。

贡献

由一位维护者维护，不提供 SLA。最简单的贡献方式是提交一条配方集条目：新增一个包含卡片和配方的文件夹，或为一种全新类型编写纯构建器，无需修改核心代码。在核心部分，我们欢迎问题报告（附上可精确复现问题的配方）、正确性修复、翻译和测试；会改变 mojulo 工作方式的概念性 PR 可能会被搁置，而分叉则始终敞开大门。直言不讳：维护者只有一人，大多数审阅工作都借助 AI 完成。完整立场和开放请求请参阅：CONTRIBUTING.md。

许可证

Apache License 2.0