makelore/.project-docs/40-domain/business-rules.md

Business Rules

Durable Rules

• Marketplace Release A is curated: only Operations publishes packages. Users may acquire an eligible Plugin for free; only server-declared metered operations may later consume Token Points, and system-included Data Service remains zero-charge.
• Account Library, Device Installation, project enablement, Agent assignment, runtime authorization, and billing are separate states. No read, install, acquisition, or assignment may silently advance another state.
• Marketplace packages become effective only after closed manifest/descriptor parsing, canonical archive and client-compatibility checks, Ed25519 verification, immutable Package Store selection, project enablement, Agent projection, and current server policy admission. Unknown or unavailable IDs remain persisted but do not materialize.
• A parent Pi worker freezes the exact verified package root, Skills, tools, policy, Account, project, and Release for its lifetime; child workers receive no Plugin resources. Lifecycle invalidation blocks new actions but does not hot-swap a running worker or delete bytes it still owns.
• System-included Data Service ships with MakeLore and has no Library acquisition, Admission, download, update, or device-uninstall action. Users may still enable it per project and assign its Skill to an Agent.
• Code-owned Game Resource and Web Search are optional bundled hosted Plugins. Their exact schema-2 manifests, Skills, and tools ship with MakeLore, so they have no device download, update, Beta, signature, or device-uninstall state. Account Library acquisition/removal, project enablement, Agent assignment, current server policy, immutable Admission, explicit confirmation, and Token Point billing remain distinct.
• Production Marketplace trust fails closed while the official Ed25519 public key is absent. Test-only/integration keys and packaged unknown-key rejection are evidence, not authority to activate production. Generic platform_hosted client execution is implemented, but production package trust and real Provider activation remain closed until the official key and separate server pricing, credential, Admission, and acceptance gates are ready.
• A platform_hosted Skill or tool may enter only an installed, enabled, assigned, trusted, compatible, policy-admitted parent Pi logical thread. Unknown, disabled, or ineligible assignments stay inert; child workers receive no hosted Plugin projection.
• A metered hosted mutation requires explicit client confirmation before resolve, Admission, or charging. Works Square owns price, payer, Token Point policy, and receipt state. Stable logical operation identity survives response loss and Main restart; submission_unknown must not become a fresh request or be conflated with a billing pending_review receipt.
• Electron Main to fixed Works Square routes is the only hosted Plugin transport. Packages, Renderer state, Pi arguments/results, logs, and saved project metadata must not expose Provider credentials, URLs, credit balances, raw responses, or Provider job IDs. Saving a hosted result must use bounded project-relative paths and the existing project write lease.
• Native Web Search is a user-acquired code-owned bundled platform_hosted Plugin. Free acquisition, project enablement, Agent assignment, current Admission, and explicit per-search Token Point confirmation are separate gates. Only the frozen parent worker receives makelore_web_search; child workers receive no hosted tool. submission_unknown is result-less and must not auto-retry, while receipt_unavailable is a Main-only closed billing projection that tells the user not to repeat the search. Provider key, model, URL, price authority, and raw response never enter Renderer, the Package, Pi arguments, or project metadata.
• 面向用户的 AI 编程新建流程必须在 mini_game、mini_program、custom 中选择；ProjectType 是产品类型，创建后不能通过 UI 或 Host API 修改，未传类型的兼容 API 调用按 custom 处理。
• 新建小游戏和小程序会生成平台固定版本的受控 Vite 发布模板，并可使用项目配置中的单一“提交审核”入口；custom 和缺少类型字段的旧项目不提供一键发布。
• ProjectType 不等于 BuildPreset：第一期两个可发布产品类型都映射到内部受控 Vite preset；本地 projectType 不是授权边界，Main-owned 安全打包、Host API 和服务端包体校验仍必须执行。
• 非专业用户只执行一次“提交审核”；构建通过后由运营审核，审核通过即直接发布。
• 创建者发布唯一链路是项目配置“一键提交审核” → Main 本地 npm/Vite 构建 → 最终 built snapshot 的客户端 UX 预检 → source+built+artifact contract 上传 → 服务端校验/固化 → 运营审核；不恢复独立发布上传页、云部署工作台、Compose/deploy-check、自动 watcher/arm/upload 或手工 ZIP 入口。
• 本地构建必须由 Main 对安全源码快照使用安装版 Electron Node 和固定 npm 11.6.2 执行 npm ci --ignore-scripts，再显式调用项目 package-lock.json 安装的 Vite；不得依赖全局 PATH、既有 node_modules 或 Renderer 提供的任意路径/origin。
• 项目 Vite config/plugins 以桌面用户权限执行，因此发布链只适用于用户信任的本地项目；它不是 sandbox。安装依赖需要网络，运行时闭包缺失或版本不符必须 fail closed。
• 提交前预检必须由 Main 以一次性 loopback origin 提供最终上传 built_archive 的同一内存文件快照，以 fresh 非持久 Electron WebContents/CDP 检查桌面/移动视口、运行错误、白屏与外域访问；不得调用 Playwright 或污染用户浏览器状态。
• 客户端预检是可绕过的 UX fail-fast，不上传可信 receipt，也不声称具备生产 opaque-origin parity。服务端把源码、构建归档和 contract 当作不可信字节，独立重算、校验并固化不可变 Release；人工审核仍是不可绕过发布门禁。未来若要求 runtime 强门禁，必须由可信 verifier 绑定精确构建产物。
• 发布安全边界由 Electron Main 持有，Renderer 不接触账号 Token、ZIP、幂等键和本地绝对路径。
• 发布 Host API 必须在读取凭据、查询项目和打包前校验 Renderer capability；仅持有 Host token/base 的非 UI 调用方不得发起发布。
• 首次 Works Project 发布必须选择 PNG/JPEG/WebP 封面（不超过 10 MiB），并由 Electron Main 将项目资料与封面通过服务端单一 multipart create 合同原子绑定；Renderer 仅传有界封面 DTO，不接触 Works Token、项目路径、归档或幂等身份。服务端创建冲突或失败时客户端必须停止版本上传，不能回退到先传封面再 JSON create。已有 draft/published 仍只提交新版本并沿用平台资料与封面；在具备 metadata revision/ETag 与 draft-only 条件写前，不得用无条件 PATCH 模拟已有资料编辑。
• 客户端只持久化服务端已接受的 submission binding v2。旧 submitted 绑定必须保留；旧 armed、waiting_for_package、waiting_for_login、uploading、failed 必须迁移为可理解的 legacy_retired，不得恢复后台任务。
• 云端上传成功但本机 submission binding 保存失败时，提交仍视为成功；客户端显示固定、无本地路径的告警并继续轮询服务端校验与 Release 固化状态，避免诱导重复提交。
• 旧客户端缺少 source+built+contract 新协议，或服务端仍存在旧 sandbox/browser 任务时，必须提示升级客户端并重新构建提交；不得把它们伪装为新版瞬时故障。新版合同校验后的 BUILD_STALE、归档存储或 ReleaseStore 瞬时失败由运营在“构建异常”中重试。
• 已发布作品优先读取 play_url，只有字段缺失时才使用一个客户端版本的 runtime_url 回退。公共播放 URL 必须是 Works Square 同源 HTTPS、无 userinfo/loopback、精确 /apps/{encodeURIComponent(app_id)}/、无 query/fragment，且上游明确 playable === true 并提供非空版本名；否则按不可播放处理。
• works-cloud-deploy.json 仅是已安装客户端的数据兼容文件名，不表示客户端仍提供 cloud deployment coordinator。
• Works Square 会话按真实键盘、鼠标或触摸活动滑动续期，连续 7 天未使用才要求重新授权。
• “记住密码”是独立于七天会话的可选桌面凭据记录：只能由 Electron Main 在正式安装包中通过可用的系统安全存储加密落盘，账号密码不得进入 Renderer 持久状态、日志或 Works Square 持久化。退出登录和短信登录保留记录；只有成功的未勾选密码登录清除旧记录。系统安全存储不可用或未打包开发版必须禁用该选项。
• 运营端可按用户关闭 Code、Canvas、Learning 或 Robot 客户端入口，默认全开。Makelore 通过 Main-owned /api/auth/me 只消费四布尔安全投影；缺失 module_access 或字段按开启处理，服务端 design 对应现有客户端 painting。
• 关闭的模块卡片必须置灰且无法点击；其根路由、深层路由和别名路由必须在 MainLayout 或模块初始化前阻断。Code provider 只能在 auth policy hydration 完成且 Code 已开启时初始化；/settings 是全局设置，不得随 Code 关闭而失去访问。
• 模块置灰/路由阻断不是 API 授权边界。每个 Works/模块服务端 API 仍必须独立执行身份与权限检查；/api/auth/me 返回终止性 401 时必须清理 Main 和 Renderer 会话，不得以默认全开继续。
• Makelore Code 的唯一 production runtime 是精确 pin 的 Pi 0.84.2。不得恢复 OpenCode fallback、RPC/SDK 双轨、兼容执行路径或 Renderer runtime 直连；产品公共合同必须保持 project/Agent/Conversation/Snapshot/Patch 中立，Pi wire 只属于 Main。
• project、Agent、Conversation 使用 .makelore/project.json 与 .makelore/conversations.json schema v2。Agent id、名称、原始 prompt、Skills 与 archive 状态必须稳定保存；不得从 .niancode 或 .opencode 读取或迁移项目元数据，也不得作为顺带清理删除这些用户内容。
• 每条 active/warm Conversation 在同一个长驻父 Agent Server 内绑定独立 Pi Runtime/Session/channel。首次本地 Conversation 创建和 Composer 编辑不得等待逻辑线程；未解析 Conversation 第一次选模必须先验证模型、持久化 resolved metadata，再 prepare。已解析且同账号的模型变化复用 target set_model，跨账号变化等 active run settled 后只重建目标逻辑线程。
• prompt、steer、follow-up、compact 等 mutation 必须先获得目标 Conversation 的 202 acceptance/dedupe 结果。confirmation timeout 只表示 uncertain，不得自动重发，也不得释放 run permit、Agent Server/child process ownership 或 Main background lease；迟到 success/failure/exit/abort 必须单调、exactly-once 收敛。线程级失败只影响目标 Conversation；整个 Agent Server 退出时所有旧父 channel 一起 fail closed，但 Main/Renderer 继续存活且下次恢复只启动一个新 Server。
• Renderer 只消费 Snapshot-first 与 patch-batch SSE。每条 Conversation 的 generation/seq 独立；stale generation 丢弃，gap/reconnect 只恢复目标 Snapshot 并应用严格连续的缓冲 tail，不重放 mutation，也不改变乐观消息的 UI identity。
• top-level 逻辑 turn 并发上限 4、warm idle logical-thread LRU 上限 8、child 并发上限 4，child 使用 FIFO process budget 8；shared parent 逻辑线程不各占一个 process lease。单次 subagent dispatch 最多 8 个 child 且禁止递归；coding child 与 parent 共用同项目 write lease，父 abort/crash/generation 失效必须清理所有 child、permit 与 process lease。
• Provider Account、credential、custom header 和 proxy token 只可投影到选中父逻辑线程的内存 credential store 或选中 child 进程，不能进入 argv、catalog、Renderer 或 sibling thread。确定性的 Works user-context 缺失必须使缓存 gateway credential 过期、fail fast 且不重放 mutation，并向产品投影固定的 CODING_PROVIDER_AUTH_REQUIRED；不能把它解释为 Pi 崩溃。
• Provider/resource revision 在 idle 逻辑线程下一 prompt 前应用；running 线程使用当前 run snapshot，settled 后重建。同账号 refresh single-flight 且最多一次 auth refresh/reopen。真实 Provider 认证、endpoint/proxy/rate-limit、协议差异、真实并发和共享 Agent Server 内跨线程凭据隔离由用户明确豁免并接受风险，realTurnVerified=false，不得写成 Pass。
• 客户端更新检查由 Electron Main 持有。缺少当前平台正式稳定 manifest 必须保持错误并提示稍后重试或从官网下载，不得宣称“已是最新版”；设置页只显示一条中文用户提示，原始堆栈、URL、路径和错误码只保留在 Main 日志。
• 一个 AI Design Workspace 公开一个 current Direction、一个 persistent Agent Session 和一个 Current Specification；conversation timeline 不是独立创建或选择的权威对象。
• Living Form 只能投影服务端 Current Specification。Chat、direct edit、decision、proposal、lock、Asset binding 与 restore 必须通过同一 V2 reducer；Renderer drafts 在 accepted 前保持本地。
• 每个 mutation 使用稳定 command 与 semantic operation identity。transport-unknown 只能重放原命令；business rejection、timeout 或用户再次点击不能自动生成新的业务意图。
• Direction projection 是 Specification 真值。event cursor、assistant delta、Task progress 与 Asset event 只用于传输/资源收敛，不得推进或覆盖 canonical specification revision。
• Main 只向 Renderer 投影已知错误码的固定中文提示，未知上游错误文本必须脱敏为通用提示；Works Token、stream ticket、provider internals 留在 Main/服务端。
• AI 绘画 Workspace JSON 请求与 shared Works token refresh 必须覆盖取凭据、发请求和读取响应 body 的完整 30 秒 deadline；即使底层 transport 忽略 abort，调用方也必须确定性结束为 504 DESIGN_WORKSPACE_REQUEST_TIMEOUT 并释放共同等待者。Electron-to-Node 透明 fallback 仅允许 GET/HEAD/OPTIONS；mutation 不得因 transport failure 被隐式重放，任何重试必须由上层显式幂等合同授权。
• design.quote.request 必须绑定 exact current Specification revision 并返回 immutable Quote；任何 production-meaning edit 都需要新 revision 与新 Quote。
• design.generation.confirm 只提交 Quote identity。客户端不编辑 provider Prompt/model/route/storage，不计算 Token Points，也不把 Task recovery 当作再次确认授权。
• 图片/视频 source 必须是当前 Workspace 的 canonical Asset，并通过 typed binding 进入 Specification；medium/role 决定用途，不得从 quick-reply 文案、V1 Brief 或本地路径推断。
• Task/Asset reconciliation 只能更新 Workspace resources；已经落库但事件迟到的 Task 可通过 refresh 恢复，不能覆盖 Living Form、local drafts 或 pending Design input。
• 删除 Canvas 项目必须要求用户完整输入项目名并通过 Main-owned Workspace DELETE。成功后被删 Workspace 的会话、任务和资产不得继续留在 Renderer 可访问状态；服务端决定软删除、任务取消、预留积分释放和运行中任务结算。
• Prompt Museum 只展示服务端审核并带稳定作者、来源、许可证/署名和素材授权信息的内容；客户端不内置数据集、不推断缺失版权、不提供投稿/点赞/评论/收藏/关注/排行，也不自动发送或生成选中的 Prompt。
• Prompt Museum Renderer 只能通过 Main-owned 固定 GET 路由读取列表和详情。Works Token 不得进入 Renderer；列表查询只允许搜索、使用场景、风格、主体、语言、模型、游标和限制字段。需要受保护图片时必须新增 Main-owned 媒体代理，不能把 access token、内部路径或用户隐私放进图片 URL。
• 产品界面当前只支持中文；系统语言与历史持久设置中的其他值必须归一为 zh，不得保留不可达的伪语言选择。
• Learning 是登录必需且受 module_access.learning 控制的运营精选项目目录。客户端只提供项目列表、README 详情和用户触发的 ZIP 下载，不提供课程生成、进度、本地课程库、OpenMAIC 播放、Agent、ASR 或课堂 runtime，也不保留旧 API/数据兼容读取路径。
• Works Square 运营后台拥有项目名称、摘要、封面、标签、版本、排序、状态、Markdown、ZIP、声明字节数和 SHA-256。只有冻结了元数据、媒体和归档校验结果的 published 项目可被客户端列表或详情读取；客户端不提供上传、编辑或发布入口。
• README 使用安全 Markdown/GFM 并禁用原始 HTML。运营发布时必须解析 Markdown，只保留无凭据、默认端口、无 fragment 且当前 DNS 全部指向公网地址的 HTTPS 图片 URL；不得下载、识别格式、转码或镜像 README 图片。客户端仅允许 Markdown 图片节点直连这些 URL，支持范围和可用性由 Electron 与远程 origin 决定；封面和历史发布媒体继续走受控媒体路径。
• Main 打开原生保存对话框，将项目 ZIP 下载流写入临时文件，只允许无 userinfo、最多五跳且保持 Works origin 的重定向，重定向请求不携带 Bearer；客户端下载不校验 Content-Length、archiveBytes、实际流字节数或大小上限，只在 SHA-256 与 ZIP 签名匹配后原子重命名。Works Square 可保留独立的运营上传/存储限制。Renderer 不得获得 Works Token、对象存储地址、任意下载 URL、临时路径或最终本地路径。
• 新客户端不读取、迁移或展示历史下载课程，但也不自动删除用户现有课程数据。任何清理功能必须另行设计为用户明确控制的可恢复维护动作。
• game-engine 不再是内置 Coding Skill。planning-with-files 在复杂任务中把 task_plan.md、findings.md、progress.md 写到当前项目根目录；不得写入 Skill 安装目录或用户目录。
• Robot V1 在现有 Binding 体验内扫描符合条件的开放 Xiaozhi-* 配网热点，并只连接用户明确选择的短效候选；该便利信号不得宣称为可信设备发现、自动下发家庭 Wi-Fi、自动认领或自动确认在线。
• Guided Hotspot Binding capability 由 Electron Main 持有且默认开启。精确 NIANCODE_AI_HARDWARE_GUIDED_HOTSPOT_BINDING=0 关闭引导；关闭或 capability 读取失败时保留现有六位码 Binding，Renderer 可以读取但不能覆盖它。
• Robot hotspot scan/connect 必须由 Electron Main 持有并在读取 Works 凭据前本地完成。Renderer 只能提交最近扫描生成的短效不透明 candidate ID，不能提交任意 SSID、BSSID、接口、profile 或命令。
• 只有开放、可连接、可打印、UTF-8 不超过 32 bytes 且以 Xiaozhi- 开头的候选可进入页面。连接只有在当前 SSID 与候选完全一致时成功；权限、平台、扫描或连接失败必须保留系统 Wi-Fi 兜底。
• Robot portal 必须由 Main 以系统浏览器打开固定 http://192.168.4.1/。Renderer 不得提交任意 URL；该本地动作不得读取 Works 凭据或访问云端。
• Wi-Fi SSID/密码只在现有固件 portal 内输入。Makelore 不收集、不代理、不日志记录、不持久化 Wi-Fi 凭据。
• 产品已明确选择在保留当前固件行为时 default-on；开放 SoftAP 与明文 HTTP portal 仍是已知残余风险，不能据此推断安全风险已被单独验收。界面必须保留不在不可信公共环境操作的警告。未核对精确固件镜像、六位码发行/消费契约、原生 opener E2E 与真机 smoke 前，不得宣称完整兼容或端到端验收；现场异常必须可用精确环境值 0 回滚。
• Binding 成功仅表示设备与账号/Agent 的云端关系建立，不表示设备在线或业务协议 ready。
• 同一进程内无法确认结果的 Binding 重试必须复用原 operation ID。无效、过期或已消费 activation code 必须清除 code 与 operation ID；下一个新码使用新 operation ID。Main 必须把 ai_hardware_activation_code_invalid 投影为 non-retryable，不信任上游相反标记。
• 应用重启后，当前 overview DTO 不能证明旧码对应的 Binding 结果；客户端不得重放旧码或旧 operation ID，必须要求新码，无法取得时停止流程。

Open Questions

• 生产整链需要真实账号、新上传/校验合同、OSS immutable Release、CDN/Edge、运营审核、App 播放与监控环境完成最终验收；当前客户端验证不能替代该验收。
• 是否需要在生产发布链引入绑定精确 Release/digest 的可信 runtime verifier；当前客户端 loopback preflight 不能承担该职责。
• 在一个客户端兼容版本且服务端与存量数据稳定提供 play_url 后，移除 runtime_url 回退。
• Design V2 发布前必须在停止服务的目标数据库运行 cutover dry-run、解决全部 blocker、显式 apply 并验证 remaining legacy rows 为零；客户端与服务端必须成对部署。
• 图生图随客户端发布前，需确认相匹配的服务端 image_to_image Brief/Quote/Task 冻结、私有源图复核与 Bailian edit 执行链已部署，并使用真实 Workspace Asset 完成生产 smoke。
• Updater 生产恢复仍需对齐权威版本、发布正式签名/公证的平台产物，并从旧安装版本执行发现、下载、重启和安装 smoke；源码提示修复本身不构成发布链恢复。
• AI Canvas V2 仍需安装包真实账号 smoke：direct edit、chat edit、Quote request、confirmation、background completion、result download 与 deliberately interrupted unknown-result retry；生产 Provider 激活需另行授权。
• Robot Guided Hotspot Binding default-on 发布仍需确认指定硬件/固件确实提供被审计的开放 Hotspot/Portal、部署端签发严格六位 ASCII 数字码且与 Works validator 的时效/消费语义一致，并完成 Windows 真机、签名 macOS x64/arm64 native worker/association 与真实设备端到端 smoke。
• Prompt Museum 客户端契约和页面完成不等于 Works Square 内容后台、审核数据或 CDN 已部署；上线前需以真实登录账号验证列表、详情、署名链接、分页、图片和 Prompt 回填。
• Learning 客户端集成不等于 Works Square 运营后台、对象存储或项目 API 已部署；上线前需先部署服务端合同，再以真实账号验证发布/下架、分页、远程 HTTPS README 图片（含 SVG 与失败隔离）、保存取消、缺失或错误 Content-Length 的 ZIP、摘要/签名错误以及 Windows/签名 macOS 安装包。
• 四模块入口策略上线前需确认 Works module_access migration/API 已部署，安装包包含对应客户端，并用真实账号逐一关闭四个模块验证卡片、根/深层/别名路由和独立 API 授权。
• Makelore Code 当前只有 Windows x64 最终安装包和 WSL2/WSLg Linux 证据。macOS x64/arm64 与 native non-WSL Linux desktop/compositor 尚未验收；在补齐前不得宣称 cross-platform release-ready。真实 Provider 风险虽经用户明确豁免，但仍不得从 loopback/provider-shaped smoke 推断为真实 Provider Pass。

Last Reviewed

2026-08-31