@agentunion/kite 1.5.0 → 1.6.0

package/docs//345/256/214/346/225/264/345/220/257/345/212/250/346/265/201/347/250/213/350/256/276/350/256/241.md

@@ -0,0 +1,452 @@
+# Kite 完整启动流程设计
+
+## 设计目标
+
+**只要安装了 Node.js 就可以安装和启动 Kite**，在启动过程中自动完成：
+1. Python 安装（如果需要）
+2. 虚拟环境准备
+3. 依赖库安装
+
+## 完整流程
+
+### 1. npm install（一次性）
+
+```
+npm install -g @agentunion/kite
+    ↓
+postinstall 钩子执行
+    ↓
+scripts/setup-python-env.js
+    ↓
+检测系统 Python（精确版本）
+    ├─ 有 → 完成
+    └─ 没有 → 下载安装（仅 Windows）
+```
+
+**职责**：只确保 Python 可用（不创建 venv，不安装依赖）
+
+### 2. kite start（每次启动）
+
+```
+用户执行: kite start
+    ↓
+cli.js (Node.js 层)
+    ├─ 1. 检查框架代码是否安装
+    ├─ 2. 调用 ensureEnvironment(versionDir)
+    │   ├─ 读取 ~/.kite/env_status.json
+    │   ├─ 步骤 1/3: 需要准备 Python？
+    │   │   ├─ YES → 执行 setup-python-env.js
+    │   │   └─ NO  → 跳过
+    │   ├─ 步骤 2/3: 需要准备虚拟环境？
+    │   │   ├─ YES → 调用: python -m kite_cli venv-setup
+    │   │   └─ NO  → 跳过
+    │   ├─ 步骤 3/3: 需要安装依赖？
+    │   │   ├─ YES → 调用: python -m kite_cli deps-install
+    │   │   └─ NO  → 跳过（快速启动）
+    │   └─ 返回成功/失败
+    └─ 3. 启动: python main.py（带异常捕获）
+         ├─ 捕获启动错误 → 标记环境失败
+         ├─ 捕获运行时错误 → 标记环境失败
+         └─ 下次启动重新检查环境
+              ↓
+main.py (Python 层)
+    ├─ 运行代码统计
+    └─ 启动 Launcher（环境已就绪）
+```
+
+## 关键模块
+
+### 1. scripts/env-manager.js（Node.js 层）
+
+**职责**：环境检查和准备的总控制器
+
+**核心函数**：
+
+```javascript
+function ensureEnvironment(versionDir) {
+  // 1. 读取环境状态
+  const status = loadEnvStatus();
+
+  // 步骤 1/3: 检查是否需要准备 Python
+  if (needsPythonSetup(versionDir)) {
+    setupPython(versionDir);
+  }
+
+  // 步骤 2/3: 检查是否需要准备虚拟环境
+  if (needsVenvSetup(status)) {
+    setupVenv(versionDir);
+  }
+
+  // 步骤 3/3: 检查是否需要安装依赖
+  if (needsDepsInstall(status)) {
+    installDeps(versionDir);
+  }
+
+  return true;
+}
+```
+
+**判断逻辑**：
+
+```javascript
+// 需要准备 Python？
+function needsPythonSetup(versionDir) {
+  // 读取 python_version.json
+  // 检测系统是否有该精确版本的 Python
+  // 没有 → true
+}
+
+// 需要准备虚拟环境？
+function needsVenvSetup(status) {
+  // 状态文件不存在 → true
+  // 上次检查失败 → true
+  // 虚拟环境不存在 → true
+  // 否则 → false
+}
+
+// 需要安装依赖？
+function needsDepsInstall(status) {
+  // 状态文件不存在 → true
+  // 上次检查失败 → true
+  // 依赖未安装 → true
+  // 否则 → false（快速启动）
+}
+```
+
+**异常处理**：
+
+```javascript
+// 任何步骤失败，标记环境失败
+function markEnvFailed(reason) {
+  // 写入 env_status.json
+  // status = "failed"
+  // 下次启动重新检查
+}
+```
+
+### 2. kite-cli 命令（Python 层）
+
+**职责**：虚拟环境和依赖库的准备（分步执行）
+
+#### kite venv-setup
+
+**执行方式**：
+```bash
+python -m kite_cli venv-setup
+```
+
+**功能**：
+- 检查 Python 版本
+- 检查虚拟环境是否存在
+- 不存在则创建虚拟环境
+
+#### kite deps-install
+
+**执行方式**：
+```bash
+python -m kite_cli deps-install
+```
+
+**功能**：
+- 加载 dependencies_lock.json
+- 检查依赖库是否安装且版本一致
+- 不一致则安装依赖
+
+#### kite env-check
+
+**执行方式**：
+```bash
+python -m kite_cli env-check
+```
+
+**功能**：
+- 完整的环境检查（venv + deps）
+- 用于开发调试
+
+### 4. cli.js（Node.js 入口）
+
+**修改**：
+```javascript
+// 环境检查和准备（Node.js 层，三步）
+console.log('[kite] 检查环境...');
+if (!ensureEnvironment(versionDir)) {
+  console.error('[kite] 环境准备失败，无法启动');
+  process.exit(1);
+}
+
+// 启动 Python（带异常捕获）
+const python = process.platform === 'win32' ? 'python' : 'python3';
+const child = spawn(python, [path.join(versionDir, 'main.py'), ...pythonArgs], {...});
+
+// 捕获启动错误
+child.on('error', err => {
+  console.error(`[kite] 启动 Python 失败: ${err.message}`);
+  markEnvFailed('python_launch_failed');
+  process.exit(1);
+});
+
+// 捕获运行时错误
+child.on('exit', (code, signal) => {
+  if (code !== 0 && code !== null) {
+    console.error(`[kite] Python 进程异常退出，退出码: ${code}`);
+
+    // 常见的环境相关错误码
+    if (code === 1 || code === 127) {
+      console.error(`[kite] 可能是环境问题，下次启动将重新检查环境`);
+      markEnvFailed('python_runtime_error');
+    }
+  }
+
+  process.exit(code ?? 0);
+});
+```
+
+### 4. main.py（Python 入口）
+
+**修改**：
+```python
+# 环境检查已在 Node.js 层完成，直接启动
+from launcher.count_lines import run_stats
+run_stats()
+
+from launcher.entry import start_launcher
+start_launcher()
+```
+
+## 状态记录文件
+
+**路径**：`~/.kite/env_status.json`
+
+**作用**：
+- 记录上次环境检查的结果
+- `status === "success"` → 跳过检查（快速启动）
+- `status === "failed"` → 重新检查
+
+**格式**：
+```json
+{
+  "version": "1.0",
+  "last_check": "2026-03-08T10:30:00Z",
+  "status": "success",
+  "python": {
+    "version": "3.13.12",
+    "required_version": "3.13.12"
+  },
+  "venv": {
+    "path": "C:/Users/xxx/.kite/venv",
+    "exists": true
+  },
+  "dependencies": {
+    "installed": true,
+    "lock_hash": "abc123..."
+  }
+}
+```
+
+## 用户体验
+
+### 首次安装和启动
+
+```bash
+# 1. 安装（只需要 Node.js）
+npm install -g @agentunion/kite
+
+# 输出：
+# [Kite Setup] 检查 Python 环境...
+# [Kite Setup] 要求的 Python 版本: 3.13.12
+# [Kite Setup] 系统未检测到 Python 3.13.12
+# [Kite Setup] 正在下载 Python embeddable 版本...
+# [Kite Setup] Python 3.13.12 已安装到: C:\Users\xxx\.kite\python
+# [Kite Setup] Python 环境检查完成
+
+# 2. 首次启动
+kite start
+
+# 输出：
+# [kite] 检查环境...
+# [Kite Env] 检查环境...
+# [Kite Env] 步骤 1/3: Python 环境已就绪
+# [Kite Env] 步骤 2/3: 准备虚拟环境
+# ============================================================
+#   Kite 虚拟环境准备
+# ============================================================
+# ✓ Python 版本: 3.13.12
+# 正在创建虚拟环境...
+# ✓ 虚拟环境创建成功: C:\Users\xxx\.kite\venv
+# [Kite Env] 虚拟环境准备完成
+# [Kite Env] 步骤 3/3: 安装依赖库
+# ============================================================
+#   Kite 依赖库安装
+# ============================================================
+# 依赖锁定文件: 18 个依赖
+# ✗ 18 个缺失
+#   缺失: 18 个
+# 正在安装依赖...
+# ... (安装进度)
+# ✓ 依赖安装成功
+# [Kite Env] 依赖安装完成
+# [Kite Env] 环境准备完成
+# [kite] 版本: 1.4.0
+# ... (Kite 启动)
+```
+
+### 后续启动（快速）
+
+```bash
+kite start
+
+# 输出：
+# [kite] 检查环境...
+# [Kite Env] 检查环境...
+# [Kite Env] 步骤 1/3: Python 环境已就绪
+# [Kite Env] 步骤 2/3: 虚拟环境已就绪
+# [Kite Env] 步骤 3/3: 依赖库已就绪
+# [Kite Env] 环境准备完成
+# [kite] 版本: 1.4.0
+# ... (Kite 启动)
+```
+
+### 异常情况（自动修复）
+
+```bash
+# 场景：虚拟环境被删除
+rm -rf ~/.kite/venv
+
+kite start
+
+# 输出：
+# [kite] 检查环境...
+# [Kite Env] 检查环境...
+# [Kite Env] 步骤 1/3: Python 环境已就绪
+# [Kite Env] 步骤 2/3: 准备虚拟环境
+# ... (自动重建虚拟环境)
+# [Kite Env] 步骤 3/3: 安装依赖库
+# ... (自动重新安装依赖)
+# [Kite Env] 环境准备完成
+# [kite] 版本: 1.4.0
+# ... (Kite 启动)
+```
+
+### 运行时错误（标记失败）
+
+```bash
+kite start
+
+# 假设 Python 运行时出错
+# [kite] Python 进程异常退出，退出码: 1
+# [kite] 可能是环境问题，下次启动将重新检查环境
+
+# 下次启动自动重新检查
+kite start
+
+# [Kite Env] 步骤 1/3: Python 环境已就绪
+# [Kite Env] 步骤 2/3: 准备虚拟环境
+# [Kite Env] 步骤 3/3: 安装依赖库
+# ... (重新准备环境)
+```
+
+## 优势
+
+### 1. 零依赖安装
+
+用户只需要：
+- ✅ Node.js（必须）
+- ❌ Python（自动安装）
+- ❌ pip（自动准备）
+- ❌ virtualenv（自动创建）
+
+### 2. 快速启动
+
+- **首次启动**：1-3 分钟（下载 Python + 创建 venv + 安装依赖）
+- **后续启动**：< 1 秒（跳过所有检查）
+
+### 3. 版本一致性
+
+- Python 版本：精确匹配（3.13.12）
+- 依赖版本：精确匹配（fastapi==0.124.4）
+- 开发环境 = 生产环境
+
+### 4. 自动修复
+
+- Python 不存在 → 自动安装
+- 虚拟环境损坏 → 自动重建
+- 依赖缺失 → 自动安装
+- 版本不匹配 → 自动更新
+
+## 故障排查
+
+### 问题：npm install 失败
+
+**原因**：网络问题或 Python 下载失败
+
+**解决**：
+```bash
+# 手动运行 setup 脚本
+node node_modules/@agentunion/kite/scripts/setup-python-env.js
+```
+
+### 问题：kite start 卡在环境准备
+
+**原因**：依赖安装缓慢
+
+**解决**：
+- 等待安装完成（首次启动需要时间）
+- 或使用国内镜像：编辑 `~/.pip/pip.conf`
+
+### 问题：环境检查失败
+
+**原因**：Python 版本不匹配或依赖冲突
+
+**解决**：
+```bash
+# 清理环境重新开始
+rm -rf ~/.kite/venv
+rm ~/.kite/env_status.json
+kite start
+```
+
+### 问题：手动测试环境检查
+
+```bash
+# 测试 Python 准备
+node scripts/setup-python-env.js
+
+# 测试虚拟环境和依赖准备
+python -m kite_cli env-check
+```
+
+## 开发流程
+
+### 打包前准备
+
+```bash
+# 1. 扫描依赖
+kite prepare
+
+# 2. 检查生成的文件
+cat dependencies_lock.json
+cat python_version.json
+
+# 3. 提交
+git add dependencies_lock.json python_version.json
+git commit -m "chore: update dependencies lock"
+
+# 4. 发布
+npm publish
+```
+
+### 测试环境准备
+
+```bash
+# 测试完整流程
+rm -rf ~/.kite/venv ~/.kite/env_status.json
+kite start
+```
+
+## 架构优势
+
+1. **分层清晰**：Node.js 层负责 Python 准备，Python 层负责业务逻辑
+2. **职责明确**：每个模块只做一件事
+3. **可测试性**：每个步骤都可以独立测试
+4. **可维护性**：逻辑集中，易于修改
+5. **用户友好**：自动化程度高，无需手动操作

package/docs//345/256/236/347/216/260/350/247/204/345/210/222.md

@@ -0,0 +1,195 @@
+# Kite 实现规划
+
+> **状态说明**：Phase 1（基础设施）已全部实现，详见各模块代码和设计文档。本文仅保留尚未实现的规划。
+> 当以下所有 Phase 完成后，本文件可删除。
+
+---
+
+## 待实现：Module SDK 公共库
+
+目标：消除各模块重复的 Registry 注册 / Event Hub 连接 / 健康检查样板代码。
+
+| 文件 | 内容 |
+|------|------|
+| `sdk/utils.py` | 日志配置、端口分配、module.md 解析 |
+| `sdk/registry_client.py` | `register()`、`deregister()`、`discover()`、`heartbeat()` — 纯 HTTP 调用 |
+| `sdk/event_client.py` | WebSocket 客户端：`connect()`、`subscribe()`、`publish()`、`on_event()` 回调、断线重连、outbox 持久化 |
+| `sdk/module.py` | `ModuleBase` 基类：整合上面三个，提供 `async run()` 模板方法 |
+
+`ModuleBase` 生命周期（适配当前机制）：
+
+```python
+class ModuleBase:
+    async def run(self):
+        self.read_boot_info()                # stdin readline → {token}
+        self.read_env()                      # KITE_REGISTRY_PORT, KITE_INSTANCE_DIR, ...
+        self.read_module_md()                # preferred_port, advertise_ip
+        await self.start_http()              # 绑定端口，启动 FastAPI
+        await self.register_to_registry()    # POST /modules
+        await self.connect_event_hub()       # 从 Registry 发现 → WebSocket 连接
+        await self.subscribe_events()        # 子类覆写
+        await self.send_module_ready()       # 发布 module.ready 事件
+        await self.start()                   # 业务逻辑（子类覆写）
+```
+
+当前 `event_hub_bench`、`watchdog`、`hello` 各自手写了注册/连接逻辑，SDK 完成后可统一替换。
+
+---
+
+## Phase 2：消息通路（Channel → Kernel → 事件流转）
+
+目标：消息从 channel 进来，Kernel 创建会话和身份，产生 session 事件。
+
+**Step 2.1 — WebChat Channel**
+
+| 文件 | 内容 |
+|------|------|
+| `extensions/channels/webchat/entry.py` | 继承 ModuleBase，启动 HTTP server |
+| `extensions/channels/webchat/server.py` | FastAPI：提供静态页面 + WebSocket 端点（前端连接） |
+| `extensions/channels/webchat/static/index.html` | 极简聊天页面：输入框 + 消息列表 |
+
+流程：
+```
+浏览器 WebSocket → webchat server
+  → 收到用户消息
+  → 发布事件 channel.message.received {channel: "webchat", sender: "web_user_xxx", content: "你好"}
+  → 订阅 channel.message.send 事件
+  → 收到发送指令 → 通过 WebSocket 推给浏览器
+```
+
+**Step 2.2 — Kernel 基础**
+
+| 文件 | 内容 |
+|------|------|
+| `core/kernel/entry.py` | 继承 ModuleBase，订阅 `channel.message.*` |
+| `core/kernel/identity_manager.py` | 首次遇到 sender → 创建身份目录 + 索引 |
+| `core/kernel/session_manager.py` | 创建/查找/结束会话，写入 session 数据 |
+
+收到 `channel.message.received` 后：
+```
+1. 查索引：sender → identity（没有则自动创建 unidentified 身份）
+2. 查会话：identity 是否有活跃会话（没有则创建新会话）
+3. 发布 session.message.received {session_id, identity, content, channel}
+```
+
+**Phase 2 验证**：
+```
+浏览器输入消息
+  → webchat 发布 channel.message.received
+  → kernel 收到，创建身份
+  → kernel 创建会话，发布 session.message.received
+  → Event Hub 日志可见完整事件流转
+```
+
+---
+
+## Phase 3：对话闭环（Agent + Model Service）
+
+目标：消息进来 → LLM 处理 → 回复发出去。
+
+**Step 3.1 — Model Service**
+
+| 文件 | 内容 |
+|------|------|
+| `extensions/services/model_service/entry.py` | 继承 ModuleBase，注册 HTTP 接口到 Registry |
+| `extensions/services/model_service/server.py` | `POST /chat` — 接收 messages + tools，调用 LLM，返回 response |
+| `extensions/services/model_service/providers/openai.py` | OpenAI 兼容 API 调用（openai SDK） |
+
+接口设计：
+```python
+POST /chat
+{
+    "messages": [...],
+    "tools": [...],       # 可选
+    "model": "...",       # 可选，默认从配置读
+    "stream": false       # 先不做流式
+}
+→ {"role": "assistant", "content": "...", "tool_calls": [...]}
+```
+
+**Step 3.2 — Conversation Agent**
+
+| 文件 | 内容 |
+|------|------|
+| `extensions/agents/conversation/entry.py` | 继承 ModuleBase，订阅 `session.message.received` |
+| `extensions/agents/conversation/engine.py` | 对话循环 |
+
+对话循环：
+```
+收到 session.message.received
+  → 加载会话历史（从 session 目录读 messages.jsonl）
+  → 拼装 messages（system prompt + history + 当前消息）
+  → POST model_service/chat
+  → 收到回复
+  → 如果有 tool_calls → 执行工具 → 把结果加入 messages → 再次调用 LLM
+  → 最终回复 → 发布事件 session.message.reply {session_id, content}
+  → 保存到 messages.jsonl
+```
+
+**Step 3.3 — Kernel 回复路由**
+
+Kernel 订阅 `session.message.reply`，转换为 channel 发送指令：
+```
+收到 session.message.reply {session_id, content}
+  → 查 session → 找到 channel + sender
+  → 发布 channel.message.send {channel: "webchat", target: "web_user_xxx", content: "..."}
+```
+
+**Phase 3 验证**：
+```
+浏览器输入 "你好"
+  → webchat → kernel（身份+会话）→ conversation agent → model_service → LLM
+  → 回复 → conversation agent → kernel → webchat → 浏览器显示回复
+完整对话闭环。
+```
+
+---
+
+## Phase 4：身份与工作区
+
+目标：补全身份管理和工作区机制。
+
+**Step 4.1 — 身份层完善**
+
+- 身份识别（unidentified → identified）
+- 身份合并/拆分
+- history.jsonl 变更记录
+- profile.md 读写
+
+**Step 4.2 — 工作区机制**
+
+- 默认工作区创建（`workspaces/{agent_name}/`）
+- config.json（agent 级配置）
+- agent.md（agent 指令/人设）
+- memory.md（长期记忆）
+- peer 级数据目录
+- session 数据存储
+
+**Step 4.3 — 权限体系**
+
+- switches.json 多级合并（deny wins）
+- context_builder 组装工具列表
+- check_permission 调用链
+
+---
+
+## Phase 5：Polyglot + Clawdbot 兼容
+
+目标：接入 clawdbot channel 和 skill。
+
+> Step 5.1（Launcher 多 runtime）已实现：`process_manager.py` 支持 python / node / binary。
+
+**Step 5.2 — Node.js Module SDK**
+
+- `@kite/module-sdk` npm 包
+- 与 Python SDK 功能对等：连 Registry + Event Hub + 健康检查
+
+**Step 5.3 — clawdbot-bridge（Channel）**
+
+- 通用 adapter：加载 clawdbot channel plugin → 转换事件
+- config 映射
+
+**Step 5.4 — clawdbot-skills（Service）**
+
+- 加载 clawdbot skill → 注册 tool 到 Registry
+- context 转换层