Makelore 2.0

一念成光，万物可创。

Makelore 是一个面向软件与视觉创作的 AI 桌面工作台。当前版本为 2.0.0，包含两个已开通产品模块，并保留一个学习模块入口：

• Makelore Code｜AI 编程：管理本地项目、项目 Agent、会话、文件上下文、代码变更和运行时，并为服务端可运行版本提供真机扫码预览。
• Makelore Canvas｜AI 绘画：以设计项目（Workspace）组织 Agent 对话、方向确认、图片/视频生成任务和私有结果。
• Makelore Learning｜AI 学习：数学与知识宇宙主题的学习入口，当前暂未开通；开屏页和模块切换菜单保留置灰入口，不能进入。

作品广场、素材广场、独立发布上传和云部署页面不属于 Makelore 2.0 工作台。新建项目可选择“小游戏”“小程序”或“自定义项目”：小游戏和小程序会创建完整的平台发布模板，项目配置底部提供“一键提交审核”；Main 自动预检、安全打包并提交，构建通过后进入运营审核，审核通过即直接发布。自定义项目只创建工作空间，不配置默认发布方式。项目成果预览 /deliverables 继续保留。

当前产品状态

• 桌面技术栈：Electron、React 19、Vite、TypeScript、Zustand、Tailwind CSS。
• AI 编程运行时：Electron Main 只启动安装目录 resources/opencode-ai/bin/ 中固定版本的 OpenCode；Renderer 不直接启动或调用运行时。首选回环端口被不健康进程占用时，Main 会改用系统分配的临时端口，并把实际 URL 贯穿到所有运行时请求。
• 共享开发浏览器：AI 编程右侧提供项目级浏览器，用户与 Agent 查看并调试同一实时页面、Console 和 Network，支持本地与公网开发地址。
• 真机预览：AI 编程项目空间可读取当前静态 Release 状态；待审版本使用短时预览地址，已发布版本使用同源 HTTPS play_url，供手机直接测试触控、屏幕和移动网络环境。
• 后端边界：Renderer 通过 Main 所有的 Host API 访问认证、模型、同步、更新、语音、图像与运行时能力。
• AI 绘画：每个设计项目固定一个设计 Agent，并可包含多条互相独立的设计会话。消息、Brief、Quote 和 turnRevision 属于 Conversation；图片/视频生成任务与资产属于 Workspace，切换或新建会话不会创建新项目，也不会隐藏项目任务。每条 Conversation 复用服务端持久 Agent Gateway Session，任务进度通过实时流推送并在统一列表中展示，断流时使用低频 REST 同步。生产环境使用 Works Square 云端 Workspace 契约，上游不可用时明确报错。
• 视觉系统：单一浅色主题，品牌蓝 #3A5578、星火橙 #F26A3D、白色画布与低饱和蓝灰层级。
• 品牌资产：生产 SVG、PNG、应用图标、托盘图标与安装器视觉位于 resources/brand/ 和 resources/icons/。

安装与开发

项目使用 package.json 中固定版本的 pnpm。

pnpm install --frozen-lockfile
pnpm run dev

开发环境中的 AI 绘画创作空间默认使用仅供开发的本地适配器；它会把设计项目、对话、Quote 和生成任务保存在本机用户数据目录，并生成本地预览。也可以使用下面的显式命令启动同一模式：

pnpm run dev:image-workspace:local

该模式只允许在未打包应用中启用，使用独立开发数据，并保持与生产相同的 Workspace-first 接口。打包应用和生产环境只使用云端适配器，云端失败不会回退到本地。

质量检查

pnpm run typecheck
pnpm run lint:check
pnpm test
pnpm run build:vite

Electron E2E：

pnpm run test:e2e

打包

pnpm run package:mac
pnpm run package:win
pnpm run package:linux

Windows 打包脚本会先准备目标架构所需的 Python、uv 与 OpenCode 运行时资源，产物写入忽略的 release/ 目录。Windows 正式包中的 OpenCode、Playwright MCP、Python 和 uv 均从安装目录解析；缺少本地资源时启动或产物验证会直接失败，不会回退到系统 Python、npm 或 npx 下载。Git、项目编译器和用户选择的浏览器仍属于项目/系统工具，不属于内置 OpenCode 运行时。macOS 与 Linux 的双架构产物需要分别完成对应架构的 staging 与产物验证后再发布。

代码结构

路径	职责
src/	React Renderer、页面、组件和状态管理
electron/	Electron Main、Preload、Host API、运行时与系统能力
shared/	Main 与 Renderer 共享的契约和项目配置
.opencode/	随产品提供的 Skill 与 OpenCode 插件
resources/	品牌、图标和打包资源
scripts/	运行时准备、图标生成、打包与验证脚本
tests/	Vitest、Electron runtime 与 Playwright 测试

架构约束

• Renderer 的后端调用统一经过 src/lib/host-api.ts 或 src/lib/api-client.ts。
• Renderer 不直接调用 Electron IPC 或本地运行时 HTTP 地址。
• Electron Main 负责认证、秘密存储、运行时生命周期、代理、同步和系统集成。
• Works Square 登录态按真实键盘、鼠标或触摸活动滑动续期；持续使用无需反复授权，连续 7 天未使用才清除会话并要求重新登录。刷新凭据只由 Electron Main 持有，并在系统提供受保护凭据存储时加密落盘；Renderer 仅保存短效公开会话状态（旧版升级迁移时仅暂存既有刷新凭据，Main 成功接管后立即删除）。
• AI 编程发布只经过 Main-owned Host API：Renderer 仅提交本地项目标识和非敏感作品资料；Main 持有文件读取、安全打包、Works Token、版本生成、幂等重试和安全状态投影。
• AI 编程项目配置以项目内 .niancode/project.json 为准；项目文件和会话保持本地。
• AI 绘画 Renderer 只调用 Main-owned Host API；Main 负责 Works Square Token 刷新、Conversation 所属的服务端持久 Agent Session、单次 WebSocket ticket、断点续传与事件契约映射，并通过本机 Host API 的 SSE 投影同步任务状态。切换会话只重连对应流；注销或退出时关闭本地流并清除本机 Session-id 缓存，不删除服务端持久 Conversation Session。远端 Token 与 ticket 不进入 Renderer。
• AI 绘画使用独立的云端 Workspace 边界，不回退到 AI 编程项目数据，也不向 Renderer 暴露 Provider、模型、Prompt、存储 URI 或远端登录 Token。
• AI 编程的 Agent 配置是项目所有的；稳定 id 用于保持会话兼容，显示名称可以修改。AI 绘画的设计 Agent 是固定产品能力，不作为用户可增删的项目实体。

共享开发浏览器

• Electron Main 持有 sandboxed WebContentsView、项目级持久浏览器配置和 CDP 连接；被调试页面不获得 Makelore Preload、Node.js 能力或 Host API 凭证。
• 用户和 Agent 操作同一个页面。Renderer 只负责显示、收起和布局；Agent 通过 Main 代理的页面级 CDP 工具导航、读取 Console/Network 和执行调试命令。
• 非 Web 协议、文件注入、跨目标及宿主级命令会被阻止。面板收起或被弹窗遮挡时隐藏原生页面并暂停 Agent 调试；该能力独立于发布和部署。

真机预览

• 真机预览属于 Makelore Code 的项目级能力，不是新的顶层 AI 模块，也不复用 /deliverables，不恢复发布上传或云部署工作台。
• Renderer 只读取 Main-owned Host API 的项目预览快照；Main 绑定当前项目、管理登录续签、核对目标版本，并只放行 Works Square 同源 HTTPS 静态 Release 地址。二维码不包含账号 Token，也不生成本机回环地址。
• 构建成功且进入待审的版本使用短时、只读、精确 Release 绑定的 Owner preview ticket；已发布版本优先使用 play_url，runtime_url 仅保留一个客户端兼容版本。构建中、旧版本或失败状态不会伪装成可扫码。

项目联系人与会话

• 新项目默认没有联系人或 Agent；用户在项目内手动创建联系人时必须填写名称、预设头像、职责和精确的 provider/model，提示词与 Skill 属于后置高级设置。
• 一个联系人可以拥有多条互相独立的 OpenCode Session；联系人、会话、归档时间、置顶和未读数分别由项目配置与 .niancode/conversations.json 保存。
• 联系人展开后按时间展示会话，默认显示前五条，更多会话通过“更多会话”展开；每条会话只显示一行精简的最新消息预览和右侧时间，归档按钮仅在悬浮或聚焦会话卡片时出现，选中联系人会在卡片上保持明确的展开状态反馈。
• 创建联系人后先进入联系人对话，首条消息发送时才懒创建 OpenCode Session；新会话从干净上下文开始，标题从“新对话”在首条消息发送后自动生成，也支持手动重命名。
• 不同 Session 由 OpenCode 自己并发运行；同一 Session 的后续消息按顺序排队。Makelore 只展示运行中、待处理和未读状态，不增加额外的全局并发锁。
• 归档联系人或单个会话前必须确认；归档会停止对应运行、保留历史，并可从列表底部恢复。未读按会话记录，打开一个会话只清除它自己的未读数。
• OpenCode 的问题与权限请求在当前会话内联处理，不自动批准；上下文压缩沿用 OpenCode 自动机制，在最新消息位置显示“正在压缩上下文”。

兼容标识

Makelore 2.0 继续保留既有 niancode 包名、应用 id、协议、数据目录、环境变量、API 请求头和服务标识，以兼容现有安装与服务。它们是内部技术契约，不是对外品牌名称。

本仓库只描述当前产品状态，不保存旧产品的任务记录、设计过程、工作日志或迁移历史。