模块注册表设计

版本号：v0.1.0 最后更新：2026-04-04

1. 目的

本文档用于定义本项目的模块注册表设计，用于支撑以下能力：

管理可用算法模块
管理可用算法链模板
支持 AI分析员发现和选择工具
约束参数、权限和执行边界
为实验执行器提供可验证的运行依据

模块注册表是本项目的重要基础设施，不是附属功能。

2. 核心定位

模块注册表是系统中的“工具目录”和“能力边界层”。

其职责不是执行算法，而是回答以下问题：

系统当前有哪些可用模块
这些模块分别属于哪个阶段
它们适用于哪些信号画像和目标
输入输出是否兼容
允许哪些参数被 AI 调整
哪些模块或链模板可进入实验流程

换句话说，AI分析员不能直接面对一堆裸代码，而必须通过模块注册表来理解和调用系统能力。

3. 设计原则

3.1 元数据优先

模块是否可用，不应由使用者记忆或硬编码决定，而应由机器可读元数据决定。

3.2 注册优先于执行

任何模块在进入实验链之前，应先被注册、校验和分类。

3.3 注册表既管理模块，也管理链模板

如果只注册单模块，不注册链模板，AI分析员仍然很难高效规划实验。

因此注册表中应同时存在：

模块定义
链模板定义

3.4 AI 只能操作注册表可见能力

AI分析员的可选工具集合必须来自注册表。

AI 不应绕过注册表直接调用未知代码、隐藏模块或未声明参数。

4. 注册对象

第一版建议注册三类对象：

算法模块
算法链模板
数据格式定义

5. 算法模块定义

5.1 作用

算法模块是算法链中的最小可组合单元。

模块通常只负责一个明确步骤，例如：

归一化
分段
周期检测
谐波检测
分类
相似度检索

5.2 建议字段

type ModuleSpec = {
  id: string
  name: string
  version: string
  stage: string
  signalProfiles: string[]
  goals: string[]
  inputFormat: string
  outputFormat: string
  params: Record<string, ParamSpec>
  evidenceKinds: string[]
  failureModes: string[]
  cost: CostSpec
  runtime: RuntimeSpec
  trustLevel: "core" | "trusted" | "experimental"
  enabled: boolean
}

5.3 字段说明

id
- 全局唯一标识
name
- 人类可读名称
version
- 模块版本
stage
- 所属阶段
signalProfiles
- 适用信号画像
goals
- 适用分析目标
inputFormat
- 输入格式标识
outputFormat
- 输出格式标识
params
- 可配置参数定义
evidenceKinds
- 可能产出的证据类型
failureModes
- 常见失败原因
cost
- 成本估计
runtime
- 执行位置和调用方式
trustLevel
- 信任等级
enabled
- 当前是否可用

6. 参数定义

模块参数必须显式声明，不能依赖 AI 或调用方猜测。

建议结构：

type ParamSpec = {
  type: "int" | "float" | "bool" | "string" | "enum"
  required?: boolean
  defaultValue?: unknown
  range?: [number, number]
  choices?: string[]
  description?: string
  tunableByAI: boolean
  riskLevel?: "low" | "medium" | "high"
}

关键点：

tunableByAI 必须明确
range 和 choices 必须明确
对高风险参数应附带风险等级

7. 成本与运行信息

AI分析员不应只知道“能不能跑”，还应知道“跑起来代价大不大”。

建议结构：

type CostSpec = {
  cpu?: number
  memory?: number
  latency?: number
  battery?: number
}

type RuntimeSpec = {
  location: "local_mobile" | "remote_host" | "either"
  invocation: "ffi" | "native" | "rpc"
  realtimeSafe: boolean
}

这些信息会直接影响 AI分析员的实验规划。

例如：

先跑低成本本地探针
复杂分离或重型分类再交给远端

8. 算法链模板定义

8.1 作用

链模板是对常见分析方法的标准化封装。

它的意义在于：

给 AI分析员提供高层实验工具
避免每次都从零拼装所有节点
让实验设计更快、更稳、更可控

8.2 建议字段

type ChainTemplateSpec = {
  id: string
  name: string
  version: string
  purpose: string
  signalProfiles: string[]
  goals: string[]
  inputFormat: string
  nodes: ChainTemplateNode[]
  expectedEvidenceKinds: string[]
  typicalFailureModes: string[]
  costClass: "low" | "medium" | "high"
  enabled: boolean
}

type ChainTemplateNode = {
  moduleId: string
  required: boolean
  presetParams?: Record<string, unknown>
}

8.3 链模板和模块的区别

模块是最小工具单元
链模板是经过组织的实验套路

AI分析员在大多数情况下应优先从链模板出发，而不是直接从裸模块拼接。

9. 数据格式注册

为了避免模块间随意拼接，输入输出格式也应进入注册表统一管理。

建议格式：

type DataFormatSpec = {
  id: string
  family: string
  encoding: string
  description?: string
}

示例：

audio.wav_pcm16
audio.spectrogram_f32
audio.embedding_f32
audio.segment_list
analysis.evidence_list

10. 注册表应支持的查询能力

模块注册表至少应支持以下查询：

10.1 按阶段查询

例如：

找到所有 detect 阶段模块
找到所有 classify 阶段模块

10.2 按信号画像查询

例如：

找到适合 periodic_pulse 的模块或链模板

10.3 按分析目标查询

例如：

找到适合 周期验证 的链模板

10.4 按输入输出格式兼容性查询

例如：

查找能接在 spectrogram_extract 后面的模块

10.5 按执行位置查询

例如：

本地可执行模块
远端可执行模块

10.6 按可调参数能力查询

例如：

查找哪些模块允许 AI 调整阈值参数

11. AI 可见性与权限控制

不是所有注册对象都必须对 AI分析员完全可见。

建议至少区分三类：

11.1 全可见对象

核心稳定模块
核心链模板

AI 可以自由选择和调度。

11.2 条件可见对象

实验模块
高成本模块
高风险参数模块

AI 需要额外条件才能使用，例如：

仅在远端模式可见
仅在指定目标下可见
仅在人工授权后可见

11.3 不可见对象

内部测试模块
已禁用模块
兼容性失效模块

AI 不应看到，更不应调用。

12. 校验规则

模块或链模板注册时应至少通过以下检查：

必填字段齐全
输入输出格式合法
参数定义完整
引用的模块存在
信任等级合法
运行位置合法
链模板的模块顺序兼容

未通过校验的对象不得进入可用目录。

13. 第一版实现建议

第一版建议采用最小可行方案：

使用本地 JSON 或 YAML 保存注册信息
应用启动时加载注册表
先只支持第一方模块
先只支持手工维护的链模板
先不做动态下载和在线安装

这足以验证：

AI 是否能基于注册表选工具
实验执行器是否能基于注册表构建链路
是否能稳定产出结构化实验记录

14. 与 AI分析员的接口关系

模块注册表不是给用户直接使用的，而是给 AI分析员和实验执行器共同使用的。

推荐关系如下：

AI分析员读取注册表，生成实验计划
实验执行器根据注册表校验计划合法性
若计划不合法，则拒绝执行并返回原因

这样可以形成双保险：

AI 负责规划
注册表负责约束

15. 结论

模块注册表是本项目的核心基础设施之一。

它的价值在于：

把算法能力变成可发现、可组合、可约束、可验证的系统资产
让 AI分析员能够真正像使用者一样选择工具和设计实验
防止系统退化为“模型自由发挥 + 隐式调用代码”的不透明结构

第一版应优先支持：

模块注册
链模板注册
参数边界声明
格式兼容性校验
AI 可见性控制

模块注册表设计.md 8.0 KB Historie Surový