记录契约常量的单一来源与前端契约用例

- 实施计划：补「Rust 是权威、前端副本由 xhsMinitoolContract 钉住」这条边界，前端 vitest 口径 21 例（新增 15 + 契约 2 + 既有 4），并说明指令正文与用例的期望值都从常量组合。 - 里程碑：证据里加 tests/xhsMinitoolContract.test.ts 这条（读 layout.rs / export/mod.rs 逐条比对）。
2026-10-05 18:42:47 +08:00
parent 11de789a8f
commit dfd392e25d
2 changed files with 4 additions and 3 deletions
@@ -16,6 +16,7 @@
 - 快照排除：`src-tauri/src/project/filesystem.rs` 新增 `PROJECT_SNAPSHOT_SYNC_ONLY_EXCLUDED_COMPONENTS = [".export"]`；**不能**并进通用排除列表（`agent/direct_patch.rs` 直接拿它拒绝路径，`agc_apply_patch` 会拒 `.export/`，首次适配无法落地）。
 - skill：`resources/agc-skills/vite-export-xhs-minitool/scripts/pack.mjs`（新增 `--zip-out <path>`，相对 cwd 解析、父目录自动创建；原 `--zip <name>` 行为不变）、`scripts/vite.config.xhs-minitool.mjs` 注释点明 `outDir` 与 `--out-dir` 必须一致、`SKILL.md` 补「被 AGC 导出面板调用时」三条硬契约；同步 `manifest.json` 指纹与 `skill_pack.rs` 的 `include_bytes!` 内容（文件数不变，仍 36 条）。
 - 文档：主规范一节、本里程碑与实施计划、`docs/README.md` 入口、`docs/project-memory/shared-memory/decision-log.md` 一条。
+- 契约常量的单一来源：Rust `export/mod.rs` 的 `EXPORT_WORK_RELATIVE_DIR` 与 `draft/xhs_minitool/layout.rs` 是权威，前端 `state/xhsMinitoolInstruction.ts` 只为插值留一份副本；这份副本由 `tests/xhsMinitoolContract.test.ts`（读上面两个 `.rs`）逐条钉住，两边任一侧改名都会红。前端指令用例只钉「正文有没有把契约写进去」，不再抄一份字面量。
 - 明确不动：`GAME_CREATION_APP_COMMANDS`、`shared-contracts`、`server-rs`、SpacetimeDB、OpenAPI、`api-server`，以及现有 `project/export.rs` 的发布链路。

 ## 实现顺序
@@ -57,9 +58,9 @@
 - `5e2426c8a` 导出收尾判据抽成 `conclude(...)` 并补 5 例确定性用例（非零退出 / 超时 / 产物缺失 / 空产物 / 成功），同时去掉 `XHSMiniToolExportRunResult.exitCode` 这个恒为 0 的死字段；`463341c4b` 导出成功后把脚本输出尾部报给用户；`b3be3ee71` 证据口径修正；`5dd158ee1` 补默认 ignore 的真实起进程用例。
 - `1b7741ac6` 适配与修复指令补上「包根在 game/ 时落点写成 `../.export/xhs-minitool.zip`」，skill 契约同步（manifest `2026-08-26.42`）；`f8ed4e898` 保存对话框的默认文件名收进下载助手并复用既有取文件名工具；`90f651ddf` 刷新时先撤掉待触发的自动保存（附回归用例；该行为已被下面的自动刷新取代——轮询不再撤掉待保存的输入，因为「磁盘为准」的刷新动作没有了）。
 - `ac666daad` 之后：未适配提示改成带入队按钮的卡片、失败卡片按变体分派适配/修/重试、提示只在注册表读回来之后出现（同一时刻只有一张卡片、一个入口）。
- `9d3018a49` / `6dd0dc00c` 之后：去掉刷新按钮，改成按固定间隔自动重读内容；内容与注册表指纹拆成两条命令（自动刷新拿不到写回基线）；同步细节（指纹、保存中、待保存）退出前端对外状态与界面。
+- 指令正文里的契约字符串全部从常量组合（`XHS_MINITOOL_EXPORT_DIR_RELATIVE_PATH` + 三个脚本落点），用例的期望值也从常量推；`9d3018a49` / `6dd0dc00c` 之后：去掉刷新按钮，改成按固定间隔自动重读内容；内容与注册表指纹拆成两条命令（自动刷新拿不到写回基线）；同步细节（指纹、保存中、待保存）退出前端对外状态与界面。

-已验证：Rust `export::` 49 例（`export::draft::xhs_minitool` 33 例）、`export_bindings` 115 例、`project_snapshot` 22 例、`check:generated-bindings`（117 个文件）、前端 vitest 19 例（新增 15 + 既有 4）、`ai-game-creator-shell:typecheck`、`agc:skill-pack:check`、`check:doc-index`、`check:encoding`、`git diff --check`。
+已验证：Rust `export::` 49 例（`export::draft::xhs_minitool` 33 例）、`export_bindings` 115 例、`project_snapshot` 22 例、`check:generated-bindings`（117 个文件）、前端 vitest 21 例（新增 15 + 契约 2 + 既有 4）、`ai-game-creator-shell:typecheck`、`agc:skill-pack:check`、`check:doc-index`、`check:encoding`、`git diff --check`。

 未验证（唯一开口项）：真实 vite 项目上的首轮适配闭环——agent 跑通 `build:xhs-minitool`、产出可上传 zip、二次导出零 agent 调用；以及 `.export/` 换机后重新适配的体感。宿主侧这一段已尽力自动化：`build.rs` 的 `executes_the_project_script_and_requires_a_non_empty_artifact_each_time`（`#[ignore]`）会真起进程执行项目脚本，覆盖「第一次产出 → 删掉产物再跑一次重新产出 → 脚本成功但没产出报 artifactMissing」。本机尝试运行被容器环境挡下，读日志时注意两点、别误判成 bug：
 - 子进程输出里的 `running 1 test` 是**预期现象**：命令沙箱的垫片就是当前可执行文件本身（`desktop.rs` 按 `--command-sandbox-trampoline` 分流），编译到测试态时 `sandbox_trampoline_arguments()` 会改成 `--exact ...trampoline_child_fixture --ignored`，所以垫片进程是测试二进制在跑那一个 fixture 用例。
@@ -51,7 +51,7 @@
 - 自动化（已落）：
  - Rust `cargo test ... --bin genarrative-ai-game-creator-shell export::` 49 例，其中 `export::draft::xhs_minitool` 33 例：注册表自动建空表单、格式漂移静默吸收、严格解析拒绝、表单首错、icon 越界/符号链接/扩展名、`hasScript` 现算、`contentHash` 冲突、产物路径守卫，以及构建收尾判据的逐条映射（脚本缺失、非零退出带退出码与输出尾部、超时无退出码、产物缺失、空产物不算、成功回输出尾部）。
  - `export_bindings` 115 例 + `npm run check:generated-bindings`（117 个生成文件）通过。
-  - 前端 `npx vitest run tests/xhsMinitoolExport.test.tsx`（15 例）与既有 `tests/artifactsPanel.test.tsx`（4 例）通过；`npm run ai-game-creator-shell:typecheck` 通过。其中 15 例覆盖：指令正文三条硬契约与 game/ 落点、失败现场拼装、失败变体人话映射与三向 action 分派（适配 / 修 / 重试）、未适配卡片自带入队按钮且按钮行不重复、注册表读回来之前不下「还没适配」结论、表单复制、icon 与 zip 下载、冲突逐字段二选一、自动保存带回读到的 `baseHash`、自动重读只更新脚本判据而不动用户未保存的表单、agent 事后改注册表/加脚本不用点刷新就能带回来、导出把脚本输出尾部报给用户、以及「只有适配/修复才叫 agent」。
+  - 前端 `npx vitest run tests/xhsMinitoolExport.test.tsx`（15 例）、`tests/xhsMinitoolContract.test.ts`（2 例，把前端契约常量的值逐条对到 Rust `layout.rs` / `export/mod.rs`）与既有 `tests/artifactsPanel.test.tsx`（4 例）通过；`npm run ai-game-creator-shell:typecheck` 通过。其中 15 例覆盖（期望值一律从契约常量推，不另抄字面量）：指令正文三条硬契约与 game/ 落点、失败现场拼装、失败变体人话映射与三向 action 分派（适配 / 修 / 重试）、未适配卡片自带入队按钮且按钮行不重复、注册表读回来之前不下「还没适配」结论、表单复制、icon 与 zip 下载、冲突逐字段二选一、自动保存带回读到的 `baseHash`、自动重读只更新脚本判据而不动用户未保存的表单、agent 事后改注册表/加脚本不用点刷新就能带回来、导出把脚本输出尾部报给用户、以及「只有适配/修复才叫 agent」。
  - `.export/` 快照排除有定向用例：`project_snapshot::tests::project_snapshot_sync_policy_keeps_agent_state_and_still_blocks_credentials` 同时钉住「同步排除」与「通用口径不排除（Agent 仍可写）」。
  - `npm run agc:skill-pack:sync` → `agc:skill-pack:check` 通过（`manifest.json` 版本 `2026-08-26.42`，文件数不变，仍 36 条）。
 - 运行时（**未验证**，本里程碑唯一开口项）：在真实 vite 项目上由 agent 完成首轮适配、产出可人工上传的 zip、二次导出零 agent 调用；`.export/` 换机后需重新适配的体感也需一并确认。宿主侧这一段已有默认 `#[ignore]` 的真起进程用例（`executes_the_project_script_and_requires_a_non_empty_artifact_each_time`：第一次产出 → 删掉产物重跑必须重新产出 → 脚本成功但没产出报 artifactMissing），一键复跑命令见实施计划；本次尝试被容器环境的 npm/沙箱解析挡下，不是代码问题。