description: "生成的 Typert 产物所用的 Loader 集成：已挂载的包如何自动把宿主侧反射与 schema 贡献给运行时注册表。" kind: "package-reference"

@qilin-agent/typert-loader

English | 中文

概述

挂载 qilin-typert-loader 后，Loader 组合中每个挂载的包都会自动把其生成的 Typert 反射与 schema factory 贡献给运行时注册表——并在包或本插件卸载时自动撤销。没有该导出的包会被跳过，因此在任何 Loader 组合中挂载它都是安全的。显式 packages 用于覆盖嵌套在另一 Loader 配置项之下的插件，这些插件的 fiber 不携带可解析的包说明符。它是仅支持 Node 的插件，需要配置树解析锚点才能解析包。

目录

• 使用本包
• 理解实现
• 进一步探索
• 模型体验
• 已知限制与延期工作
• 开发备注

使用本包

在加载发布生成 Typert 产物的包的 Host Loader 组合中挂载本插件。注册表本身来自 qilin-typert-registry；本插件只负责发现与注册。

最小配置

加载注册表与 loader；loader 默认发现每一个 Loader 配置项：

- name: '@qilin-agent/typert-registry'
- name: '@qilin-agent/typert-loader'

| 字段 | 默认值 | 含义 | |---|---|---| | packages | [] | 为嵌套在另一 Loader 配置项下的插件额外注册的包产物；每个包都必须能从配置树解析，并导出 ./typert |

生成的配置目录是所有受支持字段的完整真源。

注册什么

每个符合条件的 Loader 配置项都会把其生成的宿主侧反射、schema factory 与 TYPERT.invocations 贡献给运行时注册表。普通产物的 getter 从私有的 Remote info 实例暴露描述符；生成的直接描述符还提供具名 input 与 invocation 辅助方法。注册跟随配置项生命周期：配置项或本插件卸载时撤销；在配置项或本插件任一方卸载后才结束的导入操作会被丢弃。

需要严格 Remote 校验的源码组合会预构建并加载普通 ./typert 产物。loader 把其调用注册到 ctx.typert.local；它不会从活跃 Service 恢复被擦除的约束、文档或 schema。有限的、无描述符的源码回退仍是 Gateway 的事，而 local.hasSeen() 会在已注册定义被撤销后阻止降级到该回退。

可观察行为与失败

没有该导出的包会被静默跳过。解析结论与已导入的 manifest（元数据清单）会在整个进程生命周期内缓存，因此新增 ./typert 导出后必须重启。已挂载配置项对应的产物格式错误时，激活会明确报错；之后才发生的失败按包记录日志，不会阻止无关包完成注册。无法从配置树解析、或缺少该导出的显式 packages 条目会明确报错并指名该包。

理解实现

本节解释 loader 如何扫描、校验与注册；可观察行为已在使用本包中说明。

设计理念

本插件是一个增量扫描器，与 client-modules 的 Node 侧实现对称：每次 Kylin internal/plugin 事件都会把该 fiber 的配置项名称标记为脏，微任务 flush 会针对实时 Loader 配置项逐一调和每个脏名称；激活阶段用所有当前配置项填充同一脏集合。

Manifest 校验

validateTypertManifest() 在产物进入类型化注册表之前进行检查。manifest 必须指名导出它的包、携带 host face、持有 schema factory，并包含格式正确的反射记录；调用描述符要求带 factory 的严格编解码器。校验会检查参数 codec 与可选的 strictCodec spec，并要求生成的直接方法的 input 与 invoke 可调用；result 仍是唯一的输出 codec。文档与 JSON Schema 是可选的。注册绝不调用 input 选择器、解析器 factory 或投影 getter；校验只检查已提供的静态投影数据。每次失败都会指名包与缺陷。

缓存与归属

结论（可解析说明符、是否导出）与已导入的 manifest 按包名缓存且永不过期。注册按配置项名称键控，并通过 ctx.typert.register() 返回的同一资源释放函数撤销；进行中的任务按配置项跟踪，因此迟到的导入不可能在其所有者消失后注册贡献。

源码地图

| 文件 | 职责 | |---|---| | src/index.ts | 插件入口：Config、扫描器、manifest 校验、注册装配逻辑 |

进一步探索

当包级约定不够用时阅读以下页面；这些页面从 loader 开始，依次介绍它注册的内容及其生成方。

• Typert 注册表——本插件所供给的服务。
• Typert 生成器——产生 loader 所导入产物的包。
• 生成配置目录——packages 字段声明及其 JSDoc。
• Typert 组地图——完整的类型反射流水线。

模型体验

无，因为 loader 集成只注册生成的产物；任何模型可见投影均由消费方负责。

KV Cache 影响

无直接影响；注册变更只有通过读取注册表的消费方才会影响请求。

已知限制与延期工作

这些限制说明 loader 不会发现或注册什么；它们是当前包约束，不是任务积压。

• 仅宿主侧——发现机制只会导入宿主侧 ./typert 产物；在为客户端运行时添加等价的发现机制之前，需要先有独立的组合所有者。
• 嵌套插件需要显式条目——Loader 配置项会被自动发现，但嵌套在另一配置项之下、或完全不经 Loader 加载的插件，需要显式加入 packages，或由其所有者直接调用 ctx.typert.register()。
• 缓存结论永不过期——进程中途新增 ./typert 导出的包需要重启后 loader 才会注册它。
• Host 就绪仍由组合负责——需要严格元数据的消费方必须等注册完成后再开始服务调用。惰性 info factory 不会让异步的 Loader 注册提前就绪；local.hasSeen() 只保护已经观察到的定义。

开发备注

无。