接口命名规范

接口名不是注释，而是契约的一部分。契约声明在 src/core/<插件>/contract.ts 中以字面量登记，构建期生成 RPM，运行期据此拒绝越出契约的 provide 与声明。名字写错不是「风格问题」，而是装载被拒绝。

本页对应插槽与实现位中的分类，只讨论名字；policy、基数与卸载行为是另外的声明项，不编码进名字。

六类名字总表

类别	模式	示例
大插件契约版本	<大插件名>@<主版本>	asset@1、scriptplay@1、save@1、platform@1
服务	<域>:<名>	asset:acquire、script:vm、save:slots、platform:host、text:view
通知	<域>:on-<事件>	asset:on-invalidate、save:on-load、script:on-choice、platform:on-ui-request、audio:on-track-end
机制插槽	<域>:<动词>-<对象>	asset:resolve-path、script:resolve-command、stage:resolve-composition、text:compute-measure、save:resolve-field
实现位	<域>:<名>@<主版本>	asset:decoder@1、stage:cast-renderer@1、save:backend@1、host:backend@1、battle:damage-pipeline@1
能力	caps:<名>	caps:fs-read、caps:net-fetch、caps:raw-bytes

字面规则

所有接口名按同一套机械规则校验（src/shared/contract-decl.ts）：

规则	说明
小写	只用小写字母、数字与连字符；不得出现大写、下划线或空格
域名段	以字母开头，只含小写字母与数字
名字段	以字母开头，可含数字与连字符；不得有连续连字符，不得以连字符结尾
分隔符	域与名之间用 :；版本用 @；版本只出现在实现位与契约版本末尾
主版本	从 1 开始的正整数，不得写 @0，不得省略

实现位下的条目名是另一层名字，由插件自行登记，约束较宽：小写字母或数字开头，可含点、下划线、连字符，最长 64 字符。例如 builtin、exact、canvas、indexeddb、webaudio、hca-pcm。条目名不是接口名，不要与实现位名混用。

契约版本

模式：<大插件名>@<主版本>。

示例	对应插件
asset@1	Asset 资源管线
scriptplay@1	ScriptPlay 剧本播放
save@1	Save 进度与存档
platform@1	Platform 宿主抽象
kernel@1	Kernel 内核

规则：

• 契约版本只写主版本，不写次版本或补丁号；次版本变化不改变接口名。
• 主版本只在不兼容变更时递增；装载器接受当前主版本与上一主版本（N-1 兼容窗口）。
• 契约声明中的 contract 必须与目录 id 一致，例如 asset 目录必须声明 asset@1。
• 数据包与资源包的 IR 版本另用 ir: "^N" 声明，不占用契约版本格式。

服务

模式：<域>:<名>。服务是可被调用、可被注入的能力；名字描述「能做什么」，不携带 policy。

示例	所属	说明
asset:acquire	Asset	取资源句柄
script:vm	ScriptPlay	剧本 VM 控制
save:slots	Save	槽位读写
platform:host	Platform	宿主信息、后端选择、播放区
text:view	Text	文本视图
translate:detect	Translate	输入源识别

注意：

• 服务名不得以 on- 开头；那种形态属于通知，校验会直接拒绝。
• caps:* 是 Kernel 声明中的能力通配，不是普通服务名。
• policy（closed／trusted／public）由声明单独给出，不能从名字猜测。例如 asset:acquire 与 asset:list 都是 trusted，platform:host 是 closed。
• 不预留空服务。没有任何真实实现时不要登记名字；名字本身就是承诺。

通知

模式：<域>:on-<事件>。通知只广播事实，不承载回调，返回值不参与业务判定。

示例	载荷要点
asset:on-invalidate	{ vpaths }：缓存失效的路径
save:on-load	读档结果与缺失单元
save:on-orphan-detected	受影响的归属记录
script:on-choice	选项被选择
platform:on-ui-request	{ view: 'save'｜'menu'｜'history'｜'settings' }
platform:on-asset-url-change	无载荷；重定向规则或生效后端变化
audio:on-track-end	音轨结束

规则：

• on- 是固定的通知前缀，不能写成 notify-、event- 或省略。
• 通知不传回调、不直接调用外壳函数；接收方自己决定如何处理。
• 同一事件不要同时注册为服务和通知；校验会因名字重复而拒绝。
• 事件名用「发生了什么」，不用「请做什么」。例如 save:on-save 表示已保存，而不是请求保存。

机制插槽

模式：<域>:<动词>-<对象>。机制插槽是 Mod 的合法改写入口。

动词只取四个：

动词	语义	示例
resolve-	把输入解析为候选或最终决定	asset:resolve-path、script:resolve-command、stage:resolve-composition、platform:resolve-asset-url
filter-	过滤、裁剪或排序集合	当前没有已登记条目；需要该语义时先改设计约定，再登记
render-	产出绘制或呈现结果	当前没有已登记条目；需要该语义时先改设计约定，再登记
compute-	计算派生值，不产生副作用	text:compute-measure

更多已登记示例：

示例	所在插件	作用
asset:resolve-source-order	Asset	调整候选来源顺序
asset:resolve-decoding	Asset	决定解码器或生成器
save:resolve-field	Save	保存时决定旗标值
translate:resolve-rule	Translate	选择翻译规则
battle:resolve-targeting	Battle	决定目标选择
editor:resolve-node	Author	解析编辑节点

规则：

• 四个动词之外不得发明新动词或新后缀。需要新语义时先改设计约定，再改代码。
• 机制插槽没有 closed 档，只取 public 或 trusted。
• 新增机制插槽不要使用旧式 <动词>-pipeline 命名；translate:resolve-pipeline 属已登记存量例外，沿用既有名字。
• 机制插槽与实现位通往同一效果时，审计强度必须一致，不能借插槽绕过实现位的审计要求。

实现位

模式：<域>:<名>@<主版本>。实现位是可替换的实现挂点，single 与 multi 由声明给出，不写进名字。

示例	基数	说明
asset:decoder@1	multi	按格式分派解码器
asset:fetcher@1	multi	按 scheme 分派读取器
stage:cast-renderer@1	multi	立绘渲染实现
save:backend@1	single	存档后端，卸载回落默认
host:backend@1	single	宿主后端，卸载回落 builtin
ui:screen@1	multi	界面实现，按界面名分派
battle:damage-pipeline@1	single	伤害管线实现位

注意：

• battle:damage-pipeline@1 是实现位名，其中的 pipeline 是名字的一部分，不是机制插槽的动词后缀；不要据此发明新的机制插槽动词。
• 主版本从 1 起。主版本表达条目形状的不兼容变化；旧条目不应继续注册到新的主版本位。
• 默认条目名由实现位声明（例如 default: 'builtin'）；声明 onUnload: 'fallback' 时必须给出默认条目，否则契约校验失败。
• 实现位名与条目名是两层命名：asset:decoder@1 是位，image 是条目；消费者看位，装载器看条目。

能力

模式：caps:<名>。

示例	敏感度	当前可用	含义
caps:raw-bytes	T3	是	原始字节通道，供隔离翻译器使用
caps:fs-read	T2	是	由框架代单元读取用户本次选定的本地输入
caps:net-fetch	T2	否	网络读取；后续阶段接入

规则：

• 能力名是封闭集合，只能取已登记的名字；不要发明 caps:file、caps:network 之类的近似词。
• 能力缺失时必须降级或明确禁用，禁止崩溃。
• 能力对象是否交给单元由宿主实现决定；当前两端都不向单元交出能力对象，createCap 对请求明确报错，框架代隔离单元读取。
• 能力名不编码敏感度；敏感度在能力描述中单独声明。

常见错误

写法	问题	正确写法
Asset:Acquire	大写与域名不规范	asset:acquire
asset_acquire	缺分隔符，使用下划线	asset:acquire
asset:resolvePath	驼峰，名字段须用连字符	asset:resolve-path
asset:resolve	缺少对象，无法表达改写目标	asset:resolve-path
asset:dispatch-command	dispatch- 不在四个动词内	改用 resolve- 等已登记动词；需要新语义时先改设计约定
asset:decoder	实现位缺少主版本	asset:decoder@1
asset:decoder@0	主版本从 1 开始	asset:decoder@1
asset:on-invalidate 注册为服务	通知不得占用服务名	注册为通知
caps:FS-Read	能力名须全小写	caps:fs-read
asset:resolve--path	连续连字符	asset:resolve-path

命名是承诺

• 不预留名字。不要为「以后大概会有个 X」登记空服务、空实现位或空插件。
• 名字必须在契约中登记后才能 provide；Kernel 在运行期拒绝越出契约的 provide 与声明。
• 名字一旦发布，改动就是契约变更；不兼容时提升主版本，不要悄悄改语义。
• 文档、清单与代码使用同一套名字；发现不一致时以契约为准，并通过反馈渠道告知维护者。

相关阅读：插槽与实现位、四档扩展模型、包清单与目录、装载管线与 guard、装载原因码。