# 开发工作流

更新时间：`2026-08-27`

## 标准流程

```text
确认工作树与目标分支 → 读取入口和当前专题 → 查代码真相 → 小步修改 → 定向验证 → 更新当前文档/记忆 → 检查提交边界
```

跨模块功能、公开契约、SpacetimeDB schema、AGC/Runtime 和复杂 UI 状态链路在“小步修改”前增加 SDD 门禁：

```text
调研与定界 → 更新主规范 → 拆分并评审里程碑规范 → 为单个里程碑写实现计划 → 实现 → 对照规范验证与验收 → 合并主规范并清理临时计划
```

完整规则和模板见 [`docs/【协作规范】规范驱动开发工作流-2026-09-12.md`](../../【协作规范】规范驱动开发工作流-2026-09-12.md)。小型局部修改仍直接使用下方轻量流程；执行中若触及公开行为，立即升级到 SDD。

任务开始时先写清一句话交付结果、验收判据和不做项，再按“必须项 / 风险项 / 可选项”排序。先完成修改、定向验证和边界检查组成的最小闭环；设置时间盒和检查点，新增发现只有在影响交付判据时才扩大范围，否则记录为后续事项。不要让工具探测、历史整理或验证便利自行改变任务目标。

## 开始前

- 运行 `git status --short`，保留用户已有的未提交修改；不要在共享工作树中使用破坏性 Git 命令。
- 复杂任务先读 `AGENTS.md`、`docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md`、`docs/README.md` 和对应专题。
- 需要完整 SDD 的任务先确认主规范位置和验收证据，再创建 `docs/project-memory/plans/` 下的里程碑规范与实现计划；计划完成、取消或合并后删除。
- 后端事实以 `server-rs/crates/api-server/src/app.rs`、`server-rs/crates/api-server/src/modules.rs`、Cargo manifest、SpacetimeDB schema 和源码为准；现役 API 不从未挂载模块推导。
- External v1 以 `docs/openapi/genarrative-external-v1.openapi.json` 与 `modules/external_api.rs` 为准。
- 本地端口的默认值只用于启动配置；实际运行端口以 `.app/dev-stack.json` 和启动日志为准。
- 任务涉及 SpacetimeDB schema 时，先读 `docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md` 与现有 schema 检查脚本，不依赖仓库中已不存在的旧表目录或基线文件。

## 修改边界

- 后端路线固定为 `server-rs + Axum + SpacetimeDB`，访问 SpacetimeDB 统一经 `spacetime-client` facade。
- `module-*` 放领域规则，`spacetime-module` 放表和事务，`api-server` 放 HTTP/SSE/BFF，`platform-*` 放外部副作用，`shared-contracts` 放 DTO 与公开契约。
- 前端不承接正式业务真相；页面状态必须来自后端投影、API 或持久化合同。
- 旧模板、旧公开作品、旧运行态、旧 Node/Express/PostgreSQL/Go/maincloud 路线和人工 `spacetime --root-dir` 命令不作为新实现目标。
- 已退役对象没有现役 caller、公开契约、持久化迁移或活跃实例时，不添加兼容代码、兼容测试、墓碑注释或墓碑文档。
- 修改中文文件优先局部补丁，保持 UTF-8；不把中文文案替换成英文。

## 文档维护

- 当前稳定合同进入 `docs/`；长期决策、通用流程、排障经验进入 `shared-memory/`。
- 文档现行、历史、待复核、开放事项和活动计划的分类以 [`docs/【协作规范】文档生命周期与现状索引-2026-09-12.md`](../../【协作规范】文档生命周期与现状索引-2026-09-12.md) 为准；`historical` 和 `review` 文件开头保留状态头，不能直接作为实现依据。
- `plans/` 只保存正在执行且有明确下一门禁的计划；`todos/` 只保存真实开放且有关闭条件的事项。完成或作废后删除或融合。
- 不把分支名、一次性测试轮次、提交流水账和个人路径写成长期规则。
- H5 HostBridge 真实调用链的临时替身词扫描必须覆盖生产调用链；宿主壳真实能力以现行 HostBridge 协议与代码为准。

## 验证路由

AGC 测试构造单 HTML 项目时，必须在初始化之前写入 HTML，避免自动建立 npm 工程；npm 预览和导出测试应提供 dist 产物。已有图片生成 pending/operation 属于持久化恢复合同，修改工具默认参数后仍须验证旧动作恢复不重复提交、不因默认值变化被误判为新意图。

SpacetimeDB 任务统一先读取 `.codex/skills/genarrative-spacetimedb/SKILL.md`；该项目适配层按需调用已安装的官方 `spacetimedb` 插件 skill，插件提供通用 SDK/CLI/MCP 知识，项目 skill 负责 Genarrative 架构边界和验证门禁。

按改动范围选择定向门禁，不以无关全量扫描代替契约验证：

| 范围                | 至少运行                                                                                                                           |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| 文档 / 中文文本     | `npm run check:doc-index`、`npm run check:encoding`、`git diff --check`                                                            |
| 前端                | 相关 Vitest、类型检查；需要时做桌面/移动视口 smoke                                                                                 |
| Rust 后端           | 对应 crate 的 `cargo test` / `cargo check`、`/healthz` smoke                                                                       |
| External v1         | OpenAPI 解析、实现/DTO 契约测试和鉴权 smoke                                                                                        |
| SpacetimeDB schema  | `npm run spacetime:generate`、`npm run check:spacetime-schema`、运行时访问检查                                                     |
| AGC / DirectProject | 使用 `docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md` 中的当前定向门禁；真实 Provider/登录缺失必须记为未验证 |
| 生产发布            | 当前开发运维文档、脚本门禁、主机进程、备份和公开端点证据                                                                           |

只有 `cargo check/test/clippy/fmt/build`、`npm test`、规范命名的 npm 验证脚本和精确 `node --test` 形成验证凭证；`git`、`rg`、`cargo metadata` 和普通 `npm run` 只作为诊断。

## 提交前

1. 查看 staged diff 和 `git diff --check`。
2. 确认没有密钥、`.env`、Cookie、日志、缓存、数据库 dump、构建产物或个人路径。
3. 确认相关当前文档与共享记忆已同步，且 docs 入口没有指向已删除或退役实现依据。
4. 提交标题使用中文，标题后逐行写明本次变更。

## Gitea CI 依赖闭合

`.gitea/workflows/project-ci.yml` 的客户端门禁拆成四个 job，每个 job 只预热自己会构建的那几份依赖：`AI game creator shell Rust tests` 只预取 AGC 壳 manifest（AGC 壳那份 `Cargo.lock` 的 path 依赖已含 `platform-llm`、`platform-agent`、`agent-runtime-core` 与 `shared-contracts`；`agent-run` smoke 会用 `src-tauri/Cargo.toml` spawn `cargo run`，因此必须同 job），`AI game creator shell Rust crates` 预取 `server-rs/Cargo.toml` 与两个独立 crate，`Native shell tests` 预取桌面壳与 AGC 壳 manifest，`AI game creator shell web tests` 不触碰 Cargo，不预热。前两个 job 只用 cargo 与 node 内建模块，因此不执行 `npm ci`。两个被 `server-rs/Cargo.toml` 排除、且没有提交 `Cargo.lock` 的独立 crate（`agent-runtime-core`、`agent-runtime-orchestration`）只能在 `AI game creator shell Rust crates` 里用不带锁标志的 fetch。AGC 壳的 bin target 单测（约 2466 条）由 `apps/ai-game-creator-shell/scripts/run-rust-shell-test-shards.mjs` 编译一次后按 `--list` 名单分 4 片、每片一个进程并行跑，片内保持 `--test-threads=1` 并各自使用独立 `TMPDIR`：当年 libtest 线程并行会互相干扰的是进程内后台锁与异步终态，进程分片不共享这些状态，因此可以并行而无需放宽断言。Backend host workspace tests 使用 `cargo test --locked --workspace --exclude spacetime-module --no-fail-fast`，避免 `spacetime-module` 的 `spacetime-types` feature 统一污染普通领域 crate 的 host 测试；随后单独执行 `cargo test --locked -p spacetime-module --no-fail-fast`，由 `spacetime-module/src/active.rs` 在 host 测试构建期间提供仅测试期的 SpacetimeDB ABI 链接支持，使该 crate 的纯单元测试也纳入 Backend 门禁。`spacetime-module` 的 reducer / procedure 运行时行为仍必须通过真实 SpacetimeDB runtime/integration harness 验证，host 链接支持不得被当作运行时替身。Backend 另外执行 `cargo check --locked -p spacetime-module` 验证模块源码。AGC 壳检查还会运行 `platform-llm` 与 `shared-contracts` 的 server-rs workspace 测试，这些命令以及 AGC 壳测试必须带 `--locked`，避免在测试阶段重新解析 registry index；锁文件发生变化时应先更新受信任 CI 镜像缓存，再重跑门禁。