Makelore Code｜AI 编程：管理本地项目、项目 Agent、会话、文件上下文、代码变更和运行时。
Makelore Canvas｜AI 绘画：每个设计项目（Workspace）维护一份从创建起就存在的 Living Form。用户通过对话或直接编辑持续完善同一设计方向，再生成图片、单参考图作品或视频；参考素材可从当前项目作品选择或从本地上传。Canvas 侧栏提供“获取灵感”，进入服务端驱动的提示词博物馆。
Makelore Robot｜AI 机器：管理机器人智能体、设备激活绑定、智能体配置与设备分配；机器人工作台的智能体位于 Robot 全局侧栏，选中后在内容区先查看绑定设备、再查看基础设置，当前智能体通过 URL 参数保持可分享选择；绑定设备时默认先选择“引导配网”或“已有激活码”。在 Windows 与 macOS 的引导路径中，Makelore 可在弹窗内扫描并连接附近开放的 Xiaozhi-* 配网热点，失败时仍可通过系统 Wi-Fi 手动连接；后续继续复用机器人现有热点配网页面，不修改固件，也不由 Makelore 接收 Wi-Fi 密码。
Makelore Learning｜AI 学习：浏览运营精选的学习项目，阅读项目 README，并把经过完整性校验的 ZIP 源码包保存到电脑继续实践。

应用启动默认进入 AI 模块入口选择页。入口页可在未登录状态浏览；未登录用户点击已开通模块时进入客户端原生登录页，可使用账号密码或手机号短信验证码登录。密码登录可选“记住密码”：正式安装包仅由 Electron Main 使用系统受保护凭据存储加密保存和回填账号密码，不写入 Renderer 持久状态，未打包开发版或系统安全存储不可用时禁用该选项。登录请求由 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 管理固定版本的 Pi worker、会话绑定、Provider/凭证、恢复与事件投影；Renderer 不直接启动或调用 Pi，也不读取其 wire 类型。项目与 Conversation 元数据先从本地读取，选中对话后才按需准备对应 worker；输入框不等待运行时准备完成。
桌面性能策略：应用窗口使用不透明浅色表面并默认保留硬件合成；仅在显式安全模式或短时间内重复 GPU 进程崩溃时启用软件渲染，并把故障原因保存在用户数据目录。启动关键路径只创建本地应用壳，认证、代理、同步、更新和遥测在首帧后延迟初始化；开发版可通过 app:performance 快照观察 GPU、进程、WebContents、事件循环与 Renderer Long Task 聚合指标。
后台生命周期：Main 统一维护模块活动状态与任务租约。隐藏窗口、离开模块和关闭开发浏览器会释放非必要连接；生成、Code 执行、下载与发布构建持有租约并在完成后释放。已写入 Pi 的 prompt 或上下文整理即使确认超过 10 秒，也会继续持有运行所有权与后台租约，直到迟到响应、权威事件、明确失败或用户清理使其收敛；此时同一 Conversation 不接受重叠 mutation，其他 Conversation 不受影响。各模块的后台连接、轮询和子进程必须通过同一生命周期入口登记。
共享开发浏览器：AI 编程右侧提供项目级浏览器，用户与 Agent 查看并调试同一实时页面、Console 和 Network，支持本地与公网开发地址。
后端边界：Renderer 通过 Main 所有的 Host API 访问认证、模型、同步、更新、语音、图像与运行时能力。
客户端更新：Electron Main 按平台与架构选择更新源并保留原始诊断；设置页只显示一条脱敏后的中文状态。正式源缺少对应安装包时保持错误并允许重试，不会误报为已是最新版。
个人资料：姓名、年龄、性别与个人头像按账号同步到云端；首次登录进入模块选择页时会要求先完善姓名，首页欢迎语和主平台左下角账号区优先展示个人资料姓名；头像支持 PNG、JPEG、WebP，保存时自动居中裁剪并以圆形缩略图展示，未设置或加载失败时回退为姓名首字母。
会话观察同步：本地编程会话在一轮问答完成并进入空闲后，后台通过个人资料 PUT 上传该会话截至当前的完整问答快照；只保留用户/助手自然语言文本，过滤代码、路径、日志、工具调用、附件与产物。同步只从本地上行，云端不回写、不恢复或删除本地会话；失败数据留在本地等待重试。
AI 绘画：一个 Workspace 固定对应一个设计方向、一条 Agent Session 和一份持久 Living Form。左侧对话时间线与右侧表单不是两套状态：聊天提取、Agent 建议、用户直接编辑、建议采纳和字段锁定都提交到同一个服务端 reducer，并由方向版本、字段来源和决策状态形成权威投影。数组型规格按完整集合原子替换，图片与视频字段按当前媒介渐进展示。
AI 绘画生成：服务端从已确认规格编译专业图片或视频指令并返回不可变 Quote；客户端只展示媒介、画幅、数量、格式、时长、警告和设计点，不展示或改写供应商 Prompt、模型、价格原子或存储地址。确认时只提交 Quote 身份。图片可使用当前 Workspace 的上传素材或生成作品，视频可绑定已审核首帧；任务与资产始终属于 Workspace。
AI 绘画健壮性：Renderer 为每次命令生成稳定 operation id，网络结果未知时保留原命令供原样重试，不把未知写入当失败或创建第二次生成。Main 负责 Token 刷新、Agent Gateway REST 提交和有界 Run 查询，并将可恢复事件流投影为 Host API SSE；断线后按事件游标续接并重新读取权威 Workspace。Canvas 只使用 Works Square 云端 V2 契约，没有本地语义适配器或降级路径，上游不可用时明确报错。
AI 绘画项目栏只展示 Workspace，不再在项目下创建独立设计会话。删除时必须完整输入项目名称；删除后项目、Living Form、任务、参考图和生成作品会从账户中隐藏且无法访问，不影响用户已另存到磁盘的副本。删除当前项目后自动打开最近更新的剩余项目，删除最后一个项目后进入空状态。
AI 学习：主区展示服务端分页项目卡片，详情页用安全 Markdown 渲染 README；原始 HTML 被禁用，Markdown 图片节点直接加载服务端校验后的无凭据 HTTPS URL，包括 SVG 和 Electron 支持的其他图片格式，不经过服务端下载、识别、转码或镜像。下载按钮打开系统保存对话框，Main 不按 Content-Length、声明字节数或客户端上限阻断下载，流式校验 SHA-256 与 ZIP 签名后原子保存。客户端不提供课程生成、课程播放器、本地课程库、Agent、ASR 或课堂 runtime。运营管理与接口字段见 docs/learning-project-catalog-server-contract.md。
插件市场 Release A：插件中心（Marketplace）提供运营精选的免费 skill_only 插件；“免费获取”只写入账号 Library，“下载/更新”才写入本机 Package Store，“启用到项目”和“分配给伙伴”仍是 Project Plugins 中彼此独立的动作。我的插件（My Plugins）展示账号获取状态、本机安装/更新/删除设备包、移除后的 tombstone 和 bounded unavailable reason；Project Plugins 继续只修改项目选择，不会因获取或下载自动启用或分配。
插件运行架构：Renderer 只调用 Main-owned Marketplace facade；Main 负责账号、请求 deadline、签名/摘要校验、不可变 Release、current selection 与原子回滚。下一代 Pi worker 使用同一个 effective snapshot，将每个有效 Skill 与已验证 Package Store root 成对传给 resource loader、Extension Host 和 CLI；skill_only 不依赖运行时 Policy，也不执行分发包中的任意代码。正式激活仍等待官方 Ed25519 公钥（production key activation HOLD）；生产私钥只能来自部署 secret，测试使用注入的临时密钥。
提示词博物馆：只陈列经过审核的作品预览、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 绘画 V2 契约。Canvas 不提供本地语义适配器；开发时应使用测试替身或连接相同的云端边界，云端失败不会回退到本地状态机。

质量检查

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

Pi 正式包必须继续运行 pnpm run verify:artifact:pi、pnpm run smoke:pi:real 和 pnpm run perf:pi:release。这里的 real 表示从最终产品可执行文件启动最终 resources/pi-runtime，并使用受控的 Provider-shaped 回环服务验证会话、工具、中止、结算、重开、并发隔离、子 Agent 与退出；它不表示真实外部 Provider 已验证。各目标平台、证据字段、兼容边界与整版本回滚步骤见 docs/pi-runtime-release-runbook.md。

代码结构

路径	职责
`src/`	React Renderer、页面、组件和状态管理
`electron/`	Electron Main、Preload、Host API、运行时与系统能力
`shared/`	Main 与 Renderer 共享的契约和项目配置
`resources/`	品牌、图标、编码 Skill 和打包资源
`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-owned 加密存储，退出登录不会清除它，只有成功的未勾选密码登录才清除旧记录。未打包开发版只在内存持有会话且禁用记住密码，避免未签名 Electron 调试进程触发 macOS 钥匙串。Renderer 现有的短效公开 access-token 会话快照与持久化保持不变（旧版升级迁移时仅暂存既有刷新凭据，Main 成功接管后立即删除），账号密码不进入 Renderer 持久状态。
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 刷新、Workspace 所属的持久 Agent Session、稳定命令身份、有界 Run 查询、可恢复事件订阅与契约映射，并通过本机 Host API 的 SSE 投影同步表单、任务和资产状态。切换 Workspace 只重连对应流；注销或退出时关闭本地流，不删除服务端持久 Session。远端 Token、Provider Prompt 与存储地址不进入 Renderer。
AI 绘画使用独立的云端 Workspace 边界，不回退到 AI 编程项目数据，也不向 Renderer 暴露 Provider、模型、Prompt、存储 URI 或远端登录 Token。
AI 学习只通过 Main-owned Host API 获取项目列表、README 详情和封面/历史媒体路径；Renderer 不持有 Works Token、对象存储地址、任意归档 URL 或本地文件路径。项目 ZIP 只允许同 Works origin 最多五跳重定向，重定向请求不携带 Bearer；下载结果仅向 Renderer 返回 saved 或 cancelled。README 不执行原始 HTML，仅 Markdown 图片节点可直接加载服务端校验后的无凭据 HTTPS 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 锁定；依赖准备需要本地网络。

项目内置编码 Skills

产品内置四个核心编码 Skill 根：agent-browser（开发浏览器）、frontend-slides（项目演示）、grilling（方案质询）和 planning-with-files（项目规划），统一从 vendor-neutral 的 resources/coding-skills/ 打包。data-service（开发数据）则由固定的 resources/coding-plugins/data-service/ 插件包持有，不在核心 Skill 根中复制路径或定义。
项目插件“启用”和把插件 Skill 分配给伙伴是两个独立动作：只有项目已启用 Data Service 时，未分配的 data-service 才可供新选择；禁用后，已有分配仍会显示并继续保存在 Agent 的 skillIds，但处于不可用且不生效的状态，重新启用后恢复生效。未选择的 Skill 不进入该 Agent 的有效 Pi 资源集合。
data-service 只在用户显式请求后触发：先检查并说明最小集合，用户确认后配置一次、复制 SDK 资产，再用本地预览执行 put/read-back；它不用于已发布作品。
创建项目伙伴时，agent-browser、grilling 与 planning-with-files 默认勾选；frontend-slides 作为专项能力可手动选择。用户可以在创建或维护伙伴时调整选择。最终选择写入项目 Agent 的 skillIds。
grilling 会在复杂实现前逐项确认高影响决策，用户确认前不执行变更。planning-with-files 只在复杂、可分阶段或需要跨会话恢复的任务中使用，并把 task_plan.md、findings.md 和 progress.md 直接保存到当前项目根目录，不写入 Skill 安装目录、用户目录或 .niancode/agent-planning/。
frontend-slides 只在用户准备项目展示、汇报或结题时自动调用，生成项目目录中的固定 16:9 HTML 演示和相对路径素材；它不生成 .pptx，不访问云部署服务。

项目伙伴与会话

新项目默认没有伙伴或 Agent；用户在项目内手动创建伙伴时必须填写名称、预设头像或本地头像、职责和精确的 Provider 账号与模型。该选择以 { accountId, modelId, thinkingLevel } 保存，不依赖运行时私有 Provider id。本地头像会自动裁剪为 256×256，并优先压缩为 WebP 后随项目配置保存；提示词与 Skill 属于后置高级设置。
项目配置页的新增与已有伙伴维护统一使用居中弹窗；编辑保存先更新当前页面草稿，点击底部“保存项目配置”后统一持久化。模型资源抽屉只展示已配置模型、提供方和文本/多模态能力，不提供项目级选择。伙伴模型只作为新 Conversation 的默认值；核心聊天页可为当前 Conversation 独立切换模型和 thinking，切换不会改写伙伴默认值或其他 Conversation。
读取旧项目时会把仍缺少模型的伙伴从兼容保留的 defaultModel 自动迁移到伙伴自身配置，之后运行时只认伙伴模型。
技能资源入口使用扳手图标；点击已安装 Skill 后先展示其目录结构，再展示主文件 SKILL.md 原文，并支持返回技能列表。
一个伙伴可以拥有多条互相独立的 Pi Session；伙伴和 Conversation 元数据分别由项目配置与 .niancode/conversations.json 保存，稳定 Agent/Conversation id 保持本地历史连续。
核心聊天页左侧把本地 Conversation 嵌套在展开的所属伙伴下，并在该伙伴子组中提供新建入口；首次选择没有 Conversation 的伙伴时立即创建本地元数据，同时异步准备对应运行时。即使准备被阻塞或超时，输入框仍可编辑，草稿也不会丢失。
Conversation 历史按需从 Main-owned Snapshot 读取。公开 SSE 只交付 Snapshot 与按 Conversation、worker generation 分组的 patch-batch；Renderer 整批校验连续 seq 后在一次状态事务中顺序应用，缺口或畸形批次只恢复目标 Conversation，隐藏 Conversation 的流式更新不会提交选中时间线。
核心时间线渲染消息、Markdown、thinking、工具、压缩、轮次边界、通知和 subagent.v1 单个/并行/串行子任务；默认保留最近 120 个节点的渲染窗口，可按 100 个节点加载更早内容。工具结果和浏览器附件保留在对应工具卡片内，累计输出覆盖同一块而不形成独立气泡；压缩只展示产品摘要、重试和结算状态。
Composer 支持文字、粘贴或选择 PNG/JPEG/WebP/GIF 图片，每条消息最多 16 张、最多并行上传 4 张。图片在发送前只保留本地预览，点击发送时才经 Main-owned 有界二进制接口上传一次；Main 在落盘前核对 MIME 与最小图片签名，状态与事件只保存 attachment id，时间线按需读取二进制并创建临时 object URL，不保存重复 base64。
Makelore 在应用侧按 Session 独立提交、跟踪和隔离运行状态，不使用“当前对话正在回复”的全局界面锁；同一 Session 的后续消息仍按顺序排队。最终产品中的 Pi 运行时会通过受控 Provider-shaped 回环 smoke 验证两个 worker 的重叠执行、状态隔离与凭证引用隔离；真实外部 Provider 的并发、限流、协议兼容和凭证隔离仍是独立风险，未执行真实 Provider 验证时不得标记为 Pass。
首次发送会立即生成稳定的乐观用户消息；HTTP 202 只表示本地 Agent 已接收。后续失败不会删除已接受消息，不确定交付不会自动重发；准备失败可在目标 Conversation 上手动恢复。
运行中的 Conversation 可把新消息作为 steer 引导当前回答或 follow-up 排到下一轮，并显示队列位置；队列只在 agent_settled 后释放，用户可中止当前运行。select/confirm/input/editor 交互在输入区上方回答，并明确展示取消或失效结果。
核心聊天页支持标题、归档、未读、恢复，以及从已持久化的 user 消息“从这里创建新对话分支”；assistant 消息和未持久化消息不提供该动作。分支只创建新的 Conversation 历史，不表示文件回滚。右侧编程工具集中展示当前 Conversation 的 changes、项目文件预览、浏览器附件、技能、命令与脱敏运行诊断。分享、待办、全局运行时和 revert/unrevert 不属于该产品界面。

兼容标识

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

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

README.md Unescape Escape

Makelore 2.0