wangxuming/makelore
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
0eed70fa637f70b22be5eda7af400a702ee4a7f2
makelore/.project-docs/40-domain/business-rules.md

38 KiB
Raw Blame History

Business Rules

Project conversations and distributed agents

  • 每个新项目创建内部默认 Agent，普通界面无 Agent 创建步骤或分组列。defaultAgentId 选取已存默认、置顶或首个可用 Agent；历史 Agent 与会话绑定不重写，不重新启用停用/归档 Agent。
  • 项目直接显示会话并保留归档、改名、未读、运行状态；打开项目不创建空会话。首次发送或显式新建才创建。项目设置编辑默认配置，历史会话仍能定位原绑定配置。
  • 老师使用 Yuxi 原生配置和云资源，新话题可选择运营下发的老师，旧话题固定版本。Main 只提供当前项目和本轮捕获的 Pi 公开消息/老师话题的三个只读工具，允许 .makelore/project.json，无本机写入或命令，不进入其他账号/来源记录；每次读取与续接检查绑定及取消状态。Yuxi 保存老师消息与收到的片段，完整本地工程不全量上传。
  • 同 requestId 相同输入读取已有请求结果，不同输入冲突；重启中的请求标记中断，账号退出中止，来源删除清理相关话题。带回回答追加草稿且不自动发送；已归档来源必须先恢复。
  • 运营只管理下发、同步、默认与启停，无重复提示词编辑器或试聊。老师聊天模型由学生账号付费，个人 Agents 保持创建者付费。正文、历史及带回草稿只接收云端主线程文本；忽略子线程文本仍推进游标。
  • 客户端不内置老师／朋友角色：名称、头像、简介、欢迎语、推荐问题及人格由服务端发布定义决定，通用讨论协议不定义人格。任意名称的下发智能体都遵守同一只读工具边界；不再按角色限制项目读取。
  • 当前咨询按账号、项目保存，每轮绑定所选操作会话；新话题选择下发项或运营默认项，旧话题固定原定义与版本。旧合成朋友话题及未发送草稿仅查看，不继续调用、不自动重绑定或提交；兼容路由／存储名不定义新角色。
  • 输入预算区分近似模型 Token 与精确云端 JSON 字节，编译和提交使用同一完整请求计量。保留当前问题、明确引用和固定指令，按需缩减来源节选；固定配置／讨论超限不误报为用户短问题过长，不静默提升预算或迁移旧话题。

依据：老师决定及 ADR-008。

Permanent Token Points

  • 账号不再具有会员或订阅等级、周额度或重置卡。真实新注册一次赠送 100 点；旧账号不补送、不折算，存量旧权益直接取消。充值 1 元人民币兑换 50 点，点数永不过期。所有资格、价格、余额、赠送和入账以 Works Square 为权威，客户端不以首次登录推测新注册或自行补点。
  • 家长只给本人钱包充值。青少年可以看本人精确余额；另一付款方的共享钱包只展示可用性，不展示金额、点数或其账本。付款资格与余额可见性分别来自服务端，不再依赖旧会员管理权限。
  • family_shared=true 不足以判定是否隐藏余额：付款方自己的钱包也可能带此标记。shared_available 为布尔值时投影另一付款方的粗粒度余额；为 null 时保留本人精确余额，包括 entitlement_source=self 或 shared_group 的本人家庭钱包。
  • AI 编程明确选择付款来源，余额不足时不静默切换。云智能体仍由创建者付费，Plugin 仍用个人付款；共享付款不授予其他账号内容、订单或流水权限。
  • 充值必须由用户明确发起，Renderer 不传付款人、价格或认证凭据。一次意图复用原请求身份；结果不明时只允许同身份重试，待支付或人工核对订单先恢复原订单。订单创建时冻结金额和点数，商品改价不改变旧单，服务端确认前不展示到账。
  • Main 代理固定账务路由并投影公开字段，切换账号后丢弃旧结果；重新打开账号菜单或窗口获得焦点时刷新余额。移除旧重置卡卡包与兑换流程，历史任务记录不再定义当前权益。

依据：用户确认的永久点数政策、源 a1cce42 与集成记录。

Code conversation titles and archive

  • 新建自动命名会话使用首条真实、完整、非空用户消息的首行，合并空白并截取最多 32 个 Unicode 字符；纯图片消息使用“附件对话”。斜杠命令、乐观消息和助手输出不触发命名；不调用模型生成标题。
  • 自动标题只设置一次。手动重命名去除首尾空白、最多 200 字符，并始终优先；历史会话和分支会话按手动标题处理，不自动回填或覆盖。仅标题变化不改变会话排序时间。
  • 归档只是会话列表管理，不删除历史、不停止正在运行的任务。已归档会话可查看、审批和中止既有工作；新 prompt/steer/follow-up 与 fork 必须先恢复，已接受请求的去重结果仍可读取。
  • 每个 Agent 提供归档数量及归档列表。归档最后一条最近会话时不自动创建替代会话；恢复沿用原会话并回到最近列表。菜单操作不应隐式切换或准备目标会话。

Managed model capabilities

  • 受管模型的图片输入与思考选项来自 Works v2 官方能力投影，未知、false 和空原生 effort 列表分开处理，不靠本地模型清单推测。运营激活与能力事实分离。
  • Main 在 prompt 前校验并保存 reasoningChoice，保留任意已声明原生 effort；default 省略供应商控制字段，disabled 只在供应商支持时提供。父/子运行使用冻结上下文，Renderer 与 Pi model.input 使用同一模态依据。
  • BYOK、本地配置以及独立 Web Search 适配器策略不受本项取代；首期没有 budget 编辑器。

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. The code-owned project-wide identities are makelore.data-service, makelore.game-resource, makelore.game-audio, and makelore.project-scaffold: their existing delivery/acquisition and project enablement remain separate, but project enablement intentionally makes their Skills/tools available to every parent Agent without creating or requiring assignment 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; project enablement makes its Skill/tools available to every parent Agent.

  • Code-owned Game Resource and Game Audio are optional bundled hosted Plugins. Their exact schema-2 manifest, Skill, and tools ship with MakeLore, so it has no device download, update, Beta, signature, or device-uninstall state. Account Library acquisition/removal, project enablement, 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 a delivered/installed, enabled, trusted, compatible, policy-admitted parent Pi logical thread. Agent assignment is an additional gate only for Plugin identities whose activation scope requires it; the four code-owned project-wide identities bypass that gate. 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. A confirmed Game Resource generation is one Main-owned submit-and-deliver operation: submit once, poll internally, download every terminal output, and save it below assets/generated/game-resource/<executionId>/ in the project frozen at call time. Provider/billing state and local delivery state remain separate. A delivery retry or application restart may resume only local download/save work and must never submit or charge again. The shared project write lease is held only while materializing terminal outputs; the Agent does not choose paths, poll status, or confirm saving again.

  • Game Audio requires MakeLore >=2.0.1 and follows the same single-confirmation automatic delivery policy under assets/generated/game-audio/<executionId>/. Main persists intent before submitting and uses operation lookup after response loss; resume never repeats the POST. Full music, separately requested preview and sound have authoritative server pricing. Saved files support click-only local audio controls, no autoplay or remote Provider playback. Project-wide activation never requires partner assignment.

  • Native Web Search is a selected-model capability, not a Marketplace Plugin. Only an exact verified capability may place makelore_web_search in a frozen parent worker; it uses that worker's current model/provider/credential and ordinary model billing. Unsupported models expose no tool, child workers receive none, and the implementation must not switch models, call the retired hosted client, create a Plugin Charge, or fall back to agent_browser.

  • Device Packages are local Main-owned installations created only through conversation. Inspect/preview and a distinct later confirmation precede commit; there is no visible install/source-picker UI. Accepted npm, Git, absolute local Plugin-directory, and loose SKILL.md sources become immutable generations and default enabled. Lifecycle scripts never run. Pi extensions and non-empty standard Skill scripts/ subtrees are executable code and execute with desktop-user authority only after that fact is disclosed and confirmed. Parent Pi workers and the shared Agent Server receive the non-overridable application Node path as MAKELORE_NODE_EXECUTABLE; portable Skills must not fall back to system Node. New and idle parent workers refresh automatically, active parents switch only after settlement, and child workers never inherit Device Package resources.

  • Device Packages appear as a separate 本机 source beside Official Plugins in the unified Plugin workspace and never enter Account Library, Marketplace Package Store, Release, Channel, Admission, project enablement, Agent assignment, or server billing state.

  • Project Configuration owns the only user-visible unified Plugin workspace. Its 插件 ResourceCard opens /project-config/plugins as a same-page wide sheet while the configuration page remains mounted. Code sidebar must not add a standalone Plugin entry; /plugins and older Plugin URLs are compatibility redirects only.

  • 共享开发浏览器必须绑定当前项目和当前 generation。Renderer 的 project_id 与 viewport presentation 仅可由具备 Renderer capability 的请求使用；新浏览器首次 open 必须等待真实可见 bounds 后才报告成功。已初始化页面切回操作对话时只隐藏， 仍可执行工具；重复 open 或导航不得强制切换用户标签。隐藏截图按需请求一帧， 保留原 CDP 参数，不展示页面或转移输入焦点。非 Web 协议、文件注入、跨 target 与 宿主级 CDP 命令保持拒绝，诊断按 owner 引用计数；明确关闭浏览器、项目/模块切换、 窗口隐藏或后台休眠仍必须销毁 view、detach debugger 并停止无所有者轮询。

  • Code-owned official bundled Plugins may be platform_hosted or skill_only. Data Service is system-included; Game Resource, Game Audio and makelore.project-scaffold retain Account Library, project enablement, Release, and Admission state where applicable, while their exact resources ship only in the signed client. All four are project-wide: once their delivery/acquisition condition is satisfied and they are enabled for a project, every parent Agent receives the full resource set without partner assignment; child Agents remain empty. Downloadable Marketplace artifacts remain P0 text/image-only and must reject .mjs; official bundled authority is not inferred from provider metadata or an uploaded ZIP.

  • 面向用户的 AI 编程新建流程只要求选择目录，不展示 ProjectType、模板、原始项目 UUID、绑定或独立副本选项。Renderer 写入内部默认 interactive_ai_app，Main 自动生成 UUID；创建后类型仍不能通过 UI 或 Host API 修改。既有 custom 项目继续可用，历史 mini_game / mini_program 仅在读取边界归一为 interactive_ai_app 且不改写配置；未传类型的底层兼容 API 调用仍按 custom 处理。

  • 新建项目只原子生成 .makelore/project.json 和 knowledge/，完成后可直接进入聊天；有效旧配置仅缺 projectId 时由 Main 串行生成并持久化一次 UUID。缺失或无效的其他 metadata 仍进入 Project Configuration；旧 initialized 布尔仅为兼容字段，不得作为有效项目的导航、工作区或 Agent 创建 gate。

  • 从 Makelore 移除 Code 项目只取消本机列表登记，不删除磁盘配置或项目内容。普通“新建项目”直接选择已有有效配置的文件夹时，Main 应重新登记并打开，保留原项目身份、类型、Agent、Conversation 和知识文件；重复选择已登记目录不生成重复卡片。无效的既有配置必须提示错误且不能覆盖；新建下级目录仍拒绝同名路径，底层显式绑定身份的创建操作保持既有冲突语义。

  • 交互式 AI 应用的固定六文件 Vite 起步树只能由用户可选地明确调用官方 bundled makelore.project-scaffold Plugin 中的 makelore-project-scaffold Skill 生成。Skill 不是项目创建、进入聊天或创建首个 Agent 的前置条件；脚本必须先预检全部目标、不得覆盖已有路径，受控失败只回滚本次创建内容，且不得安装依赖、访问网络、构建、上传或提交审核。

  • ProjectType 不等于 BuildPreset 或 Scaffold 状态：规范可发布类型映射到内部受控 Vite preset；本地 projectType 和 Skill 检测结果都不是授权边界，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 天未使用才要求重新授权。

  • 账号词元点数通过 Main-owned Works Square 账务路由投影；本人精确余额与另一付款方的粗粒度余额遵循上述永久点数规则。格式或枚举不符合闭合 DTO 时整份响应 fail closed，不透传上游内部账务字段。

  • “记住密码”是独立于七天会话的可选桌面凭据记录：只能由 Electron Main 在正式安装包中通过可用的系统安全存储加密落盘，账号密码不得进入 Renderer 持久状态、日志或 Works Square 持久化。退出登录和短信登录保留记录；只有成功的未勾选密码登录清除旧记录。系统安全存储不可用或未打包开发版必须禁用该选项。

  • 运营端可按用户关闭 Code、Canvas 或 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 编辑不得等待逻辑线程；未解析或尚无 worker 的 Conversation 选模必须先验证新模型、持久化 resolved metadata，再 prepare，不能要求旧模型仍可用。已有正常 worker 的同账号模型变化复用 target set_model；已崩溃 worker 用新选择重建，跨账号变化等 active run settled 后只重建目标逻辑线程。模型下架提示重新选择，显式更换保留原会话与历史，不自动选模或重发消息。

  • 正式包中的父 Agent Server 必须从显式 staged pi-runtime manifest/root 定位 Pi 包及其导入入口，并验证入口仍位于目标包目录内；不得从脚本相邻资源目录、应用 node_modules、系统 npm 或网络下载回退解析。

  • 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。

  • lifecycle:sleep 必须关闭旧 Coding SSE；编程视图挂载、项目上下文变化、页面重新可见或窗口 focus 必须静默刷新已选 Conversation 的 Main-owned Snapshot，即使 Conversation id 没有变化。该流程只协调权威状态，绝不重放 accepted/uncertain mutation。

  • 隐藏 Conversation 的红色注意标记只可由新的 pending interaction，或当前 run 新进入 completed、failed、aborted terminal 触发；助手流式文字、thinking、工具过程、单个工具失败以及已经见过的相同 interaction/terminal 更新不得创建或重新创建标记。

  • 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 前保持本地。

  • AI Design 必须以自然对话帮助用户描述清楚需求：先提取和复述已明确内容，每次最多推进一个真正影响作品的问题。客户端 Current Specification 投影是辅助摘要和可选手动调整，不得把内部字段、缺项或普通 Decision Prompt 变成用户必须逐项填写的表单。

  • 每个 mutation 使用稳定 command 与 semantic operation identity。transport-unknown 只能重放原命令；business rejection、timeout 或用户再次点击不能自动生成新的业务意图。

  • Direction projection 是 Specification 真值。event cursor、assistant delta、Task progress 与 Asset event 只用于传输/资源收敛，不得推进或覆盖 canonical specification revision。

  • 用户提交 chat 后，客户端可以立即把同一个 pending operation 投影为临时用户气泡，并明确显示“发送中”或“正在确认”；只有服务端返回的 canonical turn 才进入 conversation timeline。确定失败时必须让原草稿重新可编辑，不得把临时投影持久化为第二条消息。

  • design.assistant.delta 只用于未完成回复的传输和结果收敛，不得进入 canonical conversation timeline。客户端可以把它临时显示为与同一 pending chat identity 绑定的单个未完成助手气泡；确定收敛后必须由 canonical turn 替换，unknown outcome 则保留原 identity 与已有片段。不得把片段伪装为完成回复、持久化为第二条消息、因其他 operation 更新而全局清除，或另加独立的整理进度栏。AI 当前整理出的设计理解仍由中央 active 制作方案中的 Current Specification 公共投影承载；连接重叠或事件重放按 connection generation 与 chunkIndex 去重收敛。

  • design.assistant.progress 只能由 Main 把服务端闭集 stage 归一为固定、通俗的活动文案，并附着在同一 pending chat identity 的 optimistic user bubble 下。它是可更新、可折叠的瞬时 presentation state，不是消息、Current Specification、任务授权或模型思考过程；不得显示 chain-of-thought、prompt、Provider response、tool argument、任意服务端文案或未验证模型文本。终态、重连和重放必须按原 operation identity 收敛。

  • 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。对话或 Current Specification 就绪态可以引导用户请求并查看 Quote，桌面端可定位到报价区、移动端可打开报价面板，但该动作不得创建 Task。

  • Quote 前先通过同一 Main-owned 输入协议执行 prepare_generation，并使用返回的最新 revision；明确失败必须停止报价，不能因未收到实时 blocker 事件而使用旧方案。准备不生成聊天消息或付费任务；视频运动由服务端模型整理，返回的创作提示词必须同步展示。类型、画幅、时长和数量只使用服务端分媒体 generation_options，不能只显示却不保存时长或自行假定可用能力。

  • design.generation.confirm 只提交用户明确确认的 Quote identity。客户端不编辑 provider Prompt/model/route/storage，不计算 Token Points，也不把聊天就绪文案、Quote 展示、重复点击或 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 可访问状态；服务端决定软删除、任务取消、预留积分释放和运行中任务结算。

  • Canvas 桌面布局把 conversation 与唯一 active 制作方案放在中央，把 Workspace 选择/创建/删除放在 320–340 px 全高右侧 Works rail；紧凑布局使用同一个右侧 Sheet。Canvas 路由不挂载全局左栏，也不得恢复“获取灵感”入口。

  • Active 制作方案的 content.concept 是用户可直接编辑的最终 Prompt。Reference 通过稳定 reference ID、真实 Workspace Asset binding 和连续 @图片N alias 关联；Prompt 表达创意用途，binding row 管理缩略图、alias、文件与替换/解绑状态，并允许明确选择“视频开始画面”。开始画面必须同时绑定 first_frame role 与 Asset identity，“已选用”不能根据文本 alias 推断。不支持的引用保留并提示用户明确调整/解绑，不删除 Asset；不得重复 purpose/preserve/style/strength 编辑器。

  • 引用了未绑定 alias 时必须显示对应上传位并阻止 Quote 请求/确认。添加、替换、删除 reference 必须通过既有 typed operations 形成新 Specification revision；删除同时清理 binding 并重排后续 alias，已有 alias 不重复插入。Reference 数量/媒体上限只能来自服务端能力，不得复制外部参考产品的硬编码限制。

  • Prompt Museum 已退出当前产品面：Canvas 不显示入口，App 不挂载或打包其 Renderer 页面，历史 /image-prompts 路由只返回 /image-canvas。未经新的明确产品决策，不得恢复入口或页面。

  • Dormant Prompt Museum Main API/auth/media validation 和共享 DTO 可为兼容/安全保留，但 Works Token、内部路径或用户隐私仍不得进入 Renderer；保留代码不代表服务端内容、授权或产品入口已启用。

  • 产品界面当前只支持中文；系统语言与历史持久设置中的其他值必须归一为 zh，不得保留不可达的伪语言选择。

  • Learning 已从产品入口、路由、Renderer、Main Host API、共享 DTO 和打包资源中移除，不保留兼容实现。客户端不读取、迁移或展示历史下载课程，也不自动删除用户现有课程数据；任何清理功能必须另行设计为用户明确控制的可恢复维护动作。

  • 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。
  • 三模块入口策略上线前需确认 Works module_access migration/API 已部署，安装包包含对应客户端，并用真实账号逐一关闭 Code、Canvas、Robot 验证卡片、根/深层/别名路由和独立 API 授权。
  • Makelore Code 已有 Windows x64 最终安装包证据、WSL2/WSLg Linux 证据，以及 macOS arm64 本地未签名 DMG 的 mounted-image Agent Server initialize/shutdown 证据。macOS arm64 的签名/公证与完整 process-enumeration gate、macOS x64、native non-WSL Linux desktop/compositor 仍未验收；在补齐前不得宣称 cross-platform release-ready。真实 Provider 风险虽经用户明确豁免，但仍不得从 loopback/provider-shaped smoke 推断为真实 Provider Pass。

Last Reviewed

2026-09-22