feat: v3.5 - Multi-language acoustic algorithm scheduler

- Core: Python/C++/MATLAB tri-protocol bridge architecture
- Validation: 5-type real-time field, type, dimension, completeness, and compatibility checking
- UI: Premium Deep Sea theme with visual pipeline preview
- Modules: Sea Trial Exclusive + Exception Hub + Algorithm Management
- Tests: Full coverage with 5 automated test cases

docs/walkthrough_2_5.md

@@ -0,0 +1,36 @@
+# Walkthrough - Phase 2.5（可演示级 MVP）
+
+Phase 2.5 将系统从“框架可跑”推进到“可演示、可做现场巡检”的状态，重点补齐真实算法、海试专属流程与异常聚合能力。
+
+## 1) 真实水声算法库
+实现于 `src/sample_algorithms.py`：
+- `dc_removal_and_bandpass`: 去直流 + 带通滤波（含参数与短序列兜底）
+- `stft_magnitude`: STFT 幅度谱
+- `snr_estimation`: 简易 SNR 估计（dB）
+- `quality_check`: 掉点/饱和巡检，输出 `quality_score` 等指标
+
+对应元数据已更新至 `data/algorithms.json`（含中文描述与输入输出字段映射）。
+
+## 2) 海试专属（⛴️ 一键质量巡检）
+实现于 `main.py` 的“海试专属”页：
+- 内置固定流程：去直流+带通 → 质量巡检 → SNR 估计
+- 指标看板：SNR、最大幅值、质量得分
+- 一键导出 `CSV` 报告
+
+## 3) 异常中心（🚑）
+实现于 `main.py` 的“异常中心”页：
+- 聚合最近一次链路校验结果（字段/类型/维度/完整性/兼容性）
+- 聚合最近一次执行结果（状态、错误信息、执行日志）
+- 支持导出 `issue_bundle.json`
+- 环境自检入口：`src/env_detect.py`
+
+## 4) 加固项
+- `src/bridges.py`: `normalize` 预处理算子增加除零与空数组保护
+- `src/models.py`: 日志统一写入 UTC 时间戳
+
+## 5) 验证
+运行 `python tests/test_core.py` 覆盖：
+- 基础链路集成测试
+- 校验拦截（缺字段/类型/维度）
+- 海试一键巡检链路（含真实算法调用）
+

docs/walkthrough_final.md

@@ -0,0 +1,33 @@
+# Walkthrough - v3.5（最终交付）
+
+本版本将平台推进为“可演示/可落地”的全协议集成与调度工具：支持 Python/C++/MATLAB(含降级) 三语言算法编排执行，具备五维校验、环境自检、海试一键巡检与异常中心排障闭环。
+
+## 1) 设计与交互
+- 深海风 UI：深蓝侧边栏、现代排版、卡片化布局（`main.py`）
+- 可视化流水线：调度页提供“运行流水线预览”（`main.py`）
+- 语言标识：Python/C++/MATLAB 徽标在算法库与流水线中可视化区分（`main.py`）
+
+## 2) 多协议桥接
+- Python：动态加载并执行（`src/algo_loader.py`、`src/bridges.py`）
+- C++：`.so/.dll` 动态库加载 + `ctypes` 调用（`src/bridges.py`、示例 `src/sample_algos_cpp/`）
+- MATLAB/Octave：Engine → oct2py → CLI+matfile 三级降级（`src/bridges.py`、示例 `src/sample_algos_matlab/`）
+
+## 3) 工业级自检与五维校验
+- 环境自检：编译器、MATLAB/Octave 能力检测（`src/env_detect.py`）
+- 五维校验：字段/类型/维度/完整性/环境兼容（`src/validator.py`、调度前拦截 `src/scheduler.py`）
+
+## 4) 海试专属与异常中心
+- 海试一键巡检：内置链路 + CSV 报告导出（`main.py`）
+- 异常中心：校验问题卡片、执行日志、环境快照、排障 JSON 包导出（`main.py`）
+
+## 5) 验证方式
+运行测试：
+```bash
+python tests/test_core.py
+```
+
+启动界面：
+```bash
+streamlit run main.py
+```
+

docs/水声算法全协议集成与调度平台 - 技术实施方案文档.md

@@ -0,0 +1,241 @@
+# 水声算法全协议集成与调度平台 - 技术实施方案文档
+文档信息
+项目	内容
+文档版本	V1.0
+编写日期	2026.01
+适用范围	软件研发、模块开发、技术实现、测试部署
+研发团队	2-3 人，核心技术栈 Python
+一、技术方案总体设计
+1.1 设计理念
+基于 **“轻量化、插件化、标准化、低耦合”** 核心设计理念，贴合微型研发团队能力，优先采用 Python 生态成熟技术，同时融合 C/C++ 高性能计算优势，打造 “上层 Python 调度交互 + 底层 C/C++ 高性能计算” 的混合技术栈，实现多语言算法统一适配，同时预留工业级拓展接口。
+1.2 整体架构
+采用分层式 + 插件化架构设计，分为用户交互层、核心调度层、桥接插件层、算法层、数据层五层，所有层之间通过标准化协议对接，低耦合、可插拔，便于开发、维护与拓展。
+plaintext
+用户交互层（Web界面）←→核心调度层（标准化内核）←→桥接插件层（语言专属）←→算法层（标准/自研，多语言）
+                                        ↓
+                                  数据层（标准化中间数据）
+1.2.1 各层核心职责
+用户交互层：基于 Streamlit 实现 Web 可视化界面，负责算法上传、接口配置、流程组合、异常展示、日志查看等客户操作，为客户提供零代码交互体验；
+核心调度层：软件核心内核，负责标准化中间数据管理、算法流程调度、接口实时校验、全流程容错、日志记录，是所有功能的调度中枢；
+桥接插件层：包含 Python/MATLAB/C/C++ 语言专属桥接插件，负责跨语言数据转换、算法调用、编译封装，屏蔽语言差异，对上层暴露标准化接口；
+算法层：包含官方标准算法库与客户自定义算法库，所有算法均为黑盒化插件，遵循标准化接口协议；
+数据层：以 WaterSoundData 为核心，负责全流程数据的存储、流转与管理，同时包含日志、报告、模板等持久化数据的存储。
+1.3 核心设计原则
+标准化：定义统一的标准化中间数据格式、黑盒插件协议、跨语言数据转换协议，所有模块均遵循标准化协议对接；
+插件化：桥接插件、预处理算子、算法黑盒均为可插拔式设计，新增 / 修改 / 删除不影响核心内核；
+低耦合：各层之间、模块之间通过标准化接口对接，无直接代码依赖，便于单独开发、测试与迭代；
+轻量化：优先采用 Python 轻量开源库，避免重型框架，保证客户侧部署零成本、运行低资源；
+容错性：全流程融入容错设计，从配置到执行层层校验、兜底，保证系统稳定性；
+可拓展：预留算法语言、预处理算子、功能模块的拓展接口，支持后续快速升级，同时预留 C++/Qt 工业级拓展接口，无技术断层。
+二、核心技术选型
+2.1 开发语言
+主开发语言：Python3.8+（团队核心技术栈，开发效率高，生态丰富，跨平台，轻量）；
+辅助语言：C/C++（仅用于 C/C++ 算法编译为动态链接库，无需自研业务代码）。
+2.2 核心技术栈与第三方库
+按功能模块梳理核心技术 / 库，均为工业级成熟方案，无前沿未验证技术，降低研发风险：
+功能模块	核心技术 / 第三方库	核心作用
+用户交互层	Streamlit	极简开发 Web 可视化界面，支持下拉、拖拽、实时校验、日志展示，无需前端开发
+核心调度层	Python 原生 OOP、dataclasses、logging、json	实现标准化中间数据定义、流程调度、实时校验、结构化日志、数据持久化
+桥接插件层	Python：原生调用
+MATLAB：matlab.engine、oct2py
+C/C++：ctypes、cffi	跨语言数据转换、算法调用，oct2py 为 MATLAB 无授权兜底，ctypes/cffi 实现 C/C++ 库加载
+C/C++ 编译模块	MinGW/GCC、Python subprocess/os/glob	自动检测编译器、生成编译脚本，将 C/C++ 文件编译为跨平台动态链接库
+数据处理模块	NumPy、SciPy	水声算法核心数据处理，与现有水声算法代码无缝兼容，实现数组、矩阵操作
+性能优化模块	Python multiprocessing、mmap（内存映射）	实现非依赖型算法并行调度、大体积数据分块处理、内存级高性能数据传递
+数据持久化模块	Python 原生文件操作（.npy/.mat/.bin/.json/.pdf/Excel）	实现算法版本、模板、日志、报告、数据的存储与导出，无需复杂数据库
+报告生成模块	reportlab、pandas	实现检测报告、对比报告的生成与导出（PDF/Excel 格式）
+2.3 技术栈优势
+研发效率高：Python 生态成熟，Streamlit 快速实现 Web 界面，无需前端 / 后端分离开发，2-3 人团队 1-2 周可完成核心功能开发；
+客户侧零成本：跨平台免编译，仅需 Python 运行环境，轻量依赖一键安装，拷贝即可运行；
+低耦合可拓展：插件化设计，新增功能 / 算法语言仅需开发对应插件，无需重构核心代码；
+性能有保障：融合 C/C++ 高性能计算优势，内存映射实现无损耗数据传递，满足水声算法处理需求；
+维护成本低：Python 代码简洁可读性强，模块化设计，团队可互相维护，客户问题可快速定位解决。
+三、核心模块技术实现
+3.1 标准化中间数据模块（数据层核心）
+3.1.1 数据定义
+基于 Python dataclasses定义WaterSoundData类，作为全流程唯一数据交换标准，包含基础数据、过程数据、结果数据、元信息四大类字段，支持动态扩展字段，适配个性化需求：
+python
+from dataclasses import dataclass
+import numpy as np
+from typing import Dict, Optional, List
+
+@dataclass
+class WaterSoundData:
+    # 基础原始数据
+    raw_data: np.ndarray          # 原始声呐数据
+    sample_rate: float            # 采样率
+    collect_time: str             # 数据采集时间
+    sea_env: Dict = None          # 海洋环境参数（声速、温度、盐度等）
+    # 处理过程数据
+    clean_data: Optional[np.ndarray] = None  # 清洗后数据
+    denoised_data: Optional[np.ndarray] = None# 降噪后数据
+    stft_data: Optional[np.ndarray] = None   # STFT时频数据
+    feat_data: Optional[np.ndarray] = None   # 特征数组
+    # 结果数据
+    final_result: Optional[np.ndarray] = None# 最终处理结果
+    core_index: Dict = None        # 核心指标（信噪比、数据完整性等）
+    vis_data: Dict = None          # 可视化数据
+    # 元信息
+    status: str = "init"           # 数据状态：init/processing/finished/error
+    error_info: str = ""           # 错误信息
+    log: List[Dict] = None         # 执行日志
+    algo_version: Dict = None      # 算法版本记录
+3.1.2 核心方法
+为 WaterSoundData 类实现数据更新、日志添加、错误记录、数据保存 / 加载等核心方法，支持全流程数据的动态管理与溯源。
+3.2 桥接插件层实现
+采用插件化工厂模式，为每种语言开发独立的桥接插件，核心实现数据转换与算法调用两大功能，对外暴露统一的call_algo方法，核心调度层无需感知语言差异。
+3.2.1 Python 桥接插件（最简）
+直接调用 Python 函数，实现标准化数据与 Python 算法输入输出的映射，核心代码示例：
+python
+class PythonBridge:
+    def __init__(self, algo_func, input_mapping, output_mapping):
+        self.algo_func = algo_func  # Python算法核心函数
+        self.input_mapping = input_mapping  # 输入映射关系
+        self.output_mapping = output_mapping# 输出映射关系
+
+    def call_algo(self, water_data: WaterSoundData) -> WaterSoundData:
+        # 提取标准化输入并映射
+        algo_input = [getattr(water_data, k) for k in self.input_mapping.values()]
+        # 调用算法
+        algo_output = self.algo_func(*algo_input)
+        # 输出映射回标准化数据
+        for k, v in zip(self.output_mapping.keys(), algo_output):
+            setattr(water_data, k, v)
+        return water_data
+3.2.2 MATLAB 桥接插件
+基于matlab.engine/oct2py实现，自动完成 numpy 数组与 MATLAB 矩阵的转换，核心实现引擎自动管理、数据转换、容错兜底：
+调用前自动检测 MATLAB 环境，有则用matlab.engine，无则切换oct2py；
+实现 numpy.ndarray ↔ matlab.double/oct2py.Array 的无损转换；
+引擎调用失败则切换为.mat文件桥接模式，通过文件实现数据传递。
+3.2.3 C/C++ 桥接插件
+核心实现C/C++ 文件编译与动态链接库调用两大功能，同时完成 numpy 数组与 C/C++ 指针 / 数组的高性能转换：
+自动编译：检测客户编译器，自动生成编译脚本，将 C/C++ 文件编译为.dll（Windows）/.so（Linux）/.dylib（macOS）；
+库加载：通过ctypes加载动态链接库，绑定核心函数；
+数据转换：采用内存映射实现 numpy 数组与 C/C++ 指针的直接映射，无数据拷贝，保证高性能；
+参数传递：自动传递数组长度、维度等信息，保证 C/C++ 算法正确执行。
+3.3 核心调度层实现
+核心调度层是软件的 “大脑”，负责接口校验、流程调度、容错处理、日志记录，基于状态机模式实现算法流程的自动化调度，核心流程：
+流程解析：解析客户拖拽的流程 / 文字指令生成的流程，得到算法黑盒列表与执行顺序；
+全局校验：校验算法之间的接口衔接性，生成校验报告；
+初始化：初始化 WaterSoundData，加载输入数据；
+按序调度：遍历算法黑盒列表，依次调用对应桥接插件的call_algo方法，传递 WaterSoundData；
+容错处理：若某算法调用失败，触发容错机制（隔离 / 兜底），记录错误信息，继续调度后续算法；
+结果处理：所有算法执行完成后，生成处理结果与报告，更新 WaterSoundData 状态为finished。
+3.3.1 实时校验模块实现
+基于规则引擎实现接口配置的实时校验，将 5 类校验规则封装为独立的校验函数，配置操作触发时实时调用，返回校验结果与错误信息，核心示例：
+python
+def check_field_exist(water_data, field_name, pre_algo_list):
+    """字段存在性校验"""
+    if hasattr(water_data, field_name):
+        if getattr(water_data, field_name) is not None:
+            return True, ""
+    # 校验前序算法是否能生成该字段
+    field_algo_map = {"stft_data": "STFT", "denoised_data": "Denoise"}
+    if field_name in field_algo_map and field_algo_map[field_name] not in pre_algo_list:
+        return False, f"该字段未生成，前序流程需添加{field_algo_map[field_name]}算法"
+    return False, f"字段{field_name}不存在或未初始化"
+所有校验函数通过统一的校验入口调用，若有任意一个校验失败，弹窗提示并禁止保存配置。
+3.3.2 容错处理模块实现
+基于异常捕获 + 策略模式实现三层容错，将不同的容错策略封装为独立的函数，根据错误类型自动触发对应策略：
+配置阶段：校验函数返回 False 则触发拦截策略，禁止保存；
+转换阶段：数据转换异常则触发自动修复策略（维度展平、类型转换等），修复后继续执行；
+执行阶段：算法调用异常则触发隔离策略/兜底策略，根据算法重要性自动选择，核心示例：
+python
+def fault_tolerance(water_data, algo_black_box, error_type, error_info):
+    """容错处理主函数"""
+    water_data.error_info = error_info
+    water_data.log.append({"step": algo_black_box.name, "error": error_type, "info": error_info})
+    # 核心算法，触发兜底策略
+    if algo_black_box.is_core:
+        water_data.log.append({"step": algo_black_box.name, "action": "启用兜底标准算法"})
+        core_algo = get_standard_algo(algo_black_box.func_type)  # 获取同功能标准算法
+        return core_algo.call_algo(water_data)
+    # 非核心算法，触发隔离策略
+    else:
+        water_data.log.append({"step": algo_black_box.name, "action": "算法隔离，继续执行后续流程"})
+        water_data.status = "part_error"
+        return water_data
+3.4 用户交互层实现
+基于Streamlit实现 Web 可视化界面，无需前端开发，纯 Python 代码实现所有交互功能，核心设计原则：简洁直观、功能分区、操作引导，界面分为算法库管理、接口配置、流程调度、海试模式、异常中心、日志报告六大功能区，核心实现：
+算法上传：通过st.file_uploader实现文件上传，支持多文件 / 压缩包，配合输入框获取算法名称、核心函数名等信息；
+接口配置：通过st.selectbox实现字段下拉选择，st.button实现预处理算子添加，实时调用校验函数，st.error实现错误提示；
+流程组合：通过st.columns+st.drag_and_drop实现算法拖拽排序，生成流程列表；
+执行调度：通过st.button触发调度函数，st.progress实现进度条，st.text实现实时日志展示；
+异常中心：通过st.expander实现异常信息折叠展示，配合st.button实现一键修复；
+日志报告：通过st.dataframe展示日志，st.download_button实现日志 / 报告导出。
+Streamlit 实现的界面支持本地离线运行，无需搭建服务器，客户启动命令仅需：streamlit run main.py，操作极简。
+3.5 海试专属模块实现
+基于核心调度层做轻量化定制，隐藏复杂配置功能，仅保留核心操作，核心实现：
+模式切换：通过 Web 界面一键切换 “科研模式 / 海试模式”，海试模式下仅显示 “数据上传、一键检测、报告导出” 三个核心模块；
+专属流程：内置海试数据质量检测流程模板，无需客户配置，直接调用；
+快速执行：关闭并行调度、非核心日志记录等功能，优化资源占用，提升执行速度；
+简洁报告：定制海试专属检测报告，突出核心指标、检测结论、处理建议，支持 PDF/Excel 快速导出。
+四、研发与部署计划
+4.1 研发计划（2-3 人团队，总周期 3 周，分阶段执行）
+阶段 1：核心框架开发（第 1 周）
+完成标准化中间数据模块、核心调度层、Python/MATLAB 桥接插件开发；
+完成基础 Web 界面（算法库管理、简单接口配置）开发；
+实现单语言算法的上传、调用、执行核心流程。
+阶段 2：功能完善（第 2 周）
+完成 C/C++ 桥接插件、自动编译模块开发，支持 C/C++ 算法上传与调用；
+完成接口配置实时校验、容错处理模块开发；
+完成流程调度、文字指令解析功能开发；
+完善 Web 界面，实现流程拖拽、异常展示、日志记录功能。
+阶段 3：优化与测试（第 3 周）
+完成海试专属模块、报告生成模块开发；
+完成性能优化（分块处理、并行调度、内存映射）；
+进行全功能测试、性能测试、稳定性测试，修复 bug；
+完成用户操作手册、技术文档编写，打包产品。
+4.2 测试计划
+分单元测试、集成测试、系统测试、客户试用测试四个阶段，由研发团队自行完成，贴合微型团队特点：
+单元测试：各模块开发完成后，编写单元测试用例，测试核心函数的正确性；
+集成测试：各模块集成后，测试模块之间的对接是否正常，跨语言算法调用是否稳定；
+系统测试：按需求文档验收标准，测试全功能、性能、稳定性、易用性；
+客户试用测试：邀请 2-3 家目标客户试用，收集反馈，修复问题，优化体验。
+4.3 部署与交付计划
+4.3.1 产品打包
+核心代码：保留纯 Python 脚本，方便后续升级与定制；
+便携包：通过pyinstaller将核心代码打包为单文件可执行程序（Windows/.exe、Linux/.bin、macOS/.app），客户无需安装 Python，双击即可运行；
+配套文件：包含用户操作手册、技术支持联系方式、一键安装依赖脚本。
+4.3.2 客户侧部署
+客户侧部署零配置、零成本，两种部署方式：
+脚本运行：客户安装 Python3.8+，解压产品包，运行install_deps.py一键安装依赖，再运行streamlit run main.py启动软件；
+可执行程序运行：直接解压便携包，双击可执行程序即可启动，无需安装任何环境。
+4.3.3 交付物
+软件产品包（脚本版 + 便携版）；
+《用户操作手册》（图文版，含操作步骤、常见问题解决）；
+《技术支持手册》（含联系方式、问题反馈流程）；
+算法示例包（含官方标准算法、多语言算法示例）。
+五、长远技术迭代与拓展
+5.1 短期迭代（0-6 个月）
+基于客户反馈优化 Web 界面体验，完善预处理算子库，新增水声行业专属预处理算子；
+支持更多算法语言（如 Fortran/Julia），仅需开发对应桥接插件；
+优化 C/C++ 编译与调用逻辑，提升高性能计算效率；
+增加算法参数可视化调参功能，支持客户在 Web 界面直接修改算法参数。
+5.2 中期迭代（6-18 个月）
+增加团队协作功能，支持多用户共享算法库、模板，实现权限管理；
+增加GPU 加速支持，对接 CUDA，实现大体积数据 GPU 加速处理；
+优化数据处理模块，支持更多水声行业数据格式；
+开发远程技术支持模块，实现日志远程上传、问题快速定位。
+5.3 长期拓展（18 + 个月，工业级方向）
+基于现有标准化协议，实现向 C++/Qt 工业级系统的平滑拓展，核心步骤：
+基于 C++ 重构核心调度层，复用现有 WaterSoundData 标准化数据定义，保证数据互通；
+将现有 Python 桥接插件移植为 C++ 版本，支持多语言算法调用；
+基于 Qt 开发工业级可视化界面，支持硬件对接（声呐采集卡、FPGA、GPU）；
+形成 **“Python 轻量化科研工具”+“C++/Qt 工业级系统”** 双产品体系，实现科研与工程的无缝衔接。
+六、风险评估与应对措施
+风险类型	具体风险	应对措施
+技术风险	C/C++ 跨平台编译兼容性问题	统一采用 MinGW/GCC 编译器，生成跨平台动态链接库，增加编译失败兜底方案
+技术风险	MATLAB 无授权导致调用失败	集成 oct2py 开源库，自动检测 MATLAB 环境，无授权则自动切换 oct2py 兜底
+性能风险	大体积数据处理效率低	实现自动分块处理、内存映射、并行调度，优化数据转换逻辑，无拷贝传递
+研发风险	团队人员少，研发进度滞后	采用模块化开发，优先实现核心功能，非核心功能可后期迭代；合理分配任务，聚焦核心模块
+客户风险	客户操作习惯不适应，上手困难	编写详细的图文操作手册，界面增加操作引导弹窗，提供 1v1 技术支持与操作培训
+客户风险	客户自研算法复杂，适配失败	提供极简代码扩展方式，增加自定义预处理插件，同时提供专业的算法适配技术支持
+七、质量保障
+代码质量：遵循 Python PEP8 编码规范，添加详细的代码注释，核心函数编写文档字符串，保证代码可读性与可维护性；
+测试覆盖：单元测试覆盖核心函数，集成测试覆盖模块对接，系统测试覆盖全功能，测试用例包含正常场景与异常场景；
+文档完善：编写完整的需求文档、技术实施方案文档、用户操作手册、技术支持手册，保证研发、测试、交付、使用全流程有文档可依；
+持续优化：基于客户反馈，建立 bug 修复与功能迭代机制，定期发布小版本更新，提升软件质量与体验。
+八、总结
+本技术实施方案基于 Python 生态，融合 C/C++ 高性能计算优势，采用分层式 + 插件化架构设计，贴合 2-3 人微型水声算法团队的研发能力与节奏，能快速实现软件的开发、测试与部署。方案既满足当前目标客户（高校 / 研究所 / 海试）的轻量化、零门槛、多语言适配核心需求，又预留了长远的工业级拓展接口，实现 “科研工具→工业级系统” 的平滑迭代。
+软件的核心价值并非技术栈本身，而是通过标准化、插件化、容错化的设计，为水声算法研发人员解决工程适配痛点，让客户聚焦算法本身，同时为公司打造水声算法调度领域的差异化竞争力，支撑商业长远发展。

docs/水声算法全协议集成与调度平台 - 需求规格说明书.md

@@ -0,0 +1,172 @@
+# 水声算法全协议集成与调度平台 - 需求规格说明书
+文档信息
+项目	内容
+文档版本	V1.0
+编写日期	2026.01
+适用范围	软件研发、测试、交付、客户使用指导
+目标客户	高校水声实验室、水声领域研究所、海试现场测试团队
+一、项目背景与目标
+1.1 项目背景
+当前水声算法研发场景中，存在多语言算法混用（Python/MATLAB/C/C++）、接口定义混乱、算法迭代频繁、跨语言调用复杂等问题，高校 / 研究所科研人员需投入大量精力解决工程适配问题，而非聚焦算法本身；海试现场则面临设备轻量化、操作零门槛、离线处理、快速出结果的核心诉求，现有工具无法同时满足科研试错与工程应用的双重需求。
+本公司作为 2-3 人规模的水声算法科技企业，依托 Python 核心技术栈，打造一款轻量化、高适配、零门槛的水声算法智能调度处理软件，解决行业核心痛点。
+1.2 项目目标
+功能目标：实现多语言算法统一纳管、复杂接口零代码适配、跨语言算法自由组合调度、全流程自动化处理与容错溯源，支持海试数据质量检测专属场景。
+性能目标：轻量化离线部署，客户侧零硬件成本，支持大体积水声数据分块处理，跨语言算法调用性能与原生调用持平，整体容错率≥95%。
+体验目标：Web 界面可视化操作，全程零代码 / 极简代码，客户无需掌握工程开发知识，10 分钟即可上手，错误可自主快速修复。
+商业目标：贴合微型企业研发节奏，快速落地商业化，同时预留工业级拓展接口，支撑长远业务发展。
+二、核心需求
+2.1 总体功能需求
+软件整体分为算法库管理模块、接口配置模块、算法调度模块、数据处理模块、容错溯源模块、客户扩展模块、海试专属模块七大核心模块，所有功能均通过 Web 界面实现，支持本地离线运行，无网络依赖。
+2.2 详细功能需求
+2.2.1 算法库管理模块
+双仓库管理
+内置官方标准算法库：包含水声通用算法（降噪、特征提取、频谱分析、数据清洗、质量检测等），支持一键调用、免费迭代更新。
+开放客户自定义算法库：支持客户上传自研算法，兼容 Python/MATLAB/C/C++ 多语言，算法按 “语言 - 名称 - 版本” 分类展示，支持搜索、筛选。
+黑盒化封装
+所有算法（标准 / 自研、任意语言）均封装为标准化黑盒插件，对内保留完整算法逻辑，对外仅暴露基于标准化中间数据的输入输出接口。
+系统自动完成算法的黑盒化处理，客户无需做任何封装、编译、转换操作。
+版本化管理
+支持算法多版本保存，自动按 “V + 数字” 打标版本号，也支持客户自定义版本号与版本备注。
+支持算法版本一键切换、回滚，可选择任意版本作为当前调用版本，无需重新配置接口。
+支持两个版本算法的效果对比：用同一组测试数据运行，自动生成维度、核心指标、可视化结果的对比报告。
+保留所有版本的修改日志（修改人、修改时间、备注），支持版本溯源与无用版本轻量删除。
+2.2.2 接口配置模块
+双接口模式
+通用接口模式：预设水声行业标准输入输出字段（如输入：清洗后数据 + 采样率；输出：特征数组 + 信噪比），一键调用，无需配置，适配 80% 常规场景。
+自定义接口模式：支持复杂接口零代码配置，适配科研试错的个性化需求。
+零代码配置能力
+支持通过下拉选择、字段拖拽、多字段组合完成输入 / 输出接口与标准化中间数据的映射。
+支持为映射字段添加轻量预处理，内置预处理算子库（维度展平 / 取维 / 切片、类型转换、归一化 / 标准化、空值过滤、平滑滤波等），一键选择即可应用。
+支持预处理规则保存为个人模板，后续配置可直接复用。
+实时强制校验
+配置过程中实时完成5 类核心校验，配错即时弹窗提示 + 红色高亮错误位置，错误配置无法保存：
+① 字段存在性校验：校验映射字段是否在标准化中间数据中存在 / 由前序算法生成；
+② 数据类型校验：校验字段类型与算法输入要求是否匹配；
+③ 数据维度校验：检测字段维度是否符合算法常规要求，不匹配则推荐预处理方案；
+④ 参数完整性校验：多参数映射时校验是否漏配，高亮未配置参数；
+⑤ 跨语言兼容性校验：配置非 Python 算法时，校验数据跨语言转换的兼容性。
+接口模板管理
+配置完成的通用 / 自定义接口均可保存为接口模板，标注模板名称与适用场景，后续调用算法可直接绑定模板，无需重新配置。
+2.2.3 算法调度模块
+可视化流程组合
+支持 Web 界面鼠标拖拽排序，自由组合官方标准算法与客户自研算法，支持 Python/MATLAB/C/C++ 跨语言混编。
+组合完成后系统自动做流程全局校验，校验前序算法输出与后序算法输入的接口衔接性，不匹配则即时提示并给出修复建议。
+文字指令智能调度
+支持客户输入自然语言指令（如 “检测海试声呐数据质量”“浅海低信噪比数据降噪 + STFT 特征提取”），系统自动解析意图、匹配场景算法，生成并执行调度流程。
+自动化调度执行
+按客户设定的顺序自动调度算法黑盒，全程完成标准化数据→语言专属数据→标准化数据的双向转换，客户无感知。
+支持非依赖型算法并行调度，提升大体积数据处理效率。
+执行过程中 Web 界面实时展示进度条 + 执行日志，显示当前执行算法、处理进度、耗时等信息。
+流程模板管理
+组合完成的算法调度流程可保存为流程模板（如 “海试数据质量检测流程”“浅海算法处理流程”），支持模板一键加载、修改、删除。
+2.2.4 数据处理模块
+标准化中间数据管理
+定义WaterSoundData为唯一数据交换标准，包含四大核心字段，支撑全流程数据流转：
+① 基础原始数据：原始声呐数据、采样率、采集时间、海洋环境参数等；
+② 处理过程数据：清洗后数据、降噪后数据、时频数据、特征数组等中间结果；
+③ 结果数据：最终处理结果、核心指标、可视化数据等；
+④ 元信息：数据状态、执行日志、错误信息、算法版本记录等。
+多语言数据转换
+由语言专属桥接插件完成无损数据转换，优先采用内存级传递（内存直接映射 / 指针传递）保证高性能，失败则采用文件级兜底（.npy/.mat/.bin 水声专属轻量化格式）。
+转换过程中自动完成数据类型、维度的适配，保证数据值与结构不丢失。
+大体积数据处理
+支持大体积水声数据自动分块处理，按水声数据特性拆分数据，逐块处理后自动合并结果，避免内存 / CPU 超限。
+分块规则可由客户在 Web 界面简单配置（如分块大小、合并方式），也可由系统自动适配。
+2.2.5 容错溯源模块
+三层递进容错体系
+配置阶段：实时校验 + 强制拦截，从根源拦截 90% 接口配置错误；
+转换阶段：自动兜底适配，对维度 / 类型不兼容、空值 / 无穷值、跨语言数据丢失等问题自动修复，修复过程记录日志；
+执行阶段：隔离式容错 + 降级执行，单个算法出错立即隔离，不影响整体流程；核心算法出错则自动调用同功能官方标准算法兜底执行，保证核心功能不丢失。
+可视化异常处理
+所有错误在 Web 界面异常中心集中展示，给出人话提示 + 一键修复建议，无需专业知识即可理解问题根源。
+支持异常快速定位，点击异常信息可直接跳转到对应的配置 / 执行页面，方便客户修改。
+全流程溯源
+自动生成结构化溯源日志，记录从接口配置→数据转换→算法执行→结果输出的每一步操作、数据变化、容错处理，按时间顺序排列，高亮异常步骤。
+自动生成接口配置校验报告，包含配置信息、校验结果、适配建议，支持日志与报告的在线查看、一键导出（JSON/Excel 格式）。
+错误修改便捷性
+接口配置与算法解耦，修改算法代码 / 参数无需重新配置接口，上传新文件即生效；
+所有修改操作均在原配置 / 执行界面完成，无需跳转其他页面，改完即保存、重新执行。
+2.2.6 客户扩展模块
+多语言算法上传
+支持客户上传各语言算法原始文件，操作极简，无需额外处理：
+① Python：上传.py 文件 / 直接粘贴函数代码；
+② MATLAB：上传.m 文件 / 直接粘贴函数代码；
+③ C/C++：上传单个.c/.cpp 文件 / 多文件压缩包，仅需填写核心函数名。
+系统自动完成 C/C++ 算法的编译（生成跨平台动态链接库）、所有语言算法的黑盒化封装，客户无感知。
+两种扩展方式
+零代码表单式（推荐，适配非开发岗）：全程 Web 界面选择、配置，无需写任何代码；
+极简代码式（适配开发岗）：提供封装好的扩展函数，5 行代码即可完成自研算法的注册与适配。
+轻量化环境适配
+若客户电脑无 C/C++ 编译器 / MATLAB 引擎，系统给出一键安装引导（轻量版 MinGW，50M 左右；oct2py 开源库），无需配置环境变量。
+技术支持入口
+Web 界面内置技术支持入口，客户可一键导出错误日志 + 配置报告，直接发送给厂家，方便快速定位问题。
+2.2.7 海试专属模块
+一键质量检测
+内置海试数据质量检测专属算法组合，支持客户上传海试原始数据，点击 “一键检测” 秒级出初步结果，几分钟内生成完整检测报告。
+简洁直观的检测报告
+报告包含核心检测指标（数据完整性、信噪比、数据噪声水平、有效数据占比）、异常点定位、检测结论（合格 / 不合格）、处理建议，支持报告导出（PDF/Excel 格式），适配现场汇报需求。
+轻量化操作优化
+海试模式下隐藏复杂配置功能，仅保留 “数据上传→一键检测→报告导出” 核心操作，界面简洁，非专业人员可快速上手。
+离线快速运行
+海试模式下系统自动优化资源占用，关闭非核心功能，保证在低配笔记本上也能快速、稳定运行，无卡顿、无崩溃。
+2.3 非功能需求
+2.3.1 性能需求
+部署性能：支持 Windows/Linux/macOS 跨平台运行，单实例运行内存占用≤4GB，CPU 占用可控；客户侧仅需 Python 运行环境，无需 GPU / 高端服务器，零硬件成本。
+执行性能：
+C/C++ 算法调用性能与原生编译执行持平，数据转换无额外损耗；
+海试数据质量检测秒级出初步结果，1GB 以内数据完整处理时间≤5 分钟；
+支持单文件≥10GB 的大体积数据分块处理，分块处理效率与单块处理持平。
+响应性能：Web 界面操作响应时间≤1s，接口配置实时校验响应时间≤0.5s，算法调度流程启动响应时间≤2s。
+2.3.2 稳定性与容错性需求
+整体容错率≥95%，其中接口配置准确率≥90%，执行异常处理率≥98%，结果准确性≥99%；
+支持 7×24h 连续运行，无卡死、无崩溃，可处理异常数据、复杂接口、跨语言混编等各类场景；
+任意算法 / 步骤执行失败，均有兜底方案，保证流程不中断、核心结果可输出；
+跨语言调用失败率≤1%，失败后自动切换兜底方案，无感知恢复。
+2.3.3 易用性需求
+全流程 Web 界面可视化操作，零代码 / 极简代码，科研人员 / 海试操作人员 10 分钟即可上手；
+错误提示为自然语言人话提示，避免专业技术术语，同时给出明确的修复建议；
+所有常用功能（算法上传、接口配置、流程组合）均有操作引导弹窗 / 图文帮助，支持一键关闭；
+界面布局简洁，按 “功能模块” 分栏，核心操作（如一键检测、一键执行）突出显示，适配客户操作习惯。
+2.3.4 安全性与兼容性需求
+离线安全性：全程本地离线运行，无网络传输，符合水声行业涉密数据管理要求，不收集、不存储客户任何算法与数据；
+数据安全性：客户算法与数据均存储在本地，系统仅做临时缓存，执行完成后可一键清理缓存，无数据泄露风险；
+环境兼容性：支持 Python3.8 及以上版本，兼容 MATLAB R2018 及以上版本，C/C++ 编译器兼容 MinGW/GCC/MSVC；
+格式兼容性：支持水声行业常用数据格式（.mat/.npy/.bin/.txt），输出结果可导出为 PDF/Excel/JSON 等通用格式。
+2.3.5 可维护性与可扩展性需求
+模块化设计：所有功能模块为可插拔式设计，开发、升级、维护互不影响；
+易开发维护：基于 Python 生态开发，代码简洁、可读性强，2-3 人团队可快速完成维护与迭代；
+易扩展：支持新增算法语言（如 Fortran/Julia）、新增预处理算子、新增容错规则，仅需开发对应轻量插件，无需重构核心代码；
+版本迭代：支持产品小版本热更新，客户无需重新安装，仅需替换插件 / 脚本即可完成升级。
+三、运行环境需求
+3.1 开发环境
+操作系统：Windows/Linux/macOS 均可；
+开发语言：Python3.8+，C/C++（仅用于跨语言桥接）；
+核心依赖：NumPy、SciPy、Streamlit、matlab.engine、oct2py、ctypes、cffi 等。
+3.2 客户运行环境
+3.2.1 基础环境
+操作系统：Windows 10/11、Linux（Ubuntu 18.04+）、macOS 10.15+；
+核心依赖：Python3.8+（一键安装，无需配置环境变量）；
+硬件配置：CPU≥4 核，内存≥8GB，硬盘剩余空间≥10GB（低配笔记本 / 办公电脑即可满足）。
+3.2.2 可选环境（按需自动安装）
+C/C++ 编译器：MinGW/GCC（轻量版，50M 左右，系统一键引导安装）；
+MATLAB 环境：MATLAB R2018+（可选，无则自动切换 oct2py 开源库兜底）。
+四、验收标准
+4.1 功能验收
+所有核心功能模块按需求实现，无功能缺失，操作流程与需求一致；
+多语言算法（Python/MATLAB/C/C++）均可正常上传、黑盒化、调用，跨语言混编组合流程可正常执行；
+复杂接口配置可完成所有个性化需求，实时校验准确，错误配置无法保存；
+容错体系有效，单个算法出错可隔离、核心算法可兜底，流程不中断；
+海试专属模块可实现一键检测，快速生成符合要求的检测报告。
+4.2 性能验收
+满足所有性能需求，部署在低配办公电脑上无明显卡顿，大体积数据可正常分块处理；
+C/C++ 算法调用性能与原生编译执行持平，数据转换无明显损耗；
+海试数据质量检测 1GB 以内数据完整处理时间≤5 分钟，秒级出初步结果；
+Web 界面操作响应时间≤1s，无延迟、无卡死。
+4.3 稳定性验收
+连续 72h 运行测试，无崩溃、无卡死，资源占用稳定；
+随机输入异常数据、配置复杂接口、进行跨语言混编，系统均可正常处理，容错率≥95%；
+任意算法执行失败，系统均可实现隔离或兜底，核心结果可正常输出。
+4.4 易用性验收
+非专业人员（无工程开发知识）按操作引导，10 分钟内可完成算法上传、接口配置、流程组合、执行的完整操作；
+错误提示清晰，修复建议明确，客户可自主完成 90% 以上的错误修改；
+所有常用功能均有操作引导，界面布局简洁，操作逻辑符合客户使用习惯。

docs/项目审查报告.md

@@ -0,0 +1,141 @@
+# 🌊 水声算法全协议集成与调度平台 项目审查报告
+
+---
+
+## 一、项目概况
+
+| 项目 | 内容 |
+|------|------|
+| **项目名称** | 水声算法全协议集成与调度平台 |
+| **目标客户** | 高校水声实验室、研究所、海试现场测试团队 |
+| **团队规模** | 2-3 人，核心技术栈 Python |
+| **当前状态** | Phase 1 已完成（核心框架），Phase 2-5 待开发 |
+
+---
+
+## 二、项目目标
+
+| 目标类型 | 描述 |
+|----------|------|
+| **功能目标** | 多语言算法统一纳管、零代码接口适配、跨语言混编调度、全流程容错溯源、海试数据质量检测 |
+| **性能目标** | 轻量化离线部署、1GB 数据 ≤5 分钟、容错率 ≥95%、C/C++ 原生性能 |
+| **体验目标** | Web 可视化、10 分钟上手、人话错误提示、一键修复 |
+| **商业目标** | 快速落地、预留工业级拓展接口 (C++/Qt) |
+
+---
+
+## 三、系统架构（五层设计）
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    用户交互层 (Streamlit)                    │
+├─────────────────────────────────────────────────────────────┤
+│                    核心调度层 (CoreScheduler)                │
+│         流程调度 | 实时校验 | 容错处理 | 日志记录              │
+├─────────────────────────────────────────────────────────────┤
+│                    桥接插件层 (Bridges)                      │
+│         PythonBridge | MATLABBridge | CppBridge             │
+├─────────────────────────────────────────────────────────────┤
+│                    算法层 (标准库 + 自定义库)                 │
+├─────────────────────────────────────────────────────────────┤
+│                    数据层 (WaterSoundData)                   │
+│         原始数据 | 过程数据 | 结果数据 | 元信息                │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 四、已完成模块 (Phase 1)
+
+| 模块 | 文件 | 状态 | 说明 |
+|------|------|------|------|
+| 数据标准 | `src/models.py` | ✅ 完成 | `WaterSoundData` 统一数据交换格式 |
+| Python 桥接 | `src/bridges.py` | ✅ 完成 | `AlgorithmBridge` 抽象类 + `PythonBridge` 实现 |
+| 核心调度 | `src/scheduler.py` | ✅ 完成 | `CoreScheduler` 流程执行与日志记录 |
+| Web 界面 | `main.py` | ✅ 完成 | Streamlit 首页 + 算法调度演示页 |
+| 集成测试 | `tests/test_core.py` | ✅ 通过 | 验证多算法链式调用 |
+
+---
+
+## 五、技术风险分析与应对策略
+
+### 5.1 核心风险点
+
+| 风险 | 级别 | 分析 | 应对策略 |
+|------|------|------|----------|
+| **C++ 编译器环境** | 🔴 高 | Windows 上 MinGW 路径配置是非开发人员的噩梦 | **优雅降级**：无编译器时禁用 C++ 上传功能，而非强行引导安装 |
+| **Streamlit 拖拽限制** | 🟡 中 | 原生不支持复杂连线 | **列表式调度**：先用上下移动排序，跑通再考虑 Canvas 可视化 |
+| **MATLAB Octave 差异** | 🟡 中 | oct2py 对复杂 Toolbox 支持有限 | **文档说明**：推荐 MATLAB，兼容模式注明精度差异 |
+| **大数据内存** | 🟢 低 | 10GB 单文件场景少见，海试数据多分段采集 | **后期优化**：Phase 4 再引入 memmap |
+
+### 5.2 设计原则
+
+> **先让系统跑起来，再让系统跑得好。**
+
+避免过早优化，聚焦最小可用版本 (MVP)。
+
+---
+
+## 六、修订后实施计划
+
+### Phase 2：算法库与接口配置（预计 5 天）— **MVP 聚焦**
+
+| 任务 | 描述 | 产出物 | 优先级 |
+|------|------|--------|--------|
+| 2.1 算法上传 | Python 文件上传、版本自动打标 | `src/algo_library.py` | P0 |
+| 2.2 元数据存储 | JSON 持久化算法信息 | `data/algorithms.json` | P0 |
+| 2.3 接口映射 | 下拉选择字段、简单预处理 | `src/interface_config.py` | P0 |
+| 2.4 实时校验 | 5 类校验规则实现 | `src/validators.py` | P0 |
+| 2.5 流程排序 | 列表式上下移动（不做拖拽） | 界面更新 | P1 |
+
+### Phase 3：多语言桥接（预计 4 天）
+
+| 任务 | 描述 | 产出物 | 优先级 |
+|------|------|--------|--------|
+| 3.1 MATLAB 桥接 | matlab.engine + oct2py 兜底 | `src/bridges_matlab.py` | P0 |
+| 3.2 C++ 编译检测 | 检测 gcc，无则禁用 C++ 功能 | `src/cpp_compiler.py` | P1 |
+| 3.3 C++ 桥接 | ctypes 加载（仅限有编译器环境） | `src/bridges_cpp.py` | P1 |
+
+### Phase 4：容错与溯源（预计 3 天）
+
+| 任务 | 描述 | 产出物 |
+|------|------|--------|
+| 4.1 三层容错 | 配置拦截、转换修复、执行兜底 | `src/fault_tolerance.py` |
+| 4.2 溯源日志 | 结构化日志、时间轴展示 | `src/traceability.py` |
+| 4.3 异常中心 | 错误列表、一键跳转修复 | 界面页 |
+| 4.4 大数据优化 | memmap + 分块处理（可选） | 性能优化 |
+
+### Phase 5：海试专属与打包（预计 3 天）
+
+| 任务 | 描述 | 产出物 |
+|------|------|--------|
+| 5.1 海试模式 | 简化界面、内置质量检测流程 | `src/seatrial_mode.py` |
+| 5.2 报告生成 | PDF/Excel 导出 | `src/report_generator.py` |
+| 5.3 产品打包 | PyInstaller 生成可执行文件 | 交付包 |
+
+---
+
+## 七、里程碑时间线（总计 15 天 — 海音·智调 1.0 版本）
+
+```
+Week 1: Phase 2 (算法库 + 接口配置) — MVP 核心
+Week 2: Phase 3 (MATLAB + C++ 桥接) — 多语言支持
+Week 3: Phase 4 + 5 (容错 + 海试 + 打包) — 产品化
+```
+
+---
+
+## 八、关键决策记录
+
+| 决策 | 理由 | 日期 |
+|------|------|------|
+| 暂定全称为：水声算法全协议集成与调度平台 | 回归技术本质，强调“全协议”兼容性，品牌名称推迟至发布前确定 | 2026-01-20 |
+| 采用列表式调度而非拖拽连线 | Streamlit 原生限制 + 开发成本 | 2026-01-20 |
+| C++ 环境采用"优雅降级"策略 | 避免非开发人员配置编译器的门槛 | 2026-01-20 |
+| 大数据 memmap 优化推迟至 Phase 4 | 目标场景以分段数据为主，10GB 单文件少见 | 2026-01-20 |
+| 算法能力标签系统简化为"类型下拉" | 降低上传门槛，后期再细化 | 2026-01-20 |
+
+---
+
+*报告生成时间：2026-01-20*
+*最后更新：2026-01-20 20:19*