pixelheros/production/qa/evidence/2026-06-20-config-editor-plan-a.md

配置编辑器 Plan A — 验证证据

• Plan: docs/superpowers/plans/2026-06-20-config-editor-foundation.md
• Branch: card0614
• Date: 2026-06-21
• Tasks implemented: 1–13 (full plan)

---

自动化测试（BLOCKING 门槛）

• 命令: npx tsx --test __tests__/*.test.ts（在 extensions/pixelhero-config-editor/ 下运行）
• 结果: 36 / 36 PASS，0 fail，0 skip
• 耗时: ~560–600ms

覆盖范围：

测试文件	用例数	覆盖点
recordValue.serializer.test.ts	8	num/str/bool/enumRef/speed/arr/obj/raw 序列化；serializeEntry 单行与嵌套续行
parser.test.ts	8	AST → RecordValue；speed 表达式识别；enumRef fallback；raw 保留；findExportObjectLiteral
tsConfigFile.test.ts	10	load/getKeys/read；patch/add/delete；.bak 备份；语法校验阻断；dirty/no-op save；speed+enumRef 往返不丢
validation.test.ts	8	dup-uuid、missing-required、bad-enum、dangling-ref（触发槽/field/revive）、bad-override-key、herolist-inconsistent
buildSkillDesc.test.ts	2	受击触发盾效、驻场光环描述

说明：Task 11（store.ts）与 Task 12（index.ts/面板）依赖 Cocos Editor 全局，无法在 Node 中 import/运行，故无单元测试——按计划设计。自动化门槛以纯逻辑层 36 用例为准。

---

构建（BLOCKING 门槛）

• 命令: npm run build（在 extensions/pixelhero-config-editor/ 下运行）
• 结果: 成功，两个产物均生成，esbuild 无错误。

产物	大小（字节）	说明
dist/main.js	9,982,310 (~9.5 MB)	node/cjs；内联 typescript 编译器 API；Editor 为运行时全局（无 esbuild 报错）
dist/panels/default.js	642,825 (~628 KB)	browser/iife；内联 vue/dist/vue.esm-bundler.js（含运行时模板编译器）

dist/ 已被 extensions/pixelhero-config-editor/.gitignore 忽略，未提交。

构建过程中的必要修正（已记入 Task 12 commit message）

Plan 给出的 esbuild.config.mjs 将面板入口设为 platform: 'browser' 且 external: []。但 Plan 的面板 src/panels/default/index.ts 在运行时用 node:fs/node:path 读取 static/template/default/index.html 与 static/style/default/index.css。esbuild 在 browser 平台下拒绝打包 node: 内建，报错：

X [ERROR] Could not resolve "node:fs"
X [ERROR] Could not resolve "node:path"

修正：将面板入口的 external 改为 ['node:fs', 'node:path']。理由：Cocos 面板进程在 Electron 渲染层运行，能访问 Node 内建；vue 仍按 plan 打进 IIFE。dist/main.js 不受影响（platform:'node' 本就允许 node: 内建）。

---

编辑器内集成（ADVISORY — 待人工完成）

以下为人工在 Cocos Creator 3.8.6 中执行的验证清单。完成后请勾选并补截图路径。

• 1. 打开 Cocos Creator 3.8.6 项目 d:\game\pixelheros。
• 2. 扩展管理器（Extension Manager）→ 项目扩展 → 启用/重载 pixelhero-config-editor；控制台无报错。
• 3. 主菜单 → 面板（Panel）→ 英雄技能配置（Hero/Skill Config），面板打开。
• 4. 表下拉切换 英雄/怪物 → 列表显示真实 uuid（应含 5011/5012/.../6106 等英雄条目）。
• 5. 表下拉切换 技能 → 列表显示 6xxx 系列技能 uuid；切 驻场技能 → 7xxx 系列。
• 6. 点选 hero 表任一条 → 右侧 <pre> 显示结构化 JSON：
  • 6a. fac 字段为 { "kind": "enumRef", "qualifier": "FacSet", "member": "HERO" }（或 MON）。
  • 6b. 技能 skills.<uuid>.cd 为 { "kind": "speed", "level": "Slow3" }（或其它 AtkSpeedLv 成员）。
  • 6c. 数值/字符串字段为 { "kind": "num"|"str", "value": ... }。
• 7. 点选 skill 表任一条 → JSON 中 TGroup/DTType/IType/RType/EType 等字段均为 enumRef，call_hero（若有）为 num 或 enumRef。
• 8. 结论：端到端 IPC 打通，IO 层正确解析真实 assets/script/game/common/config/heroSet.ts 与 SkillSet.ts。
• 9. 截图存档路径（填写）：production/qa/evidence/screenshots/config-editor-plan-a-YYYYMMDD.png

---

提交记录

Task	Commit SHA	标题
11	e3102c63	feat(config-editor): main-process store (in-memory truth + message impls + asset-db refresh)
12	24b5c498	feat(config-editor): extension entry + minimal Vue panel proving end-to-end IPC
13	（本提交）	test(config-editor): record Plan A verification evidence

Tasks 1–10 由前序批次完成并提交，SHAs 详见 git log --oneline extensions/pixelhero-config-editor/。

---

Definition of Done 对照

1. 扩展可被 Cocos 3.8.6 加载，菜单可打开面板 — 待人工确认（见上节步骤 2–3）。
2. IO 层对真实配置正确解析（含 speed 表达式与枚举引用） — 单元测试覆盖（fixtures 镜像真实形态），人工确认真实文件见步骤 6。
3. patch 一条英雄保存后：磁盘文件更新且为合法 TS；其他条目与符号表达式原样保留；.bak 已生成；asset-db 已刷新 — TsConfigFile 单元测试覆盖文件行为（patch/add/delete/save/.bak/语法校验）；asset-db refresh 在 store.saveRecord 中调用，待人工在编辑器内验证一次保存。
4. 校验层对各类非法数据正确报错（error 级阻断保存） — 8 个 validation 单元测试覆盖；saveRecord 在 error 时回滚不落盘。
5. 全部单元测试 PASS（BLOCKING） — 36/36 PASS。
6. 未改动 assets/script/game/** 任何游戏运行时代码 — 本批次仅改动 extensions/pixelhero-config-editor/** 与本证据文件。