feat: 初始化 Halo 暗色模式插件

- Halo Plugin 后端（Java/Gradle），含 DarkModePlugin 主类和测试 - Vue 3 + TypeScript 前端 UI，包含主题切换组件和设置页面 - 暗色模式 CSS 变量和覆盖样式（布局/编辑器/表单/滚动条等） - 设计文档和调查文档 - Halo 插件/主题开发 Agent Skills Co-Authored-By: Claude <noreply@anthropic.com>
2026-08-06 21:03:00 +08:00
commit edbf78f236
115 changed files with 14745 additions and 0 deletions
@@ -0,0 +1,102 @@
+# Plugin Manifest (plugin.yaml)
+
+Located at `src/main/resources/plugin.yaml`. Required.
+
+> - [create-halo-plugin repo](https://github.com/halo-dev/create-halo-plugin)
+
+## Minimal Example
+
+```yaml
+apiVersion: plugin.halo.run/v1alpha1
+kind: Plugin
+metadata:
+  name: hello-world
+spec:
+  enabled: true
+  requires: ">=2.22.0"
+  author:
+    name: Halo
+    website: https://www.halo.run
+  logo: logo.svg
+  displayName: "Hello World"
+  description: "A minimal Halo plugin"
+  license:
+    - name: "GPL-3.0"
+      url: "https://github.com/example/plugin/blob/main/LICENSE"
+```
+
+## Field Reference
+
+| Field                                 | Description                                                                                               | Required    |
+| ------------------------------------- | --------------------------------------------------------------------------------------------------------- | ----------- |
+| `apiVersion` / `kind`                 | Fixed: `plugin.halo.run/v1alpha1` / `Plugin`                                                              | Yes         |
+| `metadata.name`                       | Unique plugin ID. Max 253 chars, lowercase letters/numbers/hyphens only, must start/end with alphanumeric | Yes         |
+| `spec.enabled`                        | Auto-enable on install. For production, prefer `false` for security                                       | Yes         |
+| `spec.requires`                       | Supported Halo version range. SemVer ranges: `>=2.22.0`, `^2.22.0`, `2.22.*`, etc.                        | Yes         |
+| `spec.version`                        | Plugin version (e.g., `1.0.0`)                                                                            | Recommended |
+| `spec.author.name` / `author.website` | Author info                                                                                               | Recommended |
+| `spec.logo`                           | Logo file (relative to `src/main/resources/`) or URL                                                      | Recommended |
+| `spec.displayName`                    | Human-readable name                                                                                       | Yes         |
+| `spec.description`                    | Short description                                                                                         | Yes         |
+| `spec.homepage`                       | Plugin homepage/docs URL                                                                                  | Recommended |
+| `spec.repo`                           | Source repository URL                                                                                     | Recommended |
+| `spec.issues`                         | Issue tracker URL                                                                                         | Recommended |
+| `spec.license`                        | License name + URL array                                                                                  | Recommended |
+| `spec.settingName`                    | Setting resource name for plugin config form. Suffix with `-settings`                                     | Optional    |
+| `spec.configMapName`                  | ConfigMap name for persisting config. Suffix with `-configmap`. Required if `settingName` is set          | Conditional |
+| `spec.pluginDependencies`             | Map of `pluginName: versionRange`. Optional deps suffix name with `?` (Halo 2.20.11+)                     | Optional    |
+
+## Plugin Dependencies
+
+For dependency design, optional dependencies, and API modules, see
+[plugin-interaction.md](plugin-interaction.md).
+
+```yaml
+spec:
+  pluginDependencies:
+    # Required dependency
+    some-plugin: ">=1.0.0 & <2.0.0"
+    # Optional dependency (Halo 2.20.11+)
+    optional-plugin?: "1.*"
+```
+
+## Settings & ConfigMap
+
+To provide a user-configurable form in Console:
+
+1. Set `spec.settingName: my-plugin-settings` and `spec.configMapName: my-plugin-configmap` in `plugin.yaml`
+2. Create `src/main/resources/extensions/settings.yaml`:
+
+```yaml
+apiVersion: v1alpha1
+kind: Setting
+metadata:
+  name: my-plugin-settings # must match spec.settingName
+spec:
+  forms:
+    - group: basic
+      label: Basic Settings
+      formSchema:
+        - $formkit: text
+          name: apiKey
+          label: API Key
+        - $formkit: switch
+          name: enabled
+          label: Enable Feature
+```
+
+> If `settingName` is set but the corresponding `Setting` resource does not exist, the plugin will fail to start.
+>
+> For full form input options and Vue component usage, see [ui-forms.md](ui-forms.md).
+>
+> After setting this up, read the config at runtime using [`ReactiveSettingFetcher` or `SettingFetcher`](server-shared-beans.md#reactivesettingfetcher--settingfetcher).
+
+## App Store Annotations
+
+For distribution via Halo App Store:
+
+```yaml
+metadata:
+  annotations:
+    store.halo.run/app-id: "app-XXXXX"
+```