@agentunion/kite 1.4.0 → 1.6.0

package/docs//346/227/245/345/277/227/344/270/216/345/274/202/345/270/270/345/244/204/347/220/206/350/247/204/350/214/203.md

@@ -0,0 +1,829 @@
+# Kite 异常处理规范
+
+## 概述
+
+本文档定义 Kite 框架的异常处理与日志记录机制。所有规范基于环境变量和文件约定，**不依赖任何共享代码库**，确保跨平台（Windows/Linux/macOS）、跨语言（Python/Node.js/Binary）、跨进程完全兼容。
+
+各模块独立实现本规范，仅需遵守：路径约定、文件格式、事件协议。
+
+---
+
+## 1. 日志体系
+
+### 1.1 完整目录布局
+
+每个模块（包括启动器）统一使用 `KITE_MODULE_DATA` 环境变量构建日志路径：
+
+```
+{KITE_MODULE_DATA}/
+└── log/
+    ├── latest.log              # 常规日志（每次启动清空）
+    ├── crashes.jsonl           # 崩溃日志（每次启动清空）
+    ├── crashes/                # 崩溃按日归档
+    │   └── {YYYY-MM}/
+    │       └── {YYYY-MM-DD}.jsonl
+    └── {YYYY-MM}/              # 常规日志按日归档
+        └── {YYYY-MM-DD}.log
+```
+
+**实际路径示例：**
+
+```
+{KITE_INSTANCE_DIR}/
+├── launcher/log/
+│   ├── latest.log
+│   ├── crashes.jsonl
+│   ├── crashes/2026-03/2026-03-02.jsonl
+│   └── 2026-03/2026-03-02.log
+│
+├── registry/log/
+│   ├── latest.log
+│   ├── crashes.jsonl
+│   ├── crashes/2026-03/2026-03-02.jsonl
+│   └── 2026-03/2026-03-02.log
+│
+├── event_hub/log/
+│   └── ...（同上）
+│
+├── web/log/
+│   └── ...（同上）
+│
+└── {module_name}/log/
+    └── ...（同上）
+```
+
+### 1.2 路径构造规则
+
+**所有路径从 `KITE_MODULE_DATA` 环境变量出发：**
+
+```python
+# Python
+import os
+log_dir       = os.path.join(os.environ["KITE_MODULE_DATA"], "log")
+latest_log    = os.path.join(log_dir, "latest.log")
+crash_log     = os.path.join(log_dir, "crashes.jsonl")
+crash_archive = os.path.join(log_dir, "crashes", "2026-03", "2026-03-02.jsonl")
+daily_log     = os.path.join(log_dir, "2026-03", "2026-03-02.log")
+```
+
+```javascript
+// Node.js
+const path = require('path');
+const logDir      = path.join(process.env.KITE_MODULE_DATA, 'log');
+const latestLog   = path.join(logDir, 'latest.log');
+const crashLog    = path.join(logDir, 'crashes.jsonl');
+const crashArchive= path.join(logDir, 'crashes', '2026-03', '2026-03-02.jsonl');
+const dailyLog    = path.join(logDir, '2026-03', '2026-03-02.log');
+```
+
+### 1.3 文件生命周期
+
+| 文件 | 内容 | 启动时 | 运行时 | 归档 |
+|------|------|--------|--------|------|
+| `latest.log` | 所有常规日志 | **清空** | 追加写入 | 同时写入按日 `.log` |
+| `crashes.jsonl` | 本次运行的崩溃记录 | **清空** | 追加写入 | 同时写入按日 `.jsonl` |
+| `{YYYY-MM}/{YYYY-MM-DD}.log` | 常规日志按日归档 | 不清空 | 追加写入 | 累积保留 |
+| `crashes/{YYYY-MM}/{YYYY-MM-DD}.jsonl` | 崩溃日志按日归档 | 不清空 | 追加写入 | 累积保留 |
+
+**要点：**
+
+- `latest.log` 和 `crashes.jsonl` 每次模块启动时清空，只包含本次运行的内容
+- 按日归档文件跨启动累积，是长期记录
+- 大模型或调试工具读取 `crashes.jsonl` 只看到当次运行的崩溃，不会被历史淹没
+
+### 1.4 latest.log 规范
+
+**每个模块都必须实现 `latest.log`**，不仅仅是启动器。
+
+**要求：**
+
+1. 路径: `{KITE_MODULE_DATA}/log/latest.log`
+2. 每次模块启动时清空（截断为空文件）
+3. 运行期间所有常规日志追加写入
+4. 同时写入按日归档 `{KITE_MODULE_DATA}/log/{YYYY-MM}/{YYYY-MM-DD}.log`
+5. 写入操作应加锁（多线程安全）
+6. 使用 open-write-close 模式（不持有文件句柄），确保崩溃前数据已落盘
+
+**用途：** 调试时查看任何模块的最后一次执行情况。
+
+### 1.5 日志输出文本格式
+
+**所有模块的日志输出必须遵循统一格式**，确保日志可读性和一致性。
+
+#### 标准格式
+
+```
+[时间戳] HH:MM:SS.mmm  +增量时间 [模块名] 日志内容
+```
+
+**字段说明：**
+
+| 字段 | 格式 | 说明 | 示例 |
+|------|------|------|------|
+| 时间戳 | `[xxxms]` / `[x.xs]` / `[xxxxs]` | 从模块启动开始的累计时间，右对齐 | `[ 696ms]`、`[  1.4s]`、`[34399s]` |
+| 当前时间 | `HH:MM:SS.mmm` | 24小时制，精确到毫秒 | `13:03:17.843` |
+| 增量时间 | `+xxxms` / `+x.xs` | 距离上一条日志的时间差，右对齐 | `+1ms`、`+199ms`、`+10.0s` |
+| 模块名 | `[name]` | 模块标识，小写，下划线分隔 | `[launcher]`、`[event_hub]`、`[web]` |
+| 日志内容 | 任意文本 | 实际的日志消息 | `Kite 启动中...` |
+
+#### 格式示例
+
+```
+[ 696ms] 13:03:17.843          [launcher] Kite 启动中...
+[ 696ms] 13:03:17.844     +1ms [launcher] 日志: C:\Users\...
+[ 697ms] 13:03:17.844     +0ms [launcher] ── 环境 ──
+[ 904ms] 13:03:18.052   +199ms [launcher] 已启动 registry (PID 15504)
+[  1.4s] 13:03:18.596          [registry] 已收到启动器令牌 (64 字符) (0ms)
+[  1.5s] 13:03:18.618   +526ms [launcher] Registry 端口: 63789 (等待 592ms)
+[  3.1s] 13:03:20.271    +1.6s [launcher] 发现 11 个模块 (扫描 24ms)
+```
+
+#### 实现要点
+
+1. **时间戳对齐** — 使用固定宽度（6 字符），右对齐，左侧填充空格
+2. **增量时间对齐** — 使用固定宽度（8 字符），右对齐，首行可留空
+3. **单位自动切换** — 小于 1000ms 显示 `ms`，大于等于 1s 显示 `s`（保留 1 位小数）
+4. **模块名固定** — 每个模块硬编码自己的名称，与 `module.md` 中的 `name` 字段一致
+5. **ANSI 转义码** — 控制台输出可使用颜色（如红色错误），但写入文件时必须剥离
+
+#### Python 实现参考
+
+```python
+import time
+from datetime import datetime
+
+class LogFormatter:
+    def __init__(self, module_name: str):
+        self.module_name = module_name
+        self.start_time = time.perf_counter()
+        self.last_time = self.start_time
+
+    def format(self, message: str) -> str:
+        now = time.perf_counter()
+        elapsed = now - self.start_time
+        delta = now - self.last_time
+        self.last_time = now
+
+        # 时间戳（累计）
+        if elapsed < 1:
+            ts = f"{elapsed * 1000:5.0f}ms"
+        else:
+            ts = f"{elapsed:5.1f}s"
+
+        # 增量时间
+        if delta < 0.001:
+            delta_str = " " * 8  # 首行或极短间隔留空
+        elif delta < 1:
+            delta_str = f"+{delta * 1000:.0f}ms".rjust(8)
+        else:
+            delta_str = f"+{delta:.1f}s".rjust(8)
+
+        # 当前时间
+        current = datetime.now().strftime("%H:%M:%S.%f")[:-3]
+
+        return f"[{ts:>6}] {current} {delta_str} [{self.module_name}] {message}"
+
+# 使用示例
+logger = LogFormatter("my_module")
+print(logger.format("模块启动中..."))
+print(logger.format("配置已加载"))
+```
+
+#### Node.js 实现参考
+
+```javascript
+class LogFormatter {
+  constructor(moduleName) {
+    this.moduleName = moduleName;
+    this.startTime = performance.now();
+    this.lastTime = this.startTime;
+  }
+
+  format(message) {
+    const now = performance.now();
+    const elapsed = (now - this.startTime) / 1000;
+    const delta = (now - this.lastTime) / 1000;
+    this.lastTime = now;
+
+    // 时间戳（累计）
+    const ts = elapsed < 1
+      ? `${(elapsed * 1000).toFixed(0)}ms`.padStart(6)
+      : `${elapsed.toFixed(1)}s`.padStart(6);
+
+    // 增量时间
+    let deltaStr;
+    if (delta < 0.001) {
+      deltaStr = ' '.repeat(8);
+    } else if (delta < 1) {
+      deltaStr = `+${(delta * 1000).toFixed(0)}ms`.padStart(8);
+    } else {
+      deltaStr = `+${delta.toFixed(1)}s`.padStart(8);
+    }
+
+    // 当前时间
+    const current = new Date().toISOString().slice(11, 23);
+
+    return `[${ts}] ${current} ${deltaStr} [${this.moduleName}] ${message}`;
+  }
+}
+
+// 使用示例
+const logger = new LogFormatter('my_module');
+console.log(logger.format('模块启动中...'));
+console.log(logger.format('配置已加载'));
+```
+
+#### 特殊情况
+
+**跨模块日志聚合**（如启动器收集子模块输出）：
+
+- 保留原始模块名标签 `[module_name]`
+- 启动器可在前面添加自己的时间戳，但不修改原始格式
+- 示例：`[  1.5s] 13:03:18.672          [watchdog] Token received (64 chars)`
+
+**第三方库日志**（如 httpx、uvicorn）：
+
+- 如果第三方库输出包含自己的时间戳，保留原样
+- 在前面添加模块标签：`[web] 2026-03-02 13:03:19,642 [httpx] INFO: HTTP Request: POST ...`
+
+### 1.7 环境变量清单
+
+| 变量名 | 设置者 | 值 | 用途 |
+|--------|--------|------|------|
+| `KITE_MODULE_DATA` | Launcher | 启动器: `{KITE_INSTANCE_DIR}/launcher`<br>其他模块: `{KITE_INSTANCE_DIR}/{module_name}` | 构造所有日志路径的唯一基准 |
+| `KITE_INSTANCE_DIR` | Launcher | `{KITE_WORKSPACE}/{project_name}` | 实例根目录 |
+
+---
+
+## 2. 崩溃日志格式
+
+### 2.1 JSONL 格式规范
+
+每行一条 JSON 记录：
+
+```json
+{
+  "timestamp": "2026-03-02T09:15:23.456789+00:00",
+  "module": "web",
+  "thread": "MainThread",
+  "exception_type": "AttributeError",
+  "exception_message": "'WebSocketProtocol' object has no attribute 'transfer_data_task'",
+  "traceback": "Traceback (most recent call last):\n  File \"server.py\", line 199, in ws_endpoint\n    await ws.close(code=4001)\nAttributeError: ...",
+  "context": {
+    "function": "ws_endpoint",
+    "file": "server.py",
+    "line": 199
+  },
+  "severity": "critical",
+  "handled": false,
+  "process_id": 12345,
+  "platform": "win32",
+  "runtime_version": "Python 3.13.0"
+}
+```
+
+### 2.2 字段说明
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `timestamp` | string | ✓ | ISO 8601 格式，带时区 |
+| `module` | string | ✓ | 模块名称（如 `launcher`, `web`, `registry`） |
+| `thread` | string | ✓ | 线程名称（如 `MainThread`, `Thread-1`） |
+| `exception_type` | string | ✓ | 异常类型（如 `NameError`, `AttributeError`） |
+| `exception_message` | string | ✓ | 异常消息 |
+| `traceback` | string | ✓ | 完整堆栈跟踪 |
+| `context` | object | ✗ | 异常发生位置 |
+| `context.function` | string | ✗ | 函数名 |
+| `context.file` | string | ✗ | 文件名（相对路径即可） |
+| `context.line` | number | ✗ | 行号 |
+| `severity` | string | ✓ | 严重级别：`critical` / `error` / `warning` |
+| `handled` | boolean | ✓ | `false` = 未捕获异常，`true` = 已捕获但仍值得记录 |
+| `process_id` | number | ✓ | 进程 PID |
+| `platform` | string | ✗ | 平台标识（`win32`, `linux`, `darwin`） |
+| `runtime_version` | string | ✗ | 运行时版本（`Python 3.13.0` / `Node.js v20.11.0`） |
+
+### 2.3 严重级别定义
+
+| 级别 | 含义 | 示例 |
+|------|------|------|
+| `critical` | 导致进程退出 | 主线程未捕获异常、核心功能崩溃 |
+| `error` | 功能失效但进程继续运行 | API 请求处理失败、后台任务崩溃、非关键线程异常 |
+| `warning` | 已处理，有降级方案 | 配置缺失用默认值、重试后成功 |
+
+### 2.4 写入流程
+
+**每次写入崩溃记录时，同时写入两个文件：**
+
+```
+1. 写入 {KITE_MODULE_DATA}/log/crashes.jsonl           （当次运行）
+2. 写入 {KITE_MODULE_DATA}/log/crashes/{YYYY-MM}/{YYYY-MM-DD}.jsonl  （按日归档）
+```
+
+---
+
+## 3. 异常捕获机制
+
+### 3.1 捕获范围
+
+**每个模块必须捕获以下位置的异常：**
+
+1. **主线程最外层** — 捕获所有未处理异常
+2. **所有子线程** — 每个线程的入口函数最外层
+3. **未捕获异常钩子** — 作为最后防线
+
+### 3.2 处理顺序
+
+**异常发生时的处理顺序（严格遵守）：**
+
+```
+1. 写入本地崩溃日志文件（crashes.jsonl + 按日归档）  ← 必须先做
+2. 输出控制台摘要（见第 5 节）
+3. 尝试发送 module.crash 事件（见第 4 节）          ← 允许失败
+4. 退出或继续运行（取决于严重级别）
+```
+
+**第 1 步必须在第 3 步之前。** 因为模块崩溃时 Event Hub 可能不可达，但本地文件写入几乎不会失败。这保证了即使事件发送失败，崩溃信息也已经记录在本地日志中。
+
+### 3.3 Python 实现示例
+
+```python
+import sys
+import os
+import json
+import traceback
+from datetime import datetime, timezone
+import threading
+
+MODULE_NAME = "web"  # 硬编码或从配置读取
+LOG_DIR = os.path.join(os.environ["KITE_MODULE_DATA"], "log")
+CRASH_LOG = os.path.join(LOG_DIR, "crashes.jsonl")
+
+def _init_crash_log():
+    """模块启动时调用：创建目录，清空 crashes.jsonl"""
+    os.makedirs(LOG_DIR, exist_ok=True)
+    try:
+        with open(CRASH_LOG, "w", encoding="utf-8") as f:
+            pass  # 清空
+    except Exception:
+        pass
+
+def write_crash(exc_type, exc_value, exc_tb,
+                thread_name=None, severity="critical", handled=False):
+    """写入崩溃日志到 crashes.jsonl 和按日归档"""
+    record = {
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+        "module": MODULE_NAME,
+        "thread": thread_name or threading.current_thread().name,
+        "exception_type": exc_type.__name__ if exc_type else "Unknown",
+        "exception_message": str(exc_value),
+        "traceback": "".join(traceback.format_exception(exc_type, exc_value, exc_tb)),
+        "severity": severity,
+        "handled": handled,
+        "process_id": os.getpid(),
+        "platform": sys.platform,
+        "runtime_version": f"Python {sys.version.split()[0]}",
+    }
+
+    if exc_tb:
+        tb = traceback.extract_tb(exc_tb)[-1]
+        record["context"] = {
+            "function": tb.name,
+            "file": os.path.basename(tb.filename),
+            "line": tb.lineno,
+        }
+
+    line = json.dumps(record, ensure_ascii=False) + "\n"
+
+    # 1. 写入 crashes.jsonl（当次运行）
+    try:
+        with open(CRASH_LOG, "a", encoding="utf-8") as f:
+            f.write(line)
+    except Exception:
+        pass
+
+    # 2. 写入按日归档
+    try:
+        today = datetime.now().strftime("%Y-%m-%d")
+        archive_dir = os.path.join(LOG_DIR, "crashes", today[:7])
+        os.makedirs(archive_dir, exist_ok=True)
+        archive_path = os.path.join(archive_dir, f"{today}.jsonl")
+        with open(archive_path, "a", encoding="utf-8") as f:
+            f.write(line)
+    except Exception:
+        pass
+
+def setup_exception_hooks():
+    """设置全局异常钩子（模块启动时调用一次）"""
+
+    # 1. 主线程未捕获异常
+    def excepthook(exc_type, exc_value, exc_tb):
+        write_crash(exc_type, exc_value, exc_tb,
+                    severity="critical", handled=False)
+        _print_crash_summary(exc_type, exc_tb)
+        sys.__excepthook__(exc_type, exc_value, exc_tb)
+
+    sys.excepthook = excepthook
+
+    # 2. 子线程未捕获异常（Python 3.8+）
+    if hasattr(threading, "excepthook"):
+        def thread_excepthook(args):
+            write_crash(args.exc_type, args.exc_value, args.exc_traceback,
+                        thread_name=args.thread.name if args.thread else "unknown",
+                        severity="error", handled=False)
+            _print_crash_summary(args.exc_type, args.exc_traceback,
+                                 thread_name=args.thread.name if args.thread else None)
+
+        threading.excepthook = thread_excepthook
+
+def _print_crash_summary(exc_type, exc_tb, thread_name=None):
+    """打印崩溃摘要到控制台（红色高亮）"""
+    RED = "\033[91m"
+    RESET = "\033[0m"
+
+    if exc_tb:
+        tb = traceback.extract_tb(exc_tb)[-1]
+        location = f"{os.path.basename(tb.filename)}:{tb.lineno}"
+    else:
+        location = "unknown"
+
+    prefix = f"[{MODULE_NAME}]"
+    if thread_name:
+        print(f"{prefix} {RED}线程 {thread_name} 崩溃: "
+              f"{exc_type.__name__} in {location}{RESET}")
+    else:
+        print(f"{prefix} {RED}崩溃: {exc_type.__name__} in {location}{RESET}")
+    print(f"{prefix} 崩溃日志: {CRASH_LOG}")
+
+
+# ── 使用示例 ──
+
+def main():
+    _init_crash_log()
+    setup_exception_hooks()
+
+    try:
+        run_application()
+    except Exception as e:
+        write_crash(type(e), e, e.__traceback__,
+                    severity="critical", handled=True)
+        _print_crash_summary(type(e), e.__traceback__)
+        sys.exit(1)
+```
+
+### 3.4 Node.js 实现示例
+
+```javascript
+const fs = require('fs');
+const path = require('path');
+
+const MODULE_NAME = 'hello_node';  // 硬编码或从配置读取
+const LOG_DIR = path.join(process.env.KITE_MODULE_DATA, 'log');
+const CRASH_LOG = path.join(LOG_DIR, 'crashes.jsonl');
+
+const RED = '\x1b[91m';
+const RESET = '\x1b[0m';
+
+function initCrashLog() {
+  fs.mkdirSync(LOG_DIR, { recursive: true });
+  try { fs.writeFileSync(CRASH_LOG, '', 'utf-8'); } catch (e) {}
+}
+
+function writeCrash(error, threadName = 'MainThread',
+                    severity = 'critical', handled = false) {
+  const record = {
+    timestamp: new Date().toISOString(),
+    module: MODULE_NAME,
+    thread: threadName,
+    exception_type: error.name || 'Error',
+    exception_message: error.message || String(error),
+    traceback: error.stack || '',
+    severity,
+    handled,
+    process_id: process.pid,
+    platform: process.platform,
+    runtime_version: `Node.js ${process.version}`,
+  };
+
+  if (error.stack) {
+    const match = error.stack.match(/at\s+(.+?)\s+\((.+?):(\d+):\d+\)/);
+    if (match) {
+      record.context = {
+        function: match[1],
+        file: path.basename(match[2]),
+        line: parseInt(match[3]),
+      };
+    }
+  }
+
+  const line = JSON.stringify(record) + '\n';
+
+  // 1. 写入 crashes.jsonl（当次运行）
+  try { fs.appendFileSync(CRASH_LOG, line, 'utf-8'); } catch (e) {}
+
+  // 2. 写入按日归档
+  try {
+    const today = new Date().toISOString().slice(0, 10);  // YYYY-MM-DD
+    const archiveDir = path.join(LOG_DIR, 'crashes', today.slice(0, 7));
+    fs.mkdirSync(archiveDir, { recursive: true });
+    fs.appendFileSync(path.join(archiveDir, `${today}.jsonl`), line, 'utf-8');
+  } catch (e) {}
+}
+
+function printCrashSummary(error, threadName = null) {
+  let location = 'unknown';
+  if (error.stack) {
+    const match = error.stack.match(/\((.+?):(\d+):\d+\)/);
+    if (match) location = `${path.basename(match[1])}:${match[2]}`;
+  }
+
+  const prefix = `[${MODULE_NAME}]`;
+  if (threadName) {
+    console.error(`${prefix} ${RED}线程 ${threadName} 崩溃: `
+                + `${error.name} in ${location}${RESET}`);
+  } else {
+    console.error(`${prefix} ${RED}崩溃: ${error.name} in ${location}${RESET}`);
+  }
+  console.error(`${prefix} 崩溃日志: ${CRASH_LOG}`);
+}
+
+function setupExceptionHandlers() {
+  process.on('uncaughtException', (error) => {
+    writeCrash(error, 'MainThread', 'critical', false);
+    printCrashSummary(error);
+    process.exit(1);
+  });
+
+  process.on('unhandledRejection', (reason) => {
+    const error = reason instanceof Error ? reason : new Error(String(reason));
+    writeCrash(error, 'MainThread', 'error', false);
+    printCrashSummary(error);
+  });
+}
+
+// ── 使用示例 ──
+function main() {
+  initCrashLog();
+  setupExceptionHandlers();
+
+  try {
+    runApplication();
+  } catch (error) {
+    writeCrash(error, 'MainThread', 'critical', true);
+    printCrashSummary(error);
+    process.exit(1);
+  }
+}
+```
+
+### 3.5 线程异常处理
+
+**Python 线程入口模板：**
+
+```python
+def worker_thread():
+    try:
+        do_work()
+    except Exception as e:
+        write_crash(type(e), e, e.__traceback__,
+                    thread_name=threading.current_thread().name,
+                    severity="error", handled=True)
+        _print_crash_summary(type(e), e.__traceback__,
+                             thread_name=threading.current_thread().name)
+```
+
+---
+
+## 4. 异常事件传播
+
+### 4.1 事件定义
+
+**事件类型**: `module.crash`
+
+**事件数据：**
+
+```json
+{
+  "module_id": "web",
+  "exception_type": "AttributeError",
+  "exception_message": "'WebSocketProtocol' object has no attribute 'transfer_data_task'",
+  "traceback_preview": "File server.py, line 199, in ws_endpoint",
+  "severity": "error",
+  "timestamp": "2026-03-02T09:15:23.456789+00:00",
+  "process_id": 12345,
+  "handled": false
+}
+```
+
+**注意 `traceback_preview`**: 仅包含最后一帧的单行摘要，不含完整堆栈。完整堆栈在本地崩溃日志中。
+
+### 4.2 发送时机
+
+**发送：**
+
+- 捕获到未处理异常（`handled: false`）
+- 关键功能崩溃（`severity: critical` 或 `error`）
+- 在写入本地崩溃日志**之后**发送
+
+**不发送：**
+
+- 已处理的预期内错误（`severity: warning`）
+- 启动阶段（Event Hub 可能未就绪）
+- 频繁发生的非关键错误（限流）
+
+### 4.3 发送失败处理
+
+**事件发送是尽力而为（best-effort）。** 因为：
+
+- 模块崩溃时 Event Hub 可能不可达
+- 核心模块（Event Hub 自身）崩溃时无法发送事件
+- 启动阶段 Event Hub 未就绪
+
+**保障机制：** 本地崩溃日志（第 2 步）在事件发送（第 3 步）之前完成。即使事件丢失，崩溃信息已落盘。启动器通过读取模块的 `crashes.jsonl` 文件作为补充（见第 6 节）。
+
+---
+
+## 5. 控制台输出规范
+
+### 5.1 格式规则
+
+1. **崩溃摘要行用红色**（ANSI `\033[91m`）
+2. **不使用特殊符号**（不用 ⚠ 等 emoji/unicode 符号）
+3. **不输出完整堆栈** — 引导查看崩溃日志文件
+4. **摘要行格式**: `{异常类型} in {文件名}:{行号}`
+
+### 5.2 模块自身异常（模块进程内输出）
+
+```
+[web] 崩溃: AttributeError in server.py:199          ← 红色
+[web] 崩溃日志: C:\...\.kite\workspace\Kite\web\log\crashes.jsonl
+```
+
+**线程异常：**
+
+```
+[web] 线程 WorkerThread 崩溃: ValueError in handler.py:42   ← 红色
+[web] 崩溃日志: C:\...\.kite\workspace\Kite\web\log\crashes.jsonl
+```
+
+### 5.3 启动器检测到模块异常退出（启动器进程内输出）
+
+```
+[launcher] 模块 'web' 退出，返回码 1
+[launcher] 崩溃: AttributeError in server.py:199     ← 红色
+[launcher] 崩溃日志: C:\...\.kite\workspace\Kite\web\log\crashes.jsonl
+```
+
+### 5.4 启动器自身异常
+
+```
+[launcher] 崩溃: NameError in process_manager.py:409  ← 红色
+[launcher] 崩溃日志: C:\...\.kite\workspace\Kite\launcher\log\crashes.jsonl
+[launcher] 正在执行最终清理...
+```
+
+---
+
+## 6. 启动器特殊职责
+
+### 6.1 监听 module.crash 事件
+
+启动器监听 `module.crash` 事件，在控制台按 5.3 格式输出摘要。不重复写入日志（模块已自行记录）。
+
+### 6.2 检测异常退出（读取模块崩溃日志）
+
+当启动器在 `_monitor_loop` 中检测到模块退出（返回码非 0）时，**读取该模块的 `crashes.jsonl` 最后一条记录**，在控制台输出摘要：
+
+```python
+RED = "\033[91m"
+RESET = "\033[0m"
+
+for name, rc in exited:
+    if rc == 0:
+        print(f"[launcher] 模块 '{name}' 正常退出")
+        continue
+
+    print(f"[launcher] 模块 '{name}' 退出，返回码 {rc}")
+
+    crash_log = os.path.join(
+        os.environ["KITE_INSTANCE_DIR"], name, "log", "crashes.jsonl"
+    )
+
+    if os.path.isfile(crash_log):
+        try:
+            with open(crash_log, "rb") as f:
+                # 从文件末尾反向读取最后一行
+                f.seek(0, 2)
+                size = f.tell()
+                if size > 0:
+                    # 简单实现：读最后 4KB
+                    f.seek(max(0, size - 4096))
+                    lines = f.read().decode("utf-8").strip().split("\n")
+                    last = json.loads(lines[-1])
+                    exc_type = last.get("exception_type", "Unknown")
+                    ctx = last.get("context", {})
+                    file_name = ctx.get("file", "unknown")
+                    line_no = ctx.get("line", "?")
+                    print(f"[launcher] {RED}崩溃: "
+                          f"{exc_type} in {file_name}:{line_no}{RESET}")
+                    print(f"[launcher] 崩溃日志: {crash_log}")
+        except Exception:
+            pass
+```
+
+**这是 `module.crash` 事件的补充机制。** 即使模块在崩溃时来不及发送事件，启动器仍然可以从文件中获取崩溃信息。两者互补：
+
+- **`module.crash` 事件**: 实时通知，但可能丢失
+- **读取 `crashes.jsonl`**: 延迟通知（模块退出后），但可靠
+
+---
+
+## 7. 最佳实践
+
+### 7.1 异常捕获原则
+
+1. **最外层必须捕获** — 主函数、线程入口必须有 try/except（或等效机制）
+2. **关键路径必须捕获** — 启动、关闭、核心功能
+3. **记录后再决定** — 先写崩溃日志，再决定是否重新抛出或退出
+4. **避免吞没异常** — 不要空 except 块，至少记录日志
+5. **不要用 try/except 包裹整个业务逻辑** — 只包裹特定的风险点
+
+### 7.2 日志记录原则
+
+1. **立即写入** — 不缓冲，确保崩溃前数据已落盘
+2. **避免敏感信息** — 不记录密码、token、用户数据到 traceback
+3. **控制大小** — traceback 超过 200 行时截断（保留首尾各 50 行）
+4. **原子写入** — 追加模式 + 单行 JSON，天然支持并发
+5. **写入失败静默** — 日志写入本身不应抛出异常
+
+### 7.3 事件发送原则
+
+1. **先写文件后发事件** — 本地记录优先于远程通知
+2. **非阻塞** — 超时 2 秒，避免阻塞关闭流程
+3. **容错** — 发送失败不影响程序
+4. **去重** — 同一异常 10 秒内不重复发送
+
+---
+
+## 8. 检查清单
+
+### 新模块开发时必须实现
+
+- [ ] 日志目录初始化（`{KITE_MODULE_DATA}/log/`）
+- [ ] `latest.log`：每次启动清空，运行时追加，同时写按日归档
+- [ ] `crashes.jsonl`：每次启动清空
+- [ ] 崩溃日志写入函数（同时写 `crashes.jsonl` + 按日 `.jsonl`）
+- [ ] 主线程最外层 try/except
+- [ ] 所有子线程的异常捕获
+- [ ] 未捕获异常钩子（`sys.excepthook` / `process.on('uncaughtException')`）
+- [ ] 控制台崩溃摘要输出（红色，见第 5 节）
+- [ ] 可选：发送 `module.crash` 事件
+
+### 启动器额外职责
+
+- [ ] 监听 `module.crash` 事件
+- [ ] 模块异常退出时读取 `crashes.jsonl` 并输出摘要
+- [ ] 自身所有线程的异常捕获和日志记录
+- [ ] 自身 `crashes.jsonl` 记录
+
+---
+
+## 9. 调试指南
+
+**查看模块最后一次执行日志：**
+
+```bash
+# 查看某个模块最后一次运行的完整日志
+cat ~/.kite/workspace/Kite/web/log/latest.log
+
+# 查看启动器最后一次运行日志
+cat ~/.kite/workspace/Kite/launcher/log/latest.log
+```
+
+**查看崩溃日志：**
+
+```bash
+# 查看某个模块本次运行的崩溃
+cat ~/.kite/workspace/Kite/web/log/crashes.jsonl
+
+# 查看历史崩溃（按日归档）
+cat ~/.kite/workspace/Kite/web/log/crashes/2026-03/2026-03-02.jsonl
+
+# 格式化查看最后一条崩溃
+tail -n 1 ~/.kite/workspace/Kite/web/log/crashes.jsonl | python -m json.tool
+```
+
+**分析崩溃模式：**
+
+```bash
+# 统计按日归档中的崩溃次数
+wc -l ~/.kite/workspace/Kite/*/log/crashes/2026-03/*.jsonl
+
+# 按异常类型统计（需要 jq）
+cat crashes/2026-03/*.jsonl | jq -r '.exception_type' | sort | uniq -c | sort -rn
+```
+
+---
+
+**文档版本**: 1.1
+**最后更新**: 2026-03-02
+**维护者**: Kite Team