Genarrative/docs/project-memory/shared-memory/development-workflow.md

开发工作流

用途：给本地 Agent 和开发人员提供统一的开发、测试、提交流程。具体命令以 package.json、server-rs/Cargo.toml、AGENTS.md 和相关 docs/ 最新文档为准。

标准任务流程

同步代码 → 读取 AGENTS.md → 读取 docs/project-memory/shared-memory → 查找/完善 docs → 制定计划 → 小步实现 → 本地验证 → 更新文档/记忆 → 提交

建议启动方式

在项目根目录启动本地 Agent：

cd /path/to/Genarrative
hermes

在本机当前常见路径为：

/home/dsk/workspace/Genarrative

其他开发者以自己本地实际路径为准，不要把个人绝对路径写入共享文档作为通用规则。

开发前检查清单

• 当前分支是否正确
• 是否已拉取最新代码
• 是否阅读 AGENTS.md
• 是否阅读 docs/project-memory/shared-memory/ 相关文件
• 是否阅读 README.md 中的运行和检查命令
• 是否阅读 docs/README.md 及任务相关分类 README
• 是否存在足够具体的 PRD / 设计 / 技术文档
• 是否明确测试、验收和文档更新方式

本地运行命令

安装依赖：

npm install

完整联调开发环境：

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。

开启自动刷新：

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：

npm run dev:spacetime

单独启动 Rust API server：

npm run dev:api-server

单独启动前端：

npm run dev:web

单独启动后台管理前端：

npm run dev:admin-web

本地 SSH 服务器管理面板：

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 日志：

npm run dev:spacetime:logs

本机隔离验证外部生成 worker 队列、API-only 更新和 worker 动态扩缩容时，优先使用：

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。

后台管理前端：

npm run admin-web:build
npm run admin-web:typecheck

SpacetimeDB bindings 生成：

npm run spacetime:generate

CodeGraph 本地语义索引：

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 文档索引：

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。

编码检查：

npm run check:encoding

ESLint：

npm run lint:eslint

类型检查：

npm run typecheck

综合 lint：

npm run lint

测试：

npm run test

生产构建：

npm run build

原生壳验收：

npm run check:native-shells

该命令会覆盖 H5 HostBridge 关键测试、微信 / Expo / Tauri 三端桥接层文件结构门禁、完整相对路径文档反查、微信 capability 到真实 WebView / 支付 / 分享页面流程和测试清单的映射门禁、H5 HostBridge 事件订阅双能力门控反查、H5 navigation.canGoBack 消费 hook 与直达二级页返回锚点测试、移动端和桌面端单端源码清单门禁、Expo 壳 typecheck / test / EAS build config smoke / config smoke / Metro export smoke、Tauri 壳 typecheck / cargo test、桌面壳 release --no-bundle 构建烟测，以及可分发壳与 H5 HostBridge 真实调用链的临时替身词扫描，确认 Expo managed config、移动端 EAS 原生包构建 profile、移动端 iOS / Android production bundle、打包 H5 资产、Tauri release 入口、H5 页面内导航保留完整原生宿主上下文和 H5 HostBridge 真实调用链没有漂移；扫描范围包含微信小程序壳生产 .js、Tauri Info.plist、共享 HostBridge 契约、H5 native transport，并自动覆盖已接入真实宿主能力 facade 的 H5 生产调用链文件，但不扫描 Expo export、Tauri target/、Cargo / Metro 缓存或 release 构建产物。移动壳配置检查必须反查 EAS 生产 profile、文本 / 文档 / 图片 / 音频导入边界都来自共享 HostBridge 契约。登录与支付外链跳转必须保持在该调用链扫描内，src/services/authService.ts 和 src/services/payment/paymentRedirect.ts 是必扫文件；AuthGate 的登录成功、退出登录、身份边界刷新和登录状态异常重试都必须通过 app.reloadWebView 优先路径，并由 src/components/auth/AuthGate.test.tsx 进入该门禁。壳源码和配置继续严格禁止 mock / fake / placeholder / stub / TODO / FIXME / 占位 / 模拟 / 伪造 / 未实现 / 临时；H5 业务调用链允许正常表单 placeholder 属性、业务占位图文案和真实兼容 / 故障语义中的“未实现”“临时”表述，但仍禁止 mock / fake / stub / TODO / FIXME / 模拟 / 伪造等替身痕迹。 创作 Agent 原生壳文档导入优先走 file.importDocument，旧壳只声明 file.importText 时才回退文本导入；相关变更必须让根级和单端门禁覆盖共享 method、capability profile、文档 MIME / 5 MiB 上限、读取前 size 校验，以及 H5 base64 转 File 后继续走后端文档解析的链路。 创作 Agent 参考图上传在原生壳声明 file.importImage 时必须优先走宿主图片导入，并把 H5 base64 转 File 后继续交给既有 onReferenceImageChange 校验链路；用户取消原生选择不应再连带弹出浏览器文件输入，普通浏览器、小程序和未声明能力的裁剪壳才使用原隐藏文件输入。 创作 Agent 轻输入 composer 的参考图按钮在原生壳声明 file.importImage 时必须优先走宿主图片导入；移动壳声明 file.captureImage 时才显示拍摄参考图入口，并把宿主图片同样转为 File 后复用 readPuzzleReferenceImageAsDataUrl 的类型、大小、压缩和预览链路。 反馈页上传凭证在原生壳声明 file.importImage 时必须优先走宿主图片导入；移动壳声明 file.captureImage 时才显示拍摄凭证入口，并把拍摄图片同样转为 File 后复用反馈页原有数量、大小、MIME、data URL 预览和提交 payload 校验。 固定内置 H5 体验入口在原生壳声明 navigation.openNativePage 时必须优先走 navigateHostNativePage()；例如儿童动作热身 Demo 从平台首页进入 /child-motion-demo 时应由 HostBridge 发出 navigation.openNativePage，宿主不可用时才回退浏览器跳转。 H5 支付链接跳转在原生壳声明 app.openExternalUrl 时必须优先走宿主系统浏览器；原生壳未接真实支付 SDK 前不得声明 payment.request，也不得把外部 H5 支付跳转伪装成原生支付成功。 微信 OAuth 登录授权 URL 在原生壳声明 app.openExternalUrl 时必须优先走宿主系统浏览器；原生壳未接真实登录 SDK 前不得声明 auth.requestLogin，也不得把网页登录跳转伪装成原生登录成功。 汪汪声浪结果页玩家 / 对手 / UI 背景三图槽位上传在原生壳声明 file.importImage 时必须优先走宿主图片导入，并把 H5 base64 转 File 后继续交给 uploadBarkBattleAsset 与当前槽位写回链路；用户取消原生选择不应再连带弹出浏览器文件输入，普通浏览器、小程序和未声明能力的裁剪壳才使用原隐藏文件输入。 抓大鹅结果页发布封面图和封面参考图上传在原生壳声明 file.importImage 时必须优先走宿主图片导入，并把 H5 base64 转 File 后复用现有封面 data URL 读取、AI 重绘开关、参考图集合和封面生成 payload 链路；用户取消原生选择不应再连带弹出浏览器文件输入。 RPG 角色资产工作室的角色参考图上传在原生壳声明 file.importImage 时必须优先走宿主图片导入，并把 H5 base64 转 File 后复用现有 readFileAsDataUrl 参考图集合和角色形象生成 payload 链路；用户取消原生选择不应再连带弹出浏览器文件输入。 RPG 作品封面上传在原生壳声明 file.importImage 时必须优先走宿主图片导入，并把 H5 base64 转 File 后复用现有 10 MiB 校验、图片尺寸读取、16:9 裁剪和 uploadCustomWorldCoverImage 保存链路；用户取消原生选择不应再连带弹出浏览器文件输入。 RPG 作品封面参考图上传在原生壳声明 file.importImage 时必须优先走宿主图片导入，并把 H5 base64 转 File 后复用现有 readImageFileAsDataUrl 读取、预览和 generateCustomWorldCoverImage payload 链路；用户取消原生选择不应再连带弹出浏览器文件输入。 RPG 场景图片参考图上传在原生壳声明 file.importImage 时必须优先走宿主图片导入，并把 H5 base64 转 File 后复用现有 readImageFileAsDataUrl 读取、预览和 rpgCreationAssetClient.generateSceneImage payload 链路；用户取消原生选择不应再连带弹出浏览器文件输入。 视觉小说结果页封面 / 角色 / 场景图片和音乐 / 环境音上传在原生壳声明 file.importImage / file.importAudio 时必须优先走宿主受控导入，并把 H5 base64 转 File 后继续交给 uploadVisualNovelAsset 与当前素材字段写回链路；用户取消原生选择不应再连带弹出浏览器文件输入，历史素材选择和 AI 图片生成保持原链路。 该命令会反查微信小程序 WECHAT_HOST_CAPABILITIES 与共享 HOST_BRIDGE_WECHAT_MINI_PROGRAM_CAPABILITIES 一致；小程序生产代码继续保留 CommonJS 运行时镜像，不直接 import TypeScript shared 包。 该命令同时会运行微信小程序 miniprogram/host-bridge/、miniprogram/shell/、pages/web-view 样式和 scripts/miniprogram-web-view-auth.test.ts 的壳层测试，保证微信桥接层拆分后的支付、订阅消息、九宫切图、分享目标和 WebView 登录 / 分享入口行为与 Expo、Tauri 壳一起验收。 该命令还会反查微信小程序 app.json.pages 与 host-bridge/protocol.js 页面 URL、H5 小程序页面常量、H5 订阅授权页面常量、WebView 分享入口、分享目标消息类型、WEB_VIEW_SOURCE_QUERY、微信请求头运行时标记、H5 runtime parser、H5 路由保留字段和 H5 / API base URL 格式，避免页面路由、来源标记、宿主上下文 query 或域名配置在微信壳、H5 HostBridge 与运行时配置之间分叉。生产 / 开发 H5 与 API 域名都必须显式配置为纯 HTTPS domain，运行时开发域名回退生产域名只作为异常兜底。

内容检查：

npm run check:data
npm run check:overrides
npm run check:smoke
npm run check:content

全量检查：

npm run check

DDD 边界检查：

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 和对应单项门禁文档执行自动脚本与体验检查。

请检查当前 git diff，指出：
1. 是否违反 AGENTS.md 或 docs/project-memory/shared-memory 约定；
2. 是否需要补充 docs；
3. 是否有长期知识需要写入 docs/project-memory/shared-memory；
4. 建议的测试命令和提交信息。