docs: 06-mixin-script

Author: Ayideyia

.vitepress/config.mts

@@ -23,6 +23,7 @@ export default defineConfig({
           { text: "运行原理", link: "/guide/03-how-it-works.md" },
           { text: "插件系统", link: "/guide/04-plugins.md" },
           { text: "计划任务系统", link: "/guide/05-tasks.md" },
+          { text: "混入与脚本", link: "/guide/06-mixin-script.md" },
           { text: "使用技巧", link: "/guide/08-skills.md" },
         ],
       },

guide/04-plugins.md

@@ -6,7 +6,7 @@
 
 ## 插件系统能够做什么？
 
-- 修改你的 APP 主题、语言，管理你的配置、订阅、规则组、内核。
+- 修改你的 APP 主题、语言，管理你的配置、订阅、规则集、内核。
 
 - 对生成的配置进行修改、对订阅的结果进行修改。
 
@@ -44,7 +44,7 @@
 - 1 运行中，推荐 onRun 方法中作为返回值
 - 2 已停止，推荐自定义菜单 Stop 方法中作为返回值
 
-以下是一个示例
+以下是一个示例，包含了所有的钩子方法。
 
 ```javascript
 /**
@@ -63,6 +63,14 @@ const Stop = async () => {
   return 2; // 表示已经停止运行
 };
 
+/**
+ * 自定义菜单项：运行 - Start
+ */
+const Start = async () => {
+  await StartMyProgram();
+  return 1; // 表示插件正在运行中
+};
+
 /**
  * 插件钩子：安装按钮 - onInstall
  */
@@ -78,6 +86,45 @@ const onUninstall = async () => {
   await UninstallMyProgram();
   return 0; // 表示初始状态
 };
+
+/**
+ * 插件钩子：更新订阅时
+ */
+const onSubscribe = async (proxies, subscription) => {
+  return proxies;
+};
+
+/**
+ * 插件钩子：生成配置时
+ */
+const onGenerate = async (config, profile) => {
+  return config;
+};
+
+/**
+ * 插件钩子：启动APP时
+ */
+const onStartup = async () => {};
+
+/**
+ * 插件钩子：关闭APP时
+ */
+const onShutdown = async () => {};
+
+/**
+ * 插件钩子：APP就绪后
+ */
+const onReady = async () => {};
+
+/**
+ * 插件钩子：计划任务执行时
+ */
+const onTask = async () => {};
+
+/**
+ * 插件钩子：配置插件时
+ */
+const onConfigure = async (config, old) => {};
 ```
 
 ## 插件编写规范
@@ -240,7 +287,7 @@ scheduledTasksStore.addScheduledTask(s: ScheduledTaskType)
 
 ![](/guide/resources/105_plugin_hub.png)
 
-从插件中心添加的插件不建议修改元数据，也就是插件卡片右上角的【编辑】按钮，因为发布到插件中心的插件都是调试好的，该有哪些触发器就有哪些触发器，该有哪些菜单以及配置项也都是设计好的，有些会用户随意编辑这些插件，比如添加了源码里没有实现的触发器，就会导致插件执行失败。
+从插件中心添加的插件不建议修改元数据，也就是插件卡片右上角的【~~编辑~~】按钮(已改为`【开发】`)，因为发布到插件中心的插件都是调试好的，该有哪些触发器就有哪些触发器，该有哪些菜单以及配置项也都是设计好的，有些会用户随意编辑这些插件，比如添加了源码里没有实现的触发器，就会导致插件执行失败。
 
 那么为什么不限制编辑按钮呢？因为我们想把最大的权限交给用户，毕竟有些有想法的用户想对已有插件进行扩展，增加自己想要的功能，GUI 不会限制这部分用户。
 

guide/06-mixin-script.md

@@ -0,0 +1,112 @@
+# 混入与脚本
+
+在引入`混入`与`脚本`之前，类似的操作可以通过插件完成，实现方式是创建一个具有`生成配置时`的触发器，对生成的配置进行个性化修改，但这样做有一些不便：
+
+- 1、作用于所有配置，如果仅修改部分配置则需要使用`if`来判断；
+
+- 2、必须编写`JavaScript`代码来处理，对没有编程经验的人不友好；
+
+`混入`与`脚本`解决了以上两个问题，它们和配置强绑定，仅作用于自身，既不会影响全部配置、也不需要编写`if`与`JavaScript`代码。
+
+## 混入 - Mixin
+
+混入的原理是使用`用户提供的配置`与`GUI生成的配置`进行合并处理，如果两个配置存在冲突，则可以使用`优先级`来指定最终的配置以哪一个为准。
+
+![](/guide/resources/601_mixin.png)
+
+示例：
+
+1、GUI.for.Clash 示例，YAML 格式
+
+```yaml
+mode: global
+ipv6: true
+mixed-port: 7890
+tun:
+  enable: true
+  stack: gVisor
+  dns-hijack:
+    - any:53
+dns:
+  enable: true
+  ipv6: true
+  default-nameserver:
+    - 223.5.5.5
+    - 114.114.114.114
+```
+
+2、GUI.for.SingBox 示例，JSON 格式
+
+```json
+{
+  "log": {
+    "timestamp": false
+  },
+  "experimental": {
+    "clash_api": {
+      "external_controller": "127.0.0.1:20123",
+      "default_mode": "global"
+    },
+    "cache_file": {
+      "enabled": true,
+      "store_fakeip": true
+    }
+  }
+}
+```
+
+注意事项：混入操作不支持`数组合并`，只会取`用户提供的配置`与`GUI生成的配置`其一。如果想对数组进行操作，只能使用`脚本`。
+
+## 脚本 - `Script`
+
+脚本的实现原理和插件的`onGenerate`钩子相同，GUI 会把`GUI生成的配置`通过参数`config`传入`onGenerate`方法，用户对`config`进行修改，然后返回最终的配置。
+
+![](/guide/resources/602_script.png)
+
+示例：
+
+1、GUI.for.Clash 示例
+
+```javascript
+const onGenerate = async (config) => {
+  config.dns["default-nameserver"].unshift("223.5.5.5");
+  config.dns["default-nameserver"].unshift("114.114.114.114");
+  config.sniffer = {
+    enable: false,
+    "force-dns-mapping": true,
+    "parse-pure-ip": true,
+    "override-destination": false,
+    sniff: {
+      HTTP: {
+        ports: [80, "8080-8880"],
+        "override-destination": true,
+      },
+      TLS: {
+        ports: [443, 8443],
+      },
+      QUIC: {
+        ports: [443, 8443],
+      },
+    },
+    "force-domain": ["+.v2ex.com"],
+    "skip-domain": ["Mijia Cloud"],
+  };
+  return config;
+};
+```
+
+2、GUI.for.SingBox 示例
+
+```javascript
+const onGenerate = async (config) => {
+  config.log.timestamp = false;
+  config.experimental.clash_api.default_mode = "global";
+  config.dns.servers.unshift({
+    tag: "remote-dns-google",
+    address: "tls://8.8.4.4",
+    address_resolver: "remote-resolver-dns",
+    detour: "🚀 Select",
+  });
+  return config;
+};
+```