@agentunion/kite 1.4.0 → 1.6.0

package/docs//346/236/266/346/236/204/347/216/260/347/212/266/344/270/216/347/273/210/346/236/201/347/233/256/346/240/207/345/257/271/346/257/224/345/210/206/346/236/220.md

@@ -0,0 +1,508 @@
+# Kite 控制台架构现状与终极目标对比分析
+
+## 一、当前目录结构
+
+```
+extensions/services/evol/
+├── 核心模块文件
+│   ├── entry.py                    # 模块入口
+│   ├── server.py                   # FastAPI 服务器
+│   ├── config.yaml                 # 模块配置
+│   ├── module.md                   # 模块文档
+│   │
+│   ├── relay.py                    # 虚拟模块中转服务 ✅
+│   ├── relay_config.json5          # Relay 配置 ✅
+│   ├── pairing.py                  # 配对管理器 ✅
+│   ├── pairing_codes.jsonl         # 配对码存储
+│   │
+│   ├── auth_manager.py             # Kite Token 管理 ✅
+│   ├── evol_api.py                 # Evol 业务 API
+│   ├── evol_config.json5           # Evol 业务配置
+│   ├── stats_manager.py            # 统计管理器
+│   ├── config_loader.py            # 配置加载器
+│   └── migrate_tokens.py           # Token 迁移工具
+│
+├── routes/                         # HTTP 路由
+│   ├── __init__.py
+│   ├── routes_rpc.py               # RPC 路由（HTTP）
+│   └── routes_test.py              # 测试路由
+│
+└── static/                         # 静态文件
+    ├── index.html                  # 主页面 ✅
+    ├── pairing.html                # 配对页面 ✅
+    ├── index_evol.html             # Evol 旧页面（待删除）
+    ├── test_*.html                 # 测试页面
+    │
+    ├── css/                        # 样式文件
+    │
+    └── js/                         # JavaScript 文件
+        ├── kernel-client.js        # KernelClient 类 ✅
+        ├── evol-app.js             # 主应用逻辑 ✅
+        ├── registry-tests.js       # 注册中心测试 ✅
+        ├── dialog.js               # 对话框组件
+        │
+        ├── app.js                  # 旧文件（待清理）
+        ├── auth.js                 # 旧文件（待清理）
+        ├── main.js                 # 旧文件（待清理）
+        ├── stats.js                # 旧文件（待清理）
+        ├── token-manager.js        # 旧文件（待清理）
+        └── evol-app-fixed.js       # 备份文件（待删除）
+```
+
+## 二、当前架构分析
+
+### 2.1 核心组件
+
+#### ✅ 已实现的核心功能
+
+1. **虚拟模块中转服务（Relay Service）**
+   - 文件：`relay.py`
+   - 功能：
+     - ✅ 配对码认证
+     - ✅ Kite Token 认证（新增）
+     - ✅ WebSocket 消息转发
+     - ✅ 会话管理
+     - ✅ 自动重连
+     - ✅ 权限控制
+
+2. **统一 WebSocket 连接**
+   - 端点：`/ws/relay`
+   - 协议：JSON-RPC 2.0
+   - 认证：配对码 或 Kite Token
+   - 功能：RPC 调用 + 事件订阅
+
+3. **前端统一客户端**
+   - 文件：`kernel-client.js` + `evol-app.js`
+   - 功能：
+     - ✅ 统一使用 KernelClient
+     - ✅ 自动选择 Token（kiteToken 优先）
+     - ✅ 事件订阅
+     - ✅ RPC 调用
+
+### 2.2 业务功能
+
+#### Evol 业务（混合在控制台中）
+
+1. **账户管理**
+   - 手机号登录
+   - 用户信息显示
+   - 积分统计
+
+2. **Token 管理**
+   - Kite Token 列表
+   - Evol Token 列表
+   - Token 吊销
+
+3. **配对管理**
+   - 配对码生成
+   - 配对码列表
+
+#### Kite 基础功能
+
+1. **模块管理**
+   - 模块列表
+   - 启动/停止/重启
+   - 模块配置查看/编辑
+
+2. **注册中心**
+   - RPC 方法查询
+   - 事件查询
+   - 注册中心测试
+
+3. **事件查看**
+   - 实时事件流
+   - 事件过滤
+
+## 三、与终极目标对比
+
+### 3.1 终极目标回顾
+
+**核心理念**：
+- Kite 控制台：业务无关的基础管理界面
+- Evol：作为业务插件接入控制台
+- 插件化架构：动态菜单、独立认证、独立路由
+
+**架构设计**：
+```
+Kite Console (核心控制台)
+├── 核心功能：模块管理、配置管理、事件查看、注册中心
+├── 插件系统：Plugin Manager
+└── 认证：配对码（基础认证）
+
+Evol Plugin (业务插件)
+├── 菜单项：账户管理、积分统计、Token 管理
+├── 认证扩展：手机号登录
+├── RPC 方法：evol.*
+└── 静态文件：/evol/static/*
+```
+
+### 3.2 一致的地方 ✅
+
+| 功能 | 终极目标 | 当前实现 | 状态 |
+|------|---------|---------|------|
+| **虚拟模块机制** | 浏览器作为标准 Kite 模块 | ✅ Relay Service | ✅ 完全一致 |
+| **统一 WebSocket** | 单一 /ws/relay 端点 | ✅ 已删除 /ws/management | ✅ 完全一致 |
+| **双认证支持** | 配对码 + 业务认证 | ✅ 配对码 + Kite Token | ✅ 完全一致 |
+| **JSON-RPC 2.0** | 标准 RPC 协议 | ✅ 已实现 | ✅ 完全一致 |
+| **事件订阅** | 显式订阅机制 | ✅ kernelClient.subscribe() | ✅ 完全一致 |
+| **权限控制** | 基于 role 的白名单 | ✅ relay_config.json5 | ✅ 完全一致 |
+
+### 3.3 不一致的地方 ⚠️
+
+| 方面 | 终极目标 | 当前实现 | 差距 |
+|------|---------|---------|------|
+| **模块命名** | `kite-console` | `evol` | ⚠️ 名称混淆 |
+| **业务分离** | Evol 作为插件 | Evol 混合在控制台中 | ⚠️ 未分离 |
+| **插件系统** | Plugin Manager | 无 | ⚠️ 未实现 |
+| **动态菜单** | 插件启用时出现 | 静态菜单 | ⚠️ 未实现 |
+| **独立路由** | /evol/static/* | /static/* | ⚠️ 未分离 |
+| **RPC 注册** | 插件注册 RPC | 直接在 routes_rpc.py | ⚠️ 未标准化 |
+
+### 3.4 可以优化的地方 🔧
+
+#### 优先级 1：紧急优化
+
+1. **清理冗余文件**
+   ```
+   待删除：
+   - static/js/app.js
+   - static/js/auth.js
+   - static/js/main.js
+   - static/js/stats.js
+   - static/js/token-manager.js
+   - static/js/evol-app-fixed.js
+   - static/index_evol.html
+   ```
+
+2. **HTTP RPC 迁移到 WebSocket**
+   - 当前：部分 RPC 仍通过 HTTP（如 `/api/get_user_info`）
+   - 目标：所有 RPC 通过 WebSocket
+   - 影响：统一通信协议，减少 HTTP 请求
+
+3. **权限配置完善**
+   - 当前：只有 admin 有 evol.* 权限
+   - 目标：为 operator 和 viewer 配置适当权限
+
+#### 优先级 2：架构优化
+
+4. **模块改名**
+   ```
+   evol → kite-console
+   ```
+   - 更新所有引用
+   - 更新配置文件
+   - 更新文档
+
+5. **业务代码分离**
+   ```
+   当前：
+   evol/
+   ├── auth_manager.py (Kite 基础)
+   ├── evol_api.py (Evol 业务)
+   ├── stats_manager.py (Evol 业务)
+   └── ...
+
+   目标：
+   kite-console/
+   ├── core/ (核心功能)
+   │   ├── auth_manager.py
+   │   ├── pairing.py
+   │   └── relay.py
+   └── plugins/
+       └── evol/
+           ├── plugin.py
+           ├── evol_api.py
+           └── stats_manager.py
+   ```
+
+6. **插件系统实现**
+   - Plugin Manager
+   - 插件接口定义
+   - 动态加载机制
+   - 菜单注册系统
+
+#### 优先级 3：长期优化
+
+7. **前端架构优化**
+   - 组件化（当前是单文件）
+   - 路由系统（当前是简单的页面切换）
+   - 状态管理（当前是分散的状态）
+
+8. **配置系统统一**
+   - 当前：多个配置文件（config.yaml, relay_config.json5, evol_config.json5）
+   - 目标：统一配置管理
+
+9. **测试覆盖**
+   - 单元测试
+   - 集成测试
+   - E2E 测试
+
+## 四、当前架构的优势
+
+### 4.1 已经做对的事情 ✅
+
+1. **虚拟模块机制成熟**
+   - Relay Service 功能完整
+   - 支持双认证
+   - 权限控制完善
+   - 会话管理稳定
+
+2. **前端统一客户端**
+   - 代码简洁（减少 391 行）
+   - 职责清晰
+   - 易于维护
+
+3. **通信协议标准化**
+   - JSON-RPC 2.0
+   - 事件订阅机制
+   - 自动重连
+
+4. **安全性提升**
+   - 所有连接需要认证
+   - 基于 role 的权限控制
+   - Token 管理完善
+
+### 4.2 为插件化打好的基础
+
+1. **认证扩展机制**
+   - 已支持多种认证方式（配对码、Kite Token）
+   - 易于添加新的认证提供者
+
+2. **RPC 路由机制**
+   - 已有 routes_rpc.py
+   - 易于注册新的 RPC 方法
+
+3. **静态文件服务**
+   - 已有静态文件路由
+   - 易于添加插件静态文件
+
+4. **权限控制框架**
+   - 已有基于 role 的权限系统
+   - 易于扩展到插件权限
+
+## 五、建议的实施路径
+
+### 阶段 1：清理与优化（1-2 天）
+
+**目标**：清理冗余代码，完善当前架构
+
+**任务**：
+1. ✅ 删除冗余 JS 文件
+2. ✅ 删除旧的 HTML 文件
+3. ✅ 完善权限配置（operator、viewer）
+4. ✅ 统一 RPC 调用（HTTP → WebSocket）
+5. ✅ 更新文档
+
+**产出**：
+- 更清晰的代码结构
+- 完全统一的通信协议
+- 完善的权限配置
+
+### 阶段 2：业务分离准备（2-3 天）
+
+**目标**：为插件化做准备，但不破坏现有功能
+
+**任务**：
+1. 设计插件接口（ConsolePlugin 基类）
+2. 设计 Plugin Manager
+3. 识别 Evol 业务代码
+4. 规划目录结构
+
+**产出**：
+- 插件接口文档
+- Plugin Manager 设计文档
+- 业务分离方案
+
+### 阶段 3：插件系统实现（3-5 天）
+
+**目标**：实现插件系统，保持向后兼容
+
+**任务**：
+1. 实现 Plugin Manager
+2. 实现插件加载机制
+3. 实现动态菜单系统
+4. 实现插件 RPC 注册
+
+**产出**：
+- 可工作的插件系统
+- 向后兼容的 Evol 集成
+
+### 阶段 4：Evol 插件化（2-3 天）
+
+**目标**：将 Evol 业务拆分为插件
+
+**任务**：
+1. 创建 Evol 插件目录
+2. 迁移 Evol 业务代码
+3. 实现 Evol 插件接口
+4. 测试插件启用/禁用
+
+**产出**：
+- Evol 作为独立插件
+- 可以启用/禁用 Evol 功能
+
+### 阶段 5：模块改名（1 天）
+
+**目标**：将 evol 模块改名为 kite-console
+
+**任务**：
+1. 重命名目录
+2. 更新所有引用
+3. 更新配置文件
+4. 更新文档
+
+**产出**：
+- 名称清晰的 kite-console 模块
+
+## 六、立即可以做的事情
+
+### 6.1 快速清理（30 分钟）
+
+```bash
+# 删除冗余文件
+cd extensions/services/evol/static/js
+rm app.js auth.js main.js stats.js token-manager.js evol-app-fixed.js
+
+cd ../
+rm index_evol.html
+```
+
+### 6.2 完善权限配置（15 分钟）
+
+修改 `relay_config.json5`：
+
+```json5
+permissions: {
+  admin: [
+    "event.*",
+    "registry.*",
+    "launcher.*",
+    "kernel.*",
+    "*.health",
+    "*.status",
+    "watchdog.*",
+    "backup.*",
+    "model_service.*",
+    "web.*",
+    "evol.*"
+  ],
+
+  operator: [
+    "event.*",
+    "launcher.list_modules",
+    "launcher.start_module",
+    "launcher.stop_module",
+    "launcher.restart_module",
+    "*.health",
+    "*.status",
+    "evol.list_kite_tokens",  // 只读
+    "evol.list_evol_tokens"   // 只读
+  ],
+
+  viewer: [
+    "event.*",
+    "launcher.list_modules",
+    "*.health",
+    "*.status",
+    "evol.list_kite_tokens"   // 只读
+  ]
+}
+```
+
+### 6.3 创建架构文档（30 分钟）
+
+创建 `docs/架构现状与规划.md`，记录：
+- 当前架构
+- 终极目标
+- 实施路径
+- 决策记录
+
+### 6.4 HTTP RPC 迁移计划（1 小时）
+
+识别所有 HTTP RPC 调用：
+
+```bash
+# 搜索 fetch('/api/
+grep -r "fetch('/api/" extensions/services/evol/static/js/
+```
+
+创建迁移清单：
+- `/api/get_user_info` → `evol.get_user_info`
+- `/api/get_credits_stats` → `evol.get_credits_stats`
+- `/api/logout` → `evol.logout`
+- 等等
+
+## 七、关键决策点
+
+### 7.1 是否立即开始插件化？
+
+**建议**：不，先完成阶段 1（清理与优化）
+
+**理由**：
+1. 当前架构已经很接近目标
+2. 插件化是大改动，需要充分测试
+3. 先清理冗余代码，让架构更清晰
+4. 先完善权限配置，确保安全性
+
+### 7.2 是否立即改名？
+
+**建议**：不，放在最后（阶段 5）
+
+**理由**：
+1. 改名影响范围大
+2. 先实现功能，再改名
+3. 避免在开发过程中频繁改名
+
+### 7.3 是否保留 HTTP RPC？
+
+**建议**：短期保留，长期迁移
+
+**理由**：
+1. 向后兼容
+2. 逐步迁移，降低风险
+3. 最终目标是全部使用 WebSocket
+
+## 八、总结
+
+### 当前状态评分
+
+| 方面 | 评分 | 说明 |
+|------|------|------|
+| **虚拟模块机制** | ⭐⭐⭐⭐⭐ | 完全符合终极目标 |
+| **统一通信** | ⭐⭐⭐⭐⭐ | 已删除 /ws/management |
+| **认证机制** | ⭐⭐⭐⭐⭐ | 双认证支持完善 |
+| **权限控制** | ⭐⭐⭐⭐ | 基本完善，需要细化 |
+| **代码清晰度** | ⭐⭐⭐ | 有冗余文件待清理 |
+| **业务分离** | ⭐⭐ | Evol 混合在控制台中 |
+| **插件系统** | ⭐ | 未实现 |
+| **整体进度** | **70%** | 核心机制完成，待插件化 |
+
+### 关键成就 🎉
+
+1. ✅ 统一 WebSocket 连接（删除 /ws/management）
+2. ✅ 双认证支持（配对码 + Kite Token）
+3. ✅ 前端代码简化（减少 391 行）
+4. ✅ 虚拟模块机制成熟
+5. ✅ 权限控制框架完善
+
+### 下一步建议 🚀
+
+**立即执行**（今天）：
+1. 删除冗余文件
+2. 完善权限配置
+3. 重启 Kite 验证
+
+**短期计划**（本周）：
+1. HTTP RPC 迁移到 WebSocket
+2. 创建架构文档
+3. 设计插件接口
+
+**中期计划**（下周）：
+1. 实现 Plugin Manager
+2. Evol 业务分离
+3. 模块改名
+
+**长期愿景**（下月）：
+1. 完整的插件系统
+2. 多个业务插件示例
+3. 插件市场（可选）