docs: 添加 插件基本接入方法.md

Author: lrsgzs

docs/插件基本接入方法.md

@@ -0,0 +1,159 @@
+# 插件基本接入方法
+- version: 0.1
+
+## 接入基本方法
+
+1. 在 Plugin.cs 添加函数：
+
+    ```csharp
+    using ClassIsland.Core.Abstractions.Services;
+    
+    public static bool IsPluginInstalled(string pkgName) {
+        return IPluginService.LoadedPlugins.Any(info => info.Manifest.Id == pkgName);
+    }
+    ```
+
+2. Initialize 添加如下内容：
+
+    ```csharp
+    if (IsPluginInstalled("lrs2187.sai")) {
+        AppBase.Current.AppStarted += (_, _) => {
+            var saiServerService = IAppHost.GetService<ISaiServer>();
+            
+            // 注册 sai 元素
+            saiServerService.RegisterBlocks("SuperAutoIsland", new RegisterData
+            {
+                Actions = [/* ... */],
+                Rules = [/* ... */]
+            });
+        };
+    }
+    ```
+
+3. 大功告成
+
+## 积木示例
+
+### 行动
+
+```csharp
+var exampleActionBlock = new BlockMetadata
+{
+    Id = "sai.actions.example",
+    Name = "示例积木",
+    Icon = ("方块", "\uE326"),
+    Args = new Dictionary<string, MetaArgsBase>
+    {
+        ["_string1"] = new CommonMetaArgs
+        {
+            Name = "示例字符串区域",
+            Type = MetaType.dummy
+        },
+        ["ExampleString"] = new CommonMetaArgs
+        {
+            Name = "示例字符串字段",
+            Type = MetaType.text
+        },
+        ["ExampleNumber"] = new CommonMetaArgs
+        {
+            Name = "示例数字字段",
+            Type = MetaType.number
+        },
+        ["ExampleBoolean"] = new CommonMetaArgs
+        {
+            Name = "示例布尔值字段",
+            Type = MetaType.boolean
+        },
+        ["ExampleCheckbox"] = new CheckboxMetaArgs
+        {
+            Name = "示例复选框字段",
+            Type = MetaType.checkbox,
+            DefaultValue = true
+        },
+        ["ExampleDropdown"] = new DropDownMetaArgs
+        {
+            Name = "示例下拉框字段",
+            Type = MetaType.dropdown,
+            Options = [
+                ("字符串1", "值 val1"),
+                ("字符串2", "val2"),
+            ]
+        }
+    },
+    DropdownUseNumbers = false,  // 下拉框传入参数是否为数字(其实是直接拼接到js...)
+    InlineField = false,  // 内行字段
+    InlineBlock = false,  // 内行积木
+    IsRule = false
+};
+```
+
+### 规则集
+
+仅需把 IsRule 改为 true 即可，其他与行动一致。
+
+## 包装器注册
+
+> 用于不同形状的积木转换为同一 ci 行动，或者改 Settings 之类的
+
+位于 `ISaiServe.RegisterWrapper`，下方为定义：
+
+```csharp
+using ClassIsland.Core.Models.Ruleset;
+using ClassIsland.Shared.Models.Automation;
+
+/// <summary>
+/// 行动 wrapper
+/// </summary>
+public delegate ActionItem ActionWrapper(ActionItem action);
+
+/// <summary>
+/// 规则 wrapper
+/// </summary>
+public delegate Rule RuleWrapper(Rule rule);
+
+/// <summary>
+/// 注册行动 wrapper
+/// </summary>
+/// <param name="id">行动 id</param>
+/// <param name="wrapper">wrapper 函数</param>
+public void RegisterWrapper(string id, ActionWrapper wrapper);
+
+/// <summary>
+/// 注册规则 wrapper
+/// </summary>
+/// <param name="id">规则 id</param>
+/// <param name="wrapper">wrapper 函数</param>
+public void RegisterWrapper(string id, RuleWrapper wrapper);
+```
+
+下方为示例
+
+```csharp
+/// <summary>
+/// "运行"行动设置。
+/// </summary>
+public partial class RunActionSettings : ObservableRecipient { /* ... */ }
+
+/// <summary>
+/// 运行应用程序包装器
+/// </summary>
+/// <param name="actionItem">行动项目</param>
+/// <returns>修改后的行动项目</returns>
+public static ActionItem RunActionProgramWrapper(ActionItem actionItem)
+{
+    var settingsJson = JsonSerializer.Serialize(actionItem.Settings);
+    var settings = JsonSerializer.Deserialize<RunActionSettings>(settingsJson)!;
+    settings.RunType = RunActionSettings.RunActionRunType.Application;
+    settingsJson = JsonSerializer.Serialize(settings);
+    
+    return new ActionItem
+    {
+        Id = "classisland.os.run",
+        Settings = JsonSerializer.Deserialize<object>(settingsJson)
+    };
+}
+
+saiServerService.RegisterWrapper("classisland.os.run.program", RunActionProgramWrapper);
+```
+
+###### ~~垃圾文档集团 出品~~