2026-06-05 S4 Task2 包构建器

结论

S4 Task2 Implement Web Package Builder 已完成实现、controller 自测，并在一轮 quality finding 修复后通过 fresh review gate：

spec compliance review：首轮 PASS，二轮 PASS。
quality review：首轮 FAIL，二轮 PASS。

可以提交 Task2。提交后 S4 可进入 Task3 Implement Runtime SDK, Web Runtime Host, And Web Adapter。S5 可从 Task2 提交点创建独立 worktree 并行启动 Task1，但 S5 不得修改已冻结的 GamePackage、AssetManifest、RuntimeSdkContract、GameLogicModule artifact 合同。

变更范围

apps/api/src/modules/game-package/index.ts
apps/api/src/modules/game-package/game-package.builder.spec.ts

未实现 S4 Task3+ 的 runtime SDK、Web runtime host、preview UI、runtime smoke，也未实现 S5 mini-game conversion、S6 feed、S7 telemetry 或 deploy readiness。

子代理与 Review Gate

Role	Agent ID	Result	Blocking findings
implementer	`019e959a-8527-71e2-8884-f4f02f4e7de2`	DONE	无
spec compliance review	`019e95ad-af45-7a83-a461-be723d0e92c4`	PASS	无 Critical / Important
quality review	`019e95ad-f2c1-7033-822d-2a3a4ec51a99`	FAIL	P1: 测试缺少 runtime SDK version mismatch、sourceHash mismatch、failed report、artifact tamper、source static import full engine/bundle 的 fail-closed 覆盖
fix implementer	`019e95b0-bd7b-7b22-979c-c1ddb1c1fc79`	DONE	仅补测试，未改实现
spec compliance re-review	`019e95ba-ffec-7993-aece-5d00d18cd1f3`	PASS	无 Critical / Important；reviewer 复跑时遇到一次非 Task2 API spec 404，controller 随后复跑通过
quality re-review	`019e95bb-47f8-7d61-94dc-0a3f286ee5db`	PASS	无 Critical / Important

子代理没有写 docs/memorys，本文件为主代理留痕。

实现摘要

新增 GamePackageBuilderService 和 GamePackageBuilderModule。
从 S3 GameLogicArtifactRepository 读取可消费的 GameLogicModule，不接受内存自报的 validation 状态。
builder 输出 Web package：
- manifest.json
- config.json
- logic/logic.mjs
- assets/
- asset-manifest.json
- checksum-summary.json
GamePackage.profiles.web.status 初始化为 built。
wechat_minigame、douyin_minigame、kuaishou_minigame 初始化为 { status: "pending_conversion" }，不写 artifactPath 或 reportPath。
package logic 只复制 S3 校验过的 source artifact，并校验 source checksum 与 packaged checksum。
Web manifest 记录 S3 source artifact、source checksum、validation report id、package relative logic path 和 package logic checksum。
package artifact repository 只接受 repository-relative path，并用同目录临时文件加 rename 写入，避免半截 artifact。
P0 package gate 拒绝完整引擎依赖和 bundle import，包括 descriptor imports、ValidationReport importGraph、源码静态 import/export。

Controller 自测

已运行并通过：

pnpm --filter @huijing/api test -- game-package
pnpm --filter @huijing/api typecheck
pnpm --filter @huijing/api lint
pnpm check:s4-scope
git diff --check
node --check scripts/check-scope.mjs

关键输出：

Test Files  22 passed (22)
Tests  228 passed (228)
S4 scope check passed.

pnpm check:s3-scope 已运行，结果为 EXPECTED_FAIL：当前分支包含 S4 game-package / GamePackage / AssetManifest 内容，S3 phase 对这些路径和术语继续 fail-closed。

Review Evidence

首轮 quality finding：

Task2 builder 测试缺少关键 fail-closed 覆盖：
- unsupported runtimeSdkContractVersion
- ValidationReport.sourceHash mismatch
- ValidationReport.result != passed
- artifact tamper after validation
- source static import full engine/bundle

修复后新增测试覆盖上述路径。二轮 quality reviewer 确认：

新增 tests 覆盖 runtime SDK version mismatch、sourceHash mismatch、failed report、artifact tamper、source static import full engine/bundle。
实现仍通过 S3 repository boundary 读取 artifact/report，没有扩 scope。
API-local type mirror 的 drift 风险由 shared validators 和测试绑定缓解，非 blocker。

二轮 spec reviewer 确认：

Task2 required files exist.
Builder outputs manifest/config/logic/assets/asset-manifest/checksum-summary.
Web profile is built and mini-game profiles remain pending_conversion without artifactPath/reportPath.
Checksum, ValidationReport, P0 engine/bundle gates are covered.
No S4 Task3+ runtime/preview/smoke or S5 conversion implementation found.

S5 并行决策

S5 可在 S4 Task2 提交后从同一稳定提交点创建独立 worktree/branch 并行启动：

S4 当前分支继续 Task3+：runtime SDK、Web runtime host、Web adapter、preview、smoke。
S5 独立分支先做 Task1-4：mini-game contracts、platform adapters、converter/project builder、static gate。
S5 Task5 DevToolImportEvidence.result=passed 和 S5 final P0 acceptance 必须等待 S4 runtime/preview/smoke 证据，不得用 blocker/note 伪装 PASS。

冻结合同：

packages/shared-contracts/src/game-package.ts
packages/shared-contracts/src/runtime-sdk-contract.ts
packages/shared-contracts/src/game-logic-module.ts
apps/api/src/modules/game-logic/artifact-repository.ts

如 S5 需要修改上述合同，必须先走 change-control，不得为了转换器便利弱化 S4 validator 或 S3 artifact boundary。

SHA-256

Path	SHA-256
`apps/api/src/modules/game-package/index.ts`	`a2a939d273db650ac96be0f96e9818199f5164b9a7f235dac8fd959432b61218`
`apps/api/src/modules/game-package/game-package.builder.spec.ts`	`fc6768243559bc5dbf7491f16b34732d56f28adcf0d233dd0cbbe63bbf242a1a`
`docs/superpowers/plans/2026-05-31-mvp-S4-web-runtime.md`	`d7153b464f764aa5dd5f500f74a1a3dcc0e1df1fdc2a94435923409158d87ffe`
`docs/superpowers/specs/2026-05-31-mvp-S4-web-runtime-design.md`	`693c806836322eed8df7d6deb71dc379c519d2687b6f4f3b60626186b55a4711`

Git Status Snapshot

写入本文档前 git status --short --branch --untracked-files=all：

## codex/s1-task9-s2-prep...origin/codex/s1-task9-s2-prep [ahead 13]
?? apps/api/src/modules/game-package/game-package.builder.spec.ts
?? apps/api/src/modules/game-package/index.ts

Residual Notes

pnpm --filter @huijing/api test -- game-package 当前会匹配多组 game-* specs，不只 Task2 单文件；这是当前 repo test filter 行为。
API-local shared contract type mirror 仍有 drift 风险；当前用 shared validators 和测试绑定输出，不在 Task2 内扩大 rootDir/exports 改造。
controller 复跑通过后，spec reviewer 曾遇到的一次 creation-agent-ai-design-workbench.api.spec.ts 201/404 不再复现，记录为非 Task2 flake/environment 风险。
进入 S4 Task3 前不得修改 S5 conversion；进入 S5 并行时必须使用独立 worktree 并保持冻结合同只读。

6.9 KiB Raw Blame History Unescape Escape