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

开发工作流

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

标准任务流程

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

建议启动方式

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

cd /path/to/Genarrative
hermes

在本机当前常见路径为：

/home/dsk/workspace/Genarrative

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

开发前检查清单

• 当前分支是否正确
• 是否已拉取最新代码
• 是否阅读 AGENTS.md
• 复杂任务是否阅读 docs/【协作规范】Agent工作入口与执行准则-2026-06-22.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。

常用检查命令

Rust 格式检查：

npm run check:rustfmt

仓库通过根目录 rust-toolchain.toml 固定 Rust 1.96.0 和 rustfmt 组件， 并通过 rustfmt.toml 固定 Edition 2024 格式口径。需要修复格式时运行：

cargo fmt --all --manifest-path server-rs/Cargo.toml

• 后端通用用户行为埋点统一通过 record_tracking_event_and_return procedure、SpacetimeRuntimeClient::record_tracking_event(...) 与 api-server tracking 中间件写入 tracking_event / tracking_daily_stat；现役账号、钱包、编辑器、项目、精选素材和公共设置路由按 tracking.rs 的显式静态路由表记录，后台路由默认排除。旧玩法、公开作品和专属运行态路由已经退役，不再维护作品级游玩埋点覆盖。

编码检查：

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 / 模拟 / 伪造等替身痕迹。 反馈页上传凭证在原生壳声明 file.importImage 时必须优先走宿主图片导入；移动壳声明 file.captureImage 时才显示拍摄凭证入口，并把拍摄图片同样转为 File 后复用反馈页原有数量、大小、MIME、data URL 预览和提交 payload 校验。 Expo / Tauri 声明 navigation.openNativePage 时，只用于现役同源 H5 路由的受控导航和宿主上下文续接；微信小程序不再声明该能力。旧儿童动作 Demo、模板工作台、生成页、结果页和运行态不得作为 HostBridge 导航验收入口。 H5 支付链接跳转在原生壳声明 app.openExternalUrl 时必须优先走宿主系统浏览器；原生壳未接真实支付 SDK 前不得声明 payment.request，也不得把外部 H5 支付跳转伪装成原生支付成功。 微信 OAuth 登录授权 URL 在原生壳声明 app.openExternalUrl 时必须优先走宿主系统浏览器；原生壳未接真实登录 SDK 前不得声明 auth.requestLogin，也不得把网页登录跳转伪装成原生登录成功。 现役编辑器与个人中心新增文件导入能力时，继续复用共享 file.importDocument、file.importImage、file.captureImage 和 MIME / 大小门禁，不得把已退役模板的上传 service、玩法 DTO 或页面测试重新纳入原生壳门禁。 视觉小说结果页封面 / 角色 / 场景图片和音乐 / 环境音上传在原生壳声明 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 小程序页面常量、WebView 分享入口、分享目标消息类型、WEB_VIEW_SOURCE_QUERY、微信请求头运行时标记、H5 runtime parser、H5 路由保留字段和 H5 / API base URL 格式，避免页面路由、来源标记、宿主上下文 query 或域名配置在微信壳、H5 HostBridge 与运行时配置之间分叉。旧生成结果订阅授权页和对应 H5 service 不再进入清单。生产 / 开发 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

Gitea CI 与 PR 检查

• 仓库 CI 入口是 .gitea/workflows/project-ci.yml，向 master、codex/ai-game-creator-app 推送和所有 PR 创建、更新时必须运行，也允许手工触发。
• CI 固定拆分为 Repository checks、Frontend tests、Backend tests、Native shell tests 四个 required job；对应 PR context 完整名称是 Project CI / Repository checks (pull_request)、Project CI / Frontend tests (pull_request)、Project CI / Backend tests (pull_request)、Project CI / Native shell tests (pull_request)，首次运行后仍须从 Gitea 最近一周 context 表复核。测试使用独立 job，不能只藏在综合检查 step 中；原生壳验收单独运行以便定位重型构建失败。
• 四个 job 共同覆盖 npm run check，并追加 npm run check:server-rs-ddd、cargo test --locked --workspace --no-fail-fast --manifest-path server-rs/Cargo.toml、cargo check -p api-server --all-targets --manifest-path server-rs/Cargo.toml 和 cargo check -p spacetime-module --manifest-path server-rs/Cargo.toml。后端 runner 安装 ffmpeg，避免视频抽帧测试因工具缺失提前返回。codex/ai-game-creator-app 分支的原生壳入口还必须覆盖 npm run ai-game-creator-shell:check 和 release build smoke。
• checkout 必须使用完整历史。PR 将 base SHA 写入 SPACETIME_SCHEMA_BASE_REF，直接推送 master 使用 before SHA；事件基线不可解析时直接失败。Gitea 检查的是 PR head 而非预合并 commit，workflow 必须拒绝不包含最新 base commit 的过期 PR，分支保护同时保持“PR 过期禁止合并”。
• 普通 PR job 不读取业务 secret，不运行真实 API/SpacetimeDB/OSS/支付/生成/live smoke，也不执行会修改外部状态的维护、迁移、发布或备份命令。
• Gitea 至少升级到 1.26.4 后才能注册执行 PR job 的 runner；ubuntu-latest 标签只映射到固定 digest 的 Ubuntu 24.04 级 Docker/临时隔离镜像，不使用浮动镜像 tag，不映射 host，不向 job 暴露 Docker socket、业务 secret 或不必要内网。runner 能访问 Gitea、GitHub Actions 与 actions/node-versions、nodejs.org、npm、Rust 分发和 crates.io；workflow 的官方 action 固定完整 commit，若内网禁用 GitHub，先在当前 Gitea 镜像对应 commit 并改用绝对 URL。受控镜像优先预装 rustup。Runner 2.0.0 支持 job 级 timeout-minutes，但 runner 全局 3h 仍是所有任务的硬上限；首次运行成功后，master 分支保护必须要求上述四个 job 全部成功。
• genarrative-station 当前使用 Gitea 1.26.4 + 基于 Runner 2.0.0-dind-rootless 的固定 digest 修补镜像：只修复 systempaths=unconfined 的空 slice 被 mergo 丢失，真实 job 必须保持 MaskedPaths=[]、ReadonlyPaths=[]；外层仍非 privileged、无 CAP_SYS_ADMIN，内部 Docker 只监听 Unix socket，docker_host: "-" 阻止 socket 进入 job。job 只在 gitea-actions internal network，通过 /git reverse gateway 访问 Gitea，通过拒绝私网、保留地址和 metadata 的 80/443 proxy 访问公共依赖；直连公网和 Gitea 数据网必须失败。内层 bwrap 所需 namespace/proc 选项只能用于该 rootless DinD，不能放宽宿主 rootful runner。系统依赖步骤在 root job 中不调用 sudo，非 root 时用 sudo -E 保留受控 proxy；Cargo 关闭 HTTP multiplexing 并设置 10 次网络重试，rustup bootstrap/toolchain 安装也按有界次数重试。AI 原生壳 job 把 Node 发行目录与 rustup proxy 安装到 /usr/local 的受信任只读路径，并在测试前执行完整 bwrap canary。宿主 compose helper 必须把 /opt/gitea-stack 挂到同名绝对路径，避免相对 volume 错误落到 /stack 空目录。

后端相关默认验证

后端修改后，按 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
• 移动端视口检查

前端原则：

• 移动端优先，再兼容网页端。
• 页面只展示后端返回的状态，不自行计算结论型业务状态。
• 现役一级入口为 /creation、/project、/profile，桌面侧边栏和移动端底部 dock 都固定显示“创作 / 项目 / 我的”。/creation 只读取图片编辑器项目与 GET /api/editor/showcase/resources，不得重新接入旧模板入口配置、旧作品架或专属运行态。
• 旧创作模板目录和顶层旧业务模块必须持续退出 Vite、TypeScript、ESLint 与 Vitest；旧 /api/creation-entry/config、模板 API、公开作品详情和运行态 API 必须保持未挂载。SpacetimeDB 历史表、迁移白名单与必要兼容类型只作为数据壳保留，不得据此恢复业务逻辑。
• 优先复用现有面板、抽屉、弹窗，不新建独立大系统。
• 不在 UI 中默认写功能说明类文本。
• 弹出独立面板的交互不要实现成在当前面板下方追加内容。

文档更新规则

• 工程修改要同步更新对应文档。
• 如果没有现成文档，新文档统一放入 docs/ 下合适分类。
• docs/project-memory/shared-memory/ 只记录高频、长期、团队共享的摘要和索引，不替代完整 PRD/技术文档。
• 如果 docs/project-memory/shared-memory/ 与代码或 docs/ 冲突，以代码和最新 docs/ 为准，并同步修正共享记忆。

提交前建议让 Agent 执行

涉及现役编辑器、项目、精选素材、账号、钱包、公共设置或本地 dev 栈时，按对应定向测试、类型检查、Rust / SpacetimeDB 门禁、真实浏览器 smoke 与本文件当前命令验收。旧跨玩法回归和单玩法质量门禁只作历史记录，不再作为提交前现役检查入口。

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