Merge remote-tracking branch 'web/master' into feat/pixel_art2

# Conflicts: # .codex/skills/genarrative-external-editor-api/SKILL.md # .codex/skills/genarrative-external-editor-api/references/api-selection.md # docs/project-memory/shared-memory/decision-log.md
2026-08-03 07:47:17 +00:00
parent 3f6a8e7a0c 04a6be5c3d
commit 21da0c8380
65 changed files with 7399 additions and 1287 deletions
@@ -205,6 +205,15 @@
 - 验证方式：以当前 run 成功 `preview.validate` revision N 后断言 iframe 自动出现且 server 归 Tauri registry；再完成 revision N+1，断言 server 进程和 loopback origin 不变、iframe 重新加载新内容且所有响应为 `no-store`。Runner registry 单独 running 不得让页面显示预览；相同 / 更低 revision 不得刷新；停止预览后顶部必须显示“预览未启动”；构建产物和安装信息必须为 `0.1.1`。
 - 关联文档：`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`、`docs/project-memory/shared-memory/development-workflow.md`。

+## 2026-08-03 开放 Issue 115、118、127、128 的修复边界
+
+- AGC 的 MCP 目录以 server 为隔离单元：可选 server 的连接、tools/list、工具归一化或聚合容量失败只关闭该 server，required server 仍失败关闭；MCP schema 包入原生 action 后只沿 subschema 关键词重定位当前 document 根的 JSON Pointer fragment，`default / const / examples / enum` 等数据值、命名 anchor 与 `$id` resource 内 fragment 保持不变。Anthropic strict 不由 `apiKind` 单独推断：AGC 只对官方 HTTPS endpoint 与 Claude 4.5+ 版本化 model id 显式开启，旧模型、未知别名和兼容网关默认关闭。开启后使用官方支持关键词白名单生成专用传输 schema，剔除不受支持的约束但不修改调用方原 schema；未知关键词、不可解析 / 递归 `$ref` 或请求复杂度超限时保持 non-strict。最后一个工具设置 ephemeral prompt-cache breakpoint；usage 统计把 cache creation / read token 一并计入 prompt 和 total。
+- Windows 私有 ACL 检查复用 `Get-Item` 对象的 `GetAccessControl()`，避免从 PowerShell 7 启动时继承的模块路径让 Windows PowerShell 5.1 的 `Get-Acl` 加载不兼容模块；静态配置门禁禁止重新引入该命令。
+- 编辑器持久化的 `prompt` 统一表示规范化用户意图；provider `actual_prompt` 只保留在 resource / asset 审计字段，系统 prompt 不进入跨资源检索字段。角色和图标的透明图、切片继承源用户 prompt；本次只修新写入，不迁移历史记录，不修改 SpacetimeDB schema。
+- 画布收到生成完成等较新权威快照时，必须把同项目待保存或在途的本地布局重放到新 revision：后端资源与生成终态优先，本地布局编辑优先；后端新增项合入，后端删除项和用户本地删除项均不得复活，合并后立即进入既有串行 CAS 保存队列。
+- 生成器合并必须把 `status / composerOpen / generatedLayerId / errorMessage / generation timestamps / characterAnimationResult` 视为后端生命周期事实；生成完成快照继续保持 `composerOpen=false`，不得被本地在途快照重新展开。提示词、参数和占位位置等本地布局编辑继续保留。
+- 同项目权威快照刷新不得无条件选择第一张图层：当前仍有效的单选、多选和生成占位选择保持，已删除的选择过滤，本来未选择时保持空选；只有首次载入或切换到另一项目时才默认选择第一张可用图层。生成完成结果需要用户显式点击后才进入选中态，后台完成回包不能偷走用户当前焦点。
+
 ## 2026-07-30 Provider 503 等待与耗尽状态使用严格字段派生的安全摘要

 - 背景：game-chat 的进度卡只显示“等待 Provider upstream-5xx 瞬态故障退避到期”，没有 HTTP 状态、重试次数或等待时间；重试耗尽后，Runtime 和持久 conversation 又可能直接展示 `fingerprint/chars` 或 `<absolute-path> [redacted sensitive context]`，用户既无法判断是否在恢复，也看不到可操作的失败原因。
@@ -5721,7 +5730,7 @@
 - 背景：旧创作模板退役时误把新版 `/creation`、桌面公共侧边栏和“我的”完整资料页一起缩减；只恢复视觉后，现役 profile client 又经 `rpg-entry` barrel 把旧作品库、旧 runtime request 和展示模型重新带入 Vite 与 TypeScript 图。
 - 决策：桌面端继续使用原平台公共结构，一级导航固定为 `创作 / 项目 / 我的`；顶栏保留编辑器项目 / 素材搜索、泥点入口和账号胶囊；“我的”全宽保留资料编辑、陶泥号、三项统计、充值、兑换码、社区、反馈、通用设置、API Key 和法律信息。搜索只面向编辑器项目与公开编辑器素材，不恢复旧公开作品搜索。
 - 依赖边界：公共 dashboard、钱包、充值、兑换码、邀请码、API Key 和设置请求迁入 `services/platform-entry`，公共账单展示迁入现役 profile model。Vite 新增退役模块 graph 门禁，ESLint 对现役源码禁止导入旧目录；目录 watch ignore、Tailwind source、tsconfig include 和 tree-shaking 都不能作为依赖隔离证明。
- 路由与响应式边界：`/creation`、`/project`、`/profile` 都是可刷新、可前进 / 后退的稳定路由；桌面端使用侧边栏，移动端必须提供同样 `创作 / 项目 / 我的` 的三项底部 dock，不得因隐藏桌面侧边栏而丢失移动导航。
+- 路由与响应式边界（2026-08-03 纠正）：`/creation`、`/project`、`/profile` 都是稳定路由，但旧模板退役不授权扩大移动端创作范围。桌面端使用 `创作 / 项目 / 我的` 侧边栏；移动端底部 dock 只保留“我的”，直达 `/creation`、`/project`、`/editor/canvas` 或从首页触发项目 / 画布动作时统一显示桌面端提示，不挂载创作主页、项目列表或图片画布。2026-07-18 同批加入的移动端三入口口径无效，不作为产品决策依据。
 - 公共设置边界：`runtime_setting` 保持原表结构与历史数据，但它是音乐音量和平台主题的现役账号级公共能力，不归入旧玩法数据壳。鉴权后的 `GET/PUT /api/runtime/settings` 必须经 `spacetime-client` 调用 `get_runtime_setting_or_default` / `upsert_runtime_setting_and_return`；保留该路由不构成恢复旧 runtime API 的先例。
 - 编译门禁：除旧业务目录外，`src/uiAssets.ts`、`src/types.ts`、`src/types/**`、`src/services/runtimeAudioFeedback.ts` 和 `src/services/publicWorkCode.ts` 也是顶层退役 module，必须同时退出 Vite module graph、TypeScript、ESLint 和 Vitest；`/audio/**`、`/chat.png`、`/fusion-pixel.ttf` 及旧 pixel / story-tab / 玩法 CSS 不得进入 dev 服务或生产产物。验收时必须同时检查 `tsc --listFilesOnly`、Vite 依赖图 / 产物和退役资产路径，不能只依赖 tree-shaking。
 - Rust 产物边界：`module-runtime` 继续承载账号、钱包、公共设置、追踪和 feature gate，但 `CreationEntry*`、旧公开作品、存档、浏览历史与游玩统计 DTO / command / mapper / 规则必须退出实际 rlib；只保留历史表需要的 `RuntimeBrowseHistoryThemeMode`、完整保序的钱包流水来源枚举等持久化 ABI。`check:server-rs-ddd` 必须执行 `check:module-runtime-artifact`，同时验证旧符号和字面量为零、必要 ABI 仍存在，不能以源码存在 `#[cfg(any())]` 或路由未挂载代替产物证明。
@@ -6061,3 +6070,17 @@
 - 分档的双向后果写进了断言注释：把用户上传的坏图（`Decode`）报成 500 会让客户端当服务端故障去重试；把服务端自身失败（`Encode` / `Processing`）报成 400 又会让用户以为是自己的输入有问题。另断言底层文案原样带上，否则「识别不到网格」与「解码失败」在用户侧无法区分。
 - 验证：删掉 `retry-after` 或把 `Decode` 改判 500，两条新用例分别精确变红。api-server 679 通过 / 3 失败（`wallet_refund_outbox` 本机环境失败，与基线一致），`cargo fmt --check` 通过。
 - 关联文档：`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
+
+## 2026-08-03 托管 MCP 未鉴权响应提供安全接入引导
+
+- 决策：`/api/external/v1/mcp` 缺少、格式错误或无法验证 Bearer API Key 时继续返回相同 HTTP `401`，并增加 `WWW-Authenticate: Bearer realm="genarrative-external-editor"` 与机器可读 `details.guide`。引导只说明 Bearer Header 格式、登录后在「开发者 API Key」创建密钥、原始密钥只显示一次、凭据不得进入聊天或仓库、配置后重试 `initialize`，以及公开 manifest、Skill 与 OpenAPI 地址。
+- 安全边界：三种鉴权失败不得通过 code、message、details 结构差异暴露 Key 是否存在；未鉴权响应不得包含 MCP tools、resources、owner 或内部鉴权诊断。其它 External v1 业务路由继续使用原通用 401，不继承 MCP 专用引导。
+- 关联：`server-rs/crates/api-server/src/external_api_auth.rs`、`server-rs/crates/api-server/src/modules/external_api.rs`、`docs/openapi/genarrative-external-v1.openapi.json`、`docs/【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md`。
+## 2026-07-31 External v1 生成统一异步并提供托管 MCP 与完整 Skill 包
+
+- 异步契约：External v1 的图片生成、图片编辑、图标图集、UI 素材提取、角色动画、视频、音效和背景音乐八类 POST 固定持久化入 `external_generation_job` 并返回 HTTP `202 + operationId/statusUrl/pollAfterMs`；不受站内 `GENARRATIVE_EXTERNAL_GENERATION_MODE=inline` 影响。每次逻辑生成必须携带稳定 `Idempotency-Key`，网络结果未知或调用方轮询超时时复用原键和原 operationId，不得换键重提。
+- 查询与结果：新增 owner-safe `GET /api/external/v1/generations/{operationId}`。`queued/running` 返回 phase/progress，`completed` 返回 compact 稳定 artifact 引用，`failed` 返回脱敏错误，跨 owner 按不存在处理。compact result 允许 objectKey、resource/asset ID、assetObjectId、尺寸、媒体类型、taskId 和告警；禁止完整 project/canvas、Data URL、Blob URL、临时 signed URL、内部 provider 原文和 lease/fencing 控制字段。
+- MCP：新增托管 `/api/external/v1/mcp`，使用现有 External API Key Bearer 鉴权和无协议 session 的 Streamable HTTP JSON direct 模式。MCP tools 从同一 OpenAPI operation 形成并复用 External REST router；生成 tool 显式要求 `idempotencyKey`，另有统一任务查询 tool。MCP resources 提供使用说明、OpenAPI、Skill 入口 `SKILL.md` 和 `references/capability-routing.md`、`references/api-operations.md`、`references/authentication-and-safety.md`、`references/requests-and-outputs.md` 四篇稳定 reference；日后新增 reference 时必须同步新增独立 resource。MCP Agent 直接调用托管 tools，不安装 CLI，也不将脚本、测试或 workflow 暴露为 MCP resources。禁止开放内部 SpacetimeDB MCP、worker procedure、controller 或队列控制面。
+- Agent 发现：新增公开 `agent-integration.json`、`skill/SKILL.md` 和 `skill.zip`。manifest 同时声明 MCP、OpenAPI、完整 Skill archive、SHA-256 和包内清单；archive 必须包含 `SKILL.md`、上述四篇 references、stdlib Python helper 和 `agents/openai.yaml` 七个声明文件，不能只提供 OpenAPI JSON，也不能包含 API Key、本机路径或个人配置。完整 `skill.zip` 只供不支持 MCP 或需要本地文件上传编排的 Agent 使用，不作为 MCP resource。
+- 兼容边界：这是基于「截至 2026-07-31 尚无外部第三方存量调用方」接受的 v1 原地 breaking change；一旦出现外部活跃 Key、公开契约或联调方，后续破坏性变更必须保留兼容、经过弃用期或升级 `/api/external/v2`。
+- 关联文档：`docs/【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md`、`docs/technical/【后端架构】外部生成Worker化方案-2026-06-03.md`、`.codex/skills/genarrative-external-editor-api/SKILL.md`。
@@ -595,7 +595,7 @@ npm run check:server-rs-ddd

 - 移动端优先，再兼容网页端。
 - 页面只展示后端返回的状态，不自行计算结论型业务状态。
- 现役一级入口为 `/creation`、`/project`、`/profile`，桌面侧边栏和移动端底部 dock 都固定显示“创作 / 项目 / 我的”。`/creation` 只读取图片编辑器项目与 `GET /api/editor/showcase/resources`，不得重新接入旧模板入口配置、旧作品架或专属运行态。
+- 现役稳定路由为 `/creation`、`/project`、`/profile`。桌面侧边栏固定显示“创作 / 项目 / 我的”；移动端底部 dock 只显示“我的”，并对 `/creation`、`/project`、`/editor/canvas` 及页面内项目 / 画布动作统一显示桌面端提示，不挂载创作工具、项目列表或图片画布。桌面端 `/creation` 只读取图片编辑器项目与 `GET /api/editor/showcase/resources`，不得重新接入旧模板入口配置、旧作品架或专属运行态。
 - 旧创作模板目录和顶层旧业务模块必须持续退出 Vite、TypeScript、ESLint 与 Vitest；旧 `/api/creation-entry/config`、模板 API、公开作品详情和运行态 API 必须保持未挂载。SpacetimeDB 历史表、迁移白名单与必要兼容类型只作为数据壳保留，不得据此恢复业务逻辑。
 - 优先复用现有面板、抽屉、弹窗，不新建独立大系统。
 - 不在 UI 中默认写功能说明类文本。
@@ -4020,6 +4020,7 @@
 - 现象：旧 worktree 的 AGC Vite 长期占用 `127.0.0.1:3080`，marker 仍指向旧 API；新 worktree 启动 game-chat 后，配套后端在新端口 ready，随后 `beforeDevCommand` 因代理 target 不匹配返回非零，终端已经回到提示符，但原生客户端和它启动的 Runner 仍存活。客户端 WebView 实际加载旧 Vite，因此当前 master 的界面优化看起来全部缺失。
 - 原因：Tauri 的字符串 `beforeDevCommand` 默认 `wait=false`。只要固定 `devUrl` 上已有可访问页面，Tauri CLI 可以在配套启动脚本完成前创建原生窗口；旧实现又直接从 npm 启动 Tauri CLI，没有在 CLI leader 退出后继续持有其 PGID / Windows 进程树。`start-dev-stack.mjs` 虽会在后端 ready 后识别 marker/API 错配，但检查时机已经晚于窗口创建，且只清理自己登记的后端和 Vite。
 - 处理：`dev` 与 `game-chat` 统一先进入 `start-tauri-dev.mjs`，在启动 Tauri CLI 前无副作用检查 3080。现有 marker 只有 API target，不能证明监听器属于当前 worktree，因此任何已存在的 3080 都失败关闭，不主动杀不能证明归属的旧服务，也不因 target 看似匹配而复用。Tauri CLI 使用独立 POSIX 进程组，任意退出后按负 PGID 先 TERM、有界等待、再 KILL；Windows 固定调用 `taskkill /PID <pid> /T /F`。`start-dev-stack.mjs` 自己的后端 / Vite 独立组也在返回前有界收束。
+- Linux 容器边界：最小化 CI 容器的 PID 1 可能不回收孤儿后代，进程组在所有可执行成员退出后仍只剩 `Z` 僵尸；此时 `kill(-pgid, 0)` 仍成功，不能据此把已经完成的收束误报为失败。Linux 等待逻辑在 signal 探活后必须核对 `/proc/<pid>/stat`，只把同 PGID 的非 `Z / X` 成员视为存活；`/proc` 不可读时继续使用原保守判断，macOS 等其它 POSIX 平台仍只走 signal 探活。
 - 验证：定向测试必须覆盖旧 marker target 在 CLI spawn 前被拒绝、target 看似匹配仍拒绝无归属 Vite、非 HTTP 3080 失败、预检调用顺序、CLI leader 先退出后同 PGID 客户端仍收到 TERM、忽略 TERM 时升级 KILL，以及 Windows taskkill 的 `/PID /T /F` 参数。人工复验旧 worktree 占用 3080 时，新命令不得启动后端或弹出新窗口；正常启动后退出，确认 Tauri 客户端、Runner 和本轮自有后端 / Vite 均按生命周期收束。
 - 关联：`apps/ai-game-creator-shell/scripts/start-tauri-dev.mjs`、`apps/ai-game-creator-shell/scripts/start-dev-stack.mjs`、`apps/ai-game-creator-shell/tests/start-tauri-dev.test.ts`、`apps/ai-game-creator-shell/tests/start-dev-stack.test.ts`。

@@ -4030,3 +4031,36 @@
 - 处理：从当前 root source 的 seed lane 动态解析全部零依赖首波任务，只对这些 child 容忍 hydration `Pending`，后续 code prototype / preview 仍严格要求 Running/Completed。`streaming / ready` 仍要求当前 revision，`committed` 回复改为依据 finalization 的稳定身份查询，不随后续项目 revision 失效。
 - 验证：覆盖 `design-director / art-director / code-director` 三个 Pending 首波 child 均可投影 Completed、`code-prototype` Pending 仍被拒绝；非流式专业 Agent 在 finalization 前无 stream，提交后形成 committed stream，再推进项目 revision 后仍可查询且正文不变。
 - 关联：`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/autonomous_completion.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/response_stream.rs`。
+## 异步生成结果未知时不能换幂等键重提（2026-07-31）
+
+- 现象：生成提交发生客户端超时、连接中断或响应丢失后，调用方创建新的 `Idempotency-Key` 再提交一次；原任务其实已经入队，最终造成重复生成、重复扣费和重复画布 / 素材库写入。
+- 原因：把“客户端没有收到结果”误判为“服务端没有受理”，又没有持久保留逻辑请求的幂等键和服务端返回的 `operationId`。托管 MCP 若绕过 External REST router 直接调用 worker 或 SpacetimeDB，也会形成第二套去重与状态语义。
+- 处理：一次逻辑生成只分配一个稳定幂等键；传输重试必须使用完全相同的请求体和原键。收到 `operationId` 后只查询 `/api/external/v1/generations/{operationId}`，调用方轮询超时不改变服务端任务状态。结果未知且尚未拿到 operationId 时也只用原键重试提交。MCP 生成工具必须把 `idempotencyKey` 映射到同一 REST header，并复用同一 External router、owner 和任务账本。
+- 验证：覆盖“服务端已入队但提交响应丢失”后原键重试仍返回同一 operation、换 owner 不可见、查询最终只出现一份 completed result 和一次计费 / 写回；MCP 与 REST 对同一 owner、同一请求和同一键必须命中同一 operation。
+- 关联：`server-rs/crates/api-server/src/external_generation.rs`、`server-rs/crates/api-server/src/external_mcp.rs`、`docs/【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md`。
+
+## api-server 嵌入仓库外资源时必须同步容器构建上下文（2026-07-31）
+
+- 现象：本地 `cargo test` 可以编译 MCP 与 Skill 下载模块，但 api-server 镜像在 Rust 编译阶段报 `include_str!` 找不到 OpenAPI 或 Skill 文件。
+- 原因：本地工作树包含完整仓库，而容器 Rust builder 原先只复制 `server-rs/` 和 `public/`；crate 中向上引用的 `docs/openapi/`、`.codex/skills/` 不会自动进入镜像构建文件系统。
+- 处理：凡 api-server 通过 `include_str!` 使用仓库根目录资源，都要在 `deploy/container/api-server.Dockerfile` 的 builder 阶段显式复制对应权威目录；不要再复制一份内容到 crate 内形成平行事实源。
+- 验证：除本地 Cargo 测试外，检查 Dockerfile 构建上下文覆盖所有 `include_str!` 相对路径；新增或移动嵌入资源时同步更新容器 COPY 和接入文档。
+- 关联：`deploy/container/api-server.Dockerfile`、`server-rs/crates/api-server/src/external_mcp.rs`、`server-rs/crates/api-server/src/external_skill_api.rs`、`docs/openapi/genarrative-external-v1.openapi.json`。
+
+## 权威画布快照不能清掉本地待保存或在途布局（2026-08-03）
+
+- 现象：用户拖动、缩放、改层序、背景色或 viewport 后，生成完成回包立即覆盖画布；450ms 防抖尚未触发或布局保存仍在途时，编辑静默丢失，undo 也可能被生成保护项阻断。
+- 原因：服务端 revision 只能排序已提交事实，本地未落库布局没有 revision；直接清空 pending save 并整体应用权威快照等同于把“服务端更新更晚”误判成“服务端知道本地编辑”。
+- 处理：保留同项目最新本地 dirty snapshot，权威回包先更新资源和生成终态，再按稳定 item ID 合并本地布局字段并基于新 revision 保存。旧权威项在新快照缺失表示后端删除，不能从 pending 或在途旧输入复活；新权威项必须合入，本地删除的旧项不能从权威回包复活。
+- 生成器边界：`composerOpen` 与 `status / generatedLayerId / errorMessage` 一样属于后端生命周期事实；生成完成快照要求保持面板关闭时，不得被本地在途快照重新展开。提示词、参数和占位位置等本地布局编辑继续保留。集成测试夹具必须模拟后端真实完成快照：既有布局保持原位，完成结果层追加到末尾。同项目权威刷新还必须保留仍有效的单选、多选、生成占位选择或空选，只过滤已删除目标，不得无条件降成第一张图层的单选；首次载入 / 项目切换才设置默认选择。不要只跑 persistence Hook 单测，必须同时运行图片画布生成集成测试，覆盖完成后面板关闭、显式选择结果、背景清选和合并后 CAS 保存。
+- 验证：分别覆盖防抖 pending、真实在途成功与 409、后端新增、后端删除、本地删除、viewport、背景色和生成面板完成态；运行 `npm run test -- src/components/image-editor/useImageCanvasProjectPersistence.test.tsx src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx`。
+
+## Provider schema 能力不能从统一工具标记直接推断（2026-08-03）
+
+- 现象：把 OpenAI 风格 `strict` 原样透传给完整 Anthropic 工具目录，单个 schema 不支持的约束或全请求工具 / optional / union 上限会让整次 planning 返回 400。
+- 处理：能力不能从 `apiKind=anthropic` 推断；只对已验证 endpoint/model 显式开启，AGC 当前仅自动识别官方 HTTPS endpoint 与 Claude 4.5+ 版本化 model id，旧模型、未知别名和第三方兼容网关默认关闭。协议适配层用官方支持关键词白名单生成 Anthropic 专用传输 schema，对已知不支持约束仅从传输副本剔除，未知关键词、不可解析 / 递归 `$ref` 和复杂度超限均失败关闭为 non-strict，不删工具或修改调用方原 schema。真实 live 样例应包含 `$defs/$ref` 嵌套 schema，并使用官方 Anthropic endpoint，第三方兼容网关不能替代官方能力证据。
+
+## 可选 MCP server 的坏目录不能拖垮全部工具（2026-08-03）
+
+- 现象：可选 server 已成功连接，但返回超限 schema、重复 tool identity 或要求未支持 task-mode 时，整个 MCP catalog 和本轮 Agent planning 一起失败。
+- 处理：连接、tools/list、工具归一化与聚合容量都使用同一 required / optional 边界。optional 将该 server 投影为 `connected=false + error + tool_count=0`，required 保持失败关闭；被包入 `action.input` 的 `$ref` 只重定位当前 document 根的 `#` / `#/...` JSON Pointer，命名 anchor、外部 URI 与带 `$id` 的 schema resource 内 fragment 不得改写。
@@ -21,7 +21,7 @@ Genarrative / 陶泥儿是一个 AI 原生互动内容与小游戏平台，把 A
 - 小程序 WebView 外壳：`miniprogram/`。
 - 法律文本：`media/files/user_agreement.md`、`media/files/privacy_policy.md`、`media/files/disclaimer.md`。

-桌面端侧边栏和移动端底部 dock 的一级入口统一为 `创作 / 项目 / 我的`。`/creation` 是独立创作工具主页，`/project` 是画布项目入口，`/profile` 是“我的”稳定路由，继续承载账号、钱包、统计和通用设置等平台公共能力；刷新及浏览器前进 / 后退必须保持当前入口与选中态一致。
+桌面端侧边栏的一级入口为 `创作 / 项目 / 我的`；移动端底部 dock 只保留 `我的`。`/creation` 是桌面端独立创作工具主页，`/project` 是桌面端画布项目入口，`/profile` 是桌面端和移动端共用的“我的”稳定路由，继续承载账号、钱包、统计和通用设置等平台公共能力。移动端直达 `/creation`、`/project` 或 `/editor/canvas`，以及从首页触发项目 / 画布动作时，只显示桌面端创作提示，不挂载对应工具页面。

 ## 当前后端路线

@@ -48,6 +48,7 @@
 - 涉及中文文本时注意 UTF-8 编码和乱码排查。
 - 涉及后端时遵循 DDD 分层，不把业务真相下沉到前端或临时兼容层。
 - `packages/shared` 用于前后端 DTO、公开契约及跨页面复用的无业务真相 UI 组件和纯工具；不得把领域规则、后端副作用或正式状态放入其中。
+- 修改 `/api/external/v1` 的路由、HTTP 方法、请求 / 响应 DTO、请求头、状态码、鉴权或异步语义时，必须同批更新 `docs/openapi/genarrative-external-v1.openapi.json` 和对应契约测试；Rust 实现与 OpenAPI 未对齐时不得完成、提交或发布。
 - `maincloud` / `Maincloud` / `MAINCLOUD` 相关代码、脚本、测试、环境变量、命令和文档要求均视为历史残留，禁止新增、运行或引用；API smoke 统一使用 `npm run dev:api-server` 与 `/healthz`。
 - 涉及 SpacetimeDB 表结构、发布或迁移时，先看 `SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md` 和 `SPACETIMEDB_TABLE_CATALOG.md`。
 - 涉及生产发布、服务器配置、Jenkins Job 重建或回滚时，先看 `PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md`。