@@ -1,5 +1,53 @@
# 决策记录
## 2026-09-22 Direct 埋点与业务持久化锁隔离
- Direct 采集身份和最新成果编号改由独立纯内存状态保存，初始化时从最终执行账本冻结项目与原 run 身份；成果采集、预览采集上下文和终态成果读取不再争用业务落盘锁。
- 内存锁释放后才投递事件，不等待文件 I/O、后台队列或网络，不新增用户报错。缺少 run 元数据不套用当前用户身份，恢复不补造历史成果；退出仍尽力封存，不增加退出等待。
- 修正后台埋点查询 DTO 的分页注释：按 `(event_time, event_id)` 倒序，入库时间仅限制快照；接口和查询行为不变。
## 2026-09-22 新项目埋点资格支持有限恢复
- 真实创建成功先登记有界进程内待办，不依赖埋点服务或身份快照；后台服务就绪及后续真实受理可重试初始化资格。资格文件格式、每项目最多一次首次提交和上传合同不变。
- 业务线程仅更新内存和非阻塞投递；资格文件读写和独立锁操作仍在后台，不向用户报错或要求介入。队列满、暂时 I/O 失败和锁竞争保留待办；已有标记、备份或项目身份不符不重新授予资格。
- 内存最多 1024 项、路径与 ID 合计 1 MiB；超限或持久化前退出仍允许漏记，不补旧项目历史，不承诺零丢失。细节与验证见客户端埋点主规范。
## 2026-09-22 清理无调用方的 GUI 文件写入命令
- 确认 `write_local_project_file` 无现役前端或业务调用方后，删除命令、Tauri 注册及命令检查豁免；移除对应测试片段，保留 checkpoint、UI 保存和记忆写入的既有测试。
- Agent 使用的底层 `write_local_project_file_at` 保留。GUI 人工文件写入不再列为采集入口；不扩充其他文件操作埋点，不修改已有事件数据合同。
## 2026-09-22 客户端埋点后台按发生时间排序
- 按技术负责人要求，列表改为 `(event_time, event_id)` 倒序，历史补传按发生时间归位。入库时间仍用于固定分页快照，翻页期间新入库的事件在刷新后显示。
- 分页游标改存发生时间；旧游标刷新后重新取得，不迁移持久表、不新增索引、不改变采集与上传行为。
## 2026-09-22 埋点分支同步发布入口与工作台更新
- 合并 master `079466b29` ，同时保留项目离开埋点与工作台运行通知、后台埋点查询与游戏发布审核入口；不扩大采集范围。
- 本次冲突位于工作台相邻回调、后台 API 测试导入及本文件新增记录，均保留双方现役内容；Direct 聊天的认证重试埋点与 master 回合状态调整继续共存。
## 2026-09-22 埋点分支合并 DirectProject 聊天重构
- 保留 master 的独立 DirectProject 聊天控制器及 canonical `userItem` 合同；旧 Supervisor、独立 prompt/attachments IPC 参数和已退役删除命令不恢复。
- 原有 Direct run 埋点从 App 聊天链迁至 `useDirectProjectChatController.runTurn` ，认证重试仍逐次生成 attempt ID，并仅确认最后一次；账号代次变化时丢弃确认。项目进入/离开及用户预览的原有接线继续保留，不扩大采集范围。
- 过期测试按现役聊天入口调整，新增实际 UI→controller 认证重试用例验证最终尝试确认。上传、数据库和后台合同不变。
- 合并验证：Rust analytics 56 项通过（真实服务桥接用例维持 ignored），App 界面 203 项通过 / 13 项既有跳过；预览激活、版本切换、工作台清单及客户端埋点辅助测试通过，客户端 TypeScript、原生契约、编码、文档索引和 diff 检查通过。本次未重跑上传真实服务 smoke 或完整 GUI/Provider 创作。
## 2026-09-21 客户端埋点方案进入团队共享文档
- 本期验收完成：原始需求与已确认口径的 12 类事件入口已核对，同一 writer/session/project/goal 的宿主组件链路通过真实文件、HTTP、checkpoint 与 JSONL 关联验证；最终 51 项 Rust、46 项前端测试和类型/格式/文档检查通过。仅测试辅助模拟创建投递、run 结果和构建产物，不宣称完整 GUI/Provider 端到端验证；未提交或发布。禁止把全部资源操作逐项接线重新当作本期必做范围。
- 最新口径：共 12 类启用事件；策划审批通过后实际进入下一阶段并成功持久化，复用 project_revision_created，
- 两类 Agent run 元数据随真实受理保存，后台维护项目累计观测重试与双 Agent 当前终态槽位；重放不新建，恢复保留原身份且耗时未知，取消/不确定不伪造失败。Direct 自动认证刷新只确认最后一次原生尝试的有界内存候选，账号代次变化丢弃；缺失不回退旧失败，不为观测增加业务写盘等待。运行结果已通过独立验收，真实付费 Provider/完整 GUI run 尚未 smoke，现有 Direct 合同中断恢复行为未改变。
- Direct 宿主文件写入/正式补丁仅在已知成果内容变化且原事务 revision 成功提交后记成果，原 run 用户归属不变，末尾 projection 不重复记。当前 session 内存关联最新可信成果到 run；缺证据为 null，不据全局 fingerprint 推断作者。真实 writer、bundled patch 执行器和定向测试已通过。
- GUI 人工文件写入命令已于 2026-09-22 清理，不再作为采集入口；完整项目 checkpoint 按真实 checkpoint_id 记保存。UI State 仅 Saved 记成果；手动 Saved/Unchanged 可记保存，自动保存仅 Saved，保存并生成需全操作成功。起点冻结身份，埋点失败不影响业务。63 项 Rust、41 项前端测试及独立验收通过；无完整 GUI 跨层保存 smoke。旧 Runtime 开发/CLI 文件及 UI workflow 不因存在代码就纳入正式 GUI 必需采集。
- 正式 Web preview_ready 由 GUI 用户持续预览和 Direct 临时浏览器预览接入，冻结原身份、版本与实例；异步2秒loopback GET禁代理/重定向，原入口及响应非空、版本/实例仍匹配才记录。实例停止/替换、验证结束或取消后丢弃迟到结果；可访问不等于JS/游戏验证成功。合并后78项Rust、104项前端测试及独立验收通过，未调用真实Provider或跑完整Chrome双端验证。资源操作全面接线计划已撤销；现有采集只表示已观测变化，不代表全部资源操作或项目全部修订。
- 首次提交按本地观测口径每个新项目最多一条：真实受理候选在后台持久消费 `.agent/analytics-goal.json` 资格后投递。资格跨批次清理保留，旧项目不初始化；此前候选丢失时允许后续真实受理消费，使用后者自己的用户与时间，不宣称绝对首次。消费后事件丢失可零条，重放与恢复不补历史；不得为埋点扫描双 Agent 完整历史或阻塞业务写盘。
- 当前合同唯一维护入口为[客户端本地埋点与主站入库契约 ](../../technical/【技术方案】客户端本地埋点与主站入库契约-2026-09-21.md )，原始需求作为仓库内历史来源保存；后续里程碑规范与实施计划放在 `docs/project-memory/plans/` 。
- 本地采集阶段已验收明文 JSONL 持久化；当前仍不做加密。一个项目对应一个目标，事件按业务节点采集，5 分钟封存，7 天或 20 MiB 清理；上传失败也受保留上限约束。
- 当前上传实现已完成隔离环境验收，证据见同一主规范第 13 节：每 15 分钟上传匹配当前账号与平台的封存批次，新增一张客户端事件私有表、批次原子入库与幂等确认、成功清理及独立后台明细栏目；失败静默留待下周期重试。真实客户端文件、HTTP、数据库与后台查询已关联同一事件验证，浏览器列表/筛选/详情通过；未部署生产。保持原 12 类事件和原采集边界。上线须配置 `GENARRATIVE_AGC_ANALYTICS_ORIGIN` ，按数据库、API/后台、客户端顺序发布。
- 已按技术负责人授权开始实施：合同与本地队列、会话窗口与项目接入、策划阶段成果、首次提交及两类 Agent run 已实现并经独立审查；定向测试、生产编译和前序 GUI 启停证据统一见主规范第 12 节。不得宣称完整产品采集已上线。
## 2026-09-22 引用输入区改为宿主注入引用 provider，选择器面板与输入区分离
- 背景：`ResourceReferenceInput` （ `apps/ai-game-creator-shell/src/features/project-workspace/ResourceReferenceInput.tsx` ）同时承担「拿数据」与「编辑数据」：素材以未过滤 manifest 传入后由组件自己派生候选、显示名与「当前版本素材」scope，Skill 候选由组件自己 invoke `list_agc_skill_catalog` 与 `list_client_extensions` （只在用户敲出 `$` 时触发），素材选择面板与缩略图预览 invoke 也住在组件内部。后果是 5 个宿主（DirectProject 聊天、策划输入盒、画布生成面板、资源卡快速编辑、测试夹具）无差别获得 `$` Skill 候选，而只有 DirectProject 回合会把 `agc_skill_reference` 解析成真 Skill（ `direct_codex_user_item_to_codex_turn_input` ， `apps/ai-game-creator-shell/src-tauri/src/agent/direct_codex_user_item/wire.rs` ），其余宿主只把它退化成字面文本，形成误导入口。
@@ -763,11 +811,11 @@ Godot 编辑器操控复用既有 AGC 插件宿主、EditorAdapter、Runner 和
## 2026-09-03 server-rs workspace 保留独立 platform-agent 排除边界
- 背景：主站 #251 合并清理旧玩法表后， `server-rs/Cargo.toml` 的旧 crate 排除清单被收窄； `platform-agent` 仍 位于 `server-rs/crates/` 下，但实际由 AGC 独立 Cargo workspace 通过路径依赖使用。若不显式排除，主 workspace 的 `cargo fmt --all` 会把它识别为“位于 workspace 内但不是 member”的非法包并直接失败。
- 背景：`platform-agent` 位于 `server-rs/crates/` 下，但实际由 AGC 独立 Cargo workspace 通过路径依赖使用。若不显式排除，主 workspace 的 `cargo fmt --all` 会把它识别为“位于 workspace 内但不是 member”的非法包并直接失败。
- 决策：继续将 `crates/platform-agent` 放在 `server-rs` workspace 的 `exclude` 中。它不加入主 workspace，也不在其 manifest 中新增平行 `[workspace]` ；
- 影响范围：`server-rs/Cargo.toml` 与仓库 Rust 格式检查；不改变 `platform-agent` 源码、AGC 依赖关系或主站运行时。
- 验证方式：`npm run check:rustfmt` 通过；`cargo fmt --all --manifest-path server-rs/Cargo.toml -- --check` 不再报告 `platform-agent` workspace 错误。
- 关联材料：Repository checks #5755 、主站合并提交 `025f62729` 、 `server-rs/Cargo.toml` 、AGC `apps/ai-game-creator-shell/src-tauri/Cargo.toml` 。
- 关联材料：Repository checks #5755 、`server-rs/Cargo.toml` 、AGC `apps/ai-game-creator-shell/src-tauri/Cargo.toml` 。
## 2026-09-03 Native shell 检查清单只维护现役 HostBridge 文件
@@ -797,16 +845,6 @@ Godot 编辑器操控复用既有 AGC 插件宿主、EditorAdapter、Runner 和
- 验证方式：运行评论弹层恢复竞态回归、完整 `appSurface.test.ts` ，并执行类型、编码和 diff 检查。
- 关联文档：`docs/technical/【技术方案】立项策划Agent（ ） 、`apps/ai-game-creator-shell/src/features/project-workspace/GddApprovalCard.tsx` 。
## 2026-09-02 旧玩法表采用两阶段退役清理
- 背景：旧创作模板的业务代码已退出现役编译链，但 SpacetimeDB 中的历史表仍需先完成数据清理；直接删除表定义会扩大 schema 迁移和客户端兼容风险。
- 决策：阶段一只在 `spacetime-module/src/migration.rs` 增加受 `database_migration_operator` 保护的 `clear_retired_database_tables` procedure。procedure 使用固定的 63 张旧玩法表清单，不接受动态表名；`dry_run=true` 只返回逐表行数统计，`dry_run=false` 在同一事务内逐表清空，任一失败整体回滚。阶段一不删除表定义、不修改 `legacy_schema/**` 、migration 导入导出白名单或生成 bindings。
- 阶段边界：清理清单包含旧 gameplay、`custom_world` 、Puzzle / Puzzle Clear、Bark Battle、Match3D、Jump Hop、Wooden Fish、Square Hole、Visual Novel 和 Big Fish 表；`runtime_setting` 、`runtime_snapshot` 、`user_browse_history` 、`creation_entry_config` 等现役表明确排除。阶段二只有在备份、客户端兼容性和运行态确认完成后，才评估从 module 定义与 migration 白名单移除空表，并按 schema / bindings 流程发布；固定清单旁保留 TODO。
- 影响范围：SpacetimeDB migration procedure、`spacetime-client` 生成 bindings、后端数据契约和本决策记录；禁止新增 SQL `DROP TABLE` 、`--delete-data=always` 或直接写系统表的实现。
- 验证方式：固定清单测试确认数量为 63 且不含现役表；本地数据库以已授权 operator 执行 dry-run，确认 63 张表均返回 0 行且未写入；apply 的单事务回滚由 procedure 实现，实际 apply 仅在另行授权的维护窗口执行。另运行 bindings 生成、SpacetimeDB schema / runtime 检查、编码和 diff 门禁。
- 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md` 、`server-rs/crates/spacetime-module/src/migration.rs` 。
- 补充落地：阶段一同时删除此前仅因退役而保留的旧玩法业务实现、未挂载 API handler/router/worker、旧客户端 facade/mapper、旧领域 crate、`retired/legacy-creation-templates/**` 归档及 `packages/shared/src/contracts/**` 中已无仓库内消费者的旧玩法公共契约；`legacy_schema/**` 、生成表 bindings、现役 shared contracts 和持久化 schema 不在本次删除范围。
## 2026-08-31 DirectProject 客户端扩展按独立 Skill/MCP 导入
- 背景：DirectProject 需要使用用户在 AGC 客户端导入的市面原生 Skill、MCP 和 Plugin 内容，但第三方内容不应直接安装到运行时 Codex，也不应要求用户转换为 AGC 自定义格式。
@@ -2932,7 +2970,6 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
- 2026-06-20 桌面本地通知契约镜像：Tauri `notification.showLocal` 的 title / body 归一化、长度上限和成功结果 action 必须镜像共享 HostBridge 契约；Rust 侧常量使用 `HOST_BRIDGE_LOCAL_NOTIFICATION_TITLE_MAX_LENGTH` 、`HOST_BRIDGE_LOCAL_NOTIFICATION_BODY_MAX_LENGTH` 和 `HOST_BRIDGE_LOCAL_NOTIFICATION_DELIVERED_TO_SYSTEM_ACTION` 命名，桌面单端配置检查会与 `packages/shared/src/contracts/hostBridge.ts` 比对数值并反查成功结果由该 action 常量组装，避免通知 payload 边界变成桌面壳本地规则。
- 2026-06-19 桌面壳外链打开 helper 共用：Tauri WebView 外域拦截和 HostBridge `app.openExternalUrl` 都必须复用 `open_normalized_desktop_external_url` 执行系统外链打开动作；HostBridge 分支仍先用 `normalize_external_url` 保留 payload 错误语义并把 opener 错误回传给 H5， `dispatch.rs` 直接调用 `app.opener().open_url` 绕过该 helper，避免两条离壳路径漂移。
> 2026-07-18 覆盖说明：本段后续关于微信 `navigation.openNativePage` 、生成结果订阅页、`[subscribe-message]` 日志和订阅页路由门禁的 2026-06 决策均已由旧创作模板退役决策废止，只作为历史记录。Expo / Tauri 的同源 H5 受控导航及微信登录、支付、分享能力继续有效。
- 2026-06-20 H5 原生导航预校验：`navigateHostNativePage()` 在 `native_app` 下发送 `navigation.openNativePage` 前必须先拒绝空值、控制字符、协议相对 URL、外域绝对 URL 和非 `http:` / `https:` 协议目标；同源绝对 URL、`/path` 和保留给桌面壳兼容的相对 route 继续交给 Expo / Tauri 壳二次归一并补写宿主上下文。微信小程序分支仍按小程序页面 URL 语义走 `wx.miniProgram.navigateTo` ，不套原生 App 同源 H5 预校验。根级 `npm run check:native-shells` 会反查 H5 facade 仍使用 `normalizeNativeAppPageUrl(...)` 且发送归一后的 URL，避免明显不安全目标触达原生壳。
- 2026-06-20 微信受控原生页能力声明：微信小程序壳真实 capability profile 声明 `navigation.openNativePage` ，用于承接已经登记并测试的小程序原生页 flow；当前订阅生成结果通知页通过 H5 `requestGenerationResultSubscribePermission()` 调用 `navigateHostNativePage()` 打开 `/pages/subscribe-message/index` ，小程序页再调用真实 `wx.requestSubscribeMessage` 并按既有结果协议回灌。根级 `npm run check:native-shells` 必须把该能力反查到共享 profile、微信 `WECHAT_HOST_CAPABILITIES` 镜像、订阅页协议常量、H5 入口、小程序 host-bridge / shell / page 文件和相关测试；该能力不代表开放任意小程序页面跳转。
@@ -3062,7 +3099,6 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
## 2026-06-17 H5 宿主壳能力统一走 HostBridge
> 2026-07-18 覆盖说明：以下订阅授权、订阅页和旧玩法导航部分已退役；登录、支付、分享、九宫切图与通用 HostBridge 分层仍有效。
- 背景：主站同时运行在普通浏览器、微信小程序 `web-view` 和未来可能出现的原生 App WebView 中；登录、支付、分享、订阅授权和运行态分享目标同步曾散落在业务组件与服务文件里，后续新增宿主壳会导致同一业务重复分叉。
- 决策：前端宿主运行态识别、微信小程序 JS SDK 加载、原生页跳转、支付跳转、登录跳转、九宫切图和 `postMessage` 统一收口到 `src/services/host-bridge/hostBridge.ts` ，业务层优先调用 `getHostRuntime` 、`requestHostLogin` 、`requestHostPayment` 、`navigateHostNativePage` 、`setHostShareTarget` 和 `openHostShareGrid` 。`authService` 、分享服务、订阅授权和个人中心充值可保留兼容导出或业务编排，但不再自行加载微信 JS SDK 或直接判断 `wx.miniProgram` 。固定内置玩法不走代码包下载流程；AI 生成 H5 沙箱后续单独定义受限 `GameBridge` ，不得直接暴露完整 `HostBridge` 。
@@ -3120,14 +3156,6 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
- 验证方式：`cargo check -p server-manager-panel --manifest-path server-rs/Cargo.toml` 、`cargo test -p server-manager-panel --manifest-path server-rs/Cargo.toml` 、`npm run check:encoding` 。
- 关联文档：`docs/technical/【开发运维】本地SSH服务器管理面板技术方案-2026-06-11.md` 。
## 2026-06-10 公开作品互动能力进入后台全局配置
- 背景：作品详情页的点赞和改造能力原本由前端和各玩法 handler 的硬编码能力矩阵决定，后台无法临时关闭某类公开作品的互动入口，直接关闭创作入口又会误伤已有作品读取和游玩。
- 决策：公开作品点赞 / 改造能力作为 `creation_entry_config.public_work_interactions_json` 的全局矩阵保存，不进入单个 `creation_entry_type_config` 。`GET /api/creation-entry/config` 下发 `publicWorkInteractions` ；后台通过 `/admin/api/creation-entry/config/interactions` 按 `sourceType` 保存点赞、改造开关和关闭提示；api-server 只对已经接入后端动作的 RPG / custom-world、大鱼吃小鱼和拼图 like / remix 路由做同源熔断，公开列表、详情读取、已发布作品启动和运行态请求不受影响。
- 影响范围：`CreationEntryConfigResponse` 、`AdminCreationEntryConfigResponse` 、`module-runtime` 默认矩阵、`spacetime-module` 表字段和 procedure、`spacetime-client` 绑定、后台入口开关页、平台作品详情点赞 / 改造意图解析。
- 验证方式：`npm run spacetime:generate` 、`npm run check:spacetime-schema` 、`cargo test -p module-runtime public_work_interaction_config_defaults_and_overrides --manifest-path server-rs/Cargo.toml` 、`cargo test -p api-server public_work_interactions --manifest-path server-rs/Cargo.toml` 、后台和前台作品详情互动相关前端测试。
- 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md` 、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md` 。
## 2026-06-19 Jenkins Git 源统一为内网 SSH
- 背景：本地和 Jenkins 流水线改用 Gitea 的 `/git` 前缀内网入口后，继续在 Jenkinsfile 内保留 `http://127.0.0.1:3000/...` 主地址和 `https://git.genarrative.world/...` fallback 会让构建节点误走 localhost 或公网链路。
@@ -3601,14 +3629,6 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
- 验证方式：`cargo test -p module-auth logout_current_session --manifest-path server-rs/Cargo.toml` 、`cargo test -p module-auth refresh_from_snapshot_json_merges_session_created_by_another_process --manifest-path server-rs/Cargo.toml` 、`cargo test -p api-server logout_current_device_keeps_other_device_session_alive --manifest-path server-rs/Cargo.toml` 。
- 关联文档：`docs/【项目基线】当前产品与工程约束-2026-05-15.md` 、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md` 。
## 2026-06-07 跳一跳排行榜展示名禁止泄露内部身份键
- 背景：跳一跳排行榜曾在结果页和运行态失败弹窗里直接展示 `playerId` / `user_id` ，用户可见内容暴露了内部身份键。
- 决策：`jump_hop_leaderboard_entry.player_id` 只作为 SpacetimeDB read model 的去重和 `viewerBest` 匹配字段，HTTP 契约新增并强制使用 `displayName` 作为排行榜展示字段。api-server 出口按账号 `displayName` 补齐展示名；匿名 runtime guest 固定展示“游客玩家”；账号失效或不可解析时展示“失效玩家”；前端排行榜 UI 禁止兜底展示 `playerId` / `user_id` 。
- 影响范围：`packages/shared/src/contracts/jumpHop.ts` 、`server-rs/crates/shared-contracts/src/jump_hop.rs` 、`server-rs/crates/api-server/src/jump_hop.rs` 、跳一跳结果页和运行态排行榜组件、跳一跳 PRD 与后端契约文档。
- 验证方式：`npm run test -- src/components/jump-hop-runtime/JumpHopRuntimeShell.test.tsx -t "排行榜"` 、`npm run test -- src/components/jump-hop-result/JumpHopResultView.test.tsx -t "排行榜"` 、`cargo test -p api-server jump_hop_leaderboard_display_name_never_falls_back_to_player_id --manifest-path server-rs/Cargo.toml` 。
- 关联文档：`docs/prd/【玩法创作】跳一跳俯视角玩法模板PRD-2026-05-19.md` 、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md` 。
## 2026-06-07 generated 图片读取坚持 OSS 源站与签名缓存链路
- 背景：生成图片如果以完整 OSS 私有 bucket URL 进入前端，浏览器会裸连 OSS 并遇到 403 或绕过现有 `/api/assets/read-url` 签名缓存；同时旧对象缺少 `Cache-Control` 时只能走 `ETag` / `Last-Modified` 协商缓存，容易被误解为需要 api-server 本地磁盘缓存。
@@ -3635,16 +3655,6 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
- 验证方式：`cargo test -p module-puzzle-clear --manifest-path server-rs/Cargo.toml` 、`cargo test -p api-server puzzle_clear --manifest-path server-rs/Cargo.toml -- --nocapture` 、`npm run test -- src/services/puzzle-clear/puzzleClearLocalRuntime.test.ts` 、`npm run test -- src/components/puzzle-clear-result/PuzzleClearResultView.test.tsx src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx` 。
- 关联文档：`docs/prd/【玩法创作】拼消消玩法模板PRD-2026-05-30.md` 、`docs/technical/【玩法创作】拼消消玩法模板技术方案-2026-05-30.md` 、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md` 、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md` 。
## 2026-05-30 拼消消按独立玩法公开闭环接入
- 背景：拼消消以拼图交换手感为基础，但核心规则从“拼完整单图过关”变为“拼成多个复合图案组后逐个消除”，同时需要顶部补牌、防死局、半锁定局部拼接组和正式统计，不能继续复用拼图运行态规则本体。
- 决策：`puzzle-clear` 作为独立玩法域接入，公开作品码前缀固定为 `PC-` ；创作链路采用表单 / 图片输入工作台 -> 独立生成页 -> 结果页 -> 试玩 -> 发布 -> 统一作品详情 -> 正式 runtime。领域规则落在 `module-puzzle-clear` ， `puzzle_clear_*` 表 / procedure / view，并接入统一 `public_work_gallery_entry` / `public_work_detail_entry` ；前端只表现后端 snapshot/action 结果，不把胜负、补牌或消除裁决做成前端事实源。
- 补充约束：草稿编译和发布都必须拒绝缺失或 `placeholder` atlas / card assets，不允许后端 facade 或 SpacetimeDB 合成临时素材；当前单关正式 runtime 终态事件使用 `run-finished` 、`level-failed` ，并写入包含 `status` 、`level` 、`clears` 、`clearDelta` 、`elapsedMs` 的结果 JSON。
- 补充约束：拼消消结果页草稿试玩使用前端本地 `runtimeMode=draft` snapshot，不调用 `/api/runtime/puzzle-clear/runs` ，不写正式 run 统计；公开详情和推荐流正式运行继续走后端 `/api/runtime/puzzle-clear/*` ，客户端需要区分创作详情 `/api/creation/puzzle-clear/works/{profileId}` 与公开运行态详情 `/api/runtime/puzzle-clear/works/{profileId}` 。
- 影响范围：`CONTEXT.md` 、拼消消 PRD / 技术方案、平台玩法链路文档、`shared-contracts` / `packages/shared` 、`api-server` 、`spacetime-module` 、`spacetime-client` 、作品架 / 广场 / 统一作品详情 / runtime 前端分流。
- 验证方式：PRD 和技术方案必须覆盖资产槽位、素材工作表风险、切片验证、恢复语义、API 命名空间和验证命令；实现侧至少运行 `npm run spacetime:generate` 、`npm run check:spacetime-schema` 、`npm run check:spacetime-runtime-access` 、`npm run check:server-rs-ddd` 、`npm run typecheck` 、`npm run check:encoding` 、相关前端测试和 `cargo test -p module-puzzle-clear --manifest-path server-rs/Cargo.toml` 。
- 关联文档：`docs/prd/【玩法创作】拼消消玩法模板PRD-2026-05-30.md` 、`docs/technical/【玩法创作】拼消消玩法模板技术方案-2026-05-30.md` 、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md` 、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md` 。
## 2026-06-05 Server-Provision 全程在目标部署 agent 执行且不安装构建链
- 背景：`Genarrative-Server-Provision` 的 `DEPLOY_TARGET=development` 语义是部署到 dev 服务器，不是构建机 dry-run。旧流水线把 development 映射到 `linux && genarrative-build` ，还先在 build 节点准备 `provision-tools/` 再 stash 给后续阶段，导致真实 dev 初始化可能跑到 Jenkins controller / build 节点；脚本还安装 clang / lld / pkg-config / OpenSSL headers / sccache 等构建链依赖，超出了服务器初始化职责。
@@ -3781,20 +3791,6 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
- 验证方式：`npm run test -- src/components/platform-entry/platformCreationWorkDeleteFlow.test.ts` 、`npm run test -- src/components/platform-entry/platformDraftGenerationShelfModel.test.ts` 、针对新 Module 与平台壳执行 ESLint、`npm run typecheck` 、`npm run check:encoding` 。
- 关联文档：`docs/technical/【前端架构】CreationWorkDeleteFlow收口计划-2026-06-04.md` 。
## 2026-06-03 平台入口公开作品详情 Strategy 收口
- 背景：平台壳层直接判断公开作品详情入口的玩法类型、是否需要补读完整详情，以及自有作品按钮显示“编辑”还是“改造”，导致统一作品详情的纯决策散落在巨型 Implementation 内。
- 决策：新增 `src/components/platform-entry/platformPublicWorkDetailFlow.ts` ，以 `getPlatformPublicWorkDetailKind` 、`resolvePlatformPublicWorkDetailOpenStrategy` 、`resolvePlatformPublicWorkActionMode` 、`resolvePlatformPublicWorkDetailOpenDecision` 和 `resolveActivePlatformPublicWorkAuthorEntry` 收口公开作品详情 Strategy。`PlatformEntryFlowShellImpl.tsx` 只按 Strategy 调用现有详情读取 / 直接展示 Adapter，并保留作者请求竞态控制；启动、点赞、remix 和编辑副作用不搬入 Module。
- 追加决策：公开详情 entry 映射与公开详情反推玩法 work 摘要也归入 `platformPublicWorkDetailFlow.ts` ，包括 RPG、拼图、大鱼吃小鱼、方洞挑战、视觉小说、跳一跳、敲木鱼和汪汪声浪的通用映射。抓大鹅 `mapMatch3DWorkToPublicWorkDetail` 归入 `platformMatch3DRuntimeProfile.ts` ，继续委托 `normalizeMatch3DWorkForRuntimeUi` 做素材归一和背景资产提升，避免把 Match3D 运行态规则复制到公开详情 Flow Module。
- 追加决策：拼图公开详情封面解锁数由 `resolveVisiblePuzzleDetailCoverCount(entry, run)` 收口；非拼图、无当前 run 或 run 不匹配当前公开详情时只展示首图，匹配当前公开详情时按 `clearedLevelCount + 1` 解锁且至少为 1。`PlatformWorkDetailView` 只接收 `visibleCoverCount` 展示，不读取 run。
- 追加决策：公开详情点赞能力矩阵由 `resolvePlatformPublicWorkLikeIntent(entry)` 收口；Module 只返回大鱼吃小鱼、拼图、旧 RPG gallery fallback 或不可用文案，壳层仍执行鉴权、API 调用、缓存同步、错误展示和 busy 状态。
- 追加决策：公开详情改造能力矩阵由 `resolvePlatformPublicWorkRemixIntent(entry)` 收口；Module 只返回大鱼吃小鱼、拼图、旧 RPG gallery fallback 或不可用文案，壳层仍执行鉴权、remix API、session / 缓存写入、stage 切换、错误展示和 busy 状态。
- 追加决策：公开详情启动分流由 `resolvePlatformPublicWorkStartIntent(entry, deps)` 收口；Module 只返回大鱼吃小鱼、拼图、跳一跳、敲木鱼、抓大鹅、方洞挑战、视觉小说、汪汪声浪、宝贝识物或旧 RPG gallery 记录游玩的 intent。壳层仍执行登录保护、运行态启动、RPG 游玩记录、详情更新、busy 状态和错误展示；抓大鹅 public detail -> work mapper 作为 Adapter 注入，继续由 Match3D Runtime Profile Module 维护素材归一与背景资产提升。
- 追加决策：自有公开作品编辑分流由 `resolvePlatformPublicWorkEditIntent(entry, deps)` 收口；Module 只返回可编辑草稿目标、需解析宝贝识物本地草稿 intent、旧 RPG gallery 编辑 intent 或原阻断文案。壳层仍执行登录保护、草稿恢复、宝贝识物异步草稿解析、RPG 编辑导航和错误展示；抓大鹅 public detail -> work mapper 仍作为 Adapter 注入，不复制 Match3D 素材归一规则。
- 影响范围：统一作品详情入口、公开详情打开策略、自有公开作品编辑 / 改造动作模式，以及后续新增玩法公开详情接入。
- 验证方式：`npm run test -- src/components/platform-entry/platformPublicWorkDetailFlow.test.ts` 、`npm run test -- src/components/platform-entry/platformMatch3DRuntimeProfile.test.ts` 、公开详情壳层交互回归、`npm run typecheck` 、`npm run check:encoding` 。
- 关联文档：`docs/technical/【前端架构】PlatformPublicWorkDetailFlow收口计划-2026-06-03.md` 。
## 2026-06-03 平台入口弹窗状态规则收口
- 背景：`PlatformEntryFlowShellImpl.tsx` 曾同时持有平台级错误 / 完成弹窗的文案归一、来源格式、候选择一、dismiss key、后台生成 still-running 识别和任务完成文案，导致壳层 Interface 偏浅，测试面不稳定。
@@ -3811,14 +3807,6 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
- 验证方式：`npm run test -- src/services/sseStream.test.ts src/services/llmClient.test.ts src/services/creation-agent/creationAgentSse.test.ts src/services/creative-agent/creativeAgentSse.test.ts src/services/visual-novel-runtime/visualNovelRuntimeSse.test.ts src/services/rpg-entry/rpgProfileClient.test.ts src/services/ai.test.ts` 、`npm run typecheck` 、`npm run check:encoding` 、相关文件 `npx eslint ... --max-warnings 0` 通过。
- 关联文档：`docs/technical/【前端架构】SSE客户端传输层收口约定-2026-06-03.md` 。
## 2026-06-03 平台入口公开作品流身份规则收口
- 背景：平台入口公开作品推荐流需要同时处理 RPG、拼图、抓大鹅、跳一跳、敲木鱼、视觉小说、Bark Battle、宝贝识物等卡片，公开作品身份、跨玩法去重、排序和推荐运行态 kind 判定曾放在 `PlatformEntryFlowShellImpl.tsx` 巨型实现里。
- 决策：公开作品身份、排序规则、公开作品流聚合矩阵、推荐 runtime 启动意图和 ready 判定统一收口到 `src/components/platform-entry/platformPublicGalleryFlow.ts` ；入口壳层只调用该 Module 的 `getPlatformPublicGalleryEntryKey` 、`getPlatformRecommendRuntimeKind` 、`buildPlatformPublicGalleryFeeds` 、`resolvePlatformRecommendRuntimeStartIntent` 、`isPlatformRecommendRuntimeReadyForEntry` 、`isSamePlatformPublicGalleryEntry` 和 `mergePlatformPublicGalleryEntries` 。`edutainment` key 必须带 `templateId` ， `rpg` 。公开作品流聚合负责 featured / latest、玩法可见性 gate、汪汪声浪 works fallback 和首屏 `slice(0, 6)` ；推荐 runtime 启动 intent 只返回启动目标、`embedded` / `returnStage` 参数、阻断文案和错误落点；ready 判定只接布尔值与拼图 profile id，避免把各玩法 run snapshot 类型拖入 Module。壳层仍执行 request key、运行态 API、错误 setter 与 UI 状态。
- 影响范围：平台入口推荐流、最新公开作品流、公开作品详情、推荐 runtime 启动、跨玩法公开作品合并，以及后续新增玩法的入口接入。
- 验证方式：`npm run test -- src/components/platform-entry/platformPublicGalleryFlow.test.ts` 、`npm run typecheck` 、`npm run check:encoding` 、相关文件 ESLint 通过。
- 关联文档：`docs/technical/【前端架构】平台入口PublicGalleryFlowModule收口计划-2026-06-03.md` 。
## 2026-06-03 Work Shelf 打开动作交由 item Adapter
- 背景：`creationWorkShelf.ts` 已经为每个 `CreationWorkShelfItem` 生成 `actions.open` ，但 `CustomWorldCreationHub.tsx` 点击卡片后仍按 `item.source.kind` 重复分发 RPG、拼图、抓大鹅、方洞、跳一跳、敲木鱼、视觉小说、Bark Battle 和宝贝识物的打开逻辑。
@@ -3838,14 +3826,6 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
- 验证方式：`npm run test -- src/services/runtimeRequest.test.ts src/services/recommendedRuntimeGuestLaunch.test.ts src/services/match3d-runtime/match3dRuntimeAdapter.test.ts` 、`npm run typecheck` 、`npm run check:encoding` 、相关文件 ESLint 通过。
- 关联文档：`docs/technical/【前端架构】RuntimeClientFamily收口计划-2026-06-03.md` 。
## 2026-06-03 Public Gallery ViewModel 收口
- 背景：`RpgEntryHomeView.tsx` 巨型页面内混合了公开作品分类、跨来源去重、搜索归一化、作品号匹配、时间戳解析和排序规则，新增玩法时页面与 ViewModel 规则容易纠缠。
- 决策：新增 `src/components/rpg-entry/rpgEntryPublicGalleryViewModel.ts` ，把 `buildPublicGalleryCardKey` 、`buildPublicCategoryGroups` 、`getPlatformPublicEntries` 、`getAllPlatformPublicEntries` 、`getPlatformSearchableWorkIds` 、`filterPlatformWorkSearchResults` 、`isExactPublicWorkCodeSearch` 、`filterTodayPublishedEntries` 、公开卡片指标 getter、`buildPlatformRankingEntries` 、`getPlatformRankingMetricValue` 、`getPlatformCategoryKindFilter` 、`matchesPlatformCategoryKindFilter` 、`sortPlatformCategoryEntries` 、`getPlatformCategoryPrimaryMetric` 、`parsePlatformEntryTimestamp` 和 `getPlatformWorldTimestamp` 收口为公开作品 ViewModel Interface。公开作品 key 复用平台入口身份规则，补齐 jump-hop / wooden-fish 等玩法区分。
- 影响范围：RPG 首页公开作品发现、分类、搜索、排行数据准备，以及后续新增玩法公开卡片接入。
- 验证方式：`npm run test -- src/components/rpg-entry/rpgEntryPublicGalleryViewModel.test.ts` 、`npm run typecheck` 、`npm run check:encoding` 、相关文件 ESLint 通过。
- 关联文档：`docs/technical/【前端架构】PublicGalleryViewModel收口计划-2026-06-03.md` 。
## 2026-06-03 Profile Task ViewModel 收口
- 背景：`RpgEntryHomeView.tsx` 同时持有每日任务卡片和任务中心弹窗的任务选择、进度 clamp、奖励兜底、状态标签和按钮文案，导致任务展示规则和 JSX 缠在一起。
@@ -3902,15 +3882,6 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
- 验证方式：`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "direct jump hop result route"` ；手测 `/creation/jump-hop/result` 和 `/creation/jump-hop/result?profileId=<id>` 。
- 关联文档：`docs/planning/【玩法创作】创作流程统一总计划-2026-05-30.md` 、`quality-gates/【玩法创作】跨玩法回归与冒烟门禁-2026-05-30.md` 、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md` 。
## 2026-05-29 一期统一创作页必须提供可见统一外壳
- 背景：`UnifiedCreationPage` 首版只暴露隐藏 spec 元数据并包裹旧玩法工作台，用户打开拼图创作页时仍只能看到旧工作台外观，无法验收“统一创作页”。
- 决策：一期统一创作页（拼图、抓大鹅、敲木鱼）必须由 `UnifiedCreationPage` 提供统一标题栏、内容区、页面级纵向滚动和隐藏字段契约；字段元信息只留给测试和代码，不再额外作为可见 chip 占用首屏。玩法工作台只承载具体输入控件、上传、历史素材、校验和提交，不再各自渲染巨大入口标题。拼图、抓大鹅与敲木鱼的实现已经统一收口到 `src/components/unified-creation/workspaces/` ，统一壳只依赖 `UnifiedCreationWorkspace` 。敲木鱼右侧音效和功德面板不得再套内部滚动容器，移动端应自然跟随页面滚动。
- 追加决策：`UnifiedCreationPage` 自己负责页面级滚动；拼图、抓大鹅、跳一跳和敲木鱼四条统一创作入口必须在同一页面壳内从统一标题、表单控件一路滑到提交按钮，避免工作台内部或右侧面板形成套滚动。
- 影响范围：`src/components/unified-creation/UnifiedCreationPage.tsx` 、`src/components/unified-creation/UnifiedCreationWorkspace.tsx` 、`src/components/unified-creation/workspaces/PuzzleCreationWorkspace.tsx` 、`src/components/unified-creation/workspaces/Match3DCreationWorkspace.tsx` 、`src/components/unified-creation/workspaces/WoodenFishCreationWorkspace.tsx` 、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx` 、玩法链路文档。
- 验证方式：`UnifiedCreationPage` 测试应断言隐藏契约仍在但 UI 不再出现字段 chip；拼图和抓大鹅工作台测试应断言 `unifiedChrome=true` 时不再渲染旧巨大标题且仍保留表单输入；木鱼工作台测试或手测应确认敲击音效和功德词条不再停留在独立滚动窗内。
- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md` 。
## 2026-05-31 统一创作壳扩展到跳一跳并接管页面级滚动
- 背景：最初的统一创作页只收口拼图、抓大鹅和敲木鱼，跳一跳仍通过独立工作台壳与独立生成壳渲染，导致用户在 `/creation/jump-hop` 看到的可见外壳与其它统一入口不一致。
@@ -4002,14 +3973,6 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
- 验证方式：玩法接入 PRD 和实现验收必须列出作品架链路；若一个玩法具备发布或试玩能力，但缺少 `/api/creation/<play>/works` 、前端 client `listWorks` 、`CustomWorldCreationHub` props、`creationWorkShelf` adapter 或草稿 / 已发布作品架测试，则接入不算完成。
- 关联文档：`AGENTS.md` 、`.codex/skills/genarrative-play-type-integration/SKILL.md` 、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md` 。
## 2026-05-26 统一公开作品主读模型收口
- 背景：各玩法原有 `*_gallery_card_view` / `*_gallery_view` / `custom_world_gallery_entry` 已经足够承载各自 source 投影，但公开列表 / 详情在 `api-server` 侧分散拼装会继续放大重复逻辑和契约漂移。
- 决策：新增跨玩法统一公开主读模型 `public_work_gallery_entry` 与 `public_work_detail_entry` 。各玩法旧公开 view 不删除，退为 source / 兼容路径；`api-server` 公开列表与详情主路径统一读 public view cache，再映射回现有 HTTP DTO。前端首期仍不直接订阅 SpacetimeDB，只走 BFF HTTP。
- 影响范围：`server-rs/crates/spacetime-module` 、`server-rs/crates/spacetime-client` 、`server-rs/crates/api-server` 、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md` 、`docs/technical/【后端架构】统一公开作品ReadModel设计-2026-05-26.md` 。
- 验证方式：`SELECT * FROM public_work_gallery_entry` 与 `SELECT * FROM public_work_detail_entry` 可作为 `api-server` 长期订阅目标；`/api/public-works` 与 `/api/public-works/{publicWorkCode}` 走统一 cache；旧 `/api/runtime/<play>/gallery` 响应 shape 保持兼容。
- 关联文档：`docs/technical/【后端架构】统一公开作品ReadModel设计-2026-05-26.md` 、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md` 。
## 2026-05-26 推荐页拼图下一关 pending 时保留当前运行态
- 背景：推荐页嵌入拼图在点击“下一关”时，`advancePuzzleNextLevel` 的服务端请求会短暂处于 pending。旧逻辑把推荐卡的 `isStartingRecommendEntry` 和拼图局部 busy 混在一起，导致外层直接切回“加载中...”，把当前 `PuzzleRuntimeShell` 一起卸载，视觉上像是切关闪回。
@@ -4098,14 +4061,6 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
- 验证方式：新生成概念图必须满足“马路是主脊线、建筑群成街区聚合、左右边缘可延展、无品牌乐园元素”四项约束；若图面再跑回环形乐园或漂浮岛，需要重新收敛 prompt。
- 关联文档：`docs/design/【前端体验】寓教于乐Toca式横向世界地图入口概念图-2026-05-23.md` 、`scripts/generate-edutainment-road-town-map-concepts.mjs` 、`output/imagegen/edutainment-road-town-map-concepts-20260523/` 。
## 2026-05-22 敲木鱼图片创作采用三图 image2 链路
- 背景：敲木鱼自定义题材只生成中央敲击物时，运行态缺少与新主题匹配的竖屏背景和主题化返回按钮；若直接让背景 prompt 自由发挥，又容易把敲击物或木槌画进背景里。
- 决策：敲木鱼 `compile-draft` / `regenerate-hit-object` 图片链路固定为三步 image2 edits。第一步调用 VectorEngine `/v1/images/edits` + `gpt-image-2` ，以默认木鱼图作为结构和画风参考，用户上传参考图只作为同次请求的新主题参考，结合用户题材关键词或参考图主题生成 `1:1` 单一纯绿色 `#00FF00 / RGB(0,255,0)` 绿幕背景主体图；`api-server` 先对这张绿幕图执行去绿背景处理并写回 `hitObjectAsset` 。第二步必须以第一步抠图完成后的透明敲击物图作为参考，结合用户原始题材生成 `9:16` 背景环境图并写回 `backgroundAsset` ，避免背景图继承绿幕或纯绿色画布。第三步必须以去绿后的敲击物主体图和背景环境图为参考，生成 `1:1` 单一纯绿色 `#00FF00 / RGB(0,255,0)` 绿幕背景返回按钮图，服务端去绿后写回 `backButtonAsset` 。三步 prompt 使用 PRD 中固定隐藏关键词，不追加额外 negative prompt；返回按钮只允许参考图约束圆形底色和箭头配色，不允许继承复杂造型、花纹、浮雕边、异形外框或装饰图案，主体视觉尺寸比当前模板再放大约 50%，并带主题色外描边；背景图不得包含敲击物本体或木槌互动物品，返回按钮图不得包含文字、数字、水印或额外 UI 面板。
- 影响范围：`api-server` 木鱼图片生成编排、`wooden_fish_work_profile.background_asset_json` 、`wooden_fish_work_profile.back_button_asset_json` 、shared contracts、前端结果页 / 运行态背景与返回按钮展示、敲木鱼 PRD 和平台链路文档。
- 验证方式：执行 `cargo test -p api-server wooden_fish --manifest-path server-rs/Cargo.toml` 、`cargo test -p spacetime-client wooden_fish --manifest-path server-rs/Cargo.toml` 、`npm run spacetime:generate` 、`npm run check:spacetime-schema` 、`npm run typecheck` 。
- 关联文档：`docs/prd/【玩法创作】敲木鱼玩法模板PRD-2026-05-20.md` 、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md` 。
## 2026-05-25 通用系列素材图集实现下沉到 platform-image
- 背景：`generated_asset_sheets` 同时承载 sheet prompt、切图、绿幕去背、边缘 matte 清理和 OSS 持久化准备，长期放在 `api-server` 会把多个玩法的图片 seam 继续绑死在 HTTP crate 上。
@@ -4247,7 +4202,7 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
- 背景：生产和容器环境需要默认把 OTLP 接到本机 Collector，但压测或排障时也要能显式关闭。
- 决策：生产与容器 `api-server` env 模板默认 `GENARRATIVE_OTEL_ENABLED=true` ；生产 endpoint 用 `http://127.0.0.1:4318` ，容器 endpoint 用 `http://otelcol:4318` ； `OTEL_EXPORTER_OTLP_ENDPOINT` 只填 Collector HTTP base endpoint，不填 gRPC `4317` 或 Rider 端口；本地日志、Nginx 日志和 `GENARRATIVE_API_LOG` / `RUST_LOG` 仍保留。
- 影响范围：`deploy/env/api-server.env.example` 、`deploy/container/api-server.env.example` 、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md` 、 `scripts/loadtest/README.md`
- 影响范围：`deploy/env/api-server.env.example` 、`deploy/container/api-server.env.example` 、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md` 。
- 验证方式：检查 env 模板默认值与端点口径；压测若要关闭 OTLP，必须显式设置 `GENARRATIVE_OTEL_ENABLED=false` 。
- 关联文档：`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md` 、`scripts/run-otelcol.mjs` 。
@@ -4257,7 +4212,7 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
- 决策：`deploy/container/docker-compose.loadtest.yml` 里的 `otelcol` 支持通过 `GENARRATIVE_CONTAINER_OTELCOL_CONFIG=./otelcol.grafana.yaml` 切换配置；`deploy/container/otelcol.grafana.yaml` 同时保留 debug exporter，并通过 `GRAFANA_CLOUD_OTLP_ENDPOINT` 和 `GRAFANA_CLOUD_BASIC_AUTH_HEADER` 转发到 Grafana Cloud。
- 影响范围：`deploy/container/docker-compose.loadtest.yml` 、`deploy/container/otelcol.grafana.yaml` 、`deploy/container/README.md` 。
- 验证方式：容器 `otelcol` 启动日志应能看到 OTLP receiver ready，
- 关联文档：`deploy/container/README.md` 、 `scripts/loadtest/README.md`
- 关联文档：`deploy/container/README.md` 。
## 2026-05-17 容器化方案只作为隔离压测与预发模拟路径
@@ -4281,14 +4236,6 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
- 验证方式：Jenkins 日志应先出现 Windows 节点的 `[jenkins-powershell] workspace:` 、`[jenkins-powershell] loaded bytes:` 和 `[prepare-provision-downloads]` 下载日志，再在 `genarrative-build-01` 上出现“使用已下载的 ...”日志；目标机不应出现直接访问 `install.spacetimedb.com` 或 OpenTelemetry GitHub release 下载地址的回退日志，且不再需要 `spacetimedb-update-*` 作为离线交付包。
- 关联文档：`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md` 。
## 2026-05-19 公开 gallery 入口发布限流以快拒绝保护后端
- 背景：容器 2C / 2G 压测中，公开作品列表在约 5000 HTTP req/s 目标下可以保持 200 请求低延迟，但 SpacetimeDB 内存会随 api-server 重连和高压请求累积到容器上限附近。
- 决策：发布配置采用公开 gallery list 专用入口限流：Nginx `genarrative_gallery_rps rate=5000r/s` 、`burst=4096` 、gallery list `limit_conn=320` ； `GENARRATIVE_API_GALLERY_MAX_CONCURRENT_REQUESTS=320` ，公开详情维持更低的 `GENARRATIVE_API_DETAIL_MAX_CONCURRENT_REQUESTS=64` 。超过容量时接受明确 `429` ，不继续扩大入口并发。
- 影响范围：`deploy/nginx/` 发布模板、`deploy/env/api-server.env.example` 、`deploy/container/` 隔离压测模板和生产运维文档。
- 验证方式：容器连续 10 轮不重启 SpacetimeDB 压测，`PEAK_RPS=2500` 等价约 5000 HTTP req/s，平均实际吞吐约 `4219 HTTP req/s` ，总计 `0` 个 5xx， `p95=123ms` 、`p99=234ms` ；同时观察 SpacetimeDB 内存高水位，后续优化先处理连接 / 订阅 / tracking 下游状态。
- 关联文档：`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md` 、`deploy/container/README.md` 。
## 2026-05-19 新增玩法创作工具平台 SOP 冻结
- 背景：新增玩法的创作工具如果默认复制既有玩法的聊天式 Agent、轻输入 Agent 或专属素材模型，平台会不断复制出不可控分支，后续接入、测试和恢复语义都会漂移。
@@ -4329,14 +4276,6 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
- 验证方式：`npm test -- src/services/wooden-fish/woodenFishClient.test.ts` ，并在本地敲木鱼创作时不再提前触发 15 秒超时。
- 关联文档：`docs/prd/【玩法创作】敲木鱼玩法模板PRD-2026-05-20.md` 、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md` 。
## 2026-05-21 RPG publish_world 设定文本以后端草稿真相派生
- 背景：RPG 结果页发布动作只保证提交 `{ action: 'publish_world' }` ；旧 agent 会话可能没有 `seed_text` ，但 `draft_profile_json` 已经通过 `publish_gate` 并可发布。
- 决策：发布正式世界时，`spacetime-module` 不再把 `session.seed_text` 当作唯一 `setting_text` 兜底，而是调用 `module-custom-world::resolve_custom_world_publish_setting_text(...)` 从 payload、当前草稿 profile 和 seed 依次派生。
- 影响范围：RPG / custom-world agent 发布链路、`custom_world_profile` 编译入库、公开 gallery 投影。
- 验证方式：`cargo test -p module-custom-world publish_setting_text --manifest-path server-rs\Cargo.toml` ； `cargo check -p spacetime-module --manifest-path server-rs\Cargo.toml` ；本地 api-server 重启后检查 `/healthz` 。
- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md` 、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md` 、`docs/project-memory/shared-memory/pitfalls.md` 。
## 2026-05-19 系列素材 n\*n 图集抽为 api-server 通用模块
- 背景：抓大鹅物品 sheet 已包含 prompt 组装、固定网格切图、绿幕 / 近白底透明化、切片 PNG 持久化和 prompt 追踪；继续留在 Match3D 私有模块会让跳一跳、后续地块 / 道具类玩法重复复制同一套算法和 OSS 元数据口径。
@@ -4345,31 +4284,6 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
- 验证方式：`cargo test -p api-server generated_asset_sheets --manifest-path server-rs\Cargo.toml -- --nocapture` 覆盖通用 prompt、切片、`n` 校验和 prompt 元数据；玩法侧执行对应素材流水线定向测试。
- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md` 、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md` 。
## 2026-05-19 跳一跳玩法采用正式 scoring DTO 与 public view 投影
- 背景：跳一跳玩法新增后，前端、shared-contracts、SpacetimeDB 生成绑定和后端 mapper 对 scoring 字段口径不一致，schema guard 也要求 table / view 目录与 `migration.rs` 同步。
- 决策：跳一跳的 `JumpHopScoring` 统一采用 `chargeToDistanceRatio/maxChargeMs/hitBonus/perfectBonus` ，公开广场优先使用 `jump_hop_gallery_card_view` ，详情兼容投影保留 `jump_hop_gallery_view` 。`spacetime-module` 新增的 `jump_hop_*` table 必须同步进入 `migration.rs` 和后端架构文档。
- 影响范围：`packages/shared/src/contracts/jumpHop.ts` 、`server-rs/crates/shared-contracts/src/jump_hop.rs` 、`server-rs/crates/spacetime-client/src/mapper/jump_hop.rs` 、`server-rs/crates/spacetime-module/src/migration.rs` 、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md` 。
- 验证方式：`cargo check -p shared-contracts --manifest-path server-rs/Cargo.toml` 、`cargo check -p spacetime-client --manifest-path server-rs/Cargo.toml` 、`cargo check -p api-server --manifest-path server-rs/Cargo.toml` 、`npm run check:spacetime-schema` 。
- 关联文档：`docs/prd/【玩法创作】跳一跳俯视角玩法模板PRD-2026-05-19.md` 、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md` 。
## 2026-05-16 公开作品列表短期由 BFF 订阅读模型缓存
- 背景：作品列表压测和实时性讨论中，曾考虑让浏览器前端直接订阅公开作品列表，减少 HTTP 拉取和 BFF 压力。
- 决策：本轮不直接把作品列表整体交给前端订阅。短期继续由 `api-server` / BFF 通过 `spacetime-client` 长期订阅 SpacetimeDB 公开 read model 并读取本地 cache，维持首屏、排序、字段归一、权限降级和 HTTP fallback。中期可以新增或统一稳定的专用公开作品列表 read model，例如 `public_work_gallery_entry` ，作为前端可选直连订阅对象。
- 边界：未来前端直订阅只允许面向稳定、低基数、公开的专用 read model。前端不得直接订阅 `puzzle_work_profile` 、`custom_world_profile` 等领域源表，也不得在前端自行 join、聚合或执行公开权限逻辑；这些逻辑必须先沉到后端投影 / read model。
- 后续准入：若要落地前端直订阅，必须先完成并验收权限边界、字段契约、排序 / 分页、埋点和 BFF 回退策略；缺任一项时继续走 `api-server` / BFF 订阅缓存方案。
- 影响范围：发现页、推荐流、各玩法公开广场、`api-server` 公开列表缓存、SpacetimeDB public view / public 读模型设计。
- 验证方式：新增公开作品列表订阅能力时，检查前端只消费专用 public read model 或 BFF HTTP DTO；检查源表 row shape、权限判断和跨玩法聚合没有下沉到前端页面。
- 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md` 、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md` 。
- 背景：压测与运行观测需要把 HTTP、SpacetimeDB 调用和应用日志串起来，同时保留本地 `journalctl` / 文件日志做故障排障。
- 决策：`api-server` 通过 OTLP HTTP base endpoint 发送 traces、metrics 和 logs； `otelcol-contrib` ， `npm run otel:debug` 负责 debug 采集，`npm run otel:rider` 负责转发到 Rider；Rider 只是接收与可视化端，不直接替代 Collector。
- 日志口径：Rider Logs 面板只展示 log event 自身字段，请求完成日志需要直接携带 `request_id` 、HTTP method、规范化 route、scheme、path、status、status_class、latency 和 slow_request；更完整的 request attributes 仍以 trace/span 为准。
- 影响范围：`server-rs/crates/shared-logging` 、`server-rs/crates/api-server` 、`scripts/run-otelcol.mjs` 、压测与运维文档。
- 验证方式：`cargo test -p shared-logging --manifest-path server-rs/Cargo.toml generic_otlp_http_endpoint_expands_to_signal_paths` 、`cargo test -p api-server --manifest-path server-rs/Cargo.toml observability_route_keeps_metrics_labels_low_cardinality` 、`cargo test -p api-server --manifest-path server-rs/Cargo.toml resolve_request_scheme_uses_forwarded_proto_first_value` 、`cargo check -p api-server --manifest-path server-rs/Cargo.toml` 。
- 关联文档：`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md` 、`scripts/loadtest/README.md` 。
## 2026-05-14 创作页图像输入统一封装为图像组件
- 背景：拼图创作页已经具备“画面描述生图 / 多参考图生图 / 上传主图后 AI 重绘 / 上传主图后不重绘”四条路径，抓大鹅封面和后续创作页也会复用同一套交互；继续在页面内复制会导致参考图、预览、删除确认和重绘开关漂移。
@@ -4565,14 +4479,6 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
- 验证方式：执行拼图/抓大鹅结果页定向测试、`npm run typecheck` 、`cargo test -p api-server vector_engine_audio_generation` 、`cargo test -p shared-contracts creation_audio` 、`cargo check -p api-server` ，真实生成需配置 VectorEngine 与 OSS 私密环境。
- 关联文档：`docs/technical/PUZZLE_MATCH3D_RESULT_AUDIO_TAB_2026-05-11.md` 。
## 2026-05-11 寓教于乐公开作品使用独立 `edutainment` 来源接入
- 背景：`宝贝识物` 首关需要通过创作模板发布后进入寓教于乐板块，同时关闭入口时必须从发现页、搜索、详情深链、作品号和历史入口完全不可见；若继续落入 RPG 默认公共作品链路，容易出现误启动、误改造或近似标签误归类。
- 决策：寓教于乐公开作品在前端公共作品模型中使用 `sourceType = edutainment` ，当前只承接 `templateId = baby-object-match` 、`templateName = 宝贝识物` ；进入“发现 / 寓教于乐”频道仍必须携带精确等于 `寓教于乐` 的公开标签，不因模板名或近似标签自动归类。公开详情、推荐运行态、改造、编辑、点赞和分享链路都必须显式识别 `edutainment` ，不得回落到 RPG 默认处理。
- 影响范围：公开作品卡、发现页频道、作品号搜索、公开详情深链、分享、作品架聚合、后续儿童动作 Demo 模板的发布结果展示。
- 验证方式：执行第4线程定向单测、前端类型检查、ESLint 与编码检查；关闭 `VITE_ENABLE_EDUTAINMENT_ENTRY` 时确认精确 `寓教于乐` 作品不可通过任何公开入口访问。
- 关联文档：`docs/design/CHILD_MOTION_EDUTAINMENT_DISCOVER_ENTRY_2026-05-09.md` 、`docs/prd/BABY_OBJECT_MATCH_EDUTAINMENT_TEMPLATE_PRD_2026-05-11.md` 、`docs/technical/BABY_OBJECT_MATCH_CREATION_PUBLISH_IMPLEMENTATION_2026-05-11.md` 。
## 2026-05-10 儿童动作 Demo 视觉资产统一为绘本草地舞台
- 背景：儿童动作 Demo 需要从暗色科技风切换到更适合儿童互动的卡通绘本草地风格，并且要让背景、地面、UI、地面指示环和用户轮廓使用同一套 image-2 资源口径。
@@ -4734,14 +4640,6 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
- 验证方式：后续落地时扫描前端、后端、契约、表和文档，确认不存在 `replay` 能力；确认视觉小说没有迁入外部平台账号、订单、会员、促销、后台、公开市场或私有存档系统；确认后端落在 `server-rs + Axum + SpacetimeDB` 。
- 关联文档：`docs/prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md` 、`docs/prd/TXT_MODE_CORE_GAMEPLAY_PRD_2026-04-20.md` 、`docs/technical/TXT_MODE_VISUAL_NOVEL_MIGRATION_EXECUTION_PLAN_2026-04-20.md` 。
## 2026-05-05 视觉小说 VN-02 表与 spacetime-client facade 收口
- 背景：`visual-novel` 后续 API、创作工作台和运行时需要稳定的 SpacetimeDB schema 与 Rust facade，且必须延续“无回放、无私有存档”的产品边界。
- 决策：视觉小说首批数据库只落六张表：`visual_novel_agent_session` 、`visual_novel_agent_message` 、`visual_novel_work_profile` 、`visual_novel_runtime_run` 、`visual_novel_runtime_history_entry` 、`visual_novel_runtime_event` ； `visual_novel_runtime_event` 是 `public event` 审计事件表，不是 replay 数据源；运行历史只保存继续体验与历史重生成需要的 typed step 和快照哈希。`api-server` 后续接入必须经 `spacetime-client/src/visual_novel.rs` typed facade，不直接依赖生成 bindings。
- 影响范围：`server-rs/crates/spacetime-module/src/visual_novel.rs` 、`migration.rs` 、`server-rs/crates/spacetime-client/src/visual_novel.rs` 、`module_bindings/` 、`docs/technical/SPACETIMEDB_TABLE_CATALOG.md` 、VN-05 API 联调。
- 验证方式：执行 `npm run spacetime:generate -- --rust-only` 、`cargo check -p spacetime-module` 、`cargo check -p spacetime-client` 、`npm run check:encoding` ；扫描视觉小说 schema / facade / 表目录确认没有 `replay` 表、路由或私有 save 表。
- 关联文档：`docs/prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md` 、`docs/technical/SPACETIMEDB_TABLE_CATALOG.md` 。
## 2026-05-05 视觉小说 VN-07 前端创作闭环按阶段边界落地
- 背景：`visual-novel` 模板需要先完成创作工作台与结果页，真实生成和正式玩家 runtime 仍依赖 VN-05 后端路由。
@@ -4790,14 +4688,6 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
- 验证方式：移动端推荐页首屏应明显看到更大的作品内容区，底部作者信息区只保留紧凑一条，不再明显挤压运行态。
- 关联文档：`docs/technical/PLATFORM_MOBILE_RECOMMEND_CARD_SAFE_SWIPE_LAYOUT_2026-05-12.md` 。
## 2026-05-05 创作 Tab 固定为智能创作首页，草稿 Tab 承接旧作品架
- 背景：创作首页需要变成面向对话式生成的智能创作页，旧模板卡和作品架继续保留但不应再占据创作首屏。
- 决策：`create` 只承载 `CreativeAgentHome` 智能创作首页与会话流，顶部品牌栏、问候、快捷胶囊、底部输入框和左侧抽屉是主结构；旧的新建作品类型卡不再在 `create` 里展示。原本的 RPG / 拼图 / 大鱼 / Match3D / 方洞 / 视觉小说作品架统一归到 `saves` 草稿 Tab。
- 影响范围：平台创作页布局、创作首页抽屉、草稿页作品架、相关交互测试、旧创作入口 helper。
- 验证方式：移动端点击“创作”直接看到智能创作首页；点击“草稿”看到旧作品架；旧模板入口不再从创作页出现。
- 关联文档：`docs/design/PLATFORM_CREATE_TAB_CREATIVE_AGENT_HOME_2026-05-05.md` 。
## 2026-05-05 创意互动内容生成 Agent 采用 LangChain-Rust 六模块闭环
- 背景：需要支持用户输入文字、图片或文档后，先理解创作意图，再从多个模板候选中选择一个，并把内容填入拼图等目标玩法草稿契约中。
@@ -4814,14 +4704,6 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
- 验证方式：`cargo check -p platform-agent` 、`cargo test -p platform-agent` 、`cargo test -p platform-llm responses_multimodal` 已通过。
- 关联文档：`docs/technical/CREATIVE_INTERACTIVE_CONTENT_AGENT_TECHNICAL_SOLUTION_2026-05-05.md` 。
## 2026-05-05 creative-agent Task E API / SSE facade 已落地
- 背景：Phase 1 需要先把创意 Agent 的 HTTP/SSE 门面接入 Rust `api-server` ，用于前端工作区调用和拼图模板确认闭环。
- 决策：`api-server` 挂载 `/api/runtime/creative-agent/*` 六个鉴权路由；creative session 在 Task D 表未收口前暂存在 `api-server` 运行态并按 authenticated user 校验 owner；未确认模板前不创建拼图 session，`confirm-template` 后才通过既有 `spacetime-client` 创建/编译 `puzzle_agent_session` ；当时 `gpt-5` 请求只从 `APIMART_BASE_URL` / `APIMART_API_KEY` 构造专用 Responses client，不复用通用 `GENARRATIVE_LLM_API_KEY` 。该 LLM 来源已被 2026-07-05 VectorEngine Chat Completions `gpt-5.4-mini` 决策覆盖。
- 影响范围：`server-rs/crates/api-server/src/creative_agent.rs` 、`creative_agent_sse.rs` 、`app.rs` 、`state.rs` 、`module-puzzle` creative template/tool、Phase 1 PRD。
- 验证方式：`cargo check -p api-server` 、`cargo test -p module-puzzle creative` 、`cargo test -p api-server creative_agent` 、`npm run dev:api-server` 后检查 `/healthz` 、`POST /api/runtime/creative-agent/sessions` 、`POST /api/runtime/creative-agent/sessions/{sessionId}/messages/stream` 。
- 关联文档：`docs/prd/CREATIVE_INTERACTIVE_AGENT_PHASE1_LANGCHAIN_RUST_PUZZLE_LOOP_PRD_2026-05-05.md` 。
## 2026-05-10 视觉小说入口收敛为单句创作 + 画风选择
- 背景：视觉小说入口页要对齐抓大鹅式的线性创作入口，只保留最小可用输入，避免再暴露文档 / 空白 / 对话式工作台。
@@ -5025,14 +4907,6 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
- 验证方式：优先检查 `src/index.css` 与 `apps/admin-web/src/styles/admin.css` 是否还存在旧粉色主色；再用编码检查和可执行的本地 typecheck / build 验证。
- 关联文档：`docs/【项目基线】当前产品与工程约束-2026-05-15.md` 。
## 2026-05-20 汪汪声浪 v1 公开闭环计划
- 背景：Bark Battle v1 需要把创作、生成、结果、发布、详情和正式运行态收成一条闭环，避免把草稿试玩、公开广场和正式成绩混在一起。
- 决策：`bark-battle` 入口改为 6 字段表单（作品标题、简介、主题 / 竞技背景描述 `themeDescription` 、玩家形象描述、对手形象描述、难度）；提交后进入 `bark-battle-generating` 独立生成页，自动生成玩家形象、对手形象和竞技背景三图，部分失败也继续进入结果页。旧“角色设定 / 狗狗皮肤预设 / themePreset”统一退场，配置和文档只使用“形象描述 / themeDescription”。结果页只保留单槽重试、重新生成和上传，不再保留一次生成按钮、音频配置入口、皮肤预设入口或排名配置。发布后先跳统一作品详情页 `/works/detail?work=BB-xxxxxxxx` ，再由详情页进入正式 `published` runtime；正式 runtime 必须真实麦克风，`draft` 可试玩、可 mock 且不写正式统计。公开广场统一读取 `bark_battle_gallery_view` read model。
- 影响范围：`BarkBattleConfigEditor` 、`BarkBattleGeneratingView` 、`BarkBattleResultView` 、`BarkBattleRuntimeShell` 、`PlatformEntryFlowShellImpl` 、`appPageRoutes` 、Bark Battle creation/runtime client、公开广场聚合与相关交互测试。
- 验证方式：提交表单后先进入生成页；生成页部分失败仍能落到结果页；结果页只出现单槽重试 / 重新生成 / 上传；发布后先到 `/works/detail?work=BB-xxxxxxxx` 再进正式 runtime；正式 runtime 会要求麦克风并写基础统计，草稿试玩可 mock 且不写正式 run；公开广场读取 `bark_battle_gallery_view` 。
- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md` 。
## 2026-05-22 汪汪声浪运行态与作品外显信息收口
- 背景：Bark Battle v1 在正式运行态、图片生成提示词和作品外部卡片上仍存在体验漂移：能量条推满后还要等计时结束、进入正式 runtime 后还要二次点击声控、角色形象 prompt 会默认注入狗主体、草稿 / 已发布卡片外部看不到创作者。
@@ -5047,12 +4921,6 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
- 决策：默认入口改为 `visible=true` 、`open=true` 、`badge=可创建` ，参考图固定为 `/creation-type-references/bark-battle.webp` 。系统默认迁移只纠偏未被后台人工改过的汪汪声浪入口。发布后先进入统一作品详情页 `/works/detail?work=BB-xxxxxxxx` ；正式 runtime 使用 `runtimeMode=published` 并必须真实麦克风，调用 `startBarkBattleRun` / `finishBarkBattleRun` 写正式 run；草稿结果页试玩仍使用 `runtimeMode=draft` ，允许 mock 且不写正式 run。
- 验证方式：入口配置响应应返回汪汪声浪可创建和专属参考图；发布后地址应为 `/works/detail?work=BB-xxxxxxxx` ；草稿试玩不调用 runtime run API；正式 runtime 无麦克风时不登记正式 run，结算后提交派生指标。
## 2026-05-20 汪汪声浪生成页负责三图自动生成
- 背景：结果页承载预览、修补和发布，若继续放“一次生成”按钮会把初始生成和结果修补职责混在一起。
- 决策：初始三图生成改由 `bark-battle-generating` 独立生成页自动执行，目标槽位只有玩家形象、对手形象和竞技背景；表单术语统一为 `themeDescription` 、玩家形象描述和对手形象描述，不再回退 `themePreset` 、狗狗皮肤预设或“角色设定”。部分失败也进入结果页。结果页不再提供一次生成按钮，音频配置和排名配置不进入 v1 公开闭环；结果页只保留单槽重试、重新生成和上传。发布时 SpacetimeDB `bark_battle_published_config.config_json` 使用规范化后的最终 `publishedSnapshot` ， `published_snapshot_json` 同步保存同一份快照。
- 验证方式：表单提交后进入 `bark-battle-generating` ；结果页不会出现一次生成按钮、音频槽、皮肤预设入口或排名配置；Bark Battle 发布后正式 runtime 应读取结果页最终图片素材而不是初始草稿素材。
## 2026-05-24 敲木鱼结果页先补录作品信息再试玩 / 发布
- 背景：敲木鱼工作台只应保留生成所需输入，作品标题、简介和主题标签适合放在生成草稿后的补录阶段。
@@ -5379,10 +5247,10 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
## 2026-06-11 资产计费边界改为 fail-closed 并补偿退款
- 背景：图片 / 资产生成入口曾在钱包或 SpacetimeDB 预扣费连通性异常时允许继续生成，且失败后同步退款如果遇到 SpacetimeDB 短暂不可用缺少本地补偿；拼图首图后台任务还使用 api-server 进程内 HashSet 互斥，多实例下不能防重复 。
- 决策：暂不实现 token 限流。所有资产生成预扣费改为 fail-closed，预扣费失败直接返回错误；支持 retry 的计费 ledger id 统一包含 HTTP `request_id` ，前端静默刷新重试复用同一个 `x-request-id` 。生成失败后的退款先同步调用 SpacetimeDB，失败则写入 `wallet-refund-outbox` 本地文件并由后台 worker 重放。拼图首图后台生成互斥改为 SpacetimeDB `puzzle_background_compile_task` 表，使用 `task_id + request_id` 作为 claim id，释放时校验 claim id，避免旧任务误删新租约。
- 影响范围：`api-server` 资产计费包裹、钱包退款补偿、拼图首图后台生成、 `spacetime-module` 拼图 task 表、 `spacetime-client` bindings/facade 、前端 API request id 复用和后端架构文档。
- 验证方式：`npm run spacetime:generate` 、 `npm run check:spacetime-schema` 、 `npm run check:spacetime-runtime-access` 、 `node scripts/check-server-rs-ddd-boundaries.mjs` 、 ` cargo check -p api-server --manifest-path server-rs/Cargo.toml``cargo test -p api-server --manifest-path server-rs/Cargo.toml wallet_refund_outbox` 、`cargo test -p api-server --manifest-path server-rs/Cargo.toml asset_operation` 、`npm run test -- src/services/apiClient.test.ts` 、`npm run check:encoding` 。
- 背景：图片 / 资产生成入口曾在钱包或 SpacetimeDB 预扣费连通性异常时允许继续生成，且失败后同步退款如果遇到 SpacetimeDB 短暂不可用缺少本地补偿。
- 决策：暂不实现 token 限流。所有资产生成预扣费改为 fail-closed，预扣费失败直接返回错误；支持 retry 的计费 ledger id 统一包含 HTTP `request_id` ，前端静默刷新重试复用同一个 `x-request-id` 。生成失败后的退款先同步调用 SpacetimeDB，失败则写入 `wallet-refund-outbox` 本地文件并由后台 worker 重放。
- 影响范围：`api-server` 资产计费包裹、钱包退款补偿、`spacetime-client` 调用边界 、前端 API request id 复用和后端架构文档。
- 验证方式：`cargo check -p api-server --manifest-path server-rs/Cargo.toml` 、`cargo test -p api-server --manifest-path server-rs/Cargo.toml wallet_refund_outbox` 、`cargo test -p api-server --manifest-path server-rs/Cargo.toml asset_operation` 、`npm run test -- src/services/apiClient.test.ts` 、`npm run check:encoding` 。
- 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md` 。
## 2026-06-11 图片画布编辑器作为独立画布工程接入
@@ -6657,17 +6525,6 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
- 响应式边界：小于等于 `980px` 时仍隐藏桌面侧边栏，主内容在视口高度内滚动，底部导航继续固定。
- 验证方式：`apps/admin-web/src/styles/admin.test.ts` 锁定壳层滚动契约；桌面浏览器滚动后应保持 `window.scrollY = 0` 、侧边栏 `top = 0` ，只改变 `.admin-content.scrollTop` ；移动视口继续由 `.admin-content` 滚动。
## 2026-07-13 公开作品资产使用派生精确读授权
- 背景：资产 ACL 严格执行后，已登记为 `private` 的作品封面和正式资产不能再依赖 generated 前缀匿名读取；但公开作品仍需要允许访客读取它实际展示和运行的资产。
- 决策：已登记 `asset_object` 继续保持 `private` ，新增匿名派生 view `public_work_asset_read_grant` 。view 只从 `Published + visible` 作品（`custom-world` 另要求未删除）正式发布快照中收集实际使用的资产，历史作品随 view 计算自动补齐；资产读取 procedure 在同一事务快照内先取资产 owner，再使用各玩法 owner 索引定向计算该作者的 grant，不为每张图片执行全站 view，也不从连接级长期订阅 cache 判断 ACL。
- 授权边界：grant 携带作品 owner，API 只有在它与 `asset_object.owner_user_id` 一致，且 `asset_object_id` 或精确 `object_key` 命中时才允许匿名读取。隐藏、删除或取消发布会使 grant 自动消失；参考图、未选中候选图和 `generationInputs` 明确排除。Custom World 只遍历角色、地标、营地、章节和 opening CG 等已知正式根，不能递归 legacy payload 的未知预览 / 编辑字段。
- 禁止项：不得通过放开 `generated-*` 前缀或批量把历史对象改为 `PublicRead` 修复公开作品，两种方式都会让作品可见性生命周期与资产授权脱节，并重新引入跨账号读取。
- 影响范围：`module-assets` 公开资产授权判定、`spacetime-module` 跨玩法公开资产 view 与权威读取 procedure、`spacetime-client` facade 和 `api-server` 资产读取 ACL。
- 权威查询：`asset_object` 不进入 client 长期订阅。API 通过仅 runtime service identity 可调用的 procedure，按主键或 `(bucket, object_key)` 服务端索引读取事务内 metadata；只有位置查询明确返回不存在时才允许进入 legacy curated 前缀兼容，procedure 失败、超时或重复位置一律失败关闭。
- 一致性：隐藏、删除或取消发布提交后，后续读取 procedure 的事务快照立即按新状态判断，不等待任意池连接追上订阅水位。公开派生授权、`PublicRead` 和 legacy 兼容读取签名 URL 的有效期最多 600 秒，因此该能力仍不是对既有签名的瞬时吊销机制；owner / admin 读取保持原有效期口径。
- 验证方式：公开可见作品的正式资产可匿名读取；未选候选图、参考图、跨 owner 伪造 key 仍返回不存在；隐藏、删除或取消发布后新的读取请求立即拒绝，再恢复公开可见时新的读取请求立即恢复；超长公开 `expireSeconds` 被截断为 600 秒。
## 2026-07-13 AI 游戏创作 Agent Runtime V1.4 Git 工作树审阅
- 决策：新增一等只读 `git.inspect` ，共享 command id 为 `project.git_inspect` 且默认 `auto` 。工具只接受 `includeDiff / maxFiles / maxChars` ，返回精确 Git top-level 的 HEAD / branch、staged / unstaged / untracked 安全路径和有界 staged / unstaged unified diff；不改项目 revision 或 verification gate。
@@ -7115,12 +6972,6 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
- 验收边界：确定性测试必须分别覆盖 base handoff 与 repair handoff 在 lifecycle completed 前停止，关闭 mock Provider 后恢复零网络、原 requestId 唯一闭合、repair/protocol audit 幂等、唯一 assistant/completed/committed stream和终局零 sidecar。独立非默认真实 suite `supervisor-swarm-tool-plan-handoff-runner-kill` 已实现并完成 Shell/Root 两级注册；它只使用 sentinel-owned sibling AppData 与 metadata-only zero-fault proxy，每轮随机 capability 严格绑定 project/Agent/run/实际 request slot。断点只能在 handoff 原子落盘并回读一致后、同一实际 requestId lifecycle `completed` 前 ACK， `SIGKILL` 强杀 suite 自有 Runner。恢复必须在同一轮证明同一 requestId 唯一闭合、`networkReplayCount=0` 、protocol/repair audit 幂等、handoff 与 durable batch plan fingerprint 对应、恢复消费前 action/pending/delivery/claim 等副作用为 `0` ，并在终局得到零 sidecar、零重复、零临时资源残留和零正文/凭据/URL/绝对路径泄漏。2026-07-20 的真实单轮已经到达并通过上述 checkpoint，但随后因专业 Agent 连续连接失败而整轮 FAIL；另一独立轮因首批工具数不满足 fixture 也未通过，不能拼接为 PASS。Provider 成功到 handoff 原子落盘回读前的 unknown-result 及手动 context-compaction 仍不在本决策承诺内。
- 当前证据：`tool_plan_` 、`tool_plan_handoff_` 、`provider_handoff_` 、`provider_retry_` 、`response_stream_` 、`finalization_` 与 `finalization_resume_` 定向门禁均保持通过；本轮 `tool_plan_handoff_` 为 `44/44` ， `55/55` ，权威返工合同用例为 `1/1` 。Tauri/Rust 串行全量 1058 tests 为 `1054 passed / 4 ignored / 0 failed` ， `cargo check --tests` 与 `x86_64-pc-windows-gnu cargo check --tests` 均通过；E2E self-test、typecheck、变更脚本 ESLint、encoding 和 `git diff --check` 通过。默认并发全量只作竞态诊断，不替代 `--test-threads=1` 。实现过程中发现并修复 thinking 归一化、源码路径误判、repair 漂移删账本、durable control 清理遗漏后继 repair lifecycle、复数敏感 key/Provider ID 泄漏、malformed JSON trivia 路径绕过、Agent DB 审计字段扩张、PID 复用 temp 误判、中间目录/文件名称换绑 TOCTOU、Windows 路径枚举 ABA 和审计尾部近似去重问题。真实 suite 的 checkpoint 已有单轮外部证据，但整轮仍无 PASS。
## 2026-07-17 旧创作模板与入口停止维护
- 决策：旧创作模板、旧创作入口及其专属运行服务进入下线范围，不再为跳一跳、抓大鹅 Match3D、儿童动作 Demo 等旧链路修复兼容问题、补生成脚本或维持专属门禁。
- 边界：共享账号、钱包、资产、图片编辑器、公开作品、通用 HostBridge、API、SpacetimeDB、发布运维和安全能力不属于旧链路，仍需维持正式门禁。历史文档只作为背景材料，不再作为旧入口继续运行的依据。
- 清理方式：允许直接删除已经失效的旧素材生成命令、入口路由、专属服务和对应测试；删除工程链路时仍需核对是否被当前共享能力引用，不能连带移除仍在使用的公共契约或持久化事实。
## 2026-07-20 开发态 Project Supervisor 纯聊天独立窗口
- 背景：开发人员需要一个不依赖正式产品布局的最小 GUI，用于直接验证 `project-supervisor` 的持久多轮对话与 Runtime 行为。
@@ -7344,27 +7195,20 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
- 并发补验：确定性 Provider 只在 Runtime 明确返回 revision blocker、专业 verification-only repair、成功验证 observation，或项目锁 / repository context drift 这两类可恢复 observation 时重放终态；每个 logical run 最多 16 次。只读职责不得借补验调用未授权命令，验证失败或缺少 `ok` observation 不能交付，Provider completion 计数始终 exactly-once。
- 画布审计：资源 manifest 可以保留生成 prompt 作为本地来源元数据，但公开 `asset.register / asset.update` 审计记录必须移除 `source.prompt` ，只保留 canvas/resource/task/model 等身份字段，避免完整生成正文进入公开 Agent DB 表面。
- 当前测试事实：已有回归覆盖固定画布合同不允许被模型改写、已登记 spritesheet 禁止先删除、只有静态 repair 可原位替换、替换期间原文件 fingerprint 漂移时拒绝覆盖，以及 `design-foundation` 对 `game/index.html` 的 write / patchset / delete 和预览工具均被 Runtime 策略阻断。2026-07-27 的独立 75 分钟上限外部真实 E2E 已按上一节单轮证据完整 **PASS ** ；后续合同变化仍须新起独立轮次，不能复用这次结果替代未来验收。
- 最终落地：本次退役范围覆盖整个旧创作模板体系，包括 RPG / 自定义世界、拼图、拼消消、大鱼吃小鱼、敲木鱼、方洞挑战、视觉小说、汪汪声浪、寓教于乐、Creative Agent、Match3D、跳一跳和儿童动作 Demo。全部相关历史表继续作为数据壳参与 `spacetime-module` 编译，`migration.rs` 白名单与历史数据不变；旧 reducer/procedure/view、API 路由/handler/worker、前端页面/工作台/运行态、共享业务 DTO、纯业务 crate、未挂载旧实现和归档源码均删除，现役公共能力与历史表 schema 保留。
- 兼容读取：只保留历史审计、迁移和资产归属核对所需的最小读取定义；旧 `worldType` 、公开作品号、URL、详情页和专属运行态均不再形成用户可访问入口。
- 方案文档：`docs/technical/【架构下线】旧创作模板业务退役方案-2026-07-17.md` 。
## 2026-07-18 恢复现役 平台公共壳但禁止旧业务依赖回流
## 2026-07-18 平台公共壳与现役依赖边界
- 背景：旧创作模板退役时误把新版 `/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 都不能作为依赖隔离证明 。
- 路由与响应式边界（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())]` 或路由未挂载代替产物证明 。
- 外围编译边界： `platform-auth` 不再编译 runtime guest token， `platform-wechat` 不再编译旧玩法生成结果订阅消息，小程序不再注册订阅授权页；旧公开作品资产授权 view 退出 SpacetimeDB module，匿名素材读取只保留现役 editor showcase 派生授权 。
- 历史队列边界：现役 external generation worker 只领取 `source_module = editor-canvas` 的任务，历史旧玩法 pending / running 行保持原状态，不得被新 worker 领取后改写为失败 。
- Agent crate 边界： `platform-ag ent` 的执行器、工具注册表、回调和拼图 Phase 1 输入均属于已退役 Creative Agent 业务，不得因现役编辑器 Agent 共用一个模型名常量而留在 workspace 或 `api-server` 依赖图。该常量收口到 `platform-llm` ， `platform-agent` 与仅由它引入的 `langchainrust` 退出在运 Cargo resolve graph，相关源码已删除 。
- AI 游戏创作兼容边界：独立 AGC Tauri 壳仍复用 `p latform-agent::game_creation` 的任务图与隔离协作数据模型。 `p latform-agent` 继续排除在 `server-rs` workspace 之外，但其独立 manifest 默认只编译 `game_creation` / `error` ，旧执行器、工具注册表、回调、拼图 Phase 1 与 `langchainrust` 统一受关闭的 `legacy-creative-agent` feature 隔离；AGC lock 不得重新引入这些退役依赖 。
- 防回流补充：顶层 `creationEntryConfigService` 、`creationUrlState` 、`customWorld*` 、`runtimeGuestAuth` 、`runtimeRequest` 、`input-devices` 、`useCombatFlow` 、`useStoryOptions` 、`useMocapInput` 和微信生成订阅 facade 同样属于退役前端模块；Vite dev 对旧 `/api/creation*` 与 `/api/public-works*` 前缀直接返回 404，不能回落 SPA HTML。
- Vite 全量边界补充：`src/games/**` 、`src/data/**` 、`src/prompts/**` 、旧顶层 App / Playground、旧路由和 `services/ai.ts` 必须由 pre-transform 门禁直接拒绝；所有同源 `/generated-*` 裸读在 dev 与生产统一为空 `404` ，历史对象只经现役签名读取接口兼容，不允许 SPA fallback 伪装成资产成功响应。
- 前端混合根目录补充：`src/components` 、`src/hooks` 、`src/persistence` 、`src/routing` 、`src/services` 的根级文件实行现役白名单，Vite 与 ESLint 使用同一口径阻断旧 RPG / 玩法根文件；子目录仍按现役目录和退役目录分别管理，新增公共根文件必须显式登记。
- 影响范围：`PlatformEntryActiveFlowShell` 、`PlatformActiveProfileView` 、编辑器 / 项目搜索、平台 profile clients、`module-runtime` 、`platform-llm` 、Cargo workspace / resolve graph、Vite / ESLint / Rust 产物门禁及旧业务退役方案。
- 决策：桌面端继续使用原平台公共结构，一级导航固定为 `创作 / 项目 / 我的` ；顶栏保留编辑器项目 / 素材搜索、泥点入口和账号胶囊；“我的”全宽保留资料编辑、陶泥号、三项统计、充值、兑换码、社区、反馈、通用设置、API Key 和法律信息。搜索只面向编辑器项目与公开编辑器素材 。
- 依赖边界：公共 dashboard、钱包、充值、兑换码、邀请码、API Key 和设置请求统一放在 `services/platform-entry` ，公共账单展示使用现役 profile model。Vite、ESLint、TypeScript 和 Vitest 只加载现役白名单模块；watch ignore、source scan 和 tree-shaking 都不能作为依赖隔离证明 。
- 路由与响应式边界： `/creation` 、 `/project` 、 `/profile` 都是稳定路由。桌面端使用 `创作 / 项目 / 我的` 侧边栏；移动端底部 dock 只保留“我的”，直达 `/creation` 、 `/project` 、 `/editor/canvas` 或从首页触发项目 / 画布动作时统一显示桌面端提示，不挂载创作主页、项目列表或图片画布 。
- 公共设置边界： `runtime_setting` 是音乐音量和平台主题的现役账号级公共能力。鉴权后的 `GET/PUT /api/runtime/settings` 必须经 `spacetime-client` 调用 `get_runtime_setting_or_default` / `upsert_runtime_setting_and_return`
- 编译门禁： `tsc --listFilesOnly` 、Vite 模块依赖图和正式产物必须只包含现役白名单模块与资源；未登记的服务、路由、组件、类型和静态资源不得进入 dev 服务或生产产物 。
- Rust 产物边界： `module-runtime` 只承载账号、钱包、公共设置、追踪和 feature gate，其他领域 DTO / command / mapper / 规则不得进入实际 rlib。 `check:server-rs-ddd` 必须执行 `check:module-runtime-artifact` ，以实际产物而不是 `#[cfg(any())]` 、源码残留或未挂载路由判断边界 。
- 外围编译边界： `platform-auth` 只编译现役认证能力， `platform-wechat` 只编译现役登录、支付和分享能力，小程序只注册现役页面 。
- 外部任务边界：external generation worker 只领取 `source_module = editor-canvas` 的任务，其他 pending / running 行不得被改写 。
- Agent crate 边界： `platform-agent` 只服务 AGC 独立 workspace；编辑器 Agent 依赖 `platform-editor-agent` 与 `platform-agent-harness` ，不得把 AGC 执行器、工具注册表或回调带回主站依赖图 。
- 前端根目录边界： `src/compon ents `、 `src/hooks` 、 `src/persistence` 、 `src/routing` 、 `src/services` 的根级文件实行现役白名单，新增公共根文件必须显式登记 。
- 影响范围： `P latformEntryActiveFlowShell` 、 `P latformActiveProfileView` 、编辑器 / 项目搜索、平台 profile clients、 `module-runtime` 、 `platform-llm` 、Cargo workspace / resolve graph、Vite / ESLint / Rust 产物门禁 。
## 2026-07-20 VectorEngine 图片任务预算收口到 worker deadline
@@ -7428,9 +7272,8 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
## 2026-07-23 恢复通用灰度发布后台控制面
- 背景：旧创作模板退役时，后台灰度页因同时加载 `creation-entry:*` 动态目标与现役 `image-editor:agent-sidebar` 固定目标，被整页从路由、TypeScript、ESLint 和 Vitest 编译链摘除；通用 feature gate 后端、权限和现役画布 Agent 判定仍在，形成有 API 无正式控制面的不一致 。
- 决策：恢复后台 `#gray-release` 导航、member Tab 权限展示、前端 DTO/client、页面渲染和页面测试；页面只读取和写入 `GET/PUT /admin/api/feature-gates` ，不再请求已退役 `/admin/api/creation-entry/config`
- 目标边界：固定目标列表只登记现役 `image-editor:agent-sidebar` ；管理员仍可直接输入其他通用 Gate Key。不得恢复 `creation-entry:*` 动态目标、入口公告、入口开关、旧作品可见性页面或任何旧模板接口。
- 决策：恢复后台 `#gray-release` 导航、member Tab 权限展示、前端 DTO/client、页面渲染和页面测试；页面只读取和写入 `GET/PUT /admin/api/ feature- gates`
- 目标边界：固定目标列表只登记现役功能；管理员仍可直接输入其他通用 Gate Key。通用页面不得依赖业务入口配置接口或业务 target 列表 。
- 运行语义：环境变量继续是画布 Agent 总开关，feature gate 只在总开关开启后做黑名单、白名单、标签和稳定百分比受众限制；本次不修改 SpacetimeDB schema、灰度优先级或后端契约。
- 验证方式：后台路由与灰度页面 Vitest、`npm run admin-web:typecheck` 、定向 ESLint、`npm run check:encoding` 、`git diff --check` 。
@@ -7477,7 +7320,7 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
## 2026-07-28 画布 Agent 的通用 function-calling harness 与画布 prompt 分层
- 背景：画布 Agent 的 JSON 输出协议、tool schema 注入、memory / hook、轮次保护和“全部工具待确认即结束回合”原先位于 `platform-editor-agent/src/framework` ，与规范展板、已有图编辑路由、模型超时和画布工具混在同一 crate；八类工具还重复携带待确认控制话术。旧 `platform-agent` 已随 Creative Agent 退役，不能作为新公共层复活。
- 决策：新增无旧玩法依赖 的现役 `platform-agent-harness` ，只承载业务中立的 function-calling 执行协议；`platform-editor-agent` 通过兼容 re-export 复用该 crate，并继续承载画布 LLM profile、角色 prompt、公共美术工具路由策略、图片上下文和工具实现。无工具场景同样注入 JSON 响应格式；prompt 不再宣称工具并发执行；request 级 system prompt 必须真实进入本轮请求。待确认卡片的对话路由必须使用正向、条件化语义：只在当前意图匹配一条现存 pending 调用时引导用户点击该卡片，该确认 / 取消意图不产生新 tool call；不在 prompt 中写“不得重新发起相同工具调用”一类全局否定句，因为实测证明模型会将其过度泛化为拒绝后续明确的新生成、修改或重做请求。cancelled 调用不再确认，pending 调用不阻塞无关新任务。
- 决策：新增业务中立 的现役 `platform-agent-harness` ，只承载业务中立的 function-calling 执行协议；`platform-editor-agent` 通过兼容 re-export 复用该 crate，并继续承载画布 LLM profile、角色 prompt、公共美术工具路由策略、图片上下文和工具实现。无工具场景同样注入 JSON 响应格式；prompt 不再宣称工具并发执行；request 级 system prompt 必须真实进入本轮请求。待确认卡片的对话路由必须使用正向、条件化语义：只在当前意图匹配一条现存 pending 调用时引导用户点击该卡片，该确认 / 取消意图不产生新 tool call；不在 prompt 中写“不得重新发起相同工具调用”一类全局否定句，因为实测证明模型会将其过度泛化为拒绝后续明确的新生成、修改或重做请求。cancelled 调用不再确认，pending 调用不阻塞无关新任务。
- 执行与失败决策：prompt 每轮通过 `AgentMemory::begin_staged` 使用与调用方 memory 行为等价、写入隔离的 `StagedAgentMemory` 事务；成功或已有工具活动时显式 `commit()` ，直接 drop 表示回滚。无工具活动失败时回滚本轮 staged 增量，已发生工具活动后失败时提交已发生工具事实并追加 terminal error closure。外部 future drop / abort 若发生在工具完成后，提交工具结果与取消闭环；若发生在工具执行中，提交“已启动、结果未知”与取消闭环，后续先 reconcile，不能假装副作用未发生。harness 通过 `PromptRunError { error, partial_outputs }` 显式返回终态错误和失败前输出；结构化工具失败还必须向调用方保留 `ToolFailure.kind/retryable/fatal` 与原始 `output` ，不在 harness 内压成单一字符串。api-server 的 18 分钟总 deadline 以 runtime future 下沉到 runner：
- 保留边界：会话幂等、OSS 消息、120 秒前端软提示、20 分钟 transport、18 分钟 handler 总 deadline、1024 tokens、8 分钟 provider attempt、泥点计费、确认入队和 external job 懒回填均不进入公共 harness。SpacetimeDB schema、前端 wire DTO 和侧边栏 UI 不变。
- 验证方式：`cargo test -p platform-agent-harness` 、`cargo test -p platform-editor-agent` 、`cargo test -p api-server editor_agent` 、`cargo check -p api-server --locked` 、DDD 边界检查、Rustfmt、编码检查和 `git diff --check` 。
