@agentunion/kite 1.4.0 → 1.6.0

package/docs/Polyglot/350/277/220/350/241/214/346/227/266/344/270/216Clawdbot/345/205/274/345/256/271/346/200/247/350/256/276/350/256/241.md

@@ -0,0 +1,321 @@
+# Polyglot 运行时与 Clawdbot 兼容性设计
+
+## 1. 背景
+
+Kite 框架的目标是面向 agent 互联网的运行时，核心价值是统一身份层。Clawdbot 是一个成熟的多 channel 个人助手平台（TypeScript/Node.js），拥有丰富的 channel 和 skill 生态（Telegram、WhatsApp、Discord、Slack、Signal 等 10+ channel，50+ skill）。
+
+目标：让 Kite 框架兼容 clawdbot 的 channel 和 skill 插件，不重复造轮子。
+
+## 2. 核心洞察：进程隔离天然支持多语言
+
+Kite 的架构是每个模块一个独立进程，模块间通过 Event Hub（WebSocket + JSON）通信。这个设计天然是语言无关的——只要模块能连 WebSocket、收发 JSON，框架不关心它用什么语言实现。
+
+这意味着：不需要"桥接"clawdbot 的生态，而是让 clawdbot 的模块作为原生 Kite 模块运行，只不过碰巧是用 Node.js 写的。
+
+## 3. Launcher 多运行时支持
+
+### 改动点
+
+在 `module.md` 中增加 `runtime` 字段：
+
+```markdown
+---
+name: telegram-channel
+type: channel
+state: enabled
+runtime: node
+entry: entry.js
+---
+```
+
+`runtime` 可选值：
+
+| runtime | 启动命令 | 适用场景 |
+|---------|---------|---------|
+| `python`（默认） | `python entry.py --registry-port {port}` | Kite 原生模块 |
+| `node` | `node entry.js --registry-port {port}` | clawdbot channel/skill |
+| `binary` | `./entry --registry-port {port}` | Go/Rust 高性能模块 |
+
+Launcher 的改动极小：读取 `runtime` 字段，选择对应的解释器启动子进程。其余逻辑（进程监控、重启策略、日志收集）完全不变，因为这些都是 OS 级别的操作，跟语言无关。
+
+### 模块协议不变
+
+不管什么语言，模块启动后必须完成三件事：
+
+1. 连接 Registry，注册自己（名称、类型、能力、地址）
+2. 连接 Event Hub，订阅事件、发布事件
+3. 响应健康检查（`/health` 端点）
+
+## 4. Module SDK
+
+提供两个语言版本的轻量 SDK，封装模块协议：
+
+- **Python**: `kite-module-sdk`（pip 包）
+- **Node.js**: `@kite/module-sdk`（npm 包）
+
+SDK 封装内容：
+- Registry 连接与注册
+- Event Hub WebSocket 连接、订阅、发布
+- 事件 outbox 持久化与重放
+- 健康检查端点
+- `--registry-port` 参数解析
+
+模块开发者只需关注业务逻辑，不用手写 WebSocket 连接。
+
+## 5. Clawdbot Channel 接入方案
+
+### 架构：统一 Bridge 模块
+
+不需要每个 clawdbot channel 对应一个 Kite 模块。用一个通用的 `clawdbot-bridge` 模块承载所有 clawdbot channel，内部做多路复用：
+
+```
+Kite Launcher
+├── Registry              (Python)
+├── Event Hub             (Python)
+├── Kernel                (Python)
+├── Agent 模块             (Python)
+├── clawdbot-bridge       (Node.js, 一个进程承载所有 clawdbot channel + skill)
+└── 其他原生模块            (Python / Node.js / binary)
+```
+
+### Bridge 模块结构
+
+```
+extensions/channels/clawdbot-bridge/
+├── entry.js              ← Kite 模块入口（使用 @kite/module-sdk）
+├── module.md             ← runtime: node, type: channel
+├── package.json          ← 依赖各 clawdbot channel 包（npm install 即用）
+├── adapter.js            ← 通用适配层：加载 channel plugin → 转换事件
+└── config.json           ← 启用哪些 channel 及各自配置
+```
+
+### 工作方式
+
+1. 启动时扫描 `package.json` 中已安装的 clawdbot channel plugin
+2. 根据 `config.json` 逐个初始化启用的 channel（Telegram bot、Discord client 等）
+3. 向 Registry 注册，声明提供的所有 channel 能力：
+
+```json
+{
+  "name": "clawdbot-bridge",
+  "type": "channel",
+  "channels": ["telegram", "discord", "whatsapp", "slack", "signal"]
+}
+```
+
+4. 任何 channel 收到消息时，发布带 channel 标识的 Kite 事件：
+
+```json
+{
+  "event": "channel.message.received",
+  "source": "clawdbot-bridge",
+  "data": {
+    "channel": "telegram",
+    "sender": "...",
+    "content": "..."
+  }
+}
+```
+
+5. 收到 Kite 侧的发送指令时，根据 `data.channel` 路由到对应的 clawdbot outbound adapter
+
+### 用户添加新 channel
+
+```bash
+cd extensions/channels/clawdbot-bridge
+npm install @clawdbot/channel-line
+# 在 config.json 中启用 line channel
+# 重启模块即可
+```
+
+不需要新建 Kite 模块，不需要写代码。
+
+### 故障隔离策略
+
+默认所有 channel 在同一进程（与 clawdbot 原生行为一致，实践中够用）。如果某个 channel 不稳定需要隔离，可以单独拆出来作为独立 Kite 模块运行——两种方式并存，按需选择。
+
+### 需要解耦的 clawdbot 依赖
+
+clawdbot 的 channel 原本依赖 Gateway 的以下能力，由 adapter 层映射到 Kite 对应机制：
+
+| clawdbot Gateway 依赖 | Kite 替代方案 |
+|----------------------|-------------|
+| Session 管理 | Kernel 的会话管理 |
+| Config 系统 | Registry 的配置分发 |
+| Security/Pairing | Kernel 的身份管理 + 权限体系 |
+| Tool 注册 | Registry 的工具注册 |
+
+clawdbot 的 channel 核心代码（协议对接、消息收发）不需要修改，adapter 层负责协议翻译。
+
+## 6. Clawdbot Skill 接入方案
+
+### Clawdbot Skill 系统分析
+
+clawdbot 的 skill/tool 系统比 channel 复杂得多。tool 不是全量加载的，而是**懒加载 + 上下文感知**：
+
+- tool 通过 factory 函数注册，每次实例化时传入当前 context
+- 有 `optional` 标记的 tool 必须在 allowlist 里才会加载
+- 按 session 类型过滤（main / group / subagent）
+- 按 channel 过滤（channel-docked tools 只在对应 channel 生效）
+- sandbox 模式下 tool 被替换成受限版本
+
+clawdbot 的权限管理是四层策略叠加：
+
+| 层级 | 配置路径 |
+|------|---------|
+| Global | `config.tools.allow/deny` |
+| Provider 级 | `config.tools.byProvider[provider].allow/deny` |
+| Agent 级 | `config.agents[agentId].tools.allow/deny` |
+| Agent+Provider 级 | 嵌套组合 |
+
+还支持 tool group（`group:fs`、`group:web` 等）、profile 预设（`minimal`/`coding`/`messaging`/`full`）、subagent 限制、sandbox 模式。
+
+tool factory 依赖的 context：
+
+```typescript
+type ClawdbotPluginToolContext = {
+  config,            // clawdbot 完整配置对象
+  workspaceDir,      // 工作区路径
+  agentDir,          // agent 目录
+  agentId,           // agent ID
+  sessionKey,        // session 标识（含 channel、group 信息）
+  messageChannel,    // 当前消息 channel
+  agentAccountId,    // agent 账号
+  sandboxed,         // 是否沙箱模式
+}
+```
+
+### 兼容策略：两层方案
+
+完整模拟 clawdbot 的 policy pipeline 成本高且不必要——Kite 有自己的权限体系。采用分层兼容：
+
+**第一层（快速可用）**：bridge 直接加载 skill，跳过 clawdbot 的 policy 层，用 Kite 自己的四层权限体系管控。大部分纯 API 类 skill（github、notion、obsidian 等）factory 对 context 依赖很轻，这样就够了。
+
+**第二层（深度兼容）**：对依赖 context 的 skill（channel-docked tools、sandbox-aware tools），在 bridge 里实现 context 转换层，把 Kite 的 session/identity 信息映射成 `ClawdbotPluginToolContext`。
+
+### 架构：独立 Service 模块
+
+```
+extensions/services/clawdbot-skills/
+├── entry.js              ← Kite 模块入口（使用 @kite/module-sdk）
+├── module.md             ← runtime: node, type: service
+├── loader.js             ← 加载 skill，提取 tool 定义
+├── context-adapter.js    ← Kite context → clawdbot context 转换
+├── package.json          ← npm install 需要的 clawdbot skill
+└── config.json           ← 启用哪些 skill + 兼容层级配置
+```
+
+### 工作流程
+
+1. **启动时**：
+   - 扫描已安装的 clawdbot skill 包
+   - 调用每个 skill 的 `setup()` 拿到 tool 列表
+   - 第一层 skill：直接提取 tool 定义，忽略 clawdbot policy
+   - 第二层 skill：保留 factory，运行时按 context 实例化
+   - 启动 HTTP server，为每个 tool 暴露端点
+   - 向 Registry 注册所有 tool 的定义（名称、参数 schema、地址）
+
+2. **Agent 调用 tool 时**：
+   ```
+   Agent LLM 输出 tool_call
+     → Agent 查 Registry 发现 tool 地址指向 clawdbot-skills
+     → HTTP POST /tools/{name} {args, context}
+     → clawdbot-skills 收到请求
+     → 第一层：直接调用 handler
+     → 第二层：context-adapter 转换 → factory 实例化 → 调用 handler
+     → 返回结果
+   ```
+
+3. **对 Agent 透明**：都是通过 Registry 发现、HTTP 调用，与 Python 原生 tool 无区别
+
+### Context 转换（第二层）
+
+Kite 传入的 context：
+```json
+{
+  "workspace": "/path/to/workspace",
+  "agent_identity": "小助手",
+  "peer_identity": "王老板",
+  "channel": "telegram",
+  "session": {...}
+}
+```
+
+context-adapter.js 映射为 clawdbot 期望的格式：
+```javascript
+function adaptContext(kiteContext) {
+  return {
+    config: buildClawdbotConfig(kiteContext),  // 从 Kite config 构造
+    workspaceDir: kiteContext.workspace,
+    agentId: kiteContext.agent_identity,
+    sessionKey: buildSessionKey(kiteContext),   // 从 channel + session 构造
+    messageChannel: kiteContext.channel,
+    sandboxed: false,  // Kite 有自己的权限体系，不走 sandbox
+  };
+}
+```
+
+大部分 skill 的 factory 只用到 `config`（读 API token）和 `workspaceDir`，转换成本很低。
+
+### 用户添加新 skill
+
+```bash
+cd extensions/services/clawdbot-skills
+npm install @clawdbot/skill-notion
+# 在 config.json 中启用 notion skill
+# 重启模块即可
+```
+
+### Skill 兼容性
+
+| Skill 类型 | 依赖 | 兼容层级 | 说明 |
+|-----------|------|---------|------|
+| API 类（github、notion、obsidian） | API token | 第一层 | factory 只读 config 取 token，直接可用 |
+| 文件操作类（read、write、edit） | workspaceDir | 第一层 | 映射 Kite workspace 路径即可 |
+| Channel 关联（discord/slack actions） | channel 实例 | 第二层 | 需通过 clawdbot-bridge 共享 channel client |
+| Session 感知（sessions_send 等） | sessionKey | 第二层 | 需构造 clawdbot 格式的 sessionKey |
+| Sandbox 感知（sandboxed read/exec） | sandbox context | 不兼容 | Kite 用自己的权限体系替代，无需 sandbox |
+| 本地环境（canvas、browser） | companion app | 第二层+ | 需额外适配或跳过 |
+| 平台特定（apple-notes 等） | macOS 环境 | 平台限制 | 按平台决定 |
+
+实际操作：先启用第一层 skill（覆盖大部分常用 skill），按需逐个适配第二层。
+
+### 权限控制：两套体系的关系
+
+clawdbot 有自己的四层 policy（global → provider → agent → agent+provider），Kite 也有四层权限（全局 → channel → agent → peer）。两套体系不需要互相模拟。
+
+策略：**Kite 的权限体系作为唯一权限源**，clawdbot 的 policy 层在 bridge 中被跳过。
+
+理由：
+- clawdbot 的 policy 是围绕"单 owner 个人助手"设计的，核心是 allow/deny list
+- Kite 的权限体系是围绕"多身份多 agent"设计的，更通用
+- 两套并存会导致权限判断不一致，调试困难
+- Skill bridge 注册 tool 到 Registry 后，Kite 的开关过滤（deny wins）自动生效
+
+具体做法：
+- bridge 加载 skill 时不调用 `resolveEffectiveToolPolicy()`，直接提取 tool 定义
+- tool 的 allow/deny 由 Kite 的 `switches.json`（多级）控制
+- tool 调用时的权限检查由 Kite 的 `check_permission()` 机制执行
+- clawdbot 的 tool group 概念（`group:fs` 等）可以映射为 Kite 的 switches 批量配置
+
+## 7. 身份模型映射
+
+Kite 的身份模型是 clawdbot 的超集，向下兼容：
+
+| clawdbot 概念 | Kite 映射 |
+|--------------|----------|
+| owner（config 中定义） | `role: owner` 的身份 |
+| allowlist（per channel） | channel 级 permission 配置 |
+| pairing（未知发送者） | 身份自动创建（status: unidentified）+ 待审批 |
+| main session | agent-peer 会话 |
+| group session | 多方会话（扩展） |
+
+方向：让 clawdbot 的身份模型适配 Kite，而不是反过来。Kite 的身份层是核心价值，不应妥协。
+
+## 8. 收益
+
+- **channel 复用**：直接使用 clawdbot 成熟的 Telegram、WhatsApp、Discord 等实现，省去大量协议对接工作
+- **skill 复用**：50+ 现成 skill 可按需接入
+- **生态开放**：框架不绑定语言，未来可接入任何语言的模块（Go、Rust 等）
+- **社区友好**：降低贡献门槛，开发者用熟悉的语言写模块即可
+- **渐进迁移**：可以先用 adapter 快速跑起来，后续按需用 Python 重写高频模块