@zhin.js/adapter-kook 1.0.84 → 1.1.0

package/README.md

@@ -1,412 +1,113 @@
 # @zhin.js/adapter-kook
 
-Zhin.js KOOK（开黑啦）适配器，基于 KOOK 官方 API 开发，支持频道和私聊消息。
+Zhin.js KOOK（开黑啦）适配器（Plugin Runtime），默认通过 **WebSocket Gateway**（`kook-client`）收发消息；可选 **Webhook** 模式经 `httpHostToken` 接收平台 POST 推送。
 
-## 功能特性
+## 功能
 
-- 🗣️ 支持 KOOK 频道和私聊消息处理
-- 📨 消息发送和接收处理
-- 🔄 消息格式转换和适配
-- 📁 自动数据目录管理
-- ⚡ 基于 WebSocket 的实时通信
-- 🎯 支持 Webhook 和 WebSocket 双模式
-- 📝 支持 Markdown 消息格式
+- WebSocket Gateway 入站（默认；无需公网 HTTPS / host）
+- Webhook 入站（`connection: webhook` + `httpHostToken` + `verify_token`）
+- 解析频道与私聊文本消息
+- 出站 `send({ conversation, payload })` → KOOK KMarkdown（`kind: 'channel' | 'private'`）
+- canonical `markdown` 段原生保留为 [KMarkdown](https://developer.kookapp.cn/doc/kmarkdown-desc)
+- 约定式 `defineAdapter` / `definePlugin`（无需 `usePlugin`）
 
 ## 安装
 
 ```bash
-pnpm add @zhin.js/adapter-kook kook-client
+pnpm add @zhin.js/adapter-kook
 ```
 
-## 配置
+## Plugin Runtime
 
-### WebSocket 模式（推荐）
+- `@zhin.js/adapter` — 约定式 `adapters/kook.ts`（`defineAdapter`）
+- `@zhin.js/core` — `Endpoint.emit(...)` 入站、`outboundMessageToken` 出站
+- `@zhin.js/host-http` — Webhook 模式 POST 路由（WebSocket 不需要）
+- `zhin.js` — `plugin.ts`（`definePlugin`）
+- 配置经插件 `schema.json` 落到 `plugins.<instanceKey>`
+- **WebSocket 路径无需** `@zhin.js/host-http` / `@zhin.js/host-router`
 
-```typescript
-// zhin.config.ts
-import { defineConfig } from 'zhin.js'
+入站：`gateway.receive({ conversation, message, content, sender, metadata })`（ConversationRef：`channel` 频道消息带 guild `parent`，`private` 私聊）  
+出站：`send({ conversation, payload })` → `sendChannelMsg` / `sendPrivateMsg`
 
-export default defineConfig({
-  bots: [
-    {
-      context: 'kook',
-      name: 'my-kook-bot',
-      token: process.env.KOOK_TOKEN,        // KOOK 机器人 Token（必需）
-      mode: 'websocket',                     // WebSocket 模式
-      data_dir: './data'                     // 数据目录（可选）
-    }
-  ],
-  plugins: [
-    'http',
-    'adapter-kook'
-  ]
-})
-```
-
-### Webhook 模式
-
-```typescript
-export default defineConfig({
-  bots: [
-    {
-      context: 'kook',
-      name: 'my-kook-bot',
-      token: process.env.KOOK_TOKEN,         // KOOK 机器人 Token（必需）
-      mode: 'webhook',                        // Webhook 模式
-      endpoint: process.env.KOOK_ENDPOINT,   // Webhook 端点（必需）
-      verifyToken: process.env.KOOK_VERIFY,  // 验证令牌（可选）
-      encryptKey: process.env.KOOK_ENCRYPT,  // 加密密钥（可选）
-      data_dir: './data'
-    }
-  ],
-  plugins: [
-    'http',
-    'adapter-kook'
-  ]
-})
-```
-
-## 获取配置信息
-
-### 1. 创建 KOOK 机器人
-
-1. 访问 [KOOK 开发者平台](https://developer.kookapp.cn/)
-2. 登录并创建应用
-3. 在应用设置中获取 **Bot Token**
-
-### 2. 配置机器人
-
-在应用设置中：
-- 获取 **Bot Token**（必需）
-- 配置 Webhook 地址（Webhook 模式）
-- 设置验证令牌和加密密钥（可选，增强安全性）
-
-### 3. 邀请机器人
-
-- 在应用详情页获取邀请链接
-- 将机器人邀请到需要的服务器
-- 确保机器人有相应的权限
+## 前置条件
 
-## 使用示例
+| 要求 | 说明 |
+|------|------|
+| **Bot Token** | 在 [KOOK 开发者平台](https://developer.kookapp.cn/) 创建应用并获取 |
+| **邀请入服** | 将机器人邀请到目标服务器，并授予查看频道、发送消息等权限 |
+| **WebSocket（默认）** | `kook-client` 正向连接；无需公网 URL |
+| **Webhook** | 需公网 HTTPS + Host `httpHostToken`；与 WebSocket 互斥 |
+| **host-http** | 仅 Webhook 模式需要 |
 
-### 基础消息处理
+必填字段（`endpoints[i]`）：`name`、`token`。
 
-```typescript
-import { usePlugin, MessageCommand } from 'zhin.js'
+## 最小配置
 
-const { addCommand } = usePlugin()
-
-addCommand(new MessageCommand('hello <name:text>')
-  .action(async (message, result) => {
-    return `你好，${result.params.name}！`
-  })
-)
-```
-
-### 频道消息
-
-```typescript
-import { onMessage } from 'zhin.js'
-
-onMessage(async (message) => {
-  if (message.$channel.type === 'channel') {
-    console.log(`频道消息：${message.$raw}`)
-  }
-})
+```yaml
+# zhin.config.yml（Plugin Runtime）
+plugins:
+  kook:
+    # connection: websocket   # 默认
+    endpoints:
+      - name: my-kook-bot
+        token: ${KOOK_TOKEN}
 ```
 
-### 私聊消息
+根插件 `zhin.plugins`（或项目图）需引用 `@zhin.js/adapter-kook`（`instanceKey: kook`）。
 
-```typescript
-import { onPrivateMessage } from 'zhin.js'
+## 环境变量
 
-onPrivateMessage(async (message) => {
-  await message.$reply('收到你的私信了！')
-})
-```
+| 变量 | 说明 |
+|------|------|
+| `KOOK_TOKEN` / `KOOK_BOT_TOKEN` | Bot Token |
+| `KOOK_BOT_NAME` | 可选，默认 endpoint 名 |
+| `KOOK_VERIFY_TOKEN` | Webhook 模式 verify token |
+| `KOOK_ENCRYPT_KEY` | 可选，Webhook 消息加密密钥 |
+| `KOOK_WEBHOOK_PATH` | 可选，默认 `/kook/webhook` |
 
-### Markdown 消息
+## Webhook
 
-```typescript
-addCommand(new MessageCommand('md')
-  .action(async (message) => {
-    return [
-      {
-        type: 'text',
-        data: {
-          text: '**这是粗体** *这是斜体*\n[链接](https://kookapp.cn)'
-        }
-      }
-    ]
-  })
-)
-```
-### Card 消息 (卡片消息)
+在 KOOK 开发者后台选择 **WebHook** 连接模式，Callback URL 指向 Host 暴露的公网地址（建议在 URL 加 `?compress=0` 便于调试）。
 
-```typescript
-addCommand(new MessageCommand('card')
-    .action(async (message) => {
-        logger.info(message);
-        if (message.$adapter !== 'kook') {
-            return "暂未适配平台！";
-        } else {
-            const cardMessage = [{
-                type: 'card',
-                theme: "secondary",
-                size: "lg",
-                modules: [
-                    msgMod.section(
-                        element.markdown("(font) 卡片信息(font)[purple](font) Card信息(font)[warning]")
-                    ),
-                    msgMod.container(
-                        [
-                            element.image('https://api.owii.cn/gif/cache/2026-01-03_07-17-15.gif')
-                        ]
-                    )
-                ]
-            }];
-            return cardMessage;
-        }
-        return `当前平台：${message.$adapter}`;
-    })
-)
+```yaml
+plugins:
+  kook:
+    connection: webhook
+    webhookPath: /kook/webhook
+    endpoints:
+      - name: my-kook-bot
+        token: ${KOOK_TOKEN}
+        verify_token: ${KOOK_VERIFY_TOKEN}
+        # encrypt_key: ${KOOK_ENCRYPT_KEY}   # 启用消息加密时必填
 ```
 
-## 消息类型支持
-
-### 接收消息类型
-
-- ✅ 文本消息
-- ✅ 图片消息
-- ✅ 视频消息
-- ✅ 文件消息
-- ✅ Markdown 消息
-- ✅ KMarkdown 消息
-- ✅ 卡片消息
-
-### 发送消息类型
-
-- ✅ 文本消息
-- ✅ 图片消息
-- ✅ 视频消息
-- ✅ 文件消息
-- ✅ Markdown 消息
-- ✅ 卡片消息
-
-## API 方法
-
-```typescript
-const bot = app.adapters.get('kook')?.bots.get('my-kook-bot')
-
-// 发送频道消息
-await bot.sendChannelMsg(channelId, '消息内容')
-
-// 发送私聊消息
-await bot.sendPrivateMsg(userId, '消息内容')
-
-// 撤回消息
-await bot.$recallMessage(messageId)
-```
-
-## 🔧 频道管理工具（AI 可调用）
-
-适配器自动注册了一系列频道管理工具，这些工具可以被 AI 调用，实现智能化的频道管理。
-
-### 权限要求
-
-| 工具 | 所需权限 | 说明 |
-|------|----------|------|
-| `kook_kick_user` | 管理员 | 踢出用户 |
-| `kook_ban_user` | 管理员 | 将用户加入黑名单 |
-| `kook_unban_user` | 管理员 | 解除用户封禁 |
-| `kook_grant_role` | 管理员 | 授予用户角色 |
-| `kook_revoke_role` | 管理员 | 撤销用户角色 |
-| `kook_set_nickname` | 管理员 | 设置用户昵称 |
-| `kook_list_roles` | 普通用户 | 查看角色列表 |
-| `kook_create_role` | 服务器主人 | 创建新角色 |
-| `kook_delete_role` | 服务器主人 | 删除角色 |
-| `kook_list_members` | 普通用户 | 查看成员列表 |
-
-### 使用示例
-
-#### 通过 AI 对话管理频道
-
-```
-用户（服务器主人）：把 @小明 踢出服务器
-AI：已将用户 小明 踢出服务器。
-
-用户（管理员）：把 @捣蛋鬼 禁言，他总是发广告
-AI：已将用户 捣蛋鬼 加入黑名单，原因：发布广告。
-
-用户：查看服务器角色列表
-AI：当前服务器有以下角色：
-1. 管理员 (ID: 123)
-2. 活跃成员 (ID: 456)
-3. 新人 (ID: 789)
-```
-
-#### 编程调用
-
-```typescript
-// 获取 KOOK Bot 实例
-const kookAdapter = app.adapters.get('kook')
-const bot = kookAdapter?.bots.get('my-kook-bot')
+Host 需注入 `httpHostToken`。Challenge（`type: 255`）会校验 `verify_token` 并回显 `challenge`；普通事件经 `gateway.receive` 入站，出站仍走 KOOK HTTP API。
 
-// 踢出用户
-await bot.kickUser(guildId, userId)
+## AI 工具（Skill）
 
-// 加入黑名单（封禁）
-await bot.addToBlacklist(guildId, userId, '违规发言', 7) // 删除7天内消息
+| 类别 | 路径 |
+|------|------|
+| Permit 词汇 | `agent/PERMITS.md` |
+| 平台工具 | `agent/tools/`（角色、黑名单等） |
+| 技能说明 | `agent/skills/kook.md` |
 
-// 解除封禁
-await bot.removeFromBlacklist(guildId, userId)
+## 平台权限（platform permit）
 
-// 授予角色
-await bot.grantRole(guildId, userId, roleId)
+platform permit checker 由 `plugin.ts` 的 generation 生命周期注册；CapabilityIngress 与 ToolSystem 统一经 Core `canAccessTool()` 消费工具的 platform permit 声明。
 
-// 撤销角色
-await bot.revokeRole(guildId, userId, roleId)
+## 迁移后出站能力变化
 
-// 设置昵称
-await bot.setNickname(guildId, userId, '新昵称')
+迁移到 Plugin Runtime 后，出站统一经 `outboundMessageToken` 渲染并由 endpoint 编码为 KMarkdown（`sendChannelMsg` / `sendPrivateMsg`）。canonical `markdown` 保留格式；图片、视频、音频和文件仅有远程 URL 时可表示为 KMarkdown 链接。卡片消息与附件上传仍未接入统一出站通道。
 
-// 获取角色列表
-const roles = await bot.getRoleList(guildId)
+## 故障排查
 
-// 创建角色
-const newRole = await bot.createRole(guildId, '新角色')
-
-// 删除角色
-await bot.deleteRole(guildId, roleId)
-
-// 获取成员列表
-const members = await bot.getGuildMembers(guildId)
-```
-
-### 发送者权限信息
-
-消息中的 `$sender` 现在包含 KOOK 特有的权限信息：
-
-```typescript
-interface KookSenderInfo {
-  id: string;
-  name: string;
-  permission?: KookPermission;  // 1=普通, 2=管理员, 4=服务器主人, 5=频道管理员
-  roles?: number[];             // 用户角色ID列表
-  isGuildOwner?: boolean;       // 是否为服务器主人
-  isAdmin?: boolean;            // 是否为管理员
-}
-```
-
-#### 在插件中检查权限
-
-```typescript
-onMessage(async (message) => {
-  const sender = message.$sender as KookSenderInfo;
-  
-  if (sender.isGuildOwner) {
-    console.log('这是服务器主人的消息');
-  }
-  
-  if (sender.isAdmin) {
-    console.log('这是管理员的消息');
-  }
-})
-```
-
-## WebSocket vs Webhook
-
-### WebSocket 模式（推荐）
-- ✅ 更低的延迟
-- ✅ 实时双向通信
-- ✅ 无需公网 IP
-- ✅ 配置简单
-
-### Webhook 模式
-- ✅ 服务器资源占用少
-- ✅ 可扩展性强
-- ⚠️ 需要公网 IP
-- ⚠️ 需要配置回调地址
-
-## 消息 ID 格式
-
-本适配器使用特殊的消息 ID 格式：
-
-- 频道消息：`channel-{channelId}:{messageId}`
-- 私聊消息：`private-{userId}:{messageId}`
-
-## 注意事项
-
-### 权限配置
-
-确保机器人有以下权限：
-- 查看频道
-- 发送消息
-- 管理消息（如需撤回）
-- 查看服务器成员列表
-
-### 频率限制
-
-KOOK 有消息发送频率限制：
-- 每秒最多 5 条消息
-- 建议添加发送队列管理
-
-## 常见问题
-
-### Q: 机器人无法收到消息？
-
-A: 检查以下几点：
-1. Token 是否正确
-2. 机器人是否已加入服务器
-3. 机器人是否有查看频道权限
-4. WebSocket 连接是否正常
-
-### Q: Webhook 模式无法工作？
-
-A: 确认：
-1. Webhook URL 可以从公网访问
-2. 验证令牌配置正确
-3. 端口已开放
-4. HTTPS 配置正确（推荐）
-
-### Q: 如何发送卡片消息？
-
-A: 使用 KOOK 的卡片消息格式：
-```typescript
-await bot.sendChannelMsg(channelId, [
-  {
-    type: 'card',
-    data: {
-      // 卡片消息内容
-    }
-  }
-])
-```
-
-## 相关链接
-
-- [KOOK 开发者平台](https://developer.kookapp.cn/)
-- [KOOK 开发文档](https://developer.kookapp.cn/doc/)
-- [kook-client 文档](https://github.com/zhinjs/kook-client)
-- [Zhin.js 官方文档](https://github.com/zhinjs/zhin)
-
-## 依赖项
-
-- `kook-client` - KOOK 客户端库
-- `zhin.js` - Zhin 核心框架
-
-## 开发
-
-```bash
-pnpm build  # 构建
-pnpm clean  # 清理构建文件
-```
+| 现象 | 排查 |
+| --- | --- |
+| WebSocket 无法上线 | 检查 Bot Token、网络与机器人能力开关 |
+| Webhook challenge 失败 | 检查公网路径、`verify_token` 与 HTTP Host |
+| 频道消息未触发 | 检查应用订阅、频道权限与机器人是否已加入服务器 |
+| 附件表现为链接 | 当前统一出站不上传附件；使用远程 URL 或按能力降级 |
 
 ## 许可证
 
 MIT License
-
-## 贡献
-
-欢迎提交 Issue 和 Pull Request！
-

package/adapters/kook.js

@@ -0,0 +1,41 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+/**
+ * Convention entry: discover `adapters/kook.ts` → defineAdapter.
+ * Implementation lives under `src/` (endpoint / webhook / ws / protocol).
+ */
+import { defineAdapter } from 'zhin.js/adapter';
+import { httpHostToken } from '@zhin.js/host-http';
+import { KookWebhookEndpoint, KookWebsocketEndpoint, } from "../lib/endpoint.js";
+import { resolveKookConfig, } from "../lib/protocol.js";
+import { kookRuntimeStateToken } from "../lib/kook-runtime-state.js";
+export { KookWebhookEndpoint, KookWebsocketEndpoint, } from "../lib/endpoint.js";
+export default defineAdapter({
+    capabilities: ['inbound', 'outbound'],
+    operations: ['recall'],
+    // KOOK 图片消息消费远程 URL；KMarkdown 由 endpoint codec 原生消费；
+    // 无按钮交互面，交互段降级纯文本。
+    segments: {
+        outboundMedia: ['url'],
+        interactive: 'text',
+        markdown: 'native',
+    },
+    create(context) {
+        const config = resolveKookConfig(context.config);
+        // 注册到插件运行时状态（kook.endpoint list 的"运行中"数据源）
+        context.use(kookRuntimeStateToken).endpoints.set(config.id, {
+            id: config.id,
+            mode: config.connection,
+        });
+        if (config.connection === 'webhook') {
+            return new KookWebhookEndpoint({
+                id: context.id,
+                http: context.use(httpHostToken),
+                config,
+            });
+        }
+        return new KookWebsocketEndpoint({
+            id: context.id,
+            config,
+        });
+    },
+});

package/adapters/kook.ts

@@ -0,0 +1,56 @@
+/**
+ * Convention entry: discover `adapters/kook.ts` → defineAdapter.
+ * Implementation lives under `src/` (endpoint / webhook / ws / protocol).
+ */
+import { defineAdapter } from 'zhin.js/adapter';
+import { httpHostToken } from '@zhin.js/host-http';
+import {
+  KookWebhookEndpoint,
+  KookWebsocketEndpoint,
+} from '../src/endpoint.js';
+import {
+  resolveKookConfig,
+  type KookAdapterConfig,
+} from '../src/protocol.js';
+import { kookRuntimeStateToken } from '../src/kook-runtime-state.js';
+
+export {
+  KookWebhookEndpoint,
+  KookWebsocketEndpoint,
+} from '../src/endpoint.js';
+export type {
+  KookEndpointOptions,
+  KookWebhookEndpointOptions,
+} from '../src/endpoint.js';
+export type { CreateKookClient, KookClientTransport } from '../src/ws.js';
+
+export default defineAdapter<KookAdapterConfig>({
+  capabilities: ['inbound', 'outbound'],
+  operations: ['recall'],
+  // KOOK 图片消息消费远程 URL；KMarkdown 由 endpoint codec 原生消费；
+  // 无按钮交互面，交互段降级纯文本。
+  segments: {
+    outboundMedia: ['url'],
+    interactive: 'text',
+    markdown: 'native',
+  },
+  create(context) {
+    const config = resolveKookConfig(context.config);
+    // 注册到插件运行时状态（kook.endpoint list 的"运行中"数据源）
+    context.use(kookRuntimeStateToken).endpoints.set(config.id, {
+      id: config.id,
+      mode: config.connection,
+    });
+    if (config.connection === 'webhook') {
+      return new KookWebhookEndpoint({
+        id: context.id,
+        http: context.use(httpHostToken),
+        config,
+      });
+    }
+    return new KookWebsocketEndpoint({
+      id: context.id,
+      config,
+    });
+  },
+});

package/agent/PERMITS.md

@@ -0,0 +1,23 @@
+# KOOK Platform Permits
+
+## 入站字段
+
+| 字段 | 来源 | 取值 |
+|------|------|------|
+| `$sender.role` | `permission` / `isAdmin` / `isGuildOwner` | `owner` · `admin` · `channel_admin` · `member` |
+| `$sender.permissions` | 归一化 + `roles[]` | `guild_owner` · `guild_admin` · `channel_admin` · `manage_roles` · `role:{id}` |
+
+KOOK `permission`：1=成员，2=管理员，4=频道主，5=频道管理员（子频道场景为 `channel_admin`）。
+
+## Permit 词汇表
+
+| `platform(kook,…)` | 含义 |
+|--------------------|------|
+| `guild_owner` | 服务器主 |
+| `guild_admin` | 服务器/频道管理员 |
+| `channel_admin` | 子频道管理员 |
+| `manage_roles` | 可管理身份组 |
+
+## 工厂映射
+
+`scene_admin` → `guild_admin` · `scene_owner` → `guild_owner`

package/agent/tools/blacklist.ts

@@ -0,0 +1,31 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { platformPermit } from '../../src/platform-permit.js';
+
+export default defineAgentTool<{ guild_id: string; action: 'add' | 'remove'; user_id: string; remark?: string }>({
+  description: 'KOOK 服务器黑名单管理：添加/移除',
+  inputSchema: z.object({
+    guild_id: z.string().describe('服务器 ID'),
+    action: z.enum(['add', 'remove']).describe('add|remove'),
+    user_id: z.string().describe('用户 ID'),
+    remark: z.string().optional().describe('备注（add 可选）'),
+  }),
+  adapter: 'kook',
+  tags: ['kook'],
+  permissions: [platformPermit('guild_admin')],
+  async execute({ guild_id, action, user_id, remark }: { guild_id: string; action: 'add' | 'remove'; user_id: string; remark?: string }, context) {
+    const member = context.$client.pickGuildMember(guild_id, user_id);
+    switch (action) {
+      case 'add': {
+        const success = await member.addToBlackList(remark);
+        return { success, message: success ? `已将 ${user_id} 加入黑名单` : '操作失败' };
+      }
+      case 'remove': {
+        const success = await member.removeFromBlackList();
+        return { success, message: success ? `已将 ${user_id} 从黑名单移除` : '操作失败' };
+      }
+      default:
+        return { success: false, message: `未知操作: ${action}` };
+    }
+  },
+});

package/agent/tools/create_role.ts

@@ -0,0 +1,23 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { platformPermit } from '../../src/platform-permit.js';
+
+export default defineAgentTool<{ guild_id: string; name: string }>({
+  description: '在 KOOK 服务器中创建新角色',
+  inputSchema: z.object({
+    guild_id: z.string().describe('服务器 ID'),
+    name: z.string().describe('角色名称'),
+  }),
+  adapter: 'kook',
+  tags: ['kook'],
+  permissions: [platformPermit('guild_owner')],
+  async execute({ guild_id, name  }: { guild_id: string; name: string }, context) {
+    const client = context.$client;
+    const role = await client.pickGuild(guild_id).createRole(name);
+    return {
+      success: true,
+      message: `已创建角色 "${name}"`,
+      role: { id: role.role_id, name: role.name },
+    };
+  },
+});

package/agent/tools/delete_role.ts

@@ -0,0 +1,19 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { platformPermit } from '../../src/platform-permit.js';
+
+export default defineAgentTool<{ guild_id: string; role_id: string }>({
+  description: '删除 KOOK 服务器中的角色',
+  inputSchema: z.object({
+    guild_id: z.string().describe('服务器 ID'),
+    role_id: z.string().describe('角色 ID'),
+  }),
+  adapter: 'kook',
+  tags: ['kook'],
+  permissions: [platformPermit('guild_owner')],
+  async execute({ guild_id, role_id  }: { guild_id: string; role_id: string }, context) {
+    const client = context.$client;
+    const success = await client.pickGuild(guild_id).deleteRole(role_id);
+    return { success, message: success ? `已删除角色 ${role_id}` : '删除角色失败' };
+  },
+});