# 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（机器契约）为准并在此修正。