Panda Plugins 模块参考手册

本此文档详细描述了 src/panda_plugins 下的所有内置节点。文档由工具自动生成，确保与代码实现保持同步。

1. 目录结构概览

src/panda_plugins/
├── base/                   # 插件系统基础框架 (BaseWorkNode, 注册机制)
├── internal/               # 内置节点库 (官方提供)
│   ├── models/             # 节点间数据交互模型 (Pydantic Models)
│   ├── ...                 # 各类功能节点 (CSV, ML, Factor, Backtest)
├── utils/                  # 插件加载与辅助工具 (Loader, ErrorCode)
└── custom/                 # 用户自定义节点目录 (示例与扩展)

2. 基础框架 (Base Framework)

src/panda_plugins/base 定义了节点开发的基类和核心装饰器。

BaseWorkNode

所有节点的基类。

• run(self, input): 核心执行逻辑。
• input_model(cls): 定义输入数据结构。
• output_model(cls): 定义输出数据结构。

核心装饰器

• @work_node(name, group, type): 注册节点。
• @ui(...): 定义 UI 控件元数据。

3. 内置节点库 (Internal Nodes)

以下章节按照节点分组 (Group) 排列。

01-基础工具

Python代码输入

• 文件: code_node.py
• 类名: CodeControl

输入参数 (Input):

参数名	类型	描述	默认值
code	str	策略代码	‘’

输出数据 (Output):

参数名	类型	描述
code	str	策略代码

---

02-特征工程

特征工程构建

• 文件: feature_engineering_build_node.py
• 类名: FeatureEngineeringBuildNode

输入参数 (Input):
无

输出数据 (Output):
无

---

特征工程构建（旧）

• 文件: feature_engineering_node.py
• 类名: FeatureEngineeringNode

输入参数 (Input):

参数名	类型	描述	默认值
formulas	str	特征公式	‘’
label	str	标签公式	‘’

输出数据 (Output):

参数名	类型	描述
feature_model	FeatureModel	特征工程

---

公式输入

• 文件: formula_node.py
• 类名: FormulaControl

输入参数 (Input):

参数名	类型	描述	默认值
formulas	str	公式	‘’

输出数据 (Output):

参数名	类型	描述
formulas	str	公式

---

03-机器学习

LightGBM模型

• 文件: lightgbm_node.py
• 类名: LightGBMControl

输入参数 (Input):

参数名	类型	描述	默认值
feature	FeatureModel	特征工程	‘’
start_date	str	训练开始时间	‘20250101’
end_date	str	训练结束时间	‘20250301’
n_estimators	int	决策树数量	100
max_depth	int	最大深度	3
learning_rate	float	学习率	0.1
num_leaves	int	叶子节点数量	31
subsample	float	子样本比例	0.8
colsample_bytree	float	列采样比例	0.8
reg_alpha	float	L1正则化	0
reg_lambda	float	L2正则化	1

输出数据 (Output):
无

---

GRU模型

• 文件: ml_gru_node.py
• 类名: GRUControl

输入参数 (Input):

参数名	类型	描述	默认值
factor	pd.DataFrame	特征值
time_step	int	时间步长	10
units	int	LSTM单元数	50
batch_size	int	批大小	32
epochs	int	训练轮数	10
dropout_rate	float	Dropout比例	0.2
learning_rate	float	学习率	0.001

输出数据 (Output):
无

---

LSTM模型

• 文件: ml_lstm_node.py
• 类名: LSTMControl

输入参数 (Input):

参数名	类型	描述	默认值
factor	pd.DataFrame	特征值
time_step	int	时间步长	10
units	int	LSTM单元数	50
batch_size	int	批大小	32
epochs	int	训练轮数	10
dropout_rate	float	Dropout比例	0.2
learning_rate	float	学习率	0.001

输出数据 (Output):
无

---

Xgboost模型

• 文件: ml_xgboost_node.py
• 类名: MLXgboostControl

输入参数 (Input):

参数名	类型	描述	默认值
factor	pd.DataFrame	特征值
n_estimators	int	决策树数量	100
max_depth	int	最大深度	3
learning_rate	float	学习率	0.1
min_child_weight	int	最小子权重	1
gamma	float	Gamma	0
subsample	float	子样本比例	1
colsample_bytree	float	列采样比例	1
reg_alpha	int	L1正则化	0
reg_lambda	int	L2正则化	1

输出数据 (Output):
无

---

多任务神经网络

• 文件: mtl_nn_node.py
• 类名: MTLNNControl

输入参数 (Input):

参数名	类型	描述	默认值
feature1	FeatureModel | None	特征工程1	None
feature2	FeatureModel | None	特征工程2	None
feature3	FeatureModel | None	特征工程3	None
feature4	FeatureModel | None	特征工程4	None
feature5	FeatureModel | None	特征工程5	None
start_date	str	训练开始时间	‘20250101’
end_date	str	训练结束时间	‘20250301’
epochs	int	训练轮数	100
hidden_dim	int	隐藏层维度	64
lr	float	学习率	0.001

输出数据 (Output):
无

---

随机森林模型

• 文件: randomforest_node.py
• 类名: RandomForestControl

输入参数 (Input):

参数名	类型	描述	默认值
feature	FeatureModel	特征工程	‘’
start_date	str	训练开始时间	‘20250101’
end_date	str	训练结束时间	‘20250301’
n_estimators	int	决策树数量	100
max_depth	int	最大深度	None
min_samples_split	int	最小分裂样本数	2
min_samples_leaf	int	叶节点最小样本数	1
max_features	str	最大特征数	‘sqrt’
bootstrap	bool	自助采样	True
oob_score	bool	OOB评分	False
random_state	int	随机种子	42
n_jobs	int	并行任务数	-1

输出数据 (Output):
无

---

SVM模型

• 文件: svm_node.py
• 类名: SVMControl

输入参数 (Input):

参数名	类型	描述	默认值
feature	FeatureModel	特征工程	‘’
start_date	str	训练开始时间	‘20250101’
end_date	str	训练结束时间	‘20250301’
kernel	str	核函数类型	‘rbf’
degree	int	多项式核函数次数	3
gamma	str	核函数系数	‘scale’
coef0	float	核函数独立项	0.0
C	float	正则化参数	1.0
epsilon	float	SVR模型中的Epsilon值	0.1
shrinking	bool	是否使用收缩启发式	True
cache_size	int	核缓存大小(MB)	200
max_iter	int	最大迭代次数	1000
tol	float	停止准则容差	0.001

输出数据 (Output):
无

---

Xgboost模型(旧)

• 文件: xgboost_node.py
• 类名: XgboostControl

输入参数 (Input):

参数名	类型	描述	默认值
feature	FeatureModel	特征工程	‘’
start_date	str	训练开始时间	‘20250101’
end_date	str	训练结束时间	‘20250301’
n_estimators	int	决策树数量	100
max_depth	int	最大深度	3
learning_rate	float	学习率	0.1
min_child_weight	int	最小子权重	1
gamma	float	Gamma	0
subsample	float	子样本比例	1
colsample_bytree	float	列采样比例	1
reg_alpha	float	L1正则化	0
reg_lambda	float	L2正则化	1

输出数据 (Output):
无

---

04-因子相关

因子分析结果

• 文件: factor_analysis_chart_node.py
• 类名: FactorAnalysisChartControl

输入参数 (Input):

参数名	类型	描述	默认值
task_id	str	分析结果	‘error’

输出数据 (Output):

参数名	类型	描述
task_id	str	图表绘制

---

因子分析

• 文件: factor_analysis_node.py
• 类名: FactorAnalysisControl

输入参数 (Input):

参数名	类型	描述	默认值
df_factor	object	因子值
adjustment_cycle	str	调仓周期	‘1’
group_number	str	分组数量	‘5’
factor_direction	str	因子方向(0:正向，1:负向)	‘0’

输出数据 (Output):

参数名	类型	描述
task_id	str	分析结果

---

因子构建节点

• 文件: factor_build_node.py
• 类名: FactorBuildControl

输入参数 (Input):

参数名	类型	描述	默认值
start_date	str	因子开始时间	‘20250101’
end_date	str	因子结束时间	‘20250301’
formulas	str	因子公式	‘’

输出数据 (Output):

参数名	类型	描述
factor	DataFrame

---

综合因子构建节点

• 文件: factor_build_node_pro.py
• 类名: FactorBuildProControl

输入参数 (Input):

参数名	类型	描述	默认值
start_date	str	开始时间	‘20250101’
end_date	str	结束时间	‘20250301’
code	str	因子代码	‘’
market	str	因子类型	‘股票’
type	str	编码方式	‘Python’
direction	str	因子方向	‘正向’

输出数据 (Output):

参数名	类型	描述
factor	DataFrame	因子值

---

因子相关性分析

• 文件: factor_correlation_calculation_node.py
• 类名: FactorCorrelationCalculationControl

输入参数 (Input):

参数名	类型	描述	默认值
factor	object | None	因子组	None

输出数据 (Output):

参数名	类型	描述
task_id	str	分析结果

---

因子相关性分析结果

• 文件: factor_correlation_chart_node.py
• 类名: FactorCorrelationChartControl

输入参数 (Input):

参数名	类型	描述	默认值
task_id	str	分析结果	‘error’

输出数据 (Output):

参数名	类型	描述
task_id	str	图表绘制

---

因子集合器

• 文件: factor_to_group_node.py
• 类名: FactorToGroupControl

输入参数 (Input):

参数名	类型	描述	默认值
factor1	object | None	因子/因子组1	None
factor2	object | None	因子/因子组2	None
factor3	object | None	因子/因子组3	None
factor4	object | None	因子/因子组4	None
factor5	object | None	因子/因子组5	None

输出数据 (Output):

参数名	类型	描述
merged_factors	object	因子组

---

因子权重调整（归一化）

• 文件: factor_weight_adjust_node.py
• 类名: FactorWeightAdjustControl

输入参数 (Input):

参数名	类型	描述	默认值
df_factor	object	因子值
weight	float	权重	1.0

输出数据 (Output):

参数名	类型	描述
df_factor	object	因子值

---

因子构建(机器学习)

• 文件: ml_factor_build_node.py
• 类名: MLFactorBuildControl

输入参数 (Input):

参数名	类型	描述	默认值
model	MLModel	机器学习模型
feature	FeatureModel	特征工程
start_date	str	开始时间	‘20250101’
end_date	str	结束时间	‘20250301’

输出数据 (Output):

参数名	类型	描述
factor	Any	因子值

---

多因子合并(5-1)

• 文件: multi_factor_merge_node.py
• 类名: MultiFactorMergeControl

输入参数 (Input):

参数名	类型	描述	默认值
factor1	object | None	因子1	None
factor2	object | None	因子2	None
factor3	object | None	因子3	None
factor4	object | None	因子4	None
factor5	object | None	因子5	None

输出数据 (Output):

参数名	类型	描述
merged_factors	object	因子值

---

05-回测相关

期货回测

• 文件: backtest_future_node.py
• 类名: FutureBacktestControl

输入参数 (Input):

参数名	类型	描述	默认值
code	str	策略代码	‘’
factors	pd.DataFrame	因子值
start_future_capital	int	初始资金	10000000
commission_rate	int	佣金倍率	1
margin_rate	int	保证金倍率	1
frequency	str	回测频率	‘1d’
start_date	str	开始日期	‘20241022’
end_date	str	结束日期	‘20241231’

输出数据 (Output):

参数名	类型	描述
backtest_id	str	回测任务

---

策略回测结果

• 文件: backtest_result_node.py
• 类名: BackTestResultControl

输入参数 (Input):

参数名	类型	描述	默认值
task_id	str	回测任务	‘error’

输出数据 (Output):

参数名	类型	描述
task_id	str	图表绘制

---

股票回测

• 文件: backtest_stock_node.py
• 类名: StockBacktestControl

输入参数 (Input):

参数名	类型	描述	默认值
code	str	策略代码	‘’
factors	pd.DataFrame	因子值
start_capital	int	初始资金	10000000
standard_symbol	str	基准指数	‘上证指数’
commission_rate	int	佣金率	1
frequency	str	回测频率	‘1d’
start_date	str	回测开始时间	‘20241001’
end_date	str	回测结束时间	‘20241231’

输出数据 (Output):

参数名	类型	描述
backtest_id	str	回测id

---

06-线下课专属

因子IC计算

• 文件: factor_ic_calculation_node.py
• 类名: FactorICCalculationControl

输入参数 (Input):

参数名	类型	描述	默认值
df_factor	object	因子值
adjustment_cycle	str	调仓周期	‘1’
group_number	str	分组数量	‘5’
factor_direction	str	因子方向(0:正向，1:负向)	‘0’

输出数据 (Output):

参数名	类型	描述
ic_value	str	因子权重列表

---

因子权重组合

• 文件: factor_weight_calculation_node.py
• 类名: FactorWeightCalculationControl

输入参数 (Input):

参数名	类型	描述	默认值
df_factor	object	因子值
factor_weight	str	因子权重列表	‘error’

输出数据 (Output):

参数名	类型	描述
df_factor	object	因子值

---

多因子构建(机器学习)

• 文件: ml_multi_factor_build_node.py
• 类名: MLMultiFactorBuildControl

输入参数 (Input):

参数名	类型	描述	默认值
model1	MLModel	机器学习模型1
features1	FeatureModel	特征工程1
model2	MLModel | None	机器学习模型2	None
features2	FeatureModel | None	特征工程2	None
model3	MLModel | None	机器学习模型3	None
features3	FeatureModel | None	特征工程3	None
model4	MLModel | None	机器学习模型4	None
features4	FeatureModel | None	特征工程4	None
model5	MLModel | None	机器学习模型5	None
features5	FeatureModel | None	特征工程5	None
start_date	str	因子回测开始时间	‘20250101’
end_date	str	因子回测结束时间	‘20250301’

输出数据 (Output):

参数名	类型	描述
factor	Any

---

因子构建(机器学习-单模型多特征)

• 文件: mtl_factor_build_node.py
• 类名: MTLFactorBuildControl

输入参数 (Input):

参数名	类型	描述	默认值
model	MLModel	机器学习模型
feature1	FeatureModel | None	特征工程1	None
feature2	FeatureModel | None	特征工程2	None
feature3	FeatureModel | None	特征工程3	None
feature4	FeatureModel | None	特征工程4	None
feature5	FeatureModel | None	特征工程5	None
start_date	str	因子回测开始时间	‘20250101’
end_date	str	因子回测结束时间	‘20250301’

输出数据 (Output):

参数名	类型	描述
factor	Any

---

PCA因子构建

• 文件: pca_factor_build_node.py
• 类名: PCAFactorBuildControl

输入参数 (Input):

参数名	类型	描述	默认值
model	MLModel	机器学习模型
feature	FeatureModel	特征工程
test_start_date	str	因子回测开始时间	‘20250101’
test_end_date	str	因子回测结束时间	‘20250301’
predict_start_date	str	因子预测开始时间	‘20250301’
predict_end_date	str	因子预测结束时间	‘20250501’

输出数据 (Output):

参数名	类型	描述
factor	Any	复合因子得分
weights	list	因子权重

---

Spearman因子构建

• 文件: spearman_factor_build_node.py
• 类名: SpearmanFactorBuildControl

输入参数 (Input):

参数名	类型	描述	默认值
model	MLModel	机器学习模型
feature	FeatureModel	特征工程
start_date	str	因子回测开始时间	‘20250101’
end_date	str	因子回测结束时间	‘20250301’

输出数据 (Output):

参数名	类型	描述
factor	Any

---

4. 案例演示 (Example Scenarios)

本节展示代码如何在节点间流转并最终被执行。

核心概念：代码即数据

在 Panda Quantflow 中，CodeControl (Python代码输入) 节点本身不执行代码。它的作用是提供一个编辑器让用户输入代码，并将这段代码封装为字符串数据传递给下游节点。真正的执行发生在下游节点（如回测节点、特征构建节点）中。

示例：如何运行自定义回测策略

假设你希望运行一段 Python 策略代码。你需要将 CodeControl 节点与 StockBacktestControl 节点连接。

1. 工作流配置

1. 节点 A: CodeControl (Python代码输入)
   • 在 UI 编辑器中输入策略逻辑（例如 initialize 和 handle_data 函数）。
2. 节点 B: StockBacktestControl (股票回测)
   • 将 节点 A 的输出连接到 节点 B 的 code 输入端口。

2. 代码流转模拟脚本

以下脚本模拟了上述两个节点在后台的交互过程：

import pandas as pd
from panda_plugins.internal.code_node import CodeControl, CodeInputModel
from panda_plugins.internal.backtest_stock_node import StockBacktestControl, StockBacktestInputModel

# 1. 用户在 CodeControl 节点中输入的策略代码
user_strategy_code = """
def initialize(context):
    g.security = '600519.SH'
    print("策略初始化完成")

def handle_data(context, data):
    # 简单的买入逻辑
    if context.portfolio.positions[g.security].amount == 0:
        order(g.security, 100)
        print(f"买入 {g.security}")
"""

# 2. 运行 CodeControl 节点
# 该节点仅负责封装和传递代码字符串
code_node = CodeControl()
code_input = CodeInputModel(code=user_strategy_code)
code_output = code_node.run(code_input)
print(f"CodeControl 输出类型: {type(code_output)}")
print(f"传递的代码长度: {len(code_output.code)}")

# 3. 运行 StockBacktestControl 节点
# 该节点接收代码字符串，并调用回测引擎执行
backtest_node = StockBacktestControl()

# 注意：这里将上一个节点的输出 (code_output.code) 作为输入
backtest_input = StockBacktestInputModel(
    code=code_output.code,          # <--- 核心：代码在此处传入
    factors=pd.DataFrame(),         # 实际使用时需传入因子数据
    start_capital=1000000,
    start_date="20240101",
    end_date="20240201"
)

# 触发回测 (模拟执行)
# backtest_node.run(backtest_input) 
# print("回测节点已接收代码并开始执行...")

3. 执行原理

• CodeControl.run(): return CodeOutputModel(code=input.code)。单纯的数据透传。
• StockBacktestControl.run(): 接收 input.code，内部调用 panda_backtest.start(code=input.code, ...)。此时代码才被解释器执行。

5. 用户自建节点 (Custom Nodes)

Panda Plugins 提供了强大的扩展能力，允许用户在 src/panda_plugins/custom 目录下创建自定义节点。系统会自动扫描并加载该目录下的所有节点，使其即刻在工作流编辑器中可用。

5.1 目录规范与加载机制

系统默认加载 src/panda_plugins/custom 目录下的所有 Python 文件。
推荐的目录结构如下：

src/panda_plugins/custom/
├── __init__.py
├── my_feature_nodes.py          # 您的特征处理节点
├── my_analysis_nodes.py         # 您的分析工具节点
└── examples/                    # (可选) 参考案例
    ├── example_basic.py
    └── example_advanced_input_control.py

5.2 开发流程

创建一个自定义节点仅需简单的 4 步：

1. 定义输入模型 (InputModel): 使用 pydantic.BaseModel 定义节点接收的参数。
2. 定义输出模型 (OutputModel): 定义节点返回的数据结构。
3. 配置 UI (Optional): 使用 @ui 装饰器自定义输入参数在前端的控件类型（如文件选择器、下拉框等）。
4. 实现核心逻辑: 继承 BaseWorkNode 并重写 run 方法。

5.3 进阶案例：模型上传节点 (Model Upload)

本案例展示如何开发一个带有文件上传功能的节点。该节点允许用户在前端界面选择本地的模型文件（如 .pkl, .pth），并在工作流中加载使用。

功能亮点:

• 使用 file_picker UI 控件。
• 模拟模型加载过程。
• 错误处理与状态返回。

from typing import Optional, Type
import os
# 导入基础组件
from panda_plugins.base import BaseWorkNode, work_node, ui
from pydantic import BaseModel, Field

# ---------------------------------------------------------------------
# 1. 定义输入模型
# ---------------------------------------------------------------------
# 使用 @ui 装饰器指定 model_path 字段在前端显示为文件选择器
@ui(
    model_path={"input_type": "file_picker", "placeholder": "请选择模型文件"}
)
class ModelUploadInput(BaseModel):
    # default="" 确保默认状态为空
    model_path: str = Field(default="", title="模型文件路径")
    load_mode: str = Field(default="safe", title="加载模式")  # 普通文本输入

# ---------------------------------------------------------------------
# 2. 定义输出模型
# ---------------------------------------------------------------------
class ModelUploadOutput(BaseModel):
    loaded_model_path: str = Field(title="已加载模型路径")
    status: str = Field(title="加载状态")
    message: str = Field(title="详细信息")

# ---------------------------------------------------------------------
# 3. 注册节点与实现逻辑
# ---------------------------------------------------------------------
@work_node(name="自定义模型加载器", group="用户自建", box_color="green")
class ModelUploadNode(BaseWorkNode):
    """
    用户自定义节点案例：
    用于演示如何通过 file_picker 上传并加载外部模型文件。
    """
    
    @classmethod
    def input_model(cls) -> Optional[Type[BaseModel]]:
        return ModelUploadInput

    @classmethod
    def output_model(cls) -> Optional[Type[BaseModel]]:
        return ModelUploadOutput

    def run(self, input: BaseModel) -> BaseModel:
        # 获取输入路径
        path = input.model_path
        mode = input.load_mode
        
        print(f"尝试加载模型: {path} (模式: {mode})")
        
        # 模拟：检查文件是否存在
        if not path or not os.path.exists(path):
            self.log_error(f"文件不存在或路径为空: {path}")
            return ModelUploadOutput(
                loaded_model_path="", 
                status="Failed", 
                message="File not found"
            )
            
        # 模拟：加载逻辑 (实际场景中可使用 joblib.load 或 torch.load)
        # model = joblib.load(path)
        
        self.log_info(f"模型加载成功: {path}")
        
        return ModelUploadOutput(
            loaded_model_path=path, 
            status="Success", 
            message=f"Model loaded in {{mode}} mode"
        )

# ---------------------------------------------------------------------
# 4. 本地测试代码 (If Name is Main)
# ---------------------------------------------------------------------
if __name__ == "__main__":
    # 实例化节点
    node = ModelUploadNode()
    
    # 模拟输入数据 (假设当前目录下有个 dummy.pkl)
    input_data = ModelUploadInput(model_path="./dummy.pkl", load_mode="fast")
    
    # 运行节点
    result = node.run(input_data)
    print("运行结果:", result)

5.4 UI 控件类型参考

在 @ui 装饰器中，input_type 支持以下控件类型，满足丰富的交互需求：

控件类型 (input_type)	描述	适用场景
text_field	单行/多行文本框	普通字符串、备注、名称
number_field	数字输入框	阈值、金额、数量 (int/float)
code_editor	代码编辑器	输入 Python/SQL 代码，带语法高亮
file_picker	文件选择器	上传本地文件、选择数据文件
combobox	下拉选择框	从预设选项中选择 (需配合 options 参数)
switch	开关	布尔值 (True/False)
slider	滑动条	范围数值选择 (需配置 min/max)
date_picker	日期选择器	选择年-月-日
time_picker	时间选择器	选择时:分:秒
password_field	密码框	敏感信息输入 (掩码显示)