Merge remote-tracking branch 'origin/master' into fix/mobile-style

# Conflicts: # docs/project-memory/shared-memory/decision-log.md # docs/project-memory/shared-memory/pitfalls.md
2026-09-30 10:20:58 +08:00
parent b43a663fe2 54e534b101
commit dfd94c435f
464 changed files with 35102 additions and 20228 deletions
@@ -49,10 +49,13 @@
 - AGC 当前 Agent 与策划 Agent 的消息层级共用 `packages/shared` 的 `AgentMessageContent`：正文使用 `body`，思考、中间输出与工具调用使用 `process`；过程字号和颜色由共享组件统一定义，错误状态保留语义色。
 - 后端遵循 `module-*`、`spacetime-module`、`spacetime-client`、`api-server`、`platform-*`、`shared-contracts` 的现役边界。
 - 前端只负责表现、交互和临时 UI 状态；正式状态来自后端投影、API 或持久化契约。
+- AGC 渲染层是离线前端：平台接口、OSS 素材直传、Provider、错误上报与账户/认证的网络 IO 全部在 Rust 的 reqwest facade，渲染层不得再出现 `fetch(` / `XMLHttpRequest` / `EventSource` / `sendBeacon(` / `new WebSocket(` 或 `@tauri-apps/plugin-http`；客户端窗口 capability 也不得授予 `http:default`。`check:native-shells --groups=contract` 的 `ai-game-creator-shell-user-dev-boundary` 用负向门禁钉住这条，改动渲染层网络边界必须同批改该门禁与 `build-release.test.mjs`。
+- AGC 工作区的正式状态变化走 Rust 事件 + 一次受控快照读取，不建立固定频率轮询（纯 UI 计时器、拖拽重复器与动画 tick 除外）：渲染层先订阅再读快照，事件重复或内容未变时保持数组身份，卸载后迟到事件不写回。Direct 活动回合的唯一事实源是 Direct 线程管理器的活动回合快照（`list_direct_active_turns` 只读它；登记、进度内容变化与收口各广播一次 `game-creator-direct-active-turns-changed`），渲染层与 Rust 都不得再引第二份注册表。
+- AGC 维护态（平台 `503` 且命中 `MAINTENANCE` 或「维护」）由 Rust 在平台请求的错误分支经 `platform_maintenance::watch_platform_response` 分类并广播 `genarrative-client-maintenance-detected`；渲染层只订阅并打开唯一的「系统维护中」弹窗，不自行解析 HTTP，业务面板各自的错误文案保持不变。
 - 对已明确退役且无现役调用方、公开契约、持久化数据、活跃实例或迁移要求的对象，直接清理实现、专属测试和说明，将权威文档更新为当前状态；历史由 Git 保存。公开契约、持久化数据和正式迁移按实际需求保留最小兼容及对应测试。
 - 修改 `/api/external/v1` 时，同批更新 `docs/openapi/genarrative-external-v1.openapi.json` 与契约测试。
 - 修改 SpacetimeDB schema 时遵守字段追加/default 约束，同步 migration、表目录、生成绑定，并运行 schema 检查；删除、改名、重排或改类型前先确认迁移计划。
- 日志不递归输出完整配置、应用状态或 provider client；新增字段默认不进入安全摘要。
+- 日志不递归输出完整配置、应用状态或 provider client；新增字段默认不进入安全摘要。所有 provider 配置类型（`LlmConfig`、`OssConfig`、`WechatConfig`、`WechatPayConfig`、`MattingConfig`、`VolcengineSpeechConfig`、`Hyper3dSettings`、`VectorEngineImageSettings`、`VectorEngineAudioSettings`）都必须手写脱敏 `Debug`：只输出枚举、数值、布尔、有界标识与 `<redacted>` 占位，凭据、私钥、路径与 URL 一律不递归格式化，并各带一条哨兵值回归用例（`cargo test -p platform-* debug`）。新增同类配置必须照此办理，不允许直接 `derive(Debug)`。
 - HTTP 横切能力集中在 Axum/Tower 中间件：正常与降级路由复用追踪层；指标与 trace 使用 `MatchedPath` 模板及固定兜底，不把请求 ID、实际资源 ID 或 query 放入指标标签。在途请求通过 RAII guard 覆盖 Future 取消与 panic unwind；请求执行和响应体存活分别计量，不能把 handler 耗时当作 SSE 全生命周期。
 - 业务依赖在组合根显式装配，Axum `FromRef` 只抽取可浅拷贝的窄能力。项目元数据与 External API 鉴权不持有完整 `AppState`，测试经相同接口注入替代依赖。集中鉴权仍保留方法级 fallback、公开入口、MCP 和 body limit 顺序；Provider span 跳过完整参数，不隐藏计费、重试、幂等或事务规则。
 - 中文文案、注释和文档保持中文与 UTF-8，优先局部补丁。