@agentunion/kite 1.5.0 → 1.6.0

package/docs/Web/346/250/241/345/235/227/344/270/216Evol/346/250/241/345/235/227/351/207/215/346/236/204/345/210/206/346/236/220.md

@@ -0,0 +1,521 @@
+# Web 模块与 Evol 模块重构分析
+
+## 1. Web 模块与文档一致性分析
+
+### 1.1 架构对比
+
+| 维度 | 文档设计 | Web 模块实际实现 | 一致性 |
+|------|---------|-----------------|--------|
+| **WebSocket 端点** | `/ws/relay` | `/ws/relay` + `/ws/management` | ⚠️ 部分一致 |
+| **配对流程** | 通过 `/ws/relay` WebSocket | 通过 `/ws/relay` WebSocket | ✅ 一致 |
+| **认证流程** | 通过 `/ws/relay` WebSocket | 通过 `/ws/relay` WebSocket | ✅ 一致 |
+| **RPC 调用** | 通过 `/ws/relay` WebSocket | HTTP `/api/rpc` + `/ws/relay` | ⚠️ 混合 |
+| **事件订阅** | 通过 `/ws/relay` WebSocket | `/ws/management` 推送 | ❌ 不一致 |
+| **前端客户端** | `KernelClient` 类 | `KernelClient` 类（已实现） | ✅ 一致 |
+| **平滑重连** | 6 秒超时 | 6 秒超时 | ✅ 一致 |
+| **优雅退出** | 中转服务代理 | 中转服务代理 | ✅ 一致 |
+
+### 1.2 详细分析
+
+#### ✅ 完全符合文档的部分
+
+1. **`/ws/relay` 中转服务**
+   - 文件：`relay.py`
+   - 功能：配对、认证、双向转发、权限控制、平滑重连、优雅退出
+   - 实现：完全符合文档设计
+
+2. **`KernelClient` 前端客户端**
+   - 文件：`static/js/kernel-client.js`
+   - 功能：配对、认证、RPC 调用、事件订阅、自动重连
+   - 实现：完全符合文档设计
+
+3. **配对界面**
+   - 文件：`static/pairing.html`
+   - 功能：请求配对码、输入配对码、配对
+   - 实现：完全符合文档设计
+
+#### ⚠️ 部分符合文档的部分
+
+1. **RPC 调用方式**
+   - 文档设计：通过 `/ws/relay` WebSocket
+   - 实际实现：
+     - `pairing.html` 使用 `KernelClient`（符合文档）
+     - `index.html` 使用 HTTP `/api/rpc`（不符合文档）
+   - 原因：历史遗留，`index.html` 是主管理界面，使用了更简单的 HTTP 方式
+
+2. **事件订阅方式**
+   - 文档设计：前端通过 `/ws/relay` 调用 `event.subscribe`
+   - 实际实现：Web 模块订阅事件，通过 `/ws/management` 推送给前端
+   - 原因：简化前端实现，避免每个前端都订阅相同的事件
+
+#### ❌ 不符合文档的部分
+
+1. **`/ws/management` 端点**
+   - 文件：`routes/routes_management_ws.py`
+   - 功能：推送模块状态变更事件
+   - 问题：文档中没有这个端点，前端应该通过 `/ws/relay` 订阅事件
+
+2. **HTTP RPC API**
+   - 文件：`routes/routes_rpc.py`
+   - 功能：转发 RPC 请求到 Kernel
+   - 问题：文档中 RPC 应该通过 `/ws/relay` WebSocket 调用
+
+### 1.3 Web 模块的使用场景
+
+#### 场景 A：配对界面（`pairing.html`）
+
+**完全符合文档设计**
+
+```javascript
+// 1. 请求配对码
+const ws = new WebSocket('/ws/relay');
+ws.send(JSON.stringify({ type: 'request_code' }));
+
+// 2. 配对
+const client = new KernelClient('/ws/relay');
+await client.pair(code);
+
+// 3. 跳转到主界面
+window.location.href = '/';
+```
+
+#### 场景 B：主管理界面（`index.html`）
+
+**混合架构（不完全符合文档）**
+
+```javascript
+// 1. RPC 调用 - 使用 HTTP（不符合文档）
+const response = await fetch('/api/rpc/launcher.list_modules', {
+    method: 'POST',
+    body: JSON.stringify({})
+});
+
+// 2. 事件接收 - 使用 /ws/management（不符合文档）
+const ws = new WebSocket('/ws/management');
+ws.onmessage = (event) => {
+    const msg = JSON.parse(event.data);
+    if (msg.type === 'module.started') {
+        // 处理事件
+    }
+};
+```
+
+### 1.4 为什么 Web 模块偏离了文档设计？
+
+#### 原因 1：开发阶段不同
+
+- **配对界面**（`pairing.html`）是后期开发的，严格遵循文档设计
+- **主管理界面**（`index.html`）是早期开发的，使用了更简单的 HTTP + WebSocket 推送
+
+#### 原因 2：简化前端实现
+
+- HTTP RPC 比 WebSocket RPC 更简单（无需管理请求 ID、超时等）
+- 事件推送不需要前端主动订阅，降低了前端复杂度
+
+#### 原因 3：性能考虑
+
+- HTTP RPC 可以利用浏览器的缓存、重试机制
+- 事件推送通过单一连接，减少了 Kernel 的连接数
+
+### 1.5 Web 模块的一致性评分
+
+| 评分项 | 得分 | 说明 |
+|--------|------|------|
+| 核心架构（`/ws/relay`） | 10/10 | 完全符合文档 |
+| 前端客户端（`KernelClient`） | 10/10 | 完全符合文档 |
+| 配对流程 | 10/10 | 完全符合文档 |
+| 主管理界面 | 5/10 | 混合架构，部分符合 |
+| **总体评分** | **8.5/10** | **大部分符合，主管理界面需要重构** |
+
+---
+
+## 2. Evol 模块重构分析
+
+### 2.1 当前架构
+
+Evol 模块完全复制了 Web 模块的混合架构：
+
+```
+前端 ← HTTP (/api/rpc) → Evol 模块 ← WebSocket → Kernel
+前端 ← WebSocket (/ws/management) → Evol 模块 ← WebSocket → Kernel
+前端 ← WebSocket (/ws/relay) → 中转服务 ← WebSocket → Kernel
+```
+
+### 2.2 目标架构（符合文档设计）
+
+```
+前端 ← WebSocket (/ws/relay) → 中转服务 ← WebSocket → Kernel
+```
+
+### 2.3 需要修改的文件清单
+
+#### 服务端文件（Python）
+
+| 文件 | 修改类型 | 说明 |
+|------|---------|------|
+| `server.py` | 🔧 修改 | 移除 HTTP RPC 路由，保留 `/ws/relay` |
+| `routes/routes_rpc.py` | ❌ 删除 | HTTP RPC 不再需要 |
+| `routes/routes_management_ws.py` | ❌ 删除 | 事件推送改为通过 `/ws/relay` |
+| `relay.py` | ✅ 保留 | 已符合文档设计 |
+| `pairing.py` | ✅ 保留 | 已符合文档设计 |
+
+#### 前端文件（JavaScript/HTML）
+
+| 文件 | 修改类型 | 说明 |
+|------|---------|------|
+| `static/index.html` | 🔧 大改 | 移除 HTTP RPC 和 `/ws/management`，使用 `KernelClient` |
+| `static/js/evol-app.js` | 🔧 大改 | 重构为使用 `KernelClient` |
+| `static/js/kernel-client.js` | ✅ 保留 | 已符合文档设计（从 Web 模块复制） |
+
+#### 配置文件
+
+| 文件 | 修改类型 | 说明 |
+|------|---------|------|
+| `businesses/relay_service.json5` | ✅ 保留 | 中转服务配置 |
+
+### 2.4 详细修改清单
+
+#### 修改 1：`server.py` - 移除 HTTP RPC 路由
+
+**当前代码：**
+```python
+# 引入 RPC 路由
+from routes.routes_rpc import router as rpc_router
+
+# 注册路由
+app.include_router(rpc_router)  # /api/rpc
+app.include_router(management_ws_router)  # /ws/management
+```
+
+**修改后：**
+```python
+# 移除 RPC 路由和 management_ws_router
+# 只保留 /ws/relay
+```
+
+**影响范围：**
+- 移除 `routes_rpc.py` 的引入
+- 移除 `routes_management_ws.py` 的引入
+- 移除对应的路由注册
+
+#### 修改 2：删除 `routes/routes_rpc.py`
+
+**原因：**
+- HTTP RPC 不再需要
+- 所有 RPC 调用通过 `/ws/relay` WebSocket
+
+**影响范围：**
+- 前端所有 `fetch('/api/rpc/...')` 调用需要改为 `client.call(...)`
+
+#### 修改 3：删除 `routes/routes_management_ws.py`
+
+**原因：**
+- 事件推送不再需要
+- 前端通过 `/ws/relay` 订阅事件
+
+**影响范围：**
+- 前端所有 `new WebSocket('/ws/management')` 需要改为使用 `KernelClient`
+
+#### 修改 4：`static/index.html` - 重构为使用 `KernelClient`
+
+**当前架构：**
+```html
+<script src="js/evol-app.js"></script>
+<script>
+    const app = new EvolApp();
+    app.init();
+</script>
+```
+
+**修改后：**
+```html
+<script src="js/kernel-client.js"></script>
+<script src="js/evol-app.js"></script>
+<script>
+    const app = new EvolApp();
+    app.init();
+</script>
+```
+
+**影响范围：**
+- 引入 `kernel-client.js`
+- `evol-app.js` 需要重构
+
+#### 修改 5：`static/js/evol-app.js` - 重构核心逻辑
+
+**当前架构：**
+```javascript
+class EvolApp {
+    constructor() {
+        this.ws = null;  // /ws/management
+    }
+
+    async callRpc(method, params) {
+        // HTTP RPC
+        const res = await fetch(`/api/rpc/${method}`, {
+            method: 'POST',
+            body: JSON.stringify(params)
+        });
+        return await res.json();
+    }
+
+    initKernelClient() {
+        // 连接 /ws/management
+        this.ws = new WebSocket('/ws/management');
+        this.ws.onmessage = (event) => {
+            // 处理事件推送
+        };
+    }
+}
+```
+
+**修改后：**
+```javascript
+class EvolApp {
+    constructor() {
+        this.client = null;  // KernelClient
+    }
+
+    async init() {
+        // 创建 KernelClient
+        const proto = location.protocol === 'https:' ? 'wss:' : 'ws:';
+        this.client = new KernelClient(`${proto}//${location.host}/ws/relay`);
+
+        // 连接（已有 token）或跳转到配对页面
+        try {
+            await this.client.connect();
+            console.log('[Evol] Connected as', this.client.moduleId);
+        } catch (err) {
+            console.error('[Evol] Connection failed:', err);
+            // 跳转到配对页面
+            window.location.href = '/pairing.html';
+            return;
+        }
+
+        // 订阅事件
+        await this.client.call('event.subscribe', {
+            events: [
+                'module.started',
+                'module.stopped',
+                'module.crashed',
+                'module.ready',
+                'module.exiting',
+                'module.shutdown',
+                'module.shutdown.ack',
+                'module.shutdown.ready',
+            ]
+        });
+
+        // 监听事件
+        this.client.on('module.started', (data) => {
+            console.log('[Evol] Module started:', data);
+            this.loadModules();
+        });
+
+        // 加载初始数据
+        this.loadUserInfo();
+        this.loadModules();
+    }
+
+    async callRpc(method, params) {
+        // WebSocket RPC
+        return await this.client.call(method, params);
+    }
+
+    async toggleConsole() {
+        if (this.consoleExpanded) {
+            // 收起控制台
+            this.consoleExpanded = false;
+            this.eventLogs = [];
+
+            // 恢复默认订阅
+            await this.client.call('event.subscribe', {
+                events: [
+                    'module.started',
+                    'module.stopped',
+                    'module.crashed',
+                    'module.ready',
+                    'module.exiting',
+                    'module.shutdown',
+                    'module.shutdown.ack',
+                    'module.shutdown.ready',
+                ]
+            });
+        } else {
+            // 展开控制台
+            this.consoleExpanded = true;
+
+            // 订阅全部事件
+            await this.client.call('event.subscribe', {
+                events: ['*']
+            });
+        }
+    }
+}
+```
+
+**影响范围：**
+- 所有 `this.callRpc()` 调用保持不变（内部实现改为 WebSocket）
+- 所有事件处理改为使用 `this.client.on()`
+- 移除 `initKernelClient()` 方法
+- 移除 `subscribeAllEvents()` 和 `subscribeDefaultEvents()` 方法（改为直接调用 `client.call()`）
+
+### 2.5 修改工作量估算
+
+| 修改项 | 工作量 | 风险 | 优先级 |
+|--------|--------|------|--------|
+| 删除 `routes_rpc.py` | 5 分钟 | 低 | P0 |
+| 删除 `routes_management_ws.py` | 5 分钟 | 低 | P0 |
+| 修改 `server.py` 路由注册 | 10 分钟 | 低 | P0 |
+| 复制 `kernel-client.js` | 5 分钟 | 低 | P0 |
+| 重构 `evol-app.js` 核心逻辑 | 2 小时 | 中 | P0 |
+| 修改 `index.html` 引入 | 5 分钟 | 低 | P0 |
+| 测试配对流程 | 30 分钟 | 中 | P1 |
+| 测试 RPC 调用 | 30 分钟 | 中 | P1 |
+| 测试事件订阅 | 30 分钟 | 中 | P1 |
+| 测试平滑重连 | 30 分钟 | 中 | P1 |
+| **总计** | **约 4.5 小时** | **中** | - |
+
+### 2.6 重构步骤
+
+#### 阶段 1：准备工作（30 分钟）
+
+1. **备份当前代码**
+   ```bash
+   cd extensions/services/evol
+   git add -A
+   git commit -m "备份：重构前的 evol 模块"
+   ```
+
+2. **复制 `kernel-client.js`**
+   ```bash
+   cp ../web/static/js/kernel-client.js static/js/
+   ```
+
+3. **创建配对页面**
+   ```bash
+   cp ../web/static/pairing.html static/
+   ```
+
+#### 阶段 2：服务端重构（30 分钟）
+
+1. **删除不需要的文件**
+   ```bash
+   rm routes/routes_rpc.py
+   rm routes/routes_management_ws.py
+   ```
+
+2. **修改 `server.py`**
+   - 移除 `routes_rpc` 和 `routes_management_ws` 的引入
+   - 移除对应的路由注册
+   - 保留 `/ws/relay` 端点
+
+3. **测试服务端启动**
+   ```bash
+   python main.py
+   ```
+
+#### 阶段 3：前端重构（2 小时）
+
+1. **重构 `evol-app.js`**
+   - 修改 `constructor()`，创建 `KernelClient`
+   - 修改 `init()`，连接 `/ws/relay`
+   - 修改 `callRpc()`，使用 `client.call()`
+   - 修改事件处理，使用 `client.on()`
+   - 修改 `toggleConsole()`，使用 `client.call('event.subscribe')`
+
+2. **修改 `index.html`**
+   - 引入 `kernel-client.js`
+   - 移除 `/ws/management` 相关代码
+
+3. **测试前端功能**
+   - 配对流程
+   - RPC 调用
+   - 事件订阅
+   - 平滑重连
+
+#### 阶段 4：测试与优化（1.5 小时）
+
+1. **功能测试**
+   - 配对流程
+   - 模块列表加载
+   - 模块启动/停止
+   - 事件日志展开/收起
+   - 筛选功能
+
+2. **性能测试**
+   - WebSocket 连接稳定性
+   - RPC 调用响应时间
+   - 事件推送延迟
+
+3. **兼容性测试**
+   - Chrome
+   - Firefox
+   - Edge
+
+### 2.7 风险评估
+
+| 风险 | 影响 | 概率 | 缓解措施 |
+|------|------|------|---------|
+| WebSocket 连接不稳定 | 高 | 低 | 实现自动重连（`KernelClient` 已实现） |
+| RPC 调用超时 | 中 | 低 | 设置合理的超时时间（30 秒） |
+| 事件订阅失败 | 中 | 低 | 捕获异常，显示错误提示 |
+| 前端代码复杂度增加 | 低 | 中 | 封装 `KernelClient`，简化调用 |
+| 用户需要重新配对 | 低 | 高 | 保留 `frontend_token`，无需重新配对 |
+
+### 2.8 回滚方案
+
+如果重构失败，可以快速回滚：
+
+```bash
+git reset --hard HEAD~1
+```
+
+### 2.9 重构收益
+
+| 收益 | 说明 |
+|------|------|
+| **架构清晰** | 完全符合文档设计，易于理解和维护 |
+| **功能完整** | 前端作为标准 Kite 模块，可以调用任何 RPC，订阅任何事件 |
+| **扩展性好** | 支持多前端、多角色、细粒度权限 |
+| **代码复用** | `KernelClient` 可以在多个项目中复用 |
+| **性能优化** | 单一 WebSocket 连接，减少连接数 |
+
+---
+
+## 3. 总结
+
+### 3.1 Web 模块一致性
+
+- **总体评分**：8.5/10
+- **符合文档的部分**：`/ws/relay`、`KernelClient`、配对流程
+- **不符合文档的部分**：主管理界面使用 HTTP RPC + `/ws/management`
+
+### 3.2 Evol 模块重构
+
+- **需要修改的文件**：5 个（2 个删除，3 个修改）
+- **工作量**：约 4.5 小时
+- **风险**：中等（有回滚方案）
+- **收益**：架构清晰、功能完整、扩展性好
+
+### 3.3 推荐方案
+
+**立即重构 Evol 模块**，理由：
+
+1. Evol 模块是新模块，用户较少，重构风险低
+2. 完全符合文档设计，为后续开发奠定基础
+3. 工作量可控（约 4.5 小时）
+4. 可以作为 Web 模块重构的参考
+
+**Web 模块暂不重构**，理由：
+
+1. Web 模块是核心模块，用户较多，重构风险高
+2. 当前架构虽然混合，但功能稳定
+3. 可以在 Evol 模块重构成功后，再考虑 Web 模块的重构
+
+### 3.4 下一步行动
+
+1. **确认重构方案**：是否同意重构 Evol 模块？
+2. **开始重构**：按照阶段 1-4 的步骤执行
+3. **测试验证**：确保所有功能正常
+4. **文档更新**：更新 Evol 模块的文档

package/docs/audit-api-guide.md

@@ -0,0 +1,68 @@
+# Audit 模块 API 使用说明
+
+端口：18770
+
+## API 端点
+
+**查询审计事件**
+```
+GET /api/audit/events?limit=10&actor_id=launcher&action=module.start
+```
+参数：`start_time` `end_time` `actor_type` `actor_id` `action` `resource_type` `resource_id` `result` `limit` `offset`
+
+**审计统计**
+```
+GET /api/audit/stats
+```
+
+**时间线视图**（Phase 2）
+```
+GET /api/audit/timeline?granularity=hour
+```
+
+**按操作者分组**（Phase 2）
+```
+GET /api/audit/actors
+```
+
+## 典型用例
+
+```bash
+# 查看最近的审计事件
+curl "http://127.0.0.1:18770/api/audit/events?limit=10"
+
+# 查看特定模块的操作
+curl "http://127.0.0.1:18770/api/audit/events?actor_id=launcher&limit=20"
+
+# 查看失败的操作
+curl "http://127.0.0.1:18770/api/audit/events?result=failure"
+
+# 审计统计
+curl http://127.0.0.1:18770/api/audit/stats
+```
+
+## 订阅事件
+
+订阅以下 Kernel 事件：
+- `module.started` — 模块启动
+- `module.stopped` — 模块停止
+- `module.crashed` — 模块崩溃
+- `module.registered` — 模块注册
+- `module.unregistered` — 模块注销
+- `module.offline` — 模块离线
+- `registry.updated` — 注册表更新
+
+## 存储结构
+
+```
+{KITE_INSTANCE_DIR}/audit/
+└── events/
+    └── 2026-03/
+        └── 2026-03-09.jsonl  # 每日审计日志
+```
+
+## 注意事项
+
+- 审计日志 append-only，不可修改
+- 按日期分文件存储
+- 完整性保护（Phase 2）