整理项目记忆与Agent RAG入口

迁移项目共享记忆到 docs/project-memory，保留 .hermes 仅作为工具目录新增 Agent 本地 RAG 索引与上下文包检索脚本记录 RAG 依赖只安装到 .rag/runtime 并加入忽略规则同步文档与检查脚本中的项目记忆路径
2026-06-16 16:06:54 +08:00
parent a51e63415f
commit 15a527d7f4
29 changed files with 738 additions and 97 deletions
--- a/docs/project-memory/README.md
+++ b/docs/project-memory/README.md
@@ -0,0 +1,32 @@
+# 项目记忆目录
+
+本目录保存可以进入 Git 的项目级长期知识，供开发者和 Agent 读取。`.hermes/` 只保留 Hermes 工具专用资源，不再作为项目知识库。
+
+## 目录结构
+
+```text
+docs/project-memory/
+├─ README.md
+├─ shared-memory/
+│  ├─ project-overview.md
+│  ├─ team-conventions.md
+│  ├─ development-workflow.md
+│  ├─ document-map.md
+│  ├─ decision-log.md
+│  ├─ pitfalls.md
+│  └─ handoff-template.md
+├─ plans/
+└─ todos/
+```
+
+## 使用原则
+
+- 开发前先读 `AGENTS.md`，再按任务读取 `docs/project-memory/shared-memory/` 和当前 `docs/` 文档。
+- 长期有效的架构约定、接口变化、排障经验、开发流程和协作规则写入 `shared-memory/`。
+- 阶段性计划写入 `plans/`，已确定但暂未实施的共享 TODO 写入 `todos/`。
+- 如果本目录内容与代码或最新 `docs/` 冲突，以代码和最新 `docs/` 为准，并同步修正过期记忆。
+- 禁止写入个人配置、API Key、Token、Cookie、会话记录、认证文件、本地私密路径、构建产物、日志、缓存和数据库 dump。
+
+## RAG 索引
+
+本目录是 Agent 本地 RAG 的高权重索引源。RAG 主要用于 Agent 检索上下文，不替代人工阅读入口或正式文档地图。索引脚本位于 `scripts/rag/`，本地生成的 `.rag/` 数据不提交 Git。
--- a/docs/project-memory/plans/架构优化计划书.md
+++ b/docs/project-memory/plans/架构优化计划书.md
@@ -0,0 +1,399 @@
+# Genarrative（陶泥儿）项目架构优化计划书
+
+**文档版本**：v1.0  
+**编制日期**：2026-05-26  
+**项目名称**：Genarrative（陶泥儿）  
+**文档密级**：内部
+
+---
+
+## 一、项目概况
+
+| 维度 | 详情 |
+|---|---|
+| **项目名** | Genarrative（陶泥儿） |
+| **项目定位** | AI Native 互动视觉 RPG 平台——支持多种玩法模板的 AI 创作、运行与分享（"玩法类型平台"） |
+| **核心玩法** | 拼图、视觉小说、Match3D、Bark Battle、Big Fish、Jump-Hop、Square Hole、木鱼、教娱等 10+ 种玩法模板 |
+| **代码规模** | 前端 ~823 个 TS/TSX 文件，后端 ~1532 个 Rust 文件，属于大型项目 |
+
+### 1.1 计划目的
+
+本计划书基于对 Genarrative 项目当前架构的全面分析，识别架构层面的关键问题，并提出分阶段、可落地的优化方案。旨在：
+
+- 统一前端架构模式，降低团队认知成本和新人上手门槛
+- 提升模块内聚性，减少不必要的耦合与依赖
+- 建立自动化契约保障机制，降低跨语言同步出错风险
+- 优化工程基础设施，提高开发效率和运维可观测性
+
+---
+
+## 二、技术栈总览
+
+| 层级 | 技术选型 | 版本 |
+|---|---|---|
+| **前端框架** | React + TypeScript + Vite | React 19 / TS 5.8 / Vite 6 |
+| **样式** | TailwindCSS | v4 |
+| **3D / 动画** | Three.js、Motion、cannon-es | - |
+| **后端 HTTP** | Rust + Axum（BFF 门面） | Axum 0.8 |
+| **游戏状态 DB** | SpacetimeDB（实时反应式数据库） | v2.2 |
+| **AI / LLM** | LangChain-Rust + LLM Proxy | - |
+| **小程序** | 微信小程序（含微信支付） | - |
+| **容器化** | Docker Compose（Nginx + API Server + OTel Collector） | - |
+| **运维** | systemd、Nginx、Jenkins CI/CD、k6 压测 | - |
+| **可观测性** | OpenTelemetry（OTLP → Grafana） | - |
+
+---
+
+## 三、当前架构分层图
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                        入口层                                │
+│  index.html → main.tsx → resolveAppRoute() → RouteComponent  │
+│  (多入口路由：平台主页 / 拼图 / BigFish / Match3D / ...)      │
+└──────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌──────────────────────────────────────────────────────────────┐
+│                      前端应用层 (src/)                        │
+│  ┌─────────────┐  ┌──────────────┐  ┌──────────────────────┐│
+│  │ components/ │  │  services/   │  │  games/              ││
+│  │ *-creation  │  │ *-creation   │  │  bark-battle/        ││
+│  │ *-result    │  │ *-runtime    │  │    domain/           ││
+│  │ *-runtime   │  │ *-works      │  │    application/      ││
+│  │ common/     │  │ storyEngine  │  │    infrastructure/   ││
+│  │ auth/       │  │ payment      │  │    ui/               ││
+│  └─────────────┘  └──────────────┘  └──────────────────────┘│
+│  ┌─────────────┐  ┌──────────────┐  ┌──────────────────────┐│
+│  │ hooks/      │  │ data/        │  │ routing/             ││
+│  │ persistence/│  │ functionCat. │  │ config/  editor/     ││
+│  └─────────────┘  └──────────────┘  └──────────────────────┘│
+└──────────────────────────────────────────────────────────────┘
+                              │ Vite Proxy (/api/*)
+                              ▼
+┌──────────────────────────────────────────────────────────────┐
+│                    Rust 后端 (server-rs/)                     │
+│  ┌──────────────────────────────────────────────────────┐   │
+│  │  api-server (Axum HTTP / SSE / BFF 门面)              │   │
+│  └──────────────────────────────────────────────────────┘   │
+│         │                    │                    │          │
+│         ▼                    ▼                    ▼          │
+│  ┌──────────┐    ┌──────────────────┐   ┌──────────────┐   │
+│  │ platform │    │     module-*     │   │   shared     │   │
+│  │  -auth   │    │  -puzzle         │   │  -contracts  │   │
+│  │  -llm    │    │  -visual-novel   │   │  -kernel     │   │
+│  │  -image  │    │  -match3d        │   │  -logging    │   │
+│  │  -oss    │    │  -bark-battle    │   └──────────────┘   │
+│  │  -speech │    │  -big-fish ...   │                       │
+│  │  -agent  │    │  -runtime        │                       │
+│  └──────────┘    │  -combat/npc     │                       │
+│                  └──────────────────┘                       │
+│                          │                                  │
+│                          ▼                                  │
+│  ┌──────────────────────────────────────────────────────┐   │
+│  │  spacetime-module + spacetime-client → SpacetimeDB   │   │
+│  └──────────────────────────────────────────────────────┘   │
+└──────────────────────────────────────────────────────────────┘
+
+┌──────────────────────────────────────────────────────────────┐
+│                    辅助子系统                                │
+│  apps/admin-web (React 后台管理)                             │
+│  miniprogram/ (微信小程序)                                   │
+│  packages/shared (前后端共享契约/LLM工具)                     │
+│  deploy/ (Docker/Nginx/systemd/OTel)                         │
+│  scripts/ (40+ 构建/部署/检查脚本)                            │
+│  jenkins/ (CI/CD Pipeline)                                   │
+└──────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 四、架构亮点
+
+1. **清晰的"玩法模板"平台模式**  
+   每种玩法遵循统一的 `creation → result → runtime` 三段式生命周期，前端 `components/` 和 `services/` 均按此模式组织。新增玩法可快速套用模板，极大降低了横向扩展成本。
+
+2. **后端严格的分层约束**  
+   `api-server`（门面）→ `module-*`（领域）→ `spacetime-module`（持久化），`module-*` 不直接依赖 Axum、HTTP、SpacetimeDB table、LLM、文件系统，保证了领域纯净性和可测试性。
+
+3. **SpacetimeDB 作为游戏状态核心**  
+   采用反应式实时数据库替代传统 Redis + PostgreSQL 组合，天然适合多人实时游戏状态同步，减少了中间层复杂度和延迟。
+
+4. **前端 DDD 探索**  
+   `src/games/bark-battle/` 采用 `domain / application / infrastructure / ui` 四层 DDD 结构，为复杂玩法的前端架构提供了良好范本。
+
+5. **完善的多入口路由体系**  
+   通过 `resolveAppRoute()` 按 URL path 分发到不同的 lazy-loaded 组件，实现了按需加载和良好的首屏性能。
+
+6. **运维体系完备**  
+   Docker Compose + systemd + Nginx + OpenTelemetry + k6 压测 + Jenkins CI/CD，覆盖了构建、部署、监控、压测全链路。
+
+---
+
+## 五、问题诊断与改进方案
+
+### 问题 1：前端 services/ 与 components/ 的耦合不统一
+
+**现状**  
+大部分玩法遵循 `services/` + `components/` 分离模式，但部分玩法运行时直接放在 `components/` 下，services 层职责模糊——有的承担了业务逻辑编排，有的仅作简单 API 调用。
+
+**影响**  
+- 新人阅读代码时无法预判某个逻辑应位于哪个目录
+- 单元测试困难：services 与组件耦合的业务逻辑无法独立测试
+- 跨玩法复用时需要额外的迁移成本
+
+**改进方案**  
+1. 制定规范：`services/` 仅负责纯 API 调用和数据转换，不包含业务判断逻辑
+2. 业务逻辑统一归到 `hooks/` 或 `games/<play-type>/application/`
+3. 以 puzzle 玩法为样板，先行重构并形成迁移指南，再推广至其余玩法
+4. 在 CI 中增加 ESLint 规则，禁止 `components/` 直接 import `services/` 之外的外部模块
+
+**预期收益**  
+- 职责边界清晰，降低认知成本约 30%
+- services 层可独立单测覆盖率达到 80%+
+- 新玩法开发上手时间从 2 天缩短至 0.5 天
+
+---
+
+### 问题 2：前端 DDD 与模板模式并存，架构不统一
+
+**现状**  
+`bark-battle` 采用 DDD 四层结构（`domain/application/infrastructure/ui`），其余玩法散落在 `components/` + `services/` 下，存在两种截然不同的组织范式。
+
+**影响**  
+- 团队内部对"正确"的代码组织方式缺乏共识
+- 代码审查时需要切换判断标准
+- DDD 玩法的优势无法在全局范围内发挥
+
+**改进方案**  
+1. 所有玩法统一迁移到 `src/games/<play-type>/` 下，采用 `domain / application / ui` 三层结构（infrastructure 按需保留）
+2. 以 puzzle 为样板完成首例迁移，产出迁移 Checklist 和模板生成脚本
+3. 新增玩法脚手架直接生成 DDD 结构目录
+4. 旧玩法分批次迁移，每批次 2-3 个玩法，在 4 个迭代内完成
+
+**预期收益**  
+- 架构一致性提升至 100%
+- 跨玩法逻辑复用变得可能（domain 层可共享）
+- 为后续 monorepo 改造打下基础
+
+---
+
+### 问题 3：后端 module-* 粒度偏细，存在潜在循环依赖风险
+
+**现状**  
+后端共 35 个 crate。`module-runtime` 被拆分为 3 个独立 crate，`module-combat / npc / inventory` 各自独立。部分紧密协作的模块之间可能存在隐式耦合。
+
+**影响**  
+- 编译时间增长（35 个 crate 独立编译）
+- 跨 crate 重构时需要同时修改多处
+- 循环依赖风险增加，可能在特定组合下触发编译失败
+
+**改进方案**  
+1. 评估合并方案：
+   - `module-runtime-*` 系列合并为单 crate `module-runtime`，内部用 `mod` 做逻辑隔离
+   - `module-combat / npc / inventory` 评估合并为 `module-combat`，npc 和 inventory 作为子模块
+2. 保留 trait/interface 抽象层，确保 module 之间不直接依赖具体实现
+3. 在 CI 中引入 `cargo-deny` 或自定义脚本，自动检测 module 间的依赖方向是否违反分层约束
+4. 目标：将 35 个 crate 精简至 25 个以内
+
+**预期收益**  
+- 全量编译时间预计缩短 15%-20%
+- 循环依赖风险归零
+- module 内部重构成本降低
+
+---
+
+### 问题 4：根目录 env 文件过多且混乱
+
+**现状**  
+根目录存在 4 个 env 文件（`.env`、`.env.example`、`.env.production` 等），且 `deploy/` 下另有多个 env 文件。配置分散在多处，部分文件之间字段不一致。
+
+**影响**  
+- 排查配置问题时需要翻阅多个文件
+- 新人无法快速确定本地开发需要哪些环境变量
+- 部署时可能遗漏或错误覆盖某项配置
+
+**改进方案**  
+1. 收敛为三层配置体系：
+   - `.env.example`：包含所有可配置项的说明和默认值（唯一提交到仓库的 env 文件）
+   - `.env.local`：本地开发覆盖（加入 .gitignore）
+   - `deploy/env/<env-name>.env`：各部署环境专用配置
+2. 引入 config crate，支持层次覆盖（default → local → env-specific），启动时自动校验必填字段
+3. 在 CI 中加入 env 校验步骤：对比 `.env.example` 与部署环境的 env 文件，标记缺失或多余字段
+
+**预期收益**  
+- 配置查找时间从分钟级降至秒级
+- 部署配置遗漏导致的线上事故减少 90%+
+- 新成员本地环境搭建时间从 30 分钟缩短至 10 分钟
+
+---
+
+### 问题 5：scripts/ 目录膨胀为"万能工具箱"
+
+**现状**  
+`scripts/` 目录共 42 个文件，涵盖构建、部署、检查、迁移、生成、压测等，全部平铺在同一层级，缺乏分类。
+
+**影响**  
+- 难以快速定位所需脚本
+- 同类脚本缺乏命名规范
+- 新增脚本时不知道放在何处
+
+**改进方案**  
+1. 按功能域分类重组：
+
+```
+scripts/
+├── build/        # 构建相关（vite、cargo、wasm 等）
+├── deploy/       # 部署相关（docker、systemd、rsync）
+├── check/        # 检查/校验（lint、format、type-check）
+├── spacetime/    # SpacetimeDB 相关（migration、seed）
+├── generate/     # 代码生成（scaffold、proto、types）
+└── loadtest/     # 压测脚本（k6 配置及辅助）
+```
+
+2. 为每个子目录添加 README.md，说明各脚本用途和调用方式
+3. 将重复逻辑抽取为共享函数库
+
+**预期收益**  
+- 脚本查找效率提升 60%+
+- 降低脚本重复概率
+- 便于 CI Pipeline 直接引用标准化路径
+
+---
+
+### 问题 6：前端路由系统缺乏统一的"玩法注册"机制
+
+**现状**  
+`appRoutes.tsx` 中硬编码 `switch-case` 逻辑，每新增一种玩法需手动修改路由文件、入口组件、资源加载等多个位置。
+
+**影响**  
+- 新增玩法的接入点分散，容易遗漏
+- 路由文件随玩法增多持续膨胀
+- 无法实现"按需注册"——即使某环境不包含某玩法，路由代码仍然存在
+
+**改进方案**  
+1. 建立 `PlayTypeRegistry` 模式：每个玩法导出一个注册项对象，包含 `path`、`lazyComponent`、`preload` 等字段
+2. `resolveAppRoute()` 改为动态聚合所有注册项，替代硬编码 switch-case
+3. 支持环境级玩法开关：通过配置控制某环境启用哪些玩法，路由系统自动忽略未启用的
+
+**预期收益**  
+- 新增玩法零侵入路由系统，只需在玩法目录内添加注册文件
+- 路由文件体积与玩法数量解耦
+- 灰度发布和 A/B 测试变得可能
+
+---
+
+### 问题 7：前端缺少统一的状态管理层
+
+**现状**  
+前端状态管理依赖 React hooks + props drilling + services 层手动管理。未使用任何状态管理库（如 Zustand、Jotai、Redux）。
+
+**影响**  
+- 全局状态（用户认证、会话、通知）通过多层 props 传递，组件耦合度高
+- 跨页面状态无法优雅共享
+- 状态变更难以追踪和调试
+
+**改进方案**  
+1. 引入 Zustand（轻量、无 boilerplate、TS 友好）管理全局状态：
+   - `useAuthStore`：认证状态
+   - `useSessionStore`：当前会话/游戏状态
+   - `useNotificationStore`：全局通知
+2. 玩法内状态继续使用 React hooks + `useReducer`，保持局部自治
+3. 全局 store 与玩法内 state 通过事件总线松耦合通信
+
+**预期收益**  
+- props drilling 层级从 5+ 层降至 1-2 层
+- 全局状态可追溯，支持 Redux DevTools 调试
+- 跨玩法状态共享（如用户余额、道具）变得自然
+
+---
+
+### 问题 8：shared-contracts 的实际复用程度待验证
+
+**现状**  
+前后端通过 `packages/shared` 共享 DTO 类型定义，但依赖手动同步 TypeScript 类型。可能存在前后端契约不一致但编译期无法检出的情况。
+
+**影响**  
+- 后端修改 DTO 字段后，前端可能遗漏更新导致运行时错误
+- 手动同步耗时且易出错
+- Code Review 时难以判断契约一致性
+
+**改进方案**  
+1. 引入 `ts-rs`：从 Rust 结构体自动生成 TypeScript 类型定义
+2. 将生成步骤集成到 CI Pipeline：
+   - 每次 Rust PR 触发 `ts-rs` 重新生成 TS 类型
+   - 对比生成的类型与仓库中的类型是否一致，不一致则 CI 失败
+3. 长期考虑引入 Protobuf / OpenAPI 作为跨语言契约的单一事实来源
+
+**预期收益**  
+- 前后端契约不一致导致的线上 bug 减少 95%+
+- 手动同步工作量归零
+- PR Review 时契约一致性问题自动拦截
+
+---
+
+## 六、改进优先级路线图
+
+| 优先级 | 改进项 | 涉及层 | 建议时间 | 预期收益 |
+|---|---|---|---|---|
+| **P0** | 统一前端 services/hooks/components 职责边界 | 前端 | 第 1-2 周 | 降低认知成本，提升可测试性 |
+| **P1** | 建立 PlayType 注册机制 | 前端 | 第 2-3 周 | 新增玩法零侵入路由 |
+| **P1** | 评估 module-* 合并方案并执行 | 后端 | 第 3-4 周 | 减少编译时间 15%-20% |
+| **P1** | 引入 Zustand 全局状态管理 | 前端 | 第 4-5 周 | 改善状态追踪与跨组件共享 |
+| **P2** | 清理 scripts/ 目录结构 | 工程 | 第 5-6 周 | 提高可发现性 |
+| **P2** | 前端玩法统一迁移至 DDD 结构 | 前端 | 第 5-8 周 | 架构一致性 100% |
+| **P2** | env 配置收敛 | 工程 | 第 6-8 周 | 减少部署配置事故 |
+| **P3** | 前后端共享 DTO 自动化（ts-rs） | 全栈 | 第 6-8 周 | 消除契约不一致风险 |
+| **P3** | CI 分层约束检查（cargo-deny） | 后端 | 第 8-10 周 | 循环依赖归零 |
+
+> **说明**：P0 为阻塞项，必须最先完成。P1 项可部分并行推进（PlayType 注册与 module 合并互不依赖）。P2/P3 为优化项，可在日常迭代中穿插推进。
+
+---
+
+## 七、架构健康度评分卡
+
+| 维度 | 评分 | 当前状态 | 目标状态 |
+|---|---|---|---|
+| **分层清晰度** | ★★★★☆ | 后端分层严格，前端分层存在不一致 | ★★★★★ 前后端均严格分层 |
+| **模块化程度** | ★★★★☆ | 后端 35 crate 粒度偏细，前端结构化较好 | ★★★★☆ 后端精简至 25 crate |
+| **可扩展性** | ★★★★★ | 玩法模板模式使新增玩法成本低 | ★★★★★ 维持 |
+| **代码复用** | ★★★☆☆ | shared 层作用有限，services 层有重复 | ★★★★☆ DDD 统一后 domain 可复用 |
+| **DevOps 成熟度** | ★★★★★ | Docker + k6 + OTel + Jenkins 覆盖完整 | ★★★★★ 维持 |
+| **文档完备性** | ★★★★★ | docs/ 分类清晰，基线文档齐全 | ★★★★★ 维持 |
+| **技术债务管控** | ★★★★☆ | 有明确的"历史残留"标记和废弃策略 | ★★★★★ 增加自动化检测 |
+
+**综合评级：A-（优秀，存在可优化空间）**
+
+---
+
+## 八、附录：代码规模统计
+
+| 维度 | 数量 |
+|---|---|
+| **前端 TypeScript/TSX 文件** | ~823 个 |
+| **后端 Rust 源文件** | ~1532 个 |
+| **后端 Crate 数量** | 35 个 |
+| **核心玩法类型** | 10+ 种 |
+| **scripts/ 脚本数量** | 42 个 |
+| **根目录 env 文件** | 4 个 + deploy 下多个 |
+
+### 模块规模明细（后端）
+
+| Crate | 职责 | 建议 |
+|---|---|---|
+| `api-server` | Axum HTTP 门面，路由聚合 | 保持 |
+| `platform-*` (auth/llm/image/oss/speech/agent) | 平台级跨玩法能力 | 保持 |
+| `module-puzzle` | 拼图玩法 | 作为 DDD 迁移样板 |
+| `module-visual-novel` | 视觉小说 | 后续迁移 |
+| `module-match3d` | Match3D 三消 | 后续迁移 |
+| `module-bark-battle` | 犬吠对战 | 已对接前端 DDD |
+| `module-big-fish` | Big Fish | 后续迁移 |
+| `module-runtime*` (3 crates) | 通用运行时 | **建议合并为单 crate** |
+| `module-combat / npc / inventory` | 战斗系统 | **建议合并** |
+| `spacetime-module` + `spacetime-client` | SpacetimeDB 接入 | 保持 |
+| `shared-contracts / kernel / logging` | 共享基础设施 | 保持 |
+
+---
+
+> **文档结束**  
+> 本计划书由 Genarrative 架构分析报告衍生，所有改进项均基于对当前项目代码库的实际分析。执行过程中如遇阻力或新发现，应及时更新本计划书并同步相关方。
--- a/docs/project-memory/shared-memory/decision-log.md
+++ b/docs/project-memory/shared-memory/decision-log.md
--- a/docs/project-memory/shared-memory/development-workflow.md
+++ b/docs/project-memory/shared-memory/development-workflow.md
@@ -0,0 +1,301 @@
+# 开发工作流
+
+> 用途：给本地 Agent 和开发人员提供统一的开发、测试、提交流程。具体命令以 `package.json`、`server-rs/Cargo.toml`、`AGENTS.md` 和相关 `docs/` 最新文档为准。
+
+## 标准任务流程
+
+```text
+同步代码 → 读取 AGENTS.md → 读取 docs/project-memory/shared-memory → 查找/完善 docs → 制定计划 → 小步实现 → 本地验证 → 更新文档/记忆 → 提交
+```
+
+## 建议启动方式
+
+在项目根目录启动本地 Agent：
+
+```bash
+cd /path/to/Genarrative
+hermes
+```
+
+在本机当前常见路径为：
+
+```bash
+/home/dsk/workspace/Genarrative
+```
+
+其他开发者以自己本地实际路径为准，不要把个人绝对路径写入共享文档作为通用规则。
+
+## 开发前检查清单
+
+- [ ] 当前分支是否正确
+- [ ] 是否已拉取最新代码
+- [ ] 是否阅读 `AGENTS.md`
+- [ ] 是否阅读 `docs/project-memory/shared-memory/` 相关文件
+- [ ] 是否阅读 `README.md` 中的运行和检查命令
+- [ ] 是否阅读 `docs/README.md` 及任务相关分类 README
+- [ ] 是否存在足够具体的 PRD / 设计 / 技术文档
+- [ ] 是否明确测试、验收和文档更新方式
+
+## 本地运行命令
+
+安装依赖：
+
+```bash
+npm install
+```
+
+完整联调开发环境：
+
+```bash
+npm run dev
+```
+
+Linux 多用户共享同一台机器开发时，本地 dev 脚本会为当前 Linux 用户分配一个固定端口段并写入系统级注册表 `/var/tmp/genarrative-dev-port-ranges/registry.json`，自动分配从 `10000-10099` 开始，每段 100 个端口，四个 dev 服务依次使用 `start` 到 `start + 3`。可用 `GENARRATIVE_DEV_PORT_RANGE` 或 `npm run dev -- --port-range` 手动指定端口段用于特殊场景；注册表会阻止不同用户使用相同或重叠段，并让同一用户后续启动继续复用自己已占用的固定段。该机制只在 Linux 生效，Windows 仍沿用原有端口探测与漂移逻辑。
+
+本地 `npm run dev`、`npm run dev:spacetime` 和 `npm run dev:api-server` 会在 Rust 子进程环境中绕过项目默认 `sccache` wrapper，避免损坏的本机 cache daemon 阻断 `spacetime publish` 或 `api-server` 启动；显式设置的非 sccache 自定义 wrapper 会被保留。生产 / Jenkins 构建仍按流水线自身的 sccache 策略执行。
+
+该命令会启动：
+
+- SpacetimeDB standalone
+- Rust `api-server`
+- 主站 Vite
+- 后台 Vite
+
+`npm run dev` 和单模块 `dev:*` 命令会更新根目录 `.app/dev-stack.json`，记录四个本地服务的 pid、端口、URL、启动状态和当前命令。该目录只作本机运行态观测，不提交 Git。
+
+开启自动刷新：
+
+```bash
+npm run dev -- --watch
+```
+
+watch 模式只由外层调度器自动处理后端侧刷新：`spacetime-module` 改动后重新发布模块但不重启 standalone 宿主，`api-server` 改动后重启 Rust 进程。主站 Vite 与后台 Vite 的源码变化交给 Vite 自身 HMR，避免外层 watcher 监听到依赖缓存或临时文件后循环重启。
+
+非 watch 模式下，`npm run dev` 终端支持输入 `rs spacetime`、`rs api-server`、`rs web`、`rs admin-web` 或 `rs all`。其中 `rs spacetime` 只会重新发布 `spacetime-module`，不会重启 standalone 宿主；其他模块仍按进程重启。
+
+单独启动 SpacetimeDB：
+
+```bash
+npm run dev:spacetime
+```
+
+单独启动 Rust API server：
+
+```bash
+npm run dev:api-server
+```
+
+单独启动前端：
+
+```bash
+npm run dev:web
+```
+
+单独启动后台管理前端：
+
+```bash
+npm run dev:admin-web
+```
+
+本地 SSH 服务器管理面板：
+
+```bash
+npm run server-manager:panel
+```
+
+该命令启动 `server-rs/crates/server-manager-panel` 的 egui 桌面工具，从本机 `~/.ssh/config` 读取可用 `Host` alias，支持多服务器健康巡检、可折叠侧边栏和受控 systemd 服务启停。服务操作通过远端 `sudo -n systemctl start|stop|restart <unit>` 执行，目标服务器需要提前配置对应 unit 的免交互 sudo 权限。
+面板启动时会自动注入本机中文字体；如开发机中文仍显示为方块，可设置 `GENARRATIVE_SERVER_PANEL_CJK_FONT=/path/to/font.ttc|index` 指向本机 CJK 字体。
+
+`npm run dev:api-server` 会保留终端实时输出，并把同一份输出持久化到 `logs/api-server/api-server-<timestamp>.log`。完整联调入口 `npm run dev` 启动的 Rust `api-server` 使用同一套日志规则。如需改写路径，可设置 `GENARRATIVE_API_SERVER_LOG_FILE`；如只改目录，可设置 `GENARRATIVE_API_SERVER_LOG_DIR`。
+
+开发态 `npm run dev` / `npm run dev:api-server` 默认打开 `GENARRATIVE_DEV_PASSWORD_ENTRY_AUTO_REGISTER_ENABLED=true`，密码入口可以直接注册未知手机号账号；生产默认仍关闭该开关。
+
+生产 `Genarrative-Stdb-Module-Publish` 的备份默认使用 `DATABASE_BACKUP_MODE=async`：流水线在 publish 前先生成本地冷备份，随后继续 publish，并把同一份发布前备份交给后台 Node 进程上传 OSS，避免低带宽 OSS 上传长时间占住部署窗口。需要强制在 publish 前等待打包和上传并让失败阻断发布时，手动选择 `DATABASE_BACKUP_MODE=sync`；已有其他备份窗口且明确接受风险时才选择 `skip`。
+
+生产 API / Web / Stdb 发布流水线不在目标机器 checkout Git。对应 Build 流水线必须把发布产物、校验文件、`release-manifest.json` 和部署 / 发布脚本一起归档；Deploy / Publish 流水线只通过 `copyArtifacts` 复制上游构建归档并执行随产物归档的脚本，避免目标机器 Git 访问和产物 commit 与部署脚本 commit 漂移。
+
+查看本地 Rust/SpacetimeDB 日志：
+
+```bash
+npm run dev:spacetime:logs
+```
+
+本机隔离验证外部生成 worker 队列、API-only 更新和 worker 动态扩缩容时，优先使用：
+
+```bash
+npm run container:worker-smoke -- smoke
+```
+
+该命令生成 `deploy/container/worker-smoke/` 下的 gitignored env 与端口 state，启动独立 compose project 和独立 SpacetimeDB，用 unsupported job 验证 worker claim / fail 回写；排查时用 `api-update` 确认 API 重建不触碰 worker，用 `scale <n>` 调整 worker 数量。
+`external_generation_job` 是 private table，worker-smoke 通过 worker 日志里的 job_id 和 unsupported 记录确认消费，不通过 CLI SQL 查询队列表。
+worker-smoke 默认把本机 `spacetime` CLI 打成轻量 SpacetimeDB 镜像，避免首次 smoke 依赖官方大镜像下载。若容器内 Cargo 下载依赖不稳定，追加 `--local-binary`，让容器内 Cargo 复用本机 Cargo 缓存构建当前 `api-server` 二进制，并把产物放进 Debian bookworm smoke runtime；可用 `GENARRATIVE_WORKER_SMOKE_LOCAL_BASE_IMAGE` 覆盖运行时基础镜像；隔离端口或库数据需要重建时追加 `--force`。
+
+后台管理前端：
+
+```bash
+npm run admin-web:build
+npm run admin-web:typecheck
+```
+
+SpacetimeDB bindings 生成：
+
+```bash
+npm run spacetime:generate
+```
+
+CodeGraph 本地语义索引：
+
+```bash
+npm run codegraph:init
+npm run codegraph:status
+npm run codegraph:sync
+npm run codegraph:index
+```
+
+`.codegraph/config.json` 可随仓库共享；`.codegraph/codegraph.db`、缓存和日志为本机生成物，不提交。
+
+Codex 项目级 hook 保存在 `.codex/config.toml` 与 `.codex/hooks/`：
+
+- `PreToolUse` hook：`node .codex/hooks/pre-submit-compile-check.mjs`，Codex 准备执行 `git commit` 前检查 `npm run typecheck`、`npm run admin-web:typecheck`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`。
+- `PostToolUse` hook：`node .codex/hooks/post-edit-codegraph-sync.mjs`，工具修改文件后执行 `npm run codegraph:sync`。
+
+个人 token、模型路由、MCP server 仍属于个人环境；需要时由成员本机执行 `codegraph install` 或查看 `codegraph install --print-config codex`，不要提交个人全局配置。
+
+Agent 本地 RAG 文档索引：
+
+```bash
+npm run rag:index
+npm run rag:search -- --query "搜索内容"
+```
+
+RAG 主要供 Agent 检索项目上下文，开发者仍按 `AGENTS.md`、`docs/README.md` 和 `docs/project-memory/` 阅读正式文档。RAG 仅索引项目文档和项目共享记忆，默认不把 LanceDB、Transformers.js 或本地 embedding 模型装入根 `package.json`。需要启用 RAG 时，Agent 必须先询问用户是否安装本地运行时依赖；用户确认后只安装到 gitignored 的 `.rag/runtime/`，模型缓存和向量库也留在 `.rag/`。具体命令见 `scripts/rag/README.md`。
+
+## 常用检查命令
+
+- 后端通用用户行为埋点统一通过 `record_tracking_event_and_return` procedure、`SpacetimeRuntimeClient::record_tracking_event(...)` 与 api-server `tracking` 中间件写入 `tracking_event` / `tracking_daily_stat`；后台、RPG、大鱼吃小鱼、Visual Novel、Story、Combat 默认排除；作品级游玩埋点统一使用 `work_play_start`，详细事件清单见 `docs/technical/BACKEND_TRACKING_EVENT_COVERAGE_2026-05-09.md`。
+
+编码检查：
+
+```bash
+npm run check:encoding
+```
+
+ESLint：
+
+```bash
+npm run lint:eslint
+```
+
+类型检查：
+
+```bash
+npm run typecheck
+```
+
+综合 lint：
+
+```bash
+npm run lint
+```
+
+测试：
+
+```bash
+npm run test
+```
+
+生产构建：
+
+```bash
+npm run build
+```
+
+内容检查：
+
+```bash
+npm run check:data
+npm run check:overrides
+npm run check:smoke
+npm run check:content
+```
+
+全量检查：
+
+```bash
+npm run check
+```
+
+DDD 边界检查：
+
+```bash
+npm run check:server-rs-ddd
+```
+
+## 后端相关默认验证
+
+后端修改后，按 DDD 文档中的验收命令执行。涉及 API smoke 时：
+
+- 使用 `npm run dev:api-server` 重新拉起后端。
+- 禁止使用 `npm run api-server:maincloud`、`npm.cmd run api-server:maincloud` 或任何 `GENARRATIVE_SPACETIME_MAINCLOUD_*` 口径；这些只属于历史残留。
+- 本地 smoke 检查 `/healthz`；发布后或确认实例可接生产流量时检查 `/readyz`。
+- 执行对应自动测试。
+- 涉及 SpacetimeDB 表、reducer、procedure、row shape 或绑定变化时，同步更新 `migration.rs`、表目录和生成绑定。
+- SpacetimeDB 已有表新增字段必须放在 Rust 表结构体最后，并设置明确默认值；需要修改字段名时，先询问用户并确认迁移计划，再同步更新 `server-rs/crates/spacetime-module/src/migration.rs`、表目录和生成绑定。
+- 修改 SpacetimeDB schema 后运行 `npm run check:spacetime-schema`，用自动检查拦截缺 default、插入中间、字段删除/改名/重排/改类型，以及漏改迁移、表目录或绑定。
+
+关键文档：
+
+- `docs/technical/CURRENT_BACKEND_IMPLEMENTATION_BASELINE_2026-04-25.md`
+- `docs/technical/SERVER_RS_DDD_FULL_REFACTOR_2026-04-28.md`
+- `docs/technical/SERVER_RS_DDD_PARALLEL_TASKLIST_2026-04-29.md`
+- `docs/technical/SERVER_RS_DDD_G1_CONTRACT_AND_ROUTE_MATRIX_2026-04-29.md`
+- `docs/technical/SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md`
+- `docs/technical/SPACETIMEDB_TABLE_CATALOG.md`
+- `docs/technical/MAINCLOUD_REFERENCE_REMOVAL_POLICY_2026-05-06.md`
+
+## 生产压测与观测默认口径
+
+- 作品列表 50 HTTP req/s 压测使用 `scripts/loadtest/README.md` 中的 K6 命令；当前脚本一次 iteration 请求两个公开列表接口，因此目标 50 HTTP req/s 对应 `PEAK_RPS=25`。
+- 生产 `api-server` 默认 backlog、worker threads、HTTP 并发背压、`/readyz` 接流检查、systemd 优雅停机窗口、Nginx upstream timing log 和 OTLP 开关以 `docs/【开发运维】本地开发验证与生产运维-2026-05-15.md` 为准。
+- OpenTelemetry 现阶段可选发送 traces / metrics / logs，但不会取代本地 `journalctl -u genarrative-api.service`、`logs/api-server/` 与 `/var/log/nginx/genarrative.*.log`。
+- 指标 label 不写 raw URI、userId、profileId 或 request_id；request_id 只用于 trace/log 串联。
+
+## 前端相关默认验证
+
+前端修改后，应根据修改范围选择：
+
+- `npm run check:encoding`
+- `npm run lint:eslint`
+- `npm run typecheck`
+- `npm run test`
+- 页面交互 smoke
+- 移动端视口检查
+
+前端原则：
+
+- 移动端优先，再兼容网页端。
+- 页面只展示后端返回的状态，不自行计算结论型业务状态。
+- 创作中心入口配置事实源在 SpacetimeDB，通过 `GET /api/creation-entry/config` 下发；前端只在 `platformEntryCreationTypes.ts` 做展示派生，api-server 路由熔断也使用同一份配置，禁止恢复前端硬编码入口配置文件。底部加号创作入口页公告位也跟随后端 `eventBanners` 配置，前端只做展示和轮播；后台公告用表单维护标题与 HTML 内容，保存时再序列化为后端 `eventBannersJson` 传输字段。`最近创作` 不属于模板分类，不能作为分类缺失兜底；生成中和生成失败的真实草稿摘要都应进入最近创作。
+- 一期统一创作页字段 spec 同样跟随 `GET /api/creation-entry/config`，由 `creationTypes[].unifiedCreationSpec` 下发；拼图、抓大鹅、敲木鱼之外的模板不接入该扩展位，前端只保留旧后端缺字段时的兜底默认。
+- 优先复用现有面板、抽屉、弹窗，不新建独立大系统。
+- 不在 UI 中默认写功能说明类文本。
+- 弹出独立面板的交互不要实现成在当前面板下方追加内容。
+
+## 文档更新规则
+
+- 工程修改要同步更新对应文档。
+- 如果没有现成文档，新文档统一放入 `docs/` 下合适分类。
+- `docs/project-memory/shared-memory/` 只记录高频、长期、团队共享的摘要和索引，不替代完整 PRD/技术文档。
+- 如果 `docs/project-memory/shared-memory/` 与代码或 `docs/` 冲突，以代码和最新 `docs/` 为准，并同步修正共享记忆。
+
+## 提交前建议让 Agent 执行
+
+涉及拼图、抓大鹅、敲木鱼统一创作 / 生成链路、Phase 2 之后的跨玩法回归或本地 dev 栈时，先按 `quality-gates/README.md`、`quality-gates/【玩法创作】跨玩法回归与冒烟门禁-2026-05-30.md` 和对应单项门禁文档执行自动脚本与体验检查。
+
+```text
+请检查当前 git diff，指出：
+1. 是否违反 AGENTS.md 或 docs/project-memory/shared-memory 约定；
+2. 是否需要补充 docs；
+3. 是否有长期知识需要写入 docs/project-memory/shared-memory；
+4. 建议的测试命令和提交信息。
+```
--- a/docs/project-memory/shared-memory/document-map.md
+++ b/docs/project-memory/shared-memory/document-map.md
@@ -0,0 +1,54 @@
+# 文档地图与阅读索引
+
+更新时间：`2026-05-15`
+
+## 当前文档入口
+
+| 场景 | 优先阅读 |
+| --- | --- |
+| 建立项目背景 | `README.md`、`AGENTS.md`、`docs/project-memory/shared-memory/project-overview.md` |
+| 找当前文档 | `docs/README.md` |
+| 产品、命名、UI、协作和废弃路线 | `docs/【项目基线】当前产品与工程约束-2026-05-15.md` |
+| 后端、DDD、API、SpacetimeDB schema 和表目录 | `docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md` |
+| 创作入口、草稿架和玩法链路 | `docs/【玩法创作】平台入口与玩法链路-2026-05-15.md` |
+| 创作流程统一阶段计划 | `docs/planning/【玩法创作】创作流程统一总计划-2026-05-30.md` |
+| 本地启动、验证、部署、埋点和运营查询 | `docs/【开发运维】本地开发验证与生产运维-2026-05-15.md` |
+| 微信小程序虚拟支付 | `docs/【技术方案】微信虚拟支付接入-2026-05-26.md` |
+| UI 像素资产与 9-slice 规范 | `UI_CODING_STANDARD.md` |
+
+## 阅读顺序
+
+通用复杂任务：
+
+1. `AGENTS.md`
+2. `docs/project-memory/shared-memory/`
+3. `docs/README.md`
+4. 与任务匹配的当前融合文档
+
+后端 / 数据真相 / SpacetimeDB：
+
+1. `docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`
+2. `docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`
+3. 对应 crate README 或源码
+
+玩法 / 创作入口 / 运行态：
+
+1. `docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`
+2. 若任务涉及跨玩法创作流程统一，读取 `docs/planning/【玩法创作】创作流程统一总计划-2026-05-30.md`
+3. `docs/【项目基线】当前产品与工程约束-2026-05-15.md`
+4. 相关前端组件、service、shared contract 和后端 module
+
+生产部署 / 服务器 / Jenkins：
+
+1. `docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`
+2. `deploy/env/api-server.env.example`
+3. `deploy/nginx/README.md`
+
+## 维护规则
+
+- 当前 `docs/` 只保留少量融合文档。
+- 新增工程实现时，如果已有对应当前文档，必须同步更新。
+- 如果没有合适位置，新文档文件名必须使用 `【标签名】中文标题-YYYY-MM-DD.md`。
+- 阶段性流水账、一次性修复记录和已关闭实验不要再新增为长期文档。
+- 阶段性计划和一次性 TODO 不再作为长期文档目录；需要保留的决策、流程和坑点应进入 `docs/` 当前文档或 `docs/project-memory/shared-memory/`。
+- 如果文档与代码冲突，先确认代码事实，再更新过期文档和共享记忆。
--- a/docs/project-memory/shared-memory/handoff-template.md
+++ b/docs/project-memory/shared-memory/handoff-template.md
@@ -0,0 +1,53 @@
+# 任务交接模板
+
+> 用途：当一名开发者把任务交给另一名开发者，或让 Hermes 接续上下文时，复制本模板并填写。
+
+## 基本信息
+
+- 任务名称：
+- 负责人：
+- 当前分支：
+- 相关需求/Issue：
+- 相关文档：
+
+## 背景
+
+简要说明为什么做这个任务，以及业务/技术目标。
+
+## 已完成
+
+- [ ] 
+- [ ] 
+- [ ] 
+
+## 未完成
+
+- [ ] 
+- [ ] 
+- [ ] 
+
+## 关键文件
+
+- `path/to/file`：说明
+- `path/to/file`：说明
+
+## 当前问题/风险
+
+- 
+
+## 已执行验证
+
+```bash
+# 粘贴已执行命令和结果摘要
+```
+
+## 建议下一步
+
+1. 
+2. 
+3. 
+
+## 是否需要更新团队记忆
+
+- [ ] 不需要
+- [ ] 需要，建议更新：`docs/project-memory/shared-memory/...`
--- a/docs/project-memory/shared-memory/pitfalls.md
+++ b/docs/project-memory/shared-memory/pitfalls.md
--- a/docs/project-memory/shared-memory/project-overview.md
+++ b/docs/project-memory/shared-memory/project-overview.md
@@ -0,0 +1,59 @@
+# Genarrative 项目共享概览
+
+更新时间：`2026-06-12`
+
+## 一句话定位
+
+Genarrative / 陶泥儿是一个 AI 原生互动内容与小游戏平台，把 AI 创作、作品草稿、公开分发、运行态、用户账号、钱包任务、后台管理和小程序外壳收在同一套工程中。
+
+## 当前主要能力
+
+- RPG / 自定义世界创作与运行时。
+- 拼图玩法创作、草稿、发布、运行态和排行榜。
+- 拼消消玩法创作、素材图集生成、结果页、发布、统一作品详情、正式运行态和基础统计。
+- 敲木鱼玩法创作、草稿、发布、运行态、公开详情和分享码。
+- 抓大鹅 Match3D 创作、2D 多视角素材生成、发布和运行态。
+- 大鱼吃小鱼、方洞挑战、视觉小说、汪汪声浪和儿童向寓教于乐玩法。
+- 账号、短信 / 密码 / 微信登录、个人资料、任务、钱包、邀请码、充值、反馈、法律信息和后台管理。
+
+## 当前入口
+
+- 主站：`http://127.0.0.1:3000`。
+- 后台：`http://127.0.0.1:3000/admin/` 或 `http://127.0.0.1:3102`。
+- 后台前端工程：`apps/admin-web`。
+- 小程序 WebView 外壳：`miniprogram/`。
+- 法律文本：`media/files/user_agreement.md`、`media/files/privacy_policy.md`、`media/files/disclaimer.md`。
+
+移动端一级 Tab：`推荐 / 发现 / 创作 / 草稿 / 我的`。
+
+## 当前后端路线
+
+唯一有效后端路线：
+
+```text
+server-rs + Axum + SpacetimeDB
+```
+
+当前 SpacetimeDB crate、SDK、CLI / standalone、生成 bindings 和容器压测镜像统一按 `2.5.0` 对齐；遇到版本不匹配时先升级到 `server-rs/Cargo.toml` 锁定版本，升级后重启对应 SpacetimeDB 进程再重试。
+
+职责边界：
+
+- `api-server`：HTTP / SSE / BFF 门面和外部副作用编排。
+- `spacetime-module`：SpacetimeDB 表、reducer、procedure、事务 adapter 和 row mapper。
+- `spacetime-client`：后端访问 SpacetimeDB 的 typed facade。
+- `module-*`：纯领域模型、命令、应用规则、领域事件和领域错误。
+- `platform-*`：OSS、LLM、认证、语音等外部平台能力。
+- `shared-contracts` / `packages/shared`：前后端 DTO 和公开契约。
+- 前端：表现、交互、临时 UI 状态和后端结果渲染。
+
+明确废弃：旧 `server-node`、Express、PostgreSQL、Go 服务端、`maincloud`、人工 `spacetime --root-dir` 口径，以及前端承接正式业务真相的路线。
+
+## 当前文档入口
+
+- `docs/README.md`
+- `docs/【项目基线】当前产品与工程约束-2026-05-15.md`
+- `docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`
+- `docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`
+- `docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`
+
+旧 PRD、设计、审计、阶段计划和技术流水账已融合进上述文档；没有融合的旧材料不再作为实现依据。
--- a/docs/project-memory/shared-memory/team-conventions.md
+++ b/docs/project-memory/shared-memory/team-conventions.md
@@ -0,0 +1,100 @@
+# 团队协作约定
+
+> 用途：约定 3 名开发人员在各自本地开发环境和 Agent 中协作开发、共享项目记忆的方式。
+
+## 基本模式
+
+- 每位开发人员在自己的电脑上使用本地 Agent。
+- 每位开发人员本地拉取同一个项目仓库，独立修改代码、运行测试、提交分支。
+- 团队共享内容优先放在本仓库 `docs/project-memory/` 与 `docs/` 中，通过 Git 同步。
+- 不共享个人 `~/.hermes` 目录。
+
+## 共享与禁止共享
+
+推荐共享：
+
+- `docs/project-memory/shared-memory/` 团队级长期记忆
+- `docs/project-memory/plans/` 阶段性实施计划
+- `docs/project-memory/todos/` 已确定需要执行、但尚未进入实施的共享 TODO 计划
+- `.hermes/skills/` Hermes 专用仓库级 skills
+- `docs/` 中 PRD、设计、技术、经验、审计、查询手册
+- `AGENTS.md` 项目级 Agent 约束
+
+禁止提交：
+
+- 个人 `~/.hermes/config.yaml`
+- 个人 `~/.hermes/.env`
+- 个人 `~/.hermes/sessions/`
+- API Key、Token、Cookie、认证文件
+- 个人本地私密路径和个人隐私信息
+- 构建产物、日志、缓存、数据库 dump
+
+## 开发前
+
+1. 拉取最新代码。
+2. 阅读 `AGENTS.md`。
+3. 阅读 `docs/project-memory/shared-memory/` 中与任务相关的文件。
+4. 阅读 `docs/README.md` 和任务相关分类 README。
+5. 阅读对应 PRD、设计、技术、经验或审计文档。
+6. 如果文档不足以指导编码，先补充或修正文档。
+
+## 开发中
+
+- 保持修改范围聚焦，不做无关重构。
+- 复用、修改、扩展现有系统优先，避免新建重复系统或页面。
+- 新增 Markdown 文档时，文件名必须以分类标签开头，格式为 `【标签名】中文标题-日期.md`；只在任务需要时重命名历史文档，避免无关大 diff。
+- 涉及中文文本时注意 UTF-8 编码和乱码排查。
+- 涉及后端时遵循 DDD 分层，不把业务真相下沉到前端或临时兼容层。
+- `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`。
+
+## 开发后
+
+1. 运行与修改范围匹配的测试或验证命令。
+2. 更新相关 `docs/` 文档。
+3. 新增或沉淀 Markdown 文档时，确认文件名已使用 `【标签名】` 前缀。
+4. 若产生长期有效知识，更新 `docs/project-memory/shared-memory/`。
+5. 若形成 Hermes 专用可复用流程，考虑沉淀到 `.hermes/skills/`。
+6. 提交代码时，提交标题使用中文；标题后逐行写明本次提交修改了什么，每条变更单独一行。
+
+## 文档阅读顺序
+
+通用任务建议：
+
+1. `README.md`
+2. `AGENTS.md`
+3. `docs/project-memory/shared-memory/`
+4. `docs/README.md`
+5. `docs/experience/README.md`
+6. `docs/audits/README.md`
+7. 任务所属分类：`docs/design/`、`docs/technical/`、`docs/planning/`、`docs/prd/`、`docs/reference/`、`docs/tracking/`、`docs/operations/`
+
+后端任务建议：
+
+1. `docs/technical/CURRENT_BACKEND_IMPLEMENTATION_BASELINE_2026-04-25.md`
+2. `docs/technical/SERVER_RS_DDD_FULL_REFACTOR_2026-04-28.md`
+3. `docs/technical/SERVER_RS_DDD_G1_CONTRACT_AND_ROUTE_MATRIX_2026-04-29.md`
+4. `docs/technical/SERVER_RS_DDD_PARALLEL_TASKLIST_2026-04-29.md`
+5. `docs/technical/SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md`
+6. `docs/technical/SPACETIMEDB_TABLE_CATALOG.md`
+7. `docs/technical/MAINCLOUD_REFERENCE_REMOVAL_POLICY_2026-05-06.md`
+
+## 共享记忆更新准则
+
+适合更新：
+
+- 新增稳定架构约定
+- 新增长期开发流程
+- 已验证的踩坑和排障步骤
+- 重要接口契约变化
+- 团队协作规范变化
+- 文档索引或阅读顺序变化
+
+不适合更新：
+
+- 一次性临时计划
+- 未验证猜测
+- 个人偏好和个人路径
+- 敏感信息
+- 大段聊天记录
--- a/docs/project-memory/todos/【后端架构】前端直订阅公开作品列表准入待办-2026-05-16.md
+++ b/docs/project-memory/todos/【后端架构】前端直订阅公开作品列表准入待办-2026-05-16.md
@@ -0,0 +1,27 @@
+# 前端直订阅公开作品列表准入待办
+
+## 背景
+
+未来可以考虑让前端直接订阅公开作品列表，以减少列表读取链路中的 HTTP 往返，并复用 SpacetimeDB 的实时同步能力。
+
+## 当前结论
+
+短期仍由 `api-server` / BFF 订阅 SpacetimeDB public read model，并从本地 cache 读取后对外提供 HTTP 列表接口。前端不直接订阅作品源表，也不把正式列表排序、分页、权限裁剪逻辑下放到 UI。
+
+## 落地前置条件
+
+- 建立专用、稳定、低基数的 public read model，例如 `public_work_gallery_entry`。
+- 明确权限边界，只暴露公开列表所需字段，不泄露作者私有信息、审核内部状态或运营字段。
+- 固化字段契约，明确字段含义、默认值、兼容策略和生成绑定更新流程。
+- 明确排序与分页语义，避免依赖自增 ID 顺序，优先使用时间戳或显式排序字段。
+- 补齐埋点方案，能区分直订阅首屏、增量更新、分页加载和 fallback 命中。
+- 保留 BFF HTTP fallback，用于低版本客户端、订阅失败、权限策略调整和灰度回滚。
+- 禁止前端订阅 `puzzle_work_profile`、`custom_world_profile` 等作品源表。
+
+## 建议验收
+
+- 文档确认直订阅只面向专用 public read model，不绕过 BFF 读取源表。
+- schema、绑定、字段契约、排序分页和权限说明同步更新。
+- 前端具备订阅失败后的 BFF HTTP fallback。
+- 自动测试覆盖公开字段裁剪、排序分页稳定性和 fallback 路径。
+- 监控可观察直订阅成功率、首屏耗时、增量更新延迟和 fallback 比例。