# 模块注册表设计

版本号：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. 注册对象

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

1. 算法模块
2. 算法链模板
3. 数据格式定义

## 5. 算法模块定义

### 5.1 作用

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

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

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

### 5.2 建议字段

```ts
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 或调用方猜测。

建议结构：

```ts
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分析员不应只知道“能不能跑”，还应知道“跑起来代价大不大”。

建议结构：

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

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

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

例如：

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

## 8. 算法链模板定义

### 8.1 作用

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

它的意义在于：

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

### 8.2 建议字段

```ts
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
}
```

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

### 8.3 链模板和模块的区别

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

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

## 9. 数据格式注册

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

建议格式：

```ts
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. 校验规则

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

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

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

## 13. 第一版实现建议

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

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

这足以验证：

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

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

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

推荐关系如下：

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

这样可以形成双保险：

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

## 15. 结论

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

它的价值在于：

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

第一版应优先支持：

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