@agentunion/kite 1.5.0 → 1.6.1

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/350/256/276/350/256/241.md

@@ -0,0 +1,1708 @@
+# Evol 控制台插件化架构设计
+
+## 一、概述
+
+Evol 控制台采用插件化架构，模块通过注册中心声明控制台面板，前端动态加载并渲染。核心理念：
+
+- **数据主权在模块**：模块决定暴露什么数据和操作
+- **权限控制在模块**：模块检查每个 RPC 调用的权限
+- **前端只负责渲染**：根据配置加载数据并渲染 UI
+- **注册中心是发现机制**：前端通过注册中心发现可用面板
+
+---
+
+## 二、架构图
+
+```
+┌─────────────────────────────────────────────────────┐
+│  浏览器                                              │
+│  ┌───────────────────────────────────────────────┐  │
+│  │ Evol 控制台 (http://127.0.0.1:18766)          │  │
+│  │                                                │  │
+│  │ ┌─────────────────────────────────────────┐   │  │
+│  │ │ 主框架 (evol-app.js)                    │   │  │
+│  │ │ - 查询 Registry 获取面板列表            │   │  │
+│  │ │ - 动态加载面板 JS                       │   │  │
+│  │ │ - 提供 KernelClient                     │   │  │
+│  │ └─────────────────────────────────────────┘   │  │
+│  │                                                │  │
+│  │ ┌─────────────────────────────────────────┐   │  │
+│  │ │ 面板容器                                 │   │  │
+│  │ │ - LauncherPanel (panels/launcher.js)    │   │  │
+│  │ │ - WatchdogPanel (panels/watchdog.js)    │   │  │
+│  │ │ - GenericTablePanel (通用渲染器)        │   │  │
+│  │ └─────────────────────────────────────────┘   │  │
+│  │                                                │  │
+│  │ ┌─────────────────────────────────────────┐   │  │
+│  │ │ KernelClient (kernel-client.js)         │   │  │
+│  │ │ - 单一 WebSocket 连接                   │   │  │
+│  │ │ - rpc(method, params)                   │   │  │
+│  │ │ - subscribe(event, handler)             │   │  │
+│  │ └─────────────────────────────────────────┘   │  │
+│  └───────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────┘
+                      ↓ WebSocket (单一连接)
+┌─────────────────────────────────────────────────────┐
+│  Kernel (ws://127.0.0.1:18767/ws)                   │
+│  ┌───────────────────────────────────────────────┐  │
+│  │ RPC 路由器                                     │  │
+│  │ - 解析 method: "launcher.list_modules"       │  │
+│  │ - 查询 Registry 找到 Launcher WebSocket     │  │
+│  │ - 转发 RPC 到 Launcher                       │  │
+│  │ - 返回结果给前端                              │  │
+│  └───────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────┘
+         ↓ WebSocket         ↓ WebSocket         ↓ WebSocket
+┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐
+│ Launcher         │  │ Watchdog         │  │ Logs             │
+│ (连接到 Kernel)  │  │ (连接到 Kernel)  │  │ (连接到 Kernel)  │
+│                  │  │                  │  │                  │
+│ 注册 RPC:        │  │ 注册 RPC:        │  │ 注册 RPC:        │
+│ - list_modules   │  │ - get_stats      │  │ - search         │
+│ - start_module   │  │ - get_history    │  │ - get_changes    │
+│ - stop_module    │  │                  │  │                  │
+└──────────────────┘  └──────────────────┘  └──────────────────┘
+```
+
+---
+
+## 三、面板暴露控制
+
+### 3.1 两级控制机制
+
+面板是否暴露由两个参数控制：
+
+1. **`has_console_panel`**（模块级）：模块是否提供控制台面板
+2. **`enabled`**（配置级）：面板是否启用（可在配置文件中动态控制）
+
+### 3.2 控制逻辑
+
+```python
+# module.md (模块元数据)
+---
+name: launcher
+type: core
+has_console_panel: true  # 模块提供控制台面板
+---
+```
+
+```yaml
+# config.yaml (模块配置文件)
+console_panel:
+  enabled: true  # 面板是否启用（可动态修改）
+```
+
+### 3.3 注册逻辑
+
+```python
+# 模块注册时
+def should_register_panel():
+    # 1. 检查模块是否提供面板
+    if not module_metadata.has_console_panel:
+        return False
+
+    # 2. 检查配置是否启用
+    if not config.get('console_panel.enabled', False):
+        return False
+
+    return True
+
+# 注册到 Registry
+if should_register_panel():
+    registry.register({
+        "module_id": "launcher",
+        "metadata": {
+            "console_panel": {
+                "enabled": True,  # 最终状态
+                "panel_id": "launcher",
+                "title": "模块管理",
+                # ...
+            }
+        }
+    })
+```
+
+### 3.4 场景说明
+
+| has_console_panel | config.enabled | 结果 | 说明 |
+|-------------------|----------------|------|------|
+| `false` | - | 不注册 | 模块不提供面板 |
+| `true` | `false` | 不注册 | 面板被禁用 |
+| `true` | `true` | 注册 | 面板启用 |
+| `true` | 未配置 | 不注册 | 默认不启用 |
+
+---
+
+## 四、模块注册协议
+
+### 4.1 完整注册示例
+
+```python
+# Launcher 模块注册
+{
+    "module_id": "launcher",
+    "metadata": {
+        "console_panel": {
+            # 基础配置
+            "enabled": True,           # 最终启用状态
+            "panel_id": "launcher",    # 面板标识符
+            "title": "模块管理",        # 菜单显示名称
+            "icon": "grid",            # 图标（可选）
+            "order": 1,                # 菜单排序权重
+            "category": "system",      # 分类（system/service/tool）
+
+            # 数据源配置
+            "data_sources": [
+                {
+                    "id": "modules_list",
+                    "rpc_method": "launcher.list_modules",
+                    "params": {},
+                    "refresh": {
+                        "strategy": "event",  # event | polling | manual | hybrid
+                        "events": [
+                            "module.started",
+                            "module.stopped",
+                            "module.crashed"
+                        ]
+                    }
+                },
+                {
+                    "id": "module_stats",
+                    "rpc_method": "launcher.get_stats",
+                    "params": {},
+                    "refresh": {
+                        "strategy": "polling",
+                        "interval": 5000  # 5秒轮询
+                    }
+                }
+            ],
+
+            # 操作方法
+            "actions": [
+                {
+                    "id": "start_module",
+                    "rpc_method": "launcher.start_module",
+                    "params_schema": {
+                        "name": "string"
+                    }
+                },
+                {
+                    "id": "stop_module",
+                    "rpc_method": "launcher.stop_module",
+                    "params_schema": {
+                        "name": "string",
+                        "reason": "string"
+                    }
+                }
+            ],
+
+            # UI 提示（可选，给通用渲染器使用）
+            "ui_hints": {
+                "type": "table",  # table | form | dashboard
+                "columns": [
+                    {"field": "name", "label": "模块名", "width": "200px"},
+                    {"field": "type", "label": "类型", "width": "100px"},
+                    {"field": "state", "label": "状态", "width": "100px"}
+                ],
+                "row_actions": [
+                    {
+                        "action_id": "start_module",
+                        "label": "启动",
+                        "style": "success",
+                        "confirm": null
+                    },
+                    {
+                        "action_id": "stop_module",
+                        "label": "停止",
+                        "style": "danger",
+                        "confirm": "确定要停止该模块吗？"
+                    }
+                ]
+            }
+        }
+    },
+
+    # 注册 RPC 方法
+    "rpc_methods": {
+        "list_modules": {
+            "description": "列出所有模块",
+            "params": {},
+            "returns": {"modules": "array"}
+        },
+        "start_module": {
+            "description": "启动模块",
+            "params": {"name": "string"},
+            "returns": {"success": "boolean"}
+        },
+        "stop_module": {
+            "description": "停止模块",
+            "params": {"name": "string", "reason": "string"},
+            "returns": {"success": "boolean"}
+        },
+        "get_stats": {
+            "description": "获取统计信息",
+            "params": {},
+            "returns": {
+                "total": "number",
+                "running": "number",
+                "stopped": "number"
+            }
+        }
+    }
+}
+```
+
+### 4.2 配置字段说明
+
+#### 基础配置
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `enabled` | boolean | 是 | 面板是否启用 |
+| `panel_id` | string | 是 | 面板标识符，对应前端 JS 文件名 |
+| `title` | string | 是 | 菜单显示名称 |
+| `icon` | string | 否 | 图标名称 |
+| `order` | number | 否 | 菜单排序权重（越小越靠前） |
+| `category` | string | 否 | 分类（system/service/tool） |
+
+#### 数据源配置
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `id` | string | 是 | 数据源标识符 |
+| `rpc_method` | string | 是 | RPC 方法名（格式：`module_id.method_name`） |
+| `params` | object | 否 | RPC 调用参数 |
+| `refresh.strategy` | string | 是 | 刷新策略（event/polling/manual/hybrid） |
+| `refresh.events` | array | 否 | 订阅的事件列表（strategy=event 时必填） |
+| `refresh.interval` | number | 否 | 轮询间隔（毫秒，strategy=polling 时必填） |
+
+#### 操作配置
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `id` | string | 是 | 操作标识符 |
+| `rpc_method` | string | 是 | RPC 方法名 |
+| `params_schema` | object | 否 | 参数 schema |
+
+#### UI 提示（可选）
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `type` | string | 是 | 渲染器类型（table/form/dashboard） |
+| `columns` | array | 否 | 表格列配置（type=table 时使用） |
+| `row_actions` | array | 否 | 行操作配置（type=table 时使用） |
+
+---
+
+## 五、刷新策略
+
+### 5.1 策略类型
+
+| 策略 | 说明 | 适用场景 |
+|------|------|---------|
+| `event` | 事件驱动刷新 | 数据变化有事件通知（如模块状态变化） |
+| `polling` | 定时轮询刷新 | 数据需要定期更新（如资源监控） |
+| `manual` | 手动刷新 | 数据不需要自动更新（如历史记录） |
+| `hybrid` | 混合策略 | 同时使用事件和轮询 |
+
+### 5.2 配置示例
+
+#### 事件驱动
+
+```python
+"refresh": {
+    "strategy": "event",
+    "events": [
+        "module.started",
+        "module.stopped",
+        "module.crashed"
+    ]
+}
+```
+
+#### 定时轮询
+
+```python
+"refresh": {
+    "strategy": "polling",
+    "interval": 5000  # 5秒
+}
+```
+
+#### 手动刷新
+
+```python
+"refresh": {
+    "strategy": "manual"
+}
+```
+
+#### 混合策略
+
+```python
+"refresh": {
+    "strategy": "hybrid",
+    "polling": {
+        "interval": 10000  # 10秒轮询
+    },
+    "events": [
+        "watchdog.resource.warning",
+        "watchdog.resource.critical"
+    ]
+}
+```
+
+---
+
+## 六、前端实现
+
+### 6.1 目录结构
+
+```
+evol/static/
+├── index.html
+├── js/
+│   ├── evol-app.js        # 主应用
+│   ├── kernel-client.js   # Kernel WebSocket 客户端
+│   ├── base-panel.js      # 面板基类
+│   ├── panel-loader.js    # 面板加载器
+│   ├── event-bus.js       # 全局事件总线
+│   └── state-manager.js   # 全局状态管理
+├── panels/                 # 面板实现
+│   ├── launcher.js        # Launcher 自定义面板
+│   ├── watchdog.js        # Watchdog 自定义面板
+│   ├── logs.js            # Logs 自定义面板
+│   ├── generic-table.js   # 通用表格渲染器
+│   ├── generic-form.js    # 通用表单渲染器
+│   └── generic-dashboard.js # 通用仪表盘渲染器
+└── css/
+    ├── style.css          # 全局样式
+    └── panel.css          # 面板通用样式
+```
+
+### 6.2 面板加载流程
+
+```javascript
+// evol/static/js/evol-app.js
+class EvolConsole {
+    async init() {
+        // 1. 连接 Kernel
+        await this.connectKernel();
+
+        // 2. 查询所有面板
+        await this.loadPanels();
+
+        // 3. 构建菜单
+        this.buildMenu();
+
+        // 4. 订阅系统事件
+        this.subscribeSystemEvents();
+
+        // 5. 加载默认面板
+        if (this.panels.length > 0) {
+            await this.loadPanel(this.panels[0]);
+        }
+    }
+
+    async loadPanels() {
+        // 查询 Registry 获取所有声明了 console_panel 的模块
+        const modules = await this.kernel.rpc('registry.query', {
+            filter: 'metadata.console_panel.enabled == true'
+        });
+
+        this.panels = modules
+            .map(m => m.metadata.console_panel)
+            .filter(p => p.enabled)  // 二次过滤
+            .sort((a, b) => (a.order || 999) - (b.order || 999));
+
+        stateManager.setState({ modules: this.panels });
+    }
+
+    async loadPanel(panelConfig) {
+        const container = document.getElementById('panel-container');
+        await this.panelLoader.loadPanel(panelConfig, container);
+
+        stateManager.setState({ activeModule: panelConfig.panel_id });
+        eventBus.emit('panel:loaded', panelConfig);
+    }
+}
+```
+
+### 6.3 面板渲染决策
+
+```javascript
+// evol/static/js/panel-loader.js
+class PanelLoader {
+    async loadPanel(panelConfig, container) {
+        const panelId = panelConfig.panel_id;
+
+        try {
+            // 策略 1：尝试加载自定义面板
+            const panel = await this.loadCustomPanel(panelId, panelConfig, container);
+            this.currentPanel = panel;
+
+        } catch (error) {
+            console.warn(`Custom panel ${panelId}.js not found:`, error);
+
+            // 策略 2：使用通用渲染器
+            const panel = await this.loadGenericPanel(panelConfig, container);
+            this.currentPanel = panel;
+        }
+    }
+
+    async loadCustomPanel(panelId, panelConfig, container) {
+        // 尝试加载自定义面板 JS
+        const panelPath = `/panels/${panelId}.js`;
+        const module = await import(panelPath);
+        const PanelClass = module.default;
+
+        // 实例化
+        const panel = new PanelClass(container, this.kernel, panelConfig);
+        await panel.onMount();
+
+        return panel;
+    }
+
+    async loadGenericPanel(panelConfig, container) {
+        // 根据 ui_hints 选择通用渲染器
+        const renderer = this.selectGenericRenderer(panelConfig);
+
+        const module = await import(`/panels/${renderer}.js`);
+        const PanelClass = module.default;
+
+        const panel = new PanelClass(container, this.kernel, panelConfig);
+        await panel.onMount();
+
+        return panel;
+    }
+
+    selectGenericRenderer(panelConfig) {
+        const uiType = panelConfig.ui_hints?.type;
+
+        if (uiType === 'table') return 'generic-table';
+        if (uiType === 'form') return 'generic-form';
+        if (uiType === 'dashboard') return 'generic-dashboard';
+
+        // 默认使用表格渲染器
+        return 'generic-table';
+    }
+}
+```
+
+### 6.4 Base Panel（面板基类）
+
+```javascript
+// evol/static/js/base-panel.js
+export class BasePanel {
+    constructor(container, kernelClient, panelConfig) {
+        this.container = container;
+        this.kernel = kernelClient;
+        this.config = panelConfig;
+        this.subscriptions = [];
+        this.state = {};
+        this.mounted = false;
+
+        // 数据源管理
+        this.dataSources = new Map();  // id -> { data, loading, error }
+        this.refreshTimers = new Map();  // id -> timer
+    }
+
+    async onMount() {
+        this.mounted = true;
+
+        // 自动初始化所有数据源
+        if (this.config.data_sources) {
+            await this.initDataSources();
+        }
+    }
+
+    async onUnmount() {
+        this.mounted = false;
+
+        // 清理所有订阅
+        this.subscriptions.forEach(unsub => unsub());
+        this.subscriptions = [];
+
+        // 清理所有定时器
+        this.refreshTimers.forEach(timer => clearInterval(timer));
+        this.refreshTimers.clear();
+    }
+
+    async initDataSources() {
+        for (const source of this.config.data_sources) {
+            // 初始化数据源状态
+            this.dataSources.set(source.id, {
+                data: null,
+                loading: false,
+                error: null
+            });
+
+            // 加载初始数据
+            await this.loadDataSource(source.id);
+
+            // 设置刷新策略
+            this.setupRefreshStrategy(source);
+        }
+    }
+
+    async loadDataSource(sourceId, showLoading = true) {
+        const source = this.config.data_sources.find(s => s.id === sourceId);
+        if (!source) return;
+
+        const state = this.dataSources.get(sourceId);
+
+        if (showLoading) {
+            state.loading = true;
+            this.onDataSourceChange(sourceId, state);
+        }
+
+        try {
+            const result = await this.rpc(source.rpc_method, source.params || {});
+
+            state.data = result;
+            state.loading = false;
+            state.error = null;
+
+            this.onDataSourceChange(sourceId, state);
+
+        } catch (error) {
+            state.loading = false;
+            state.error = error.message;
+
+            this.onDataSourceChange(sourceId, state);
+            this.showError(`加载 ${sourceId} 失败: ${error.message}`);
+        }
+    }
+
+    setupRefreshStrategy(source) {
+        const { refresh } = source;
+
+        if (!refresh) return;
+
+        // 事件驱动刷新
+        if (refresh.strategy === 'event' || refresh.strategy === 'hybrid') {
+            refresh.events?.forEach(event => {
+                const unsubscribe = this.kernel.subscribe(event, () => {
+                    this.loadDataSource(source.id, false);  // 静默刷新
+                });
+                this.subscriptions.push(unsubscribe);
+            });
+        }
+
+        // 轮询刷新
+        if (refresh.strategy === 'polling' || refresh.strategy === 'hybrid') {
+            const interval = refresh.polling?.interval || refresh.interval || 5000;
+            const timer = setInterval(() => {
+                this.loadDataSource(source.id, false);  // 静默刷新
+            }, interval);
+            this.refreshTimers.set(source.id, timer);
+        }
+
+        // 手动刷新（不做任何自动刷新）
+        // strategy === 'manual'
+    }
+
+    // 子类重写此方法来响应数据变化
+    onDataSourceChange(sourceId, state) {
+        // 默认实现：触发重新渲染
+        this.render();
+    }
+
+    // 获取数据源数据
+    getData(sourceId) {
+        return this.dataSources.get(sourceId)?.data;
+    }
+
+    // 检查数据源是否加载中
+    isLoading(sourceId) {
+        return this.dataSources.get(sourceId)?.loading || false;
+    }
+
+    // 获取数据源错误
+    getError(sourceId) {
+        return this.dataSources.get(sourceId)?.error;
+    }
+
+    // 手动刷新数据源
+    async refreshDataSource(sourceId) {
+        await this.loadDataSource(sourceId, true);
+    }
+
+    // 执行操作
+    async executeAction(actionId, params) {
+        const action = this.config.actions?.find(a => a.id === actionId);
+        if (!action) {
+            throw new Error(`Action not found: ${actionId}`);
+        }
+
+        try {
+            const result = await this.rpc(action.rpc_method, params);
+            return result;
+        } catch (error) {
+            this.showError(`操作失败: ${error.message}`);
+            throw error;
+        }
+    }
+
+    // RPC 调用
+    async rpc(method, params = {}) {
+        return await this.kernel.rpc(method, params);
+    }
+
+    // 订阅事件
+    subscribe(eventPattern, handler) {
+        const unsubscribe = this.kernel.subscribe(eventPattern, handler);
+        this.subscriptions.push(unsubscribe);
+        return unsubscribe;
+    }
+
+    // 渲染方法（子类实现）
+    render() {
+        // 子类重写
+    }
+
+    showError(message) {
+        console.error(message);
+        // 可以集成 toast 通知
+    }
+}
+```
+
+---
+
+## 七、自定义面板开发
+
+### 7.1 Launcher 面板示例
+
+```javascript
+// evol/static/panels/launcher.js
+import { BasePanel } from '../js/base-panel.js';
+
+export default class LauncherPanel extends BasePanel {
+    async onMount() {
+        // 调用父类初始化（自动加载数据源）
+        await super.onMount();
+
+        // 渲染 UI
+        this.render();
+
+        // 绑定事件
+        this.bindEvents();
+    }
+
+    // 响应数据变化（自动调用）
+    onDataSourceChange(sourceId, state) {
+        if (sourceId === 'modules_list') {
+            this.renderModuleList();
+        } else if (sourceId === 'module_stats') {
+            this.renderStats();
+        }
+    }
+
+    render() {
+        this.container.innerHTML = `
+            <div class="launcher-panel">
+                <div class="panel-header">
+                    <h2>模块管理</h2>
+                    <div class="actions">
+                        <input type="text" id="module-filter" placeholder="搜索模块...">
+                        <button id="btn-refresh">刷新</button>
+                    </div>
+                </div>
+
+                <div class="statistics" id="module-stats"></div>
+
+                <table class="module-table">
+                    <thead>
+                        <tr>
+                            <th>模块名</th>
+                            <th>类型</th>
+                            <th>状态</th>
+                            <th>运行状态</th>
+                            <th>操作</th>
+                        </tr>
+                    </thead>
+                    <tbody id="modules-tbody"></tbody>
+                </table>
+            </div>
+        `;
+
+        // 初始渲染
+        this.renderModuleList();
+        this.renderStats();
+    }
+
+    renderModuleList() {
+        const tbody = this.container.querySelector('#modules-tbody');
+
+        // 获取数据（自动管理）
+        const modules = this.getData('modules_list')?.modules || [];
+        const loading = this.isLoading('modules_list');
+
+        if (loading) {
+            tbody.innerHTML = '<tr><td colspan="5">加载中...</td></tr>';
+            return;
+        }
+
+        if (modules.length === 0) {
+            tbody.innerHTML = '<tr><td colspan="5">暂无模块</td></tr>';
+            return;
+        }
+
+        tbody.innerHTML = modules.map(mod => {
+            const running = mod.actual_state?.startsWith('running');
+
+            return `
+                <tr>
+                    <td>${mod.name}</td>
+                    <td>${mod.type}</td>
+                    <td>${mod.state}</td>
+                    <td>${running ? '运行中' : '已停止'}</td>
+                    <td>
+                        ${this.renderActionButton(mod, running)}
+                    </td>
+                </tr>
+            `;
+        }).join('');
+    }
+
+    renderActionButton(mod, running) {
+        if (mod.state === 'disabled' || ['kernel', 'launcher'].includes(mod.name)) {
+            return '-';
+        }
+
+        if (running) {
+            return `<button class="btn-danger" data-action="stop" data-module="${mod.name}">停止</button>`;
+        } else {
+            return `<button class="btn-success" data-action="start" data-module="${mod.name}">启动</button>`;
+        }
+    }
+
+    renderStats() {
+        const stats = this.getData('module_stats');
+        if (!stats) return;
+
+        const statsEl = this.container.querySelector('#module-stats');
+        statsEl.innerHTML = `
+            <div class="stat-item">
+                <span>总数</span>
+                <span>${stats.total}</span>
+            </div>
+            <div class="stat-item">
+                <span>运行中</span>
+                <span>${stats.running}</span>
+            </div>
+            <div class="stat-item">
+                <span>已停止</span>
+                <span>${stats.stopped}</span>
+            </div>
+        `;
+    }
+
+    bindEvents() {
+        // 刷新按钮
+        this.container.querySelector('#btn-refresh').addEventListener('click', () => {
+            this.refreshDataSource('modules_list');
+            this.refreshDataSource('module_stats');
+        });
+
+        // 模块操作（事件委托）
+        this.container.querySelector('#modules-tbody').addEventListener('click', async (e) => {
+            const btn = e.target.closest('[data-action]');
+            if (!btn) return;
+
+            const action = btn.dataset.action;
+            const moduleName = btn.dataset.module;
+
+            btn.disabled = true;
+            btn.textContent = '操作中...';
+
+            try {
+                if (action === 'start') {
+                    await this.executeAction('start_module', { name: moduleName });
+                    // 等待 module.started 事件自动刷新
+                } else if (action === 'stop') {
+                    await this.executeAction('stop_module', {
+                        name: moduleName,
+                        reason: 'user_request'
+                    });
+                    // 等待 module.stopped 事件自动刷新
+                }
+            } catch (error) {
+                // 错误已在 executeAction 中处理
+                btn.disabled = false;
+                this.renderModuleList();  // 恢复按钮状态
+            }
+        });
+    }
+}
+```
+
+---
+
+## 八、通用渲染器
+
+### 8.1 通用表格渲染器
+
+```javascript
+// evol/static/panels/generic-table.js
+import { BasePanel } from '../js/base-panel.js';
+
+export default class GenericTablePanel extends BasePanel {
+    async onMount() {
+        await super.onMount();  // 自动加载数据源
+        this.render();
+        this.bindEvents();
+    }
+
+    onDataSourceChange(sourceId, state) {
+        this.renderTable();
+    }
+
+    render() {
+        const { title, ui_hints } = this.config;
+        const columns = ui_hints?.columns || [];
+
+        this.container.innerHTML = `
+            <div class="generic-table-panel">
+                <div class="panel-header">
+                    <h2>${title}</h2>
+                    <button id="btn-refresh">刷新</button>
+                </div>
+
+                <table class="data-table">
+                    <thead>
+                        <tr>
+                            ${columns.map(col => `
+                                <th style="width: ${col.width || 'auto'}">
+                                    ${col.label}
+                                </th>
+                            `).join('')}
+                            <th>操作</th>
+                        </tr>
+                    </thead>
+                    <tbody id="table-body"></tbody>
+                </table>
+            </div>
+        `;
+
+        this.renderTable();
+    }
+
+    renderTable() {
+        const tbody = this.container.querySelector('#table-body');
+        const { ui_hints, data_sources } = this.config;
+        const columns = ui_hints?.columns || [];
+        const rowActions = ui_hints?.row_actions || [];
+
+        // 获取第一个数据源的数据
+        const dataSource = data_sources[0];
+        const data = this.getData(dataSource.id);
+
+        if (!data) {
+            tbody.innerHTML = '<tr><td colspan="100">加载中...</td></tr>';
+            return;
+        }
+
+        // 假设数据格式是 { items: [...] } 或 [...]
+        const items = Array.isArray(data) ? data : (data.items || data.list || []);
+
+        if (items.length === 0) {
+            tbody.innerHTML = '<tr><td colspan="100">暂无数据</td></tr>';
+            return;
+        }
+
+        tbody.innerHTML = items.map(item => `
+            <tr>
+                ${columns.map(col => `
+                    <td>${item[col.field] || '-'}</td>
+                `).join('')}
+                <td>
+                    ${rowActions.map(action => `
+                        <button
+                            class="btn-${action.style || 'primary'}"
+                            data-action="${action.action_id}"
+                            data-item='${JSON.stringify(item)}'>
+                            ${action.label}
+                        </button>
+                    `).join('')}
+                </td>
+            </tr>
+        `).join('');
+    }
+
+    bindEvents() {
+        // 刷新按钮
+        this.container.querySelector('#btn-refresh').addEventListener('click', () => {
+            const dataSource = this.config.data_sources[0];
+            this.refreshDataSource(dataSource.id);
+        });
+
+        // 行操作（事件委托）
+        this.container.querySelector('#table-body').addEventListener('click', async (e) => {
+            const btn = e.target.closest('[data-action]');
+            if (!btn) return;
+
+            const actionId = btn.dataset.action;
+            const item = JSON.parse(btn.dataset.item);
+
+            const action = this.config.ui_hints.row_actions.find(a => a.action_id === actionId);
+
+            // 确认对话框
+            if (action.confirm && !confirm(action.confirm)) {
+                return;
+            }
+
+            btn.disabled = true;
+            btn.textContent = '处理中...';
+
+            try {
+                // 执行操作（从 item 中提取参数）
+                await this.executeAction(actionId, item);
+
+                // 等待事件自动刷新
+
+            } catch (error) {
+                btn.disabled = false;
+                btn.textContent = action.label;
+            }
+        });
+    }
+}
+```
+
+---
+
+## 九、模块侧实现
+
+### 9.1 模块配置文件
+
+```yaml
+# launcher/config.yaml
+console_panel:
+  enabled: true  # 是否启用控制台面板
+```
+
+### 9.2 模块元数据
+
+```markdown
+<!-- launcher/module.md -->
+---
+name: launcher
+type: core
+has_console_panel: true  # 模块提供控制台面板
+---
+
+# Launcher
+
+Kite 启动器模块。
+```
+
+### 9.3 模块注册实现
+
+```python
+# launcher/entry.py
+import asyncio
+import json
+from core.kernel_client import KernelClient
+
+class LauncherModule:
+    def __init__(self, token, kernel_port):
+        self.kernel = KernelClient(token, kernel_port)
+        self.config = self.load_config()
+        self.metadata = self.load_metadata()
+        self.rpc_handlers = {
+            'list_modules': self.handle_list_modules,
+            'start_module': self.handle_start_module,
+            'stop_module': self.handle_stop_module,
+            'get_stats': self.handle_get_stats,
+        }
+
+    def load_config(self):
+        """加载配置文件"""
+        with open('config.yaml', 'r') as f:
+            return yaml.safe_load(f)
+
+    def load_metadata(self):
+        """加载模块元数据"""
+        with open('module.md', 'r') as f:
+            content = f.read()
+            # 解析 frontmatter
+            return parse_frontmatter(content)
+
+    def should_register_panel(self):
+        """判断是否应该注册控制台面板"""
+        # 1. 检查模块是否提供面板
+        if not self.metadata.get('has_console_panel', False):
+            return False
+
+        # 2. 检查配置是否启用
+        if not self.config.get('console_panel', {}).get('enabled', False):
+            return False
+
+        return True
+
+    async def start(self):
+        # 连接 Kernel
+        await self.kernel.connect()
+
+        # 构建注册 payload
+        payload = {
+            'module_id': 'launcher',
+            'rpc_methods': {
+                'list_modules': {
+                    'description': '列出所有模块',
+                    'params': {},
+                    'returns': {'modules': 'array'}
+                },
+                'start_module': {
+                    'description': '启动模块',
+                    'params': {'name': 'string'},
+                    'returns': {'success': 'boolean'}
+                },
+                'stop_module': {
+                    'description': '停止模块',
+                    'params': {'name': 'string', 'reason': 'string'},
+                    'returns': {'success': 'boolean'}
+                },
+                'get_stats': {
+                    'description': '获取统计信息',
+                    'params': {},
+                    'returns': {
+                        'total': 'number',
+                        'running': 'number',
+                        'stopped': 'number'
+                    }
+                }
+            }
+        }
+
+        # 如果应该注册面板，添加 console_panel 配置
+        if self.should_register_panel():
+            payload['metadata'] = {
+                'console_panel': {
+                    'enabled': True,
+                    'panel_id': 'launcher',
+                    'title': '模块管理',
+                    'icon': 'grid',
+                    'order': 1,
+                    'category': 'system',
+                    'data_sources': [
+                        {
+                            'id': 'modules_list',
+                            'rpc_method': 'launcher.list_modules',
+                            'params': {},
+                            'refresh': {
+                                'strategy': 'event',
+                                'events': [
+                                    'module.started',
+                                    'module.stopped',
+                                    'module.crashed'
+                                ]
+                            }
+                        },
+                        {
+                            'id': 'module_stats',
+                            'rpc_method': 'launcher.get_stats',
+                            'params': {},
+                            'refresh': {
+                                'strategy': 'polling',
+                                'interval': 5000
+                            }
+                        }
+                    ],
+                    'actions': [
+                        {
+                            'id': 'start_module',
+                            'rpc_method': 'launcher.start_module',
+                            'params_schema': {'name': 'string'}
+                        },
+                        {
+                            'id': 'stop_module',
+                            'rpc_method': 'launcher.stop_module',
+                            'params_schema': {
+                                'name': 'string',
+                                'reason': 'string'
+                            }
+                        }
+                    ]
+                }
+            }
+
+        # 注册到 Registry
+        await self.kernel.rpc('registry.register', payload)
+
+        # 注册 RPC 处理器
+        self.kernel.register_rpc_handler(self.handle_rpc)
+
+        # 发送 module.ready
+        await self.kernel.publish_event('module.ready', {
+            'module_id': 'launcher'
+        })
+
+        # 运行主循环
+        await self.run()
+
+    async def handle_rpc(self, method, params, context):
+        """处理 RPC 调用"""
+        # 权限检查
+        if method == 'stop_module':
+            module_name = params.get('name')
+
+            # 核心模块不允许停止
+            if module_name in ['kernel', 'launcher']:
+                raise PermissionError("Cannot stop core modules")
+
+            # 只有管理员可以停止模块
+            caller_role = context.get('caller_role')
+            if caller_role != 'admin':
+                raise PermissionError("Only admin can stop modules")
+
+        # 执行操作
+        handler = self.rpc_handlers.get(method)
+        if not handler:
+            raise ValueError(f"Unknown RPC method: {method}")
+
+        return await handler(params)
+
+    async def handle_list_modules(self, params):
+        """列出所有模块"""
+        modules = self.get_all_modules()
+        return {'modules': modules}
+
+    async def handle_start_module(self, params):
+        """启动模块"""
+        name = params['name']
+        await self.start_module_process(name)
+        return {'success': True}
+
+    async def handle_stop_module(self, params):
+        """停止模块"""
+        name = params['name']
+        reason = params.get('reason', 'user_request')
+        await self.stop_module_process(name, reason)
+        return {'success': True}
+
+    async def handle_get_stats(self, params):
+        """获取统计信息"""
+        modules = self.get_all_modules()
+        running = sum(1 for m in modules if m['actual_state'].startswith('running'))
+        return {
+            'total': len(modules),
+            'running': running,
+            'stopped': len(modules) - running
+        }
+```
+
+---
+
+## 十、职责划分
+
+### 10.1 职责边界
+
+| 层级 | 职责 | 不负责 |
+|------|------|--------|
+| **模块** | - 数据主权<br>- 权限控制<br>- 业务逻辑<br>- 决定暴露什么<br>- RPC 实现 | - UI 渲染<br>- 前端交互<br>- 样式设计 |
+| **注册中心** | - 服务发现<br>- 配置存储<br>- 查询接口 | - 权限判断<br>- 数据处理<br>- 业务逻辑 |
+| **Kernel** | - RPC 路由<br>- 事件分发<br>- 上下文传递 | - 业务逻辑<br>- 权限判断<br>- 数据存储 |
+| **前端** | - UI 渲染<br>- 用户交互<br>- 加载状态显示<br>- 错误提示 | - 权限判断<br>- 业务逻辑<br>- 数据过滤 |
+
+### 10.2 数据流向
+
+```
+模块决定暴露 → 注册到 Registry → 前端查询发现 → 前端渲染 UI
+     ↓                                              ↓
+模块提供 RPC ←────── Kernel 路由 ←────── 前端调用 RPC
+     ↓                                              ↓
+模块检查权限 ────────────────────────→ 返回结果/错误
+     ↓                                              ↓
+模块发送事件 ────────────────────────→ 前端自动刷新
+```
+
+---
+
+## 十一、开发流程
+
+### 11.1 模块开发者（后端）
+
+#### 步骤 1：配置模块元数据
+
+```markdown
+<!-- module.md -->
+---
+name: my_module
+type: service
+has_console_panel: true  # 声明提供控制台面板
+---
+
+# My Module
+
+模块说明。
+```
+
+#### 步骤 2：配置面板启用状态
+
+```yaml
+# config.yaml
+console_panel:
+  enabled: true  # 启用控制台面板
+```
+
+#### 步骤 3：实现 RPC 处理器
+
+```python
+# entry.py
+class MyModule:
+    def __init__(self):
+        self.rpc_handlers = {
+            'get_data': self.handle_get_data,
+            'update_config': self.handle_update_config,
+        }
+
+    async def handle_get_data(self, params):
+        """获取数据"""
+        data = self.load_data()
+        return {'items': data}
+
+    async def handle_update_config(self, params):
+        """更新配置"""
+        config_key = params['key']
+        config_value = params['value']
+
+        # 权限检查
+        if not self.check_permission(context, 'update_config'):
+            raise PermissionError("No permission")
+
+        self.update_config(config_key, config_value)
+        return {'success': True}
+```
+
+#### 步骤 4：注册到 Registry
+
+```python
+async def start(self):
+    # 判断是否应该注册面板
+    if self.should_register_panel():
+        payload = {
+            'module_id': 'my_module',
+            'metadata': {
+                'console_panel': {
+                    'enabled': True,
+                    'panel_id': 'my_module',
+                    'title': '我的模块',
+                    'icon': 'star',
+                    'order': 20,
+                    'category': 'service',
+                    'data_sources': [
+                        {
+                            'id': 'items_list',
+                            'rpc_method': 'my_module.get_data',
+                            'params': {},
+                            'refresh': {
+                                'strategy': 'event',
+                                'events': ['my_module.data_changed']
+                            }
+                        }
+                    ],
+                    'actions': [
+                        {
+                            'id': 'update_config',
+                            'rpc_method': 'my_module.update_config',
+                            'params_schema': {
+                                'key': 'string',
+                                'value': 'string'
+                            }
+                        }
+                    ],
+                    # 可选：提供 UI 提示（使用通用渲染器）
+                    'ui_hints': {
+                        'type': 'table',
+                        'columns': [
+                            {'field': 'id', 'label': 'ID', 'width': '100px'},
+                            {'field': 'name', 'label': '名称', 'width': '200px'}
+                        ],
+                        'row_actions': [
+                            {
+                                'action_id': 'update_config',
+                                'label': '编辑',
+                                'style': 'primary'
+                            }
+                        ]
+                    }
+                }
+            },
+            'rpc_methods': {
+                'get_data': {
+                    'description': '获取数据',
+                    'params': {},
+                    'returns': {'items': 'array'}
+                },
+                'update_config': {
+                    'description': '更新配置',
+                    'params': {'key': 'string', 'value': 'string'},
+                    'returns': {'success': 'boolean'}
+                }
+            }
+        }
+
+        await self.kernel.rpc('registry.register', payload)
+```
+
+#### 步骤 5：完成
+
+- 如果提供了 `ui_hints`，前端会使用通用渲染器自动渲染
+- 如果需要自定义 UI，通知前端开发者创建 `panels/my_module.js`
+
+---
+
+### 11.2 前端开发者
+
+#### 选择 1：使用通用渲染器（无需开发）
+
+如果模块提供了 `ui_hints`，前端会自动使用通用渲染器，无需任何开发工作。
+
+#### 选择 2：开发自定义面板
+
+如果需要完全自定义的 UI，创建面板 JS 文件：
+
+```javascript
+// evol/static/panels/my_module.js
+import { BasePanel } from '../js/base-panel.js';
+
+export default class MyModulePanel extends BasePanel {
+    async onMount() {
+        await super.onMount();  // 自动加载数据源
+        this.render();
+        this.bindEvents();
+    }
+
+    onDataSourceChange(sourceId, state) {
+        if (sourceId === 'items_list') {
+            this.renderItems();
+        }
+    }
+
+    render() {
+        this.container.innerHTML = `
+            <div class="my-module-panel">
+                <h2>我的模块</h2>
+                <div id="items-container"></div>
+            </div>
+        `;
+
+        this.renderItems();
+    }
+
+    renderItems() {
+        const items = this.getData('items_list')?.items || [];
+        const container = this.container.querySelector('#items-container');
+
+        container.innerHTML = items.map(item => `
+            <div class="item">
+                <span>${item.name}</span>
+                <button data-action="update" data-id="${item.id}">
+                    编辑
+                </button>
+            </div>
+        `).join('');
+    }
+
+    bindEvents() {
+        this.container.addEventListener('click', async (e) => {
+            const btn = e.target.closest('[data-action="update"]');
+            if (!btn) return;
+
+            const id = btn.dataset.id;
+            const newValue = prompt('输入新值');
+
+            if (newValue) {
+                await this.executeAction('update_config', {
+                    key: id,
+                    value: newValue
+                });
+            }
+        });
+    }
+}
+```
+
+---
+
+## 十二、最佳实践
+
+### 12.1 模块侧
+
+#### ✅ 推荐做法
+
+```python
+# 1. 明确声明面板配置
+has_console_panel: true  # 在 module.md 中声明
+
+# 2. 提供清晰的 RPC 方法
+async def handle_get_data(self, params):
+    """获取数据 - 清晰的文档注释"""
+    return {'items': [...]}
+
+# 3. 严格的权限检查
+async def handle_delete_item(self, params, context):
+    if not self.check_permission(context, 'delete'):
+        raise PermissionError("No permission to delete")
+    # ...
+
+# 4. 合理的刷新策略
+'refresh': {
+    'strategy': 'event',  # 优先使用事件驱动
+    'events': ['my_module.data_changed']
+}
+
+# 5. 提供 UI 提示（可选）
+'ui_hints': {
+    'type': 'table',
+    'columns': [...]
+}
+```
+
+#### ❌ 避免做法
+
+```python
+# 1. 不要在模块中处理前端逻辑
+# 错误示例：
+def get_html_for_item(item):
+    return f"<div>{item.name}</div>"  # ❌
+
+# 2. 不要在 RPC 中返回 HTML
+# 错误示例：
+return {'html': '<table>...</table>'}  # ❌
+
+# 3. 不要在模块中做前端权限判断
+# 错误示例：
+if user_role == 'viewer':
+    return {'items': []}  # ❌ 应该返回完整数据，让前端决定显示
+
+# 4. 不要过度轮询
+# 错误示例：
+'refresh': {
+    'strategy': 'polling',
+    'interval': 100  # ❌ 太频繁
+}
+```
+
+---
+
+### 12.2 前端侧
+
+#### ✅ 推荐做法
+
+```javascript
+// 1. 继承 BasePanel
+export default class MyPanel extends BasePanel {
+    // ...
+}
+
+// 2. 使用 BasePanel 提供的方法
+const data = this.getData('items_list');  // ✅
+await this.executeAction('delete_item', {id: 1});  // ✅
+
+// 3. 响应数据变化
+onDataSourceChange(sourceId, state) {
+    this.renderItems();  // ✅
+}
+
+// 4. 显示加载状态
+if (this.isLoading('items_list')) {
+    // 显示加载动画
+}
+
+// 5. 处理错误
+try {
+    await this.executeAction('delete_item', {id: 1});
+} catch (error) {
+    this.showError(error.message);  // ✅
+}
+```
+
+#### ❌ 避免做法
+
+```javascript
+// 1. 不要做权限判断
+// 错误示例：
+if (moduleName === 'kernel') {
+    alert('不能操作核心模块');  // ❌
+    return;
+}
+// 正确做法：直接调用，让模块检查权限
+
+// 2. 不要做业务逻辑判断
+// 错误示例：
+const filteredItems = items.filter(item => item.status !== 'deleted');  // ❌
+// 正确做法：渲染模块返回的所有数据
+
+// 3. 不要手动管理数据缓存
+// 错误示例：
+localStorage.setItem('items', JSON.stringify(items));  // ❌
+// 正确做法：让 BasePanel 自动管理
+
+// 4. 不要绕过 BasePanel 的方法
+// 错误示例：
+fetch('/api/my_module/get_data').then(...);  // ❌
+// 正确做法：使用 this.rpc('my_module.get_data', {})
+```
+
+---
+
+## 十三、常见问题
+
+### Q1：模块如何动态启用/禁用面板？
+
+**A**：修改 `config.yaml` 中的 `console_panel.enabled`，然后重新注册到 Registry。
+
+```python
+# 动态禁用面板
+self.config['console_panel']['enabled'] = False
+await self.kernel.rpc('registry.register', payload)
+```
+
+---
+
+### Q2：如何实现不同用户看到不同的面板？
+
+**A**：在注册时根据用户上下文决定是否注册面板。
+
+```python
+async def register_to_registry(self, user_context):
+    # 只有管理员才能看到管理面板
+    if user_context.get('role') != 'admin':
+        return  # 不注册面板
+
+    # 注册面板
+    await self.kernel.rpc('registry.register', payload)
+```
+
+---
+
+### Q3：如何实现面板的权限控制？
+
+**A**：权限控制在模块侧的 RPC 处理器中实现。
+
+```python
+async def handle_delete_item(self, params, context):
+    # 检查权限
+    caller_role = context.get('caller_role')
+    if caller_role != 'admin':
+        raise PermissionError("Only admin can delete items")
+
+    # 执行操作
+    self.delete_item(params['id'])
+    return {'success': True}
+```
+
+前端会收到错误并显示给用户。
+
+---
+
+### Q4：如何实现复杂的自定义 UI？
+
+**A**：创建自定义面板 JS 文件，完全控制 UI 渲染。
+
+```javascript
+// evol/static/panels/my_module.js
+export default class MyModulePanel extends BasePanel {
+    render() {
+        // 完全自定义的 HTML
+        this.container.innerHTML = `
+            <div class="custom-layout">
+                <!-- 任意复杂的 UI -->
+            </div>
+        `;
+    }
+}
+```
+
+---
+
+### Q5：如何调试面板加载问题？
+
+**A**：打开浏览器开发者工具，查看 Console 和 Network 面板。
+
+```javascript
+// 常见错误：
+// 1. 找不到面板 JS 文件
+// → 检查 panel_id 是否正确
+// → 检查 panels/xxx.js 文件是否存在
+
+// 2. RPC 调用失败
+// → 检查 rpc_method 是否正确
+// → 检查模块是否已注册该 RPC
+
+// 3. 数据不刷新
+// → 检查 refresh.strategy 配置
+// → 检查事件是否正确订阅
+```
+
+---
+
+## 十四、总结
+
+### 14.1 核心原则
+
+1. **数据主权在模块**：模块决定暴露什么数据和操作
+2. **权限控制在模块**：模块检查每个 RPC 调用的权限
+3. **前端只负责渲染**：根据配置加载数据并渲染 UI
+4. **注册中心是发现机制**：前端通过注册中心发现可用面板
+
+### 14.2 架构优势
+
+- ✅ **解耦**：模块和前端完全解耦，通过 RPC 通信
+- ✅ **灵活**：支持自定义面板和通用渲染器
+- ✅ **安全**：权限控制在模块侧，前端无法绕过
+- ✅ **可扩展**：新增模块自动接入控制台
+- ✅ **易维护**：职责清晰，前后端分离
+
+### 14.3 开发效率
+
+- **模块开发者**：只需实现 RPC + 声明配置，无需关心前端
+- **前端开发者**：可选择通用渲染器（零开发）或自定义面板（完全控制）
+- **用户**：通过配置文件动态控制面板启用/禁用
+
+---
+
+## 附录
+
+### A. 完整示例项目结构
+
+```
+Kite/
+├── extensions/
+│   └── services/
+│       ├── launcher/
+│       │   ├── module.md              # has_console_panel: true
+│       │   ├── config.yaml            # console_panel.enabled: true
+│       │   └── entry.py               # 注册面板 + RPC 实现
+│       ├── watchdog/
+│       │   ├── module.md
+│       │   ├── config.yaml
+│       │   └── entry.py
+│       └── evol/
+│           ├── static/
+│           │   ├── index.html
+│           │   ├── js/
+│           │   │   ├── evol-app.js
+│           │   │   ├── kernel-client.js
+│           │   │   ├── base-panel.js
+│           │   │   └── panel-loader.js
+│           │   └── panels/
+│           │       ├── launcher.js    # 自定义面板
+│           │       ├── watchdog.js    # 自定义面板
+│           │       └── generic-table.js  # 通用渲染器
+│           └── server.py
+└── docs/
+    └── Evol控制台插件化架构设计.md  # 本文档
+```
+
+### B. 参考文档
+
+- [Kite 框架设计](Kite框架设计/)
+- [注册中心设计](注册中心设计.md)
+- [事件中心设计](事件中心设计.md)
+- [模块开发指南](模块开发指南.md)
+