@agentunion/kite 1.4.0 → 1.5.0

package/kernel/module.md

@@ -9,6 +9,7 @@ version: 1.0.1
 advertise_ip: 127.0.0.1
 monitor: true
 preferred_port: 0
+display_order: 100
 ---
 # Kernel
 
@@ -16,10 +17,11 @@ Unified infrastructure module that merges Registry (service discovery) and Event
 
 ## Responsibilities
 
-- **Service Registry**: Module registration, heartbeat TTL, glob lookup, dot-path queries
+- **Service Registry**: Module registration, glob lookup, dot-path queries
 - **Event Routing**: NATS-style wildcard subscriptions, per-subscriber queues, 1h dedup
 - **RPC Routing**: JSON-RPC 2.0 dispatch for builtin methods + cross-module forwarding
 - **Token Verification**: In-memory token→module_id resolution (no cross-process HTTP)
+- **Ping/Pong Monitoring**: Active ping to all connected modules, track response latencies
 
 ## Protocol
 
@@ -34,3 +36,25 @@ Three frame types on the wire:
 
 - `GET /health` — combined registry + event hub health
 - `GET /stats` — connections, subscriptions, counters
+
+## RPC Methods
+
+### Registry Methods
+- `registry.register` — Register a module
+- `registry.deregister` — Deregister a module
+- `registry.lookup` — Lookup modules by field/value
+- `registry.get` — Get module info by dot-path
+- `registry.verify` — Verify a token
+
+### Event Methods
+- `event.publish` — Publish an event
+- `event.subscribe` — Subscribe to events
+- `event.unsubscribe` — Unsubscribe from events
+
+### Kernel Methods
+- `kernel.ping` — Ping (used for latency measurement)
+- `kernel.stats` — Get kernel statistics
+- `kernel.health` — Get kernel health status
+- `kernel.latencies` — Get ping/pong latencies for all modules
+- `kernel.generate_tokens` — Generate tokens for modules (Launcher only)
+- `kernel.register_tokens` — Register token mapping (Launcher only)

package/kernel/registry_store.py

@@ -20,9 +20,6 @@ class RegistryStore:
         self.launcher_token = launcher_token
         self.token_map: dict[str, str] = {}       # module_id -> token
         self.modules: dict[str, dict] = {}         # module_id -> registration payload
-        self.heartbeats: dict[str, float] = {}     # module_id -> last heartbeat timestamp
-        self.ttl = 60           # seconds before marking offline
-        self.heartbeat_interval = 30
         self.is_debug = os.environ.get("KITE_DEBUG") == "1"
         self.last_update_time = time.time()        # Global registry update timestamp
 
@@ -59,7 +56,7 @@ class RegistryStore:
 
     def register_module(self, data: dict) -> dict:
         """Register or update a module. Idempotent — same module_id overwrites.
-        Returns dict with ttl, heartbeat_interval, and changed flag on success, raises exception on failure."""
+        Returns dict with changed flag on success, raises exception on failure."""
         # Validate required fields
         missing = [f for f in self._REQUIRED_FIELDS if not data.get(f)]
         if missing:
@@ -111,30 +108,20 @@ class RegistryStore:
         record["status"] = "registered"  # State machine: connected → registered (via register RPC)
         record["registered_at"] = time.time()
         self.modules[mid] = record
-        self.heartbeats[mid] = time.time()
 
         # Update global timestamp if content changed
         if changed:
             self.last_update_time = time.time()
 
-        return {"ttl": self.ttl, "heartbeat_interval": self.heartbeat_interval, "changed": changed}
+        return {"changed": changed}
 
     def deregister_module(self, module_id: str) -> dict:
         """Remove a module record immediately. Returns empty dict."""
         self.modules.pop(module_id, None)
-        self.heartbeats.pop(module_id, None)
         # Update global timestamp
         self.last_update_time = time.time()
         return {}
 
-    def heartbeat(self, module_id: str) -> dict:
-        """Renew heartbeat for a module. Returns empty dict on success, raises exception on failure."""
-        if module_id not in self.modules:
-            raise KeyError(f"Module '{module_id}' not registered")
-        self.heartbeats[module_id] = time.time()
-        # Don't change status — heartbeat just keeps alive, doesn't upgrade state
-        return {}
-
     def set_connected(self, module_id: str):
         """Mark a module as connected (WS established, not yet registered).
         Only upgrades from offline; doesn't downgrade from registered/ready."""
@@ -157,17 +144,6 @@ class RegistryStore:
         mod = self.modules.get(module_id)
         return mod is not None and mod.get("status") == "ready"
 
-    def check_ttl(self) -> list[str]:
-        """Mark modules as offline if heartbeat expired. Returns list of newly-offline module_ids."""
-        now = time.time()
-        expired = []
-        for mid, last in list(self.heartbeats.items()):
-            if mid in self.modules and now - last > self.ttl:
-                if self.modules[mid].get("status") not in ("offline",):
-                    self.modules[mid]["status"] = "offline"
-                    expired.append(mid)
-        return expired
-
     # ── Get by dot-path ──
 
     def get_by_path(self, path: str) -> Any | None:

package/kernel/rpc_router.py

@@ -83,7 +83,6 @@ class RpcRouter:
         self.methods: dict[str, callable] = {
             "registry.register":      self._registry_register,
             "registry.deregister":    self._registry_deregister,
-            "registry.heartbeat":     self._registry_heartbeat,
             "registry.lookup":        self._registry_lookup,
             "registry.get":           self._registry_get,
             "registry.verify":        self._registry_verify,
@@ -93,6 +92,7 @@ class RpcRouter:
             "kernel.ping":            self._kernel_ping,
             "kernel.stats":           self._kernel_stats,
             "kernel.health":          self._kernel_health,
+            "kernel.latencies":       self._kernel_latencies,
             "kernel.generate_tokens": self._kernel_generate_tokens,
             "kernel.register_tokens": self._kernel_register_tokens,
         }
@@ -218,6 +218,11 @@ class RpcRouter:
         # Strip target prefix from method for the forwarded request
         actual_method = method[len(target) + 1:]  # e.g. "watchdog.get_status" -> "get_status"
 
+        # Inject caller_id into params for permission checking
+        if not isinstance(params, dict):
+            params = {}
+        params["_caller_id"] = caller_id
+
         # Record pending forward
         loop = asyncio.get_event_loop()
         pending = PendingForward(
@@ -324,15 +329,6 @@ class RpcRouter:
 
         return {}
 
-    async def _registry_heartbeat(self, caller_id: str, params: dict) -> dict:
-        mid = params.get("module_id")
-        if not mid:
-            raise ValueError("module_id required")
-        if caller_id != "launcher" and caller_id != mid:
-            raise PermissionError(f"Module '{caller_id}' cannot heartbeat for '{mid}'")
-
-        return self.registry.heartbeat(mid)
-
     async def _registry_lookup(self, caller_id: str, params: dict) -> dict:
         field = params.get("field")
         module = params.get("module")
@@ -382,7 +378,9 @@ class RpcRouter:
         # When a module publishes module.ready, update its status in registry
         if event_type == "module.ready":
             mid = (data or {}).get("module_id", caller_id)
+            print(f"[kernel] DEBUG: 收到 module.ready 事件，module_id={mid}, caller_id={caller_id}")
             self.registry.set_ready(mid)
+            print(f"[kernel] DEBUG: 已调用 set_ready({mid})")
 
         return self.event_hub.publish_event(caller_id, event_id, event_type, data, echo)
 
@@ -428,6 +426,34 @@ class RpcRouter:
             "event_stats": eh_health.get("details", {}),
         }
 
+    async def _kernel_latencies(self, caller_id: str, params: dict) -> dict:
+        """Get ping/pong latencies for all connected modules.
+
+        Returns:
+            {
+                "latencies": {
+                    "module1": {
+                        "outbound": 12.34,  # ms, Kernel → module
+                        "inbound": 23.45,   # ms, module → Kernel
+                        "status": "ok" | "timeout" | "never"
+                    },
+                    ...
+                }
+            }
+        """
+        result = {}
+        for module_id in self.kernel_server.connections.keys():
+            latency_data = self.kernel_server._pong_latencies.get(module_id, {})
+            status = self.kernel_server._pong_status.get(module_id, "never")
+
+            result[module_id] = {
+                "outbound": latency_data.get("outbound"),
+                "inbound": latency_data.get("inbound"),
+                "status": status,
+            }
+
+        return {"latencies": result}
+
     async def _kernel_generate_tokens(self, caller_id: str, params: dict) -> dict:
         """Generate tokens for a list of module names.
 

package/kernel/server.py

@@ -33,12 +33,13 @@ class KernelServer:
     - Event notifications (delivered to subscribers)
     """
 
-    def __init__(self, launcher_token: str = None, advertise_ip: str = "127.0.0.1", module_id: str = None):
+    def __init__(self, launcher_token: str = None, advertise_ip: str = "127.0.0.1", module_id: str = None, boot_t0: float = 0):
         if module_id is None:
             raise ValueError("module_id is required")
         self.module_id = module_id
         self.advertise_ip = advertise_ip
         self.port: int = 0  # set by entry.py before uvicorn.run
+        self.boot_t0 = boot_t0  # Startup time for ready event
 
         # Core components
         self.registry = RegistryStore(launcher_token)  # Can be None
@@ -57,7 +58,6 @@ class KernelServer:
         )
 
         # Background tasks
-        self._ttl_task: asyncio.Task | None = None
         self._dedup_task: asyncio.Task | None = None
         self._uvicorn_server = None  # set by entry.py for graceful shutdown
         self._shutting_down = False
@@ -69,7 +69,7 @@ class KernelServer:
 
         # Subscribe to events that Kernel needs to handle
         # Kernel 通过订阅机制接收事件（与其他模块一致）
-        self.event_hub.handle_subscribe(self.module_id, ["module.shutdown"])
+        self.event_hub.handle_subscribe(self.module_id, ["module.shutdown", "system.pong"])
 
         # Register internal event callback for Kernel
         # Kernel 自身没有 WebSocket 连接，通过回调机制接收订阅的事件
@@ -80,6 +80,12 @@ class KernelServer:
         # Launcher loss timer (35s after launcher offline)
         self._launcher_loss_task: asyncio.Task | None = None
 
+        # Ping/Pong tracking
+        self._ping_sent_times: dict[str, float] = {}  # module_id -> last ping sent time (t1)
+        self._pong_latencies: dict[str, dict] = {}  # module_id -> {"outbound": ms, "inbound": ms, "last_update": timestamp}
+        self._pong_status: dict[str, str] = {}  # module_id -> "ok" | "timeout" | "never"
+        self._ping_task: asyncio.Task | None = None  # Global ping broadcast task
+
         # Build FastAPI app
         self.app = self._create_app()
 
@@ -92,15 +98,15 @@ class KernelServer:
         @app.on_event("startup")
         async def _startup():
             server.event_hub.start_internal_senders()
-            server._ttl_task = asyncio.create_task(server._ttl_loop())
             server._dedup_task = asyncio.create_task(server._dedup_loop())
+            server._ping_task = asyncio.create_task(server._ping_broadcast_loop())
 
         @app.on_event("shutdown")
         async def _shutdown():
-            if server._ttl_task:
-                server._ttl_task.cancel()
             if server._dedup_task:
                 server._dedup_task.cancel()
+            if server._ping_task:
+                server._ping_task.cancel()
 
         # ── WebSocket endpoint ──
 
@@ -150,9 +156,9 @@ class KernelServer:
                     print(f"[kernel] launcher reconnected, cancelled loss timer")
                 print(f"[kernel] launcher connected")
 
-            # Renew heartbeat on connect
-            if module_id in server.registry.modules:
-                server.registry.heartbeat(module_id)
+            # Initialize ping status for new connection
+            if module_id not in server._pong_status:
+                server._pong_status[module_id] = "never"
 
             try:
                 while True:
@@ -243,17 +249,54 @@ class KernelServer:
 
     # ── Background loops ──
 
-    async def _ttl_loop(self):
-        """Check heartbeat TTL every 10s and publish offline events."""
+    async def _ping_broadcast_loop(self):
+        """Broadcast system.ping event every 20s to all connected modules."""
+        import time
+        import uuid
         while True:
-            await asyncio.sleep(10)
             try:
-                expired = self.registry.check_ttl()
-                for mid in expired:
-                    self.event_hub.publish_internal(
-                        "module.offline", {"module_id": mid}, source=self.module_id)
+                await asyncio.sleep(20)
+
+                # Record ping send time for all connected modules
+                t1 = time.time()
+                for module_id in list(self.connections.keys()):
+                    self._ping_sent_times[module_id] = t1
+                    # Mark as timeout if previous ping didn't get pong
+                    if module_id in self._pong_status:
+                        if self._pong_status[module_id] == "ok":
+                            # Previous was ok, now waiting for new pong
+                            pass
+                        elif self._pong_status[module_id] == "never":
+                            # Still never received pong
+                            pass
+                        # If was timeout, keep it as timeout until pong arrives
+
+                # Broadcast system.ping event
+                self.event_hub.publish_internal(
+                    "system.ping",
+                    {"ping_time": t1},
+                    source=self.module_id
+                )
+
+                # Check for timeouts after 20s
+                await asyncio.sleep(20)
+                t_check = time.time()
+                for module_id in list(self.connections.keys()):
+                    if module_id in self._ping_sent_times:
+                        # If no pong received within 20s, mark as timeout
+                        if module_id not in self._pong_latencies or \
+                           self._pong_latencies[module_id].get("last_update", 0) < self._ping_sent_times[module_id]:
+                            if self._pong_status.get(module_id) == "never":
+                                # Keep as "never" if never received
+                                pass
+                            else:
+                                self._pong_status[module_id] = "timeout"
+                                print(f"[kernel] {module_id} ping timeout (no pong in 20s)")
+
+            except asyncio.CancelledError:
+                break
             except Exception as e:
-                print(f"[kernel] TTL loop error: {e}")
+                print(f"[kernel] Ping broadcast loop error: {e}")
 
     async def _dedup_loop(self):
         """Clean up dedup table every 30s."""
@@ -325,10 +368,13 @@ class KernelServer:
 
     def publish_ready(self):
         """Publish module.ready event for Kernel (internal, no WS needed)."""
+        import time
+        startup_time = time.monotonic() - self.boot_t0 if self.boot_t0 else 0
         self.event_hub.publish_internal("module.ready", {
             "module_id": self.module_id,
             "ws_endpoint": f"ws://{self.advertise_ip}:{self.port}/ws",
             "graceful_shutdown": True,
+            "startup_time": startup_time,
         }, source=self.module_id)
 
     async def _handle_internal_event(self, event_type: str, data: dict):
@@ -347,6 +393,8 @@ class KernelServer:
             # 处理 Kernel 订阅的事件
             if event_type == "module.shutdown":
                 await self.handle_shutdown_event(data)
+            elif event_type == "system.pong":
+                await self._handle_pong_event(data)
             # 忽略系统广播事件（Kernel 没有订阅但会收到广播）
             elif event_type in ("module.ready", "module.registered", "module.started",
                                 "module.stopped", "module.crashed", "module.exiting",
@@ -363,6 +411,47 @@ class KernelServer:
             traceback.print_exc()
             raise  # 重新抛出，让 EventHub 的包装器记录
 
+    async def _handle_pong_event(self, data: dict):
+        """处理 system.pong 事件，计算往返延迟
+
+        Args:
+            data: {
+                "module_id": str,
+                "ping_time": float,  # t1 - Kernel 发送 ping 的时间
+                "pong_time": float,  # t2 - 模块收到 ping 并发送 pong 的时间
+            }
+        """
+        import time
+        module_id = data.get("module_id")
+        t1 = data.get("ping_time")  # Kernel 发送 ping 的时间
+        t2 = data.get("pong_time")  # 模块收到 ping 并发送 pong 的时间
+        t3 = time.time()  # Kernel 收到 pong 的时间
+
+        if not module_id or t1 is None or t2 is None:
+            print(f"[kernel] Invalid pong event data: {data}")
+            return
+
+        # 验证 ping_time 是否匹配
+        if module_id not in self._ping_sent_times:
+            print(f"[kernel] Received pong from {module_id} but no ping record")
+            return
+
+        expected_t1 = self._ping_sent_times[module_id]
+        if abs(t1 - expected_t1) > 0.1:  # 允许 100ms 误差
+            print(f"[kernel] Pong from {module_id} has mismatched ping_time (expected {expected_t1}, got {t1})")
+            return
+
+        # 计算两个延迟
+        outbound_ms = (t2 - t1) * 1000  # 去程：Kernel → 模块
+        inbound_ms = (t3 - t2) * 1000   # 回程：模块 → Kernel
+
+        self._pong_latencies[module_id] = {
+            "outbound": round(outbound_ms, 2),
+            "inbound": round(inbound_ms, 2),
+            "last_update": t3,
+        }
+        self._pong_status[module_id] = "ok"
+
     async def handle_shutdown_event(self, event_data):
         """处理 module.shutdown 事件（标准优雅退出流程）
 

package/kite_cli/commands/deps_install.py

@@ -0,0 +1,67 @@
+"""
+kite deps-install 命令
+
+只负责安装依赖库
+"""
+
+import sys
+from pathlib import Path
+
+
+def run_deps_install(args):
+    """安装依赖库"""
+    project_root = Path(__file__).parent.parent.parent
+    sys.path.insert(0, str(project_root))
+
+    from core.env_checker import (
+        check_dependencies_installed,
+        install_dependencies,
+        load_dependencies_lock
+    )
+
+    print("=" * 60)
+    print("  Kite 依赖库安装")
+    print("=" * 60)
+    print()
+
+    try:
+        # 1. 加载依赖锁定
+        lock_data = load_dependencies_lock()
+        if not lock_data:
+            print("✓ 无依赖锁定文件，跳过")
+            return 0
+
+        dependencies = lock_data.get("dependencies", {})
+        if not dependencies:
+            print("✓ 无依赖要求，跳过")
+            return 0
+
+        print(f"依赖锁定文件: {len(dependencies)} 个依赖")
+
+        # 2. 检查依赖
+        deps_ok, deps_msg, deps_details = check_dependencies_installed()
+        if deps_ok:
+            print(f"✓ 依赖库已安装且版本一致")
+            return 0
+
+        # 3. 安装依赖
+        print(f"✗ {deps_msg}")
+        if deps_details:
+            if deps_details.get("missing"):
+                print(f"  缺失: {len(deps_details['missing'])} 个")
+            if deps_details.get("version_mismatch"):
+                print(f"  版本不匹配: {len(deps_details['version_mismatch'])} 个")
+
+        print(f"\n正在安装依赖...")
+        if not install_dependencies():
+            print("✗ 依赖安装失败")
+            return 1
+
+        print(f"✓ 依赖安装成功")
+        return 0
+
+    except Exception as e:
+        print(f"\n✗ 依赖安装失败: {e}")
+        import traceback
+        traceback.print_exc()
+        return 1

package/kite_cli/commands/env_check.py

@@ -0,0 +1,45 @@
+"""
+kite env-check 命令
+
+环境检查和准备：
+1. 检查虚拟环境是否存在
+2. 检查依赖库是否安装且版本一致
+3. 创建虚拟环境（如果需要）
+4. 安装依赖库（如果需要）
+"""
+
+import sys
+from pathlib import Path
+
+
+def run_env_check(args):
+    """执行环境检查"""
+    # 导入环境检查器
+    project_root = Path(__file__).parent.parent.parent
+
+    # 添加到 sys.path
+    sys.path.insert(0, str(project_root))
+
+    # 导入并执行环境检查
+    from core.env_checker import check_environment
+
+    print("=" * 60)
+    print("  Kite 环境检查")
+    print("=" * 60)
+    print()
+
+    try:
+        success = check_environment()
+
+        if success:
+            print("\n✓ 环境检查通过")
+            return 0
+        else:
+            print("\n✗ 环境检查失败")
+            return 1
+
+    except Exception as e:
+        print(f"\n✗ 环境检查异常: {e}")
+        import traceback
+        traceback.print_exc()
+        return 1

package/kite_cli/commands/prepare.py

@@ -0,0 +1,49 @@
+"""
+kite prepare 命令
+
+打包前的准备工作：
+1. 扫描所有模块的依赖
+2. 生成 dependencies_lock.json
+3. 更新 python_version.json
+"""
+
+import sys
+from pathlib import Path
+
+
+def run_prepare(args):
+    """执行打包准备"""
+    # 导入扫描脚本
+    project_root = Path(__file__).parent.parent.parent
+
+    # 添加到 sys.path
+    sys.path.insert(0, str(project_root))
+
+    # 导入并执行扫描
+    from scripts.scan_dependencies import main as scan_main
+
+    print("=" * 60)
+    print("  Kite 打包准备")
+    print("=" * 60)
+    print()
+
+    try:
+        scan_main()
+        print()
+        print("✓ 打包准备完成")
+        print()
+        print("生成的文件:")
+        print(f"  - {project_root / 'dependencies_lock.json'}")
+        print(f"  - {project_root / 'python_version.json'}")
+        print()
+        print("下一步:")
+        print("  1. 检查生成的文件")
+        print("  2. 提交到 git: git add dependencies_lock.json python_version.json")
+        print("  3. 发布: npm publish")
+        return 0
+
+    except Exception as e:
+        print(f"\n✗ 打包准备失败: {e}")
+        import traceback
+        traceback.print_exc()
+        return 1

package/kite_cli/commands/venv_setup.py

@@ -0,0 +1,56 @@
+"""
+kite venv-setup 命令
+
+只负责创建虚拟环境
+"""
+
+import sys
+from pathlib import Path
+
+
+def run_venv_setup(args):
+    """创建虚拟环境"""
+    project_root = Path(__file__).parent.parent.parent
+    sys.path.insert(0, str(project_root))
+
+    from core.env_checker import (
+        get_venv_path,
+        check_venv_exists,
+        create_venv,
+        check_python_version
+    )
+
+    print("=" * 60)
+    print("  Kite 虚拟环境准备")
+    print("=" * 60)
+    print()
+
+    try:
+        # 1. 检查 Python 版本
+        py_ok, py_version, required_version = check_python_version()
+        if not py_ok:
+            print(f"✗ Python 版本不匹配: {py_version}（需要 {required_version}）")
+            return 1
+
+        print(f"✓ Python 版本: {py_version}")
+
+        # 2. 检查虚拟环境
+        venv_ok, venv_msg = check_venv_exists()
+        if venv_ok:
+            print(f"✓ 虚拟环境已存在: {get_venv_path()}")
+            return 0
+
+        # 3. 创建虚拟环境
+        print(f"正在创建虚拟环境...")
+        if not create_venv():
+            print("✗ 虚拟环境创建失败")
+            return 1
+
+        print(f"✓ 虚拟环境创建成功: {get_venv_path()}")
+        return 0
+
+    except Exception as e:
+        print(f"\n✗ 虚拟环境准备失败: {e}")
+        import traceback
+        traceback.print_exc()
+        return 1