231 lines
38 KiB
Markdown
231 lines
38 KiB
Markdown
# Business Rules
|
||
|
||
## Project conversations and distributed agents
|
||
|
||
- 每个新项目创建内部默认 Agent，普通界面无 Agent 创建步骤或分组列。defaultAgentId 选取已存默认、置顶或首个可用 Agent；历史 Agent 与会话绑定不重写，不重新启用停用/归档 Agent。
|
||
- 项目直接显示会话并保留归档、改名、未读、运行状态；打开项目不创建空会话。首次发送或显式新建才创建。项目设置编辑默认配置，历史会话仍能定位原绑定配置。
|
||
- 老师使用 Yuxi 原生配置和云资源，新话题可选择运营下发的老师，旧话题固定版本。Main 只提供当前项目和本轮捕获的 Pi 公开消息/老师话题的三个只读工具，允许 `.makelore/project.json`，无本机写入或命令，不进入其他账号/来源记录；每次读取与续接检查绑定及取消状态。Yuxi 保存老师消息与收到的片段，完整本地工程不全量上传。
|
||
- 同 requestId 相同输入读取已有请求结果，不同输入冲突；重启中的请求标记中断，账号退出中止，来源删除清理相关话题。带回回答追加草稿且不自动发送；已归档来源必须先恢复。
|
||
- 运营只管理下发、同步、默认与启停，无重复提示词编辑器或试聊。老师聊天模型由学生账号付费，个人 Agents 保持创建者付费。正文、历史及带回草稿只接收云端主线程文本；忽略子线程文本仍推进游标。
|
||
- 客户端不内置老师／朋友角色：名称、头像、简介、欢迎语、推荐问题及人格由服务端发布定义决定，通用讨论协议不定义人格。任意名称的下发智能体都遵守同一只读工具边界；不再按角色限制项目读取。
|
||
- 当前咨询按账号、项目保存，每轮绑定所选操作会话；新话题选择下发项或运营默认项，旧话题固定原定义与版本。旧合成朋友话题及未发送草稿仅查看，不继续调用、不自动重绑定或提交；兼容路由／存储名不定义新角色。
|
||
- 输入预算区分近似模型 Token 与精确云端 JSON 字节，编译和提交使用同一完整请求计量。保留当前问题、明确引用和固定指令，按需缩减来源节选；固定配置／讨论超限不误报为用户短问题过长，不静默提升预算或迁移旧话题。
|
||
|
||
依据：[老师决定](../10-decisions/ADR-2026-09-22-coding-teacher.md)及 [ADR-008](../10-decisions/adr-008-interactive-ai-app-scaffold.md)。
|
||
|
||
## Permanent Token Points
|
||
|
||
- 账号不再具有会员或订阅等级、周额度或重置卡。真实新注册一次赠送 100 点；旧账号不补送、不折算，存量旧权益直接取消。充值 1 元人民币兑换 50 点，点数永不过期。所有资格、价格、余额、赠送和入账以 Works Square 为权威，客户端不以首次登录推测新注册或自行补点。
|
||
- 家长只给本人钱包充值。青少年可以看本人精确余额；另一付款方的共享钱包只展示可用性，不展示金额、点数或其账本。付款资格与余额可见性分别来自服务端，不再依赖旧会员管理权限。
|
||
- `family_shared=true` 不足以判定是否隐藏余额：付款方自己的钱包也可能带此标记。`shared_available` 为布尔值时投影另一付款方的粗粒度余额；为 `null` 时保留本人精确余额，包括 `entitlement_source=self` 或 `shared_group` 的本人家庭钱包。
|
||
- AI 编程明确选择付款来源，余额不足时不静默切换。云智能体仍由创建者付费，Plugin 仍用个人付款；共享付款不授予其他账号内容、订单或流水权限。
|
||
- 充值必须由用户明确发起，Renderer 不传付款人、价格或认证凭据。一次意图复用原请求身份；结果不明时只允许同身份重试，待支付或人工核对订单先恢复原订单。订单创建时冻结金额和点数，商品改价不改变旧单，服务端确认前不展示到账。
|
||
- Main 代理固定账务路由并投影公开字段，切换账号后丢弃旧结果；重新打开账号菜单或窗口获得焦点时刷新余额。移除旧重置卡卡包与兑换流程，历史任务记录不再定义当前权益。
|
||
|
||
依据：用户确认的永久点数政策、源 `a1cce42` 与[集成记录](../30-worklog/tasks/20260922-integrate-permanent-points-client-38f5b921.md)。
|
||
|
||
## 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
|
||
|
||
- 微信渠道按扫码账号独立连接并选择目标智能体，多个账号可以指向同一已发布智能体。只接受可信扫码身份；没有使用范围、联系人邀请或单调用者授权管理。创建者付款不改变各账号和历史受邀内容的隔离；旧邀请不恢复、不兑换、不交付遗留结果。详见[渠道决定](../10-decisions/ADR-2026-09-11-personal-cloud-agents.md)。
|
||
|
||
- 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
|