zizi 6f854851f5 feat(game-runtime): core-protocol-v0 冻结(Gate0.1 受控面补丁,38/38 绿)

- 受控面 v0 六项冻结:getContext2d/onFrame/getInput/getAudioContext/time/random
- getInput=归一化事件订阅面(5枚举,host注入桥+_emit测试口,dispose自动清理防泄漏);getAudioContext=lazy单例无工厂返null告警降级
- per-plugin 派生随机流(FNV-1a子种子,序列互不影响同seed复现,向后兼容回退);useContext 守卫(友好错误带插件名)
- 向后兼容增量不bump版本;manifest schema 未动;三 lane 按此冻结面开工

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

2026-06-12 11:28:52 +00:00

3.7 KiB

Raw Blame History

PLUGIN.md 规格模板（core-protocol-v0）

owner：T1b-α lane-core（Gate0 奠基件）｜消费方：所有 lane 写插件文档时照此结构 + agent 读插件能力时按此找信息。 这是「插件使用文档」的固定骨架：每个插件目录下的 PLUGIN.md 必须包含下列六节，章节标题与顺序不变（便于 agent / 索引脚本机器读取）。活样板见 src/plugins/_example/PLUGIN.md。

为什么需要统一规格

插件库是「给 agent 造游戏用的能力面」。agent 不读源码，只读 PLUGIN.md 决定「这个插件能干什么、怎么接、边界在哪」。
文档结构不统一 → agent 找信息成本高、易误用。固定六节 = 让每个插件的能力面以同一形状被检索。
与 manifest.json（机器契约）互补：manifest 给「名称/版本/字节预算/导出入口」等结构化元数据；PLUGIN.md 给「人/agent 读的能力说明与用法」。两者的 name/version 必须一致。

必含六节（标题照抄，顺序不变）

1. 能力（Capabilities）

一句话定位 + 能力清单。engine 级、无玩法语义（不得出现「金币/敌人/关卡/商店」等品类词；只说「碰撞查询/粒子发射/调色映射」等引擎能力）。

写清：这个插件提供哪些可调用的能力面；
写清：不提供什么（划清与「agent 生成域 = 玩法/美术成品/关卡/UI」的边界）。

2. 集成点（Integration）

插件如何接入宿主与受控面。必须覆盖：

依赖：dependencies 声明了哪些其它插件（无则写「无」）；
受控面用法：用到 PluginContext 的哪几项（getContext2d/onFrame/getInput/getAudioContext/time/random；Gate0.1 由 4 扩 6），各自用途；
注册方式：registry.register(createXxxPlugin(opts)) 的标准接法；
配置项：工厂 opts 的字段与含义（无则写「无配置」）。

3. 示例（Usage）

最小可跑代码片段（ESM）。展示：构造受控上下文（host-dev：createHostDevContext）→ register → initAll → 驱动（tick/或集成段引擎主循环）→ disposeAll。片段须与该插件 test/ 下的真实测试用法一致，不得是「伪代码」。

4. 测试（Test）

测试文件路径 + 运行命令（node --test <path>）；
覆盖了哪些性质（确定性/边界/错误隔离/生命周期…）；
node 层测什么、什么留到集成段浏览器证据（vfx/audio 类插件尤其要写清「渲染/发声哈希在集成段 harness 出」）。

5. 边界与字节预算（Boundaries & Budget）

字节预算：gzBudgetBytes（与 manifest 一致）；超配额触发评审（执行版 §5）；
行为边界：null 渲染环境如何降级、错误如何隔离、不做什么（如「不做拓扑重排」「不内置成品色板」）；
受控面铁律：声明「只经 PluginContext 拿引擎能力，绝不直透 littlejsengine 裸对象」。

6. v2 声明（v2 Notes）

本版（v1 / seed）刻意未做、留给后续的能力或扩展点，逐条列出（YAGNI 边界透明化）。无则写「本版能力已闭环，暂无 v2 待办」。

写作约束

全文简体中文；标题用上述中文节名（括号内英文仅本模板示意，正文 PLUGIN.md 可省略英文）。
不堆术语、不写营销话术；以「agent 能照着接上」为唯一标准。
任何代码片段必须能跑（与 test/ 真实用法对齐），不放无法验证的示例。
与 manifest.json 的 name/version/dependencies/gzBudgetBytes 保持一致，冲突时以 manifest（机器契约）为准并在此修正。

3.7 KiB Raw Blame History Unescape Escape