别动脑，喊出你的想法--- 剩下的交给乌萨奇
给孩子和家长一起开发的乌萨奇小屋 3D 造物工作台。界面使用 TypeScript / React / Three.js，桌面使用 Electron，造物引擎使用 Python。代码按功能拆分，约定见 AGENTS.md。
当前版本为 0.1.2。直接打开 release/YaHa-Craft-0.1.2-Windows.exe。EXE、桌面窗口与网页标签统一使用乌萨奇应用图标。角色插画、小屋与默认模型已换成乌萨奇；旧内置示例会新增一个主题版本，原版本仍可回退。主题素材、图标设计要求与生成来源见 public/art/usagi/README.md。
本项目已配置本地开发环境。在目录中运行 pnpm dev 打开桌面版；pnpm dev:web 打开浏览器版，地址 http://127.0.0.1:5173。如果命令行找不到 pnpm，可双击 启动呀哈造物.cmd，它会尝试系统命令和本机 Codex 提供的运行环境。
双击 启动呀哈造物网页.cmd，会启动本地引擎并自动打开浏览器。保留启动窗口，在浏览器访问 http://127.0.0.1:5173 即可使用。无需安装发布包，也无需为每次代码修改重新打包。
启动前会自动关闭占用 5173 端口的进程及其子进程，再启动新版工作台（包括其他使用该端口的程序）。关闭旧网页服务时一并结束旧 Python 引擎，作品仍保存在磁盘。
- 修改 React 页面、样式与主题代码：保存后自动更新；替换图片素材后如未立即更新，刷新浏览器即可。
- 修改 Python 引擎：关闭启动窗口，再双击网页启动文件，让引擎加载最新代码。
- 网页支持项目、真实模型生成、3D 预览、体检、文件下载和展厅；密钥与云端能力仍由本地引擎和家长设置管理。
- 网页作品默认保存在项目目录的
.yaha；桌面发布版使用自己的作品目录。需要迁移时导出并导入.usagi作品包。 - 网页只在本机运行，不能直接双击
.artifacts/web/index.html使用引擎功能。调用桌面桥接打开 Bambu Studio 时使用桌面开发版pnpm dev；网页可先下载模型后手动用 Bambu Studio 打开。
需要检查桌面专属能力时使用桌面开发版；发布给其他电脑时再生成 Windows 发布包。
第一次打开会建立真实的本地乌萨奇示例。先输入想法，选“参数模板”，点击“生成模型”。调整尺寸后再次生成，会保存新版本。在作品柜可回退，旧版本不会被删除。
需要 Node.js 24+、pnpm 和 Python 3.12（64 位）：
python -m venv .venv
.venv\Scripts\python.exe -m pip install -r backend\requirements-lock.txt
pnpm install --frozen-lockfile
pnpm devElectron 下载失败时，在网络可访问后执行 node node_modules/electron/install.js。不要把 .venv 直接复制到其他电脑，它可能引用原电脑的 Python。
| 房间 | 已实现的操作 |
|---|---|
| 造物桌 | 真实 3D 预览、参数模板、AI 任务、尺寸/底座/挂孔、新版本 |
| 小屋门厅 | 六种造物模式与新作品 |
| 取材角 | 上传图片与模型、多视角选材、恢复 .usagi 作品包 |
| 心意卡 | 本地规则整理、多模态 AI 理解、Meshy 概念图 |
| 模型体检室 | 空间、封闭、朝向、连通部件检查；基础法线与补孔修复 |
| 打印准备台 | 保存配置、导出 STL/3MF/GLB/.usagi、打开 Bambu Studio |
| 打印站 | 家庭清单、明确标注的教学模拟 |
| 作品柜 | 切换项目、改名字、完整模型版本回退 |
| 乌萨奇展厅 | 本机展示、作品故事、收回展柜 |
| 小屋工坊 | 安全参数练习与真实源码入口说明 |
| 家长与设置 | 口令、系统凭据库密钥、云端开关、每日任务次数、任务编号 |
由家长在设置中首次建立 6–12 位口令并解锁，再配置：
- Meshy API key：文字 3D、单图/多图 3D、概念图。默认三维模型标识
meshy-7.1，概念图nano-banana-2，以账户可用型号为准。 - 多模态服务：兼容 Chat Completions 的 HTTPS API 根地址、支持图片和 JSON 的模型名及密钥，负责理解描述与照片并生成可校验心意卡。
- 打开云端开关，设置每日最多提交次数。密钥写入 Windows 凭据库，不回传前端、不包含在作品包中。也可使用家长配置的
MESHY_API_KEY/YAHA_AI_API_KEY环境变量。
本地模式无需密钥。当前开发环境没有服务密钥，实际云端生成未做付费联调；已用模拟 HTTP 验证协议、任务编号记录与下载保存。服务可能计费；本软件的次数限制不是金额限制。云端提交不自动重试，取消等待不保证取消云端任务。
初始机型为 A1 mini 单色，180 mm 立方。3MF 导出保留毫米单位，但不包含切片结果。基础检查未做完整壁厚求解、悬垂求解和实际支撑规划；Bambu Studio 中仍需要家长检查并确认打印。打印站模拟不连接真实机器。本轮没有测试真实设备或发送任何实际打印任务。
轮廓模式是二维轮廓挤出，适合白底深色画或透明图片；复杂照片前景分割仍需后续增加可编辑蒙版。浮雕是明暗高度映射；透光照片厚度为 0.8 mm 到所选最大厚度。它们都不是自由三维重建。AI 自由模型可通过“本地调整尺寸 / 底座 / 挂孔”调整现有网格，不必为尺寸改变再次付费。
src/pages/ 小屋各房间
src/features/ 造物、素材、版本、打印、家长设置
src/components/ 向导、小屋、3D 预览、导航
src/state/ 项目与任务状态
src/api/ 受控调用与资源地址
src/theme/ 模式、房间与默认参数
src/styles/ 主题、布局、造物桌、其他页面
desktop/ 窗口、隔离通信、引擎、文件交接
backend/yaha/geometry/ 本地模板、轮廓、浮雕、网格保存
backend/yaha/ai/ Meshy 与多模态理解适配器
backend/yaha/storage/ SQLite、不可变版本、受控资产
backend/yaha/ 校验、任务、设置、导入导出与领域操作
shared/ 允许调用的能力清单
tests/ 网格/存储/AI 协议与界面流程
引擎通过逐行 JSON 协议通信，长任务独立执行。任务关联项目及开始时版本，旧任务不会覆盖后来恢复的版本。重启后中断任务保留远程编号；在设置中的任务记录可继续查询原云端任务，不会重新提交生成或再次占用次数。如果原作品已切换版本，可从 Meshy 下载后作为新模型导入。SQLite 初始 schema 为 1，未来新增字段应提供迁移；不应覆盖旧作品文件。
本地开发数据在 .yaha/；桌面版在系统用户数据目录中的“小屋作品”。备份时关闭小屋，复制整个数据目录（数据库与 assets 一起），或逐件导出 .usagi。包里只恢复数据，不执行代码。当前包保存当前版本，完整版本历史请备份整个数据目录。
见 小屋工坊指南.md。先改变主题和耳朵参数，再添加一个自己的模板。界面文件和造物引擎文件分别修改；不要把所有逻辑塞进入口文件。
双击 一键打包呀哈造物.cmd，自动完成代码检查、网页构建、桌面构建、独立 Python 准备与 Windows EXE 打包。入口会自动查找系统或本机 Codex 运行环境中的 pnpm，并提前验证依赖 JSON；所有打包子进程使用同一个已验证的环境。成功后输出 release/YaHa-Craft-<版本号>-Windows.exe；失败会停止并保留错误信息。打包需要几分钟，窗口结束前请保持打开。命令行也可运行 pnpm package。
pnpm test:engine
pnpm exec playwright install chromium
pnpm test:ui
pnpm build
pnpm packageruntime:prepare 将开发 Python 与本项目依赖复制成独立运行时；Windows 发布输出在 release/。发布前以独立包启动验证。应用暂未配置代码签名，供家庭本机使用；正式发行时应增加签名、自动更新、服务条款及角色素材授权。
所有构建中间产物集中在 .artifacts/：web/ 是网页，desktop/ 是桌面代码，python/ 是独立引擎，windows/ 是打包工作目录。release/ 只保存最终 EXE。这些中间产物可以重新生成，日常网页开发不需要保留。pnpm build 重建前端与桌面代码，pnpm runtime:prepare 重建独立 Python，pnpm package:dir 重建桌面验收目录；运行 node scripts/check-desktop.mjs 前先执行 pnpm package:dir。测试数据 .yaha-*/ 与测试缓存也可清理；请保留真实作品目录 .yaha/、开发依赖 .venv/ 和 node_modules/。