Makelore Code｜AI 编程：管理本地项目、项目 Agent、会话、文件上下文、代码变更和运行时。
Makelore Canvas｜AI 绘画：以设计项目（Workspace）组织 Agent 对话、方向确认、文生图、单参考图生图、视频生成任务和私有结果；参考图可从当前项目作品选择或从本地上传。Canvas 侧栏在“新建设计项目”上方提供“获取灵感”，进入服务端驱动的提示词博物馆。
Makelore Robot｜AI 机器：管理机器人智能体、设备激活绑定、智能体配置与设备分配，让 AI 能力走进真实世界。
Makelore Learning｜AI 学习：浏览和下载 Works 课程，也可以从需求、材料与多媒体选项发起后台单课生成；下载后的 frozen 课程包由内置 OpenMAIC production Stage 播放。

应用启动默认进入 AI 模块入口选择页。入口页可在未登录状态浏览；未登录用户点击已开通模块时进入浏览器授权，授权成功后回到入口选择页，已登录用户可直接进入对应工作区。

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

当前产品状态

桌面技术栈：Electron、React 19、Vite、TypeScript、Zustand、Tailwind CSS。
AI 编程运行时：Electron Main 只启动安装目录 resources/opencode-ai/bin/ 中固定版本的 OpenCode；Renderer 不直接启动或调用运行时。已有登录态、已初始化项目和可用 Provider 时，Main 会在应用启动后后台预热运行时；首次设置、条件不完整或预热失败时仍由 Chat 按需启动。首选回环端口被不健康进程占用时，Main 会改用系统分配的临时端口，并把实际 URL 贯穿到所有运行时请求。
共享开发浏览器：AI 编程右侧提供项目级浏览器，用户与 Agent 查看并调试同一实时页面、Console 和 Network，支持本地与公网开发地址。
后端边界：Renderer 通过 Main 所有的 Host API 访问认证、模型、同步、更新、语音、图像与运行时能力。
客户端更新：Electron Main 按平台与架构选择更新源并保留原始诊断；设置页只显示一条脱敏后的中文状态。正式源缺少对应安装包时保持错误并允许重试，不会误报为已是最新版。
个人资料：姓名、年龄、性别与个人头像按账号同步到云端；首次登录进入模块选择页时会要求先完善姓名，首页欢迎语和主平台左下角账号区优先展示个人资料姓名；头像支持 PNG、JPEG、WebP，保存时自动居中裁剪并以圆形缩略图展示，未设置或加载失败时回退为姓名首字母。
会话观察同步：本地编程会话在一轮问答完成并进入空闲后，后台通过个人资料 PUT 上传该会话截至当前的完整问答快照；只保留用户/助手自然语言文本，过滤代码、路径、日志、工具调用、附件与产物。同步只从本地上行，云端不回写、不恢复或删除本地会话；失败数据留在本地等待重试。
AI 绘画：每个设计项目固定一个设计 Agent，并可包含多条互相独立的设计会话。消息、Brief、Quote 和 turnRevision 属于 Conversation；图片/视频生成任务与资产属于 Workspace，切换或新建会话不会创建新项目，也不会隐藏项目任务。图片创作既支持文生图，也支持从当前项目已完成作品或本地上传中选择一张参考图继续生成；输入框支持直接上传参考图，上传后可在候选区点击或输入 @ 选择，并将所选资产随消息提交；视频沿用同一单图选择器绑定首帧。每条 Conversation 复用服务端持久 Agent Gateway Session；已连接时 Agent 命令、流式回复和任务进度共用 WebSocket，断流时使用幂等 REST 提交与低频同步。确认栏展示并允许编辑服务端最终提示词和 generation options，分别展示清晰度、画幅和视频时长；每次修改都会按当前 Quote 重新报价、刷新设计点，报价完成前不能确认，确认时将最新提示词与参数原值提交给后端。客户端不计算百炼尺寸、供应商价格或积分价格，服务端 Quote 是唯一计费准则。确认结果会按 Quote 对账，即使 Run 在任务落库后异常结束，Workspace 任务仍会恢复到统一列表。生产环境使用 Works Square 云端 Workspace 契约，上游不可用时明确报错。
AI 绘画项目栏会在当前项目下保留会话历史，默认显示最近五条消息摘要和更新时间，更多会话可展开；新建或点击历史条目都在同一项目中切换并恢复完整对话。
AI 绘画项目支持从侧栏删除。确认删除时必须完整输入项目名称；删除后项目及其会话、任务、参考图和生成作品会从账户中隐藏且无法访问，不影响用户已另存到磁盘的副本。服务端采用软删除，数据库记录和对象存储暂不物理清理。未提交的任务会被取消并释放预留积分，已提交或运行中的任务继续后台结算但对用户隐藏；删除当前项目后自动打开最近更新的剩余项目，删除最后一个项目后进入空状态。
AI 学习：默认主区直接展示课程广场，生成课程从全局左栏打开宽工作台；无材料请求使用 JSON，有材料请求使用受限 multipart（最多 5 个、单个 50 MiB、总计 150 MiB）。大课在课程广场保持一张课程卡，进入后按有序模块切换同一 production Stage。课程包先校验大小与 SHA-256 再原子安装，音频、媒体与互动内容可离线播放；Agent、ASR、PBL 与主观题评分通过 Main 白名单桥接并在离线或无权益时明确提示。
提示词博物馆：只陈列经过审核的作品预览、Prompt、分类以及作者/来源/许可证信息，支持搜索、使用场景/风格/主体筛选和详情抽屉；“使用此 Prompt”只把原文带回当前 Canvas 会话输入框，不自动发送、不构成社区。列表和详情数据由服务端提供，客户端不打包数据集；服务端字段契约见 docs/prompt-museum-server-contract.md。
视觉系统：单一浅色主题，品牌蓝 #3A5578、星火橙 #F26A3D、白色画布与低饱和蓝灰层级。
字体系统：Renderer UI 内嵌 Inter Variable 与 Source Han Sans SC，按字符范围统一中英文；代码、路径和日志使用独立等宽字体。
界面语言：仅保留中文；系统语言和历史设置中的其他语言会自动归一为中文。
品牌资产：生产 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/ 目录。正式发布还必须通过 MAKELORE_LEARNING_PLAYER_ARTIFACT 提供已解压且通过清单校验的 OpenMAIC 播放器产物；CI 先按固定 URL 与 SHA-256 下载，未提供或校验失败会立即停止，安装包不依赖相邻源码仓库或被忽略的本机构建目录。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 持有源码快照、本地 npm/Vite 构建、精确产物预检、双归档、Works Token、版本生成、幂等重试和安全状态投影。项目的 Vite config/plugins 会以当前桌面用户权限执行，因此该链路只适用于用户信任的本地项目，不是 sandbox。
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、ASR 与课堂 runtime 都经过 Main-owned 边界；Renderer 不持有 Works Token、模型或 Provider 配置。云端绑定始终使用课程 aggregate contentHash，模块 id/hash 仅作为受控上下文；课堂 runtime 只允许固定能力路径，播放器不能自报课程身份或代理任意 URL。
Prompt Museum 使用独立的 Main-owned Host API 代理；Renderer 只接收分页卡片、详情和服务端返回的图片地址，Works Square Token 只由 Main 持有。发布记录必须由服务端完成作者、来源、许可证和素材授权审核，模块不提供投稿、点赞、评论或排行榜。
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 会从待上传构建归档的同一组 Main-owned 内存字节启动临时回环站点，并在两个独立的临时 Chromium profile 中检查桌面和移动视口的主页面加载、运行错误、失败资源与白屏。临时页面不挂载到界面，不读取或写入用户浏览器的 Cookie、历史和登录态；检查结束后始终销毁并清理，也不要求用户预先打开开发预览。
客户端复用 Electron 内置 Chromium，不安装 Playwright 或额外浏览器。预检只改善提交前反馈，可被非官方客户端绕过，也不会上传“已通过”凭据；平台仍把源码、构建归档和清单视为不可信输入，逐字节重算并在人工审核后发布。安装包携带固定 npm 运行时，项目依赖和 Vite 版本由 package-lock.json 锁定；依赖准备需要本地网络。

项目内置 OpenCode Skills

项目随产品提供 agent-browser（开发浏览器）、frontend-slides（项目演示）、grilling（方案质询）和 planning-with-files（项目规划）四个 OpenCode Skill。它们从 .opencode/skills/ 打包，并由 Electron Main 安装到受管的 OpenCode 配置目录。
创建项目伙伴时，agent-browser、grilling 与 planning-with-files 默认勾选；frontend-slides 作为专项能力可手动选择。用户可以在创建或维护伙伴时调整选择。最终选择写入项目 Agent 的 skillIds，未选择的 Skill 保持拒绝权限。
grilling 会在复杂实现前逐项确认高影响决策，用户确认前不执行变更。planning-with-files 只在复杂、可分阶段或需要跨会话恢复的任务中使用，并把 task_plan.md、findings.md 和 progress.md 直接保存到当前项目根目录，不写入 Skill 安装目录、用户目录或 .niancode/agent-planning/。
frontend-slides 只在用户准备项目展示、汇报或结题时自动调用，生成项目目录中的固定 16:9 HTML 演示和相对路径素材；它不生成 .pptx，不访问云部署服务。

项目伙伴与会话

新项目默认没有伙伴或 Agent；用户在项目内手动创建伙伴时必须填写名称、预设头像或本地头像、职责和精确的 provider/model。本地头像会自动裁剪为 256×256，并优先压缩为 WebP 后随项目配置保存；提示词与 Skill 属于后置高级设置。
项目配置页的新增与已有伙伴维护统一使用居中弹窗；编辑保存先更新当前页面草稿，点击底部“保存项目配置”后统一持久化。模型资源抽屉只展示已配置模型、提供方和文本/多模态能力，不提供项目级选择；模型切换只能在伙伴维护弹窗中完成，聊天输入区仅展示当前伙伴模型。
读取旧项目时会把仍缺少模型的伙伴从兼容保留的 defaultModel 自动迁移到伙伴自身配置，之后运行时只认伙伴模型。
技能资源入口使用扳手图标；点击已安装 Skill 后先展示其目录结构，再展示主文件 SKILL.md 原文，并支持返回技能列表。
一个伙伴可以拥有多条互相独立的 OpenCode Session；伙伴、会话、归档时间、置顶和未读数分别由项目配置与 .niancode/conversations.json 保存。
伙伴展开后按时间展示会话，默认显示前五条，更多会话通过“更多会话”展开；每条会话只显示一行精简的最新消息预览和右侧时间，归档按钮仅在悬浮或聚焦会话卡片时出现，选中伙伴会在卡片上保持明确的展开状态反馈。
创建伙伴后先进入伙伴对话，首条消息发送时才懒创建 OpenCode Session；新会话从干净上下文开始，标题从“新对话”在首条消息发送后自动生成，也支持手动重命名。
不同 Session 由 OpenCode 自己并发运行；同一 Session 的后续消息按顺序排队。Makelore 只展示运行中、待处理和未读状态，不增加额外的全局并发锁。
归档伙伴或单个会话前必须确认；归档会停止对应运行、保留历史，并可从列表底部恢复。未读按会话记录，打开一个会话只清除它自己的未读数。
OpenCode 的问题在当前会话内联处理；项目对话权限默认自动允许，遗留的待处理权限也会自动批准；上下文压缩在聊天时间线实际发生的位置显示为独立事件：自动压缩使用“正在优化对话”/“已优化对话”文案，手动执行 /compact 使用“正在压缩上下文”/“已压缩上下文”文案。压缩进行中使用弱化动画，完成后变为静态状态并保留在原位置；触发阈值与同一 Session 的消息排队语义保持不变。

兼容标识

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

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

README.md Unescape Escape

Makelore 2.0