zizi-al/games-development-ai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(s3): add runtime backend presearch

Browse Source
This commit is contained in:
zizi 2026-06-05 08:09:47 +08:00
parent 53dd2f031e
commit 5d023c0b3d
2 changed files with 215 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

163
docs/memorys/2026-06-05-S3Task7预研报告.md Normal file
View File

@ -0,0 +1,163 @@
# 2026-06-05 S3 Task7 预研报告
## 结论
S3 Task7 `Write Runtime And Conversion Backend Presearch Note` 已完成文档实现、controller 自测，并通过 fresh review gate：
- spec compliance review：PASS，无 Critical / Important。
- quality review：PASS，无 Critical / Important。
Task7 可以提交。S3 Task0-Task7 均已完成后，下一步不是直接进入 S4/S5 实现，而是先执行 S3 阶段验收 review gate。
## 变更范围
- 新增 `docs/technical-presearch/2026-05-31-minigame-backend-cocos-laya.md`。
- 删除两个 S3 已提交代码中的未使用 import，用于恢复 root `pnpm lint`：
- `packages/shared-contracts/src/game-config.ts`
- `apps/api/src/modules/game-logic/index.ts`
未实现真实 S4 Web runtime、S5 mini-game conversion、feed、deploy、routes、UI、三端 devtool import 或 channel readiness。
## 子代理与 Review Gate
| Role | Agent ID | Result | Blocking findings |
| --- | --- | --- | --- |
| implementer | `019e9318-2fe9-7563-9f28-5224c193f96f` | DONE | 无 |
| spec compliance review | `019e932a-e927-7230-a8b2-c47f079fd5aa` | PASS | 无 Critical / Important |
| quality review | `019e932b-1ae4-70e1-acfb-f0e627958d3f` | PASS | 无 Critical / Important |
子代理没有写 `docs/memorys`，本文件为主代理留痕。
## 文档摘要
Task7 预研文档包含：
- `# Runtime And Mini-game Backend Presearch`
- `## Contract Boundary`
- `## Evaluation Template`
- `## Decision`
合同边界明确：
- Input must be `GameIRArtifact/GameConfig/GameLogicModule/GamePackage`。
- Output must be `MiniGameCodeConversion/MiniGameProject/ConversionReport/DevToolImportEvidence`。
- Web runtime 只能向 `GameLogicModule` 暴露 `RuntimeSdkContract/WebPlatformAdapter`。
- 本报告不能替代 S3 `GameConfig/GameLogicModule` contracts 或 S5 `DevToolImportEvidence.result=passed`。
Evaluation table 覆盖 11 个必需 topic：
- LittleJS loop/runtime
- PixiJS adapter/ticker
- GDevelop export/runtime
- ct-js export/runtime
- WeChat export support
- Douyin export support
- Kuaishou export support
- CI/build feasibility
- License constraints
- Package size risk
- Adapter conformance
文档对缺失事实使用 `unknown`，并为每个 `unknown` 写明 next command / manual check / owner。任何 `unknown` 证据都没有被用于替换 self-owned lightweight runtime/adapter。
## Controller 自测
Task7 review 前已运行并通过：
```bash
test -f docs/technical-presearch/2026-05-31-minigame-backend-cocos-laya.md
pnpm check:s3-scope
git diff --check
rg -n "Finding \\| Evidence \\| Risk \\| Decision|unknown|Default MVP line remains" docs/technical-presearch/2026-05-31-minigame-backend-cocos-laya.md
```
关键输出：
```text
S3 scope check passed.
```
## Final Verification
双 review PASS 后，按 Task7 plan 补跑 root 验证。第一次 `pnpm lint` 暴露两个已提交 S3 文件中的未使用 import：
```text
packages/shared-contracts/src/game-config.ts
'GameIRArtifact' is defined but never used
apps/api/src/modules/game-logic/index.ts
'createHash' is defined but never used
```
主代理只删除上述未使用 import，不改变运行逻辑、合同、测试或 scope gate。
修复后已运行并通过：
```bash
pnpm lint
pnpm typecheck
pnpm test
pnpm check:s3-scope
rg -n "Finding \\| Evidence \\| Risk \\| Decision|unknown|Default MVP line remains" docs/technical-presearch/2026-05-31-minigame-backend-cocos-laya.md
git diff --check
```
关键输出：
```text
pnpm lint: apps/worker, packages/harness-client, packages/shared-contracts, apps/web, apps/api Done
pnpm typecheck: apps/worker, packages/harness-client, packages/shared-contracts, apps/web, apps/api Done
pnpm test: Test Files 34 passed; Tests 289 passed
S3 scope check passed.
```
`pnpm test` 仍输出既有 `pg@9` deprecation warning，退出码为 0。
## Review Evidence
Spec reviewer 确认：
```text
标题和结构符合。
Contract Boundary 与 Task7 plan 一致。
S3 边界未被替代。
Evaluation table 列完整，11 个必需 topic 均存在。
每个含 unknown 的行都带 next command/manual check 和 owner，且没有用 unknown 支撑替换 self-owned runtime/adapter。
Decision 保持计划原句。
未发现越界实现或宣称替代 S4/S5 gate。
```
Quality reviewer 确认：
```text
文档明确合同边界，声明本报告不能替代 S3 合同或 S5 DevToolImportEvidence.result=passed。
unknown 规则清楚，每个未验证项都有下一步和 owner。
Pixi/Cocos 仅作为窄范围参考，没有过度承诺。
S5 仍必须验证 DevToolImportEvidence.result=passed。
```
## SHA-256
| Path | SHA-256 |
| --- | --- |
| `docs/technical-presearch/2026-05-31-minigame-backend-cocos-laya.md` | `e7f683e7723c91cbc50d9ad7d9bfebdc449412f58fb1f116f5ec14d33f6eb6c7` |
| `docs/superpowers/plans/2026-05-31-mvp-S3-simulation-slice.md` | `cbc7fb2afaab3cf64b578984b9def7ef265a46aa07029b732ac4ecbc2d68b76a` |
| `docs/superpowers/specs/2026-05-31-mvp-S3-simulation-slice-design.md` | `08abff96b9a1a7b7680e71678f5c479edab24467dd10185c0b0b0e29ea7e613e` |
## Git Status Snapshot
写入本文档前 `git status --short --branch`：
```text
## codex/s1-task9-s2-prep...origin/codex/s1-task9-s2-prep [ahead 8]
M apps/api/src/modules/game-logic/index.ts
M packages/shared-contracts/src/game-config.ts
?? docs/technical-presearch/
```
## Residual Notes
- Task7 是技术预研文档，不是 S4/S5 runtime/conversion implementation。
- PixiJS 和 Cocos Creator 只能作为 reference pattern；不能替代 S3 contracts 或 S5 import evidence。
- Kuaishou、LayaAir、LittleJS、GDevelop、ct-js、CI/build、license、package size、adapter conformance 等未验证事实仍必须按文档中的 owner 和 next step 在后续阶段补证。
- S3 全部 task 完成后，进入 S4/S5 前必须先执行 S3 阶段验收 review gate。

52
docs/technical-presearch/2026-05-31-minigame-backend-cocos-laya.md Normal file
View File

@ -0,0 +1,52 @@
# Runtime And Mini-game Backend Presearch
## Contract Boundary
- Input must be GameIRArtifact/GameConfig/GameLogicModule/GamePackage.
- Output must be MiniGameCodeConversion/MiniGameProject/ConversionReport/DevToolImportEvidence.
- Web runtime may expose only RuntimeSdkContract/WebPlatformAdapter to GameLogicModule.
- This report cannot replace S3 GameConfig/GameLogicModule contracts or S5 DevToolImportEvidence.result=passed.
已验证的本地合同边界：
- `packages/shared-contracts/src/runtime-sdk-contract.ts` freezes `RuntimeSdkContractVersion="mvp-s3-runtime-sdk-v1"` and exposes only platform-neutral Canvas/Input/Audio/Network/Storage/Lifecycle/Telemetry DTO methods. It rejects raw canvas/context, DOM events, arbitrary URL/audio paths, unsafe references, and host object leaks.
- `packages/shared-contracts/src/game-logic-module.ts` requires `sourceRef/artifactPath/checksum/exportSignature/runtimeSdkContractVersion/validationReportId/buildGraphId/languageSubset/imports/forbiddenApis/entrypoints`, rejects descriptor self-reported `validationStatus`, and requires controlled relative paths.
- `harness/fixtures/mvp/valid/simulation-game-logic-module-valid.json` and `harness/fixtures/mvp/valid/game-logic-validation-report-valid.json` prove the current valid fixture path: descriptor references `runtimeSdkContractVersion`, `exportSignature`, `artifactPath`, and validator-owned `ValidationReport.result="passed"`.
- `docs/memorys/2026-06-04-S3Task6消费者合同.md` records that S4/S5 mock consumers read through `GameLogicArtifactRepository`, require `ValidationReport.result="passed"`, and reject missing, failed, self-reported, mismatched, absolute, or traversal report/artifact references.
Rules:
- A missing fact must be written as `unknown`, not omitted.
- Every `unknown` must include the next command, manual check, or owner needed to resolve it.
- A row with `unknown` evidence cannot support replacing the self-owned lightweight runtime/adapter.
- Candidate engines or channel builders may provide reference patterns only after they pass the frozen `RuntimeSdkContract` and artifact/report boundary; they cannot become a parallel contract surface.
## Evaluation Template
Each candidate and each channel capability uses this shape:
| Topic | Finding | Evidence | Risk | Decision |
| --- | --- | --- | --- | --- |
| LittleJS loop/runtime | unknown; likely reference-only if later verified | Evidence is `unknown`: GitHub raw and GitHub Pages fetches timed out during this run; `npm view littlejs version license repository.url dist.unpackedSize --json` returned E404. Next command: manually clone or fetch `https://github.com/KilledByAPixel/LittleJS` and inspect engine loop, input, canvas creation, license, and package/build output. Owner: S4 runtime implementer. Local boundary evidence: `docs/superpowers/specs/2026-05-31-mvp-S3-simulation-slice-design.md` says LittleJS can be referenced for fixed tick/RAF/canvas fallback/context-lost handling but cannot be copied with `document/window` creation or global input dependencies. | DOM/global coupling risk; unverified license and package output cannot support replacement. | defer; may borrow loop pattern only after source/license/package evidence is verified and conformance passes. |
| PixiJS adapter/ticker | useful as S4 renderer/ticker reference; not useful as GameLogicModule API | Official docs: `https://pixijs.com/8.x/guides/components/application` says Application abstracts renderer setup and ticker updates, but example appends `app.canvas` to `document.body`; `https://pixijs.com/8.x/guides/components/ticker` says Ticker runs callbacks on every animation frame and supports start/stop/FPS limits. Package metadata command `npm view pixi.js version license repository.url dist.unpackedSize --json` returned version `8.19.0`, license `MIT`, repository `git+https://github.com/pixijs/pixijs.git`, unpacked size `72415382`. Local boundary evidence: `RuntimeSdkContract.Canvas` accepts opaque handles and render commands, not raw renderer/canvas/context. | renderer coupling risk; direct Pixi exposure would leak canvas/DOM/renderer concepts and package size is risky for mini-game main package budgets. | borrow adapter/ticker pattern only inside adapter-owned renderer; do not expose Pixi to GameLogicModule or use it to replace the self-owned runtime line. |
| GDevelop export/runtime | unknown; reference-only if later verified | Evidence is `unknown`: current official HTML5 export docs path `https://wiki.gdevelop.io/gdevelop5/publishing/html5/` returned 404, and `npm view gdevelop version license repository.url dist.unpackedSize --json` returned E404. Next manual check: locate current official GDevelop export/runtime docs and repository license, then export a minimal project and inspect whether output is browser-only or can target mini-game adapters. Owner: S5 converter implementer. Local boundary evidence: S3 spec says GDevelop may be referenced for resource export, manifest, preview, screenshot, and QA gates, but its Web runtime cannot directly become mini-game runtime. | DOM/Web-only runtime risk; export contract and license are not verified in this run. | defer; do not use as runtime or project builder until official docs, license, export artifact shape, and conformance evidence are available. |
| ct-js export/runtime | unknown; reference-only if later verified | Evidence is `unknown`: search did not return a stable official export/runtime page, and `npm view ct-js version license repository.url dist.unpackedSize --json` returned E404. Next manual check: use official ct.js site/repository to export a minimal project, inspect generated manifest/runtime entry, and verify license/package size. Owner: S5 converter implementer. Local boundary evidence: S3 spec says ct-js may be referenced for resource export, manifest, preview, screenshot, and QA gates, but its Web runtime cannot directly become mini-game runtime. | DOM/Web-only runtime risk; generated output and legal status are unverified. | defer; do not use as runtime or project builder until source, export, license, size, and conformance evidence are available. |
| WeChat export support | supported as a Cocos Creator reference; LayaAir status unknown in this run | Cocos official docs `https://docs.cocos.com/creator/3.8/manual/zh/editor/publish/publish-wechatgame.html` say Cocos Creator can publish to WeChat mini-game, generate `wechatgame` with `game.json` and `project.config.json`, adapt WeChat mini-game APIs, invoke WeChat devtools, and manage remote resource/cache/version behavior. Same doc says WeChat mini-game is not equivalent to a browser environment, main package is limited to 4MB, and remote script download is not allowed. Laya evidence is `unknown`: `npm view layaair version license repository.url dist.unpackedSize --json` returned only version `1.0.1` and license `ISC`; no official WeChat publish doc was verified. Next manual check: open current LayaAir official publish docs and build a minimal WeChat project. Owner: S5 converter implementer. | channel package and resource-cache constraints; Cocos editor output cannot bypass GamePackage/ConversionReport/DevToolImportEvidence. Laya support is unverified. | defer with next step; borrow WeChat template/cache/lifecycle ideas, but keep MVP on static mini-game project builder until actual S5 import evidence passes. |
| Douyin export support | supported as a Cocos Creator reference; LayaAir status unknown in this run | Cocos official docs `https://docs.cocos.com/creator/3.8/manual/zh/editor/publish/publish-bytedance-mini-game.html` say Cocos Creator can publish to Douyin mini-game, generate `bytedance-mini-game` with `game.json` and `project.config.json`, and open the result in Douyin developer tools. The same doc records package constraints: normal package total 20MB, subpackage mode main package 4MB, and remote resources are required beyond the main package limit. Laya evidence is `unknown`: no current official Douyin publish doc was verified. Next manual check: open current LayaAir official publish docs and build a minimal Douyin project. Owner: S5 converter implementer. | channel package limits, devtool version constraints, and remote-resource handling can break reproducible conversion. | defer with next step; borrow Douyin template/package-limit references only, not a replacement runtime/backend. |
| Kuaishou export support | unknown | Evidence is `unknown`: guessed Cocos 3.8 URL `https://docs.cocos.com/creator/3.8/manual/zh/editor/publish/publish-kuaishou-mini-game.html` returned 404, and the Cocos 3.8 publish index `https://docs.cocos.com/creator/3.8/manual/zh/editor/publish/` lists WeChat, Taobao, Douyin, OPPO, Huawei quick game, vivo, and Honor, but not Kuaishou. No current LayaAir official Kuaishou publish doc was verified. Next manual check: query current Cocos/LayaAir release docs and Kuaishou developer docs, then build/import a minimal fixture in Kuaishou devtools. Owner: S5 converter implementer plus channel-integration owner. | concrete Kuaishou coverage gap; assuming support would create false three-channel readiness. | defer with next step; unknown Kuaishou evidence blocks any replacement of the static self-owned project builder. |
| CI/build feasibility | unknown | Evidence is `unknown`: no Cocos Creator or LayaAir CLI/editor was installed or executed in this task; no local/CI fixture generated `MiniGameProject`, `ConversionReport`, or `DevToolImportEvidence`. Next command: in S5, install/use pinned editor tooling outside this S3 doc task, run a minimal fixture build for WeChat/Douyin/Kuaishou, and record exact CLI/devtool commands plus exit codes. Owner: build/release owner. | build reproducibility risk; editor-dependent builds may require GUI, credentials, devtools paths, or platform accounts. | defer with next step; do not adopt external backend until headless or controlled CI build proof exists. |
| License constraints | unknown for full backend choice | Partial evidence: `npm view pixi.js version license repository.url dist.unpackedSize --json` returned `MIT`; `npm view layaair version license repository.url dist.unpackedSize --json` returned license `ISC` but no repository/size fields. Evidence is `unknown` for LittleJS, GDevelop, ct-js, Cocos Creator/editor/runtime distribution, and channel devtools terms in this run. Next manual check: inspect official repository LICENSE files, editor/runtime EULAs, package licenses, and redistribution rules for every candidate/channel tool. Owner: legal/release owner. | legal/release risk; tool/editor license may allow reference use but restrict redistribution, SaaS automation, or generated runtime packaging. | defer with next step; no candidate can replace self-owned runtime/project builder until full license matrix is reviewed. |
| Package size risk | fail for direct Pixi package; unknown for final channel builders | Evidence: `npm view pixi.js ... dist.unpackedSize` returned `72415382`, which is too large to treat as safe for direct mini-game main package use without bundling/tree-shaking measurement. Cocos WeChat docs state WeChat mini-game main package cannot exceed 4MB and remote scripts cannot be downloaded; Cocos Douyin docs state normal package total 20MB and subpackage main package 4MB. Evidence is `unknown` for LittleJS/GDevelop/ct-js/Cocos/Laya final generated package sizes. Next command: build minimal bundles with pinned candidates, run `du -sk` on output and measure compressed/uncompressed main package/subpackage sizes per channel. Owner: S5 converter implementer. | channel budget risk; direct engine inclusion can exceed main package limits or force remote resources/scripts that channels reject. | defer with next step; only borrow patterns until measured package outputs pass channel budgets. |
| Adapter conformance | unknown for all external candidates | Evidence is `unknown`: no LittleJS/Pixi/GDevelop/ct-js/Cocos/Laya adapter was implemented or run through `createRuntimeSdkConformanceSuite`. Local conformance target exists in `packages/shared-contracts/src/runtime-sdk-contract.ts`, and fixtures require `runtimeSdkContractVersion="mvp-s3-runtime-sdk-v1"`. Next command: in S4/S5, create candidate adapter stubs and run `createRuntimeSdkConformanceSuite(adapterFactory)` plus host-object leak cases before any adoption decision. Owner: S4/S5 adapter owner. | API drift risk; renderer/runtime may leak DOM, canvas/context, audio objects, arbitrary URL, storage/global, or lifecycle events into GameLogicModule. | defer with next step; unknown conformance blocks replacement and limits candidates to reference material. |
## Decision
Default MVP line remains self-owned lightweight 2D runtime/adapter and static mini-game project builder until this report proves replacement is safe.
This presearch is not sufficient to replace the S3 contracts or the S5 import gate. The only evidence-backed use today is to borrow narrowly scoped implementation patterns:
- PixiJS: adapter/ticker layering ideas for an adapter-owned renderer only.
- Cocos Creator: WeChat/Douyin package template, remote resource/cache, lifecycle, and devtool workflow references only.
- LittleJS/GDevelop/ct-js/LayaAir/Kuaishou: `unknown` evidence in this run; keep them deferred until the listed owner resolves the next check.
No row with `unknown` evidence supports replacing the self-owned lightweight runtime/adapter. S5 still must produce and verify `DevToolImportEvidence.result=passed` before any channel conversion is considered accepted.