自定义插件

1. 引言

本文档概要阐述了如何开发基于 ICustomComponent 接口的自定义节点组件插件，以便在流程编辑器中创建可拖放的交互节点。 这些节点将允许用户配置表单、连接数据流，并在流程执行时执行特定的业务逻辑。遵循以下步骤和规范，将有助于快速理解和开始插件开发。

更详细的使用请到 torchdb.plugins 包下查看系统自带插件的源码。

2. 类结构与接口

2.1 ICustomComponent

属性

• display_name: (str) 组件的显示名称，用于识别节点。
• description: (str) 描述组件的功能和用途。
• icon: (str) 图标路径，用于视觉区分不同类型的节点。
• inputs & outputs: (List[Dock]) 分别表示组件的输入和输出停靠点，用于数据流连接。
• category: (str) 组件分类，用于组织和排序节点。
• position: (int) 排序位置，数值越小越靠前。
• experimental: (bool) 标记为实验性，可能包含未稳定的功能。
• form: (ComponentPropsForm) 子类用于快速生成表单的工具类。

方法

• bind(self, dock_name: str, value: Any, **kwargs): 将值绑定到输出停靠点。
• error(self, msg: str, **kwargs): 记录并可能显示错误信息。
• context(self, **kwargs): 获取流程上下文。
• upstream(self, docker_name: str, many: bool = False, **kwargs): 获取上一个节点的输入值。many 是否允许接受多个输入。
• template(self, form_field_name: str, **kwargs): 使用模板变量处理表单项值。
• empty(self, value: any, default_value: any = ''): 处理表单项值缺失时的默认行为。
• parametric(self, name: str, **kwargs): 优先使用流程参数。
• config(self): 子类自定义表单配置。
• build(self, **kwargs): 流程执行时的业务逻辑核心，需子类实现。

2.2 Dock & DockDataType

• Dock: 定义输入/输出的元数据，包括名称、数据类型、标题等。
• DockDataType: 数据类型枚举，如字符串、整数、浮点数等。

Dock 类

class Dock:
    # 输入输出定义
    name: str
    # 值类型, DockDataType, 可根据需要自行添加自己的数据类型, 用于连线检查及是否可以连线。
    dtype: str
    # 停靠点名称
    title: str
    # 控制是否接受多输入
    many: bool = False,
    # 控制输入dock可以在模版中被使用
    use_in_template: bool = False

DockDataType 类

class DockDataType(Enum):
    ANY = "ANY"
    STR = "STR"
    INT = "INT"
    FLOAT = "FLOAT"
    NUMERIC = "NUMERIC"
    BOOL = "BOOL"
    LIST = "LIST"
    DICT = "DICT"
    DATAFRAME = "DATAFRAME"
    CHAT_MODEL = "CHAT_MODEL"
    EMBEDDING_MODEL = "EMBEDDING_MODEL"
    AGENT_ACTION = "AGENT_ACTION"
    TOOLS = "TOOLS"
    DOCUMENTS = "DOCUMENTS"
    DATABASE = "DATABASE"

2.3 ComponentPropsForm

ComponentPropsForm类提供了创建表单项的方法。

• input(self, **kwargs): 用于添加输入字段，其中kwargs用于设置输入框的属性或选项。
• markdown(self, **kwargs): 用于添加Markdown文本，其中kwargs用于设置Markdown文本的属性或选项。
• code(self, **kwargs): 用于添加代码编辑器组件。
• sql(self, **kwargs): 用于添加SQL查询组件。
• password(self, **kwargs): 用于添加密码输入字段。
• number_picker(self, **kwargs): 用于添加数字选择器组件。
• text(self, **kwargs): 用于添加文本输入字段。
• switch(self, **kwargs): 用于添加开关按钮组件。
• select(self, options=None, **kwargs): 用于添加选择器组件，其中options参数表示可选的值列表，kwargs用于设置其他属性。
• checkbox(self, options=None, **kwargs): 用于添加复选框组件。
• radio(self, options=None, **kwargs): 用于添加单选按钮组件。
• params(self, **kwargs): 用于添加具有数据类型约束的函数参数输入组件。
• plain_params(self, **kwargs): 用于添加没有数据类型约束的函数参数输入组件。
• configure(self, **kwargs): 用于添加具备配置项功能的输入组件。
• text_items(self, plain=False, **kwargs): 用于添加单行文本数组项，其中plain参数表示不使用markdown作为输入。

3. 开发流程

3.1 创建子类

继承 ICustomComponent ，并实现必要的属性和方法。确保 build() 方法实现核心业务逻辑。

class CustomComponent(ICustomComponent):
    # 实现自定义属性和方法
    ...

3.2 配置表单

在 config() 方法中返回表单配置，定义组件的输入和输出字段。

class TextMessageComponent(ICustomComponent):
    display_name = "文本消息"
    description = "构造消息、提示词或者其他文本内容"
    category = "inputs"
    position = 1

    inputs = [
        Dock(name="data", dtype=DockDataType.ANY.value, title="数据", use_in_template=True)
    ]

    outputs = [
        Dock(name="message", dtype=DockDataType.STR.value, title="消息"),
    ]

    def config(self) -> dict:
        return {
            "message": self.form.markdown(title="消息", required=True)
        }

    def build(self, **kwargs):
        self.bind("message", self.template("message", **kwargs), **kwargs)

3.3 连接数据流

在 bind() 方法中处理节点间的数据传递。

self.bind("message", self.template("message", **kwargs), **kwargs)

3.4 处理空值和模板

empty() 和 template() 方法用于处理表单值的空值以及模板变量的使用。

3.5 错误处理

在 error() 方法中记录和报告错误信息。

3.6 流程上下文管理

context() 方法获取流程上下文，upstream() 方法获取上游节点的输入值。

3.7 注册与部署

将包含自定义组件的插件放到 torchdb.plugins 模块下。再次启动系统刷新界面则可以看到自定义的节点组件。