@agentunion/kite 1.5.0 → 1.6.0

package/docs/Kite/346/216/247/345/210/266/345/217/260/346/217/222/344/273/266/345/214/226/346/236/266/346/236/204/350/256/276/350/256/241-/347/273/210/346/236/201/347/233/256/346/240/207.md

@@ -0,0 +1,721 @@
+# Kite 控制台插件化架构设计 - 终极目标
+
+## 概述
+
+Kite 控制台是一个业务无关的、可扩展的 Web 管理界面，通过插件化架构支持多种业务系统的接入。核心控制台提供 Kite 框架的基础管理功能，业务插件可以动态扩展菜单、路由、认证方式和功能模块。
+
+## 设计目标
+
+### 核心原则
+
+1. **业务无关** - 核心控制台不包含任何业务逻辑，只提供框架管理功能
+2. **插件化** - 业务功能通过插件接入，插件可独立开发、部署、启用/禁用
+3. **认证灵活** - 支持多种认证方式并存（配对码、手机号、OAuth 等）
+4. **动态扩展** - 插件启用时菜单项出现，禁用时菜单项消失
+5. **统一通信** - 所有通信通过 WebSocket JSON-RPC 2.0 协议
+6. **虚拟模块** - 浏览器客户端作为标准 Kite 模块接入 Kernel
+
+## 整体架构
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                      浏览器客户端                                │
+│                                                                  │
+│  ┌────────────────────────────────────────────────────────────┐ │
+│  │ Kite Console UI (核心界面)                                 │ │
+│  │  - 顶部导航栏（控制台名称、连接状态、用户信息）            │ │
+│  │  - 左侧菜单（核心菜单 + 插件菜单）                         │ │
+│  │  - 主内容区（路由视图）                                    │ │
+│  └────────────────────────────────────────────────────────────┘ │
+│                                                                  │
+│  ┌────────────────────────────────────────────────────────────┐ │
+│  │ KernelClient (统一 WebSocket 客户端)                       │ │
+│  │  - 连接管理（认证、重连、心跳）                            │ │
+│  │  - RPC 调用                                                 │ │
+│  │  - 事件订阅                                                 │ │
+│  └────────────────────────────────────────────────────────────┘ │
+└──────────────────────────┬──────────────────────────────────────┘
+                           │ WebSocket: /ws/relay
+                           ↓
+┌─────────────────────────────────────────────────────────────────┐
+│              Kite Console 模块 (服务端)                         │
+│                                                                  │
+│  ┌────────────────────────────────────────────────────────────┐ │
+│  │ Relay Service (虚拟模块中转服务)                           │ │
+│  │  - 多认证支持（配对码、插件认证）                          │ │
+│  │  - 消息转发到 Kernel                                       │ │
+│  │  - 会话管理                                                 │ │
+│  └────────────────────────────────────────────────────────────┘ │
+│                                                                  │
+│  ┌────────────────────────────────────────────────────────────┐ │
+│  │ Plugin Manager (插件管理器)                                │ │
+│  │  - 插件发现与加载                                          │ │
+│  │  - 菜单注册                                                 │ │
+│  │  - RPC 路由注册                                             │ │
+│  │  - 静态文件路由注册                                        │ │
+│  │  - 认证提供者注册                                          │ │
+│  │  - 插件生命周期管理                                        │ │
+│  └────────────────────────────────────────────────────────────┘ │
+│                                                                  │
+│  ┌────────────────────────────────────────────────────────────┐ │
+│  │ Core RPC Methods (核心 RPC 方法)                           │ │
+│  │  - console.get_menu_items (获取菜单项)                     │ │
+│  │  - console.get_plugin_list (获取插件列表)                  │ │
+│  │  - console.enable_plugin (启用插件)                        │ │
+│  │  - console.disable_plugin (禁用插件)                       │ │
+│  │  - console.get_config (获取控制台配置)                     │ │
+│  └────────────────────────────────────────────────────────────┘ │
+│                                                                  │
+│  ┌────────────────────────────────────────────────────────────┐ │
+│  │ Static Files (静态文件服务)                                │ │
+│  │  - /static/core/* (核心静态文件)                           │ │
+│  │  - /static/plugins/{plugin_name}/* (插件静态文件)          │ │
+│  └────────────────────────────────────────────────────────────┘ │
+└──────────────────────────┬──────────────────────────────────────┘
+                           │ WebSocket: Kernel 连接
+                           ↓
+┌─────────────────────────────────────────────────────────────────┐
+│                         Kernel                                   │
+│  - RPC 路由                                                      │
+│  - 事件分发                                                      │
+│  - 注册中心                                                      │
+└─────────────────────────────────────────────────────────────────┘
+                           ↑
+                           │ 标准 Kite 模块
+                           │
+┌─────────────────────────────────────────────────────────────────┐
+│                    业务插件模块                                  │
+│  (如 Evol、其他业务系统)                                        │
+│                                                                  │
+│  - 提供 RPC 方法                                                 │
+│  - 发布事件                                                      │
+│  - 订阅事件                                                      │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## 核心控制台功能
+
+### 基础管理功能
+
+1. **模块管理**
+   - 模块列表查看
+   - 模块启动/停止/重启
+   - 模块配置查看/编辑
+   - 模块状态监控
+
+2. **配置管理**
+   - 全局配置查看/编辑
+   - 模块配置查看/编辑
+   - 配置热重载
+
+3. **事件查看**
+   - 实时事件流
+   - 事件过滤（按模块、事件类型）
+   - 事件搜索
+   - 事件导出
+
+4. **注册中心**
+   - RPC 方法查询
+   - 事件查询
+   - 注册记录查看
+   - 注册中心测试
+
+5. **系统监控**
+   - Kernel 健康状态
+   - 模块运行时长
+   - RPC 调用统计
+   - 事件统计
+
+6. **认证管理**
+   - 配对码生成
+   - Token 管理
+   - 会话管理
+
+## 插件系统设计
+
+### 插件接口定义
+
+每个插件需要实现以下接口：
+
+```python
+# plugin_interface.py
+from abc import ABC, abstractmethod
+from typing import Optional, List, Dict, Callable
+
+class ConsolePlugin(ABC):
+    """控制台插件基类"""
+
+    @abstractmethod
+    def get_plugin_info(self) -> dict:
+        """
+        返回插件基本信息
+
+        Returns:
+            {
+                "id": "evol",
+                "name": "Evol 业务系统",
+                "version": "1.0.0",
+                "description": "AI 模型服务计费系统",
+                "author": "Your Name",
+                "requires": ["kite>=1.5.0"]
+            }
+        """
+        pass
+
+    @abstractmethod
+    def get_menu_items(self) -> List[dict]:
+        """
+        返回菜单项定义
+
+        Returns:
+            [
+                {
+                    "id": "evol-account",
+                    "label": "账户管理",
+                    "icon": "user",
+                    "route": "/evol/account",
+                    "order": 100,
+                    "requires_auth": ["evol_user"]
+                },
+                {
+                    "id": "evol-credits",
+                    "label": "积分统计",
+                    "icon": "chart",
+                    "route": "/evol/credits",
+                    "order": 101,
+                    "requires_auth": ["evol_user"]
+                }
+            ]
+        """
+        pass
+
+    @abstractmethod
+    def get_rpc_methods(self) -> Dict[str, Callable]:
+        """
+        返回 RPC 方法映射
+
+        Returns:
+            {
+                "evol.get_user_info": self.get_user_info,
+                "evol.get_credits_stats": self.get_credits_stats,
+                "evol.list_tokens": self.list_tokens
+            }
+        """
+        pass
+
+    def get_auth_provider(self) -> Optional['AuthProvider']:
+        """
+        返回认证提供者（可选）
+
+        Returns:
+            EvolAuthProvider() 或 None
+        """
+        return None
+
+    def get_static_routes(self) -> List[tuple]:
+        """
+        返回静态文件路由
+
+        Returns:
+            [
+                ("/evol/static", "plugins/evol/static")
+            ]
+        """
+        return []
+
+    def get_config_schema(self) -> Optional[dict]:
+        """
+        返回配置 Schema（可选）
+
+        Returns:
+            {
+                "type": "object",
+                "properties": {
+                    "api_url": {"type": "string"},
+                    "timeout": {"type": "integer"}
+                }
+            }
+        """
+        return None
+
+    async def on_enable(self):
+        """插件启用时的回调"""
+        pass
+
+    async def on_disable(self):
+        """插件禁用时的回调"""
+        pass
+```
+
+### 认证提供者接口
+
+```python
+# auth_provider.py
+from abc import ABC, abstractmethod
+
+class AuthProvider(ABC):
+    """认证提供者基类"""
+
+    @abstractmethod
+    async def verify_token(self, token: str) -> Optional[dict]:
+        """
+        验证 token
+
+        Args:
+            token: 认证 token
+
+        Returns:
+            如果有效，返回用户信息:
+            {
+                "user_id": "...",
+                "role": "admin",
+                "display_name": "...",
+                "expires_at": "..."
+            }
+            否则返回 None
+        """
+        pass
+
+    @abstractmethod
+    def get_auth_type(self) -> str:
+        """
+        返回认证类型标识
+
+        Returns:
+            "evol_phone" 或 "oauth_github" 等
+        """
+        pass
+```
+
+### 插件目录结构
+
+```
+extensions/
+└── plugins/
+    ├── evol/
+    │   ├── plugin.py          # 插件主文件（实现 ConsolePlugin）
+    │   ├── config.yaml        # 插件配置
+    │   ├── auth_provider.py   # 认证提供者（可选）
+    │   ├── rpc_methods.py     # RPC 方法实现
+    │   ├── static/            # 静态文件
+    │   │   ├── js/
+    │   │   ├── css/
+    │   │   └── images/
+    │   └── templates/         # 模板文件（可选）
+    │
+    └── another_plugin/
+        └── ...
+```
+
+### 插件配置文件
+
+```yaml
+# plugins/evol/config.yaml
+plugin:
+  id: evol
+  name: Evol 业务系统
+  version: 1.0.0
+  enabled: true
+
+  # 依赖
+  requires:
+    - kite>=1.5.0
+
+  # 菜单项
+  menu_items:
+    - id: evol-account
+      label: 账户管理
+      icon: user
+      route: /evol/account
+      order: 100
+      requires_auth: [evol_user]
+
+    - id: evol-credits
+      label: 积分统计
+      icon: chart
+      route: /evol/credits
+      order: 101
+      requires_auth: [evol_user]
+
+  # 认证
+  auth:
+    provider: evol_phone
+    login_route: /evol/login
+
+  # 静态文件
+  static:
+    mount_path: /evol/static
+    directory: static
+```
+
+## 插件管理器实现
+
+### 核心功能
+
+```python
+# plugin_manager.py
+class PluginManager:
+    """插件管理器"""
+
+    def __init__(self, plugins_dir: str):
+        self.plugins_dir = plugins_dir
+        self.plugins: Dict[str, ConsolePlugin] = {}
+        self.enabled_plugins: Set[str] = set()
+        self.auth_providers: Dict[str, AuthProvider] = {}
+
+    async def discover_plugins(self):
+        """发现并加载所有插件"""
+        for plugin_dir in Path(self.plugins_dir).iterdir():
+            if plugin_dir.is_dir() and (plugin_dir / "plugin.py").exists():
+                await self._load_plugin(plugin_dir)
+
+    async def _load_plugin(self, plugin_dir: Path):
+        """加载单个插件"""
+        # 动态导入插件模块
+        # 实例化插件类
+        # 注册到 plugins 字典
+        pass
+
+    async def enable_plugin(self, plugin_id: str):
+        """启用插件"""
+        plugin = self.plugins.get(plugin_id)
+        if not plugin:
+            raise ValueError(f"Plugin {plugin_id} not found")
+
+        # 注册菜单项
+        # 注册 RPC 方法
+        # 注册静态文件路由
+        # 注册认证提供者
+        # 调用 on_enable 回调
+
+        self.enabled_plugins.add(plugin_id)
+
+    async def disable_plugin(self, plugin_id: str):
+        """禁用插件"""
+        plugin = self.plugins.get(plugin_id)
+        if not plugin:
+            raise ValueError(f"Plugin {plugin_id} not found")
+
+        # 注销菜单项
+        # 注销 RPC 方法
+        # 注销静态文件路由
+        # 注销认证提供者
+        # 调用 on_disable 回调
+
+        self.enabled_plugins.discard(plugin_id)
+
+    def get_all_menu_items(self) -> List[dict]:
+        """获取所有已启用插件的菜单项"""
+        menu_items = []
+        for plugin_id in self.enabled_plugins:
+            plugin = self.plugins[plugin_id]
+            menu_items.extend(plugin.get_menu_items())
+
+        # 按 order 排序
+        menu_items.sort(key=lambda x: x.get("order", 999))
+        return menu_items
+
+    async def verify_token(self, token: str, auth_type: str) -> Optional[dict]:
+        """使用指定的认证提供者验证 token"""
+        provider = self.auth_providers.get(auth_type)
+        if provider:
+            return await provider.verify_token(token)
+        return None
+```
+
+## 前端架构
+
+### 核心控制台 UI
+
+```javascript
+// console-app.js
+class ConsoleApp {
+  constructor() {
+    this.kernelClient = null;
+    this.menuItems = [];
+    this.currentRoute = '/';
+    this.userInfo = null;
+  }
+
+  async init() {
+    // 初始化 KernelClient
+    await this.initKernelClient();
+
+    // 加载菜单项
+    await this.loadMenuItems();
+
+    // 渲染菜单
+    this.renderMenu();
+
+    // 初始化路由
+    this.initRouter();
+  }
+
+  async loadMenuItems() {
+    // 调用 console.get_menu_items RPC
+    const result = await this.kernelClient.call('console.get_menu_items');
+    this.menuItems = result.menu_items;
+  }
+
+  renderMenu() {
+    // 渲染左侧菜单
+    // 核心菜单 + 插件菜单
+  }
+
+  initRouter() {
+    // 前端路由
+    // 根据 route 加载对应的视图
+  }
+}
+```
+
+### 插件前端集成
+
+插件可以提供自己的前端代码：
+
+```html
+<!-- plugins/evol/static/account.html -->
+<div id="evol-account-page">
+  <h2>账户管理</h2>
+  <!-- 插件的 UI -->
+</div>
+
+<script>
+// 插件的 JS 代码
+// 可以使用全局的 kernelClient 调用 RPC
+async function loadAccountInfo() {
+  const result = await window.kernelClient.call('evol.get_user_info');
+  // 渲染数据
+}
+</script>
+```
+
+## 认证流程
+
+### 多认证方式并存
+
+```
+用户访问控制台
+    ↓
+检查本地 token
+    ↓
+┌─────────────────────────────────────┐
+│ 有 token？                          │
+├─────────────────────────────────────┤
+│ YES → 尝试连接 /ws/relay            │
+│       ├─ 配对码 token？             │
+│       │   └─ 使用配对码认证         │
+│       ├─ Kite token？               │
+│       │   └─ 使用 Kite token 认证   │
+│       └─ 插件 token？               │
+│           └─ 使用插件认证提供者     │
+│                                     │
+│ NO → 显示登录选项                   │
+│      ├─ 配对码登录                  │
+│      ├─ 手机号登录 (Evol 插件)     │
+│      └─ 其他登录方式 (其他插件)    │
+└─────────────────────────────────────┘
+```
+
+### Relay Service 认证改造
+
+```python
+# relay.py
+async def _handle_auth(self, client_ws: WebSocket, msg: dict):
+    token = msg.get("token")
+    auth_type = msg.get("auth_type", "auto")  # auto | pairing | plugin:{name}
+
+    # 1. 自动检测认证类型
+    if auth_type == "auto":
+        # 尝试配对码
+        token_info = self.pairing_manager.verify_token(token)
+        if token_info:
+            role = token_info["role"]
+            auth_type = "pairing"
+        else:
+            # 尝试所有插件的认证提供者
+            for plugin_id, provider in self.plugin_manager.auth_providers.items():
+                user_info = await provider.verify_token(token)
+                if user_info:
+                    role = user_info["role"]
+                    auth_type = f"plugin:{plugin_id}"
+                    break
+
+    # 2. 指定认证类型
+    elif auth_type == "pairing":
+        token_info = self.pairing_manager.verify_token(token)
+        if token_info:
+            role = token_info["role"]
+
+    elif auth_type.startswith("plugin:"):
+        plugin_id = auth_type.split(":", 1)[1]
+        provider = self.plugin_manager.auth_providers.get(plugin_id)
+        if provider:
+            user_info = await provider.verify_token(token)
+            if user_info:
+                role = user_info["role"]
+
+    # 3. 认证失败
+    else:
+        await client_ws.send_json({"type": "error", "message": "Invalid token"})
+        await client_ws.close(code=4001)
+        return
+
+    # 继续连接流程...
+```
+
+## 配置管理
+
+### 控制台配置
+
+```yaml
+# console/config.yaml
+console:
+  name: Kite 控制台
+  version: 1.0.0
+
+  # 插件目录
+  plugins_dir: extensions/plugins
+
+  # 默认启用的插件
+  enabled_plugins:
+    - evol
+
+  # 核心菜单项
+  core_menu_items:
+    - id: modules
+      label: 模块管理
+      icon: grid
+      route: /modules
+      order: 1
+
+    - id: config
+      label: 配置管理
+      icon: settings
+      route: /config
+      order: 2
+
+    - id: events
+      label: 事件查看
+      icon: activity
+      route: /events
+      order: 3
+
+    - id: registry
+      label: 注册中心
+      icon: database
+      route: /registry
+      order: 4
+
+  # 认证配置
+  auth:
+    # 配对码配置
+    pairing:
+      enabled: true
+      code_length: 6
+      token_expiry: 2592000  # 30天
+```
+
+## 部署与使用
+
+### 安装插件
+
+```bash
+# 1. 将插件复制到 plugins 目录
+cp -r my_plugin extensions/plugins/
+
+# 2. 启用插件（通过控制台或配置文件）
+# 方式 1：修改 console/config.yaml
+enabled_plugins:
+  - evol
+  - my_plugin
+
+# 方式 2：通过控制台 UI 启用
+```
+
+### 开发插件
+
+```python
+# plugins/my_plugin/plugin.py
+from console.plugin_interface import ConsolePlugin
+
+class MyPlugin(ConsolePlugin):
+    def get_plugin_info(self):
+        return {
+            "id": "my_plugin",
+            "name": "我的插件",
+            "version": "1.0.0"
+        }
+
+    def get_menu_items(self):
+        return [
+            {
+                "id": "my-page",
+                "label": "我的页面",
+                "icon": "star",
+                "route": "/my/page",
+                "order": 200
+            }
+        ]
+
+    def get_rpc_methods(self):
+        return {
+            "my_plugin.hello": self.hello
+        }
+
+    async def hello(self, params: dict, context: dict):
+        return {"message": "Hello from my plugin!"}
+```
+
+## 优势与特性
+
+### 1. 业务隔离
+- 核心控制台不包含业务逻辑
+- 业务功能通过插件接入
+- 插件可独立开发、测试、部署
+
+### 2. 灵活扩展
+- 动态菜单：插件启用时菜单项出现
+- 动态路由：插件提供自己的路由
+- 动态认证：插件提供自己的认证方式
+
+### 3. 统一体验
+- 统一的 UI 风格
+- 统一的通信协议（WebSocket JSON-RPC 2.0）
+- 统一的错误处理
+
+### 4. 易于定制
+- 控制台名称可配置
+- 主题可定制
+- 菜单顺序可调整
+
+### 5. 安全可控
+- 基于角色的权限控制
+- 插件隔离
+- Token 管理
+
+## 未来扩展
+
+### 1. 插件市场
+- 插件发现与安装
+- 插件评分与评论
+- 插件更新管理
+
+### 2. 主题系统
+- 多主题支持
+- 自定义主题
+- 暗色模式
+
+### 3. 国际化
+- 多语言支持
+- 插件本地化
+
+### 4. 权限细化
+- 基于资源的权限控制
+- 动态权限分配
+- 审计日志
+
+### 5. 插件通信
+- 插件间事件通信
+- 插件间 RPC 调用
+- 共享状态管理