@playcraft/common 0.0.27 → 0.0.29

package/dist/recommend/atom-graph/remix-examples.js

@@ -0,0 +1,192 @@
+/** 与 `basicAtomGraph` 对齐的示意 Remix：每条为一条 plausible 生产闭包（引擎→玩法→素材/音频/配置→包装→校验）。 */
+export const basicAtomRemixExamples = [
+    {
+        id: 'remix_fake_game_match3',
+        label: { zh: 'FakeGame 三消稿', en: 'FakeGame match-3 creative' },
+        primaryGameplayId: 'match3',
+        atomIds: [
+            'phaser',
+            'grid_puzzle_framework',
+            'match3',
+            'jewel_tile_set',
+            'background_image',
+            'ui_button_set',
+            'win_lose_panel',
+            'casual_bgm',
+            'match_sfx',
+            'win_sfx',
+            'board_size',
+            'move_limit',
+            'scoring_rule',
+            'camera_preset',
+            'fake_game_packaging',
+            'asset_reference_check',
+            'creative_size_check',
+            'semantic_consistency_check',
+            'build_smoke_test',
+            'playable_runtime_check',
+        ],
+    },
+    {
+        id: 'remix_runner_collect_fake',
+        label: { zh: '跑酷收集 FakeGame', en: 'Runner collect FakeGame' },
+        primaryGameplayId: 'runner_collect',
+        atomIds: [
+            'phaser',
+            'casual_2d_framework',
+            'runner_collect',
+            'character_sprite',
+            'background_image',
+            'ui_button_set',
+            'win_lose_panel',
+            'casual_bgm',
+            'collision_sfx',
+            'win_sfx',
+            'level_timer',
+            'scoring_rule',
+            'camera_preset',
+            'fake_game_packaging',
+            'asset_reference_check',
+            'creative_size_check',
+            'semantic_consistency_check',
+            'build_smoke_test',
+            'playable_runtime_check',
+        ],
+    },
+    {
+        id: 'remix_iq_sort_puzzle',
+        label: { zh: 'IQ 分类排序稿', en: 'IQ sort puzzle' },
+        primaryGameplayId: 'sort_puzzle',
+        atomIds: [
+            'phaser',
+            'grid_puzzle_framework',
+            'sort_puzzle',
+            'fruit_tile_set',
+            'background_image',
+            'ui_button_set',
+            'win_lose_panel',
+            'casual_bgm',
+            'match_sfx',
+            'win_sfx',
+            'board_size',
+            'move_limit',
+            'difficulty_curve',
+            'camera_preset',
+            'iq_test_packaging',
+            'asset_reference_check',
+            'creative_size_check',
+            'semantic_consistency_check',
+            'build_smoke_test',
+            'playable_runtime_check',
+        ],
+    },
+    {
+        id: 'remix_iq_pin_puzzle',
+        label: { zh: 'IQ 拉针稿', en: 'IQ pin puzzle' },
+        primaryGameplayId: 'pin_puzzle',
+        atomIds: [
+            'phaser',
+            'casual_2d_framework',
+            'pin_puzzle',
+            'direction_arrow_sprite',
+            'background_image',
+            'ui_button_set',
+            'win_lose_panel',
+            'tension_bgm',
+            'collision_sfx',
+            'win_sfx',
+            'difficulty_curve',
+            'level_timer',
+            'camera_preset',
+            'iq_test_packaging',
+            'asset_reference_check',
+            'creative_size_check',
+            'semantic_consistency_check',
+            'build_smoke_test',
+            'playable_runtime_check',
+        ],
+    },
+    {
+        id: 'remix_doctor_word_puzzle',
+        label: { zh: '医生建议 文字解谜', en: 'Doctor advice word puzzle' },
+        primaryGameplayId: 'word_puzzle',
+        atomIds: [
+            'phaser',
+            'grid_puzzle_framework',
+            'word_puzzle',
+            'ui_button_set',
+            'background_image',
+            'win_lose_panel',
+            'casual_bgm',
+            'win_sfx',
+            'move_limit',
+            'board_size',
+            'scoring_rule',
+            'camera_preset',
+            'doctor_advice_packaging',
+            'asset_reference_check',
+            'creative_size_check',
+            'semantic_consistency_check',
+            'build_smoke_test',
+            'playable_runtime_check',
+        ],
+    },
+    {
+        id: 'remix_showcase_eight_ball',
+        label: { zh: '玩法展示 台球', en: 'Gameplay showcase 8-ball' },
+        primaryGameplayId: 'eight_ball',
+        atomIds: [
+            'phaser',
+            'physics_ball_framework',
+            'eight_ball',
+            'billiard_ball_set',
+            'pool_table_skin',
+            'background_image',
+            'ui_button_set',
+            'win_lose_panel',
+            'casual_bgm',
+            'collision_sfx',
+            'win_sfx',
+            'scoring_rule',
+            'camera_preset',
+            'gameplay_showcase_packaging',
+            'asset_reference_check',
+            'creative_size_check',
+            'semantic_consistency_check',
+            'build_smoke_test',
+            'playable_runtime_check',
+        ],
+    },
+    {
+        id: 'remix_showcase_tetris',
+        label: { zh: '玩法展示 方块', en: 'Gameplay showcase Tetris-like' },
+        primaryGameplayId: 'tetris',
+        atomIds: [
+            'phaser',
+            'grid_puzzle_framework',
+            'tetris',
+            'block_skin_set',
+            'background_image',
+            'ui_button_set',
+            'win_lose_panel',
+            'tension_bgm',
+            'collision_sfx',
+            'win_sfx',
+            'gravity_mode',
+            'difficulty_curve',
+            'camera_preset',
+            'gameplay_showcase_packaging',
+            'asset_reference_check',
+            'creative_size_check',
+            'semantic_consistency_check',
+            'build_smoke_test',
+            'playable_runtime_check',
+        ],
+    },
+];
+/** 返回 `atomIds` 中在图中不存在的 id（用于测试或导入校验）。 */
+export function collectUnknownRemixAtomIds(graph, example) {
+    const ids = new Set(graph.nodes.map((n) => n.id));
+    return example.atomIds.filter((id) => !ids.has(id));
+}
+//# sourceMappingURL=remix-examples.js.map

package/dist/recommend/atom-graph/remix-examples.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remix-examples.js","sourceRoot":"","sources":["../../../src/recommend/atom-graph/remix-examples.ts"],"names":[],"mappings":"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"}

package/dist/recommend/atom-graph/types.d.ts

@@ -0,0 +1,323 @@
+export type AtomCategory = 'engine' | 'gameplay' | 'visual' | 'audio' | 'config' | 'packaging' | 'validator' | 'layout' | 'scene' | 'state' | 'component' | 'build' | 'util';
+export type AtomMode = 'fixed' | 'parametric' | 'generative';
+export type AtomEdgeKind = 'requires' | 'compatibleWith' | 'semanticallyRelatedTo' | 'alternativeTo';
+export type AtomBindingRole = 'gameEngine' | 'playableSdk' | 'buildPipeline' | 'responsiveLayout' | 'gridBoardLayout' | 'sceneLifecycle' | 'preloaderScene' | 'gameMainScene' | 'userSettings' | 'themeManager' | 'levelProgress' | 'runContext' | 'gameplayRule' | 'levelDataFormat' | 'pathBatchRenderer' | 'pathAnimationDirector' | 'boardInputHandler' | 'levelLifecycleController' | 'directionalIndicator' | 'boardBackgroundTexture' | 'successFeedbackPanel' | 'failFeedbackPanel' | 'dangerFlashOverlay' | 'appLogo' | 'tutorialPointer' | 'clockIcon' | 'winParticleAsset' | 'normalParticleAsset' | 'bgMusic' | 'sfxClick' | 'sfxAppear' | 'sfxSuccess' | 'sfxFail' | 'sfxLose' | 'sfxMistake' | 'sfxWinAnim' | 'sfxArrowMoveError' | 'sfxButtonClick' | 'loadingScreen' | 'topUiBar' | 'countdownTimer' | 'livesIndicator' | 'comboDisplay' | 'comboPraiseText' | 'progressBar' | 'downloadCta' | 'gameOverDialog' | 'tutorialOverlay' | 'digitGlyphRenderer' | 'audioPlayHelper' | 'levelDataPack' | 'themeVariantConfig' | 'appMetadata' | 'engineRuntime' | 'frameworkRuntime' | 'backgroundTexture' | 'tileTextureSet' | 'vehicleSpriteSet' | 'billiardBallSet' | 'poolTableSkin' | 'blockSkinSet' | 'bubbleSkinSet' | 'characterSprite' | 'uiButtonSet' | 'resultPanel' | 'backgroundMusic' | 'soundEffect' | 'gameConfig' | 'packagingPattern' | 'validationGate';
+export type AtomNode = {
+    id: string;
+    category: AtomCategory;
+    mode: AtomMode;
+    label: {
+        zh: string;
+        en: string;
+    };
+    description?: string;
+    bindingRoles?: AtomBindingRole[];
+    tags?: string[];
+    skillRefs?: string[];
+};
+export type AtomEdge = {
+    from: string;
+    to: string;
+    kind: AtomEdgeKind;
+    label?: string;
+    weight?: number;
+};
+export type AtomGraph = {
+    id: string;
+    version: number;
+    status: 'prototype' | 'active' | 'deprecated';
+    description: string;
+    nodes: AtomNode[];
+    edges: AtomEdge[];
+};
+/** 示意性 Remix（试玩实例）原子闭包：用于可视化高亮或交付清单，非线上投放事实源。 */
+export type AtomRemixExample = {
+    id: string;
+    label: {
+        zh: string;
+        en: string;
+    };
+    /** 该实例主玩法 atom id（便于说明与排序） */
+    primaryGameplayId: string;
+    /** 属于该 Remix 的全部 Atom id */
+    atomIds: readonly string[];
+};
+export type AtomGraphValidationErrorCode = 'duplicate_node_id' | 'edge_missing_source' | 'edge_missing_target' | 'cycle_detected';
+export type AtomGraphValidationError = {
+    code: AtomGraphValidationErrorCode;
+    message: string;
+    nodeId?: string;
+    edge?: AtomEdge;
+};
+export type AtomGraphValidationWarningCode = 'gameplay_without_engine_path' | 'isolated_node' | 'invalid_edge_weight';
+export type AtomGraphValidationWarning = {
+    code: AtomGraphValidationWarningCode;
+    message: string;
+    nodeId?: string;
+    edge?: AtomEdge;
+};
+export type AtomGraphValidationResult = {
+    valid: boolean;
+    errors: AtomGraphValidationError[];
+    warnings: AtomGraphValidationWarning[];
+    topologicalOrder: string[];
+};
+/**
+ * 封包后缀类型，对应 asset-library 的 BUNDLE_SUFFIXES
+ *
+ * - aiimage / aiaudio / aiconfig / aigameplay：资源/配置/玩法，同原有用法
+ * - aicomponent：通用代码 skill（引擎/布局/场景/UI/状态/构建/工具等）
+ * - prefab：已废除，不要再使用，现有 prefab skill 已拆解为多个具体 skill
+ */
+export type AtomBundleType = 'aiimage' | 'aiaudio' | 'aiconfig' | 'aigameplay' | 'aicomponent';
+/**
+ * Recipe：怎么来的——生成过程的完整记录，支持复用和 fork。
+ * Agent 读取历史决策，修改后重新生成时写回。
+ */
+export type AtomRecipe = {
+    /** 生成类型（image / sfx / bgm / sprite-sheet / config-patch / level-data / theme-config / scaffold / pgs / ...） */
+    kind: string;
+    /**
+     * 关联的 Platform Skill 名称（在 packages/skills/platform-skills/ 下）。
+     * Agent 应读取该 skill 了解 CLI 用法，再结合本 manifest 的其他字段生成内容。
+     * - aiimage: "playcraft-image-generation"
+     * - aiaudio (bgm): "playcraft-audio-generation"
+     * - aiaudio (sfx): "playcraft-audio-generation"（同一 skill，命令不同）
+     */
+    platformSkill?: string;
+    /** 生成 prompt（generative 模式必填） */
+    prompt?: string;
+    /**
+     * AI 模型标识（使用 Platform Skill 中的 modelRef 格式，如 google/imagen-3.0-generate-002）
+     * 留空则使用平台默认配置
+     */
+    model?: string;
+    /** 参考图片路径（相对于 skill 目录，用于图生图） */
+    referenceImage?: string;
+    /** 参考音频路径（相对于 skill 目录，用于音频生成参考） */
+    referenceAudio?: string;
+    /** 随机种子，用于可复现生成 */
+    seed?: number;
+    /** 宽高比（图像封包），如 "1:1" | "9:16" | "16:9" */
+    aspectRatio?: string;
+    /** 风格约束（图像封包） */
+    style?: string;
+    /** 时长秒数（音频封包） */
+    duration?: number;
+    /** 是否循环（音频封包） */
+    loop?: boolean;
+    /** BGM 风格（bgm 类型） */
+    bgmStyle?: string;
+    /** BGM 节奏（bpm） */
+    bpm?: number;
+    /** parametric/fixed 模式的参数键值对 */
+    params?: Record<string, string | number | boolean>;
+    /** 其他扩展字段 */
+    [key: string]: unknown;
+};
+/**
+ * Result：是什么——生成产物的规格与引用。
+ * Agent 可直接引用，不必重新生成。
+ */
+export type AtomResult = {
+    /** 产物主文件名（相对于封包目录） */
+    outputFile?: string;
+    /** 文件格式 */
+    format?: string;
+    /** 尺寸与格式约束 */
+    constraints?: Record<string, number | string>;
+    /** 参数化配置的键路径（config 封包） */
+    configKey?: string;
+    /** 参数化配置的值 */
+    configValue?: string | number | boolean;
+    /** 其他扩展字段 */
+    [key: string]: unknown;
+};
+/**
+ * Binding：怎么用——接入 Prefab/DAG 的契约。
+ * Binding 由容器（Prefab）定义，不由 Atom 自身定义。
+ * Recipe + Result 可跨容器复用，Binding 需在新容器下重新生成。
+ */
+export type AtomBinding = {
+    /** binding role，对应 AtomBindingRole */
+    role: AtomBindingRole;
+    /** 目标挂载路径（scene:// URI 或文件路径） */
+    target: string;
+    /** 引用类型 */
+    type: string;
+    /** 约束条件（格式、尺寸等） */
+    constraints?: Record<string, number | string>;
+    /** 其他扩展字段 */
+    [key: string]: unknown;
+};
+/** Atom 实例在生产流水线中的状态 */
+export type AtomInstanceStatus = 'planned' | 'generating' | 'generated' | 'bound' | 'validated' | 'failed';
+/**
+ * AtomInstance：某次 Remix 生产中的具体 Atom。
+ * 对应一个已实例化（或待实例化）的封包。
+ */
+export type AtomInstance = {
+    /** 实例唯一 id */
+    instanceId: string;
+    /** 对应图节点 id（= skill 名称，例如 forest.aiimage） */
+    atomId: string;
+    /** 所属 Remix id */
+    remixId?: string;
+    /** 三要素：生成方式 */
+    recipe?: AtomRecipe;
+    /** 三要素：产物规格 */
+    result?: AtomResult;
+    /** 三要素：接入契约 */
+    binding?: AtomBinding;
+    /** 实例状态 */
+    status: AtomInstanceStatus;
+};
+/**
+ * Scaffold 文件贡献：描述一个 skill 向 Remix 项目贡献的某个文件的来源与合并策略。
+ * 文件路径 key 为相对 Remix 项目根目录的目标路径。
+ */
+export type ScaffoldContribution = {
+    /** scaffold 来源：Atom ref/ 目录内的相对路径，例如 "ref/PathRenderer.ts" */
+    source: string;
+    /**
+     * 贡献权重：组装时同一目标文件有多个贡献者时，按权重降序，最高者胜出。
+     * 默认 0。
+     */
+    weight?: number;
+    /**
+     * 贡献模式（默认 "full"）：
+     * - full：完整提供该文件
+     * - merge-json：JSON 文件按 deep-merge 合并（package.json / tsconfig.json 等）
+     * - anchor-insert：在已有文件的指定 anchor 注入代码片段
+     * - patch：提供 unified diff，应用到上一版本
+     */
+    mode?: 'full' | 'merge-json' | 'anchor-insert' | 'patch';
+    /** anchor-insert 模式时使用，如 "// @atom-insert: imports" */
+    anchor?: string;
+};
+/**
+ * Import 声明：此 skill 需要什么。
+ *
+ * 双形态：
+ * - 硬依赖（pinAtomId）：目标 skill 已知，无候选，组装时直接引入
+ * - 软槽位（matchBindingRoles + constraints）：目标从图谱候选实例中按权重选出
+ *
+ * 注意：具体如何根据声明选实例是图谱组装机制的职责（后续讨论）。
+ * manifest 中只需写清楚"要什么"即可。
+ */
+export type ImportDeclaration = {
+    /** 槽位名，在本 skill manifest 中唯一标识此 import */
+    slot: string;
+    /** 自然语言描述（给 LLM 和人理解用） */
+    description?: string;
+    /** scaffold 中引用此槽位选中实例的占位符标识 */
+    bindAs: string;
+    /** 是否必需，默认 true */
+    required?: boolean;
+    /** 边类型（默认：硬依赖用 requires，软槽位用 compatibleWith） */
+    edgeKind?: AtomEdgeKind;
+    /** 锁定具体 atomId（已知唯一目标）。与软槽位字段互斥。 */
+    pinAtomId?: string;
+    /** 候选筛选：实例必须有这些 bindingRoles 之一 */
+    matchBindingRoles?: AtomBindingRole[];
+    /** 候选筛选：实例的 category 限定 */
+    allowedCategories?: AtomCategory[];
+    /** 候选筛选：实例的 bundleType 限定 */
+    allowedBundleTypes?: AtomBundleType[];
+    /** 规格约束：用于过滤不合规候选 + LLM 验证（如 { directions: 4, minSize: {...} }） */
+    constraints?: Record<string, unknown>;
+    /** 选几个候选（默认 1） */
+    cardinality?: number | 'many';
+};
+/**
+ * AtomSkillManifest：packages/skills/skills/<atomId>/manifest.json 的 TypeScript 映射。
+ * 每个 Skill 目录下的 manifest 必须满足此类型。
+ *
+ * 字段分两类：
+ * - 身份信息（必填）：schemaVersion / atomId / bundleType / category / mode / label / tags / files
+ * - 内容描述（按 bundleType 选填）：
+ *   - aiimage / aiaudio / aiconfig / aigameplay 用 generation + result + binding（旧三要素）
+ *   - aicomponent 用 scaffold + imports + exports（新机制）
+ *   - 任意类型均可附 neutralDescriptor + usageHints + bindingRoles
+ */
+export type AtomSkillManifest = {
+    schemaVersion: 1;
+    /** 等于目录名，等于图节点 id，例如 forest.aiimage */
+    atomId: string;
+    /** 封包后缀类型 */
+    bundleType: AtomBundleType;
+    /** Atom 分类 */
+    category: AtomCategory;
+    /** 操作模式 */
+    mode: AtomMode;
+    /** 双语标签 */
+    label: {
+        zh: string;
+        en: string;
+    };
+    /** 索引和过滤标签（至少 1 个） */
+    tags: string[];
+    /** 语义角色标签：标识该 skill 是哪一类节点，用于候选召回和同类替代簇识别 */
+    bindingRoles?: AtomBindingRole[];
+    /** Recipe（生成方式模板）——aiimage / aiaudio / aiconfig / aigameplay 使用 */
+    generation?: AtomRecipe;
+    /** Result（产物规格模板）——aiimage / aiaudio / aiconfig / aigameplay 使用 */
+    result?: AtomResult;
+    /** Binding（接入契约模板）——aiimage / aiaudio / aiconfig / aigameplay 使用 */
+    binding?: AtomBinding;
+    /**
+     * Scaffold：该 skill 向 Remix 项目贡献的文件骨架。
+     * key 为相对 Remix 项目根目录的目标路径，value 为贡献描述。
+     */
+    scaffold?: {
+        files: Record<string, ScaffoldContribution>;
+        /** 合并到 package.json 的依赖与脚本 */
+        packageJson?: {
+            dependencies?: Record<string, {
+                version: string;
+                weight?: number;
+            }>;
+            devDependencies?: Record<string, {
+                version: string;
+                weight?: number;
+            }>;
+            scripts?: Record<string, {
+                command: string;
+                weight?: number;
+            }>;
+        };
+    };
+    /**
+     * Imports：声明该 skill 需要什么（双形态）。
+     * 具体候选实例如何选取由图谱组装机制决定（后续落地）。
+     */
+    imports?: ImportDeclaration[];
+    /** Exports：暴露给其他 skill 使用的符号 */
+    exports?: Array<{
+        /** 导出标识（其他 skill 通过 imports.bindAs 引用） */
+        name: string;
+        /** 符号类型：class / function / asset-key / route / scene-name 等 */
+        kind: string;
+        /** 在 scaffold 中的位置（用于编译期解析） */
+        location: string;
+    }>;
+    /**
+     * 中性描述：避免情境名词锁死 LLM 关联范围，提供纯几何/功能性描述。
+     * 见 agent-decision-mechanism.md §3。
+     */
+    neutralDescriptor?: {
+        geometry?: string;
+        layers?: string[];
+        replaceable?: string[];
+        material?: string;
+        [key: string]: unknown;
+    };
+    /** 使用提示（给人看，不进入 LLM 提示词） */
+    usageHints?: string[];
+    /** 关联文件 */
+    files: {
+        skill: 'SKILL.md';
+        [key: string]: string;
+    };
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/recommend/atom-graph/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/recommend/atom-graph/types.ts"],"names":[],"mappings":"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"}

package/dist/recommend/atom-graph/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/recommend/atom-graph/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/recommend/atom-graph/types.ts"],"names":[],"mappings":""}

package/dist/recommend/atom-graph/validate.d.ts

@@ -0,0 +1,7 @@
+import type { AtomEdge, AtomEdgeKind, AtomGraph, AtomGraphValidationResult, AtomNode } from './types.js';
+export declare function getAtomNode(graph: AtomGraph, nodeId: string): AtomNode | undefined;
+export declare function getAtomEdges(graph: AtomGraph, edgeKinds?: AtomEdgeKind[]): AtomEdge[];
+export declare function findAtomAncestors(graph: AtomGraph, nodeId: string, edgeKinds?: AtomEdgeKind[]): string[];
+export declare function topologicalSortAtomGraph(graph: AtomGraph, edgeKinds?: AtomEdgeKind[]): string[];
+export declare function validateAtomGraph(graph: AtomGraph): AtomGraphValidationResult;
+//# sourceMappingURL=validate.d.ts.map

package/dist/recommend/atom-graph/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../src/recommend/atom-graph/validate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EACR,YAAY,EACZ,SAAS,EAET,yBAAyB,EAEzB,QAAQ,EACT,MAAM,YAAY,CAAC;AAIpB,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAElF;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,EAAE,SAAS,CAAC,EAAE,YAAY,EAAE,GAAG,QAAQ,EAAE,CAIrF;AAED,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,SAAS,EAChB,MAAM,EAAE,MAAM,EACd,SAAS,GAAE,YAAY,EAAgC,GACtD,MAAM,EAAE,CAoBV;AAED,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,SAAS,EAChB,SAAS,GAAE,YAAY,EAAgC,GACtD,MAAM,EAAE,CAoCV;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,SAAS,GAAG,yBAAyB,CA4F7E"}