# 开发工作流

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

## 标准任务流程

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

## 建议启动方式

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

```bash
cd /path/to/Genarrative
hermes
```

在本机当前常见路径为：

```bash
/home/dsk/workspace/Genarrative
```

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

## 开发前检查清单

- [ ] 当前分支是否正确
- [ ] 是否已拉取最新代码
- [ ] 是否阅读 `AGENTS.md`
- [ ] 复杂任务是否阅读 `docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md`
- [ ] 是否阅读 `docs/project-memory/shared-memory/` 相关文件
- [ ] 是否阅读 `README.md` 中的运行和检查命令
- [ ] 是否阅读 `docs/README.md` 及任务相关分类 README
- [ ] 是否存在足够具体的 PRD / 设计 / 技术文档
- [ ] 是否明确测试、验收和文档更新方式

## 本地运行命令

安装依赖：

```bash
npm install
```

完整联调开发环境：

```bash
npm run dev
```

AI 游戏创作独立客户端常用短命令：

```bash
npm run agc
```

开发侧需要无 UI 验收某个单 Agent 的完整 Runtime 时使用：

```bash
npm run ai-game-creator-shell:agent-task -- --config-dir /absolute/app-data --init /absolute/project code-prototype "修复失败测试并完成验证"
```

省略 `--init` 时项目必须已经由客户端初始化。所有 Runtime 写命令都必须显式传入项目外 `--config-dir` 并投递给独立 Runner；`--runner-status` 和 Agent 状态查询只读取已有配置与 endpoint，不得创建 AppData、修改权限或为了查询启动 Runner。遇到权限确认会返回非零并保留待确认动作，继续操作应回到开发窗口，不能用 CLI 静默绕过。

### AI 游戏创作 Runtime V1.2 定向复验

`command.exec` 动作必须保留固定程序和逐项 argv，不得把参数拼成 shell 字符串。例如，定向执行当前仓库的受控命令测试时，action 形状为：

```json
{
  "program": "cargo",
  "args": ["test", "project_command_"],
  "cwd": "apps/ai-game-creator-shell/src-tauri",
  "timeoutSeconds": 120
}
```

该 action 仍需开发窗口精确确认；不能用 CLI 或项目策略把 `command.exec` 默认改为 `auto`。实现或调整 Runtime V1.2 后，从仓库根目录优先运行以下定向命令：

只有 `cargo check/test/clippy/fmt/build`、`npm test`、规范命名的 npm 验证脚本和精确 `node --test` 可以形成验证凭证；`git`、`rg`、`cargo metadata` 与普通 `npm run` 即使成功也只是诊断结果，最后仍需执行验证型命令。

```bash
cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml project_command_
cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml config_file_overrides_defaults_without_env
cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml llm_reasoning_effort_supports_provider_default_and_explicit_levels
npm run test -- packages/shared/src/contracts/gameCreationApp.test.ts
npm run ai-game-creator-shell:typecheck
```

第一条覆盖固定程序 / argv 拒绝规则、输出清洗、超时和源码改写检测；第二条覆盖全局 / per-Agent 配置继承，第三条覆盖 `default / low / medium / high` 到 Provider 请求的映射；后两条覆盖共享 `confirm` 契约、配置结构和发布默认 `high`。模块级定向验证通过后，再按改动范围运行 `npm run ai-game-creator-shell:check`、`npm run check:encoding` 和 `git diff --check`。

### AI 游戏创作 Swarm 显式重试真实复验

正常 `supervisor-swarm` 全部 completed 不能替代真实 retry 证据。修改 Runtime 显式重试、Provider lifecycle、隔离 AppData 或 Swarm 验收器后，先跑代理夹具和静态门禁，再运行独立真实 suite：

```bash
npm run test -- apps/ai-game-creator-shell/tests/llmTransientFaultProxy.test.ts
npm run ai-game-creator-shell:typecheck
npm run ai-game-creator-shell:agent-runtime:supervisor-swarm-transient-retry-real-e2e -- --config-dir <AppData>
```

真实 PASS 必须恰好包含 1 个 failed lifecycle、1 条 retry audit 和 1 个 `-transient-1` 后继 identity；forwarding gate 放行前 action、receipt、目标 Agent 子委派、claim、assistant、pending、project revision 与 upstream forwarding 全为 0。放行后仍须完成双专业 Agent 重叠、唯一 repair、Runner 强杀恢复、唯一 Supervisor assistant 和零重复/残留/泄漏。suite 只能读正式 AppData，在其同级目录写入 sentinel 管理的 `0600` 私有副本和 overlay；启动 CLI/Runner 时须把 loopback 合并进大小写两套 no-proxy 环境，防止系统 HTTP 代理绕过本地故障门禁；source-dir guard 必须证明本 suite 前缀未进入源目录，源配置和 endpoint 身份保持不变，报告不得保存 Provider URL、headers、正文、凭据或绝对配置路径。若后续 repair/恢复/终局失败，partial report 仍应保留已经取得的 retry checkpoint。

### AI 游戏创作自主 Swarm 终端复验

修改 Supervisor 自主编排、`agent.message`、static delivery/claim/repair、Swarm CLI `turn.report`、Runner 恢复或 autonomous harness 后，先跑确定性收敛门禁，再运行真实终端 suite：

```bash
cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml background_agent_runtime_bounds_duplicate_agent_message_livelock -- --nocapture
cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml agent_runtime_context_window_ -- --nocapture
cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml project_supervisor_ -- --nocapture
cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml swarm_cli::tests:: -- --nocapture
npm run ai-game-creator-shell:agent-runtime:supervisor-swarm-autonomous-chat-real-e2e -- --config-dir <AppData>
```

业务任务和一次性仓库规则不得出现 Agent ID、数量、并行/同轮、工具、repair 次数、run/action/delegation 或 Runner 配方。PASS 必须由真实发布二进制的 `--swarm-chat` 自主形成至少两个不同专业 Agent 的同批委派和真实 Provider 重叠，在 acceptance criteria 不满足时只形成一个继承原合同的 repair；repair 确认边界执行 Runner 强杀后仍保持父 Session/run、delivery、claim、pending action 和 Provider started 身份。父 run 的 `project.verify` 是允许的宿主验证，其它意外父 pending action继续失败关闭。

终局必须同时得到 `turn.report=settled`、新增 Supervisor assistant 恰好 1、专业 assistant 只在内部 Session、队列/确认/用户输入/reconciliation/sidecar 全 0，以及重复 action/delivery/message/receipt/Provider lifecycle 和正文/凭据/绝对路径泄漏全 0。`agent.message` 完整回归还要证明同语义消息只写一次、后续 no-op 不刷新进展、6 轮后保持未完成计划并诚实 `budget-exhausted`。隔离 AppData 必须位于正式 AppData 同级并自动清理；失败尝试与后续 PASS 不能拼接，`maxRetries=0` 下的真实外部 Provider 失败应单独保留为失败证据。

### AI 游戏创作静态与隔离混合 Swarm 复验

修改 static delivery/claim、isolated group/result/all-join、父 waiting phase、`agent.run_status` 混合认领、Supervisor 混合协作策略、Runner 恢复或 finalization blocker 后，先运行三条确定性回归，再运行独立真实终端 suite：

```bash
cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml project_supervisor_mixed_ -- --nocapture --test-threads=1
npm run agc:mixed-swarm-e2e -- --config-dir <AppData>
```

业务任务只写正式交付、临时检查和验证等结果范围，不写 Agent ID、数量、并行方式、具体工具或 Runner 操作。真实 suite 必须以单个独立 run 证明两类 Provider 真重叠、两类 durable 记录绑定同一父 Session/run、认领 observation 早于唯一父 finalization、Runner 恢复身份稳定、isolated 实际零 mutation、唯一用户回复、零重复/残留/泄漏并完成 sentinel 清理；不能把 isolated 的 suite 零写入要求解释成生产权限层面的只读沙箱。命令未运行、退出非零或报告字段不完整时不得标记 PASS，也不得把失败轮和后续成功轮拼接。

### AI 游戏创作 Runtime V1.10 持久进程定向复验

V1.10 的 PTY 只通过四个 Runner-owned 工具开放；不要把 V1.2 `command.exec` 改成长驻入口。最小工具输入保持结构化：

```json
{"tool":"command.start","input":{"program":"npm","args":["run","dev"],"cwd":".","timeoutSeconds":300}}
{"tool":"command.poll","input":{"processId":"proc-...","cursor":"v1:proc-...:0","maxChars":8000,"waitMs":1000}}
{"tool":"command.stdin","input":{"processId":"proc-...","data":"q","appendNewline":true,"eof":false}}
{"tool":"command.terminate","input":{"processId":"proc-...","cursor":"v1:proc-...:254"}}
```

定向复验按以下顺序取证：

1. 用 Runner-owned PTY fixture 覆盖 start、增量 poll、stdin、自然退出和 terminate；确认 `processId` 绑定完整 owning project / Agent / task / session / run / start action / Runner boot，而不是 OS PID。
2. 让发起 App / CLI 在 start 后退出，确认 Runner 仍持有会话；随后分别在 launch、running、stdin 和 graceful / force 终止窗口强杀 Runner，确认恢复只进入 reconciliation，不增加 fixture launch / stdin 次数，也不按 PID 重连。
3. terminate 必须携带最后一次 poll 的 `nextCursor`，返回同一 cursor 且不消费输出；活会话和 unresolved reconciliation 期间尝试 finalization 与 `runner.shutdown_if_idle`，必须分别被完成门禁和 busy 状态阻断；终止成功必须同时满足 child terminal、同组残留清理、wait / reap 和 PTY drain。
4. 使用不同静态 Agent、动态 sibling、run 和项目重放同一 `processId`，全部必须失败关闭。扫描 task、event、Agent DB、receipt、action history、activity/output、UI snapshot 和报告，PTY 输出正文命中数必须为 0，stdin 只能出现 `bytesWritten / contentSha256 / stdinOpen / eof`。
5. Linux 用忽略 SIGHUP 的 npm / Node fixture 验证 Runner 强杀后 owner watchdog 回收同一前台进程组；Windows 验证 kill-on-close Job Object。仍要明确 PTY、固定 argv、隔离环境和两阶段终止不是容器或 OS sandbox，主动 `setsid` / 外部 service 仍不在完整隔离承诺内。

实现用例统一使用可检索的 `process_session_` 前缀。先运行定向 Rust 用例，再跑 Tauri 全量和真实 Provider：

```bash
cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml process_session_ -- --nocapture
cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml
npm run ai-game-creator-shell:agent-runtime:real-e2e -- --config-dir <AppData> --suite process-session
npm run ai-game-creator-shell:agent-runtime:real-e2e -- --config-dir <AppData> --suite process-session-runner-kill
```

定向命令必须实际匹配到 V1.10 用例，`0 tests` 不算通过。真实 Provider fixture 不得把工具顺序、processId、readiness 文本所在 chunk 或 OS PID 写进任务提示；验收器只按持久 action identity、fixture 计数、私有输出和公共泄漏扫描判定。三项门禁实际通过后才能把日期、Provider、数量和 PASS 结果写入技术方案或 decision log；未运行或被外部配置阻断时只记录 `BLOCKED` / 未验收事实。

`npm run agc` 会启动 Tauri 开发客户端；其 `beforeDevCommand` 通过 `npm run agc:serve` 先完成壳 typecheck，再启动或复用配套 SpacetimeDB、`api-server` 和固定 `127.0.0.1:3080` Vite。只需要浏览器预览同一客户端时可用 `npm run agc:serve`；只启动配套后端和数据库时可用 `npm run agc:backend -- --database <name>`。

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`。

## 常用检查命令

Rust 格式检查：

```bash
npm run check:rustfmt
```

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

```bash
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`；后台、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: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，运行时开发域名回退生产域名只作为异常兜底。

内容检查：

```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、Agent 执行准则或 docs/project-memory/shared-memory 约定；
2. 是否需要补充 docs；
3. 是否有长期知识需要写入 docs/project-memory/shared-memory；
4. 建议的测试命令和提交信息。
```

## AI 游戏创作 App 命令沙箱验证

- Linux `command.exec / command.start / project.verify` 必须经过受信任系统 bubblewrap；缺失或 namespace / mount preflight 失败时工具失败关闭，不能回退宿主执行。
- 修改命令执行、PTY、项目验证或发布配置后，至少运行 `GENARRATIVE_COMMAND_SANDBOX_REAL_TEST=1 cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml command_sandbox -- --nocapture --test-threads=1`、`cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml command_exec` 和 `cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml process_session -- --test-threads=1`。
- 真实门禁必须同时证明项目内 Cargo / npm / Git 成功，项目外普通文件读写失败，`.git / .agent / .agents / .codex / .hermes` 写入失败，网络默认不可达，shell / PTY 后代在 `setsid + chdir` 后仍继承相同边界；process record、poll / stdin / terminate 和 project.verify 审计必须断言 `bubblewrap / workspace-write / disabled / workspace-v1`。另测 `RUSTUP_HOME=$HOME` 与 `.rustup -> $HOME` 必须在目标执行前失败。Linux deb / rpm 包必须声明 `bubblewrap` 依赖；AppImage 发布说明必须要求宿主预装受支持的 bwrap，缺失时只能返回 sandbox unavailable。