@agentunion/kite 1.5.0 → 1.6.0

package/docs/Evol/346/216/247/345/210/266/345/217/260/346/217/222/344/273/266/345/214/226/346/236/266/346/236/204/346/246/202/350/246/201.md

@@ -0,0 +1,604 @@
+# Evol 控制台插件化架构概要
+
+> 详细实现参考 [Evol控制台插件化架构设计.md](Evol控制台插件化架构设计.md)
+
+---
+
+## 一、核心理念
+
+### 1.1 设计原则
+
+- **数据主权在模块**：模块决定暴露什么数据和操作
+- **权限控制在模块**：模块检查每个 RPC 调用的权限
+- **前端只负责渲染**：根据配置加载数据并渲染 UI
+- **注册中心是发现机制**：前端通过注册中心发现可用面板
+
+### 1.2 职责边界
+
+| 层级 | 职责 | 不负责 |
+|------|------|--------|
+| **模块** | 数据主权、权限控制、业务逻辑、决定暴露什么 | UI 渲染、前端交互 |
+| **注册中心** | 服务发现、配置存储、查询接口 | 权限判断、业务逻辑 |
+| **Kernel** | RPC 路由、事件分发、上下文传递 | 业务逻辑、权限判断 |
+| **前端（Evol）** | UI 渲染、用户交互、加载状态显示 | 权限判断、业务逻辑、数据过滤 |
+
+---
+
+## 二、整体架构
+
+### 2.1 架构图
+
+```mermaid
+graph TB
+    subgraph Browser["浏览器"]
+        UI["Evol 控制台<br/>http://127.0.0.1:18766"]
+        Framework["主框架 evol-app.js"]
+        PanelContainer["面板容器"]
+        KC["KernelClient<br/>单一 WebSocket"]
+
+        UI --> Framework
+        Framework --> PanelContainer
+        Framework --> KC
+    end
+
+    subgraph KernelLayer["Kernel"]
+        RPCRouter["RPC 路由器"]
+        EventHub["事件分发器"]
+    end
+
+    subgraph Modules["模块层"]
+        Launcher["Launcher"]
+        Watchdog["Watchdog"]
+        Logs["Logs"]
+        Other["其他模块..."]
+    end
+
+    subgraph Registry["注册中心"]
+        RegDB[("面板配置<br/>RPC 方法<br/>事件定义")]
+    end
+
+    KC -->|WebSocket| KernelLayer
+    Framework -.->|查询面板列表| Registry
+    RPCRouter -->|转发 RPC| Modules
+    Modules -.->|注册| Registry
+    EventHub -->|事件通知| KC
+
+    style Browser fill:#e1f5ff
+    style KernelLayer fill:#fff4e1
+    style Modules fill:#e8f5e9
+    style Registry fill:#f3e5f5
+```
+
+### 2.2 核心流程
+
+```mermaid
+sequenceDiagram
+    participant Module as 模块
+    participant Registry as 注册中心
+    participant Kernel as Kernel
+    participant Frontend as 前端
+
+    Note over Module,Registry: 1. 注册阶段
+    Module->>Registry: 注册面板配置 + RPC 方法
+
+    Note over Frontend,Registry: 2. 发现阶段
+    Frontend->>Registry: 查询面板列表
+    Registry-->>Frontend: 返回面板配置
+    Frontend->>Frontend: 构建菜单
+
+    Note over Frontend,Module: 3. 调用阶段
+    Frontend->>Kernel: RPC 调用
+    Kernel->>Module: 转发 RPC
+    Module->>Module: 权限检查 + 执行
+    Module-->>Frontend: 返回数据
+    Frontend->>Frontend: 渲染 UI
+
+    Note over Module,Frontend: 4. 事件驱动刷新
+    Module->>Kernel: 发布事件
+    Kernel->>Frontend: 事件通知
+    Frontend->>Frontend: 自动刷新
+```
+
+---
+
+## 三、面板暴露控制
+
+### 3.1 两级控制机制
+
+面板是否暴露由两个参数控制：
+
+| 参数 | 位置 | 作用 | 说明 |
+|------|------|------|------|
+| `has_console_panel` | `module.md` | 模块级声明 | 模块是否提供控制台面板（静态，随代码发布） |
+| `enabled` | `config.yaml` | 配置级控制 | 面板是否启用（动态，用户可修改） |
+
+### 3.2 控制逻辑
+
+```mermaid
+graph LR
+    A[模块启动] --> B{module.md<br/>has_console_panel?}
+    B -->|false| C[不注册面板]
+    B -->|true| D{config.yaml<br/>console_panel.enabled?}
+    D -->|false| C
+    D -->|true| E[注册面板到 Registry]
+
+    style C fill:#ffcdd2
+    style E fill:#c8e6c9
+```
+
+| has_console_panel | config.enabled | 结果 |
+|-------------------|----------------|------|
+| `false` | - | 不注册（模块不提供面板） |
+| `true` | `false` | 不注册（面板被禁用） |
+| `true` | `true` | 注册 |
+| `true` | 未配置 | 不注册（默认不启用） |
+
+---
+
+## 四、注册配置链路
+
+### 4.1 配置文件分布
+
+每个提供面板的模块有三个配置文件：
+
+```
+extensions/services/statistics/
+├── module.md               # 声明 has_console_panel: true
+├── config.yaml             # 控制 console_panel.enabled: true
+├── console_panel.yaml      # 面板详细配置（数据源、操作、资源路径）
+└── entry.py                # 读取配置并执行注册
+```
+
+### 4.2 配置职责
+
+| 文件 | 内容 | 修改频率 |
+|------|------|---------|
+| `module.md` | `has_console_panel: true/false` | 极少（跟随代码） |
+| `config.yaml` | `console_panel.enabled: true/false` | 偶尔（用户控制开关） |
+| `console_panel.yaml` | 面板详细配置（数据源、操作、资源路径等） | 偶尔（功能变更时） |
+| `entry.py` | 读取以上配置，执行注册 | 极少 |
+
+### 4.3 注册流程
+
+```mermaid
+graph TB
+    A[module.md] -->|has_console_panel: true| B{提供面板?}
+    B -->|false| C[跳过]
+    B -->|true| D[config.yaml]
+
+    D -->|enabled: true| E{启用?}
+    E -->|false| C
+    E -->|true| F[console_panel.yaml]
+
+    F --> G[entry.py 读取配置]
+    G --> H[构建注册 payload]
+    H --> I[RPC: registry.register]
+    I --> J[注册中心存储]
+    J --> K[Evol 控制台查询并显示菜单]
+
+    style C fill:#ffcdd2
+    style K fill:#c8e6c9
+```
+
+### 4.4 console_panel.yaml 配置结构
+
+```yaml
+# 基础信息
+panel_id: statistics
+title: 统计分析
+icon: chart
+order: 10
+category: business           # system / service / business / tool
+
+# 数据源（面板需要展示的数据）
+data_sources:
+  - id: stats_data
+    rpc_method: statistics.get_stats
+    refresh:
+      strategy: event        # event / polling / manual / hybrid
+      events: [statistics.data_changed]
+
+  - id: history
+    rpc_method: statistics.get_history
+    refresh:
+      strategy: polling
+      interval: 10000
+
+# 操作（面板提供的功能）
+actions:
+  - id: export_report
+    rpc_method: statistics.export_report
+    params_schema:
+      format: string
+
+# 资源路径（面板前端文件位置）
+resources:
+  type: local                # local / remote / api
+```
+
+---
+
+## 五、核心概念
+
+### 5.1 面板（Panel）
+
+控制台中的一个功能页面，对应左侧菜单的一个菜单项。由**数据源**、**操作**、**渲染器**组成。
+
+### 5.2 数据源（Data Source）
+
+面板需要展示的数据，通过 RPC 方法获取。每个数据源有独立的**刷新策略**。
+
+### 5.3 操作（Action）
+
+面板提供的功能按钮，通过 RPC 方法执行。权限检查由模块侧完成。
+
+### 5.4 刷新策略（Refresh Strategy）
+
+| 策略 | 说明 | 适用场景 |
+|------|------|---------|
+| `event` | 事件驱动刷新 | 数据变化有事件通知 |
+| `polling` | 定时轮询 | 需要定期更新（如监控） |
+| `manual` | 手动刷新 | 按需查看（如历史记录） |
+| `hybrid` | 事件 + 轮询 | 需要实时性又需要兜底 |
+
+### 5.5 渲染器（Renderer）
+
+负责将数据渲染成 UI 的前端组件。两种类型：
+
+- **自定义面板**：完全自定义的 JS 文件（如 `panels/launcher/`）
+- **通用渲染器**：根据 `ui_hints` 配置自动渲染（如 `generic-table.js`）
+
+---
+
+## 六、前端页面组织
+
+### 6.1 单页应用（SPA）架构
+
+**核心特点**：
+- ✅ 只有一个 HTML 文件（`index.html`）
+- ✅ 统一入口：`http://localhost:18766/`
+- ✅ 菜单切换不刷新页面，只替换面板容器内容
+- ✅ WebSocket 连接保持，登录状态保持
+
+### 6.2 页面结构
+
+```
+index.html（主框架）
+├── 左侧菜单容器（始终存在）
+└── 右侧面板容器（内容动态替换）
+```
+
+**菜单切换机制**：
+
+```mermaid
+sequenceDiagram
+    participant User as 用户
+    participant Menu as 菜单
+    participant Container as 面板容器
+
+    User->>Menu: 点击"统计分析"
+    Menu->>Container: 清空容器
+    Menu->>Container: 加载 statistics/ 资源
+    Container->>User: 显示统计面板
+
+    Note over User,Container: 页面未刷新<br/>URL 不变<br/>WebSocket 保持连接
+
+    User->>Menu: 点击"套餐支付"
+    Menu->>Container: 清空容器
+    Menu->>Container: 加载 payment/ 资源
+    Container->>User: 显示支付面板
+```
+
+**关键特征**：
+
+| 特征 | 状态 |
+|------|------|
+| 页面刷新 | ❌ 不刷新 |
+| URL 变化 | ❌ 不变（或 hash 变化） |
+| WebSocket | ✅ 保持连接 |
+| 登录状态 | ✅ 保持 |
+| 菜单 | ✅ 始终显示 |
+
+### 6.3 前端实现归属
+
+**由 Evol 模块统一提供**：
+
+```
+extensions/services/evol/static/
+├── index.html              # 主页面框架
+├── js/                     # 框架 JS
+│   ├── evol-app.js        # 主应用
+│   ├── kernel-client.js   # WebSocket 客户端
+│   ├── base-panel.js      # 面板基类
+│   └── panel-loader.js    # 面板加载器
+├── panels/                 # 面板实现（可选）
+│   ├── launcher/          # Launcher 面板
+│   ├── system-info/       # 系统信息面板
+│   └── generic-table.js   # 通用渲染器
+└── css/                    # 全局样式
+    ├── style.css          # 框架样式
+    ├── components.css     # 组件样式
+    └── panel.css          # 面板通用样式
+```
+
+**职责划分**：
+
+| 团队 | 负责内容 |
+|------|---------|
+| **Evol 团队** | 框架 + 通用渲染器 + 核心面板 |
+| **模块团队** | 后端 RPC（必须）+ 自定义面板（可选） |
+
+---
+
+## 七、面板资源的三种组织方式
+
+模块可以灵活选择面板资源的存放位置：
+
+### 7.1 方式 1：放在 Evol 模块下（集中管理）
+
+```
+evol/static/panels/statistics/
+├── index.html
+├── style.css
+└── panel.js
+```
+
+**特点**：
+- Statistics 模块只注册配置，不提供前端
+- 前端由 Evol 团队统一维护
+- 适合：简单面板、需要统一风格
+
+### 7.2 方式 2：放在模块自己下（模块自治）
+
+```
+statistics/static/console/
+├── index.html
+├── style.css
+└── panel.js
+```
+
+**配置**：
+
+```yaml
+resources:
+  type: remote
+  base_url: http://127.0.0.1:18773/console/
+```
+
+**特点**：
+- 模块提供静态文件服务
+- 前端和后端在同一模块
+- 适合：复杂面板、独立开发
+
+### 7.3 方式 3：通过 API 动态获取
+
+```yaml
+resources:
+  type: api
+  endpoints:
+    html: http://127.0.0.1:18773/api/console/template
+    css: http://127.0.0.1:18773/api/console/style
+    js: http://127.0.0.1:18773/api/console/script
+```
+
+**特点**：
+- 模块提供 API 返回 HTML/CSS/JS
+- 可以根据用户权限动态生成
+- 适合：需要动态定制的面板
+
+### 7.4 方式对比
+
+| 方式 | 前端位置 | 开发团队 | 适用场景 | 推荐度 |
+|------|---------|---------|---------|--------|
+| 方式 1 | Evol 模块 | Evol 团队 | 简单面板 | ⭐⭐⭐⭐⭐ |
+| 方式 2 | 模块自己 | 模块团队 | 复杂面板 | ⭐⭐⭐⭐ |
+| 方式 3 | API 动态 | 模块团队 | 动态面板 | ⭐⭐⭐ |
+
+---
+
+## 八、RPC 调用链路
+
+### 8.1 调用层级
+
+```mermaid
+graph LR
+    A[面板 JS] -->|调用| B[BasePanel]
+    B -->|调用| C[KernelClient]
+    C -->|WebSocket| D[Kernel]
+    D -->|转发| E[模块]
+
+    style A fill:#e1f5ff
+    style C fill:#e8f5e9
+    style E fill:#fff9c4
+```
+
+**调用者**：面板 JS（渲染器）是 RPC 调用的发起者。
+
+### 8.2 完整调用流程
+
+```mermaid
+sequenceDiagram
+    participant User as 用户
+    participant Panel as 面板 JS
+    participant BP as BasePanel
+    participant KC as KernelClient
+    participant Kernel as Kernel
+    participant Module as 模块
+
+    User->>Panel: 点击"启动模块"
+    Panel->>BP: executeAction('start_module', {name: 'xxx'})
+    BP->>KC: rpc('launcher.start_module', {name: 'xxx'})
+    KC->>Kernel: WebSocket 发送 RPC
+    Kernel->>Module: 转发 RPC
+    Module->>Module: 权限检查
+
+    alt 权限通过
+        Module->>Module: 执行业务逻辑
+        Module-->>Kernel: 返回结果
+        Kernel-->>KC: 返回结果
+        KC-->>BP: 返回结果
+        BP-->>Panel: 返回结果
+        Panel->>Panel: 等待事件自动刷新
+    else 权限不足
+        Module-->>Kernel: 返回错误
+        Kernel-->>KC: 返回错误
+        KC-->>BP: 抛出异常
+        BP->>BP: showError()
+        BP-->>Panel: 抛出异常
+        Panel->>Panel: 恢复按钮状态
+    end
+```
+
+### 8.3 关键角色
+
+| 角色 | 职责 |
+|------|------|
+| **面板 JS** | 响应用户交互，调用 BasePanel 方法 |
+| **BasePanel** | 封装 RPC 调用，自动数据管理，错误处理 |
+| **KernelClient** | 管理 WebSocket 连接，发送/接收 RPC |
+| **Kernel** | RPC 路由，转发到目标模块 |
+| **模块** | 权限检查，执行业务逻辑，返回数据 |
+
+---
+
+## 九、实际场景示例
+
+### 9.1 场景：统计 + 支付两个模块
+
+**推荐方案**：两个独立面板
+
+```mermaid
+graph TB
+    A[Evol 控制台] --> B[菜单]
+    B --> C[📊 统计分析]
+    B --> D[💳 套餐支付]
+
+    C --> C1[Statistics 模块提供]
+    D --> D1[Payment 模块提供]
+
+    style C fill:#e3f2fd
+    style D fill:#f3e5f5
+```
+
+**菜单组织**：
+
+```
+Evol 控制台
+├── 系统管理
+│   ├── 模块管理
+│   └── 系统监控
+├── 业务功能
+│   ├── 📊 统计分析    ← Statistics 模块
+│   └── 💳 套餐支付    ← Payment 模块
+```
+
+**用户体验**：
+1. 访问 `http://localhost:18766/`
+2. 点击"统计分析" → 显示统计面板
+3. 点击"套餐支付" → 显示支付面板
+4. 无需跳转页面，无需记住多个 URL
+
+---
+
+## 十、开发流程
+
+### 10.1 模块开发者（后端）
+
+**步骤**：
+
+1. 在 `module.md` 中声明 `has_console_panel: true`
+2. 在 `config.yaml` 中配置 `console_panel.enabled: true`
+3. 创建 `console_panel.yaml` 配置面板详情
+4. 实现 RPC 处理器（业务逻辑 + 权限检查）
+5. 在 `entry.py` 中读取配置并注册
+
+**开发成本**：
+- 简单模块：只需配置 + RPC，使用通用渲染器（零前端开发）
+- 复杂模块：配置 + RPC + 自定义面板 JS
+
+### 10.2 前端开发者
+
+**职责**：
+- 如果模块提供了 `ui_hints`，无需开发（通用渲染器自动处理）
+- 如果需要自定义 UI，创建面板 JS 文件
+
+**开发位置**：
+- 方式 1：在 `evol/static/panels/` 下创建
+- 方式 2：在模块的 `static/console/` 下创建
+
+---
+
+## 十一、核心优势
+
+```mermaid
+mindmap
+  root((插件化架构))
+    统一入口
+      单一 URL
+      一次登录
+      风格统一
+    降低成本
+      简单模块零前端
+      通用渲染器
+      复用框架
+    用户体验
+      无缝切换
+      实时更新
+      共享状态
+    易于扩展
+      新增模块自动接入
+      动态发现
+      灵活配置
+```
+
+---
+
+## 十二、总结
+
+### 12.1 核心要点
+
+1. **两级控制**：`has_console_panel`（模块级）+ `enabled`（配置级）
+2. **配置驱动**：通过 `console_panel.yaml` 声明数据源、操作、资源路径
+3. **单页应用**：统一入口，菜单切换不刷新页面
+4. **三种资源组织方式**：Evol 模块 / 模块自己 / API 动态
+5. **RPC 调用链路**：面板 JS → BasePanel → KernelClient → Kernel → 模块
+6. **权限控制在模块**：前端不做权限判断，模块检查每个 RPC
+
+### 12.2 架构优势
+
+- ✅ **解耦**：模块和前端通过 RPC 通信，职责清晰
+- ✅ **灵活**：支持自定义面板和通用渲染器
+- ✅ **安全**：权限控制在模块侧，前端无法绕过
+- ✅ **可扩展**：新增模块自动接入控制台
+- ✅ **易维护**：前后端分离，配置驱动
+
+### 12.3 开发效率
+
+| 角色 | 工作量 |
+|------|--------|
+| **模块开发者** | 配置 + RPC（简单模块零前端） |
+| **前端开发者** | 通用渲染器（零开发）或自定义面板 |
+| **用户** | 修改配置文件动态控制 |
+
+---
+
+## 附录
+
+### A. 参考文档
+
+- [Evol 控制台插件化架构设计（详细版）](Evol控制台插件化架构设计.md)
+- [Kite 框架设计](Kite框架设计/)
+- [注册中心设计](注册中心设计.md)
+- [事件中心设计](事件中心设计.md)
+- [模块开发指南](模块开发指南.md)
+
+### B. 关键问题速查
+
+| 问题 | 答案 |
+|------|------|
+| 模块需要独立页面吗？ | 不需要，统一入口，菜单切换 |
+| 前端资源放在哪里？ | 三种方式：Evol 模块 / 模块自己 / API 动态 |
+| 谁调用模块的 RPC？ | 面板 JS（渲染器） |
+| 菜单切换是打开新页面吗？ | 不是，只是替换面板容器内容 |
+| 配置在哪里完成？ | module.md + config.yaml + console_panel.yaml |
+| 权限在哪里检查？ | 模块侧（RPC 处理器中） |