@agentunion/kite 1.3.2 → 1.5.0

package/extensions/services/web/entry.py

@@ -26,7 +26,113 @@ import uvicorn
 
 
 # ── Module configuration ──
-MODULE_NAME = "web"
+
+def _load_module_config() -> dict:
+    """Load module configuration from module.md frontmatter.
+
+    Returns:
+        Dict with keys: name, preferred_port, advertise_ip
+
+    Raises:
+        SystemExit: If module.md is invalid or name is non-compliant
+    """
+    _this_dir = os.path.dirname(os.path.abspath(__file__))
+    module_md = os.path.join(_this_dir, "module.md")
+
+    # Calculate relative path for error messages
+    project_root = os.environ.get("KITE_PROJECT", "")
+    if project_root and _this_dir.startswith(project_root):
+        rel_path = os.path.relpath(_this_dir, project_root)
+    else:
+        rel_path = _this_dir
+
+    # Default values (will be overridden if valid config exists)
+    result = {
+        "name": "",
+        "preferred_port": 0,
+        "advertise_ip": "0.0.0.0"
+    }
+
+    # Check if module.md exists
+    if not os.path.exists(module_md):
+        print(f"[{rel_path}] ERROR: Invalid module configuration in module.md")
+        print(f"  Path: {rel_path}/module.md")
+        print(f"  Reason: File not found")
+        sys.exit(1)
+
+    try:
+        with open(module_md, encoding="utf-8") as f:
+            text = f.read()
+
+        # Extract YAML frontmatter (between --- markers)
+        import re
+        m = re.match(r'^---\s*\n(.*?)\n---', text, re.DOTALL)
+        if not m:
+            print(f"[{rel_path}] ERROR: Invalid module configuration in module.md")
+            print(f"  Path: {rel_path}/module.md")
+            print(f"  Reason: Missing YAML frontmatter")
+            sys.exit(1)
+
+        # Parse YAML frontmatter
+        try:
+            import yaml
+            fm = yaml.safe_load(m.group(1)) or {}
+        except ImportError:
+            print(f"[{rel_path}] ERROR: PyYAML not installed, cannot parse module.md")
+            sys.exit(1)
+        except Exception as e:
+            print(f"[{rel_path}] ERROR: Invalid module configuration in module.md")
+            print(f"  Path: {rel_path}/module.md")
+            print(f"  Reason: YAML parse error: {e}")
+            sys.exit(1)
+
+        # Validate 'name' field (required)
+        if "name" not in fm:
+            print(f"[{rel_path}] ERROR: Invalid module configuration in module.md")
+            print(f"  Path: {rel_path}/module.md")
+            print(f"  Reason: Missing 'name' field")
+            sys.exit(1)
+
+        raw_name = str(fm["name"]).strip()
+
+        if not raw_name:
+            print(f"[{rel_path}] ERROR: Invalid module configuration in module.md")
+            print(f"  Path: {rel_path}/module.md")
+            print(f"  Reason: Empty module name")
+            sys.exit(1)
+
+        # Validate name characters
+        sanitized = re.sub(r'[^a-zA-Z0-9_\-]', '', raw_name)
+
+        if sanitized != raw_name:
+            invalid_chars = ''.join(sorted(set(c for c in raw_name if c not in sanitized)))
+            print(f"[{rel_path}] ERROR: Invalid module configuration in module.md")
+            print(f"  Path: {rel_path}/module.md")
+            print(f"  Reason: Invalid characters in name '{raw_name}': {repr(invalid_chars)}")
+            sys.exit(1)
+
+        result["name"] = sanitized
+
+        # Extract optional fields
+        if "preferred_port" in fm:
+            try:
+                result["preferred_port"] = int(fm["preferred_port"])
+            except (ValueError, TypeError):
+                pass
+
+        if "advertise_ip" in fm:
+            result["advertise_ip"] = str(fm["advertise_ip"])
+
+    except SystemExit:
+        raise  # Re-raise exit to prevent catching by outer except
+    except Exception as e:
+        print(f"[{rel_path}] ERROR: Failed to read module.md: {e}")
+        sys.exit(1)
+
+    return result
+
+_module_config = _load_module_config()
+MODULE_NAME = _module_config["name"]
 
 
 class _SafeWriter:
@@ -251,27 +357,6 @@ def _fmt_elapsed(t0: float) -> str:
     return f"{d:.0f}s"
 
 
-def _read_module_md() -> dict:
-    """Read preferred_port and advertise_ip from own module.md."""
-    md_path = os.path.join(_this_dir, "module.md")
-    result = {"preferred_port": 0, "advertise_ip": "0.0.0.0"}
-    try:
-        with open(md_path, "r", encoding="utf-8") as f:
-            text = f.read()
-        m = re.match(r'^---\s*\n(.*?)\n---', text, re.DOTALL)
-        if m:
-            try:
-                import yaml
-                fm = yaml.safe_load(m.group(1)) or {}
-            except ImportError:
-                fm = {}
-            result["preferred_port"] = int(fm.get("preferred_port", 0))
-            result["advertise_ip"] = fm.get("advertise_ip", "0.0.0.0")
-    except Exception:
-        pass
-    return result
-
-
 def _bind_port(preferred: int, host: str, max_attempts: int = 10) -> int | None:
     """
     Try to bind to preferred port, then port+1, port+2, ... up to max_attempts.
@@ -351,10 +436,9 @@ def main():
 
     print(f"[web] Token received ({len(token)} chars), kernel port: {kernel_port} ({_fmt_elapsed(_t0)})")
 
-    # Read preferred_port from module.md
-    md_cfg = _read_module_md()
-    host = md_cfg["advertise_ip"]
-    port = _bind_port(md_cfg["preferred_port"], host)
+    # Use cached module config (already loaded at module level)
+    host = _module_config["advertise_ip"]
+    port = _bind_port(_module_config["preferred_port"], host)
 
     # If port binding failed after 10 attempts, exit gracefully
     if port is None:
@@ -385,6 +469,10 @@ def main():
         _print_crash_summary(type(e), e.__traceback__)
         sys.exit(1)
 
+    # Check if server requested exit with non-zero code
+    if server._exit_code != 0:
+        sys.exit(server._exit_code)
+
 
 if __name__ == "__main__":
     main()

package/extensions/services/web/module.md

@@ -1,24 +1,35 @@
----
-name: web
-display_name: Web Management
-version: "1.0"
-type: service
-state: enabled
-runtime: python
-entry: entry.py
-preferred_port: 18766
-advertise_ip: 0.0.0.0
-events:
-  - web.test
-subscriptions:
-  - module.started
-  - module.stopped
-  - module.shutdown
----
-
-# Web Management（Web 管理界面）
-
-Web 管理界面模块，提供系统管理和监控的 Web UI。
-
-- 管理界面 — 提供系统配置和状态监控的 Web UI
-- 事件通知 — 通过 Event Hub 发布管理操作事件
+---
+name: web
+display_name: Web Management
+version: '1.0'
+type: service
+state: manual
+runtime: python
+entry: entry.py
+preferred_port: 18766
+advertise_ip: 0.0.0.0
+events:
+- web.test
+subscriptions:
+- module.started
+- module.stopped
+- module.shutdown
+
+# 业务配置列表
+businesses:
+  - name: web_server
+    type: http_service
+    description: Web 管理界面和 API 服务
+    config_file: web_config.json5
+
+  - name: relay_service
+    type: kernel_relay
+    description: Kernel WebSocket 中转服务
+    config_file: relay_config.json5
+---
+# Web Management（Web 管理界面）
+
+Web 管理界面模块，提供系统管理和监控的 Web UI。
+
+- 管理界面 — 提供系统配置和状态监控的 Web UI
+- 事件通知 — 通过 Event Hub 发布管理操作事件

package/extensions/services/web/pairing.py

@@ -0,0 +1,250 @@
+"""
+配对码管理模块
+
+负责配对码的生成、验证、使用和 frontend_token 的管理。
+
+零共享代码依赖 - 此文件可以独立拷贝到其他模块使用。
+"""
+
+import json
+import os
+import secrets
+import string
+import time
+from datetime import datetime, timezone
+from typing import Optional
+
+
+class PairingManager:
+    """配对码管理器"""
+
+    def __init__(self, pairing_file: str, code_length: int = 6, token_expiry: int = 2592000):
+        """
+        初始化配对码管理器。
+
+        Args:
+            pairing_file: 配对码文件路径（JSONL 格式）
+            code_length: 配对码长度（默认 6）
+            token_expiry: frontend_token 有效期（秒，默认 30 天）
+        """
+        self.pairing_file = pairing_file
+        self.code_length = code_length
+        self.token_expiry = token_expiry
+
+        # 临时配对码（未持久化）
+        self.pending_codes = {}  # {code: {"role": "admin", "created_at": timestamp}}
+
+        # 确保文件存在
+        if not os.path.exists(pairing_file):
+            os.makedirs(os.path.dirname(pairing_file), exist_ok=True)
+
+    def generate_pairing_code(self, role: str = "admin") -> str:
+        """
+        生成临时配对码（不持久化）。
+
+        Args:
+            role: 用户角色
+
+        Returns:
+            配对码
+        """
+        code = self._generate_code()
+        self.pending_codes[code] = {
+            "role": role,
+            "created_at": time.time()
+        }
+
+        # 清理过期的配对码（超过 5 分钟）
+        self._cleanup_expired_codes()
+
+        return code
+
+    def _cleanup_expired_codes(self):
+        """清理过期的临时配对码"""
+        now = time.time()
+        expired = [
+            code for code, info in self.pending_codes.items()
+            if now - info["created_at"] > 300  # 5 分钟
+        ]
+        for code in expired:
+            del self.pending_codes[code]
+
+    def _ensure_active_code(self):
+        """确保有 active 状态的配对码，如果没有则生成（已废弃）"""
+        pass
+
+    def _print_pairing_code(self, code: str, is_new: bool):
+        """在控制台绿色高亮显示配对码（已废弃，改为通过事件发送给 Launcher）"""
+        pass
+
+    def _create_initial_code(self):
+        """创建初始配对码（已废弃，由 _ensure_active_code 替代）"""
+        pass
+
+    def _generate_code(self) -> str:
+        """生成随机配对码"""
+        chars = string.ascii_uppercase + string.digits
+        return ''.join(secrets.choice(chars) for _ in range(self.code_length))
+
+    def _generate_token(self) -> str:
+        """生成 frontend_token"""
+        return "tok_" + secrets.token_urlsafe(32)
+
+    def _read_codes(self) -> list[dict]:
+        """读取所有配对码记录"""
+        if not os.path.exists(self.pairing_file):
+            return []
+
+        codes = []
+        with open(self.pairing_file, "r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if line:
+                    try:
+                        codes.append(json.loads(line))
+                    except json.JSONDecodeError:
+                        pass
+        return codes
+
+    def _write_code(self, code_record: dict):
+        """追加配对码记录"""
+        with open(self.pairing_file, "a", encoding="utf-8") as f:
+            f.write(json.dumps(code_record, ensure_ascii=False) + "\n")
+
+    def verify_code(self, code: str) -> Optional[dict]:
+        """
+        验证配对码（包括临时配对码和持久化配对码）。
+
+        Args:
+            code: 配对码
+
+        Returns:
+            如果有效，返回配对码信息（包含 role）；否则返回 None
+        """
+        # 先检查临时配对码
+        if code in self.pending_codes:
+            info = self.pending_codes[code]
+            # 检查是否过期（5 分钟）
+            if time.time() - info["created_at"] < 300:
+                return {"code": code, "role": info["role"], "status": "pending"}
+
+        # 再检查持久化配对码（向后兼容）
+        codes = self._read_codes()
+        for record in reversed(codes):
+            if record.get("code") == code and record.get("status") == "active":
+                return record
+
+        return None
+
+    def pair(self, code: str) -> Optional[dict]:
+        """
+        使用配对码进行配对。
+
+        Args:
+            code: 配对码
+
+        Returns:
+            如果成功，返回 {"token": "...", "role": "..."}；否则返回 None
+        """
+        # 验证配对码
+        code_info = self.verify_code(code)
+        if not code_info:
+            return None
+
+        # 生成 frontend_token
+        token = self._generate_token()
+        role = code_info.get("role", "viewer")
+
+        # 持久化保存 token
+        used_record = {
+            "code": code,
+            "role": role,
+            "status": "used",
+            "token": token,
+            "paired_at": datetime.now(timezone.utc).isoformat(),
+            "expires_at": datetime.fromtimestamp(
+                time.time() + self.token_expiry, tz=timezone.utc
+            ).isoformat()
+        }
+        self._write_code(used_record)
+
+        # 从临时配对码中删除
+        if code in self.pending_codes:
+            del self.pending_codes[code]
+
+        return {
+            "token": token,
+            "role": role,
+            "expires_at": used_record["expires_at"]
+        }
+
+    def verify_token(self, token: str) -> Optional[dict]:
+        """
+        验证 frontend_token。
+
+        Args:
+            token: frontend_token
+
+        Returns:
+            如果有效，返回 {"role": "...", "expires_at": "..."}；否则返回 None
+        """
+        codes = self._read_codes()
+
+        # 检查 token 是否被吊销
+        for record in reversed(codes):
+            if record.get("token") == token and record.get("status") == "revoked":
+                return None  # Token 已被吊销
+
+        # 查找 token 对应的记录
+        for record in reversed(codes):
+            if record.get("token") == token and record.get("status") == "used":
+                # 检查是否过期
+                expires_at = record.get("expires_at")
+                if expires_at:
+                    expire_time = datetime.fromisoformat(expires_at)
+                    if datetime.now(timezone.utc) < expire_time:
+                        return {
+                            "role": record.get("role", "viewer"),
+                            "expires_at": expires_at
+                        }
+
+        return None
+
+    def renew_token(self, old_token: str) -> Optional[str]:
+        """
+        续期 frontend_token。
+
+        Args:
+            old_token: 旧的 frontend_token
+
+        Returns:
+            如果成功，返回新的 token；否则返回 None
+        """
+        # 验证旧 token
+        token_info = self.verify_token(old_token)
+        if not token_info:
+            return None
+
+        # 生成新 token
+        new_token = self._generate_token()
+        role = token_info["role"]
+
+        # 写入新 token 记录
+        new_record = {
+            "token": new_token,
+            "role": role,
+            "status": "used",
+            "renewed_from": old_token,
+            "paired_at": datetime.now(timezone.utc).isoformat(),
+            "expires_at": datetime.fromtimestamp(
+                time.time() + self.token_expiry, tz=timezone.utc
+            ).isoformat()
+        }
+        self._write_code(new_record)
+
+        return new_token
+
+    def get_active_codes(self) -> list[dict]:
+        """获取所有 active 状态的配对码"""
+        codes = self._read_codes()
+        return [c for c in codes if c.get("status") == "active"]

package/extensions/services/web/pairing_codes.jsonl

@@ -0,0 +1,16 @@
+{"code": "Z02ZRG", "role": "admin", "status": "active", "created_at": "2026-03-05T15:47:25.324158+00:00"}
+{"code": "6LL9JO", "role": "admin", "status": "used", "token": "tok_bRHd1ci_m5ziNGhGrza-OVUFqiu5dukqVUnZP3DB5rM", "paired_at": "2026-03-05T16:15:24.338472+00:00", "expires_at": "2026-04-04T16:15:24.338483+00:00"}
+{"code": "1KEKFO", "role": "admin", "status": "used", "token": "tok_mQRErFLfPTOd5iuMM0tR3HlsL-ZwRjaoqAOsrd3f7o0", "paired_at": "2026-03-05T16:19:32.214747+00:00", "expires_at": "2026-04-04T16:19:32.214758+00:00"}
+{"token": "tok_bRHd1ci_m5ziNGhGrza-OVUFqiu5dukqVUnZP3DB5rM", "status": "revoked", "revoked_at": "2026-03-05T17:16:47.003028+00:00"}
+{"token": "tok_mQRErFLfPTOd5iuMM0tR3HlsL-ZwRjaoqAOsrd3f7o0", "status": "revoked", "revoked_at": "2026-03-05T17:16:51.276194+00:00"}
+{"code": "62DLAO", "role": "admin", "status": "used", "token": "tok_xUecpGG2v64ET3OIvLvmMZx73AhwMH3GvbuFVYeWThQ", "paired_at": "2026-03-05T17:19:27.498121+00:00", "expires_at": "2026-04-04T17:19:27.498131+00:00"}
+{"token": "tok_xUecpGG2v64ET3OIvLvmMZx73AhwMH3GvbuFVYeWThQ", "status": "revoked", "revoked_at": "2026-03-05T17:19:52.246926+00:00"}
+{"code": "B2KC73", "role": "admin", "status": "used", "token": "tok_mtdU9v_mqwtx5Vzq4NpWL7X8oN_te9G3mKYKbyJ3KJQ", "paired_at": "2026-03-05T17:20:02.715650+00:00", "expires_at": "2026-04-04T17:20:02.715660+00:00"}
+{"token": "tok_mtdU9v_mqwtx5Vzq4NpWL7X8oN_te9G3mKYKbyJ3KJQ", "status": "revoked", "revoked_at": "2026-03-05T17:24:19.299991+00:00"}
+{"code": "RR46UW", "role": "admin", "status": "used", "token": "tok_okmAev1nyxMTpZr5NeIYR5i0GOoQBiBsyu-7O5Zt-bY", "paired_at": "2026-03-05T17:24:42.072484+00:00", "expires_at": "2026-04-04T17:24:42.072494+00:00"}
+{"token": "tok_okmAev1nyxMTpZr5NeIYR5i0GOoQBiBsyu-7O5Zt-bY", "status": "revoked", "revoked_at": "2026-03-05T17:24:46.132417+00:00"}
+{"code": "HUBWSE", "role": "admin", "status": "used", "token": "tok_ycxZ6hbiHg1xmuTbUX7yivvy__YMVYIn6cKvtuDPrM0", "paired_at": "2026-03-05T17:37:23.438551+00:00", "expires_at": "2026-04-04T17:37:23.438560+00:00"}
+{"token": "tok_ycxZ6hbiHg1xmuTbUX7yivvy__YMVYIn6cKvtuDPrM0", "status": "revoked", "revoked_at": "2026-03-05T17:37:43.801272+00:00"}
+{"code": "15Q4QJ", "role": "admin", "status": "used", "token": "tok_byVOicuvkitvDTQRuh05XQpmtAdyUineSddRCi5MHbs", "paired_at": "2026-03-05T17:38:50.616922+00:00", "expires_at": "2026-04-04T17:38:50.616932+00:00"}
+{"token": "tok_byVOicuvkitvDTQRuh05XQpmtAdyUineSddRCi5MHbs", "status": "revoked", "revoked_at": "2026-03-06T07:55:02.015491+00:00"}
+{"code": "7N5Q43", "role": "admin", "status": "used", "token": "tok_J8zYOS5OKcHkEyOzIFRD_sHbq61ngWqyoxlVQrDdhyA", "paired_at": "2026-03-06T07:55:19.446442+00:00", "expires_at": "2026-04-05T07:55:19.446452+00:00"}