@agentunion/kite 1.4.0 → 1.6.0

package/extensions/services/proxy/agentcp/docs/UDP_HEARTBEAT_FIX_REPORT.md

@@ -0,0 +1,265 @@
+# AgentCP UDP 心跳自动恢复修复报告
+
+**修复日期**: 2026-01-30
+**修复版本**: agentcp (python_backend)
+**修复人员**: Claude Opus 4.5
+
+---
+
+## 一、问题描述
+
+### 1.1 现象
+- 服务器端观察到客户端没有发送心跳
+- 客户端重启后恢复正常
+- 心跳发送线程在异常情况下停止，且没有自动恢复机制
+
+### 1.2 影响范围
+- UDP 心跳客户端 (`heartbeat_client.py`)
+- 认证客户端 (`auth_client.py`)
+
+---
+
+## 二、问题根因分析
+
+### 2.1 HeartbeatClient 问题
+
+| 问题 | 严重程度 | 描述 |
+|------|---------|------|
+| Socket 异常后不重建 | 🔴 严重 | `sendto()` 异常后只打印错误，不尝试重建 socket，导致心跳永久失效 |
+| 401 重登录后不更新 socket | 🔴 严重 | `sign_in()` 获取新服务器信息后，UDP socket 未重建，心跳发送到错误地址 |
+| 接收线程阻塞无法中断 | 🔴 严重 | `recvfrom()` 阻塞调用，socket 损坏后陷入无限异常循环 |
+| `offline()` 关闭顺序错误 | 🟡 中等 | 先关 socket 再置标志位，可能导致线程访问已关闭的 socket |
+| 线程没有 join() | 🟡 中等 | 未等待线程退出，可能导致资源泄漏 |
+| 无心跳超时检测 | 🟡 设计缺陷 | 只发送心跳不检测响应，无法主动发现断连 |
+
+### 2.2 AuthClient 问题
+
+| 问题 | 严重程度 | 描述 |
+|------|---------|------|
+| 重试逻辑缺陷 | 🟡 中等 | `is_retry` 标志位设置后永不重置，导致后续登录尝试直接返回 |
+| 递归调用未返回结果 | 🟡 中等 | `sign_in()` 递归调用未 return，结果丢失 |
+| 返回值不一致 | 🟡 中等 | 失败时返回空字符串 `""`，调用方当 dict 使用会崩溃 |
+| HTTP 请求无超时 | 🟡 中等 | 可能导致线程被无限阻塞 |
+
+---
+
+## 三、修复方案
+
+### 3.1 HeartbeatClient 修复
+
+#### 3.1.1 新增常量配置
+
+```python
+class HeartbeatClient:
+    MAX_SEND_FAILURES = 3           # 发送失败触发重连的阈值
+    MAX_RECV_FAILURES = 3           # 接收失败触发重连的阈值
+    MAX_MISSED_HEARTBEATS = 3       # 心跳响应超时阈值（错过次数）
+    RECONNECT_BACKOFF_MAX = 30      # 重连退避上限（秒）
+    SOCKET_TIMEOUT = 1.0            # socket 超时时间（秒）
+```
+
+#### 3.1.2 新增状态变量
+
+```python
+self._socket_lock = threading.Lock()        # 保护 socket 操作
+self._reconnect_lock = threading.Lock()     # 防止并发重连
+self._last_reconnect_ts = 0                 # 上次重连时间戳
+self._last_hb_recv = 0                      # 上次收到心跳响应的时间戳
+self._send_failures = 0                     # 连续发送失败次数
+self._recv_failures = 0                     # 连续接收失败次数
+```
+
+#### 3.1.3 统一 Socket 生命周期管理
+
+新增方法：
+- `_create_socket()`: 创建并绑定 UDP socket，设置超时
+- `_close_socket()`: 安全关闭 socket
+- `_reconnect(reason)`: 限流/退避后执行 sign_in + 重建 socket
+
+#### 3.1.4 发送线程异常恢复
+
+```python
+def __send_heartbeat(self):
+    backoff = 1
+    while self.is_sending_heartbeat and self.is_running:
+        try:
+            # 检查心跳响应超时
+            if self._last_hb_recv > 0:
+                timeout_threshold = self.MAX_MISSED_HEARTBEATS * self.heartbeat_interval
+                if current_time_ms - self._last_hb_recv > timeout_threshold:
+                    self._reconnect("heartbeat_response_timeout")
+                    continue
+
+            # 发送心跳（使用锁保护 socket）
+            with self._socket_lock:
+                if self.udp_socket is not None:
+                    self.udp_socket.sendto(data, (self.server_ip, self.port))
+
+            self._send_failures = 0
+            backoff = 1
+
+        except Exception as e:
+            self._send_failures += 1
+            if self._send_failures >= self.MAX_SEND_FAILURES:
+                self._reconnect("send_failures_threshold")
+            else:
+                time.sleep(backoff)
+                backoff = min(backoff * 2, self.RECONNECT_BACKOFF_MAX)
+```
+
+#### 3.1.5 接收线程可中断、可恢复
+
+```python
+def _receive_messages(self):
+    while self.is_running:
+        try:
+            # socket 设置超时，确保能定期检查 is_running
+            try:
+                data, addr = sock.recvfrom(1536)
+            except socket.timeout:
+                continue  # 超时是正常的
+
+            self._recv_failures = 0
+            self._last_hb_recv = current_time_ms  # 更新响应时间
+
+            if hb_resp.NextBeat == 401:
+                self._reconnect("401_auth_failed")  # 401 触发重连
+
+        except Exception as e:
+            self._recv_failures += 1
+            if self._recv_failures >= self.MAX_RECV_FAILURES:
+                self._reconnect("recv_failures_threshold")
+```
+
+#### 3.1.6 修复 offline() 关闭顺序
+
+```python
+def offline(self):
+    # 1. 先设置标志位
+    self.is_running = False
+    self.is_sending_heartbeat = False
+
+    # 2. 关闭 socket
+    self._close_socket()
+
+    # 3. 等待线程退出
+    if self.send_thread is not None and self.send_thread.is_alive():
+        self.send_thread.join(timeout=3)
+    if self.receive_thread is not None and self.receive_thread.is_alive():
+        self.receive_thread.join(timeout=3)
+```
+
+### 3.2 AuthClient 修复
+
+#### 3.2.1 新增 HTTP 超时配置
+
+```python
+HTTP_TIMEOUT = (3, 10)  # (连接超时, 读取超时)
+```
+
+#### 3.2.2 重写 sign_in() 重试逻辑
+
+```python
+def sign_in(self, max_retry_num: int = 10) -> Union[dict, None]:
+    """登录方法，使用循环重试，失败返回 None"""
+    for retry_count in range(max_retry_num + 1):
+        try:
+            if retry_count > 0:
+                backoff = min(2 * retry_count, 30)  # 指数退避
+                time.sleep(backoff)
+
+            response = requests.post(url, ..., timeout=self.HTTP_TIMEOUT)
+
+            if response.status_code == 200:
+                # ... 处理成功响应 ...
+                return result
+
+        except Exception as e:
+            log_warning(f"Sign in exception (retry {retry_count}/{max_retry_num}): {e}")
+
+    log_error(f"Sign in failed after {max_retry_num} retries")
+    return None  # 统一返回 None，不再返回空字符串
+```
+
+#### 3.2.3 所有 HTTP 请求添加超时
+
+- `sign_in()`: 添加 `timeout=self.HTTP_TIMEOUT`
+- `sign_out()`: 添加 `timeout=self.HTTP_TIMEOUT`
+- `__check_server_cert()`: 添加 `timeout=self.HTTP_TIMEOUT`
+
+---
+
+## 四、修改文件清单
+
+| 文件路径 | 修改类型 | 说明 |
+|---------|---------|------|
+| `agentcp/heartbeat/heartbeat_client.py` | 重构 | 添加自动恢复机制 |
+| `agentcp/base/auth_client.py` | 重构 | 修复重试逻辑 |
+
+---
+
+## 五、修复效果
+
+### 5.1 解决的问题
+
+| 场景 | 修复前 | 修复后 |
+|------|-------|-------|
+| 网络短暂中断 | ❌ 心跳永久失效 | ✅ 自动重连恢复 |
+| 服务器重启(401) | ❌ 心跳发送到错误地址 | ✅ 重建 socket 恢复 |
+| 长时间无响应 | ❌ 无法检测 | ✅ 超时检测触发重连 |
+| 登录失败 | ❌ 一次失败后永久失败 | ✅ 循环重试直到成功 |
+| 调用 offline() | ❌ 可能异常/资源泄漏 | ✅ 安全关闭 |
+
+### 5.2 新增能力
+
+1. **心跳响应超时检测**: 连续 3 次心跳周期无响应，自动触发重连
+2. **发送/接收失败计数**: 连续 3 次失败触发重连
+3. **指数退避重试**: 避免频繁重连对服务器造成压力
+4. **重连限流**: 距离上次重连至少间隔 5 秒
+5. **线程安全**: 使用锁保护 socket 操作
+
+---
+
+## 六、测试建议
+
+### 6.1 功能测试
+
+1. **正常心跳**: 启动后确认心跳持续发送并收到响应
+2. **网络中断恢复**: 断网 30 秒后恢复，观察是否自动重连
+3. **服务器重启**: 服务端重启返回 401，确认客户端自动重新登录
+4. **offline/online 循环**: 重复调用，确认无资源泄漏
+
+### 6.2 异常测试
+
+1. **模拟 socket 异常**: 确认触发重连
+2. **模拟登录失败**: 确认重试机制正常工作
+3. **模拟长时间无响应**: 确认超时检测触发重连
+
+---
+
+## 七、回滚策略
+
+如需回滚，可按以下步骤操作：
+
+1. 使用 git 恢复修改前的版本：
+   ```bash
+   git checkout <commit-hash> -- python_backend/agentcp/heartbeat/heartbeat_client.py
+   git checkout <commit-hash> -- python_backend/agentcp/base/auth_client.py
+   ```
+
+2. 或者仅回滚部分修改：
+   - 保留 `AuthClient` 的 HTTP 超时修复
+   - 回滚 `HeartbeatClient` 的重连逻辑
+
+---
+
+## 八、后续优化建议
+
+1. **添加监控指标**: 记录重连次数、失败次数等，便于运维监控
+2. **配置化参数**: 将重连阈值、超时时间等参数配置化
+3. **健康检查接口**: 提供 API 查询心跳状态
+4. **日志分级**: 区分 DEBUG/INFO/WARNING/ERROR 日志级别
+
+---
+
+*报告生成时间: 2026-01-30 08:07:15 UTC*

package/extensions/services/proxy/agentcp/docs/heartbeat_issue_analysis.md

@@ -0,0 +1,291 @@
+# AgentCP UDP 心跳断开后无法自动恢复的问题分析报告
+
+## 一、问题现象
+
+服务器端观察到客户端没有发送心跳，但客户端重启后恢复正常。说明心跳发送线程在某种异常情况下停止了，且没有自动恢复机制。
+
+---
+
+## 二、代码审查发现的问题
+
+### 问题 1：UDP Socket 异常后线程静默退出（严重）
+
+**文件**: `heartbeat_client.py:71-94`
+
+```python
+def __send_heartbeat(self):
+    while self.is_sending_heartbeat and self.is_running:
+        try:
+            # ... 发送心跳 ...
+            self.udp_socket.sendto(data, (self.server_ip, self.port))
+        except Exception as e:
+            print(f"Heartbeat send error: {e}")
+            ErrorContext.publish(...)
+            # ❌ 问题：异常后没有任何恢复措施，只是打印错误继续循环
+```
+
+**问题分析**：
+- 如果 `self.udp_socket` 变成 `None` 或被关闭，`sendto()` 会抛出异常
+- 异常被捕获后只是打印错误，**没有尝试重建 socket**
+- 如果 socket 损坏，后续所有心跳发送都会失败，但线程不会退出也不会恢复
+
+---
+
+### 问题 2：接收线程异常可能导致 socket 状态不一致（严重）
+
+**文件**: `heartbeat_client.py:96-133`
+
+```python
+def _receive_messages(self):
+    while self.is_running:
+        try:
+            data, addr = self.udp_socket.recvfrom(1536)  # ❌ 阻塞调用
+            # ... 处理响应 ...
+        except Exception as e:
+            print(f"Receive message exception: {e}")
+            time.sleep(1.5)
+            # ❌ 问题：没有检查 socket 是否仍然有效
+```
+
+**问题分析**：
+- `recvfrom()` 是阻塞调用，如果 socket 被关闭会抛出异常
+- 异常后只是 sleep 1.5 秒继续，**没有检查 socket 状态**
+- 如果 socket 已损坏，会陷入无限的异常-sleep-异常循环
+
+---
+
+### 问题 3：401 重新登录后没有更新 socket 连接信息（严重）
+
+**文件**: `heartbeat_client.py:105-108`
+
+```python
+if hb_resp.NextBeat == 401:
+    print(f"Heartbeat failed: {hb_resp.NextBeat}, try sign in again")
+    ErrorContext.publish(...)
+    self.sign_in()  # ❌ 只是重新登录，没有重建 socket
+```
+
+**问题分析**：
+- `sign_in()` 会获取新的 `server_ip`、`port`、`sign_cookie`
+- 但是 **UDP socket 没有重新绑定到新的服务器地址**
+- 如果服务器 IP/端口变了，心跳会发送到错误的地址
+
+---
+
+### 问题 4：`offline()` 关闭 socket 后状态不一致（中等）
+
+**文件**: `heartbeat_client.py:157-162`
+
+```python
+def offline(self):
+    """停止心跳"""
+    if self.udp_socket is not None:
+        self.udp_socket.close()  # ❌ 关闭 socket
+    self.is_running = False      # ❌ 设置标志位在后面
+```
+
+**问题分析**：
+- 先关闭 socket，再设置 `is_running = False`
+- 在这个时间窗口内，发送/接收线程可能还在运行，会访问已关闭的 socket
+- 应该先设置标志位，等线程退出后再关闭 socket
+
+---
+
+### 问题 5：线程没有等待退出（中等）
+
+**文件**: `heartbeat_client.py:157-162`
+
+```python
+def offline(self):
+    if self.udp_socket is not None:
+        self.udp_socket.close()
+    self.is_running = False
+    # ❌ 没有 join() 等待线程退出
+```
+
+**问题分析**：
+- 没有调用 `self.send_thread.join()` 和 `self.receive_thread.join()`
+- 线程可能还在运行时就返回了，导致资源泄漏或状态不一致
+
+---
+
+### 问题 6：`auth_client.sign_in()` 重试逻辑有缺陷（中等）
+
+**文件**: `auth_client.py:129-136`
+
+```python
+except Exception as e:
+    log_error(f"链接建立失败，正在重试")
+    if self.is_retry == False:  # ❌ 只有第一次异常才重试
+        log_error("重试登录失败，6s后尝试重新连接")
+        self.is_retry = True
+        time.sleep(6)
+        self.sign_in(retry_count+1, max_retry_num)
+    # ❌ 如果 is_retry == True，直接返回 None，不再重试
+```
+
+**问题分析**：
+- `is_retry` 标志位设置后永远不会重置为 `False`
+- 第一次重试失败后，后续所有登录尝试都会直接返回 `None`
+- 这会导致心跳客户端拿不到有效的服务器信息
+
+---
+
+### 问题 7：没有心跳超时检测机制（设计缺陷）
+
+**问题分析**：
+- 当前实现只是定时发送心跳，**不检测服务器是否响应**
+- 如果网络断开，客户端会一直发送心跳但收不到响应
+- 没有机制检测"连续 N 次没收到响应"然后触发重连
+
+---
+
+## 三、问题根因总结
+
+| 问题 | 严重程度 | 影响 |
+|------|---------|------|
+| Socket 异常后不重建 | 🔴 严重 | 心跳永久失效 |
+| 401 重登录后不更新 socket | 🔴 严重 | 心跳发送到错误地址 |
+| 接收线程异常后不检查 socket | 🔴 严重 | 无限异常循环 |
+| offline() 关闭顺序错误 | 🟡 中等 | 可能导致异常 |
+| 线程没有 join() | 🟡 中等 | 资源泄漏 |
+| auth_client 重试逻辑缺陷 | 🟡 中等 | 登录失败后无法恢复 |
+| 无心跳超时检测 | 🟡 设计缺陷 | 无法主动发现断连 |
+
+---
+
+## 四、最可能的故障场景
+
+根据"服务器看不到心跳，重启客户端后正常"的现象，最可能的原因是：
+
+### 场景 A：网络波动导致 socket 异常
+1. 网络短暂中断
+2. `sendto()` 或 `recvfrom()` 抛出异常
+3. 异常被捕获，但 socket 可能已损坏
+4. 后续心跳发送全部失败，但线程继续运行（静默失败）
+
+### 场景 B：服务器重启返回 401
+1. 服务器重启
+2. 客户端收到 401 响应
+3. 调用 `sign_in()` 获取新的服务器信息
+4. **但 UDP socket 仍然绑定到旧地址**
+5. 心跳发送到错误的地址
+
+### 场景 C：登录重试失败后放弃
+1. 网络异常导致登录失败
+2. `auth_client.sign_in()` 重试一次后设置 `is_retry = True`
+3. 后续所有登录尝试直接返回 `None`
+4. 心跳客户端拿不到有效的服务器信息
+
+---
+
+## 五、建议修复方向
+
+### 5.1 添加 socket 健康检查和重建机制
+
+```python
+def _rebuild_socket(self):
+    """重建 UDP socket"""
+    try:
+        if self.udp_socket:
+            self.udp_socket.close()
+    except:
+        pass
+    self.udp_socket = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    self.udp_socket.bind((self.local_ip, 0))
+    self.local_ip, self.local_port = self.udp_socket.getsockname()
+```
+
+### 5.2 401 重登录后重新创建 UDP socket
+
+```python
+if hb_resp.NextBeat == 401:
+    self.sign_in()
+    self._rebuild_socket()  # 重建 socket
+```
+
+### 5.3 添加心跳响应超时检测
+
+```python
+def __send_heartbeat(self):
+    consecutive_failures = 0
+    MAX_FAILURES = 5
+
+    while self.is_sending_heartbeat and self.is_running:
+        try:
+            # 检查是否长时间没收到响应
+            if time.time() - self.last_response_time > 30:
+                consecutive_failures += 1
+                if consecutive_failures >= MAX_FAILURES:
+                    log_error("心跳超时，尝试重连")
+                    self.sign_in()
+                    self._rebuild_socket()
+                    consecutive_failures = 0
+            # ... 发送心跳 ...
+        except Exception as e:
+            # 异常处理
+```
+
+### 5.4 修复 `offline()` 的关闭顺序
+
+```python
+def offline(self):
+    """停止心跳"""
+    # 1. 先设置标志位
+    self.is_running = False
+    self.is_sending_heartbeat = False
+
+    # 2. 等待线程退出
+    if self.send_thread and self.send_thread.is_alive():
+        self.send_thread.join(timeout=3)
+    if self.receive_thread and self.receive_thread.is_alive():
+        self.receive_thread.join(timeout=3)
+
+    # 3. 最后关闭 socket
+    if self.udp_socket:
+        self.udp_socket.close()
+        self.udp_socket = None
+```
+
+### 5.5 修复 `auth_client` 的重试逻辑
+
+```python
+def sign_in(self, retry_count=0, max_retry_num=10) -> Union[dict, None]:
+    try:
+        # ... 登录逻辑 ...
+    except Exception as e:
+        log_error(f"链接建立失败，正在重试 ({retry_count}/{max_retry_num})")
+        if retry_count < max_retry_num:
+            time.sleep(min(6 * (retry_count + 1), 30))  # 指数退避
+            return self.sign_in(retry_count + 1, max_retry_num)
+        else:
+            log_error("重试登录失败，已达最大重试次数")
+            return None
+```
+
+---
+
+## 六、相关文件清单
+
+| 文件路径 | 说明 |
+|---------|------|
+| `agentcp/heartbeat/heartbeat_client.py` | UDP 心跳客户端主文件 |
+| `agentcp/base/auth_client.py` | 认证客户端 |
+| `agentcp/agentcp.py` | AgentID 主入口 |
+| `agentcp/context/context.py` | 错误上下文处理 |
+
+---
+
+## 七、总结
+
+当前 UDP 心跳实现存在多个严重的异常恢复缺陷，主要问题是：
+
+1. **Socket 异常后不重建** - 导致心跳永久失效
+2. **401 重登录后不更新连接** - 导致心跳发送到错误地址
+3. **缺少心跳超时检测** - 无法主动发现断连
+
+建议按照第五节的修复方向进行改进，增强心跳机制的健壮性和自动恢复能力。
+
+---
+
+*报告生成时间: 2026-01-30*

package/extensions/services/proxy/agentcp/file/__init__.py

@@ -0,0 +1,16 @@
+# -*- coding: utf-8 -*-
+# Copyright 2025 AgentUnion Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from . import file_client