kdletters
2566ae705f
上一轮把 2466 条 bin target 单测切成 4 片放在同一个 job 内多进程并行，run 2102 证明这条路 不通：门禁步骤跑满 18 分钟仍未结束，比整套串行的 507 秒还慢——同一容器内这几片共享 HOME、target 目录与固定临时路径，会互相拖慢。这一轮改成按 job 拆分。 - run-rust-shell-test-shards.mjs 新增 --shard-index=<i>：只跑第 i 片，供 CI 的每个分片 job 使用；覆盖自校验（片并集等于 --list 全集且互斥）仍针对全集执行，所以每个 job 都会 发现分片规则改动，不会被"只跑一片"绕过。负例 --shard-index 超出 --shards 立即失败。 不传 --shard-index 时行为不变（一条命令把 N 片放进程里并行），留给本地全量自测。 - project-ci.yml 由 7 个 job 变 11 个：原 AGC Rust job 拆成 AI game creator shell Rust shard 1/4 ~ 4/4 与 AI game creator shell Rust smoke，加上已有的 Rust crates，AGC 相关 门禁共 6 个 job。4 个片 job 只预热 AGC 壳自己那份锁定依赖，且与 smoke、crates 一样都是 纯 cargo 门禁，因此这 6 个 job 都不再执行 npm ci（每个省 1~3 分钟）。 - check-native-shells.mjs 分组由五个变十个：agc-rust-shard-1 ~ agc-rust-shard-4 与 agc-rust-smoke 取代 agc-rust-shell；每个分片分组的命令是 `npm run ai-game-creator-shell:check:rust:shell -- --shard-index=<i>`。 - project-ci-workflow.test.ts 相应更新：11 个 job、6 个 job 免 npm ci、10 个分组各被一个 job 恰好调用一次，并新增「每个分片 job 都落到 --shard-index」「4 个 index 各一次」 「分片运行器保留覆盖自校验」等断言。 - 同步运维文档、development-workflow、decision-log、pitfalls 与 gitea-ci-triage 技能到 job 级分片口径，并记录 run 2102 的反面实验，避免以后又改回单 job 内并行。 验证：npx vitest run scripts/project-ci-workflow.test.ts（12 passed）、eslint、prettier、 check:encoding（13330 文件）、check:doc-index、--groups=contract、mobile check-config 全绿； 分片运行器本地以 agent-runtime-core（7 条 → 2/2/2/1）验证 --shard-index 四个 index 各自 只跑一片、片 TMPDIR 隔离、无 index 时全量模式不变。Gitea master 分支保护需补 6 个新 context（共十一个），其中含 4 个分片 job、smoke job 与 crates job。 Co-authored-by: DotCraft <273930855+dotcraft-ai@users.noreply.github.com>
9.5 KiB
开发工作流
更新时间：2026-08-27
标准流程
确认工作树与目标分支 → 读取入口和当前专题 → 查代码真相 → 小步修改 → 定向验证 → 更新当前文档/记忆 → 检查提交边界
跨模块功能、公开契约、SpacetimeDB schema、AGC/Runtime 和复杂 UI 状态链路在“小步修改”前增加 SDD 门禁：
调研与定界 → 更新主规范 → 拆分并评审里程碑规范 → 为单个里程碑写实现计划 → 实现 → 对照规范验证与验收 → 合并主规范并清理临时计划
完整规则和模板见 docs/【协作规范】规范驱动开发工作流-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-clientfacade。 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为准；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 只作为诊断。
提交前
- 查看 staged diff 和
git diff --check。 - 确认没有密钥、
.env、Cookie、日志、缓存、数据库 dump、构建产物或个人路径。 - 确认相关当前文档与共享记忆已同步，且 docs 入口没有指向已删除或退役实现依据。
- 提交标题使用中文，标题后逐行写明本次变更。
Gitea CI 依赖闭合
.gitea/workflows/project-ci.yml 的客户端门禁拆成八个 job，每个 job 只预热自己会构建的那几份依赖：AI game creator shell Rust shard 1/4 到 4/4 各只预取 AGC 壳 manifest 并各跑一片（AGC 壳那份 Cargo.lock 的 path 依赖已含 platform-llm、platform-agent、agent-runtime-core 与 shared-contracts），AI game creator shell Rust smoke 同样只预取 AGC 壳 manifest（agent-run smoke 会用 src-tauri/Cargo.toml spawn cargo run），AI game creator shell Rust crates 预取 server-rs/Cargo.toml 与两个独立 crate，Native shell tests 预取桌面壳与 AGC 壳 manifest，AI game creator shell web tests 不触碰 Cargo，不预热。AGC 壳的 4 个分片 job、smoke job 与 crates 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 片：CI 的每个分片 job 用 --shard-index=<i> 只跑自己那片，片内保持 --test-threads=1 并各自使用独立 TMPDIR，片与片之间靠 job 级并发摊开；本地不传 --shard-index 时仍是同一条命令把 4 片放进程里并行。不要改回「一个 job 内多进程并行这几片」——同一容器里它们会争抢共享 HOME、target 目录与固定临时路径，实测比整套串行还慢。每个分片 job 都会自校验「片并集等于全集且互斥」，因此改分片规则不会静默漏跑。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 镜像缓存，再重跑门禁。