@agentunion/kite 1.4.0 → 1.6.0

package/docs//346/236/266/346/236/204/345/200/237/351/211/264/346/214/207/345/215/227.md

@@ -0,0 +1,977 @@
+# 架构借鉴指南
+
+> 本文档基于 Kite 与两个参考项目（龙虾 clawdbot、CoPaw）的机制层面对比，列出 Kite 需要深入探讨和改进的架构点。每一条都是独立议题，可在单独会话中展开讨论。
+>
+> **讨论方法**：指定要讨论的条目编号（如 P0-1），先深入阅读该条目列出的三个项目的源码文件，分析各自的设计取舍，然后为 Kite 给出具体的修改方案。
+
+---
+
+## 项目路径与源码导航
+
+### Kite（本项目）
+
+- 路径：`C:/Users/agentcp/AppData/Roaming/Evol/default/workspace/openclaw-acp-channel/ai-phone-agent/Kite`
+- 设计文档：`docs/`（查阅方法见 `docs/KITE_DOCS_GUIDE.md`）
+
+| 组件 | 文件 | 关键内容 |
+|------|------|---------|
+| 入口 | `main.py` | token 生成（`secrets.token_hex(32)`）、环境变量设置、启动 Launcher |
+| Launcher | `core/launcher/entry.py` | `class Launcher`：11 步启动序列、模块监控、API 线程、Event Hub 连接 |
+| 进程管理 | `core/launcher/process_manager.py` | `class ProcessManager`：start_module / stop / cleanup_leftovers / write_stdin / close_stdio |
+| 模块扫描 | `core/launcher/module_scanner.py` | `class ModuleScanner`：module.md 发现、`_parse_frontmatter()` YAML 解析、`class ModuleInfo` |
+| Registry 入口 | `core/registry/entry.py` | stdin 读 token → 启动 FastAPI → stdout 输出端口 |
+| Registry 存储 | `core/registry/store.py` | `class RegistryStore`：内存模块表、token 验证、lookup glob 查询、get 点路径读取 |
+| Event Hub 入口 | `core/event_hub/entry.py` | stdin 读 token + launcher_ws_token → 启动 WS 服务 → stdout 输出 ws_endpoint |
+| Event Hub 核心 | `core/event_hub/hub.py` | `class EventHub`：WS 路由、NATS 匹配、`class EventDedup` 去重、订阅管理 |
+| Python 模块示例 | `test_modules/hello/entry.py` | 最小 Python 模块：stdin 读 boot_info、读环境变量 |
+| Node.js 模块示例 | `test_modules/hello_node/entry.js` | 完整 Node.js 模块：readline 读 boot_info → HTTP 注册 → WS 连接 → module.ready |
+
+### 龙虾（clawdbot）
+
+- 路径：`C:/Users/agentcp/AppData/Roaming/evol/default/workspace/clawdbot`
+- 语言：TypeScript/Node.js（ESM）
+- 架构：单进程 Gateway + 插件系统，WebSocket 控制面
+
+| 机制 | 文件（相对于项目根） | 关键内容 |
+|------|---------------------|---------|
+| 插件注册表 | `src/plugins/registry.ts` | 插件记录管理、8 种注册类型（Tool/Hook/Channel/Provider/Gateway Method/HTTP Route/CLI/Service） |
+| 插件加载器 | `src/plugins/loader.ts` | jiti 动态加载、3 路发现（bundled/workspace/node_modules） |
+| 插件类型定义 | `src/plugins/types.ts` | `ClawdbotPluginApi` 接口定义（registerTool/registerHook/registerChannel 等） |
+| 插件清单 | `src/plugins/manifest.ts` | clawdbot.plugin.json 加载与验证 |
+| Schema 校验 | `src/plugins/schema-validator.ts` | AJV 实例 + 缓存，`validateJsonSchemaValue()` |
+| Zod 配置 Schema | `src/config/zod-schema.ts` | `ClawdbotSchema` 全配置 Zod 定义 + `toJSONSchema()` 导出 |
+| 配置加载 | `src/config/io.ts` | `createConfigIO()`、`loadConfig()`、JSON5 解析、读写快照 |
+| 配置验证修复 | `src/config/validation.ts` | `validateConfigObject()`、带插件的扩展验证 |
+| RPC 协议 Schema | `src/gateway/protocol/schema/protocol-schemas.ts` | TypeBox 定义所有 request/response schema（50+ 方法） |
+| 错误码 | `src/gateway/protocol/schema/error-codes.ts` | `ErrorCodes` 枚举 + `errorShape()` 工厂（NOT_LINKED/NOT_PAIRED/AGENT_TIMEOUT/INVALID_REQUEST/UNAVAILABLE） |
+| 认证 | `src/gateway/auth.ts` | `ResolvedGatewayAuth`（token/password/tailscale）、timing-safe 比较 |
+| 设备配对 | `src/infra/device-pairing.ts` | 配对请求、DeviceAuthToken（publicKey/role/scopes） |
+| DM 策略 | `src/agents/pi-tools.policy.ts` | DM 历史限制、工具访问策略 |
+| 健康检查 | `src/gateway/server-methods/health.ts` | Gateway RPC health 方法（agent/channel/device 状态） |
+| 健康命令 | `src/commands/health.ts` | CLI health 子命令 |
+| 生命周期钩子 | `src/hooks/internal-hooks.ts` | `InternalHookEvent` 类型、`registerInternalHook()`、`triggerInternalHook()` |
+| 优雅关闭 | `src/gateway/server-close.ts` | `createGatewayCloseHandler()`：按序停止 channel/cron/heartbeat/browser/plugins/bonjour/tailscale |
+| 进程管理 | `src/process/spawn-utils.ts` | `spawnWithFallback()` 多策略降级 |
+| 子进程桥接 | `src/process/child-process-bridge.ts` | `attachChildProcessBridge()` 信号转发（SIGTERM/SIGINT/SIGHUP） |
+| CLI 构建 | `src/cli/program/build-program.ts` | `buildProgram()` Commander.js 实例 |
+| CLI 命令注册 | `src/cli/program/command-registry.ts` | `registerProgramCommands()`、命令路由 |
+| 路由解析 | `src/routing/resolve-route.ts` | `resolveAgentRoute()`：channel/peer → agentId 映射 |
+| 路由绑定 | `src/routing/bindings.ts` | `listBindings()`、channel-account-agent 绑定 |
+| Agent 运行时 | `src/agents/pi-embedded-runner.ts` | `runEmbeddedPiAgent()`：Pi Agent 执行入口、session 管理、工具分割 |
+| Agent 工具注册 | `src/agents/clawdbot-tools.ts` | `createClawdbotTools()`：50+ 参数的工具工厂（sessions/browser/messaging/cron/image 等） |
+| 思维模式 | `src/auto-reply/thinking.ts` | `ThinkLevel` 类型（off/minimal/low/medium/high/xhigh）、provider/model 兼容性映射 |
+| Session 管理 | `src/sessions/session-key-utils.ts` | session key 解析（agent/subagent/ACP）、线程父会话解析、key 规范化 |
+| Session 模型覆盖 | `src/sessions/model-overrides.ts` | `applyModelOverrideToSessionEntry()`：per-session provider/model 覆盖 |
+| 内存管理 | `src/memory/manager.ts` | `MemoryIndexManager`：embeddings + sqlite-vec 向量搜索 + BM25 混合搜索 |
+| 混合搜索 | `src/memory/hybrid.ts` | BM25 关键词 + 向量相似度混合排序 |
+| Provider failover | `src/agents/failover-error.ts` | `FailoverError`：reason 分类（billing/rate_limit/auth/timeout）+ HTTP 状态映射 |
+| Auth profile | `src/agents/auth-profiles/session-override.ts` | auth profile 选择、fallback 逻辑、session 级 provider 切换 |
+| Daemon 服务 | `src/daemon/service.ts` | 统一 daemon 抽象：systemd (Linux) + launchd (macOS) + Task Scheduler (Windows) |
+| systemd 集成 | `src/daemon/systemd.ts` | Linux systemd unit 安装/卸载/启用/重启 |
+| launchd 集成 | `src/daemon/launchd.ts` | macOS launchd plist 管理 |
+| 结构化日志 | `src/logging/logger.ts` | tslog 集成、文件轮转（24h）、subsystem 命名空间、外部 transport |
+| 日志配置 | `src/logging/config.ts` | 日志级别从环境变量/配置文件解析 |
+| Cron 调度 | `src/cron/service.ts` | cron 任务增删改查、内存状态 + 持久化、任务执行 API |
+| Cron 隔离执行 | `src/cron/isolated-agent.ts` | cron 任务隔离 agent 调用、delivery target 解析、heartbeat |
+| Web UI 入口 | `ui/src/main.ts` | Lit Web Components 入口、样式初始化 |
+| Web UI 主组件 | `ui/src/ui/app.ts` | dashboard 主组件：Gateway 连接、chat/cron/config/sessions/channels 管理 |
+| 引导向导 | `src/wizard/onboarding.ts` | onboarding 流程编排：auth → model → channel → skills → hooks → config |
+| 媒体理解 | `src/media-understanding/index.ts` | 图像/视频/音频转录 providers（Anthropic/OpenAI/Google/Deepgram/Groq/Minimax） |
+| 测试配置 | `vitest.config.ts` | Vitest 配置：coverage 70%、forks pool、120s timeout、878+ 测试文件 |
+
+### CoPaw
+
+- 路径：`C:/Users/agentcp/AppData/Roaming/evol/default/workspace/CoPaw-main`
+- 语言：Python
+- 架构：单进程 FastAPI + AgentScope，全异步
+
+| 机制 | 文件（相对于项目根） | 关键内容 |
+|------|---------------------|---------|
+| Channel 基类 | `src/copaw/app/channels/base.py` | `BaseChannel` ABC：async request/response 接口 |
+| Channel 注册表 | `src/copaw/app/channels/registry.py` | 内置 channel 注册 + `~/.copaw/custom_channels/` 自动发现 |
+| Channel 管理器 | `src/copaw/app/channels/manager.py` | `ChannelManager`：生命周期管理、消息队列、`from_config()` 工厂 |
+| 配置模型 | `src/copaw/config/config.py` | Pydantic 模型：`Config`、`ChannelConfig`、`AgentsConfig`、`MCPConfig` |
+| 配置工具 | `src/copaw/config/utils.py` | `load_config()`、`get_config_path()`、配置持久化 |
+| 配置监视器 | `src/copaw/config/watcher.py` | `ConfigWatcher`：2s 轮询 mtime + hash → 触发 channel 重载 |
+| Skill 管理器 | `src/copaw/agents/skills_manager.py` | `sync_skills_to_working_dir()`、SKILL.md frontmatter 解析 |
+| Provider 注册表 | `src/copaw/providers/registry.py` | `PROVIDERS` 字典：内置 provider 定义 + 自定义 provider 加载 |
+| Provider 数据模型 | `src/copaw/providers/models.py` | Pydantic：`ModelInfo`、`ProviderDefinition`、`CustomProviderData` |
+| MCP 客户端管理 | `src/copaw/app/mcp/manager.py` | `MCPClientManager`：生命周期管理、lock-based atomic swap 热重载 |
+| MCP 配置监视 | `src/copaw/app/mcp/watcher.py` | `MCPConfigWatcher`：独立轮询 MCP 配置段变更 |
+| Agent 实现 | `src/copaw/agents/react_agent.py` | `CoPawAgent`（extends `ReActAgent`）：工具 + 技能 + 记忆 |
+| 模型工厂 | `src/copaw/agents/model_factory.py` | `create_model_and_formatter()`：按 provider 创建 LLM 实例 |
+| 查询处理器 | `src/copaw/app/runner/runner.py` | `AgentRunner`：query_handler 创建 agent → 运行 → 管理 session |
+| Cron 管理器 | `src/copaw/app/crons/manager.py` | APScheduler `AsyncIOScheduler` + CronTrigger/IntervalTrigger |
+| App 生命周期 | `src/copaw/app/_app.py` | FastAPI lifespan：按序初始化 Runner → MCP → Channel → Cron → Watcher |
+| CLI 入口 | `src/copaw/cli/main.py` | Click CLI：app/channels/chats/clean/cron/env/init/models/skills |
+| 错误转储 | `src/copaw/app/runner/query_error_dump.py` | `write_query_error_dump()`：traceback + 请求 + agent 状态写入 temp JSON |
+| 内存实现 | `src/copaw/agents/memory/copaw_memory.py` | `CoPawInMemoryMemory`：扩展 InMemoryMemory，支持 mark 过滤 + summary 前置 |
+| 内存管理器 | `src/copaw/agents/memory/memory_manager.py` | 继承 ReMeFs：消息压缩/摘要、语义搜索、token 感知截断、70% 阈值自动压缩 |
+| Markdown 管理 | `src/copaw/agents/memory/agent_md_manager.py` | `AgentMdManager`：working/memory 目录的 md 文件读写、元数据追踪 |
+| 初始化命令 | `src/copaw/cli/init_cmd.py` | 交互式初始化：channels/env/providers/skills 配置 + 安全警告 + HEARTBEAT.md 创建 |
+| 日志工具 | `src/copaw/utils/logging.py` | `ColorFormatter`：ANSI 着色、Windows 兼容、`LOG_NAMESPACE = "copaw"` |
+| Console 布局 | `console/src/layouts/MainLayout/index.tsx` | Ant Design Layout + 侧边栏 + 路由（chat/channels/sessions/cron/skills/mcp/models 等） |
+| Console API | `console/src/api/index.ts` | 聚合 12 个 API 模块（channel/cron/chat/session/env/provider/skill/agent/workspace/mcp 等） |
+| Console Chat | `console/src/pages/Chat/index.tsx` | `AgentScopeRuntimeWebUI` 集成、model 配置提示、options panel |
+
+---
+
+## 优先级说明
+
+- **P0（地基级）** — 不补会在后续开发中持续产生问题，越晚补代价越高
+- **P1（骨架级）** — 影响日常可用性和开发效率，在功能铺开前需要到位
+- **P2（肌肉级）** — 提升开发体验和运维能力，可在功能开发中渐进完善
+
+---
+
+## P0-1：Module SDK
+
+### 现状
+
+每个模块都要手写：stdin 读取 boot_info → 启动 HTTP 服务 → POST 注册 Registry → 连接 Event Hub WebSocket → 发送 module.ready → 启动 heartbeat 定时器 → 退出时 deregister。这套流程约 80-120 行样板代码，且容易实现不一致（如忘记 heartbeat、readline 用法错误导致 Node.js 死锁等）。
+
+### 需要阅读的源码
+
+**Kite — 看「模块要手写什么」**：
+- `test_modules/hello_node/entry.js` — 完整 Node.js 模块实现（stdin readline → HTTP → Registry 注册 → Event Hub WS → module.ready → heartbeat），这就是当前需要 SDK 封装的全部样板代码
+- `test_modules/hello/entry.py` — 最小 Python 模块（只读 boot_info，未完整实现 8 步协议）
+- `core/launcher/process_manager.py` — Launcher 侧如何向模块 stdin 写 boot_info、管理 stdio 生命周期
+
+**龙虾 — 看「Plugin API 注入模式」**：
+- `src/plugins/types.ts` — `ClawdbotPluginApi` 接口定义：插件拿到的 API 对象有哪些方法（registerTool / registerHook / registerChannel / registerProvider / registerGatewayMethod / registerHttpRoute / registerService / registerCliCommand）
+- `src/plugins/registry.ts` — API 对象如何创建、注册信息如何存储
+- `src/plugins/loader.ts` — 插件如何被发现和加载，API 对象何时注入
+
+**CoPaw — 看「基类继承模式」**：
+- `src/copaw/app/channels/base.py` — `BaseChannel` ABC：开发者只需继承并实现抽象方法，框架负责生命周期
+- `src/copaw/app/channels/manager.py` — `ChannelManager` 如何管理 channel 实例的 start/stop
+- `src/copaw/app/_app.py` — lifespan 中如何编排所有组件的初始化顺序
+
+### 要解决的问题
+
+1. Python SDK 和 Node.js SDK 应该封装到什么程度？是薄封装（只封装协议），还是厚封装（提供完整的 app 框架如 FastAPI 实例）？
+2. SDK 是否应该内置 HTTP 服务器？还是只提供注册/事件客户端，让模块自己选 HTTP 框架？
+3. 如何处理 SDK 版本与框架版本的兼容性？
+4. 二进制模块（Go/Rust）怎么办？是提供静态库还是只维护协议文档？
+
+### Kite 相关文档
+
+- 已有规划：[Polyglot L49-63](Polyglot运行时与Clawdbot兼容性设计.md)
+- 模块入口协议：[04-模块规范 L67-164](Kite框架设计/04-模块规范.md)
+- 实现规划 SDK 部分：[实现规划 L10-31](实现规划.md)
+
+---
+
+## P0-2：module.md Schema 校验
+
+### 现状
+
+`ModuleScanner` 解析 module.md 的 YAML frontmatter 后直接使用，没有校验必填字段、类型、枚举值、值范围。一个拼写错误（如 `staet: enabled`）不会报错，只会在运行时产生诡异行为。
+
+### 需要阅读的源码
+
+**Kite — 看「当前解析逻辑有多脆弱」**：
+- `core/launcher/module_scanner.py` — `_parse_frontmatter()` 解析 YAML 后直接赋值给 `ModuleInfo`，无任何校验；`ModuleInfo` dataclass 定义了 12 个字段但没有验证逻辑
+- `core/registry/store.py` — `register_module()` 接收注册 payload 后直接存储，也无 schema 校验
+
+**龙虾 — 看「AJV schema 校验机制」**：
+- `src/plugins/schema-validator.ts` — AJV 实例配置、schema 缓存、`validateJsonSchemaValue()` 验证函数
+- `src/plugins/manifest.ts` — 插件清单 `clawdbot.plugin.json` 的加载和验证流程
+- `src/config/zod-schema.ts` — Zod schema 如何定义嵌套配置结构（对比：如果 Kite 用 JSON Schema，这是另一种思路）
+- `src/gateway/protocol/schema/protocol-schemas.ts` — TypeBox 定义 RPC 消息 schema（看它如何用 schema 校验运行时数据）
+
+**CoPaw — 看「Pydantic 模型校验模式」**：
+- `src/copaw/config/config.py` — Pydantic `Config` 模型：字段类型、默认值、嵌套模型、可选字段如何定义
+- `src/copaw/config/utils.py` — `load_config()` 如何用 Pydantic 做加载时校验
+- `src/copaw/providers/models.py` — `ProviderDefinition` Pydantic 模型：看更复杂的嵌套 schema 定义
+
+### 要解决的问题
+
+1. 用什么做校验？Python 侧可选 Pydantic / jsonschema / cerberus；Node.js 侧可选 AJV / Zod。还是统一用 JSON Schema 定义，各语言各自用对应库？
+2. 校验在什么时机执行？扫描时？注册时？两者都要？
+3. 校验失败的策略：跳过该模块继续启动（降级），还是直接报错退出？
+4. 如何处理模块自定义的 metadata 字段——是放任自由还是要求模块声明 schema？
+
+### Kite 相关文档
+
+- 模块发现：[Launcher L159-281](Launcher启动器文档.md)
+- module.md 字段：[04-模块规范 L25-65](Kite框架设计/04-模块规范.md)
+
+---
+
+## P0-3：集中配置系统
+
+### 现状
+
+Kite 的配置散落在三处：环境变量（`KITE_*`）、各模块的 `module.md`、运行时由各模块自行管理。没有一个统一的全局配置文件来控制框架级别的行为（如默认 heartbeat 间隔、TTL 超时、日志级别、启用的模块列表等）。
+
+### 需要阅读的源码
+
+**Kite — 看「配置散落在哪里」**：
+- `main.py` — 环境变量 `KITE_*` 的默认值设置（KITE_PROJECT/KITE_WORKSPACE/KITE_DATA/KITE_ENV 等）
+- `core/launcher/entry.py` — Launcher 里硬编码的配置值（heartbeat 30s、monitor 1s、ready timeout 等），搜索 `30`、`timeout`、`TTL` 看散落的配置点
+- `core/registry/store.py` — Registry 里硬编码的 TTL 60s、心跳超时等
+- `core/launcher/module_scanner.py` — 模块发现路径配置（`discovery` 字段在 Launcher 自己的 module.md 里）
+
+**龙虾 — 看「集中配置全家桶」**：
+- `src/config/zod-schema.ts` — 完整的 Zod schema：所有配置段（agent/channels/gateway/hooks/cron/models 等），看它如何组织大型配置结构
+- `src/config/io.ts` — `createConfigIO()`：JSON5 解析、读写快照、文件路径解析
+- `src/config/validation.ts` — `validateConfigObject()`：配置修复/doctor 逻辑
+- 参考项目根目录下的 `~/.clawdbot/clawdbot.json` 实际配置文件结构（可在代码中搜索 default 值了解结构）
+
+**CoPaw — 看「Pydantic 配置 + 热重载」**：
+- `src/copaw/config/config.py` — Pydantic `Config` 根模型：channels / mcp / agents / last_api 等顶级配置段
+- `src/copaw/config/utils.py` — `load_config()` / `save_config()`：JSON ↔ Pydantic 双向转换
+- `src/copaw/config/watcher.py` — `ConfigWatcher`：2s 轮询 mtime + hash，检测变更触发重载
+
+### 要解决的问题
+
+1. 配置文件格式：YAML（与 module.md 一致）、JSON5（人类友好）、TOML？
+2. 配置文件位置：`KITE_WORKSPACE/kite.yaml`？`KITE_DATA/config.yaml`？
+3. 与环境变量的优先级关系：环境变量 > 配置文件 > 默认值？
+4. 配置的作用域：全局配置 vs 模块级配置 vs 实例级配置，如何分层？
+5. 模块自定义配置放哪里？集中配置的子节点（如 `modules.webchat.port`）？还是模块自己的 `config.yaml`？
+6. 是否需要配置变更事件（`config.changed`）通知各模块？
+
+### Kite 相关文档
+
+- 当前环境变量设计：[环境变量与运行时目录设计](环境变量与运行时目录设计.md)
+- 目录结构：[06-目录结构](Kite框架设计/06-目录结构.md)
+
+---
+
+## P0-4：Agent 推理运行时
+
+### 现状
+
+Kite 自身定位为"事件驱动多 Agent 运行时"，设计文档中有 Agent 概念（02-核心概念 L221-251）和会话生命周期（05-核心流程 L94-127），但框架层面没有提供任何 Agent 推理执行的基础设施——如何调用 LLM、如何执行 ReAct 循环、如何管理工具调用链、如何处理流式输出。目前 Agent 模块需要从零实现全部推理逻辑。
+
+### 需要阅读的源码
+
+**Kite — 看「当前对 Agent 执行的规划」**：
+- `docs/Kite框架设计/02-核心概念.md` L221-251 — Agent 概念定义：执行单元、类型（conversation/group/post/planner）、单实例多会话异步协程模型
+- `docs/Kite框架设计/03-系统架构.md` L166-181 — Model Service 设计：独立进程提供 LLM 调用能力、支持多 API（OpenAI/Claude/Gemini）、流式输出
+- `docs/Kite框架设计/05-核心流程.md` L74-92 — 工具调用流程：LLM 输出 tool_call → Agent 拦截 → Registry 查询 → 权限校验 → 执行
+- `docs/Kite框架设计/05-核心流程.md` L94-127 — 会话生命周期：事件触发 → Kernel 创建会话 → 启动 Agent → 对话循环 → 会话结束
+
+**龙虾 — 看「完整 Agent 执行栈」**（最值得学习）：
+- `src/agents/pi-embedded-runner.ts` — Pi Agent 运行时入口：`runEmbeddedPiAgent()` 非阻塞 RPC 执行、session 管理、工具分割
+- `src/agents/clawdbot-tools.ts` — `createClawdbotTools()` 工厂：50+ 参数，注册 sessions/browser/messaging/cron/image 等工具
+- `src/auto-reply/thinking.ts` — 5 级思维模式（off/minimal/low/medium/high/xhigh），按 provider/model 兼容性映射
+- `src/agents/failover-error.ts` — `FailoverError` 类：故障分类（billing/rate_limit/auth/timeout）+ auth profile 轮换实现模型故障转移
+
+**CoPaw — 看「ReAct 循环模式」**：
+- `src/copaw/agents/react_agent.py` — `CoPawAgent`（extends `ReActAgent`）：最多 50 轮推理循环、内置工具注册、动态 skill 加载、系统命令处理（/compact /new /clear）
+- `src/copaw/agents/model_factory.py` — `create_model_and_formatter()`：按 provider 创建 LLM 实例，支持文件块扩展的 Formatter
+- `src/copaw/app/runner/runner.py` — `AgentRunner`：query_handler 创建 agent → 加载 session → 运行 → 流式回复 → 保存 session
+
+### 要解决的问题
+
+1. Kite 应该在框架层提供 Agent 执行基础设施，还是完全交给模块自行实现？
+   - 方案 A：框架提供 Agent SDK（含 ReAct 循环、工具调度、LLM 调用抽象），模块只需定义 system prompt + 工具集
+   - 方案 B：框架只提供 Model Service（LLM 调用抽象），推理循环由各 Agent 模块自行实现
+   - 方案 C：保持现状，Agent 模块自带推理逻辑（如引入 AgentScope 或 LangChain 作为依赖）
+2. 工具调用是否应该跨进程？当 Agent 模块调用另一个模块的工具时，经过 Registry 查询 → HTTP 调用的延迟是否可接受？还是需要 RPC 优化（与 P1-3 关联）？
+3. 流式输出如何跨进程传递？LLM → Agent 模块 → Channel 模块，每一跳的流式协议是什么？
+4. 思维模式（thinking level）是否应该作为框架级概念？还是各 Agent 模块自行实现？
+5. 模型故障转移是否应该在 Model Service 层统一处理？还是各 Agent 自行管理 API Key 轮换？
+
+### Kite 相关文档
+
+- Agent 概念：[02-核心概念 L221-251](Kite框架设计/02-核心概念.md)
+- Model Service：[03-系统架构 L166-181](Kite框架设计/03-系统架构.md)
+- 工具调用流程：[05-核心流程 L74-92](Kite框架设计/05-核心流程.md)
+- 会话生命周期：[05-核心流程 L94-127](Kite框架设计/05-核心流程.md)
+
+---
+
+## P0-5：Session 会话管理
+
+### 现状
+
+Kite 设计文档定义了完整的 Session 数据模型（07-数据模型 L3-23）和生命周期流程（05-核心流程 L94-127），但框架层面没有 Session 管理的实现。两个参考项目都有成熟的 Session 系统——龙虾的 session 隔离（main + per-group + Docker 沙箱）尤其值得学习，因为 Kite 的多进程架构天然适合进程级 session 隔离。
+
+### 需要阅读的源码
+
+**Kite — 看「已有的 Session 设计」**：
+- `docs/Kite框架设计/02-核心概念.md` L168-220 — Session 概念：session key 规则（`{agent}:peer:{peer_identity}` / `{agent}:group:{group_identity}`）、参与者、方向、来源、状态
+- `docs/Kite框架设计/07-数据模型.md` L3-23 — Session JSON 结构：session_id / session_key / agent_id / peer_id / peer_kind / channel / direction / source / mode / status
+- `docs/Kite框架设计/05-核心流程.md` L94-127 — 会话生命周期：事件触发 → Kernel 创建 → Agent 启动 → 对话循环 → 结束 → 后处理
+
+**龙虾 — 看「Session 隔离与沙箱」**（最值得学习）：
+- `src/sessions/session-key-utils.ts` — session key 解析：agent / subagent / ACP 三种 key 类型、线程父会话解析、规范化逻辑
+- `src/sessions/model-overrides.ts` — `applyModelOverrideToSessionEntry()`：per-session 的 provider/model 覆盖，支持运行时切换模型
+- `src/sessions/send-policy.ts` — 消息发送策略：per-session 的消息路由和投递配置
+- `src/routing/resolve-route.ts` — `resolveAgentRoute()`：channel/peer → agentId 的路由映射，决定消息进入哪个 session
+
+**CoPaw — 看「session 持久化与恢复」**：
+- `src/copaw/app/runner/runner.py` — `AgentRunner`：query_handler 创建 agent 时加载 session state → 运行 → 保存 session state，JSON 文件持久化
+- `src/copaw/agents/react_agent.py` — `CoPawAgent` 的 session 相关逻辑：系统命令 `/new`（新建 session）、`/history`（查看历史）
+
+### 要解决的问题
+
+1. Session 管理应该在哪个组件中实现？Kernel 模块（设计文档中的规划）？还是作为框架基础设施（如 Registry 的扩展）？
+2. Session state 的持久化方式：文件系统（CoPaw 方式，简单）？SQLite（更适合查询）？通过 Event Hub 广播让各模块自行持久化？
+3. Session 与模块进程的关系：
+   - 一个 Agent 模块进程处理多个 session（Kite 设计文档中的方案——协程并发）？
+   - 每个 session 启动独立进程（类似龙虾的 Docker 沙箱，利用 Kite 的多进程优势）？
+4. 消息历史的存储：集中存储（所有 session 的消息统一管理）？还是 per-session 文件（`messages.jsonl`，Kite 设计文档中的方案）？
+5. Session key 的设计：Kite 设计文档的 `{agent}:{channel}:peer:{peer}` 与龙虾的 `main` / per-group 模型，哪种更适合 Kite 的多 Agent 场景？
+6. 跨 Channel 的 session 连续性——同一个用户从钉钉切到微信，是否应该延续同一个 session？如果是，session key 中是否不应包含 channel？
+
+### Kite 相关文档
+
+- Session 概念：[02-核心概念 L168-220](Kite框架设计/02-核心概念.md)
+- Session 数据模型：[07-数据模型 L3-23](Kite框架设计/07-数据模型.md)
+- 会话生命周期：[05-核心流程 L94-127](Kite框架设计/05-核心流程.md)
+
+---
+
+## P1-1：模块间权限控制
+
+### 现状
+
+当前只要持有有效 token，任何模块就能调用 Registry 的所有 API、连接 Event Hub 发布/订阅任何事件、调用任何其他模块的工具。没有"模块 A 能否调用模块 B 的工具 X"这样的访问控制。
+
+### 需要阅读的源码
+
+**Kite — 看「当前认证只到什么程度」**：
+- `core/registry/store.py` — `verify_token()` 方法：只检查 token 是否存在于 token_map，不检查该 token 对应的模块是否有权限执行请求的操作
+- `core/event_hub/hub.py` — WS 连接认证：调用 Registry `/verify` 验证 token，但不限制订阅/发布的事件范围
+- `core/launcher/entry.py` — `_register_module_tokens()`：所有 module token 同等权力
+
+**龙虾 — 看「多层权限模型」**：
+- `src/agents/pi-tools.policy.ts` — DM 策略和工具访问策略的实现逻辑
+- `src/infra/device-pairing.ts` — 设备配对：token 附带 role 和 scopes，不同设备有不同权限
+- `src/gateway/auth.ts` — Gateway 认证：token/password/tailscale 三种方式，`ResolvedGatewayAuth` 结构体含权限信息
+
+**CoPaw — 对比参考（无权限模型，但有启用/禁用控制）**：
+- `src/copaw/agents/skills_manager.py` — Skill 的启用/禁用机制：`list_available_skills()` + `sync_skills_to_working_dir()`
+
+### 要解决的问题
+
+1. 权限控制的粒度：模块级（A 能否调用 B）？工具级（A 能否调用 B.tool_x）？事件级（A 能否订阅 event_y）？
+2. 权限定义在哪里？集中配置（如 `kite.yaml` 的 `permissions` 段）？还是各模块的 `module.md` 声明自己暴露给谁？
+3. Registry 是否要承担权限检查的职责？还是单独一个权限服务？
+4. 如何处理核心模块与扩展模块的权限差异——核心模块是否默认 full access？
+5. 与已有的工具权限体系（五级 switches + check_permission）如何衔接？
+
+### Kite 相关文档
+
+- 当前认证设计：[注册中心设计 L519-690](注册中心设计.md)
+- 工具权限模型：[02-核心概念 L252-315](Kite框架设计/02-核心概念.md)
+
+---
+
+## P1-2：配置热重载
+
+### 现状
+
+修改任何配置（环境变量、module.md、未来的集中配置文件）都需要重启整个框架。对于一个多进程系统来说，全重启代价高（11 步启动序列，所有模块重新初始化）。
+
+### 需要阅读的源码
+
+**Kite — 看「当前重启代价」**：
+- `core/launcher/entry.py` — `_async_main()` 的 11 步启动序列，理解全重启的代价
+- 已有设计文档 `docs/模块热更新.md` — 7 步热更新流程（重启单个模块进程），与配置热重载的区别
+
+**龙虾 — 看「配置变更事件机制」**：
+- `src/hooks/internal-hooks.ts` — `InternalHookEvent` 定义，包含 config reload 事件的触发机制
+- `src/gateway/server-close.ts` — 优雅关闭中各子系统的停止顺序（理解部分重载需要停哪些、保留哪些）
+
+**CoPaw — 看「文件轮询 + 原子替换热重载」**（最值得学习）：
+- `src/copaw/config/watcher.py` — `ConfigWatcher` 完整实现：轮询间隔、mtime 检测、hash 比对、变更分段（只重载 channels 段变更）
+- `src/copaw/app/channels/manager.py` — `ChannelManager` 如何响应配置变更：stop 旧 channel → 创建新实例 → start
+- `src/copaw/app/mcp/manager.py` — `MCPClientManager` 热重载：lock-based atomic swap（connect new outside lock → swap inside lock）
+- `src/copaw/app/mcp/watcher.py` — `MCPConfigWatcher`：独立于主 ConfigWatcher，专门监视 MCP 配置段
+
+### 要解决的问题
+
+1. 哪些配置应该支持热重载？哪些必须重启？（如 token 相关的肯定要重启，日志级别应该能热改）
+2. 变更检测机制：文件轮询（CoPaw 方式）？文件系统 watch（inotify/FSEvents/ReadDirectoryChanges）？API 触发？
+3. 变更通知机制：Event Hub 事件（`config.changed`）？Registry 推送？Launcher 通知？
+4. 模块侧如何响应？强制要求实现 `on_config_changed` 回调？还是各模块自己订阅事件？
+5. 与已有的模块热更新文档的关系——热更新是重启模块进程，热重载是不重启进程更新配置，两者如何协作？
+
+### Kite 相关文档
+
+- 已有热更新设计：[模块热更新](模块热更新.md)
+- Launcher API（restart 端点）：[Launcher L359-480](Launcher启动器文档.md)
+
+---
+
+## P1-3：标准化 RPC 协议
+
+### 现状
+
+模块间的请求-响应通信没有统一协议。每个模块自己定义 REST API（路径、参数、响应格式各异），调用方需要知道对方的具体 API 设计。Event Hub 只处理单向事件广播，不支持请求-响应模式。
+
+### 需要阅读的源码
+
+**Kite — 看「当前模块间怎么互调」**：
+- `core/registry/store.py` — `lookup()` 和 `get_by_path()` 方法：调用方如何通过 Registry 发现目标模块的 API 端点
+- `core/event_hub/hub.py` — 当前事件协议只有 `event` / `subscribe` / `unsubscribe`，没有 request/response
+- `test_modules/hello_node/entry.js` — 看模块如何通过 HTTP 调用 Registry API（`fetch` + 自定义路径 + 自定义格式）
+
+**龙虾 — 看「完整 RPC 协议」**（最值得学习）：
+- `src/gateway/protocol/schema/protocol-schemas.ts` — 所有 RPC 方法的 TypeBox schema 定义（50+ 方法），理解统一协议的结构：`{id, method, params} → {id, result|error}`
+- `src/gateway/protocol/schema/error-codes.ts` — 协议级错误码枚举和 `errorShape()` 工厂函数
+- `src/plugins/schema-validator.ts` — AJV 如何在运行时校验每条 RPC 消息
+
+**CoPaw — 对比参考（无 RPC，看单进程如何避开这个问题）**：
+- `src/copaw/app/runner/runner.py` — 所有组件在同一进程，直接函数调用，不需要 RPC
+
+### 要解决的问题
+
+1. 在现有架构上加 RPC，走什么通道？
+   - 方案 A：Event Hub 扩展——加 `request`/`response` 消息类型，Hub 负责路由回复
+   - 方案 B：独立 RPC 层——新的通信通道（如 gRPC、JSON-RPC over HTTP）
+   - 方案 C：保持 HTTP 直调，但统一格式和错误码
+2. 请求路由：调用方是直接知道目标模块地址（通过 Registry 查询），还是通过中间层路由？
+3. 超时和重试策略：框架统一管还是调用方自己管？
+4. 是否需要双向流式 RPC（如 LLM 流式输出）？如果需要，HTTP 不够用，需要 WebSocket 或 SSE。
+5. 与现有 Registry `lookup` → HTTP POST 模式如何兼容/迁移？
+
+### Kite 相关文档
+
+- 当前工具调用流程：[05-核心流程 L74-92](Kite框架设计/05-核心流程.md)
+- Registry lookup API：[注册中心设计 L153-317](注册中心设计.md)
+- Event Hub 协议：[事件中心设计 L29-95](事件中心设计.md)
+
+---
+
+## P1-4：长期记忆系统
+
+### 现状
+
+Kite 设计文档中没有专门的记忆/上下文管理设计。Agent 模块需要自行处理对话历史的存储、检索、压缩和语义搜索。对于个人助手场景，长期记忆是核心能力——用户期望 Agent 记住之前的对话内容和个人偏好。两个参考项目用了截然不同的方案，都值得借鉴。
+
+### 需要阅读的源码
+
+**Kite — 看「当前没有记忆基础设施」**：
+- `docs/Kite框架设计/02-核心概念.md` — 搜索"记忆"、"memory"、"上下文"：概念层面未定义记忆模型
+- `docs/Kite框架设计/07-数据模型.md` L3-23 — Session 数据模型只有 `summary` 字段，没有完整的记忆结构
+
+**龙虾 — 看「向量搜索 + BM25 混合检索」**（最值得学习）：
+- `src/memory/manager.ts` — `MemoryIndexManager`：embeddings 生成 + sqlite-vec 向量存储 + BM25 关键词搜索 + 文件同步，支持 OpenAI/Gemini 两种 embedding provider
+- `src/memory/hybrid.ts` — 混合搜索实现：BM25 关键词 + 向量相似度结果合并排序
+
+**CoPaw — 看「语义搜索 + token 感知压缩」**：
+- `src/copaw/agents/memory/copaw_memory.py` — `CoPawInMemoryMemory`：扩展 InMemoryMemory，支持 mark 过滤和 summary 前置
+- `src/copaw/agents/memory/memory_manager.py` — 继承 ReMeFs（reme-ai）：语义搜索、消息压缩/摘要、token 感知截断、70% 上下文阈值触发自动压缩、保留最近 3 条消息
+- `src/copaw/agents/memory/agent_md_manager.py` — `AgentMdManager`：working/memory 目录 markdown 文件管理，元数据追踪（创建/修改时间）
+
+### 要解决的问题
+
+1. 记忆应该作为框架基础设施（如独立的 Memory Service 模块），还是作为 Agent SDK 的一部分？
+   - 方案 A：独立 Memory Service 模块——提供 embedding + 向量存储 + 检索 API，所有 Agent 共享
+   - 方案 B：Agent SDK 内置——每个 Agent 模块自带记忆管理逻辑
+   - 方案 C：混合——框架提供 embedding/存储基础设施，Agent SDK 提供上下文管理策略
+2. 存储后端选择：sqlite-vec（龙虾方案，嵌入式）？外部向量数据库（Milvus/Qdrant）？纯文件系统（CoPaw 方案）？
+3. 上下文压缩策略：token 阈值触发自动摘要（CoPaw 方案）？滑动窗口？还是让 Agent 自行管理？
+4. 跨 session 的记忆共享——不同 session 中获取的用户偏好是否应该全局可访问？
+5. 记忆的持久化与隐私——用户能否查看/删除/导出自己的记忆数据？
+
+### Kite 相关文档
+
+- Session 数据模型：[07-数据模型 L3-23](Kite框架设计/07-数据模型.md)
+
+---
+
+## P1-5：Model Provider 抽象层
+
+### 现状
+
+Kite 设计文档中有 Model Service 的概念（03-系统架构 L166-181），规划了独立进程提供 LLM 调用能力，但没有讨论 Provider 抽象、API Key 管理、模型故障转移、本地模型支持等实现细节。两个参考项目都有成熟的 Provider 系统，设计取舍各有不同。
+
+### 需要阅读的源码
+
+**Kite — 看「当前 Model Service 的规划」**：
+- `docs/Kite框架设计/03-系统架构.md` L166-181 — Model Service：支持多 LLM API（OpenAI/Claude/Gemini）、function calling、流式输出、配置管理
+
+**龙虾 — 看「Auth Profile 轮换 + 故障转移」**（最值得学习）：
+- `src/agents/failover-error.ts` — `FailoverError` 类：故障 reason 分类（billing/rate_limit/auth/timeout/server_error）、HTTP 状态码映射、决定是否触发 failover
+- `src/agents/auth-profiles/session-override.ts` — auth profile 选择逻辑：last-good 优先、round-robin 降级、cooldown 机制（失败后冷却），session 级 provider 覆盖
+- `src/providers/github-copilot-auth.ts` — GitHub Copilot OAuth 集成（看非标准 provider 如何接入）
+- `src/providers/qwen-portal-oauth.ts` — Qwen OAuth 集成
+
+**CoPaw — 看「Provider Registry + 本地模型」**：
+- `src/copaw/providers/registry.py` — `PROVIDERS` 字典 + `_CHAT_MODEL_MAP`：6 个内置 provider（modelscope/dashscope/aliyun/ollama/llamacpp/mlx），自定义 provider 验证规则
+- `src/copaw/providers/models.py` — Pydantic 模型：`ProviderDefinition`（id/name/default_base_url/api_key_prefix/models）、`ResolvedModelConfig`（运行时配置）、`CustomProviderData`（用户自定义 provider）
+- `src/copaw/providers/store.py` — `get_active_llm_config()` / `set_active_llm()`：活跃模型切换、per-provider 模型增删、config.json 持久化
+
+### 要解决的问题
+
+1. Model Service 是独立模块还是框架内置？
+   - 独立模块：灵活，可替换，但增加进程间通信开销（每次 LLM 调用走 HTTP）
+   - 框架内置：低延迟，但不符合 Kite 的"万物皆模块"哲学
+2. Provider 抽象的接口设计：参考 OpenAI 兼容接口（CoPaw 方案）？还是定义自己的抽象层（龙虾方案）？
+3. API Key 管理：集中配置（config 文件）？环境变量？还是 per-provider 独立管理？
+4. 故障转移策略：是否在 Model Service 层统一处理（透明 failover）？还是返回错误让 Agent 自行决定？
+5. 本地模型支持（llama.cpp / MLX / Ollama）：是否作为特殊 provider 集成？还是作为独立模块？
+6. 流式输出的跨进程传递：Model Service → Agent 模块的流式通道用什么协议（SSE / WebSocket / chunked HTTP）？
+
+### Kite 相关文档
+
+- Model Service：[03-系统架构 L166-181](Kite框架设计/03-系统架构.md)
+
+---
+
+## P1-6：消息路由与 Channel 抽象
+
+### 现状
+
+Kite 设计文档定义了 Channel 概念（02-核心概念 L128-135）——消息传输媒介，提供事件和工具——但没有讨论消息内容的标准化（不同 channel 的消息格式各异）、消息如何路由到正确的 Agent/Session、以及多 Channel 消息的统一处理。这对计划中的 clawdbot-bridge 模块尤其关键。
+
+### 需要阅读的源码
+
+**Kite — 看「当前 Channel 的规划」**：
+- `docs/Kite框架设计/02-核心概念.md` L128-135 — Channel 概念：消息传输媒介、提供事件（消息到达、连接变化）和工具（发送消息、建立连接）
+- `docs/Kite框架设计/08-扩展性.md` — 如何添加新 Channel
+
+**龙虾 — 看「消息路由 + 统一消息格式」**（最值得学习）：
+- `src/routing/resolve-route.ts` — `resolveAgentRoute()`：channel + peer → agentId 映射，消息路由到正确的 Agent
+- `src/routing/bindings.ts` — `listBindings()`：channel-account-agent 三方绑定，决定消息流向
+- `src/channels/` — 共享 channel 逻辑：routing/allowlists/内容标准化
+
+**CoPaw — 看「BaseChannel + content_parts 标准化」**：
+- `src/copaw/app/channels/base.py` — `BaseChannel` ABC：native payload → `content_parts`（`TextContent` / `ImageContent` / `FileContent`）标准化，时间 debounce，消息合并
+- `src/copaw/app/channels/registry.py` — Channel 注册表：内置 + `~/.copaw/custom_channels/` 自动发现
+- `src/copaw/app/channels/manager.py` — `ChannelManager`：per-channel 消息队列、异步 consumer loop、热重载
+
+### 要解决的问题
+
+1. 消息内容标准化：是否定义统一的消息格式（如 CoPaw 的 `content_parts`）？还是让 Channel 模块和 Agent 模块自行协商？
+2. 消息路由规则：Channel → Agent 的映射如何定义？
+   - 固定映射（配置文件中绑定 channel → agent）？
+   - 动态路由（如龙虾的 route resolver，按 channel + peer 动态解析）？
+   - 事件驱动（Channel 发 `channel.message.received` 事件，由 Kernel 路由）？
+3. clawdbot-bridge 的消息协议：bridge 模块收到 10+ channel 的消息后，如何转换为 Kite 标准事件？事件 payload 的 schema 是什么？
+4. 多媒体消息的处理：图片/音频/视频/文件在不同 channel 中的表示差异很大，如何统一？
+5. 消息回复的路由：Agent 回复后，如何知道应该通过哪个 Channel 发送？如果用户从钉钉发消息但已切换到 QQ，回复发到哪里？
+
+### Kite 相关文档
+
+- Channel 概念：[02-核心概念 L128-135](Kite框架设计/02-核心概念.md)
+- 扩展新 Channel：[08-扩展性](Kite框架设计/08-扩展性.md)
+- Clawdbot 兼容性设计：[Polyglot运行时与Clawdbot兼容性设计](Polyglot运行时与Clawdbot兼容性设计.md)
+
+---
+
+## P1-7：Daemon 后台常驻
+
+### 现状
+
+Kite 目前只能前台运行（`python main.py` 或 `kite` 命令），关闭终端后框架停止。对于个人助手场景，"always-on"是基本需求——用户希望 Agent 在后台持续运行，开机自启，不需要手动管理进程。
+
+### 需要阅读的源码
+
+**Kite — 看「当前的进程管理能力」**：
+- `core/launcher/entry.py` — Launcher 的 monitor 循环：1s 检查子进程存活、heartbeat 续约——这些机制已存在，但 Launcher 自己没有 daemon 化
+- `core/launcher/process_manager.py` — `cleanup_leftovers()`：遗留进程清理——说明框架已考虑异常退出的情况
+
+**龙虾 — 看「完整的 daemon 支持」**（最值得学习）：
+- `src/daemon/service.ts` — 统一 daemon 抽象：`installDaemon()` / `uninstallDaemon()` / `restartDaemon()` 跨平台接口
+- `src/daemon/systemd.ts` — Linux：systemd unit 文件生成、`systemctl enable/start/stop/restart`
+- `src/daemon/launchd.ts` — macOS：launchd plist 生成和管理
+- `src/wizard/onboarding.ts` — onboarding 流程中 `--install-daemon` 选项，首次使用即可设置自启
+
+**CoPaw — 对比参考（无 daemon，但有 Docker 部署）**：
+- `deploy/Dockerfile` — 多阶段 Docker 构建作为替代方案
+- `deploy/config/supervisord.conf.template` — supervisord 进程管理（容器内）
+
+### 要解决的问题
+
+1. Daemon 化的实现方式：
+   - 方案 A：systemd (Linux) + launchd (macOS) + Windows Service（龙虾方案，原生集成）
+   - 方案 B：跨平台进程管理器（如 PM2 for Node.js、Supervisor for Python）
+   - 方案 C：Docker 容器化部署（CoPaw 方案，但需要用户安装 Docker）
+2. daemon 与 Launcher 的关系：daemon 管理的是 Launcher 进程本身，Launcher 再管理所有模块进程？还是 daemon 直接管理所有进程？
+3. 日志管理：daemon 模式下日志写到哪里？`journalctl`（systemd）？自定义日志文件？与 P2-4 结构化日志的关系？
+4. CLI 集成：`kite install-daemon` / `kite uninstall-daemon` / `kite daemon status`
+5. 自动更新：daemon 模式下如何优雅地更新框架版本？stop → update → start 的自动化？
+
+### Kite 相关文档
+
+- 当前 CLI：[npm发布与CLI使用指南](npm发布与CLI使用指南.md)
+- 进程管理：Launcher 进程监控已有基础，需扩展到 Launcher 自身的 daemon 化
+
+---
+
+## P2-1：扩展点分类与注册语义
+
+### 现状
+
+Kite 的 Registry 注册 payload 是一个扁平的字典，tools / hooks / events_publish / events_subscribe 都塞在同一个对象里。模块注册时没有明确的"我是 Channel"、"我是 Agent"、"我是 Service"的语义区分——虽然 `module.md` 有 `type` 字段（infrastructure/channel/agent/service/kernel），但 Registry 不利用这个信息做差异化处理。
+
+### 需要阅读的源码
+
+**Kite — 看「当前注册是什么结构」**：
+- `core/registry/store.py` — `register_module()` 接收的 payload 结构：扁平字典，tools/hooks/events 混在一起
+- `core/launcher/module_scanner.py` — `ModuleInfo` 的 `type` 字段（infrastructure/channel/agent/service/kernel）在扫描后如何使用（几乎没使用）
+
+**龙虾 — 看「8 种注册类型如何实现」**（最值得学习）：
+- `src/plugins/types.ts` — `ClawdbotPluginApi` 的 8 个 register 方法，每种类型有独立的参数签名和语义
+- `src/plugins/registry.ts` — 不同类型的注册信息如何分别存储和管理
+- `src/plugins/loader.ts` — 插件加载后如何按类型分发到不同的注册路径
+
+**CoPaw — 看「三种注册表各自独立」**：
+- `src/copaw/app/channels/registry.py` — Channel 注册表：`get_channel_registry()` 返回 `dict[str, type[BaseChannel]]`
+- `src/copaw/providers/registry.py` — Provider 注册表：`PROVIDERS` 字典 + 自定义 provider 动态加载
+- `src/copaw/agents/skills_manager.py` — Skill 发现：扫描目录 + 解析 SKILL.md frontmatter
+
+### 要解决的问题
+
+1. 是否需要在 Registry 层面区分模块类型？还是保持当前的"万物皆模块"哲学，只在约定层面区分？
+2. 如果区分，哪些类型需要特殊处理？Channel 需要消息路由，Agent 需要会话管理，Service 只需健康检查——这些差异是否应该在框架层体现？
+3. 注册 payload 是否需要重构？当前的扁平字典 vs 按类型分区（`{channel: {...}, tools: {...}, hooks: {...}}`）？
+4. 是否引入"能力声明"机制——模块声明自己提供哪些能力（`capabilities: [messaging, tool_hosting, llm_serving]`），让其他模块按能力发现而不是按名称发现？
+
+### Kite 相关文档
+
+- 当前注册 payload：[注册中心设计 L53-151](注册中心设计.md)
+- 模块类型定义：[04-模块规范 L25-65](Kite框架设计/04-模块规范.md)
+- 扩展性说明：[08-扩展性](Kite框架设计/08-扩展性.md)
+
+---
+
+## P2-2：统一错误码体系
+
+### 现状
+
+Kite 各模块的错误处理各自为政：Registry 返回 HTTP 状态码 + 简单 `detail` 字符串，Event Hub 返回 `{type: "error", message: "..."}`，Launcher 在控制台打印日志。没有统一的错误码、错误分类、错误格式。
+
+### 需要阅读的源码
+
+**Kite — 看「当前错误格式有多碎片化」**：
+- `core/registry/store.py` — 搜索 `HTTPException` 或 `raise`：看 Registry 的错误返回格式
+- `core/event_hub/hub.py` — 搜索 `"error"`：看 Event Hub 的 WS 错误消息格式
+- `core/launcher/entry.py` — 搜索 `print` 或 `log`：看 Launcher 的日志格式
+
+**龙虾 — 看「统一错误码体系」**（最值得学习）：
+- `src/gateway/protocol/schema/error-codes.ts` — `ErrorCodes` 枚举定义：每个错误码有 code 字符串 + 描述；`errorShape()` 工厂函数生成统一的 `{code, message, data?}` 结构
+- `src/gateway/protocol/schema/protocol-schemas.ts` — RPC 响应 schema 中错误部分的统一定义
+
+**CoPaw — 看「错误转储模式」**：
+- `src/copaw/app/runner/query_error_dump.py` — `write_query_error_dump()`：错误发生时保存完整上下文（traceback + request + agent state）到 temp JSON 文件，方便调试
+
+### 要解决的问题
+
+1. 错误码的作用范围：仅框架内部通信？还是也暴露给最终用户（如 Web UI 展示）？
+2. 错误码的编号方案：数字码（如 HTTP 1xx-5xx）？字符串码（如 `MODULE_NOT_FOUND`）？带前缀的命名空间码（如 `REGISTRY.AUTH_FAILED`）？
+3. 错误响应的统一格式：`{code, message, data?, module?, timestamp?}`？
+4. 是否需要错误链（cause chain）——当模块 A 调用模块 B 失败时，A 返回的错误是否应包含 B 的原始错误？
+5. 日志格式是否也需要统一？结构化日志（JSON）vs 人类可读日志？
+
+### Kite 相关文档
+
+- 当前 Registry 错误处理：[注册中心设计 L153-317](注册中心设计.md)
+- Event Hub 错误格式：[事件中心设计 L29-95](事件中心设计.md)
+- Launcher 错误处理：[Launcher L551-564](Launcher启动器文档.md)
+
+---
+
+## P2-3：CLI 运维工具增强
+
+### 现状
+
+Kite 的 CLI 目前只有 `python main.py`（启动）和 `kite`（npm 全局命令，功能等同）。没有运维子命令来查看系统状态、管理模块、查看日志。运维操作只能通过 Launcher 的 HTTP API 手动调用。
+
+### 需要阅读的源码
+
+**Kite — 看「当前 CLI 和 API 能力」**：
+- `cli.js` — 当前 npm CLI 实现：只是启动 `python main.py` 的薄包装
+- `core/launcher/entry.py` — Launcher API 端点定义（搜索 `@app.get` / `@app.post`）：GET /launcher/modules、POST .../start、POST .../stop、POST .../restart、POST /launcher/rescan、PUT .../state
+
+**龙虾 — 看「丰富的 CLI 子命令」**（最值得学习）：
+- `src/cli/program/build-program.ts` — Commander.js 程序构建：看它如何组织子命令
+- `src/cli/program/command-registry.ts` — 命令注册机制：`registerProgramCommands()` 如何分发到各 register.*.ts
+- `src/commands/health.ts` — `health` 子命令实现：多探针健康检查，了解 CLI 如何调用 Gateway API
+
+**CoPaw — 看「Click CLI 组织方式」**：
+- `src/copaw/cli/main.py` — Click 主入口：lazy-loaded 命令分组，看它如何组织 10+ 子命令
+- 各子命令文件在 `src/copaw/cli/` 下（app_cmd.py / channels_cmd.py / config_cmd.py / cron_cmd.py / env_cmd.py / init_cmd.py / providers_cmd.py / skills_cmd.py 等）
+
+### 要解决的问题
+
+1. 最小可用的 CLI 子命令集：
+   - `kite start` — 启动（已有）
+   - `kite status` — 显示所有模块状态（调 Launcher API）
+   - `kite logs <module>` — 查看模块日志（需要日志持久化）
+   - `kite stop <module>` / `kite restart <module>` — 管理模块
+   - `kite config get/set` — 读写配置（需要先有集中配置系统）
+   - 还需要什么？
+2. CLI 的实现语言：Python（argparse/click）？Node.js（commander）？还是两套都要（跟 SDK 对应）？
+3. CLI 与 Launcher API 的关系：CLI 是 API 的薄客户端？还是直接操作文件/进程？
+4. 是否需要交互式模式（如龙虾的 `chat` 子命令）？
+5. 是否需要 `kite init`（初始化工作区）和 `kite doctor`（诊断修复）？
+
+### Kite 相关文档
+
+- 当前 CLI：[npm发布与CLI使用指南](npm发布与CLI使用指南.md)
+- Launcher API：[Launcher L359-480](Launcher启动器文档.md)
+
+---
+
+## P2-4：结构化日志系统
+
+### 现状
+
+Kite 各模块通过 stdout 输出日志，Launcher 在启动阶段捕获 stdout 消息（包含结构化 `{"kite": ...}` 和普通日志），但 `module.ready` 后就关闭 stdio。此后模块的日志无处可去——没有统一的日志收集、格式化、持久化、查询机制。多进程架构下这个问题比单进程更严重。
+
+### 需要阅读的源码
+
+**Kite — 看「当前日志怎么处理」**：
+- `core/launcher/process_manager.py` — `_handle_stdout()` / `close_stdio()`：stdout 回调在 module.ready 后关闭，之后日志丢失
+- `core/launcher/entry.py` — Launcher 自己用 `print()` 输出日志，无结构化格式
+
+**龙虾 — 看「完整的结构化日志」**（最值得学习）：
+- `src/logging/logger.ts` — tslog 集成：subsystem 命名空间（如 `gateway.auth`、`channel.telegram`）、文件轮转（24h）、外部 transport attachment
+- `src/logging/config.ts` — 日志配置从环境变量/config 文件解析，支持按 subsystem 设置不同级别
+- `src/logging/console.ts` — Console 输出样式化和捕获
+
+**CoPaw — 看「简单但实用的日志」**：
+- `src/copaw/utils/logging.py` — `ColorFormatter`：ANSI 着色、Windows 兼容（ctypes 启用 VT processing）、`LOG_NAMESPACE = "copaw"` 统一前缀
+
+### 要解决的问题
+
+1. 多进程日志汇聚方案：
+   - 方案 A：各模块写本地日志文件，Launcher/CLI 聚合查询
+   - 方案 B：通过 Event Hub 广播日志事件（`log.*`），由专门的日志收集模块持久化
+   - 方案 C：保持 stdout，但 module.ready 后不关闭 stdio（需改变 Launcher 的 stdio 生命周期管理）
+2. 日志格式：JSON 结构化（机器友好）？人类可读（开发调试友好）？两者兼顾（如 tslog 的双输出）？
+3. 日志级别的动态调整：是否支持运行时通过 API 或配置修改某个模块的日志级别？（与 P1-2 配置热重载关联）
+4. 日志持久化：轮转策略（按时间/大小）？保留期限？是否需要日志搜索/查询能力？
+5. 与 CLI 的集成：`kite logs <module>` 的实现——实时 tail（如 `docker logs -f`）还是历史查询？
+
+### Kite 相关文档
+
+- 当前 stdio 管理：Launcher process_manager 的 stdout 回调机制
+- Launcher 日志：[Launcher L551-564](Launcher启动器文档.md)
+
+---
+
+## P2-5：测试策略
+
+### 现状
+
+Kite 目前只有两个手动验证模块（`test_modules/hello` 和 `test_modules/hello_node`），没有自动化测试框架、单元测试、集成测试或 CI 流水线。多进程架构的测试比单进程更复杂——需要测试模块发现、进程启动、Registry 注册、Event Hub 通信等跨进程交互。
+
+### 需要阅读的源码
+
+**Kite — 看「当前的验证手段」**：
+- `test_modules/hello/entry.py` — 最小 Python 模块：只验证 boot_info 读取和环境变量
+- `test_modules/hello_node/entry.js` — 完整 Node.js 模块：验证完整的 8 步协议（stdin → HTTP → Registry → Event Hub → module.ready）
+
+**龙虾 — 看「完整的测试体系」**（最值得学习）：
+- `vitest.config.ts` — 测试配置：120s 超时（Windows 180s）、forks pool（进程隔离）、max workers 3-16、coverage 70% 阈值
+- 测试文件组织：`*.test.ts`（单元测试，colocated）、`*.e2e.test.ts`（端到端）、`*.live.test.ts`（真实 API）
+- 覆盖率排除：CLI 入口 / daemon / macOS 特定 / channel 集成 / TUI / Gateway 等难以自动化测试的部分
+- `package.json` 测试命令：`test` / `test:coverage` / `test:e2e` / `test:live` / `test:docker:*`
+
+**CoPaw — 对比参考（测试较少但有配置）**：
+- `pyproject.toml` 测试配置：pytest + pytest-asyncio（asyncio_mode = "auto"）、`slow` marker、pytest-cov
+
+### 要解决的问题
+
+1. 测试框架选择：Python 侧用 pytest（与现有生态一致）？Node.js 测试模块用 vitest/jest？
+2. 多进程测试策略：
+   - 单元测试：各模块独立测试（mock Registry/Event Hub 接口）
+   - 集成测试：启动真实的 Launcher + Registry + Event Hub，测试模块间通信
+   - 端到端测试：完整启动框架，验证从消息到回复的全链路
+3. 测试中的 Registry/Event Hub 如何处理？
+   - 方案 A：提供 mock/stub 版本（轻量，快速）
+   - 方案 B：每个测试启动真实的 Registry + Event Hub 实例（真实，但慢）
+4. 覆盖率目标：核心模块（Registry/Event Hub/Launcher）要求高覆盖率，扩展模块可以较低？
+5. CI 流水线：GitHub Actions 配置，何时运行哪些测试（push 跑单元，PR 跑集成，release 跑端到端）？
+
+### Kite 相关文档
+
+- 测试模块：`test_modules/hello/` 和 `test_modules/hello_node/`（当前仅有的测试资产）
+
+---
+
+## P2-6：Web UI 管理控制台
+
+### 现状
+
+Kite 的运维操作只能通过 Launcher HTTP API 或未来的 CLI 命令。没有可视化界面来查看模块状态、管理配置、监控事件、查看日志。对于多模块系统，Web UI 比 CLI 更直观——能同时展示所有模块的状态、实时事件流、依赖关系图等。
+
+### 需要阅读的源码
+
+**Kite — 看「已有的 API 端点」**：
+- `core/launcher/entry.py` — Launcher API：GET /launcher/modules、POST .../start|stop|restart、POST /launcher/rescan、PUT .../state——这些 API 可以直接作为 Web UI 的后端
+
+**龙虾 — 看「Lit Web Components 控制台」**：
+- `ui/src/main.ts` — Web UI 入口：Lit 初始化、样式加载
+- `ui/src/ui/app.ts` — 主组件：Gateway WebSocket 连接、chat/cron/config/sessions/channels/device pairing 管理面板
+
+**CoPaw — 看「React + Ant Design 全功能控制台」**（最值得学习）：
+- `console/src/layouts/MainLayout/index.tsx` — Ant Design Layout：侧边栏导航、11 个页面路由（chat/channels/sessions/cron-jobs/skills/mcp/workspace/agents/models/environments/agent-config）
+- `console/src/api/index.ts` — 聚合 12 个 API 模块：channel/cron/chat/session/env/provider/skill/agent/workspace/localModel/ollamaModel/mcp
+- `console/src/pages/Chat/index.tsx` — Chat 页面：`AgentScopeRuntimeWebUI` 集成、实时对话
+
+### 要解决的问题
+
+1. 技术选型：
+   - Lit Web Components（龙虾方案，轻量，无构建依赖）？
+   - React + Ant Design（CoPaw 方案，生态丰富，开发快）？
+   - 纯 HTML + HTMX（最简单，无前端构建）？
+2. 部署方式：Web UI 由哪个模块 serve？Launcher 直接 serve 静态文件？还是独立的 Web UI 模块？
+3. 最小可用功能集：
+   - 模块列表 + 三层状态展示（config/desired/actual）
+   - 模块 start/stop/restart 操作
+   - 实时事件流（连接 Event Hub WebSocket）
+   - 日志查看（与 P2-4 关联）
+4. 是否需要 Chat UI？如果 Kite 承载了 Agent 模块，是否需要内置聊天界面？还是交给前端应用？
+5. 认证保护：Web UI 是否需要登录？localhost 访问是否可以免认证？
+
+### Kite 相关文档
+
+- Launcher API（Web UI 后端基础）：[Launcher L359-480](Launcher启动器文档.md)
+
+---
+
+## P2-7：初始化引导向导
+
+### 现状
+
+Kite 的 `cli.js` 首次运行时会自动安装框架到 `~/.kite/versions/`，但没有交互式初始化向导来引导用户完成工作区配置、模块启用、API Key 设置等首次使用步骤。用户需要手动了解环境变量和模块结构才能开始使用。
+
+### 需要阅读的源码
+
+**Kite — 看「当前的首次运行流程」**：
+- `cli.js` — npm CLI：首次运行复制框架到 `~/.kite/versions/{version}/`，创建 modules/data/workspace/repo 目录，但无交互式配置
+
+**龙虾 — 看「完整的 onboarding 向导」**（最值得学习）：
+- `src/wizard/onboarding.ts` — onboarding 流程编排：auth 选择 → model 配置 → channel 设置 → skills → hooks → config 最终确认
+- `src/wizard/session.ts` — wizard 状态管理：跨步骤的配置收集和验证
+
+**CoPaw — 看「交互式 init 命令」**：
+- `src/copaw/cli/init_cmd.py` — `copaw init`：`configure_channels_interactive()` / `configure_env_interactive()` / `configure_providers_interactive()` / `configure_skills_interactive()`，包含安全警告说明 CoPaw 的能力范围
+
+### 要解决的问题
+
+1. 向导应该覆盖哪些配置步骤？
+   - 工作区目录确认
+   - 模块发现路径配置
+   - API Key 设置（LLM provider）
+   - 默认 Agent 和 Channel 选择
+   - daemon 安装（与 P1-7 关联）
+2. 实现方式：交互式 CLI（questionary/inquirer）？Web 页面（启动临时 HTTP 服务）？
+3. `--defaults` 非交互模式：是否支持跳过所有提示，使用默认值快速启动？
+4. 配置验证（doctor）：`kite doctor` 命令检查环境、依赖、配置完整性（与 P2-3 CLI 关联）
+5. 向导完成后是否自动启动框架？
+
+### Kite 相关文档
+
+- 当前 CLI：[npm发布与CLI使用指南](npm发布与CLI使用指南.md)
+- 环境变量：[环境变量与运行时目录设计](环境变量与运行时目录设计.md)
+
+---
+
+## P2-8：Cron 定时任务
+
+### 现状
+
+Kite 设计文档中有 Task 概念（02-核心概念 L317-333）和 Task System（03-系统架构 L182-207），但更偏向"任务队列"而非"定时调度"。个人助手场景中定时任务是核心能力——每日摘要、定时提醒、周期性数据收集等都依赖 cron 调度。
+
+### 需要阅读的源码
+
+**Kite — 看「当前 Task System 的设计」**：
+- `docs/Kite框架设计/02-核心概念.md` L317-333 — Task 概念：task_id / type / goal / status / priority / parent_task_id / created_by / assigned_to
+- `docs/Kite框架设计/03-系统架构.md` L182-207 — Task System：独立进程、注册任务接口（create/query/claim/submit/delete）
+- `docs/Kite框架设计/05-核心流程.md` L129-155 — 任务执行流程：创建 → 排队 → Kernel 启动 planner Agent → 执行 → 完成
+
+**龙虾 — 看「Cron 服务 + 隔离执行」**：
+- `src/cron/service.ts` — cron 调度服务：add/update/remove/list/run API、内存状态 + 持久化、cron 表达式解析
+- `src/cron/isolated-agent.ts` — cron 任务隔离 agent 调用：delivery target 解析（发送到哪个 channel）、heartbeat 防超时
+
+**CoPaw — 看「APScheduler 集成」**：
+- `src/copaw/app/crons/manager.py` — APScheduler `AsyncIOScheduler`：CronTrigger（cron 表达式）+ IntervalTrigger（间隔触发），JSON 文件持久化 jobs
+
+### 要解决的问题
+
+1. 定时调度是 Task System 的一部分（trigger 类型扩展 `scheduled`），还是独立的 Cron 模块？
+   - Task System 已规划了 `created_by` 字段，scheduled trigger 可以是一种 task 创建来源
+   - 独立 Cron 模块更简单，职责清晰
+2. cron 表达式解析：用成熟库（Python APScheduler / Node.js node-cron）？还是自行实现？
+3. 任务持久化：重启后 cron 任务是否自动恢复？持久化到哪里（集中配置文件 / 独立 jobs.json / SQLite）？
+4. 任务执行上下文：cron 触发时，是否需要创建新 session？执行结果发送到哪个 channel？
+5. 错误处理：cron 任务执行失败时的重试策略和通知机制？
+
+### Kite 相关文档
+
+- Task 概念：[02-核心概念 L317-333](Kite框架设计/02-核心概念.md)
+- Task System：[03-系统架构 L182-207](Kite框架设计/03-系统架构.md)
+- 任务执行流程：[05-核心流程 L129-155](Kite框架设计/05-核心流程.md)
+
+---
+
+## 附录：Kite 现有优势（对标确认）
+
+以下是 Kite 在对比中表现出的设计优势，应在后续改进中**保持**而非削弱：
+
+| 优势 | 说明 | 对比 |
+|------|------|------|
+| **多进程隔离** | 每模块独立进程，崩溃不扩散 | 龙虾/CoPaw 都是单进程，一个插件/channel 出问题可能拖垮全局 |
+| **stdin token 传递** | token 不出现在环境变量、命令行、文件系统 | 龙虾 token 持久化在 device-auth.json；CoPaw 无认证 |
+| **Token 不持久化** | 每次启动重新生成，泄露窗口极小 | 龙虾的 device token 长期有效 |
+| **NATS 风格事件匹配** | `*` 和 `>` 通配符，灵活的订阅模式 | 龙虾只有具名事件；CoPaw 无事件总线 |
+| **事件去重 + Outbox** | 1h 滑动窗口去重 + 断连持久化重发 | 龙虾/CoPaw 均无此机制 |
+| **遗留进程清理** | processes.json + PID/cmdline 双重验证后清理 | 龙虾/CoPaw 均无此机制 |
+| **跨平台进程管理** | Win/Linux/Mac 各有策略且多级降级 | 龙虾依赖 Node.js 抽象；CoPaw 无子进程 |
+| **语言无关协议** | JSON + HTTP + WebSocket，任何语言都能接入 | 龙虾绑定 Node.js 生态；CoPaw 绑定 Python |
+| **模块生命周期事件** | starting → ready → started → stopped 完整链 | 龙虾有但较简单；CoPaw 只有 start/stop |
+| **三层状态模型** | config × desired × actual，状态可追溯 | 龙虾/CoPaw 只有 enabled/disabled |
+| **多语言模块混编** | Python + Node.js + Binary（Go/Rust）同时运行，IPC 协议语言无关 | 龙虾只能用 TypeScript；CoPaw 只能用 Python |
+| **版本共存** | `~/.kite/versions/{version}/` 多版本并存，`kite --use 1.0.6` 按需切换 | 龙虾/CoPaw 只能安装一个版本 |
+| **依赖拓扑排序** | 模块按 `depends_on` 声明自动计算启动顺序 | 龙虾/CoPaw 均无模块依赖管理 |
+
+---
+
+## 讨论索引
+
+逐条探讨时，建议按以下顺序（依赖关系从上到下）：
+
+```
+P0-3 集中配置系统           ← 很多后续改进的基础
+  ↓
+P0-2 module.md Schema 校验  ← 模块加载的安全网
+  ↓
+P0-1 Module SDK             ← 依赖配置系统和校验来定义 SDK 接口
+  ↓
+P0-4 Agent 推理运行时       ← 依赖 SDK 定义 Agent 执行模型
+  ↓
+P0-5 Session 会话管理       ← 依赖 Agent 运行时和配置系统
+  ↓
+P1-2 配置热重载             ← 依赖集中配置系统
+  ↓
+P1-1 模块间权限控制         ← 依赖 Registry 和配置系统
+  ↓
+P1-3 标准化 RPC 协议        ← 可能影响 SDK 设计
+  ↓
+P1-4 长期记忆系统           ← 依赖 Agent 运行时和 Session 管理
+  ↓
+P1-5 Model Provider 抽象层  ← 依赖配置系统和 RPC 协议
+  ↓
+P1-6 消息路由与 Channel 抽象 ← 依赖 SDK、RPC、Session 管理
+  ↓
+P1-7 Daemon 后台常驻        ← 依赖 CLI 和配置系统
+  ↓
+P2-1 扩展点分类             ← 依赖 RPC 和 Registry 改进
+  ↓
+P2-2 统一错误码             ← 贯穿所有通信层
+  ↓
+P2-3 CLI 运维工具           ← 依赖 API 和配置系统完善
+  ↓
+P2-4 结构化日志系统         ← 依赖进程管理和配置系统
+  ↓
+P2-5 测试策略               ← 依赖 SDK 和核心模块稳定
+  ↓
+P2-6 Web UI 管理控制台      ← 依赖 API 和日志系统
+  ↓
+P2-7 初始化引导向导         ← 依赖 CLI 和配置系统
+  ↓
+P2-8 Cron 定时任务          ← 依赖 Agent 运行时和 Session 管理
+```