pan/pixelheros
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0a960b737cb510120da212a38fd2a621f4a6f885
pixelheros/docs/superpowers/plans/2026-06-20-config-editor-foundation.md

74 KiB
Raw Blame History

英雄/技能配置编辑器 — Plan A：基础层（脚手架 + IO + Schema + 校验 + 主进程）

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: 在 extensions/pixelhero-config-editor/ 下交付一个可加载的 Cocos Creator 3.8.6 扩展，包含经自动化测试的纯逻辑层（TS AST 往返 IO、schema、校验）与主进程消息处理，外加一个最小面板证明端到端 IPC 打通。

Architecture: schema 驱动；IO 层用 TypeScript Compiler API 对现有 Record<number,X> 配置做"条目级 AST 区间替换"，保留符号表达式（AtkSpeedSet[AtkSpeedLv.X].cd）与枚举引用（FacSet.HERO）；纯逻辑层零 Cocos 依赖、可独立测试；主进程单例持有内存真理源，面板经 Editor.Message 读写。

Tech Stack: TypeScript、typescript（编译器 API）、vue@3（面板，esm-bundler 含编译器）、esbuild（打包）、tsx+node:test（单元测试）。Cocos Creator 3.8.6 扩展 API（Editor.Panel.define、Editor.Message、contributions.messages/menu）。

本计划范围（Plan A）： P0 脚手架 + P1 IO + P2 schema/校验 + P3 主进程（只读+patch保存）+ 最小面板。不在本计划： 完整 UI（master-detail/嵌套编辑器/预览）、add/delete 记录的消息与 HeroList 写同步 —— 见 Plan B。

Refines spec §5.2： RecordValue 增加 enumRef（FacSet.HERO 等）与 raw（未识别表达式原样保留、UI 标只读）两种；v1 序列化不输出 info 行注释（info 作为普通字段），以规避条目前置注释在 patch 时的重复问题。

File Structure

extensions/pixelhero-config-editor/
├── package.json                 # 扩展清单（package_version:2, panels, contributions, deps）
├── tsconfig.json
├── esbuild.config.mjs           # 打包 main（node/cjs）+ 面板（browser/iife, bundle vue）
├── i18n/en.js, i18n/zh.js
├── static/template/default/index.html   # 面板宿主 <div id="app">
├── static/style/default/index.css
├── src/
│   ├── main/
│   │   ├── index.ts             # 扩展入口：onLoad/onMessage 注册
│   │   └── store.ts             # 三张表 TsConfigFile 单例 + 消息处理实现
│   ├── io/
│   │   ├── recordValue.ts       # RecordValue 类型（纯类型，无依赖）
│   │   ├── parser.ts            # AST → RecordValue（含 speed/enumRef/raw）
│   │   ├── serializer.ts        # RecordValue → TS 文本（serializeValue / serializeEntry）
│   │   └── TsConfigFile.ts      # load/getKeys/read/patch/add/delete/save（条目级区间替换）
│   ├── shared/                  # 纯逻辑（无 cc / Editor 依赖，可独立测试）
│   │   ├── schema/
│   │   │   ├── types.ts         # TableSchema / FieldSchema / FieldType
│   │   │   ├── enums.ts         # 枚举镜像（HType/FacSet/TGroup/.../AtkSpeedLv/Attrs）
│   │   │   ├── hero.ts          # HeroInfo schema
│   │   │   ├── skill.ts         # SkillSet(SkillConfig) schema
│   │   │   ├── field.ts         # FieldSkillSet(FieldSkillConfig) schema
│   │   │   └── registry.ts      # 三表注册 + getSchema
│   │   ├── validation/index.ts  # validate(tableId, allRecords, context) → Issue[]
│   │   └── desc/buildSkillDesc.ts  # HeroSkillDesc 的 JS 移植（预览用）
│   └── panels/default/
│       ├── index.ts             # Editor.Panel.define + Vue mount
│       └── app.ts               # 最小 Vue app（Plan A：证明 query-keys 打通）
├── dist/                        # 产物（main.js, panels/default.js）—— gitignore
└── __tests__/
    ├── fixtures/heroSet.sample.ts   # 真实片段副本（含 speed + enumRef）
    ├── fixtures/skillSet.sample.ts
    ├── recordValue.serializer.test.ts
    ├── parser.test.ts
    ├── tsConfigFile.test.ts
    ├── validation.test.ts
    ├── schema.test.ts
    └── buildSkillDesc.test.ts

职责边界： src/shared/** 与 src/io/** 严禁 import cc 或 Editor（保证可测）。src/main/** 才允许用 Editor。IO 层 save() 只做 fs+语法校验（纯），asset-db refresh 由 main 在 save 成功后调用（解耦）。

Task 1: 扩展脚手架（package.json / tsconfig / esbuild / i18n）

Files:

  • Create: extensions/pixelhero-config-editor/package.json

  • Create: extensions/pixelhero-config-editor/tsconfig.json

  • Create: extensions/pixelhero-config-editor/esbuild.config.mjs

  • Create: extensions/pixelhero-config-editor/i18n/en.js

  • Create: extensions/pixelhero-config-editor/i18n/zh.js

  • Create: extensions/pixelhero-config-editor/.gitignore

  • Step 1: 写 package.json

{
  "package_version": 2,
  "name": "pixelhero-config-editor",
  "version": "0.1.0",
  "description": "i18n:pixelhero-config-editor.description",
  "main": "./dist/main.js",
  "author": "pixelhero",
  "editor": ">=3.8.0",
  "scripts": {
    "build": "node esbuild.config.mjs",
    "watch": "node esbuild.config.mjs --watch",
    "test": "tsx --test __tests__/*.test.ts"
  },
  "panels": {
    "default": {
      "title": "i18n:pixelhero-config-editor.title",
      "type": "dockable",
      "main": "./dist/panels/default.js",
      "size": { "width": 960, "height": 640, "min-width": 640, "min-height": 480 }
    }
  },
  "contributions": {
    "menu": [
      { "path": "i18n:menu.panel/英雄技能配置", "message": "open-panel" }
    ],
    "messages": {
      "open-panel": { "methods": ["open-panel"] },
      "query-schema": { "methods": ["query-schema"] },
      "query-enums": { "methods": ["query-enums"] },
      "query-keys": { "methods": ["query-keys"] },
      "query-record": { "methods": ["query-record"] },
      "query-preview-desc": { "methods": ["query-preview-desc"] },
      "validate": { "methods": ["validate"] },
      "save-record": { "methods": ["save-record"] },
      "revert-record": { "methods": ["revert-record"] }
    }
  },
  "dependencies": {
    "typescript": "^5.4.0",
    "vue": "^3.4.0"
  },
  "devDependencies": {
    "@types/node": "^20.0.0",
    "esbuild": "^0.20.0",
    "fs-extra": "^11.0.0",
    "tsx": "^4.7.0"
  }
}
  • Step 2: 写 tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "CommonJS",
    "moduleResolution": "node",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "resolveJsonModule": true,
    "experimentalDecorators": true,
    "types": ["node"],
    "lib": ["ES2020", "DOM"]
  },
  "include": ["src/**/*", "__tests__/**/*"]
}
  • Step 3: 写 esbuild.config.mjs（含 vue esm-bundler 别名以启用运行时模板编译）
import { build, context } from 'esbuild';
import { readFileSync } from 'fs';
import { join } from 'path';

const watch = process.argv.includes('--watch');

const common = {
  bundle: true,
  sourcemap: false,
  logLevel: 'info',
  alias: { 'vue': 'vue/dist/vue.esm-bundler.js' },
};

const entries = [
  { entryPoints: ['src/main/index.ts'], outfile: 'dist/main.js', platform: 'node', format: 'cjs', external: [] },
  { entryPoints: ['src/panels/default/index.ts'], outfile: 'dist/panels/default.js', platform: 'browser', format: 'iife', external: [] },
];

if (watch) {
  for (const e of entries) {
    const ctx = await context({ ...common, ...e });
    await ctx.watch();
  }
} else {
  for (const e of entries) await build({ ...common, ...e });
}
  • Step 4: 写 i18n/en.js 与 i18n/zh.js

i18n/en.js:

exports.en = {
  'pixelhero-config-editor': { description: 'Hero/Skill Config Editor', title: 'Hero/Skill Config' },
  'menu': { 'panel/英雄技能配置': 'Hero/Skill Config' },
};

i18n/zh.js:

exports.zh = {
  'pixelhero-config-editor': { description: '英雄/技能配置编辑器', title: '英雄/技能配置' },
  'menu': { 'panel/英雄技能配置': '英雄技能配置' },
};
  • Step 5: 写 .gitignore
node_modules/
dist/
*.bak
  • Step 6: 安装依赖并提交
cd extensions/pixelhero-config-editor
npm install
cd ../..
git add extensions/pixelhero-config-editor/package.json extensions/pixelhero-config-editor/package-lock.json extensions/pixelhero-config-editor/tsconfig.json extensions/pixelhero-config-editor/esbuild.config.mjs extensions/pixelhero-config-editor/i18n extensions/pixelhero-config-editor/.gitignore
git commit -m "feat(config-editor): scaffold extension manifest, build, i18n"

Task 2: RecordValue 类型与枚举镜像（纯逻辑）

Files:

  • Create: extensions/pixelhero-config-editor/src/io/recordValue.ts

  • Create: extensions/pixelhero-config-editor/src/shared/schema/enums.ts

  • Step 1: 写 recordValue.ts

/** IO 层对配置对象字面量值的结构化表示。零依赖。 */
export type RecordValue =
  | { kind: 'num'; value: number }
  | { kind: 'str'; value: string }
  | { kind: 'bool'; value: boolean }
  | { kind: 'enumRef'; qualifier: string; member: string }   // 如 FacSet.HERO
  | { kind: 'speed'; level: string }                          // AtkSpeedSet[AtkSpeedLv.X].cd
  | { kind: 'obj'; props: Record<string, RecordValue> }
  | { kind: 'arr'; items: RecordValue[] }
  | { kind: 'raw'; text: string };                            // 未识别表达式，原样保留

export function isScalar(v: RecordValue): boolean {
  return v.kind === 'num' || v.kind === 'str' || v.kind === 'bool'
      || v.kind === 'enumRef' || v.kind === 'speed' || v.kind === 'raw';
}
  • Step 2: 写 enums.ts（镜像游戏枚举；value 与游戏 enum 数值一致）
export interface EnumMember { label: string; value: number | string; }
export interface EnumDef { qualifier: string; members: EnumMember[]; }

export const ENUMS: Record<string, EnumDef> = {
  HType: { qualifier: 'HType', members: [
    { label: '近战 Melee', value: 0 }, { label: '中程 Mid', value: 1 }, { label: '远程 Long', value: 2 } ] },
  FacSet: { qualifier: 'FacSet', members: [
    { label: '英雄 HERO', value: 0 }, { label: '怪物 MON', value: 1 } ] },
  TGroup: { qualifier: 'TGroup', members: [
    { label: '自身 Self', value: 0 }, { label: '友方含己 Ally', value: 1 },
    { label: '友方 Team', value: 2 }, { label: '敌方 Enemy', value: 3 }, { label: '全体 All', value: 4 } ] },
  DTType: { qualifier: 'DTType', members: [
    { label: '单体 single', value: 0 }, { label: '范围 range', value: 1 }, { label: '3x3 aoe_grid', value: 2 } ] },
  SkillKind: { qualifier: 'SkillKind', members: [
    { label: '伤害 Damage', value: 0 }, { label: '治疗 Heal', value: 1 }, { label: '护盾 Shield', value: 2 },
    { label: '辅助 Support', value: 3 }, { label: '金币 Gold', value: 4 } ] },
  DType: { qualifier: 'DType', members: [
    { label: '物理 ATK', value: 0 }, { label: '冰 ICE', value: 1 }, { label: '火 FIRE', value: 2 }, { label: '风 WIND', value: 3 } ] },
  IType: { qualifier: 'IType', members: [
    { label: '近战 Melee', value: 0 }, { label: '远程 remote', value: 1 }, { label: '辅助 support', value: 2 } ] },
  RType: { qualifier: 'RType', members: [
    { label: '直线 linear', value: 0 }, { label: '贝塞尔 bezier', value: 1 },
    { label: '固定起点 fixed', value: 2 }, { label: '固定终点 fixedEnd', value: 3 } ] },
  EType: { qualifier: 'EType', members: [
    { label: '动画结束 animationEnd', value: 0 }, { label: '时间结束 timeEnd', value: 1 }, { label: '碰撞 collision', value: 2 } ] },
  FieldSkillType: { qualifier: 'FieldSkillType', members: [
    { label: '召唤次数 SummonCount', value: 1 }, { label: '死亡次数 DeadCount', value: 2 },
    { label: '开场次数 StartCount', value: 3 }, { label: '结束次数 EndCount', value: 4 },
    { label: '每波金币 WaveGold', value: 5 }, { label: '卖出金币 SellGold', value: 6 },
    { label: '战后回复 WaveHeal', value: 7 }, { label: '英雄攻击 HeroAtk', value: 8 },
    { label: '英雄击晕 HeroStun', value: 9 }, { label: '英雄暴击 HeroCrit', value: 10 },
    { label: '英雄暴伤 HeroCritDamage', value: 11 }, { label: '英雄攻速 HeroSpeed', value: 12 },
    { label: '购买优惠 BuyDiscount', value: 13 }, { label: '刷新优惠 RefreshDiscount', value: 14 },
    { label: '英雄生命 HeroHp', value: 16 }, { label: '英雄风怒 HeroWindFury', value: 17 },
    { label: '英雄穿刺 HeroPuncture', value: 18 }, { label: '攻击次数 AtkCount', value: 19 },
    { label: '受击次数 BeAtkCount', value: 20 } ] },
  AtkSpeedLv: { qualifier: 'AtkSpeedLv', members: [
    { label: '极速++ VeryFast1', value: 1 }, { label: '极速+ VeryFast2', value: 2 }, { label: '极速 VeryFast3', value: 3 },
    { label: '快速++ Fast1', value: 4 }, { label: '快速+ Fast2', value: 5 }, { label: '快速 Fast3', value: 6 },
    { label: '中速++ Normal1', value: 7 }, { label: '中速+ Normal2', value: 8 }, { label: '中速 Normal3', value: 9 },
    { label: '一般+ Mid1', value: 10 }, { label: '一般 Mid2', value: 11 }, { label: '一般- Mid3', value: 12 },
    { label: '慢 Slow1', value: 13 }, { label: '慢+ Slow2', value: 14 }, { label: '慢++ Slow3', value: 15 },
    { label: '很慢 VerySlow1', value: 16 }, { label: '很慢+ VerySlow2', value: 17 }, { label: '很慢++ VerySlow3', value: 18 } ] },
  Attrs: { qualifier: 'Attrs', members: [
    { label: 'ap', value: 'ap' }, { label: 'hp', value: 'hp' }, { label: 'hp_max', value: 'hp_max' },
    { label: 'critical', value: 'critical' }, { label: 'critical_damage', value: 'critical_damage' },
    { label: 'stun_chance', value: 'stun_chance' }, { label: 'puncture_chance', value: 'puncture_chance' },
    { label: 'wfuny', value: 'wfuny' }, { label: 'freeze_chance', value: 'freeze_chance' },
    { label: 'knockback_chance', value: 'knockback_chance' } ] },
};

/** qualifier（如 'FacSet'）→ 对应 enumId（如 'FacSet'）。当前两者同名。 */
export const QUALIFIER_TO_ID: Record<string, string> = Object.fromEntries(
  Object.entries(ENUMS).map(([id, def]) => [def.qualifier, id])
);
  • Step 3: 提交
git add extensions/pixelhero-config-editor/src/io/recordValue.ts extensions/pixelhero-config-editor/src/shared/schema/enums.ts
git commit -m "feat(config-editor): add RecordValue type and enum mirror"

Task 3: Schema 类型与三张表 schema

Files:

  • Create: extensions/pixelhero-config-editor/src/shared/schema/types.ts

  • Create: extensions/pixelhero-config-editor/src/shared/schema/hero.ts

  • Create: extensions/pixelhero-config-editor/src/shared/schema/skill.ts

  • Create: extensions/pixelhero-config-editor/src/shared/schema/field.ts

  • Create: extensions/pixelhero-config-editor/src/shared/schema/registry.ts

  • Step 1: 写 types.ts

export type TableId = 'hero' | 'skill' | 'field';

export type FieldType =
  | 'number' | 'string' | 'boolean'
  | 'enum'        // 下拉，选项来自 enumRef
  | 'ref'         // 引用另一表 uuid
  | 'speedExpr'   // 攻速符号表达式
  | 'skillMap' | 'triggerSlots' | 'fieldList' | 'reviveSlot' | 'overrides';

export interface FieldSchema {
  key: string;
  label: string;
  type: FieldType;
  required?: boolean;
  default?: unknown;
  group?: string;
  enumRef?: string;     // type='enum'
  refTable?: TableId;   // type='ref'
}

export interface IdSegment { label: string; min: number; max: number; }

export interface TableSchema {
  id: TableId;
  label: string;
  sourceFile: string;      // 相对 assets/script/game/common/config/
  exportName: string;      // 'HeroInfo' | 'SkillSet' | 'FieldSkillSet'
  listExportName?: string; // 'HeroList'（仅 hero）
  idSegments: IdSegment[];
  fields: FieldSchema[];
}
  • Step 2: 写 hero.ts
import { TableSchema } from './types';
export const heroSchema: TableSchema = {
  id: 'hero', label: '英雄/怪物',
  sourceFile: 'heroSet.ts', exportName: 'HeroInfo', listExportName: 'HeroList',
  idSegments: [
    { label: '英雄', min: 5000, max: 5999 },
    { label: '怪物', min: 6000, max: 6999 },
  ],
  fields: [
    { key: 'uuid', label: 'UUID', type: 'number', required: true, group: '基础' },
    { key: 'name', label: '名称', type: 'string', required: true, group: '基础' },
    { key: 'path', label: '资源路径', type: 'string', required: true, group: '基础' },
    { key: 'icon', label: '图标', type: 'string', group: '基础' },
    { key: 'fac', label: '阵营', type: 'enum', enumRef: 'FacSet', required: true, group: '基础' },
    { key: 'pool_lv', label: '卡片等级', type: 'number', group: '基础' },
    { key: 'lv', label: '英雄等级', type: 'number', required: true, default: 1, group: '基础' },
    { key: 'type', label: '攻击定位', type: 'enum', enumRef: 'HType', required: true, group: '基础' },
    { key: 'hp', label: '生命上限', type: 'number', required: true, group: '基础' },
    { key: 'ap', label: '攻击力', type: 'number', required: true, group: '基础' },
    { key: 'dis', label: '攻击距离', type: 'number', group: '基础' },
    { key: 'speed', label: '移动速度', type: 'number', group: '基础' },
    { key: 'skills', label: '携带技能', type: 'skillMap', required: true, group: '技能' },
    { key: 'call', label: '召唤触发', type: 'triggerSlots', group: '触发技能' },
    { key: 'dead', label: '死亡触发', type: 'triggerSlots', group: '触发技能' },
    { key: 'fstart', label: '战斗开始触发', type: 'triggerSlots', group: '触发技能' },
    { key: 'fend', label: '战斗结束触发', type: 'triggerSlots', group: '触发技能' },
    { key: 'atking', label: '攻击触发', type: 'triggerSlots', group: '触发技能' },
    { key: 'atked', label: '受击触发', type: 'triggerSlots', group: '触发技能' },
    { key: 'field', label: '驻场技能', type: 'fieldList', group: '触发技能' },
    { key: 'revive', label: '复活触发', type: 'reviveSlot', group: '触发技能' },
    { key: 'info', label: '描述文案', type: 'string', required: true, group: '基础' },
  ],
};
  • Step 3: 写 skill.ts
import { TableSchema } from './types';
export const skillSchema: TableSchema = {
  id: 'skill', label: '技能',
  sourceFile: 'SkillSet.ts', exportName: 'SkillSet',
  idSegments: [{ label: '技能', min: 6000, max: 6999 }],
  fields: [
    { key: 'uuid', label: 'UUID', type: 'number', required: true, group: '基础' },
    { key: 'name', label: '名称', type: 'string', required: true, group: '基础' },
    { key: 'sp_name', label: '特效名', type: 'string', required: true, group: '基础' },
    { key: 'icon', label: '图标ID', type: 'string', required: true, group: '基础' },
    { key: 'act', label: '执行动画', type: 'string', required: true, group: '基础' },
    { key: 'TGroup', label: '目标群体', type: 'enum', enumRef: 'TGroup', required: true, group: '目标' },
    { key: 'DTType', label: '伤害类型', type: 'enum', enumRef: 'DTType', required: true, group: '目标' },
    { key: 'IType', label: '技能类型', type: 'enum', enumRef: 'IType', required: true, group: '目标' },
    { key: 'RType', label: '运行类型', type: 'enum', enumRef: 'RType', required: true, group: '目标' },
    { key: 'EType', label: '结束条件', type: 'enum', enumRef: 'EType', required: true, group: '目标' },
    { key: 'kind', label: '主效果', type: 'enum', enumRef: 'SkillKind', group: '目标' },
    { key: 'ap', label: 'ap(伤害%/护盾次)', type: 'number', required: true, group: '数值' },
    { key: 'gold', label: '金币值', type: 'number', group: '数值' },
    { key: 'hit_count', label: '可命中次数', type: 'number', required: true, group: '数值' },
    { key: 'hitcd', label: '伤害间隔', type: 'number', required: true, group: '数值' },
    { key: 'speed', label: '移动速度', type: 'number', required: true, group: '数值' },
    { key: 'ready', label: '前摇时间', type: 'number', required: true, group: '数值' },
    { key: 'with', label: '宽度', type: 'number', default: 0, group: '数值' },
    { key: 'readyAnm', label: '前摇动画', type: 'string', group: '动画' },
    { key: 'endAnm', label: '结束动画', type: 'string', group: '动画' },
    { key: 'DAnm', label: '命中动画ID', type: 'string', group: '动画' },
    { key: 'EAnm', label: '结束动画ID', type: 'number', group: '动画' },
    { key: 'crt', label: '额外暴击率', type: 'number', group: '高级' },
    { key: 'stun', label: '额外击晕概率', type: 'number', group: '高级' },
    { key: 'frz', label: '额外冰冻概率', type: 'number', group: '高级' },
    { key: 'bck', label: '额外击退概率', type: 'number', group: '高级' },
    { key: 'buff_type', label: 'Buff类型', type: 'enum', enumRef: 'Attrs', group: '高级' },
    { key: 'call_hero', label: '召唤英雄', type: 'ref', refTable: 'hero', group: '高级' },
    { key: 'time', label: '持续时间', type: 'number', group: '高级' },
    { key: 'bezier_start_y', label: '贝塞尔起始Y', type: 'number', group: '高级' },
    { key: 'bezier_mid_y', label: '贝塞尔中点Y', type: 'number', group: '高级' },
    { key: 'bezier_arc', label: '贝塞尔弧度', type: 'number', group: '高级' },
    { key: 'info', label: '描述', type: 'string', required: true, group: '基础' },
  ],
};
  • Step 4: 写 field.ts
import { TableSchema } from './types';
export const fieldSchema: TableSchema = {
  id: 'field', label: '驻场技能',
  sourceFile: 'SkillSet.ts', exportName: 'FieldSkillSet',
  idSegments: [{ label: '驻场技能', min: 7000, max: 7999 }],
  fields: [
    { key: 'uuid', label: 'UUID', type: 'number', required: true, group: '基础' },
    { key: 'name', label: '名称', type: 'string', required: true, group: '基础' },
    { key: 'icon', label: '图标', type: 'string', required: true, group: '基础' },
    { key: 'type', label: '类型', type: 'enum', enumRef: 'FieldSkillType', required: true, group: '效果' },
    { key: 'value', label: '数值', type: 'number', required: true, group: '效果' },
    { key: 'info', label: '描述', type: 'string', required: true, group: '基础' },
  ],
};
  • Step 5: 写 registry.ts
import { TableId, TableSchema } from './types';
import { heroSchema } from './hero';
import { skillSchema } from './skill';
import { fieldSchema } from './field';

export const REGISTRY: Record<TableId, TableSchema> = {
  hero: heroSchema, skill: skillSchema, field: fieldSchema,
};
export function getSchema(id: TableId): TableSchema { return REGISTRY[id]; }
export function allSchemas(): TableSchema[] { return Object.values(REGISTRY); }
  • Step 6: 提交
git add extensions/pixelhero-config-editor/src/shared/schema
git commit -m "feat(config-editor): add schema types and hero/skill/field table schemas"

Task 4: 序列化器 serializer（RecordValue → TS 文本）

Files:

  • Create: extensions/pixelhero-config-editor/src/io/serializer.ts

  • Test: extensions/pixelhero-config-editor/__tests__/recordValue.serializer.test.ts

  • Create: extensions/pixelhero-config-editor/__tests__/.gitignore（忽略 .tmp/）

  • Step 1: 写 .gitignore（测试临时目录）

.tmp/
  • Step 2: 写失败测试 recordValue.serializer.test.ts
import { test } from 'node:test';
import assert from 'node:assert/strict';
import { serializeValue, serializeEntry } from '../src/io/serializer';
import { RecordValue } from '../src/io/recordValue';

test('serializeValue: num/str/bool', () => {
  assert.equal(serializeValue({ kind: 'num', value: 400 }), '400');
  assert.equal(serializeValue({ kind: 'str', value: '小铁卫' }), '"小铁卫"');
  assert.equal(serializeValue({ kind: 'bool', value: true }), 'true');
});
test('serializeValue: enumRef', () => {
  const v: RecordValue = { kind: 'enumRef', qualifier: 'FacSet', member: 'HERO' };
  assert.equal(serializeValue(v), 'FacSet.HERO');
});
test('serializeValue: speed', () => {
  const v: RecordValue = { kind: 'speed', level: 'Slow3' };
  assert.equal(serializeValue(v), 'AtkSpeedSet[AtkSpeedLv.Slow3].cd');
});
test('serializeValue: arr', () => {
  const v: RecordValue = { kind: 'arr', items: [{ kind: 'num', value: 1 }, { kind: 'num', value: 2 }] };
  assert.equal(serializeValue(v), '[1,2]');
});
test('serializeValue: obj', () => {
  const v: RecordValue = { kind: 'obj', props: { a: { kind: 'num', value: 1 }, b: { kind: 'str', value: 'x' } } };
  assert.equal(serializeValue(v), '{a:1,b:"x"}');
});
test('serializeValue: raw passthrough', () => {
  const v: RecordValue = { kind: 'raw', text: 'a + b' };
  assert.equal(serializeValue(v), 'a + b');
});
test('serializeEntry: all-scalar one line with trailing comma', () => {
  const v: RecordValue = { kind: 'obj', props: { uuid: { kind: 'num', value: 1 }, name: { kind: 'str', value: 'x' } } };
  assert.equal(serializeEntry('1', v), '1:{uuid:1,name:"x"},');
});
test('serializeEntry: nested on continuation lines', () => {
  const v: RecordValue = { kind: 'obj', props: {
    uuid: { kind: 'num', value: 5011 },
    skills: { kind: 'obj', props: { 6001: { kind: 'obj', props: { uuid: { kind: 'num', value: 6001 } } } } },
  } };
  const out = serializeEntry('5011', v);
  assert.match(out, /^5011:\{uuid:5011,$/);                      // 首行：键 + 标量
  assert.match(out, /        skills:\{6001:\{uuid:6001\}\},$/m); // 续行 8 空格
  assert.match(out, /^    \},$/m);                               // 闭合 4 空格
});
  • Step 3: 运行测试，确认失败
cd extensions/pixelhero-config-editor && npx tsx --test __tests__/recordValue.serializer.test.ts

Expected: FAIL（Cannot find module '../src/io/serializer'）

  • Step 4: 写 serializer.ts
import { RecordValue, isScalar } from './recordValue';

export function serializeValue(v: RecordValue): string {
  switch (v.kind) {
    case 'num': return String(v.value);
    case 'str': return JSON.stringify(v.value);
    case 'bool': return String(v.value);
    case 'enumRef': return `${v.qualifier}.${v.member}`;
    case 'speed': return `AtkSpeedSet[AtkSpeedLv.${v.level}].cd`;
    case 'arr': return `[${v.items.map(serializeValue).join(',')}]`;
    case 'obj': {
      const body = Object.entries(v.props).map(([k, val]) => `${k}:${serializeValue(val)}`).join(',');
      return `{${body}}`;
    }
    case 'raw': return v.text;
  }
}

/** 序列化一条顶层记录。首行无缩进（缩进由调用处保留的 trivia 提供）；嵌套字段 8 空格续行；闭合 4 空格。 */
export function serializeEntry(key: string, obj: RecordValue): string {
  if (obj.kind !== 'obj') return `${key}:${serializeValue(obj)},`;
  const props = obj.props;
  const keys = Object.keys(props);
  const scalars = keys.filter(k => isScalar(props[k]));
  const nested = keys.filter(k => !isScalar(props[k]));
  const scalarTxt = scalars.map(k => `${k}:${serializeValue(props[k])}`).join(',');
  if (nested.length === 0) return `${key}:{${scalarTxt}},`;
  const lines = [`${key}:{${scalarTxt},`];
  for (const k of nested) lines.push(`        ${k}:${serializeValue(props[k])},`);
  lines.push('    },');
  return lines.join('\n');
}
  • Step 5: 运行测试，确认通过
npx tsx --test __tests__/recordValue.serializer.test.ts

Expected: PASS（全部用例）

  • Step 6: 提交
git add extensions/pixelhero-config-editor/src/io/serializer.ts extensions/pixelhero-config-editor/__tests__/recordValue.serializer.test.ts extensions/pixelhero-config-editor/__tests__/.gitignore
git commit -m "feat(config-editor): add RecordValue serializer with tests"

Task 5: 解析器 parser（AST → RecordValue）

Files:

  • Create: extensions/pixelhero-config-editor/src/io/parser.ts

  • Test: extensions/pixelhero-config-editor/__tests__/parser.test.ts

  • Step 1: 写失败测试 parser.test.ts

import { test } from 'node:test';
import assert from 'node:assert/strict';
import * as ts from 'typescript';
import { parseExpression, findExportObjectLiteral } from '../src/io/parser';

function parse(text: string): ts.Expression {
  const src = ts.createSourceFile('x.ts', `const _ = ${text};`, ts.ScriptTarget.Latest, true);
  const decl = src.statements[0] as ts.VariableStatement;
  return decl.declarationList.declarations[0].initializer!;
}

test('num / str / bool', () => {
  assert.deepEqual(parseExpression(parse('400')), { kind: 'num', value: 400 });
  assert.deepEqual(parseExpression(parse('"小铁卫"')), { kind: 'str', value: '小铁卫' });
  assert.deepEqual(parseExpression(parse('true')), { kind: 'bool', value: true });
});
test('enumRef: FacSet.HERO', () => {
  assert.deepEqual(parseExpression(parse('FacSet.HERO')), { kind: 'enumRef', qualifier: 'FacSet', member: 'HERO' });
});
test('speed: AtkSpeedSet[AtkSpeedLv.Slow3].cd', () => {
  assert.deepEqual(parseExpression(parse('AtkSpeedSet[AtkSpeedLv.Slow3].cd')), { kind: 'speed', level: 'Slow3' });
});
test('non-Speed two-segment access falls back to enumRef', () => {
  assert.deepEqual(parseExpression(parse('Foo.bar')), { kind: 'enumRef', qualifier: 'Foo', member: 'bar' });
});
test('arr', () => {
  assert.deepEqual(parseExpression(parse('[1,2,3]')), { kind: 'arr', items: [
    { kind: 'num', value: 1 }, { kind: 'num', value: 2 }, { kind: 'num', value: 3 }] });
});
test('obj with numeric + identifier keys', () => {
  const v = parseExpression(parse('{6001:{uuid:6001},name:"x"}'));
  assert.equal(v.kind, 'obj');
  assert.deepEqual(v.props['6001'], { kind: 'obj', props: { uuid: { kind: 'num', value: 6001 } } });
  assert.deepEqual(v.props['name'], { kind: 'str', value: 'x' });
});
test('raw: unsupported expression preserved verbatim', () => {
  const v = parseExpression(parse('a + b'));
  assert.equal(v.kind, 'raw');
  assert.equal((v as any).text, 'a + b');
});
test('findExportObjectLiteral locates HeroInfo', () => {
  const src = ts.createSourceFile('x.ts',
    `export const HeroInfo: Record<number, any> = { 5011:{uuid:5011} };`, ts.ScriptTarget.Latest, true);
  const node = findExportObjectLiteral(src, 'HeroInfo');
  assert.ok(node);
  assert.equal(node!.properties.length, 1);
});
  • Step 2: 运行测试，确认失败
npx tsx --test __tests__/parser.test.ts

Expected: FAIL（模块不存在）

  • Step 3: 写 parser.ts
import * as ts from 'typescript';
import { RecordValue } from './recordValue';

/** 在 SourceFile 中查找 `export const <name> = {...}`，返回其对象字面量节点。 */
export function findExportObjectLiteral(src: ts.SourceFile, name: string): ts.ObjectLiteralExpression | null {
  let result: ts.ObjectLiteralExpression | null = null;
  const visit = (node: ts.Node) => {
    if (result) return;
    if (ts.isVariableStatement(node)) {
      for (const d of node.declarationList.declarations) {
        if (d.name.getText() === name && d.initializer && ts.isObjectLiteralExpression(d.initializer)) {
          result = d.initializer;
          return;
        }
      }
    }
    ts.forEachChild(node, visit);
  };
  visit(src);
  return result;
}

/** 识别 `AtkSpeedSet[AtkSpeedLv.<level>].cd`，否则 null。 */
function tryParseSpeedExpr(node: ts.PropertyAccessExpression): RecordValue | null {
  if (node.name.text !== 'cd') return null;
  const inner = node.expression;
  if (!ts.isElementAccessExpression(inner)) return null;
  if (!ts.isIdentifier(inner.expression) || inner.expression.text !== 'AtkSpeedSet') return null;
  const arg = inner.argumentExpression;
  if (!ts.isPropertyAccessExpression(arg)) return null;
  if (!ts.isIdentifier(arg.expression) || arg.expression.text !== 'AtkSpeedLv') return null;
  return { kind: 'speed', level: arg.name.text };
}

export function parseExpression(node: ts.Expression): RecordValue {
  if (ts.isNumericLiteral(node)) return { kind: 'num', value: Number(node.text) };
  if (ts.isStringLiteral(node)) return { kind: 'str', value: node.text };
  if (node.kind === ts.SyntaxKind.TrueKeyword) return { kind: 'bool', value: true };
  if (node.kind === ts.SyntaxKind.FalseKeyword) return { kind: 'bool', value: false };

  if (ts.isPropertyAccessExpression(node)) {
    const speed = tryParseSpeedExpr(node);
    if (speed) return speed;
    if (ts.isIdentifier(node.expression)) {
      return { kind: 'enumRef', qualifier: node.expression.text, member: node.name.text };
    }
    return { kind: 'raw', text: node.getText() }; // 多级 a.b.c 等
  }

  if (ts.isArrayLiteralExpression(node)) {
    return { kind: 'arr', items: node.elements.map(e => parseExpression(e)) };
  }

  if (ts.isObjectLiteralExpression(node)) {
    const props: Record<string, RecordValue> = {};
    for (const m of node.properties) {
      if (ts.isPropertyAssignment(m)) {
        props[m.name.getText()] = parseExpression(m.initializer);
      }
    }
    return { kind: 'obj', props };
  }

  return { kind: 'raw', text: node.getText() }; // 二元/模板/调用/其他元素访问
}
  • Step 4: 运行测试，确认通过
npx tsx --test __tests__/parser.test.ts

Expected: PASS

  • Step 5: 提交
git add extensions/pixelhero-config-editor/src/io/parser.ts extensions/pixelhero-config-editor/__tests__/parser.test.ts
git commit -m "feat(config-editor): add AST parser (speed/enumRef/raw) with tests"

Task 6: 测试夹具 fixtures

Files:

  • Create: extensions/pixelhero-config-editor/__tests__/fixtures/heroSet.sample.ts

  • Create: extensions/pixelhero-config-editor/__tests__/fixtures/skillSet.sample.ts

  • Step 1: 写 heroSet.sample.ts（真实片段；未解析标识符不影响纯语法解析）

// 测试夹具：镜像真实 heroSet.ts 片段（speed 表达式 + 枚举引用 + 触发槽 + 驻场 + 复活）
export const HeroInfo: Record<number, any> = {
    5011:{uuid:5011,name:"小铁卫",path:"hk1", fac:FacSet.HERO,pool_lv:1,lv:1,type:HType.Melee,hp:400,ap:20,
        skills:{6001:{uuid:6001,lv:1,cd:AtkSpeedSet[AtkSpeedLv.Slow3].cd,ccd:0}},
        atked:[{s_uuid:6301,t_num:3,overrides:{TGroup:TGroup.Self,ap:4}}],
        field:[7015],
        revive:{s_uuid:6501,r_num:1,upr:0.3},
        info:"每受击3次为自身添加4层护盾"},
    6001:{uuid:6001,name:"兽人战士",path:"m1", fac:FacSet.MON,lv:1,type:HType.Melee,hp:220,ap:10,speed:70,
        skills:{6005:{uuid:6005,lv:1,cd:AtkSpeedSet[AtkSpeedLv.VerySlow1].cd,ccd:0}},info:"基础近战位怪"},
};

export const HeroList: number[] = [5011];
  • Step 2: 写 skillSet.sample.ts
// 测试夹具：镜像真实 SkillSet.ts 片段（含 SkillSet + FieldSkillSet）
export const SkillSet: Record<number, any> = {
    6001:{uuid:6001,name:"火球",sp_name:"atk_1",icon:"Stat_Attack_01",TGroup:TGroup.Enemy,act:"atk",
        DTType:DTType.single,ap:100,hit_count:1,hitcd:0.2,speed:720,with:0,ready:0.2,
        IType:IType.Melee,RType:RType.bezier,EType:EType.collision,info:"造成攻击力100%的伤害"},
    6301:{uuid:6301,name:"护盾",sp_name:"buff_wind",icon:"Stat_Defense",TGroup:TGroup.Self,act:"atk",
        DTType:DTType.single,kind:SkillKind.Shield,ap:3,hit_count:1,hitcd:0.2,speed:720,with:0,ready:0.2,
        IType:IType.support,RType:RType.fixed,EType:EType.animationEnd,info:"添加护盾"},
    6501:{uuid:6501,name:"复活",sp_name:"buff_wind",icon:"Stat_HolyDamage",TGroup:TGroup.Self,act:"atk",
        DTType:DTType.single,kind:SkillKind.Support,ap:50,hit_count:3,hitcd:0.2,speed:720,with:0,ready:0.2,
        IType:IType.support,RType:RType.fixed,EType:EType.animationEnd,info:"复活百分比"},
};

export const FieldSkillSet: Record<number, any> = {
    7015:{uuid:7015,name:"死亡强化",icon:"Stat_PoisonChanceIncrease",type:FieldSkillType.DeadCount,value:1,info:"死亡触发技能次数+1"},
};
  • Step 3: 提交
git add extensions/pixelhero-config-editor/__tests__/fixtures
git commit -m "test(config-editor): add hero/skill fixtures mirroring real config shape"

Task 7: TsConfigFile — load / getKeys / read

Files:

  • Create: extensions/pixelhero-config-editor/src/io/TsConfigFile.ts

  • Test: extensions/pixelhero-config-editor/__tests__/tsConfigFile.test.ts

  • Step 1: 写失败测试 tsConfigFile.test.ts（load/keys/read 部分）

import { test } from 'node:test';
import assert from 'node:assert/strict';
import { readFileSync, copyFileSync, mkdtempSync, readdirSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { fileURLToPath } from 'node:url';
import { dirname, join } from 'node:path';
import { TsConfigFile } from '../src/io/TsConfigFile';

const here = dirname(fileURLToPath(import.meta.url));
const fixture = join(here, 'fixtures', 'heroSet.sample.ts');

test('load + getKeys', () => {
  const f = new TsConfigFile(fixture, 'HeroInfo');
  f.load();
  assert.deepEqual(f.getKeys(), ['5011', '6001']);
});
test('read returns structured value with speed/enumRef preserved', () => {
  const f = new TsConfigFile(fixture, 'HeroInfo');
  f.load();
  const v = f.read('5011')!;
  assert.equal(v.kind, 'obj');
  assert.deepEqual(v.props['fac'], { kind: 'enumRef', qualifier: 'FacSet', member: 'HERO' });
  const skill = v.props['skills'].props['6001'];
  assert.deepEqual(skill.props['cd'], { kind: 'speed', level: 'Slow3' });
});
test('getText after load equals original file (no mutation on load)', () => {
  const f = new TsConfigFile(fixture, 'HeroInfo');
  f.load();
  assert.equal(f.getText(), readFileSync(fixture, 'utf8'));
});
test('read missing key returns null', () => {
  const f = new TsConfigFile(fixture, 'HeroInfo');
  f.load();
  assert.equal(f.read('9999'), null);
});
  • Step 2: 运行测试，确认失败
npx tsx --test __tests__/tsConfigFile.test.ts

Expected: FAIL（模块不存在）

  • Step 3: 写 TsConfigFile.ts（先实现 load/getKeys/read/getText）
import * as fs from 'node:fs';
import * as ts from 'typescript';
import { RecordValue } from './recordValue';
import { findExportObjectLiteral, parseExpression } from './parser';

export class TsConfigFile {
  private sourceText = '';
  private sourceFile!: ts.SourceFile;
  private targetNode!: ts.ObjectLiteralExpression;
  private dirty = false;

  constructor(public readonly filePath: string, public readonly exportName: string) {}

  load(): void {
    this.sourceText = fs.readFileSync(this.filePath, 'utf8');
    this.reparse();
    this.dirty = false;
  }

  private reparse(): void {
    this.sourceFile = ts.createSourceFile(this.filePath, this.sourceText, ts.ScriptTarget.Latest, true);
    const node = findExportObjectLiteral(this.sourceFile, this.exportName);
    if (!node) throw new Error(`export const ${this.exportName} not found or not an object literal in ${this.filePath}`);
    this.targetNode = node;
  }

  getKeys(): string[] {
    return this.targetNode.properties.map(p => (p.name as ts.PropertyName).getText());
  }

  read(key: string): RecordValue | null {
    const entry = this.findEntry(key);
    if (!entry) return null;
    return parseExpression(entry.initializer);
  }

  private findEntry(key: string): ts.PropertyAssignment | undefined {
    return this.targetNode.properties.find(p => (p.name as ts.PropertyName).getText() === key) as ts.PropertyAssignment | undefined;
  }

  getText(): string { return this.sourceText; }
  isDirty(): boolean { return this.dirty; }

  // —— patch/add/delete/save 在 Task 8 实现 ——
  patch(_key: string, _value: RecordValue): void { throw new Error('not implemented'); }
  add(_key: string, _value: RecordValue): void { throw new Error('not implemented'); }
  delete(_key: string): void { throw new Error('not implemented'); }
  save(): { ok: true } | { ok: false; error: string } { throw new Error('not implemented'); }
}
  • Step 4: 运行测试，确认通过
npx tsx --test __tests__/tsConfigFile.test.ts

Expected: PASS（4 个用例）

  • Step 5: 提交
git add extensions/pixelhero-config-editor/src/io/TsConfigFile.ts extensions/pixelhero-config-editor/__tests__/tsConfigFile.test.ts
git commit -m "feat(config-editor): TsConfigFile load/getKeys/read with tests"

Task 8: TsConfigFile — patch / add / delete / save（含 .bak + 语法校验）

Files:

  • Modify: extensions/pixelhero-config-editor/src/io/TsConfigFile.ts（替换 patch/add/delete/save 桩，并 import serializeEntry）

  • Test: append to extensions/pixelhero-config-editor/__tests__/tsConfigFile.test.ts

  • Step 1: 在测试文件追加失败用例

function withTempFixture(): { dir: string; file: string } {
  const dir = mkdtempSync(join(tmpdir(), 'phcfg-'));
  const file = join(dir, 'heroSet.sample.ts');
  copyFileSync(fixture, file);
  return { dir, file };
}

test('patch updates one entry; reload reads new value; other entries intact', () => {
  const { file } = withTempFixture();
  const f = new TsConfigFile(file, 'HeroInfo'); f.load();
  const v = f.read('5011')!;
  v.props['ap'] = { kind: 'num', value: 99 };
  f.patch('5011', v);
  assert.equal(f.isDirty(), true);
  assert.equal(f.save().ok, true);
  const f2 = new TsConfigFile(file, 'HeroInfo'); f2.load();
  assert.deepEqual(f2.read('5011')!.props['ap'], { kind: 'num', value: 99 });
  assert.equal(f2.read('6001')!.props['name'].value, '兽人战士'); // 另一条未破坏
});

test('patch preserves speed + enumRef on reload', () => {
  const { file } = withTempFixture();
  const f = new TsConfigFile(file, 'HeroInfo'); f.load();
  const v = f.read('5011')!;
  v.props['hp'] = { kind: 'num', value: 500 };
  f.patch('5011', v); f.save();
  const f2 = new TsConfigFile(file, 'HeroInfo'); f2.load();
  const again = f2.read('5011')!;
  assert.deepEqual(again.props['fac'], { kind: 'enumRef', qualifier: 'FacSet', member: 'HERO' });
  assert.deepEqual(again.props['skills'].props['6001'].props['cd'], { kind: 'speed', level: 'Slow3' });
});

test('add appends entry readable after save+reload', () => {
  const { file } = withTempFixture();
  const f = new TsConfigFile(file, 'HeroInfo'); f.load();
  f.add('5099', { kind: 'obj', props: { uuid: { kind: 'num', value: 5099 }, name: { kind: 'str', value: '新英雄' } } });
  f.save();
  const f2 = new TsConfigFile(file, 'HeroInfo'); f2.load();
  assert.ok(f2.getKeys().includes('5099'));
  assert.equal(f2.read('5099')!.props['name'].value, '新英雄');
});

test('delete removes entry', () => {
  const { file } = withTempFixture();
  const f = new TsConfigFile(file, 'HeroInfo'); f.load();
  f.delete('6001'); f.save();
  const f2 = new TsConfigFile(file, 'HeroInfo'); f2.load();
  assert.ok(!f2.getKeys().includes('6001'));
  assert.ok(f2.getKeys().includes('5011'));
});

test('save writes a .bak backup of the pre-save file', () => {
  const { file } = withTempFixture();
  const f = new TsConfigFile(file, 'HeroInfo'); f.load();
  const v = f.read('5011')!; v.props['hp'] = { kind: 'num', value: 1 }; f.patch('5011', v);
  f.save();
  assert.equal(readFileSync(file + '.bak', 'utf8'), readFileSync(fixture, 'utf8'));
});

test('save with no edits is a no-op (ok, no .bak written)', () => {
  const { file, dir } = withTempFixture();
  const f = new TsConfigFile(file, 'HeroInfo'); f.load();
  assert.equal(f.save().ok, true);
  assert.equal(readdirSync(dir).some(p => p.endsWith('.bak')), false);
});
  • Step 2: 运行测试，确认新增用例失败
npx tsx --test __tests__/tsConfigFile.test.ts

Expected: 6 个新用例 FAIL（not implemented）

  • Step 3: 实现 patch/add/delete/save（替换 TsConfigFile 中四个桩；文件顶部 import 补 import { serializeEntry } from './serializer';）
  patch(key: string, value: RecordValue): void {
    const entry = this.findEntry(key);
    const newText = serializeEntry(key, value);
    if (entry) {
      const { start, end } = this.entrySpan(entry);
      this.sourceText = this.sourceText.slice(0, start) + newText + this.sourceText.slice(end);
    } else {
      this.insertEntry(newText);
    }
    this.reparse();
    this.dirty = true;
  }

  add(key: string, value: RecordValue): void {
    if (this.findEntry(key)) throw new Error(`key ${key} already exists`);
    this.insertEntry(serializeEntry(key, value));
    this.reparse();
    this.dirty = true;
  }

  delete(key: string): void {
    const entry = this.findEntry(key);
    if (!entry) return;
    const { start, end } = this.entrySpan(entry);
    this.sourceText = this.sourceText.slice(0, start) + this.sourceText.slice(end);
    this.reparse();
    this.dirty = true;
  }

  save(): { ok: true } | { ok: false; error: string } {
    if (!this.dirty) return { ok: true };
    const check = ts.createSourceFile(this.filePath, this.sourceText, ts.ScriptTarget.Latest, true);
    if (check.parseDiagnostics.length > 0) {
      const msg = check.parseDiagnostics.map(d => ts.flattenDiagnosticMessageText(d.messageText, '\n')).join('; ');
      return { ok: false, error: `syntax error after edit: ${msg}` };
    }
    fs.writeFileSync(this.filePath + '.bak', fs.readFileSync(this.filePath));
    fs.writeFileSync(this.filePath, this.sourceText);
    this.dirty = false;
    return { ok: true };
  }

  /** 条目文本区间，含尾随逗号；不含前导缩进 trivia（避免吞掉上一行换行）。 */
  private entrySpan(entry: ts.PropertyAssignment): { start: number; end: number } {
    const start = entry.getStart();
    let end = entry.getEnd();
    const comma = /^\s*,/.exec(this.sourceText.slice(end));
    if (comma) end += comma[0].length;
    return { start, end };
  }

  private insertEntry(entryText: string): void {
    const closeBrace = this.targetNode.getLastToken();
    if (!closeBrace) throw new Error('object literal has no closing brace');
    const pos = closeBrace.getStart();
    this.sourceText = this.sourceText.slice(0, pos) + `    ${entryText}\n    ` + this.sourceText.slice(pos);
  }
  • Step 4: 运行该测试，确认通过
npx tsx --test __tests__/tsConfigFile.test.ts

Expected: PASS（10 个用例）

  • Step 5: 跑全部测试套件，确认无回归
npx tsx --test __tests__/*.test.ts

Expected: 全部 PASS

  • Step 6: 提交
git add extensions/pixelhero-config-editor/src/io/TsConfigFile.ts extensions/pixelhero-config-editor/__tests__/tsConfigFile.test.ts
git commit -m "feat(config-editor): TsConfigFile patch/add/delete/save with .bak + syntax check"

Task 9: 校验层 validation

Files:

  • Create: extensions/pixelhero-config-editor/src/shared/validation/index.ts
  • Test: extensions/pixelhero-config-editor/__tests__/validation.test.ts

校验上下文需引用他表（hero 触发槽引用 skill、field 引用驻场）。context 提供 hasSkill(uuid)、hasField(uuid)、hasHero(uuid)、heroListKeys: Set<string>。

  • Step 1: 写失败测试 validation.test.ts
import { test } from 'node:test';
import assert from 'node:assert/strict';
import { validate } from '../src/shared/validation';
import { RecordValue } from '../src/io/recordValue';

const ctx = {
  hasSkill: (u: number) => [6001, 6301, 6501].includes(u),
  hasField: (u: number) => [7015].includes(u),
  hasHero: (u: number) => [5011, 6001].includes(u),
  heroListKeys: new Set<string>(['5011']),
};

function heroObj(extra: Record<string, RecordValue> = {}): RecordValue {
  return { kind: 'obj', props: {
    uuid: { kind: 'num', value: 5011 }, name: { kind: 'str', value: 'x' }, path: { kind: 'str', value: 'p' },
    fac: { kind: 'enumRef', qualifier: 'FacSet', member: 'HERO' }, lv: { kind: 'num', value: 1 },
    type: { kind: 'enumRef', qualifier: 'HType', member: 'Melee' }, hp: { kind: 'num', value: 400 },
    ap: { kind: 'num', value: 20 },
    skills: { kind: 'obj', props: { 6001: { kind: 'obj', props: { uuid: { kind: 'num', value: 6001 }, lv: { kind: 'num', value: 1 }, cd: { kind: 'speed', level: 'Slow3' }, ccd: { kind: 'num', value: 0 } } } } },
    info: { kind: 'str', value: 'ok' },
    ...extra,
  } };
}

test('valid hero → no errors', () => {
  const issues = validate('hero', new Map([['5011', heroObj()]]), ctx);
  assert.equal(issues.filter(i => i.severity === 'error').length, 0);
});
test('duplicate uuid → error', () => {
  const issues = validate('hero', new Map([['5011', heroObj()], ['5011', heroObj()]]), ctx);
  assert.ok(issues.some(i => i.severity === 'error' && i.code === 'dup-uuid'));
});
test('missing required field → error', () => {
  const h = heroObj(); delete h.props['name'];
  const issues = validate('hero', new Map([['5011', h]]), ctx);
  assert.ok(issues.some(i => i.code === 'missing-required' && i.fieldPath === 'name'));
});
test('trigger slot references missing skill → error', () => {
  const h = heroObj({ atked: { kind: 'arr', items: [{ kind: 'obj', props: {
    s_uuid: { kind: 'num', value: 9999 }, t_num: { kind: 'num', value: 3 } } }] } });
  const issues = validate('hero', new Map([['5011', h]]), ctx);
  assert.ok(issues.some(i => i.code === 'dangling-ref'));
});
test('field list references missing field skill → error', () => {
  const h = heroObj({ field: { kind: 'arr', items: [{ kind: 'num', value: 8888 }] } });
  const issues = validate('hero', new Map([['5011', h]]), ctx);
  assert.ok(issues.some(i => i.code === 'dangling-ref'));
});
test('HeroList/hero consistency: fac=HERO entry missing from HeroList → error', () => {
  const ctx2 = { ...ctx, heroListKeys: new Set<string>([]) };
  const issues = validate('hero', new Map([['5011', heroObj()]]), ctx2);
  assert.ok(issues.some(i => i.code === 'herolist-inconsistent'));
});
test('invalid enum value → error', () => {
  const h = heroObj({ fac: { kind: 'enumRef', qualifier: 'FacSet', member: 'NOPE' } });
  const issues = validate('hero', new Map([['5011', h]]), ctx);
  assert.ok(issues.some(i => i.code === 'bad-enum'));
});
test('unknown overrides key → error', () => {
  const h = heroObj({ atked: { kind: 'arr', items: [{ kind: 'obj', props: {
    s_uuid: { kind: 'num', value: 6301 }, t_num: { kind: 'num', value: 3 },
    overrides: { kind: 'obj', props: { bogus: { kind: 'num', value: 1 } } } } }] } });
  const issues = validate('hero', new Map([['5011', h]]), ctx);
  assert.ok(issues.some(i => i.code === 'bad-override-key'));
});
  • Step 2: 运行测试，确认失败
npx tsx --test __tests__/validation.test.ts

Expected: FAIL（模块不存在）

  • Step 3: 写 validation/index.ts
import { RecordValue } from '../../io/recordValue';
import { TableId } from '../schema/types';
import { ENUMS } from '../schema/enums';

export type Severity = 'error' | 'warn';
export interface Issue {
  tableId: TableId; key: string; fieldPath: string;
  severity: Severity; code: string; message: string;
}
export interface ValidationContext {
  hasSkill: (u: number) => boolean;
  hasField: (u: number) => boolean;
  hasHero: (u: number) => boolean;
  heroListKeys: Set<string>;
}

const OVERRIDE_KEYS = new Set(['TGroup', 'ap', 'gold', 'hit_count', 'hitcd', 'crt', 'frz', 'stun', 'bck', 'buff_type', 'call_hero']);
const TRIGGER_ARRAY_KEYS = ['call', 'dead', 'fstart', 'fend', 'atking', 'atked'];

function num(v: RecordValue | undefined): number | undefined {
  return v && v.kind === 'num' ? v.value : undefined;
}
function isKnownEnum(qualifier: string, member: string): boolean {
  const def = ENUMS[qualifier] ?? Object.values(ENUMS).find(e => e.qualifier === qualifier);
  return !!def && def.members.some(m => String(m.value) === member || m.label.split(' ').pop() === member);
}

export function validate(tableId: TableId, records: Map<string, RecordValue>, ctx: ValidationContext): Issue[] {
  const issues: Issue[] = [];
  const seen = new Set<string>();

  for (const [key, rec] of records) {
    const push = (fieldPath: string, severity: Severity, code: string, message: string) =>
      issues.push({ tableId, key, fieldPath, severity, code, message });

    if (seen.has(key)) push('uuid', 'error', 'dup-uuid', `重复 uuid: ${key}`);
    seen.add(key);

    if (rec.kind !== 'obj') { push('', 'error', 'not-object', '记录不是对象'); continue; }
    const p = rec.props;

    // 必填（按表最小集合）
    const required: Record<TableId, string[]> = {
      hero: ['uuid', 'name', 'path', 'fac', 'lv', 'type', 'hp', 'ap', 'skills', 'info'],
      skill: ['uuid', 'name', 'sp_name', 'icon', 'act', 'TGroup', 'DTType', 'IType', 'RType', 'EType', 'ap', 'hit_count', 'hitcd', 'speed', 'ready', 'info'],
      field: ['uuid', 'name', 'icon', 'type', 'value', 'info'],
    };
    for (const f of required[tableId]) {
      if (p[f] === undefined) push(f, 'error', 'missing-required', `缺少必填字段 ${f}`);
    }

    // 枚举值合法
    for (const [f, v] of Object.entries(p)) {
      if (v.kind === 'enumRef' && !isKnownEnum(v.qualifier, v.member)) {
        push(f, 'error', 'bad-enum', `非法枚举值 ${v.qualifier}.${v.member}`);
      }
    }

    if (tableId === 'hero') {
      // 触发槽数组引用 + overrides 键
      for (const tk of TRIGGER_ARRAY_KEYS) {
        const arr = p[tk];
        if (!arr || arr.kind !== 'arr') continue;
        for (const it of arr.items) {
          if (it.kind !== 'obj') continue;
          const su = num(it.props['s_uuid']);
          if (su !== undefined && !ctx.hasSkill(su)) push(tk, 'error', 'dangling-ref', `引用了不存在的技能 ${su}`);
          const ov = it.props['overrides'];
          if (ov && ov.kind === 'obj') {
            for (const k of Object.keys(ov.props)) {
              if (!OVERRIDE_KEYS.has(k)) push(`${tk}.overrides`, 'error', 'bad-override-key', `非法覆盖键 ${k}`);
            }
          }
        }
      }
      // field 列表
      const fl = p['field'];
      if (fl && fl.kind === 'arr') {
        for (const it of fl.items) { const u = num(it); if (u !== undefined && !ctx.hasField(u)) push('field', 'error', 'dangling-ref', `引用了不存在的驻场技能 ${u}`); }
      }
      // revive
      const rv = p['revive'];
      if (rv && rv.kind === 'obj') {
        const su = num(rv.props['s_uuid']); if (su !== undefined && !ctx.hasSkill(su)) push('revive', 'error', 'dangling-ref', `引用了不存在的技能 ${su}`);
      }
      // call_hero（技能表里的 ref 也用 hasHero）
    }
    if (tableId === 'skill') {
      const ch = num(p['call_hero']); if (ch !== undefined && !ctx.hasHero(ch)) push('call_hero', 'error', 'dangling-ref', `引用了不存在的英雄 ${ch}`);
    }

    // HeroList 一致性（仅 hero 表）
    if (tableId === 'hero') {
      const u = num(p['uuid']); const fac = p['fac'];
      const isHero = fac && fac.kind === 'enumRef' && fac.member === 'HERO';
      if (isHero && u !== undefined && !ctx.heroListKeys.has(String(u))) {
        push('uuid', 'error', 'herolist-inconsistent', `英雄 ${u} 不在 HeroList 中`);
      }
    }
  }
  return issues;
}
  • Step 4: 运行测试，确认通过
npx tsx --test __tests__/validation.test.ts

Expected: PASS（8 个用例）

  • Step 5: 提交
git add extensions/pixelhero-config-editor/src/shared/validation extensions/pixelhero-config-editor/__tests__/validation.test.ts
git commit -m "feat(config-editor): add validation rules (dup/required/enum/ref/overrides/herolist) with tests"

Task 10: buildSkillDesc 的 JS 移植（描述预览）

Files:

  • Create: extensions/pixelhero-config-editor/src/shared/desc/buildSkillDesc.ts
  • Test: extensions/pixelhero-config-editor/__tests__/buildSkillDesc.test.ts

移植自 assets/script/game/common/config/HeroSkillDesc.ts，输入 hero RecordValue（含已合并的触发槽）+ 一个查 SkillSet/FieldSkillSet 的函数，输出多行描述。Plan A 只需纯函数（UI 预览在 Plan B 接线）。

  • Step 1: 写失败测试
import { test } from 'node:test';
import assert from 'node:assert/strict';
import { buildSkillDesc } from '../src/shared/desc/buildSkillDesc';
import { RecordValue } from '../src/io/recordValue';

const skillSet: Record<number, RecordValue> = {
  6301: { kind: 'obj', props: { name: { kind: 'str', value: '护盾' }, kind: { kind: 'enumRef', qualifier: 'SkillKind', member: 'Shield' }, ap: { kind: 'num', value: 4 } } },
};
const fieldSet: Record<number, RecordValue> = {
  7015: { kind: 'obj', props: { name: { kind: 'str', value: '死亡强化' }, info: { kind: 'str', value: '死亡触发技能次数+1' } } },
};
const hero: RecordValue = { kind: 'obj', props: {
  atked: { kind: 'arr', items: [{ kind: 'obj', props: { s_uuid: { kind: 'num', value: 6301 }, t_num: { kind: 'num', value: 3 }, overrides: { kind: 'obj', props: { ap: { kind: 'num', value: 4 } } } } }] },
  field: { kind: 'arr', items: [{ kind: 'num', value: 7015 }] },
} };

test('renders atked trigger with shield effect', () => {
  const out = buildSkillDesc(hero, skillSet, fieldSet);
  assert.match(out, /受击3次:护盾/);
  assert.match(out, /护盾4次/);
});
test('renders field aura', () => {
  const out = buildSkillDesc(hero, skillSet, fieldSet);
  assert.match(out, /场上存活:死亡强化 死亡触发技能次数\+1/);
});
  • Step 2: 运行测试，确认失败
npx tsx --test __tests__/buildSkillDesc.test.ts

Expected: FAIL（模块不存在）

  • Step 3: 写 buildSkillDesc.ts（语义对齐 HeroSkillDesc.ts；触发模板与 buildEffectDesc 等价）
import { RecordValue } from '../../io/recordValue';

const TRIGGER_KEYS = ['call', 'dead', 'fstart', 'fend', 'atking', 'atked'] as const;
const TRIGGER_DESC: Record<string, string> = {
  call: '召唤时', dead: '死亡时', fstart: '战斗开始时', fend: '战斗结束时',
  field: '场上存活', atking: '攻击n次', atked: '受击n次', revive: '复活时',
};

function num(v: RecordValue | undefined): number | undefined { return v && v.kind === 'num' ? v.value : undefined; }
function str(v: RecordValue | undefined): string | undefined { return v && v.kind === 'str' ? v.value : undefined; }
function member(v: RecordValue | undefined): string | undefined { return v && v.kind === 'enumRef' ? v.member : undefined; }

function buildEffect(merged: RecordValue): string {
  if (merged.kind !== 'obj') return '';
  const kind = member(merged.props['kind']);
  const ap = num(merged.props['ap']) ?? 0;
  const parts: string[] = [];
  if (kind === 'Heal') parts.push(`治疗伙伴${ap}`);
  else if (kind === 'Shield') parts.push(`护盾${ap}次`);
  else if (kind === 'Gold') parts.push(`金币+${num(merged.props['gold']) ?? 0}`);
  else if (kind === 'Support') parts.push(String(str(merged.props['info']) ?? ''));
  else { // Damage / undefined
    parts.push(`伤害${ap}%`);
    if ((num(merged.props['hit_count']) ?? 1) > 1) parts.push(`${num(merged.props['hit_count'])}段`);
    if (num(merged.props['crt'])) parts.push(`暴击+${num(merged.props['crt'])}%`);
    if (num(merged.props['stun'])) parts.push(`击晕+${num(merged.props['stun'])}%`);
  }
  return parts.join(' ');
}

/** 合并 overrides 到 base（浅合并对象 props） */
function merge(base: RecordValue, overrides: RecordValue | undefined): RecordValue {
  if (!overrides || overrides.kind !== 'obj' || base.kind !== 'obj') return base;
  return { kind: 'obj', props: { ...base.props, ...overrides.props } };
}

export function buildSkillDesc(hero: RecordValue, skillSet: Record<number, RecordValue>, fieldSet: Record<number, RecordValue>): string {
  if (hero.kind !== 'obj') return '';
  const lines: string[] = [];
  for (const key of TRIGGER_KEYS) {
    const arr = hero.props[key];
    if (!arr || arr.kind !== 'arr') continue;
    const tpl = TRIGGER_DESC[key] ?? key;
    for (const it of arr.items) {
      if (it.kind !== 'obj') continue;
      const su = num(it.props['s_uuid']); if (su === undefined) continue;
      const base = skillSet[su]; if (!base) continue;
      const merged = merge(base, it.props['overrides']);
      const trigger = tpl.includes('n') ? tpl.replace('n', String(num(it.props['t_num']) ?? '')) : tpl;
      lines.push(`${trigger}:${str(base.props['name'])} ${buildEffect(merged)}`);
    }
  }
  const fl = hero.props['field'];
  if (fl && fl.kind === 'arr') {
    for (const it of fl.items) { const u = num(it); if (u === undefined) continue; const fs = fieldSet[u]; if (fs) lines.push(`${TRIGGER_DESC.field}:${str(fs.props['name'])} ${str(fs.props['info'])}`); }
  }
  const rv = hero.props['revive'];
  if (rv && rv.kind === 'obj') {
    const su = num(rv.props['s_uuid']); const base = su !== undefined ? skillSet[su] : undefined;
    if (base) lines.push(`${TRIGGER_DESC.revive} : ${str(base.props['name'])} ${buildEffect(merge(base, undefined))}`);
  }
  return lines.join('\n');
}
  • Step 4: 运行测试，确认通过
npx tsx --test __tests__/buildSkillDesc.test.ts

Expected: PASS

  • Step 5: 提交
git add extensions/pixelhero-config-editor/src/shared/desc extensions/pixelhero-config-editor/__tests__/buildSkillDesc.test.ts
git commit -m "feat(config-editor): port buildSkillDesc to JS for panel preview"

Task 11: 主进程 store（内存真理源 + 消息实现）

Files:

  • Create: extensions/pixelhero-config-editor/src/main/store.ts

主进程持有三张表的 TsConfigFile（hero 用 heroSet.ts 的 HeroInfo；skill/field 共用 SkillSet.ts，分别 SkillSet/FieldSkillSet 两个实例指向同一文件）。所有读写消息在此实现；save 成功后触发 asset-db refresh。

  • Step 1: 写 store.ts
import { join } from 'node:path';
import { TsConfigFile } from '../io/TsConfigFile';
import { allSchemas } from '../shared/schema/registry';
import { ENUMS } from '../shared/schema/enums';
import { validate, ValidationContext } from '../shared/validation';
import { buildSkillDesc } from '../shared/desc/buildSkillDesc';
import { RecordValue } from '../io/recordValue';
import { TableId } from '../shared/schema/types';

/** 游戏配置目录（相对项目根）。主进程用 __dirname 解析到项目根的 assets 配置目录。 */
const CONFIG_DIR = join(Editor.Project.path, 'assets/script/game/common/config');

interface Entry { file: TsConfigFile; }
const tables: Partial<Record<TableId, Entry>> = {};
// skill 与 field 共享 SkillSet.ts，但用不同 exportName 的 TsConfigFile 实例
const fileCache: Record<string, TsConfigFile> = {};

function getTable(id: TableId): Entry {
  if (tables[id]) return tables[id]!;
  const schema = allSchemas().find(s => s.id === id)!;
  const cacheKey = `${schema.sourceFile}:${schema.exportName}`;
  let file = fileCache[cacheKey];
  if (!file) { file = new TsConfigFile(join(CONFIG_DIR, schema.sourceFile), schema.exportName); file.load(); fileCache[cacheKey] = file; }
  const entry = { file };
  tables[id] = entry;
  return entry;
}

function recordsOf(id: TableId): Map<string, RecordValue> {
  const { file } = getTable(id);
  const m = new Map<string, RecordValue>();
  for (const k of file.getKeys()) { const v = file.read(k); if (v) m.set(k, v); }
  return m;
}

function buildContext(): ValidationContext {
  const hero = recordsOf('hero');
  const skill = recordsOf('skill');
  const field = recordsOf('field');
  const heroKeys = Array.from(hero.keys()).map(Number);
  const skillKeys = Array.from(skill.keys()).map(Number);
  const fieldKeys = Array.from(field.keys()).map(Number);
  // HeroList 读取（hero 表的 listExportName）
  const heroList = new TsConfigFile(join(CONFIG_DIR, 'heroSet.ts'), 'HeroList');
  heroList.load();
  const listRaw = heroList.getText();
  const heroListKeys = new Set<string>(
    (listRaw.match(/HeroList[\s\S]*?=\s*\[([^\]]*)\]/)?.[1].match(/-?\d+/g) ?? []).map(String)
  );
  return {
    hasHero: (u) => heroKeys.includes(u),
    hasSkill: (u) => skillKeys.includes(u),
    hasField: (u) => fieldKeys.includes(u),
    heroListKeys,
  };
}

export const store = {
  queryEnums: () => ENUMS,
  querySchema: (id?: TableId) => id ? allSchemas().find(s => s.id === id) : allSchemas(),
  queryKeys: (id: TableId) => getTable(id).file.getKeys(),
  queryRecord: (id: TableId, key: string) => getTable(id).file.read(key),
  queryPreviewDesc: (hero: RecordValue) => {
    const skill = recordsOf('skill'); const field = recordsOf('field');
    const skillSet: Record<number, RecordValue> = {};
    for (const [k, v] of skill) skillSet[Number(k)] = v;
    const fieldSet: Record<number, RecordValue> = {};
    for (const [k, v] of field) fieldSet[Number(k)] = v;
    return buildSkillDesc(hero, skillSet, fieldSet);
  },
  validate: (id: TableId) => validate(id, recordsOf(id), buildContext()),
  saveRecord: (id: TableId, key: string, value: RecordValue) => {
    // 先在副本上试写并校验
    const { file } = getTable(id);
    file.patch(key, value);
    const issues = validate(id, recordsOf(id), buildContext()).filter(i => i.key === key && i.severity === 'error');
    if (issues.length) { file.load(); return { ok: false as const, issues }; } // 回滚内存
    const r = file.save();
    if (!r.ok) { file.load(); return { ok: false as const, issues: [] }; }
    void Editor.Message.request('asset-db', 'refresh-asset', `db://assets/script/game/common/config/${allSchemas().find(s => s.id === id)!.sourceFile}`);
    return { ok: true as const, issues: [] };
  },
  revertRecord: (id: TableId, key: string) => { getTable(id).file.load(); return getTable(id).file.read(key); },
  reloadAll: () => { for (const k of Object.keys(fileCache)) fileCache[k].load(); },
};

说明：saveRecord 采用"先 patch 到内存 → 校验该 key 的 error → 有则 load 回滚 → 否则 save"。这保证保存被 error 阻断时不落盘。Plan B 再加 add/delete + HeroList 写同步。

  • Step 2: 提交
git add extensions/pixelhero-config-editor/src/main/store.ts
git commit -m "feat(config-editor): main-process store (in-memory truth + message impls + asset-db refresh)"

Task 12: 扩展入口 + 最小面板（端到端 IPC 证明）

Files:

  • Create: extensions/pixelhero-config-editor/src/main/index.ts

  • Create: extensions/pixelhero-config-editor/src/panels/default/index.ts

  • Create: extensions/pixelhero-config-editor/src/panels/default/app.ts

  • Create: extensions/pixelhero-config-editor/static/template/default/index.html

  • Create: extensions/pixelhero-config-editor/static/style/default/index.css

  • Step 1: 写入口 src/main/index.ts（注册消息→store）

Cocos 3.x 消息回复机制（已核实）： 主进程消息处理函数的返回值即 Editor.Message.request(...) 的 Promise resolve 值（3.x 起，无需 event.reply；旧式 event.reply 仍兼容但非首选）。异步处理函数可直接返回 Promise。handler 签名为 (event, ...args)，此处不使用 event。验证点： 若面板收到 undefined 响应，先回到 https://docs.cocos.com/creator/3.8/manual/en/editor/extension/messages.html 核对，必要时改为 event.reply(result)。

import { store } from './store';

module.exports = {
  onLoad() { store.reloadAll(); },

  'open-panel'() { Editor.Panel.open('pixelhero-config-editor'); },

  'query-schema'(_event: unknown, id?: string) { return store.querySchema(id as any); },
  'query-enums'() { return store.queryEnums(); },
  'query-keys'(_event: unknown, id: string) { return store.queryKeys(id as any); },
  'query-record'(_event: unknown, id: string, key: string) { return store.queryRecord(id as any, key); },
  'query-preview-desc'(_event: unknown, hero: any) { return store.queryPreviewDesc(hero); },
  'validate'(_event: unknown, id: string) { return store.validate(id as any); },
  'save-record'(_event: unknown, id: string, key: string, value: any) { return store.saveRecord(id as any, key, value); },
  'revert-record'(_event: unknown, id: string, key: string) { return store.revertRecord(id as any, key); },
};
  • Step 2: 写面板宿主 static/template/default/index.html
<div id="app" style="padding:12px;"></div>
  • Step 3: 写面板样式 static/style/default/index.css
#app { color: var(--color-font-normal); font-size: 12px; }
.row { margin: 6px 0; }
button { margin-right: 8px; }
ul { list-style: none; padding: 0; max-height: 360px; overflow:auto; }
li { padding: 3px 6px; cursor: pointer; }
li:hover { background: var(--color-hover-bg); }
.err { color: var(--color-warn); }
  • Step 4: 写最小 Vue app src/panels/default/app.ts
import { createApp, defineComponent, reactive } from 'vue';

export const App = defineComponent({
  setup() {
    const state = reactive({ table: 'hero' as string, keys: [] as string[], picked: '' as string, detail: '' as string });
    async function load() {
      const keys = await Editor.Message.request('pixelhero-config-editor', 'query-keys', state.table);
      state.keys = keys || [];
      state.picked = ''; state.detail = '';
    }
    async function pick(k: string) {
      state.picked = k;
      const v = await Editor.Message.request('pixelhero-config-editor', 'query-record', state.table, k);
      state.detail = JSON.stringify(v, null, 2);
    }
    load();
    return { state, load, pick };
  },
  template: `
    <div>
      <div class="row">
        <label>表：</label>
        <select v-model="state.table" @change="load">
          <option value="hero">英雄/怪物</option>
          <option value="skill">技能</option>
          <option value="field">驻场技能</option>
        </select>
        <span style="margin-left:12px;color:#888">共 {{ state.keys.length }} 条（端到端 IPC 已打通）</span>
      </div>
      <ul>
        <li v-for="k in state.keys" :key="k" @click="pick(k)" :style="state.picked===k ? 'font-weight:bold' : ''">{{ k }}</li>
      </ul>
      <pre v-if="state.detail" style="white-space:pre-wrap;background:var(--color-normal-fill);padding:8px">{{ state.detail }}</pre>
    </div>
  `,
});

export function mount(el: HTMLElement) { createApp(App).mount(el); }
  • Step 5: 写面板入口 src/panels/default/index.ts
import { readFileSync } from 'node:fs';
import { join } from 'node:path';
import { mount } from './app';

const template = readFileSync(join(__dirname, '../../../static/template/default/index.html'), 'utf-8');
const style = readFileSync(join(__dirname, '../../../static/style/default/index.css'), 'utf-8');

module.exports = Editor.Panel.define({
  template,
  style,
  $: { app: '#app' },
  ready() { mount(this.$.app); },
  close() { /* Vue 卸载随面板进程退出自动清理 */ },
});
  • Step 6: 打包
cd extensions/pixelhero-config-editor && npm run build

Expected: 生成 dist/main.js 与 dist/panels/default.js，无错误。

  • Step 7: 提交
git add extensions/pixelhero-config-editor/src/main/index.ts extensions/pixelhero-config-editor/src/panels extensions/pixelhero-config-editor/static
git commit -m "feat(config-editor): extension entry + minimal Vue panel proving end-to-end IPC"

Task 13: 全套测试 + 手动集成验证

  • Step 1: 跑全部单元测试
cd extensions/pixelhero-config-editor && npx tsx --test __tests__/*.test.ts

Expected: 全部 PASS（serializer/parser/tsConfigFile/validation/buildSkillDesc）。记录通过数到 production/qa/evidence/（见 Step 3）。

  • Step 2: 打包扩展
npm run build

Expected: dist/main.js、dist/panels/default.js 生成成功。

  • Step 3: 写手动验证证据 production/qa/evidence/2026-06-20-config-editor-plan-a.md
# 配置编辑器 Plan A — 验证证据

## 自动化测试（BLOCKING）
- 命令：`npx tsx --test __tests__/*.test.ts`
- 结果：[填写通过用例数] / 全部 PASS
- 覆盖：序列化、解析（speed/enumRef/raw）、TsConfigFile 往返（load/patch/add/delete/save + .bak + 语法校验）、校验规则、buildSkillDesc 移植。

## 编辑器内集成（ADVISORY）
1. Cocos Creator → 扩展管理器 → 重载 `pixelhero-config-editor`。
2. 菜单"面板 → 英雄技能配置"打开面板。
3. 截图：面板可见，下拉切换 hero/skill/field，列表显示真实 uuid（hero 表应含 5011/5012/.../6106 等），点选任一条右侧显示结构化 JSON（含 `cd` 为 `{kind:'speed',level:'Slow3'}`、`fac` 为 `{kind:'enumRef',...}`）。
4. 结论：端到端 IPC 打通，IO 正确解析真实 `heroSet.ts`/`SkillSet.ts`。
  • Step 4: 提交证据
cd ../..
git add production/qa/evidence/2026-06-20-config-editor-plan-a.md
git commit -m "test(config-editor): record Plan A verification evidence"

Plan A 完成标准（Definition of Done）

  1. 扩展可被 Cocos 3.8.6 加载，菜单可打开面板。
  2. IO 层对真实 heroSet.ts/SkillSet.ts 正确解析（含 speed 表达式与枚举引用）。
  3. patch 一条英雄保存后：磁盘文件更新且为合法 TS；其他条目与符号表达式原样保留；.bak 已生成；asset-db 已刷新。
  4. 校验层对各类非法数据正确报错（error 级阻断保存）。
  5. 全部单元测试 PASS（BLOCKING）。
  6. 未改动 assets/script/game/** 任何游戏运行时代码。

Plan B 预告（下一计划）

完整 UI：master-detail 布局、schema 驱动的字段表单（含 enum/ref/speedExpr 控件）、嵌套编辑器（TriggerSlots/SkillMap/FieldList/Revive/Override）、描述实时预览、校验面板、新建/复制/删除、HeroList 写同步、还原。Plan B 仅新增/改动 src/panels/** 与 store 的 add/delete 消息；逻辑层（Plan A）无需改动。

自审（Self-Review）

1. Spec 覆盖： Plan A 覆盖 spec §4（五层架构中的 IO/校验/schema/主进程）、§5.1–5.4、§7（消息，除 add/delete/record-changed 列入 Plan B）、§11（测试）。§5.5 完整 UI 与 §14.5–14.6（新建/删除/HeroList）显式归入 Plan B —— 已在"范围"声明。无遗漏。

2. 占位符扫描： 各步均含完整代码或确切命令；无 TBD/TODO/"适当处理"等。

3. 类型一致性： RecordValue 各 kind（num/str/bool/enumRef/speed/obj/arr/raw）在 parser/serializer/validation/buildSkillDesc/store 中使用一致；TsConfigFile 方法签名（load/getKeys/read/patch/add/delete/save/getText/isDirty）跨任务一致；TableId = 'hero'|'skill'|'field'、FieldSchema、ENUMS、validate/ValidationContext/Issue 在任务间命名一致。serializeEntry 首行无缩进的约定（Task 4 测试 + Task 8 实现一致）。

4. 已知简化（相对 spec）： v1 不输出 info 行注释（避免 patch 注释重复，已声明）；add/delete 记录与 HeroList 写同步归 Plan B；record-changed 广播归 Plan B（Plan A 单面板无需）。

Reference in New Issue View Git Blame Copy Permalink