wangxuming/makelore
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
1907924203a1a998182c8e44e8884682ef216d95
makelore/README.md

23 KiB
Raw Blame History

Makelore 2.0

一念成光，万物可创。

Makelore 是一个面向软件、视觉创作、互动学习与智能机器人的 AI 桌面工作台。当前版本为 2.0.0，包含四个已开通产品模块。模块入口页采用统一的横向卡片视觉，工作区左上角入口点击后返回模块入口页：

  • Makelore Code｜AI 编程：管理本地项目、项目 Agent、会话、文件上下文、代码变更和运行时。
  • Makelore Canvas｜AI 绘画：以设计项目（Workspace）组织 Agent 对话、方向确认、文生图、单参考图生图、视频生成任务和私有结果；参考图可从当前项目作品选择或从本地上传。Canvas 侧栏在“新建设计项目”上方提供“获取灵感”，进入服务端驱动的提示词博物馆。
  • Makelore Robot｜AI 机器：管理机器人智能体、设备激活绑定、智能体配置与设备分配；机器人工作台的智能体位于 Robot 全局侧栏，选中后在内容区先查看绑定设备、再查看基础设置，当前智能体通过 URL 参数保持可分享选择；绑定设备时默认先选择“引导配网”或“已有激活码”。在 Windows 与 macOS 的引导路径中，Makelore 可在弹窗内扫描并连接附近开放的 Xiaozhi-* 配网热点，失败时仍可通过系统 Wi-Fi 手动连接；后续继续复用机器人现有热点配网页面，不修改固件，也不由 Makelore 接收 Wi-Fi 密码。
  • Makelore Learning｜AI 学习：浏览和下载 Works 课程，也可以从需求、材料与多媒体选项发起后台单课生成；下载后的 frozen 课程包由内置 OpenMAIC production Stage 播放。

应用启动默认进入 AI 模块入口选择页。入口页可在未登录状态浏览；未登录用户点击已开通模块时进入客户端原生登录页，可使用账号密码或手机号短信验证码登录。登录请求由 Renderer 经 Host API 交给 Electron Main，再由 Main 调用 Works Square；成功后回到入口选择页。已登录时，Electron Main 会从 Works Square /api/auth/me 读取当前账号的四模块开关并只向 Renderer 投影布尔策略；被管理员关闭的模块会在入口页置灰且无法点击，直接访问其工作区路径也会返回入口页。旧服务端未返回策略或缺少单项字段时默认开放；这个客户端门禁不替代服务端 API 授权。

作品广场、素材广场、独立发布上传和云部署页面不属于 Makelore 2.0 工作台。新建项目可选择“小游戏”“小程序”或“自定义项目”：小游戏和小程序会创建完整的平台发布模板，项目配置底部提供“一键提交审核”；Main 自动预检、安全打包并提交，构建通过后进入运营审核，审核通过即直接发布。首次创建必须选择 PNG、JPEG 或 WebP 项目封面，并通过 Main-owned multipart 原子接口同时保存资料与封面；已有 draft/published 只提交新版本并沿用平台现有资料与封面。自定义项目只创建工作空间，不配置默认发布方式。项目成果预览 /deliverables 继续保留。

当前产品状态

  • 桌面技术栈：Electron、React 19、Vite、TypeScript、Zustand、Tailwind CSS。
  • AI 编程运行时：Electron Main 只启动安装目录 resources/opencode-ai/bin/ 中固定版本的 OpenCode；Renderer 不直接启动或调用运行时。OpenCode 不参与首屏启动，只在进入 Code 或发起 Code 操作时按需启动；离开 Code 且无活动任务 60 秒后由 Main 关闭 runtime、SSE 与项目监听。首选回环端口被不健康进程占用时，Main 会改用系统分配的临时端口，并把实际 URL 贯穿到所有运行时请求。
  • 桌面性能策略：应用窗口使用不透明浅色表面并默认保留硬件合成；仅在显式安全模式或短时间内重复 GPU 进程崩溃时启用软件渲染，并把故障原因保存在用户数据目录。启动关键路径只创建本地应用壳，认证、代理、同步、更新和遥测在首帧后延迟初始化；开发版可通过 app:performance 快照观察 GPU、进程、WebContents、事件循环与 Renderer Long Task 聚合指标。
  • 后台生命周期：Main 统一维护模块活动状态与任务租约。隐藏窗口、离开模块和关闭开发浏览器会释放非必要连接；生成、Code 执行、下载与发布构建持有租约并在完成后释放。各模块的后台连接、轮询和子进程必须通过同一生命周期入口登记。
  • 共享开发浏览器：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，需求最多 4,000 字）。大课在课程广场保持一张课程卡，进入后按有序模块切换同一 production Stage。课程包最大 512 MiB，先校验大小与 SHA-256 再原子安装；课程媒体只允许与 MIME 匹配的被动图片、音频、视频和字体类型，同源 HTML/SVG/XML/脚本/PDF 等在安装与服务阶段都被拒绝。本地课程按 Main 确认的账号隔离，Agent、ASR、PBL 与主观题评分通过 Main 白名单桥接并在离线或无权益时明确提示。
  • 提示词博物馆：只陈列经过审核的作品预览、Prompt、分类以及作者/来源/许可证信息，支持搜索、使用场景/风格/主体筛选和详情抽屉；“使用此 Prompt”只把原文带回当前 Canvas 会话输入框，不自动发送、不构成社区。列表和详情数据由服务端提供，客户端不打包数据集；服务端字段契约见 docs/prompt-museum-server-contract.md。
  • 视觉系统：单一浅色主题，品牌蓝 #3A5578、星火橙 #F26A3D、白色画布与低饱和蓝灰层级。
  • 字体系统：Renderer UI 内嵌 Inter Variable 与经过字符子集化的 Source Han Sans SC WOFF2，按字符范围统一中英文并保留系统中文字体 fallback；代码、路径和日志使用独立等宽字体。
  • 界面语言：仅保留中文；系统语言和历史设置中的其他语言会自动归一为中文。
  • 品牌资产：生产 SVG、PNG、应用图标、托盘图标与安装器视觉位于 resources/brand/ 和 resources/icons/。

安装与开发

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

pnpm install --frozen-lockfile
pnpm run dev

pnpm run dev 默认使用 Works Square 云端 AI 绘画适配器，与打包应用保持一致。需要离线开发或调试本地 Workspace 契约时，可以显式启动仅供开发的本地适配器；它会把设计项目、对话、Quote 和生成任务保存在本机用户数据目录，并生成本地预览：

pnpm run dev:image-workspace:local

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

质量检查

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

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；请求先经 Main-owned IPC，再由兼容 Host API 路由处理。只有真正需要 URL 的资源和流会把 loopback 地址暴露给 Renderer。
  • Renderer 不直接调用 Electron IPC 或本地运行时 HTTP 地址。
  • Electron Main 负责认证、秘密存储、运行时生命周期、代理、同步和系统集成；所有 stream、watcher、poller、loopback server 与子进程必须登记到模块活动和任务租约，不允许页面自行创建无托管后台任务。
  • Works Square 原生密码与短信登录均沿 Renderer → Host API → Electron Main → Works Square 链路完成。登录态按真实键盘、鼠标或触摸活动滑动续期；持续使用无需反复登录，连续 7 天未使用才清除会话并要求重新登录。刷新凭据始终只由 Electron Main 持有，并在正式安装包中通过系统受保护凭据存储加密落盘；未打包开发版只在内存持有凭据，Main 重启后需要重新登录，避免未签名 Electron 调试进程触发 macOS 钥匙串。Renderer 现有的短效公开 access-token 会话快照与持久化保持不变（旧版升级迁移时仅暂存既有刷新凭据，Main 成功接管后立即删除）。
  • AI 编程发布只经过 Main-owned Host API：Renderer 仅提交本地项目标识、非敏感作品资料和有界封面 DTO；Main 持有源码快照、本地 npm/Vite 构建、精确产物预检、双归档、Works Token、版本生成、幂等重试和安全状态投影。发布构建同时提供 Main-owned ReleaseJob 的 start/progress/status/cancel 契约，同一项目串行执行并支持取消；异步 Job 的扫描、依赖安装、构建和双归档均在独立 utilityProcess 中以流式文件处理，Main 只接收进度、摘要和契约，旧的同步提交接口继续兼容已有客户端。首次项目 create 使用 /api/projects/with-cover multipart 原子写入资料与封面；已有项目只提交版本，状态竞态会固定失败并要求重新确认，不执行无条件 metadata PATCH 或封面替换。项目的 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 配置或本地 archive 路径。Main 以登录身份派生不透明账号分区并拒绝切换后的迟到结果；课程下载重定向只允许同一 Works origin，播放器使用账号绑定的 loopback origin 与短效 nonce。只有显式 readClassroom 播放路径可以注册课程资源，Agent/runtime 会先验证调用前已存在的 active player registration，再做无副作用权威解析；课程不能靠请求自身完成注册。云端绑定始终使用课程 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 协议、文件注入、跨目标及宿主级命令会被阻止。面板关闭时销毁 WebContentsView、detach debugger 并释放页面；诊断域只在用户打开诊断视图时连接，面板重新打开时按 URL 和轻量历史元数据恢复。该能力独立于发布和部署。
  • 一键提交时，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 runtime 完整读取；Renderer 最多保留 8 个非活动会话的消息缓存，淘汰只影响内存副本，不删除或改写任何服务端历史。连接稳定时以事件流为准，只有断流才启用低频 REST 回退，并对同一会话的并发历史读取去重。
  • 创建伙伴后先进入伙伴对话，首条消息发送时才懒创建 OpenCode Session；新会话从干净上下文开始，标题从“新对话”在首条消息发送后自动生成，也支持手动重命名。
  • Makelore 在应用侧按 Session 独立提交、跟踪和隔离运行状态，不使用“当前对话正在回复”的全局界面锁；同一 Session 的后续消息仍按顺序排队。共享 runtime/provider 是否真正并发执行不同 Session 尚未经过自动化真实运行 smoke 验证，运行时仍可能自行串行、限流或拒绝请求。
  • 已在当前 fresh OpenCode 运行代际加载且通过 live Agent registry 校验的项目伙伴，会按 Session 独立提交和跟踪回复。若共享 runtime/provider 未确认新 Session 已开始，该 Session 会在 10 秒后单独终止并提示手动重试，不会自动重发或改写其他 Session 状态。运行期间新建、编辑或删除伙伴只更新项目配置与生成文件，不会自动重启、reload 或 dispose 共享运行时，以免打断其他 Session；这类变更会保持“等待运行时重新加载”，用户需等当前回复完成后手动重启运行时再发送。
  • 归档伙伴或单个会话前必须确认；归档会停止对应运行、保留历史，并可从列表底部恢复。未读按会话记录，打开一个会话只清除它自己的未读数。
  • OpenCode 的问题在当前会话内联处理；项目对话权限默认自动允许，遗留的待处理权限也会自动批准；上下文压缩在聊天时间线实际发生的位置显示为独立事件：自动压缩使用“正在优化对话”/“已优化对话”文案，手动执行 /compact 使用“正在压缩上下文”/“已压缩上下文”文案。压缩进行中使用弱化动画，完成后变为静态状态并保留在原位置；触发阈值与同一 Session 的消息排队语义保持不变。

兼容标识

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

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