@agentunion/kite 1.4.0 → 1.6.0

package/.claude/skills/kite/skill.md

@@ -0,0 +1,272 @@
+---
+name: kite
+description: Kite 模块脚手架 — 生成新模块、适配现有项目、审查现有模块、查看 Kite 机制说明
+---
+
+# /kite — Kite 模块脚手架
+
+## 触发条件
+
+用户输入 `/kite` 时执行本 skill。
+
+## 源代码发现
+
+执行任何操作前，必须先确定 Kite 框架源代码位置。按以下优先级查找：
+
+1. **读取运行时环境**：检查 `~/.kite/data/env.json`（Launcher 每次启动时写入）
+   - 读取 `env.KITE_PROJECT.value` 字段，验证路径下有 `main.py` + `kernel/` + `extensions/`
+   - 该文件同时包含版本、实例目录、工作区等完整环境信息（可辅助诊断问题）
+   - `env.KITE_ENV.value` 为 `development` 表示开发模式，`production` 表示 npm/cli 安装模式
+2. **当前工作目录**：检查 cwd 是否有 `main.py` + `kernel/` + `extensions/` → 是 Kite 源码
+3. **用户级版本目录**：扫描 `~/.kite/versions/` 下最新版本目录（按 semver 排序）
+4. **npm 全局安装**：检查 `npm root -g`/@agentunion/kite
+5. **都没找到**：用 AskUserQuestion 让用户指定路径
+
+**找到多个时**，列出所有候选让用户选择。
+
+**env.json 结构说明**（Launcher 启动时写入 `~/.kite/data/env.json`）：
+```json
+{
+  "updated": "2026-03-27T10:00:00",
+  "pid": 12345,
+  "python": "/path/to/python",
+  "platform": "win32",
+  "env": {
+    "KITE_PROJECT":      {"value": "/path/to/kite", "description": "Kite 框架源代码根目录"},
+    "KITE_VERSION":      {"value": "1.5.0",          "description": "当前运行的 Kite 版本号"},
+    "KITE_ENV":          {"value": "development",    "description": "运行环境（development / production）"},
+    "KITE_WORKSPACE":    {"value": "~/.kite/workspace", "description": "所有实例工作区的根目录"},
+    "KITE_DATA":         {"value": "~/.kite/data",   "description": "全局持久化数据目录"},
+    "KITE_INSTANCE_DIR": {"value": "~/.kite/workspace/Kite", "description": "本次实例的工作区目录"},
+    "KITE_INSTANCE":     {"value": "12345",          "description": "本次 Launcher 进程的 PID"}
+  }
+}
+```
+
+## 文档目录
+
+Kite 框架的设计文档位于源代码根目录的 `docs/` 下，内容非常丰富。两个核心索引文件：
+
+| 文件 | 用途 |
+|------|------|
+| `docs/INDEX.md` | 三层索引：Layer 1 地图 + Layer 2 交叉索引 + Layer 3 详细摘要，快速定位任意主题 |
+| `docs/KITE_DOCS_GUIDE.md` | 按主题分类的查阅指南，含精确的文件名和行区间引用 |
+
+**使用方式：**
+1. 先读 `docs/KITE_DOCS_GUIDE.md`，按主题找到对应文档和行区间
+2. 如果不确定主题，先读 `docs/INDEX.md` 定位文档名
+3. 再直接跳到目标文档的对应行区间，不要全文通读
+
+## 代码为最终事实
+
+- references/ 和 docs/ 是指导方针，Kite 实际代码是最终事实
+- 生成/审查/适配时，先读 references 获取标准模式，再读实际模块代码确认最新实现
+- 如果 references 描述与实际代码不一致，以实际代码为准，并提示用户 references 需要更新
+
+## 工作流
+
+### Step 0: 选择操作
+
+用 AskUserQuestion 询问：
+
+```
+你要做什么？
+[1] 生成新模块 — 从零创建标准 Kite 模块
+[2] 适配现有项目 — 让已有工程接入 Kite 框架
+[3] 审查现有模块 — 检查模块的规范性和完整性
+[4] 查看说明 — 了解 Kite 运行机制和核心概念
+```
+
+根据选择进入对应主线。
+
+---
+
+## 主线 1: 生成新模块
+
+### Step 1.1: 收集基础信息
+
+依次用 AskUserQuestion 询问：
+
+1. **模块名称**（必填，英文 + 下划线/连字符，如 `my_service`）
+2. **一句话描述**（用于 module.md 文档部分）
+3. **模块类型**：`service` / `channel` / `agent`
+4. **运行时**：`python` / `node` / `go（暂未实现，选择后提示）`
+5. **部署模式**：`本地模块`（直连 Kernel）/ `远程模块`（经 Gateway）
+6. **启动状态**：`enabled`（随 Kite 启动）/ `manual`（手动启动）/ `disabled`
+
+### Step 1.2: 选择特性
+
+用 AskUserQuestion 多选：
+
+```
+勾选需要的特性（可多选）：
+
+基础能力：
+  [ ] HTTP 服务 — 提供 REST API（FastAPI + uvicorn）
+  [ ] 优雅关闭 — 完整的 shutdown 序列（推荐勾选）
+  [ ] 看门狗监控 — Watchdog 心跳监控
+
+连接与实例：
+  [ ] 多连接 — max_connections > 1，支持连接槽管理
+  [ ] 多实例 — max_instances > 1，支持多进程
+  [ ] 弹性伸缩 — 根据负载自动扩缩连接/实例
+
+数据与配置：
+  [ ] 配置文件 — config.json5 业务配置
+  [ ] 自定义事件 — 发布自定义事件
+  [ ] 事件订阅 — 订阅其他模块事件
+
+前端：
+  [ ] 前端页面 — 在 kite_console 注册 UI 页面
+```
+
+### Step 1.3: 确认摘要
+
+展示所有选项的摘要表格，让用户确认后再生成。
+
+### Step 1.4: 生成代码
+
+根据收集的信息，参考以下文件生成代码：
+
+- **module.md** — 参考 `references/module-md-spec.md` 生成 YAML frontmatter
+- **entry.py / entry.js** — 参考 `templates/{runtime}/entry.*` 模板，根据特性组合填充
+- **server.py / server.js** — 参考 `templates/{runtime}/server.*` 或 `server_http.*`，根据特性组合填充
+- **config.json5** — 如果勾选了配置文件特性
+- **`__init__.py`** — Python 模块必须
+
+生成位置：`extensions/{type}s/{name}/`（type 为 service → services，channel → channels，agent → agents）
+
+**生成后必须提示用户**：
+- 模块已生成到 `extensions/{type}s/{name}/`
+- 需要重启 Kite 才能加载新模块
+- 如果勾选了前端页面，需要在 kite_console 中注册（参考 `references/test-center-integration.md`）
+
+---
+
+## 主线 2: 适配现有项目
+
+### Step 2.1: 收集信息
+
+1. **项目目录路径**（必填）
+2. **模块名称**（默认：目录末级名称）
+3. **模块类型**：`service` / `channel` / `agent`
+4. **运行时**（自动检测：有 `package.json` → node，有 `*.py` → python，否则询问）
+5. **部署模式**：`本地` / `远程`
+6. **勾选特性**（同主线 1 的 Step 1.2）
+
+### Step 2.2: 分析项目
+
+读取项目代码结构，识别：
+- 入口文件（main.py / index.js / app.py 等）
+- 现有 HTTP 服务（FastAPI / Express / Flask 等）
+- 现有配置文件
+- 依赖关系
+
+### Step 2.3: 生成适配方案
+
+列出：
+- 要新增的文件（module.md、entry.py 等）
+- 要修改的文件（接入 stdin 协议、WebSocket 连接等）
+- 每个修改点的说明
+
+**必须让用户确认方案后再执行。**
+
+### Step 2.4: 执行适配
+
+按方案逐步执行，每步完成后报告进度。
+
+适配时参考：
+- `references/stdin-protocol.md` — stdin boot_info 协议
+- `references/ws-lifecycle.md` — WebSocket 连接生命周期
+- `references/rpc-patterns.md` — RPC 标准模式
+- `references/event-patterns.md` — 事件标准模式
+- `references/shutdown-sequence.md` — 优雅关闭序列
+- `checklists/feature-checklist.md` — 特性实现检查清单
+
+---
+
+## 主线 3: 审查现有模块
+
+### Step 3.1: 选择模块
+
+列出 `extensions/` 下所有模块，让用户选择。或让用户指定路径。
+
+### Step 3.2: 读取模块信息
+
+读取 module.md，识别声明的特性和配置。
+
+### Step 3.3: 逐项审查
+
+参考 `checklists/feature-checklist.md`，逐项检查：
+
+1. **module.md 规范性** — 字段完整性、值合法性
+2. **entry.py 标准模式** — stdin 协议、日志设置、异常处理
+3. **server.py 标准模式** — WebSocket 连接、RPC 处理、事件处理
+4. **特性实现** — 按声明的特性逐项检查实现是否正确
+5. **常见坑检查** — 参考 `references/` 中的注意事项
+6. **启动时间优化** — import 顺序、_do_init 并行化、业务初始化异步化
+7. **退出时间优化** — ack 时机、清理并行化、超时保护
+
+### Step 3.4: 输出审查报告
+
+```
+| 检查项 | 状态 | 说明 |
+|--------|------|------|
+| module.md 字段完整 | ✅ | — |
+| stdin 协议正确 | ✅ | — |
+| RPC 死锁防范 | ⚠️ | _handle_rpc_request 使用了 await 而非 create_task |
+| 优雅关闭序列 | ❌ | 缺少 shutdown.ack 步骤 |
+| ... | ... | ... |
+```
+
+---
+
+## 主线 4: 查看说明
+
+### Step 4.1: 选择主题
+
+```
+你想了解什么？
+[1] Kite 整体架构概览
+[2] 模块生命周期（启动 → 注册 → 运行 → 关闭）
+[3] 通信机制（WebSocket JSON-RPC 2.0）
+[4] 事件系统（订阅 / 发布）
+[5] 注册中心机制
+[6] 多连接与多实例
+[7] 远程模块与 Gateway
+[8] 前端页面接入与测试中心
+[9] 特性清单详解
+[10] 启动与退出时间优化
+```
+
+### Step 4.2: 输出说明
+
+从 `references/` 目录下对应文件中提取关键信息，精简输出。不要大段复制，讲清机制和要点即可。
+
+---
+
+## 参考文件索引
+
+生成和审查时，必须读取以下参考文件以确保实现正确：
+
+| 文件 | 用途 |
+|------|------|
+| `references/module-md-spec.md` | module.md 完整字段规范 |
+| `references/stdin-protocol.md` | stdin boot_info 协议 |
+| `references/ws-lifecycle.md` | WebSocket 连接生命周期 |
+| `references/rpc-patterns.md` | RPC 调用/响应标准模式 |
+| `references/event-patterns.md` | 事件订阅/发布标准模式 |
+| `references/shutdown-sequence.md` | 优雅关闭完整序列 |
+| `references/multi-connection.md` | 多连接槽管理 |
+| `references/http-service.md` | HTTP 服务接入模式 |
+| `references/test-center-integration.md` | 测试中心接入 |
+| `references/health-check.md` | 健康检查机制（两层：ping/pong + health RPC） |
+| `checklists/feature-checklist.md` | 特性检查清单 |
+| `templates/python/entry.py` | Python 入口模板 |
+| `templates/python/server.py` | Python WebSocket 服务端模板 |
+| `templates/python/server_http.py` | Python HTTP 服务端模板 |
+| `templates/python/module.md` | Python module.md 模板 |
+| `templates/node/entry.js` | Node.js 入口模板 |
+| `templates/node/server.js` | Node.js WebSocket 服务端模板 |
+| `templates/node/server_http.js` | Node.js HTTP 服务端模板 |
+| `templates/node/module.md` | Node.js module.md 模板 |

package/.claude/skills/kite/templates/go/README.md

@@ -0,0 +1,20 @@
+# Go 模板
+
+Go 运行时的代码模板暂未实现。选择 Go 运行时后，skill 会提示该功能尚在开发中。
+
+## 计划支持
+
+- `entry.go` — Go 入口，读取 stdin boot_info，连接 Kernel WebSocket
+- `server.go` — Go WebSocket 客户端，JSON-RPC 2.0 通信
+- `module.md` — runtime 设为 binary，entry 设为编译后的可执行文件名
+
+## 编译方式
+
+Go 模块编译后以 binary 方式运行：
+
+```yaml
+runtime: binary
+entry: my_module      # 编译后的可执行文件
+```
+
+Launcher 直接执行该二进制文件，通过 stdin 传入 boot_info。

package/.claude/skills/kite/templates/node/entry.js

@@ -0,0 +1,134 @@
+/**
+ * {{DISPLAY_NAME}} — Node.js entry point.
+ * Reads boot_info from stdin, connects to Kernel via WebSocket JSON-RPC 2.0.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml'); // npm install js-yaml
+const { {{SERVER_CLASS}} } = require('./server');
+
+// ── Module configuration ──
+
+function loadModuleConfig() {
+  const thisDir = __dirname;
+  const moduleMd = path.join(thisDir, 'module.md');
+
+  if (!fs.existsSync(moduleMd)) {
+    console.error(`[ERROR] module.md not found: ${moduleMd}`);
+    process.exit(1);
+  }
+
+  const text = fs.readFileSync(moduleMd, 'utf-8');
+  const match = text.match(/^---\s*\n([\s\S]*?)\n---/);
+  if (!match) {
+    console.error('[ERROR] Missing YAML frontmatter in module.md');
+    process.exit(1);
+  }
+
+  const fm = yaml.load(match[1]);
+  if (!fm || !fm.name) {
+    console.error('[ERROR] Missing "name" in module.md');
+    process.exit(1);
+  }
+
+  const name = String(fm.name).trim();
+  if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
+    console.error(`[ERROR] Invalid module name: ${name}`);
+    process.exit(1);
+  }
+
+  return {
+    name,
+    preferredPort: parseInt(fm.preferred_port || '0', 10) || 0,
+    advertiseIp: fm.advertise_ip || '0.0.0.0',
+    maxConnections: Math.max(1, Math.min(10, parseInt(fm.max_connections || '1', 10) || 1)),
+  };
+}
+
+const moduleConfig = loadModuleConfig();
+const MODULE_NAME = moduleConfig.name;
+
+// ── Timestamped logging ──
+
+const startTs = Date.now();
+let lastTs = Date.now();
+
+const originalLog = console.log.bind(console);
+console.log = function (...args) {
+  const now = Date.now();
+  const elapsed = now - startTs;
+  const delta = now - lastTs;
+  lastTs = now;
+
+  const elapsedStr = elapsed < 1000 ? `${elapsed}ms` : `${(elapsed / 1000).toFixed(1)}s`;
+  const deltaStr = delta < 1 ? '' : delta < 1000 ? `+${delta}ms` : `+${(delta / 1000).toFixed(1)}s`;
+  const ts = new Date().toISOString().slice(11, 23);
+
+  originalLog(`[${elapsedStr.padStart(6)}] ${ts} ${deltaStr.padStart(8)}`, ...args);
+};
+
+// ── Read boot_info from stdin ──
+
+async function readBootInfo() {
+  return new Promise((resolve, reject) => {
+    const readline = require('readline');
+    const rl = readline.createInterface({ input: process.stdin });
+
+    const timer = setTimeout(() => {
+      rl.close();
+      reject(new Error('boot_info read timeout'));
+    }, 10000);
+
+    rl.once('line', (line) => {
+      clearTimeout(timer);
+      rl.close();
+      try {
+        const msg = JSON.parse(line.trim());
+        if (msg.error) {
+          reject(new Error(`Launcher error: ${msg.error}`));
+          return;
+        }
+        if (!msg.token) {
+          reject(new Error('No token in boot_info'));
+          return;
+        }
+        resolve(msg);
+      } catch (e) {
+        reject(new Error(`boot_info parse error: ${e.message}`));
+      }
+    });
+  });
+}
+
+// ── Main ──
+
+async function main() {
+  const kernelPort = process.env.KITE_KERNEL_PORT;
+  if (!kernelPort) {
+    console.error(`[${MODULE_NAME}] ERROR: KITE_KERNEL_PORT not set`);
+    process.exit(1);
+  }
+
+  try {
+    const bootInfo = await readBootInfo();
+    console.log(`[${MODULE_NAME}] Local mode: port=${kernelPort}`);
+
+    const server = new {{SERVER_CLASS}}({
+      token: bootInfo.token,
+      kernelPort: parseInt(kernelPort, 10),
+      maxConnections: moduleConfig.maxConnections,
+      maxInstances: bootInfo.max_instances || 1,
+      instanceElastic: bootInfo.instance_elastic || false,
+    });
+
+    await server.run();
+  } catch (e) {
+    console.error(`[${MODULE_NAME}] Fatal: ${e.message}`);
+    process.exit(1);
+  }
+}
+
+main();

package/.claude/skills/kite/templates/node/module.md

@@ -0,0 +1,16 @@
+---
+name: {{MODULE_NAME}}
+display_name: {{DISPLAY_NAME}}
+version: '1.0'
+type: {{MODULE_TYPE}}
+state: {{STATE}}
+runtime: node
+entry: entry.js
+# preferred_port: 0
+# advertise_ip: 127.0.0.1
+max_connections: {{MAX_CONNECTIONS}}
+monitor: true
+---
+# {{DISPLAY_NAME}}
+
+{{DESCRIPTION}}