Genarrative/.hermes/shared-memory/pitfalls.md

踩坑与排障记录

用途：记录已验证、未来很可能再次遇到的问题。每条都应包含现象、原因、处理方式和验证方式。

记录格式

## 问题标题

- 现象：看到什么错误或异常行为
- 原因：确认后的根因
- 处理：具体修复步骤
- 验证：如何确认修复有效
- 关联：相关文件、文档、提交或 Issue

---

中文乱码与编码风险

• 现象：中文文案、注释、剧情或文档显示为乱码，或被改写成英文。
• 原因：Windows/PowerShell/终端编码不一致，或整文件重写导致编码变化。
• 处理：
  • 不要直接沿用乱码文本。
  • 不要用英文替换中文，除非用户明确要求翻译。
  • 在 PowerShell 5.1 中显式使用 UTF-8。
  • 优先用 Python/Node 或 Get-Content -Encoding UTF8 核对原文。
  • 修改中文文件时优先局部补丁，避免无关内容重写。
• 验证：运行仓库已有编码检查；人工抽查修改文件中的中文内容。
• 关联：AGENTS.md、npm run check:encoding。

.hermes 只放共享内容，不放个人 Hermes 配置

• 现象：团队成员误把个人 Hermes 配置、会话或密钥复制进仓库。
• 原因：仓库 .hermes/ 与个人 ~/.hermes/ 名称相似。
• 处理：仓库 .hermes/ 只放 Markdown 共享记忆、计划和可公开 skills；不提交 .env、config.yaml、sessions/、auth.json。
• 验证：提交前检查 git diff -- .hermes，确认没有密钥、会话记录或个人路径敏感信息。
• 关联：.hermes/README.md。

旧后端路线文档造成判断漂移

• 现象：开发时参考到 Express、Node、PostgreSQL 或 Go 方向旧文档，导致接口、数据真相或部署路径与当前主线不一致。
• 原因：项目历史文档较多，部分旧方案仍保留作迁移参考。
• 处理：涉及服务端、数据真相、SpacetimeDB、运行时状态时，先看 CURRENT_BACKEND_IMPLEMENTATION_BASELINE_2026-04-25.md，再看 DDD 总纲和具体技术方案。
• 验证：代码改动应落在 server-rs + Axum + SpacetimeDB 主线；旧路线只作为迁移参考，不作为兼容目标。
• 关联：docs/technical/CURRENT_BACKEND_IMPLEMENTATION_BASELINE_2026-04-25.md、AGENTS.md。

SpacetimeDB 表结构变更不能按 PostgreSQL 迁移直觉处理

• 现象：发布时 schema 冲突、自动迁移拒绝、旧客户端调用 reducer 失败、private 表数据迁移遗漏。
• 原因：SpacetimeDB 对字段删除、类型变化、索引/主键/RLS/reducer 变化有不同自动迁移边界。
• 处理：变更前阅读 SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md；涉及表变化时同步 migration.rs、SPACETIMEDB_TABLE_CATALOG.md 和 bindings；必要时走 JSON 导入导出与分片导入迁移流程。
• 验证：发布前完成 schema 检查、bindings 生成、表目录更新和相关 smoke。
• 关联：docs/technical/SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md、docs/technical/SPACETIMEDB_TABLE_CATALOG.md。

本地 SpacetimeDB replica identity 不匹配

• 现象：本地 standalone 启动时报 mismatched database identity。
• 原因：root-dir / replica 数据残留与当前数据库身份不一致。
• 处理：按本地 replica identity mismatch 文档进行备份、重建和脚本诊断。
• 验证：本地 SpacetimeDB 可正常启动并 publish / 访问。
• 关联：docs/technical/SPACETIMEDB_LOCAL_REPLICA_IDENTITY_MISMATCH_FIX_2026-04-30.md。

Vite SPA fallback 吞掉 API 请求

• 现象：本地请求 /api/profile/* 等接口时返回 HTML，被前端当 JSON 解析报错。
• 原因：Vite 代理缺少对应 /api/* 前缀，API 请求落到 SPA fallback。
• 处理：补齐 Vite 代理，让 API 请求转发到 Rust api-server。
• 验证：请求返回 JSON，相关页面不再出现 HTML parse 错误。
• 关联：docs/technical/PROFILE_MAIN_ROUTE_VITE_PROXY_FIX_2026-05-02.md。

拼图 APIMart 图片生成密钥不能复用 DashScope / ARK key

• 现象：拼图新手引导或拼图创作点击生成后返回 APIMart 图片生成密钥未配置。
• 原因：拼图 gpt-image-2 / nanobanana2 图片生成已按技术方案统一走 APIMart；后端只读取 APIMART_BASE_URL、APIMART_API_KEY、APIMART_IMAGE_REQUEST_TIMEOUT_MS，不会用 DASHSCOPE_API_KEY、LLM_API_KEY 或 ARK_API_KEY 兜底。
• 处理：在本机私密配置 .env.secrets.local 或进程环境中配置真实 APIMART_API_KEY，不要提交到 Git；填入后必须重启 api-server / npm run dev，运行中的进程不会自动加载新 env。
• 验证：不打印密钥内容，只检查 APIMART_API_KEY 非空；重启后触发拼图生成不再返回本地配置缺失的 503。
• 关联：docs/technical/PUZZLE_APIMART_IMAGE_MODEL_ROUTING_2026-05-01.md、.codex/skills/gpt-image-2-apimart/SKILL.md。

Rust 冷编译导致 api-server 健康检查误超时

• 现象：npm run dev:rust 在 Windows 冷编译/链接阶段误判 /healthz 等待超时并杀掉 cargo run。
• 原因：脚本把 SpacetimeDB 与 api-server 等待窗口混在一起，未考虑 Rust 冷编译耗时。
• 处理：按冷编译超时修复文档拆分等待窗口。
• 验证：冷启动时不再误杀仍在编译的 api-server。
• 关联：docs/technical/API_SERVER_DEV_STACK_COLD_BUILD_TIMEOUT_FIX_2026-04-25.md。

server-rs 默认 cargo build 不能等同于构建 SpacetimeDB 模块

• 现象：在 server-rs 下无参数 cargo build 期望同时构建 spacetime-module，导致链接或构建范围误判。
• 原因：workspace default-members 当前只包含 crates/api-server；SpacetimeDB module 有独立构建/发布方式。
• 处理：默认 Rust 构建只覆盖原生 api-server；模块产物继续走 spacetime build / publish / bindings 生成流程。
• 验证：查看 server-rs/Cargo.toml default-members，并按相关 SpacetimeDB 文档执行模块构建。
• 关联：server-rs/Cargo.toml、docs/technical/RUST_WORKSPACE_DEFAULT_BUILD_SCOPE_FIX_2026-04-25.md。

生产发布入口不要沿用旧 Jenkinsfile / 一体化脚本

• 现象：部署、回滚或 Jenkins Job 重建时参考旧发布文档，导致 systemd、Nginx、SpacetimeDB 自托管和生产包拆分不一致。
• 原因：旧 Jenkins / 旧本地远端部署脚本文档仍作为历史经验保留。
• 处理：生产相关操作先看 PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md，再按需追溯旧文档。
• 验证：发布链路使用当前 deploy/systemd、deploy/nginx、scripts/deploy 和 jenkins/Jenkinsfile.production-*。
• 关联：docs/technical/PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md。

个人任务 scope 不得扩成 work/site/module

• 现象：个人任务配置为 work / site / module 后进度串桶或静默按 0 处理。
• 原因：首版个人任务只支持用户维度，非 user scope 会造成任务进度读取语义错误。
• 处理：Admin 任务配置页不展示范围选择，保存时固定 scopeKind: 'user'；API 和领域构造层拒绝非 User。
• 验证：非 user scope 返回错误；相关测试覆盖 Site / Module / Work 被拒绝。
• 关联：docs/technical/RUNTIME_PROFILE_TASK_SCOPE_2026-05-04.md、docs/technical/ANALYTICS_DATE_DIMENSION_IMPLEMENTATION_2026-05-04.md。