@agentunion/kite 1.5.0 → 1.6.1

package/docs/INDEX.md

@@ -0,0 +1,388 @@
+# Kite 文档索引
+
+> 渐进式三层结构。Layer 1（L1-59）极简地图，总是加载；Layer 2（L62-149）概念交叉索引，按主题查找时加载；Layer 3（L152+）每篇文档的详细摘要，需要深入时加载。
+> 行区间格式 `L3-48` 表示源文件第 3-48 行。
+
+---
+
+## 用户常用概念速查表
+
+> 快速查找用户常用术语的准确含义，避免歧义。
+
+| 用户术语 | 准确含义 | 对应路径/模块 |
+|---------|---------|--------------|
+| **Evol 控制台** | Evol 模块的 Web 管理界面，提供 WebSocket 连接、Kernel 客户端、会话管理等功能 | `extensions/services/evol/static/` (index.html + evol-app.js) |
+| **Launcher** | Kite 启动器，负责启动和管理所有模块的生命周期 | `launcher/` |
+| **Kernel** | Kite 内核模块，负责会话管理、Agent 调度、身份管理、权限控制 | `kernel/` |
+| **Registry** | 注册中心，第一个启动的 core 模块，负责服务发现和能力索引 | `extensions/services/registry/` |
+| **Event Hub** | 事件中心，负责事件路由和订阅管理 | `extensions/services/event_hub/` |
+| **Watchdog** | 监控模块，负责健康检查和资源监控 | `extensions/services/watchdog/` |
+| **Logs 模块** | 日志查询服务，提供日志搜索、变更追踪、崩溃分析等 API | `extensions/services/logs/` |
+| **Audit 模块** | 审计事件服务，记录和查询系统审计事件 | `extensions/services/audit/` |
+
+---
+
+## Layer 1：文档地图
+
+### Kite框架设计/（总纲）
+
+| 文档 | 章节 → 行区间 |
+|------|--------------|
+| [01-框架定位](Kite框架设计/01-框架定位.md) | 全文 L1-13 |
+| [02-核心概念](Kite框架设计/02-核心概念.md) | 2.1 身份 L3 · 2.2 渠道 L128 · 2.3 事件 L136 · 2.4 会话 L168 · 2.5 Agent L221 · 2.6 工具与技能 L252 · 2.7 任务 L317 · 2.8 工作模式 L335 |
+| [03-系统架构](Kite框架设计/03-系统架构.md) | 3.1 进程模型 L3 · 3.2 Launcher L43 · 3.3 Registry L79 · 3.4 Event Hub L109 · 3.5 Kernel L149 · 3.6 Model Service L166 · 3.7 Task System L182 · 3.8 Watchdog L208 · 3.9 事件可靠性 L220 |
+| [04-模块规范](Kite框架设计/04-模块规范.md) | 4.1 统一结构 L3 · 4.2 module.md L25 · 4.3 entry.py 协议 L67 · 4.4 模块职责 L166 · 4.5 Hook 规范 L174 |
+| [05-核心流程](Kite框架设计/05-核心流程.md) | 5.1 启动 L3 · 5.2 事件驱动 L55 · 5.3 工具调用 L74 · 5.4 会话生命周期 L94 · 5.5 任务执行 L129 |
+| [06-目录结构](Kite框架设计/06-目录结构.md) | 6.1 生产环境 L7 · 6.2 开发环境 L82 · 6.3 环境变量对应 L120 · 6.4 数据归属 L138 · 6.5 模块规范 L153 |
+| [07-数据模型](Kite框架设计/07-数据模型.md) | 7.1 Session L3 · 7.2 Task L25 · 7.3 Identity L46 · 7.4 索引 L62 |
+| [08-扩展性](Kite框架设计/08-扩展性.md) | 全文 L1-35（添加渠道/Agent/工具/事件） |
+| [09-与应用的关系](Kite框架设计/09-与具体应用的关系.md) | 全文 L1-23 |
+
+### 独立专题
+
+| 文档 | 章节 → 行区间 |
+|------|--------------|
+| [注册中心设计](注册中心设计.md) | 1 定位 L3 · 2 决策 L12 · 3 三层状态 L28 · 4 Payload L53 · 5 API L153 · 6 场景 L319 · 7 时序 L489 · 8 认证 L519 |
+| [事件中心设计](事件中心设计.md) | 1 定位 L3 · 2 决策 L14 · 3 WS 协议 L29 · 4 处理流程 L97 · 5 匹配规则 L127 · 6 去重可靠性 L167 · 7 认证 L239 · 8 HTTP L312 · 9 启动 L357 · 10 数据结构 L384 · 11 场景 L428 · 12 文件 L499 · 13 决策 Q&A L513 |
+| [Launcher启动器](Launcher启动器文档.md) | 1 概述 L3 · 2 快速开始 L8 · 3 启动序列 L53 · 4 线程模型 L133 · 5 模块发现 L159 · 6 故障恢复 L283 · 7 遗留清理 L318 · 8 API L359 · 9 跨平台 L482 · 10 端口 L498 · 11 安全 L519 · 12 错误 L551 · 13 文件 L566 · 14 类参考 L579 |
+| [实现规划](实现规划.md) | P1 已完成 · SDK L10 · P2 WebChat+Kernel L33 · P3 Agent+ModelService L69 · P4 身份+工作区 L121 · P5 Polyglot L145 |
+| [优雅退出规范](优雅退出规范.md) | 1 概述 L3 · 2 能力声明 L9 · 3 事件 L29 · 4 流程 L87 · 5 规范 L142 · 6 兼容 L171 · 7 SIGTERM L179 · 8 主动退出 L189 |
+| [启动依赖与排序](启动依赖与排序.md) | 1 概述 L3 · 2 module.md L8 · 3 就绪标准 L20 · 4 排序算法 L48 · 5 manual L65 · 6 core L72 · 7 事件 L76 |
+| [模块热更新](模块热更新.md) | 1 概述 L3 · 2 流程 L9 · 3 事件 L39 · 4 配套 L70 · 5 模块侧 L82 |
+| [Watchdog资源监控](Watchdog资源监控策略.md) | 1 概述 L3 · 2 列表 L12 · 3 采集 L18 · 4 异常 L39 · 5 处理 L57 · 6 事件 L75 · 7 现有机制 L83 |
+| [代理启动器与容器化](代理启动器与容器化.md) | 1 概述 L3 · 2 架构 L12 · 3 代理启动器 L35 · 4 容器化 L66 · 5 配套改动 L97 |
+| [Polyglot与Clawdbot](Polyglot运行时与Clawdbot兼容性设计.md) | 1 背景 L3 · 2 洞察 L9 · 3 多运行时 L15 · 4 SDK L49 · 5 Channel 接入 L65 · 6 Skill 接入 L150 · 7 身份映射 L301 · 8 收益 L315 |
+| [npm发布与CLI使用指南](npm发布与CLI使用指南.md) | 1 工程支持文件 · 2 发布流程 · 3 安装流程 · 4 kite命令执行原理 · 5 启动方式汇总 |
+| [环境变量与运行时目录设计](环境变量与运行时目录设计.md) | 1 环境变量定义 · 2 两种启动模式 · 3 目录结构 · 4 调试模式 · 5 传递链 · 6 .env配置 · 7 模块中使用 |
+| [stdio与端口发现重构](stdio与端口发现重构.md) | 1 概述 L1 · 2 boot_info 精简 L12 · 3 stdio 生命周期 L41 · 4 stdout 结构化消息 L111 · 5 完整启动流程 L167 · 6 Registry 感知 Event Hub L393 · 7 消除内容 L426 · 8 代码改动清单 L444 |
+| [架构借鉴指南](架构借鉴指南.md) | P0-1 Module SDK · P0-2 Schema 校验 · P0-3 集中配置 · P1-1 权限控制 · P1-2 配置热重载 · P1-3 RPC 协议 · P2-1 扩展点分类 · P2-2 错误码体系 · P2-3 CLI 工具 · 附录 现有优势 · 讨论索引（依赖顺序图） |
+| [重构机制清单](重构机制清单.md) | 机制 1 启动序列重排 L7 · 机制 2 Registry 端口发现 L19 · 机制 3 stdin 延迟关闭 L25 · 机制 4 stdout 结构化消息 L35 · 机制 5 Event Hub 启动协议 L47 · 机制 6 Launcher↔Event Hub 认证 L58 · 机制 7 Registry 延迟就绪 L66 · 机制 8 boot_info 精简 L76 · 机制 9 _start_one_module 流程 L90 · 机制 10 全量重启 L100 · 机制 11 端口文件移除 L112 · 机制 12 内置模块校验 L120 · 机制 13 模块自获取信息 L128 · 机制 14 ProcessManager 扩展 L142 |
+| [架构改造-合并Kernel方案](架构改造-合并Kernel方案.md) | 1 目标 · 2 决策清单 · 3 协议规范（帧格式/方法/转发/错误码/心跳） · 4 Kernel 内部架构 · 5 启动流程 · 6 各模块改造 · 7 Bridge 简化 · 8 依赖清理 · 9 环境变量 · 10 实施顺序 · 附录 A-C |
+| [模块开发指南](模块开发指南.md) | 1 概述 L5 · 2 快速开始 L21 · 3 模块结构 L235 · 4 module.md L258 · 5 启动协议 L345（5.11 连接韧性 L595） · 6 事件系统 L678 · 7 优雅退出 L779 · 8 主动退出 L928 · 9 提供工具 L954 · 10 启动依赖 L1034 · 11 发现与放置 L1057 · 12 数据存储 L1094 · 13 业务配置 L1322 · 14 跨平台 L1508 · 15 常见问题 L1526 · 16 附录 L1555 |
+| [WebSocket接收循环死锁防范规范](WebSocket接收循环死锁防范规范.md) | 🔴 最高优先级 · 问题描述 · 核心原则 · Python/Node.js/Go/Rust 实现模式 · 常见错误 · 调试方法 · 检查清单 |
+| [配置系统开发计划](配置系统/配置系统开发计划.md) | 1 现状分析 · 2 开发计划（阶段1-5） · 3 技术选型 · 4 参考项目 · 5 实施优先级 · 6 风险与注意事项 · 7 后续优化方向 |
+| [异常处理规范](日志与异常处理规范.md) | 1 日志体系 L12 · 2 崩溃日志格式 L118 · 3 异常捕获机制 L184 · 4 事件传播 L456 · 5 控制台输出 L505 · 6 启动器职责 L546 · 7 最佳实践 L600 · 8 检查清单 L627 · 9 调试指南 L650 |
+| [降级策略设计方案](降级策略设计方案.md) | 1 问题与目标 L3 · 2 降级等级 L38 · 3 事件协议(Kernel RPC中转) L48 · 4 RPC 错误增强(-32006) L185 · 5 Registry 状态扩展 L240 · 6 降级判定 L282 · 7 恢复判定 L318 · 8 角色职责 L348 · 9 改动清单(含实施状态) L434 · 10 交互时序 L505 · 11 兼容性 L584 · 12 现有机制关系 L598 · 13 未来扩展 L612 |
+| [日志调试实战指南](日志调试实战指南.md) | 快速诊断 · 崩溃调试流程 · 常用关键词 · 时间范围搜索 · 高级技巧 · 调试思路总结 |
+| [Logs模块API](logs-api-guide.md) | API端点 · 快速指令 · 调试流程 · 日志文件说明 |
+| [Audit模块API](audit-api-guide.md) | API端点 · 订阅事件 · 存储结构 |
+| [WebSocket连接韧性方案](WebSocket连接韧性方案.md) | 1 WS重连机制 L14（1.1 模块状态机 L16 · 1.2 客户端重连策略 L41）· 2 Launcher异常终止 L64（2.1 Kernel行为 L66 · 2.2 Watchdog行为 L83 · 2.3 重连恢复 L110）· 3 残留清理顺序 L121 · 时间线示例 L135 |
+| [握手认证方案](握手认证方案.md) | 1 架构模型 · 2 握手流程（四步：WS连接→challenge→connect→hello-ok）· 3 认证方式（token/配对码/短信/AID）· 4 hello-ok 响应 · 5 同ID并发连接 · 6 Token轮换 · 7 连接速率限制 · 8 错误码 · 9 改造清单 |
+| [事件处理机制](事件处理机制.md) | 1 概述 · 2 核心架构 · 3 事件格式 · 4 事件类型 · 5 订阅机制 · 6 发布机制 · 7 队列与背压 · 8 消费循环 · 9 异常处理 · 10 事件去重 · 11 优雅退出 · 12 调试与监控 · 13 最佳实践 |
+| [事件订阅通配符规范](事件订阅通配符规范.md) | 1 概述 · 2 通配符类型（`*` 单段 / `>` 多段尾部） · 3 匹配规则 · 4 常见模式 · 5 性能考虑 · 6 错误用法 · 7 与其他系统对比 |
+| [模块配置加载与热重载规范](模块配置加载与热重载规范.md) | 1 概述 · 2 配置分层 · 3 加载机制 · 4 热重载 · 5 配置验证 · 6 最佳实践 |
+| [模块退出机制完整方案](模块退出机制完整方案.md) | 1 概述 · 2 退出类型 · 3 事件序列 · 4 模块实现 · 5 Kernel 处理 · 6 Launcher 处理 · 7 超时与强制终止 |
+| [CLI开发计划](CLI开发计划.md) | 1 现状分析 · 2 目标 · 3 技术方案 · 4 实施计划 · 5 风险与注意事项 |
+| [计划管理器使用指南](计划管理器使用指南.md) | 1 概述 · 2 基本用法 · 3 计划文件格式 · 4 命令参考 · 5 最佳实践 |
+| [模块安装机制设计](模块安装机制设计.md) | 1 概述 · 2 安装流程 · 3 依赖管理 · 4 版本控制 · 5 卸载机制 |
+| [链路追踪方案](链路追踪方案.md) | 1 问题与目标 · 2 设计原则 · 3 trace 上下文结构 · 4 传播规则 · 5 rpc.call.completed 事件增强 · 6 内存缓存 · 7 查询接口 · 8 故障诊断流程 · 9 职责分工 · 10 错误码 · 11 改动清单 · 12 兼容性 |
+| [模块多连接控制策略](模块多连接控制策略.md) | 概述 · 术语 · 配置 · 连接生命周期 · 双层队列架构 · 保序机制 · Offer/Release 协议 · 弹性模式 · Slot Token 管理 · 向后兼容 |
+| [测试中心添加模块测试指南](测试中心添加模块测试指南.md) | 1 概述 · 2 创建模块测试文件 · 3 创建集成测试文件 · 4 注册到测试中心 · 5 示例（Redis） · 6 测试运行 · 7 注意事项 |
+
+---
+
+## Layer 2：概念交叉索引
+
+### 身份（Identity）
+- 统一模型 / profile.md / 角色 / 合并 → [02-核心概念 L3-126](Kite框架设计/02-核心概念.md)
+- JSON 数据模型 + 索引文件 → [07-数据模型 L46-68](Kite框架设计/07-数据模型.md)
+- 存储目录结构 → [06-目录结构 L138-152](Kite框架设计/06-目录结构.md)
+- Kernel 身份管理 → [03-系统架构 L149-164](Kite框架设计/03-系统架构.md)
+- 实现规划 → [实现规划 L121-143](实现规划.md)
+- Clawdbot 映射 → [Polyglot L301-313](Polyglot运行时与Clawdbot兼容性设计.md)
+
+### 会话（Session）
+- 定义 / Session Key / 隔离 / messages.jsonl → [02-核心概念 L168-219](Kite框架设计/02-核心概念.md)
+- JSON 数据模型 → [07-数据模型 L3-23](Kite框架设计/07-数据模型.md)
+- 生命周期流程 → [05-核心流程 L94-127](Kite框架设计/05-核心流程.md)
+
+### 事件系统
+- 事件结构与类型 → [02-核心概念 L136-166](Kite框架设计/02-核心概念.md)
+- Event Hub 完整设计 → [事件中心设计](事件中心设计.md)（全文 524 行）
+- **事件处理机制（完整说明）** → [事件处理机制](事件处理机制.md)（架构/格式/订阅/发布/队列/背压/去重/退出）
+- **订阅通配符规范（NATS-style）** → [事件订阅通配符规范](事件订阅通配符规范.md)（`*` 单段 / `>` 多段尾部 / 匹配规则 / 性能考虑）
+- 订阅匹配 NATS `*`/`>` → [事件中心设计 L127-165](事件中心设计.md)
+- 去重（seen_events 1h） → [事件中心设计 L167-193](事件中心设计.md)
+- Outbox（内存 pending_acks + 磁盘 jsonl） → [事件中心设计 L195-227](事件中心设计.md)
+- 可靠性边界（发送 at-least-once / 接收 best-effort） → [事件中心设计 L229-237](事件中心设计.md)
+
+### 模块生命周期
+- **实操指南（从零创建模块）** → [模块开发指南](模块开发指南.md)（全文 ~1600 行，含 Python/Node.js 完整示例）
+- 统一结构 + module.md → [04-模块规范 L3-65](Kite框架设计/04-模块规范.md)
+- entry.py 协议（stdin boot_info / 8 步 / module.ready） → [04-模块规范 L67-164](Kite框架设计/04-模块规范.md)
+- 三层状态模型（config/desired/actual + 7 场景） → [注册中心设计 L28-51](注册中心设计.md)
+- 模块发现（discovery 配置 + frontmatter 12 字段） → [Launcher L159-281](Launcher启动器文档.md)
+- 启动依赖拓扑排序 → [启动依赖与排序 L48-63](启动依赖与排序.md)
+- 优雅退出（能力声明 + shutdown/ack/ready 三事件） → [优雅退出规范](优雅退出规范.md)（全文 245 行）
+- **退出机制完整方案** → [模块退出机制完整方案](模块退出机制完整方案.md)（退出类型/事件序列/实现/超时处理）
+- 热更新（7 步 / 回滚） → [模块热更新](模块热更新.md)（全文 90 行）
+- WS 断开重连 / 模块状态机（offline→connected→registered→ready） → [WebSocket连接韧性方案 L14-62](WebSocket连接韧性方案.md)
+
+### 配置系统
+- 配置分层（模块配置 vs 业务配置） → [模块开发指南 L1322-1507](模块开发指南.md)
+- businesses 块声明 + JSON5 配置文件 → [模块开发指南 L1336-1370](模块开发指南.md)
+- config_loader.py 工具 → [模块开发指南 L1372-1450](模块开发指南.md)
+- 配置验证（JSON Schema） → [模块开发指南 L1476-1492](模块开发指南.md)
+- 配置热重载 → [模块开发指南 L1494-1507](模块开发指南.md)
+- **配置加载与热重载规范** → [模块配置加载与热重载规范](模块配置加载与热重载规范.md)（分层/加载机制/热重载/验证/最佳实践）
+- 配置系统开发计划（5 阶段 + 技术选型 + 风险） → [配置系统开发计划](配置系统/配置系统开发计划.md)（全文 ~300 行）
+- 参考项目（龙虾 Zod / CoPaw Pydantic） → [配置系统开发计划](配置系统/配置系统开发计划.md)
+
+### 认证与安全
+- 两层 Token（KITE_TOKEN + per-module）+ stdin 管道 → [注册中心设计 L519-690](注册中心设计.md)
+- **握手认证方案（四步握手 + 四种认证 + 速率限制 + Token 轮换）** → [握手认证方案](握手认证方案.md)（全文）
+- Launcher 侧安全特性 → [Launcher L519-549](Launcher启动器文档.md)
+- Event Hub 连接认证（/verify） → [事件中心设计 L239-310](事件中心设计.md)
+- 分布式 API 认证 → [代理启动器 L97-140](代理启动器与容器化.md)
+
+### 工具与权限
+- 三阶段（加载→开关→权限） / 五级 switches / check_permission / 反提权 → [02-核心概念 L252-315](Kite框架设计/02-核心概念.md)
+- 工具调用流程（LLM→Registry→HTTP→权限→执行） → [05-核心流程 L74-92](Kite框架设计/05-核心流程.md)
+- 工具注册发现（lookup 查询） → [注册中心设计 L319-349](注册中心设计.md)
+- 工具命名冲突 → [注册中心设计 L24](注册中心设计.md)
+- Clawdbot Skill 兼容 + 权限映射 → [Polyglot L150-299](Polyglot运行时与Clawdbot兼容性设计.md)
+
+### Hook 机制
+- void vs modifying / 10 调用点 / 链式执行 → [04-模块规范 L174-209](Kite框架设计/04-模块规范.md)
+- Hook 链查询（Registry lookup） → [注册中心设计 L353-374](注册中心设计.md)
+
+### Launcher 启动器
+- 完整文档 → [Launcher启动器文档](Launcher启动器文档.md)（全文 654 行）
+- npm 发布与 CLI 使用 → [npm发布与CLI使用指南](npm发布与CLI使用指南.md)（cli.js / package.json / 执行链路 / 数据目录）
+- 环境变量与运行时目录 → [环境变量与运行时目录设计](环境变量与运行时目录设计.md)（KITE_PROJECT / KITE_DATA / 调试模式 / .env）
+- 11 步启动序列 → [Launcher L53-131](Launcher启动器文档.md)
+- 线程模型（主/API/stdout/键盘） → [Launcher L133-157](Launcher启动器文档.md)
+- 故障恢复 + 全量重启 → [Launcher L283-316](Launcher启动器文档.md)
+- Launcher 异常终止善后（Kernel 代理优雅退出 / Watchdog 重启实例） → [WebSocket连接韧性方案 L64-119](WebSocket连接韧性方案.md)
+- API 6 端点 → [Launcher L359-480](Launcher启动器文档.md)
+- 遗留清理（PID+命令行匹配） → [Launcher L318-357](Launcher启动器文档.md)
+- 残留清理顺序（Watchdog 先 → 普通模块 → Kernel 最后） → [WebSocket连接韧性方案 L121-133](WebSocket连接韧性方案.md)
+- 跨平台差异 → [Launcher L482-496](Launcher启动器文档.md)
+- 核心类（Launcher/ProcessManager/ModuleInfo） → [Launcher L579-675](Launcher启动器文档.md)
+
+### Registry 服务发现
+- 完整设计 → [注册中心设计](注册中心设计.md)（全文 690 行）
+- 设计决策 11 项 → [注册中心设计 L12-26](注册中心设计.md)
+- 注册 Payload（字典式 tools/hooks/events） → [注册中心设计 L53-151](注册中心设计.md)
+- API（modules/lookup/get/tokens/verify/query） → [注册中心设计 L153-317](注册中心设计.md)
+- 业务场景查询总表（服务发现/工具/Hook/事件/健康） → [注册中心设计 L262-317](注册中心设计.md)
+- 心跳与 TTL 超时 → [注册中心设计 L410-426](注册中心设计.md)
+- 启动时序 T0-T5 → [注册中心设计 L489-517](注册中心设计.md)
+
+### Agent
+- 进程模型（单进程多协程）/ 4 类型 / conversation vs group → [02-核心概念 L221-250](Kite框架设计/02-核心概念.md)
+- Agent 调度（Kernel 路由） → [05-核心流程 L94-127](Kite框架设计/05-核心流程.md)
+- Hook 调用规范 → [04-模块规范 L174-209](Kite框架设计/04-模块规范.md)
+- Conversation Agent 实现 → [实现规划 L93-119](实现规划.md)
+- 添加新 Agent 类型 → [08-扩展性 L13-22](Kite框架设计/08-扩展性.md)
+
+### 渠道（Channel）
+- 定义与类型 → [02-核心概念 L128-134](Kite框架设计/02-核心概念.md)
+- 添加新渠道 → [08-扩展性 L3-11](Kite框架设计/08-扩展性.md)
+- WebChat 实现规划 → [实现规划 L37-52](实现规划.md)
+- Clawdbot Channel Bridge → [Polyglot L65-148](Polyglot运行时与Clawdbot兼容性设计.md)
+
+### 任务系统
+- 任务定义与属性 → [02-核心概念 L317-333](Kite框架设计/02-核心概念.md)
+- JSON 数据模型 → [07-数据模型 L25-44](Kite框架设计/07-数据模型.md)
+- 任务执行流程 → [05-核心流程 L129-155](Kite框架设计/05-核心流程.md)
+- Task System 模块设计 + API → [03-系统架构 L182-206](Kite框架设计/03-系统架构.md)
+
+### 工作区（Workspace）
+- 目录结构 → [06-目录结构](Kite框架设计/06-目录结构.md)
+- 额外工作区 → [06-目录结构](Kite框架设计/06-目录结构.md)
+- 实现规划 → [实现规划 L344-357](实现规划.md)
+
+### 异常处理与崩溃日志
+- 日志体系（latest.log + crashes.jsonl + 按日归档） → [异常处理规范 L12-116](日志与异常处理规范.md)
+- 崩溃日志 JSONL 格式与字段定义 → [异常处理规范 L118-182](日志与异常处理规范.md)
+- 异常捕获机制（主线程/子线程/钩子/处理顺序） → [异常处理规范 L184-454](日志与异常处理规范.md)
+- module.crash 事件定义与发送策略 → [异常处理规范 L456-503](日志与异常处理规范.md)
+- 控制台崩溃摘要输出格式 → [异常处理规范 L505-544](日志与异常处理规范.md)
+- 启动器特殊职责（事件监听 + 崩溃日志读取） → [异常处理规范 L546-598](日志与异常处理规范.md)
+- 共享工具库 `core/kite_log.py` → Python 模块的统一实现
+- **Logs 模块（日志查询 API）** → `extensions/services/logs/` (entry.py, server.py, scanner.py, searcher.py, cleaner.py, api_logger.py, quick_diagnostic.py)
+- **Audit 模块（审计事件）** → `extensions/services/audit/` (entry.py, server.py)
+
+### 健康检查与 Watchdog
+- Watchdog 完整设计 → [Watchdog资源监控](Watchdog资源监控策略.md)（全文 93 行）
+- 采集指标（CPU/内存/fd/线程） → [Watchdog L18-37](Watchdog资源监控策略.md)
+- 三级状态（normal/warning/critical） → [Watchdog L39-55](Watchdog资源监控策略.md)
+- 漏斗式 4 层检查 → [注册中心设计 L428-462](注册中心设计.md)
+- Launcher 丢失时 Watchdog 行为（判断正常/异常退出 → 决定是否重启实例） → [WebSocket连接韧性方案 L83-109](WebSocket连接韧性方案.md)
+
+### 分布式 / 容器化
+- Master-Slave 架构 + Proxy Launcher → [代理启动器 L3-64](代理启动器与容器化.md)
+- Docker 运行模式（runtime: docker / BOOT_INFO） → [代理启动器 L66-95](代理启动器与容器化.md)
+- 框架配套改动（bind/advertise_ip/API 认证） → [代理启动器 L97-140](代理启动器与容器化.md)
+
+### 多语言 / Clawdbot 兼容
+- 进程隔离天然多语言 → [Polyglot L9-13](Polyglot运行时与Clawdbot兼容性设计.md)
+- runtime 字段 + Module SDK → [Polyglot L15-63](Polyglot运行时与Clawdbot兼容性设计.md)
+- Channel Bridge（统一适配层） → [Polyglot L65-148](Polyglot运行时与Clawdbot兼容性设计.md)
+- Skill 接入（两层兼容 / Context 转换 / 兼容矩阵 7 类） → [Polyglot L150-299](Polyglot运行时与Clawdbot兼容性设计.md)
+- 权限：Kite 作为唯一源 → [Polyglot L283-299](Polyglot运行时与Clawdbot兼容性设计.md)
+
+### 系统启动流程（汇总）
+- 启动总览 → [05-核心流程 L3-53](Kite框架设计/05-核心流程.md)
+- Launcher 11 步 → [Launcher L53-131](Launcher启动器文档.md)
+- Registry 时序 T0-T5 → [注册中心设计 L489-517](注册中心设计.md)
+- Event Hub 启动 6 步 → [事件中心设计 L357-382](事件中心设计.md)
+- 拓扑排序算法 → [启动依赖与排序 L48-63](启动依赖与排序.md)
+- module.ready 就绪标准 → [启动依赖与排序 L20-46](启动依赖与排序.md)
+- stdio 与端口发现重构（唯一事实源） → [stdio与端口发现重构](stdio与端口发现重构.md)（全文 480 行）
+- 重构 14 机制清单 → [重构机制清单](重构机制清单.md)（全文 155 行）
+
+### 实现路线图
+- P1 基础设施 → **已完成**（Launcher / Registry / Event Hub / ProcessManager / ModuleScanner）
+- SDK 公共库 → [实现规划 L10-31](实现规划.md)
+- P2 WebChat+Kernel → [实现规划 L33-67](实现规划.md)
+- P3 ModelService+Agent+回复路由 → [实现规划 L69-119](实现规划.md)
+- P4 身份+工作区+权限 → [实现规划 L121-143](实现规划.md)
+- P5 Polyglot+Clawdbot → [实现规划 L145-165](实现规划.md)
+
+---
+
+## Layer 3：详细摘要
+
+> 以下为每篇文档的详细内容摘要，按需加载。
+
+---
+
+### [02-核心概念.md](Kite框架设计/02-核心概念.md) 详细摘要
+
+| § | 行区间 | 内容摘要 |
+|---|--------|---------|
+| 2.1 身份 | L3-126 | 统一身份模型，所有参与者地位平等；身份存储在 `identities/` 扁平目录，`_index/` 做 channel ID→身份映射；profile.md 用 frontmatter+正文（agent 含 owners、contact 含 channels、group 含群名）；status 三态（unidentified→identified→merged）；history.jsonl 记录所有变更（created/identified/channel_added/merged/profile_updated）；身份识别与合并由 LLM 执行；角色标记（agent/owner/contact/group）可多个；群是一等公民，路由由 Kernel 按 peer role 决定 |
+| 2.2 渠道 | L128-134 | 渠道是消息传输通道，以模块接入；提供事件（消息到达等）和工具（发送消息等） |
+| 2.3 事件 | L136-166 | 事件 JSON 结构（event_id/type/event/source/timestamp/data）；事件类型：channel.message.received/sent、channel.connected/disconnected、session.started/ended、task.created/completed、module.starting/ready/started/stopped |
+| 2.4 会话 | L168-219 | 会话属性（session_id/agent_id/peer_id/peer_kind/channel/direction/source/mode/status）；Session Key 由 `resolve_session_key()` 生成，私聊 `{agent}:peer:{peer}`，群 `{agent}:group:{group}`；scope 可配 per-peer（默认，跨渠道共享）或 per-channel-peer；messages.jsonl 统一多发言人格式，群可带 triggered_by |
+| 2.5 Agent | L221-250 | 每种 Agent 一个进程，内部多协程并发；4 类型草案：conversation（一对一对话）、group（群观察+选择性回复）、post（会话后处理）、planner（任务拆分）；Kernel 按 peer role 路由（contact→conversation，group→group） |
+| 2.6 工具与技能 | L252-315 | 阶段一：从内核+Channel+Agent 三处加载定义；阶段二：五级 switches（全局→Channel→Agent 模块→工作区 agent 级→peer/group 级，deny wins）；阶段三：handler.py 的 `check_permission(args, context)` 返回 None 通过或字符串拒绝；context 含 workspace/agent_identity/peer_identity/channel/session/task_info（不含 is_owner）；owner 身份由工具提供者独立验证（读 profile.md owners）；反提权：非 owner 不可修改 config.json 的 switches/permissions |
+| 2.7 任务 | L317-333 | 创建方式：API/Agent 决策/定时/手动；属性：task_id/type/goal/status/priority/parent_task_id/created_by/assigned_to |
+| 2.8 工作模式 | L335-342 | 托管模式（AI 完全自主）vs 授权模式（webhook 请示确认后执行） |
+
+---
+
+### [03-系统架构.md](Kite框架设计/03-系统架构.md) 详细摘要
+
+| § | 行区间 | 内容摘要 |
+|---|--------|---------|
+| 3.1 进程模型 | L3-41 | main.py 启动 5 步：检查遗留→启动 Registry（stdin 传 token）→注册自身→注册 token 映射→扫描并行启动模块；core 崩溃→整体重启，非 core→Watchdog 处理，多次失败→Launcher 退出 |
+| 3.2 Launcher | L43-77 | 三层状态（config: enabled/manual/disabled → desired: running/stopped → actual: running(PID)/stopped）；API 4 端点（modules/start/stop/state）；生命周期事件（starting/ready/started/stopped/state_changed）；任何模块可通过 API 启停其他模块 |
+| 3.3 Registry | L79-107 | per-module token + stdin 管道认证；服务发现/能力索引/glob 通配符/LLM 发现；API 6 个（modules/lookup/get/tokens/query/health）；心跳 30s/TTL 60s；POST /modules 幂等覆盖；同名工具不阻止 |
+| 3.4 Event Hub | L109-147 | WebSocket 事件路由；发送/订阅/取消订阅 JSON 格式 |
+| 3.5 Kernel | L149-164 | 会话管理/Agent 调度/身份管理/权限控制（开关过滤+配置合并）/文件存储/内部 API；内置工具（read_file/write_file/edit_file/list_files/get_config/set_config/get_identity/search_contacts） |
+| 3.6 Model Service | L166-180 | 多 LLM API 支持/提示词模板/Function Calling/SSE 流式/配置管理 |
+| 3.7 Task System | L182-206 | CRUD API 6 端点（tasks/tasks/{id}/claim/submit）；注册工具 3 个（create_task/query_tasks/get_task） |
+| 3.8 Watchdog | L208-218 | 扩展模块非 core，可降级；心跳检测/资源监控/通过 Launcher API 重启/可用 Channel 告警 owner |
+| 3.9 事件可靠性 | L220-236 | 发送确认（ack）/本地持久化（event_outbox.jsonl）/重连自动重发/重新订阅；event_id UUID 去重（Hub 内存 set 保留 1h） |
+
+---
+
+### [04-模块规范.md](Kite框架设计/04-模块规范.md) 详细摘要
+
+| § | 行区间 | 内容摘要 |
+|---|--------|---------|
+| 4.1 统一结构 | L3-23 | 所有组件都是模块；目录：entry.py/module.md/data/tools/{name}/(tool.md+handler.py)/skills/permissions/ |
+| 4.2 module.md | L25-65 | YAML frontmatter（name/display_name/version/type/state/runtime/entry/preferred_port/depends_on/events/subscriptions）+ Markdown 正文说明 |
+| 4.3 entry.py | L67-164 | stdin 一行 JSON `{token}`，Registry 端口从 env `KITE_REGISTRY_PORT` 读取；8 步：读 stdin→启 HTTP→注册 Registry→连 Event Hub→发 module.ready→启心跳→工作→退出注销；注册 payload 示例（字典式 tools/hooks/events_publish/events_subscribe） |
+| 4.4 职责 | L166-172 | 注册事件/订阅事件/产生事件/处理事件 |
+| 4.5 Hook | L174-209 | void hook（发事件不等回复）vs modifying hook（调接口等返回值）；10 调用点：收消息/LLM 前后/工具前后/发消息前后/会话始末/上下文压缩前后；链式执行按 priority、block:true 中断、单个超时不阻塞 |
+
+---
+
+### [注册中心设计.md](注册中心设计.md) 详细摘要
+
+| § | 行区间 | 内容摘要 |
+|---|--------|---------|
+| 1 定位 | L3-10 | 第一个启动的 core 模块；服务注册发现/能力索引/通用查询/LLM 智能发现 |
+| 2 设计决策 | L12-26 | 不持久化纯内存；stdin token 认证；Hook 链只返回不执行；Pull 为主发现；不做健康探测；动态端口；主动注销+TTL 续约；HTTP REST；同名工具不阻止；健康端点由模块声明；POST /modules 幂等 |
+| 3 三层状态 | L28-51 | config(enabled/manual/disabled) × desired(running/stopped) × actual(running/stopped)；7 场景示例表；初始化规则 |
+| 4 Payload | L53-151 | 字典结构（tools/hooks/events 用名称做 key）；字段说明（module_id/health_path/metadata/tools/hooks/events_publish/events_subscribe）；Event Hub 注册示例（metadata.ws_endpoint）；Model Service 示例（metadata.llm_endpoint/available_models）；Launcher 示例（events_publish） |
+| 5 API | L153-317 | 5.1 接口表 6 个；5.2 modules 统一生命周期（register/deregister/heartbeat）；5.3 lookup 三参数 glob（field/module/value）返回列表；5.4 get 点号路径精确读取返回单值；5.5 查询总表——服务发现（模块地址/Event Hub WS/Model Service LLM）、工具（已知提供者 get / 未知 lookup / 全量 / 模糊搜索）、Hook 链（跨模块 lookup）、事件（谁发布/谁订阅 lookup）、健康端点、LLM 语义查询 |
+| 6 场景 | L319-462 | 6.1 启动注册 5 步（stdin→HTTP→注册→心跳→注销）；6.2 工具调用（lookup→拼地址→POST）；6.3 Hook 链（lookup→priority 排序→依次调用→block 中断）；6.4 服务发现（lookup→拿地址→调 API；未注册→订阅 module.started 等通知）；6.5 Event Hub 连接（lookup ws_endpoint→建 WS→subscribe）；6.6 心跳/超时（30s 心跳→60s TTL→offline 保留记录→事件通知）；6.7 Watchdog 漏斗检查（Q1 该不该跑→Q2 进程在不在→Q3 注册了吗心跳新鲜吗→Q4 /health 状态） |
+| 7 时序 | L489-517 | T0 Launcher 启动 Registry（stdin 传 token→stdout 回传端口→写入 KITE_REGISTRY_PORT）→T1 注册自身→T2 注册 token 映射→T3 启动 Event Hub→T4 各模块注册→T5 系统就绪 |
+| 8 认证 | L519-690 | 8.1 per-module 独立 token；8.2 stdin 管道方案对比（5 方案，stdin 四维最优）；8.3 认证流程 6 步（生成→传 Registry→注册自身→生成各模块 token→POST /tokens→stdin 传各模块）；8.4 模块读取（Python/Node.js/Go 示例）；8.5 Launcher 写入（Python 示例）；8.6 Registry 验证逻辑；8.7 新增 POST /tokens 接口；8.8 token 生命周期（首次/重启/整体重启） |
+
+---
+
+### [事件中心设计.md](事件中心设计.md) 详细摘要
+
+| § | 行区间 | 内容摘要 |
+|---|--------|---------|
+| 1 定位 | L3-12 | core 模块，职责单一：接收/路由/订阅/去重/ACK；不是消息队列，不持久化不保证离线投递 |
+| 2 设计决策 | L14-27 | WebSocket（FastAPI 内置 HTTP+WS 共端口）；不持久化；认证调 Registry /verify；NATS 风格匹配；去重 1h dict；ACK 确认；默认不自发自收；转发失败不重试；30s 单定时器 |
+| 3 WS 协议 | L29-95 | 连接 `ws://.../ws?token=...`→/verify→加入连接表；模块→Hub（event 含 event_id/type/event/source/data，subscribe 含 events 列表，unsubscribe）；Hub→模块（原样转发、ack 含 event_id、error 含 message） |
+| 4 处理流程 | L97-125 | 7 步：解析 JSON→校验必填→去重检查→自动补全 source/timestamp→遍历订阅匹配（跳过发送者）→并发转发→返回 ack |
+| 5 匹配规则 | L127-165 | `*` 匹配恰好一段，`>` 匹配一段或多段（只能末尾）；组合示例表；Python 实现 `match_event()` |
+| 6 去重可靠性 | L167-237 | 6.1 三种未收到 ack 场景（断线/延迟/格式错误）；6.2 seen_events dict 1h 窗口 30s 清理；6.3 Outbox 两层——内存 pending_acks（收 ack 删除/收 error 删除不重发/超时 5s 重发一次/断线写磁盘）+ 磁盘 event_outbox.jsonl（仅断线写入，重连后逐条检查 timestamp，超 1h 丢弃，未过期重发，全部 ack 后清空）；6.4 发送方→Hub at-least-once，Hub→订阅方 best-effort |
+| 7 认证 | L239-310 | 不持 token 映射（避免同步），调 Registry POST /verify；重复连接关闭旧连接清空旧订阅；断线立即清理连接+订阅 |
+| 8-10 | L312-426 | /health（status+connections/subscriptions/events_routed/dedup_size）；/stats（连接详情/订阅详情/计数器）；启动 6 步（stdin→端口→FastAPI→注册→定时器→就绪）；5 个数据结构（connections/connection_info/subscriptions/seen_events/counters） |
+| 11 场景 | L428-497 | 连接并订阅（查 Registry→建 WS→subscribe）；事件发布转发（发→去重→匹配→转发→ack）；断线重连（pending 写 outbox→重连→重新 subscribe→重发 outbox→去重→清空） |
+| 13 决策 | L513-524 | 重复连接清空订阅；`>` 限末尾；断线立即清理；不订阅 module.stopped；不限大小；/stats 无需认证；gather 并发超时隔离；outbox 公共 py 文件 |
+
+---
+
+### [Launcher启动器文档.md](Launcher启动器文档.md) 详细摘要
+
+| § | 行区间 | 内容摘要 |
+|---|--------|---------|
+| 1-2 | L3-51 | 入口+控制台，极简极稳；`python main.py` 启动示例输出；退出 Ctrl+C/q；依赖 fastapi uvicorn httpx |
+| 3 启动序列 | L53-131 | 11 步：cleanup_leftovers→_start_registry（等待 stdout port 消息→写入 KITE_REGISTRY_PORT）→_start_api_thread（bind 0 获端口→独立线程 uvicorn）→_register_self→scan→init desired_state→_register_module_tokens→_start_enabled_modules（拓扑序→stdin token→等 module.ready→发 module.started→断开 stdio）→persist_records→_connect_event_hub→_heartbeat_loop（30s）→_monitor_loop（1s）；重启时新 token 旧失效 |
+| 4 线程 | L133-157 | 主线程（asyncio 启动+监控）、API 线程（daemon uvicorn）、stdout 线程（每子进程一个，加前缀输出）、Windows 键盘线程（msvcrt 轮询）；子进程 CREATE_NO_WINDOW |
+| 5 发现 | L159-281 | core/+extensions/ 始终内置扫描，discovery 配置叠加额外源（scan_dir / module_list），每项可独立启用/禁用；模块名唯一（重名跳过）；module.md 12 字段表；三层状态模型；Polyglot；stdin boot_info JSON |
+| 6 故障 | L283-316 | 每秒 check_exited 非阻塞；core 崩溃→全量重启（11 步）；非 core→Watchdog 决定；连续 3 次→failed；3+ 模块 failed→Launcher 退出 |
+| 7 遗留 | L318-357 | processes.json 格式（name/pid/cmd/module_dir/started_at）；清理：PID 存活（Linux os.kill / Windows tasklist）+ 命令行匹配（Linux /proc / macOS ps / Windows wmic）→确认杀 |
+| 8 API | L359-480 | GET /launcher/modules（列表+三层状态+pid+monitor）；POST .../start（enabled/manual 可启动，disabled 403）；POST .../stop（可选 reason: stop_requested/hot_update/restart/resource_critical）；POST .../restart（stop+start）；POST /launcher/rescan（发现新增/移除）；PUT .../state（修改 module.md state，core 不可 disabled） |
+| 9 跨平台 | L482-496 | 7 项差异表（进程检查/命令行匹配/终止/强杀/子进程窗口/退出信号/最终退出） |
+| 10 端口 | L498-518 | 全部 OS 动态分配；Registry 端口发现（stdout port 消息→KITE_REGISTRY_PORT 环境变量）；Launcher API（bind 0）；preferred_port（模块从 module.md 读取，绑定失败回退） |
+| 11 安全 | L519-549 | KITE_TOKEN 全局（secrets.token_hex(32) 64 字符）→通过 stdin 传 Registry；per-module token→POST /tokens→stdin 传各模块；6 安全特性（独立 token/kite_token 特权/不持久化/127.0.0.1/不在 cmd/重启刷新） |
+| 14 类参考 | L579-675 | Launcher 类 10 属性 + 15 方法；ProcessManager 7 方法；ModuleInfo 12 字段 + is_core()；ProcessRecord 5 字段 |
+
+---
+
+### [事件处理机制.md](事件处理机制.md) 详细摘要
+
+| § | 行区间 | 内容摘要 |
+|---|--------|---------|
+| 概述 | L1-10 | 发布-订阅模式，所有模块通过 Kernel EventHub 通信；统一队列缓冲架构 |
+| 核心架构 | L12-35 | 事件流转：发布者→EventHub路由→订阅者队列→消费循环→事件处理；统一队列（含Kernel）、异步消费、背压控制、异常隔离 |
+| 事件格式 | L37-56 | JSON-RPC 2.0 Notification 格式（event_id/event/source/timestamp/data） |
+| 事件类型 | L58-77 | 系统事件（module.registered/ready/offline/heartbeat_timeout/kernel.shutdown）+ 业务事件（命名规范 `{namespace}.{action}`） |
+| 订阅机制 | L79-105 | event.subscribe RPC 方法；通配符支持（`*` 单段 / `>` 多段尾部）；订阅生命周期（注册时/运行时/取消/自动清理） |
+| 发布机制 | L107-135 | 外部模块通过 event.publish RPC；Kernel 通过 publish_internal() 直接发布 |
+| 队列与背压 | L137-165 | 队列大小 1000 条；溢出时阻塞发送者（背压）；支持 10,000+ 事件/秒 |
+| 消费循环 | L167-195 | 外部模块通过 WebSocket 接收；Kernel 通过回调函数处理 |
+| 异常处理 | L197-220 | 消费异常隔离（单模块异常不影响其他）；路由异常捕获记录 |
+| 事件去重 | L222-235 | 去重窗口 1000 个事件；去重键 `(source, event_type, data_hash)`；内部事件不去重 |
+| 优雅退出 | L237-250 | 退出流程：shutdown 事件→ack→exiting→清理；事件序列说明 |
+| 调试与监控 | L252-275 | 实时统计（received/routed/overflow/subscribers）；日志输出关键操作 |
+| 最佳实践 | L277-305 | 事件命名规范；订阅粒度建议；数据大小限制；异常处理要求 |
+
+---
+
+### [事件订阅通配符规范.md](事件订阅通配符规范.md) 详细摘要
+
+| § | 行区间 | 内容摘要 |
+|---|--------|---------|
+| 概述 | L1-5 | NATS-style 通配符匹配，支持灵活的事件过滤和路由 |
+| 通配符类型 | L7-95 | `*` 单段通配符（匹配恰好一个段，可多次使用）；`>` 多段通配符（匹配一个或多个段，只能在末尾）；详细示例和组合用法 |
+| 匹配规则 | L97-165 | 基本规则（段分割/逐段比较/段数要求）；匹配算法 Python 实现；匹配示例表（12 个示例） |
+| 常见模式 | L167-195 | 订阅所有事件（`>`）；订阅特定命名空间（`module.>`）；订阅特定类型（`*.ready`）；订阅多个模式 |
+| 性能考虑 | L197-235 | 匹配效率 O(n)；订阅建议（优先精确匹配/避免过度使用 `>`）；路由优化（匹配成功立即 break） |
+| 错误用法 | L237-265 | `>` 不能在中间；段数不匹配；空段无效 |
+| 系统对比 | L267-285 | NATS vs fnmatch 对比表；选择 NATS-style 的原因（简单明确/性能优秀/行业标准/足够灵活） |
+
+---
+
+### [Polyglot运行时与Clawdbot兼容性设计.md](Polyglot运行时与Clawdbot兼容性设计.md) 详细摘要
+
+| § | 行区间 | 内容摘要 |
+|---|--------|---------|
+| 1-2 | L3-13 | Clawdbot 成熟生态（10+ channel/50+ skill TypeScript）；进程隔离+WebSocket+JSON 天然语言无关 |
+| 3 多运行时 | L15-47 | module.md 增 runtime 字段（python 默认/node/binary），Launcher 选解释器；模块协议不变（连 Registry+Event Hub+/health） |
+| 4 SDK | L49-63 | Python `kite-module-sdk` + Node.js `@kite/module-sdk`；封装 Registry 连接注册/Event Hub WS/outbox 持久化/健康检查/参数解析 |
+| 5 Channel 接入 | L65-148 | 一个 clawdbot-bridge 模块（Node.js）承载所有 channel 多路复用；目录（entry.js/module.md/package.json/adapter.js/config.json）；启动扫描 plugin→初始化→注册 channels→收消息发 Kite 事件→收指令路由 outbound；新 channel 仅 npm install+config 启用；默认同进程可拆隔离；依赖映射表（Session→Kernel/Config→Registry/Security→身份管理/Tool→Registry） |
+| 6 Skill 接入 | L150-299 | Skill 系统分析（懒加载/上下文感知/四层 policy/tool factory context 8 字段）；两层兼容——第一层跳过 policy 用 Kite 权限（API 类 skill 够用）、第二层 context-adapter 转换（channel-docked/session-aware）；独立 Service 模块（loader.js/context-adapter.js）；启动时提取 tool 定义注册 Registry 暴露 HTTP，调用时 Agent 透明 HTTP POST；Context 转换示例（workspace/agentId/sessionKey/messageChannel 映射）；兼容矩阵 7 类（API 类=第一层/文件类=第一层/channel 关联=第二层/session 感知=第二层/sandbox=不兼容用 Kite 替代/本地环境=第二层+/平台特定=平台限制）；权限：Kite 唯一权限源，跳过 clawdbot resolveEffectiveToolPolicy，tool group 映射 switches 批量配置 |
+| 7-8 | L301-322 | 身份映射表（owner→role:owner/allowlist→channel 级 permission/pairing→自动创建 unidentified/session→agent-peer 会话）；5 项收益 |

package/docs/KITE_DOCS_GUIDE.md

@@ -0,0 +1,33 @@
+# Kite 文档查阅指南
+
+Kite 框架设计文档在 `docs/` 下，索引文件 `docs/INDEX.md` 分三层，**严格按需逐层加载，禁止一次性读取整个索引**。
+
+行区间格式：`L43-49` 表示用 Read 工具读取时 读取第43行到49行。
+
+## 渐进式查阅流程
+
+### Step 1：只读 Layer 1（L1-62）
+
+列出所有文档名和章节行区间。能直接定位目标 → 跳 Step 4。
+
+**特别注意**：如果涉及 WebSocket 接收循环实现，必须先读 [WebSocket接收循环死锁防范规范](WebSocket接收循环死锁防范规范.md)（🔴 最高优先级）。
+
+### Step 2：按需读 Layer 2 对应小节
+
+仅当 Step 1 不够时，按关键词读：
+
+身份 L60-66 · 会话 L68-71 · 事件 L73-81 · 模块生命周期 L83-93 · 配置 L95-103 · 认证安全 L105-109 · 工具权限 L111-116 · Hook L118-120 · Launcher L122-134 · Registry L136-143 · Agent L145-150 · 渠道 L152-156 · 任务 L158-162 · 工作区 L164-167 · 异常处理 L169-176 · Watchdog L178-183 · 分布式 L185-188 · 多语言 L190-195 · 启动流程 L197-205 · 路线图 L207-213 · 链路追踪 → [链路追踪方案](链路追踪方案.md) 全文 · 架构借鉴（对标龙虾/CoPaw）→ [架构借鉴指南](架构借鉴指南.md) 全文 · 握手认证 → [握手认证方案](握手认证方案.md) 全文 · 多连接控制 → [模块多连接控制策略](模块多连接控制策略.md) 全文
+
+### Step 3：按需读 Layer 3 单篇摘要
+
+仅当需要某篇详情但不确定读哪个章节时：
+
+核心概念 L223-236 · 系统架构 L238-252 · 模块规范 L254-264 · 注册中心 L266-279 · 事件中心 L281-296 · Launcher L298-314 · 事件处理机制 L316-334 · 事件订阅通配符 L336-348 · Polyglot L350-359
+
+架构改造方案 → [架构改造-合并Kernel方案](架构改造-合并Kernel方案.md) 全文
+
+大多数问题在摘要层就能解答。
+
+### Step 4：读原文目标章节
+
+根据前面获得的文档路径和行区间，精确读取对应章节。**只有需要完整分析时候才整篇原文。**