插件系统改进

[Monomux]

问题

目前的插件功能实现还是有点野路子，存在一些问题：

• 尽管可以通过自定义插件实现一些软件做不到的功能，但是对于部分需求的实现来说，采用现有的框架还是有点麻烦。如 希望能增加一个随机参数的功能 #122 中的需求实现，我给出的三种方案均是在运行时对执行事件进行修改，实际上如果能在脚本解析时将自定义的参数转化成相应的事件就可以实现相同的结果，并且可读性更高一些(issue用户的建议)。
• 目前一次只能加载一个扩展实例，目前的项目较小，这种实现尚可以接受但不够规范。参考其它软件的插件系统，需要一个插件管理器管理所有插件的注册与调用。

改进

我对插件系统的改进有以下想法：

• 扩展接口：提供解析脚本的接口，使得一些修改原始参数的操作在解析时完成而不是运行时，使脚本看起来更可读。
• 引入插件管理器：插件的注册与调用交由管理器统一管理，因此可以添加多个不同类型的插件(如改变程序的主题)。

[Monomux]

下面是关于实现的想法：

插件类型

目前想到的插件类型仅有对解析和执行流程的修改插件(mod)和改变主题的插件(theme)。mod可以在现有的实现上修改，theme可以参考qt-material的配置写xml文件，在加载中提供xml文件路径即可。

插件加载

目前考虑在plugins文件夹下新建配置文件指定加载的插件，比如settings.json，格式类似:

{
    "plugins": [
        {"type": "Theme", "path": "MyTheme.xml"},
        {"type": "Mod", "path": "MyPlugin.py"}
    ]
}

在程序每次执行启动或录制时插件管理器都会先检查配置文件以实现热更新。程序中的插件选择控件则可以移除。

功能移除

改变执行速度这个功能感觉可有可无，可以写成一个插件，使界面更简洁。

[ZutJoe]

我觉得我需要补补相关的插件知识。。。。。

我们目前的插件是较少的 基本没有，我觉得插件系统怎么做是不是很是要根据有什么插件需求来做？？或者我们得将运行时的节奏打的破碎，不知道我的理解对不对

我昨天在做一些测试的时候，我也在思考能不能写一段脚本，然后直接自动化的改变里面的参数

[ZutJoe]

但是如果用json设计的话，它的脚本语法结构如果是像下面那样，那么循环调用某一段的脚本会不会更方便一些，只需要通过索引调用

{
...
scripts: [
    {},
    {},
    ...
],
...
}

[Monomux]

原来如此，这样编写时的可读性的确更好一些。

[ZutJoe]

如果我们插件足够多的话，不同的脚本也许会使用不同的功能，那么我们也许就不需要在plugins文件夹下面添加setting.json文件了，直接在相应的json脚本内添加plugins的key-value，但是这样也可能会造成会多一些内容，实现可能没有那么方便？？也许相对于来说你的那个方法大概会好一点？

[Monomux]

然后就像你说的，如果我们插件足够多的话，不同的脚本也许会使用不同的功能，那么我们也许就不需要在plugins文件夹下面添加setting.json文件了，直接在相应的json脚本内添加plugins的key-value，但是这样也可能会造成会多一些内容，实现可能没有那么方便？？也许相对于来说你的那个方法大概会好一点？

脚本加载这块可以参考现在的实现，优先级：脚本内指定>程序配置指定>不加载。这样具体指定了插件的脚本就加载具体插件，对于一些通用型的插件，在每个脚本内都指定有些麻烦，就可以放在配置文件中。

[ZutJoe]

脚本加载这块可以参考现在的实现，优先级：脚本内指定>程序配置指定>不加载。这样具体指定了插件的脚本就加载具体插件，对于一些通用型的插件，在每个脚本内都指定有些麻烦，就可以放在配置文件中。

可行

[Monomux]

但是如果用json设计的话，它的脚本语法结构如果是像下面那样，那么循环调用某一段的脚本会不会更方便一些，只需要通过索引调用

我根据这种结构设想一下新脚本的语法：
基本框架是

{
    "plugins": [
        {"type": ___ , "path": ___ },
        ...
    ], // 脚本指定的插件，可不填
    "scripts": [
        {
            "delay": ___ ,
            "event_type": ___,
            "action": ___,
            "message": ____
        }, // 默认语句
        {
            "delay": ___ ,
            "event_type": ___,
            "action": ___,
            "message": ____,
            "label": ___ // *可选，给当前事件加标记，以便插件定位事件位置
        }，
        {
            "delay": “$random_delay”, // *可选，在插件中定义了一些变量可以在这使用
            "event_type": ___,
            "action": ___,
            "message": ____
        },
        ...
    ]
}

每一个插件的目录结构为:

/plugins/Myplugin/
    - manifest.json
    - random_variable.py
    - ...

每一个插件需要有manifest.json指定其内容，而py文件则是各种具体接口的实现:

//manifest.json
{
    // 基本信息
    "name": ____,    
    "type": ____,
    ...
    // Optional settings
    "resource_path": ____,
    // 自定义的变量
    {
        "type": "variable",
        "name": "random_variable",
        "implement": "random_variable.py" // 获取变量的实现
    },
    // 流程控制
    {
        "type": "jump",           // 跳转
        "to": "label", // 事件的label
        "invoke": ____ // 触发条件
    },
    {
        "type": "loop",           // 循环
        "times": 1,
        "from": "label",
        "to": "label", // 事件的label
        "invoke": ____ // 触发条件
    },
    {
        "type": "subscript",   // 子脚本
        "path": ____,
        "invoke": ____ // 触发条件
    },
    // 自定义方法
    {
        "type": "custom",
        "implement": "xxx.py",
        "invoke": ____ // 触发条件
    }
}

[ZutJoe]

{
    "plugins": [
        {"type": ___ , "path": ___ },
        ...
    ], // 脚本指定的插件，可不填
    "scripts": [
        {
            "delay": ___ ,
            "event_type": ___,
            "action": ___,
            "message": ____,
            "label": ___ // 给当前事件加标记，以便插件定位事件位置
        }，
        ...
    ]
}

这个label放在全局（放在和scripts同一级下）会不会好一点，直接记录位置，查询就是O(1)的

[ZutJoe]

//manifest.json
{
    // 基本信息
    "name": ____,    
    "type": ____,
    ...
    "resource_path": ____,
    // 自定义的变量
    {
        "type": "variable",
        "name": "random_variable",
        "implement": "random_variable.py" // 获取变量的实现
    },
    // 流程控制
    {
        "type": "jump",           // 跳转
        "to": "label", // 事件的label
        "invoke": ____ // 触发条件
    },
    {
        "type": "loop",           // 循环
        "times": 1,
        "from": "label",
        "to": "label", // 事件的label
        "invoke": ____ // 触发条件
    },
    {
        "type": "subscript",   // 子脚本
        "path": ____,
        "invoke": ____ // 触发条件
    },
    // 自定义方法
    {
        "type": "custom",
        "implement": "xxx.py",
        "invoke": ____ // 触发条件
    }
}

没太懂，插件的实现不是通过钩子函数吗，为啥在manifest.json文件里要配置这么多东西

[Monomux]

这个label放在全局（放在和scripts同一级下）会不会好一点，直接记录位置，查询就是O(1)的

{
    "scripts": [
        {
            "delay": ___ ,
            "event_type": ___,
            "action": ___,
            "message": ____
        }，
        ...
    ],
    "labels": [
        {"label": ___, "index": 0},
        {"label": ___, "index": 2},
        ....
    ]
}

这样吗？我设想的是读取后用一个字典存储label对应索引。

[Monomux]

没太懂，插件的实现不是通过钩子函数吗，为啥在manifest.json文件里要配置这么多东西

我设想的是管理器根据触发条件将相应操作注册到相应的hook上，这部分的功能也可以放在py中实现。

[ZutJoe]

这样吗？我设想的是读取后用一个字典存储label对应索引。

好像也行，这样能做的操作好像会更多一点

我设想的是管理器根据触发条件将相应操作注册到相应的hook上，这部分的功能也可以放在py中实现。

哦哦，好的，可以

[Monomux]

我正在尝试实现上面的想法，以下是对一些问题的想法：

Label的定义位置

脚本的语法修改后，录制的脚本会变成下面的形式

{
   "scripts": [
       {
           "delay": ___ ,
           "event_type": ___,
           "action": ___,
           "message": ____
       }，
       ...
   ]
}

或者

{
   "scripts": [
       {"delay": ___ , "event_type": ___, "action": ___, "message": ____}，
       ...
   ]
}

如果label在script同级定义，需要指定每个索引处对应的label。如果脚本较长，又采用第一种形式保存，要数索引是很不方便的，用第二种形式的话结合带行数的文本编辑器做减法还是可以算出索引的。如果label直接指定在对应索引事件的定义处，则不需要人工数索引，相对方便一些，但仍需要指定索引。
至于程序执行时的查询，可以在解析脚本时用字典保存label-index对。

插件配置文件

我上面的回复设想在menifest.json中加入插件基本信息以及各种实现的声明，实际上没必要，插件实现了相应接口则调用生效，没实现则pass，因此只需要指定基本信息。

// manifest.json
{
   // 基本信息
   "name": ____,    
   "description": ____,
   "author": ____,
   "version": ____,
   // 如果要改动资源文件(如提示音，主题)
   "resource_path": {
        "theme": ____,
        "tone": ____
    }
}

钩子函数设计

从使用的角度想到了几个”挂载点“：

• 程序初始化
• 录制事件时，在每录制到一个事件后调用(可以保存当前鼠标位置窗口句柄之类的)
• 解析事件时，采用json.loads(content)之后调用
• 运行时(供流程跳转)

方案一

如果参考5.0版的设计，指定9个调用时机：

class HookType(Enum):
   INIT = 0  # 程序初始化时触发
   PARSING = 1  # 解析脚本时触发
   RECORD = 2  # 录制事件时触发
   EXE_INIT = 3  # 脚本解析后，脚本执行前触发
   EXE_LOOP = 4  # 每次执行前触发
   EXE_EVENT = 5  # 每次执行事件前触发
   EXE_EVENT_END = 6  # 每次执行事件后触发
   EXE_LOOP_END = 7  # 每次执行后触发
   EXE_END = 8  # 执行结束后触发

或者修改一下：

   EXE_EVENT = 5  # 每次执行到指定label的事件前触发
   EXE_EVENT_END = 6  # 每次执行到指定label的事件后触发

假如要实现动态改变参数(如运行时随机改变延时)，插件需要实现以下hook

def get_exe_event_hook(label: str, event: ScriptEvent):
    def random_delay(event):
        # ...
        event.delay = random_delay # mod event
        return event
    return random_delay

假如要实现跳转(如等待当前位置窗口出现)

def get_exe_event_hook(label: str):
    def check_handle(event):
        # check handle of window
        if window_is_open:
            return event
        else:
            # sleep
            raise JumpProcess(targetlabel)
    return check_handle

这样的话因为”挂载点“相同，可以兼容前一版的插件。

方案二

仅保留4个”挂载点“：

class HookType(Enum):
   INIT = 0  # 程序初始化时触发
   PARSING = 1  # 解析脚本时触发
   RECORD = 2  # 录制事件时触发
   EXE_INIT = 3  # 脚本解析后，脚本执行前触发

而程序的执行交由一个”流程执行器“执行，在未追加任何定义时，执行器顺序执行脚本，用户则可以在执行器中添加一些条件判断或循环。

def get_exe_init_hook():
    def check_handle(event):
        # check window handle at current position
        return True # or False
    def add_window_check(workflow):
        workflow.addCondition(
            atlabel=targetlabel,  #  在targetlabel处检查条件
            judge=check_handle  # 根据judge函数的结果(bool)判断结果
            isTrue=WorkFlow.DONOTHING,
            isFalse=WorkFlow.JUMP,
            args=jumptolabel
        )
    return add_window_check

用户可以在脚本中加入自定义参数或变量

// script.json
{
    "delay": “$random_delay”,  // *
    "event_type": ___,
    "action": ___,
    "message": ____,
    "window_handle": ____  // *
},

在解析时，变量需要转为增强基本类型以便在执行时能够被读取：

import random
class RandomDelay(int):
    def __new__(cls, a, b):
        return int.__new__(cls, random.randint(a, b))

这样子插件的编写也许对用户更友好？在脚本中，在运行时才知道具体值的参数可以设为变量，在py文件中给出读取方法，比方案一类似hack的方式更好一些？

[Monomux]

目前是决定使用方案二的想法。
程序执行的流程分为若干个功能节点构成的流程图，定义的基本节点为：

• Custom(Callable): 执行自定义功能
• Sequential(start_label, end_label, attach: Callable=None): 从start_label执行到end_label，如果attach的函数存在，则在执行每条事件前调用一次attach
• Condition(Callable): 根据调用函数的返回值决定下一节点
• SubRoutine(subscript): 中断当前执行转而执行子脚本内容

程序默认的流程仅包含一个节点Sequential("BUILTIN_START", "BUILTIN_END")，其中的两个label是内部约定的起始事件和结尾事件的label。

假如有一个脚本要通过插件实现等待窗口出现的功能，内容为：

{
    script: [
        {/* ... */, label: "exe1_start"},
        {/* ... */},
        {/* ... */, label: "exe1_end"},
        // 等待窗口出现后操作
        {/* ... */, label: "exe2_start"},
        {/* ... */},
        {/* ... */, label: "exe2_end"}
    ]
}

相应的流程图为：

在插件的钩子函数中，需要在脚本执行前重新设计流程:

# 定义节点
node1 = SequentialNode("exe1_start", "exe1_end")
node2 = ConditionNode(check_window_handle)
node3 = CustomNode(sleep)
node4 = SequentialNode("exe2_start", "exe2_end")
# 连接节点
node1.setnextnode(node2)
node2.setnextnode(iftrue=node4, iffalse=node3)
node3.setnextnode(node2)
# 修改流程
workflow.clear()
workflow.register(headnode=node1)

节点的连接可以简化(就像神经网络的神经层连接)

sequence = SequentialFlow(
    SequentialNode("exe1_start", "exe1_end"),
    ConditionNode(check_window_handle),
    {                                                               # Condition Node 后需跟上字典，值为达到相应条件后的后续节点
        False: (
            CustomNode(sleep),
            WorkFlow.SelfFlag                           # 定义一个Flag表示与这个字典相关联的ConditionNode
        )
        True: (
            SequentialNode("exe2_start", "exe2_end")
        )
    }
)
workflow.clear()
workflow.register(sequence=sequence)

---

自定义函数访问程序数据的方法

某些自定义函数需要依赖脚本中的参数，比如上面的检测窗口就需要鼠标的当前位置(当然pyautogui.position()就能解决)，这时函数访问参数的方法可以是：

• 通过参数传递，把当前事件传给函数
• 通过访问namespace获得，假如流程节点、解析的脚本字典以及其它运行时相关信息全部存在一个WorkFlow对象中，并且插件可以get到这个对象，那么自定义函数就可以通过这个对象取得需要的信息
• ...

自定义参数的解析

比如说随机等待时间，脚本中所有的delay参数都被修改为符合正则表达式[0-9]+-[0-9]+的形式的字符串，那么就可以在解析时将其转为一个随机的int数值。
当执行次数不止一次时，由于脚本仅解析一次，采用上面的方法会使每次执行时同行事件的等待时间是相同的，则需要在运行时修改。

node = SequentialNode("BUILTIN_START", "BUILTIN_END", attach=random_delay)

[ZutJoe]

我们在做这个的时候需不需要向下兼容

[Monomux]

脚本读取这块需要，插件的话不考虑？

[ZutJoe]

嗯，对

[Monomux]

还有一些小想法...就是目前的脚本和增强功能(流程修改、自定义功能等)是分离的，对于整体的执行内容需要结合脚本和插件的内容才能看出(有点后知后觉了，4个月前的issue就提到了这个问题，当时的思维有点局限)。
Copy一下以往issue的评论：

1. 首先，这样做是否会导致主程序的脚本和插件的脚本分离，形成两个文件？
   每次需要执行原定的操作时都必须手动匹配两个脚本来协同工作才能完成预期的目标？
2. 脚本编辑时的便捷性/可读性是否非常差？
   就目前主程序所使用的脚本来说，普通用户还是勉强能透过阅读说明文档来快速理解并进行所需的修改。但一旦引入了这个插件，看起来就对非代码技术人员绝缘了。主代码和变量直接混在一起完全是“不可操作”的。（虽然说我能通过注释大致明白要怎么改，但还是看着有点头大）
   而且就算是会编辑代码的专业人员，如果需要两个文件并排，并且要左顾右盼的在脑内模拟合并后的结果来对照修改，想必那体验是绝对的不好的。

根据这个思路看新的设计，还是存在以下问题：

1. 脚本与流程设计分离，需结合注释等辅助修改
2. 对于非程序设计人员来说插件编写困难

那么，是否可以：

1. 将执行内容与流程设计合并在一个文件内？
2. 是否可以用图形化编辑替代脚本编写？

---

改变脚本语法

当前的脚本语法无论修改前后都是用json(json5)格式存储的，不包含流程控制的信息，不过按照现在的脚本语法，嵌入流程控制看上去似乎可行，比如：

{
    script: [
        {/* ... */},
        {
            type: "if",
            call: "${function}"
            iftrue: [
                {/* ... */},
                {/* ... */}
            ],
            else: [
                {
                    type: "goto",
                    tolabel: "Window_check"
                }
            ],
            label: "Window_check"
        },
        {/* ... */}
    ]
}

或者，参考TagUI的设计，让脚本更加程序语言化一些。

引入图形化设计修改执行内容和流程

可以参考UIPath StudioX中的设计界面。这只是个想法，目前不打算这么弄。

[Monomux]

终于改完了这个插件系统，下面是所有改动的内容：

脚本语法

脚本统一采用json5格式保存，脚本格式为：

{
   scripts: [
       {
           // 如果仅靠无插件的录制得到，每一个object仅含以下5个参数，且type一定为"event"
           type: "event",
           delay: ___ ,
           event_type: ___,
           action: ___,
           message: ____,
           // (可选)执行前调用的函数，可以指定多个函数
           call: [/* ... */],
           // (可选)标签，供goto跳转使用，其它类型的object也可以有标签
           label: ___,
           // (可选)其它参数，key和value均任意，可供插件注册函数读取
           // ___: ___,
       }，
       {
           type: "sequence",  // 程序将顺序执行events内的事件
           events: [
               // 内容必须为type=='event'的object
           ],
           // (可选)执行前调用的函数，与call不同的是执行events内每一个object前都会调用attach内的函数
           // 对于一系列需要添加相同调用函数的object来说可以靠这个简化编写
           attach: [/* ... */]
       },
       {
           type: "if", // 程序先调用judge指定的函数，根据返回值决定后续执行内容，为True执行do内的事件，为False执行else内的事件
           judge: "function_name",
           do: [/* ... */],
           else: [/* ... */],
       },
       {
           type: "subroutine",
           path: ["path", /* ... */] // 执行其它脚本
       },
       {
           type: "goto",
           tolabel: "target_label" // 跳转到相应label的object
       }
       ...
   ]
}

插件编写

每个插件需要包含一个manifest.json5作为表示，目录结构为
/plugins/Myplugin/
- manifest.json5
- ___.py
- ...

manifest.json5内容：

// manifest.json5
{
   // 基本信息
   "name": "Example",
   "description": "This is an example plugin",
   "author": "",
   "version": "1.0",
   "enabled": true, // 是否启用插件，如为False，程序不会加载该插件
   // (可选) 注册新的函数
   "entry": "Example.py", // 实现插件接口的文件
   "plugin_class": "MyExample", // 实现插件接口的类名
   // (可选) 添加新的资源文件路径
   "resource_path": {
        "theme": ["mytheme.xml"]
    }
}

插件接口的定义:

class PluginInterface:
    def __init__(self, manifest: Dict):
        self.meta = PluginMeta(manifest)

    # 注册运行时可调用的函数
    @abstractmethod
    def register_functions(self) -> Dict[str, Callable]:
        pass
    # 注册录制时可调用的函数
    @abstractmethod
    def register_record_functions(self) -> List[Callable]:
        pass

register_functions需要返回一个字典，key相当于函数的label，脚本中call和attach中输入的便是函数对应的key值，相应的value为函数本身。所有注册的函数都会收到一个类型为JsonObject的参数，通过访问该对象的content属性可以得到当前执行对象的属性。

register_record_functions需要返回一个列表，内容为函数，所有在此注册的函数会在录制到一个事件时依次调用。

这么说不够直接，这是测试时写的样例：
脚本：

{
    scripts: [
        {
            type: "sequence",
            events: [
                {
                    type: "event",
                    delay: "2-8",
                    event_type: "EM",
                    message: "mouse move",
                    action: ["0.39427083333333335%","0.45740740740740743%"]
                },
                {
                    type: "event",
                    delay: "1-514",
                    event_type: "EM",
                    message: "mouse move",
                    action: ["0.49270833333333336%","0.4398148148148148%"]
                }
            ],
            attach: ["rd"]
        },
    ]
}

manifest.json5

{
   // 基本信息
   "name": "Random Delay",
   "description": "使延时的格式变为[0-9]+-[0-9]+，即X-Y，其中X为最小延时，Y为最大延时，X,Y均为整数，单位毫秒",
   "author": "Monomux",
   "version": "1.0",
   "entry": "Random_Delay.py",
   "plugin_class": "RandomDelay",
   "enabled": true
}

Random_Delay.py

from typing import Dict, Callable, List
from Util.Parser import JsonObject
from Plugin.Interface import PluginInterface
from loguru import logger
import re
import random


class RandomDelay(PluginInterface):
    def __init__(self, manifest: Dict):
        super().__init__(manifest)

    def register_functions(self) -> Dict[str, Callable]:
        funcs: Dict[str, Callable] = {}

        def random_delay(json_object: JsonObject):
            delay: str = json_object.content['delay']
            # 避免重复修改
            if type(delay) == str:
                delays = re.match('([0-9]+)\-([0-9]+)', delay).groups()
                json_object.content['delay'] = random.randint(int(delays[0]), int(delays[1]))

        funcs['rd'] = random_delay
        return funcs

    def register_record_functions(self) -> List[Callable]:
        return []