f59991b9f3
- core 协议:Plugin 接口/注册器(重名拒绝/生命周期正序逆序/dispose幂等/错误隔离不连坐)+受控面 PluginContext(禁直透 littlejsengine)——前任agent核心设计17测绿收编(死于收尾的工具调用解析失败,续作字节级未碰) - _example 空插件样例五件全(克隆母本)+PLUGIN-TEMPLATE 六节规格+manifest schema+零依赖校验器(负例自检逮6违规) - scripts:esbuild锁参build/增量法size/test.sh遍历;browser-evidence harness纯计算口径冻结(FNV-1a/直方图/几何,CDP四函数=集成段占位) - 22/22 测全绿(RESULT.txt 留档);ESM JS+JSDoc+手写d.ts 零工具链纪律全程 - rc 状态:待 Gate0.1 受控面补丁(input/audio+per-plugin派生RNG+useContext守卫)后冻结 core-protocol-v0 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
70 lines
3.6 KiB
TypeScript
70 lines
3.6 KiB
TypeScript
/**
|
||
* _example/api.d.ts — 空插件样例的公开类型门面（手写，对齐 core-protocol-v0）
|
||
* owner：T1b-α lane-core（Gate0 奠基件 · 可直接克隆为新插件骨架）
|
||
* 消费方：所有 lane（读本件了解「一个插件的 d.ts 该长什么样」）+ 集成段 host
|
||
*
|
||
* 【本件定位】
|
||
* 这是「最小空插件」的类型契约样板。它不含任何玩法语义，只演示：
|
||
* 1) 如何复用 core 的 Plugin / PluginContext 类型（从 ../../core/api.d.ts 引入）；
|
||
* 2) 一个插件工厂函数（createXxxPlugin）的对外签名应如何手写声明；
|
||
* 3) manifest.json 的 exports.named 与本件导出的具名符号如何一一对应。
|
||
* 克隆新插件时：复制本目录 → 改 name/版本/能力面，d.ts 的写法照搬。
|
||
*
|
||
* 【受控面铁律（继承自 core）】
|
||
* 插件只经 PluginContext 的 4 项受控面（getContext2d/onFrame/time/random）拿引擎能力，
|
||
* 绝不直透 littlejsengine 裸对象 —— 本样例严格示范此约束。
|
||
*/
|
||
|
||
// 复用 core 的协议类型，不在插件层重复定义（单一事实源 = core/api.d.ts）。
|
||
import type { Plugin, PluginContext } from '../../core/api.d.ts';
|
||
|
||
/**
|
||
* 创建一个空插件实例（样例工厂）。
|
||
*
|
||
* 该插件 init 时仅做「无害的受控面演示」：
|
||
* - 经 ctx.onFrame 注册一个逐帧回调，用 ctx.time / ctx.random 累计无副作用的内部计数；
|
||
* - 经 ctx.getContext2d 尝试取 2D 上下文，取不到（node 侧为 null）即安全降级；
|
||
* - dispose 时撤销帧回调并复位内部状态（幂等：重复 dispose 安全）。
|
||
* 它不渲染玩法、不改全局、不假设任何品类 —— 纯协议用法演示。
|
||
*
|
||
* @param opts 可选配置：仅演示「插件可接受自身配置」这一模式，无玩法含义。
|
||
* @returns 一个实现 core Plugin 接口的插件对象，可直接 register 进 PluginRegistry。
|
||
*/
|
||
export declare function createExamplePlugin(opts?: ExamplePluginOptions): ExamplePlugin;
|
||
|
||
/** 空插件的可选配置（仅示范「插件可带配置」，字段无玩法语义）。 */
|
||
export interface ExamplePluginOptions {
|
||
/**
|
||
* 演示用的初始随机种子。给定时，插件 init 会对 ctx.random.reseed(seed)，
|
||
* 使「样例帧回调里取的随机序列」确定可复现（示范取证友好写法）。缺省不重设种子。
|
||
*/
|
||
seed?: number;
|
||
}
|
||
|
||
/**
|
||
* 空插件实例类型 —— 即 core Plugin，外加样例自暴露的只读探针字段，
|
||
* 便于单测断言「受控面确实被驱动」（生产插件可不暴露此类内省字段，这里仅为可测性示范）。
|
||
*/
|
||
export interface ExamplePlugin extends Plugin {
|
||
/**
|
||
* 只读探针：返回插件内部累计状态快照（帧数 / 最近一次随机值 / 是否拿到 2D 上下文）。
|
||
* 仅供测试与诊断观察，**不是**插件对玩法层的能力面（生产插件按需删除）。
|
||
*/
|
||
readonly probe: () => ExampleProbeSnapshot;
|
||
}
|
||
|
||
/** 样例探针快照（仅测试/诊断用）。 */
|
||
export interface ExampleProbeSnapshot {
|
||
/** init 后经由 onFrame 累计被驱动的帧数。 */
|
||
frames: number;
|
||
/** 最近一帧用 ctx.random.next() 取到的随机值（未驱动过为 null）。 */
|
||
lastRandom: number | null;
|
||
/** init 时 ctx.getContext2d() 是否返回了非 null 上下文（node 侧通常 false）。 */
|
||
hasContext2d: boolean;
|
||
/** 是否已 dispose（幂等观察用）。 */
|
||
disposed: boolean;
|
||
}
|
||
|
||
// 同时把复用的协议类型再导出，方便克隆者「只 import 本插件 d.ts」即可拿到全套类型。
|
||
export type { Plugin, PluginContext } from '../../core/api.d.ts';
|