@agentunion/kite 1.4.0 → 1.6.0

package/docs/Kernel/344/270/273/345/212/250Ping/346/234/272/345/210/266/345/256/236/346/226/275/346/200/273/347/273/223.md

@@ -0,0 +1,204 @@
+# Kernel 主动 Ping 机制实施总结
+
+## 变更概述
+
+将 WebSocket ping/pong 机制从**客户端主动**改为**Kernel 主动**，使 Kernel 能够记录每个模块的响应延迟。
+
+## 实施内容
+
+### 1. 客户端移除 ping_interval 配置
+
+**修改的文件：**
+- `launcher/entry.py`
+- `extensions/services/watchdog/entry.py`
+- `extensions/services/backup/entry.py`
+- `extensions/services/model_service/entry.py`
+- `extensions/services/web/server.py`
+- `extensions/services/evol/server.py`
+
+**变更：**
+```python
+# 修改前
+websockets.connect(ws_url, open_timeout=5, ping_interval=20, ping_timeout=20, close_timeout=10)
+
+# 修改后
+websockets.connect(ws_url, open_timeout=5, ping_interval=None, close_timeout=10)
+```
+
+**效果：** 客户端不再主动发送 ping，只被动响应 Kernel 的 ping 请求。
+
+### 2. Kernel 端实现主动 ping
+
+**修改的文件：** `kernel/server.py`
+
+**新增字段：**
+```python
+# Ping/Pong tracking
+self._ping_times: dict[str, float] = {}  # module_id -> last ping sent time
+self._pong_latencies: dict[str, float] = {}  # module_id -> last pong latency (ms)
+self._ping_tasks: dict[str, asyncio.Task] = {}  # module_id -> ping task
+```
+
+**新增方法：**
+```python
+async def _ping_loop(self, module_id: str, ws: WebSocket):
+    """Send RPC ping every 20s and measure response latency."""
+    # 每 20 秒发送一次 kernel.ping RPC 请求
+    # 记录发送时间到 _ping_times
+```
+
+**连接建立时启动 ping 循环：**
+```python
+# Start ping loop for this connection
+ping_task = asyncio.create_task(server._ping_loop(module_id, ws))
+server._ping_tasks[module_id] = ping_task
+```
+
+**接收响应时记录延迟：**
+```python
+# 检测 kernel_ping_ 开头的响应 ID
+if isinstance(msg_id, str) and msg_id.startswith("kernel_ping_"):
+    latency_ms = (time.time() - server._ping_times[module_id]) * 1000
+    server._pong_latencies[module_id] = round(latency_ms, 2)
+```
+
+**连接断开时清理：**
+```python
+# Cancel ping task
+ping_task = server._ping_tasks.pop(module_id, None)
+if ping_task:
+    ping_task.cancel()
+```
+
+### 3. 添加 RPC 方法查询延迟
+
+**修改的文件：** `kernel/rpc_router.py`
+
+**新增 RPC 方法：**
+```python
+async def _kernel_latencies(self, caller_id: str, params: dict) -> dict:
+    """Get ping/pong latencies for all connected modules.
+
+    Returns:
+        {"latencies": {"module1": 12.34, "module2": 23.45, ...}}
+        Latency in milliseconds, or null if no data yet.
+    """
+    return {
+        "latencies": {
+            mid: self.kernel_server._pong_latencies.get(mid)
+            for mid in self.kernel_server.connections.keys()
+        }
+    }
+```
+
+**注册到方法表：**
+```python
+self.methods: dict[str, callable] = {
+    ...
+    "kernel.latencies": self._kernel_latencies,
+    ...
+}
+```
+
+### 4. 更新文档
+
+**修改的文件：** `kernel/module.md`
+
+**新增职责：**
+- Ping/Pong Monitoring: Active ping to all connected modules, track response latencies
+
+**新增 RPC 方法说明：**
+- `kernel.latencies` — Get ping/pong latencies for all modules
+
+## 使用方法
+
+### 查询模块延迟
+
+通过 RPC 调用 `kernel.latencies` 方法：
+
+```python
+# 通过 Launcher 或其他模块调用
+resp = await rpc_call("kernel.latencies", {})
+latencies = resp["result"]["latencies"]
+
+# 返回示例
+{
+    "latencies": {
+        "launcher": 2.34,
+        "watchdog": 3.12,
+        "web": 1.89,
+        "evol": 2.56,
+        "backup": null  # 尚未收到第一次 pong
+    }
+}
+```
+
+### 在模块列表中显示延迟
+
+Launcher 可以在 `list_modules` RPC 响应中添加延迟信息：
+
+```python
+async def _rpc_list_modules(self, params: dict) -> dict:
+    # 获取延迟数据
+    latencies_resp = await self._rpc_call(self._ws, "kernel.latencies", {})
+    latencies = latencies_resp.get("result", {}).get("latencies", {})
+
+    result = []
+    for name, info in self.modules.items():
+        rec = {
+            "name": name,
+            ...
+            "latency_ms": latencies.get(name),  # 添加延迟字段
+        }
+        result.append(rec)
+    return {"modules": result}
+```
+
+## 工作流程
+
+```
+Kernel                                    模块（客户端）
+  │                                           │
+  │────────── WebSocket 连接建立 ──────────────│
+  │                                           │
+  │ 启动 _ping_loop() 后台任务                 │
+  │                                           │
+  ├─ 每 20 秒发送 ──────────────────────────────┤
+  │   {"jsonrpc":"2.0",                       │
+  │    "id":"kernel_ping_launcher_1",         │
+  │    "method":"kernel.ping",                │
+  │    "params":{}}                           │
+  │                                           │
+  │   记录发送时间到 _ping_times               │
+  │                                           │
+  │                                           │
+  │ ◄────────── RPC 响应 ─────────────────────┤
+  │   {"jsonrpc":"2.0",                       │
+  │    "id":"kernel_ping_launcher_1",         │
+  │    "result":{}}                           │
+  │                                           │
+  │   计算延迟 = 当前时间 - _ping_times        │
+  │   保存到 _pong_latencies                  │
+  │                                           │
+```
+
+## 优势
+
+1. **集中管理** — Kernel 统一管理所有模块的 ping，不需要每个模块自己配置
+2. **延迟可见** — Kernel 记录每个模块的响应延迟，可以通过 RPC 查询
+3. **故障检测** — 如果模块无法响应 ping，Kernel 可以检测到（20秒超时）
+4. **监控友好** — 延迟数据可以展示在 Web UI 或监控面板中
+
+## 注意事项
+
+1. **首次 ping 前延迟为 null** — 模块刚连接时，需要等待第一次 ping/pong 完成才有延迟数据
+2. **ping 间隔固定 20 秒** — 当前硬编码，未来可以配置化
+3. **RPC 方式实现** — 使用 RPC 而非 WebSocket 原生 ping 帧，因为 FastAPI WebSocket 不支持直接发送 ping 帧
+4. **延迟单位为毫秒** — 保留 2 位小数
+
+## 后续优化
+
+1. **可配置的 ping 间隔** — 允许在 `kernel/module.md` 中配置 ping_interval
+2. **超时告警** — 如果模块响应时间超过阈值（如 5 秒），发布告警事件
+3. **历史延迟统计** — 记录最近 N 次的延迟，计算平均值、最大值、最小值
+4. **Web UI 展示** — 在 Web 管理界面的模块列表中显示延迟列

package/docs/Kite/345/256/211/350/243/205/351/227/256/351/242/230/350/247/243/345/206/263/346/226/271/346/241/210.md

@@ -0,0 +1,362 @@
+# Kite 安装问题解决方案
+
+## 环境信息
+
+- **操作系统**: Windows 11 Pro 10.0.26200
+- **Shell**: bash (Git Bash)
+- **Kite 版本**: 1.5.0
+- **Python 版本**: 3.13.12 (嵌入式版本)
+
+## 问题概述
+
+在 Windows 系统上运行 `kite start` 时遇到一系列环境配置问题，主要涉及 Python 命令重定向、虚拟环境创建和依赖安装。
+
+---
+
+## 问题 1: Windows Python 命令重定向
+
+### 错误信息
+
+```
+Python was not found; run without arguments to install from the Microsoft Store,
+or disable this shortcut from Settings > Manage App Execution Aliases.
+```
+
+### 问题原因
+
+Windows 在 `%LOCALAPPDATA%\Microsoft\WindowsApps\` 目录下放置了 `python.exe` 占位符（App Execution Aliases）。当代码调用 `python` 命令时，Windows 优先找到这些占位符并打开 Microsoft Store，而不是使用已下载的嵌入式 Python。
+
+### 解决方案
+
+修改 `env-manager.js` 文件，使用完整路径而不是命令名。
+
+**文件位置**:
+- `C:\Users\admin\AppData\Roaming\npm\node_modules\@agentunion\kite\scripts\env-manager.js`
+- `C:\Users\admin\.kite\versions\1.5.0\scripts\env-manager.js`
+
+**修改内容**:
+
+1. 添加 `getPythonCommand()` 函数：
+
+```javascript
+/**
+ * 获取 Python 命令路径
+ */
+function getPythonCommand() {
+  if (process.platform === 'win32') {
+    // Windows: 优先使用嵌入式 Python
+    const embeddedPython = path.join(getKiteDataPath(), 'python', 'python.exe');
+    if (fs.existsSync(embeddedPython)) {
+      return embeddedPython;
+    }
+    return 'python';
+  }
+  return 'python3';
+}
+```
+
+2. 修改 `setupVenv()` 函数：
+
+```javascript
+function setupVenv(versionDir) {
+  log('准备虚拟环境...', 'cyan');
+
+  const pythonCmd = getPythonCommand();  // 使用新函数
+
+  try {
+    const result = spawnSync(
+      pythonCmd,
+      ['-m', 'kite_cli', 'venv-setup'],
+      {
+        cwd: versionDir,
+        stdio: 'inherit',
+        encoding: 'utf-8',
+        env: {
+          ...process.env,
+          PYTHONPATH: versionDir
+        }
+      }
+    );
+
+    return result.status === 0;
+  } catch (e) {
+    error('虚拟环境准备失败');
+    return false;
+  }
+}
+```
+
+3. 同样修改 `installDeps()` 函数，将 `const pythonCmd = process.platform === 'win32' ? 'python' : 'python3';` 替换为 `const pythonCmd = getPythonCommand();`
+
+---
+
+## 问题 2: Python 模块路径问题
+
+### 错误信息
+
+```
+C:\Users\admin\.kite\python\python.exe: No module named kite_cli
+```
+
+### 问题原因
+
+嵌入式 Python 使用 `python313._pth` 文件限制模块搜索路径，默认不包含 Kite 版本目录，导致无法找到 `kite_cli` 模块。
+
+### 解决方案
+
+修改 `python313._pth` 文件，添加版本目录路径并启用 site 模块。
+
+**文件位置**: `C:\Users\admin\.kite\python\python313._pth`
+
+**修改内容**:
+
+```
+python313.zip
+.
+C:\Users\admin\.kite\versions\1.5.0
+
+# Uncomment to run site.main() automatically
+import site
+```
+
+**关键修改**:
+1. 添加 `C:\Users\admin\.kite\versions\1.5.0` 路径
+2. 将 `#import site` 改为 `import site`（去掉注释）
+
+---
+
+## 问题 3: 嵌入式 Python 缺少 venv 模块
+
+### 错误信息
+
+```
+C:\Users\admin\.kite\python\python.exe: No module named venv
+```
+
+### 问题原因
+
+Windows 嵌入式 Python 是精简版，不包含 `venv` 模块。
+
+### 解决方案
+
+为嵌入式 Python 安装 pip 和 virtualenv，然后修改代码使用 virtualenv。
+
+#### 步骤 1: 安装 pip
+
+```bash
+# 下载 get-pip.py
+curl -o /tmp/get-pip.py https://bootstrap.pypa.io/get-pip.py
+
+# 安装 pip
+"C:\Users\admin\.kite\python\python.exe" /tmp/get-pip.py
+```
+
+#### 步骤 2: 安装 virtualenv
+
+```bash
+"C:\Users\admin\.kite\python\python.exe" -m pip install virtualenv
+```
+
+#### 步骤 3: 修改代码使用 virtualenv
+
+**文件位置**: `C:\Users\admin\.kite\versions\1.5.0\core\env_checker.py`
+
+**修改 `create_venv()` 函数**:
+
+```python
+def create_venv() -> bool:
+    """创建虚拟环境"""
+    venv_path = get_venv_path()
+
+    print(f"[环境检查] 正在创建虚拟环境: {venv_path}")
+
+    try:
+        venv_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # 优先使用 virtualenv，如果不存在则使用 venv
+        try:
+            subprocess.run(
+                [sys.executable, "-m", "virtualenv", str(venv_path)],
+                check=True,
+                capture_output=True,
+                text=True
+            )
+        except subprocess.CalledProcessError:
+            # 如果 virtualenv 失败，尝试使用 venv
+            subprocess.run(
+                [sys.executable, "-m", "venv", str(venv_path)],
+                check=True,
+                capture_output=True,
+                text=True
+            )
+
+        print(f"[环境检查] 虚拟环境创建成功")
+        return True
+
+    except subprocess.CalledProcessError as e:
+        print(f"[环境检查] 虚拟环境创建失败: {e.stderr}")
+        return False
+```
+
+---
+
+## 问题 4: Unicode 编码错误
+
+### 错误信息
+
+```
+UnicodeEncodeError: 'gbk' codec can't encode character '\u2713' in position 0:
+illegal multibyte sequence
+```
+
+### 问题原因
+
+Python 脚本中使用了 Unicode 特殊字符（✓ 和 ✗），在 Windows GBK 编码环境下无法正常显示。
+
+### 解决方案
+
+将 Unicode 字符替换为 ASCII 字符。
+
+#### 修改文件 1: `venv_setup.py`
+
+**文件位置**: `C:\Users\admin\.kite\versions\1.5.0\kite_cli\commands\venv_setup.py`
+
+**替换内容**:
+- `✓` → `[OK]`
+- `✗` → `[X]`
+
+```python
+# 修改前
+print(f"✓ Python 版本: {py_version}")
+print(f"✗ Python 版本不匹配: {py_version}（需要 {required_version}）")
+
+# 修改后
+print(f"[OK] Python 版本: {py_version}")
+print(f"[X] Python 版本不匹配: {py_version}（需要 {required_version}）")
+```
+
+#### 修改文件 2: `deps_install.py`
+
+**文件位置**: `C:\Users\admin\.kite\versions\1.5.0\kite_cli\commands\deps_install.py`
+
+**替换内容**: 同样将所有 `✓` 替换为 `[OK]`，`✗` 替换为 `[X]`
+
+---
+
+## 完整解决流程
+
+### 1. 修复 Python 重定向问题
+
+```bash
+# 编辑 npm 全局包中的 env-manager.js
+# 添加 getPythonCommand() 函数并修改 setupVenv() 和 installDeps()
+```
+
+### 2. 配置 Python 模块路径
+
+```bash
+# 编辑 python313._pth
+# 添加版本目录路径并启用 site 模块
+```
+
+### 3. 安装 pip 和 virtualenv
+
+```bash
+curl -o /tmp/get-pip.py https://bootstrap.pypa.io/get-pip.py
+"C:\Users\admin\.kite\python\python.exe" /tmp/get-pip.py
+"C:\Users\admin\.kite\python\python.exe" -m pip install virtualenv
+```
+
+### 4. 修改虚拟环境创建代码
+
+```bash
+# 编辑 env_checker.py
+# 修改 create_venv() 函数使用 virtualenv
+```
+
+### 5. 修复 Unicode 编码问题
+
+```bash
+# 编辑 venv_setup.py 和 deps_install.py
+# 替换 Unicode 字符为 ASCII
+```
+
+### 6. 验证安装
+
+```bash
+kite start
+```
+
+---
+
+## 验证结果
+
+成功启动后应该看到：
+
+```
+✓ Phase 1 完成: Kernel 已就绪
+✓ Phase 1.5 完成: Watchdog
+✓ Phase 2 完成: 核心模块启动
+✓ Evol UI ready: http://localhost:18766
+```
+
+所有模块（kernel, watchdog, assistant, acp_channel, evol, backup）应该都显示为 "已就绪"。
+
+---
+
+## 替代方案
+
+如果不想使用嵌入式 Python，可以：
+
+### 方案 1: 禁用 Windows App Execution Aliases
+
+1. 打开 Windows 设置（Win + I）
+2. 进入"应用" → "高级应用设置" → "应用执行别名"
+3. 关闭 "python.exe" 和 "python3.exe"
+
+### 方案 2: 安装完整版 Python
+
+下载并安装 Python 3.13.12 完整版：
+https://www.python.org/downloads/release/python-31312/
+
+---
+
+## 注意事项
+
+1. **文件路径**: 确保所有路径使用正确的分隔符（Windows 使用反斜杠）
+2. **权限**: 某些操作可能需要管理员权限
+3. **版本兼容**: 确保 Python 版本与 `python_version.json` 中要求的版本一致
+4. **备份**: 修改文件前建议先备份原文件
+
+---
+
+## 相关文件清单
+
+### 需要修改的文件
+
+1. `C:\Users\admin\AppData\Roaming\npm\node_modules\@agentunion\kite\scripts\env-manager.js`
+2. `C:\Users\admin\.kite\python\python313._pth`
+3. `C:\Users\admin\.kite\versions\1.5.0\core\env_checker.py`
+4. `C:\Users\admin\.kite\versions\1.5.0\kite_cli\commands\venv_setup.py`
+5. `C:\Users\admin\.kite\versions\1.5.0\kite_cli\commands\deps_install.py`
+
+### 关键目录
+
+- Kite 数据目录: `C:\Users\admin\.kite\`
+- Python 嵌入式: `C:\Users\admin\.kite\python\`
+- 虚拟环境: `C:\Users\admin\.kite\venv\`
+- 版本目录: `C:\Users\admin\.kite\versions\1.5.0\`
+
+---
+
+## 总结
+
+通过以上步骤，成功解决了 Windows 环境下 Kite 安装的所有问题：
+
+1. ✅ Windows Python 重定向问题
+2. ✅ Python 模块路径配置
+3. ✅ 虚拟环境创建（使用 virtualenv）
+4. ✅ Unicode 编码兼容性
+5. ✅ 依赖安装（19个依赖包）
+
+Kite 现已完全正常运行，所有模块启动成功。