Merge pull request #148 from SeasonsChange422/main

vuepress文档

Author: SeasonsChange422

.github/workflows/deploy.yml

@@ -0,0 +1,33 @@
+name: Build and Deploy
+
+on:
+  push:
+    branches: [ main ]
+    paths:
+      - 'docs/**'
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install and Build
+        run: |
+          cd docs
+          npm install
+          npm run docs:build
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/.vuepress/dist
+          publish_branch: gh-pages

docs/.gitignore

@@ -0,0 +1,39 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+src/*.d.ts
+dist-ssr
+*.local
+
+# VuePress/Vite generated
+.vuepress/.cache
+.vuepress/.temp
+.vuepress/dist
+.vite
+.eslintcache
+
+# OS files
+Thumbs.db
+
+# Env files
+.env
+.env.*
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

docs/.vuepress/config.ts

@@ -0,0 +1,91 @@
+import { defineUserConfig } from 'vuepress'
+import { defaultTheme } from '@vuepress/theme-default'
+import { viteBundler } from '@vuepress/bundler-vite'
+import { path } from '@vuepress/utils'
+
+export default defineUserConfig({
+  lang: 'zh-CN',
+  title: 'Mosaic Framework',
+  description: '基于插件化架构的Java模块化框架',
+  base: '/Mosaic/',
+  public: path.resolve(__dirname, '../public'),
+  bundler: viteBundler({
+    viteOptions: {},
+    vuePluginOptions: {},
+  }),
+  
+  theme: defaultTheme({
+    logo: '/logo.png',
+    navbar: [
+      {
+        text: '指南',
+        link: '/guide/',
+      },
+      {
+        text: 'API参考',
+        link: '/api/',
+      },
+      {
+        text: '插件开发',
+        link: '/plugin/',
+      },
+      {
+        text: '示例',
+        link: '/examples/',
+      },
+      {
+        text: 'GitHub',
+        link: 'https://github.com/Time-Machine-Lab/Mosaic'
+      }
+    ],
+    sidebar: {
+      '/guide/': [
+        {
+          text: '指南',
+          children: [
+            '/guide/README.md',
+            '/guide/getting-started.md',
+            '/guide/core-concepts.md',
+            '/guide/configuration.md',
+            '/guide/event-system.md'
+          ]
+        }
+      ],
+      '/api/': [
+        {
+          text: 'API参考',
+          children: [
+            '/api/README.md',
+            '/api/cube-api.md',
+            '/api/extension-api.md',
+            '/api/event-api.md',
+            '/api/config-api.md'
+          ]
+        }
+      ],
+      '/plugin/': [
+        {
+          text: '插件开发',
+          children: [
+            '/plugin/README.md',
+            '/plugin/cube-development.md',
+            '/plugin/extension-development.md',
+            '/plugin/listener-development.md',
+            '/plugin/best-practices.md'
+          ]
+        }
+      ],
+      '/examples/': [
+        {
+          text: '示例',
+          children: [
+            '/examples/README.md',
+            '/examples/ai-chat-plugin.md',
+            '/examples/system-log-plugin.md',
+            '/examples/listener-plugin.md'
+          ]
+        }
+      ]
+    }
+  })
+})

docs/README.md

@@ -0,0 +1,60 @@
+---
+home: true
+heroImage: /logo.png
+heroText: Mosaic Framework
+tagline: 基于插件化架构的Java模块化框架
+actionText: 快速开始 →
+actionLink: /guide/getting-started
+features:
+- title: 🧩 插件化架构
+  details: 基于Cube概念的模块化设计，支持插件的动态加载和管理
+- title: 🔌 扩展点机制
+  details: 通过注解驱动的扩展点系统，实现插件间的松耦合交互
+- title: 📡 事件驱动
+  details: 完整的事件系统支持插件间的异步通信
+- title: ⚙️ 配置管理
+  details: 灵活的配置系统，支持类型验证和默认值
+- title: 🔄 生命周期管理
+  details: 完整的插件生命周期管理（初始化、启动、停止、销毁）
+- title: 🏗️ 多实例支持
+  details: 支持单例和多例插件模式
+footer: MIT Licensed | Copyright © 2024 Mosaic Framework
+---
+
+## 什么是 Mosaic Framework？
+
+Mosaic Framework 是一个基于插件化架构的Java模块化框架，旨在帮助开发者构建可扩展、可维护的模块化应用系统。
+
+### 核心特性
+
+- **插件化架构**: 基于Cube概念的模块化设计
+- **扩展点机制**: 注解驱动的扩展点系统
+- **事件驱动**: 完整的事件系统
+- **配置管理**: 灵活的配置系统
+- **生命周期管理**: 完整的插件生命周期
+
+### 快速体验
+
+```xml
+<dependency>
+    <groupId>io.github.timemachinelab</groupId>
+    <artifactId>mosaic-core</artifactId>
+    <version>1.0-SNAPSHOT</version>
+</dependency>
+```
+
+```java
+@MCube(name = "示例插件", description = "这是一个示例插件")
+public class ExampleCube extends MosaicCube {
+    @Override
+    public boolean init() {
+        System.out.println("插件初始化成功！");
+        return true;
+    }
+    
+    @Override
+    public String cubeId() {
+        return "example.cube";
+    }
+}
+```

docs/api/README.md

@@ -0,0 +1,7 @@
+# API 概览
+
+本节列出宿主与插件常用 API：
+- Cube API：生命周期、配置访问、标识
+- 扩展 API：扩展点注解、扩展包抽象与注入
+- 事件 API：事件与监听器编写
+- 配置 API：CubeConfig 读取

docs/api/config-api.md

@@ -0,0 +1,22 @@
+# 配置 API
+
+## CubeConfig
+```java
+public class CubeConfig {
+    <T> T getConfig(String name, Class<T> type);
+    <T> T getConfig(String name, Class<T> type, T defaultValue);
+    Map<String, Object> getAllConfigs();
+}
+```
+
+## 读取示例
+```java
+CubeConfig cfg = getCubeConfig();
+String model = cfg.getConfig("model", String.class, "gpt-3.5-turbo");
+Integer timeout = cfg.getConfig("timeout", Integer.class, 30);
+Boolean enableLogging = cfg.getConfig("enableLogging", Boolean.class, true);
+```
+
+说明：
+- CubeConfig 由框架在实例化时注入（线程上下文绑定 cubeId -> 配置）。
+- 不建议在插件中长期持有可变引用，按需读取或复制。

docs/api/cube-api.md

@@ -0,0 +1,32 @@
+# Cube API
+
+## 接口
+```java
+public interface CubeApi {
+    boolean init();
+    boolean destroy();
+    String cubeId();
+    default CubeConfig getCubeConfig() { ... }
+}
+```
+
+## 基类
+- MosaicCube：插件实现通常继承此类，覆盖 init/destroy/cubeId。
+- AngelCube：守护型方块，需实现 start()/stop()，由 AngelCubeActuator 管理其生命周期。
+
+## 注解
+```java
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface MCube {
+    String name() default "";
+    String version() default "1.0.0";
+    String description() default "";
+    String scope() default "singleton";
+}
+```
+
+## 运行特性
+- scope=singleton/property 控制实例复用与重建；
+- 获取配置：getCubeConfig()；
+- AngelCube 的 execute 只负责启动守护任务，停止请使用 ActuatorProxy.stop(slotId)。

docs/api/event-api.md

@@ -0,0 +1,13 @@
+# 事件 API
+
+## 监听器编写
+- 继承 SelectiveMosaicEventListener，覆盖 getListenedEventTypes() 指定关心事件；
+- 在 onSelectiveEvent 中用 when(...).orWhen(...).orDefault() 分派处理；
+- 通过 getListenerName() 返回监听器名称。
+
+常见事件（示例）：
+- CubeConfigUpdateEvent：Cube 配置变更
+- CubeDefinitionRegisteredEvent：Cube 定义注册完成
+
+提示：
+- AngelCube 的监听器会在 init 成功后自动注册到广播器。

docs/api/extension-api.md

@@ -0,0 +1,29 @@
+# 扩展 API
+
+## 扩展点注解
+```java
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface MExtension {
+    String extPointId();
+    String name() default "";
+    String description() default "";
+    int priority() default 100;
+}
+```
+
+## 扩展包抽象
+```java
+public abstract class MosaicExtPackage<T extends MosaicCube> implements ExtensionPackageApi {
+    protected T mosaicCube;
+    @Override
+    public void initCube(MosaicCube mosaicCube) {
+        this.mosaicCube = (T) mosaicCube;
+    }
+}
+```
+
+## 返回值约定
+- 返回 MosaicResult：框架原样使用（并以 default 名再存一份），调用方可按 resName + itemName 拿到命名结果；
+- 返回普通类型：框架封装为 MosaicResult 并以 default 命名；
+- 返回 void/MosaicVoid：表示无返回。

docs/examples/README.md

@@ -0,0 +1,6 @@
+# 示例
+
+本节包含三个示例：
+- AI 聊天插件：HTTP 调用大模型接口，演示配置读取与重试
+- 系统日志插件：演示多实例配置读取
+- 监听器插件：演示选择性事件监听与处理