games-development-ai/.agents/skills/plugin-capability-map.md

插件能力图谱 —— 注入了什么、储备着什么、为什么

便宜档生成 agent 只能用已注入的插件（经 plugins.<键> 取，不能 import）。这份图谱回答：现在桌上有哪 11 件、 每件去哪读详细用法、还有哪些造好了但没摆上桌、以及为什么没摆。改这里的裁定要同步改机器门 .agents/tools/plugin-surface-gate.py 的台账常量（三方一致性它会自动对账）。

已注入的 11 件（plugins.<键> 直接用）

方法头部选型见 littlejs-game-dev.md §4；精确签名读各插件 api.d.ts；用法散文 + 集成注意读各插件 PLUGIN.md（比 api.d.ts 多了「怎么装、坑在哪、示例」）。

键	目录	一句话能力	详细读
sceneFsm	scene-fsm	场景/状态机（menu→play→over）	game-runtime/src/plugins/scene-fsm/{api.d.ts,PLUGIN.md}
sessionScore	session-score	计分 + 胜负闸	game-runtime/src/plugins/session-score/{api.d.ts,PLUGIN.md}
hudUi	hud-ui	HUD/UI 绘制 + 命中判定	game-runtime/src/plugins/hud-ui/{api.d.ts,PLUGIN.md}
timerScheduler	timer-scheduler	受控时钟调度（毫秒）	game-runtime/src/plugins/timer-scheduler/{api.d.ts,PLUGIN.md}
save	save-progress	KV 持久化（最佳分等）	game-runtime/src/plugins/save-progress/{api.d.ts,PLUGIN.md}
gamefeel	gamefeel	手感：缓动 + 输入缓冲 + coyote/combo	game-runtime/src/plugins/gamefeel/{api.d.ts,PLUGIN.md}
juice	particles-juice	粒子 + 打击感（顿帧/震屏/闪白）	game-runtime/src/plugins/particles-juice/{api.d.ts,PLUGIN.md}
palettePost	palette-post	调色 + 后处理（预设一键观感）	game-runtime/src/plugins/palette-post/{api.d.ts,PLUGIN.md}
audioMusic	audio-music	程序化音乐 + 语义音效	game-runtime/src/plugins/audio-music/{api.d.ts,PLUGIN.md}
collision	collision	碰撞查询（纯数学）	game-runtime/src/plugins/collision/{api.d.ts,PLUGIN.md}
physics	physics-lite	街机运动原语（非刚体）	game-runtime/src/plugins/physics-lite/{api.d.ts,PLUGIN.md}

runtime-probe（取证不注入）：只在收口取证六锚（启动耗时等），不进 plugins 面，生成 agent 用不到。

仅 puzzle L1 的受保护注入（3 件）

match3-producer-profile 不是第 12 个通用插件。它只在 _template-puzzle/src/host-config.js 收到显式 match3.orthogonal-swap-v1 时由 L1 实例化，以 plugins.match3ProducerProfile 给 Match-3 Writer 调用；普通 puzzle、 其它品类、通用 _template、all-plugins 与 cheap-system 白名单都不注入。该能力冻结 390×844 / 8×8 / 40px 棋格几何、472 像素 selection mask 和主题安全区， 同一实例再由 __genHost.readProducerCapabilityProbe() 进入可信 preflight。L3 _forensicsView 或页面全局自报不参与身份判断。

match3-visual-timeline 同样只在显式 match3.orthogonal-swap-v1 下创建，以 plugins.match3VisualTimeline 注入，并与 producer 一起进入 registerOrder。它根据标准 0-based 8×8 kindToken 快照 独立分配稳定 pieceId，封存 Match3VisualTransaction/1，推导消除、列压实与顶部补位，按固定阶段输出 1-based 视觉棋子并用 isLocked() 统一锁住第二击后的额外输入。它拥有独立 id/version/configHash，绝不修改 match3ProducerProfile 已校准的身份。visualTimelineCapability 已从 host-config 独立返回；可信 host probe 与 runner visualDrain/Proof/3 接线属于后续 contract-first 实现线，本次不冒充已完成。

match3-audio-director 只在同一标准 Match-3 profile 下由 L1 以冻结 Match3AudioTheme/1 和同一份 visual timeline 实例创建。它进入 registerOrder 并以 audioDirectorCapability 单独返回给可信 host，但不写入 L3 plugins；标准 Match-3 的 audioMusic 同样从 L3 门面移除。导演独占包内 BGM、交换/回滚/逐轮消除/下落/终局 cue、master 静音与只读 probe，按 host-only transition 账调度，避免游戏自制音效、同步连锁叠音或双 BGM 图。

这类“品类专用且影响验收像素”的能力必须登记在机器门 PROTECTED_INJECTION_DIRS，不能为了通过目录门而塞进 通用 11 件，也不能降成储备。机器门同时核对唯一模板、plugins 注入、registerOrder 与各自能力返回键， 并拒绝其它官方模板出现同一目录或键。新增受保护品类能力时，必须同时写清唯一模板入口、Writer 调用键、可信读口和未注入范围。

未注入的能力储备（6 件·造好了但没摆上桌）

这 6 件都是通过测试的真插件（各有 api.d.ts/impl.js/test），但当前 5 个注入品类（经营/剧情/TRPG/解谜/非遗）全是 点击/回合制 tap 玩法，它们服务的是别的品类或需要额外装配，故本波不注入。生成 agent 现在读不到、也用不了它们—— 别在 game-logic 里写 plugins.autoTargeting 之类，会是 undefined。每件的裁定依据与「什么时候该注入」：

目录	是什么	为什么没注入	注入触发条件
auto-targeting	索敌策略族（最近/锥内/随机选目标）	服务射击/动作类「自动锁敌」，当前 tap 品类用不上	W-GENRE 上动作/射击品类时
swarm-steering	均匀网格 + 群体运动学（同屏千级实体）	服务动作/idle-sim 的大规模实体，tap 品类无此需求	W-GENRE 上动作或放置模拟品类时
entity-pool	对象池 + swap-remove（局内零 GC）	密集实体（子弹/敌群）性能件；粒子已由 particles-juice 承接	同上，动作品类需要密集实体时
virtual-joystick	浮动原点虚拟摇杆 + 轨迹 driver	连续移动输入，与当前 handleTap 输入契约不同轴；tap 品类不需要	W-GENRE 上需要连续移动/瞄准的品类，且输入契约扩展后
canvas-ui-kit	卡片选择器 / 滚动列表 / 顶栏（hud-ui 之上的组合件）	需 draw: hudUi 复合装配；对 TRPG 选天赋、经营选货有价值，但注入是行为面变更	后续给 TRPG/经营注入的首选候选——单起一个装配任务，同步 3 方对账
hit-feedback	反馈档位编排（一次事件→顿帧/震屏/音效/飘字）	需 juice + sfx 复合装配；与直调 juice+audioMusic 重叠，skill/settlement recipe 已教直调	若要把反馈收敛成单入口 + 音画同帧取证时

把任一储备提升为通用注入 = 改 6 个 _template*/src/host-config.js 的 plugins 装配 + prompt 白名单（cheap-system.md）+ tools.mjs PLUGIN_KEY_DIR，三处同改、再跑 plugin-surface-gate.py 验三方对齐。品类专用受保护注入不走这条通用扩面路径，须登记 PROTECTED_INJECTION_DIRS 并只改其唯一 L1 模板。gate 会拦「注入了但白名单漏列」「白名单列了但没注入」「受保护品类件误进通用面」「新插件目录没裁定」。