@agentunion/kite 1.4.0 → 1.6.0

package/docs/Kite/346/241/206/346/236/266/350/256/276/350/256/241/01-/346/241/206/346/236/266/345/256/232/344/275/215.md

@@ -0,0 +1,12 @@
+# 1. 框架定位
+
+Kite 是一个**事件驱动的多 Agent 运行时框架**，为构建各类 AI Agent 应用提供基础设施。框架本身不包含任何特定应用逻辑，所有功能通过模块化扩展。
+
+核心能力：
+- 事件驱动架构
+- 模块化扩展
+- 服务注册与发现
+- 多进程隔离
+- 统一的身份和权限体系
+- 任务管理
+- 大模型调用抽象

package/docs/Kite/346/241/206/346/236/266/350/256/276/350/256/241/02-/346/240/270/345/277/203/346/246/202/345/277/265.md

@@ -0,0 +1,341 @@
+# 2. 核心概念
+
+## 2.1 身份（Identity）
+
+系统中所有参与者（人、群或 Agent）共享统一的身份模型。**所有身份地位平等**，代理、用户、联系人、群只是角色标记，不存在层级关系。
+
+一个身份可以拥有多个渠道上的多个 ID：
+
+```
+身份 (Identity)
+├── 渠道 ID: phone:138xxxx
+├── 渠道 ID: email:xxx@xxx.com
+├── 渠道 ID: aid:abc123
+└── 角色标记: agent / owner / contact / group（可多个）
+```
+
+**身份存储结构：**
+
+所有身份平铺在 `identities/` 目录下，纯身份信息。通过索引目录实现渠道 ID → 身份的映射：
+
+```
+identities/
+├── _index/                              ← 索引目录
+│   ├── phone_13800138000.json           ← {"identity": "王老板"}
+│   ├── phone_18766661234.json           ← {"identity": "小助手"}
+│   ├── phone_13900139000.json           ← {"identity": "phone_13900139000"}
+│   ├── wechat_group_abc123.json         ← {"identity": "项目X讨论群"}
+│   └── ...
+├── 王老板/                              ← 已确认身份
+│   ├── profile.md                       ← 身份信息（frontmatter + 正文）
+│   └── history.jsonl                    ← 身份变更记录
+├── 小助手/                              ← agent 身份（扁平共存）
+│   ├── profile.md                       ← agent 人设（含 owners）
+│   └── history.jsonl
+├── phone_13900139000/                   ← 未识别身份
+│   ├── profile.md
+│   └── history.jsonl
+├── 项目X讨论群/                          ← 群身份（与个人扁平共存）
+│   ├── profile.md
+│   └── history.jsonl
+└── ...
+```
+
+**profile.md 格式：**
+
+所有身份（agent、contact、group）都使用 profile.md，格式统一，仅 role 和具体字段不同。
+
+agent 身份：
+```markdown
+---
+name: 小助手
+role: agent
+status: identified
+channels:
+  - phone: "18766661234"
+  - sms: "18766661234"
+owners:
+  - 张三
+  - 李四
+---
+
+我是一个电话助手，性格温和，说话简洁...
+```
+
+联系人身份：
+```markdown
+---
+name: 王老板
+role: contact
+status: identified
+channels:
+  - phone: "13800138000"
+  - wechat: "wang_boss"
+---
+
+张三的合作伙伴，做建材生意...
+```
+
+**status 字段：**
+- `unidentified` — 首次遇到，仅有 channel_id，尚未确认真实身份
+- `identified` — 已确认身份，目录名为人类可读名称
+- `merged` — 已被合并到其他身份（保留目录作为重定向，profile.md 记录合并目标）
+
+**history.jsonl — 身份变更记录：**
+
+记录身份从创建到当前的所有变更，用于回溯和审计：
+
+```jsonl
+{"event": "created", "at": "2026-02-27T10:00:00", "source": "phone_13800138000", "note": "首次来电自动创建"}
+{"event": "identified", "at": "2026-02-27T10:05:00", "from": "phone_13800138000", "to": "王老板", "by": "小助手", "note": "通话中确认身份"}
+{"event": "channel_added", "at": "2026-02-27T11:00:00", "channel": "wechat", "id": "wang_boss", "note": "通话中获知微信号"}
+{"event": "merged", "at": "2026-02-28T09:00:00", "absorbed": "wechat_wang_boss", "note": "合并微信身份"}
+{"event": "profile_updated", "at": "2026-02-28T09:01:00", "field": "name", "from": "王老板", "to": "王建国", "note": "确认全名"}
+```
+
+事件类型：`created`、`identified`、`channel_added`、`channel_removed`、`merged`、`split`、`profile_updated`
+
+**身份识别与合并：**
+- 首次遇到一个渠道 ID 时，创建 `{channel}_{id}` 命名的身份文件夹，同时在 `_index/` 下创建索引
+- 当确认多个渠道 ID 属于同一个人或同一个群时，由 LLM 执行合并操作：将多个文件夹合并为一个，文件夹名改为人类可读的姓名/昵称/群名，更新索引指向
+- 所有变更记录到 history.jsonl，支持回溯
+
+**角色标记：**
+- `agent` — 系统执行主体，profile.md 中定义 owners 列表
+- `owner` — agent 的主人，最高权限（owner 关系是 per-agent 的，不同 agent 身份可以有不同的主人）
+- `contact` — 交互对象（个人）
+- `group` — 群/群组，也是一等公民身份，拥有 profile.md 和 history.jsonl，与 contact 共享相同的存储结构
+- 一个身份可以同时有多个角色（如某人既是某 agent 的 owner 又是 contact）
+
+**群身份示例：**
+
+群与个人联系人在身份层没有额外信息，只是 role 不同。群成员关系等业务数据存放在工作区 `{agent}/data/{group_id}/` 下，不在身份层。
+
+```markdown
+---
+name: 项目X讨论群
+role: group
+status: identified
+channels:
+  - wechat: "group_abc123"
+---
+
+张三的项目组工作群，讨论项目进度和技术问题。
+```
+
+**群的路由与处理：** Kernel 根据 peer 的 role 决定路由到哪个 Agent 模块。`contact` 类型路由到对话 Agent，`group` 类型路由到群处理 Agent（见 2.5 节）。
+
+## 2.2 渠道（Channel）
+
+渠道是消息传输通道，以模块形式接入。每个渠道提供：
+- **事件** — 渠道上发生的事情（消息到达、连接状态变化等）
+- **工具** — 在渠道上执行的操作（发送消息、建立连接等）
+
+渠道类型示例：电话、短信、邮箱、即时通讯、Web 接口、ACP 网络等。
+
+## 2.3 事件（Event）
+
+事件是系统中所有交互的基本单元。事件驱动系统运行。
+
+事件结构：
+```json
+{
+  "event_id": "uuid",
+  "type": "event",
+  "event": "channel.message.received",
+  "source": "module_name",
+  "timestamp": "2026-02-26T10:00:00Z",
+  "data": { ... }
+}
+```
+
+事件类型示例：
+- `channel.message.received` — 收到消息
+- `channel.message.sent` — 消息已发送
+- `channel.connected` — 渠道连接成功
+- `channel.disconnected` — 渠道断开
+- `channel.error` — 渠道异常
+- `session.started` — 会话开始
+- `session.ended` — 会话结束
+- `task.created` — 任务创建
+- `task.completed` — 任务完成
+- `module.starting` — 模块即将启动
+- `module.ready` — 模块服务就绪
+- `module.started` — 模块启动成功
+- `module.stopped` — 模块停止
+- `module.state_changed` — 模块状态变更
+
+## 2.4 会话（Session）
+
+会话是代理与某个身份（contact 或 group）之间的一次交互过程。会话由一系列事件组成。
+
+会话属性：
+- **会话 ID** — 唯一标识
+- **参与者** — 代理 ID + 对方 ID
+- **对方类型** — 私聊（peer）或群（group），决定路由到哪个 Agent
+- **渠道** — 通过哪个渠道
+- **方向** — 主动发起（outgoing）或被动接收（incoming）
+- **来源** — 触发方式（api / auto / manual）
+- **状态** — active / ended / failed
+
+会话在不同阶段由不同的 Agent 处理。
+
+**Session Key 与会话隔离：**
+
+Session key 决定了"哪些消息属于同一个对话"，是会话数据存储路径的依据。session key 的生成规则由 Kernel 中的 `resolve_session_key()` 函数统一管理，不在各处硬编码。
+
+私聊和群使用不同的 key 结构：
+
+```
+# 私聊（一对一）
+session_key = "{agent}:peer:{peer_identity}"
+
+# 群
+session_key = "{agent}:group:{group_identity}"
+```
+
+私聊的 session scope 可配置（在工作区 config.json 中）：
+
+| scope | session key 格式 | 说明 |
+|-------|-----------------|------|
+| `per-peer` | `{agent}:peer:{peer}` | 同一个联系人跨渠道共享上下文（默认） |
+| `per-channel-peer` | `{agent}:{channel}:peer:{peer}` | 不同渠道独立上下文 |
+
+群的 session key 始终按群隔离，不按发言人。群的上下文是群的，不是某个发言人的。但 agent 同时会更新发言人的 identity 信息（跨 session 的关系记忆）。
+
+**消息记录格式：**
+
+messages.jsonl 统一支持多发言人，私聊和群使用相同格式：
+
+```jsonl
+{"sender": "wang-boss", "content": "项目进度怎么样了", "timestamp": "2026-02-27T10:00:00Z", "channel": "wechat"}
+{"sender": "agent", "content": "报告已经写好了", "timestamp": "2026-02-27T10:00:05Z", "channel": "wechat"}
+```
+
+群消息额外可带 `triggered_by` 字段，记录 agent 回复的触发原因：
+
+```jsonl
+{"sender": "agent", "content": "我可以帮忙审阅", "timestamp": "...", "channel": "wechat", "triggered_by": "mention"}
+```
+
+## 2.5 Agent
+
+Agent 是实际执行 LLM 调用的处理单元。Agent 是模块，与 Channel、Kernel 等一样遵循统一模块规范（enabled/manual/disabled 三态）。每个 Agent 是独立的常驻进程，通过事件与系统交互。
+
+**进程模型：** 每种 Agent 类型只有一个进程实例。Agent 内部通过异步协程并发处理多个会话——收到事件时创建新的异步会话协程，而非启动新进程。例如 conversation Agent 同时处理 5 通电话时，是一个进程内 5 个并发协程。
+
+**生命周期管理：**
+- **启动** — enabled 状态的 Agent 随系统启动，由 Launcher 管理保活（进程异常退出时自动重启）
+- **按需启动** — manual 状态的 Agent 可由其他 Agent 通过 Launcher API 启动
+- **自主管理** — Agent 的内部状态（会话管理、资源清理等）由自身负责
+- **事件驱动** — Agent 启动后订阅关心的事件，收到事件时创建会话协程处理
+
+**Agent 类型（草案）：**
+
+以下类型划分为初始草案。实际场景中，一个主 Agent 模块（如 conversation）可能就足够处理大部分对话场景，其他类型作为辅助 Agent 按需存在（如压缩、总结、身份管理等）。辅助 Agent 不一定需要独立进程，可以由主 Agent 在协程内按需调用 Model Service 完成。
+
+| 类型 | 职责 | 触发事件 |
+|------|------|---------|
+| **conversation** | 对话循环 — 一对一的交互 | 会话建立后 |
+| **group** | 群处理 — 观察群消息、判断是否参与、按需回复 | 群消息到达时 |
+| **post** | 后处理 — 总结、评估、身份检查、触发后续 | 会话结束后 |
+| **planner** | 任务规划 — 复杂目标拆分 | 任务创建时 |
+
+**conversation 与 group 的核心区别：**
+- conversation：收到消息 → 进入 LLM loop → 回复。每条消息都期待响应。
+- group：收到消息 → 观察/记录 → 判断是否需要行动 → 可能回复、可能触发任务、可能什么都不做。大部分消息只需"听到"，不需要回复。
+
+Kernel 根据 peer identity 的 role（`contact` → conversation，`group` → group）路由到对应的 Agent 模块。
+
+Agent 可通过 Launcher API 启动其他 Agent（如 conversation 按需启动 retrieval）。
+
+## 2.6 工具与技能
+
+工具和技能是 Agent 可调用的能力单元。从加载到调用分为三个阶段：
+
+**阶段一：加载定义。** 从以下三个位置加载工具和技能定义，合并后注入上下文：
+
+1. **系统内核** — `kernel/tools/` 和 `kernel/skills/`（全局可用）
+2. **发起方 Channel** — `{channel}/tools/` 和 `{channel}/skills/`（渠道特有能力）
+3. **当前 Agent** — `{agent}/tools/` 和 `{agent}/skills/`（Agent 特有能力）
+
+**阶段二：开关过滤。** 多级开关控制哪些工具和技能对当前会话可见：
+
+| 级别 | switches 位置 | 说明 |
+|------|-------------|------|
+| 1. 全局 | `kernel/data/switches.json` | 全局开关 |
+| 2. Channel | `{channel}/data/switches.json` | 渠道级开关 |
+| 3. Agent 模块 | `{agent_module}/data/switches.json` | Agent 模块级开关 |
+| 4. 工作区 agent 级 | `{workspace}/config.json` → switches | agent 级开关 |
+| 5. 工作区 peer/group 级 | `{workspace}/data/{peer}/config.json` → switches | peer/group 级开关 |
+
+合并规则：deny wins。任一级 disabled 即不注入 LLM 上下文，peer/group 级不能放宽 agent 级的禁止。
+
+**阶段三：调用时权限检查。** 工具/技能被实际调用时，由工具/技能自身执行权限检查。
+
+**context 构造：** Kernel 在上下文组装阶段将权限相关信息打包到事件 payload 中，Agent 模块的工具调用层直接使用，随 args 传给工具提供者：
+
+```python
+context = {
+    "workspace": str,             # 最终工作区路径
+    "agent_identity": str,        # agent 身份名
+    "peer_identity": str,         # 对方身份名（contact 或 group）
+    "channel": str,               # 当前渠道名
+    "session": dict,              # 会话信息
+    "task_info": dict | None,     # 任务信息（如有）
+}
+```
+
+注意 context 中不包含 `is_owner` 字段。owner 身份由工具提供者在 `check_permission` 中独立验证（读取 `identities/{agent}/profile.md` 中的 owners 列表比对 peer identity），不信任调用方传入的值。
+
+**权限检查数据来源：** 工具提供者从 context 中获取 workspace 路径，读取 config.json 中的 permissions 配置（已由 Kernel 合并 agent 级 + peer/group 级，deny wins）。
+
+**工具/技能自主检查：** handler.py 中必须实现统一命名的权限检查函数：
+
+```python
+def check_permission(args: dict, context: dict) -> str | None:
+    """检查权限。返回 None 表示通过，返回字符串表示拒绝原因（含来源）。"""
+```
+
+模块收到工具调用请求时，先调用 handler 的 `check_permission(args, context)`，返回非 None 则直接返回拒绝，不调用 `execute()`。这是模块规范约定，agent 可通过审查模块的工具分发代码验证。
+
+**信任模型说明：** context 由 Kernel 组装并通过事件传递，工具提供者对关键安全判断做独立验证：
+- **owner 身份** — 工具提供者自行读取 agent 身份的 profile.md 中的 owners 列表，不依赖 context 传值
+- **权限配置** — 工作区 config.json 中的 permissions 由 Kernel 合并，工具提供者可自行读取验证
+- **会话信息** — channel、identity 等字段用于业务逻辑，工具提供者可按需校验
+
+**权限检查规则：**
+- 权限格式由工具/技能自定义（如文件工具用 `allowed_paths`/`denied_paths`，短信工具可能用 `allowed_numbers`）
+- 整体默认值：owner 默认允许，非 owner 默认拒绝
+- 跨级合并：deny wins
+- 被拒绝时记录来源
+
+**反提权保护：** 文件操作类工具（read_file、write_file 等）必须在 `check_permission` 中阻止非 owner 修改 config.json 中的 switches 和 permissions 字段，防止通过工具调用修改自身权限。
+
+**权限修改流程：** 只有 owner 身份可以修改权限配置。owner 要求 agent 调整某工具/技能的权限时，agent 修改工作区 config.json 中对应的 permissions 字段。
+
+## 2.7 任务（Task）
+
+任务是系统中需要完成的工作单元。任务可以由以下方式创建：
+- 外部 API 调用
+- Agent 决策产生（如会话结束后需要跟进）
+- 定时触发
+- 手动创建
+
+任务属性：
+- **任务 ID** — 唯一标识
+- **类型** — 任务类型（自定义）
+- **目标** — 任务要达成的目标
+- **状态** — pending / in_progress / completed / failed
+- **优先级** — 紧急程度
+- **父任务** — 如果是后续任务，记录父任务 ID
+- **创建者** — 谁创建的（Agent / API / 用户）
+- **执行者** — 谁在执行（Agent 实例）
+
+## 2.8 工作模式
+
+系统支持两种工作模式（可按联系人或群配置）：
+
+**托管模式（Managed）** — AI 完全自主决策，收到事件后自动处理。
+
+**授权模式（Authorized）** — 收到事件后，通过 webhook 请示外部系统或主人，等确认后再执行。

package/docs/Kite/346/241/206/346/236/266/350/256/276/350/256/241/03-/347/263/273/347/273/237/346/236/266/346/236/204.md

@@ -0,0 +1,257 @@
+# 3. 系统架构
+
+## 3.1 进程模型
+
+```
+main.py（Launcher 进程，有控制台，输出所有日志）
+  │
+  ├─① 检查遗留进程
+  │     → 读取持久化的子进程记录（进程名 + PID + 启动命令参数）
+  │     → 比对当前系统进程（不只看 PID，还要匹配进程名和启动命令参数）
+  │     → 确认是上次遗留的进程则杀死
+  │
+  ├─② 生成所有模块专属 token，启动 Kernel (kernel/)
+  │     → 通过 stdin 传入 boot_info token 和 tokens 映射表
+  │     → Kernel 分配端口 → 通过 stdout 回传端口
+  │     → Launcher 连接 Kernel WebSocket，订阅所有事件
+  │     → Launcher 通过 RPC 向 Kernel 注册自身
+  │
+  └─③ 扫描所有模块的 module.md，并行启动 config_state: enabled 的模块
+        → 通过 stdin 向每个模块传入 {"token": "..."} 和 kernel_port
+        → Model Service、Task System、Web Admin、各 Channel、各 Agent ...
+        → 每个模块自行: 连接 Kernel WS → 通过 RPC 注册 → 订阅事件 → 发布 module.ready
+        → manual 状态的模块不自动启动，等待手动或接口调用启动
+        → 持久化所有子进程信息（进程名 + PID + 启动命令参数）
+```
+
+Launcher 只保证 Kernel 先就绪，其余模块并行启动。模块间的依赖通过 Kernel 的服务发现机制解决——模块启动后轮询或订阅等待所需服务上线。
+
+**子进程监控与故障恢复：**
+
+Launcher 监听子进程退出信号。所有子进程无控制台，日志统一输出到 Launcher 进程的控制台。
+
+- **core 模块**（Kernel）退出 → Launcher 触发 Kite 整体重启：通知所有子进程优雅退出，超时强杀，然后重新启动所有模块
+- **非 core 模块**退出 → 由保活模块（见 3.8）处理，通过 Launcher RPC 重启
+- **多次重启仍失败** → 日志输出故障信息，Launcher 退出（整个 Kite 停止）
+
+**优雅退出：** Launcher 收到退出信号（Ctrl+C / SIGTERM）时，向所有子进程发送退出通知，等待超时后强杀未退出的进程，清理持久化的进程记录，然后退出。
+
+## 3.2 启动器（Launcher）
+
+Launcher 与 main.py 在同一进程中（Launcher 进程），是整个 Kite 系统的入口和控制台。职责：启停模块、监听子进程退出、遗留进程清理、优雅退出。Launcher 的健壮性要求最高，代码应极简，极小概率崩溃。
+
+**模块三层状态模型：**
+
+| 层 | 名称 | 值 | 谁写 | 存在哪 |
+|----|------|---|------|--------|
+| 配置状态 | `config_state` | enabled / manual / disabled | owner 修改 module.md | module.md |
+| 期望状态 | `desired_state` | running / stopped | 其他模块通过 Launcher API 改变 | Launcher 内存 |
+| 实际状态 | `actual_state` | running(PID) / stopped | Launcher 观测进程 | Launcher 内存 |
+
+初始化规则：
+- enabled → desired_state 初始为 running
+- manual → desired_state 初始为 stopped
+- disabled → desired_state 固定为 stopped，不可改
+
+Launcher 启动时扫描 `launcher/`、`kernel/` 和 `extensions/` 下所有模块目录，读取各自的 `module.md`，按 config_state 决定是否启动。core 模块（kernel）始终 enabled，不可禁用。
+
+**Launcher RPC 方法（通过 Kernel 调用）：**
+```
+launcher.list_modules        ← 查询所有模块及状态
+launcher.start_module        ← 启动模块（enabled 或 manual）
+launcher.stop_module         ← 停止模块
+launcher.restart_module      ← 重启模块
+launcher.rescan              ← 重新扫描模块
+launcher.shutdown            ← 关闭整个 Kite
+```
+
+**模块间启停：** 任何模块都可以通过 Kernel RPC 调用 Launcher 方法来启动或停止其他模块。例如：某模块发现依赖的服务不在线，可调用 `launcher.start_module` 启动它。disabled 状态的模块无法被启动，必须先由 owner 修改 state。
+
+**模块生命周期事件：**
+- `module.starting` — 模块即将启动（Launcher 广播）
+- `module.ready` — 模块服务就绪（模块发出，Launcher 据此判定启动成功）
+- `module.started` — 模块启动成功（Launcher 收到 ready 后广播）
+- `module.stopped` — 模块停止
+- `module.state_changed` — 模块状态变更（含变更前后状态和操作者）
+
+## 3.3 内核（Kernel）
+
+独立进程，合并了注册中心（Registry）和事件中心（Event Hub）的功能，使用 WebSocket JSON-RPC 2.0 协议提供统一的服务注册、发现和事件路由能力。
+
+**核心功能：**
+- 服务注册与发现 — 所有模块的"电话簿"
+- 事件路由 — 根据订阅关系转发事件
+- 跨模块 RPC 转发 — 模块间通过 Kernel 调用彼此的 RPC 方法
+- 能力索引 — 工具、Hook、事件的聚合查询
+- 通用字段查询 — 支持 glob 通配符的灵活搜索
+
+**模块认证：** 每个模块拥有独立的专属 token，由 Launcher 生成并通过 stdin 管道传递（内核级 IPC，只有父子进程可读写）。Launcher 启动 Kernel 时传入 tokens 映射表，模块连接 Kernel WebSocket 时带 `?token={token}&id={module_id}` 参数。泄露一个 token 不影响其他模块。
+
+**WebSocket JSON-RPC 2.0 协议：**
+
+注册模块：
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "uuid",
+  "method": "registry.register",
+  "params": {
+    "module_id": "module_name",
+    "type": "service",
+    "capabilities": {...}
+  }
+}
+```
+
+订阅事件：
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "uuid",
+  "method": "event.subscribe",
+  "params": {
+    "events": ["channel.message.*", "session.*"]
+  }
+}
+```
+
+发布事件：
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "uuid",
+  "method": "event.publish",
+  "params": {
+    "event_id": "uuid",
+    "event": "module.ready",
+    "data": {...}
+  }
+}
+```
+
+跨模块 RPC 调用：
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "uuid",
+  "method": "launcher.restart_module",
+  "params": {"module_name": "watchdog"}
+}
+```
+
+Kernel 自动转发到目标模块，返回结果或超时错误（默认 5s）。
+
+**内置 RPC 方法：**
+```
+registry.register       ← 注册模块
+registry.lookup         ← 查询模块
+registry.heartbeat      ← 心跳续约
+event.subscribe         ← 订阅事件
+event.unsubscribe       ← 取消订阅
+event.publish           ← 发布事件
+kernel.ping             ← 心跳检测
+kernel.stats            ← 获取统计信息
+```
+
+**HTTP 接口（仅用于调试）：**
+```
+GET    /health         ← Kernel 自身健康（无需 token）
+GET    /stats          ← 统计信息（连接数、事件数等）
+```
+
+**心跳与 TTL：** 模块注册后需定期心跳续约（默认每 30s），超过 TTL（默认 60s）未心跳则标记 offline，从索引中摘除但记录保留。主动注销（`registry.deregister`）立即清理记录。
+
+**连接管理：** 模块断开 WebSocket 连接时，Kernel 自动标记为 offline 并发布 `module.offline` 事件。重连后需重新注册和订阅。
+
+**事件去重：** Kernel 维护去重窗口（内存 set，保留最近 1 小时的 event_id），收到重复事件时跳过转发，直接返回成功响应。
+
+**工具命名冲突：** 不阻止，如实记录。同名工具返回多个 provider，由调用方按优先级选择。冲突时记录警告日志。
+
+## 3.4 系统内核（Kernel）
+
+系统内核是框架的核心逻辑，以模块形式运行。
+
+**核心功能：**
+- 会话管理 — 创建、跟踪、结束会话
+- Agent 调度 — 根据事件和会话状态启动 Agent
+- 身份管理 — 管理代理、用户、联系人身份
+- 权限控制 — 多级开关过滤 + 配置合并（权限检查由工具提供者自行执行，见 2.6 阶段三）
+- 存储引擎 — 文件系统存储（JSONL + Markdown）
+- 内部 API — 供其他模块调用的服务接口
+
+**内置工具：**
+- 文件操作（read_file, write_file, edit_file, list_files）
+- 配置管理（get_config, set_config）
+- 身份查询（get_identity, search_contacts）
+
+## 3.5 模型服务（Model Service）
+
+独立进程，提供大模型调用能力。
+
+**核心功能：**
+- LLM 调用 — 支持 OpenAI / Claude / Gemini 等多种 API
+- 提示词管理 — 提示词模板和注入机制
+- 工具调用 — Function Calling / Tool Use
+- 流式输出 — 支持 SSE 流式响应
+- 配置管理 — 模型端点、Key、参数配置
+
+**注册到注册中心的配置：**
+- LLM 端点和 Key
+- 可用模型列表
+- 默认参数（temperature, max_tokens 等）
+
+## 3.6 任务系统（Task System）
+
+独立进程，提供任务管理能力。
+
+**核心功能：**
+- 任务创建 — 接收任务创建请求
+- 任务队列 — 管理待执行任务
+- 任务分配 — 将任务分配给 Agent
+- 任务跟踪 — 跟踪任务执行状态
+- 任务查询 — 提供任务查询接口
+
+**注册到注册中心的接口：**
+```
+POST   /tasks              ← 创建任务
+GET    /tasks              ← 查询任务列表
+GET    /tasks/{id}         ← 查看任务详情
+POST   /tasks/{id}/claim   ← 认领任务
+POST   /tasks/{id}/submit  ← 提交任务结果
+DELETE /tasks/{id}         ← 删除任务
+```
+
+**注册到注册中心的工具：**
+- `create_task` — Agent 可调用创建任务
+- `query_tasks` — 查询任务列表
+- `get_task` — 获取任务详情
+
+## 3.7 保活模块（Watchdog）
+
+扩展模块（非 core），负责应用层健康监控。Launcher 处理进程级故障（子进程退出），Watchdog 处理应用级故障（进程活着但不健康）。
+
+**核心功能：**
+- 心跳检测 — 定期通过 Kernel RPC 调用各模块的 `{module_id}.health` 方法
+- 资源监控 — 检测模块的 CPU / 内存 / 连接数等指标
+- 非 core 模块重启 — 发现异常时通过 Kernel RPC 调用 `launcher.restart_module`
+- 告警通知 — 模块持续异常时，通过可用的 Channel 通知 owner
+
+**Watchdog 是可降级的扩展模块**，崩溃时由 Launcher 按普通模块处理（尝试重启），不触发 Kite 整体重启。Watchdog 不可用期间系统仍正常运行，仅失去应用层健康监控能力。
+
+## 3.8 事件可靠性
+
+模块发送事件到 Kernel 可能失败（Kernel 重启、网络抖动等）。为保证事件不丢失，所有模块应实现以下机制：
+
+- **发送确认** — Kernel 收到事件后返回 JSON-RPC 响应
+- **本地持久化** — 未收到响应的事件写入本地文件（`{module}/data/event_outbox.jsonl`）
+- **自动重放** — 重连 Kernel 后，自动重发 outbox 中的未确认事件
+- **重连与重新订阅** — 与 Kernel 的 WebSocket 断开后自动重连，重连后重新注册和订阅事件
+
+**事件幂等性：** 自动重放可能导致事件重复（Kernel 已收到但响应丢失）。通过 `event_id` 去重解决：
+
+- 模块为每个事件生成唯一 `event_id`（UUID），写入事件体
+- Kernel 维护去重窗口（内存 set，保留最近 1 小时的 event_id）
+- 收到事件时先查去重表，已存在则跳过转发，直接返回成功响应
+- 重连后 outbox 重发的事件携带原始 event_id，Kernel 自动去重
+
+模块需自行实现事件可靠性机制（Kite 框架遵循零共享代码原则，不提供公共库）。