# 算法模块与插件系统

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

说明：本版为按规范整理的历史文档，正文暂保留原英文内容。

## 1. Purpose

This document defines how algorithms should be packaged, discovered, loaded, validated, and distributed inside the multimodal analysis framework.

This is necessary because:

- the system cannot ship every possible algorithm in the core binary
- different modalities require different algorithm families
- the framework needs a stable way to support internal, third-party, and experimental modules
- AI orchestration requires machine-readable metadata about available modules

This document complements:

- [多模态分析框架.md](D:/dev/TC/doc/总体架构/多模态分析框架.md)
- [便携式信号分析仪架构说明.md](D:/dev/TC/doc/总体架构/便携式信号分析仪架构说明.md)

## 2. Design Goals

The module system should satisfy these goals:

- support multiple modalities
- allow modular growth without bloating the core application
- expose enough metadata for AI orchestration
- support safe experimentation
- allow trusted and untrusted modules to coexist under different policies
- make updates possible without rebuilding the entire application

## 3. Core Principle

Do not build the first version as one giant binary with every algorithm linked in.

Instead, separate the system into:

- core runtime
- built-in core algorithms
- installable algorithm packs
- experimental modules

This keeps the product maintainable and makes future platformization possible.

## 4. Algorithm Source Categories

Algorithms will usually come from four sources.

### 4.1 First-Party Algorithms

Algorithms implemented and maintained by the core product team.

Examples:

- core preprocessing
- core signal quality analysis
- scoring engine components
- framing logic
- protocol-adaptation utilities

These should be the most trusted modules and should form the baseline product capability.

### 4.2 Open-Source Algorithms

Algorithms integrated from external open-source projects.

Selection criteria should include:

- license compatibility
- maintenance activity
- code quality
- platform support
- dependency weight
- input/output compatibility
- deterministic behavior under replay

Open-source code should not be copied in casually.
Every imported algorithm should be reviewed as a product dependency.

### 4.3 Third-Party Partner Modules

Algorithms supplied by partners, vendors, researchers, or domain teams.

These are important for scaling the ecosystem but should usually be isolated behind clear packaging and trust rules.

### 4.4 AI-Generated or AI-Modified Experimental Modules

These may be useful for rapid experimentation, but they must be treated as experimental only.

They must not enter the production path automatically.
They should first pass:

- compatibility checks
- replay validation
- scoring validation
- regression tests

## 5. Delivery Model

The system should use a layered delivery model.

### 5.1 Built-In Core

Always shipped with the main application.

Recommended contents:

- runtime and scheduler
- module registry
- experiment manager
- scoring engine
- a small number of essential modality-specific modules

The core should remain intentionally small.

### 5.2 Trusted Packs

Installable packs for specific domains.

Examples:

- RF base pack
- audio pack
- vision pack
- optical decoding pack
- industrial bus pack

These can be versioned and installed independently of the main application.

### 5.3 Experimental Modules

Modules that are not yet promoted to trusted packs.

Examples:

- research algorithms
- low-confidence ports
- AI-generated modules
- partner-preview modules

These should run under stricter policy and default isolation.

## 6. Loading Strategy

Do not start with unrestricted remote code download and execution.

The loading strategy should mature in phases.

### 6.1 Phase 1: Local Discovery and Registration

The application scans known directories and registers available modules.

This is the minimum viable plugin system and should come first.

### 6.2 Phase 2: Managed Pack Installation

The system can install signed or trusted algorithm packs from a local or remote repository, then register them after validation.

### 6.3 Phase 3: AI-Assisted Pack Recommendation

AI may recommend installing additional modules when current capability is insufficient.
However, AI should not be allowed to silently install and execute arbitrary code.

The correct flow is:

1. AI recommends a pack
2. system downloads or locates it
3. compatibility and signature checks run
4. validation runs in sandbox or replay mode
5. pack is promoted to installed state if approved

## 7. Plugin Execution Models

Different algorithm types have different isolation and performance needs.

The framework should support multiple execution models.

### 7.1 In-Process Native Modules

Examples:

- `.dll`
- `.so`
- direct statically linked modules

Best for:

- high-performance real-time stages
- low-latency DSP
- trusted first-party runtime-critical modules

Tradeoffs:

- ABI management complexity
- crash risk if module quality is poor
- tighter coupling with host process

### 7.2 Out-of-Process Modules

Modules run as separate processes and communicate via RPC, pipes, sockets, or structured IPC.

Best for:

- isolation
- multi-language module support
- crash containment
- medium-cost experimental algorithms

Tradeoffs:

- IPC overhead
- more operational complexity

### 7.3 Sandboxed Modules

Examples:

- Wasm-based modules
- restricted containerized workers
- sandboxed runners

Best for:

- third-party modules
- AI-generated modules
- untrusted or semi-trusted experimentation

Tradeoffs:

- performance limits for very heavy real-time workloads
- additional runtime complexity

## 8. Recommended Execution Policy

Recommended default policy:

- real-time production-critical modules -> in-process native
- replay and heavy analysis modules -> out-of-process
- third-party and AI-generated modules -> sandboxed first

Do not force all algorithms into one execution model.
Different layers of the system need different safety and performance tradeoffs.

## 9. Module Metadata

Every algorithm module must expose machine-readable metadata.

Suggested minimum shape:

```json
{
  "name": "gfsk_demod_basic",
  "version": "0.1.0",
  "stage": "demod",
  "modality": ["rf"],
  "input_format": "complex_iq",
  "output_format": "soft_bits",
  "params": {
    "symbol_rate": {
      "type": "float",
      "range": [1000, 1000000]
    },
    "deviation": {
      "type": "float",
      "range": [100, 500000]
    }
  },
  "metrics": ["snr_estimate", "lock_stability"],
  "realtime_safe": true,
  "trust_level": "trusted",
  "license": "MIT"
}
```

This metadata is not optional.
Without it:

- the runtime cannot compose pipelines safely
- AI cannot reason about compatibility
- the UI cannot explain what is installed
- pack management becomes fragile

## 10. Required Metadata Fields

Every module should declare:

- `name`
- `version`
- `author`
- `source`
- `license`
- `modality`
- `stage`
- `input_format`
- `output_format`
- `params`
- `metrics`
- `platforms`
- `realtime_safe`
- `trust_level`
- `execution_model`

Optional but valuable:

- `hardware_requirements`
- `estimated_cost`
- `known_limitations`
- `supported_sample_ranges`
- `preferred_predecessors`
- `preferred_successors`

## 11. Pack Structure

A pack should be more than a raw binary.

Suggested pack contents:

- manifest file
- one or more modules
- dependency declaration
- optional test vectors
- optional replay validation cases
- optional documentation
- signature or checksum metadata

Example structure:

```text
rf-base-pack/
  manifest.json
  modules/
    gfsk_demod_basic.dll
    burst_detect.dll
    crc_scan.dll
  tests/
    replay_case_01.json
    replay_case_02.json
  docs/
    README.md
  signatures/
    sha256.txt
```

## 12. Discovery and Registration

The runtime should have a deterministic registration process.

Suggested startup flow:

1. scan built-in modules
2. scan installed trusted-pack directories
3. scan experimental-module directories
4. load manifest metadata
5. validate schema and compatibility
6. register modules in the module registry
7. expose only approved modules to the orchestrator

The registry should track:

- module identity
- version
- load state
- trust state
- dependency state
- runtime errors

## 13. Dependency Management

Modules should be able to declare dependencies on:

- runtime version
- host API version
- other modules
- hardware capabilities
- external libraries

The host must reject incompatible modules early.

This avoids problems such as:

- ABI mismatch
- unsupported platform
- missing runtime features
- invalid pipeline assembly

## 14. Validation Pipeline

Before a module becomes usable, it should pass validation.

Validation should include:

- manifest schema validation
- compatibility checks
- signature/checksum validation where applicable
- sandbox smoke test
- replay validation against known samples
- optional performance validation

For trusted promotion, add:

- regression comparison
- scoring sanity checks
- resource stability checks

## 15. Trust Levels

The framework should explicitly track trust levels.

Suggested levels:

- `core`
- `trusted`
- `partner`
- `experimental`
- `untrusted`

Trust level should influence:

- execution model
- default enablement
- visibility to AI orchestrator
- whether use is allowed in live mode

For example:

- `core` and `trusted` modules can be used in live mode
- `experimental` modules require replay or manual approval
- `untrusted` modules are disabled by default

## 16. AI Interaction Rules

AI should only operate over registered metadata and installed modules.

AI may:

- discover available modules
- choose among installed modules
- request installation of a missing pack
- recommend parameter ranges
- recommend promoting or demoting modules based on evidence

AI should not:

- download and execute arbitrary code without validation
- bypass trust policy
- silently enable experimental modules in production
- write new production modules directly into the live path

## 17. Distribution Strategy

The long-term distribution model can evolve into:

- built-in modules with the main app
- local pack installation
- remote pack repositories
- enterprise private registries
- domain marketplaces

But the implementation order should remain conservative:

1. local pack loading
2. signed pack installation
3. repository-backed updates
4. AI-assisted pack recommendation
5. optional ecosystem / marketplace

## 18. Why This Matters Strategically

The algorithm module system is not just an implementation detail.
It is one of the main leverage points for the whole platform.

It enables:

- independent growth of algorithm inventory
- narrower core binaries
- field updates without full rebuilds
- third-party ecosystem participation
- safer experimentation
- AI-driven orchestration at scale

This is also the foundation for turning the framework into a real platform rather than a single-device product.

## 19. Recommended Immediate Starting Point

The first implementation should be intentionally small.

Recommended order:

1. define manifest schema for modules
2. define module registry interfaces
3. support local module discovery from one directory
4. support one execution model first
5. add trust-level metadata
6. add replay validation hooks
7. add pack installation later

For the first version, it is acceptable to support only:

- first-party modules
- local discovery
- one trusted-pack folder
- manual installation

That is enough to prove the architecture.

## 20. Summary

The correct architecture is not to embed every algorithm in the main application.

The correct architecture is:

- small core runtime
- metadata-driven module registry
- installable algorithm packs
- trust-aware execution policies
- validation before activation
- AI operating only on registered and policy-approved modules

This keeps the framework scalable, safe, and extensible.